@tailor-platform/app-shell 1.15.0 → 1.17.0

package/skills/app-shell-patterns/references/components/sidebar-layout.md

@@ -0,0 +1,258 @@
+---
+title: SidebarLayout
+description: Default AppShell layout with a built-in sidebar, content header, optional app-wide top bar, and an escape-hatch body slot
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/sidebar-layout.docs.outline.md — do not edit by hand. -->
+
+# SidebarLayout
+
+`SidebarLayout` is the default AppShell layout. By default it renders:
+
+- `SidebarLayout.DefaultSidebar`
+- `SidebarLayout.DefaultHeader`
+- the current route outlet
+
+You can replace the sidebar, replace the content header, add a full-width `topBar` above the whole shell, or take over the entire region beside the sidebar with the `body` slot.
+
+If you want the opinionated "global app header + icon rail" mode, use [`GlobalHeaderLayout`](./global-header-layout.md), which is built on top of `SidebarLayout`.
+
+## Import
+
+```tsx
+import { SidebarLayout } from "@tailor-platform/app-shell";
+```
+
+## Basic usage
+
+```tsx
+import { AppShell, SidebarLayout } from "@tailor-platform/app-shell";
+
+function App() {
+  return (
+    <AppShell modules={modules}>
+      <SidebarLayout />
+    </AppShell>
+  );
+}
+```
+
+This gives you:
+
+- ✅ Responsive sidebar with auto-generated navigation from modules
+- ✅ Breadcrumb navigation
+- ✅ Theme toggle via the built-in header
+- ✅ Mobile-friendly collapse behavior
+
+## Props
+
+### Common props
+
+| Prop          | Type              | Default                            | Description                                                                                                  |
+| ------------- | ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `sidebar`     | `React.ReactNode` | `<SidebarLayout.DefaultSidebar />` | Replaces the entire sidebar region.                                                                          |
+| `defaultOpen` | `boolean`         | `true`                             | Whether the sidebar starts expanded on desktop.                                                              |
+| `collapsible` | `boolean`         | `true`                             | Whether the sidebar can be collapsed. When `false`, toggle controls are hidden and `defaultOpen` is ignored. |
+| `topBar`      | `React.ReactNode` | -                                  | Full-width bar above both the sidebar and the content region.                                                |
+
+### Default content mode
+
+Use this when AppShell should keep owning the content column.
+
+| Prop       | Type                                                            | Default                           | Description                                                 |
+| ---------- | --------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------- |
+| `header`   | `React.ReactNode`                                               | `<SidebarLayout.DefaultHeader />` | Replaces the content header above the main column.          |
+| `children` | `(props: { Outlet: () => React.ReactNode }) => React.ReactNode` | current route outlet              | Custom content renderer that wraps or surrounds the outlet. |
+
+### Body-slot mode
+
+Use this when you need to compose your own columns beside the sidebar.
+
+| Prop   | Type              | Default  | Description                                                                                                   |
+| ------ | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `body` | `React.ReactNode` | required | Replaces everything to the right of the sidebar. Compose it with `ContentContainer`, `Outlet`, and `Trigger`. |
+
+`body` is mutually exclusive with `header` and `children`, because it replaces the region those props normally describe.
+
+## Extending the built-in header
+
+The supported "small customization" path is to pass `SidebarLayout.DefaultHeader` into the `header` slot and fill its `actions` cluster.
+
+```tsx
+import { AppearanceSwitcher, Button, SidebarLayout } from "@tailor-platform/app-shell";
+import { BellIcon } from "lucide-react";
+
+<SidebarLayout
+  header={
+    <SidebarLayout.DefaultHeader
+      actions={[
+        <Button key="notifications" variant="outline" size="icon" aria-label="Notifications">
+          <BellIcon className="size-4" />
+        </Button>,
+        <AppearanceSwitcher key="appearance" />,
+      ]}
+    />
+  }
+/>;
+```
+
+`actions` replaces the entire right-hand cluster. If you still want the built-in appearance switcher, include `<AppearanceSwitcher />` yourself.
+
+## Replacing the sidebar
+
+Pass `sidebar` to replace the whole left-side region. The built-in component is [`SidebarLayout.DefaultSidebar`](./default-sidebar.md), also exported as `DefaultSidebar`.
+
+```tsx
+import {
+  SidebarGroup,
+  SidebarItem,
+  SidebarLayout,
+  SidebarSeparator,
+} from "@tailor-platform/app-shell";
+
+<SidebarLayout
+  sidebar={
+    <SidebarLayout.DefaultSidebar>
+      <SidebarItem to="/" />
+      <SidebarSeparator />
+      <SidebarGroup title="Main">
+        <SidebarItem to="/dashboard" />
+        <SidebarItem to="/orders" />
+      </SidebarGroup>
+    </SidebarLayout.DefaultSidebar>
+  }
+/>;
+```
+
+## Adding an app-wide top bar
+
+`topBar` renders above the whole shell, spanning both the sidebar and the content region.
+
+```tsx
+<SidebarLayout topBar={<MyGlobalTopBar />} sidebar={<SidebarLayout.DefaultSidebar hideHeader />} />
+```
+
+When `topBar` is present, the fixed sidebar is offset below it. The bar should be `3.5rem` tall (`h-14`) to match the built-in layout.
+
+If you specifically want AppShell's opinionated global-header mode, use [`GlobalHeaderLayout`](./global-header-layout.md), which wires the top bar, icon rail, and matching default sidebar for you.
+
+## Owning the region beside the sidebar
+
+Use `body` when the stock content column is too restrictive and you need your own side columns.
+
+```tsx
+<SidebarLayout
+  body={
+    <>
+      <aside className="w-64 shrink-0 overflow-y-auto border-r">
+        <TableOfContents />
+      </aside>
+      <SidebarLayout.ContentContainer header={<SidebarLayout.DefaultHeader />}>
+        <SidebarLayout.Outlet />
+      </SidebarLayout.ContentContainer>
+      <aside className="w-96 shrink-0 overflow-y-auto border-l">
+        <AssistantPanel />
+      </aside>
+    </>
+  }
+/>
+```
+
+`SidebarLayout.ContentContainer` is the stock main column: inset padding, pinned header slot, scroll region, and `useAppShellScrollContainer()` support. `SidebarLayout.Trigger` exposes the built-in sidebar toggle so custom headers do not need DOM workarounds.
+
+## Reading and controlling the sidebar
+
+Use `useAppShellSidebar()` to read and control the sidebar state instead of observing internal DOM attributes or clicking the trigger through the DOM.
+
+```tsx
+import { useAppShellSidebar } from "@tailor-platform/app-shell";
+
+function CustomHeader() {
+  const { open, isMobile, toggle } = useAppShellSidebar();
+
+  return (
+    <div className="flex items-center justify-between border-b px-4 py-3">
+      <button type="button" onClick={toggle}>
+        {open ? "Hide navigation" : "Show navigation"}
+      </button>
+      <span>{isMobile ? "Mobile" : "Desktop"}</span>
+    </div>
+  );
+}
+```
+
+Outside `SidebarLayout`, the hook returns a safe fallback (`open: true`, `isMobile: false`, no-op setters) rather than throwing.
+
+## Reusing the built-in breadcrumb
+
+`DynamicBreadcrumb` is exported when you want the same route-driven breadcrumb in a custom header or top bar:
+
+```tsx
+import { DynamicBreadcrumb, SidebarLayout } from "@tailor-platform/app-shell";
+
+<header className="flex items-center gap-3 border-b px-4 py-3">
+  <SidebarLayout.Trigger />
+  <DynamicBreadcrumb />
+</header>;
+```
+
+## Accessing the content scroll container
+
+The AppShell is viewport-bounded (`h-svh`), so the **document itself does not scroll** — the content area does. Code that previously relied on `window`/document scroll (reading `window.scrollY`, listening to `window`'s `scroll` event, `window.scrollTo(...)`, or an `IntersectionObserver` with the default viewport root) should target the content scroll container instead.
+
+Use the `useAppShellScrollContainer()` hook to get a ref to that element from any page:
+
+```tsx
+import { useAppShellScrollContainer } from "@tailor-platform/app-shell";
+import { useEffect, useState } from "react";
+
+function ReadingProgress() {
+  const scrollRef = useAppShellScrollContainer();
+  const [progress, setProgress] = useState(0);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const onScroll = () => {
+      const max = el.scrollHeight - el.clientHeight;
+      setProgress(max > 0 ? el.scrollTop / max : 0);
+    };
+    onScroll();
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }, [scrollRef]);
+
+  return <progress value={progress} />;
+}
+```
+
+The same element handles imperative scrolling (`scrollRef.current?.scrollTo({ top: 0, behavior: "smooth" })`) and works as an `IntersectionObserver` root (`new IntersectionObserver(cb, { root: scrollRef.current })`).
+
+Notes:
+
+- The element mounts with the layout, above your page, so read `ref.current` inside an effect — it is populated by the time effects run, not during render.
+- On a [`<Layout fill>`](./layout.md#fill-mode) page this element does **not** scroll; its children (for example a `DataTable`) manage their own scrolling.
+- Outside a `SidebarLayout` (a fully custom layout) the returned ref's `current` is always `null` — such layouts own their own scroll region.
+- For non-React access (CSS, tests, plain DOM) the container also carries a `data-appshell-scroll-container` attribute: `document.querySelector("[data-appshell-scroll-container]")`.
+
+## Styling
+
+The sidebar and layout are styled with the library's internal `astw:`-prefixed utilities. Write **plain** Tailwind utilities in your own markup — see [Styling AppShell components](../concepts/styling-theming.md#styling-appshell-components).
+
+## Accessibility
+
+SidebarLayout includes built-in accessibility features:
+
+- **Keyboard navigation** for sidebar interaction
+- **ARIA labels** on built-in controls
+- **Focus management** when the sidebar opens on mobile
+- **Responsive behavior** that works with keyboard, mouse, and touch input
+
+## Related
+
+- [AppShell](./app-shell.md) - root component
+- [DefaultHeader](./default-header.md) - built-in content header (`SidebarLayout.DefaultHeader`)
+- [DefaultSidebar](./default-sidebar.md) - built-in sidebar (`SidebarLayout.DefaultSidebar`)
+- [GlobalHeaderLayout](./global-header-layout.md) - opinionated app-wide header mode built on SidebarLayout
+- [AppearanceSwitcher](./appearance-switcher.md) - color-theme dropdown for header actions
+- [usePageMeta](../api/use-page-meta.md) - route metadata lookup used by sidebar items

package/skills/app-shell-patterns/references/components/sidebar-section.md

@@ -0,0 +1,114 @@
+---
+title: SidebarSection
+description: Static, non-collapsible heading for grouping flat sidebar navigation items
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/sidebar-section.docs.outline.md — do not edit by hand. -->
+
+# SidebarSection
+
+`SidebarSection` places a static heading above a run of flat navigation items. Unlike [`SidebarGroup`](./sidebar-group.md), a section is neither collapsible nor navigable, and its items keep the same styling and indentation as top-level items.
+
+## Import
+
+```tsx
+import { SidebarSection } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+```tsx
+import {
+  DefaultSidebar,
+  SidebarItem,
+  SidebarSection,
+  SidebarSeparator,
+} from "@tailor-platform/app-shell";
+
+<DefaultSidebar>
+  <SidebarItem to="/overview" />
+
+  <SidebarSeparator />
+
+  <SidebarSection title="Services">
+    <SidebarItem to="/ai-gateways" />
+    <SidebarItem to="/applications" />
+    <SidebarItem to="/auth-connections" />
+  </SidebarSection>
+
+  <SidebarSeparator />
+
+  <SidebarSection title="Logs">
+    <SidebarItem to="/activity-logs" />
+    <SidebarItem to="/dataplane-logs" />
+  </SidebarSection>
+</DefaultSidebar>;
+```
+
+## Props
+
+| Prop       | Type                        | Default      | Description                       |
+| ---------- | --------------------------- | ------------ | --------------------------------- |
+| `title`    | `string \| LocalizedString` | **Required** | Section heading (supports i18n)   |
+| `children` | `React.ReactNode`           | **Required** | Child items (usually SidebarItem) |
+
+## Behavior
+
+- **Not interactive.** The heading is plain text: it is not a link and has no expand/collapse toggle.
+- **Flat items.** Children render at the same level as top-level `SidebarItem`s, not as an indented submenu.
+- **Icon rail.** When the sidebar collapses to an icon rail, the heading is hidden and the items stay in the rail as ordinary icons. Unlike `SidebarGroup`, there is no hover flyout.
+- **No automatic dividers.** Add a `SidebarSeparator` between sections where you want a line.
+
+## Internationalization
+
+Titles support i18n with `defineI18nLabels`:
+
+```tsx
+import { defineI18nLabels } from "@tailor-platform/app-shell";
+
+const labels = defineI18nLabels({
+  en: { services: "Services" },
+  ja: { services: "サービス" },
+});
+
+<SidebarSection title={labels.t("services")}>
+  <SidebarItem to="/ai-gateways" />
+</SidebarSection>;
+```
+
+## When to Use
+
+**Use SidebarSection when:**
+
+- You want to label a run of items with a heading, but keep them always visible
+- The items are peers of your top-level items, not children of a parent page
+- You want the items to stay as individual icons in the icon rail
+
+**Use SidebarGroup when:**
+
+- Users should be able to collapse the items
+- The items belong under a parent with its own icon (or landing page via `to`)
+- You need nesting
+
+| Feature             | SidebarSection    | SidebarGroup              |
+| ------------------- | ----------------- | ------------------------- |
+| **Collapsible**     | ❌ No             | ✅ Yes                    |
+| **Heading is link** | ❌ No             | Optional (`to` prop)      |
+| **Icon**            | ❌ No             | Optional                  |
+| **Child styling**   | Same as top level | Indented submenu          |
+| **Icon rail**       | Heading hidden    | Group icon opens a flyout |
+| **Nesting**         | Not intended      | Can contain groups        |
+
+## Accessibility
+
+The children are rendered as their own list, labelled by the heading, so screen readers announce the section name (for example, "Services, list, 3 items") when entering it.
+
+## Related Components
+
+- [SidebarGroup](./sidebar-group.md) - Collapsible, nested navigation groups
+- [SidebarItem](./sidebar-item.md) - Individual navigation items
+- [DefaultSidebar](./default-sidebar.md) - Container for sidebar navigation
+
+## Related Concepts
+
+- [Sidebar Navigation](../concepts/sidebar-navigation.md) - Sidebar customization guide

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

@@ -0,0 +1,81 @@
+---
+title: Spinner
+description: Lightweight loading indicator component with accessible defaults and preset sizes
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/spinner.docs.outline.md — do not edit by hand. -->
+
+# Spinner
+
+`Spinner` is AppShell's reusable loading indicator. It renders a small rotating SVG and is used throughout the built-in UI for loading states such as `ActionPanel`, command palette search, and CSV import progress.
+
+## Import
+
+```tsx
+import { Spinner } from "@tailor-platform/app-shell";
+```
+
+## Basic usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return <Spinner aria-label="Loading" />;
+}
+```
+
+## Props
+
+`Spinner` accepts all standard `<svg>` props plus one AppShell prop:
+
+| Prop   | Type                                | Default     | Description                                                                |
+| ------ | ----------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| `size` | `"xs" \| "sm" \| "default" \| "lg"` | `"default"` | Preset square size. Ignored when `width` or `height` is passed explicitly. |
+
+Preset sizes map to:
+
+| `size`      | Pixels |
+| ----------- | ------ |
+| `"xs"`      | `12`   |
+| `"sm"`      | `14`   |
+| `"default"` | `16`   |
+| `"lg"`      | `20`   |
+
+## Accessibility
+
+`Spinner` defaults to decorative output unless you give it an accessible name:
+
+- with `aria-label` or `aria-labelledby`, it renders with `role="status"`
+- with `aria-hidden={true}`, it stays decorative
+- with neither, it is treated as decorative and gets `aria-hidden="true"`
+
+Use a label when the spinner is the primary visible loading affordance:
+
+```tsx
+<Spinner size="sm" aria-label="Loading orders" />
+```
+
+When the surrounding control already has its own accessible name, keep the spinner decorative:
+
+```tsx
+<Button disabled>
+  <Spinner size="sm" aria-hidden />
+  Saving
+</Button>
+```
+
+## Sizing and styling
+
+Pass ordinary Tailwind utilities through `className` for color and layout, or override the dimensions directly with `width` / `height`.
+
+```tsx
+<Spinner className="text-muted-foreground" />
+<Spinner size="lg" className="text-primary" aria-label="Generating report" />
+<Spinner width={24} height={24} aria-label="Loading" />
+```
+
+## Related
+
+- [ActionPanel](./action-panel.md) - uses `Spinner` for per-row loading states
+- [WithGuard](./with-guard.md) - common place to render a loading spinner while guards resolve

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

@@ -0,0 +1,188 @@
+---
+title: Table
+description: Semantic HTML table with pre-styled sub-components
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/table.docs.outline.md — do not edit by hand. -->
+
+# Table
+
+The `Table` component provides a set of pre-styled, semantic HTML table sub-components. It wraps a standard `<table>` element in a horizontally scrollable container.
+
+## Import
+
+```tsx
+import { Table } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Table.Root>
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Name</Table.Head>
+          <Table.Head>Email</Table.Head>
+          <Table.Head>Role</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell>Alice</Table.Cell>
+          <Table.Cell>alice@example.com</Table.Cell>
+          <Table.Cell>Admin</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table.Root>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component   | HTML element | Description                            |
+| --------------- | ------------ | -------------------------------------- |
+| `Table.Root`    | `<table>`    | Root element with scrollable container |
+| `Table.Header`  | `<thead>`    | Table header section                   |
+| `Table.Body`    | `<tbody>`    | Table body section                     |
+| `Table.Footer`  | `<tfoot>`    | Table footer section                   |
+| `Table.Row`     | `<tr>`       | Table row (hover and selection styles) |
+| `Table.Head`    | `<th>`       | Header cell                            |
+| `Table.Cell`    | `<td>`       | Data cell                              |
+| `Table.Caption` | `<caption>`  | Table caption                          |
+
+## Props
+
+### Table.Root Props
+
+| Prop                 | Type                        | Default | Description                                                       |
+| -------------------- | --------------------------- | ------- | ----------------------------------------------------------------- |
+| `className`          | `string`                    | -       | Additional CSS classes for the `<table>` element                  |
+| `containerClassName` | `string`                    | -       | Additional CSS classes for the outer scrollable `<div>` container |
+| `containerRef`       | `React.Ref<HTMLDivElement>` | -       | Ref forwarded to the outer scrollable `<div>` container           |
+
+All other standard HTML `<table>` props are accepted.
+
+All other sub-components (`Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.Caption`) accept `className` and their corresponding standard HTML element props.
+
+`Table.Head` and `Table.Cell` also accept `align?: "left" | "center" | "right"` for semantic text alignment without relying on utility-class overrides.
+
+## Examples
+
+### With Footer
+
+```tsx
+<Table.Root>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Product</Table.Head>
+      <Table.Head>Qty</Table.Head>
+      <Table.Head>Price</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Widget A</Table.Cell>
+      <Table.Cell>10</Table.Cell>
+      <Table.Cell>$100.00</Table.Cell>
+    </Table.Row>
+    <Table.Row>
+      <Table.Cell>Widget B</Table.Cell>
+      <Table.Cell>5</Table.Cell>
+      <Table.Cell>$75.00</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+  <Table.Footer>
+    <Table.Row>
+      <Table.Cell colSpan={2}>Total</Table.Cell>
+      <Table.Cell>$175.00</Table.Cell>
+    </Table.Row>
+  </Table.Footer>
+</Table.Root>
+```
+
+### With Caption
+
+```tsx
+<Table.Root>
+  <Table.Caption>Order line items</Table.Caption>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Item</Table.Head>
+      <Table.Head>Status</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Item 1</Table.Cell>
+      <Table.Cell>Shipped</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table.Root>
+```
+
+### Right-aligned numeric columns
+
+```tsx
+<Table.Root>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Item</Table.Head>
+      <Table.Head align="right">Amount</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Widget A</Table.Cell>
+      <Table.Cell align="right">123</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table.Root>
+```
+
+### Center-aligned status column
+
+```tsx
+<Table.Root>
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Item</Table.Head>
+      <Table.Head align="center">Status</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Widget A</Table.Cell>
+      <Table.Cell align="center">Active</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table.Root>
+```
+
+### Constrained Height with Scroll
+
+```tsx
+<Table.Root containerClassName="max-h-64 overflow-y-auto">
+  <Table.Header>
+    <Table.Row>
+      <Table.Head>Name</Table.Head>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    {items.map((item) => (
+      <Table.Row key={item.id}>
+        <Table.Cell>{item.name}</Table.Cell>
+      </Table.Row>
+    ))}
+  </Table.Body>
+</Table.Root>
+```
+
+## Related Components
+
+- [Badge](./badge.md) - Display status inside table cells
+- [Layout](./layout.md) - Place tables inside page layouts