@tailor-platform/app-shell 1.16.0 → 1.17.0

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>
+```

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

@@ -381,6 +381,11 @@ The title styling is controlled by AppShell's theme. `SidebarGroup` takes no `cl
 - You want to organize a large navigation menu
 - Users need to focus on specific sections
 
+**Use [SidebarSection](./sidebar-section.md) when:**
+
+- You only need a heading above items that should always stay visible
+- The items should keep top-level styling instead of an indented submenu
+
 **Use SidebarItem directly when:**
 
 - You have standalone top-level navigation
@@ -453,6 +458,7 @@ Without `to`, only the chevron is clickable (for expand/collapse).
 ## Related Components
 
 - [SidebarItem](./sidebar-item.md) - Individual navigation items
+- [SidebarSection](./sidebar-section.md) - Static headings for flat items
 - [DefaultSidebar](./sidebar-layout.md) - Container for groups
 - [WithGuard](./with-guard.md) - Conditional rendering
 

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/concepts/custom-components.md

@@ -44,7 +44,7 @@ export function StepIndicator({ steps, current }: Props) {
             flex items-center gap-2 rounded-md px-3 py-2
             bg-muted text-sm text-muted-foreground
             data-[active]:bg-primary data-[active]:text-primary-foreground
-            data-[completed]:text-status-completed
+            data-[completed]:text-success-text
           "
         >
           {i < current && <Check className="size-4" />}

package/skills/app-shell-patterns/references/concepts/file-based-routing.md

@@ -143,12 +143,18 @@ type AppShellPageProps = {
   meta?: {
     title?: LocalizedString;
     icon?: ReactNode;
-    breadcrumbTitle?: string | ((segment: string) => string);
+    breadcrumbTitle?: string | ((segment: string) => LocalizedString);
   };
   guards?: Guard[];
 };
 ```
 
+For a localized breadcrumb, use `meta: { breadcrumbTitle: labels.t("orders") }`, just like `meta.title`.
+AppShell recognizes translation functions created by `labels.t()` and resolves them with the current locale.
+For a dynamic label, use `breadcrumbTitle: (segment) => labels.t("order", { id: segment })`.
+Other callbacks receive the URL segment; AppShell resolves any returned `LocalizedString` with the current locale.
+The existing `() => labels.t("orders")` form remains supported. Wrap handwritten locale functions in an outer callback rather than passing them directly.
+
 ## Path Conventions
 
 | Directory Name | Converts To | Description                                    |

package/skills/app-shell-patterns/references/concepts/graphql.md

@@ -153,22 +153,28 @@ function CreateOrderButton() {
 
 ### `additionalTypenames`
 
-When a mutation creates/updates/deletes an entity that another query already has cached, urql won't know to refetch unless you pass `additionalTypenames`. Use it on **both** the query and the mutation when they share a typename:
+When a mutation creates/updates/deletes an entity that another query already has cached, urql won't know to refetch unless you pass `additionalTypenames`. Use it on **both** the query and the mutation when they share a typename.
+
+Define the query's static `context` at module scope, outside the component, so its reference stays stable between renders. `useQuery` lists `context` as a hook dependency, so a fresh object on each render re-creates the query subscription and can cause query re-execution loops. The mutation's second argument is passed per call and is not a hook dependency, so it can stay inline.
 
 ```tsx
-// Query side — declares it cares about the Order typename
-const [{ data }] = useQuery({
-  query: OrdersQuery,
-  variables: { first: 25 },
-  context: { additionalTypenames: ["Order"] },
-});
-
-// Mutation side — declares it produces Order writes
-const [, createOrder] = useMutation(CreateOrderMutation);
-await createOrder(
-  { input },
-  { additionalTypenames: ["Order"] }, // triggers refetch of any query subscribed to 'Order'
-);
+const ordersQueryContext = { additionalTypenames: ["Order"] };
+
+function useOrders() {
+  // Query side — declares it cares about the Order typename
+  const [{ data }] = useQuery({
+    query: OrdersQuery,
+    variables: { first: 25 },
+    context: ordersQueryContext,
+  });
+
+  // Mutation side — declares it produces Order writes
+  const [, executeCreateOrder] = useMutation(CreateOrderMutation);
+  const createOrder = (input: CreateOrderInput) =>
+    executeCreateOrder({ input }, { additionalTypenames: ["Order"] });
+
+  return { data, createOrder };
+}
 ```
 
 Skip `additionalTypenames` only when the mutation's return type already includes the affected entity _and_ every cached query for it touched the same `id` — urql will then refresh by id. When in doubt, add it.

package/skills/app-shell-patterns/references/concepts/routing-navigation.md

@@ -159,15 +159,15 @@ const MyComponent = () => {
 
 ## Declarative Redirects
 
-`Navigate` redirects as a render result, which avoids the `useEffect` + `navigate()` pattern (that pattern renders the old page for a frame before it redirects):
+`Navigate` redirects as a render result, which avoids the `useEffect` + `navigate()` pattern (that pattern renders the old page for a frame before it redirects). `contextData` is typed through the `AppShellRegister` augmentation described in [useAppShell](../api/use-app-shell.md):
 
 ```tsx
 import { Navigate, useAppShellData } from "@tailor-platform/app-shell";
 
 const AdminPage = () => {
-  const { currentUser } = useAppShellData();
+  const { contextData } = useAppShellData();
 
-  if (currentUser?.role !== "admin") {
+  if (contextData.currentUser?.role !== "admin") {
     return <Navigate to="/dashboard" replace />;
   }
 
@@ -207,6 +207,44 @@ defineResource({
 // Breadcrumb shows: "Orders > Order #12345"
 ```
 
+### Localized Breadcrumb Titles
+
+Pass `labels.t(key)` directly to `meta.breadcrumbTitle`, just like `meta.title`.
+AppShell recognizes these translation functions and resolves them using the current locale.
+For labels that depend on the URL segment, return a `LocalizedString` from a segment callback:
+
+```tsx
+import { defineI18nLabels, defineResource } from "@tailor-platform/app-shell";
+
+const labels = defineI18nLabels({
+  en: {
+    orders: "All Orders",
+    order: ({ id }: { id: string }) => `Order #${id}`,
+  },
+  ja: {
+    orders: "すべての注文",
+    order: ({ id }: { id: string }) => `注文 #${id}`,
+  },
+});
+
+const ordersResource = defineResource({
+  path: "orders",
+  meta: { breadcrumbTitle: labels.t("orders") },
+  subResources: [
+    defineResource({
+      path: ":id",
+      meta: { breadcrumbTitle: (segment) => labels.t("order", { id: segment }) },
+    }),
+  ],
+});
+```
+
+The same pattern works for `defineModule` and file-based `appShellPageProps.meta`.
+Other callbacks still receive the URL segment. The existing `() => labels.t(key)` form remains supported.
+Handwritten locale functions must be returned from an outer callback, for example `breadcrumbTitle: () => (locale) => locale === "ja" ? "注文" : "Orders"`.
+If navigation and breadcrumbs share a label, omit `breadcrumbTitle` and use `title: labels.t(key)` instead.
+Existing strings and `(segment) => string` callbacks remain supported; no `as string` cast is needed.
+
 ### Dynamic Breadcrumb Titles
 
 Use the `useOverrideBreadcrumb` hook to replace a breadcrumb segment with a data-driven value from within the rendered page component:

package/skills/app-shell-patterns/references/concepts/sidebar-navigation.md

@@ -182,6 +182,38 @@ const labels = defineI18nLabels({
 
 ---
 
+### SidebarSection
+
+A static heading for a run of flat navigation items. Unlike `SidebarGroup`, a section is neither collapsible nor navigable, and its items keep top-level styling. In the icon rail the heading is hidden.
+
+#### Props
+
+| Prop       | Type              | Required | Description                       |
+| ---------- | ----------------- | -------- | --------------------------------- |
+| `title`    | `LocalizedString` | Yes      | Section heading (supports i18n)   |
+| `children` | `ReactNode`       | Yes      | Child items (usually SidebarItem) |
+
+#### Example
+
+```tsx
+<DefaultSidebar>
+  <SidebarItem to="/overview" />
+  <SidebarSeparator />
+  <SidebarSection title="Services">
+    <SidebarItem to="/ai-gateways" />
+    <SidebarItem to="/applications" />
+  </SidebarSection>
+  <SidebarSeparator />
+  <SidebarSection title="Logs">
+    <SidebarItem to="/activity-logs" />
+  </SidebarSection>
+</DefaultSidebar>
+```
+
+Use `SidebarGroup` when users should be able to collapse the items or when they belong under a parent page; use `SidebarSection` when you only need a label above items that stay visible.
+
+---
+
 ### SidebarSeparator
 
 A visual divider between sidebar sections.