@tailor-platform/app-shell 1.11.0 → 1.12.0

package/dist/theme-bridge.test.ts

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * The bridge is what makes semantic tokens reachable as Tailwind utilities in
+ * consumer apps (`bg-alert-info-background`). Nothing else in the suite covers
+ * it: component snapshots record *class names*, not resolved CSS, so dropping a
+ * bridge entry would leave every other test green while the utility silently
+ * stops producing colour.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const bridge = readFileSync(join(here, "theme.bridge.css"), "utf8");
+const defaultTheme = readFileSync(join(here, "themes/default.css"), "utf8");
+
+/** Token names defined in the default palette for a given prefix, e.g. `alert`. */
+function definedTokens(prefix: string): string[] {
+  const matches = defaultTheme.matchAll(new RegExp(`^\\s*--(${prefix}-[a-z-]+):`, "gm"));
+  return [...new Set([...matches].map((m) => m[1]))].toSorted();
+}
+
+/** Token names bridged as `--color-<name>`, mapped to the var() they resolve to. */
+function bridgedTokens(prefix: string): Map<string, string> {
+  const matches = bridge.matchAll(
+    new RegExp(`^\\s*--color-(${prefix}-[a-z-]+):\\s*var\\(--([a-z-]+)\\);`, "gm"),
+  );
+  return new Map([...matches].map((m) => [m[1], m[2]]));
+}
+
+describe("theme bridge", () => {
+  describe.each(["alert", "status"])("--%s-* tokens", (prefix) => {
+    const defined = definedTokens(prefix);
+    const bridged = bridgedTokens(prefix);
+
+    it("defines at least one token in the default palette", () => {
+      expect(defined.length).toBeGreaterThan(0);
+    });
+
+    it("bridges every token defined in the default palette", () => {
+      expect([...bridged.keys()].toSorted()).toEqual(defined);
+    });
+
+    it("maps each bridged token to its own source variable", () => {
+      // Guards against cross-wiring, e.g. --color-alert-info-foreground
+      // accidentally resolving to var(--alert-info-foreground-muted).
+      for (const [name, target] of bridged) {
+        expect(target).toBe(name);
+      }
+    });
+  });
+
+  it("bridges all 20 alert slots", () => {
+    // 5 variants x 4 slots. Pinned so that dropping a whole variant — which
+    // would still satisfy the symmetry checks above if it were removed from
+    // both files — fails loudly.
+    expect(bridgedTokens("alert").size).toBe(20);
+  });
+});

package/dist/theme.bridge.css

@@ -51,6 +51,27 @@
   --color-status-attention: var(--status-attention);
   --color-status-danger: var(--status-danger);
 
+  --color-alert-neutral-background: var(--alert-neutral-background);
+  --color-alert-neutral-foreground: var(--alert-neutral-foreground);
+  --color-alert-neutral-foreground-muted: var(--alert-neutral-foreground-muted);
+  --color-alert-neutral-border: var(--alert-neutral-border);
+  --color-alert-success-background: var(--alert-success-background);
+  --color-alert-success-foreground: var(--alert-success-foreground);
+  --color-alert-success-foreground-muted: var(--alert-success-foreground-muted);
+  --color-alert-success-border: var(--alert-success-border);
+  --color-alert-warning-background: var(--alert-warning-background);
+  --color-alert-warning-foreground: var(--alert-warning-foreground);
+  --color-alert-warning-foreground-muted: var(--alert-warning-foreground-muted);
+  --color-alert-warning-border: var(--alert-warning-border);
+  --color-alert-error-background: var(--alert-error-background);
+  --color-alert-error-foreground: var(--alert-error-foreground);
+  --color-alert-error-foreground-muted: var(--alert-error-foreground-muted);
+  --color-alert-error-border: var(--alert-error-border);
+  --color-alert-info-background: var(--alert-info-background);
+  --color-alert-info-foreground: var(--alert-info-foreground);
+  --color-alert-info-foreground-muted: var(--alert-info-foreground-muted);
+  --color-alert-info-border: var(--alert-info-border);
+
   --shadow-xs: var(--semantic-shadow-xs);
   --shadow-sm: var(--semantic-shadow-sm);
   --shadow-md: var(--semantic-shadow-md);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@base-ui/react": "^1.6.0",
+    "@base-ui/react": "1.6.0",
     "@internationalized/date": "3.12.2",
     "@standard-schema/spec": "^1.1.0",
     "@tailor-platform/auth-public-client": "^0.5.1",
@@ -61,26 +61,26 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",
-    "@testing-library/react": "^16.3.2",
-    "@testing-library/user-event": "^14.6.3",
+    "@testing-library/react": "16.3.2",
+    "@testing-library/user-event": "14.6.3",
     "@types/encoding-japanese": "^2.2.1",
     "@types/node": "^25.9.5",
     "@types/papaparse": "^5.5.2",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "@vitejs/plugin-react": "^5.2.0",
-    "happy-dom": "^20.9.0",
-    "postcss": "^8.5.26",
+    "happy-dom": "20.9.0",
+    "postcss": "8.5.26",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "tailwindcss": "^4.2.4",
     "tw-animate-css": "^1.4.0",
-    "typescript": "^5.9.3",
+    "typescript": "5.9.3",
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.5.0",
     "vite-plugin-externalize-deps": "^0.10.0",
     "vite-tsconfig-paths": "^6.1.1",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "react": ">=19.2.7",

