@tailor-platform/app-shell 1.15.0 → 1.16.0

package/skills/app-shell-patterns/references/components/menu.md

@@ -0,0 +1,218 @@
+---
+title: Menu
+description: Dropdown menu with a compound component API, supporting checkbox/radio items, groups, separators, and nested sub-menus
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/menu.docs.outline.md — do not edit by hand. -->
+
+# Menu
+
+The `Menu` component provides a dropdown menu with a compound component API. It is backed by Base UI's Menu primitive.
+
+## Import
+
+```tsx
+import { Menu } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Menu.Root>
+      <Menu.Trigger>Open menu</Menu.Trigger>
+      <Menu.Content>
+        <Menu.Item>Edit</Menu.Item>
+        <Menu.Item>Duplicate</Menu.Item>
+        <Menu.Separator />
+        <Menu.Item>Delete</Menu.Item>
+      </Menu.Content>
+    </Menu.Root>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component                | Description                                               |
+| ---------------------------- | --------------------------------------------------------- |
+| `Menu.Root`                  | Manages menu open/close state                             |
+| `Menu.Trigger`               | Element that opens the menu when clicked                  |
+| `Menu.Content`               | The menu popup containing menu items                      |
+| `Menu.Item`                  | An individual interactive item                            |
+| `Menu.LinkItem`              | A link item for navigation                                |
+| `Menu.CheckboxItem`          | A menu item that toggles a setting on or off              |
+| `Menu.CheckboxItemIndicator` | Indicates whether the checkbox item is ticked             |
+| `Menu.RadioItem`             | A menu item that works like a radio button within a group |
+| `Menu.RadioItemIndicator`    | Indicates whether the radio item is selected              |
+| `Menu.RadioGroup`            | Groups related radio items                                |
+| `Menu.Group`                 | Groups related menu items                                 |
+| `Menu.GroupLabel`            | An accessible label for a `Menu.Group`                    |
+| `Menu.Separator`             | A visual separator between menu items                     |
+| `Menu.SubmenuRoot`           | Groups all parts of a nested sub-menu                     |
+| `Menu.SubmenuTrigger`        | A menu item that opens a sub-menu                         |
+
+## Props
+
+### Menu.Root Props
+
+| Prop           | Type                      | Default | Description                       |
+| -------------- | ------------------------- | ------- | --------------------------------- |
+| `open`         | `boolean`                 | -       | Controlled open state             |
+| `defaultOpen`  | `boolean`                 | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | -       | Callback when open state changes  |
+| `modal`        | `boolean`                 | `true`  | Whether the menu is modal         |
+| `disabled`     | `boolean`                 | `false` | Disables the entire menu          |
+| `children`     | `React.ReactNode`         | -       | Menu sub-components               |
+
+### Menu.Content Props
+
+| Prop        | Type                                                                                                           | Default                                             | Description                         |
+| ----------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------- |
+| `position`  | `{ side?: "top" \| "right" \| "bottom" \| "left"; align?: "start" \| "center" \| "end"; sideOffset?: number }` | `{ side: "bottom", align: "start", sideOffset: 4 }` | Placement of the popup              |
+| `className` | `string`                                                                                                       | -                                                   | Additional CSS classes              |
+| `children`  | `React.ReactNode`                                                                                              | -                                                   | Menu items and other sub-components |
+
+### Menu.Item Props
+
+Accepts `className`, `disabled`, and all standard Base UI `Menu.Item` props.
+
+### Menu.SubmenuRoot Props
+
+| Prop           | Type                      | Default | Description                       |
+| -------------- | ------------------------- | ------- | --------------------------------- |
+| `open`         | `boolean`                 | -       | Controlled open state             |
+| `defaultOpen`  | `boolean`                 | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | -       | Callback when open state changes  |
+| `disabled`     | `boolean`                 | `false` | Disables the entire sub-menu      |
+| `children`     | `React.ReactNode`         | -       | Sub-menu sub-components           |
+
+## Grouped Items
+
+Use `Menu.Group` and `Menu.GroupLabel` to visually group related items:
+
+```tsx
+<Menu.Root>
+  <Menu.Trigger>Actions</Menu.Trigger>
+  <Menu.Content>
+    <Menu.Group>
+      <Menu.GroupLabel>File</Menu.GroupLabel>
+      <Menu.Item>New</Menu.Item>
+      <Menu.Item>Open</Menu.Item>
+    </Menu.Group>
+    <Menu.Separator />
+    <Menu.Group>
+      <Menu.GroupLabel>Edit</Menu.GroupLabel>
+      <Menu.Item>Cut</Menu.Item>
+      <Menu.Item>Copy</Menu.Item>
+      <Menu.Item>Paste</Menu.Item>
+    </Menu.Group>
+  </Menu.Content>
+</Menu.Root>
+```
+
+## Checkbox Items
+
+```tsx
+const [bold, setBold] = useState(false);
+const [italic, setItalic] = useState(false);
+
+<Menu.Root>
+  <Menu.Trigger>Format</Menu.Trigger>
+  <Menu.Content>
+    <Menu.CheckboxItem checked={bold} onCheckedChange={setBold}>
+      <Menu.CheckboxItemIndicator>✓</Menu.CheckboxItemIndicator>
+      Bold
+    </Menu.CheckboxItem>
+    <Menu.CheckboxItem checked={italic} onCheckedChange={setItalic}>
+      <Menu.CheckboxItemIndicator>✓</Menu.CheckboxItemIndicator>
+      Italic
+    </Menu.CheckboxItem>
+  </Menu.Content>
+</Menu.Root>;
+```
+
+## Radio Items
+
+```tsx
+const [align, setAlign] = useState("left");
+
+<Menu.Root>
+  <Menu.Trigger>Align</Menu.Trigger>
+  <Menu.Content>
+    <Menu.RadioGroup value={align} onValueChange={setAlign}>
+      <Menu.RadioItem value="left">
+        <Menu.RadioItemIndicator>●</Menu.RadioItemIndicator>
+        Left
+      </Menu.RadioItem>
+      <Menu.RadioItem value="center">
+        <Menu.RadioItemIndicator>●</Menu.RadioItemIndicator>
+        Center
+      </Menu.RadioItem>
+      <Menu.RadioItem value="right">
+        <Menu.RadioItemIndicator>●</Menu.RadioItemIndicator>
+        Right
+      </Menu.RadioItem>
+    </Menu.RadioGroup>
+  </Menu.Content>
+</Menu.Root>;
+```
+
+## Nested Sub-menus
+
+```tsx
+<Menu.Root>
+  <Menu.Trigger>Edit</Menu.Trigger>
+  <Menu.Content>
+    <Menu.Item>Cut</Menu.Item>
+    <Menu.Item>Copy</Menu.Item>
+    <Menu.SubmenuRoot>
+      <Menu.SubmenuTrigger>Paste Special ›</Menu.SubmenuTrigger>
+      <Menu.Content>
+        <Menu.Item>Paste as Plain Text</Menu.Item>
+        <Menu.Item>Paste and Match Style</Menu.Item>
+      </Menu.Content>
+    </Menu.SubmenuRoot>
+  </Menu.Content>
+</Menu.Root>
+```
+
+## Examples
+
+### Context Menu
+
+```tsx
+function OrderActions({ order }: { order: Order }) {
+  return (
+    <Menu.Root>
+      <Menu.Trigger>
+        <Button variant="ghost" size="icon">
+          <EllipsisVerticalIcon />
+        </Button>
+      </Menu.Trigger>
+      <Menu.Content>
+        <Menu.Item onSelect={() => handleEdit(order)}>Edit</Menu.Item>
+        <Menu.Item onSelect={() => handleDuplicate(order)}>Duplicate</Menu.Item>
+        <Menu.Separator />
+        <Menu.Item onSelect={() => handleDelete(order)}>Delete</Menu.Item>
+      </Menu.Content>
+    </Menu.Root>
+  );
+}
+```
+
+## Accessibility
+
+- Menu items are keyboard navigable with arrow keys
+- Pressing `Escape` closes the menu
+- Sub-menus open on arrow-right and close on arrow-left
+- `Menu.GroupLabel` is automatically associated with its parent group
+
+## Related Components
+
+- [Dialog](./dialog.md) - For actions that require confirmation
+- [Sheet](./sheet.md) - Slide-in panel for more complex workflows
+- [Button](./button.md) - Common trigger element for menus

package/skills/app-shell-patterns/references/components/metric-card.md

@@ -0,0 +1,94 @@
+---
+title: MetricCard
+description: Compact card for dashboard KPI summaries with title, value, optional trend and description
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/metric-card.docs.outline.md — do not edit by hand. -->
+
+# MetricCard
+
+`MetricCard` is a presentational card for displaying a single KPI (key performance indicator) on dashboards. It shows a small title, a prominent value, and optionally a trend indicator and supplementary description text. In v1 the component is static (no click handler or internal actions).
+
+## Import
+
+```tsx
+import { MetricCard } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <MetricCard
+      title="Net total payment"
+      value="$1,500.00"
+      trend={{ direction: "up", value: "+5%" }}
+      description="vs last month"
+    />
+  );
+}
+```
+
+## Props
+
+_Generated from the type surface — first-party props only._
+
+### MetricCardProps
+
+| Prop           | Type              | Default | Description                                                                                                                                                       |
+| -------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className?`   | `string`          | -       | Additional CSS classes for the card container                                                                                                                     |
+| `description?` | `string`          | -       | Optional supplementary description (e.g. "vs last period", "this week"). Empty strings are treated as absent and the description is not rendered in the meta row. |
+| `icon?`        | `ReactNode`       | -       | Optional leading icon                                                                                                                                             |
+| `title`        | `string`          | -       | Metric title / header (e.g. "Net total payment")                                                                                                                  |
+| `trend?`       | `MetricCardTrend` | -       | Optional trend indicator                                                                                                                                          |
+| `value`        | `ReactNode`       | -       | Primary value (e.g. formatted currency or number)                                                                                                                 |
+
+## Exports
+
+- `MetricCard` — function
+- `MetricCardProps` — interface
+
+## Trend Directions
+
+- **up** — Positive change (success styling, e.g. green).
+- **down** — Negative change (destructive styling, e.g. red).
+- **neutral** — No change or neutral (muted styling).
+
+```tsx
+<MetricCard
+  title="Revenue"
+  value="$2,400"
+  trend={{ direction: "up", value: "+12%" }}
+  description="vs last month"
+/>
+
+<MetricCard
+  title="Costs"
+  value="$800"
+  trend={{ direction: "down", value: "-5%" }}
+  description="vs last quarter"
+/>
+
+<MetricCard
+  title="Balance"
+  value="$0"
+  trend={{ direction: "neutral", value: "0%" }}
+/>
+```
+
+## With Icon
+
+```tsx
+<MetricCard title="Total orders" value="142" icon={<OrderIcon />} description="this week" />
+```
+
+## Related
+
+- [Grid](./grid.md) — Arrange MetricCards in responsive columns (e.g. KPI grids).
+- [Layout](./layout.md) — Page layout for placing MetricCards in a grid.
+- [DescriptionCard](./description-card.md) — Structured key-value cards for detail views.
+- [Badge](./badge.md) — Status badges that can complement metric displays.

