@tristan2828/ui-foundation 3.18.1 → 3.19.0

package/README.md

@@ -18,14 +18,14 @@ than installing this by hand:
 
 | Import | What |
 |---|---|
-| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown`, `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown`, `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `DataEnvironmentBanner`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
 | `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, checkbox, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, 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`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |
-| `@tristan2828/ui-foundation/testing` | Playwright: `defineA11ySuite`, `defineMockModeBannerSuite`, `forceMswOverride`, `forceLoggedOut`, `waitForMswReady` |
+| `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `environmentHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |
+| `@tristan2828/ui-foundation/testing` | Playwright: `defineA11ySuite`, `defineMockModeBannerSuite`, `defineDataEnvironmentBannerSuite`, `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";` |
-| `@tristan2828/ui-foundation/openapi.yaml` | the part of an app's API contract the package calls: `/auth/*` and the error bodies |
+| `@tristan2828/ui-foundation/openapi.yaml` | the part of an app's API contract the package calls: `/auth/*`, `/environment` (optional) and the error bodies |
 
 ## The `ui-foundation` command
 

package/conventions/AGENTS.md

@@ -37,8 +37,8 @@ is right. Do not disable, skip, or work around it.
 - NEVER hand-write an API type. All types come from `src/api/schema.d.ts`,
   generated from `openapi.yaml`. If a type is missing, run `npm run gen:api`.
   (Enforced: codegen diff in verify.)
-- NEVER change the foundation's part of `openapi.yaml` — the `/auth/*` paths
-  and the error envelopes. The package's code calls exactly those shapes.
+- NEVER change the foundation's part of `openapi.yaml` — the `/auth/*` and
+  `/environment` paths and the error envelopes. The package's code calls exactly those shapes.
   (Enforced: `ui-foundation check-contract` in verify.)
 - NEVER use a raw hex value or a Tailwind palette color (`bg-blue-500`).
   Semantic tokens only: `bg-primary`, `text-muted-foreground`. (Enforced:

package/conventions/docs/add-an-entity.md

@@ -68,7 +68,7 @@ is a filled-in example while the Widgets demo is still here).
    query parameter for each field the plan marks as a filter. Reuse the
    `Page` and error components already in the spec; do not redefine
    pagination or error shapes per entity, and leave the foundation's part
-   of the spec (`/auth/*`, the error bodies) alone — `ui-foundation
+   of the spec (`/auth/*`, `/environment`, the error bodies) alone — `ui-foundation
    check-contract` fails verify if it changes.
 2. **`npm run gen:api`** to regenerate `src/api/schema.d.ts`. Never
    hand-edit it.

package/dist/api/gateway/environment.d.ts

@@ -0,0 +1 @@
+export declare function getDataLabel(): Promise<string | null>;

package/dist/api/gateway/environment.js

@@ -0,0 +1,10 @@
+import { safeFetch, toAppError } from "./errors.js";
+export async function getDataLabel() {
+    const res = await safeFetch("/environment");
+    if (res.status === 404)
+        return null;
+    if (res.status !== 200)
+        throw toAppError(res.status, res.body);
+    const label = res.body?.dataLabel;
+    return typeof label === "string" && label.trim() !== "" ? label.trim() : null;
+}

package/dist/api/schema.d.ts

@@ -71,10 +71,34 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/environment": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Which data the backend is serving, for DataEnvironmentBanner
+         * @description Needs no session: the banner shows on /login too. A null dataLabel means production data, and no banner.
+         */
+        get: operations["getDataEnvironment"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        DataEnvironment: {
+            /** @description What the data is, as the banner names it ("dev" shows "Dev data"). null when the backend serves production data. */
+            dataLabel: string | null;
+        };
         User: {
             readonly id: number;
             /** Format: email */
@@ -243,4 +267,25 @@ export interface operations {
             500: components["responses"]["ServerError"];
         };
     };
+    getDataEnvironment: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DataEnvironment"];
+                };
+            };
+            500: components["responses"]["ServerError"];
+        };
+    };
 }

package/dist/auth/auth-provider.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect } from 'react';
 import { useQuery, useQueryClient } from '@tanstack/react-query';
 import { getCurrentUser, login as loginRequest, logout as logoutRequest, register as registerRequest, } from '../api/gateway/auth.js';
+import { DATA_LABEL_QUERY_KEY } from '../hooks/use-data-label.js';
 import { AuthContext } from './auth-context.js';
 // TanStack Query, not useEffect — AGENTS.md's "NEVER fetch in useEffect"
 // rule applies here too. A 401 here just means "not logged in", which the
@@ -11,14 +12,17 @@ const AUTH_QUERY_KEY = ['auth', 'me'];
 function isAuthError(error) {
     return error?.kind === 'auth';
 }
