@tristan2828/ui-foundation 4.11.0 → 4.13.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

@@ -934,15 +934,26 @@ row`), every editable cell is an editable value, exactly as on a view.
 one is open, "Saving…" and a refusal in the cell. There's no pencil
 column and no edit route.
 
-- **A cell** is `<EditableValue label="<Column> of <name>" layout="inline"
-  edit={editInPlace({ ... })}>`, its shown value the cell as it always
-  was. The label names the column and the row, so its pencil reads "Edit
-  Colour of Work" and its control "Colour of Work". The kinds are the
-  same: `text` (Enter saves), `choice` (the list opens with it, non-modal,
-  a pick saves), `multi`.
+- **A cell is one of the package's three row-edit cells**, or an
+  `<EditableValue label="<Column> of <name>" layout="inline"
+  edit={editInPlace({ ... })}>` for anything else. The label names the
+  column and the row, so its pencil reads "Edit Colour of Work" and its
+  control "Colour of Work".
+  - **`NameCell`**: one line; Enter saves, the form's rule (`schema`)
+    runs first, a taken name's 422 shows in the cell. `children` is how
+    the name shows at rest (an icon beside it).
+  - **`ChoiceCell<T>`** (`options`, `render`): the list opens with the
+    cell, non-modal; a pick saves, closing it with no pick gives up.
+    `render` draws a value at rest, on the trigger and in the list.
+  - **`LinkCell`** (`linkText`, `emptyLabel`, `save(link | null)`): a
+    link opening in a new tab (said to screen readers), or the not-set
+    label; edited as one line. A bare `example.com` gains `https://`,
+    another scheme (`javascript:`) is refused in the cell, and a blank
+    box saves `null`. Clicking the link follows it; the pencil edits.
 - **A cell is a component** (`<Entity><Field>Cell`) that calls
   `useEdit<Entity>Field(row.id)` for its save, the view's single-field
-  save. A hook can't be called inside a column definition.
+  save, and renders the package's cell with it. A hook can't be called
+  inside a column definition.
 - **Stable columns and row ids.** Make the column definitions once
   (at module level, or `useMemo`) and give
   `DataTable` a `getRowId`: new definitions every render, or rows keyed
