@tailor-platform/app-shell 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -44,6 +44,7 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.5.0",
+    "@internationalized/date": "3.12.2",
     "@standard-schema/spec": "^1.1.0",
     "@tailor-platform/auth-public-client": "^0.5.0",
     "change-case": "^5.4.4",
@@ -51,6 +52,7 @@
     "clsx": "^2.1.1",
     "encoding-japanese": "^2.2.0",
     "lucide-react": "^1.8.0",
+    "openai": "6.45.0",
     "papaparse": "^5.5.3",
     "react-router": "^7.14.1",
     "sonner": "^2.0.7",

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

@@ -47,7 +47,9 @@ For the full upstream API of any component, follow the link to the published ref
 
 **Import:** `import { Layout } from '@tailor-platform/app-shell'`
 **Purpose:** Standard page container with header + 1–N column body. The most-used component — every page wraps content in `<Layout>`.
-**API:** `Layout` (root) + `Layout.Column` + `Layout.Header`. `LayoutProps`: `columns` (number, default auto-detected from children), `gap`, `title`, `actions`, `className`, `style`.
+**API:** `Layout` (root) + `Layout.Column` + `Layout.Header`. `LayoutProps`: `fill` (boolean), `columns` (number, default auto-detected from children), `gap`, `title`, `actions`, `className`, `style`.
+
+**`fill`** — stretches the layout to the available height and bounds the column row so children can scroll internally instead of growing the page. Use on table-first pages (`<Layout fill>` + `DataTable`): the title, table toolbar, sticky column headers, and pagination footer stay pinned while only the rows scroll — see **`patterns/list-dense-scan.md`**. Omit on pages that should flow and scroll naturally (forms, dashboards).
 
 **Column-count → width rules** (column count is auto-detected from `Layout.Column` children):
 
@@ -111,15 +113,29 @@ import { Button, Layout, Tabs } from "@tailor-platform/app-shell";
 
 **Import:** `import { SidebarLayout } from '@tailor-platform/app-shell'`
 **Purpose:** Top-level layout that mounts the sidebar and renders the page outlet.
-**API:** `SidebarLayoutProps` — sidebar config, header config, content slot. Used in `App.tsx`.
+**API:** `SidebarLayoutProps` — `sidebar`, `header`, and `children` are full-region slots (each defaults to a built-in). `sidebar` defaults to `SidebarLayout.DefaultSidebar`; `header` defaults to `SidebarLayout.DefaultHeader`. Used in `App.tsx`.
 **Used in patterns:** consumed by AppShell init, not directly by page patterns. See `project-setup.md`.
 
-### `DefaultSidebar`, `SidebarGroup`, `SidebarItem`, `SidebarSeparator`
+### `SidebarLayout.DefaultHeader` (`DefaultHeader`)
+
+**Import:** `import { SidebarLayout } from '@tailor-platform/app-shell'` → `SidebarLayout.DefaultHeader` (also top-level `DefaultHeader`)
+**Purpose:** The built-in top bar (trigger + breadcrumb, plus an `actions` cluster). Drop into `SidebarLayout`'s `header` slot to extend the header without rebuilding it.
+**API:** `actions?: ReactNode | ReactNode[]` — the right-hand cluster (opinionated flex row). **Defaults to `[<AppearanceSwitcher />]`, and passing `actions` REPLACES the switcher** — include `<AppearanceSwitcher />` in the array to keep it. `actions={[]}` = empty right side.
+**Used in patterns:** project-level header customization (notification bell, user menu). See `project-setup.md`.
+
+### `SidebarLayout.DefaultSidebar` (`DefaultSidebar`), `SidebarGroup`, `SidebarItem`, `SidebarSeparator`
 
-**Import:** `import { DefaultSidebar, SidebarGroup, SidebarItem, SidebarSeparator } from '@tailor-platform/app-shell'`
+**Import:** `import { SidebarLayout, SidebarGroup, SidebarItem, SidebarSeparator } from '@tailor-platform/app-shell'` → `SidebarLayout.DefaultSidebar` (also top-level `DefaultSidebar`)
 **Purpose:** Sidebar composition. `DefaultSidebar` auto-resolves nav items from `appShellPageProps.meta` on each page; the others let you customize manually.
 **Used in patterns:** sidebar is a project-level concern. See `project-setup.md`.
 
