@astryxdesign/core 0.3.0 → 0.4.0

package/dist/hooks/useIndicatorFocusRing.js

@@ -0,0 +1,96 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIndicatorFocusRing.tsx
+ * @input A ref to the element wrapping only the indicator
+ * @output Focus handlers that draw the standard ring on the indicator itself
+ * @position Used by controls whose focusable input is visually hidden
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (exports)
+ *
+ * A checkbox or radio focuses a native `<input>` that is `opacity: 0`, so the
+ * visible focus indicator has to appear on the picture beside it — and that
+ * picture is a themeable indicator, which is what makes "who draws the ring"
+ * awkward:
+ *
+ * - Only the indicator's own element can shape the ring: `outline` follows
+ *   that element's `border-radius`. Draw it on a wrapper and the owner has to
+ *   hardcode a guess about whatever indicator it hosts (RadioListItem used to
+ *   carry `border-radius: 50%` for a circle it did not own).
+ * - But an indicator supplied by a theme is third-party code. If drawing the
+ *   ring is its job, a replacement that simply doesn't ships a control with no
+ *   visible focus (WCAG 2.4.7) — and that is the DEFAULT outcome: the sample
+ *   replacement in our own Storybook destructures `{state, size, isDisabled}`
+ *   and drops the rest, which is what a theme author plausibly writes. Nothing
+ *   can enforce otherwise; a component ignoring every prop is still assignable
+ *   to `IndicatorComponent`, and branding the return type does not work either
+ *   (JSX types every expression as `JSX.Element`).
+ *
+ * So the owner draws it, on the indicator's own element, imperatively at focus
+ * time. No cooperation is required and none can be forgotten.
+ *
+ * Two details that are load-bearing, both measured rather than assumed:
+ *
+ * 1. **Inline style, not a class.** React replaces `className` wholesale on
+ *    re-render, so an injected class disappears the moment the control changes
+ *    state — pressing Space on a focused checkbox lost the ring. React
+ *    reconciles `style` per property, so an `outline` set here survives.
+ * 2. **`:focus-visible`, not `:focus`.** The CSS this replaces got
+ *    keyboard-vs-pointer for free; an event handler has to ask. Checking the
+ *    element keeps the browser's heuristic, including `focus({focusVisible:
+ *    true})`, which a hand-rolled modality guess would miss.
+ *
+ * Imperative styling on an interaction event follows `useTableSelection`,
+ * which sets row-selection styles the same way.
+ */
+import { useCallback, useMemo } from 'react';
+import { FOCUS_OUTLINE_PARTS, FOCUS_OUTLINE_PARTS_NONE } from "../utils/focusOutline.stylex.js";
+/**
+ * Draw the standard focus ring on the indicator inside `containerRef`, shaped
+ * by whatever that indicator actually is.
+ *
+ * @param containerRef - Wraps ONLY the indicator, so its single element child
+ *   is unambiguously the thing to ring, whatever a theme renders there.
+ * @param isDisabled - Skip the ring; a disabled control is not focusable.
+ *
+ * @example
+ * ```
+ * const indicatorRef = useRef<HTMLSpanElement>(null);
+ * const {focusProps} = useIndicatorFocusRing(indicatorRef, isDisabled);
+ * <div {...focusProps}>
+ *   <input type="checkbox" />
+ *   <span ref={indicatorRef}><Indicator state="checked" /></span>
+ * </div>
+ * ```
+ */
+export function useIndicatorFocusRing(containerRef, isDisabled = false) {
+  const paint = useCallback(on => {
+    // `firstElementChild`, not a search: the container holds the indicator
+    // and nothing else, so there is no ambiguity — and no way for a later
+    // sibling to quietly become the target.
+    const indicator = containerRef.current?.firstElementChild;
+    if (indicator instanceof HTMLElement) {
+      Object.assign(indicator.style, on ? FOCUS_OUTLINE_PARTS : FOCUS_OUTLINE_PARTS_NONE);
+    }
+  }, [containerRef]);
+  const onFocus = useCallback(event => {
+    if (isDisabled) {
+      return;
+    }
+    const target = event.target;
+    if (target instanceof HTMLElement && !target.matches(':focus-visible')) {
+      return;
+    }
+    paint(true);
+  }, [isDisabled, paint]);
+  const onBlur = useCallback(() => paint(false), [paint]);
+  return useMemo(() => ({
+    focusProps: {
+      onFocus,
+      onBlur
+    }
+  }), [onFocus, onBlur]);
+}

package/dist/hooks/useLongPress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLongPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useLongPress.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,WAAW,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,IAAI,CAAC;IACrD,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5C,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC3C,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,mBAAmB,GAC3B,oBAAoB,CAsEtB"}
+{"version":3,"file":"useLongPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useLongPress.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,WAAW,EAAE,CAAC,KAAK,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,KAAK,IAAI,CAAC;IACrD,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC5C,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAC3C,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,mBAAmB,GAC3B,oBAAoB,CAgFtB"}

package/dist/hooks/useLongPress.js

@@ -44,7 +44,12 @@ export function useLongPress(options) {
     startRef.current = null;
   }, []);
   const onTouchStart = useCallback(e => {
-    if (disabled || e.touches.length !== 1) {
+    if (disabled) {
+      return;
+    }
+    if (e.touches.length !== 1) {
+      // Multi-touch cancels any pending long-press.
+      clear();
       return;
     }
     const touch = e.touches[0];
@@ -68,7 +73,12 @@ export function useLongPress(options) {
   }, [disabled, delayMs, clear]);
   const onTouchMove = useCallback(e => {
     const start = startRef.current;
-    if (start == null || e.touches.length !== 1) {
+    if (start == null) {
+      return;
+    }
+    if (e.touches.length !== 1) {
+      // Multi-touch cancels the pending long-press.
+      clear();
       return;
     }
     const touch = e.touches[0];

package/dist/hooks/useScrollLock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useScrollLock.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollLock.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CA8BrD"}
+{"version":3,"file":"useScrollLock.d.ts","sourceRoot":"","sources":["../../src/hooks/useScrollLock.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAiDrD"}

package/dist/hooks/useScrollLock.js

@@ -15,6 +15,8 @@
  * - /packages/core/src/hooks/index.ts
  */
 import { useEffect } from 'react';
+let lockCount = 0;
+let originalBodyState = null;
 
 /**
  * Locks body scroll when `isLocked` is true.
@@ -34,28 +36,41 @@ export function useScrollLock(isLocked) {
     if (!isLocked) {
       return;
     }
-    const scrollX = window.scrollX;
-    const scrollY = window.scrollY;
     const {
       body
     } = document;
-    const prevOverflow = body.style.overflow;
-    const prevPosition = body.style.position;
-    const prevTop = body.style.top;
-    const prevLeft = body.style.left;
-    const prevRight = body.style.right;
-    body.style.overflow = 'hidden';
-    body.style.position = 'fixed';
-    body.style.top = `-${scrollY}px`;
-    body.style.left = '0';
-    body.style.right = '0';
+    if (lockCount === 0) {
+      const scrollX = window.scrollX;
+      const scrollY = window.scrollY;
+      originalBodyState = {
+        scrollX,
+        scrollY,
+        overflow: body.style.overflow,
+        position: body.style.position,
+        top: body.style.top,
+        left: body.style.left,
+        right: body.style.right
+      };
+      body.style.overflow = 'hidden';
+      body.style.position = 'fixed';
+      body.style.top = `-${scrollY}px`;
+      body.style.left = '0';
+      body.style.right = '0';
+    }
+    lockCount += 1;
     return () => {
-      body.style.overflow = prevOverflow;
-      body.style.position = prevPosition;
-      body.style.top = prevTop;
-      body.style.left = prevLeft;
-      body.style.right = prevRight;
-      window.scrollTo(scrollX, scrollY);
+      lockCount -= 1;
+      if (lockCount !== 0 || originalBodyState == null) {
+        return;
+      }
+      const state = originalBodyState;
+      originalBodyState = null;
+      body.style.overflow = state.overflow;
+      body.style.position = state.position;
+      body.style.top = state.top;
+      body.style.left = state.left;
+      body.style.right = state.right;
+      window.scrollTo(state.scrollX, state.scrollY);
     };
   }, [isLocked]);
 }

package/dist/hooks/useStreamingText.d.ts

@@ -12,6 +12,19 @@ export interface UseStreamingTextOptions {
      */
     speed?: StreamingTextSpeed;
 }
+/**
+ * Snap a UTF-16 code-unit offset down to the start of the grapheme cluster
+ * it falls inside, so slicing `text` at the returned offset never splits a
+ * surrogate pair, flag sequence, or ZWJ emoji mid-glyph. Offsets at the
+ * start/end of the string are returned unchanged (nothing to snap).
+ *
+ * Falls back to snapping off a lone low surrogate when `Intl.Segmenter` is
+ * unavailable — narrower than full grapheme-cluster awareness (a ZWJ
+ * sequence or flag pair can still split in that path), but it's what's
+ * achievable without a full grapheme-aware dependency, and it's strictly
+ * better than the unguarded default of never checking at all.
+ */
+export declare function snapToGraphemeBoundary(text: string, offset: number): number;
 /**
  * Smooths bursty streamed text into a steady character-by-character reveal.
  *
@@ -20,9 +33,11 @@ export interface UseStreamingTextOptions {
  * reduced motion, the progressive reveal is skipped entirely and the full
  * `targetText` is returned immediately.
  *
- * The hook advances on word and syntax boundaries, avoiding slices inside
- * markdown markers like `**`, backticks, `[]()`, etc. This prevents visual
- * glitches when the output is rendered through a markdown parser.
+ * The reveal cadence itself advances by a fixed number of UTF-16 code units
+ * per tick, not on word or markdown-syntax boundaries — but the rendered
+ * slice is always snapped back to the nearest grapheme cluster boundary, so
+ * a tick landing mid-surrogate-pair or mid-emoji-sequence never renders a
+ * broken glyph.
  *
  * @example
  * ```

