@tristan2828/ui-foundation 4.10.0 → 4.12.0

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

@@ -121,7 +121,8 @@ is a filled-in example while the Widgets demo is still here).
    (`WIDGET_STATUS_LABELS`) read by the options, the trigger (through
    `<SelectValue>`'s children, which otherwise shows the raw value), the
    toolbar filter and every badge — a `date-time` copies
-   Available From's date picker, a `yes/no` copies In Stock — a `Switch`
+   Available From's date picker, a `date` (a day, no time) is the
+   foundation's `DateField` (see below), a `yes/no` copies In Stock — a `Switch`
    (`@tristan2828/ui-foundation/ui/switch`) in a horizontal `Field` with
    its label beside it on the form, cell pattern 12 (the word Yes/No) in
    the table, and a three-way toolbar `Select` (either / yes / no) whose URL
@@ -170,6 +171,21 @@ is a filled-in example while the Widgets demo is still here).
    that arrives later reaches the cells through context, as
    `category-names.tsx` does for category names.
 
+   **A `date`** (a day with no time: when something was finished, a
+   due day) is `type: string, format: date` in `openapi.yaml`, so the
+   wire, the generated type and the form all hold `'YYYY-MM-DD'`, and
+   `''` on the form for an optional one not set (sent as `null`). No
+   `Date` object anywhere, so no time zone can move the day. On the form
+   it's the foundation's `DateField` in a `Controller` (`clearable` when
+   optional); the schema is the string (`z.string().min(1, …)` when
+   required). The table and the view show `formatPlainDate(value)`
+   ("Sep 2, 2026"), the not-set label when empty. Editing in place is
+   `editInPlace({ kind: 'choice', ... })` with `DateField` as the
+   control, `defaultOpen`, `modal={false}`, `onChange={(day) =>
+   props.commit(day)}` and `onOpenChange` cancelling on close, as a
+   Select is (Storybook `app/DateField` EditInPlace). The backend column
+   is a SQL `date` (`datetime.date` in the model).
+
    **A `yes/no` marked `toggle`** copies In Stock's cell
    (`in-stock-toggle.tsx`, cell pattern 15): a `Switch` in its own
    component that PATCHes the one field through `useSaveWidgetField`, the

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/entity-plan-template.md

