@tristan2828/ui-foundation 4.9.1 → 4.11.0

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

@@ -265,6 +265,18 @@ is a filled-in example while the Widgets demo is still here).
      view is `rail`, with Details in the rail. The rail's sections come
      first in the page (header, rail, main) at every width, so the
      view's specs find them first too.
+   - **A notice** (`notice`), only when the plan names a state that
+     decides what you do with the record (held, overdue, archived and
+     read-only): a `<Notice tone=…>` saying what it means and what to do,
+     with at most one action. It goes under the header, across the page.
+     Pass `null` when the state doesn't hold; the view announces it
+     appearing or clearing. A badge still shows the state itself; the
+     notice is for the few states a badge is too quiet for.
+   - **A source credit** (`footer`), only when the record's data comes
+     from an outside service whose terms ask for one (many free APIs
+     do: a film database, a games catalogue): `<SourceCredit sources={[{
+     name, href, note }]} />`, with `note` the sentence the terms ask for,
+     word for word. Logos and their rules are the app's own.
    - **Every value renders the way its table cell does**: badges, names
      of linked records, a done-count, from the shared lookups in
      `<entity>-format.ts`. Never re-derive one for the view.

package/conventions/docs/cell-patterns.md

@@ -10,11 +10,13 @@ alternatives ([`column-options.md`](column-options.md)), not designed in the abs
 Patterns 12 (boolean), 15 (yes/no flipped in the row), 16 (title linking
 to its view), 17 (quick action on the view) and 18 (editable value) are
 the template's own references: Widget's In Stock and Name columns and its
-view render them, and their specs pin them. Patterns 19 (stage circle)
-and 20 (count linking to the related records), the multi-value variant
-of 4, the dependency list in 10 and the pressed icon in 15 were each
-built for a real app's screen first; the package's Storybook renders
-them (`app/StageCircle`, `app/CountLink`, `patterns/CellPatterns`), and
+view render them, and their specs pin them. Patterns 19 (stage circle),
+20 (count linking to the related records) and 22 (a highlighted row),
+the multi-value variant of 4, the step bar and star in 9, the dependency
+list in 10, the ring in 13 and the pressed icon in 15 were each built
+for a real app's screen first; the package's Storybook renders
+them (`app/StageCircle`, `app/CountLink`, `patterns/CellPatterns`,
+`patterns/Scales`, `app/DataTable`), and
 its checks pin their accessibility and contrast in both themes. The
 other patterns from 11 on are marked **Unproven**: written ahead of a
 real column, so no app has tested them on real data yet. Prefer a proven
@@ -281,6 +283,38 @@ own state.
   does not check icon contrast. That's a defensible choice — make it
   deliberately, in a comment, not by accident.
 
+### Two variants the package draws: a step bar and a star
+
+Both are in the package's Storybook (`patterns/Scales`), every value on
+the page and on a card, measured by axe and the glyph check in both
+themes. Each is one image to a screen reader, named in words.
+
+- **`StepBar`, an ordered enum of a few bands** (best to worst): a short
+  bar of steps, the first `value` filled in `foreground`, the rest the
+  track (`border`), with the band's word beside it in `muted-foreground`.
+  Narrower than five stars, and it reads as a scale, not a rating. Its
+  name says both: `label="Quality: High, 4 of 5"` (the default is
+  "High, 4 of 5", enough where the column header names the field).
+
+  ```tsx
+  const QUALITY: Record<Quality, { word: string; value: number }> = {
+    best: { word: 'Best', value: 5 }, high: { word: 'High', value: 4 }, /* … */
+  }
+  <StepBar value={QUALITY[q].value} word={QUALITY[q].word} />
+  ```
+
+- **`RatingStar`, a three-value enum** (yes / partly / no): a full, half
+  or empty star with the word beside it. The shape carries the value, so
+  it survives greyscale. The half is the left half filled over the whole
+  outline, never half a star: alone, half a star reads as broken.
+
+  ```tsx
+  <RatingStar value={OWNED[o].value /* 'full' | 'half' | 'empty' */} word={OWNED[o].word} />
+  ```
+
+- Both draw in `foreground`. Tone one only as pattern 5 would (a `*-text`
+  class in `className`), never by band alone.
+
 ## 10. Summary in the cell, detail in a popover
 
 A one-to-many value (`★ 4.7 (3)` opening a per-person breakdown).
@@ -414,6 +448,24 @@ A percentage, or a count out of a total (`7 of 12 done`).
 - **Cost:** a bar takes far more width than the number it replaces. On a
   wide table, the plain number from pattern 11 usually wins.
 
