@tristan2828/ui-foundation 4.11.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/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/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,8 @@ 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 { 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,8 @@ 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.11.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": {