@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/utils/touchPresentation.stylex.ts

@@ -6,30 +6,24 @@
  * @output Exports touchKeys: the touch presentation resolver's queries as
  *   StyleX at-rule keys
  * @position The reference spellings of the touch, compact and iOS-gate
- *   conditions. Core styles write these as literal keys wherever they need
- *   them (`spec:AST-094` FR13, `spec:AST-012` FR9), and a test pins each
- *   literal to these values; utils/touchPresentation.ts holds the same
- *   queries for script (matchMedia)
- *
- * These are the spellings to match. A style that changes with these
- * conditions writes the same literal key (`'@media (pointer: coarse)'`, the
- * iOS gate as that media key outside `'@supports (-webkit-touch-callout:
- * none)'`), and a test pins every literal in core to these values. Do not use
- * an imported key as a computed StyleX key: it compiles to a different
- * priority than the literal (6000 against 3200) and reorders the cascade.
- * The iOS supports gate is only for a style iOS WebKit itself requires (the
- * 16px input floor), never a behaviour.
+ *   conditions. utils/touchPresentation.ts holds the same queries for script.
  *
  * SYNC: When modified, update touchPresentation.ts and
  * touchPresentation.test.ts.
  */
 
+// Core styles write these as literal keys (AST-012), and a test pins each
+// literal to these values. Do not use an imported key as a computed StyleX key:
+// it gets a different priority than the literal (6000 against 3200) and
+// reorders the cascade. The iOS supports gate is only for a style that iOS
+// WebKit requires (the 16px input floor), never for a behavior (AST-094).
+
 import * as stylex from '@stylexjs/stylex';
 
 export const touchKeys = stylex.defineConsts({
   /** The primary pointer is coarse (TOUCH_QUERY). */
   touch: '@media (pointer: coarse)',
-  /** The viewport is compact (COMPACT_QUERY, `spec:AST-012` FR9). */
+  /** The viewport is compact (COMPACT_QUERY). */
   compact: '@media (width < 768px), (height < 500px)',
   /** Both: a presentation such as a sheet in place of a popover. */
   compactTouch:

package/src/utils/touchPresentation.ts

@@ -4,62 +4,40 @@
 
 /**
  * @file touchPresentation.ts
- * @input Uses the SSR-safe useMediaQuery hook, window.matchMedia, and
- *   TOUCH_QUERY from touchQueries.ts (which loads without React or the theme)
- * @output The one definition of when a component presents itself the touch
- *   way: TOUCH_QUERY, COMPACT_QUERY, COMPACT_TOUCH_QUERY, the iOS style gate
- *   (IOS_SUPPORTS_QUERY and its StyleX keys); the hook useTouchPresentation;
- *   readTouchPresentation for a decision taken at one moment
- * @position Internal shared resolver beside interactionModality.ts
- *
- * Two questions, answered once:
- *
- * - TOUCH behaviours (the press model, gesture recognizers, UIKit springs and
- *   timings) key on the PRIMARY pointer being coarse: a finger. A touchscreen
- *   laptop reports its trackpad (fine) and keeps pointer behaviours; a tablet
- *   reports coarse and gets touch ones at any width. Not `hover: none` (some
- *   touch browsers report hover) and not `any-pointer` (a laptop's touch
- *   screen is not how it is driven).
- * - LAYOUT behaviours key on the available size, whatever the pointer:
- *   the theme's one compact definition (`spec:AST-012` FR9), width below the
- *   `md` point or height below 500, the same numbers on every platform. A
- *   phone in landscape is compact by its height; no platform size class is
- *   consulted.
- * - A presentation that needs both (a bottom sheet in place of a popover, a
- *   drilled-in sub-menu in place of a flyout) asks for both.
- *
- * Touch behaviour is one model on every touch device, iOS and Android alike;
- * nothing here chooses a platform. Touch motion plays the measured table,
- * through the internal motion roles where a value is one.
- *
- * CSS first: a style that changes with these conditions writes the same
- * query as a StyleX media key, spelled exactly as here (`@media` followed by
- * the constant's text), so the right rule paints before hydration. The iOS
- * gate is two nested keys, the media query outside and the supports query
- * inside (IOS_TOUCH_STYLE_KEYS):
- *
- *   '@media (pointer: coarse)': {
- *     '@supports (-webkit-touch-callout: none)': value,
- *   },
- *
- * One `@supports (-webkit-touch-callout: none) and (pointer: coarse)` never
- * matches anywhere (`pointer` is not a property), so it is not written. A
- * test keeps core's compact-touch keys identical to COMPACT_TOUCH_QUERY and
- * every touch-callout key spelled and nested as above. The iOS style gate
- * is only for a style iOS WebKit itself requires (core's 16px input floor);
- * it never selects a behaviour. Core spells the keys literally: an imported
- * `defineConsts` key compiles to a different StyleX priority than the same
- * literal, which would reorder the cascade. `touchKeys`
- * (touchPresentation.stylex.ts, internal to core) holds the same keys, and a
- * test keeps every literal equal to them. The hook is for behaviour. It answers the server default
- * (not touch, not compact) until hydrated unless the caller passes a server
- * hint, and follows the pointer and size when they change (a tablet docking
- * a mouse).
+ * @input useMediaQuery, window.matchMedia, and TOUCH_QUERY from touchQueries.ts
+ * @output TOUCH_QUERY, COMPACT_QUERY, COMPACT_TOUCH_QUERY, the iOS style gate
+ *   (IOS_SUPPORTS_QUERY and its StyleX keys), useTouchPresentation, and
+ *   readTouchPresentation
+ * @position Internal shared resolver beside interactionModality.ts; the one
+ *   definition of when a component presents itself the touch way
  *
  * SYNC: When modified, update touchPresentation.test.ts and every StyleX
  * media key that spells these queries.
  */
 
+// - Touch behaviors key on a coarse primary pointer: a finger. A touchscreen
+//   laptop reports its trackpad and keeps pointer behaviors. Not
+//   `hover: none` (some touch browsers report hover), and not `any-pointer`.
+// - Layout behaviors key on the available size: the theme's compact
+//   definition (AST-012, and its AST-012 FR9). A phone in landscape is
+//   compact by its height.
+// - A presentation that needs both asks for both. No platform is chosen.
+//
+// A style that changes with these conditions uses the same query as a StyleX
+// media key, so the right rule paints before hydration. The iOS gate is two
+// nested keys, the media query outside and the supports query inside:
+//
+//   '@media (pointer: coarse)': {
+//     '@supports (-webkit-touch-callout: none)': value,
+//   },
+//
+// One combined `@supports` never matches, because `pointer` is not a
+// property. The iOS gate is only for a style that iOS WebKit requires (the
+// 16px input floor). Core spells the keys literally, because an imported
+// `defineConsts` key gets a different StyleX priority. Tests keep the
+// literals equal to these queries and to `touchKeys`. The hook answers the
+// server default until hydrated, unless the caller passes a hint.
+
 import {useMemo} from 'react';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 import {
@@ -68,15 +46,15 @@ import {
   type CompactDefinition,
 } from '../theme/themeAdaptations';
 import {useThemeDefinition} from '../theme/useTheme';
-import {TOUCH_QUERY} from './touchQueries';
+import {IOS_SUPPORTS_QUERY, TOUCH_QUERY} from './touchQueries';
 
 // The primary pointer is coarse: touch behaviours. Defined in touchQueries.ts,
 // which loads without React or the theme.
 export {TOUCH_QUERY};
 
 /**
- * The viewport is compact at the default width points: layout behaviours
- * (`spec:AST-012` FR9). A StyleX media key, which cannot read the theme,
+ * The viewport is compact at the default width points: layout behaviours.
+ * A StyleX media key, which cannot read the theme,
  * spells this; behaviour reads the active theme's definition
  * (useCompactDefinition), so a theme that moves `md` moves compact with it.
  */
@@ -86,12 +64,9 @@ export const COMPACT_QUERY = DEFAULT_COMPACT_DEFINITION.query;
 export const COMPACT_TOUCH_QUERY =
   DEFAULT_COMPACT_DEFINITION.coarsePointerQuery;
 
-/**
- * The engine is WebKit on iOS or iPadOS: the only one that implements
- * `-webkit-touch-callout`. For a style iOS WebKit requires, never a
- * behaviour.
- */
-export const IOS_SUPPORTS_QUERY = '(-webkit-touch-callout: none)';
+// The engine is WebKit on iOS or iPadOS, for a style iOS WebKit requires.
+// Defined in touchQueries.ts, which loads without React or the theme.
+export {IOS_SUPPORTS_QUERY};
 
 /**
  * The iOS gate as StyleX keys, nested in this order: the media query
@@ -110,7 +85,7 @@ export interface TouchPresentation {
 }
 
 /**
- * The active theme's compact definition (`spec:AST-012` FR9): width below the
+ * The active theme's compact definition: width below the
  * theme's effective `md` point, or height below 500.
  */
 export function useCompactDefinition(): CompactDefinition {
@@ -142,7 +117,7 @@ export function useTouchPresentation(
  * The touch presentation at this moment, for a decision taken once (a menu
  * deciding how it presents as it opens). `compact` is the active theme's
  * definition (`useCompactDefinition()`, read while rendering), required so a
- * theme that moves `md` is never ignored (spec:AST-012 FR9). Not touch and
+ * theme that moves `md` is never ignored. Not touch and
  * not compact where there is no window.
  */
 export function readTouchPresentation(

package/src/utils/touchQueries.ts

@@ -3,7 +3,8 @@
 /**
  * @file touchQueries.ts
  * @input Nothing: plain strings
- * @output TOUCH_QUERY, the media query for a coarse primary pointer
+ * @output TOUCH_QUERY, the media query for a coarse primary pointer; and
+ *   IOS_SUPPORTS_QUERY with isIosWebKit, the iOS WebKit engine check
  * @position The dependency-free half of touchPresentation.ts, for code that
  *   must load without React or the theme: the motion foundation, which
  *   Node-side specs and browser proofs load without a StyleX compile.
@@ -13,3 +14,25 @@
 
 /** The primary pointer is coarse: touch behaviours. */
 export const TOUCH_QUERY = '(pointer: coarse)';
+
+/**
+ * The engine is WebKit on iOS or iPadOS: the only one that implements
+ * `-webkit-touch-callout`. For a style iOS WebKit requires, never a
+ * behaviour; isIosWebKit reads it for an engine workaround a record names.
+ */
+export const IOS_SUPPORTS_QUERY = '(-webkit-touch-callout: none)';
+
+/**
+ * Whether `view`'s engine is iOS WebKit, by IOS_SUPPORTS_QUERY. Only for an
+ * engine workaround a record names (`spec:AST-013` FR6): the selection
+ * lock's inline style, and the gesture host's presented hit testing. False
+ * where `CSS.supports` is missing (jsdom has `CSS.escape` only).
+ */
+export function isIosWebKit(
+  view:
+    | {CSS?: Partial<Pick<typeof CSS, 'supports'>>}
+    | null
+    | undefined = globalThis,
+): boolean {
+  return view?.CSS?.supports?.(IOS_SUPPORTS_QUERY) === true;
+}

package/src/utils/typeaheadMatch.ts

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file typeaheadMatch.ts
+ * @input Plain strings (an item label and the letters a person typed)
+ * @output foldForTypeahead, nextTypeaheadBuffer, typeaheadPrefixMatch,
+ *   findTypeaheadMatch
+ * @position Shared type-to-select matching for useTypeahead, useTreeFocus and
+ *   MultiSelector
+ *
+ * Type-to-select is navigation, not sorting, so it folds the same way in every
+ * locale: case, the combining marks canonical decomposition leaves
+ * (U+0300–U+036F), six Latin letters with a stroke or bar, and Turkish ı and
+ * İ. Typed letters that carry one of those marks prefer an exact match, with
+ * case paired the Turkish way (ı with I, İ with i).
+ */
+
+const COMBINING_MARKS = /[\u0300-\u036f]/g;
+
+// The six stroked or barred Latin letters that the fold removes, in both cases.
+// Turkish dotless ı joins them; dotted İ decomposes to I + U+0307 and needs no
+// entry.
+const STROKED: Readonly<Record<string, string>> = {
+  đ: 'd',
+  Đ: 'd',
+  ł: 'l',
+  Ł: 'l',
+  ø: 'o',
+  Ø: 'o',
+  ħ: 'h',
+  Ħ: 'h',
+  ŧ: 't',
+  Ŧ: 't',
+  ƀ: 'b',
+  Ƀ: 'b',
+  ı: 'i',
+};
+const STROKED_CHARS = /[đĐłŁøØħĦŧŦƀɃı]/g;
+const MARKED_CHARS = /[đĐłŁøØħĦŧŦƀɃıİ]/;
+
+/**
+ * Fold text for type-to-select: no case, no combining marks, the six stroked
+ * letters and ı as their base letter. Locale-independent by design.
+ */
+export function foldForTypeahead(text: string): string {
+  return (
+    text
+      .normalize('NFD')
+      .replace(COMBINING_MARKS, '')
+      .replace(STROKED_CHARS, c => STROKED[c] ?? c)
+      // Recompose what the fold keeps (a Japanese voiced mark, an Arabic hamza,
+      // a Hangul final consonant), so a one-letter prefix does not skip it.
+      .normalize('NFC')
+      .toLowerCase()
+  );
+}
+
+/**
+ * The type-to-select buffer after one more key, shared by every path so they
+ * buffer the same way. Returns null when the key is not a letter to jump to: a
+ * lone combining mark typed first. Pressing the same letter again (as folded)
+ * cycles, so the buffer stays that one letter instead of growing.
+ */
+export function nextTypeaheadBuffer(
+  buffer: string,
+  key: string,
+): string | null {
+  if (
+    buffer.length === 0 &&
+    key !== ' ' &&
+    foldForTypeahead(key).length === 0
+  ) {
+    return null;
+  }
+  const isRepeatSameChar =
+    buffer.length > 0 &&
+    buffer.split('').every(c => foldForTypeahead(c) === foldForTypeahead(key));
+  return isRepeatSameChar ? key : buffer + key;
+}
+
+/**
+ * Case-fold for the exact-match preference, pairing the Turkish way: I with ı
+ * and İ with i. Composed, so an accent typed as its own key counts as one
+ * letter, as it does in a composed label.
+ */
+function exactFold(text: string): string {
+  return text
+    .normalize('NFC')
+    .replace(/I/g, 'ı')
+    .replace(/İ/g, 'i')
+    .toLowerCase();
+}
+
+/** Whether typed letters carry a mark that makes an exact match preferable. */
+function hasMark(typed: string): boolean {
+  return (
+    MARKED_CHARS.test(typed) || /[\u0300-\u036f]/.test(typed.normalize('NFD'))
+  );
+}
+
+/**
+ * Whether `label` starts with `typed` under the fold. `exact` additionally
+ * requires the unfolded letters to match (Turkish case pairing).
+ */
+export function typeaheadPrefixMatch(
+  label: string,
+  typed: string,
+  exact = false,
+): boolean {
+  const trimmed = label.trim();
+  if (exact) {
+    return exactFold(trimmed).startsWith(exactFold(typed));
+  }
+  const foldedTyped = foldForTypeahead(typed);
+  // A lone combining mark folds to nothing; it is not a letter to jump to.
+  if (foldedTyped.length === 0) {
+    return false;
+  }
+  return foldForTypeahead(trimmed).startsWith(foldedTyped);
+}
+
+/**
+ * Find the next item whose label matches the typed letters, visiting indexes
+ * in `order`. When the typed letters carry a diacritic, a stroked letter, ı or
+ * İ, an exact match anywhere in the order wins over a folded one.
+ */
+export function findTypeaheadMatch(
+  order: ReadonlyArray<number>,
+  getLabel: (index: number) => string | null | undefined,
+  typed: string,
+): number {
+  const passes = hasMark(typed) ? [true, false] : [false];
+  for (const exact of passes) {
+    for (const index of order) {
+      const label = getLabel(index);
+      if (label != null && typeaheadPrefixMatch(label, typed, exact)) {
+        return index;
+      }
+    }
+  }
+  return -1;
+}

package/src/utils/useFocusLeavingChange.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useFocusLeavingChange.ts
+ * @input A state whose change can remove or hide focused content, how to note
+ *   the focus before the change, and how to move it after
+ * @output A before-change callback for `LayoutChangeSnapshot`, and the move,
+ *   run from a layout effect of the same commit
+ * @position Internal hook, not exported from the package: the one sequence a
+ *   disclosure runs so focus leaves content its change takes away
+ *   (`component:SideNav` AR3, `component:Collapsible` AR4). It pairs with
+ *   `noteFocusWithin` and `moveFocusLeftBehind` in `focusReturn.ts`, which
+ *   stays free of React so `isFocusDetached` remains server-safe.
+ */
+
+import {useCallback, useLayoutEffect, useRef} from 'react';
+
+/**
+ * Notes focus in the commit before `value`'s change touches the DOM, and
+ * moves it from a layout effect of the same commit.
+ *
+ * Pass the returned callback as `LayoutChangeSnapshot`'s `onBeforeChange`
+ * (with `value` as its `value`). `note` receives the value being left and
+ * returns what `move` needs, or `null` when there is nothing to move; `move`
+ * receives that and the new value once the change has committed. `move` is
+ * the latest render's. `note` runs before this commit's effects, so it is the
+ * previous committed render's: read refs or the DOM in it, not props.
+ */
+export function useFocusLeavingChange<V, N>(
+  value: V,
+  note: (previous: V) => N | null,
+  move: (noted: N, value: V) => void,
+): (previous: V) => void {
+  const noteRef = useRef(note);
+  const moveRef = useRef(move);
+  const pendingRef = useRef<N | null>(null);
+  useLayoutEffect(() => {
+    noteRef.current = note;
+    moveRef.current = move;
+  });
+  useLayoutEffect(() => {
+    const noted = pendingRef.current;
+    pendingRef.current = null;
+    if (noted != null) {
+      moveRef.current(noted, value);
+    }
+  }, [value]);
+  return useCallback((previous: V) => {
+    pendingRef.current = noteRef.current(previous);
+  }, []);
+}