@tristan2828/ui-foundation 3.1.1 → 3.2.0

package/conventions/AGENTS.md

@@ -51,6 +51,13 @@ is right. Do not disable, skip, or work around it.
 - NEVER import `@tristan2828/ui-foundation/gateway` outside
   `src/api/gateway/`. Components and hooks call a gateway module through
   TanStack Query. (Enforced: no-restricted-imports.)
+- NEVER add a database table or column without a comment. The migration
+  that creates it also runs `COMMENT ON TABLE` / `COMMENT ON COLUMN`,
+  saying what it holds in words someone with only database access can use:
+  units, what null means, which table an id points at. A second agent with
+  credentials and no repo reads the schema alone. Applies to an app with a
+  Postgres backend. (Enforced: `backend/scripts/check_db_comments.py`, run
+  by `scripts/check-backend-postgres.sh` after `alembic upgrade head`.)
 - NEVER let a backend-shaped response reach a component. Paginated data is
   `Page<T>`. Failures are `AppError`. Queries are `QuerySpec`. The gateway
   translates; nothing above it knows the wire format. (Enforced: gateway

package/conventions/docs/cell-patterns.md

@@ -162,7 +162,28 @@ When the useful question is "how soon?" rather than "which day?".
   rebuilt as UTC midnight** (`Date.UTC(y, m, d)`). Subtracting `Date.now()`
   shifts the answer by a day for anyone west of UTC.
 - Relative text **goes stale**, so a fixture pinning a date drifts. Freeze
-  the clock (Playwright's `page.clock`) in any test asserting one.
+  the clock (Playwright's `page.clock`) in any test asserting one, and
+  assert one past and one future value:
+
+```ts
+// West of UTC, where subtracting Date.now() would be off by a day.
+test.use({ timezoneId: 'America/Los_Angeles' })
+
+test('release dates read relative to today', async ({ page }) => {
+  // Before goto, so the first render already sees it. Noon UTC is the same
+  // calendar day in every timezone from UTC-11 to UTC+11.
+  await page.clock.setFixedTime(new Date('2026-06-01T12:00:00Z'))
+  await page.goto('/games')
+  // Mock fixtures: one released 2026-04-01, one due 2026-06-22.
+  await expect(page.getByRole('cell', { name: '2 months ago' })).toBeVisible()
+  await expect(page.getByRole('cell', { name: 'in 3 weeks' })).toBeVisible()
+})
+```
+
+`setFixedTime` pins `Date.now()` and `new Date()` and leaves the real
+timers alone, so debounces and TanStack Query behave as usual. Reach for
+`page.clock.install()` only when a test has to move time forward.
+
 - `title` is mouse-only. If the exact date matters, use pattern 4 instead.
 - **Cost:** "2 years ago" is vague, and the column doesn't look sorted even
   though server-side sorting still works.

package/conventions/docs/design-language.md

@@ -8,16 +8,24 @@ composites don't grow that way; they are built against a real app's screen.
 
 ## Semantic tones
 
-Three tones carry meaning: **success**, **warning**, **destructive**. Grey
-is not a tone — it is the absence of one, and most values should stay grey.
+Four tones carry meaning: **success**, **warning**, **destructive** and
+**info**. Grey is not a tone — it is the absence of one, and most values
+should stay grey.
+
+The first three say good or bad. **Info** says neither: *notice this*,
+without a verdict. It is for a state that is worth seeing but isn't good
+news or bad news: in progress, new, scheduled, beta. If the honest answer
+to "is this good?" is "neither, but it matters right now", it's info. If
+the answer is "neither, and it doesn't", it's grey: info is still a
+colour, and the "about a third" limit below counts it.
 
 Each tone has two kinds of token, and picking the wrong one is the single
 most common way to ship an unreadable label:
 
 | Token | For | Why it can't be the other one |
 |---|---|---|
-| `--success` / `--warning` / `--destructive` (+ `-foreground`) | a **solid fill**, always with white text on it | chosen to contrast with *white*, so on the page background it's too light in light mode |
-| `--success-text` / `--warning-text` / `--destructive-text` | the tone as **text, a border or an icon** on the page background | chosen to contrast with *the page*, so as a fill under white text it's needlessly dark |
+| `--success` / `--warning` / `--destructive` / `--info` (+ `-foreground`) | a **solid fill**, always with white text on it | chosen to contrast with *white*, so on the page background it's too light in light mode |
+| `--success-text` / `--warning-text` / `--destructive-text` / `--info-text` | the tone as **text, a border or an icon** on the page background | chosen to contrast with *the page*, so as a fill under white text it's needlessly dark |
 
 Only the `*-text` tokens are remapped in `.dark`. A solid fill keeps one
 shade in both themes, because it always carries white text and the page
@@ -25,20 +33,22 @@ behind it never enters the calculation.
 
 Measured ratios (WCAG 2.x, sRGB) are recorded next to each primitive in
 the package's `styles/theme.css`, and its `e2e/storybook-visual.spec.ts` re-checks all
-nine tone/style combinations with axe against the rendered DOM in both
+twelve tone/style combinations with axe against the rendered DOM in both
 themes. **A new tone or style is not done until it appears in that story.**
 
 ## The three badge styles
 
 `Badge` ships each tone in three styles. They are not interchangeable:
 
-- **Outline** — `outline-success`, `outline-warning`, `outline-destructive`.
+- **Outline** — `outline-success`, `outline-warning`, `outline-destructive`,
+  `outline-info`.
   The default choice, and the one proven across real columns. Quiet enough
   to repeat down 25 rows without the column becoming a wall of color.
-- **Tinted** — `tinted-success`, `tinted-warning`, `tinted-destructive`. A
+- **Tinted** — `tinted-success`, `tinted-warning`, `tinted-destructive`,
+  `tinted-info`. A
   low-alpha wash of the tone with `*-text` on top. More presence than
   outline; use when the value is the point of the row, not a detail of it.
-- **Solid** — `success`, `warning`, `destructive`. The loudest. Use for one
+- **Solid** — `success`, `warning`, `destructive`, `info`. The loudest. Use for one
   value that must be impossible to miss, rarely for a whole column: solid
   reads as an alert, and a column of alerts reads as noise.
 
@@ -75,7 +85,7 @@ Two rules that keep this honest:
 
 ## Categorical colour
 
-Tones say good or bad. A value that is merely *different* from its
+Tones say good, bad or *notice this*. A value that is merely *different* from its
 neighbours — a genre, a team, a category — needs a different mechanism, and
 it is `--category-1` through `--category-8`.
 
@@ -98,7 +108,9 @@ Four things about them:
 
 - **The hues avoid red, green and amber**, which the tones already spend. A
   category drawn in red reads as "this one is bad" even when nothing is
-  wrong.
+  wrong. Info's blue came later, and slots 1, 6 and 8 sit near it: a table
+  that shows an info badge keeps its categories off those three, so a blue
+  genre isn't read as "notice this".
 - **They are ordered by distinctness, not by hue angle.** An app using
   three categories gets three obviously different colours. Past about five,
   hue alone stops separating them — slots 3 and 7 are both yellow-greens —

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

@@ -1,13 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { LogOutIcon, MoonIcon, SunIcon } from 'lucide-react';
 import { useTheme } from 'next-themes';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { NavLink, Navigate, Outlet, useLocation } from 'react-router';
 import { useAuth } from '../../auth/use-auth.js';
 import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
 import { Skeleton } from '../ui/skeleton.js';
-import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider, SidebarTrigger, } from '../ui/sidebar.js';
+import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider, SidebarTrigger, useSidebar, } from '../ui/sidebar.js';
 import { Toaster } from '../ui/sonner.js';
 import { TooltipProvider } from '../ui/tooltip.js';
 // Must match SIDEBAR_COOKIE_NAME in ../ui/sidebar.tsx, which writes the
@@ -17,6 +17,18 @@ function storedSidebarOpen(fallback) {
     const match = document.cookie.match(new RegExp(`(?:^|; )${SIDEBAR_COOKIE_NAME}=([^;]*)`));
     return match ? match[1] === 'true' : fallback;
 }
+// Below the mobile breakpoint the sidebar is a modal sheet, and the
+// primitive leaves it open when one of its links navigates, covering the
+// page the user just asked for. Keyed on location.key, so following a link
+// to the page already showing closes it too. Covers sidebarExtra's links.
+function CloseMobileSidebarOnNavigate() {
+    const { setOpenMobile } = useSidebar();
+    const { key } = useLocation();
+    useEffect(() => {
+        setOpenMobile(false);
+    }, [key, setOpenMobile]);
+    return null;
+}
 function ThemeToggle() {
     const { resolvedTheme, setTheme } = useTheme();
     const isDark = resolvedTheme === 'dark';
@@ -52,7 +64,7 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }
         const from = `${location.pathname}${location.search}${location.hash}`;
         return _jsx(Navigate, { to: "/login", replace: true, state: isLoggingOut ? undefined : { from } });
     }