-// Every cached query except the session itself belongs to whoever was
-// logged in when it ran. Dropped on every session change so the next user
-// never sees the previous user's rows — widgets are per-user on the
-// backend. `removeQueries` with a predicate, not `clear()`: clear() would
-// also drop the auth query this provider's own useQuery observes, and that
-// observer wouldn't pick up the replacement setQueryData creates.
+// Every cached query except these belongs to whoever was logged in when it
+// ran: the session itself, and which data the backend serves
+// (DataEnvironmentBanner's, the same for everyone).
+const SESSION_INDEPENDENT_KEYS = new Set([AUTH_QUERY_KEY[0], DATA_LABEL_QUERY_KEY[0]]);
+// Dropped on every session change so the next user never sees the
+// previous user's rows — widgets are per-user on the backend.
+// `removeQueries` with a predicate, not `clear()`: clear() would also drop
+// the auth query this provider's own useQuery observes, and that observer
+// wouldn't pick up the replacement setQueryData creates.
 function removeUserScopedQueries(queryClient) {
-    queryClient.removeQueries({ predicate: (query) => query.queryKey[0] !== AUTH_QUERY_KEY[0] });
+    queryClient.removeQueries({ predicate: (query) => !SESSION_INDEPENDENT_KEYS.has(query.queryKey[0]) });
 }
 function startSession(queryClient, user) {
     removeUserScopedQueries(queryClient);

package/dist/components/app/data-environment-banner.d.ts

@@ -0,0 +1,5 @@
+export declare function DataEnvironmentBanner(): import("react").JSX.Element;
+/** The banner itself, for a label already known (Storybook, tests). Renders nothing for null. */
+export declare function DataEnvironmentNotice({ label }: {
+    label: string | null;
+}): import("react").JSX.Element | null;

package/dist/components/app/data-environment-banner.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DatabaseIcon } from 'lucide-react';
+import { useDataLabel } from '../../hooks/use-data-label.js';
+// The real backend, on data that isn't production's: a dev branch of the
+// hosted database, a local one. Locally the app looks exactly like the
+// deployed one (same data, same login), and an edit made there lands in
+// data that gets reset. Only the backend knows which database it's on, so
+// the label is its DATA_LABEL, served from GET /environment. Unset in
+// production: no label, no banner.
+//
+// Rendered above the router, inside FoundationProviders (it queries
+// through TanStack Query), so it shows on every route including /login.
+// In mock mode the mock handler answers null: MockModeBanner already says
+// what the data is there.
+export function DataEnvironmentBanner() {
+    const label = useDataLabel();
+    return _jsx(DataEnvironmentNotice, { label: label });
+}
+/** The banner itself, for a label already known (Storybook, tests). Renders nothing for null. */
+export function DataEnvironmentNotice({ label }) {
+    if (label === null)
+        return null;
+    return (_jsxs("div", { role: "status", "data-slot": "data-environment-banner", className: "flex h-9 items-center justify-center gap-1.5 border-b border-border bg-info px-4 text-sm text-info-foreground", children: [_jsx(DatabaseIcon, { className: "size-4 shrink-0", "aria-hidden": "true" }), _jsxs("span", { className: "truncate", children: [_jsx("strong", { className: "font-semibold", children: `${dataName(label)}:` }), " changes here don't reach production"] })] }));
+}
+// "dev" → "Dev data", "staging" → "Staging data".
+function dataName(label) {
+    return `${label.charAt(0).toUpperCase()}${label.slice(1)} data`;
+}

package/dist/components/app/foundation-providers.js

@@ -9,6 +9,8 @@ import { ThemeProvider } from '../theme-provider.js';
 // works: the theme outermost, the mock-mode banner above the router so it
 // shows on every route (/login included), and AuthProvider inside
 // QueryClientProvider because it queries /auth/me through TanStack Query.