@@ -47,7 +47,10 @@ One or two sentences: what one record is, and who uses the screens.
     (cell pattern 20) and which of them it counts (`open tasks`).
   - *Close variants* (built by a small, stated change to the nearest
     pattern): `integer` (from decimal), `url` (from email — a format
-    check), `date` (from date-time — no time part).
+    check).
+  - *From the package, no Widget example:* `date` (a calendar day, no
+    time: OpenAPI `format: date`; the foundation's `DateField`; say
+    whether it's optional).
   - *Not supported yet:* a yes/no that can also be unset (three states),
     file, and anything else.
     Write it anyway with a note; the playbook will stop and raise it

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/date-field.d.ts

@@ -0,0 +1,31 @@
+import { type PlainDate } from '../../lib/plain-date.js';
+export type DateFieldProps = {
+    /** The trigger button's id, for the field's `<FieldLabel htmlFor>`. */
+    id?: string;
+    /** `'YYYY-MM-DD'`, or `''` for not set. */
+    value: PlainDate;
+    /** Called with the picked day as `'YYYY-MM-DD'`, or `''` when cleared. */
+    onChange: (value: PlainDate) => void;
+    /** What the button says with no day set. Defaults to "Pick a date". */
+    placeholder?: string;
+    /** Offer Clear in the calendar, for an optional field. */
+    clearable?: boolean;
+    /** The value was refused: `aria-invalid` on the button. */
+    invalid?: boolean;
+    /** Saving: the button shows the day but won't open. */
+    readOnly?: boolean;
+    /** Open on mount: editing in place, where the calendar opens with the field. */
+    defaultOpen?: boolean;
+    /** Passed to the Popover; `false` when editing in place, as for a Select. */
+    modal?: boolean;
+    /** Told when the calendar opens or closes; editing in place gives up on a close with nothing picked. */
+    onOpenChange?: (open: boolean) => void;
+    /** How the day is shown on the button. Defaults to `{ dateStyle: 'medium' }`. */
+    format?: Intl.DateTimeFormatOptions;
+    locale?: string;
+    className?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+};
+export declare function DateField({ id, value, onChange, placeholder, clearable, invalid, readOnly, defaultOpen, modal, onOpenChange, format, locale, className, ...aria }: DateFieldProps): import("react").JSX.Element;

package/dist/components/app/date-field.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A plain date, no time: when something was finished, a due day. The value
+// is the wire's own `'YYYY-MM-DD'` (OpenAPI `format: date`), or `''` for
+// not set, and it's read as a calendar day, never an instant: nothing here
+// goes through the browser's time zone, so Sep 2 is Sep 2 everywhere.
+//
+// A button showing the day, opening the package's Calendar in a Popover.
+// One control for the form (a react-hook-form `Controller`) and for
+// editing in place (`editInPlace({ kind: 'choice' })`: picking a day saves,
+// and the calendar opens with the field). `clearable` adds Clear for an
+// optional field.
+import { useRef, useState } from 'react';
+import { CalendarIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Calendar } from '../ui/calendar.js';
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover.js';
+import { formatPlainDate, localToPlainDate, plainDateToLocal } from '../../lib/plain-date.js';
+export function DateField({ id, value, onChange, placeholder = 'Pick a date', clearable = false, invalid = false, readOnly = false, defaultOpen = false, modal, onOpenChange, format, locale, className, ...aria }) {
+    const [open, setOpen] = useState(defaultOpen && !readOnly);
+    const popup = useRef(null);
+    const selected = plainDateToLocal(value);
+    const shown = formatPlainDate(value, format, locale);
+    const changeOpen = (next) => {
+        if (next && readOnly)
+            return;
+        setOpen(next);
+        onOpenChange?.(next);
+    };
+    const pick = (next) => {
+        onChange(next);
+        changeOpen(false);
+    };
+    return (_jsxs(Popover, { open: open, onOpenChange: changeOpen, modal: modal, children: [_jsxs(PopoverTrigger, { render: _jsx(Button, { id: id, type: "button", variant: "outline", "aria-invalid": invalid || undefined, "aria-readonly": readOnly || undefined, className: cn('w-full justify-start font-normal', !shown && 'text-muted-foreground', className), ...aria }), children: [_jsx(CalendarIcon, { "aria-hidden": "true", className: "size-4" }), shown || placeholder] }), _jsxs(PopoverContent, { ref: popup, className: "w-auto p-0", "data-slot": "date-field-calendar", 
+                // The day the keyboard starts from (the chosen one, else today):
+                // the one day react-day-picker makes tabbable. The popup would
+                // otherwise take focus itself, past the Calendar's autoFocus.
+                initialFocus: () => popup.current?.querySelector('button[data-day][tabindex="0"]') ?? true, children: [_jsx(Calendar, { mode: "single", 
+                        // Picking the chosen day again keeps it (and closes), never unsets it: Clear does that.
+                        required: true, selected: selected, defaultMonth: selected, onSelect: (date) => pick(localToPlainDate(date)) }), clearable && value && (_jsx("div", { className: "border-t border-border p-2", children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", className: "w-full", onClick: () => pick(''), children: "Clear" }) }))] })] }));
+}

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/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/calendar.js

@@ -68,7 +68,15 @@ function CalendarDayButton({ className, day, modifiers, locale, ...props }) {
         if (modifiers.focused)
             ref.current?.focus();
     }, [modifiers.focused]);
-    return (_jsx(Button, { variant: "ghost", size: "icon", "data-day": day.date.toLocaleDateString(locale?.code), "data-selected-single": modifiers.selected &&
+    return (_jsx(Button
+    // Patched (ui-foundation, #157): upstream makes this ref but never
+    // passes it, so the effect above focused nothing and the arrow keys
+    // moved react-day-picker's focused day without moving focus.
+    , { 
+        // Patched (ui-foundation, #157): upstream makes this ref but never
+        // passes it, so the effect above focused nothing and the arrow keys
+        // moved react-day-picker's focused day without moving focus.
+        ref: ref, variant: "ghost", size: "icon", "data-day": day.date.toLocaleDateString(locale?.code), "data-selected-single": modifiers.selected &&
             !modifiers.range_start &&
             !modifiers.range_end &&
             !modifiers.range_middle, "data-range-start": modifiers.range_start, "data-range-end": modifiers.range_end, "data-range-middle": modifiers.range_middle, className: cn("relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 data-[range-end=true]:rounded-(--cell-radius) data-[range-end=true]:rounded-r-(--cell-radius) data-[range-end=true]:bg-primary data-[range-end=true]:text-primary-foreground data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-muted data-[range-middle=true]:text-foreground data-[range-start=true]:rounded-(--cell-radius) data-[range-start=true]:rounded-l-(--cell-radius) data-[range-start=true]:bg-primary data-[range-start=true]:text-primary-foreground data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-foreground [&>span]:text-xs [&>span]:opacity-70", defaultClassNames.day, className), ...props }));

package/dist/index.d.ts

@@ -24,6 +24,11 @@ export { SecondaryFilters, type ActiveFilter, type SecondaryFiltersProps } from
 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 { DateField, type DateFieldProps } from './components/app/date-field.js';
+export { formatPlainDate, type PlainDate } from './lib/plain-date.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

@@ -29,6 +29,11 @@ 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 { DateField } from './components/app/date-field.js';
+export { formatPlainDate } from './lib/plain-date.js';
 export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell

package/dist/lib/plain-date.d.ts

@@ -0,0 +1,12 @@
+/** A calendar day as the wire writes it, `'YYYY-MM-DD'`, or `''` for not set. */
+export type PlainDate = string;
+/**
+ * Shows a plain date ("Sep 2, 2026") without ever shifting it by the
+ * time zone: the day is formatted as UTC midnight, in UTC. `''` and
+ * anything that isn't a real `'YYYY-MM-DD'` day give `''`.
+ */
+export declare function formatPlainDate(value: PlainDate, options?: Intl.DateTimeFormatOptions, locale?: string): string;
+/** The day as a local Date at midnight (what a date picker works in), or undefined when not set. */
+export declare function plainDateToLocal(value: PlainDate): Date | undefined;
+/** A local Date's own calendar day, as `'YYYY-MM-DD'`. */
+export declare function localToPlainDate(date: Date): PlainDate;

package/dist/lib/plain-date.js

@@ -0,0 +1,37 @@
+// A plain date: a calendar day with no time, as the wire writes it
+// (OpenAPI `format: date`, `'YYYY-MM-DD'`), or `''` for not set. It's a
+// day, never an instant, so nothing here goes through the browser's time
+// zone: Sep 2 is Sep 2 everywhere. DateField edits one.
+const PLAIN_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function parts(value) {
+    const match = PLAIN_DATE.exec(value);
+    if (!match)
+        return null;
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    // Reject what Date would roll over (Feb 30 → Mar 2).
+    const check = new Date(Date.UTC(year, month - 1, day));
+    if (check.getUTCFullYear() !== year || check.getUTCMonth() !== month - 1 || check.getUTCDate() !== day)
+        return null;
+    return [year, month, day];
+}
+/**
+ * Shows a plain date ("Sep 2, 2026") without ever shifting it by the
+ * time zone: the day is formatted as UTC midnight, in UTC. `''` and
+ * anything that isn't a real `'YYYY-MM-DD'` day give `''`.
+ */
+export function formatPlainDate(value, options = { dateStyle: 'medium' }, locale) {
+    const day = parts(value);
+    if (!day)
+        return '';
+    return new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' }).format(Date.UTC(day[0], day[1] - 1, day[2]));
+}
+/** The day as a local Date at midnight (what a date picker works in), or undefined when not set. */
+export function plainDateToLocal(value) {
+    const day = parts(value);
+    return day ? new Date(day[0], day[1] - 1, day[2]) : undefined;
+}
+/** A local Date's own calendar day, as `'YYYY-MM-DD'`. */
+export function localToPlainDate(date) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.10.0",
+  "version": "4.12.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);