package/dist/hooks/useStreamingText.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useStreamingText.d.ts","sourceRoot":"","sources":["../../src/hooks/useStreamingText.ts"],"names":[],"mappings":"AA4BA;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AA4BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,EACpB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAiGR"}
+{"version":3,"file":"useStreamingText.d.ts","sourceRoot":"","sources":["../../src/hooks/useStreamingText.ts"],"names":[],"mappings":"AA+BA;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AAwCD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAW3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,EACpB,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CAiGR"}

package/dist/hooks/useStreamingText.js

@@ -9,9 +9,12 @@
  * @position Core hook; smooths bursty streamed text into steady character reveal
  *
  * Decouples the arrival rate of streamed chunks from the display rate,
- * draining characters at a steady pace using requestAnimationFrame.
- * Advances on word/syntax boundaries to avoid slicing mid-markdown or
- * mid-word, preventing visual glitches when used with markdown renderers.
+ * draining characters at a steady pace using requestAnimationFrame. The
+ * reveal cadence advances by a fixed number of UTF-16 code units per tick;
+ * the rendered slice is then snapped back to the nearest grapheme cluster
+ * boundary (see snapToGraphemeBoundary) so a tick landing inside a
+ * surrogate pair, flag sequence, or ZWJ emoji doesn't render a lone
+ * surrogate or a partial glyph for one frame.
  *
  * Animation timing derives from Astryx motion tokens (via useTheme) when
  * an Theme provider is present. Falls back to sensible defaults when
