@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/dist/utils/presentation.js

@@ -0,0 +1,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file presentation.ts
+ * @input A component's `presentation` prop (a caller's value, or omitted),
+ *   what the component does when it is omitted, and the touch presentation
+ *   (utils/touchPresentation.ts)
+ * @output usePresentation and readPresentation (and the pure
+ *   resolvePresentation): the surface to render and whether the component's
+ *   touch input modes apply
+ * @position Internal resolver for stable components that, under a finger,
+ *   present a different surface or switch how an open surface follows input
+ *   (architecture:public-component-api INV16)
+ *
+ * A caller's explicit `presentation` always wins over the touch default:
+ *
+ * - `'popover'`: the fine-pointer surface AND input modes, on every device;
+ * - `'bottom-sheet'`: the sheet everywhere, with touch input modes under a
+ *   finger;
+ * - `'adaptive'`: the sheet on a compact touch screen and the popover
+ *   elsewhere, with touch input modes under a finger;
+ * - omitted: the component's default. `whenOmitted: 'popover'` answers as
+ *   `'popover'` (today's components). `whenOmitted: 'touch'` keeps the
+ *   popover surface and turns the component's touch input modes on under a
+ *   finger, as UIMenu tracks a finger in an anchored menu. Making `'touch'`
+ *   a released component's default is a functional default change
+ *   (`spec:AST-017` FR3) whose Changeset names `presentation="popover"`.
+ *
+ * One touch model on every touch device: the modes depend on the pointer,
+ * never on the platform. Touch styling (press paint, the text-size floor)
+ * and touch-only behavior that a component's own record defines (a row
+ * swipe, a slider's thumb) do not read this: they keep the touch
+ * presentation.
+ *
+ * CSS: a style that implements a touch surface or input mode is applied with
+ * `touchModes` (`stylex.props(touchModes && styles.touchMode)`), never as a
+ * bare media key on a base style, so a pinned `'popover'` keeps none of it.
+ * A rule inside it that needs the touch query uses the touch presentation's
+ * touch key; the iOS `@supports` gate is only for the one style iOS WebKit
+ * itself requires (the 16px text-size floor), never for a touch mode. On the
+ * server and while hydrating, `touchModes` is false and `'adaptive'` is the
+ * popover: a touch surface or mode opens only after hydration
+ * (`spec:AST-094` FR13), and no hint changes that. usePresentation listens
+ * only to the queries a request reads (`architecture:react-component-runtime`
+ * INV5): none for a pinned `'popover'`.
+ *
+ * SYNC: When modified, update presentation.test.ts.
+ */
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { readTouchPresentation, TOUCH_QUERY, useCompactDefinition } from "./touchPresentation.js";
+
+/** What a component does when the caller omits `presentation`. */
+
+/**
+ * usePresentation's options. There is no server hint: the server and
+ * hydrating render never present touch modes (`spec:AST-094` FR13).
+ */
+
+/** The decision, from a presentation request and a touch presentation. */
+export function resolvePresentation(presentation, touch, whenOmitted = 'popover') {
+  const request = presentation ?? whenOmitted;
+  const surface = request === 'bottom-sheet' || request === 'adaptive' && touch.isTouch && touch.isCompact ? 'bottom-sheet' : 'popover';
+  const touchModes = request !== 'popover' && touch.isTouch;
+  return {
+    surface,
+    touchModes
+  };
+}
+const noSubscription = () => () => {};
+/** The server and hydrating render match no query (`spec:AST-094` FR13). */
+const matchesNothing = () => false;
+
+/**
+ * A media query's match, subscribed only while `query` is given
+ * (`architecture:react-component-runtime` INV5); false on the server and
+ * while hydrating (`spec:AST-094` FR13).
+ */
+function useMatchWhileRead(query) {
+  const subscribe = useCallback(onStoreChange => {
+    if (query == null) {
+      return noSubscription();
+    }
+    const mql = window.matchMedia(query);
+    mql.addEventListener('change', onStoreChange);
+    return () => mql.removeEventListener('change', onStoreChange);
+  }, [query]);
+  const getSnapshot = useCallback(() => query != null && window.matchMedia(query).matches, [query]);
+  return useSyncExternalStore(subscribe, getSnapshot, matchesNothing);
+}
+
+/**
+ * The presentation now, following the pointer and the size as they change
+ * (a tablet docking a trackpad). SSR-safe: renders the server default (not
+ * touch, not compact) until hydrated (`spec:AST-094` FR13). It subscribes
+ * only to what the request reads: a pinned `'popover'` to neither query,
+ * `'bottom-sheet'` and the omitted `'touch'` default to the pointer, and
+ * `'adaptive'` to the pointer and the compact size.
+ */
+export function usePresentation(presentation, {
+  whenOmitted = 'popover'
+} = {}) {
+  const request = presentation ?? whenOmitted;
+  const compact = useCompactDefinition();
+  const isTouch = useMatchWhileRead(request === 'popover' ? null : TOUCH_QUERY);
+  const isCompact = useMatchWhileRead(request === 'adaptive' ? compact.query : null);
+  return useMemo(() => resolvePresentation(presentation, {
+    isTouch,
+    isCompact
+  }, whenOmitted), [presentation, isTouch, isCompact, whenOmitted]);
+}
+
+/**
+ * The presentation at this moment, for a decision taken once (a menu
+ * deciding how it follows the finger that opened it).
+ */
+export function readPresentation(presentation, {
+  whenOmitted = 'popover',
+  view,
+  compact
+}) {
+  const target = view === undefined ? typeof window === 'undefined' ? null : window : view;
+  return resolvePresentation(presentation, readTouchPresentation(target, compact), whenOmitted);
+}

package/dist/utils/pressDisabled.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file pressDisabled.ts
+ * @input An element
+ * @output `isDisabledControl`: whether an element is a disabled control, so a
+ *   press on it performs no action
+ * @position The one disabled-control check that press feedback
+ *   (../gestures/haptics) and the hover layers' touch trigger
+ *   (../Layer/useTouchTrigger) share, so the two never disagree about a
+ *   control. It lives outside the gesture code, which a public import that
+ *   uses no gesture never carries (architecture:react-component-runtime
+ *   INV13).
+ */
+/**
+ * Whether `element` is a disabled control: `aria-disabled="true"`, or a form
+ * control the browser counts as `:disabled` (a disabled fieldset's controls
+ * included). A disabled control performs no action, so it gives no press
+ * feedback (spec:AST-094 FR23), and a tap on it opens its reason instead
+ * (component:Tooltip FR5).
+ */
+export declare function isDisabledControl(element: Element): boolean;
+//# sourceMappingURL=pressDisabled.d.ts.map

package/dist/utils/pressDisabled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pressDisabled.d.ts","sourceRoot":"","sources":["../../src/utils/pressDisabled.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAS3D"}

package/dist/utils/pressDisabled.js

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file pressDisabled.ts
+ * @input An element
+ * @output `isDisabledControl`: whether an element is a disabled control, so a
+ *   press on it performs no action
+ * @position The one disabled-control check that press feedback
+ *   (../gestures/haptics) and the hover layers' touch trigger
+ *   (../Layer/useTouchTrigger) share, so the two never disagree about a
+ *   control. It lives outside the gesture code, which a public import that
+ *   uses no gesture never carries (architecture:react-component-runtime
+ *   INV13).
+ */
+
+/**
+ * Whether `element` is a disabled control: `aria-disabled="true"`, or a form
+ * control the browser counts as `:disabled` (a disabled fieldset's controls
+ * included). A disabled control performs no action, so it gives no press
+ * feedback (spec:AST-094 FR23), and a tap on it opens its reason instead
+ * (component:Tooltip FR5).
+ */
+export function isDisabledControl(element) {
+  if (element.getAttribute('aria-disabled') === 'true') {
+    return true;
+  }
+  try {
+    return element.matches(':disabled');
+  } catch {
+    return false;
+  }
+}

package/dist/utils/pressFeedback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pressFeedback.d.ts","sourceRoot":"","sources":["../../src/utils/pressFeedback.ts"],"names":[],"mappings":"AAyDA;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD,qDAAqD;AACrD,eAAO,MAAM,cAAc,EAAE;IAAC,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,EAAE,CAAA;CAE/D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AA6kB5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,IAAI,CA0BjD"}
+{"version":3,"file":"pressFeedback.d.ts","sourceRoot":"","sources":["../../src/utils/pressFeedback.ts"],"names":[],"mappings":"AA2DA;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD,qDAAqD;AACrD,eAAO,MAAM,cAAc,EAAE;IAAC,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,EAAE,CAAA;CAE/D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAomB5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,IAAI,CA0BjD"}

package/dist/utils/pressFeedback.js

@@ -2,8 +2,9 @@
 
 /**
  * @file pressFeedback.ts
- * @input The press state machine (pressGesture.ts) and the document's pointer,
- *   keyboard, scroll and visibility events
+ * @input The press state machine (pressGesture.ts), the menu-press marker
+ *   (hooks/menuPressMarker.ts) and the document's pointer, keyboard, scroll and
+ *   visibility events
  * @output Exports PRESSABLE_ATTRIBUTE, PRESSED_ATTRIBUTE, pressableProps and
  *   installPressFeedback
  * @position The DOM half of the touch press model: one delegated controller
@@ -44,6 +45,7 @@
  * pressFeedback.test.ts.
  */
 
+import { MENU_PRESS_MARKER } from "../hooks/menuPressMarker.js";
 import { idlePressGesture, PRESS_FADE_MS, PRESS_FLASH_MS, PRESS_ONSET_MS, PRESS_SCROLL_BRAKE_MS, pressGestureStep } from "./pressGesture.js";
 import { TOUCH_QUERY } from "./touchPresentation.js";
 
@@ -94,7 +96,7 @@ const SPACE_ACTIVATED_INPUT_TYPES = new Set(['button', 'image', 'reset', 'submit
  * FR6, DEC-6): a press held on one row while the highlight follows the
  * pointer to another would light two rows.
  */
-const MENU_PRESS_ROOT = '[data-astryx-menu-press]';
+const MENU_PRESS_ROOT = `[${MENU_PRESS_MARKER}]`;
 
 /**
  * One tracking slot. A finger's press runs the whole machine (the delay, the
@@ -131,6 +133,22 @@ const TIMER_MS = {
   flash: PRESS_FLASH_MS,
   onset: PRESS_ONSET_MS
 };
+
+/**
+ * The release fade's clock on `element`, read once, at the release, from the
+ * property its stylesheet reads: the theme's `--_astryx-motion-tempo`
+ * (`spec:AST-108` FR4, `component:Button` FR15). Under Reduce Motion a tempo
+ * may shorten the fade, never lengthen it past 200 ms.
+ */
+function fadeMs(element) {
+  const style = getComputedStyle(element);
+  const value = style.getPropertyValue('--_astryx-motion-tempo').trim();
+  const read = value === '' ? Number.NaN : Number(value);
+  const tempo = Number.isFinite(read) && read > 0 ? read : 1;
+  const scaled = PRESS_FADE_MS * tempo;
+  const reduced = typeof window.matchMedia === 'function' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  return reduced ? Math.min(scaled, PRESS_FADE_MS) : scaled;
+}
 const TIMER_EVENT = {
   fade: 'fadeEnd',
   flash: 'flashEnd',
@@ -197,7 +215,10 @@ function apply(slot, step) {
       apply(slot, pressGestureStep(slot.live?.gesture ?? idlePressGesture(), {
         kind: TIMER_EVENT[kind]
       }));
-    }, TIMER_MS[kind]);
+    },
+    // The release fade follows the theme's tempo (`spec:AST-108` FR4,
+    // `component:Button` FR15); the onset delay and the tap flash do not.
+    kind === 'fade' ? fadeMs(live.element) : TIMER_MS[kind]);
   }
 }
 