-    return (_jsxs(TooltipProvider, { children: [_jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [_jsxs(SidebarGroup, { children: [_jsx(SidebarGroupLabel, { children: "Navigation" }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: nav.map(({ to, label, icon: Icon, end }) => {
+    return (_jsxs(TooltipProvider, { children: [_jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [_jsxs(SidebarGroup, { children: [_jsx(SidebarGroupLabel, { children: "Navigation" }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: nav.map(({ to, label, icon: Icon, end }) => {
                                                             const isActive = end
                                                                 ? location.pathname === to
                                                                 : location.pathname.startsWith(to);

package/dist/components/ui/badge.d.ts

@@ -1,7 +1,7 @@
 import { useRender } from "@base-ui/react/use-render";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: ({
-    variant?: "link" | "success" | "default" | "outline" | "secondary" | "ghost" | "destructive" | "warning" | "outline-success" | "outline-warning" | "outline-destructive" | "tinted-success" | "tinted-warning" | "tinted-destructive" | null | undefined;
+    variant?: "link" | "success" | "default" | "outline" | "secondary" | "ghost" | "destructive" | "warning" | "info" | "outline-success" | "outline-warning" | "outline-info" | "outline-destructive" | "tinted-success" | "tinted-warning" | "tinted-info" | "tinted-destructive" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Badge({ className, variant, render, ...props }: useRender.ComponentProps<"span"> & VariantProps<typeof badgeVariants>): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export { Badge, badgeVariants };

package/dist/components/ui/badge.js

@@ -10,14 +10,16 @@ const badgeVariants = cva("group/badge inline-flex h-5 w-fit shrink-0 items-cent
             destructive: "bg-destructive text-destructive-foreground focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 [a]:hover:bg-destructive/90",
             success: "bg-success text-success-foreground focus-visible:ring-success/20 dark:focus-visible:ring-success/40 [a]:hover:bg-success/90",
             warning: "bg-warning text-warning-foreground focus-visible:ring-warning/20 dark:focus-visible:ring-warning/40 [a]:hover:bg-warning/90",
+            info: "bg-info text-info-foreground focus-visible:ring-info/20 dark:focus-visible:ring-info/40 [a]:hover:bg-info/90",
             outline: "border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground",
-            // Three tones x three styles. The *-text tokens, never the solid
+            // Four tones x three styles. The *-text tokens, never the solid
             // fill tokens: `border-destructive`/`text-destructive` would use
             // the shade chosen to carry white text, which is too light to read
             // against the page in light mode and too dark in dark mode. See
             // styles/theme.css and conventions/docs/design-language.md.
             "outline-success": "border-success-text text-success-text",
             "outline-warning": "border-warning-text text-warning-text",
+            "outline-info": "border-info-text text-info-text",
             "outline-destructive": "border-destructive-text text-destructive-text",
             // The fill is the solid token at low alpha (a wash of the tone),
             // while the text is the *-text shade — mixing the two is the point.
@@ -25,6 +27,7 @@ const badgeVariants = cva("group/badge inline-flex h-5 w-fit shrink-0 items-cent
             // against a near-black page.
             "tinted-success": "bg-success/15 text-success-text dark:bg-success/20",
             "tinted-warning": "bg-warning/15 text-warning-text dark:bg-warning/20",
+            "tinted-info": "bg-info/15 text-info-text dark:bg-info/20",
             "tinted-destructive": "bg-destructive/15 text-destructive-text dark:bg-destructive/20",
             ghost: "hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50",
             link: "text-primary underline-offset-4 hover:underline",

package/dist/components/ui/sidebar.js

@@ -182,12 +182,17 @@ const sidebarMenuButtonVariants = cva("peer/menu-button group/menu-button flex w
 });
 function SidebarMenuButton({ render, isActive = false, variant = "default", size = "default", tooltip, className, ...props }) {
     const { isMobile, state } = useSidebar();
+    // Patched (ui-foundation): upstream keeps the tooltip on mobile and only
+    // hides its content, so keyboard focus still opened an invisible tooltip
+    // and the first Escape closed that instead of the sidebar sheet. On
+    // mobile the label is always visible, so there is no tooltip at all.
+    const hasTooltip = !!tooltip && !isMobile;
     const comp = useRender({
         defaultTagName: "button",
         props: mergeProps({
             className: cn(sidebarMenuButtonVariants({ variant, size }), className),
         }, props),
-        render: !tooltip ? render : _jsx(TooltipTrigger, { render: render }),
+        render: !hasTooltip ? render : _jsx(TooltipTrigger, { render: render }),
         state: {
             slot: "sidebar-menu-button",
             sidebar: "menu-button",
@@ -195,7 +200,7 @@ function SidebarMenuButton({ render, isActive = false, variant = "default", size
             active: isActive,
         },
     });
-    if (!tooltip) {
+    if (!hasTooltip) {
         return comp;
     }
     if (typeof tooltip === "string") {
@@ -203,7 +208,7 @@ function SidebarMenuButton({ render, isActive = false, variant = "default", size
             children: tooltip,
         };
     }
-    return (_jsxs(Tooltip, { children: [comp, _jsx(TooltipContent, { side: "right", align: "center", hidden: state !== "collapsed" || isMobile, ...tooltip })] }));
+    return (_jsxs(Tooltip, { children: [comp, _jsx(TooltipContent, { side: "right", align: "center", hidden: state !== "collapsed", ...tooltip })] }));
 }
 function SidebarMenuAction({ className, render, showOnHover = false, ...props }) {
     return useRender({

package/package.json

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

package/styles/index.css

@@ -44,6 +44,9 @@
     --color-warning: var(--warning);
     --color-warning-foreground: var(--warning-foreground);
     --color-warning-text: var(--warning-text);
+    --color-info: var(--info);
+    --color-info-foreground: var(--info-foreground);
+    --color-info-text: var(--info-text);
     --color-category-1: var(--category-1);
     --color-category-2: var(--category-2);
     --color-category-3: var(--category-3);

package/styles/theme.css

@@ -53,6 +53,9 @@
   --amber-700: oklch(0.555 0.163 48.998); /* white on it: 5.05 */
   --amber-800: oklch(0.47 0.14 48.998); /* on white: 7.20 */
   --amber-400: oklch(0.828 0.189 84.429); /* on near-black: 11.53 */
+  --blue-700: oklch(0.52 0.17 255); /* white on it: 5.59 */
+  --blue-800: oklch(0.45 0.15 255); /* on white: 7.54 */
+  --blue-400: oklch(0.75 0.12 255); /* on near-black: 8.90 */
   /*
    * Categorical slots. For values that differ from each other but are not
    * better or worse than each other — a genre, a team, a category. Tones
@@ -65,7 +68,8 @@
    *
    * Hues avoid the red and green bands that destructive/success already
    * spend, and the amber that warning does — a category drawn in red reads
-   * as "bad". They are ordered by distinctness, not by hue angle, so an app
+   * as "bad". The blue slots (1, 6, 8) sit near info's hue, which came
+   * later: a table using info keeps its categories off those three. They are ordered by distinctness, not by hue angle, so an app
    * using only the first three gets three obviously different colours.
    * Past about five, hue alone stops separating them and the glyph has to
    * carry the meaning; see docs/design-language.md.
@@ -116,7 +120,9 @@
   --success-foreground: var(--white);
   --warning: var(--amber-700);
   --warning-foreground: var(--white);
-  /* The three pairs above are a SOLID fill plus its own text color, and
+  --info: var(--blue-700);
+  --info-foreground: var(--white);
+  /* The four pairs above are a SOLID fill plus its own text color, and
      nothing else. Used as text or a border on the page's own background —
      an outline badge, a tinted chip, an icon tint — a fill shade is the
      wrong value: it was picked to carry white, not to read against the
@@ -125,6 +131,7 @@
   --destructive-text: var(--red-700);
   --success-text: var(--green-800);
   --warning-text: var(--amber-800);
+  --info-text: var(--blue-800);
   /* Categorical slots — a glyph tint, never a fill behind text. */
   --category-1: var(--category-1-700);
   --category-2: var(--category-2-700);
@@ -175,12 +182,15 @@
   --success-foreground: var(--white);
   --warning: var(--amber-700);
   --warning-foreground: var(--white);
+  --info: var(--blue-700);
+  --info-foreground: var(--white);
   /* Solid fills keep one shade in both themes — they always carry white
      text, so the page behind them never enters the calculation. Only the
      *-text shades flip, because those read against the page. */
   --destructive-text: var(--red-400);
   --success-text: var(--green-400);
   --warning-text: var(--amber-400);
+  --info-text: var(--blue-400);
   /* Categorical slots — lighter shades to read against the dark page. */
   --category-1: var(--category-1-400);
   --category-2: var(--category-2-400);