@tailor-platform/app-shell 1.15.0 → 1.16.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.