makersclaw 0.2.0 → 0.3.0

package/templates/next/files/components/ui/tooltip.jsx

@@ -0,0 +1,270 @@
+"use client";
+
+import { useEffect, useId, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { cx } from "./cx";
+import { panelClass, usePopoverPosition } from "./popover";
+
+// Tooltip and HoverCard — what shows while the pointer rests on something,
+// placed by usePopoverPosition (./popover). Both wrap their trigger in an
+// inline span that listens; neither is the only way to learn anything.
+//
+// Tooltip — a short label for a control: the name of an icon button, a
+// shortcut. Hover (after `delay`) or keyboard focus shows it; leaving,
+// clicking, blur or Escape hides it. While one shows (or just after), the
+// next opens at once, so running along a toolbar reads every label. Plain text only:
+// it never holds a link or a button. A `popover="hint"` where the browser
+// has it (one hint at a time, never closing an open Popover), else
+// "manual" with the same rules kept here.
+//
+//   <Tooltip label="Copy link"><IconButton icon="link" label="Copy link" /></Tooltip>
+//
+//   label   the text; nothing (or "") renders the child alone
+//   side    top (default) · right · bottom · left; align start · center · end
+//   delay   ms before a hover shows it (default 500)
+//
+// Touch shows nothing, on purpose: a long press belongs to the OS (text
+// selection, the link menu) and a tap is the action. So what a touch user
+// needs is visible or in the control's label — the tooltip only repeats
+// it for the pointer. The child's `title` is removed while it is wrapped,
+// so the browser's own tooltip does not double this one, and the label is
+// tied to the child's control with aria-describedby unless it already is
+// that control's name.
+//
+// HoverCard — a richer preview of what a link or a name points at: a
+// person's card, a company's summary. Opens after `openDelay` on hover or
+// keyboard focus, stays while the pointer or focus is on the trigger or
+// the card, closes `closeDelay` after both are left, or on Escape. It may
+// hold any content — links, buttons, blocks — because it is portalled to
+// <body>; Tab from the trigger walks into it and out again. Touch shows
+// nothing — the tap follows the link — so the card only previews what the
+// link's own page shows in full.
+//
+//   <HoverCard trigger={<a href="/people/ada">Ada Lovelace</a>}>…the card…</HoverCard>
+//
+//   trigger     the inline thing hovered: a link, a name, an avatar
+//   side        bottom (default) · top · right · left; align start · center · end
+//   width       sm · md (default) · lg · auto, as Popover
+//   openDelay   ms (default 600); closeDelay ms (default 300)
+//   className   the card's (it has p-4 unless it names a padding)
+
+const FOCUSABLE = 'a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])';
+
+// "hint" where the browser has it; the attribute reads back "manual" where not.
+function hintable() {
+  const d = document.createElement("div");
+  d.popover = "hint";
+  return d.popover === "hint";
+}
+
+// One tooltip at a time, and the warm-up skipped just after one closed.
+let hideShown = null;
+let closedAt = 0;
+
+// Show, hide and their timer, made once per mounted part: they read only
+// refs, so the Escape listener added on show is the one removed on hide.
+function useFloat(panel, { onHide } = {}) {
+  const api = useRef(null);
+  if (!api.current) {
+    let timer = 0;
+    const self = {
+      later(fn, ms) {
+        clearTimeout(timer);
+        timer = setTimeout(fn, ms);
+      },
+      cancel: () => clearTimeout(timer),
+      isOpen: () => Boolean(panel.current?.matches(":popover-open")),
+      show() {
+        clearTimeout(timer);
+        if (!panel.current || self.isOpen()) return;
+        panel.current.showPopover();
+        document.addEventListener("keydown", self.onKey);
+      },
+      hide() {
+        clearTimeout(timer);
+        document.removeEventListener("keydown", self.onKey);
+        if (!self.isOpen()) return;
+        const inside = panel.current.contains(document.activeElement);
+        panel.current.hidePopover();
+        onHide?.(inside);
+      },
+      onKey(e) {
+        if (e.key === "Escape") self.hide();
+      },
+    };
+    api.current = self;
+  }
+  useEffect(() => () => {
+    api.current.cancel();
+    document.removeEventListener("keydown", api.current.onKey);
+  }, []);
+  return api.current;
+}
+
+export function Tooltip({ label, side = "top", align = "center", delay = 500, className, children }) {
+  const id = useId();
+  const anchor = useRef(null);
+  const tip = useRef(null);
+  usePopoverPosition(anchor, tip, { side, align, offset: 6 });
+  const f = useFloat(tip);
+
+  useEffect(() => {
+    const t = tip.current;
+    const control = anchor.current?.querySelector(FOCUSABLE) ?? anchor.current?.firstElementChild;
+    if (!t || !control) return;
+    if (hintable()) t.setAttribute("popover", "hint");
+    const title = control.getAttribute("title");
+    if (title !== null) control.removeAttribute("title");
+    const name = (control.getAttribute("aria-label") ?? control.textContent ?? "").trim();
+    const describe = name !== String(label).trim();
+    if (describe) control.setAttribute("aria-describedby", id);
+    return () => {
+      if (title !== null) control.setAttribute("title", title);
+      if (describe) control.removeAttribute("aria-describedby");
+    };
+  }, [id, label]);
+
+  if (!label) return children;
+
+  function show() {
+    if (hideShown && hideShown !== f.hide) hideShown();
+    f.show();
+    hideShown = f.hide;
+  }
+
+  return (
+    <>
+      <span
+        ref={anchor}
+        className="inline-flex"
+        onPointerEnter={(e) => e.pointerType !== "touch" && f.later(show, hideShown || Date.now() - closedAt < 400 ? 0 : delay)}
+        onPointerLeave={() => f.later(f.hide, 80)}
+        onPointerDown={f.hide}
+        onFocus={(e) => e.target.matches(":focus-visible") && show()}
+        onBlur={f.hide}
+      >
+        {children}
+      </span>
+      <span
+        ref={tip}
+        id={id}
+        role="tooltip"
+        popover="manual"
+        // However it closed (ours, or a hint's own Escape and light dismiss).
+        onToggle={(e) => {
+          if (e.newState !== "closed") return;
+          f.hide();
+          closedAt = Date.now();
+          if (hideShown === f.hide) hideShown = null;
+        }}
+        // A pointer crossing the gap onto the label keeps it (WCAG 1.4.13).
+        onPointerEnter={f.cancel}
+        onPointerLeave={() => f.later(f.hide, 80)}
+        className={cx(
+          "max-w-64 rounded-md bg-foreground px-2 py-1 text-xs leading-snug text-background shadow-md text-balance",
+          "opacity-0 transition-[opacity,display,overlay] transition-discrete duration-100 open:opacity-100 starting:open:opacity-0 motion-reduce:transition-none",
+          className,
+        )}
+      >
+        {label}
+      </span>
+    </>
+  );
+}
+
+export function HoverCard({
+  trigger,
+  side = "bottom",
+  align = "center",
+  width = "md",
+  openDelay = 600,
+  closeDelay = 300,
+  className,
+  children,
+}) {
+  const anchor = useRef(null);
+  const card = useRef(null);
+  const hovering = useRef(false);
+  const [host, setHost] = useState(null);
+  useEffect(() => setHost(document.body), []);
+  usePopoverPosition(anchor, card, { side, align, offset: 8 });
+  // Focus inside the card goes back to the trigger, not to the page.
+  const control = () => anchor.current?.querySelector(FOCUSABLE);
+  const f = useFloat(card, { onHide: (inside) => inside && control()?.focus() });
+
+  // Pointer or focus on either the trigger or the card keeps it open.
+  const stay = {
+    onPointerEnter: (e) => {
+      if (e.pointerType === "touch") return;
+      hovering.current = true;
+      if (f.isOpen()) f.cancel();
+      else f.later(f.show, openDelay);
+    },
+    onPointerLeave: (e) => {
+      if (e.pointerType === "touch") return;
+      hovering.current = false;
+      f.later(f.hide, closeDelay);
+    },
+    onBlur: (e) => {
+      const to = e.relatedTarget;
+      if (to ? !anchor.current?.contains(to) && !card.current?.contains(to) : !hovering.current) f.later(f.hide, 0);
+    },
+  };
+
+  // The card lives at the end of <body> (a name in a <p> may not hold a
+  // <div>), so Tab is carried by hand: from the trigger into the open card,
+  // from the card's first control back to the trigger, and from its last
+  // on to whatever follows the trigger on the page.
+  function onTriggerKey(e) {
+    if (e.key !== "Tab" || e.shiftKey || !f.isOpen()) return;
+    const first = card.current?.querySelector(FOCUSABLE);
+    if (!first) return;
+    e.preventDefault();
+    first.focus();
+  }
+  function onCardKey(e) {
+    if (e.key !== "Tab") return;
+    const inCard = [...card.current.querySelectorAll(FOCUSABLE)];
+    const back = e.shiftKey && document.activeElement === inCard[0];
+    const on = !e.shiftKey && document.activeElement === inCard[inCard.length - 1];
+    if (!back && !on) return;
+    e.preventDefault();
+    const from = control();
+    if (back) return from?.focus();
+    const page = [...document.querySelectorAll(FOCUSABLE)].filter((n) => !card.current.contains(n) && n.tabIndex >= 0 && n.offsetParent);
+    f.hide();
+    (page[page.indexOf(from) + 1] ?? from)?.focus();
+  }
+
+  return (
+    <>
+      <span
+        ref={anchor}
+        className="inline"
+        {...stay}
+        onKeyDown={onTriggerKey}
+        onFocus={(e) => {
+          if (f.isOpen()) f.cancel();
+          else if (e.target.matches(":focus-visible")) f.later(f.show, openDelay);
+        }}
+      >
+        {trigger}
+      </span>
+      {host
+        ? createPortal(
+            <div
+              ref={card}
+              popover="manual"
+              {...stay}
+              onKeyDown={onCardKey}
+              onFocus={f.cancel}
+              className={panelClass(width, cx(!/(^|\s)p[xytrbl]?-/.test(className ?? "") && "p-4", "text-sm", className))}
+            >
+              {children}
+            </div>,
+            host,
+          )
+        : null}
+    </>
+  );
+}

package/templates/next/template.json

@@ -30,23 +30,23 @@
       "name": "button",
       "type": "component",
       "title": "Button, IconButton",
-      "description": "The one button: variant primary (one per surface) · secondary · quiet · danger · link; size md (44px) · sm; icon; href for a link. IconButton for an icon alone, label required.",
+      "description": "The one button: variant primary (one per surface) · secondary · quiet · danger · link (inline text: no padding, no min-height, wraps and truncates with its sentence; size inherit takes the sentence's text; tone primary · muted for a secondary link) · nav (a full-width, start-aligned, normal-weight navigation row, filled when aria-current); size md (44px) · sm; align center · start; icon; href for a link; loading (a spinner, same width, aria-busy, disabled). IconButton for an icon alone, label required.",
       "tags": ["button", "action", "link", "icon button"],
       "files": ["components/ui/button.jsx"]
     },
     {
       "name": "field",
       "type": "component",
-      "title": "Field, Input, Textarea, Select, Switch, Checkbox",
-      "description": "Form controls with their label, hint and error. Select with empty options renders a muted line, never a disabled dropdown.",
-      "tags": ["form", "input", "select", "dropdown", "textarea", "switch", "checkbox", "toggle"],
+      "title": "Field, Input, TimeInput, Textarea, Select, Switch, Checkbox",
+      "description": "Form controls with their label, hint and error. TimeInput is the native time input (\"HH:MM\"; min, max, step) with the kit's clock glyph in place of the browser's grey one. Textarea autoGrow grows with its text from minRows to maxRows. Select with empty options renders a muted line, never a disabled dropdown.",
+      "tags": ["form", "input", "select", "dropdown", "textarea", "switch", "checkbox", "toggle", "time", "time picker"],
       "files": ["components/ui/field.jsx"]
     },
     {
       "name": "notice",
       "type": "component",
       "title": "Card, Notice, Badge, Kicker, Empty",
-      "description": "Containers and signals: Card, Notice (tone neutral · info · success · warning · danger), Badge, Kicker (the small line above a heading), Empty (a search or filter with no matches).",
+      "description": "Containers and signals: Card (padding md · sm · none; titleSize md · lg), Notice (tone neutral · info · success · warning · danger), Badge (tone neutral · primary · success · warning · danger · info; variant label — small caps · soft — sentence case, every tone tinted, primary included · outline — sentence case, a hairline on no fill · code — the mono face in its own case for a version tag or a commit hash; hue 1..5 a categorical colour from --color-chart-N for kinds of things, never status: soft a hue tint with a hue dot, label filled, outline a hue hairline, the text always readable), Kicker (the small line above a heading), Empty (a search or filter with no matches).",
       "tags": ["card", "alert", "notice", "badge", "empty state", "status"],
       "files": ["components/ui/notice.jsx"]
     },
