@tailor-platform/app-shell 1.15.0 → 1.16.0

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

@@ -0,0 +1,138 @@
+---
+title: Attachment
+description: Attachment list with upload, previews, and per-item actions; compose with Card for titles and surface styling
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/attachment.docs.outline.md — do not edit by hand. -->
+
+# Attachment
+
+`Attachment` is a reusable file/image attachment surface for ERP detail pages. It provides upload affordance (click or drag-and-drop onto the upload tile), optional helper text via `uploadHint`, image/file preview tiles, and per-item menu actions for download and delete.
+
+## Import
+
+```tsx
+import { Attachment, useAttachment } from "@tailor-platform/app-shell";
+import type { AttachmentItem, AttachmentOperation } from "@tailor-platform/app-shell";
+```
+
+## Basic usage
+
+Use `useAttachment` to manage upload/delete state locally, then flush operations to your backend on submit via `applyChanges`. Spread the returned `props` directly onto `<Attachment />`.
+
+```tsx
+import { Attachment, Card, useAttachment } from "@tailor-platform/app-shell";
+import type { AttachmentOperation } from "@tailor-platform/app-shell";
+
+function ProductForm() {
+  const { props, applyChanges } = useAttachment({
+    initialItems: existingAttachments,
+    accept: "image/*,.pdf",
+  });
+
+  async function handleSubmit() {
+    await applyChanges(async (operations) => {
+      for (const op of operations) {
+        if (op.type === "upload") await uploadToServer(op.file);
+        if (op.type === "delete") await deleteFromServer(op.item.id);
+      }
+    });
+  }
+
+  return (
+    <Card.Root>
+      <Card.Header title="Product images" description="PNG, JPG, or PDF — max 10 MB per file." />
+      <Card.Content>
+        <Attachment
+          {...props}
+          uploadLabel="Upload image"
+          uploadHint="PNG, JPG, or PDF — max 10 MB per file."
+          onDownload={(item) => console.log("download", item)}
+        />
+      </Card.Content>
+    </Card.Root>
+  );
+}
+```
+
+## Composition with Card
+
+- Use **`Card.Header`** for the section title and description.
+- Use **`Card.Root`** (and usually **`Card.Content`**) for border, radius, shadow, and padding around the attachment block.
+
+## useAttachment
+
+`useAttachment` tracks pending uploads and deletes locally until `applyChanges` is called. It handles object URL creation/revocation for image previews automatically.
+
+### Options
+
+| Option         | Type               | Default | Description                                  |
+| -------------- | ------------------ | ------- | -------------------------------------------- |
+| `initialItems` | `AttachmentItem[]` | `[]`    | Existing items to populate on mount          |
+| `accept`       | `string`           | -       | Accepted file types passed to the file input |
+| `disabled`     | `boolean`          | `false` | Disable upload and item actions              |
+
+### Return value
+
+| Field          | Type                                                                   | Description                                                                                                                                           |
+| -------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `props`        | `{ items, onUpload, onDelete, accept, disabled }`                      | Spread directly onto `<Attachment />`                                                                                                                 |
+| `applyChanges` | `(fn: (ops: AttachmentOperation[]) => Promise<void>) => Promise<void>` | Flush buffered operations to your backend; clears the buffer after `fn` resolves. If `fn` throws, the buffer is preserved so the call can be retried. |
+| `isApplying`   | `boolean`                                                              | `true` while `applyChanges` is in progress. Use to show a loading indicator during form submission.                                                   |
+
+> **Upload ordering:** newly uploaded files are prepended to `items`, so the most recent uploads appear first in the tile list.
+
+## AttachmentOperation
+
+Represents a single pending change buffered by `useAttachment`. Passed as an array to the `applyChanges` callback.
+
+```ts
+type AttachmentOperation =
+  | { type: "upload"; file: File; item: AttachmentItem }
+  | { type: "delete"; item: AttachmentItem };
+```
+
+## AttachmentItem
+
+```ts
+interface AttachmentItem {
+  id: string;
+  fileName: string;
+  mimeType: string;
+  previewUrl?: string;
+}
+```
+
+## Attachment props
+
+| Prop          | Type                             | Default             | Description                                                                                   |
+| ------------- | -------------------------------- | ------------------- | --------------------------------------------------------------------------------------------- |
+| `items`       | `AttachmentItem[]`               | `[]`                | Attachment list rendered as preview tiles                                                     |
+| `onUpload`    | `(files: File[]) => void`        | _(required)_        | Called when files are selected or dropped on the upload tile                                  |
+| `onDelete`    | `(item: AttachmentItem) => void` | _(required)_        | Called when Delete is chosen in a preview menu                                                |
+| `onDownload`  | `(item: AttachmentItem) => void` | -                   | Called when Download is chosen in a preview menu                                              |
+| `uploadLabel` | `string`                         | `"Click to upload"` | Primary label on the upload tile                                                              |
+| `uploadHint`  | `string`                         | -                   | Supporting text below the upload label                                                        |
+| `accept`      | `string`                         | -                   | Accepted file types for hidden file input                                                     |
+| `disabled`    | `boolean`                        | `false`             | Disables upload, drop, and hides per-item menu actions                                        |
+| `className`   | `string`                         | -                   | Classes on the root (e.g. padding); component has no outer border or inset padding by default |
+
+## Behavior
+
+- **Layout**: hidden file input, then the tile row—no built-in page inset.
+- **Image items** (`mimeType` starts with `image/`) render as 120×120 image thumbnails when `previewUrl` loads; otherwise a fallback tile.
+- **Non-image items** render as 120×120 file tiles with icon and wrapped filename.
+- **Drag and drop** applies only to the **upload tile** (dashed “click to upload” control), not the full attachment block. Use the file picker from the same tile for click-to-upload.
+- **Disabled state** (`disabled={true}`): the upload tile and drop target are hidden; per-item menu actions are also hidden.
+- **Item actions** are available through the preview menu (`Download`, `Delete`) when not disabled.
+
+### DOM
+
+- Root: `data-slot="attachment"`
+- Content wrapper: `data-slot="attachment-content"`
+
+## Related components
+
+- [Card](./card.md)
+- [Button](./button.md)
+- [Menu](./menu.md)

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