+### The compact form: `ProgressRing`
+
+Done out of total (a checklist, how far through an ordered list, the
+steps of a process) as a small ring filling clockwise beside the count
+("4/6"). Proven in an app's table cells and on its view; the package
+ships it, so this needs no `progress` install.
+
+```tsx
+<ProgressRing done={row.original.doneCount} total={row.original.itemCount} />
+```
+
+- The arc is `foreground` while under way and `success-text` once
+  complete, on a `border` track; the count is in tabular numbers. Zero
+  of zero shows the empty ring and reads "Not started".
+- Its name is "4 of 6 done" unless `label` says better ("4 of 6 chapters
+  read"). The count beside it is `aria-hidden`: the name already says it.
+- Prefer it to the bar in a table: it's as narrow as the count.
+
 ## 14. Avatar and name — *Unproven*
 
 A person: an assignee or an owner.
@@ -1155,3 +1207,34 @@ const { page, filters, setFilter, setPage } = useTableUrlState(['kind'])
   filter, with a button to take it off. An empty group never renders:
   groups come from the rows.
 - **Not built:** collapsing groups, grouping by more than one key.
+
+## 22. A highlighted row, and rows that are done
+
+One row of a table marked as **the one to look at**: next up, the
+current one. `DataTable`'s `highlightRow` returns true for it.
+
+```tsx
+<DataTable highlightRow={(book) => book.id === nextUpId} … />
+```
+
+- **A wash of info on every cell**, over the zebra stripe and the pinned
+  columns' opaque backgrounds (`--table-highlight`, pre-mixed onto the
+  page), and a bar in `info-text` at the row's start, so it reads without
+  colour too. Still **say why in the row** (a "Next up" word or badge):
+  the wash says "look here", not what it is.
+- **Muted text inside it is darkened for you.** `muted-foreground`
+  measures 4.09:1 on the wash, under 4.5:1, and no lighter wash fixes it
+  (4.47:1 even at 4%). So the row redefines `--muted-foreground` as
+  `--table-highlight-muted-foreground`: 6.75:1 in light, the usual grey in
+  dark (6.61:1). Use `text-muted-foreground` as anywhere else.
+- **At most a row or two.** A highlight on every other row highlights
+  nothing; a state many rows share is a column (pattern 5).
+- **Rows that are done: colour, not opacity.** Greying finished rows with
+  `opacity-50` (or `text-foreground/60`) drops their text under 4.5:1 the
+  same way. Render their text in `text-muted-foreground`, which is
+  measured, and keep the word that says done.
+- Storybook's `app/DataTable` Highlighted story has two highlighted rows
+  (one striped), pinned columns and muted text inside them, under axe and
+  the token check in both themes; `e2e/data-table.spec.ts` checks every
+  cell wears the wash.
+

package/conventions/docs/design-language.md

@@ -346,3 +346,33 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
 - Storybook's `app/WidgetCard` shows three widgets on a page and every
   one in each state; its checks run axe and the token and glyph checks in
   both themes and at `large`.
+
+## Notices
+
+A `Notice` says, across the page, a state that decides what you do with
+what's on it: held, overdue, archived and read-only. It's louder than a
+badge and stays until the state changes, unlike a toast. `EntityView`'s
+`notice` is its usual place (under the header); any page can render one
+under its own header.
+
+```tsx
+<Notice tone="warning" title="On hold" action={<Button size="sm" variant="outline">Release the hold</Button>}>
+  Read “Hyperion” first: this one follows it.
+</Notice>
+```
+
+- **The tone is the state's**, from the same grouping as its badge
+  (warning for held, destructive for overdue, info for "up next", success
+  rarely: a good state seldom needs saying across the page). `icon`
+  swaps the tone's own icon for a better one (a lock for read-only).
+- **A wash, not a fill:** the tone at 10% (20% in dark) with `foreground`
+  text and the tone's `*-text` icon. The message reads as body text, so
+  nothing inside it is muted. Storybook's `app/Notice` measures every
+  tone with axe and the glyph check in both themes.
+- **One or two sentences and at most one action**: what the state means
+  and what to do about it. More than that belongs in a section.
+- **Not an alert.** A notice there when the page opens is part of the
+  page, so it has no role of its own. `EntityView` keeps a `role="status"`
+  region in its place, so one appearing or clearing later is announced.
+  Elsewhere, put it in a status region that is rendered before it
+  changes.

package/dist/components/app/data-table.d.ts

