feat(registry): let components declare a description

src/fancy/components/background/animated-gradient-with-svg.json

@@ -1,4 +1,5 @@
 {
+  "description": "Fills its container with softly blurred, randomly placed and sized SVG circles that drift and pulse, forming an ambient animated gradient backdrop.",
   "cssVars": {
     "@theme inline": {
       "--animate-background-gradient": "background-gradient",

src/fancy/components/background/pixel-trail.json

@@ -0,0 +1,3 @@
+{
+  "description": "Divides the container into a pixel grid that lights up and fades out as the cursor passes over it, leaving a trailing wake of squares."
+}

src/fancy/components/blocks/circling-elements.json

@@ -1,4 +1,5 @@
 {
+  "description": "Arranges child elements evenly around a circle and spins them continuously at a set radius, direction, and speed, pausable on hover.",
   "cssVars": {
     "@keyframes circling": {
       "0%": {

src/fancy/components/blocks/css-box.json

@@ -0,0 +1,3 @@
+{
+  "description": "Renders a draggable, spring-animated 3D cube built from six CSS faces, with imperative controls to snap to any face or arbitrary rotation."
+}

src/fancy/components/blocks/drag-elements.json

@@ -0,0 +1,3 @@
+{
+  "description": "Makes each child freely draggable within its container with elastic constraints and momentum, bringing the dragged item to the front."
+}

src/fancy/components/blocks/element-along-svg-path.json

@@ -0,0 +1,3 @@
+{
+  "description": "Moves one or more child elements along a custom SVG path, driven either automatically over time or by scroll progress, slowing on hover."
+}

src/fancy/components/blocks/float.json

@@ -0,0 +1,3 @@
+{
+  "description": "Applies continuous, organic sine-wave drifting and 3D tilt to its children, simulating a slow floating object suspended in space."
+}

src/fancy/components/blocks/marquee-along-svg-path.json

@@ -0,0 +1,3 @@
+{
+  "description": "Loops repeated copies of its children endlessly along a custom SVG path, with optional scroll-linked speed, drag, and rolling z-index depth."
+}

src/fancy/components/blocks/media-between-text.json

@@ -0,0 +1,3 @@
+{
+  "description": "Expands an image or video from zero width between two text labels on hover, scroll into view, or manual trigger, like text swallowing a thumbnail."
+}

src/fancy/components/blocks/screensaver.json

@@ -0,0 +1,3 @@
+{
+  "description": "Bounces its child element around inside a container at a constant angle and speed, reflecting off the edges like a classic DVD screensaver."
+}

src/fancy/components/blocks/simple-carousel.json

@@ -0,0 +1,3 @@
+{
+  "description": "Scrolls repeated children endlessly in a row or column at constant velocity, with optional scroll-linked speed, hover slowdown, and drag control."
+}

src/fancy/components/blocks/simple-marquee.json

@@ -0,0 +1,3 @@
+{
+  "description": "Scrolls repeated children endlessly in a row or column at constant velocity, with optional scroll-linked speed, hover slowdown, and drag control."
+}

src/fancy/components/blocks/stacking-cards.json

@@ -0,0 +1,3 @@
+{
+  "description": "Stacks sticky cards on scroll so each new card shrinks the ones beneath it, creating a layered deck-of-cards reveal effect."
+}

src/fancy/components/carousel/box-carousel.json

@@ -0,0 +1,3 @@
+{
+  "description": "Displays images or videos on the faces of a rotating 3D cube, navigable by drag, buttons, or keyboard to cycle through media items."
+}

src/fancy/components/filter/gooey-svg-filter.json

@@ -0,0 +1,3 @@
+{
+  "description": "An SVG filter definition that blurs and re-thresholds overlapping shapes so they visually merge into a smooth, blobby gooey mass."
+}

src/fancy/components/filter/pixelate-svg-filter.json

@@ -0,0 +1,3 @@
+{
+  "description": "An SVG filter definition that mosaics whatever it's applied to into large flat blocks, producing a chunky pixelated look at a configurable block size."
+}

src/fancy/components/image/image-trail.json

@@ -0,0 +1,3 @@
+{
+  "description": "Reveals repeated child images one by one as the cursor moves past a distance threshold, each easing toward the pointer to form a following trail."
+}

src/fancy/components/image/parallax-floating.json

@@ -0,0 +1,3 @@
+{
+  "description": "Shifts registered child elements by amounts proportional to their declared depth as the cursor moves, producing a multi-layer parallax effect."
+}

src/fancy/components/physics/cursor-attractor-and-gravity.json

@@ -1,5 +1,4 @@
 {
-    "additionalDependencies": [
-        "poly-decomp", "@types/matter-js"
-    ]
-}
+  "description": "Runs a Matter.js physics simulation where draggable DOM elements are pulled toward both a fixed attractor point and the cursor whenever it is within a set radius.",
+  "additionalDependencies": ["poly-decomp", "@types/matter-js"]
+}

src/fancy/components/physics/elastic-line.json

@@ -0,0 +1,3 @@
+{
+  "description": "Draws a straight SVG line that can be grabbed and pulled into a curve, springing back to straight when released, like a plucked string."
+}

src/fancy/components/physics/gravity.json

@@ -1,5 +1,4 @@
 {
-    "additionalDependencies": [
-        "poly-decomp", "@types/matter-js"
-    ]
-}
+  "description": "Runs a Matter.js physics simulation that turns DOM children into draggable rigid bodies which fall, collide, and settle under configurable gravity.",
+  "additionalDependencies": ["poly-decomp", "@types/matter-js"]
+}

src/fancy/components/text/basic-number-ticker.json

@@ -0,0 +1,3 @@
+{
+  "description": "Animates a number counting from a start value to a target value over a configurable transition, with imperative start and complete callbacks."
+}

src/fancy/components/text/breathing-text.json

@@ -0,0 +1,3 @@
+{
+  "description": "Cycles each letter's variable font weight (or other font-variation axis) back and forth on a staggered loop, giving text a pulsing breathing look."
+}

src/fancy/components/text/letter-3d-swap.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, flips each letter as a 3D cube face to reveal a second character behind it, staggered per letter in a chosen rotation direction."
+}

src/fancy/components/text/letter-swap-forward-anim.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, slides each letter out and swaps in a duplicate that resets instantly, playing the letters in order (first to last) once per hover."
+}

src/fancy/components/text/letter-swap-pingpong-anim.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, slides letters in sequence to reveal a duplicate underneath, then slides them back in the same order when the cursor leaves."
+}

src/fancy/components/text/random-letter-swap-forward-anim.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, slides each letter out to reveal a duplicate in a randomized per-letter order, playing forward once without reversing on hover-out."
+}

src/fancy/components/text/random-letter-swap-pingpong-anim.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, slides letters in a randomized order to reveal duplicates underneath, then reverses the swap back when the cursor leaves."
+}

