Skip to content

Visualize Your Ideas With Code

docs: improve node examples (#602)

Jacob5555c809e067
diff --git a/packages/2d/src/components/Circle.ts b/packages/2d/src/components/Circle.ts
index 5b8cfa6c..00e105f2 100644
--- a/packages/2d/src/components/Circle.ts
+++ b/packages/2d/src/components/Circle.ts
@@ -24,41 +24,62 @@ export interface CircleProps extends ShapeProps {
* This node can be used to render shapes such as: circle, ellipse, arc, and
* sector (pie chart).
*
- * @example
- * A simple circle:
- * ```tsx
- * <Circle
- * size={300}
- * fill={'lightseagreen'}
- * />
- * ```
- * An ellipse:
- * ```tsx
- * <Circle
- * width={300}
- * height={100}
- * fill={'lightseagreen'}
- * />
- * ```
- * A sector (pie chart):
- * ```tsx
- * <Circle
- * size={300}
- * fill={'lightseagreen'}
- * startAngle={30}
- * endAngle={270}
- * closed={true}
- * />
- * ```
- * An arc:
- * ```tsx
- * <Circle
- * size={300}
- * stroke={'lightseagreen'}
- * lineWidth={8}
- * startAngle={-90}
- * endAngle={90}
- * />
+ * @preview
+ * ```tsx editor
+ * // snippet Simple circle
+ * export default makeScene2D(function* (view) {
+ * view.add(
+ * <Circle
+ * size={160}
+ * fill={'lightseagreen'}
+ * />
+ * );
+ * });
+ *
+ * // snippet Ellipse
+ * export default makeScene2D(function* (view) {
+ * view.add(
+ * <Circle
+ * width={160}
+ * height={80}
+ * fill={'lightseagreen'}
+ * />
+ * );
+ * });
+ *
+ * // snippet Sector (pie chart):
+ * export default makeScene2D(function* (view) {
+ * const ref = createRef<Circle>();
+ * view.add(
+ * <Circle
+ * ref={ref}
+ * size={160}
+ * fill={'lightseagreen'}
+ * startAngle={30}
+ * endAngle={270}
+ * closed={true}
+ * />
+ * );
+ *
+ * yield* ref().startAngle(270, 2).to(30, 2);
+ * });
+ *
+ * // snippet Arc:
+ * export default makeScene2D(function* (view) {
+ * const ref = createRef<Circle>();
+ * view.add(
+ * <Circle
+ * ref={ref}
+ * size={160}
+ * stroke={'lightseagreen'}
+ * lineWidth={8}
+ * startAngle={-90}
+ * endAngle={90}
+ * />
+ * );
+ *
+ * yield* ref().startAngle(-270, 2).to(-90, 2);
+ * });
* ```
*/
export class Circle extends Shape {
diff --git a/packages/2d/src/components/Img.ts b/packages/2d/src/components/Img.ts
index 059cd238..5f98b31d 100644
--- a/packages/2d/src/components/Img.ts
+++ b/packages/2d/src/components/Img.ts
@@ -34,7 +34,7 @@ export interface ImgProps extends RectProps {
/**
* A node for displaying images.
*
- * @remarks
+ * @preview
* ```tsx editor
* import {Img} from '@motion-canvas/2d/lib/components';
* import {all, waitFor} from '@motion-canvas/core/lib/flow';
diff --git a/packages/2d/src/components/Polygon.ts b/packages/2d/src/components/Polygon.ts
index d454a039..0e13bb29 100644
--- a/packages/2d/src/components/Polygon.ts
+++ b/packages/2d/src/components/Polygon.ts
@@ -27,23 +27,34 @@ export interface PolygonProps extends ShapeProps {
* will be particularly noticable if the number of sides is low, e.g. for a
* triangle.
*
- * @example
- * A hexagon:
- * ```tsx
- * <Polygon
- * sides={6}
- * size={300}
- * fill={'lightseagreen'}
- * />
- * ```
- * A pentagon outline:
- * ```tsx
- * <Polygon
- * sides={5}
- * size={300}
- * stroke={'lightblue'}
- * lineWidth={8}
- * />
+ * @preview
+ * ```tsx editor
+ * // snippet Polygon
+ * export default makeScene2D(function* (view) {
+ * const ref = createRef<Polygon>();
+ * view.add(
+ * <Polygon
+ * ref={ref}
+ * sides={6}
+ * size={160}
+ * fill={'lightseagreen'}
+ * />
+ * );
+ *
+ * yield* ref().sides(3, 2).to(6, 2);
+ * });
+ *
+ * // snippet Pentagon outline
+ * export default makeScene2D(function* (view) {
+ * view.add(
+ * <Polygon
+ * sides={5}
+ * size={160}
+ * stroke={'lightblue'}
+ * lineWidth={8}
+ * />
+ * );
+ * });
* ```
*/
export class Polygon extends Shape {
diff --git a/packages/docs/src/components/Api/Comment/index.tsx b/packages/docs/src/components/Api/Comment/index.tsx
index b131ec66..f08b314b 100644
--- a/packages/docs/src/components/Api/Comment/index.tsx
+++ b/packages/docs/src/components/Api/Comment/index.tsx
@@ -27,6 +27,10 @@ export default function Comment({
function FullComment({comment}: {comment: JSONOutput.Comment}) {
const [collapsed, setCollapsed] = useState(true);
+ const preview = useMemo(
+ () => comment?.blockTags?.find(({tag}) => tag === '@preview'),
+ [comment],
+ );
const examples = useMemo(
() => comment?.blockTags?.filter(({tag}) => tag === '@example') ?? [],
[comment],
@@ -46,6 +50,7 @@ function FullComment({comment}: {comment: JSONOutput.Comment}) {
return (
<>
+ <Summary id={preview?.contentId} />
{examples.length > 0 && (
<>
<h4>
diff --git a/packages/docs/src/components/Fiddle/index.tsx b/packages/docs/src/components/Fiddle/index.tsx
index 9b32fc3a..bb6bfe88 100644
--- a/packages/docs/src/components/Fiddle/index.tsx
+++ b/packages/docs/src/components/Fiddle/index.tsx
@@ -137,10 +137,12 @@ export default function Fiddle({children}: FiddleProps) {
<div className={styles.preview} ref={previewRef}>
{!player && <div>Press play to preview the animation</div>}
</div>
- <div
- className={styles.progress}
- style={{width: player ? `${(frame / duration) * 100}%` : 0}}
- />
+ {duration > 0 && (
+ <div
+ className={styles.progress}
+ style={{width: player ? `${(frame / duration) * 100}%` : 0}}
+ />
+ )}
<div className={styles.controls}>
<div className={styles.section}>
{hasChangedSinceLastUpdate && (
diff --git a/packages/docs/src/components/Fiddle/styles.module.css b/packages/docs/src/components/Fiddle/styles.module.css
index 98619b0b..903eff6c 100644
--- a/packages/docs/src/components/Fiddle/styles.module.css
+++ b/packages/docs/src/components/Fiddle/styles.module.css
@@ -105,3 +105,7 @@
display: flex;
align-items: center;
}
+
+.picker {
+ margin-right: var(--ifm-button-padding-vertical);
+}
diff --git a/tsdoc.json b/tsdoc.json
index 8592d23c..99b4ab04 100644
--- a/tsdoc.json
+++ b/tsdoc.json
@@ -10,18 +10,19 @@
"syntaxKind": "modifier"
},
{
- "tagName": "@default",
+ "tagName": "@category",
"syntaxKind": "modifier"
},
{
- "tagName": "@category",
- "syntaxKind": "modifier"
+ "tagName": "@preview",
+ "syntaxKind": "block"
}
],
"supportForTags": {
"@packageDocumentation": true,
"@module": true,
"@category": true,
+ "@preview": true,
"@param": true,
"@deprecated": true,
"@returns": true,