@tailor-platform/app-shell 1.15.0 → 1.17.0

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

@@ -0,0 +1,164 @@
+---
+title: Dialog
+description: Modal dialog with a compound component API
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/dialog.docs.outline.md — do not edit by hand. -->
+
+# Dialog
+
+The `Dialog` component provides a modal dialog with a compound component API. It is backed by Base UI's Dialog primitive.
+
+## Import
+
+```tsx
+import { Dialog } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger render={<Button />}>Open</Dialog.Trigger>
+      <Dialog.Content>
+        <Dialog.Header>
+          <Dialog.Title>Confirm Action</Dialog.Title>
+          <Dialog.Description>Are you sure you want to proceed?</Dialog.Description>
+        </Dialog.Header>
+        <Dialog.Footer>
+          <Dialog.Close render={<Button variant="outline" />}>Cancel</Dialog.Close>
+          <Button>Confirm</Button>
+        </Dialog.Footer>
+      </Dialog.Content>
+    </Dialog.Root>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component        | Description                                                             |
+| -------------------- | ----------------------------------------------------------------------- |
+| `Dialog.Root`        | Manages open/close state                                                |
+| `Dialog.Trigger`     | Element that opens the dialog when clicked                              |
+| `Dialog.Content`     | The main dialog panel (includes overlay and close button automatically) |
+| `Dialog.Header`      | Layout wrapper for title and description                                |
+| `Dialog.Footer`      | Layout wrapper for action buttons                                       |
+| `Dialog.Title`       | Dialog title (announced by screen readers)                              |
+| `Dialog.Description` | Additional context below the title                                      |
+| `Dialog.Close`       | Button that closes the dialog                                           |
+
+## Props
+
+### Dialog.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 dialog is modal       |
+| `children`     | `React.ReactNode`         | -       | Dialog sub-components             |
+
+### Dialog.Content Props
+
+Accepts `className` and all standard HTML `<div>` props.
+
+### Dialog.Trigger / Dialog.Close Props
+
+Accept a `render` prop for custom element rendering (Base UI render pattern), plus standard button props.
+
+## Controlled Usage
+
+<example-preview name="controlled"></example-preview>
+
+```tsx
+function Controlled() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button variant="outline" onClick={() => setOpen(true)}>
+        Open Dialog
+      </Button>
+      <Dialog.Root open={open} onOpenChange={setOpen}>
+        <Dialog.Content>
+          <Dialog.Header>
+            <Dialog.Title>Settings</Dialog.Title>
+          </Dialog.Header>
+          <Dialog.Footer>
+            <Button onClick={() => setOpen(false)}>Done</Button>
+          </Dialog.Footer>
+        </Dialog.Content>
+      </Dialog.Root>
+    </>
+  );
+}
+```
+
+## Examples
+
+### Delete Confirmation
+
+```tsx
+function DeleteConfirmation({ onDelete }: { onDelete: () => void }) {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger render={<Button variant="destructive" />}>Delete</Dialog.Trigger>
+      <Dialog.Content>
+        <Dialog.Header>
+          <Dialog.Title>Delete Order</Dialog.Title>
+          <Dialog.Description>
+            This action cannot be undone. The order will be permanently deleted.
+          </Dialog.Description>
+        </Dialog.Header>
+        <Dialog.Footer>
+          <Dialog.Close render={<Button variant="outline" />}>Cancel</Dialog.Close>
+          <Button variant="destructive" onClick={onDelete}>
+            Delete
+          </Button>
+        </Dialog.Footer>
+      </Dialog.Content>
+    </Dialog.Root>
+  );
+}
+```
+
+### Form Dialog
+
+```tsx
+function EditDialog({ item }: { item: Item }) {
+  const [name, setName] = useState(item.name);
+
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger render={<Button variant="outline" />}>Edit</Dialog.Trigger>
+      <Dialog.Content>
+        <Dialog.Header>
+          <Dialog.Title>Edit Item</Dialog.Title>
+        </Dialog.Header>
+        <Input value={name} onChange={(e) => setName(e.target.value)} />
+        <Dialog.Footer>
+          <Dialog.Close render={<Button variant="outline" />}>Cancel</Dialog.Close>
+          <Button onClick={() => handleSave(name)}>Save</Button>
+        </Dialog.Footer>
+      </Dialog.Content>
+    </Dialog.Root>
+  );
+}
+```
+
+## Accessibility
+
+- Dialog title is announced by screen readers via `Dialog.Title`
+- Focus is trapped inside the dialog while open
+- Pressing `Escape` closes the dialog
+- The close button is always present inside `Dialog.Content`
+
+## Related Components
+
+- [Sheet](./sheet.md) - Slide-in panel alternative for non-modal workflows
+- [Button](./button.md) - Use as trigger and action buttons

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

@@ -0,0 +1,154 @@
+---
+title: DocumentProgressCard
+description: Generic card visualising a document's lifecycle state — optional percentage, stacked progress bar, and status legend
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/document-progress-card.docs.outline.md — do not edit by hand. -->
+
+# DocumentProgressCard
+
+`DocumentProgressCard` is a generic, presentational card for communicating the lifecycle/fulfilment state of a document in a record detail right rail. It shows an optional completion percentage, a stacked progress bar, and a legend — driven by an arbitrary set of status `segments`.
+
+It is view-only and domain-agnostic: pass the segments and an explicit `percent`. Any domain-specific math — deriving the percentage, or decomposing overlapping buckets into bar segments — lives in the consumer. See [Example: purchase-order fulfilment](#example-purchase-order-fulfilment) for a complete, copyable pattern.
+
+## Import
+
+```tsx
+import { DocumentProgressCard } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <DocumentProgressCard
+      title="Shipment status"
+      percent={60}
+      segments={[
+        { label: "Shipped", value: 30, color: "green" },
+        { label: "Returned", value: 3, color: "red" },
+        { label: "Pending", value: 17, color: "neutral" },
+      ]}
+    />
+  );
+}
+```
+
+## Props
+
+_Generated from the type surface — first-party props only._
+
+### DocumentProgressCardProps
+
+| Prop         | Type                        | Default | Description                                                                                                                                          |
+| ------------ | --------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className?` | `string`                    | -       | Additional CSS classes for the card root.                                                                                                            |
+| `legend?`    | `DocumentProgressSegment[]` | -       | Legend rows. Defaults to `segments`. Provide this only when the legend should differ from the bar (e.g. overlapping buckets shown distinctly).       |
+| `percent?`   | `number`                    | -       | Headline percentage shown top-right (0–100). Optional and explicit — the generic card has no notion of "complete", so the consumer supplies it.      |
+| `segments`   | `DocumentProgressSegment[]` | -       | Status segments rendered as a single stacked bar (and, by default, the legend).                                                                      |
+| `title?`     | `ReactNode`                 | -       | Optional card title shown top-left.                                                                                                                  |
+| `total?`     | `number`                    | -       | Denominator used to size the bar. Defaults to the sum of segment values (the bar is fully tiled). A larger value leaves an unfilled track remainder. |
+
+## Exports
+
+- `DocumentProgressCard` — function
+- `DocumentProgressCardProps` — interface
+
+### `DocumentProgressSegment`
+
+| Field   | Type                    | Description                                            |
+| ------- | ----------------------- | ------------------------------------------------------ |
+| `label` | `string`                | Legend label.                                          |
+| `value` | `number`                | Amount — shown in the legend and used to size the bar. |
+| `color` | `DocumentProgressColor` | Bar / marker color (required).                         |
+
+`DocumentProgressColor` is one of: `"indigo"`, `"pink"`, `"green"`, `"amber"`, `"red"`, `"blue"`, `"neutral"`.
+
+## Progress Bar
+
+The bar tiles `segments` left-to-right, each sized as `value / (total ?? sum of values)`. When `total` exceeds the segment sum, the shortfall renders as an empty `bg-muted` track — useful for a "remaining" portion you don't want as a colored segment. A `"neutral"` segment reads as a muted/track-like fill.
+
+## Legend
+
+By default the legend mirrors `segments`. Pass `legend` to render different rows — for example when buckets overlap and the bar shows a decomposition while the legend shows the raw figures:
+
+```tsx
+<DocumentProgressCard
+  percent={30}
+  total={40}
+  segments={[
+    { label: "Net received", value: 10, color: "indigo" },
+    { label: "Returned", value: 2, color: "pink" },
+  ]}
+  legend={[
+    { label: "Received items", value: 12, color: "indigo" },
+    { label: "Returned items", value: 2, color: "pink" },
+    { label: "Yet to receive", value: 28, color: "neutral" },
+  ]}
+/>
+```
+
+## Example: purchase-order fulfilment
+
+A common use is communicating a purchase order's receiving state — **received**, **returned**, and **yet to receive**. `DocumentProgressCard` stays generic, so derive the percentage and the bar breakdown in your component and pass them in. This recipe reproduces the recommended look (labels, indigo/pink/neutral colors, and a bar that decomposes received into "kept" + "returned" against the ordered total):
+
+```tsx
+function PurchaseOrderFulfilment({
+  received,
+  returned,
+  yetToReceive,
+  // Whether returned items still count as fulfilled. Set false to subtract them.
+  returnedCountsAsComplete = true,
+}: {
+  received: number;
+  returned: number;
+  yetToReceive: number;
+  returnedCountsAsComplete?: boolean;
+}) {
+  // Returned is a subset of received; clamp so the breakdown can't exceed it.
+  const effectiveReturned = Math.min(Math.max(returned, 0), Math.max(received, 0));
+  const total = Math.max(received, 0) + Math.max(yetToReceive, 0); // the ordered quantity
+  const complete = returnedCountsAsComplete ? received : received - effectiveReturned;
+  const percent = total > 0 ? Math.round((complete / total) * 100) : 0;
+
+  return (
+    <DocumentProgressCard
+      title="Fulfilment rate"
+      percent={percent}
+      total={total} // ordered quantity — the shortfall renders as the "yet to receive" track
+      // Bar: net received (kept) + returned. Yet-to-receive is the unfilled remainder.
+      segments={[
+        { label: "Received items", value: received - effectiveReturned, color: "indigo" },
+        { label: "Returned items", value: effectiveReturned, color: "pink" },
+      ]}
+      // Legend: the three buckets as-is, so "Received items" shows the full amount.
+      legend={[
+        { label: "Received items", value: received, color: "indigo" },
+        { label: "Returned items", value: returned, color: "pink" },
+        { label: "Yet to receive", value: yetToReceive, color: "neutral" },
+      ]}
+    />
+  );
+}
+
+// <PurchaseOrderFulfilment received={12} returned={2} yetToReceive={28} /> → 30%
+```
+
+Notes for adapting it:
+
+- **Colors:** `indigo` (received), `pink` (returned), `neutral` (yet to receive) is the recommended set; swap any of the seven palette colors to fit your domain.
+- **Bar vs. legend:** the bar uses `received − returned` so the two colored segments don't double-count the returned items, while the `legend` override keeps "Received items" showing the full received figure.
+- **`total`:** pass the ordered quantity so the unfilled portion of the bar represents "yet to receive". Omit it (or use the segment sum) if you want a fully-tiled bar instead.
+- **Percentage policy:** flip `returnedCountsAsComplete` to decide whether returned items count toward completion.
+
+## Input handling
+
+Segment values are expected to be non-negative numbers. Non-finite or negative values are coerced to `0`, and `percent` is rounded and clamped to `[0, 100]`.
+
+## Related
+
+- [MetricCard](./metric-card.md) — Compact KPI summary card.
+- [Card](./card.md) — The underlying card primitive.