@@ -57,6 +60,41 @@ const CHARS_PER_TICK = {
   instant: Infinity
 };
 
+// Reuse a single segmenter when the runtime supports Intl.Segmenter.
+// Granularity is fixed and locale doesn't affect grapheme-cluster
+// boundaries, so one instance is safe to share across calls.
+const graphemeSegmenter = typeof Intl.Segmenter === 'function' ? new Intl.Segmenter(undefined, {
+  granularity: 'grapheme'
+}) : null;
+function isLowSurrogate(codeUnit) {
+  return codeUnit >= 0xdc00 && codeUnit <= 0xdfff;
+}
+
+/**
+ * Snap a UTF-16 code-unit offset down to the start of the grapheme cluster
+ * it falls inside, so slicing `text` at the returned offset never splits a
+ * surrogate pair, flag sequence, or ZWJ emoji mid-glyph. Offsets at the
+ * start/end of the string are returned unchanged (nothing to snap).
+ *
+ * Falls back to snapping off a lone low surrogate when `Intl.Segmenter` is
+ * unavailable — narrower than full grapheme-cluster awareness (a ZWJ
+ * sequence or flag pair can still split in that path), but it's what's
+ * achievable without a full grapheme-aware dependency, and it's strictly
+ * better than the unguarded default of never checking at all.
+ */
+export function snapToGraphemeBoundary(text, offset) {
+  if (offset <= 0 || offset >= text.length) {
+    return offset;
+  }
+  if (graphemeSegmenter) {
+    // `containing` only returns undefined for an out-of-range index; offset
+    // is already guarded to [1, text.length - 1] above, so this is always
+    // defined at runtime — the `??` is to satisfy the type, which is wider.
+    return graphemeSegmenter.segment(text).containing(offset)?.index ?? offset;
+  }
+  return isLowSurrogate(text.charCodeAt(offset)) ? offset - 1 : offset;
+}
+
 /**
  * Smooths bursty streamed text into a steady character-by-character reveal.
  *
@@ -65,9 +103,11 @@ const CHARS_PER_TICK = {
  * reduced motion, the progressive reveal is skipped entirely and the full
  * `targetText` is returned immediately.
  *
- * The hook advances on word and syntax boundaries, avoiding slices inside
- * markdown markers like `**`, backticks, `[]()`, etc. This prevents visual
- * glitches when the output is rendered through a markdown parser.
+ * The reveal cadence itself advances by a fixed number of UTF-16 code units
+ * per tick, not on word or markdown-syntax boundaries — but the rendered
+ * slice is always snapped back to the nearest grapheme cluster boundary, so
+ * a tick landing mid-surrogate-pair or mid-emoji-sequence never renders a
+ * broken glyph.
  *
  * @example
  * ```
@@ -168,5 +208,5 @@ export function useStreamingText(targetText, isStreaming, options) {
   if (!isStreaming || speed === 'instant' || prefersReducedMotion) {
     return targetText;
   }
-  return targetText.slice(0, displayedLen);
+  return targetText.slice(0, snapToGraphemeBoundary(targetText, displayedLen));
 }

package/dist/hooks/useTreeFocus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTreeFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useTreeFocus.ts"],"names":[],"mappings":"AAmCA;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAEhD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC;IAEzC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE7C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC;IAEtD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAEtC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CACX,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,MAAM,GAAG,SAAS,KACnB,OAAO,GAAG,SAAS,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAElD;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE,iEAAiE;IACjE,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC,wDAAwD;IACxD,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C,gDAAgD;IAChD,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAqWvB"}
+{"version":3,"file":"useTreeFocus.d.ts","sourceRoot":"","sources":["../../src/hooks/useTreeFocus.ts"],"names":[],"mappings":"AAmCA;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAEhD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC;IAEzC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IAE7C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC;IAEtD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAEtC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CACX,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,MAAM,GAAG,SAAS,KACnB,OAAO,GAAG,SAAS,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAElD;;;;;;;;;;;;;;;;OAgBG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE,iEAAiE;IACjE,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAEnC,wDAAwD;IACxD,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAEhD;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IAE3C,gDAAgD;IAChD,UAAU,EAAE,MAAM,IAAI,CAAC;IAEvB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CAgXvB"}

package/dist/hooks/useTreeFocus.js

@@ -188,13 +188,19 @@ export function useTreeFocus(options = {}) {
     if (state.timer != null) {
       clearTimeout(state.timer);
     }
-    state.buffer += e.key.toLowerCase();
+    // "aa" would match nothing; a repeat means "next match" (useTypeahead).
+    const char = e.key.toLowerCase();
+    const isRepeatSameChar = state.buffer.length > 0 && state.buffer.split('').every(c => c === char);
+    state.buffer = isRepeatSameChar ? char : state.buffer + char;
     state.timer = setTimeout(() => {
       typeaheadRef.current.buffer = '';
     }, typeaheadResetMs);
     const query = state.buffer;
-    const start = currentIndex < 0 ? 0 : currentIndex;
-    const ordered = [...items.slice(start + 1), ...items.slice(0, start + 1)];
+    // A longer query is refining, so the current item may still be the match.
+    const hasCurrent = currentIndex >= 0;
+    const start = hasCurrent ? currentIndex : 0;
+    const offset = hasCurrent && query.length === 1 ? 1 : 0;
+    const ordered = [...items.slice(start + offset), ...items.slice(0, start + offset)];
     const match = ordered.find(item => !itemDisabled(item) && (item.textContent ?? '').trim().toLowerCase().startsWith(query));
     if (match != null) {
       e.preventDefault();

package/dist/hooks/useTypeahead.d.ts

@@ -12,8 +12,9 @@ export interface UseTypeaheadOptions {
     onMatch: (index: number) => void;
     /**
      * The index to start searching from — typically the currently focused item,
-     * so repeated presses of the same letter cycle through matches. Defaults to
-     * -1 (search from the top).
+     * so repeated presses of the same letter cycle through matches. Any negative
+     * value (the default) means nothing is current: the search runs from the top
+     * and never skips the first item.
      */
     getCurrentIndex?: () => number;
     /**

package/dist/hooks/useTypeahead.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTypeahead.d.ts","sourceRoot":"","sources":["../../src/hooks/useTypeahead.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,aAAa,EAAE,MAAM,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAE9D;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;IAE/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,GAAG,aAAa,KAAK,OAAO,CAAC;IAC/D,gDAAgD;IAChD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAiBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAkF7E"}
+{"version":3,"file":"useTypeahead.d.ts","sourceRoot":"","sources":["../../src/hooks/useTypeahead.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,aAAa,EAAE,MAAM,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAE9D;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEjC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;IAE/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,GAAG,aAAa,KAAK,OAAO,CAAC;IAC/D,gDAAgD;IAChD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAoBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CA6F7E"}

package/dist/hooks/useTypeahead.js

@@ -19,7 +19,12 @@ import { useCallback, useRef } from 'react';
  * candidate) rather than a control/navigation key or a shortcut chord.
  */
 function isPrintableCharacter(e) {
-  return e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey &&
+  return e.key.length === 1 &&
+  // Alt alone is not excluded: Option+letter on macOS composes a printable
+  // character (Option+a → "å"), and dropping those makes accented labels
+  // untypeable. Real chords still carry ctrl or meta — including AltGr,
+  // which sets ctrlKey on Windows and Linux.
+  !e.ctrlKey && !e.metaKey &&
   // A lone space is used for activation in menus, not typeahead-from-empty.
   e.key !== ' ';
 }
