@cueplusplus/ui 0.13.0

package/dist/configurator/use-zoom.js

@@ -0,0 +1,113 @@
+"use client";
+import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effect.js";
+import * as React from "react";
+//#region src/configurator/use-zoom.ts
+/**
+* The root zoom valve — luma's relief mechanism, adopted system-wide.
+*
+* Density is a *design* decision made in discrete, hand-authored steps; zoom is
+* a *comfort* decision the person at the keyboard makes, continuously, about
+* this screen at this distance. Conflating the two is how systems end up with a
+* naive multiplier and blurry half-pixel geometry, so this is deliberately not a
+* token: it sets the CSS `zoom` property on one element and lets the browser
+* scale the finished layout, which keeps every hairline crisp and every rem
+* ratio intact.
+*
+* The range is 0.7–1.5 because that is the band luma's console shipped and the
+* spec adopted: below 0.7 the 9px type stops being type, above 1.5 the
+* ultra-compact ladder has stopped being ultra-compact and the density picker is
+* the better tool.
+*
+* @example
+* const zoom = useZoom();
+* <Slider aria-label="Zoom" min={zoom.min} max={zoom.max} value={zoom.zoom} onValueChange={zoom.setZoom} />
+*/
+/** Floor of the valve — below this the type ladder stops being legible. */
+const MIN_ZOOM = .7;
+/** Ceiling of the valve — above this, pick a larger density instead. */
+const MAX_ZOOM = 1.5;
+/** One notch of the valve, and of ⌘+ / ⌘−. */
+const ZOOM_STEP = .1;
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/** Two decimals: `0.7 + 0.1` is not 0.8, and a zoom of 0.7999999999999999 helps nobody. */
+const round = (value) => Number(value.toFixed(2));
+/**
+* A bounded, stepped root-zoom valve with the usual keyboard shortcuts.
+*
+* Controlled or uncontrolled, the same way every other control in this system
+* is: pass `zoom` to own the value, `defaultZoom` to let the hook own it.
+*
+* The declaration belongs to the hook while it is mounted — unmounting takes it
+* back off, so a configurator that is closed does not leave the page at 1.4.
+*
+* @param options - Range, target, controlled value, shortcut opt-out.
+* @returns The valve: the value and the four ways to move it.
+* @example
+* const { zoom, zoomIn, zoomOut, reset } = useZoom({ shortcuts: false });
+*/
+function useZoom(options = {}) {
+	const { zoom: zoomProp, defaultZoom = 1, onZoomChange, min = MIN_ZOOM, max = MAX_ZOOM, step = ZOOM_STEP, target, shortcuts = true } = options;
+	const [uncontrolled, setUncontrolled] = React.useState(() => round(clamp(defaultZoom, min, max)));
+	const zoom = zoomProp === void 0 ? uncontrolled : round(clamp(zoomProp, min, max));
+	const setZoom = React.useCallback((next) => {
+		const clamped = round(clamp(next, min, max));
+		if (clamped === zoom) return;
+		if (zoomProp === void 0) setUncontrolled(clamped);
+		onZoomChange?.(clamped);
+	}, [
+		max,
+		min,
+		onZoomChange,
+		zoom,
+		zoomProp
+	]);
+	const zoomIn = React.useCallback(() => setZoom(zoom + step), [
+		setZoom,
+		step,
+		zoom
+	]);
+	const zoomOut = React.useCallback(() => setZoom(zoom - step), [
+		setZoom,
+		step,
+		zoom
+	]);
+	const reset = React.useCallback(() => setZoom(1), [setZoom]);
+	const element = target === void 0 ? typeof document === "undefined" ? null : document.documentElement : target;
+	useIsomorphicLayoutEffect(() => {
+		if (element === null) return;
+		if (zoom === 1) element.style.removeProperty("zoom");
+		else element.style.setProperty("zoom", String(zoom));
+		return () => {
+			element.style.removeProperty("zoom");
+		};
+	}, [element, zoom]);
+	React.useEffect(() => {
+		if (!shortcuts || typeof window === "undefined") return;
+		const onKeyDown = (event) => {
+			if (!(event.metaKey || event.ctrlKey) || event.altKey) return;
+			const step = event.key === "=" || event.key === "+" ? zoomIn : event.key === "-" || event.key === "_" ? zoomOut : event.key === "0" ? reset : null;
+			if (step === null) return;
+			event.preventDefault();
+			step();
+		};
+		window.addEventListener("keydown", onKeyDown);
+		return () => window.removeEventListener("keydown", onKeyDown);
+	}, [
+		reset,
+		shortcuts,
+		zoomIn,
+		zoomOut
+	]);
+	return {
+		zoom,
+		setZoom,
+		zoomIn,
+		zoomOut,
+		reset,
+		min,
+		max,
+		step
+	};
+}
+//#endregion
+export { MAX_ZOOM, MIN_ZOOM, ZOOM_STEP, useZoom };

