@tristan2828/ui-foundation 4.4.0 → 4.5.0

package/dist/components/app/app-shell-version.d.ts

@@ -0,0 +1,15 @@
+export type AppShellVersion = {
+    /** The full or short commit hash. Empty or missing: nothing is shown. */
+    commit?: string;
+    /** The PR the build came from; links there instead of to the commit. */
+    pr?: string | number;
+    /** The repository's web address, e.g. `https://github.com/me/app`. Missing: the commit shows unlinked. */
+    repoUrl?: string;
+};
+/** What the entry says, or null when there's no commit (development). */
+export declare function versionLabel({ commit, pr }: AppShellVersion): string | null;
+/**
+ * The PR's page, else the commit's, or null when there's no address to
+ * trust: only an http(s) repository makes a link.
+ */
+export declare function versionHref({ commit, pr, repoUrl }: AppShellVersion): string | null;

package/dist/components/app/app-shell-version.js

@@ -0,0 +1,26 @@
+// AppShell's version entry: which build is live, and where it came from.
+// The values are set at build time by `@tristan2828/ui-foundation/vite`.
+function prNumber(pr) {
+    const value = String(pr ?? '').trim();
+    return /^\d+$/.test(value) ? value : null;
+}
+/** What the entry says, or null when there's no commit (development). */
+export function versionLabel({ commit, pr }) {
+    const hash = commit?.trim();
+    if (!hash)
+        return null;
+    const number = prNumber(pr);
+    return number ? `Version ${hash.slice(0, 7)} · PR #${number}` : `Version ${hash.slice(0, 7)}`;
+}
+/**
+ * The PR's page, else the commit's, or null when there's no address to
+ * trust: only an http(s) repository makes a link.
+ */
+export function versionHref({ commit, pr, repoUrl }) {
+    const hash = commit?.trim();
+    const repo = repoUrl?.trim().replace(/\/+$/, '');
+    if (!hash || !repo || !/^https?:\/\/[^/]/i.test(repo))
+        return null;
+    const number = prNumber(pr);
+    return number ? `${repo}/pull/${number}` : `${repo}/commit/${encodeURIComponent(hash)}`;
+}

package/dist/components/app/app-shell.d.ts

@@ -1,6 +1,8 @@
 import { type ReactNode } from 'react';
 import { type NavEntry } from './app-shell-nav.js';
+import { type AppShellVersion } from './app-shell-version.js';
 export type { NavEntry, NavItem, NavSection } from './app-shell-nav.js';
+export type { AppShellVersion } from './app-shell-version.js';
 export type AppShellProps = {
     /** Shown at the top of the sidebar (hidden on the collapsed icon rail). */
     title: string;
@@ -24,5 +26,12 @@ export type AppShellProps = {
      * primitive writes a cookie, read back here). A wide table wants false.
      */
     defaultSidebarOpen?: boolean;
+    /**
+     * Which build is live, as a short commit in the sidebar footer linking to
+     * its PR (or to the commit when there's no PR). Nothing is shown without
+     * a commit, so development shows nothing. The values come from
+     * `@tristan2828/ui-foundation/vite` (`import.meta.env.VITE_BUILD_*`).
+     */
+    version?: AppShellVersion;
 };
-export declare function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen }: AppShellProps): import("react").JSX.Element;
+export declare function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen, version }: AppShellProps): import("react").JSX.Element;

package/dist/components/app/app-shell.js

@@ -5,6 +5,7 @@ import { useEffect, useState } from 'react';
 import { Link, Navigate, Outlet, useLocation } from 'react-router';
 import { useAuth } from '../../auth/use-auth.js';
 import { activeNavTo, navGroups } from './app-shell-nav.js';
+import { versionHref, versionLabel } from './app-shell-version.js';
 import { ErrorState } from './error-state.js';
 import { useErrorReporter } from '../../error-reporting/error-reporting-context.js';
 import { ReportRoutePattern } from '../../error-reporting/error-reporting-provider.js';