package/dist/utils/primaryClick.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether a button press is a primary click: the main button, and not a
+ * ctrl-click on macOS or iPadOS, which is that platform's context click
+ * (`spec:AST-094` FR43). A right click, a pen's barrel button and a macOS
+ * ctrl-click start no press.
+ */
+export declare function isPrimaryClick(event: {
+    readonly button: number;
+    readonly ctrlKey: boolean;
+}): boolean;
+//# sourceMappingURL=primaryClick.d.ts.map

package/dist/utils/primaryClick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primaryClick.d.ts","sourceRoot":"","sources":["../../src/utils/primaryClick.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAEV"}

package/dist/utils/primaryClick.js

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file primaryClick.ts
+ * @input A mouse or pen button press: its `button` and `ctrlKey`
+ * @output Exports isPrimaryClick
+ * @position Internal util, the one primary-click rule: the gesture host
+ *   starts a press only for one, and the press controller paints only one;
+ *   platform detection is utils/isApplePlatform.ts
+ *
+ * Deliberately absent from utils/index.ts: packages/core/src/index.ts does
+ * `export * from './utils'`, so naming it there would publish it as API.
+ */
+
+import { isApplePlatform } from "./isApplePlatform.js";
+
+/**
+ * Whether a button press is a primary click: the main button, and not a
+ * ctrl-click on macOS or iPadOS, which is that platform's context click
+ * (`spec:AST-094` FR43). A right click, a pen's barrel button and a macOS
+ * ctrl-click start no press.
+ */
+export function isPrimaryClick(event) {
+  return event.button === 0 && !(event.ctrlKey && isApplePlatform());
+}

