@tristan2828/ui-foundation 3.0.0

package/dist/testing/index.js

@@ -0,0 +1,103 @@
+// `@tristan2828/ui-foundation/testing` — Playwright helpers and suites for
+// what every app built on the foundation must keep true. An app's spec file
+// 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).
+//
+// 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';
+import { expect, test } from '@playwright/test';
+/**
+ * Forces a response for the page's *first* load: set before navigation, so
+ * it wins the race against the app's own first fetch. For states forced
+ * after load, use `waitForMswReady` and then `window.__msw.worker.use(...)`.
+ */
+export async function forceMswOverride(page, override) {
+    await page.addInitScript((spec) => {
+        window.__E2E_MSW_OVERRIDE__ = spec;
+    }, override);
+}
+/** `window.__msw` is set only once the app's mocking has started — page.goto's load event doesn't wait for it. */
+export async function waitForMswReady(page) {
+    await page.waitForFunction(() => window.__msw !== undefined);
+}
+/** Starts the page logged out: GET /auth/me answers 401 on first load. */
+export function forceLoggedOut(page) {
+    return forceMswOverride(page, {
+        method: 'get',
+        path: '*/api/auth/me',
+        status: 401,
+        body: { detail: 'Not authenticated' },
+    });
+}
+export async function expectNoAxeViolations(page) {
+    const results = await new AxeBuilder({ page }).analyze();
+    expect(results.violations).toEqual([]);
+}
+// The app's own pages, read from the Primary nav. Below the sidebar's
+// mobile breakpoint the nav renders into an off-canvas Sheet *portaled to
+// document.body*, outside the <nav aria-label="Primary"> landmark, so the
+// links are read from the sheet there. Keyed off the `isMobile` fixture,
+// deliberately not a link count: count() doesn't retry, so on a slow first
+// paint it read 0 on desktop too, clicked the trigger (which collapses the
+// desktop sidebar) and then waited for a sheet that never came.
+async function navRoutes(page, isMobile) {
+    await page.goto('/');
+    const nav = isMobile
+        ? (await page.getByRole('button', { name: 'Toggle Sidebar' }).first().click(), page.getByRole('dialog'))
+        : page.getByRole('navigation', { name: 'Primary' });
+    await expect(nav.getByRole('link').first()).toBeVisible();
+    const hrefs = await nav
+        .getByRole('link')
+        .evaluateAll((links) => links.map((link) => link.href));
+    // Only this app's pages: a sidebarExtra group may link to other sites.
+    const origin = new URL(page.url()).origin;
+    return [...new Set(hrefs.filter((href) => new URL(href).origin === origin).map((href) => new URL(href).pathname))];
+}
+/**
+ * Accessibility of the real screens in light and dark mode: every page in
+ * the Primary nav (discovered, so a new entity's table is covered with no
+ * edit), the given form routes, and the logged-out screens. axe's
+ * color-contrast rule against the rendered dark DOM is also what keeps the
+ * dark-mode tokens readable. The theme follows the OS setting, so
+ * emulateMedia switches it.
+ */
+export function defineA11ySuite({ formRoutes, loggedOutRoutes }) {
+    for (const colorScheme of ['light', 'dark']) {
+        test.describe(`accessibility (${colorScheme})`, () => {
+            test.beforeEach(async ({ page }) => {
+                await page.emulateMedia({ colorScheme });
+            });
+            test('every nav page has zero axe violations', async ({ page, isMobile }) => {
+                for (const route of await navRoutes(page, isMobile)) {
+                    await page.goto(route);
+                    await expect(page.locator('html')).toHaveClass(colorScheme);
+                    // Wait for data, not the loading skeleton, so the real UI is checked.
+                    await expect(page.locator('[data-state="loading"]')).toHaveCount(0);
+                    await test.step(route, () => expectNoAxeViolations(page));
+                }
+            });
+            for (const route of [...formRoutes, ...loggedOutRoutes]) {
+                test(`${route} has zero axe violations`, async ({ page }) => {
+                    await page.goto(route);
+                    await expect(page.locator('form')).toBeVisible();
+                    await expectNoAxeViolations(page);
+                });
+            }
+        });
+    }
+}
+/**
+ * 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.
+ */
+export function defineMockModeBannerSuite({ routes }) {
+    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());
+        }
+    });
+}