@@ -54,7 +54,7 @@
       "name": "sheet",
       "type": "component",
       "title": "Sheet, Confirm",
-      "description": "The one overlay — a rail beside the work (side end), a dialog (center) or a bottom sheet; every side is a bottom sheet on a narrow window. Confirm is the \"delete this?\" case.",
+      "description": "The one overlay — a rail beside the work (side end), a drawer from the leading edge (start, for navigation), a dialog (center) or a bottom sheet; every side is a bottom sheet on a narrow window. bare (with label): no header and a flush body, for a panel that draws its own top. Confirm is the \"delete this?\" case: consequences (a muted bullet list), requireText (type the exact text to unlock) and acknowledge (a checkbox to tick) hold Confirm disabled until each is met.",
       "tags": ["dialog", "modal", "drawer", "overlay", "confirm", "rail"],
       "files": ["components/ui/sheet.jsx"]
     },
@@ -70,10 +70,74 @@
       "name": "menu",
       "type": "component",
       "title": "Menu",
-      "description": "The \"…\" of a row, on the Popover API. Empty items render nothing: a menu is earned by having actions.",
-      "tags": ["menu", "dropdown", "actions", "overflow"],
+      "description": "The dropdown menu — the \"…\" of a row, a View or Account menu — on the Popover API, placed by usePopoverPosition (side, align; flips at the window's edge). Data-driven items: actions (icon, tone danger, disabled, shortcut drawn as keys, description), labelled groups, labels, separators, checkbox and radio items (they keep it open), submenus (to the side; inline on a phone). WAI-ARIA menu keys with typeahead. Trigger size sm (36px, default) · md (44px). Empty items render nothing: a menu is earned by having actions.",
+      "tags": ["menu", "dropdown", "dropdown-menu", "actions", "overflow", "submenu", "checkbox", "radio"],
       "files": ["components/ui/menu.jsx"]
     },