package/dist/date/_glyphs.js

@@ -0,0 +1,34 @@
+import "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/date/_glyphs.tsx
+/**
+* Glyphs for the date group.
+*
+* Drawn inline for the same reason as `forms/_glyphs.tsx`: a caret on a month
+* nav and a grid on a picker trigger should not put an icon dependency on the
+* render path, and hand-set strokes stay hairline-thin at the 8–12px sizes
+* console density asks for. `currentColor` everywhere.
+*
+* @internal Not part of the public API.
+*/
+/** A month grid — the trigger mark of every date control. */
+function CalendarGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.25",
+		strokeLinecap: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [/* @__PURE__ */ jsx("rect", {
+			x: "2.5",
+			y: "3.5",
+			width: "11",
+			height: "10",
+			rx: "1"
+		}), /* @__PURE__ */ jsx("path", { d: "M2.5 6.5h11M5.5 2v3M10.5 2v3" })]
+	});
+}
+//#endregion
+export { CalendarGlyph };

package/dist/date/_segments.js

@@ -0,0 +1,101 @@
+import { cn } from "../lib/cn.js";
+import { controlGroupFocusClasses, controlVariants } from "../forms/_chassis.js";
+import { ariaClassName } from "../lib/aria-class.js";
+import "react";
+import { jsx } from "react/jsx-runtime";
+import { DateInput, DateSegment } from "react-aria-components";
+//#region src/date/_segments.tsx
+/**
+* The shared skin of the two segmented React Aria fields, `DateField` and
+* `TimeField`.
+*
+* Both render the same part — a `DateInput` of `DateSegment`s — so the recipe
+* lives here once. The group takes the recessed control chassis, resized to
+* `w-auto` (a date field is exactly as wide as a date, unlike a text input that
+* fills its column), and each segment is a focus target in its own right,
+* highlighted with the solid accent because a segment *is* the selection rather
+* than a hover.
+*
+* @internal Not part of the public API.
+*/
+/**
+* The chassis, resized for a control whose width comes from its content.
+*
+* The chassis lights its rim on `:focus`, which this group can never match —
+* React Aria keeps DOM focus on the individual segment and reports the group's
+* state as `data-focus-within`. Without the extra variant the inherited
+* `focus:border-border-strong` is a rule that cannot fire, and a segmented field
+* would be the only control in the system whose rim stays dead while it is being
+* typed into.
+*
+* A segmented field is a grouped control in every sense that matters, so it
+* takes the grouped contract whole rather than a rim of its own invention:
+* `controlGroupFocusClasses` strengthens the rim for any focus inside and paints
+* the single flush `--cue-focus` ring only for a `:focus-visible` descendant.
+* React Aria makes each value segment `contentEditable`, and a typing surface
+* matches `:focus-visible` on a pointer click as well as on Tab, so the ring
+* lands whenever the field is actually being edited. `data-focus-within` is kept
+* beside the native `:focus-within` rim because it is the state React Aria
+* documents, and the two agree on the same colour either way.
+*/
+function segmentGroupClasses(size) {
+	return cn(controlVariants({ size }), "inline-flex w-auto items-center whitespace-nowrap data-[focus-within]:border-border-strong", controlGroupFocusClasses);
+}
+/**
+* One segment. `data-focused` — not `:focus` — carries the highlight, because
+* React Aria keeps DOM focus on the segment element and reports the active one
+* through data attributes.
+*/
+const segmentClasses = "rounded-[2px] px-[0.0625rem] tabular-nums outline-none data-[focused]:bg-accent data-[focused]:text-accent-fg data-[placeholder]:text-fg-subtle data-[disabled]:opacity-40 data-[type=literal]:px-0 data-[type=literal]:text-fg-subtle";
+/**
+* The `DateInput` children render prop, wired to the segment skin.
+*
+* `suppressHydrationWarning`, and it is not papering over a bug of ours. A
+* segment's text comes from `Intl.DateTimeFormat`, which resolves against the
+* *ICU data of whatever is rendering* — and a server and a browser update their
+* ICU on different schedules. Today, `en-US` at 7:30 PM is `7:30\u202FPM` from
+* Node 24 (CLDR 48) and `7:30\u0020PM` from Chrome 151: one narrow no-break
+* space against one ordinary one, identical on screen, different to React.
+*
+* Without this, that one character is a hydration mismatch, and a mismatch is
+* not a warning — React throws away the server's HTML and re-renders the whole
+* document on the client. That re-mounts `<html>`, which React treats as a
+* singleton and therefore strips every attribute off, including the four the
+* pre-paint script wrote. Measured on this repository's own docs site: 208 ms
+* with no theme, density, mode or pairing on the document, 6,423 elements
+* resolving to a monospace nobody selected, and 40 KB of webfont fetched for it
+* that painted zero glyphs.
+*
+* So the mismatch is declared expected, on the one element whose text can
+* legitimately differ. The server's spelling of the space is kept; nobody can
+* see which one it is.
+*
+* It needs the extra `<span>` because React Aria runs its props through
+* `filterDOMProps`, which drops `suppressHydrationWarning` before the segment's
+* own element ever sees it — and React only honours the flag on the element
+* that directly contains the differing text. Only **literal** segments are
+* wrapped: they are the separators, `aria-hidden` and not focusable, while the
+* value segments React Aria makes `contentEditable` are left exactly as they
+* were. Digits and `AM`/`PM` are spelled the same by every ICU there has been;
+* it is only ever the space between them that moves.
+*/
+function renderSegment(segment) {
+	return /* @__PURE__ */ jsx(DateSegment, {
+		segment,
+		className: segmentClasses,
+		children: ({ text }) => segment.type === "literal" ? /* @__PURE__ */ jsx("span", {
+			suppressHydrationWarning: true,
+			children: text
+		}) : text
+	});
+}
+/** The `DateInput` both fields render, dressed and wired to the segment skin. */
+function SegmentGroup({ size, className }) {
+	return /* @__PURE__ */ jsx(DateInput, {
+		"data-slot": "date-input",
+		className: ariaClassName(segmentGroupClasses(size), className),
+		children: renderSegment
+	});
+}
+//#endregion
+export { SegmentGroup, renderSegment, segmentClasses, segmentGroupClasses };