@@ -75,8 +80,10 @@ export function useTypeahead(options) {
   }, [resetMs]);
   const onKeyDown = useCallback(e => {
     // A bare Space with no active buffer is not typeahead (menus activate on
-    // Space); once the user is mid-typing, Space extends the query.
-    const isSpaceMidType = e.key === ' ' && bufferRef.current.length > 0;
+    // Space); once the user is mid-typing, Space extends the query. Chorded
+    // with ctrl or meta it is neither — that is an OS or IME shortcut, and
+    // consuming it would append a raw space that poisons the whole buffer.
+    const isSpaceMidType = e.key === ' ' && !e.ctrlKey && !e.metaKey && bufferRef.current.length > 0;
     if (!isPrintableCharacter(e) && !isSpaceMidType) {
       return false;
     }
@@ -92,11 +99,16 @@ export function useTypeahead(options) {
     const nextBuffer = isRepeatSameChar ? char : bufferRef.current + char;
     bufferRef.current = nextBuffer;
     scheduleReset();
-    const start = getCurrentIndex?.() ?? -1;
+    const current = getCurrentIndex?.() ?? -1;
     const count = labels.length;
-    // When repeating a single char, start the search AFTER the current item
-    // so we advance; otherwise include the current item.
-    const offset = isRepeatSameChar ? 1 : 0;
+    const hasCurrent = current >= 0;
+    const start = hasCurrent ? current : 0;
+    // A single-character search starts AFTER the current item, so pressing a
+    // letter walks to the next item beginning with it instead of re-matching
+    // the one already selected (native <select> and APG getIndexByLetter).
+    // Once the buffer is longer it is refining a match, so the current item
+    // stays in range. With nothing current there is nothing to advance past.
+    const offset = hasCurrent && nextBuffer.length === 1 ? 1 : 0;
     for (let i = 0; i < count; i++) {
       const index = (start + offset + i + count) % count;
       if (isDisabled?.(index)) {

package/dist/index.d.ts

@@ -59,6 +59,7 @@ export * from './SelectableCard';
 export * from './Selector';
 export * from './MultiSelector';
 export * from './Icon';
+export * from './Indicator';
 export * from './InputGroup';
 export * from './Item';
 export * from './Text';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -66,6 +66,7 @@ export * from "./SelectableCard/index.js";
 export * from "./Selector/index.js";
 export * from "./MultiSelector/index.js";
 export * from "./Icon/index.js";
+export * from "./Indicator/index.js";
 export * from "./InputGroup/index.js";
 export * from "./Item/index.js";
 export * from "./Text/index.js";

package/dist/theme/defineTheme.d.ts

@@ -28,6 +28,7 @@
  * ```
  */
 import type { IconRegistry } from '../Icon/globalIconRegistry';
+import type { IndicatorRegistry } from '../Indicator/types';
 import type { TypographyConfig } from './types';
 import { type OnMediaOverrides, type ResolvedOnMedia } from './onMediaTokens';
 import { colorDefaults, spacingDefaults, sizeDefaults, radiusDefaults, shadowDefaults, durationDefaults, easeDefaults, typographyDefaults, textSizeDefaults, fontWeightDefaults, typeScaleDefaults } from './tokens.stylex';
@@ -231,6 +232,19 @@ export interface DefineThemeInput {
     components?: ComponentStyleMap;
     /** Icon registry — maps semantic icon names to React nodes */
     icons?: Partial<IconRegistry>;
+    /**
+     * Indicator overrides — replaces the components that draw stateful control
+     * visuals with the theme's own, by name.
+     *
+     * Replacement is by indicator name, not per call site, so a single entry
+     * reaches every component that draws that indicator: mapping `check` to
+     * `RadioIndicator` gives radio visuals to every single-selection mark in the
+     * app.
+     *
+     * Each entry is checked against its indicator's family, so a replacement
+     * must accept the states that family passes.
+     */
+    indicators?: IndicatorRegistry;
     /**
      * Default syntax highlighting theme for code components.
      * Sets --color-syntax-* tokens at the theme root. Can be overridden
@@ -279,6 +293,8 @@ export interface DefinedTheme {
     components?: ComponentStyleMap;
     /** Icon registry */
     icons?: Partial<IconRegistry>;
+    /** Indicator overrides for stateful control visuals, keyed by name */
+    indicators?: IndicatorRegistry;
     /** Whether this theme has been pre-compiled by theme build CLI */
     __built?: true;
     /**

package/dist/theme/defineTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineTheme.d.ts","sourceRoot":"","sources":["../../src/theme/defineTheme.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"defineTheme.d.ts","sourceRoot":"","sources":["../../src/theme/defineTheme.ts"],"names":[],"mappings":"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"}

package/dist/theme/defineTheme.js

@@ -371,11 +371,19 @@ export function defineTheme(input) {
     ...base.icons,
     ...input.icons
   } : input.icons ?? base?.icons;
+
+  // Indicator overrides merge by name, like icons: a child theme replacing one
+  // indicator keeps the ones its base replaced.
+  const indicators = input.indicators && base?.indicators ? {
+    ...base.indicators,
+    ...input.indicators
+  } : input.indicators ?? base?.indicators;
   const theme = {
     name: input.name,
     tokens,
     components,
     icons,
+    indicators,
     __inputTokens: input.tokens,
     __onDark,
     __onLight

package/dist/theme/derivedVarRegistry.d.ts

@@ -22,6 +22,14 @@ export interface DerivedVarEntry {
     vars?: string[];
     /** Named expansion strategy. 'container' expands padding to container tokens. */
     expand?: 'container';
+    /**
+     * Emit only the internal `vars`, dropping the source property from the rule.
+     * Use when the class-carrying element must NOT receive the standard property
+     * itself — the value is consumed by a child through the var instead. Without
+     * this, the property is emitted alongside the var (correct when the same
+     * element both reads the var and applies the property, e.g. Chat/DropdownMenu).
+     */
+    replaces?: boolean;
 }
 /**
  * Component → derived var mappings.

package/dist/theme/derivedVarRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derivedVarRegistry.d.ts","sourceRoot":"","sources":["../../src/theme/derivedVarRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAiChE,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,eAAe,EAAE,CAMnB"}
+{"version":3,"file":"derivedVarRegistry.d.ts","sourceRoot":"","sources":["../../src/theme/derivedVarRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAsChE,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,eAAe,EAAE,CAMnB"}

package/dist/theme/derivedVarRegistry.js

@@ -26,19 +26,6 @@
  * entries share the same property.
  */
 export const derivedVarRegistry = {
-  avatar: [{
-    property: 'fontSize',
-    vars: ['--_avatar-fallback-font-size']
-  }, {
-    property: 'fontWeight',
-    vars: ['--_avatar-fallback-font-weight']
-  }, {
-    property: 'color',
-    vars: ['--_avatar-fallback-color']
-  }, {
-    property: 'backgroundColor',
-    vars: ['--_avatar-fallback-background']
-  }],
   banner: [{
     property: 'borderRadius',
     vars: ['--_banner-radius']
@@ -87,6 +74,15 @@ export const derivedVarRegistry = {
     property: 'borderRadius',
     vars: ['--_popover-radius']
   }],
+  'progressbar-mark': [{
+    property: 'width',
+    vars: ['--_progressbar-mark-width'],
+    replaces: true
+  }, {
+    property: 'height',
+    vars: ['--_progressbar-mark-height'],
+    replaces: true
+  }],
   section: [{
     property: 'padding',
     expand: 'container'
@@ -97,6 +93,11 @@ export const derivedVarRegistry = {
   }, {
     property: 'padding',
     vars: ['--_segmented-control-padding']
+  }],
+  textarea: [{
+    property: 'paddingInline',
+    vars: ['--_textarea-inline-padding'],
+    replaces: true
   }]
 };
 

package/dist/theme/expandColorScale.d.ts

@@ -30,7 +30,9 @@ export interface ColorScaleConfig {
      */
     neutralStyle?: 'warm' | 'cool' | 'neutral';
     /**
-     * Contrast level. Affects tone assignments for text and UI elements.
+     * Contrast level. `'high'` pulls text, icons, and borders toward stronger
+     * tones (and thickens the subtle border's alpha) so structural and textual
+     * boundaries stay perceivable.
      * @default 'standard'
      */
     contrast?: 'standard' | 'high';

package/dist/theme/expandColorScale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expandColorScale.d.ts","sourceRoot":"","sources":["../../src/theme/expandColorScale.ts"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAyCtD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAYR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAuH3E"}
+{"version":3,"file":"expandColorScale.d.ts","sourceRoot":"","sources":["../../src/theme/expandColorScale.ts"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAyCtD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,EACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAYR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAoI3E"}