+### `AppearanceSwitcher`
+
+**Import:** `import { AppearanceSwitcher } from '@tailor-platform/app-shell'`
+**Purpose:** Palette-icon dropdown for Light/Dark/System color mode. The default `SidebarLayout.DefaultHeader` action; also usable standalone (e.g. a sidebar footer). Include it in `DefaultHeader`'s `actions` array when customizing the header to keep it visible.
+**API:** No props — reads/writes theme via `useTheme`.
+**Used in patterns:** project-level. See `project-setup.md`.
+
 ### `CommandPalette`
 
 **Import:** `import { CommandPalette } from '@tailor-platform/app-shell'`

package/skills/app-shell-patterns/references/patterns/list-dense-scan.md

@@ -78,7 +78,7 @@ export const columns: Column<Order>[] = [
 
 ```tsx
 /* pattern: list/dense-scan */
-import { DataTable, useDataTable, Button, Input } from "@tailor-platform/app-shell";
+import { DataTable, Layout, useDataTable, Button, Input } from "@tailor-platform/app-shell";
 import type { Order } from "./columns";
 import { columns } from "./columns";
 import type { DataTableData } from "@tailor-platform/app-shell";
@@ -92,19 +92,46 @@ export default function DenseScanList({ data, onCreateClick }: Props) {
   const table = useDataTable({ data, columns });
 
   return (
-    <div className="space-y-4">
-      <div className="flex items-center justify-between">
-        <Input placeholder="Search orders..." className="max-w-sm" />
-        <Button onClick={onCreateClick}>Create Order</Button>
-      </div>
-      <DataTable.Root value={table}>
-        <DataTable.Table />
-      </DataTable.Root>
-    </div>
+    // `fill` pins the page chrome for table-first pages: the title, toolbar,
+    // column header row, and pagination footer stay visible at every viewport
+    // height — only the table's rows region scrolls. Omit `fill` on pages
+    // that should flow and scroll naturally (forms, dashboards, articles).
+    <Layout fill>
+      <Layout.Header
+        title="Orders"
+        actions={[
+          <Button key="create" onClick={onCreateClick}>
+            Create Order
+          </Button>,
+        ]}
+      />
+      <Layout.Column>
+        <DataTable.Root value={table}>
+          <DataTable.Toolbar>
+            <Input placeholder="Search orders..." className="max-w-sm" />
+          </DataTable.Toolbar>
+          <DataTable.Table />
+          <DataTable.Footer>
+            <DataTable.Pagination />
+          </DataTable.Footer>
+        </DataTable.Root>
+      </Layout.Column>
+    </Layout>
   );
 }
 ```
 
+## Page Layout & Internal Scrolling
+
+Table-first pages should pin their chrome and scroll only the rows region. Wrap the page in `<Layout fill>`:
+
+- `fill` stretches the layout to the available height and bounds the column row, so the `DataTable` shrinks to fit instead of growing past the viewport
+- The `Layout.Header` (title/actions), `DataTable.Toolbar`, the column header row (sticky), and `DataTable.Footer` (pagination) stay visible at every viewport height — only the rows scroll vertically
+- When the current page of rows fits, nothing stretches and no scrollbar appears — short tables render identically with or without `fill`
+- Requires no extra styling on the page: the height chain (`AppShell` content area → `Layout fill` → `Layout.Column` → `DataTable.Root`) is wired by the components
+
+Omit `fill` on pages that should flow and scroll naturally (forms, dashboards, articles) — the AppShell content area scrolls those.
+
 ## Variants
 
 - **Toolbar chips only (`DataTable.Filters`)** — best when filters map cleanly to typed column metadata / enum facets
@@ -117,6 +144,7 @@ export default function DenseScanList({ data, onCreateClick }: Props) {
 
 - Column count: 4-8 recommended
 - Must include pagination — never render unbounded lists
+- Table-first pages use `<Layout fill>` so title/toolbar/header/footer stay pinned and only rows scroll
 - Status Badge colors must use design system tokens (variant prop)
 - Bulk actions toolbar appears only when ≥1 row is selected
 - Whole row is clickable via `onClickRow`; no per-row "View" / "Open" buttons
@@ -125,6 +153,7 @@ export default function DenseScanList({ data, onCreateClick }: Props) {
 ## Anti-patterns
 
 - Building a bespoke table + custom pagination instead of `DataTable` + `useCollectionVariables`
+- Hand-rolled `max-height`/`overflow` wrappers around `DataTable` to contain scrolling — use `<Layout fill>` instead
 - Tabs that mutate only local UI state while pagination/filters assume the full server set
 - Using `<table>` directly instead of `<DataTable>` for live collections
 - Client-side filtering on 1000+ records without server-side support