package/dist/date/_trigger.js

@@ -0,0 +1,31 @@
+import { cn } from "../lib/cn.js";
+import { controlVariants } from "../forms/_chassis.js";
+//#region src/date/_trigger.ts
+/**
+* The shared skin of the two popover-backed date controls, `DatePicker` and
+* `DateRangePicker`.
+*
+* Both are the same shape: a chassis-styled button that reads out a formatted
+* date and opens a calendar. Encoding the trigger once keeps the pair from
+* drifting, and keeps "what a value-carrying trigger looks like" a single
+* decision — the same reason `_listbox.ts` exists for the filterable family.
+*
+* @internal Not part of the public API.
+*/
+/**
+* A control-chassis button: recessed fill, hairline rim, density height ladder,
+* with the value on the left and its glyph pinned right.
+*/
+function dateTriggerClasses(size) {
+	return cn(controlVariants({ size }), "flex cursor-pointer items-center justify-between gap-(--cue-space-2) text-left");
+}
+/** The value readout. Placeholder copy is one ink rung down. */
+const dateTriggerValueClasses = "truncate tabular-nums";
+/** Placeholder ink, applied to the readout when there is nothing to read. */
+const dateTriggerPlaceholderClasses = "text-fg-subtle";
+/** The trailing glyph — never a control, so it never takes the pointer. */
+const dateTriggerGlyphClasses = "size-icon-sm shrink-0 text-fg-subtle";
+/** Padding of the popup around a calendar: one unit tighter than a popover's. */
+const datePopupClasses = "p-(--cue-space-3)";
+//#endregion
+export { datePopupClasses, dateTriggerClasses, dateTriggerGlyphClasses, dateTriggerPlaceholderClasses, dateTriggerValueClasses };