+// An app's DataEnvironmentBanner goes first among the children, before its
+// router: it queries too, and shows on every route like the mock banner.
 export function FoundationProviders({ mockMode, queryClient, children, }) {
     const [client] = useState(() => queryClient ?? createQueryClient());
     return (_jsxs(ThemeProvider, { attribute: "class", defaultTheme: "system", enableSystem: true, children: [_jsx(MockModeBanner, { active: mockMode }), _jsx(QueryClientProvider, { client: client, children: _jsx(AuthProvider, { children: children }) })] }));

package/dist/hooks/use-data-label.d.ts

@@ -0,0 +1,3 @@
+export declare const DATA_LABEL_QUERY_KEY: readonly ["environment"];
+/** The backend's data label ("dev"), or null for production data, a failed request, or while it loads. */
+export declare function useDataLabel(): string | null;

package/dist/hooks/use-data-label.js

@@ -0,0 +1,18 @@
+import { useQuery } from '@tanstack/react-query';
+import { getDataLabel } from '../api/gateway/environment.js';
+// Which data the backend serves (GET /environment), for
+// DataEnvironmentBanner. It can't change while the page is open, so it's
+// asked once per load: never stale, never refetched on focus. And it's the
+// same whoever is signed in, so AuthProvider keeps it across session
+// changes instead of dropping it with the user's rows.
+export const DATA_LABEL_QUERY_KEY = ['environment'];
+/** The backend's data label ("dev"), or null for production data, a failed request, or while it loads. */
+export function useDataLabel() {
+    const { data } = useQuery({
+        queryKey: DATA_LABEL_QUERY_KEY,
+        queryFn: getDataLabel,
+        staleTime: Infinity,
+        gcTime: Infinity,
+    });
+    return data ?? null;
+}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { DataTable, type DataTableProps, type SortingState } from './components/
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
 export { EntityView, type EntityViewField, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
 export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceOptions, type EditKind, } from './components/app/edit-in-place.js';
+export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue, type EditableValueProps } from './components/app/editable-value.js';
 export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';

package/dist/index.js

@@ -8,6 +8,7 @@ export { DataTable } from './components/app/data-table.js';
 export { EntityForm } from './components/app/entity-form.js';
 export { EntityView, } from './components/app/entity-view.js';
 export { editInPlace, } from './components/app/edit-in-place.js';
+export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue } from './components/app/editable-value.js';
 export { ErrorState } from './components/app/error-state.js';
 export { FoundationProviders } from './components/app/foundation-providers.js';

package/dist/mocks/environment.d.ts

@@ -0,0 +1 @@
+export declare const environmentHandlers: import("msw").HttpHandler[];

package/dist/mocks/environment.js

@@ -0,0 +1,8 @@
+// MSW handler for GET /environment (openapi/foundation.yaml). Mock data is
+// never production's, but MockModeBanner already says so: answering null
+// keeps DataEnvironmentBanner out of mock mode. An app that renders the
+// banner spreads `environmentHandlers` into its own handler list.
+import { http, HttpResponse } from 'msw';
+export const environmentHandlers = [
+    http.get('*/api/environment', () => HttpResponse.json({ dataLabel: null })),
+];

package/dist/mocks/index.d.ts

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

package/dist/mocks/index.js

@@ -2,4 +2,5 @@
 // so msw (an optional peer dependency) never reaches an app's main bundle
 // unless it imports this.
 export { authHandlers, getMockCurrentUser, isMockAuthenticated, MOCK_PASSWORD, MOCK_USER, resetMockAuth, setMockAuthenticated, } from './auth.js';
+export { environmentHandlers } from './environment.js';
 export { exposeMswForE2E } from './e2e-hooks.js';

package/dist/testing/index.d.ts

@@ -73,3 +73,29 @@ export type MockModeBannerSuiteOptions = {
  * were production, which is what the banner exists for.
  */
 export declare function defineMockModeBannerSuite({ routes, mockMode, }: MockModeBannerSuiteOptions): void;
+export type DataEnvironmentBannerSuiteOptions = {
+    /** 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'`, as for the mock-mode banner. */
+    mockMode?: boolean;
+    /**
+     * Against the real backend only: the DATA_LABEL it was started with.
+     * Defaults to `process.env.DATA_LABEL`, null when that's unset or empty
+     * (production data, so no banner).
+     */
+    dataLabel?: string | null;
+};
+/**
+ * DataEnvironmentBanner: shown on every route, logged-out ones included,
+ * whenever the backend says its data isn't production's, and nowhere when
+ * it says it is.
+ *
+ * Mock mode: the mock handler answers null, so no banner (MockModeBanner
+ * covers mock data). A label forced through MSW shows on every route, in
+ * a tone apart from the mock banner, and passes axe in light and dark.
+ *
+ * Real backend (`VITE_API=real`): the banner names `dataLabel` on every
+ * route, or is absent when it's null, which is how a production deploy
+ * runs.
+ */
+export declare function defineDataEnvironmentBannerSuite({ routes, mockMode, dataLabel, }: DataEnvironmentBannerSuiteOptions): void;

package/dist/testing/index.js

@@ -154,3 +154,83 @@ export function defineMockModeBannerSuite({ routes, mockMode = process.env.VITE_
         }
     });
 }