@@ -37,10 +38,19 @@ function ThemeToggle() {
     const isDark = resolvedTheme === 'dark';
     return (_jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Toggle dark mode", onClick: () => setTheme(isDark ? 'light' : 'dark'), children: isDark ? _jsx(SunIcon, {}) : _jsx(MoonIcon, {}) }));
 }
+// Hidden on the icon rail, like the user's name beside it.
+function VersionEntry({ version }) {
+    const label = versionLabel(version);
+    if (!label)
+        return null;
+    const href = versionHref(version);
+    const className = 'block truncate px-2 type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden';
+    return href ? (_jsx("a", { href: href, target: "_blank", rel: "noreferrer", className: `${className} hover:underline`, children: label })) : (_jsx("span", { className: className, children: label }));
+}
 function AppShellSkeleton() {
     return (_jsxs("div", { className: "flex h-screen w-full gap-4 p-4", "data-state": "loading", children: [_jsx(Skeleton, { className: "h-full w-56 shrink-0" }), _jsxs("div", { className: "flex-1 space-y-4 pt-2", children: [_jsx(Skeleton, { className: "h-8 w-64" }), _jsx(Skeleton, { className: "h-40 w-full" })] })] }));
 }
-export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }) {
+export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true, version }) {
     const { user, status, error, retry, logout } = useAuth();
     const location = useLocation();
     const reporter = useErrorReporter();
@@ -75,11 +85,11 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }
                                                             // one should be (activeNavTo).
                                                             const isActive = to === activeTo;
                                                             return (_jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { isActive: isActive, tooltip: label, render: _jsx(Link, { to: to, "aria-current": isActive ? 'page' : undefined }), children: [_jsx(Icon, {}), _jsx("span", { children: label })] }) }, to));
-                                                        }) }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsx(SidebarFooter, { children: _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
-                                                    setIsLoggingOut(true);
-                                                    // A failed request still ends the session on screen
-                                                    // (AuthProvider), so this stays a deliberate logout: a
-                                                    // clean /login, never the previous user's page as `from`.
-                                                    logout().catch(() => { });
-                                                }, children: _jsx(LogOutIcon, {}) })] }) })] }) }), _jsxs(SidebarInset, { className: "min-w-0", children: [_jsxs("header", { className: "flex h-14 shrink-0 items-center gap-2 border-b border-border px-4", children: [_jsx(SidebarTrigger, {}), _jsx("div", { className: "flex-1" }), _jsx(ThemeToggle, {})] }), _jsx("div", { className: "flex-1 p-6", children: _jsx(Outlet, {}) })] })] }), _jsx(Toaster, { position: "top-center" })] }));
+                                                        }) }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsxs(SidebarFooter, { children: [version && _jsx(VersionEntry, { version: version }), _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
+                                                        setIsLoggingOut(true);
+                                                        // A failed request still ends the session on screen
+                                                        // (AuthProvider), so this stays a deliberate logout: a
+                                                        // clean /login, never the previous user's page as `from`.
+                                                        logout().catch(() => { });
+                                                    }, children: _jsx(LogOutIcon, {}) })] })] })] }) }), _jsxs(SidebarInset, { className: "min-w-0", children: [_jsxs("header", { className: "flex h-14 shrink-0 items-center gap-2 border-b border-border px-4", children: [_jsx(SidebarTrigger, {}), _jsx("div", { className: "flex-1" }), _jsx(ThemeToggle, {})] }), _jsx("div", { className: "flex-1 p-6", children: _jsx(Outlet, {}) })] })] }), _jsx(Toaster, { position: "top-center" })] }));
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AppShell, type AppShellProps, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
+export { AppShell, type AppShellProps, type AppShellVersion, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, type DataTableWidth, type SortingState } from './components/app/data-table.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.4.0",
+  "version": "4.5.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": {
@@ -16,6 +16,7 @@
     "dist",
     "styles",
     "eslint",
+    "vite",
     "bin",
     "conventions",
     "openapi"
@@ -48,6 +49,10 @@
       "types": "./eslint/index.d.ts",
       "default": "./eslint/index.js"
     },