package/dist/date/calendar.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+import { DayPickerProps } from "react-day-picker";
+//#region src/date/calendar.d.ts
+/** Everything react-day-picker takes; the skin is applied on top. */
+type CalendarProps = DayPickerProps;
+/**
+ * A month grid, on react-day-picker v10.
+ *
+ * Selection modes, keyboard navigation, the ARIA grid wiring and the date maths
+ * (date-fns under the hood) are the library's; this layer supplies the token
+ * skin and nothing else, so upgrading the library never means re-deriving
+ * behaviour. Every `classNames` slot the caller passes is merged *over* the
+ * skin rather than replacing it.
+ *
+ * `react-day-picker` and `date-fns` are **optional peers**: import this from
+ * `@cueplusplus/ui/date`, never from the core barrel.
+ *
+ * @example
+ * <Calendar mode="single" selected={date} onSelect={setDate} />
+ * @example
+ * <Calendar mode="range" numberOfMonths={2} selected={range} onSelect={setRange} />
+ */
+declare function Calendar(props: CalendarProps): React.JSX.Element;
+//#endregion
+export { Calendar, CalendarProps };

package/dist/date/calendar.js

@@ -0,0 +1,125 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import "react";
+import { jsx } from "react/jsx-runtime";
+import { DayPicker } from "react-day-picker";
+//#region src/date/calendar.tsx
+/**
+* The token skin for every element react-day-picker renders.
+*
+* react-day-picker ships its own stylesheet; this system never loads it. Each
+* key below is one `UI` / `DayFlag` / `SelectionState` slot, dressed from the
+* same tokens as the rest of the kit: the day cell is one rung of the control
+* ladder (`size-control-sm`), the caption is a mono micro label, the selected
+* day takes the solid accent and a range's middle takes `accent-soft` — the
+* same "soft tint for a span, solid for the thing you picked" rule the menus
+* use.
+*
+* Written as a `Partial<ClassNames>` rather than sprayed across the component
+* so a caller can merge over any single slot (see {@link mergeCalendarClasses}).
+*/
+const CALENDAR_CLASSES = {
+	root: "font-mono text-(length:--cue-text-ui) text-fg",
+	months: "relative flex flex-wrap items-start gap-(--cue-space-5)",
+	month: "flex flex-col gap-(--cue-space-2)",
+	month_caption: "flex h-control-sm items-center justify-center",
+	caption_label: "font-mono text-(length:--cue-text-label) tracking-[0.15em] text-fg-subtle uppercase",
+	nav: "absolute inset-x-0 top-0 flex h-control-sm items-center justify-between",
+	button_previous: "flex size-control-sm cursor-pointer items-center justify-center rounded-(--radius-control) border-0 bg-transparent p-0 text-fg-subtle outline-none transition-colors duration-150 hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:pointer-events-none disabled:opacity-30 motion-reduce:transition-none",
+	button_next: "flex size-control-sm cursor-pointer items-center justify-center rounded-(--radius-control) border-0 bg-transparent p-0 text-fg-subtle outline-none transition-colors duration-150 hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:pointer-events-none disabled:opacity-30 motion-reduce:transition-none",
+	chevron: "size-icon-sm fill-current",
+	month_grid: "border-collapse border-spacing-0",
+	weekdays: "",
+	weekday: "size-control-sm p-0 text-center align-middle font-mono text-(length:--cue-text-micro) font-normal tracking-[0.1em] text-fg-subtle uppercase",
+	week: "",
+	day: "p-0 text-center align-middle",
+	day_button: "size-control-sm cursor-pointer rounded-(--radius-control) border-0 bg-transparent p-0 font-mono text-(length:--cue-text-ui) tabular-nums text-fg-muted outline-none transition-colors duration-150 hover:bg-surface-3 hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:pointer-events-none disabled:opacity-30 motion-reduce:transition-none",
+	today: "[&_button]:font-medium [&_button]:ring-1 [&_button]:ring-inset [&_button]:ring-accent/60",
+	outside: "[&_button]:text-fg-subtle [&_button]:opacity-50",
+	disabled: "opacity-40",
+	hidden: "invisible",
+	selected: "bg-accent text-accent-fg [&_button]:bg-accent [&_button]:text-accent-fg [&_button]:hover:bg-accent-hover",
+	range_start: "rounded-l-(--radius-control)",
+	range_end: "rounded-r-(--radius-control)",
+	range_middle: "rounded-none bg-accent-soft text-fg [&_button]:rounded-none [&_button]:bg-transparent [&_button]:text-fg",
+	footer: "pt-(--cue-space-2) font-mono text-(length:--cue-text-label) text-fg-muted",
+	dropdowns: "flex items-center gap-(--cue-space-2)",
+	dropdown_root: "relative inline-flex items-center",
+	dropdown: "h-control-sm cursor-pointer rounded-(--radius-control) border border-border bg-sunken px-(--cue-space-2) font-mono text-(length:--cue-text-label) text-fg outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent",
+	week_number: "size-control-sm text-center align-middle font-mono text-(length:--cue-text-micro) tabular-nums text-fg-subtle",
+	week_number_header: "size-control-sm text-center align-middle font-mono text-(length:--cue-text-micro) text-fg-subtle"
+};
+/**
+* Merge the caller's per-slot class names over the skin with `cn`, so an
+* override replaces only the utilities it conflicts with instead of wiping the
+* whole slot. Mirrors how every other component in the kit treats `className`.
+*/
+function mergeCalendarClasses(overrides) {
+	if (overrides === void 0) return CALENDAR_CLASSES;
+	const merged = { ...CALENDAR_CLASSES };
+	for (const [slot, value] of Object.entries(overrides)) merged[slot] = cn(CALENDAR_CLASSES[slot], value);
+	return merged;
+}
+/**
+* The calendar's root. Swapped in only to stamp `data-slot` — react-day-picker
+* does not forward unknown props to the element it renders.
+*/
+function CalendarRoot({ rootRef, ...elementProps }) {
+	return /* @__PURE__ */ jsx("div", {
+		ref: rootRef,
+		"data-slot": "calendar",
+		...elementProps
+	});
+}
+/** react-day-picker's chevron slot, restyled to the kit's hairline caret. */
+function CalendarChevron({ orientation = "left", className, size }) {
+	const rotation = {
+		left: 90,
+		right: -90,
+		up: 180,
+		down: 0
+	}[orientation];
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		width: size,
+		height: size,
+		fill: "currentColor",
+		"aria-hidden": "true",
+		className,
+		style: { transform: `rotate(${rotation}deg)` },
+		children: /* @__PURE__ */ jsx("path", { d: "M4 6h8l-4 4.5z" })
+	});
+}
+/**
+* A month grid, on react-day-picker v10.
+*
+* Selection modes, keyboard navigation, the ARIA grid wiring and the date maths
+* (date-fns under the hood) are the library's; this layer supplies the token
+* skin and nothing else, so upgrading the library never means re-deriving
+* behaviour. Every `classNames` slot the caller passes is merged *over* the
+* skin rather than replacing it.
+*
+* `react-day-picker` and `date-fns` are **optional peers**: import this from
+* `@cueplusplus/ui/date`, never from the core barrel.
+*
+* @example
+* <Calendar mode="single" selected={date} onSelect={setDate} />
+* @example
+* <Calendar mode="range" numberOfMonths={2} selected={range} onSelect={setRange} />
+*/
+function Calendar(props) {
+	const { className, classNames, showOutsideDays = true, components, ...rest } = props;
+	return /* @__PURE__ */ jsx(DayPicker, {
+		showOutsideDays,
+		className: cn("inline-block", className),
+		classNames: mergeCalendarClasses(classNames),
+		components: {
+			Root: CalendarRoot,
+			Chevron: CalendarChevron,
+			...components
+		},
+		...rest
+	});
+}
+//#endregion
+export { Calendar };

