@tailor-platform/app-shell 1.6.1 → 1.8.0

package/dist/theme.bridge.css

@@ -0,0 +1,58 @@
+@custom-variant dark (&:where(.dark, .dark *));
+
+/**
+ * Tailwind v4 theme bridge — maps raw CSS custom properties to Tailwind's
+ * design token namespace so utilities like `bg-background`, `text-primary`,
+ * `shadow-sm` resolve correctly regardless of the active palette.
+ */
+@theme inline {
+  --font-sans: "Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif;
+
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+
+  --color-status-default: var(--status-default);
+  --color-status-neutral: var(--status-neutral);
+  --color-status-completed: var(--status-completed);
+  --color-status-attention: var(--status-attention);
+  --color-status-danger: var(--status-danger);
+
+  --shadow-xs: var(--semantic-shadow-xs);
+  --shadow-sm: var(--semantic-shadow-sm);
+  --shadow-md: var(--semantic-shadow-md);
+  --shadow-lg: var(--semantic-shadow-lg);
+}

package/dist/theme.css

@@ -22,62 +22,4 @@
  * Palette selection is by CSS import; there is no runtime palette prop.
  */
 @import "./themes/default.css" layer(theme.defaults);
-
-@custom-variant dark (&:where(.dark, .dark *));
-
-/**
- * Tailwind v4 theme bridge — maps raw CSS custom properties to Tailwind's
- * design token namespace so utilities like `bg-background`, `text-primary`,
- * `shadow-sm` resolve correctly regardless of the active palette.
- */
-@theme inline {
-  --font-sans: "Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif;
-
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-destructive-foreground: var(--destructive-foreground);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
-  --color-chart-1: var(--chart-1);
-  --color-chart-2: var(--chart-2);
-  --color-chart-3: var(--chart-3);
-  --color-chart-4: var(--chart-4);
-  --color-chart-5: var(--chart-5);
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-  --color-sidebar: var(--sidebar);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-ring: var(--sidebar-ring);
-
-  --color-status-default: var(--status-default);
-  --color-status-neutral: var(--status-neutral);
-  --color-status-completed: var(--status-completed);
-  --color-status-attention: var(--status-attention);
-  --color-status-danger: var(--status-danger);
-
-  --shadow-xs: var(--semantic-shadow-xs);
-  --shadow-sm: var(--semantic-shadow-sm);
-  --shadow-md: var(--semantic-shadow-md);
-  --shadow-lg: var(--semantic-shadow-lg);
-}
+@import "./theme.bridge.css";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.6.1",
+  "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