package/skills/app-shell-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: app-shell-patterns
-description: "Best-practice UI patterns and correct component usage for building pages in apps that use @tailor-platform/app-shell. Use when: building or editing any screen, page, list, table, detail view, form, modal, dialog, wizard, or bulk/confirm/toast interaction in an app with @tailor-platform/app-shell installed — or when choosing the right AppShell component, layout, or design token for a UI."
+description: "Best-practice UI patterns and correct component usage for building pages in apps that use @tailor-platform/app-shell. Use when: building or editing any screen, page, list, table, detail view, form, modal, dialog, wizard, or bulk/confirm/toast interaction in an app with @tailor-platform/app-shell installed — when choosing the right AppShell component, layout, or design token for a UI — or when upgrading @tailor-platform/app-shell, or diagnosing styling, theming, or dark-mode breakage that appeared after a version bump."
 ---
 
 # App-Shell Patterns
@@ -19,6 +19,12 @@ These are the foundational rules that underpin all patterns. All patterns build
 | [design-system.md](references/fundamental/design-system.md) | design-system reference |
 | [graphql.md](references/fundamental/graphql.md)             | graphql reference       |
 
+## Migrations
+
+[`migrations.md`](references/migrations.md) lists every change that requires editing the consuming app, newest first — what breaks, how to detect it, and what to change.
+
+Read it when upgrading `@tailor-platform/app-shell`, and whenever styling, theming, or dark mode looks wrong after a version bump. These breakages are silent: the build succeeds and nothing warns, so the cause is not discoverable from the error output. The package ships no CHANGELOG, so this file is the only migration record available locally.
+
 ## Available Patterns
 
 ### detail

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

@@ -250,7 +250,7 @@ import { Button, Link } from '@tailor-platform/app-shell';
 
 **Used in patterns:** `list/*` (filter sheet variant).
 
-**Notes:** Size the panel with **`contentClassName`** (often `astw:*` utilities). Rules → **`design-system.md`** §5.
+**Notes:** Size the panel with `Sheet.Content`'s **`size`** prop (`"sm" | "md" | "lg" | "xl" | "full"`, default `"sm"`) — not a width utility. `astw:` rules → **`design-system.md`** §5.
 
 ### `Menu`
 
@@ -378,7 +378,7 @@ Plus `badgeVariants` CVA for custom-styled siblings.
 
 **Notes:**
 
-- **Inside a card?** Pass `containerClassName="astw:px-6"` on `Table.Root` for the horizontal inset, and either drop `Card.Content` (bare list form) or pass `Card.Content className="astw:px-0"` (header+content form). Skipping the `containerClassName` lands the first column flush against the card edge. See the `Card` entry for the two canonical forms and a DON'T example. Dense cell typography (**`text-body-sm`**, **`text-mono`**) → **`design-system.md`** §4 Typography.
+- **Inside a card?** Pass `containerClassName="astw:px-6"` on `Table.Root` for the horizontal inset, and either drop `Card.Content` (bare list form) or pass `Card.Content className="astw:px-0"` (header+content form). Skipping the `containerClassName` lands the first column flush against the card edge. See the `Card` entry for the two canonical forms and a DON'T example. Dense cell typography (**`text-sm`**, **`tabular-nums`** for figures, **`font-mono`** for identifiers) → **`design-system.md`** §4 Typography.
 - **Whole row is clickable.** Use `<Table.Row onClick={() => navigate(detailPath)} className="astw:cursor-pointer">`. For keyboard and screen-reader users, also wrap the primary identifier cell content in `<Link>` (so the row is reachable via Tab; `Table.Row` is a `<tr>` and cannot itself be a Link — wrapping a `<tr>` in `<a>` is invalid HTML). **No per-row "View" / "Open" / "→" buttons.** Per-row `Menu` (overflow `…`) is the only allowed per-row action surface and is reserved for non-navigation actions like Archive, Duplicate.
 
 ### `DataTable`
@@ -387,7 +387,7 @@ Plus `badgeVariants` CVA for custom-styled siblings.
 
 **Import:** compound namespace + helpers from `'@tailor-platform/app-shell'`, e.g. `DataTable`, `useDataTable`, `useCollectionVariables`, `createColumnHelper`, and types such as `Column`, `UseDataTableReturn`.
 
-**Purpose:** Production list screens over GraphQL **connections**. Owns toolbar filter chips (**`DataTable.Filters`** from column `filter` configs), header sort, **`DataTable.Pagination`** (cursor-first; First/Last when `total` is provided), loading skeleton/error row, **`onClickRow`**, **`rowActions`** (kebab column), **`onSelectionChange`** (checkbox column), **column pinning** (`pin: "left" | "right"`) and built-in **column settings** (`<DataTable.Toolbar columnSettings>` — user show/hide + reorder + pin, persisted per-user via **`tableId`**).
+**Purpose:** Production list screens over GraphQL **connections**. Owns toolbar filter chips (**`DataTable.Filters`** from column `filter` configs), header sort, **`DataTable.Pagination`** (cursor-first; First/Last when `total` is provided), loading skeleton/error row, **`onClickRow`**, **`rowActions`** (kebab column), **`onSelectionChange`** (checkbox column), **expandable rows** (**`rowExpansion`** — a chevron column plus a full-width detail panel per row; `render` with optional `canExpand` / `getLabel`, and `expandedIds` + `onChange` for controlled mode), **column pinning** (`pin: "left" | "right"`) and built-in **column settings** (`<DataTable.Toolbar columnSettings>` — user show/hide + reorder + pin, persisted per-user via **`tableId`**).
 
 **Primitives:** Builds on low-level **`Table`**; do not reinvent pagination/filters manually unless the dataset is trivial.