package/dist/date/date-field.d.ts

@@ -0,0 +1,34 @@
+import { FormControlSize } from "../forms/_chassis.js";
+import * as React from "react";
+import { DateFieldProps, DateInputProps, DateValue } from "react-aria-components";
+//#region src/date/date-field.d.ts
+interface DateFieldProps$1<T extends DateValue = DateValue> extends Omit<DateFieldProps<T>, "children"> {
+  /** Rung of the control ladder. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /** Extra classes for the segment group itself. */
+  inputClassName?: DateInputProps["className"];
+}
+/**
+ * A typed date, one segment at a time — day, month, year — with no calendar.
+ *
+ * The right control when the user already knows the date: typing `08172026` is
+ * faster than three clicks, and a segmented field cannot produce an ambiguous
+ * `03/04`. Wraps React Aria's `DateField`, so locale-aware segment order,
+ * arrow-key stepping, overflow between segments and the `spinbutton` ARIA
+ * wiring are the library's; this layer restyles it onto the form chassis.
+ *
+ * Values are `@internationalized/date` objects (`CalendarDate`,
+ * `CalendarDateTime`, `ZonedDateTime`) — not `Date`, which cannot represent
+ * "a day" without dragging a timezone along.
+ *
+ * `react-aria-components` is an **optional peer**: import this from
+ * `@cueplusplus/ui/date`.
+ *
+ * @example
+ * <DateField aria-label="Go live" value={date} onChange={setDate} />
+ * @example
+ * <DateField label={undefined} aria-label="Cutoff" granularity="minute" size="sm" />
+ */
+declare function DateField$1<T extends DateValue = DateValue>({ size, className, inputClassName, ...fieldProps }: DateFieldProps$1<T>): React.JSX.Element;
+//#endregion
+export { DateField$1 as DateField, DateFieldProps$1 as DateFieldProps, type DateValue };