+// The banner names the label as data: "dev" → "Dev data".
+const dataName = (label) => `${label.charAt(0).toUpperCase()}${label.slice(1)} data`;
+/**
+ * Opens a route and waits for the app's own GET /environment to answer,
+ * so "no banner" is checked after the backend has spoken, not before.
+ */
+async function gotoWithDataLabel(page, route) {
+    const answered = page.waitForResponse((response) => new URL(response.url()).pathname === '/api/environment');
+    await page.goto(route);
+    await answered;
+    // The banner renders beside the router: once a screen's <main> is on
+    // the page, the banner would be too.
+    await expect(page.getByRole('main')).toBeVisible();
+}
+/**
+ * DataEnvironmentBanner: shown on every route, logged-out ones included,
+ * whenever the backend says its data isn't production's, and nowhere when
+ * it says it is.
+ *
+ * Mock mode: the mock handler answers null, so no banner (MockModeBanner
+ * covers mock data). A label forced through MSW shows on every route, in
+ * a tone apart from the mock banner, and passes axe in light and dark.
+ *
+ * Real backend (`VITE_API=real`): the banner names `dataLabel` on every
+ * route, or is absent when it's null, which is how a production deploy
+ * runs.
+ */
+export function defineDataEnvironmentBannerSuite({ routes, mockMode = process.env.VITE_API !== 'real', dataLabel = process.env.DATA_LABEL?.trim() || null, }) {
+    const banner = (page) => page.getByRole('status').filter({ hasText: "changes here don't reach production" });
+    const expectAbsentEverywhere = async (page) => {
+        for (const route of routes) {
+            await gotoWithDataLabel(page, route);
+            await test.step(route, () => expect(banner(page)).toHaveCount(0));
+        }
+    };
+    const expectNamedEverywhere = async (page, label) => {
+        for (const route of routes) {
+            await gotoWithDataLabel(page, route);
+            await test.step(route, () => expect(banner(page)).toContainText(`${dataName(label)}:`));
+        }
+    };
+    if (!mockMode) {
+        if (dataLabel === null) {
+            test('no data-environment banner on production data', async ({ page }) => {
+                await expectAbsentEverywhere(page);
+            });
+        }
+        else {
+            test(`"${dataName(dataLabel)}" is announced on every route, including logged-out ones`, async ({ page }) => {
+                await expectNamedEverywhere(page, dataLabel);
+            });
+        }
+        return;
+    }
+    const forceLabel = (page) => forceMswOverride(page, { method: 'get', path: '*/api/environment', body: { dataLabel: 'dev' } });
+    test('no data-environment banner in mock mode, where the mock banner says it', async ({ page }) => {
+        await expectAbsentEverywhere(page);
+    });
+    test('a data label from the backend is announced on every route, including logged-out ones', async ({ page }) => {
+        await forceLabel(page);
+        await expectNamedEverywhere(page, 'dev');
+        // Both banners at once, and never the same one.
+        await expect(page.getByRole('status').filter({ hasText: 'Mock data' })).toBeVisible();
+        const fill = (locator) => locator.evaluate((element) => getComputedStyle(element).backgroundColor);
+        expect(await fill(banner(page))).not.toBe(await fill(page.getByRole('status').filter({ hasText: 'Mock data' })));
+    });
+    for (const colorScheme of ['light', 'dark']) {
+        test(`the data-environment banner has zero axe violations (${colorScheme})`, async ({ page }) => {
+            await page.emulateMedia({ colorScheme });
+            await forceLabel(page);
+            for (const route of routes) {
+                await gotoWithDataLabel(page, route);
+                await expect(page.locator('html')).toHaveClass(colorScheme);
+                await expect(banner(page)).toBeVisible();
+                await expect(page.locator('[data-state="loading"]')).toHaveCount(0);
+                await test.step(route, () => expectNoAxeViolations(page));
+            }
+        });
+    }
+}

package/openapi/foundation.yaml

@@ -12,8 +12,9 @@ info:
     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.
+    app without self-service sign-up omits /auth/register, an app that
+    doesn't render DataEnvironmentBanner omits /environment), but if
+    present it must match.
 
 servers:
   - url: /api
@@ -83,8 +84,36 @@ paths:
         "401": { $ref: "#/components/responses/UnauthorizedError" }
         "500": { $ref: "#/components/responses/ServerError" }
 
+  /environment:
+    x-optional: true
+    get:
+      operationId: getDataEnvironment
+      summary: Which data the backend is serving, for DataEnvironmentBanner
+      description: >
+        Needs no session: the banner shows on /login too. A null dataLabel
+        means production data, and no banner.
+      tags: [environment]
+      responses:
+        "200":
+          description: OK.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/DataEnvironment" }
+        "500": { $ref: "#/components/responses/ServerError" }
+
 components:
   schemas:
+    DataEnvironment:
+      type: object
+      required: [dataLabel]
+      properties:
+        dataLabel:
+          type: ["string", "null"]
+          minLength: 1
+          description: >
+            What the data is, as the banner names it ("dev" shows "Dev
+            data"). null when the backend serves production data.
+
     User:
       type: object
       required: [id, email, name]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.18.1",
+  "version": "3.19.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": {