feat(DateTimePicker): a date-and-time picker with presets

[IgorShevchik]

Linked issue

Rebuilds what #55 attempted. That branch was opened before main was re-rooted, so it shares no merge base with it — git merge-base exits 1 — and could neither rebase nor merge. It was closed and used here as a specification rather than as a base.

Follow-ups filed from this PR: #582 (native review of thirteen locales), #583 (nothing catches an empty API section).

Type of change

• Documentation (updates to the documentation or readme)
• Bug fix (a non-breaking change that fixes an issue)
• Enhancement (improving an existing functionality)
• New feature (a non-breaking change that adds functionality)
• Chore (updates to the build process or auxiliary tools and libraries)
• Revert (undoing a merged change — retitle this PR revert(Scope): ...)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

B24DateTimePicker picks a date and a time in one control: a calendar, then a time grid, with a preset column beside them. It renders in a B24Popover on pointer-sized screens and a B24Drawer on small ones, through the existing useDevice composable.

Public surface

• Props: modelValue, defaultValue, open, defaultOpen, dateOnly, minuteStep, locale, placeholder, presets, hidePresets, format, color, size, disabled, icon, timeIcon, plus pass-through objects popover, drawer, calendar, input.
• Emits: update:modelValue, change, update:open.
• Slots: default (replaces the trigger), presets, preset, time-header.
• Theme src/theme/date-time-picker.ts: 20 slots, color (5 values) and size (xs/sm/md/lg) variants, defaults md / air-primary.

Decisions worth a reviewer's attention

The trigger is a B24Input, not a wrapper around one. The first version wrapped a readonly input in a clickable div. axe rejected it twice: aria-allowed-attr, because aria-expanded sat on a role-less element; then nested-interactive, once a role="button" was added and the real <input> was still inside it. B24Input forwards fall-through attributes onto its <input>, so the popover's aria-haspopup / aria-expanded land on a genuine control and the wrapper is gone.

shallowRef for the value, not ref. Vue's deep unwrapping widens the DateValue union of class instances into a structural object that no longer matches the type. Measured: swapping the one word and running pnpm typecheck produces seven TS2322/TS2345 errors in this file. Date values are immutable, so there is nothing to track deeply anyway. The component carries no as any and no as unknown as DateValue.

minuteStep is clamped, not trusted. 1…30, with a non-finite value falling back to the default rather than rendering an empty or unbounded grid. Covered at five values, not one — undefined, 15, 90, 0, NaN — because a guard checked at one value is not a guard checked.

Presets resolve once per render. A preset's value may be a function so that "today" stays today across a long session; resolvedPresets calls it a single time and the test asserts the call count, so rendering and applying cannot disagree.

dateOnly drops the time rather than zeroing it. The value stays a CalendarDate, so it carries no time at all instead of an implied 00:00, and applying a preset under dateOnly discards the preset's time too.

Documentation — docs/content/docs/2.components/date-time-picker.md with five runnable examples, both playgrounds, and the page registered in docs/nuxt.config.ts and in the skill index. The scaffolder's Nuxt UI and reka-ui front-matter links were removed: reka-ui has no such component and the generated URL returns 404.

What the review found

A five-reviewer panel ran over the first four commits. Every finding below was reproduced before being acted on, and the fixes are in 02fe7e09 and bddc6ae3.

The end-of-week preset resolved to the wrong day. It was derived from startOfWeek(…).add({ days: 4 }), which reads as Friday only where the week starts on Monday. Measured: Thursday under en — this repository's own default locale — and Wednesday under ar, where it could resolve to the current day and the button would do nothing. The wrong day was already sitting in the committed snapshot, accepted because nothing asserted the weekday. The index is now anchored to en-US, so Friday is 5 everywhere.

Seven locales named the weekend, not the end of the week — ja, sc, tc, th, id, ms, la — which is a different day from the one the preset picks. The same class of error was fixed for de/fr/it/br/tr during #55; it came back because the preset itself had no settled meaning. Corrected here; the remaining thirteen unreviewed locales are #582, and the replacements are the author's, not a native speaker's.

open was not a controlled prop. It was mirrored into a ref that every internal handler wrote to, so picking a date closed the picker even while the parent held the prop at true. It now reads through the prop and asks to close by emitting.

A throwing preset factory took the whole component down. presets[].value may be consumer-supplied and is called during render; an exception escaped the computed the template reads. Under SSR that rejected the page render outright, and on the client it replaced the component — working calendar included — with an empty node. One bad preset now drops out of the list with a warning.

A locale string Intl rejects threw before the picker could open. The prop feeds four Intl.DateTimeFormat constructions, one of them on the always-visible trigger, so a malformed tag was fatal on first render. It falls back to en.

The spec did not pin the clock. Calendar, InputDate and InputTime all call vi.setSystemTime; this one did not, so the preset hints wrote the day it was authored into the snapshots six times. They would have gone red the next morning.

The API section on the docs page was empty. interface DateTimePickerProps {}, and the same for slots and emits, while docs:generate reported 1100 routes with no failures. The cause was not in the component: the componentMeta transformer in docs/nuxt.config.ts rewrites the b24ui slot-prop token anywhere it appears, including where it is an object key in an expression, and the result does not parse. vue-component-meta then returns nothing for the component, silently. B24Theme and B24DashboardSearchButton were being rewritten the same way, and B24EditorDragHandle's onClick slot prop was being swallowed by the same pattern crossing a brace. Bounding it to the plain <script> block and forbidding the run from crossing a brace keeps 119 of the 125 sites it hit and drops exactly the six it was damaging. That the failure is invisible at all is #583.

Nine tests added, each checked against a mutation of the code it covers: accessibility on the time step (the first check never opened it), change, update:open, the controlled open, the resolved weekday across three locales, the throwing factory, the rejected locale, a time step opened without a value, and the defaultValue / defaultOpen seeds.

Not acted on. One reviewer read the "Inside a FormField" example as decorative, on the grounds that the component does not call useFormField itself. Measured instead: inside a B24FormField, the picker's inner input receives id="reka-popover-trigger-…" with the label's for pointing at it and aria-describedby="…-description" — the association works, through B24Input's own useFormField. disabled does not propagate, but a bare B24Input in the same disabled B24FormField does not receive it either, so that is not this component's behaviour to fix. Separately, a reviewer noted that a v-bind spread placed after individual binds can overwrite them with undefined; that ordering is the established convention at every forwarding site in the kit, so changing it here alone would make this component the odd one out.

What this does not do

• No range mode, and no top-level min-value / max-value / is-date-disabled — those reach the calendar through the calendar pass-through prop only.
• No segmented trigger; the trigger is readonly and opens the picker rather than accepting typed input.
• defineModel was not used; the component keeps the explicit prop/emit pair the rest of the kit uses.

Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

---

Local gate on bddc6ae3: lint 0, typecheck 0, pnpm test 353 files / 8049 passed / 6 skipped, docs:generate from a cold cache 1100 routes with no prerender errors and the API section populated (21 props, 4 slots, 3 emits).

🤖 Generated with Claude Code

https://claude.ai/code/session_012MsMuj8Fic9tjWVjyEyrxc