@net-advantage/jo-ui-date-picker

Optional, clearable date field. A typed yyyy-mm-dd value stays in sync with a calendar popover. The value is an ISO date string, or null when the field is cleared. An empty string is accepted and treated as cleared.

There is no custom date-picker mock. Colour comes from the theme (--jo-color-*) and, inside a dialog, from the dialog tokens (--jo-ui-dialog-*). Type uses --jo-font-family (Inter) through --jo-ui-control-font-family. Metrics live on @net-advantage/jo-ui-theme as --jo-date-picker-*. This package depends on that theme with workspace:* (published as the workspace version) and peers ^1.4.4, the same dependency and peer split the year bar uses for its packages and React. Each var(--jo-date-picker-*) repeats the theme value as a fallback, so an older theme stylesheet still renders.

The field uses FieldMetadata for the label, helper, required marker, and ids. value and onValueChange match FormLayout. label or ariaLabel is required. A visible label is preferred and is referenced with aria-labelledby. ariaLabel is the text field's aria-label when the picker should not show a label. Passing neither is a compile error. A string label is trimmed, and a blank string is treated as no visible label. label may be any React node.

MVVM

flowchart LR
  Props["DatePickerProps"] --> ViewModel["useDatePickerViewModel"]
  Model["jo-ui-date-picker.model.ts<br/>ISO dates, grid, min and max"] --> ViewModel
  ViewModel --> View["DatePicker.tsx"]
  View -->|"type, pick, clear"| ViewModel
  ViewModel -->|"onValueChange"| Host["Host application"]

| Layer | File | Responsibility | | --- | --- | --- | | Contract | jo-ui-date-picker.types.ts | Props, ISO value, and the view-model | | Model | jo-ui-date-picker.model.ts | Normalize ISO dates, build the month grid, apply min and max, decide keyboard moves, and place the popover against a boundary | | View-model | jo-ui-date-picker.view-model.ts | Framework-free date picker observable; own the draft, open state, focus return, and event guards | | View | jo-ui-date-picker.use-view-model.ts | useDatePickerViewModel reads that observable and owns focus, popover placement, and outside-pointer effects | | View | DatePicker.tsx | Render the field, clear control, and dialog grid from the view-model |

Models

flowchart TD
  Props["DatePickerProps"] --> Value["ISO value or null"]
  Props --> Bounds["min and max"]
  Value --> Grid["month grid"]
  Bounds --> Grid
  Today["today"] --> Grid
  Grid --> ViewModel["DatePickerViewModel"]
  Value --> ViewModel
  Field["field box"] --> Placement["above or below, shifted"]
  Boundary["viewport and clipping ancestors"] --> Placement
  Placement --> ViewModel

• value controls the field when it is not undefined. null and '' are empty. Omit value to use defaultValue.
• onValueChange receives yyyy-mm-dd or null. It does not emit ''.
• clearable defaults to true. The clear button is in the tab order while a value is present and the field can be edited.
• required defaults to false. The required marker comes from FieldMetadata.
• min and max are inclusive. Out-of-range days stay visible, with aria-disabled="true", and typed out-of-range values are rejected.
• The popover is role="dialog" with aria-modal="true". The month is role="grid". Arrow keys move by day, Home and End move to the start and end of the displayed week, PageUp and PageDown move by month, and Shift plus PageUp or PageDown move by year. Enter or Space selects. Escape calls preventDefault and stopPropagation, closes the calendar, and returns focus to the calendar button. A parent jo-ui-dialog listens for Escape on the way back up and ignores an event that is already defaultPrevented, so the parent stays open. Today has aria-current="date". The value has aria-selected="true". Column headers use the weekday name for the first day of that column.
• weekStartsOn is 0 (Sunday) or 1 (Monday). It defaults to 1, which matches an AU/NZ week. Home and End follow the same start. Day names stay the real weekday either way.
• The field uses the same border-box height as a jo-ui-input text field: --jo-date-picker-control-height (2.5rem, 40px), with the 1px border inside that height. The inner input stretches to the content box (height: 100%). It used to set its own height to 2.5rem, so the control's top and bottom borders added 2px and the field painted at 42px.
• From --jo-date-picker-compact-max (420px) down, including a 375px viewport, the field's border box is the 44px hit target (--jo-date-picker-hit-min). Calendar nav buttons keep that 44px target on their own. The popover width is capped to the viewport.
• The popover opens below the field. When that box does not fit in the viewport, or in a scrolling or clipping ancestor, it flips above the field. It shifts sideways, and its width and height are capped to that boundary, so a dialog edge does not cut off the month controls. The gap is --jo-date-picker-gap and the boundary inset is --jo-date-picker-popover-gutter.
• The shipped stylesheet is scoped to .jo-ui-date-picker. It does not emit Tailwind utility selectors such as .flex, .hidden, or .block.

Structure

• src: runtime component, model, view-model, types, and companion tests.
• stories: Storybook stories for the closed field, open calendar, Sunday week start, min and max, the cleared state, and the calendar near the bottom of a dialog.

Publish footprint

This package publishes only:

• dist
• README.md

Stories and tests are excluded from the published artifact by design.