package/skills/app-shell-patterns/references/components/select.md

@@ -0,0 +1,283 @@
+---
+title: Select
+description: Single or multi-select dropdown with optional async data fetching
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/select.docs.outline.md — do not edit by hand. -->
+
+# Select
+
+The `Select` component provides a fully assembled single or multi-select dropdown. Pass `items` and get a ready-to-use select out of the box. For async data fetching use `Select.Async`. For custom compositions use `Select.Parts`.
+
+## Import
+
+```tsx
+import { Select } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Select
+      items={["Apple", "Banana", "Cherry"]}
+      placeholder="Pick a fruit"
+      onValueChange={(value) => console.log(value)}
+    />
+  );
+}
+```
+
+## Props
+
+### Select Props
+
+| Prop              | Type                                                                       | Default | Description                                                         |
+| ----------------- | -------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------- |
+| `items`           | `I[]`                                                                      | -       | Items to display. May be a flat array or an array of `ItemGroup<T>` |
+| `placeholder`     | `string`                                                                   | -       | Placeholder text shown when no value is selected                    |
+| `multiple`        | `true \| false \| undefined`                                               | `false` | Enables multi-select mode                                           |
+| `value`           | `T \| null` (single) or `T[]` (multiple)                                   | -       | Controlled value                                                    |
+| `defaultValue`    | `T \| null` (single) or `T[]` (multiple)                                   | -       | Initial value (uncontrolled)                                        |
+| `onValueChange`   | `(value: T \| null) => void` (single) or `(value: T[]) => void` (multiple) | -       | Called when the selected value changes                              |
+| `renderValue`     | `(value: T \| null \| T[]) => React.ReactNode`                             | -       | Custom render function for the selected value display               |
+| `mapItem`         | `(item: T) => MappedItem`                                                  | -       | Map each item to its label, key, and optional custom render         |
+| `className`       | `string`                                                                   | -       | Additional CSS classes for the root container                       |
+| `disabled`        | `boolean`                                                                  | `false` | Disables the select                                                 |
+| `aria-label`      | `string`                                                                   | -       | Accessible name for the trigger. Use when there is no visible label |
+| `aria-labelledby` | `string`                                                                   | -       | ID of the element(s) that label the trigger                         |
+| `id`              | `string`                                                                   | -       | ID applied to the combobox trigger element                          |
+
+### MappedItem
+
+```ts
+interface MappedItem {
+  label: string; // Display text, used for filtering and a11y
+  key?: string; // React key. Defaults to label
+  render?: React.ReactNode; // Custom JSX to render in the dropdown
+}
+```
+
+### ItemGroup
+
+Pass grouped items by wrapping them in `ItemGroup<T>` objects:
+
+```ts
+interface ItemGroup<T> {
+  label: string;
+  items: T[];
+}
+```
+
+## Grouped Items
+
+```tsx
+const fruits = [
+  { label: "Citrus", items: ["Orange", "Lemon", "Lime"] },
+  { label: "Berries", items: ["Strawberry", "Blueberry"] },
+];
+
+<Select items={fruits} placeholder="Pick a fruit" />;
+```
+
+## Object Items with mapItem
+
+When items are objects, use `mapItem` to tell the component how to display them:
+
+```tsx
+type Fruit = { id: number; name: string };
+
+const fruits: Fruit[] = [
+  { id: 1, name: "Apple" },
+  { id: 2, name: "Banana" },
+];
+
+<Select
+  items={fruits}
+  mapItem={(fruit) => ({ label: fruit.name, key: String(fruit.id) })}
+  onValueChange={(fruit) => console.log(fruit?.id)}
+/>;
+```
+
+## Multi-select
+
+```tsx
+<Select
+  items={["Red", "Green", "Blue"]}
+  multiple
+  placeholder="Pick colors"
+  onValueChange={(colors) => console.log(colors)}
+/>
+```
+
+## Async Loading
+
+Use `Select.Async` to load items from an API. The fetcher is called each time the dropdown is opened.
+
+```tsx
+import { type SelectAsyncFetcher } from "@tailor-platform/app-shell";
+
+const fetcher: SelectAsyncFetcher<Fruit> = async ({ signal }) => {
+  const res = await fetch("/api/fruits", { signal });
+  return res.json();
+};
+
+<Select.Async
+  fetcher={fetcher}
+  mapItem={(fruit) => ({ label: fruit.name, key: String(fruit.id) })}
+  placeholder="Pick a fruit"
+  onValueChange={(fruit) => console.log(fruit)}
+/>;
+```
+
+### Select.Async Props
+
+Accepts all the same props as `Select` except `items`, plus:
+
+| Prop                   | Type                       | Default                    | Description                                                                                                                        |
+| ---------------------- | -------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `fetcher`              | `SelectAsyncFetcher<T>`    | -                          | Fetcher called each time the dropdown is opened                                                                                    |
+| `loadingText`          | `string`                   | `"Loading..."`             | Text shown while loading                                                                                                           |
+| `errorText`            | `string`                   | `"Couldn't load results."` | Message shown in the dropdown when the fetcher fails (with Retry)                                                                  |
+| `retryText`            | `string`                   | `"Retry"`                  | Label for the retry button in the error state                                                                                      |
+| `onFetchError`         | `(error: unknown) => void` | -                          | Called once per outage when a fetch fails (logging/error tracking)                                                                 |
+| `modal`                | `boolean`                  | `false`                    | Whether the select traps focus (modal behavior). Set to `true` when rendering inside a `Dialog` or `Sheet` to preserve focus-trap. |
+| `alignItemWithTrigger` | `boolean`                  | `false`                    | Whether to align the selected item with the trigger when the dropdown opens.                                                       |
+
+> **Note:** `Select.Async` does not support `ItemGroup<T>[]` — the fetcher must return a flat array.
+
+> **Limitation:** `Select.Async` defaults to `modal={false}` and `alignItemWithTrigger={false}` to work around a Base UI scroll-lock bug with dynamically loaded items. As a result, it may not function correctly inside focus-trapping containers such as `Dialog` or `Sheet` — the focus trap can block interaction with the dropdown, or the portal may render outside the modal's visible area. If you need an async dropdown inside a `Dialog` or `Sheet`, prefer [`Combobox.Async`](./combobox.md) which uses Popover-based positioning and does not have this constraint.
+
+### SelectAsyncFetcher
+
+```ts
+type SelectAsyncFetcher<T> = (options: { signal: AbortSignal }) => Promise<T[]>;
+```
+
+### Error handling
+
+If the fetcher throws or rejects, `Select.Async` renders a built-in inline error state in the dropdown — the `errorText` message plus a **Retry** button that re-runs the fetch — instead of the misleading empty state. Aborted requests (the dropdown closed before the fetch settled) are ignored, and announcements are de-duped per outage. Pass `onFetchError` to run a side effect (logging, toast) — it fires once per outage and re-arms after the next successful fetch.
+
+## Low-level Primitives
+
+`Select.Parts` exposes the styled sub-components for fully custom compositions:
+
+```tsx
+const { Root, Trigger, Value, Content, Item, Group, GroupLabel, Separator } = Select.Parts;
+```
+
+## Form submission
+
+Inside a `Field.Root`, the field's `name` identifies the value and these props are unnecessary —
+see [Form](./form.md). They matter for **native** submission: a plain `<form>`, `new FormData(form)`,
+or a server action.
+
+| Prop                | Type                          | Default | Description                                                                                              |
+| ------------------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `name`              | `string`                      | -       | Names the hidden input for native submission. **Ignored inside a `Field.Root`** — the field's name wins. |
+| `form`              | `string`                      | -       | `id` of the owning form, when the control is rendered outside it.                                        |
+| `required`          | `boolean`                     | `false` | Blocks submission until a value is chosen, surfacing the matching `Field.Error`.                         |
+| `inputRef`          | `React.Ref<HTMLInputElement>` | -       | Ref to the hidden input (use for React Hook Form's `field.ref`).                                         |
+| `itemToStringValue` | `(item: T) => string`         | -       | Serialises a non-string item for submission. Items shaped `{ value, label }` use `value` automatically.  |
+
+## Examples
+
+### Controlled Select
+
+```tsx
+const [selected, setSelected] = useState<string | null>(null);
+
+<Select
+  items={["Draft", "Pending", "Approved", "Rejected"]}
+  value={selected}
+  onValueChange={setSelected}
+  placeholder="Select status"
+/>;
+```
+
+### Custom Render
+
+```tsx
+<Select
+  items={statuses}
+  mapItem={(s) => ({
+    label: s.name,
+    key: s.id,
+    render: (
+      <span className="flex items-center gap-2">
+        <span className={`size-2 rounded-full bg-${s.color}`} />
+        {s.name}
+      </span>
+    ),
+  })}
+  placeholder="Select status"
+/>
+```
+
+### Async with Parts (custom composition)
+
+Combine `Select.useAsync` with `Select.Parts` for full control over layout and rendering:
+
+`Select.useAsync` accepts the same options as `Select.Async` (including `onFetchError`) and returns:
+
+| Property  | Type         | Description                                             |
+| --------- | ------------ | ------------------------------------------------------- |
+| `items`   | `T[]`        | Currently loaded items                                  |
+| `loading` | `boolean`    | Whether a fetch is in progress                          |
+| `error`   | `unknown`    | The error thrown by the last fetch, if any              |
+| `retry`   | `() => void` | Re-runs the last fetch (use to build a custom retry UI) |
+
+```tsx
+type Fruit = { id: number; name: string };
+
+const fruits = Select.useAsync({
+  fetcher: async ({ signal }) => {
+    const res = await fetch("/api/fruits", { signal });
+    return res.json() as Promise<Fruit[]>;
+  },
+  onFetchError: (error) => reportError(error),
+});
+
+<Select.Parts.Root {...fruits} itemToStringLabel={(f) => f.name}>
+  <Select.Parts.Trigger>
+    <Select.Parts.Value placeholder="Pick a fruit" />
+  </Select.Parts.Trigger>
+  <Select.Parts.Content>
+    {fruits.error ? (
+      <div className="px-4 py-2 text-center text-sm">
+        Couldn't load. <button onClick={fruits.retry}>Retry</button>
+      </div>
+    ) : fruits.loading ? (
+      <div className="px-4 py-2 text-center text-sm text-muted-foreground">Loading...</div>
+    ) : (
+      fruits.items.map((f) => (
+        <Select.Parts.Item key={f.id} value={f}>
+          {f.name}
+        </Select.Parts.Item>
+      ))
+    )}
+  </Select.Parts.Content>
+</Select.Parts.Root>;
+```
+
+## Accessibility
+
+- The trigger exposes the `combobox` role. When used inside a `Form`/`FormControl` it is labeled automatically.
+- When used standalone (e.g. a table toolbar or list filter) there is no visible `<label>`, so give the trigger an accessible name with `aria-label` or `aria-labelledby`. Otherwise screen readers announce only the current value.
+
+```tsx
+// Announced as "Direction filter, combobox" instead of just the value
+<Select items={items} value={value} onValueChange={setValue} aria-label="Direction filter" />
+
+// Or point at a visible label
+<span id="dir-label">From</span>
+<Select items={items} aria-labelledby="dir-label" />
+```
+
+## Related Components
+
+- [Combobox](./combobox.md) - Searchable combobox with filtering
+- [Autocomplete](./autocomplete.md) - Free-text input with suggestions