@@ -90,6 +90,13 @@ export type DataTableProps<TData extends Record<string, unknown>> = {
      * still get the column names; sorting moves to the toolbar.
      */
     header?: boolean;
+    /**
+     * The one row to look at (next up, the current one): tinted with info's
+     * wash, a bar in `info-text` at its start, and muted text inside it
+     * darkened so it still clears 4.5:1. Return true for at most a row or two.
+     * Colour isn't the only signal: say why in the row too (a badge, a word).
+     */
+    highlightRow?: (row: TData) => boolean;
 };
 export type DataTableWidth = 'full' | 'content';
-export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width, groupBy, groupSummary, header: showHeader, }: DataTableProps<TData>): import("react").JSX.Element;
+export declare function DataTable<TData extends Record<string, unknown>>({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width, groupBy, groupSummary, header: showHeader, highlightRow, }: DataTableProps<TData>): import("react").JSX.Element;

package/dist/components/app/data-table.js

@@ -75,6 +75,13 @@ const PINNED_FIRST_CONTENT_CLASS = 'max-md:max-w-[45cqw] max-md:whitespace-norma
 // background so it reads identically on striped and unstriped rows, and it
 // stays on screen when the table is scrolled right.
 const ROW_GROUP_CLASS = 'group/row hover:bg-transparent';
+// `highlightRow`: the wash on every cell, so it covers the zebra stripe
+// (on the row) and the pinned cells' opaque backgrounds (on the cell, and
+// one class weaker than this), while a pinned cell's hover still wins. A
+// bar on the first cell, as hover's is, so it reads without colour too.
+// Inside, muted text takes the darker grey the wash needs (theme.css).
+const HIGHLIGHTED_ROW_CLASS = '[--muted-foreground:var(--table-highlight-muted-foreground)] [&>td]:bg-(--table-highlight) ' +
+    '[&>td:first-child]:shadow-[inset_3px_0_0_0_var(--info-text)]';
 // `header={false}`: the header row stays in the table, so every cell keeps
 // its column header for a screen reader, but takes no room: each header
 // is its name in an sr-only span, in a cell with no height or padding.
@@ -150,7 +157,7 @@ function useBottomScrollbar(containerRef, isSuccessView) {
     }, [containerRef, isSuccessView, isOverflowing]);
     return { barRef, isOverflowing, scrollWidth };
 }