package/dist/date/date-field.js

@@ -0,0 +1,41 @@
+"use client";
+import { ariaClassName } from "../lib/aria-class.js";
+import { SegmentGroup } from "./_segments.js";
+import "react";
+import { jsx } from "react/jsx-runtime";
+import { DateField } from "react-aria-components";
+//#region src/date/date-field.tsx
+/**
+* A typed date, one segment at a time — day, month, year — with no calendar.
+*
+* The right control when the user already knows the date: typing `08172026` is
+* faster than three clicks, and a segmented field cannot produce an ambiguous
+* `03/04`. Wraps React Aria's `DateField`, so locale-aware segment order,
+* arrow-key stepping, overflow between segments and the `spinbutton` ARIA
+* wiring are the library's; this layer restyles it onto the form chassis.
+*
+* Values are `@internationalized/date` objects (`CalendarDate`,
+* `CalendarDateTime`, `ZonedDateTime`) — not `Date`, which cannot represent
+* "a day" without dragging a timezone along.
+*
+* `react-aria-components` is an **optional peer**: import this from
+* `@cueplusplus/ui/date`.
+*
+* @example
+* <DateField aria-label="Go live" value={date} onChange={setDate} />
+* @example
+* <DateField label={undefined} aria-label="Cutoff" granularity="minute" size="sm" />
+*/
+function DateField$1({ size, className, inputClassName, ...fieldProps }) {
+	return /* @__PURE__ */ jsx(DateField, {
+		"data-slot": "date-field",
+		className: ariaClassName("inline-flex flex-col gap-(--cue-space-1)", className),
+		...fieldProps,
+		children: /* @__PURE__ */ jsx(SegmentGroup, {
+			size,
+			className: inputClassName
+		})
+	});
+}
+//#endregion
+export { DateField$1 as DateField };

