motion-ui-skill 2.0.0

package/references/blocks/infinite-masonry.md

@@ -0,0 +1,211 @@
+---
+title: "Infinite Masonry"
+description: "Responsive virtualized masonry that measures variable-height cards and loads more data as the user nears the end."
+category: "Blocks"
+publishedAt: "2026-07-15"
+updatedAt: "2026-07-15"
+documentation: "references/blocks/infinite-masonry.md"
+markdown: "references/blocks/infinite-masonry.md"
+license: "MIT"
+---
+
+# Infinite Masonry
+
+> Responsive virtualized masonry that measures variable-height cards and loads more data as the user nears the end.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py infinite-masonry --dest ./src
+```
+
+## Dependencies
+
+- `@tanstack/react-virtual`
+- `clsx`
+- `lucide-react`
+- `motion`
+- `next`
+- `react`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import Image from "next/image";
+import { useCallback, useState } from "react";
+import { InfiniteMasonry } from "@/components/motion/infinite-masonry";
+
+type GalleryItem = {
+  id: string;
+  title: string;
+  category: string;
+  image: string;
+  imageHeight: number;
+};
+
+const PAGE_SIZE = 6;
+const MAX_ITEMS = 42;
+
+const gallerySource = [
+  {
+    title: "Soft geometry",
+    category: "Architecture",
+    image:
+      "https://images.unsplash.com/photo-1511818966892-d7d671e672a2?auto=format&fit=crop&w=720&q=80",
+    imageHeight: 260,
+  },
+  {
+    title: "Open horizon",
+    category: "Landscape",
+    image:
+      "https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?auto=format&fit=crop&w=720&q=80",
+    imageHeight: 190,
+  },
+  {
+    title: "Working rhythm",
+    category: "Workspace",
+    image:
+      "https://images.unsplash.com/photo-1497366754035-f200968a6e72?auto=format&fit=crop&w=720&q=80",
+    imageHeight: 230,
+  },
+  {
+    title: "Shared table",
+    category: "Studio",
+    image:
+      "https://images.unsplash.com/photo-1524758631624-e2822e304c36?auto=format&fit=crop&w=720&q=80",
+    imageHeight: 300,
+  },
+  {
+    title: "In session",
+    category: "People",
+    image:
+      "https://images.unsplash.com/photo-1521737711867-e3b97375f902?auto=format&fit=crop&w=720&q=80",
+    imageHeight: 210,
+  },
+  {
+    title: "After hours",
+    category: "Office",
+    image:
+      "https://images.unsplash.com/photo-1504384308090-c894fdcc538d?auto=format&fit=crop&w=720&q=80",
+    imageHeight: 280,
+  },
+] as const;
+
+function createItems(start: number, count: number): GalleryItem[] {
+  return Array.from({ length: count }, (_, offset) => {
+    const index = start + offset;
+    const source = gallerySource[index % gallerySource.length];
+
+    return {
+      ...source,
+      id: `gallery-${index}`,
+      title: `${source.title} ${Math.floor(index / gallerySource.length) + 1}`,
+    };
+  });
+}
+
+export function InfiniteMasonryPreview() {
+  const [items, setItems] = useState(() => createItems(0, 12));
+  const [loading, setLoading] = useState(false);
+  const hasMore = items.length < MAX_ITEMS;
+
+  const loadMore = useCallback(async () => {
+    if (loading || !hasMore) return;
+    setLoading(true);
+
+    await new Promise((resolve) => setTimeout(resolve, 650));
+    setItems((current) => {
+      const count = Math.min(PAGE_SIZE, MAX_ITEMS - current.length);
+      return count > 0
+        ? [...current, ...createItems(current.length, count)]
+        : current;
+    });
+    setLoading(false);
+  }, [hasMore, loading]);
+
+  return (
+    <div className="w-full max-w-5xl">
+      <div className="mb-3 flex items-end justify-between gap-4 px-1">
+        <div>
+          <p className="text-sm font-semibold text-foreground">Visual index</p>
+          <p className="mt-0.5 text-xs text-muted-foreground">
+            Scroll to load the next page
+          </p>
+        </div>
+        <p className="font-mono text-xs tabular-nums text-muted-foreground">
+          {items.length} items
+        </p>
+      </div>
+
+      <InfiniteMasonry
+        items={items}
+        getItemKey={(item) => item.id}
+        renderItem={(item) => (
+          <figure className="overflow-hidden rounded-2xl border border-border bg-card">
+            <div
+              className="relative w-full overflow-hidden"
+              style={{ height: item.imageHeight }}
+            >
+              <Image
+                src={item.image}
+                alt={item.title}
+                fill
+                sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 25vw"
+                className="object-cover"
+              />
+            </div>
+            <figcaption className="flex items-start justify-between gap-3 p-3">
+              <p className="text-sm font-medium text-foreground">
+                {item.title}
+              </p>
+              <p className="shrink-0 text-[10px] uppercase tracking-wider text-muted-foreground">
+                {item.category}
+              </p>
+            </figcaption>
+          </figure>
+        )}
+        onLoadMore={loadMore}
+        hasMore={hasMore}
+        loading={loading}
+        estimateSize={(item) => item.imageHeight + 66}
+        ariaLabel="Visual inspiration gallery"
+        className="h-[34rem]"
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### InfiniteMasonry
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `readonly T[]` | — | Yes | — |
+| `getItemKey` | `(item: T, index: number) => InfiniteMasonryKey` | — | Yes | — |
+| `renderItem` | `(item: T, index: number) => ReactNode` | — | Yes | — |
+| `onLoadMore` | `() => void \| Promise<void>` | — | Yes | — |
+| `hasMore` | `boolean` | — | Yes | — |
+| `loading` | `boolean` | `false` | No | — |
+| `error` | `ReactNode` | — | No | — |
+| `onRetry` | `(() => void)` | — | No | — |
+| `estimateSize` | `((item: T, index: number) => number)` | `() => 240` | No | — |
+| `renderLoadingItem` | `((index: number) => ReactNode)` | `(index) => <DefaultLoadingItem index={index} />` | No | — |
+| `emptyState` | `ReactNode` | `<DefaultEmptyState />` | No | — |
+| `endState` | `ReactNode` | — | No | — |
+| `minColumnWidth` | `number` | `208` | No | — |
+| `maxColumns` | `number` | `4` | No | — |
+| `gap` | `number` | `12` | No | — |
+| `overscan` | `number` | `4` | No | — |
+| `prefetch` | `number` | `3` | No | — |
+| `animateItems` | `boolean` | `true` | No | — |
+| `ariaLabel` | `string` | `Infinite masonry feed` | No | — |
+| `className` | `string` | — | No | — |
+| `contentClassName` | `string` | — | No | — |
+| `itemClassName` | `string` | — | No | — |
+

package/references/blocks/knockout-bracket.md

@@ -0,0 +1,161 @@
+---
+title: "Fixtures"
+description: "Animated tournament fixtures in two styles: a knockout bracket that pages through rounds, and a wheel that wraps the same tree around the champion. Both read the same array of rounds, so one dataset draws either."
+category: "Blocks"
+publishedAt: "2026-07-12"
+updatedAt: "2026-07-27"
+documentation: "references/blocks/knockout-bracket.md"
+markdown: "references/blocks/knockout-bracket.md"
+license: "MIT"
+---
+
+# Fixtures
+
+> Animated tournament fixtures in two styles: a knockout bracket that pages through rounds, and a wheel that wraps the same tree around the champion. Both read the same array of rounds, so one dataset draws either.
+
+## Install
+
+### Knockout Wheel
+
+The tournament drawn radially. The champion holds the hub, each round is a ring further out, and the teams themselves form the rim. Nodes spring in ring by ring, and hovering one isolates that team while the rest recede. Teams show a flag, a logo or their initials, and a deeper draw grows another ring.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py knockout-wheel --dest ./src
+```
+
+### Knockout Bracket
+
+Pages one round at a time. The leftmost round stacks at a fixed rhythm, each later round centers between its two feeder matches, and cards, elbow connectors, headers and stage height animate into every new layout. A third place play-off sits below the tree under its own rule. Round names, team artwork, dates and result chips all come from the data you pass.
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py knockout-bracket --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+### Knockout Wheel usage
+
+The tournament drawn radially. The champion holds the hub, each round is a ring further out, and the teams themselves form the rim. Nodes spring in ring by ring, and hovering one isolates that team while the rest recede. Teams show a flag, a logo or their initials, and a deeper draw grows another ring.
+
+```tsx
+"use client";
+
+import { KnockoutWheel, ROUNDS } from "@/components/motion/knockout-wheel";
+
+// `ROUNDS` is the sample 32-team cup that ships with the component, and it's the
+// same array the knockout bracket takes, so one dataset feeds both fixture
+// styles. Any other single-elimination tournament renders the same way. Build
+// your own `Round[]`, widest round first, each round holding half the matches of
+// the one before it, and pass it in:
+//
+//   const rounds: Round[] = [
+//     {
+//       name: "Quarter-finals",
+//       matches: [
+//         {
+//           id: "qf-1",
+//           home: { team: { name: "Cloud9", logo: "/logos/c9.svg" }, score: 2 },
+//           away: { team: { name: "T1", logo: "/logos/t1.svg" }, score: 1 },
+//           winner: "home",
+//         },
+//         // qf-2, qf-3, qf-4 …
+//       ],
+//     },
+//     { name: "Semi-finals", matches: [/* fed by qf 1+2 and qf 3+4 */] },
+//     { name: "Grand final", matches: [/* the one final */] },
+//   ];
+//
+// The wheel grows a ring per round and holds a 32rem stage at every size, so it
+// pans on a phone rather than shrinking its marks. A team carries a `logo` URL,
+// an ISO country `code` for a flag, or neither, in which case its initials stand
+// in. `initialRound` drops the outer rounds.
+export function KnockoutWheelPreview() {
+  return (
+    <div className="w-full py-8">
+      <KnockoutWheel rounds={ROUNDS} />
+    </div>
+  );
+}
+```
+
+### Knockout Bracket usage
+
+Pages one round at a time. The leftmost round stacks at a fixed rhythm, each later round centers between its two feeder matches, and cards, elbow connectors, headers and stage height animate into every new layout. A third place play-off sits below the tree under its own rule. Round names, team artwork, dates and result chips all come from the data you pass.
+
+```tsx
+"use client";
+
+import {
+  KnockoutBracket,
+  ROUNDS,
+  THIRD_PLACE,
+} from "@/components/motion/knockout-bracket";
+
+// `ROUNDS` is the sample World Cup draw that ships with the component. Any other
+// single-elimination tournament renders the same way. Build your own `Round[]`,
+// widest round first, each round holding half the matches of the one before it,
+// and pass it in:
+//
+//   const rounds: Round[] = [
+//     {
+//       name: "Quarter-finals",
+//       matches: [
+//         {
+//           id: "qf-1",
+//           date: "Sat, 14 Mar",
+//           home: { team: { name: "Cloud9", logo: "/logos/c9.svg" }, score: 2 },
+//           away: { team: { name: "T1", logo: "/logos/t1.svg" }, score: 1 },
+//           winner: "home",
+//           badge: "BO3",
+//         },
+//         // qf-2, qf-3, qf-4 …
+//       ],
+//     },
+//     { name: "Semi-finals", matches: [/* fed by qf 1+2 and qf 3+4 */] },
+//     { name: "Grand final", matches: [/* the one final */] },
+//   ];
+//
+// A team carries a `logo` URL, an ISO country `code` for a flag, or neither, in
+// which case its initials stand in. `date`, `time`, `status` and `badge` are all
+// optional. `thirdPlaceLabel` renames the play-off when a tournament calls it
+// something else ("Bronze match").
+export function KnockoutBracketPreview() {
+  return (
+    <div className="w-full py-8">
+      <KnockoutBracket rounds={ROUNDS} thirdPlace={THIRD_PLACE} />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### KnockoutWheel
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `rounds` | `Round[]` | — | Yes | The whole draw, ordered widest round first — the same array the knockout bracket takes. Any single-elimination tournament fits: each round holds half the matches of the one before it (16 → 8 → 4 → 2 → 1) and `rounds[r].matches[k]` is fed by matches `2k` and `2k + 1` of the round before it. Two rounds are enough; the wheel grows a ring per round and sizes itself to the rim. |
+| `initialRound` | `number` | `0` | No | Index of the outermost round to draw. Earlier rounds are dropped and the kept round's own teams become the rim, so `1` on a 32-team draw opens at the Round of 16. Defaults to 0 (the whole tree); clamped to the valid range. |
+| `className` | `string` | — | No | — |
+
+### KnockoutBracket
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `rounds` | `Round[]` | — | Yes | The whole draw, ordered widest round first. Any single-elimination tournament fits: each round holds half the matches of the one before it (16 → 8 → 4 → 2 → 1) and `rounds[r].matches[k]` is fed by matches `2k` and `2k + 1` of the round before it. Two rounds are enough. |
+| `initialRound` | `number` | `1` | No | Round shown as the leftmost column on mount. Defaults to 1, clamped to the valid range. |
+| `thirdPlace` | `Match` | — | No | Third place play-off, rendered under the bracket instead of inside it. |
+| `thirdPlaceLabel` | `string` | `Third place play-off` | No | Heading over `thirdPlace`. Defaults to "Third place play-off". |
+| `className` | `string` | — | No | — |
+

package/references/blocks/morphing-search.md

@@ -0,0 +1,113 @@
+---
+title: "Morphing Search"
+description: "Search field or compact icon that morphs into a glass results surface, whether opened by click or keyboard shortcut."
+category: "Blocks"
+publishedAt: "2026-08-18"
+updatedAt: "2026-08-22"
+documentation: "references/blocks/morphing-search.md"
+markdown: "references/blocks/morphing-search.md"
+license: "MIT"
+---
+
+# Morphing Search
+
+> Search field or compact icon that morphs into a glass results surface, whether opened by click or keyboard shortcut.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py morphing-search --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { Blocks, BookOpen, Bot, FolderOpen, Palette } from "lucide-react";
+import {
+  MorphingSearch,
+  type MorphingSearchItem,
+} from "@/components/motion/morphing-search";
+
+const ITEMS: MorphingSearchItem[] = [
+  {
+    id: "project-folder",
+    title: "Project Folder",
+    description: "Block · Files and previews",
+    keywords: ["files", "overlay"],
+    icon: FolderOpen,
+  },
+  {
+    id: "motion-components",
+    title: "Motion components",
+    description: "Collection · Interaction primitives",
+    keywords: ["animation", "components"],
+    icon: Blocks,
+  },
+  {
+    id: "agent-interfaces",
+    title: "Agent interfaces",
+    description: "Collection · AI building blocks",
+    keywords: ["ai", "chat"],
+    icon: Bot,
+  },
+  {
+    id: "installation",
+    title: "Installation guide",
+    description: "Documentation · Add your first component",
+    keywords: ["setup", "shadcn"],
+    icon: BookOpen,
+  },
+  {
+    id: "design-tokens",
+    title: "Design tokens",
+    description: "Documentation · Color, type, and motion",
+    keywords: ["theme", "styles"],
+    icon: Palette,
+  },
+];
+
+export function MorphingSearchPreview() {
+  return (
+    <div className="flex w-full max-w-[22rem] items-center gap-3">
+      <MorphingSearch items={ITEMS} placeholder="Find components" />
+      <MorphingSearch
+        items={ITEMS}
+        placeholder="Find components"
+        shortcut=""
+        iconOnly
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### MorphingSearch
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `MorphingSearchItem[]` | — | Yes | — |
+| `placeholder` | `string` | `Search` | No | — |
+| `shortcut` | `string` | `f` | No | — |
+| `iconOnly` | `boolean` | `false` | No | Render the closed trigger as a compact search icon. |
+| `emptyMessage` | `string` | `No results found.` | No | — |
+| `open` | `boolean` | — | No | — |
+| `defaultOpen` | `boolean` | `false` | No | — |
+| `onOpenChange` | `((open: boolean) => void)` | — | No | — |
+| `onQueryChange` | `((query: string) => void)` | — | No | — |
+| `onSelect` | `((item: MorphingSearchItem) => void)` | — | No | — |
+| `className` | `string` | — | No | — |
+

package/references/blocks/morphing-tabs.md

@@ -0,0 +1,143 @@
+---
+title: "Morphing Tabs"
+description: "Reorderable tabs whose selected item grows into a white content surface, with the active shape gliding as tabs move and a shared morph between rooms."
+category: "Blocks"
+publishedAt: "2026-08-06"
+updatedAt: "2026-08-06"
+documentation: "references/blocks/morphing-tabs.md"
+markdown: "references/blocks/morphing-tabs.md"
+license: "MIT"
+---
+
+# Morphing Tabs
+
+> Reorderable tabs whose selected item grows into a white content surface, with the active shape gliding as tabs move and a shared morph between rooms.
+
+## Install
+
+```bash
+# Install via motion-ui skill CLI:
+python scripts/install-component.py morphing-tabs --dest ./src
+```
+
+## Dependencies
+
+- `clsx`
+- `lucide-react`
+- `motion`
+- `react`
+- `react-dom`
+- `tailwind-merge`
+
+## Usage
+
+```tsx
+"use client";
+
+import { useMemo, useState } from "react";
+import { MorphingTabs, type MorphingTabsItem } from "@/components/motion/morphing-tabs";
+
+const ROOM_CONTENT: Record<string, { eyebrow: string; title: string; detail: string; accent: string }> = {
+  "room-2": {
+    eyebrow: "quiet focus",
+    title: "Room 2",
+    detail: "A small space for the work that needs a little more air around it.",
+    accent: "#db5b2f",
+  },
+  general: {
+    eyebrow: "shared space",
+    title: "General",
+    detail: "The common room for notes, links and the ideas that are still finding their shape.",
+    accent: "#1bb273",
+  },
+  archive: {
+    eyebrow: "kept close",
+    title: "Archive",
+    detail: "Past rooms stay available without competing with the conversations in motion.",
+    accent: "#7a6de2",
+  },
+};
+
+function RoomPanel({ id }: { id: string }) {
+  const room = ROOM_CONTENT[id];
+
+  return (
+    <div className="relative min-h-64 overflow-hidden bg-[radial-gradient(circle_at_1px_1px,#dfe2e3_1px,transparent_1.5px)] bg-[size:4.8rem_4.8rem] px-7 py-8 md:px-12 md:py-10">
+      <div className="relative max-w-xl">
+        <p className="text-[0.68rem] font-semibold uppercase tracking-[0.24em] text-black/40">
+          {room.eyebrow}
+        </p>
+        <h3 className="mt-3 text-3xl font-light tracking-[-0.055em] text-[#151515] md:text-5xl">
+          {room.title}
+        </h3>
+        <p className="mt-4 max-w-md text-sm leading-6 text-black/55 md:text-base">
+          {room.detail}
+        </p>
+        <div className="mt-8 flex items-center gap-3 text-xs font-medium text-black/50">
+          <span className="size-2 rounded-full" style={{ backgroundColor: room.accent }} />
+          drag any room to reorder
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function MorphingTabsPreview() {
+  const initialItems = useMemo<MorphingTabsItem[]>(
+    () =>
+      Object.keys(ROOM_CONTENT).map((id) => ({
+        id,
+        label: ROOM_CONTENT[id].title,
+        content: <RoomPanel id={id} />,
+      })),
+    [],
+  );
+  const [items, setItems] = useState(initialItems);
+  const [value, setValue] = useState<string | null>("room-2");
+
+  return (
+    <div className="flex w-full min-w-0 items-center justify-center bg-[#242424] p-3 md:p-8">
+      <MorphingTabs
+        items={items}
+        value={value}
+        onValueChange={setValue}
+        onOrderChange={(ids) => {
+          setItems((current) => {
+            const byId = new Map(current.map((item) => [item.id, item]));
+            return ids.flatMap((id) => {
+              const item = byId.get(id);
+              return item ? [item] : [];
+            });
+          });
+        }}
+        onClose={(id) => {
+          setItems((current) => {
+            const next = current.filter((item) => item.id !== id);
+            if (id === value) setValue(next[0]?.id ?? null);
+            return next;
+          });
+        }}
+        ariaLabel="Rooms"
+        className="w-full max-w-5xl"
+      />
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### MorphingTabs
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `MorphingTabsItem[]` | — | Yes | — |
+| `value` | `string \| null` | — | No | — |
+| `defaultValue` | `string \| null` | — | No | — |
+| `onValueChange` | `((id: string \| null) => void)` | — | No | — |
+| `onOrderChange` | `((ids: string[]) => void)` | — | No | Called once after a pointer drag or keyboard reorder completes. |
+| `onClose` | `((id: string) => void)` | — | No | Enables the close affordance on every tab when provided. |
+| `ariaLabel` | `string` | `Tabs` | No | — |
+| `className` | `string` | — | No | — |
+| `classNames` | `MorphingTabsClassNames` | — | No | — |
+