@tailor-platform/app-shell 1.15.0 → 1.17.0

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

@@ -0,0 +1,138 @@
+---
+title: Toolbar
+description: Full-width action bars with composable rows, grouped controls, and keyboard navigation
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/toolbar.docs.outline.md — do not edit by hand. -->
+
+# Toolbar
+
+`Toolbar` is a full-width action bar. It is independent of `DataTable`: place any AppShell or application control in it, including buttons, search fields, selects, comboboxes, and tabs.
+
+```tsx
+import { Toolbar } from "@tailor-platform/app-shell";
+
+<Toolbar.Root>
+  <Toolbar.Row justify="between" aria-label="Order actions">
+    <Toolbar.Group>
+      <Button variant="outline">Export</Button>
+    </Toolbar.Group>
+    <Toolbar.Group>
+      <Button>New order</Button>
+    </Toolbar.Group>
+  </Toolbar.Row>
+</Toolbar.Root>;
+```
+
+## Structure
+
+`Toolbar.Root` stacks rows. `Toolbar.Row` is one horizontal, keyboard-navigable action row. Use `Toolbar.Group` to keep related controls together and `Toolbar.Separator` to divide groups.
+
+```tsx
+<Toolbar.Root>
+  <Toolbar.Row justify="between" aria-label="Text formatting">
+    <Toolbar.Group>
+      <Button>Bold</Button>
+      <Button>Italic</Button>
+      <Toolbar.Separator />
+      <Button>Copy</Button>
+    </Toolbar.Group>
+
+    <Toolbar.Group>
+      <Button>Save</Button>
+    </Toolbar.Group>
+  </Toolbar.Row>
+
+  <Toolbar.Row aria-label="Active filters">
+    <Toolbar.Group>
+      <Button variant="secondary">Status: Open</Button>
+    </Toolbar.Group>
+  </Toolbar.Row>
+</Toolbar.Root>
+```
+
+### Row alignment
+
+Use `justify="between"` when a row has one leading and one trailing group. The row places those outer groups at opposite edges. The default, `"start"`, keeps every group at the leading edge.
+
+```tsx
+<Toolbar.Row justify="between" aria-label="List actions">
+  <Toolbar.Group>{/* search and filters */}</Toolbar.Group>
+  <Toolbar.Group>{/* export and create actions */}</Toolbar.Group>
+</Toolbar.Row>
+```
+
+Keep controls that belong to the leading region in the same group. `justify="between"` distributes **direct** groups, so a separator should also stay inside that group.
+
+### Sizing fields
+
+`Input` keeps its normal `w-full` behavior inside a toolbar. Give a field an explicit layout box when it shares a group with other controls.
+
+```tsx
+<Toolbar.Group>
+  <div className="w-52">
+    <Input placeholder="Search orders" />
+  </div>
+  <Combobox className="w-40" items={users} placeholder="Assignee" />
+  <Select className="w-40" items={sortOptions} />
+</Toolbar.Group>
+```
+
+## Keyboard navigation
+
+Every row has `role="toolbar"` and supports `ArrowLeft`, `ArrowRight`, `Home`, and `End` for registered AppShell controls. Disabled controls are skipped and focus loops at either end.
+
+AppShell `Button`, `Input`, `Select`, `Combobox`, and `Tabs.Tab` register automatically when rendered inside a row. Composite controls retain their own directional keys: arrows move the caret in an input, move between tabs, or navigate an open select/combobox. Use `Tab` to leave a composite control.
+
+Each row should have an accessible name via `aria-label` or `aria-labelledby`.
+
+## DataTable example
+
+`DataTable.Filters` and `DataTable.ColumnSettings` are ordinary toolbar controls. They can be placed wherever the layout requires.
+
+```tsx
+<DataTable.Root value={table}>
+  <Toolbar.Root>
+    <Toolbar.Row justify="between" aria-label="Invoice table controls">
+      <Toolbar.Group>
+        <DataTable.Filters />
+      </Toolbar.Group>
+      <Toolbar.Group>
+        <DataTable.ColumnSettings />
+      </Toolbar.Group>
+    </Toolbar.Row>
+  </Toolbar.Root>
+  <DataTable.Table />
+</DataTable.Root>
+```
+
+When a generic toolbar is a direct child of `DataTable.Root`, DataTable retains its outer top corners and turns the toolbar border into only the divider beneath the toolbar.
+
+## API
+
+### `Toolbar.Root`
+
+| Prop        | Type        | Default | Description                                      |
+| ----------- | ----------- | ------- | ------------------------------------------------ |
+| `children`  | `ReactNode` | —       | One or more `Toolbar.Row` elements.              |
+| `className` | `string`    | —       | Additional classes for the full-width container. |
+
+### `Toolbar.Row`
+
+| Prop                             | Type                   | Default   | Description                                             |
+| -------------------------------- | ---------------------- | --------- | ------------------------------------------------------- |
+| `children`                       | `ReactNode`            | —         | Groups and separators in this horizontal row.           |
+| `justify`                        | `"start" \| "between"` | `"start"` | Align direct groups at the start, or at opposite edges. |
+| `aria-label` / `aria-labelledby` | `string`               | —         | Accessible name for this toolbar row.                   |
+| `className`                      | `string`               | —         | Additional classes for the row.                         |
+
+### `Toolbar.Group`
+
+| Prop        | Type        | Default | Description                                                 |
+| ----------- | ----------- | ------- | ----------------------------------------------------------- |
+| `children`  | `ReactNode` | —       | Related controls arranged horizontally and allowed to wrap. |
+| `className` | `string`    | —       | Additional classes for the group.                           |
+
+### `Toolbar.Separator`
+
+A vertical, accessible separator between related control groups. It accepts `className` for visual customization.

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

