[Victor Genaev (mainframev)]

Stack: #36811 scaffold (merged) → #36845 spec → #36812 time utilities → #36813 TimePicker → #36814 headless TimePicker

Previous Behavior

The spec for @fluentui/react-timepicker-preview was part of the scaffold PR #36811, next to the generated boilerplate.

New Behavior

Adds library/docs/Spec.md on its own so the API can be reviewed separately from the scaffolding. The first commit is the spec as it was in #36811; the second commit resolves the review comments left there:

• onSelectedTimeChange data extends EventData<'change' | 'click' | 'keydown' | 'blur', TimePickerSelectedTimeChangeEvent>, so it satisfies EventHandler. A table documents how option selection, freeform commits and clearing are told apart from the payload.
• The default dateAnchor is resolved once on mount (initial selected time, else the current date) and never re-derived from later selections. Ranges that cross midnight require an explicit dateAnchor.
• Formatting and the default parser share one resolved hour cycle (hourCycle prop, else the locale's via Intl). The accepted input formats per cycle are listed, with a round-trip guarantee for ASCII digits and AM/PM; localized digits and day periods need a custom parseTimeStringToDate.
• increment is a finite positive integer. getTimesBetween advances by elapsed time and returns no options for an invalid increment.
• Selection follows the v9 form control convention: value / defaultValue (Date | null), optional displayValue for controlled input text, and onChange firing on commit, in the shape SpinButton uses. Compat's selectedTime / defaultSelectedTime / onTimeChange are mapped in the migration table.
• Commit outcomes are defined for invalid-input, out-of-bounds and required-input (selection, input text, highlighted option), together with the required attribute, the clear button and custom parsers.

The spec defines the contract. The implementation in #36812/#36813 is aligned to it in those PRs, together with the timeMath.ts review on #36812.

[github-actions]

Pull request demo site: URL

[github-actions]

📊 Bundle size report

✅ No changes found

[Paul Mardling (PaulGMardling)]

After an agent review, it left me with a few questions

[Paul Mardling (PaulGMardling)]

Looks good! Just the hook signature comment to address before merging. Thanks for the updates.

[Copilot]

🟢 Approval recommended

The documentation-only change has no identified blocking issues.

No open issues 🎉

What changed in this PR

Adds a standalone specification for the preview v9 TimePicker, separating API review from scaffolding and implementation.

Changes:

• Defines value handling, change events, formatting, parsing, and validation.
• Documents composition hooks, migration guidance, and accessibility behavior.

File	Description
packages/​react-components/​react-timepicker-preview/​library/​docs/​Spec.md	Defines the TimePicker API and behavior contract.

_{Review effort: Balanced}