+    {
+      "name": "context-menu",
+      "type": "component",
+      "title": "ContextMenu",
+      "description": "The menu a right-click, a long press or Shift+F10 opens on a region, at the pointer; the same items as Menu (groups, checkboxes, radios, shortcuts, submenus) and the same keys. Never the only way to an action.",
+      "tags": ["menu", "context-menu", "right-click", "long-press", "actions"],
+      "files": ["components/ui/context-menu.jsx"]
+    },
+    {
+      "name": "popover",
+      "type": "component",
+      "title": "Popover, usePopoverPosition, panelClass",
+      "description": "A panel beside the control that opened it, on the Popover API with CSS anchor positioning (a measured fallback elsewhere): side top · right · bottom · left, align start · center · end, width sm · md · lg · auto; flips at the window's edge and tries the asked side first again on every open, follows scroll; controlled or not; focus moves in and back. usePopoverPosition places any floating panel.",
+      "tags": ["popover", "floating", "panel", "dropdown", "anchor", "flyout"],
+      "files": ["components/ui/popover.jsx"]
+    },
+    {
+      "name": "calendar",
+      "type": "component",
+      "title": "Calendar, parseDate, isDateString, toDateString, todayString, addDays, addMonths, startOfMonth, endOfMonth, dayOfWeek, formatDate, firstDayOfWeek",
+      "description": "A month grid, the WAI-ARIA date grid (arrows a day or a week, Page Up/Down a month, Home/End the week's edges, Enter picks): mode single · multiple · range, dates as \"YYYY-MM-DD\" strings in and out (no timezone drift); numberOfMonths side by side (stacked on a phone); captionLayout label · dropdown (month and year Selects) · none (the parent shows and moves a controlled month); min, max, disabled(date); today ringed, outside days muted, range start/middle/end; marked days (a dot in a tone, a label for readers; emphasizeMarked draws them bold and the rest muted; onlyMarked makes the rest unpickable, unstruck); week numbers; week start and names from Intl, weekStartsOn overrides; size md (44px days) · sm. The string-date helpers do the same arithmetic in a surface.",
+      "tags": ["calendar", "date", "month", "range", "schedule", "day picker", "week"],
+      "files": ["components/ui/calendar.jsx"]
+    },
+    {
+      "name": "date-picker",
+      "type": "component",
+      "title": "DatePicker, DateInput, DATE_PRESETS",
+      "description": "DatePicker: a field that reads like an input and opens a Calendar in a Popover — mode single · range (formatRange in the field), presets beside the calendar (true for Today, Last 7 days, This month… or your own), clearable, disabled, min/max, a hidden input for forms; goes in <Field>. DateInput: the browser's own typed date field with the Calendar one button away.",
+      "tags": ["date picker", "date", "range", "due date", "presets", "date input", "report period"],
+      "files": ["components/ui/date-picker.jsx"]
+    },
+    {
+      "name": "tooltip",
+      "type": "component",
+      "title": "Tooltip, HoverCard",
+      "description": "Tooltip: a short text label on hover (after a delay) or keyboard focus, side top · right · bottom · left; never on touch. HoverCard: a richer preview of a link or a name (a profile card) with open and close delays; may hold links.",
+      "tags": ["tooltip", "hint", "hover card", "preview", "profile card", "hover"],
+      "files": ["components/ui/tooltip.jsx"]
+    },
+    {
+      "name": "avatar",
+      "type": "component",
+      "title": "Avatar, AvatarGroup",
+      "description": "A person's face with initials from name while it loads and when the image fails (a user icon with no name); size xs · sm · md · lg; shape round · square; status dot online · away · busy · offline. AvatarGroup overlaps people with \"+N\" after max.",
+      "tags": ["avatar", "profile", "user", "initials", "presence", "status", "people", "facepile"],
+      "files": ["components/ui/avatar.jsx"]
+    },
+    {
+      "name": "breadcrumb",
+      "type": "component",
+      "title": "Breadcrumb",
+      "description": "Where this page sits: items as data ({ label, href }), the last is the current page. The middle folds into a \"…\" popover past max and always on a phone; earlier crumbs are capped and truncate, the current page takes the rest of the row and truncates only when it runs out; separator chevron · slash. A client part a server surface renders as it is (items are plain data).",
+      "tags": ["breadcrumb", "navigation", "path", "hierarchy", "trail"],
+      "files": ["components/ui/breadcrumb.jsx"]
+    },
+    {
+      "name": "pagination",
+      "type": "component",
+      "title": "Pagination",
+      "description": "Page numbers with \"…\" around the current page, previous/next disabled at the ends; links via hrefFor(page) (server-safe) or buttons via onPageChange; compact \"Page 3 of 12\" on a phone or when asked; optional Rows per page Select; size md · sm.",
+      "tags": ["pagination", "pager", "pages", "table", "list", "page size", "navigation"],
+      "files": ["components/ui/pagination.jsx"]
+    },
     {
       "name": "icon",
       "type": "component",
@@ -90,6 +154,198 @@
       "tags": ["depiction", "preview", "mockup", "frame"],
       "files": ["components/ui/depiction.jsx"]
     },