-export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width = 'full', groupBy, groupSummary, header: showHeader = true, }) {
+export function DataTable({ columns, data, total, page, pageSize, onPageChange, sorting, onSortingChange, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, toolbar, getRowId, pinFirstColumn, pinLastColumn, enableSortingRemoval, visibleColumns, width = 'full', groupBy, groupSummary, header: showHeader = true, highlightRow, }) {
     // Editing in place in the rows (cell pattern 18, "In a table's rows"):
     // a cell that renders an <EditableValue> edits where it's shown, one at
     // a time, with the leave-page prompt while one is open, the same rules
@@ -211,7 +218,7 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
     const rows = table.getRowModel().rows;
     const visibleColumnCount = table.getVisibleLeafColumns().length;
     // One body row, the same in a plain table and a grouped one.
-    const renderRow = (row) => (_jsx(TableRow, { className: cn(pinFirstColumn && ROW_GROUP_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn && index === row.getVisibleCells().length - 1 && PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: flexRender(cell.column.columnDef.cell, cell.getContext()) })) : (flexRender(cell.column.columnDef.cell, cell.getContext())) }, cell.id))) }, row.id));
+    const renderRow = (row) => (_jsx(TableRow, { "data-highlighted": highlightRow?.(row.original) || undefined, className: cn(pinFirstColumn && ROW_GROUP_CLASS, highlightRow?.(row.original) && HIGHLIGHTED_ROW_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn && index === row.getVisibleCells().length - 1 && PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: pinFirstColumn && index === 0 ? (_jsx("div", { className: PINNED_FIRST_CONTENT_CLASS, children: flexRender(cell.column.columnDef.cell, cell.getContext()) })) : (flexRender(cell.column.columnDef.cell, cell.getContext())) }, cell.id))) }, row.id));
     const content = (_jsxs("div", { ref: root, className: cn('flex flex-col gap-4', width === 'content' && CONTENT_WIDTH_CLASS), "data-width": width, style: width === 'content' && !isSuccessView && lastWidth !== null
             ? { '--data-table-last-width': `${lastWidth}px` }
             : undefined, children: [toolbar, error ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : isLoading || isPastLastPage ? (_jsx(TableSkeleton, { columnCount: table.getVisibleLeafColumns().length })) : isEmpty ? (_jsxs(Empty, { "data-state": "empty", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction] })) : (_jsxs(_Fragment, { children: [_jsxs(Table, { "data-state": "success", containerRef: containerRef, 

package/dist/components/app/entity-view.d.ts

@@ -67,7 +67,19 @@ export type EntityViewProps = {
     badges?: ReactNode;
     /** The header's actions: an Edit button, a Delete with its confirm dialog. */
     actions?: ReactNode;
+    /**
+     * A state that decides what you do with the record, said before
+     * anything else (a `<Notice>`): under the header, across the page at
+     * every width. Announced when it appears or changes after the page loads.
+     */
+    notice?: ReactNode;
     sections: EntityViewSection[];
+    /**
+     * Below every section (both columns in the rail layout), in small muted
+     * type outside any card: where the record's data comes from
+     * (`<SourceCredit>`), when its source's terms ask for a credit.
+     */
+    footer?: ReactNode;
     /** `rail` puts the sections placed `rail` in a column on the right. Defaults to `column`. */
     layout?: EntityViewLayout;
     /** The rail's landmark name (its `<aside>`). Defaults to the title + " details". */
@@ -82,4 +94,4 @@ export type EntityViewProps = {
         label: string;
     };
 };
-export declare function EntityView({ title, titleEdit, badges, actions, sections, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;
+export declare function EntityView({ title, titleEdit, badges, actions, notice, sections, footer, layout, railLabel, isLoading, error, onRetry, back, }: EntityViewProps): import("react").JSX.Element;

package/dist/components/app/entity-view.js

@@ -29,6 +29,10 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // autosave as it's typed (`autosave`), and be the editor itself, with no
 // click to open (`alwaysEditable`).
 //
+// Around the sections: `notice` (a <Notice>) under the header, across the
+// page, for a state that decides what you do with the record; `footer`
+// (a <SourceCredit>) after them all, for crediting the data's source.
+//
 // Two layouts. `column` (the default): every section in one column capped
 // at max-w-4xl. `rail`, for a record with long content: the page takes the
 // content area's whole width, sections placed `rail` go in a narrow column
@@ -136,7 +140,7 @@ function Rail({ label, sections }) {
     const [ref, fits] = useFitsWindow();
     return (_jsx("aside", { ref: ref, "aria-label": label, "data-fits": fits ? '' : undefined, className: cn(RAIL_LAYOUT.rail, RAIL_LAYOUT.sticky, 'flex min-w-0 flex-col gap-6'), children: sections.map((section) => (_jsx(ViewSection, { section: section, inRail: true }, section.title))) }));
 }
-export function EntityView({ title, titleEdit, badges, actions, sections, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
+export function EntityView({ title, titleEdit, badges, actions, notice, sections, footer, layout = 'column', railLabel, isLoading, error, onRetry, back, }) {
     // Editing in place: one store per view, and the leave-page prompt only
     // while a field is open (or one is always editable).
     const [store] = useState(() => new EditInPlaceStore());
@@ -152,5 +156,5 @@ export function EntityView({ title, titleEdit, badges, actions, sections, layout
         return _jsx(EntityViewSkeleton, { layout: layout });
     const railSections = sections.filter((section) => section.placement === 'rail');
     const mainSections = sections.filter((section) => section.placement !== 'rail');
-    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title)))] }) }));
+    return (_jsx(EditInPlaceContext.Provider, { value: store, children: _jsxs("div", { className: layout === 'rail' ? RAIL_LAYOUT.page : 'flex max-w-4xl flex-col gap-6', "data-state": "success", "data-layout": layout, children: [editing && _jsx(LeaveGuard, { store: store }), _jsx(BackLink, { back: back }), _jsxs("header", { className: "flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between", children: [_jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: [_jsx("h1", { className: "type-page-title break-words text-foreground", children: titleEdit ? (_jsx(EditableValue, { label: titleEdit.label, edit: titleEdit, layout: "inline", className: "w-full", children: title })) : (title) }), badges && _jsx("div", { className: "flex flex-wrap items-center gap-1.5", children: badges })] }), actions && _jsx("div", { className: "flex shrink-0 flex-wrap items-center gap-2", children: actions })] }), _jsx("div", { role: "status", "data-slot": "entity-view-notice", className: "empty:hidden", children: notice }), layout === 'rail' ? (_jsxs("div", { className: RAIL_LAYOUT.columns, children: [railSections.length > 0 && (_jsx(Rail, { label: railLabel ?? `${title ?? 'Record'} details`, sections: railSections })), _jsx("div", { className: cn(RAIL_LAYOUT.main, railSections.length === 0 && RAIL_LAYOUT.mainAlone), children: mainSections.map((section) => (_jsx(ViewSection, { section: section }, section.title))) })] })) : (sections.map((section) => _jsx(ViewSection, { section: section }, section.title))), footer && (_jsx("footer", { "data-slot": "entity-view-footer", className: "type-caption text-muted-foreground", children: footer }))] }) }));
 }

package/dist/components/app/notice.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import { type LucideIcon } from 'lucide-react';
+export type NoticeTone = 'info' | 'success' | 'warning' | 'destructive';
+export type NoticeProps = {
+    /** What kind of state it is (design-language.md "Semantic tones"). Defaults to `info`. */
+    tone?: NoticeTone;
+    /** A short lead in bold ("On hold"), before the message. */
+    title?: ReactNode;
+    /** The message: one or two sentences saying what to do about it. */
+    children: ReactNode;
+    /** One way to act on it: a link or a small button (`<Button size="sm" variant="outline">`). */
+    action?: ReactNode;
+    /** Another icon than the tone's own, when the state has a better one (a lock for read-only). */
+    icon?: LucideIcon;
+    className?: string;
+};
+export declare function Notice({ tone, title, children, action, icon, className }: NoticeProps): import("react").JSX.Element;

package/dist/components/app/notice.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CircleAlertIcon, CircleCheckIcon, InfoIcon, TriangleAlertIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Alert, AlertDescription, AlertTitle } from '../ui/alert.js';
+const TONE = {
+    info: { surface: 'border-info-text/30 bg-info/10 dark:bg-info/20', icon: 'text-info-text', Icon: InfoIcon },
+    success: {
+        surface: 'border-success-text/30 bg-success/10 dark:bg-success/20',
+        icon: 'text-success-text',
+        Icon: CircleCheckIcon,
+    },
+    warning: {
+        surface: 'border-warning-text/30 bg-warning/10 dark:bg-warning/20',
+        icon: 'text-warning-text',
+        Icon: TriangleAlertIcon,
+    },
+    destructive: {
+        surface: 'border-destructive-text/30 bg-destructive/10 dark:bg-destructive/20',
+        icon: 'text-destructive-text',
+        Icon: CircleAlertIcon,
+    },
+};
+export function Notice({ tone = 'info', title, children, action, icon, className }) {
+    const look = TONE[tone];
+    const Icon = icon ?? look.Icon;
+    return (_jsxs(Alert, { role: undefined, "data-slot": "notice", "data-tone": tone, 
+        // Flex, not Alert's grid, so the action wraps under the message on a
+        // narrow screen instead of squeezing it.
+        className: cn('flex flex-wrap items-start gap-x-3 gap-y-2 px-4 py-3 text-foreground', look.surface, className), children: [_jsx("span", { className: cn('mt-0.5 shrink-0', look.icon), children: _jsx(Icon, { "aria-hidden": "true", className: "size-4" }) }), _jsxs("div", { className: "flex min-w-0 flex-1 basis-48 flex-col gap-0.5", children: [title && _jsx(AlertTitle, { className: "font-semibold", children: title }), _jsx(AlertDescription, { className: "text-foreground", children: children })] }), action && _jsx("div", { className: "flex shrink-0 items-center gap-2 pl-7 sm:pl-0", children: action })] }));
+}

package/dist/components/app/progress-ring.d.ts

@@ -0,0 +1,12 @@
+export type ProgressRingProps = {
+    /** How many are done. Clamped to 0…total. */
+    done: number;
+    /** How many there are. Zero of zero reads as not started. */
+    total: number;
+    /** What a screen reader hears. Defaults to "4 of 6 done", or "Not started" for zero of zero. */
+    label?: string;
+    /** Hide the count beside the ring (the ring's name still says it). */
+    hideCount?: boolean;
+    className?: string;
+};
+export declare function ProgressRing({ done, total, label, hideCount, className }: ProgressRingProps): import("react").JSX.Element;

package/dist/components/app/progress-ring.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Done out of total (cell pattern 13's compact form): a small ring that
+// fills clockwise from twelve o'clock, with the count beside it ("4/6").
+// Narrow enough for a table column, readable on a view: a checklist, how
+// far through an ordered list someone is, the steps of a process.
+//
+// The arc is the ink (currentColor: `foreground` while under way,
+// `success-text` once complete), so it clears 3:1 on the page in both
+// themes; the track is `border`, decoration only, the same ring empty.
+// The count carries the value exactly, the ring roughly, and the whole is
+// one image to a screen reader, named in words.
+import { cn } from 'cn';
+// 16×16, the stage circle's grid: a thick ring of radius 6 so the arc
+// reads at 16px.
+const R = 6;
+const CIRCUMFERENCE = 2 * Math.PI * R;
+const STROKE = 2.5;
+export function ProgressRing({ done, total, label, hideCount = false, className }) {
+    const safeTotal = Math.max(0, total);
+    const safeDone = Math.min(Math.max(0, done), safeTotal);
+    const complete = safeTotal > 0 && safeDone === safeTotal;
+    const fraction = safeTotal === 0 ? 0 : safeDone / safeTotal;
+    const name = label ?? (safeTotal === 0 ? 'Not started' : `${safeDone} of ${safeTotal} done`);
+    return (_jsxs("span", { role: "img", "aria-label": name, "data-slot": "progress-ring", "data-complete": complete || undefined, className: cn('inline-flex shrink-0 items-center gap-1.5 tabular-nums', complete ? 'text-success-text' : 'text-foreground', className), children: [_jsxs("svg", { viewBox: "0 0 16 16", "aria-hidden": "true", className: "size-4 shrink-0 -rotate-90", children: [_jsx("circle", { cx: "8", cy: "8", r: R, strokeWidth: STROKE, className: "fill-none stroke-border" }), fraction > 0 && (_jsx("circle", { cx: "8", cy: "8", r: R, strokeWidth: STROKE, strokeDasharray: `${fraction * CIRCUMFERENCE} ${CIRCUMFERENCE}`, 
+                        // A full ring with a round cap would show a seam; butt it then.
+                        strokeLinecap: complete ? 'butt' : 'round', className: "fill-none stroke-current" }))] }), !hideCount && safeTotal > 0 && (_jsxs("span", { "aria-hidden": "true", className: "type-caption", children: [safeDone, "/", safeTotal] }))] }));
+}

package/dist/components/app/rating-star.d.ts

@@ -0,0 +1,10 @@
+export type RatingStarValue = 'full' | 'half' | 'empty';
+export type RatingStarProps = {
+    value: RatingStarValue;
+    /** The value's word, shown beside the star ("Partly"). */
+    word?: string;
+    /** What a screen reader hears. Defaults to the word, else "Full star", "Half star" or "Empty star". */
+    label?: string;
+    className?: string;
+};
+export declare function RatingStar({ value, word, label, className }: RatingStarProps): import("react").JSX.Element;

package/dist/components/app/rating-star.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A three-value enum as one star (cell pattern 9's variant): yes, partly,
+// no as a full, half or empty star, with the word beside it. The shape
+// carries the value, so it survives greyscale. A half star alone reads as
+// broken, so it's drawn as the left half filled over the whole outline.
+//
+// The star is the ink (currentColor, `foreground` by default; pass a
+// `*-text` tone in `className` to tone it), clearing 3:1 on the page in
+// both themes. One image to a screen reader, named in words.
+import { useId } from 'react';
+import { cn } from 'cn';
+// Lucide's star (24×24), so it matches the icons around it.
+const STAR = 'M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z';
+const DEFAULT_NAME = {
+    full: 'Full star',
+    half: 'Half star',
+    empty: 'Empty star',
+};
+export function RatingStar({ value, word, label, className }) {
+    const clipId = useId();
+    return (_jsxs("span", { role: "img", "aria-label": label ?? word ?? DEFAULT_NAME[value], "data-slot": "rating-star", "data-value": value, className: cn('inline-flex shrink-0 items-center gap-1.5 text-foreground', className), children: [_jsxs("svg", { viewBox: "0 0 24 24", "aria-hidden": "true", className: "size-4 shrink-0", children: [value === 'half' && (_jsx("defs", { children: _jsx("clipPath", { id: clipId, children: _jsx("rect", { x: "0", y: "0", width: "12", height: "24" }) }) })), value !== 'empty' && (_jsx("path", { d: STAR, className: "fill-current", clipPath: value === 'half' ? `url(#${clipId})` : undefined })), _jsx("path", { d: STAR, className: "fill-none stroke-current", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" })] }), word && _jsx("span", { "aria-hidden": "true", children: word })] }));
+}

package/dist/components/app/source-credit.d.ts

@@ -0,0 +1,14 @@
+export type Source = {
+    /** The service's name, the link's text: "TMDB". */
+    name: string;
+    /** Its site; the link opens in a new tab. */
+    href: string;
+    /** A sentence the service's terms ask for, shown after the list as written. */
+    note?: string;
+};
+export type SourceCreditProps = {
+    sources: Source[];
+    /** What comes before the names. Defaults to "Data from". */
+    lead?: string;
+};
+export declare function SourceCredit({ sources, lead }: SourceCreditProps): import("react").JSX.Element | null;

package/dist/components/app/source-credit.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Credits the outside services a record's data comes from, as many free
+// APIs require on every screen showing their data ("This product uses the
+// TMDB API but is not endorsed or certified by TMDB"). EntityView's
+// `footer` is its usual home. Text and links only: a service's logo and
+// its usage rules are the app's.
+import { Fragment } from 'react';
+import { ExternalLinkIcon } from 'lucide-react';
+function joined(index, count) {
+    if (index === 0)
+        return '';
+    if (index === count - 1)
+        return count === 2 ? ' and ' : ', and ';
+    return ', ';
+}
+export function SourceCredit({ sources, lead = 'Data from' }) {
+    if (sources.length === 0)
+        return null;
+    const notes = sources.flatMap((source) => (source.note ? [source.note] : []));
+    return (_jsxs("p", { "data-slot": "source-credit", className: "type-caption text-muted-foreground", children: [lead, ' ', sources.map((source, index) => (_jsxs(Fragment, { children: [joined(index, sources.length), _jsxs("a", { href: source.href, target: "_blank", rel: "noreferrer", className: "rounded-sm underline underline-offset-2 outline-none hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50", children: [source.name, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "ml-0.5 inline size-3 align-baseline" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] })] }, source.name))), ".", notes.map((note) => ` ${note}`).join('')] }));
+}

package/dist/components/app/step-bar.d.ts

@@ -0,0 +1,16 @@
+export type StepBarProps = {
+    /** How many steps are filled, 0…steps. */
+    value: number;
+    /** How many steps the scale has. Defaults to 5. */
+    steps?: number;
+    /** The band's word, shown beside the bar ("High"). */
+    word?: string;
+    /**
+     * What a screen reader hears. Defaults to the word and the count
+     * ("High, 4 of 5"); pass the field's name in front when the cell
+     * doesn't give it ("Quality: High, 4 of 5").
+     */
+    label?: string;
+    className?: string;
+};
+export declare function StepBar({ value, steps, word, label, className }: StepBarProps): import("react").JSX.Element;

package/dist/components/app/step-bar.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// An ordered enum of a few bands, best to worst (cell pattern 9's
+// variant): a short bar of steps, the first `value` filled, with the
+// band's word beside it. Narrower than five stars, and reads as a scale,
+// not a rating. "Quality: High" as ■■■■□ High.
+//
+// The filled steps are the ink (currentColor, `foreground`), clearing 3:1
+// on the page in both themes; the empty steps are the track (`border`),
+// deliberately faint and carrying nothing on their own: the count of
+// filled steps and the word carry the value. One image to a screen
+// reader, named with both ("Quality: High, 4 of 5").
+import { cn } from 'cn';
+// Each step 4×8 with a 1.5 gap, in a 16-high box, so the bar sits on the
+// text's line like the other glyphs.
+const STEP_WIDTH = 4;
+const STEP_GAP = 1.5;
+const STEP_HEIGHT = 8;
+export function StepBar({ value, steps = 5, word, label, className }) {
+    const filled = Math.min(Math.max(0, Math.round(value)), steps);
+    const width = steps * STEP_WIDTH + (steps - 1) * STEP_GAP;
+    const name = label ?? `${word ? `${word}, ` : ''}${filled} of ${steps}`;
+    return (_jsxs("span", { role: "img", "aria-label": name, "data-slot": "step-bar", "data-value": filled, className: cn('inline-flex shrink-0 items-center gap-1.5 text-foreground', className), children: [_jsx("svg", { viewBox: `0 0 ${width} 16`, "aria-hidden": "true", className: "h-4 shrink-0", style: { width: `${width / 16}rem` }, children: Array.from({ length: steps }, (_, step) => (_jsx("rect", { x: step * (STEP_WIDTH + STEP_GAP), y: (16 - STEP_HEIGHT) / 2, width: STEP_WIDTH, height: STEP_HEIGHT, rx: "1", className: step < filled ? 'fill-current' : 'fill-border' }, step))) }), word && (_jsx("span", { "aria-hidden": "true", className: "text-muted-foreground", children: word }))] }));
+}

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

@@ -0,0 +1,10 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const alertVariants: (props?: ({
+    variant?: "default" | "destructive" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function Alert({ className, variant, ...props }: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>): React.JSX.Element;
+declare function AlertTitle({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function AlertDescription({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function AlertAction({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+export { Alert, AlertTitle, AlertDescription, AlertAction };

package/dist/components/ui/alert.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { cn } from "cn";
+const alertVariants = cva("group/alert relative grid w-full gap-0.5 rounded-lg border px-2.5 py-2 text-left text-sm has-data-[slot=alert-action]:relative has-data-[slot=alert-action]:pr-18 has-[>svg]:grid-cols-[auto_1fr] has-[>svg]:gap-x-2 *:[svg]:row-span-2 *:[svg]:translate-y-0.5 *:[svg]:text-current *:[svg:not([class*='size-'])]:size-4", {
+    variants: {
+        variant: {
+            default: "bg-card text-card-foreground",
+            // Patched (ui-foundation): upstream's text-destructive is the solid
+            // fill's shade, 3.2:1 on the dark card; text is --destructive-text.
+            destructive: "bg-card text-destructive-text *:data-[slot=alert-description]:text-destructive-text *:[svg]:text-current",
+        },
+    },
+    defaultVariants: {
+        variant: "default",
+    },
+});
+function Alert({ className, variant, ...props }) {
+    return (_jsx("div", { "data-slot": "alert", role: "alert", className: cn(alertVariants({ variant }), className), ...props }));
+}
+function AlertTitle({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "alert-title", className: cn("font-medium group-has-[>svg]/alert:col-start-2 [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground", className), ...props }));
+}
+function AlertDescription({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "alert-description", className: cn("text-sm text-balance text-muted-foreground md:text-pretty [&_a]:underline [&_a]:underline-offset-3 [&_a]:hover:text-foreground [&_p:not(:last-child)]:mb-4", className), ...props }));
+}
+function AlertAction({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "alert-action", className: cn("absolute top-2 right-2", className), ...props }));
+}
+export { Alert, AlertTitle, AlertDescription, AlertAction };

package/dist/index.d.ts

@@ -22,6 +22,11 @@ export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter, type PillFilterOption, type PillFilterProps } from './components/app/pill-filter.js';
 export { SecondaryFilters, type ActiveFilter, type SecondaryFiltersProps } from './components/app/secondary-filters.js';
 export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
+export { Notice, type NoticeProps, type NoticeTone } from './components/app/notice.js';
+export { SourceCredit, type Source, type SourceCreditProps } from './components/app/source-credit.js';
+export { ProgressRing, type ProgressRingProps } from './components/app/progress-ring.js';
+export { StepBar, type StepBarProps } from './components/app/step-bar.js';
+export { RatingStar, type RatingStarProps, type RatingStarValue } from './components/app/rating-star.js';
 export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';

package/dist/index.js

@@ -27,6 +27,11 @@ export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { PillFilter } from './components/app/pill-filter.js';
 export { SecondaryFilters } from './components/app/secondary-filters.js';
 export { StageCircle, } from './components/app/stage-circle.js';
+export { Notice } from './components/app/notice.js';
+export { SourceCredit } from './components/app/source-credit.js';
+export { ProgressRing } from './components/app/progress-ring.js';
+export { StepBar } from './components/app/step-bar.js';
+export { RatingStar } from './components/app/rating-star.js';
 export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.9.1",
+  "version": "4.11.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/theme.css

@@ -229,6 +229,13 @@
      matches the row without letting scrolled columns show through. Mixed
      in sRGB, as the browser composites the translucent stripe. */
   --table-stripe: color-mix(in srgb, var(--muted) 40%, var(--background));
+  /* A highlighted row (DataTable's highlightRow, #156): info's wash
+     pre-mixed onto the page, opaque so pinned cells can wear it. Muted
+     text measures 4.09:1 on it (below 4.5 at 12px; no lighter tint gets
+     there: 4.47 at 4%), so inside the row muted text takes a darker grey:
+     6.75:1. In dark the usual muted already clears it (6.61:1). */
+  --table-highlight: color-mix(in srgb, var(--info) 10%, var(--background));
+  --table-highlight-muted-foreground: var(--gray-600);
   --border: var(--gray-200);
   --input: var(--gray-200);
   --ring: var(--gray-400);
@@ -358,6 +365,8 @@
   --category-11: var(--category-11-400);
   --category-12: var(--category-12-400);
   --table-stripe: color-mix(in srgb, var(--muted) 40%, var(--background));
+  --table-highlight: color-mix(in srgb, var(--info) 20%, var(--background));
+  --table-highlight-muted-foreground: var(--gray-400); /* the usual muted: not var(--muted-foreground), which the row redefines from this */
   --border: var(--white-a10);
   --input: var(--white-a15);
   --ring: var(--gray-500);