FieldHub Date Pickers — UI/UX Reference Package

A. Orientation

Where everything lives. The numbered map keys each demo panel to its production component.

**01 — Full page overview AUTO** All panels: DateInput states, range modes, preset ranges, DateTimeInput & TimeInput, input rules, known gaps; props/model/event sidebar.

**02 — Component map ANNOT** 1 DateInput (`common/forms/fields/date-input`) · 2 range modes · 3 preset ranges (proposed) · 4 DateTimeInput + TimeInput (`date-time-input`, `time-input`) · 5 input rules · 6 known gaps · 7 live prop toggles.

B. Anatomy

The reference sheets a developer measures against. All parts wrap FormRow; menus come from @vuepic/vue-datepicker 8.8.1 restyled by jsapp3-datepicker.scss.

**03 — Closed field ANNOT** Label wired via `label[for]`; 32px icon `<button>`; input (34px, border `#ced4da`, radius 0 4 4 0); clear button when value && clearable; hint linked by `aria-describedby`.

**04 — Calendar menu ANNOT** 260px menu, 8px padding, 1px radius; stock month/year header; blue weekday row (`#0398db`); 35px cells; today ring.

**05 — Stock month/year header ANNOT PROPOSED** Chevrons step months; month button opens the all-months grid overlay; year button opens the original year picker.

**06 — Inline time picker ANNOT** Hour/minute columns with chevron steppers (proposed styling, see 42); 40px AM/PM toggle; 12-hour (`is24=false`).

**07 — Preset sidebar ANNOT PROPOSED** 118px-min sidebar via the library's `preset-dates`; clicking a preset applies the range and closes (autoApply).

C. Field states

Closed-input states. Focus border #66afe9 + glow; error border --dp-danger-color with aria-invalid + role="alert".

**08 — Empty AUTO** Placeholder `--/--/----` (`#767676`, AA), no clear button.

**09 — Filled AUTO** Committed value + clear button.

10 — Icon hover AUTO Addon darkens #e9ecef → #dde2e6.

**11 — Focused AUTO** Border `#66afe9` + soft glow on input and icon.

**12 — Disabled AUTO** Muted icon/input; icon button gets `disabled`.

**13 — Error AUTO** Red borders, message with `role="alert"`, input `aria-invalid`.

**14 — Required, resolved AUTO** Asterisk on label; error cleared after a valid pick.

**15 — State matrix COMP** All seven states side by side.

D. Menu variants

Every calendar/menu configuration the components support.

**16 — Default AUTO** Baseline single-date calendar, today ring.

**17 — highlightToday AUTO PROPOSED** Bold date number via `dayClass` hook; independent of `noToday`.

**18 — noToday AUTO** Today ring suppressed; today still selectable.

**19 — All-months overlay AUTO PROPOSED** Month button → Jan–Dec grid, current month highlighted.

**20 — Year overlay AUTO PROPOSED** Original year picker; ±20-year window, auto-extends at the edge.

**21 — disabledWeekDays AUTO** `[0, 6]`: weekends unselectable.

**22 — minDate/maxDate AUTO** Today → today+30; out-of-window days muted.

**23 — Range in progress AUTO** Start picked; hover previews the span.

**24 — Range complete AUTO** Start/end solid primary; between fill `#f3f3f3`.

**25 — multiCalendars AUTO** Two solo static calendars (`{ solo: true, static: true }`).

**26 — Preset ranges AUTO PROPOSED** Today … Last Year; Sunday-based weeks matching `week-start="0"`.

**27 — DateTimeInput AUTO** Calendar + inline 12-hour time.

**28 — TimeInput AUTO** Time columns only, clock icon trigger. Production structures this menu differently (15-min list + external AM/PM).

E. Interaction flows

Multi-frame sequences that a single still can't convey.

**29 — Range selection COMP** Empty → start + hover preview → committed range.

**30 — Error resolve COMP** Required error clears (message, border, `aria-invalid`) once a date is picked.

**31 — Forgiving text entry COMP PROPOSED** `7-5-26`, `07152026`, `7 . 5 . 2026`, a typed range, `3.30p`, `15:30` — all parse and commit. Production requires strict `MM/dd/yyyy`.

**32 — Preset apply COMP PROPOSED** "This Quarter" → full quarter committed, menu closes.

F. Responsive

Grid collapses at 1000px; fields stack single-column on phones; the two-calendar range stacks vertically.

**33 — Desktop 1440 AUTO** Two columns, sticky sidebar.

**34 — Tablet 768 AUTO** Sidebar stacks below the fields.

**35 — Mobile 375 AUTO** Single-column fields; no horizontal scroll.

**36 — Mobile two-calendar menu AUTO** Calendars stack vertically; 35px cells are below the 44px touch guideline (open finding).

G. Accessibility

What the proposal fixes and what still needs attention. Known open issues: Tab from an open menu drops focus to <body>; weekday-header contrast fails AA (see 39).

**37 — Focus rings COMP PROPOSED** 2px `#1976d2` `:focus-visible` outline, offset 1px, on icon and clear buttons (illustrative force-applied).

**38 — Tab order ANNOT** icon → input → (clear) per field, top-to-bottom through the form.

**39 — Contrast audit ANNOT BUG** Weekday header 2.6:1 and Fri/Sat `red-color` 2.5:1 fail AA (production palette); day text 7.5:1 passes.

**40 — ARIA wiring ANNOT PROPOSED** `label[for]`, per-field `aria-label`, `aria-invalid`, `aria-describedby` → `role="alert"` error. Production hardcodes `"Datepicker input"` on every field.

H. Proposed vs production

The decision set — each image is a change request or a defect report.

**41 — Month/year header COMP PROPOSED** Custom `MonthYearSelect` bar (production) vs library stock header. Adopting stock retires `MonthYearSelect` — and bug 46 with it.

**42 — Time steppers COMP PROPOSED** Production's flat 10×2 `#e0e0e0` bars vs chevrons in `#59676b` with `#1976d2` hover.

**43 — Today marking COMP PROPOSED** Default 1px ring vs `highlightToday` bold number.

**44 — Text contrast COMP PROPOSED** Placeholder 1.9:1 → 4.5:1; hint 3.2:1 → 5.8:1.

**45 — Weekend column bug ANNOT BUG** `#calendar-header` colours `index === 5 || 6` — Friday and Saturday under `week-start="0"`; the weekend is columns 0 and 6. `DateInput.vue:104`.

**46 — Partial-month bug ANNOT BUG** With a today→today+30 window, `MonthYearSelect.getMonths` truncates the fractional month diff and lists only "Jul" — August is selectable but unlisted. Needs `Math.ceil` (moot if 41 is adopted).

I. Tokens

Source of truth: uam/htdocs/v3/scss/jsapp3/_variables.scss and jsapp3-datepicker.scss.

**47 — Colour tokens COMP** Swatches with usage; AA-fixed values marked.

**48 — Sizing tokens ANNOT** Menu 260px / pad 8 / radius 1; header 35px; weekday row 40px; cells 35×35; font 13px.

Captured from the mockup at 2× device scale by docs/tools/capture.mjs (Playwright + installed Chrome). "Production" frames in section H come from a git worktree of the pre-change commit (d2b5f06) or from injected production CSS values, as noted per image. The mockup itself simplifies production in two ways (native Date model, library menu positioning) — see the "Known gaps" panel on the demo page.