package/skills/app-shell-patterns/references/components/filter-rail.md

@@ -0,0 +1,165 @@
+---
+title: FilterRail
+description: An always-visible faceted filter rail with user layout settings, driven by the same CollectionControl as DataTable
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/filter-rail.docs.outline.md — do not edit by hand. -->
+
+# FilterRail
+
+`FilterRail` shows every filterable axis beside the results instead of hiding it behind a filter dropdown. Each section shows its options up front, so users see what they can filter by without opening anything.
+
+It writes the same `CollectionControl` a `DataTable` reads, so there is no second filter engine: a checkbox section **is** the `in` operator, a radio section is `eq`, a range is `between`.
+
+```tsx
+import { FilterRail, type FilterRailSection } from "@tailor-platform/app-shell";
+
+const sections: FilterRailSection[] = [
+  {
+    id: "category",
+    label: "Category",
+    control: "checkbox",
+    field: "category",
+    options: categories,
+  },
+  { id: "status", label: "Status", control: "radio", field: "status", options: statuses },
+];
+
+<FilterRail.Root control={control} sections={sections}>
+  <FilterRail.Sections />
+</FilterRail.Root>;
+```
+
+## Sections and parts
+
+What the rail shows is **config**: `sections`, one entry per axis, in screen order. How the rail is assembled is **parts**: leave a part out and that feature is not rendered.
+
+| Part                  | Renders                                                                       |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `FilterRail.Root`     | The rail. Takes `control`, `sections`, `layout`.                              |
+| `FilterRail.Header`   | A title row with a slot for actions.                                          |
+| `FilterRail.ClearAll` | Clears the rail's own filters only. Hidden while none are active.             |
+| `FilterRail.Settings` | Show / hide, reorder and sort sections. Needs `layout`.                       |
+| `FilterRail.Sections` | The sections, in the user's layout. Scrolls while the header stays put.       |
+| `FilterRail.Provider` | Holds the config when a `Trigger` sits outside the rail (see Narrow screens). |
+| `FilterRail.Trigger`  | The narrow-screen "Filters" button, placed anywhere inside `Provider`.        |
+
+```tsx
+<FilterRail.Root control={control} sections={sections} layout={layout}>
+  <FilterRail.Header>
+    <FilterRail.ClearAll />
+    <FilterRail.Settings />
+  </FilterRail.Header>
+  <FilterRail.Sections />
+</FilterRail.Root>
+```
+
+### Section types
+
+Every section has an `id`, a `label` and an optional `hint`. The operator is fixed per section — the user picks values, never operators.
+
+| `control`     | Commits                                    | Notes                                                       |
+| ------------- | ------------------------------------------ | ----------------------------------------------------------- |
+| `checkbox`    | `in` (or `nin`) with the ticked values     | `sort`, `truncate` (default 8), `pinned`, `searchThreshold` |
+| `radio`       | `eq` (or `ne`) with one value              | An "Any" row removes the filter; `anyLabel: null` hides it  |
+| `boolean`     | `eq` with `true` / `false`                 | Three states: Any, `trueLabel`, `falseLabel`                |
+| `text`        | `contains`, `hasPrefix` or `eq`            | Debounced (`debounceMs`, default 250)                       |
+| `numberRange` | `between` `{ min, max }`, or `gte` / `lte` | Commits on blur / Enter; one end alone is half-open         |
+| `date`        | `eq`, `gte` or `lte` a `YYYY-MM-DD`        | Uses `DatePicker`                                           |
+| `dateRange`   | `between` `{ min, max }`                   | Uses `DateRangePicker`; optional `presets`                  |
+| `custom`      | Whatever `render` writes                   | Declares the `fields` it owns so Clear all includes them    |
+
+A checkbox list long enough to be truncated also gets a search box, so a value can be found without scrolling (`searchThreshold` overrides when it appears).
+
+A field holds one filter, so two sections must not share a field; the rail warns in the console when they do.
+
+#### Typing fields
+
+Give `FilterRailSection` the row's keys so a `field` that is not on the table is a type error, the same way `createColumnHelper<Row>()` types columns. This works with a typed control or a plain one:
+
+```tsx
+const sections: FilterRailSection<keyof Product & string>[] = [
+  { id: "category", label: "Category", control: "checkbox", field: "category", options },
+  // field: "categroy" → type error
+];
+```
+
+With a typed control (from `useCollectionVariables({ tableMetadata })`), a section whose field the control does not have is also rejected.
+
+```tsx
+const stockLevel: FilterRailSection = {
+  id: "stockLevel",
+  label: "Stock level",
+  control: "custom",
+  fields: ["stock"],
+  render: ({ getFilter, setFilter }) => (
+    <Button
+      variant="outline"
+      size="xs"
+      onClick={() => setFilter("stock", { operator: "between", value: { min: 1, max: 20 } })}
+    >
+      Low stock
+    </Button>
+  ),
+};
+```
+
+The rail never hides state: a selected option is never truncated away, never disabled and never hidden by a section's search box.
+
+### Collapsing sections
+
+Each section collapses and expands from the chevron by its title. Sections start expanded; set `defaultCollapsed: true` to start one collapsed (for a rarely used axis). While a section is collapsed, its header still shows how many values are selected and keeps its **Clear**, so a collapsed section never hides an applied filter. The open / closed state is kept while the page is open, including across the narrow-screen sheet opening and closing.
+
+```tsx
+{ id: "warehouse", label: "Warehouse", control: "checkbox", field: "warehouse", options, defaultCollapsed: true }
+```
+
+## Choosing a control
+
+Checkbox and radio sections list every option, so they are only for **small, fixed sets** whose values you know up front — status, category, size, a handful of warehouses. Their `options` are a static array; the rail does not fetch them.
+
+Do **not** use a checkbox or radio list for a field whose values **keep growing** — product names, SKUs, customers, suppliers, order numbers. The list gets longer with every new record, takes over the rail, and becomes a scroll hunt. Give those fields a search instead:
+
+| The field's values are…                          | Use                                                                         |
+| ------------------------------------------------ | --------------------------------------------------------------------------- |
+| A small fixed set (≈ up to 20), pick any         | `checkbox`                                                                  |
+| A small fixed set, pick one                      | `radio` (or `boolean` for yes / no)                                         |
+| Open-ended and growing (names, codes, customers) | `text` — a search that commits `contains`, `hasPrefix` or `eq`              |
+| Open-ended, but users must pick exact records    | a `custom` section rendering a searchable picker (e.g. an async `Combobox`) |
+| Numbers or dates                                 | `numberRange`, `date`, `dateRange`                                          |
+
+In development the rail warns in the console when a checkbox or radio section lists more than 50 options, as a nudge towards a search.
+
+## User layout
+
+`useFilterRailLayout(storageKey)` persists the user's section order, hidden sections and option sort to localStorage. Pass it as `layout` and add `FilterRail.Settings`. Hiding a section that carries a filter also clears that filter. To share a layout across a team, pass your own `{ value, onChange, onReset }` binding instead.
+
+## Beside a DataTable
+
+The rail sits in its own `Layout.Column`, outside `DataTable.Root`, which is why `control` is a prop. Do not also render `DataTable.Filters` for the same fields — one fact in two places can drift.
+
+## Narrow screens
+
+Below the `lg` breakpoint there is no room for a side column, so the rail turns itself into a left sheet behind a **Filters** button carrying the active count — the same way the Sidebar handles small screens. Apps write no breakpoint code.
+
+By default the button appears where the rail would have been. To put it somewhere else — a table toolbar, a page header — wrap the page in `FilterRail.Provider`, move the config there, and place `FilterRail.Trigger` wherever you want it. The Trigger renders nothing on wide screens, and while one is mounted the rail skips its own button.
+
+```tsx
+<FilterRail.Provider control={control} sections={sections}>
+  <Layout fill>
+    <Layout.Column area="left">
+      <FilterRail.Root>
+        <FilterRail.Sections />
+      </FilterRail.Root>
+    </Layout.Column>
+    <Layout.Column area="main">
+      <DataTable.Root value={table}>
+        <DataTable.Toolbar>
+          <FilterRail.Trigger />
+        </DataTable.Toolbar>
+        <DataTable.Table />
+      </DataTable.Root>
+    </Layout.Column>
+  </Layout>
+</FilterRail.Provider>
+```