@@ -0,0 +1,144 @@
+---
+title: Tooltip
+description: Hover/focus tooltip with configurable placement and shared delay via Tooltip.Provider
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/tooltip.docs.outline.md — do not edit by hand. -->
+
+# Tooltip
+
+The `Tooltip` component displays contextual information on hover or focus. It is backed by Base UI's Tooltip primitive.
+
+## Import
+
+```tsx
+import { Tooltip } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Tooltip.Root>
+      <Tooltip.Trigger render={<Button variant="outline" />}>Hover me</Tooltip.Trigger>
+      <Tooltip.Content>Helpful information</Tooltip.Content>
+    </Tooltip.Root>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component      | Description                                                 |
+| ------------------ | ----------------------------------------------------------- |
+| `Tooltip.Provider` | Provides shared delay configuration for all nested tooltips |
+| `Tooltip.Root`     | Manages tooltip open/close state                            |
+| `Tooltip.Trigger`  | Element that shows the tooltip on hover or focus            |
+| `Tooltip.Content`  | The tooltip popup containing the help text                  |
+
+## Props
+
+### Tooltip.Provider Props
+
+Wrap a section of your UI (e.g. a toolbar) with `Tooltip.Provider` to share delay settings across multiple tooltips.
+
+| Prop         | Type              | Default | Description                                         |
+| ------------ | ----------------- | ------- | --------------------------------------------------- |
+| `delay`      | `number`          | `0`     | Delay in ms before the tooltip opens (milliseconds) |
+| `closeDelay` | `number`          | -       | Delay in ms before the tooltip closes               |
+| `timeout`    | `number`          | -       | Timeout in ms after which the tooltip auto-closes   |
+| `children`   | `React.ReactNode` | -       | Nested tooltip components                           |
+
+### Tooltip.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  |
+| `children`     | `React.ReactNode`         | -       | Tooltip sub-components            |
+
+### Tooltip.Content Props
+
+| Prop         | Type                                     | Default    | Description                                              |
+| ------------ | ---------------------------------------- | ---------- | -------------------------------------------------------- |
+| `side`       | `"top" \| "right" \| "bottom" \| "left"` | `"top"`    | Preferred placement of the tooltip                       |
+| `align`      | `"start" \| "center" \| "end"`           | `"center"` | Alignment along the placement axis                       |
+| `sideOffset` | `number`                                 | `5`        | Distance in px from the trigger                          |
+| `noArrow`    | `boolean`                                | `false`    | When `true`, suppresses the arrow indicator on the popup |
+| `className`  | `string`                                 | -          | Additional CSS classes                                   |
+| `children`   | `React.ReactNode`                        | -          | Tooltip text or content                                  |
+
+## Placement
+
+```tsx
+<Tooltip.Root>
+  <Tooltip.Trigger render={<Button />}>Trigger</Tooltip.Trigger>
+  <Tooltip.Content side="right" align="start">
+    Appears on the right
+  </Tooltip.Content>
+</Tooltip.Root>
+```
+
+## Shared Delay with Provider
+
+Use `Tooltip.Provider` to avoid tooltips opening immediately in dense UIs like toolbars:
+
+```tsx
+<Tooltip.Provider delay={300}>
+  <Toolbar>
+    <Tooltip.Root>
+      <Tooltip.Trigger render={<Button size="icon" />}>
+        <BoldIcon />
+      </Tooltip.Trigger>
+      <Tooltip.Content>Bold</Tooltip.Content>
+    </Tooltip.Root>
+    <Tooltip.Root>
+      <Tooltip.Trigger render={<Button size="icon" />}>
+        <ItalicIcon />
+      </Tooltip.Trigger>
+      <Tooltip.Content>Italic</Tooltip.Content>
+    </Tooltip.Root>
+  </Toolbar>
+</Tooltip.Provider>
+```
+
+## Examples
+
+### Icon Button with Tooltip
+
+```tsx
+import { PencilIcon } from "lucide-react";
+
+<Tooltip.Root>
+  <Tooltip.Trigger render={<Button size="icon" variant="ghost" />}>
+    <PencilIcon />
+    <span className="sr-only">Edit</span>
+  </Tooltip.Trigger>
+  <Tooltip.Content>Edit order</Tooltip.Content>
+</Tooltip.Root>;
+```
+
+### Controlled Tooltip
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Tooltip.Root open={open} onOpenChange={setOpen}>
+  <Tooltip.Trigger render={<Button />}>Info</Tooltip.Trigger>
+  <Tooltip.Content>Additional details here</Tooltip.Content>
+</Tooltip.Root>;
+```
+
+## Accessibility
+
+- Tooltip content is rendered in a portal
+- Trigger receives focus and keyboard activation support
+- `sr-only` text on icon-only triggers is recommended for screen readers
+
+## Related Components
+
+- [Button](./button.md) - Common trigger element for tooltips