package/eslint/index.d.ts

@@ -0,0 +1,11 @@
+import type { Linter } from 'eslint'
+
+export declare const PACKAGE_NAME: string
+export declare const PRIMITIVES: string[]
+export declare const TOKEN_SYNTAX_RULES: { selector: string; message: string }[]
+export declare const NO_BARE_FETCH: { selector: string; message: string }
+export declare function baseConfig(): Linter.Config
+export declare function kebabCaseFilenames(files: string[], ignores?: string[]): Linter.Config
+
+/** The lint config for an app built on the foundation. */
+export default function uiFoundation(options?: { ignores?: string[] }): Linter.Config[]

package/eslint/index.js

@@ -0,0 +1,179 @@
+// `@tristan2828/ui-foundation/eslint` — the lint half of the Hard Rules
+// (AGENTS.md), shared so every app enforces the same ones and gets new ones
+// by upgrading the package. An app's whole eslint.config.js:
+//
+//   import uiFoundation from '@tristan2828/ui-foundation/eslint'
+//   export default uiFoundation()
+//
+// Plain JavaScript on purpose: ESLint loads this before any TypeScript
+// tooling runs. The plugins are the app's own devDependencies (optional
+// peer dependencies of the package).
+import { readdirSync } from 'node:fs'
+import js from '@eslint/js'
+import tanstackQuery from '@tanstack/eslint-plugin-query'
+import checkFile from 'eslint-plugin-check-file'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export const PACKAGE_NAME = '@tristan2828/ui-foundation'
+
+// The primitives the package ships, read from what was built (dist/) or,
+// inside this repo before a build, from source. An app importing one of
+// these from its own src/components/ui/ has a second, unpatched copy —
+// usually because `shadcn add` pulled it in as another primitive's
+// dependency.
+function shippedPrimitives() {
+  for (const dir of ['../dist/components/ui', '../src/components/ui']) {
+    try {
+      return readdirSync(new URL(dir, import.meta.url))
+        .filter((file) => /^[a-z0-9-]+\.(js|tsx)$/.test(file) && !file.includes('.stories.'))
+        .map((file) => file.replace(/\.(js|tsx)$/, ''))
+    } catch {
+      // Not there — try the next location.
+    }
+  }
+  return []
+}
+export const PRIMITIVES = shippedPrimitives()
+
+// Raw Tailwind palette classes bypass the semantic token layer — this is
+// what makes "dark mode looks right" a lint error instead of a visual
+// surprise.
+const TAILWIND_PALETTE_CLASS =
+  '/\\b(bg|text|border|ring|fill|stroke)-(red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-\\d{2,3}\\b/'
+const HEX_COLOR = '/#[0-9a-f]{3,8}/i'
+
+export const TOKEN_SYNTAX_RULES = [
+  {
+    selector: `JSXAttribute[name.name='className'] Literal[value=${TAILWIND_PALETTE_CLASS}]`,
+    message:
+      'Use semantic tokens (bg-primary, text-muted-foreground, ...), not raw Tailwind palette classes. See the design-language doc.',
+  },
+  {
+    selector: `JSXAttribute[name.name='style'] Property Literal[value=${HEX_COLOR}]`,
+    message: 'No raw hex colors in style props. Use a semantic token.',
+  },
+]
+
+export const NO_BARE_FETCH = {
+  selector: "CallExpression[callee.name='fetch']",
+  message:
+    'Do not call fetch directly. All server state goes through TanStack Query, which calls src/api/gateway/, which builds on the foundation gateway entry point.',
+}
+
+// The rules every TypeScript file gets, before any boundary rule.
+export function baseConfig() {
+  return {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  }
+}
+
+export function kebabCaseFilenames(files, ignores = []) {
+  return {
+    files,
+    ignores,
+    plugins: { 'check-file': checkFile },
+    rules: {
+      'check-file/filename-naming-convention': [
+        'error',
+        { '**/*.{ts,tsx}': 'KEBAB_CASE' },
+        { ignoreMiddleExtensions: true },
+      ],
+    },
+  }
+}
+
+const GATEWAY_ONLY = {
+  group: [`${PACKAGE_NAME}/gateway`],
+  message:
+    'Only src/api/gateway/ may import the foundation gateway entry point. Components and hooks call a gateway module through TanStack Query.',
+}
+
+const PACKAGE_INTERNALS = {
+  group: [`${PACKAGE_NAME}/dist/*`, `${PACKAGE_NAME}/src/*`],
+  message: `Import from ${PACKAGE_NAME}'s public entry points only. Need something it doesn't export? Raise it for the foundation instead of reaching in.`,
+}
+
+function appImportPatterns({ allowGateway }) {
+  const patterns = [PACKAGE_INTERNALS]
+  if (!allowGateway) patterns.push(GATEWAY_ONLY)
+  if (PRIMITIVES.length > 0) {
+    patterns.push({
+      regex: `^@/components/ui/(${PRIMITIVES.join('|')})$`,
+      message: `The foundation ships this primitive: import it from ${PACKAGE_NAME}/ui/<name> and delete the app's copy (shadcn add re-creates one when another primitive depends on it).`,
+    })
+  }
+  return patterns
+}
+
+/**
+ * The lint config for an app built on the foundation.
+ * @param {{ ignores?: string[] }} [options] extra paths to ignore, on top of build output and generated files
+ */
+export default function uiFoundation(options = {}) {
+  return defineConfig([
+    // .claude/worktrees: a session running in a git worktree nested under
+    // the project root is normal in an agent-built repo; without this, one
+    // session's in-progress files fail another session's verify.
+    globalIgnores([
+      'dist',
+      'storybook-static',
+      'test-results',
+      'playwright-report',
+      'public/mockServiceWorker.js',
+      '.claude/worktrees',
+      'backend',
+      ...(options.ignores ?? []),
+    ]),
+    {
+      ...baseConfig(),
+      rules: {
+        'no-restricted-syntax': ['error', ...TOKEN_SYNTAX_RULES, NO_BARE_FETCH],
+        'no-restricted-imports': ['error', { patterns: appImportPatterns({ allowGateway: false }) }],
+      },
+    },
+    {
+      // App-added shadcn primitives: CLI-installed, and shadcn's convention
+      // exports a component alongside its `*Variants` helper from one file
+      // — a false positive for fast-refresh.
+      files: ['src/components/ui/**/*.{ts,tsx}'],
+      rules: { 'react-refresh/only-export-components': 'off' },
+    },
+    {
+      // The gateway is the one layer allowed onto the network.
+      files: ['src/api/gateway/**/*.{ts,tsx}'],
+      rules: {
+        'no-restricted-imports': ['error', { patterns: appImportPatterns({ allowGateway: true }) }],
+      },
+    },
+    // Kebab-case for everything hand-authored. App.tsx and main.tsx are
+    // Vite's own scaffold names; src/components/ui/ is shadcn's.
+    kebabCaseFilenames(['src/**/*.{ts,tsx}', 'e2e/**/*.ts', 'tests/**/*.ts'], [
+      'src/App.tsx',
+      'src/main.tsx',
+      'src/components/ui/**',
+    ]),
+    {
+      // Tests exercise the HTTP boundary directly (gateway tests stub
+      // fetch, conformance tests call it against MSW, e2e specs call it in
+      // the page) — the no-bare-fetch rule keeps app code on the gateway,
+      // not tests off the primitive they're testing.
+      files: ['tests/**/*.{ts,tsx}', 'e2e/**/*.{ts,tsx}'],
+      rules: { 'no-restricted-syntax': ['error', ...TOKEN_SYNTAX_RULES] },
+    },
+    ...tanstackQuery.configs['flat/recommended'],
+  ])
+}

