@hex-core/components 1.4.0 → 1.6.0

package/dist/schemas.js

@@ -4638,6 +4638,1654 @@ var sidebarSchema = {
   tags: ["sidebar", "navigation", "app-shell", "layout"]
 };
 
-export { accordionSchema, alertDialogSchema, alertSchema, aspectRatioSchema, avatarSchema, badgeSchema, breadcrumbSchema, buttonSchema, calendarSchema, cardSchema, checkboxSchema, clusterSchema, collapsibleSchema, colorPickerSchema, comboboxSchema, commandSchema, containerSchema, contextMenuSchema, dataTableSchema, datePickerSchema, dialogSchema, drawerSchema, dropdownMenuSchema, dropzoneSchema, fileTreeSchema, formSchema, gridSchema, hoverCardSchema, inputOTPSchema, inputSchema, labelSchema, menubarSchema, multiComboboxSchema, navigationMenuSchema, paginationSchema, popoverSchema, progressSchema, radioGroupSchema, resizableSchema, scrollAreaSchema, selectSchema, separatorSchema, sheetSchema, sidebarSchema, skeletonSchema, sliderSchema, sonnerSchema, spacerSchema, stackSchema, stepperSchema, switchSchema, tableSchema, tabsSchema, textareaSchema, timePickerSchema, timelineSchema, toggleGroupSchema, toggleSchema, tooltipSchema };
+// src/primitives/empty/empty.schema.ts
+var emptySchema = {
+  name: "empty",
+  displayName: "Empty",
+  description: "A zero-state surface for lists, dashboards, and search results with no content. Explains why the slot is empty + provides a call-to-action.",
+  category: "primitive",
+  subcategory: "feedback",
+  props: [
+    {
+      name: "icon",
+      type: "ReactNode",
+      required: false,
+      description: "Icon (typically an <svg>) rendered in a circular muted container above the title."
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      required: true,
+      description: "Heading copy. Becomes the region's accessible name via aria-labelledby."
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      required: false,
+      description: "Supporting copy that explains why the slot is empty + what to do next."
+    },
+    {
+      name: "action",
+      type: "ReactNode",
+      required: false,
+      description: "Call-to-action \u2014 typically a <Button> that creates the missing record."
+    },
+    {
+      name: "titleAs",
+      type: "enum",
+      required: false,
+      default: "h3",
+      description: "Heading level for the title. Pick to match surrounding heading hierarchy.",
+      enumValues: ["h2", "h3", "h4", "h5", "h6", "p"]
+    },
+    {
+      name: "size",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "Visual scale.",
+      enumValues: ["sm", "default", "lg"]
+    }
+  ],
+  variants: [
+    {
+      name: "size",
+      description: "Vertical density of the empty-state surface.",
+      values: [
+        {
+          value: "sm",
+          description: "Compact \u2014 fits inside a card / panel.",
+          useWhen: "the empty surface is one of several stacked pieces of content; full-bleed would dominate"
+        },
+        {
+          value: "default",
+          description: "Standard \u2014 for table / list / dashboard widget empty states.",
+          useWhen: "default everywhere; the only size you need on most surfaces"
+        },
+        {
+          value: "lg",
+          description: "Large \u2014 for full-page empty states (no items at all yet).",
+          useWhen: "the empty surface owns the entire page \u2014 onboarding, first-run, no records yet"
+        }
+      ],
+      default: "default"
+    }
+  ],
+  slots: [
+    {
+      name: "icon",
+      description: "Icon rendered in the circular muted container above the title.",
+      required: false,
+      acceptedTypes: ["ReactNode"]
+    },
+    {
+      name: "action",
+      description: "Call-to-action button under the description.",
+      required: false,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted", "muted-foreground", "foreground", "border"],
+  examples: [
+    {
+      title: "List zero-state",
+      description: "Inbox with no messages \u2014 icon + title + description + compose button",
+      code: '<Empty\n  icon={<InboxIcon />}\n  title="No messages yet"\n  description="When someone sends a message, it shows up here."\n  action={<Button>Compose</Button>}\n/>',
+      composition: ["zero-state", "list", "with-action"]
+    },
+    {
+      title: "Search zero-state",
+      description: "Search returned zero results \u2014 show the query + suggest a reset",
+      code: '<Empty\n  icon={<SearchIcon />}\n  title="No results found"\n  description={`No items match "${query}". Try a different search.`}\n  action={<Button variant="secondary" onClick={onReset}>Clear search</Button>}\n  size="sm"\n/>',
+      composition: ["zero-state", "search"]
+    },
+    {
+      title: "Onboarding",
+      description: "Full-page first-run state",
+      code: '<Empty\n  icon={<SparklesIcon />}\n  title="Welcome to your dashboard"\n  description="Create your first project to get started."\n  action={<Button size="lg">Create project</Button>}\n  size="lg"\n  titleAs="h1"\n/>',
+      composition: ["zero-state", "onboarding", "first-run"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use for lists, search results, or dashboards where the request returned successfully but there's nothing to show. Explain why and what to do \u2014 the title names the absence, the description sets context, the action gives a way out.",
+    whenNotToUse: "Don't use while data is still loading (use Loading). Don't use when something failed (use ErrorState). Don't use for inline form-field 'no options' messages (use Combobox's empty slot or Form's helper text).",
+    commonMistakes: [
+      "Using Empty without an action \u2014 leaves the user stuck",
+      "Long descriptions \u2014 keep to one sentence; this is a state surface, not documentation",
+      "Forgetting titleAs when the page already has an h2 above (heading hierarchy break)"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using Empty while data is still being fetched",
+        insteadUse: "loading",
+        why: "Empty announces 'no items exist'; Loading announces 'fetching items.' Showing Empty during the fetch flashes a misleading 'no results' state then snaps to real data on resolution."
+      },
+      {
+        mistake: "Using Empty to display a fetch failure",
+        insteadUse: "error-state",
+        why: "ErrorState carries role='alert' so screen readers announce the failure on first render, AND it ships a retry affordance. Empty is silent on retry semantics."
+      },
+      {
+        mistake: "Using Empty as an inline 'no matching options' notice inside a Combobox or Select",
+        insteadUse: "combobox",
+        why: "Combobox + Command already render a sub-AA-conformant empty state inside the listbox. Using Empty there leaks the page-level zero-state language into a focused interaction."
+      }
+    ],
+    relatedComponents: ["loading", "error-state", "alert", "card", "skeleton"],
+    accessibilityNotes: "Wrapped in a region landmark labeled by the title (aria-labelledby + auto-generated id). Icon is decorative (aria-hidden). Pair the action with a Button that has a visible label.",
+    tokenBudget: 350
+  },
+  tags: ["empty", "zero-state", "feedback", "list", "dashboard"]
+};
+
+// src/primitives/loading/loading.schema.ts
+var loadingSchema = {
+  name: "loading",
+  displayName: "Loading",
+  description: "A composed loading-placeholder pattern for lists, cards, and stacks. Skeleton is the atom; Loading is the canonical molecule most surfaces want.",
+  category: "primitive",
+  subcategory: "feedback",
+  props: [
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      default: "list",
+      description: "Layout family \u2014 picks the row shape.",
+      enumValues: ["list", "card", "stack"]
+    },
+    {
+      name: "rows",
+      type: "number",
+      required: false,
+      default: 3,
+      description: "Number of placeholder rows to render. Each row may contain multiple Skeleton elements depending on variant \u2014 list emits 1 per row; card emits 3 (heading + 2 body lines); stack emits 3 (avatar + 2 text lines)."
+    },
+    {
+      name: "label",
+      type: "string",
+      required: false,
+      default: "Loading\u2026",
+      description: "sr-only label announced by screen readers via aria-live polite."
+    },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [
+    {
+      name: "variant",
+      description: "Layout family for the placeholder rows.",
+      values: [
+        {
+          value: "list",
+          description: "Single full-width line per row \u2014 table / list / sidebar nav loaders.",
+          useWhen: "the surface being filled is a flat list of equally-shaped rows"
+        },
+        {
+          value: "card",
+          description: "Heading + two body lines inside a bordered card surface.",
+          useWhen: "loading a Card-shaped widget (settings panel, dashboard tile)"
+        },
+        {
+          value: "stack",
+          description: "Avatar + two-line text block per row \u2014 message / contact / search-result loaders.",
+          useWhen: "loading a list of avatar-paired items (chat history, contact list, comment thread)"
+        }
+      ],
+      default: "list"
+    }
+  ],
+  slots: [],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: ["skeleton"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted", "card", "border"],
+  examples: [
+    {
+      title: "List loader",
+      description: "5 placeholder rows for a dashboard table",
+      code: '<Loading rows={5} variant="list" />',
+      composition: ["loading", "table"]
+    },
+    {
+      title: "Card loader",
+      description: "Card-shaped placeholder with heading + 2 body lines",
+      code: '<Loading variant="card" />',
+      composition: ["loading", "card", "widget"]
+    },
+    {
+      title: "Stack loader (chat / contacts)",
+      description: "Avatar + 2-line text rows",
+      code: '<Loading rows={4} variant="stack" />',
+      composition: ["loading", "stack", "chat"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use when fetching data for a list, card, or avatar-paired stack and you want pre-arranged placeholders. Pair the rows count with how many items you expect \u2014 avoid 10-row loaders for 2-item results (jarring on resolve).",
+    whenNotToUse: "Don't use for a single shaped placeholder (use Skeleton). Don't use when the wait has a measurable percent-done (use Progress). Don't use for full-page transitions where a top progress bar is more informative.",
+    commonMistakes: [
+      "Forgetting `aria-live` would prevent screen-reader announcement \u2014 Loading already wires it; don't override role",
+      "Using too many rows \u2014 flashes a heavy 'something's wrong' impression",
+      "Applying Loading inside a Card AND also wrapping in another Card \u2014 double-bordered shimmer"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using Loading for a single shaped placeholder (avatar circle, heading line, image rectangle)",
+        insteadUse: "skeleton",
+        why: "Skeleton is the atom; render exactly one Skeleton with the right size class. Loading composes Skeletons for canonical multi-row patterns \u2014 no value if you only need one shape."
+      },
+      {
+        mistake: "Using Loading when the wait has a measurable percent (file upload, batch import)",
+        insteadUse: "progress",
+        why: "Progress's `value` prop announces actual completion to assistive tech. Loading is for indeterminate waits."
+      },
+      {
+        mistake: "Using Loading for a full-page route transition where the user just clicked a link",
+        insteadUse: "skeleton",
+        why: "Compose page-shaped Skeletons via `generateStaticParams` + Suspense; full-page Loading flashes 'work is happening here' while the right answer is 'show the page shell instantly.'"
+      }
+    ],
+    relatedComponents: ["skeleton", "progress", "empty", "error-state"],
+    accessibilityNotes: "role='status' + aria-live='polite' + sr-only label, so screen readers announce on first render. Caller doesn't need to wire any of this.",
+    tokenBudget: 300
+  },
+  tags: ["loading", "skeleton", "placeholder", "feedback"]
+};
+
+// src/primitives/error-state/error-state.schema.ts
+var errorStateSchema = {
+  name: "error-state",
+  displayName: "ErrorState",
+  description: "A surface for failed-fetch / failed-action states. Visually mirrors Empty but with destructive bias and an optional retry button. Mounts with role='alert' so screen readers announce on first render.",
+  category: "primitive",
+  subcategory: "feedback",
+  props: [
+    { name: "icon", type: "ReactNode", required: false, description: "Icon (typically an alert / x-circle SVG)." },
+    { name: "title", type: "ReactNode", required: false, default: "Something went wrong", description: "Heading copy. Falls back to a generic message." },
+    { name: "message", type: "ReactNode", required: true, description: "Body copy explaining what failed and (optionally) what the user can do." },
+    { name: "action", type: "ReactNode", required: false, description: "Call-to-action slot \u2014 typically a <Button onClick={refetch}>Retry</Button>. Consumer controls the button variant, loading state, and asChild composition." },
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "Visual tone \u2014 destructive draws more attention, default is calmer.",
+      enumValues: ["default", "destructive"]
+    }
+  ],
+  variants: [
+    {
+      name: "variant",
+      description: "Tone of the surface.",
+      values: [
+        {
+          value: "default",
+          description: "Muted neutral surface \u2014 for recoverable / transient failures.",
+          useWhen: "the failure is recoverable and you don't want to alarm: 'temporarily unavailable,' 'try again in a moment'"
+        },
+        {
+          value: "destructive",
+          description: "Tinted destructive surface \u2014 for hard / unrecoverable failures.",
+          useWhen: "the failure is significant: data lost, permission denied, server error 5xx"
+        }
+      ],
+      default: "default"
+    }
+  ],
+  slots: [
+    {
+      name: "icon",
+      description: "Icon rendered in the circular tinted container.",
+      required: false,
+      acceptedTypes: ["ReactNode"]
+    },
+    {
+      name: "action",
+      description: "Call-to-action \u2014 typically a Button. Consumer composes the button variant + click handler.",
+      required: false,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["destructive", "muted", "muted-foreground", "foreground", "border"],
+  examples: [
+    {
+      title: "Fetch failure with retry",
+      description: "Couldn't load messages \u2014 show the error + a Retry button in the action slot",
+      code: `<ErrorState
+  icon={<AlertCircleIcon />}
+  title="Couldn't load messages"
+  message="The server didn't respond. Check your connection and try again."
+  action={<Button onClick={() => refetch()}>Retry</Button>}
+/>`,
+      composition: ["error-state", "retry", "fetch-failure"]
+    },
+    {
+      title: "Hard failure (destructive)",
+      description: "Server returned 5xx and we want to alarm",
+      code: `<ErrorState
+  icon={<XCircleIcon />}
+  variant="destructive"
+  title="Sync failed"
+  message="We couldn't save your changes. They're still on this device \u2014 refresh to retry."
+/>`,
+      composition: ["error-state", "destructive", "sync-failure"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use for any failure surface where the user might benefit from context + a retry path. Pair with onRetry whenever the operation is genuinely retryable; omit it when the user has to take a different action (e.g. log in again).",
+    whenNotToUse: "Don't use for inline form-field errors (Form's <FormMessage> handles those). Don't use for blocking destructive confirmations (AlertDialog). Don't use for transient toasts (Sonner / Toaster).",
+    commonMistakes: [
+      "Generic 'Something went wrong' message without context \u2014 at minimum, name what failed",
+      "Using destructive variant for recoverable network blips (cries wolf)",
+      "Wiring the action's click handler to a function that doesn't actually re-trigger the failed operation",
+      "Forgetting the action slot when the failure IS retryable \u2014 leaves the user stuck"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using ErrorState for an inline form-field validation error",
+        insteadUse: "form",
+        why: "Form ships <FormMessage> which is wired to the field's aria-describedby. ErrorState announces page-level failures; using it inline duplicates the role='alert' on every keystroke and confuses assistive tech."
+      },
+      {
+        mistake: "Using ErrorState as a blocking destructive confirmation modal",
+        insteadUse: "alert-dialog",
+        why: "AlertDialog is role='alertdialog' (modal, focus-trapped, dismiss-on-Escape). ErrorState is a passive surface \u2014 no interaction guarantees. If you need the user to confirm before proceeding, use AlertDialog."
+      },
+      {
+        mistake: "Using ErrorState for a transient toast notification",
+        insteadUse: "sonner",
+        why: "Sonner / Toaster auto-dismiss + stack + animate. ErrorState sits in the layout. For 'fire-and-forget failure ack,' use the toaster."
+      }
+    ],
+    relatedComponents: ["alert", "alert-dialog", "form", "empty", "loading", "sonner"],
+    accessibilityNotes: "role='alert' so screen readers announce on first render. Icon decorative (aria-hidden). Retry button uses focus-visible ring; pressing it doesn't dismiss the surface \u2014 caller controls that via state.",
+    tokenBudget: 450
+  },
+  tags: ["error", "error-state", "failure", "retry", "feedback"]
+};
+
+// src/primitives/tag/tag.schema.ts
+var tagSchema = {
+  name: "tag",
+  displayName: "Tag",
+  description: "Interactive tag / chip primitive \u2014 Badge with an optional dismiss button. Mirrors Badge's variants so the visual sibling is obvious; ships with a close affordance for filter pills, multi-select selections, draft attachments.",
+  category: "primitive",
+  subcategory: "feedback",
+  props: [
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      default: "default",
+      description: "Visual style.",
+      enumValues: ["default", "secondary", "destructive", "outline"]
+    },
+    {
+      name: "icon",
+      type: "ReactNode",
+      required: false,
+      description: "Optional leading icon (sized 12x12 inside the tag)."
+    },
+    {
+      name: "onRemove",
+      type: "function",
+      required: false,
+      description: "Click handler for the close button. When provided, the dismiss \u2715 is rendered. Signature: () => void."
+    },
+    {
+      name: "removeLabel",
+      type: "string",
+      required: false,
+      description: "Override the auto-derived close-button aria-label (default: 'Remove ${children}')."
+    },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [
+    {
+      name: "variant",
+      description: "Visual style \u2014 mirrors Badge so users get consistent token use.",
+      values: [
+        {
+          value: "default",
+          description: "Primary-tinted filled tag.",
+          useWhen: "the tag represents an active selected state \u2014 applied filter, picked option"
+        },
+        {
+          value: "secondary",
+          description: "Muted neutral filled tag with a hairline border.",
+          useWhen: "default for everyday tags \u2014 list of selected items, draft attachments, filter pills"
+        },
+        {
+          value: "destructive",
+          description: "Red-tinted filled tag.",
+          useWhen: "the tag represents a flagged / problematic value \u2014 banned user, archived item"
+        },
+        {
+          value: "outline",
+          description: "Bordered transparent tag.",
+          useWhen: "the tag lives on a busy surface and shouldn't add visual fill weight"
+        }
+      ],
+      default: "default"
+    }
+  ],
+  slots: [
+    {
+      name: "icon",
+      description: "Leading icon (sized 12x12).",
+      required: false,
+      acceptedTypes: ["ReactNode"]
+    },
+    {
+      name: "children",
+      description: "Tag label content (string preferred for auto aria-label derivation).",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "primary-foreground", "secondary", "secondary-foreground", "destructive", "destructive-foreground", "foreground", "ring"],
+  examples: [
+    {
+      title: "Filter pill with dismiss",
+      description: "Removable filter chip in a search bar",
+      code: '<Tag variant="secondary" onRemove={() => removeFilter("urgent")}>Urgent</Tag>',
+      composition: ["filter", "search", "removable"]
+    },
+    {
+      title: "Multi-select selections",
+      description: "Stack of selected values with per-tag dismiss",
+      code: '<div className="flex flex-wrap gap-2">\n  {selected.map((tag) => (\n    <Tag key={tag} variant="secondary" onRemove={() => deselect(tag)}>\n      {tag}\n    </Tag>\n  ))}\n</div>',
+      composition: ["multi-select", "form", "removable"]
+    },
+    {
+      title: "Status tag (non-interactive)",
+      description: "Static tag without dismiss \u2014 equivalent to Badge but uses Tag for consistency",
+      code: '<Tag variant="outline">Beta</Tag>',
+      composition: ["status", "label"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use for tokens the user can dismiss: filter pills, multi-select selections, draft attachments. Pair onRemove with a state setter that drops the value from your collection.",
+    whenNotToUse: "Don't use for non-interactive labels (use Badge). Don't use for state-bearing 'click to filter' affordances \u2014 those should be Toggle or ToggleGroup so the active state is announced as 'pressed'/'not pressed' to assistive tech.",
+    commonMistakes: [
+      "Forgetting onRemove on a tag the user CAN dismiss \u2014 leaves the affordance invisible",
+      "Calling it Tag but rendering inside a list of static labels \u2014 confuses Tag (interactive) vs Badge (decorative) semantics",
+      "Wrapping the tag itself in a <button> \u2014 the dismiss button already handles its own click; double-button breaks accessibility"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using Tag without onRemove for a static / decorative label",
+        insteadUse: "badge",
+        why: "Badge is the non-interactive sibling. Tag without onRemove ships an unused close-button container \u2014 wasted DOM and ambiguous semantics. Reach for Badge when there's nothing to dismiss."
+      },
+      {
+        mistake: "Using Tag as a click-to-filter chip (selected vs unselected state)",
+        insteadUse: "toggle",
+        why: "Toggle's role='button' + aria-pressed announces selected state to AT. Tag's close-button doesn't model 'pressed'; consumers end up with non-announced state."
+      },
+      {
+        mistake: "Using Tag for a single-select dropdown's chosen value",
+        insteadUse: "select",
+        why: "Select renders its value text inside the trigger. Tag would duplicate the token and complicate the keyboard nav (focus on Tag's close vs Select's trigger)."
+      }
+    ],
+    relatedComponents: ["badge", "toggle", "toggle-group", "multi-combobox"],
+    accessibilityNotes: "Close button gets aria-label derived from children when they're a string ('Remove Urgent'). Override via removeLabel. Tag itself is a span \u2014 wrap in a list (`role='list'` + `role='listitem'`) when rendering N tags as a collection.",
+    tokenBudget: 350
+  },
+  tags: ["tag", "chip", "pill", "filter", "removable", "multi-select"]
+};
+
+// src/components/tree/tree.schema.ts
+var treeSchema = {
+  name: "tree",
+  displayName: "Tree",
+  description: "Generic hierarchical list with roving-tabindex keyboard navigation. Distinct from FileTree (which adds folder/file icon-by-extension logic) \u2014 Tree is content-agnostic for org charts, taxonomy pickers, navigation trees.",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    { name: "data", type: "object", required: true, description: "Root nodes (TreeNode[])." },
+    { name: "defaultExpanded", type: "object", required: false, description: "Initial expanded ids (uncontrolled). string[]." },
+    { name: "expanded", type: "object", required: false, description: "Controlled expanded ids. string[]." },
+    { name: "onExpandedChange", type: "function", required: false, description: "Callback (ids: string[]) => void." },
+    { name: "selected", type: "string", required: false, description: "Controlled selected node id." },
+    { name: "onSelect", type: "function", required: false, description: "Callback (id: string) => void on activation." },
+    { name: "aria-label", type: "string", required: true, description: "Accessible name for the tree landmark." },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["foreground", "accent", "accent-foreground", "ring"],
+  examples: [
+    {
+      title: "Org chart",
+      description: "Hierarchical staff tree with expand/select",
+      code: '<Tree\n  aria-label="Org chart"\n  data={[\n    { id: "ceo", label: "CEO", children: [\n      { id: "cto", label: "CTO", children: [{ id: "eng-lead", label: "Eng Lead" }] },\n      { id: "cmo", label: "CMO" },\n    ]},\n  ]}\n  defaultExpanded={["ceo"]}\n  onSelect={(id) => console.log(id)}\n/>',
+      composition: ["tree", "navigation", "hierarchy"]
+    },
+    {
+      title: "Taxonomy picker",
+      description: "Categorize a record by picking a leaf in a 3-level taxonomy",
+      code: '<Tree\n  aria-label="Category"\n  data={taxonomy}\n  selected={category}\n  onSelect={setCategory}\n/>',
+      composition: ["tree", "form", "picker"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use for hierarchical data the user navigates by keyboard or click \u2014 org charts, taxonomy pickers, generic nav trees. Pair with selected + onSelect for picker semantics; pair with onExpandedChange to control expansion externally.",
+    whenNotToUse: "Don't use for filesystem-shaped data \u2014 FileTree adds folder/file icon-by-extension. Don't use for two-level groupings without item-selection \u2014 Accordion is the cleaner abstraction. Don't use for primary site nav (NavigationMenu).",
+    commonMistakes: [
+      "Forgetting aria-label \u2014 required, no fallback",
+      "Confusing data prop (TreeNode[]) with FileTree's nodes prop (FileTreeNode[]) \u2014 same shape but different icon defaults",
+      "Trying to pass selected without onSelect \u2014 controlled-mode without an updater leaves it stuck"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using Tree for filesystem-shaped data (folders + files with icon-by-extension)",
+        insteadUse: "file-tree",
+        why: "FileTree ships file/folder icon defaults + extension-based color hints. Tree is icon-agnostic \u2014 using it for files means hand-wiring icon logic each time."
+      },
+      {
+        mistake: "Using Tree for a two-level grouping (sections that expand to reveal content) without item-selection",
+        insteadUse: "accordion",
+        why: "Accordion is purpose-built for collapse-content-into-sections. Tree's role='tree' implies item-selection semantics that don't fit pure expand/collapse content groups."
+      },
+      {
+        mistake: "Using Tree for primary site / app navigation",
+        insteadUse: "navigation-menu",
+        why: "NavigationMenu ships landmark role + skip links + the right ARIA for primary nav. Tree's tree role is for data, not routing."
+      }
+    ],
+    relatedComponents: ["file-tree", "accordion", "navigation-menu"],
+    accessibilityNotes: "role='tree' on root, role='treeitem' per row, aria-expanded on parents, aria-selected on the chosen leaf. Keyboard: \u2191\u2193 move focus, \u2192 expand (or jump to first child if expanded), \u2190 collapse (or jump to parent), Home/End first/last visible row, Enter/Space activate.",
+    tokenBudget: 700
+  },
+  tags: ["tree", "hierarchy", "navigation", "picker", "ARIA-tree"]
+};
+
+// src/components/toolbar/toolbar.schema.ts
+var toolbarSchema = {
+  name: "toolbar",
+  displayName: "Toolbar",
+  description: "A horizontal or vertical group of related controls (buttons, toggles, links, separators) with arrow-key roving focus. Wraps Radix Toolbar so the keyboard semantics are correct out of the box.",
+  category: "component",
+  subcategory: "navigation",
+  props: [
+    {
+      name: "orientation",
+      type: "enum",
+      required: false,
+      default: "horizontal",
+      description: "Layout direction. Drives arrow-key behavior \u2014 \u2190\u2192 for horizontal, \u2191\u2193 for vertical.",
+      enumValues: ["horizontal", "vertical"]
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: true,
+      description: "Accessible name for the toolbar landmark. Toolbar mounts as a role='toolbar' region \u2014 without a name, AT users hear an unlabelled landmark. If a visible heading sits adjacent, you may pair via aria-labelledby instead (which still satisfies this requirement)."
+    }
+  ],
+  variants: [
+    {
+      name: "orientation",
+      description: "Layout direction.",
+      values: [
+        {
+          value: "horizontal",
+          description: "Default \u2014 controls flow left-to-right.",
+          useWhen: "the toolbar sits at the top or bottom of a panel / editor"
+        },
+        {
+          value: "vertical",
+          description: "Controls flow top-to-bottom.",
+          useWhen: "the toolbar runs alongside a canvas / editor as a side rail"
+        }
+      ],
+      default: "horizontal"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "Mix of ToolbarButton / ToolbarToggleGroup / ToolbarToggleItem / ToolbarLink / ToolbarSeparator.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-toolbar", "class-variance-authority", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "border", "foreground", "accent", "accent-foreground", "ring"],
+  examples: [
+    {
+      title: "Editor toolbar with toggle group",
+      description: "Undo + Redo + Separator + alignment toggles",
+      code: '<Toolbar aria-label="Editor controls">\n  <ToolbarButton onClick={onUndo}>Undo</ToolbarButton>\n  <ToolbarButton onClick={onRedo}>Redo</ToolbarButton>\n  <ToolbarSeparator />\n  <ToolbarToggleGroup type="single" defaultValue="left">\n    <ToolbarToggleItem value="left">Left</ToolbarToggleItem>\n    <ToolbarToggleItem value="center">Center</ToolbarToggleItem>\n    <ToolbarToggleItem value="right">Right</ToolbarToggleItem>\n  </ToolbarToggleGroup>\n</Toolbar>',
+      composition: ["toolbar", "editor", "toggle-group"]
+    },
+    {
+      title: "Side-rail vertical toolbar",
+      description: "Vertical toolbar alongside a canvas",
+      code: '<Toolbar orientation="vertical" aria-label="Drawing tools">\n  <ToolbarToggleGroup type="single" defaultValue="select">\n    <ToolbarToggleItem value="select"><CursorIcon /></ToolbarToggleItem>\n    <ToolbarToggleItem value="pen"><PenIcon /></ToolbarToggleItem>\n    <ToolbarToggleItem value="eraser"><EraserIcon /></ToolbarToggleItem>\n  </ToolbarToggleGroup>\n  <ToolbarSeparator />\n  <ToolbarButton aria-label="Settings"><SettingsIcon /></ToolbarButton>\n</Toolbar>',
+      composition: ["toolbar", "vertical", "canvas", "icon-only"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use to group related controls that operate on a single content area (editor, canvas, table). The roving-tabindex behavior means Tab enters the toolbar at the first item, then arrow keys navigate within \u2014 preserves the surrounding page's tab order.",
+    whenNotToUse: "Don't use for app-level menus (use Menubar). Don't use for a single mutually-exclusive selection (use ToggleGroup directly \u2014 Toolbar is for groupING ToggleGroups + Buttons + Links). Don't use for navigation (use NavigationMenu).",
+    commonMistakes: [
+      "Forgetting aria-label when the toolbar isn't adjacent to a visible heading",
+      "Mixing controls that operate on different content areas \u2014 Toolbar implies a single target",
+      "Using Toolbar inside a Toolbar \u2014 nest a vertical Toolbar inside a horizontal one if you really need a 2D grid, but consider whether a single Toolbar with Separators is clearer"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using Toolbar for a single-axis mutually-exclusive selection (alignment, list-style)",
+        insteadUse: "toggle-group",
+        why: "Toolbar is the multi-control container. ToggleGroup directly gives you 'pick one of N' with proper keyboard semantics \u2014 adding a Toolbar wrapper just costs DOM."
+      },
+      {
+        mistake: "Using Toolbar for an application top-level menu (File, Edit, View, \u2026)",
+        insteadUse: "menubar",
+        why: "Menubar models nested menus with proper open-on-focus semantics. Toolbar is for flat command groups; the menu pattern needs Menubar."
+      },
+      {
+        mistake: "Using Toolbar for primary site / app navigation",
+        insteadUse: "navigation-menu",
+        why: "NavigationMenu ships landmark role + skip links + the right ARIA attributes for primary nav. Toolbar is for content-region controls, not page-level routing."
+      }
+    ],
+    relatedComponents: ["toggle", "toggle-group", "menubar", "navigation-menu", "separator"],
+    accessibilityNotes: "Radix wires role='toolbar', roving tabindex (Tab enters at the first focusable item, arrows move within), Home/End jump to first/last. Always pass aria-label when there's no visible heading next to the toolbar.",
+    tokenBudget: 600
+  },
+  tags: ["toolbar", "editor", "controls", "command-group"]
+};
+
+// src/ai/attachment/attachment.schema.ts
+var attachmentSchema = {
+  name: "attachment",
+  displayName: "Attachment",
+  description: "File / image thumbnail with optional remove affordance + upload-progress overlay. Composes with the AI Composer for multimodal message drafts. Auto-detects image vs file variant from MIME type + preview URL.",
+  category: "ai",
+  subcategory: "input",
+  props: [
+    {
+      name: "file",
+      type: "object",
+      required: true,
+      description: "Native File OR { name, size, type, preview? } metadata. Drives variant auto-detection (image+preview \u2192 thumbnail; else file icon + name + size)."
+    },
+    {
+      name: "onRemove",
+      type: "function",
+      required: false,
+      description: "Click handler for the \xD7 overlay button. Signature: () => void."
+    },
+    {
+      name: "progress",
+      type: "number",
+      required: false,
+      description: "Upload progress in [0, 1). Values >= 1 (or undefined) hide the progressbar \u2014 pass undefined once the upload completes. Internally scaled to 0\u2013100 for aria-valuenow so AT announces 'NN percent.'"
+    },
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      description: "Override the auto-detected variant. 'image' renders a thumbnail; 'file' renders icon + name + size.",
+      enumValues: ["file", "image"]
+    },
+    { name: "className", type: "string", required: false, description: "Additional CSS classes" }
+  ],
+  variants: [
+    {
+      name: "variant",
+      description: "Visual layout. Auto-detected unless overridden.",
+      values: [
+        {
+          value: "file",
+          description: "Generic file icon + name + size. Bordered card with horizontal padding.",
+          useWhen: "the attachment is a non-image (PDF, code, archive, audio) OR an image without a preview URL"
+        },
+        {
+          value: "image",
+          description: "80\xD780 thumbnail of the preview URL. Zero padding so the image fills the card.",
+          useWhen: "the attachment is an image AND a preview URL is available (use URL.createObjectURL on the File before passing in)"
+        }
+      ],
+      default: "file"
+    }
+  ],
+  slots: [],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: [],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "border", "foreground", "muted", "muted-foreground", "primary", "accent", "ring"],
+  examples: [
+    {
+      title: "Image preview in composer",
+      description: "Image attachment with remove affordance",
+      code: "function ComposerWithImage() {\n  const [file, setFile] = React.useState<File | null>(null);\n  const preview = file ? URL.createObjectURL(file) : null;\n  return (\n    <Composer>\n      {file && preview ? (\n        <Attachment\n          file={{ name: file.name, size: file.size, type: file.type, preview }}\n          onRemove={() => setFile(null)}\n        />\n      ) : null}\n      {/* \u2026textarea + send button\u2026 */}\n    </Composer>\n  );\n}",
+      composition: ["composer", "ai", "image", "removable"]
+    },
+    {
+      title: "Upload progress",
+      description: "File attachment with live progress overlay",
+      code: '<Attachment\n  file={{ name: "report.pdf", size: 2_400_000, type: "application/pdf" }}\n  progress={uploadProgress}\n  onRemove={() => cancelUpload()}\n/>',
+      composition: ["upload", "progress", "removable"]
+    },
+    {
+      title: "Static file preview (no remove)",
+      description: "Read-only attachment in a sent message",
+      code: '<Attachment file={{ name: "diagram.svg", size: 18000, type: "image/svg+xml" }} />',
+      composition: ["read-only", "message"]
+    }
+  ],
+  ai: {
+    whenToUse: "Use inside a Composer to show pending attachments the user can remove before sending, or inside a Message to show attached files in a sent turn. Pair native File objects with URL.createObjectURL(file) before rendering \u2014 the component doesn't manage object URLs.",
+    whenNotToUse: "Don't use for the upload-target affordance itself (that's Dropzone \u2014 it handles drag-drop + click-to-pick). Don't use for static document previews outside a chat composer (use Card with a file icon). Don't use for inline images in markdown \u2014 use Markdown's image rendering.",
+    commonMistakes: [
+      "Forgetting URL.createObjectURL on a native File \u2014 preview won't render and the variant falls back to file",
+      "Not revoking object URLs when the attachment is removed \u2014 leaks memory",
+      "Using Attachment without onRemove inside a Composer \u2014 leaves the user unable to remove"
+    ],
+    antiPatterns: [
+      {
+        mistake: "Using Attachment as the upload-input affordance (drag-drop area, click-to-pick)",
+        insteadUse: "dropzone",
+        why: "Dropzone is purpose-built for the upload-target \u2014 drag/drop semantics, click-to-pick, accept-MIME validation. Attachment SHOWS the result; Dropzone is the input."
+      },
+      {
+        mistake: "Using Attachment for static document previews on a profile / details page",
+        insteadUse: "card",
+        why: "Card is the static-content surface. Attachment ships remove + progress overlays consumers don't need outside the chat-composer flow."
+      },
+      {
+        mistake: "Using Attachment to render an inline image inside markdown body text",
+        insteadUse: "markdown",
+        why: "Markdown's `![alt](url)` already renders an inline image with the right semantics. Attachment is for the discrete-attachment-token UX (with name, size, remove); markdown handles inline media."
+      }
+    ],
+    relatedComponents: ["composer", "dropzone", "message", "message-list"],
+    accessibilityNotes: "Image variant uses <img alt> from the file name. Remove button gets aria-label='Remove ${name}'. Progress overlay is role='progressbar' with aria-valuemin=0 / aria-valuemax=100 / aria-valuenow=Math.round(progress * 100) and a generic 'Uploading ${name}' aria-label \u2014 AT announces 'NN percent.'",
+    tokenBudget: 500
+  },
+  tags: ["attachment", "ai", "composer", "file", "image", "upload", "multimodal"]
+};
+
+// src/ai/message/message.schema.ts
+var messageSchema = {
+  name: "message",
+  displayName: "Message",
+  description: "Single chat-message row scoped to one speaker (user / assistant / system / tool). Headless content slot \u2014 pair with Markdown, CodeBlock, or ToolCall children.",
+  category: "ai",
+  subcategory: "chat",
+  props: [
+    {
+      name: "role",
+      type: "enum",
+      required: true,
+      description: "Speaker. Drives variant styling and the data-role attribute.",
+      enumValues: ["user", "assistant", "system", "tool"]
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      required: true,
+      description: "Message content. Strings, Markdown, CodeBlock, ToolCall, or any composition."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes merged onto the row."
+    }
+  ],
+  variants: [
+    {
+      name: "role",
+      description: "Visual treatment per speaker.",
+      values: [
+        { value: "user", description: "Tinted secondary background \u2014 user turns.", useWhen: "The author is the human." },
+        { value: "assistant", description: "Card background \u2014 model output.", useWhen: "The author is the LLM/agent." },
+        { value: "system", description: "Muted, italic \u2014 system instructions.", useWhen: "Rendering a visible system prompt or framing message." },
+        { value: "tool", description: "Accent left-border \u2014 tool messages distinct from assistant text.", useWhen: "Showing raw tool/function output as its own turn." }
+      ],
+      default: "assistant"
+    }
+  ],
+  slots: [
+    {
+      name: "children",
+      description: "Message body. Compose with Markdown, CodeBlock, ToolCall, or plain text.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: ["lib/utils", "ai/types"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["secondary", "foreground", "card", "card-foreground", "muted", "muted-foreground", "accent", "accent-foreground"],
+  examples: [
+    {
+      title: "User and assistant turns",
+      description: "Two messages alternating roles.",
+      code: `<>
+  <Message role="user">What's the capital of France?</Message>
+  <Message role="assistant">Paris.</Message>
+</>`,
+      composition: ["chat", "turns"]
+    },
+    {
+      title: "Composed assistant turn",
+      description: "Markdown + ToolCall inside one assistant message.",
+      code: '<Message role="assistant">\n  <Markdown>{response}</Markdown>\n  <ToolCall name="search" state="result" result={hits} />\n</Message>',
+      composition: ["chat", "agent", "tool-use"]
+    }
+  ],
+  ai: {
+    whenToUse: "Wrap every conversation turn \u2014 user, assistant, system, or tool. Pair with MessageList for the scrolling viewport. Compose Markdown, CodeBlock, and ToolCall as children for rich assistant turns.",
+    whenNotToUse: "Don't use for non-conversational text (use Card or plain elements). Don't put streaming logic here \u2014 the consumer drives state, Message just renders.",
+    commonMistakes: [
+      "Adding streaming/fetch logic inside Message \u2014 keep it pure",
+      'Using `role="tool"` for assistant text that mentions a tool \u2014 `tool` is for the actual tool turn',
+      "Hard-coding markdown rendering inside Message \u2014 pass <Markdown>{...}</Markdown> as a child instead"
+    ],
+    relatedComponents: ["message-list", "markdown", "code-block", "tool-call", "message-actions"],
+    accessibilityNotes: 'Renders as a div with `data-role`. For screen-reader chat semantics, wrap MessageList in `role="log"` and consider `aria-live="polite"` on the streaming container.',
+    tokenBudget: 220
+  },
+  tags: ["ai", "chat", "message", "turn", "conversation"]
+};
+
+// src/ai/message-list/message-list.schema.ts
+var messageListSchema = {
+  name: "message-list",
+  displayName: "MessageList",
+  description: "Auto-scrolling viewport for a chat stream. Pins to the bottom during streaming unless the user scrolls up to read history.",
+  category: "ai",
+  subcategory: "chat",
+  props: [
+    {
+      name: "autoScroll",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Pin to bottom on content change (when the user is already near the bottom)."
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      required: true,
+      description: "Sequence of <Message> elements."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes (e.g. height, padding)."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Messages to render in order.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [],
+  examples: [
+    {
+      title: "Basic chat",
+      description: "Map messages from useChat into a viewport with bottom-pin behavior.",
+      code: '<MessageList className="h-96">\n  {messages.map((m) => (\n    <Message key={m.id} role={m.role}>{m.content}</Message>\n  ))}\n</MessageList>',
+      composition: ["chat", "scroll"]
+    }
+  ],
+  ai: {
+    whenToUse: "Wrap a list of <Message> components when you want auto-scroll-on-stream behavior. Always set an explicit height (h-*, max-h-*) on the className so the viewport actually scrolls.",
+    whenNotToUse: "Don't use for static FAQs or non-streaming layouts (use a normal Stack). Don't use as a generic scroll container \u2014 its bottom-pin behavior is opinionated.",
+    commonMistakes: [
+      "Forgetting to set a height \u2014 the viewport won't scroll without `h-*` or `max-h-*`",
+      "Disabling autoScroll while still expecting bottom-pin behavior \u2014 they're the same flag",
+      "Putting non-Message children inside \u2014 a divider or banner breaks the role=log semantics"
+    ],
+    relatedComponents: ["message", "composer", "loading-indicator"],
+    accessibilityNotes: 'Renders as `role="log"` with `aria-live="polite"` and `aria-relevant="additions"` so assistive tech announces new turns. If you replace turns wholesale (e.g. on regenerate), pass `aria-relevant="additions removals"` as a prop \u2014 props spread onto the underlying div and override the default.',
+    tokenBudget: 240
+  },
+  tags: ["ai", "chat", "scroll", "viewport", "streaming"]
+};
+
+// src/ai/composer/composer.schema.ts
+var composerSchema = {
+  name: "composer",
+  displayName: "Composer",
+  description: "Multi-line input + submission shell for chat. Submits on Enter (Shift+Enter inserts newline). Trailing slot for attachment + send buttons.",
+  category: "ai",
+  subcategory: "input",
+  props: [
+    {
+      name: "value",
+      type: "string",
+      required: true,
+      description: "Controlled textarea value."
+    },
+    {
+      name: "onValueChange",
+      type: "function",
+      required: true,
+      description: "Called with the new value on each keystroke."
+    },
+    {
+      name: "onSubmit",
+      type: "function",
+      required: true,
+      description: "Called with the trimmed value on Enter or form submit."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Lock the input and suppress submission (e.g. during streaming)."
+    },
+    {
+      name: "placeholder",
+      type: "string",
+      required: false,
+      description: "Textarea placeholder copy."
+    },
+    {
+      name: "submitOnEnter",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Submit when Enter is pressed without Shift. Disable to require button click."
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      required: false,
+      description: "Trailing slot \u2014 attachment buttons, voice toggle, send button, etc."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the form wrapper."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Trailing action buttons rendered after the textarea.",
+      required: false,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "ring", "muted-foreground"],
+  examples: [
+    {
+      title: "Basic composer",
+      description: "Controlled input + send button.",
+      code: 'const [value, setValue] = useState("");\n<Composer\n  value={value}\n  onValueChange={setValue}\n  onSubmit={(v) => { send(v); setValue(""); }}\n  placeholder="Ask anything\u2026"\n>\n  <Button type="submit" disabled={!value.trim()}>Send</Button>\n</Composer>',
+      composition: ["chat", "form"]
+    },
+    {
+      title: "With attachment slot",
+      description: "Attach button on the leading edge of the trailing slot.",
+      code: '<Composer value={v} onValueChange={setV} onSubmit={send}>\n  <Button variant="ghost" size="icon" onClick={pickFile}><Paperclip /></Button>\n  <Button type="submit">Send</Button>\n</Composer>',
+      composition: ["chat", "form", "attachment"]
+    }
+  ],
+  ai: {
+    whenToUse: "Wrap any user-input surface in an AI app \u2014 chatbots, AI editors, agent prompts. Pair with `useChat` from @ai-sdk/react or any equivalent state hook.",
+    whenNotToUse: "Don't use for non-chat forms (use Form + Textarea). Don't bake fetch/streaming logic into onSubmit \u2014 keep the network call in the consumer.",
+    commonMistakes: [
+      "Calling onSubmit with the raw event instead of the value \u2014 onSubmit receives the trimmed string already",
+      "Forgetting to clear `value` after submit \u2014 Composer is fully controlled",
+      "Wrapping the component in <form> \u2014 Composer renders its own form element"
+    ],
+    relatedComponents: ["message-list", "suggestion", "loading-indicator"],
+    accessibilityNotes: "Renders a real <form> + <textarea>, so Enter submission and screen-reader announcements work without extra ARIA. Pass `aria-label` on the wrapper if there's no visible label.",
+    tokenBudget: 280
+  },
+  tags: ["ai", "input", "chat", "form", "composer", "textarea"]
+};
+
+// src/ai/loading-indicator/loading-indicator.schema.ts
+var loadingIndicatorSchema = {
+  name: "loading-indicator",
+  displayName: "LoadingIndicator",
+  description: "Streaming/typing feedback with three motion variants \u2014 dots, pulse, bar.",
+  category: "ai",
+  subcategory: "feedback",
+  props: [
+    {
+      name: "variant",
+      type: "enum",
+      required: false,
+      default: "dots",
+      description: "Animation style.",
+      enumValues: ["dots", "pulse", "bar"]
+    },
+    {
+      name: "size",
+      type: "enum",
+      required: false,
+      default: "md",
+      description: "Text/icon scale.",
+      enumValues: ["sm", "md"]
+    },
+    {
+      name: "label",
+      type: "string",
+      required: false,
+      description: 'Optional adjacent text label (e.g. "Thinking\u2026").'
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes."
+    }
+  ],
+  variants: [
+    {
+      name: "variant",
+      description: "Motion style.",
+      values: [
+        { value: "dots", description: "Three bouncing dots \u2014 classic typing indicator.", useWhen: "You want a familiar chat-style loading affordance." },
+        { value: "pulse", description: "Single throbbing circle \u2014 minimal.", useWhen: "Tight inline space; one-character signal." },
+        { value: "bar", description: "Horizontal sweep \u2014 implies progress without claiming a percentage.", useWhen: "Longer-running task (search, retrieval) where dots feel too perpetual." }
+      ],
+      default: "dots"
+    }
+  ],
+  slots: [],
+  dependencies: {
+    npm: ["class-variance-authority", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted-foreground"],
+  examples: [
+    {
+      title: "Inline typing dots",
+      description: "Render while waiting for the first token.",
+      code: '{isLoading && <LoadingIndicator label="Thinking\u2026" />}',
+      composition: ["chat", "loading"]
+    }
+  ],
+  ai: {
+    whenToUse: "Show during the gap between submitting a prompt and the first streamed token, or while a long-running tool call is in flight.",
+    whenNotToUse: "Don't use for known-percent progress (use Progress). Don't keep visible after the first token streams in \u2014 stream itself signals activity.",
+    commonMistakes: [
+      "Leaving the indicator visible while content streams \u2014 overlap looks broken",
+      "Using `bar` for sub-second waits \u2014 the sweep can't complete a cycle"
+    ],
+    relatedComponents: ["message", "composer"],
+    accessibilityNotes: 'Renders as `role="status"` with `aria-live="polite"` and an `aria-label`. Pass a meaningful label so screen readers announce "Searching docs" rather than the default "Loading".',
+    tokenBudget: 200
+  },
+  tags: ["ai", "loading", "spinner", "typing", "indicator", "streaming"]
+};
+
+// src/ai/suggestion/suggestion.schema.ts
+var suggestionSchema = {
+  name: "suggestion",
+  displayName: "Suggestion",
+  description: "Clickable prompt pill / quick-action chip. Forwards a payload to onSelect on click.",
+  category: "ai",
+  subcategory: "input",
+  props: [
+    {
+      name: "value",
+      type: "string",
+      required: false,
+      description: "Payload sent to onSelect. Defaults to the rendered children when they are a string."
+    },
+    {
+      name: "onSelect",
+      type: "function",
+      required: true,
+      description: "Called with the payload when the chip is clicked."
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      required: true,
+      description: "Visible label."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Visible label of the chip.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["background", "secondary", "ring", "foreground"],
+  examples: [
+    {
+      title: "Starter prompts",
+      description: "Render onboarding suggestions and drop into the composer on click.",
+      code: '<Cluster gap="sm">\n  {STARTERS.map((s) => (\n    <Suggestion key={s} value={s} onSelect={setInput}>{s}</Suggestion>\n  ))}\n</Cluster>',
+      composition: ["chat", "onboarding", "prompts"]
+    }
+  ],
+  ai: {
+    whenToUse: "Show 3\u20136 starter prompts before the first turn, or follow-up prompts after an assistant turn. Combine with Cluster for wrap-friendly layout.",
+    whenNotToUse: "Don't use for navigation (use Button or a link). Don't auto-send on click without showing the user what's about to be sent \u2014 set the value into Composer first.",
+    commonMistakes: [
+      "Auto-firing onSelect into useChat.append without populating the input first \u2014 feels surprising",
+      "Long labels \u2014 these are pills, keep under ~40 chars"
+    ],
+    relatedComponents: ["composer", "cluster", "button"],
+    accessibilityNotes: "Real <button>, so keyboard activation and screen-reader announcement work natively. If the label is non-text, set `aria-label`.",
+    tokenBudget: 220
+  },
+  tags: ["ai", "suggestion", "prompt", "pill", "chip", "quick-action"]
+};
+
+// src/ai/tool-call/tool-call.schema.ts
+var toolCallSchema = {
+  name: "tool-call",
+  displayName: "ToolCall",
+  description: "Collapsible card showing a tool/function invocation \u2014 name, lifecycle state badge, expandable args + result body.",
+  category: "ai",
+  subcategory: "agent",
+  props: [
+    {
+      name: "name",
+      type: "string",
+      required: true,
+      description: "Tool / function name (e.g. searchDocs, getWeather)."
+    },
+    {
+      name: "state",
+      type: "enum",
+      required: true,
+      description: "Lifecycle of the invocation.",
+      enumValues: ["pending", "running", "result", "error"]
+    },
+    {
+      name: "args",
+      type: "object",
+      required: false,
+      description: "JSON-stringifiable input passed to the tool."
+    },
+    {
+      name: "result",
+      type: "object",
+      required: false,
+      description: "JSON-stringifiable output returned by the tool. May be a string for plain-text results."
+    },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Start expanded. Default collapsed to keep the chat clean."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the outer Collapsible root."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-collapsible", "clsx", "tailwind-merge"],
+    internal: ["lib/utils", "ai/types"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "card-foreground", "muted", "muted-foreground", "primary", "accent", "accent-foreground", "destructive", "ring", "background"],
+  examples: [
+    {
+      title: "Done invocation",
+      description: "Map an AI SDK `tool-*` part to a ToolCall.",
+      code: '<ToolCall\n  name="searchDocs"\n  state="result"\n  args={{ query: "auth" }}\n  result={{ hits: docs.length }}\n/>',
+      composition: ["agent", "tool-use"]
+    },
+    {
+      title: "Streaming run",
+      description: "While the tool is executing, show running state without args.",
+      code: '<ToolCall name="getWeather" state="running" args={{ city: "NYC" }} />',
+      composition: ["agent", "tool-use", "streaming"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render every tool/function invocation in an agent UI. Map AI SDK v5 `tool-TOOLNAME` parts (state: input-streaming|input-available|output-available|output-error) or LangChain `AIMessage.tool_calls` directly.",
+    whenNotToUse: "Don't use for plain assistant text (use Message). Don't render the tool's actual UI here \u2014 ToolCall is a debug/transparency card; for a rich tool UI, render that as a sibling node inside the Message.",
+    commonMistakes: [
+      "Passing the entire AI SDK part object as `result` \u2014 extract the output payload first",
+      "Setting `defaultOpen` for every call \u2014 quickly clutters the chat",
+      'Using `state="result"` for an error \u2014 use `error` so the user sees red'
+    ],
+    relatedComponents: ["message", "reasoning", "loading-indicator"],
+    accessibilityNotes: "Built on Radix Collapsible \u2014 keyboard expand/collapse with Enter/Space works natively. Add `aria-label` on the trigger if the tool name is opaque.",
+    tokenBudget: 320
+  },
+  tags: ["ai", "agent", "tool-call", "function-call", "collapsible", "transparency"]
+};
+
+// src/ai/reasoning/reasoning.schema.ts
+var reasoningSchema = {
+  name: "reasoning",
+  displayName: "Reasoning",
+  description: "Collapsible thinking-trace block for Anthropic-style reasoning or chain-of-thought scratchpads. Optional duration in the header.",
+  category: "ai",
+  subcategory: "agent",
+  props: [
+    {
+      name: "children",
+      type: "ReactNode",
+      required: true,
+      description: "Reasoning content. Wrap with Markdown for formatted thinking traces."
+    },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Start expanded. Default collapsed."
+    },
+    {
+      name: "durationMs",
+      type: "number",
+      required: false,
+      description: 'Time spent thinking in ms \u2014 renders "Thought for 4.2s" in the header.'
+    },
+    {
+      name: "label",
+      type: "string",
+      required: false,
+      description: "Override the default header label."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Reasoning trace body.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-collapsible", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["foreground", "muted", "muted-foreground", "ring"],
+  examples: [
+    {
+      title: "Thinking trace with duration",
+      description: 'Header reads "Thought for 4.2s" \u2014 body reveals the full trace on click.',
+      code: "<Reasoning durationMs={4200}>\n  <Markdown>{thinkingMarkdown}</Markdown>\n</Reasoning>",
+      composition: ["agent", "reasoning", "anthropic"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render Anthropic `thinking` blocks, chain-of-thought scratchpads, or any model-internal reasoning the user can optionally inspect.",
+    whenNotToUse: "Don't use for the assistant's actual answer (use Message). Don't auto-open for routine turns \u2014 only worth expanding for debug or trust-building UX.",
+    commonMistakes: [
+      "Showing reasoning that wasn't actually produced \u2014 fabricating thinking blocks erodes trust",
+      "`durationMs` measured from request start instead of model thinking time \u2014 use the model's reported duration when available"
+    ],
+    relatedComponents: ["message", "tool-call", "markdown"],
+    accessibilityNotes: "Radix Collapsible \u2014 keyboard expand/collapse via Enter/Space. The italic header is decorative; use the visible label for screen readers.",
+    tokenBudget: 280
+  },
+  tags: ["ai", "agent", "reasoning", "thinking", "chain-of-thought", "collapsible"]
+};
+
+// src/ai/message-actions/message-actions.schema.ts
+var messageActionsSchema = {
+  name: "message-actions",
+  displayName: "MessageActions",
+  description: "Inline action-button row beneath a message \u2014 copy, regenerate, thumbs-up/down. Pure container; consumer supplies the buttons + handlers.",
+  category: "ai",
+  subcategory: "chat",
+  props: [
+    {
+      name: "children",
+      type: "ReactNode",
+      required: true,
+      description: 'Action buttons (typically Button variant="ghost" size="icon").'
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Action buttons rendered in a horizontal row.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: [],
+  examples: [
+    {
+      title: "Copy + regenerate",
+      description: "Two ghost icon buttons under an assistant message.",
+      code: '<MessageActions>\n  <Button variant="ghost" size="icon" onClick={() => navigator.clipboard.writeText(text)}><CopyIcon /></Button>\n  <Button variant="ghost" size="icon" onClick={onRegenerate}><RetryIcon /></Button>\n</MessageActions>',
+      composition: ["chat", "actions"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render after assistant turns where the user might want to copy, regenerate, or rate the response. Combine with `group/message` on the parent Message to enable hover-reveal.",
+    whenNotToUse: "Don't use under user turns (no actions to take). Don't put primary CTAs here \u2014 actions row is for secondary, optional follow-ups.",
+    commonMistakes: [
+      "Forgetting `group/message` on the parent Message \u2014 hover-reveal won't trigger",
+      "Stacking too many buttons (more than ~4) \u2014 overwhelms the chat"
+    ],
+    relatedComponents: ["message", "button"],
+    accessibilityNotes: "Pure layout container. Each child button must carry its own `aria-label` since icon-only buttons have no accessible text.",
+    tokenBudget: 180
+  },
+  tags: ["ai", "chat", "actions", "row", "container"]
+};
+
+// src/ai/citation/citation.schema.ts
+var citationSchema = {
+  name: "citation",
+  displayName: "Citation",
+  description: "Source attribution chip \u2014 renders a citation for a RAG hit, search result, or any external reference. Becomes a focusable link when url is provided.",
+  category: "ai",
+  subcategory: "rag",
+  props: [
+    {
+      name: "title",
+      type: "string",
+      required: true,
+      description: 'Source title or filename (e.g. "auth-overview.md").'
+    },
+    {
+      name: "url",
+      type: "string",
+      required: false,
+      description: "If provided, the chip becomes an anchor opening in a new tab."
+    },
+    {
+      name: "page",
+      type: "number",
+      required: false,
+      description: 'Optional page number (renders "p.3").'
+    },
+    {
+      name: "index",
+      type: "number",
+      required: false,
+      description: 'Optional inline footnote number (renders "[1]").'
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      required: false,
+      description: "Trailing slot \u2014 extra metadata (e.g. relevance score)."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Trailing extras \u2014 relevance score, badge, etc.",
+      required: false,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "secondary", "ring", "foreground", "muted-foreground"],
+  examples: [
+    {
+      title: "Footnote-style citations",
+      description: "Numbered citations after an assistant turn.",
+      code: '<Cluster gap="xs">\n  {sources.map((s, i) => (\n    <Citation key={s.id} title={s.title} url={s.url} index={i + 1} />\n  ))}\n</Cluster>',
+      composition: ["rag", "citations"]
+    }
+  ],
+  ai: {
+    whenToUse: "Surface RAG/search-result sources after an assistant message. Use `index` for footnote-style numbering tied to inline `[1]` markers in the answer.",
+    whenNotToUse: "Don't use for general external links in chat (use Markdown). Don't fabricate sources \u2014 only render Citation for retrievals the model actually used.",
+    commonMistakes: [
+      "Showing the URL twice (in `title` AND `url`) \u2014 pick a human title separately",
+      'Skipping `target="_blank"` \u2014 handled automatically when url is set; don\'t override'
+    ],
+    relatedComponents: ["message", "cluster"],
+    accessibilityNotes: 'With `url`, renders a real anchor (`rel="noreferrer noopener"`). Without `url`, renders a static span. Add `aria-label` on the wrapper if title alone lacks context.',
+    tokenBudget: 240
+  },
+  tags: ["ai", "rag", "citation", "source", "footnote", "chip"]
+};
+
+// src/ai/markdown/markdown.schema.ts
+var markdownSchema = {
+  name: "markdown",
+  displayName: "Markdown",
+  description: "Streaming-safe markdown renderer wrapping Vercel's streamdown. Handles partial input mid-stream without throwing.",
+  category: "ai",
+  subcategory: "content",
+  props: [
+    {
+      name: "children",
+      type: "string",
+      required: true,
+      description: "Raw markdown. May be a partial chunk during streaming."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the root element."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "Markdown source as a string.",
+      required: true,
+      acceptedTypes: ["string"]
+    }
+  ],
+  dependencies: {
+    npm: ["streamdown", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["foreground", "primary"],
+  examples: [
+    {
+      title: "Streaming assistant turn",
+      description: "Render the in-flight assistant message as it arrives.",
+      code: '<Message role="assistant">\n  <Markdown>{message.content}</Markdown>\n</Message>',
+      composition: ["chat", "streaming", "markdown"]
+    },
+    {
+      title: "Custom rendering: drop down to Streamdown",
+      description: "For per-element overrides, use streamdown directly with our CodeBlock primitive.",
+      code: 'import { Streamdown } from "streamdown";\nimport { CodeBlock } from "@hex-core/components";\n\n<Streamdown components={{ pre: ({ children }) => <CodeBlock code={extractCode(children)} /> }}>\n  {markdown}\n</Streamdown>',
+      composition: ["chat", "code", "override"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render any markdown content from an LLM \u2014 assistant turns, system messages with formatting, RAG citations with inline links. Required for streaming because raw markdown parsers throw on unfinished input.",
+    whenNotToUse: "Don't use for plain text without formatting (just render the string). Don't bypass it for streamed content \u2014 partial input WILL break a non-streaming parser.",
+    commonMistakes: [
+      "Passing JSX children instead of a markdown string \u2014 Markdown only accepts strings",
+      "Trying to override per-element renderers via Markdown \u2014 drop down to `Streamdown` directly for that (we keep our public surface minimal so the DTS bundle doesn't drag in shiki's giant language union)",
+      "Forgetting Tailwind Typography (`prose`) classes are required to style the output"
+    ],
+    relatedComponents: ["message", "code-block", "citation"],
+    accessibilityNotes: "Inherits semantics from streamdown: real headings, lists, links. Verify Tailwind Typography (prose) is enabled in your CSS \u2014 without it, output renders unstyled.",
+    tokenBudget: 280
+  },
+  tags: ["ai", "markdown", "streaming", "content", "renderer"]
+};
+
+// src/ai/code-block/code-block.schema.ts
+var codeBlockSchema = {
+  name: "code-block",
+  displayName: "CodeBlock",
+  description: "Server-rendered, syntax-highlighted code block with a language-label header and a copy button. Dual-theme via Shiki \u2014 same HTML for light + dark.",
+  category: "ai",
+  subcategory: "content",
+  props: [
+    {
+      name: "code",
+      type: "string",
+      required: true,
+      description: "The code to display. Plain text \u2014 no markdown fences."
+    },
+    {
+      name: "label",
+      type: "string",
+      required: false,
+      description: 'Header label (e.g. "pnpm", "tsx"). Inferred from `language` if omitted.'
+    },
+    {
+      name: "language",
+      type: "enum",
+      required: false,
+      description: "Shiki grammar key. Overrides inference from `label`.",
+      enumValues: ["bash", "ts", "tsx", "js", "jsx", "json", "css", "html", "md", "py", "text"]
+    },
+    {
+      name: "themes",
+      type: "object",
+      required: false,
+      default: { light: "github-light-high-contrast", dark: "github-dark" },
+      description: "Override the default theme pair. Keys: `light`, `dark` \u2014 values are Shiki theme IDs."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the outer card."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["shiki", "clsx", "tailwind-merge"],
+    internal: ["lib/utils", "ai/code-block-copy"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "card-foreground", "muted", "muted-foreground", "border"],
+  examples: [
+    {
+      title: "Install command",
+      description: "Header label drives both the visible chip and Shiki grammar inference.",
+      code: '<CodeBlock label="pnpm" code="pnpm add @hex-core/components" />',
+      composition: ["docs", "install"]
+    },
+    {
+      title: "Inline TS sample",
+      description: "Explicit language overrides label inference.",
+      code: '<CodeBlock language="tsx" code={`<Button>Click</Button>`} />',
+      composition: ["docs", "code"]
+    }
+  ],
+  ai: {
+    whenToUse: "Render any code snippet in docs, copy-to-clipboard install commands, or static AI chat output where server rendering is acceptable. Pair with Markdown's `components.pre` override to take over markdown code fences.",
+    whenNotToUse: "Don't use for streaming chat where the code grows mid-render \u2014 async Server Components can't update token-by-token. Use Streamdown's built-in client CodeBlock for that.",
+    commonMistakes: [
+      "Passing markdown-fenced code (with ```) \u2014 strip the fences first",
+      "Forgetting that this is async \u2014 must be awaited or rendered as RSC",
+      "Using a Shiki theme that isn't bundled \u2014 fails with a runtime fetch error"
+    ],
+    relatedComponents: ["markdown", "message"],
+    accessibilityNotes: "Highlighted output is plain text inside a `<pre>` \u2014 screen readers read it normally. The copy button has its own `aria-label`. Add a meaningful `aria-label` on the wrapper if the label alone isn't descriptive.",
+    tokenBudget: 320
+  },
+  tags: ["ai", "code", "shiki", "highlight", "copy", "rsc"]
+};
+
+export { accordionSchema, alertDialogSchema, alertSchema, aspectRatioSchema, attachmentSchema, avatarSchema, badgeSchema, breadcrumbSchema, buttonSchema, calendarSchema, cardSchema, checkboxSchema, citationSchema, clusterSchema, codeBlockSchema, collapsibleSchema, colorPickerSchema, comboboxSchema, commandSchema, composerSchema, containerSchema, contextMenuSchema, dataTableSchema, datePickerSchema, dialogSchema, drawerSchema, dropdownMenuSchema, dropzoneSchema, emptySchema, errorStateSchema, fileTreeSchema, formSchema, gridSchema, hoverCardSchema, inputOTPSchema, inputSchema, labelSchema, loadingIndicatorSchema, loadingSchema, markdownSchema, menubarSchema, messageActionsSchema, messageListSchema, messageSchema, multiComboboxSchema, navigationMenuSchema, paginationSchema, popoverSchema, progressSchema, radioGroupSchema, reasoningSchema, resizableSchema, scrollAreaSchema, selectSchema, separatorSchema, sheetSchema, sidebarSchema, skeletonSchema, sliderSchema, sonnerSchema, spacerSchema, stackSchema, stepperSchema, suggestionSchema, switchSchema, tableSchema, tabsSchema, tagSchema, textareaSchema, timePickerSchema, timelineSchema, toggleGroupSchema, toggleSchema, toolCallSchema, toolbarSchema, tooltipSchema, treeSchema };
 //# sourceMappingURL=schemas.js.map
 //# sourceMappingURL=schemas.js.map