package/dist/utils/sharedMutationObserver.d.ts

@@ -1,21 +1,29 @@
 /**
  * @file sharedMutationObserver.ts
  * @input MutationObserver API
- * @output Exports observeContent for shared content-change observation
- * @position Internal utility; consumed by useTruncation. The content-change
- *   counterpart of sharedResizeObserver: one observer for every element, so a
- *   repeated cell or row path does not create one observer per instance.
+ * @output Exports observeMutations (one shared observer per set of options)
+ *   and observeContent, its text-and-children form
+ * @position Internal utility; consumed by useTruncation, hitArea and AppShell's
+ *   main-overflow observer. The mutation counterpart of sharedResizeObserver:
+ *   one observer for every element observed with the same options, so a
+ *   repeated cell, row or region does not create one observer per instance.
  */
-type ContentCallback = () => void;
+type MutationCallback = () => void;
 /**
- * Call `callback` when the element's text or children change (including
- * descendants). Returns an unsubscribe that removes only this registration.
+ * Call `callback` for mutations of `element` matching `options`, through the
+ * one observer shared by every registration with the same options. Returns an
+ * unsubscribe that removes only this registration.
  *
  * MutationObserver has no per-target unobserve, so a released element stays
- * registered with the shared observer until no element remains; its records
- * match no callback and are ignored. The observer disconnects and is released
- * when the last registration goes.
+ * registered with its shared observer until no element remains; its records
+ * match no callback and are ignored. An observer disconnects and is released
+ * when its last registration goes.
+ */
+export declare function observeMutations(element: Node, options: MutationObserverInit, callback: MutationCallback): () => void;
+/**
+ * Call `callback` when the element's text or children change (including
+ * descendants). Returns an unsubscribe that removes only this registration.
  */