package/openapi/foundation.yaml

@@ -0,0 +1,156 @@
+openapi: 3.1.0
+info:
+  title: UI Foundation — the contract every app shares
+  version: "3.0.0"
+  description: >
+    The part of an app's API contract that the foundation package's own code
+    calls: session-cookie auth under /auth/*, and the two error envelopes the
+    gateway's toAppError() translates (FastAPI's default 422 and
+    HTTPException shapes). An app's openapi.yaml must contain every path and
+    component here, unchanged — `ui-foundation check-contract` fails verify
+    when it drifts. Descriptions, summaries and examples may differ; shapes
+    may not.
+
+    A path marked `x-optional: true` may be left out of an app's spec (an
+    app without self-service sign-up omits /auth/register), but if present
+    it must match.
+
+servers:
+  - url: /api
+
+paths:
+  /auth/login:
+    post:
+      operationId: login
+      summary: Log in with email and password, receiving a session cookie
+      tags: [auth]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/LoginRequest" }
+      responses:
+        "200":
+          description: Authenticated. Sets the session_id cookie.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/User" }
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
+  /auth/register:
+    x-optional: true
+    post:
+      operationId: register
+      summary: Create an account and immediately log in, receiving a session cookie
+      tags: [auth]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RegisterRequest" }
+      responses:
+        "200":
+          description: Registered and authenticated. Sets the session_id cookie.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/User" }
+        "422": { $ref: "#/components/responses/ValidationError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
+  /auth/logout:
+    post:
+      operationId: logout
+      summary: Clear the current session
+      tags: [auth]
+      responses:
+        "204":
+          description: Logged out (always, whether or not a session existed).
+        "500": { $ref: "#/components/responses/ServerError" }
+
+  /auth/me:
+    get:
+      operationId: getCurrentUser
+      summary: The currently authenticated user
+      tags: [auth]
+      responses:
+        "200":
+          description: OK.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/User" }
+        "401": { $ref: "#/components/responses/UnauthorizedError" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email, name]
+      properties:
+        id: { type: integer, readOnly: true }
+        email: { type: string, format: email }
+        name: { type: string, minLength: 1, maxLength: 200 }
+
+    LoginRequest:
+      type: object
+      required: [email, password]
+      properties:
+        email: { type: string, format: email }
+        password: { type: string, minLength: 8 }
+
+    RegisterRequest:
+      type: object
+      required: [email, name, password]
+      properties:
+        email: { $ref: "#/components/schemas/User/properties/email" }
+        name: { $ref: "#/components/schemas/User/properties/name" }
+        password: { $ref: "#/components/schemas/LoginRequest/properties/password" }
+
+    ValidationErrorBody:
+      type: object
+      description: FastAPI's default 422 shape (RequestValidationError).
+      required: [detail]
+      properties:
+        detail:
+          type: array
+          items:
+            type: object
+            required: [loc, msg, type]
+            properties:
+              loc:
+                type: array
+                items:
+                  type: ["string", "integer"]
+              msg: { type: string }
+              type: { type: string }
+
+    HTTPErrorBody:
+      type: object
+      description: FastAPI's default HTTPException shape.
+      required: [detail]
+      properties:
+        detail: { type: string }
+
+  responses:
+    ValidationError:
+      description: Validation failed on one or more fields.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/ValidationErrorBody" }
+    NotFoundError:
+      description: Resource not found.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/HTTPErrorBody" }
+    UnauthorizedError:
+      description: Missing or invalid credentials.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/HTTPErrorBody" }
+    ServerError:
+      description: Unhandled server error.
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/HTTPErrorBody" }

package/package.json

@@ -0,0 +1,158 @@
+{
+  "name": "@tristan2828/ui-foundation",
+  "version": "3.0.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/Tristan2828/ui-foundation.git",
+    "directory": "packages/ui-foundation"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "styles",
+    "eslint",
+    "bin",
+    "conventions",
+    "openapi"
+  ],
+  "bin": {
+    "ui-foundation": "bin/ui-foundation.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ui/*": {
+      "types": "./dist/components/ui/*.d.ts",
+      "default": "./dist/components/ui/*.js"
+    },
+    "./gateway": {
+      "types": "./dist/gateway.d.ts",
+      "default": "./dist/gateway.js"
+    },
+    "./mocks": {
+      "types": "./dist/mocks/index.d.ts",
+      "default": "./dist/mocks/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./eslint": {
+      "types": "./eslint/index.d.ts",
+      "default": "./eslint/index.js"
+    },
+    "./styles.css": {
+      "style": "./styles/index.css",
+      "default": "./styles/index.css"
+    },
+    "./openapi.yaml": "./openapi/foundation.yaml",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "gen:api": "openapi-typescript ./openapi/foundation.yaml -o ./src/api/schema.ts",
+    "lint": "eslint .",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "preview-storybook": "vite preview --outDir storybook-static --port 6006 --strictPort",
+    "verify:fast": "npm run gen:api && git diff --exit-code -- src/api/schema.ts && tsc -b && eslint . --max-warnings 0 && node bin/ui-foundation.mjs check-deps && npm run build && vitest run",
+    "verify": "npm run verify:fast && playwright test -c playwright.storybook.config.ts"
+  },
+  "peerDependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@base-ui/react": "^1.8.0",
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.63.0",
+    "@tanstack/eslint-plugin-query": "^5.103.1",
+    "@tanstack/react-query": "^5.103.1",
+    "@tanstack/react-table": "^9.2.4",
+    "eslint": "^10.10.0",
+    "eslint-plugin-check-file": "^3.3.2",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.7",
+    "globals": "^17.12.0",
+    "msw": "^2.15.0",
+    "next-themes": "^0.4.6",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-hook-form": "^7.88.0",
+    "react-router": "^7.18.4",
+    "sonner": "^2.0.8",
+    "tailwindcss": "^4.3.3",
+    "typescript-eslint": "^8.70.0",
+    "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 }
+  },
+  "dependencies": {
+    "@fontsource-variable/geist": "^5.3.0",
+    "@hookform/resolvers": "^5.9.1",
+    "class-variance-authority": "^0.7.1",
+    "cn": "^0.3.0",
+    "date-fns": "^4.4.0",
+    "js-yaml": "^5.4.2",
+    "lucide-react": "^1.47.0",
+    "react-day-picker": "^10.0.1",
+    "shadcn": "^4.21.0",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@base-ui/react": "^1.8.0",
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.63.0",
+    "@storybook/addon-docs": "^10.6.0",
+    "@storybook/react-vite": "^10.6.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/eslint-plugin-query": "^5.103.1",
+    "@tanstack/react-query": "^5.103.1",
+    "@tanstack/react-table": "^9.2.4",
+    "@types/node": "^24.13.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "eslint": "^10.10.0",
+    "eslint-plugin-check-file": "^3.3.2",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.7",
+    "globals": "^17.12.0",
+    "msw": "^2.15.0",
+    "next-themes": "^0.4.6",
+    "openapi-typescript": "^7.13.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-hook-form": "^7.88.0",
+    "react-router": "^7.18.4",
+    "sonner": "^2.0.8",
+    "storybook": "^10.6.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.70.0",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1",
+    "zod": "^4.6.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}