+    "./vite": {
+      "types": "./vite/index.d.ts",
+      "default": "./vite/index.js"
+    },
     "./styles.css": {
       "style": "./styles/index.css",
       "default": "./styles/index.css"
@@ -88,6 +93,7 @@
     "sonner": "^2.0.8",
     "tailwindcss": "^4.3.3",
     "typescript-eslint": "^8.70.0",
+    "vite": "^8.3.0",
     "zod": "^4.6.5"
   },
   "peerDependenciesMeta": {
@@ -123,6 +129,9 @@
     },
     "typescript-eslint": {
       "optional": true
+    },
+    "vite": {
+      "optional": true
     }
   },
   "dependencies": {

package/vite/index.d.ts

@@ -0,0 +1,14 @@
+import type { Plugin } from 'vite'
+
+export type BuildInfoOptions = {
+  /** The app's repository, e.g. `https://github.com/me/app`. `BUILD_REPO_URL` wins over it. */
+  repoUrl?: string
+}
+
+/**
+ * On `vite build`, writes `dist/build-info.json` (`api`: "real" or "mock",
+ * `commit`, `pr`, `builtAt`) and sets `import.meta.env.VITE_BUILD_COMMIT`,
+ * `VITE_BUILD_PR` and `VITE_BUILD_REPO_URL` from `BUILD_COMMIT`,
+ * `BUILD_PR` and `BUILD_REPO_URL`.
+ */
+export default function buildInfo(options?: BuildInfoOptions): Plugin

package/vite/index.js

@@ -0,0 +1,56 @@
+// `@tristan2828/ui-foundation/vite` — what a production build says about
+// itself. An app's vite.config.ts:
+//
+//   import buildInfo from '@tristan2828/ui-foundation/vite'
+//   plugins: [react(), tailwindcss(), buildInfo({ repoUrl: 'https://github.com/me/app' })]
+//
+// On `vite build` it:
+// - writes dist/build-info.json: which API the bundle calls ("real", or
+//   "mock" for MSW), and the commit and PR it was built from. The reference
+//   backend refuses to serve a mock bundle with APP_ENV=production.
+// - sets import.meta.env.VITE_BUILD_COMMIT, VITE_BUILD_PR and
+//   VITE_BUILD_REPO_URL from the environment's BUILD_COMMIT, BUILD_PR and
+//   BUILD_REPO_URL (the repoUrl option when that's unset), for AppShell's
+//   `version`. Unset, they're empty strings and nothing is shown.
+//
+// Build only: in development the three are undefined. Plain JavaScript, like
+// the eslint entry: Vite loads the config before any TypeScript tooling runs.
+
+/** @param {string | undefined} value */
+function clean(value) {
+  const trimmed = value?.trim()
+  return trimmed ? trimmed : null
+}
+
+/** @param {{ repoUrl?: string }} [options] */
+export default function buildInfo(options = {}) {
+  const commit = clean(process.env.BUILD_COMMIT)
+  const pr = clean(process.env.BUILD_PR)
+  const repoUrl = clean(process.env.BUILD_REPO_URL) ?? clean(options.repoUrl)
+  let api = 'mock'
+
+  return {
+    name: 'ui-foundation:build-info',
+    apply: 'build',
+    config() {
+      return {
+        define: {
+          'import.meta.env.VITE_BUILD_COMMIT': JSON.stringify(commit ?? ''),
+          'import.meta.env.VITE_BUILD_PR': JSON.stringify(pr ?? ''),
+          'import.meta.env.VITE_BUILD_REPO_URL': JSON.stringify(repoUrl ?? ''),
+        },
+      }
+    },
+    configResolved(config) {
+      // The same test as the app's main.tsx: anything but "real" ships MSW.
+      api = config.env.VITE_API === 'real' ? 'real' : 'mock'
+    },
+    generateBundle() {
+      this.emitFile({
+        type: 'asset',
+        fileName: 'build-info.json',
+        source: `${JSON.stringify({ api, commit, pr, builtAt: new Date().toISOString() }, null, 2)}\n`,
+      })
+    },
+  }
+}