+    {
+      "name": "radio",
+      "type": "component",
+      "title": "RadioGroup, Radio",
+      "description": "One choice out of a few, all visible: native radios (arrow keys move and select). Options as data or <Radio> children, each with an optional description and icon; variant list · card (each option a selectable card); orientation vertical · horizontal; size md · sm; invalid; inside <Field> with the same id it takes the label, hint and error.",
+      "tags": ["radio", "radio group", "choice", "option", "choice card", "form"],
+      "files": ["components/ui/radio.jsx"]
+    },
+    {
+      "name": "toggle",
+      "type": "component",
+      "title": "Toggle, ToggleGroup",
+      "description": "Toggle: a button that stays down (aria-pressed), variant secondary · quiet, size md · sm, icon (square with label). ToggleGroup: the segmented control — type single · multiple over items, roving focus with the arrow keys, size md · sm, stretches to a given width.",
+      "tags": ["toggle", "toggle group", "segmented control", "pressed", "view switcher", "toolbar"],
+      "files": ["components/ui/toggle.jsx"]
+    },
+    {
+      "name": "button-group",
+      "type": "component",
+      "title": "ButtonGroup, ButtonGroupSeparator",
+      "description": "Joins Buttons, IconButtons and a Menu trigger into one attached piece (a split button, a pager, a zoom control); orientation horizontal · vertical; size md · sm; ButtonGroupSeparator between primary or quiet buttons.",
+      "tags": ["button group", "split button", "segmented", "toolbar", "attached buttons"],
+      "files": ["components/ui/button-group.jsx"]
+    },
+    {
+      "name": "collapsible",
+      "type": "component",
+      "title": "Collapsible, Accordion",
+      "description": "A row that shows or hides what is under it, on native <details>: title, meta on the right (a count, a date), controlled (open + onOpenChange) or not (defaultOpen); variant plain · outline · flush (edge-to-edge rows inside a Card, a rule between them; accordion-outline is its older name); chevron down (turns up, the default) · right (the disclosure triangle, turns down); the chevron turns and the height animates unless reduced motion. Accordion is a list of them: type single · multiple, collapsible, value + onChange, variant plain · outline, chevron; arrow keys, Home and End move between rows.",
+      "tags": ["collapsible", "accordion", "disclosure", "expand", "details", "faq", "show more"],
+      "files": ["components/ui/collapsible.jsx"]
+    },
+    {
+      "name": "item",
+      "type": "component",
+      "title": "Item, ItemGroup",
+      "description": "The list row: media (an avatar, an image) or an icon, title, description, meta on the right, actions; href makes the whole row a link, onClick a button, neither static — actions still click on their own. aria-current, onClick, target and rel go on the row's link or button (aria-current fills the row); other props on the row. size default (56px) · sm (44px) · lg (64px); variant plain · outline · muted; layout row · stacked (a card for a grid: icon or media on top, title, description, meta at the foot, actions top-right, full cell height). ItemGroup stacks them with a rule between each (variant plain · outline).",
+      "tags": ["item", "list", "row", "list item", "contact", "file", "settings row"],
+      "files": ["components/ui/item.jsx"]
+    },
+    {
+      "name": "table",
+      "type": "component",
+      "title": "Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption",
+      "description": "Native table parts in the workspace's look, presentation only. Table scrolls inside itself so it never widens a phone (variant outline · plain); TableRow selected; TableHead sort asc · desc · none with onSort renders a button and aria-sort, sortIndex shows each column's priority in a multi-column sort; numeric head and cells are right-aligned with tabular figures.",
+      "tags": ["table", "data table", "grid", "rows", "columns", "sort", "spreadsheet"],
+      "files": ["components/ui/table.jsx"]
+    },
+    {
+      "name": "slider",
+      "type": "component",
+      "title": "Slider",
+      "description": "A number, or a range (value [low, high] — two thumbs that never cross), picked by dragging the native range input: min, max, step, showValue through format (also the screen reader's text), disabled. A value someone will type is an Input type=\"number\".",
+      "tags": ["slider", "range", "number", "threshold", "budget", "price range"],
+      "files": ["components/ui/slider.jsx"]
+    },
+    {
+      "name": "input-group",
+      "type": "component",
+      "title": "InputGroup, PasswordInput",
+      "description": "An Input with addons that reads as one field: a leading icon or text (\"https://\"), trailing text (\"USD\"), a keyboard hint, a trailing button (copy, search). PasswordInput is the password field with a show/hide IconButton (aria-pressed); autoComplete passes through (current-password by default, new-password on sign-up). Focus, invalid and disabled belong to the whole group. Goes inside <Field>. multiline: a textarea that grows with its text (minRows, maxRows) with the addons in a bar under it — tools at the start, the action at the end, `above` for attached files — the chat composer.",
+      "tags": ["input", "addon", "prefix", "suffix", "search", "copy", "url", "currency", "composer", "textarea", "multiline", "password", "show password"],
+      "files": ["components/ui/input-group.jsx"]
+    },
+    {
+      "name": "image",
+      "type": "component",
+      "title": "Image",
+      "description": "A picture of a thing (a thumbnail, a product shot, a cover): the native <img> in a rounded box, a Skeleton while it loads, an image glyph (or `fallback`) when it fails or has no src; lazy by default; alt required. ratio auto · square · video · portrait · photo · wide or a number; fit cover · contain; rounded none · sm · md · lg · full. A person's face is an Avatar.",
+      "tags": ["image", "img", "picture", "photo", "thumbnail", "cover", "media"],
+      "files": ["components/ui/image.jsx"]
+    },
+    {
+      "name": "file-input",
+      "type": "component",
+      "title": "FileInput, FileDrop, fileMatches",
+      "description": "How files come in, over a real hidden <input type=file>: FileInput is a Button (or, with only a label, an IconButton) that opens the picker; FileDrop is a drop zone (size md · sm; label, hint, invalid) that lights up on drag-over and opens the picker on click, Enter or Space. Both take accept, multiple, disabled and onFiles(files); a drop is filtered by accept and the rest go to onReject(files). Neither uploads.",
+      "tags": ["file", "upload", "file input", "drop zone", "dropzone", "drag and drop", "attach", "picker"],
+      "files": ["components/ui/file-input.jsx"]
+    },
+    {
+      "name": "input-otp",
+      "type": "component",
+      "title": "InputOTP",
+      "description": "A one-time code in N one-character slots: typing advances, Backspace goes back, arrows move, paste and SMS autofill fill every slot; groups (e.g. [3, 3]) with a separator; digits only by default; onComplete(code); invalid.",
+      "tags": ["otp", "one-time code", "verification", "2fa", "pin", "code"],
+      "files": ["components/ui/input-otp.jsx"]
+    },
+    {
+      "name": "command",
+      "type": "component",
+      "title": "Command, CommandDialog, commandScore, commandFilter",
+      "description": "A searchable list of actions (combobox + listbox ARIA, aria-activedescendant): items with icon, label, description, shortcut hint, keywords and groups; fuzzy/substring filtering (commandScore, commandFilter, exported); arrows, Home/End, PageUp/PageDown, Enter; empty and loading states; async onSearch (debounced, stale answers dropped). CommandDialog opens it in a center Sheet (a bottom sheet on a phone) with an optional ⌘K / Ctrl+K hotkey.",
+      "tags": ["command", "palette", "cmdk", "search", "spotlight", "quick actions", "jump to", "filter"],
+      "files": ["components/ui/command.jsx"]
+    },
+    {
+      "name": "combobox",
+      "type": "component",
+      "title": "Combobox",
+      "description": "Pick one or many from a searchable list: a field-shaped trigger showing the choice, a Popover panel with a search input and options (icons, descriptions, groups, a count at the right; Command's list and filter); open + onOpenChange or defaultOpen. multiple (chips with remove buttons), searchable={false} (the rich custom-drawn Select), creatable, async onSearch with loading, clearable, disabled, invalid, name for forms; goes inside <Field> by id. On a phone it opens as a bottom Sheet.",
+      "tags": ["combobox", "select", "autocomplete", "multi-select", "tags", "typeahead", "picker", "dropdown"],
+      "files": ["components/ui/combobox.jsx"]
+    },
+    {
+      "name": "rating",
+      "type": "component",
+      "title": "Rating",
+      "description": "Stars. Read-only (value of max, default 5; fractional values drawn to the nearest half; one image a reader hears as \"4.5 out of 5\") or, with onChange, an input: a native radio group, arrow keys, each star a 44px target at size md, named \"3 out of 5\". size sm · md; label names what is rated; readOnly, disabled, name for forms. Filled stars wear the primary token, empty ones the border.",
+      "tags": ["rating", "stars", "review", "score", "feedback", "reviews", "nps"],
+      "files": ["components/ui/rating.jsx"]
+    },
+    {
+      "name": "feedback",
+      "type": "component",
+      "title": "Spinner, Skeleton, Progress",
+      "description": "Waiting signals. Spinner (size sm · md · lg, currentColor, a label for readers). Skeleton (shape line · circle · rect, sized by className, a gentle pulse). Progress (value of max, or indeterminate with no value; tone neutral · success · warning · danger · info; a label; valueText). Motion stops or slows under prefers-reduced-motion. A Button shows its own spinner with loading.",
+      "tags": ["spinner", "loading", "skeleton", "placeholder", "progress", "progress bar", "upload", "busy"],
+      "files": ["components/ui/feedback.jsx"]
+    },
+    {
+      "name": "stat",
+      "type": "component",
+      "title": "Stat, StatGroup, Delta, StatusDot, Legend, Meter",
+      "description": "Numbers at a glance, server-safe, tabular figures. Stat (label, value, unit, caption; tone colours the value for a threshold state; dot; icon; delta; size sm · md · lg). StatGroup (the strip of 2–4 Stats; variant card · divided · bare; columns; two columns on a phone). Delta (a signed change with an arrow, coloured by sign; invert for lower-is-better; zero is neutral; suffix, display, label; variant text · badge; hideValue for the arrow and tone alone, the value still read to a screen reader). StatusDot (tone dot, or hue 1..5 for a category, size sm · md, pulse that stops under reduced motion, label or hideLabel). Legend (items [{ tone or hue, label, count }] as a wrapping row of dots). Meter (value against max, a role=meter: used / limit, a target mark, thresholds [{ at, tone }] in percent, over the limit the bar caps and turns danger and a reader hears \"over by\"; direction higher · lower picks the tone against the target when no tone is given; valueTone colours the value text (or \"bar\"); targetMark={false} hides the tick; tone muted for a plain grey share; size thin · md; shape ring: a circular gauge with the percent (or center) in the middle, size sm · md · lg, same tones, thresholds, target tick and reader words). Tones neutral · primary · success · warning · danger · info.",
+      "tags": ["stat", "kpi", "metric", "summary", "stat strip", "delta", "trend", "change", "status dot", "legend", "meter", "usage", "quota", "limit", "budget", "target", "threshold"],
+      "files": ["components/ui/stat.jsx"]
+    },
+    {
+      "name": "distribution",
+      "type": "component",
+      "title": "Distribution",
+      "description": "Parts of one whole as a single stacked bar, server-safe: segments [{ label, value, tone?, hue? }] drawn as shares of their total, thin gaps between them, round ends. Each segment takes a categorical hue by default (segment i gets hue i+1, round 1..5, from --color-chart-N); a status tone (success · warning · danger · info · neutral) overrides it for sentiment; hue pins a category's colour. size thin · md; legend adds a row of dot, label and share %; label names it, and a reader hears every label and share. Zero values are skipped; an empty total draws the empty track. total: shares of a whole larger than the sum, the rest drawn as unfilled track, restLabel names it (\"Free\") in the legend; formatValue shows values (\"$450\") in the legend instead of shares; formatLegend({ label, value, pct, share, rest }) writes the legend text whole.",
+      "tags": ["distribution", "stacked bar", "breakdown", "share", "parts of a whole", "composition", "split", "segments", "legend", "category"],
+      "files": ["components/ui/distribution.jsx"]
+    },
+    {
+      "name": "swatch",
+      "type": "component",
+      "title": "Swatch",
+      "description": "A square of a colour that comes from data (a brand colour in an audit row, a label colour a user picked), with a hairline border; color is any CSS colour string; size sm · md; label is the accessible name (none: decoration). The one kit part that sets an inline background from a prop, so no block ever writes one.",
+      "tags": ["swatch", "colour", "color", "palette", "brand colour", "colour chip"],
+      "files": ["components/ui/swatch.jsx"]
+    },
+    {
+      "name": "steps",
+      "type": "component",
+      "title": "Steps",
+      "description": "Where a job with named stages has got to, server-safe: an ordered list with aria-current=\"step\" and each step's state in words for readers. steps [{ key, label, description, status, meta }] with status complete · current · pending · failed · skipped, or a current index for the simple case. variant dots (markers joined by a line filled up to where the job has got; size md with check, cross and number · sm plain dots; hideStepLabels draws bare markers and gives each step's label to readers only, \"Build, complete\") · bar (one segment per phase, a rollout's 5% → 25% → 100%). orientation horizontal · vertical; a horizontal list with descriptions or meta turns vertical below sm, bare dots and short labels stay in one row. pulse on the current step stops under reduced motion. label + valueText as a header like Progress; onSelect(step, index) makes steps buttons, otherwise it takes no clicks.",
+      "tags": ["steps", "stepper", "stages", "phases", "pipeline", "rollout", "timeline", "wizard progress", "checklist", "progress"],
+      "files": ["components/ui/steps.jsx"]
+    },
+    {
+      "name": "separator",
+      "type": "component",
+      "title": "Separator, Kbd, KbdGroup, AspectRatio",
+      "description": "Layout bits. Separator (orientation horizontal · vertical; decorative by default, decorative={false} for a role=separator; label for an \"or\" line). Kbd (one key cap; ⌘ ⇧ ⌥ are spelled out to readers) and KbdGroup (a combo: keys={[\"⌘\", \"K\"]}). AspectRatio (ratio square · video · portrait · photo · wide or a number; its child fills it).",
+      "tags": ["separator", "divider", "hr", "kbd", "keyboard", "shortcut", "hotkey", "aspect ratio", "thumbnail", "video"],
+      "files": ["components/ui/separator.jsx"]
+    },
+    {
+      "name": "scroll-area",
+      "type": "component",
+      "title": "ScrollArea",
+      "description": "A bounded box whose content scrolls: orientation vertical · horizontal · both, thin scrollbars in the theme, fade at the edges that have more content past them, and keyboard-focusable (a labelled region) only while it overflows. Bound it with className (max-h-80). ref (and onScroll, aria-busy…) reach the scrolling element, to read and set scrollTop.",
+      "tags": ["scroll", "scroll area", "overflow", "list", "carousel", "rail"],
+      "files": ["components/ui/scroll-area.jsx"]
+    },
+    {
+      "name": "toast",
+      "type": "component",
+      "title": "toast, Toaster",
+      "description": "A short line about something that just happened, which leaves on its own. toast(title) and toast.success · .error · .info · .warning(title, { description, action: { label, onClick }, duration, id }); toast.promise(promise, { loading, success, error }); toast.dismiss(id). Needs nothing mounted: the first toast lays its own host in the top layer. <Toaster position visible /> only to choose where they stack (bottom-end · bottom-center · top-end · top-center; full width on a phone). Stacked, fans out and pauses on hover or focus, swipe or × to close, announced through a live region.",
+      "tags": ["toast", "snackbar", "notification", "sonner", "flash message", "feedback", "alert"],
+      "files": ["components/ui/toast.jsx"]
+    },
+    {
+      "name": "carousel",
+      "type": "component",
+      "title": "Carousel",
+      "description": "Slides the user moves through, on native CSS scroll-snap: swipe, previous/next buttons, dots (indicator dots · counter · none), arrow keys. itemsPerView a number or { sm, md, lg } (always 1 on a phone); loop off by default; autoplay only when asked for, paused on hover, focus and reduced motion, with a pause button; onChange(index).",
+      "tags": ["carousel", "slider", "slideshow", "gallery", "testimonials", "swipe"],
+      "files": ["components/ui/carousel.jsx"]
+    },
+    {
+      "name": "resizable",
+      "type": "component",
+      "title": "ResizablePanelGroup, ResizablePanel, ResizableHandle",
+      "description": "Panes sized by dragging the line between them. Group direction horizontal · vertical, storageKey remembers the sizes; Panel defaultSize and minSize / maxSize in %; Handle is a keyboard-movable separator (arrows, Home/End, Enter folds), grip for a visible grip. Below md a horizontal group stacks its panes and hides the handles.",
+      "tags": ["resizable", "split pane", "splitter", "panels", "layout", "master detail"],
+      "files": ["components/ui/resizable.jsx"]
+    },
     {
       "name": "cx",
       "type": "component",