package/dist/date/date-picker.d.ts

@@ -0,0 +1,69 @@
+import { FormControlSize } from "../forms/_chassis.js";
+import { CalendarProps } from "./calendar.js";
+import * as React from "react";
+//#region src/date/date-picker.d.ts
+/** The calendar knobs a picker leaves open; selection is the picker's own job. */
+type DatePickerCalendarProps = Omit<CalendarProps, "mode" | "selected" | "onSelect" | "required">;
+interface DatePickerProps {
+  /** The chosen day. Use with `onValueChange` for a controlled field. */
+  value?: Date | null;
+  /** Initially chosen day for an uncontrolled field. */
+  defaultValue?: Date | null;
+  /** Called with the new day, or `undefined` when the day is unpicked. */
+  onValueChange?: (value: Date | undefined) => void;
+  /** Read out while nothing is chosen. Defaults to `"Pick a date"`. */
+  placeholder?: string;
+  /** date-fns pattern for the readout. Defaults to `"d MMM yyyy"`. */
+  dateFormat?: string;
+  /** Rung of the control ladder. Defaults to `"md"`. */
+  size?: FormControlSize;
+  /** Prevent opening and grey the trigger out. */
+  disabled?: boolean;
+  /** Paint the danger rim — pair it with a `FieldError`. */
+  invalid?: boolean;
+  /**
+   * Name for the hidden input, when the field is part of a form. The submitted
+   * value is the ISO date (`yyyy-MM-dd`), never the formatted readout.
+   */
+  name?: string;
+  /** Id forwarded to the trigger. */
+  id?: string;
+  /** Accessible name for the trigger, when no `FieldLabel` names it. */
+  "aria-label"?: string;
+  /** Id of the element naming the trigger. */
+  "aria-labelledby"?: string;
+  /** Extra classes for the trigger. */
+  className?: string;
+  /** Extra classes for the popup surface. */
+  popupClassName?: string;
+  /** Everything else the calendar takes — month bounds, disabled days, locale. */
+  calendarProps?: DatePickerCalendarProps;
+  /** Open state, for a controlled popover. */
+  open?: boolean;
+  /** Initial open state. */
+  defaultOpen?: boolean;
+  /** Called when the popover opens or closes. */
+  onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A single day, picked from a calendar in a popover.
+ *
+ * The trigger is a control-chassis button carrying the formatted day, so a date
+ * field lines up with the inputs beside it at every density. The calendar is
+ * `Calendar` (react-day-picker) inside the kit's `Popover`, which means it is
+ * portalled through the portal contract and renders at the theme and density of
+ * the tree it was opened from — not the body's.
+ *
+ * Picking a day closes the popup: a single-date picker has nothing left to ask.
+ *
+ * `react-day-picker` and `date-fns` are **optional peers**: import this from
+ * `@cueplusplus/ui/date`.
+ *
+ * @example
+ * <DatePicker aria-label="Show date" value={date} onValueChange={setDate} />
+ * @example
+ * <DatePicker name="showDate" dateFormat="EEE d MMM" calendarProps={{ disabled: past }} />
+ */
+declare function DatePicker({ value, defaultValue, onValueChange, placeholder, dateFormat, size, disabled, invalid, name, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className, popupClassName, calendarProps, open, defaultOpen, onOpenChange }: DatePickerProps): React.JSX.Element;
+//#endregion
+export { DatePicker, DatePickerCalendarProps, DatePickerProps };

package/dist/date/date-picker.js

@@ -0,0 +1,89 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { Popover } from "../overlays/popover.js";
+import { Calendar } from "./calendar.js";
+import { CalendarGlyph } from "./_glyphs.js";
+import { datePopupClasses, dateTriggerClasses, dateTriggerGlyphClasses, dateTriggerValueClasses } from "./_trigger.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { format } from "date-fns";
+//#region src/date/date-picker.tsx
+/** The wire format for a submitted date: sortable, unambiguous, locale-free. */
+const ISO_DATE = "yyyy-MM-dd";
+/**
+* A single day, picked from a calendar in a popover.
+*
+* The trigger is a control-chassis button carrying the formatted day, so a date
+* field lines up with the inputs beside it at every density. The calendar is
+* `Calendar` (react-day-picker) inside the kit's `Popover`, which means it is
+* portalled through the portal contract and renders at the theme and density of
+* the tree it was opened from — not the body's.
+*
+* Picking a day closes the popup: a single-date picker has nothing left to ask.
+*
+* `react-day-picker` and `date-fns` are **optional peers**: import this from
+* `@cueplusplus/ui/date`.
+*
+* @example
+* <DatePicker aria-label="Show date" value={date} onValueChange={setDate} />
+* @example
+* <DatePicker name="showDate" dateFormat="EEE d MMM" calendarProps={{ disabled: past }} />
+*/
+function DatePicker({ value, defaultValue, onValueChange, placeholder = "Pick a date", dateFormat = "d MMM yyyy", size, disabled, invalid, name, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className, popupClassName, calendarProps, open, defaultOpen, onOpenChange }) {
+	const [uncontrolled, setUncontrolled] = React.useState(defaultValue ?? void 0);
+	const selected = value === void 0 ? uncontrolled : value ?? void 0;
+	const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen ?? false);
+	const isOpen = open ?? uncontrolledOpen;
+	const setOpen = (next) => {
+		if (open === void 0) setUncontrolledOpen(next);
+		onOpenChange?.(next);
+	};
+	const select = (next) => {
+		if (value === void 0) setUncontrolled(next);
+		onValueChange?.(next);
+		setOpen(false);
+	};
+	return /* @__PURE__ */ jsxs(Popover.Root, {
+		open: isOpen,
+		onOpenChange: setOpen,
+		children: [
+			/* @__PURE__ */ jsxs(Popover.Trigger, {
+				render: /* @__PURE__ */ jsx("button", {
+					type: "button",
+					id,
+					disabled,
+					"aria-label": ariaLabel,
+					"aria-labelledby": ariaLabelledBy,
+					"data-slot": "date-picker-trigger",
+					"data-empty": selected === void 0 ? "true" : void 0,
+					"data-invalid": invalid ? "" : void 0,
+					className: cn(dateTriggerClasses(size), className)
+				}),
+				children: [/* @__PURE__ */ jsx("span", {
+					className: cn(dateTriggerValueClasses, selected === void 0 && "text-fg-subtle"),
+					children: selected === void 0 ? placeholder : format(selected, dateFormat)
+				}), /* @__PURE__ */ jsx(CalendarGlyph, { className: dateTriggerGlyphClasses })]
+			}),
+			/* @__PURE__ */ jsx(Popover.Content, {
+				className: cn(datePopupClasses, popupClassName),
+				align: "start",
+				"data-slot": "date-picker-popup",
+				children: /* @__PURE__ */ jsx(Calendar, {
+					...calendarProps,
+					mode: "single",
+					selected,
+					onSelect: select,
+					defaultMonth: calendarProps?.defaultMonth ?? selected,
+					autoFocus: true
+				})
+			}),
+			name === void 0 ? null : /* @__PURE__ */ jsx("input", {
+				type: "hidden",
+				name,
+				value: selected === void 0 ? "" : format(selected, ISO_DATE)
+			})
+		]
+	});
+}
+//#endregion
+export { DatePicker };