@tristan2828/ui-foundation 3.0.0 → 3.1.1

package/README.md

@@ -1,5 +1,8 @@
 # @tristan2828/ui-foundation
 
+[![npm](https://img.shields.io/npm/v/@tristan2828/ui-foundation)](https://www.npmjs.com/package/@tristan2828/ui-foundation)
+[![release](https://github.com/Tristan2828/ui-foundation/actions/workflows/release.yml/badge.svg)](https://github.com/Tristan2828/ui-foundation/actions/workflows/release.yml)
+
 The shared layer of a family of small, contract-first, database-backed React
 apps: shadcn primitives, the `DataTable`/`EntityForm` composites, an app
 shell with session-cookie auth, the gateway's error seam, design tokens,
@@ -18,7 +21,7 @@ than installing this by hand:
 | `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityForm`, `ErrorState`, `MultiChoice`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
 | `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
-| `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `resetMockAuth`, `exposeMswForE2E` |
+| `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |
 | `@tristan2828/ui-foundation/testing` | Playwright: `defineA11ySuite`, `defineMockModeBannerSuite`, `forceMswOverride`, `forceLoggedOut`, `waitForMswReady` |
 | `@tristan2828/ui-foundation/eslint` | the lint rules, as a flat config: `export default [...uiFoundation()]` |
 | `@tristan2828/ui-foundation/styles.css` | tokens and base styles, after `@import "tailwindcss";` |
@@ -34,7 +37,8 @@ Run from an app's root:
   `sync --check` (in `verify`) fails when they differ from the installed
   version.
 - `ui-foundation check-contract [openapi.yaml]` fails unless the app's spec
-  contains the foundation's part unchanged.
+  contains the foundation's part unchanged. A path marked `x-optional` may
+  be left out, and so may the components only such a path uses.
 - `ui-foundation check-deps` fails if `package.json` names a dependency
   missing from `deps-allowlist.json`.
 

package/bin/ui-foundation.mjs

@@ -160,6 +160,42 @@ function normalise(value) {
 
 const same = (a, b) => JSON.stringify(normalise(a)) === JSON.stringify(normalise(b))
 
+// Every component a value reaches through $refs, following refs inside the
+// components themselves, as 'section/name' keys.
+function reachableComponents(roots, components) {
+  const found = new Set()
+  const walk = (value) => {
+    if (Array.isArray(value)) return value.forEach(walk)
+    if (!value || typeof value !== 'object') return
+    for (const [key, child] of Object.entries(value)) {
+      const match = key === '$ref' && typeof child === 'string' && child.match(/^#\/components\/([^/]+)\/([^/]+)/)
+      if (match) {
+        const id = `${match[1]}/${match[2]}`
+        if (!found.has(id)) {
+          found.add(id)
+          walk(components[match[1]]?.[match[2]])
+        }
+      } else {
+        walk(child)
+      }
+    }
+  }
+  roots.forEach(walk)
+  return found
+}
+
+// Components reachable from optional paths the app leaves out, and from no
+// path it must (or does) have.
+function optionalOnlyComponents(foundation, appHasPath) {
+  const required = []
+  const omitted = []
+  for (const [route, item] of Object.entries(foundation.paths)) {
+    ;(item['x-optional'] && !appHasPath(route) ? omitted : required).push(item)
+  }
+  const requiredIds = reachableComponents(required, foundation.components)
+  return new Set([...reachableComponents(omitted, foundation.components)].filter((id) => !requiredIds.has(id)))
+}
+
 function checkContract(specPath) {
   const target = path.resolve(APP_ROOT, specPath)
   if (!existsSync(target)) fail(`check-contract: no ${specPath} here`)
@@ -175,11 +211,18 @@ function checkContract(specPath) {
       problems.push(`path ${route} differs`)
     }
   }
+  // A component only an omitted optional path uses may be left out with it
+  // (RegisterRequest, when there's no /auth/register). Computed from the
+  // refs, so a future optional path can't forget to mark its schemas.
+  const optionalOnly = optionalOnlyComponents(foundation, (route) => app.paths?.[route] !== undefined)
   for (const [section, entries] of Object.entries(foundation.components)) {
     for (const [name, entry] of Object.entries(entries)) {
       const appEntry = app.components?.[section]?.[name]
-      if (appEntry === undefined) problems.push(`missing components.${section}.${name}`)
-      else if (!same(appEntry, entry)) problems.push(`components.${section}.${name} differs`)
+      if (appEntry === undefined) {
+        if (!optionalOnly.has(`${section}/${name}`)) problems.push(`missing components.${section}.${name}`)
+      } else if (!same(appEntry, entry)) {
+        problems.push(`components.${section}.${name} differs`)
+      }
     }
   }
 

package/dist/components/ui/sidebar.js

@@ -132,7 +132,7 @@ function SidebarGroupLabel({ className, render, ...props }) {
     return useRender({
         defaultTagName: "div",
         props: mergeProps({
-            className: cn("flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium text-sidebar-foreground/70 ring-sidebar-ring outline-hidden transition-[margin,opacity] duration-200 ease-linear group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0", className),
+            className: cn("flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium text-sidebar-foreground/70 ring-sidebar-ring outline-hidden transition-[margin,opacity] duration-200 ease-linear group-data-[collapsible=icon]:pointer-events-none group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0", className),
         }, props),
         render,
         state: {

package/dist/mocks/auth.d.ts

@@ -4,6 +4,13 @@ export declare const MOCK_USER: User;
 export declare const MOCK_PASSWORD = "dev-password-123";
 export declare function isMockAuthenticated(): boolean;
 export declare function setMockAuthenticated(value: boolean): void;
+/**
+ * The user the mock session is signed in as, or null when signed out — the
+ * same answer GET /auth/me gives. For an app's own handlers that act as the
+ * signed-in user (per-user rows): after a mock registration this is the new
+ * user, not MOCK_USER. On null, answer 401 as /auth/me does.
+ */
+export declare function getMockCurrentUser(): User | null;
 export declare function resetMockAuth(): void;
 export declare const authHandlers: import("msw").HttpHandler[];
 export {};

package/dist/mocks/auth.js

@@ -22,6 +22,15 @@ export function isMockAuthenticated() {
 export function setMockAuthenticated(value) {
     authenticated = value;
 }
+/**
+ * The user the mock session is signed in as, or null when signed out — the
+ * same answer GET /auth/me gives. For an app's own handlers that act as the
+ * signed-in user (per-user rows): after a mock registration this is the new
+ * user, not MOCK_USER. On null, answer 401 as /auth/me does.
+ */
+export function getMockCurrentUser() {
+    return authenticated ? currentUser : null;
+}
 export function resetMockAuth() {
     authenticated = true;
     registeredUsers = new Map([[MOCK_USER.email, MOCK_USER]]);

package/dist/mocks/index.d.ts

@@ -1,3 +1,3 @@
-export { authHandlers, isMockAuthenticated, MOCK_PASSWORD, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
+export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
 export { exposeMswForE2E } from './e2e-hooks.js';
 export type { MswHandle, MswOverride } from './override.js';

package/dist/mocks/index.js

@@ -1,5 +1,5 @@
 // `@tristan2828/ui-foundation/mocks` — MSW support. A separate entry point
 // so msw (an optional peer dependency) never reaches an app's main bundle
 // unless it imports this.
-export { authHandlers, isMockAuthenticated, MOCK_PASSWORD, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
+export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
 export { exposeMswForE2E } from './e2e-hooks.js';

package/dist/testing/index.d.ts

@@ -30,11 +30,23 @@ export type A11ySuiteOptions = {
  * emulateMedia switches it.
  */
 export declare function defineA11ySuite({ formRoutes, loggedOutRoutes }: A11ySuiteOptions): void;
+export type MockModeBannerSuiteOptions = {
+    /** Screens to check, logged-out ones included (e.g. '/login'). */
+    routes: readonly string[];
+    /**
+     * Whether this run's app is MSW-backed. Defaults to
+     * `process.env.VITE_API !== 'real'`, the same switch the app is built with.
+     * When false (a run against the real backend) the banner must be absent.
+     */
+    mockMode?: boolean;
+};
 /**
  * Mock mode is announced on every route, logged-out ones included — /login
  * is where a mock session passing for a real one first cost someone time.
  * The default Playwright run is MSW-backed, so the banner must be there.
+ *
+ * Against the real backend (`VITE_API=real`) it asserts the opposite: no
+ * banner on any route. That half catches a mock bundle shipped as if it
+ * were production, which is what the banner exists for.
  */
-export declare function defineMockModeBannerSuite({ routes }: {
-    routes: readonly string[];
-}): void;
+export declare function defineMockModeBannerSuite({ routes, mockMode, }: MockModeBannerSuiteOptions): void;

package/dist/testing/index.js

@@ -3,6 +3,12 @@
 // calls a suite with its own routes, instead of carrying a copy of the spec
 // to edit (each of these was forked by the first real app for exactly that).
 //
+// Call a suite inside the spec file's own `test.describe(...)`. Playwright
+// locates a test where test() is called, which for a suite is this package;
+// a file argument (`playwright test e2e/a11y.spec.ts`) keeps a test only if
+// it or an enclosing describe is located in that file. Without the app's
+// own describe, selecting the spec by file runs nothing.
+//
 // Runs in Node, inside Playwright: @playwright/test and @axe-core/playwright
 // are optional peer dependencies, needed only by apps that import this.
 import AxeBuilder from '@axe-core/playwright';
@@ -91,13 +97,33 @@ export function defineA11ySuite({ formRoutes, loggedOutRoutes }) {
  * Mock mode is announced on every route, logged-out ones included — /login
  * is where a mock session passing for a real one first cost someone time.
  * The default Playwright run is MSW-backed, so the banner must be there.
+ *
+ * Against the real backend (`VITE_API=real`) it asserts the opposite: no
+ * banner on any route. That half catches a mock bundle shipped as if it
+ * were production, which is what the banner exists for.
  */
-export function defineMockModeBannerSuite({ routes }) {
-    test('mock mode is announced on every route, including logged-out ones', async ({ page }) => {
+export function defineMockModeBannerSuite({ routes, mockMode = process.env.VITE_API !== 'real', }) {
+    if (mockMode) {
+        test('mock mode is announced on every route, including logged-out ones', async ({ page }) => {
+            const banner = page.getByRole('status').filter({ hasText: 'Mock data' });
+            for (const route of routes) {
+                await page.goto(route);
+                await test.step(route, () => expect(banner).toBeVisible());
+            }
+        });
+        return;
+    }
+    test('no mock-mode banner on any route against the real backend', async ({ page }) => {
         const banner = page.getByRole('status').filter({ hasText: 'Mock data' });
         for (const route of routes) {
             await page.goto(route);
-            await test.step(route, () => expect(banner).toBeVisible());
+            await test.step(route, async () => {
+                // The banner renders beside the router, so once a screen's <main>
+                // is on the page the banner would be too. Without this wait a
+                // blank page would pass the count check trivially.
+                await expect(page.getByRole('main')).toBeVisible();
+                await expect(banner).toHaveCount(0);
+            });
         }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {
@@ -91,17 +91,39 @@
     "zod": "^4.6.5"
   },
   "peerDependenciesMeta": {
-    "@axe-core/playwright": { "optional": true },
-    "@eslint/js": { "optional": true },
-    "@playwright/test": { "optional": true },
-    "@tanstack/eslint-plugin-query": { "optional": true },
-    "eslint": { "optional": true },
-    "eslint-plugin-check-file": { "optional": true },
-    "eslint-plugin-react-hooks": { "optional": true },
-    "eslint-plugin-react-refresh": { "optional": true },
-    "globals": { "optional": true },
-    "msw": { "optional": true },
-    "typescript-eslint": { "optional": true }
+    "@axe-core/playwright": {
+      "optional": true
+    },
+    "@eslint/js": {
+      "optional": true
+    },
+    "@playwright/test": {
+      "optional": true
+    },
+    "@tanstack/eslint-plugin-query": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    },
+    "eslint-plugin-check-file": {
+      "optional": true
+    },
+    "eslint-plugin-react-hooks": {
+      "optional": true
+    },
+    "eslint-plugin-react-refresh": {
+      "optional": true
+    },
+    "globals": {
+      "optional": true
+    },
+    "msw": {
+      "optional": true
+    },
+    "typescript-eslint": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@fontsource-variable/geist": "^5.3.0",