@@ -958,24 +969,29 @@ column and no edit route.
   and its delete together on a wide screen.
 
 ```tsx
-// A cell is its own component, so it can call the record's save hook.
+import { ChoiceCell, InlineCreate, LinkCell, NameCell } from '@tristan2828/ui-foundation'
+
+// Each cell is its own component, so it can call the record's save hook.
 function CategoryColourCell({ category }: { category: Category }) {
   const editField = useEditCategoryField(category.id)       // optimistic: false, toastOnError: false
   return (
-    <EditableValue label={`Colour of ${category.name}`} layout="inline"
-      edit={editInPlace({
-        kind: 'choice',
-        value: category.colour,
-        schema: categoryFormSchema.shape.colour,
-        save: (colour) => editField.mutateAsync({ colour }),
-        control: (props) => (
-          <CategoryColourSelect id={props.id} value={props.value} onChange={(colour) => props.commit(colour)}
-            readOnly={props.disabled} defaultOpen modal={false} onOpenChange={(open) => !open && props.cancel()}
-            aria-label={props.label} aria-describedby={props.describedBy} />
-        ),
-      })}>
-      <ColourSwatch colour={category.colour} />
-    </EditableValue>
+    <ChoiceCell label={`Colour of ${category.name}`} value={category.colour} options={CATEGORY_COLOURS}
+      render={(colour) => <ColourSwatch colour={colour} />}
+      save={(colour) => editField.mutateAsync({ colour })} />
+  )
+}
+function CategoryNameCell({ category }: { category: Category }) {
+  const editField = useEditCategoryField(category.id)
+  return (
+    <NameCell label={`Name of ${category.name}`} value={category.name} schema={categoryFormSchema.shape.name}
+      save={(name) => editField.mutateAsync({ name })} />
+  )
+}
+function CategoryWebsiteCell({ category }: { category: Category }) {
+  const editField = useEditCategoryField(category.id)
+  return (
+    <LinkCell label={`Website of ${category.name}`} value={category.website} emptyLabel="No website"
+      save={(website) => editField.mutateAsync({ website })} />
   )
 }
 
@@ -983,6 +999,7 @@ function CategoryColourCell({ category }: { category: Category }) {
 const CATEGORY_COLUMNS: LegacyColumnDef<Category, unknown>[] = [
   { id: 'name', header: 'Name', cell: ({ row }) => <CategoryNameCell category={row.original} /> },
   { id: 'colour', header: 'Colour', cell: ({ row }) => <CategoryColourCell category={row.original} /> },
+  { id: 'website', header: 'Website', cell: ({ row }) => <CategoryWebsiteCell category={row.original} /> },
   { id: 'actions', header: () => <span className="sr-only">Actions</span>, cell: ({ row }) => <DeleteCategoryAction category={row.original} /> },
 ]
 

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/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/row-edit-cells.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+import { type EditInPlaceOptions } from './edit-in-place.js';
+type Schema<TValue> = EditInPlaceOptions<unknown, TValue>['schema'];
+export type NameCellProps = {
+    /** The cell's name, column and row: "Name of Home". */
+    label: string;
+    /** The saved name. */
+    value: string;
+    /** Saves the new name (already checked by `schema`). Rejects with the AppError. */
+    save: (name: string) => Promise<unknown>;
+    /** The form's rule for the name (`schema.shape.name`): checked before anything is sent. */
+    schema?: Schema<string>;
+    /** How the name shows at rest (an icon beside it). Defaults to the name. */
+    children?: ReactNode;
+    /** The input's width class. Defaults to `w-48`. */
+    inputClassName?: string;
+};
+/** A name in one line: Enter saves, the form's rule runs first, a taken name's 422 shows in the cell. */
+export declare function NameCell({ label, value, save, schema, children, inputClassName }: NameCellProps): import("react").JSX.Element;
+export type ChoiceCellProps<T extends string> = {
+    /** The cell's name, column and row: "Colour of Home". */
+    label: string;
+    /** The saved value. */
+    value: T;
+    /** Every value, in the order the list shows them. */
+    options: readonly T[];
+    /** How a value shows: at rest, on the open trigger and in the list (a swatch and its word). */
+    render: (value: T) => ReactNode;
+    /** Saves the picked value. Rejects with the AppError. */
+    save: (value: T) => Promise<unknown>;
+    /** The trigger's width class. Defaults to `w-40`. */
+    triggerClassName?: string;
+};
+/** A single choice: its list opens with the cell, a pick saves, closing it with no pick gives up. */
+export declare function ChoiceCell<T extends string>({ label, value, options, render, save, triggerClassName, }: ChoiceCellProps<T>): import("react").JSX.Element;
+export type LinkCellProps = {
+    /** The cell's name, column and row: "Website of Home". */
+    label: string;
+    /** The saved address, or null when there's none. */
+    value: string | null;
+    /** Saves the address, or null to clear it (the box left blank). Rejects with the AppError. */
+    save: (link: string | null) => Promise<unknown>;
+    /** The link's text at rest. Defaults to the address without its scheme. */
+    linkText?: string | ((href: string) => ReactNode);
+    /** What the cell says with no address. Defaults to "Not set". */
+    emptyLabel?: string;
+    /** The input's width class. Defaults to `w-64`. */
+    inputClassName?: string;
+};
+/** An optional link: shown as a link out (or the not-set label), edited as one line; blank clears it. */
+export declare function LinkCell({ label, value, save, linkText, emptyLabel, inputClassName }: LinkCellProps): import("react").JSX.Element;
+export {};

package/dist/components/app/row-edit-cells.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ExternalLinkIcon } from 'lucide-react';
+import { Input } from '../ui/input.js';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select.js';
+import { linkHref } from '../../lib/link-href.js';
+import { editInPlace } from './edit-in-place.js';
+import { EditableValue } from './editable-value.js';
+/** A name in one line: Enter saves, the form's rule runs first, a taken name's 422 shows in the cell. */
+export function NameCell({ label, value, save, schema, children, inputClassName = 'w-48' }) {
+    return (_jsx(EditableValue, { label: label, layout: "inline", edit: editInPlace({
+            kind: 'text',
+            value,
+            schema,
+            save,
+            control: (props) => (_jsx(Input, { id: props.id, className: inputClassName, value: props.value, readOnly: props.disabled, "aria-invalid": props.invalid || undefined, "aria-label": props.label, "aria-describedby": props.describedBy, onChange: (event) => props.onChange(event.target.value) })),
+        }), children: children ?? value }));
+}
+/** A single choice: its list opens with the cell, a pick saves, closing it with no pick gives up. */
+export function ChoiceCell({ label, value, options, render, save, triggerClassName = 'w-40', }) {
+    return (_jsx(EditableValue, { label: label, layout: "inline", edit: editInPlace({
+            kind: 'choice',
+            value,
+            save,
+            control: (props) => (_jsxs(Select, { value: props.value, onValueChange: (next) => {
+                    if (next)
+                        props.commit(next);
+                }, disabled: props.disabled, defaultOpen: true, modal: false, onOpenChange: (open) => {
+                    if (!open)
+                        props.cancel();
+                }, children: [_jsx(SelectTrigger, { id: props.id, className: triggerClassName, "aria-invalid": props.invalid || undefined, "aria-label": props.label, "aria-describedby": props.describedBy, children: _jsx(SelectValue, { children: (shown) => render(shown) }) }), _jsx(SelectContent, { children: options.map((option) => (_jsx(SelectItem, { value: option, children: render(option) }, option))) })] })),
+        }), children: render(value) }));
+}
+// A web or email address (`example.com` gains https://), blank for none.
+// Another scheme (`javascript:`) is refused before anything is sent.
+const LINK_RULE = {
+    safeParse: (value) => {
+        const href = linkHref(String(value ?? ''));
+        if (href === '')
+            return { success: true, data: null };
+        if (href === null) {
+            return { success: false, error: { issues: [{ message: 'Use a web or email address' }] } };
+        }
+        return { success: true, data: href };
+    },
+};
+function shownLinkText(href, linkText) {
+    if (typeof linkText === 'function')
+        return linkText(href);
+    return linkText ?? href.replace(/^(https?:\/\/|mailto:)/i, '').replace(/\/$/, '');
+}
+/** An optional link: shown as a link out (or the not-set label), edited as one line; blank clears it. */
+export function LinkCell({ label, value, save, linkText, emptyLabel = 'Not set', inputClassName = 'w-64' }) {
+    // Only an address the editor would have saved is shown as a link: a
+    // stored `javascript:` reads as text, never as something to click.
+    const href = value ? linkHref(value) : null;
+    return (_jsx(EditableValue, { label: label, layout: "inline", edit: editInPlace({
+            kind: 'text',
+            value: value ?? '',
+            schema: LINK_RULE,
+            save,
+            control: (props) => (_jsx(Input, { id: props.id, type: "url", inputMode: "url", className: inputClassName, value: props.value, placeholder: "https://", readOnly: props.disabled, "aria-invalid": props.invalid || undefined, "aria-label": props.label, "aria-describedby": props.describedBy, onChange: (event) => props.onChange(event.target.value) })),
+        }), children: !value ? (_jsx("span", { className: "text-muted-foreground", children: emptyLabel })) : href ? (_jsxs("a", { href: href, target: "_blank", rel: "noreferrer", className: "rounded-sm text-link underline underline-offset-4 outline-none focus-visible:ring-3 focus-visible:ring-ring/50", children: [shownLinkText(href, linkText), _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)" })] })) : (value) }));
+}

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

@@ -27,6 +27,9 @@ export { SourceCredit, type Source, type SourceCreditProps } from './components/
 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 { ChoiceCell, LinkCell, NameCell, type ChoiceCellProps, type LinkCellProps, type NameCellProps, } from './components/app/row-edit-cells.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

@@ -32,6 +32,9 @@ 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 { ChoiceCell, LinkCell, NameCell, } from './components/app/row-edit-cells.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.11.0",
+  "version": "4.13.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": {