@@ -0,0 +1,278 @@
+---
+title: Autocomplete
+description: Text input with a suggestion list — value is the raw input string, not a discrete item selection
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/autocomplete.docs.outline.md — do not edit by hand. -->
+
+# Autocomplete
+
+The `Autocomplete` component provides a free-text input with a suggestion list. Unlike `Select` and `Combobox`, the component value is the raw input string — not a discrete item selection. For async suggestions use `Autocomplete.Async`. For custom compositions use `Autocomplete.Parts`.
+
+## Import
+
+```tsx
+import { Autocomplete } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Autocomplete
+      items={["Apple", "Banana", "Cherry"]}
+      placeholder="Type a fruit..."
+      onValueChange={(value) => console.log(value)}
+    />
+  );
+}
+```
+
+## Props
+
+### Autocomplete Props
+
+| Prop              | Type                      | Default         | Description                                                         |
+| ----------------- | ------------------------- | --------------- | ------------------------------------------------------------------- |
+| `items`           | `I[]`                     | -               | Suggestion items. May be a flat array or an array of `ItemGroup<T>` |
+| `placeholder`     | `string`                  | -               | Placeholder text for the input                                      |
+| `emptyText`       | `string`                  | `"No results."` | Text shown when no items match                                      |
+| `value`           | `string`                  | -               | Controlled value (raw input string)                                 |
+| `defaultValue`    | `string`                  | -               | Initial value (uncontrolled)                                        |
+| `onValueChange`   | `(value: string) => void` | -               | Called when the value changes                                       |
+| `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 autocomplete                                           |
+| `aria-label`      | `string`                  | -               | Accessible name for the input. Use when there is no visible label   |
+| `aria-labelledby` | `string`                  | -               | ID of the element(s) that label the input                           |
+| `id`              | `string`                  | -               | ID applied to the combobox input 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
+
+```ts
+interface ItemGroup<T> {
+  label: string;
+  items: T[];
+}
+```
+
+## Grouped Suggestions
+
+```tsx
+const cities = [
+  { label: "Japan", items: ["Tokyo", "Osaka", "Kyoto"] },
+  { label: "France", items: ["Paris", "Lyon", "Marseille"] },
+];
+
+<Autocomplete items={cities} placeholder="Search cities..." />;
+```
+
+## Object Items with mapItem
+
+When items are objects, use `mapItem` to tell the component how to display them. The selected value is the item's `label` string returned by `mapItem`:
+
+```tsx
+type City = { code: string; name: string };
+
+const cities: City[] = [
+  { code: "TYO", name: "Tokyo" },
+  { code: "OSA", name: "Osaka" },
+];
+
+<Autocomplete
+  items={cities}
+  mapItem={(city) => ({ label: city.name, key: city.code })}
+  placeholder="Search cities..."
+  onValueChange={(name) => console.log(name)} // receives "Tokyo", "Osaka", etc.
+/>;
+```
+
+## Async Suggestions
+
+Use `Autocomplete.Async` to fetch suggestions as the user types. The fetcher is called on each keystroke (debounced). When the dropdown first opens or the input is cleared, the fetcher receives `null` as the query — return initial/default suggestions for `null`, or return an empty array to show nothing until the user starts typing.
+
+```tsx
+import { type AutocompleteAsyncFetcher } from "@tailor-platform/app-shell";
+
+const fetcher: AutocompleteAsyncFetcher<string> = async (query, { signal }) => {
+  const res = await fetch(`/api/suggestions?q=${query ?? ""}`, { signal });
+  return res.json();
+};
+
+<Autocomplete.Async
+  fetcher={fetcher}
+  placeholder="Search..."
+  onValueChange={(value) => console.log(value)}
+/>;
+```
+
+### Autocomplete.Async Props
+
+Accepts all the same props as `Autocomplete` except `items`, plus:
+
+| Prop           | Type                          | Default                    | Description                                                        |
+| -------------- | ----------------------------- | -------------------------- | ------------------------------------------------------------------ |
+| `fetcher`      | `AutocompleteAsyncFetcher<T>` | -                          | Fetcher called on each keystroke (debounced by default)            |
+| `loadingText`  | `string`                      | `"Loading..."`             | Text shown while loading                                           |
+| `errorText`    | `string`                      | `"Couldn't load results."` | Message shown in the popover 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) |
+
+### AutocompleteAsyncFetcher
+
+```ts
+type AutocompleteAsyncFetcher<T> =
+  | ((query: string | null, options: { signal: AbortSignal }) => Promise<T[]>)
+  | {
+      fn: (query: string | null, options: { signal: AbortSignal }) => Promise<T[]>;
+      debounceMs: number;
+    };
+```
+
+`query` is `null` when the user has not typed anything (e.g. the dropdown was just opened or the input was cleared). Pass `{ fn, debounceMs }` to customize the debounce delay.
+
+### Error handling
+
+If the fetcher throws or rejects, `Autocomplete.Async` renders a built-in inline error state in the popover — the `errorText` message plus a **Retry** button that re-runs the last fetch — instead of the misleading "No results." empty state. Aborted/superseded requests 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
+
+`Autocomplete.Parts` exposes styled sub-components and hooks for fully custom compositions:
+
+```tsx
+const {
+  Root,
+  Value,
+  InputGroup,
+  Input,
+  Trigger,
+  Content,
+  List,
+  Item,
+  Empty,
+  Clear,
+  Group,
+  GroupLabel,
+  Collection,
+  Status,
+} = Autocomplete.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 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 underlying text input (use for React Hook Form's `field.ref`).                         |
+
+Autocomplete's value is the raw input string, so no value-serialisation hook is needed.
+
+## Examples
+
+### Controlled Autocomplete
+
+```tsx
+const [query, setQuery] = useState("");
+
+<Autocomplete items={suggestions} value={query} onValueChange={setQuery} placeholder="Search..." />;
+```
+
+### Address Input with Async Suggestions
+
+```tsx
+const fetcher: AutocompleteAsyncFetcher<string> = async (query, { signal }) => {
+  if (!query) return [];
+  const res = await fetch(`/api/address-lookup?q=${encodeURIComponent(query)}`, { signal });
+  return res.json();
+};
+
+<Autocomplete.Async
+  fetcher={fetcher}
+  placeholder="Start typing an address..."
+  onValueChange={(address) => form.setValue("address", address)}
+/>;
+```
+
+### Async with Parts (custom composition)
+
+Combine `Autocomplete.useAsync` with `Autocomplete.Parts` for full control over layout and rendering:
+
+`Autocomplete.useAsync` accepts the same options as `Autocomplete.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
+const suggestions = Autocomplete.useAsync({
+  fetcher: async (query, { signal }) => {
+    const res = await fetch(`/api/suggestions?q=${query ?? ""}`, { signal });
+    return res.json();
+  },
+  onFetchError: (error) => reportError(error),
+});
+
+<Autocomplete.Parts.Root {...suggestions} filter={null}>
+  <Autocomplete.Parts.InputGroup>
+    <Autocomplete.Parts.Input placeholder="Search..." />
+    <Autocomplete.Parts.Clear />
+  </Autocomplete.Parts.InputGroup>
+  <Autocomplete.Parts.Content>
+    <Autocomplete.Parts.List>
+      {suggestions.items.map((item) => (
+        <Autocomplete.Parts.Item key={item} value={item}>
+          {item}
+        </Autocomplete.Parts.Item>
+      ))}
+      <Autocomplete.Parts.Empty>
+        {suggestions.error ? (
+          <button onClick={suggestions.retry}>Couldn't load. Retry</button>
+        ) : suggestions.loading ? (
+          "Loading..."
+        ) : (
+          "No results."
+        )}
+      </Autocomplete.Parts.Empty>
+    </Autocomplete.Parts.List>
+  </Autocomplete.Parts.Content>
+</Autocomplete.Parts.Root>;
+```
+
+## Accessibility
+
+- Input is keyboard accessible with arrow key navigation
+- Pressing `Escape` closes the suggestion list
+- Selecting a suggestion fills the input with the item's label
+- When used standalone (no visible `<label>`), give the input an accessible name with `aria-label` or `aria-labelledby` — otherwise screen readers announce only the current value:
+
+```tsx
+<Autocomplete items={items} aria-label="City search" />
+```
+
+## Related Components
+
+- [Select](./select.md) - Non-searchable discrete item selection
+- [Combobox](./combobox.md) - Searchable combobox that returns discrete items
+- [Input](./input.md) - Plain text input without suggestions

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

@@ -0,0 +1,80 @@
+---
+title: Avatar
+description: User avatar with image and fallback (Base UI)
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/avatar.docs.outline.md — do not edit by hand. -->
+
+# Avatar
+
+The `Avatar` component wraps [Base UI Avatar](https://base-ui.com/react/components/avatar): a root container with an optional image and fallback content (typically initials) when the image is missing or fails to load.
+
+## Import
+
+```tsx
+import { Avatar } from "@tailor-platform/app-shell";
+```
+
+## Basic usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Avatar.Root>
+      <Avatar.Image src="/user.png" alt="Jane Doe" />
+      <Avatar.Fallback>JD</Avatar.Fallback>
+    </Avatar.Root>
+  );
+}
+```
+
+## Parts
+
+| Part              | Description                                                |
+| ----------------- | ---------------------------------------------------------- |
+| `Avatar.Root`     | Outer container; applies size and surface styles.          |
+| `Avatar.Image`    | `<img>` for the photo; hidden when not loaded or on error. |
+| `Avatar.Fallback` | Shown when there is no image or the image failed to load.  |
+
+## Root props
+
+| Prop        | Type                                | Default     | Description                |
+| ----------- | ----------------------------------- | ----------- | -------------------------- |
+| `size`      | `"xs" \| "sm" \| "default" \| "lg"` | `"default"` | Circle size (28px default) |
+| `className` | `string`                            | —           | Extra classes              |
+| `children`  | `React.ReactNode`                   | —           | Image + fallback           |
+
+`Avatar.Root` forwards other stable props from Base UI (for example `aria-hidden`, `style`) and standard HTML attributes for the `<span>` root.
+
+## Sizes
+
+The smallest size, `xs` (16px), is intended for compact/inline contexts and single-glyph or icon content; two-letter initials will be cramped.
+
+```tsx
+<Avatar.Root size="xs">
+  <Avatar.Fallback>A</Avatar.Fallback>
+</Avatar.Root>
+<Avatar.Root size="sm">
+  <Avatar.Fallback>AB</Avatar.Fallback>
+</Avatar.Root>
+<Avatar.Root size="default">
+  <Avatar.Fallback>CD</Avatar.Fallback>
+</Avatar.Root>
+<Avatar.Root size="lg">
+  <Avatar.Fallback>EF</Avatar.Fallback>
+</Avatar.Root>
+```
+
+## Types
+
+`AvatarProps` is the props type for `Avatar.Root` (includes `size` and Base UI root props). Import when wrapping or composing:
+
+```tsx
+import { Avatar, type AvatarProps } from "@tailor-platform/app-shell";
+```
+
+## `avatarVariants`
+
+The same size styles used by `Avatar.Root` are exported as `avatarVariants` (for example if you need to mirror avatar dimensions in layout code). Prefer the `size` prop on `Avatar.Root` for normal use.