@hex-core/components 1.5.0 → 1.7.0

package/dist/schemas.js

@@ -1646,7 +1646,7 @@ var toggleGroupSchema = {
       "clsx",
       "tailwind-merge"
     ],
-    internal: ["toggle"],
+    internal: ["primitives/toggle/toggle"],
     peer: ["react", "react-dom"]
   },
   tokensUsed: ["muted", "accent", "accent-foreground", "ring"],
@@ -1704,7 +1704,7 @@ var formSchema = {
       "clsx",
       "tailwind-merge"
     ],
-    internal: ["label"],
+    internal: ["primitives/label/label"],
     peer: ["react", "react-dom"]
   },
   tokensUsed: ["destructive", "muted-foreground"],
@@ -4638,6 +4638,806 @@ var sidebarSchema = {
   tags: ["sidebar", "navigation", "app-shell", "layout"]
 };
 
+// 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: ["primitives/skeleton/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",
@@ -5439,7 +6239,7 @@ var codeBlockSchema = {
       name: "themes",
       type: "object",
       required: false,
-      default: { light: "github-light", dark: "github-dark" },
+      default: { light: "github-light-high-contrast", dark: "github-dark" },
       description: "Override the default theme pair. Keys: `light`, `dark` \u2014 values are Shiki theme IDs."
     },
     {
@@ -5486,6 +6286,6 @@ var codeBlockSchema = {
   tags: ["ai", "code", "shiki", "highlight", "copy", "rsc"]
 };
 
-export { accordionSchema, alertDialogSchema, alertSchema, aspectRatioSchema, avatarSchema, badgeSchema, breadcrumbSchema, buttonSchema, calendarSchema, cardSchema, checkboxSchema, citationSchema, clusterSchema, codeBlockSchema, collapsibleSchema, colorPickerSchema, comboboxSchema, commandSchema, composerSchema, containerSchema, contextMenuSchema, dataTableSchema, datePickerSchema, dialogSchema, drawerSchema, dropdownMenuSchema, dropzoneSchema, fileTreeSchema, formSchema, gridSchema, hoverCardSchema, inputOTPSchema, inputSchema, labelSchema, loadingIndicatorSchema, 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, textareaSchema, timePickerSchema, timelineSchema, toggleGroupSchema, toggleSchema, toolCallSchema, tooltipSchema };
+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