@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/DateTimeInput/DateTimeInput.doc.mjs

@@ -115,8 +115,8 @@ export const docs = {
       name: 'hourFormat',
       type: "'12h' | '24h'",
       description:
-        "Hour display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
-      default: "'12h'",
+        "Hour display format. '12h' shows the locale's day period; '24h' uses 24-hour notation. When unset, follows the InternationalizationProvider locale's hour cycle (en-US 12-hour, en-GB 24-hour); a person's own preference rides on the locale tag (e.g. 'en-US-u-hc-h23').",
+      default: "the locale's hour cycle",
     },
     {
       name: 'timeIncrement',
@@ -270,7 +270,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          "Choose the hour format (12h or 24h) that matches your audience's locale.",
+          "Leave hourFormat unset so the field follows the InternationalizationProvider locale's hour cycle (12-hour in en-US, 24-hour in en-GB or de-DE). Set it only when the field itself needs a fixed format, and carry a person's own 12/24-hour preference on the provider locale (e.g. 'en-US-u-hc-h23') rather than on each field.",
       },
       {
         guidance: false,
@@ -393,7 +393,7 @@ export const docsZh = {
       {
         guidance: true,
         description:
-          "Choose the hour format (12h or 24h) that matches your audience's locale.",
+          "Leave hourFormat unset so the field follows the InternationalizationProvider locale's hour cycle (12-hour in en-US, 24-hour in en-GB or de-DE). Set it only when the field itself needs a fixed format, and carry a person's own 12/24-hour preference on the provider locale (e.g. 'en-US-u-hc-h23') rather than on each field.",
       },
       {
         guidance: false,
@@ -502,8 +502,9 @@ export const docsZh = {
     {
       name: 'hourFormat',
       type: "'12h' | '24h'",
-      description: "控制显示格式。'12h' 显示 AM/PM；'24h' 使用 24 小时制。",
-      default: "'12h'",
+      description:
+        "控制显示格式。'12h' 使用区域设置的上午/下午用语；'24h' 使用 24 小时制。未设置时遵循 InternationalizationProvider 区域设置的小时制（en-US 为 12 小时制，en-GB 为 24 小时制）；用户自己的偏好可通过区域标签传入（例如 'en-US-u-hc-h23'）。",
+      default: '区域设置的小时制',
     },
     {
       name: 'timeIncrement',
@@ -648,7 +649,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          "Choose the hour format (12h or 24h) that matches your audience's locale.",
+          "Leave hourFormat unset so the field follows the InternationalizationProvider locale's hour cycle (12-hour in en-US, 24-hour in en-GB or de-DE). Set it only when the field itself needs a fixed format, and carry a person's own 12/24-hour preference on the provider locale (e.g. 'en-US-u-hc-h23') rather than on each field.",
       },
       {
         guidance: false,
@@ -690,7 +691,8 @@ export const docsDense = {
     dateConstraints: 'custom constraint fns to disable specific dates',
     hasSeconds:
       'include seconds; retains Astryx time field because iOS native picker has no seconds wheel',
-    hourFormat: "display format. '12h' shows AM/PM; '24h' uses 24-hour",
+    hourFormat:
+      "display format. '12h' shows the locale's day period; '24h' uses 24-hour. Unset follows the provider locale's hour cycle (a -u-hc- tag carries a user preference)",
     timeIncrement:
       'minute step for Astryx typed field; non-default retains Astryx time field in native modes because iOS native step is validation-only',
     timeOptionInterval:

package/src/DateTimeInput/DateTimeInput.spec.md

@@ -3,11 +3,11 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:DateTimeInput
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-30
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
@@ -16,30 +16,37 @@ verified_by:
     packages/core/src/DateTimeInput/DateTimeInputTouch.test.tsx,
     packages/core/src/DateTimeInput/NativePickerSegments.test.tsx,
     packages/core/src/DateTimeInput/Presentation.test.tsx,
+    packages/core/src/DateTimeInput/DateTimeInput.fr10.test.tsx,
+    packages/core/src/__tests__/BusyOwnerAnnouncement.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
     scripts/check-knowledge.mjs,
   ]
 modules: []
 families: [family:input-fields, family:overlay-dismissal]
 design_specs: []
-architecture: [architecture:component-theming-surface]
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:internationalization,
+    architecture:public-component-api,
+  ]
 contributing: []
-system_specs: [spec:AST-043]
+system_specs: [spec:AST-043, spec:AST-085, spec:AST-086, spec:AST-102]
 ---
 
 # DateTimeInput component contract
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                  |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | One controlled ISO date-time value presented through coordinated date and time segments; `presentation` selects Astryx, native, or adaptive picker surfaces.                                              |
-| Behavior                | Date and time changes emit one combined value; clear emits `undefined`; controlled empty state remains empty in every rendered picker.                                                                    |
-| End-user impact         | People selecting a date and time see one value reflected consistently in the closed field and the active picker, including after clearing.                                                                |
-| Builder impact          | None.                                                                                                                                                                                                     |
-| Compatibility/readiness | Released defaults and deprecated `nativePicker` behavior remain unchanged. The presentation matrix is governed by current `spec:AST-043`; component-local observations remain draft pending owner review. |
-| Review checks           | Reject competing picker selection, date/time output that is not one valid combined value, presentation precedence drift, lost per-segment fallback, or broken segment accessibility.                      |
-| Governing rules         | `spec:AST-043`, `family:input-fields`, `family:overlay-dismissal`, and objective platform accessibility standards.                                                                                        |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | One controlled ISO date-time value presented through coordinated date and time segments; `presentation` selects Astryx, native, or adaptive picker surfaces.                                                                                                                                                                                                                                    |
+| Behavior                | Date and time changes emit one combined value; clear emits `undefined`; controlled empty state remains empty in every rendered picker.                                                                                                                                                                                                                                                          |
+| End-user impact         | People selecting a date and time see one value reflected consistently in the closed field and the active picker, including after clearing.                                                                                                                                                                                                                                                      |
+| Builder impact          | A caller that relied on the `12h` hour-format default under a 24-hour locale passes `hourFormat="12h"` to keep twelve-hour time text. A per-user 12/24-hour preference goes on the provider locale as a `-u-hc-` extension (`en-US-u-hc-h23`).                                                                                                                                                  |
+| Compatibility/readiness | The `hourFormat` default is the provider locale's hour cycle (`12h` for `en`/`en-US` and with no provider); every other released default, API, and DOM shape holds. The presentation matrix and deprecated `nativePicker` mapping follow `spec:AST-043`. Fixed segment height, typed-time prefix commits, busy paint, and caller handlers while disabled are listed under Current-state impact. |
+| Review checks           | Reject competing picker selection, date/time output that is not one valid combined value, presentation precedence drift, lost per-segment fallback, or broken segment accessibility.                                                                                                                                                                                                            |
+| Governing rules         | `spec:AST-043`, `family:input-fields`, `family:overlay-dismissal`, `spec:AST-085`, `spec:AST-086` FR8, and objective platform accessibility standards.                                                                                                                                                                                                                                          |
 
 This table is a review projection; the body below is authoritative.
 
@@ -52,9 +59,11 @@ or pointer-adaptive combinations of those surfaces.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: no public surface change; existing types, defaults,
-  callbacks, roles, and exports remain stable
+- Released default preserved: `yes`, except `hourFormat`, which follows the
+  provider locale's hour cycle (`12h` for `en` and `en-US`, the released
+  default with no provider) and shares TimeInput's locale time text
+- Compatibility class: default change for non-English-US locales; existing
+  types, callbacks, roles, and exports remain stable
 - Controlled/uncontrolled behavior: DateTimeInput remains controlled; `undefined`
   represents no committed date-time value
 - Migration decision: none; picker presentation and deprecated `nativePicker`
@@ -71,13 +80,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 - Applying component-local date-time bounds, date constraints, time precision,
   typed-time stepping, and optional preset-time behavior.
 - Emitting `onChange` before an optional optimistic `changeAction`.
+- The disabled-reason Tooltip composition, which `family:input-fields` assigns
+  to the member.
 
 **Does not own / non-goals**
 
-- Field label, description, status, disabled-reason, and clear-button presentation —
-  owned by `component:Field` and `component:FieldStatus`.
+- Field label, description, status, and clear-button presentation —
+  owned by Field under `family:input-fields` (shared owner section) and
+  `component:FieldStatus`.
 - Calendar-grid rendering and date-cell interaction — owned by
-  `component:Calendar`.
+  Calendar.
 - Popover and sheet hosting or dismissal — owned by the composed layer components
   and `family:overlay-dismissal`.
 - Cross-component picker-presentation vocabulary and deprecated-prop mapping —
@@ -95,18 +107,17 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                       | Basis                                                                 | Draft review state                                     |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------ |
-| FR1 | DateTimeInput MUST reflect one controlled date-time value across its visible segments and active picker, and MUST NOT reveal a competing selected date after the parent accepts a clear.                                                  | Public docs, controlled component seam, current source, focused tests | Verified observation; owner approval pending           |
-| FR2 | Every committed date or time change MUST emit one valid combined ISO date-time value; clearing MUST emit `undefined`; changing time while no date is committed MUST emit nothing.                                                         | Public types, docs, current source, focused tests                     | Verified observation; owner approval pending           |
-| FR3 | `presentation`, deprecated `nativePicker`, precedence, pointer adaptation, forced surfaces, and per-segment native fallbacks MUST follow `spec:AST-043` FR1–FR4.                                                                          | `spec:AST-043`                                                        | Inherited current authority                            |
-| FR4 | When `changeAction` is present, every value-change path MUST call `onChange` first, show the proposed controlled value optimistically, and contribute to one busy state until the controlled value accepts or replaces it.                | `family:input-fields/FR6`                                             | Inherited current authority                            |
-| FR5 | The two pointer segments share one row while each retains its intrinsic basis; when the container is narrower, flex wrapping moves them into separate full-width rows.                                                                    | Public docs, current source, focused layout tests                     | Verify rendered geometry; class-level behavior covered |
-| FR6 | Date-time bounds and date constraints MUST prevent invalid commits. Native controls MAY receive platform hints, but JavaScript validation remains the final commit boundary; calendar-only options MAY be unavailable on native surfaces. | Public docs, current source, focused presentation tests               | Verified observation; owner approval pending           |
-| FR7 | A preset-time listbox MUST remain optional, preserve typed entry, expose one selected option independently from keyboard highlight, and limit offered values to the selected date's effective minimum and maximum.                        | Public docs, current source, focused interaction tests                | Verified observation; owner approval pending           |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                                                                                   |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| FR1 | DateTimeInput MUST reflect one controlled date-time value across its visible segments and active picker, and MUST NOT reveal a competing selected date after the parent accepts a clear.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Public docs, controlled component seam, current source, focused tests                                   |
+| FR2 | Every committed date or time change MUST emit one valid combined ISO date-time value; clearing MUST emit `undefined`; changing time while no date is committed MUST emit nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Public types, docs, current source, focused tests                                                       |
+| FR3 | `presentation`, deprecated `nativePicker`, precedence, pointer adaptation, forced surfaces, and per-segment native fallbacks MUST follow `spec:AST-043` FR1–FR4.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `spec:AST-043`                                                                                          |
+| FR4 | When `changeAction` is present, every value-change path MUST call `onChange` first, show the proposed controlled value optimistically, and contribute to one busy state until the controlled value accepts or replaces it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `family:input-fields/FR6`                                                                               |
+| FR5 | The two pointer segments share one row while each retains its intrinsic basis; when the container is narrower, flex wrapping moves them into separate full-width rows. Each segment is the shared element height for its size, as a minimum that grows with a set text size under `spec:AST-102` FR4. Implementation gap: the height is fixed at that size.                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Public docs, current source, focused layout tests; `spec:AST-102` FR4                                   |
+| FR6 | Date-time bounds and date constraints MUST prevent invalid commits. Native controls MAY receive platform hints, but JavaScript validation remains the final commit boundary; calendar-only options MAY be unavailable on native surfaces.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Public docs, current source, focused presentation tests                                                 |
+| FR7 | A preset-time listbox MUST remain optional, preserve typed entry, expose one selected option independently from keyboard highlight, and limit offered values to the selected date's effective minimum and maximum. Time text and typed times MUST follow the active locale's digits, separator, and day-period words (`architecture:internationalization` INV1a, INV8). The hour format is `hourFormat` when set, else the provider locale's hour cycle; time text, preset options, and the stepped-time announcement come from the shared time formatter, and typed times parse the locale's digits, separators, and day-period words as well as English. Implementation gap: the typed time field commits as soon as a prefix parses.                                                                            | Public docs, current source, focused interaction tests; `architecture:internationalization` INV1a, INV8 |
+| FR8 | Base props and `ref` MUST reach the date segment's input; a caller `aria-describedby` joins the component's own descriptions, and a caller DOM handler runs after the field's own handler. `container*` reaches the Field box and `control*` the segment row; root `xstyle`, `className`, and `style` are not accepted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `family:input-fields` FR10; `DateTimeInput.fr10.test.tsx`                                               |
+| FR9 | A disabled field MUST keep both segments focusable with `aria-disabled` and no native `disabled`, block every value-changing path, keep the calendar button's tab stop, and paint the keyboard focus ring. Explicit `isLoading` makes every surface inert the same way; a pending `changeAction` does so only on the popover surface, and the bottom sheet and any field with a native date segment keep accepting edits. The busy start is announced once. Implementation gap: a caller `onKeyDown` and other DOM handlers on the date segment still run while disabled (`spec:AST-085` FR2). Implementation gap: a busy field that is not disabled takes the disabled paint (half opacity), on every surface while `isLoading` and on the popover while a `changeAction` is pending, against `spec:AST-085` FR6. | `spec:AST-085` FR1, FR2, FR6; `spec:AST-086` FR8; current source and tests                              |
 
 ### Allowed variation
 
@@ -119,13 +130,13 @@ intentional decision.
 
 ### Representative states
 
-| State                       | Required invariant                                                                                        | Allowed variation                          |
-| --------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| Empty                       | Both segments and every active picker expose no committed selection.                                      | Placeholder and selected surface.          |
-| Date-time value             | Date segment, time segment, and active picker reflect the same committed value.                           | Locale, hour format, and time precision.   |
-| Cleared after picker change | Closed field is empty and reopening the picker reveals no selected date or retained committed time.       | Picker focus date may remain navigational. |
-| Busy                        | Proposed value remains visible; mutation paths are unavailable; both editable segments expose busy.       | Explicit loading or pending action source. |
-| Focusable disabled          | Both segments remain focusable enough to expose the reason while every value-changing path stays blocked. | Disabled-reason text.                      |
+| State                       | Required invariant                                                                                                                                                                                          | Allowed variation                          |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| Empty                       | Both segments and every active picker expose no committed selection.                                                                                                                                        | Placeholder and selected surface.          |
+| Date-time value             | Date segment, time segment, and active picker reflect the same committed value.                                                                                                                             | Locale, hour format, and time precision.   |
+| Cleared after picker change | Closed field is empty and reopening the picker reveals no selected date or retained committed time.                                                                                                         | Picker focus date may remain navigational. |
+| Busy                        | Proposed value remains visible; both editable segments expose busy. With explicit `isLoading`, mutation paths are unavailable on every surface; with a pending `changeAction`, only on the popover surface. | Explicit loading or pending action source. |
+| Focusable disabled          | Both segments stay focusable with `aria-disabled` while every value-changing path stays blocked.                                                                                                            | Disabled-reason text.                      |
 
 ### Transformation and precedence order
 
@@ -220,24 +231,37 @@ leading clock glyph uses `date-time-input-clock-icon`.
 
 ## Verification map
 
-| Contract            | Verification                                                                            | Representative states                                         | Mutation or failure expectation                                                                                                      | Audit section                     |
-| ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
-| FR1–FR2             | `DateTimeInput.test.tsx`                                                                | empty, calendar selection, typed date/time, clear             | A stale Calendar selection, partial output, or invalid mutation makes a public-state test fail.                                      | `audit:DateTimeInput/behavior`    |
-| FR3, FR6            | `Presentation.test.tsx`, `NativePickerSegments.test.tsx`, `DateTimeInputTouch.test.tsx` | forced, adaptive, legacy, native fallback, constrained commit | A substituted surface, precedence drift, or invalid commit makes a presentation test fail.                                           | `audit:DateTimeInput/surfaces`    |
-| FR4, AR4            | `DateTimeInput.test.tsx`, `DateTimeInputTouch.test.tsx`                                 | pending, loading, disabled reason                             | Mutation during busy/disabled state or stale optimistic output makes a state test fail.                                              | `audit:DateTimeInput/state`       |
-| FR5                 | `DateTimeInput.test.tsx`                                                                | intrinsic row, narrow-container wrap classes                  | Removing the intrinsic basis or wrap styles makes the class-level layout assertions fail; rendered geometry remains review evidence. | `audit:DateTimeInput/layout`      |
-| FR7, AR1–AR3        | `DateTimeInput.test.tsx`, `DateTimeInputTouch.test.tsx`                                 | popovers, time options, keyboard/focus                        | Wrong role, name, state, keyboard behavior, or focus behavior makes a focused interaction test fail.                                 | `audit:DateTimeInput/interaction` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`                                 | root, segments, icons, listbox, options                       | Missing, undocumented, or wrongly placed targets fail knowledge or target checks.                                                    | `audit:DateTimeInput/theming`     |
+| Contract            | Verification                                                                                                 | Representative states                                         | Mutation or failure expectation                                                                                                                                                                                                                      | Audit section                     |
+| ------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1–FR2             | `DateTimeInput.test.tsx`                                                                                     | empty, calendar selection, typed date/time, clear             | A stale Calendar selection, partial output, or invalid mutation makes a public-state test fail.                                                                                                                                                      | `audit:DateTimeInput/behavior`    |
+| FR3, FR6            | `Presentation.test.tsx`, `NativePickerSegments.test.tsx`, `DateTimeInputTouch.test.tsx`                      | forced, adaptive, legacy, native fallback, constrained commit | A substituted surface, precedence drift, or invalid commit makes a presentation test fail.                                                                                                                                                           | `audit:DateTimeInput/surfaces`    |
+| FR4, FR9, AR4       | `DateTimeInput.test.tsx`, `DateTimeInputTouch.test.tsx`; `BusyOwnerAnnouncement.test.tsx` DateTimeInput case | pending, loading, disabled reason                             | Mutation during busy/disabled state or stale optimistic output makes a state test fail. Evidence gap: no test asserts that caller handlers still run while disabled.                                                                                 | `audit:DateTimeInput/state`       |
+| FR5                 | `DateTimeInput.test.tsx`                                                                                     | intrinsic row, narrow-container wrap classes                  | Removing the intrinsic basis or wrap styles makes the class-level layout assertions fail; rendered geometry remains review evidence. Evidence gap: no test asserts segment heights or text growth.                                                   | `audit:DateTimeInput/layout`      |
+| FR7, AR1–AR3        | `DateTimeInput.test.tsx`, `DateTimeInputTouch.test.tsx`                                                      | popovers, time options, keyboard/focus                        | Wrong role, name, state, keyboard behavior, or focus behavior makes a focused interaction test fail. A provider-locale test asserts the closed time text follows the locale's hour cycle and day period; the shared formatter's tests cover parsing. | `audit:DateTimeInput/interaction` |
+| FR8                 | `DateTimeInput.fr10.test.tsx`                                                                                | each surface; caller id, describedby, onClick, onKeyDown      | A base prop off the date input, a dropped caller description, or styling on the wrong part fails.                                                                                                                                                    | `audit:DateTimeInput/api`         |
+| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`                                                      | root, segments, icons, listbox, options                       | Missing, undocumented, or wrongly placed targets fail knowledge or target checks.                                                                                                                                                                    | `audit:DateTimeInput/theming`     |
+
+## Current-state impact
+
+- **Fixed height (FR5).** Segments hold the fixed shared element height instead
+  of growing with a set text size, against `spec:AST-102` FR4.
+- **Typed-time prefix commits (FR7).** The typed time field commits a parsed
+  prefix, so a typed time can commit a different time, against
+  `architecture:internationalization` INV8.
+- **Busy paint (FR9).** A busy field that is not disabled takes the disabled
+  half-opacity paint, against `spec:AST-085` FR6.
+- **Caller handlers while disabled (FR9).** Caller DOM handlers on the date
+  segment, such as `onKeyDown`, still run while disabled, against
+  `spec:AST-085` FR2.
 
 ## Decision log
 
-No component-local decision is asserted by this draft. Current cross-component
-picker decisions remain in `spec:AST-043`.
+No component-local decision. Cross-component picker decisions live in
+`spec:AST-043`.
 
 ## Open questions
 
-None. Owner review may accept, amend, or reject the observational component-local
-rows without changing inherited current authority.
+None.
 
 ## Content boundary
 

package/src/DateTimeInput/DateTimeInput.tsx

@@ -71,9 +71,6 @@ import {
   type ISOTimeString,
   parseDateInput,
   parseISOTime,
-  parseTimeInput,
-  formatDisplayTime12h,
-  formatDisplayTime24h,
   formatISOTime,
   isTimeInRange,
   adjustTime,
@@ -102,6 +99,11 @@ import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {useLocale, useTranslator} from '../i18n';
+import {
+  formatLocaleTime,
+  parseLocaleTime,
+  resolveHourFormat,
+} from '../utils/timeFormat';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useHighlightedOptionScroll} from '../hooks/useHighlightedOptionScroll';
@@ -412,8 +414,11 @@ export interface DateTimeInputProps extends Omit<
   hasSeconds?: boolean;
 
   /**
-   * Hour display format.
-   * @default '12h'
+   * Hour display format: '12h' with the locale's day period, or '24h'.
+   * When unset, follows the `InternationalizationProvider` locale's hour
+   * cycle (`en-US` 12-hour, `en-GB` 24-hour); a per-user preference rides on
+   * the locale tag (`en-US-u-hc-h23`).
+   * @default the locale's hour cycle
    */
   hourFormat?: DateTimeInputHourFormat;
 
@@ -836,8 +841,11 @@ function PointerDateTimeField({
   }
   const nativeTimeValue = nativeTimeDraft ?? valueParts.time;
 
-  const formatDisplayTime =
-    hourFormat === '12h' ? formatDisplayTime12h : formatDisplayTime24h;
+  const formatDisplayTime = useCallback(
+    (time: ISOTimeString, includeSeconds: boolean) =>
+      formatLocaleTime(time, locale, hourFormat, includeSeconds),
+    [locale, hourFormat],
+  );
 
   const timeDisplayValue = useMemo(() => {
     if (timePendingInput !== null) {
@@ -852,12 +860,12 @@ function PointerDateTimeField({
     if (timePendingInput === null || !timePendingInput.trim()) {
       return true;
     }
-    const parsed = parseTimeInput(timePendingInput, hasSeconds);
+    const parsed = parseLocaleTime(timePendingInput, locale, hasSeconds);
     if (!parsed) {
       return false;
     }
     return isTimeInRange(parsed, timeMin, timeMax);
-  }, [timePendingInput, hasSeconds, timeMin, timeMax]);
+  }, [timePendingInput, locale, hasSeconds, timeMin, timeMax]);
 
   const resolvedTimePlaceholder = useMemo(() => {
     if (isTimeFocused && !timeDisplayValue) {
@@ -1362,7 +1370,7 @@ function PointerDateTimeField({
       const text = e.target.value;
       setTimePendingInput(text);
 
-      const parsed = parseTimeInput(text, hasSeconds);
+      const parsed = parseLocaleTime(text, locale, hasSeconds);
 
       // Typing narrows nothing — free-form entry is the contract, and a time
       // between two options must stay reachable. The list instead follows the
@@ -1386,6 +1394,7 @@ function PointerDateTimeField({
       }
     },
     [
+      locale,
       hasSeconds,
       timeMin,
       timeMax,
@@ -1440,7 +1449,7 @@ function PointerDateTimeField({
         return;
       }
 
-      const parsed = parseTimeInput(timePendingInput, hasSeconds);
+      const parsed = parseLocaleTime(timePendingInput, locale, hasSeconds);
       if (parsed && isTimeInRange(parsed, timeMin, timeMax)) {
         if (parsed !== valueParts.time && valueParts.date) {
           const combined = combineDateTime(valueParts.date, parsed);
@@ -1453,6 +1462,7 @@ function PointerDateTimeField({
     },
     [
       timePendingInput,
+      locale,
       hasSeconds,
       timeMin,
       timeMax,
@@ -1530,7 +1540,7 @@ function PointerDateTimeField({
               const typed =
                 timeHighlightFollowsTypingRef.current &&
                 timePendingInput !== null
-                  ? parseTimeInput(timePendingInput, hasSeconds)
+                  ? parseLocaleTime(timePendingInput, locale, hasSeconds)
                   : null;
               const option = timeOptions[activeTimeIndex];
               if (typed) {
@@ -1582,6 +1592,7 @@ function PointerDateTimeField({
     },
     [
       valueParts,
+      locale,
       hasSeconds,
       timeIncrement,
       timeMin,
@@ -1937,17 +1948,21 @@ function PointerDateTimeField({
 
       {!usesNativePicker &&
         popover.render(
-          <Calendar
-            handleRef={calendarRef}
-            mode="single"
-            value={valueParts.date ?? null}
-            onChange={(d: ISODateString) => handleDateChange(d, 'calendar')}
-            min={calendarMin}
-            max={calendarMax}
-            dateConstraints={dateConstraints}
-            numberOfMonths={numberOfMonths}
-            weekStartsOn={weekStartsOn}
-          />,
+          // Mounted only while open, like the time list below; the calendar
+          // opens on the current value.
+          !popover.isOpen ? null : (
+            <Calendar
+              handleRef={calendarRef}
+              mode="single"
+              value={valueParts.date ?? null}
+              onChange={(d: ISODateString) => handleDateChange(d, 'calendar')}
+              min={calendarMin}
+              max={calendarMax}
+              dateConstraints={dateConstraints}
+              numberOfMonths={numberOfMonths}
+              weekStartsOn={weekStartsOn}
+            />
+          ),
           {placement: 'below', alignment: 'start'},
         )}
 
@@ -2030,11 +2045,18 @@ export function DateTimeInput(props: DateTimeInputProps) {
     props.presentation,
     props.nativePicker,
   );
+  const locale = useLocale();
   const {
     presentation: _presentation,
     nativePicker: _nativePicker,
-    ...rest
+    ...surfaceProps
   } = props;
+  // Every surface gets the resolved hour format, so typed text, the native
+  // field's resting text, preset times, and the sheet wheels agree.
+  const rest = {
+    ...surfaceProps,
+    hourFormat: resolveHourFormat(locale, props.hourFormat),
+  };
   if (effective === 'native') {
     return (
       <PointerDateTimeField

package/src/DateTimeInput/NativeTimeSegment.tsx

@@ -34,13 +34,12 @@ import type {InputStatusType} from '../Field';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {Icon} from '../Icon';
-import {useTranslator} from '../i18n';
+import {useLocale, useTranslator} from '../i18n';
+import {formatLocaleTime} from '../utils/timeFormat';
 import type {ThemeProps} from '../utils/themeProps';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {
   focusOutlineStyles,
-  formatDisplayTime12h,
-  formatDisplayTime24h,
   formatISOTime,
   isTimeInRange,
   parseISOTime,
@@ -126,6 +125,7 @@ export function NativeTimeSegment({
     ...inputProps
   } = controlProps ?? {};
   const t = useTranslator();
+  const locale = useLocale();
   const isTouchPointer = useMediaQuery('(pointer: coarse)');
   const internalInputRef = useRef<HTMLInputElement | null>(null);
   const mergedInputRef = useMergedRefs(inputRef, internalInputRef);
@@ -151,10 +151,8 @@ export function NativeTimeSegment({
 
   const nativeValue = normalizeNativeTime(value) ?? '';
   const isInputValid = rejectedValue === null;
-  const formatDisplayTime =
-    hourFormat === '12h' ? formatDisplayTime12h : formatDisplayTime24h;
   const overlayText = nativeValue
-    ? formatDisplayTime(nativeValue, false)
+    ? formatLocaleTime(nativeValue, locale, hourFormat, false)
     : placeholder;
   const showsOverlay = !!overlayText && !(isFocused && isSegmentEditable);
 

package/src/DateTimeInput/TouchDateTimeField.tsx

@@ -69,9 +69,8 @@ import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {rtlStyles} from '../utils/rtlStyles';
 import {themeProps} from '../utils/themeProps';
 import {normalizeDayOfWeek} from '../utils/dateTypes';
+import {formatLocaleTime} from '../utils/timeFormat';
 import {
-  formatDisplayTime12h,
-  formatDisplayTime24h,
   formatISOTime,
   isImeKeyEvent,
   isRenderable,
@@ -689,12 +688,9 @@ export function TouchDateTimeField({
   const timeDisplayValue = useMemo(() => {
     const displayTime = normalizedValueTime ?? draftTime;
     return displayTime
-      ? (hourFormat === '12h' ? formatDisplayTime12h : formatDisplayTime24h)(
-          displayTime,
-          hasSeconds,
-        )
+      ? formatLocaleTime(displayTime, locale, hourFormat, hasSeconds)
       : '';
-  }, [draftTime, normalizedValueTime, hourFormat, hasSeconds]);
+  }, [draftTime, normalizedValueTime, locale, hourFormat, hasSeconds]);
 
   const timeBoundsForDate = useCallback(
     (date: ISODateString | undefined) => ({

package/src/Dialog/Dialog.tsx

@@ -69,14 +69,18 @@ import {
   overlayPaddingReset,
 } from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {chainEventHandlers} from '../utils/chainEventHandlers';
 import {devWarn} from '../utils/devWarning';
 import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
 import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
-import {useInteractionModalityTracking} from '../utils/interactionModality';
+import {
+  getInteractionModality,
+  trackInteractionModalityIn,
+  useInteractionModalityTracking,
+} from '../utils/interactionModality';
 import {focusForLastInput} from '../utils/focusReturn';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 
@@ -91,8 +95,11 @@ function getDialogDirection(
   distance = 16,
 ): {x: number; y: number} {
   const rect = triggerEl.getBoundingClientRect();
-  const dx = rect.left + rect.width / 2 - window.innerWidth / 2;
-  const dy = rect.top + rect.height / 2 - window.innerHeight / 2;
+  // The trigger's own window: its rect is measured in that window's viewport,
+  // which is not the page's when the dialog renders into a second document.
+  const view = triggerEl.ownerDocument.defaultView ?? window;
+  const dx = rect.left + rect.width / 2 - view.innerWidth / 2;
+  const dy = rect.top + rect.height / 2 - view.innerHeight / 2;
   const dist = Math.sqrt(dx * dx + dy * dy) || 1;
   return {
     x: Math.round((dx / dist) * distance),
@@ -534,6 +541,18 @@ export function Dialog({
 
   useInteractionModalityTracking();
 
+  // Input in a second document (a same-origin iframe, a Document
+  // Picture-in-Picture window) never reaches the page's listeners, so the
+  // dialog's own document keeps its own last input for the focus return while
+  // this Dialog is mounted, from before it opens until it unmounts.
+  useEffect(() => {
+    const ownerDocument = dialogRef.current?.ownerDocument;
+    if (ownerDocument == null || ownerDocument === document) {
+      return undefined;
+    }
+    return trackInteractionModalityIn(ownerDocument);
+  }, [isInline]);
+
   // This runs in a layout effect so the capture lands before any descendant's
   // passive mount effect: all layout effects run before any passive effect,
   // while a child's passive effect runs before this parent's passive effect.
@@ -545,7 +564,15 @@ export function Dialog({
     if (isInline || !isOpen) {
       return;
     }
-    triggerElementRef.current = document.activeElement as HTMLElement | null;
+    // The dialog's own document while it holds focus: an app can render a
+    // dialog into a second document (a same-origin iframe, a Document
+    // Picture-in-Picture window) through a portal, and a control there that
+    // opens it is focused in that document, which the page's document reports
+    // only as the iframe element, or not at all. A control in the page that
+    // opens such a dialog leaves focus in the page.
+    const dialogDocument = dialogRef.current?.ownerDocument ?? document;
+    const doc = dialogDocument.hasFocus() ? dialogDocument : document;
+    triggerElementRef.current = doc.activeElement as HTMLElement | null;
   }, [isOpen, isInline]);
 
   // Derive dismissal behavior from purpose
@@ -567,7 +594,7 @@ export function Dialog({
       // captured by the layout effect above, before any descendant effect
       // could move focus.
       const trigger = triggerElementRef.current;
-      if (trigger && trigger !== document.body) {
+      if (trigger && trigger !== trigger.ownerDocument.body) {
         const dir = getDialogDirection(trigger);
         dialog.style.setProperty('--dialog-dir-x', `${dir.x}px`);
         dialog.style.setProperty('--dialog-dir-y', `${dir.y}px`);
@@ -591,9 +618,15 @@ export function Dialog({
       if (dialog.open) {
         dialog.close();
       }
-      // Return focus to the element that opened the dialog
-      if (triggerElementRef.current) {
-        focusForLastInput(triggerElementRef.current);
+      // Return focus to the element that opened the dialog, with the ring
+      // the last input in that element's own document calls for.
+      const trigger = triggerElementRef.current;
+      if (trigger) {
+        focusForLastInput(
+          trigger,
+          undefined,
+          getInteractionModality(trigger.ownerDocument),
+        );
       }
       triggerElementRef.current = null;
     }