-export declare function observeContent(element: Element, callback: ContentCallback): () => void;
+export declare function observeContent(element: Element, callback: MutationCallback): () => void;
 export {};
 //# sourceMappingURL=sharedMutationObserver.d.ts.map

package/dist/utils/sharedMutationObserver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sharedMutationObserver.d.ts","sourceRoot":"","sources":["../../src/utils/sharedMutationObserver.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,KAAK,eAAe,GAAG,MAAM,IAAI,CAAC;AAuBlC;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,eAAe,GACxB,MAAM,IAAI,CA6BZ"}
+{"version":3,"file":"sharedMutationObserver.d.ts","sourceRoot":"","sources":["../../src/utils/sharedMutationObserver.ts"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,KAAK,gBAAgB,GAAG,MAAM,IAAI,CAAC;AA4DnC;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,IAAI,EACb,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,gBAAgB,GACzB,MAAM,IAAI,CAmCZ;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,gBAAgB,GACzB,MAAM,IAAI,CAEZ"}

package/dist/utils/sharedMutationObserver.js

@@ -5,50 +5,82 @@
 /**
  * @file sharedMutationObserver.ts
  * @input MutationObserver API
- * @output Exports observeContent for shared content-change observation
- * @position Internal utility; consumed by useTruncation. The content-change
- *   counterpart of sharedResizeObserver: one observer for every element, so a
- *   repeated cell or row path does not create one observer per instance.
+ * @output Exports observeMutations (one shared observer per set of options)
+ *   and observeContent, its text-and-children form
+ * @position Internal utility; consumed by useTruncation, hitArea and AppShell's
+ *   main-overflow observer. The mutation counterpart of sharedResizeObserver:
+ *   one observer for every element observed with the same options, so a
+ *   repeated cell, row or region does not create one observer per instance.
  */
-const OPTIONS = {
+const CONTENT_OPTIONS = {
   characterData: true,
   childList: true,
   subtree: true
 };
-let observer = null;
-const callbacks = new Map();
-function dispatch(records) {
-  // One call per callback per batch, however many records it received. A
-  // record's target can be any descendant, so walk up to the observed roots.
-  const pending = new Set();
-  for (const record of records) {
-    for (let node = record.target; node; node = node.parentNode) {
-      callbacks.get(node)?.forEach(callback => pending.add(callback));
+/**
+ * One observer per distinct set of options: an observer holds one set of
+ * options per node, so registrations that need different options cannot
+ * share one.
+ */
+const observers = new Map();
+function optionsKey(options) {
+  return JSON.stringify([options.attributes === true, options.attributeFilter == null ? null : [...options.attributeFilter].sort(), options.characterData === true, options.childList === true, options.subtree === true]);
+}
+function createSharedObserver(options) {
+  const callbacks = new Map();
+  const isSubtree = options.subtree === true;
+  const observer = new MutationObserver(records => {
+    // One call per callback per batch, however many records it received.
+    // With `subtree`, a record's target can be any descendant, so walk up to
+    // the observed roots; without it, the target is the observed node.
+    const pending = new Set();
+    for (const record of records) {
+      if (!isSubtree) {
+        callbacks.get(record.target)?.forEach(callback => pending.add(callback));
+        continue;
+      }
+      for (let node = record.target; node; node = node.parentNode) {
+        callbacks.get(node)?.forEach(callback => pending.add(callback));
+      }
     }
-  }
-  pending.forEach(callback => callback());
+    pending.forEach(callback => callback());
+  });
+  return {
+    observer,
+    callbacks
+  };
 }
 
 /**
- * Call `callback` when the element's text or children change (including
- * descendants). Returns an unsubscribe that removes only this registration.
+ * Call `callback` for mutations of `element` matching `options`, through the
+ * one observer shared by every registration with the same options. Returns an
+ * unsubscribe that removes only this registration.
  *
  * MutationObserver has no per-target unobserve, so a released element stays
- * registered with the shared observer until no element remains; its records
- * match no callback and are ignored. The observer disconnects and is released
- * when the last registration goes.
+ * registered with its shared observer until no element remains; its records
+ * match no callback and are ignored. An observer disconnects and is released
+ * when its last registration goes.
  */
-export function observeContent(element, callback) {
+export function observeMutations(element, options, callback) {
   if (typeof MutationObserver === 'undefined') {
     return () => {};
   }
-  observer ??= new MutationObserver(dispatch);
+  const key = optionsKey(options);
+  let shared = observers.get(key);
+  if (shared == null) {
+    shared = createSharedObserver(options);
+    observers.set(key, shared);
+  }
+  const {
+    observer,
+    callbacks
+  } = shared;
   const existing = callbacks.get(element);
   if (existing) {
     existing.add(callback);
   } else {
     callbacks.set(element, new Set([callback]));
-    observer.observe(element, OPTIONS);
+    observer.observe(element, options);
   }
   let isSubscribed = true;
   return () => {
@@ -61,9 +93,17 @@ export function observeContent(element, callback) {
     if (targetCallbacks?.size === 0) {
       callbacks.delete(element);
     }
-    if (callbacks.size === 0 && observer) {
+    if (callbacks.size === 0 && observers.get(key)?.observer === observer) {
       observer.disconnect();
-      observer = null;
+      observers.delete(key);
     }
   };
+}
+
+/**
+ * Call `callback` when the element's text or children change (including
+ * descendants). Returns an unsubscribe that removes only this registration.
+ */
+export function observeContent(element, callback) {
+  return observeMutations(element, CONTENT_OPTIONS, callback);
 }

package/dist/utils/timeFormat.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file timeFormat.ts
+ * @input An ISO time or typed text, plus the provider's BCP 47 locale
+ * @output Exports resolveHourFormat, formatLocaleTime, and parseLocaleTime
+ * @position Internal shared helper for TimeInput and DateTimeInput; not part
+ *   of the public surface
+ *
+ * Time of day as the locale writes it. The hour cycle, digits, separator, and
+ * day-period words all come from Intl rather than a table, so a field reads
+ * the same way `Timestamp` does beside it.
+ *
+ * The hour cycle is the locale's own: `en-US` and `ko-KR` read twelve-hour,
+ * `en-GB`, `de-DE`, and `vi-VN` read twenty-four-hour. A `-u-hc-` extension
+ * on the provider locale (`en-US-u-hc-h23`) carries an app's per-user
+ * preference through the same path, so every Astryx time honors it.
+ *
+ * The parser reads back what the formatter writes: the locale's digits, its
+ * hour-minute separator, and its day-period words, on either side of the time.
+ * Whatever is left goes through the shared English-tolerant parser, so "2:30
+ * PM" and "14:30" keep working in every locale.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/utils/timeFormat.test.ts
+ * - /packages/core/src/TimeInput/TimeInput.tsx
+ * - /packages/core/src/DateTimeInput/DateTimeInput.tsx
+ */
+import type { Locale } from '../i18n/types.js';
+import { type ISOTimeString } from './timeParser.js';
+export type HourFormat = '12h' | '24h';
+/**
+ * The hour format a field shows: the caller's explicit choice, else the
+ * locale's hour cycle (including a `-u-hc-` extension on the tag).
+ */
+export declare function resolveHourFormat(locale: Locale, hourFormat?: HourFormat): HourFormat;
+/**
+ * Formats an ISO time as the locale writes it, in the given hour format.
+ * en-US: "14:30" → "2:30 PM"; de-DE 24h: "14:30"; ko-KR 12h: "오후 2:30".
+ * Returns '' for an empty or malformed time.
+ */
+export declare function formatLocaleTime(time: ISOTimeString | undefined, locale: Locale, hourFormat: HourFormat, includeSeconds?: boolean): string;
+/**
+ * Parses typed text into an ISO time, accepting the locale's digits,
+ * separator, and day-period words as well as everything `parseTimeInput`
+ * accepts. Returns null when no reading fits.
+ */
+export declare function parseLocaleTime(input: string, locale: Locale, includeSeconds?: boolean): ISOTimeString | null;
+//# sourceMappingURL=timeFormat.d.ts.map

package/dist/utils/timeFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeFormat.d.ts","sourceRoot":"","sources":["../../src/utils/timeFormat.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,eAAe,CAAC;AAC1C,OAAO,EAA+B,KAAK,aAAa,EAAC,MAAM,cAAc,CAAC;AAG9E,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,KAAK,CAAC;AAsLvC;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,UAAU,GACtB,UAAU,CAEZ;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,cAAc,GAAE,OAAe,GAC9B,MAAM,CAeR;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,cAAc,GAAE,OAAe,GAC9B,aAAa,GAAG,IAAI,CAmDtB"}