src/fancy/components/text/scramble-hover.json

@@ -0,0 +1,3 @@
+{
+  "description": "While hovered, cycles each character through random glyphs before settling, optionally revealing characters in sequence from the start, end, or center."
+}

src/fancy/components/text/scramble-in.json

@@ -0,0 +1,3 @@
+{
+  "description": "On mount or manual trigger, reveals text left to right while a trailing window of characters scrambles through random glyphs just ahead of the reveal."
+}

src/fancy/components/text/scroll-and-swap-text.json

@@ -0,0 +1,3 @@
+{
+  "description": "Slides the current text up and out while a duplicate slides up into place, with the transition driven by scroll progress through a tracked container."
+}

src/fancy/components/text/text-along-path.json

@@ -0,0 +1,3 @@
+{
+  "description": "Renders text following a custom SVG path, animating its position along the path automatically over time or by tying it to scroll progress."
+}

src/fancy/components/text/text-cursor-proximity.json

@@ -0,0 +1,3 @@
+{
+  "description": "Animates each letter's CSS properties based on its distance from the cursor, with linear, exponential, or gaussian falloff for a proximity-reactive effect."
+}

src/fancy/components/text/text-highlighter.json

@@ -0,0 +1,3 @@
+{
+  "description": "Sweeps a colored highlight background across text from a chosen direction, triggered on hover, scroll into view, or manual control."
+}

src/fancy/components/text/text-rotate.json

@@ -0,0 +1,3 @@
+{
+  "description": "Cycles through an array of text strings, animating each in and out by words, characters, or lines with staggered enter and exit transitions."
+}

src/fancy/components/text/typewriter.json

@@ -0,0 +1,3 @@
+{
+  "description": "Types out one or more strings character by character with a blinking cursor, then deletes and retypes the next string when given an array."
+}

src/fancy/components/text/underline-center.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, grows an underline outward from the center of the text to full width beneath it, for a centered reveal effect."
+}

src/fancy/components/text/underline-comes-in-goes-out.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, an underline grows in from one edge across the full text width, then shrinks back out the opposite edge on the way out."
+}

src/fancy/components/text/underline-goes-out-comes-in.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, an underline shrinks away from one edge before regrowing across the full text width from the opposite edge, the reverse of comes-in-goes-out."
+}

src/fancy/components/text/underline-to-background.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, expands a thin underline vertically into a full background fill behind the text while the text color animates to a target color."
+}

src/fancy/components/text/variable-font-and-cursor.json

@@ -0,0 +1,3 @@
+{
+  "description": "Maps cursor x and y position within a container to two variable font axes, morphing the whole text's weight or slant as the mouse moves."
+}

src/fancy/components/text/variable-font-cursor-proximity.json

@@ -0,0 +1,3 @@
+{
+  "description": "Interpolates each letter's variable font axes individually based on distance from the cursor, with linear, exponential, or gaussian falloff."
+}

src/fancy/components/text/variable-font-hover-by-letter.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, animates every letter's variable font settings (like weight or slant) together in a staggered sweep from a chosen starting letter."
+}

src/fancy/components/text/variable-font-hover-by-random-letter.json

@@ -0,0 +1,3 @@
+{
+  "description": "On hover, animates each letter's variable font settings in a randomized per-letter order rather than sweeping sequentially across the text."
+}

src/fancy/components/text/vertical-cut-reveal.json

@@ -0,0 +1,3 @@
+{
+  "description": "Reveals text by sliding words, characters, or lines up (or down) into view from behind a clipped mask, staggered across the chosen split unit."
+}

src/fancy/schema.ts

@@ -9,6 +9,7 @@ export const registrySchema = z.record(
   z.string(),
   z.object({
     name: z.string(),
+    description: z.string().optional(), // one line summary of the component. fetched from the addition .json file next to the component .tsx file
     dependencies: z.array(z.string()).optional(), // external dependencies. inferred from the import statements, and fetched from the addition .json file next to the component .tsx file
     devDependencies: z.array(z.string()).optional(), // dev dependencies. fetched from the addition .json file next to the component .tsx file
     registryDependencies: z.array(z.string()).optional(), // other component dependencies

src/scripts/build-registry-index.ts

@@ -340,6 +340,9 @@ function generateRegistryItem(
           ],
         }
       : null),
+    ...(additionalConfig?.description && {
+      description: additionalConfig.description,
+    }),
     ...(additionalConfig?.tailwind && {
       tailwind: additionalConfig.tailwind,
     }),