@astryxdesign/core 0.3.0 → 0.4.0-canary.3112e99

package/src/hooks/useScrollLock.ts

@@ -17,6 +17,19 @@
 
 import {useEffect} from 'react';
 
+interface ScrollLockSnapshot {
+  scrollX: number;
+  scrollY: number;
+  overflow: string;
+  position: string;
+  top: string;
+  left: string;
+  right: string;
+}
+
+let lockCount = 0;
+let originalBodyState: ScrollLockSnapshot | null = null;
+
 /**
  * Locks body scroll when `isLocked` is true.
  *
@@ -36,28 +49,47 @@ export function useScrollLock(isLocked: boolean): void {
       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/src/hooks/useStreamingText.test.ts

@@ -2,7 +2,7 @@
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {renderHook, act} from '@testing-library/react';
-import {useStreamingText} from './useStreamingText';
+import {snapToGraphemeBoundary, useStreamingText} from './useStreamingText';
 
 describe('useStreamingText', () => {
   let rafCallbacks: ((time: number) => void)[];
@@ -189,4 +189,49 @@ describe('useStreamingText', () => {
     // (or close to it — the hook drains charsPerTick per tickMs)
     expect(result.current.length).toBeGreaterThan(targetText.length * 0.5);
   });
+
+  it('never reveals a tick boundary landing mid-surrogate-pair or mid-ZWJ-emoji-sequence (#4779)', () => {
+    // natural speed advances 10 UTF-16 code units per tick. 9 ASCII chars
+    // (indices 0-8) followed by a 4-person ZWJ family emoji (indices 9-19,
+    // one grapheme cluster, 11 code units) means the first tick's raw
+    // boundary (index 10) lands one code unit into the family emoji's first
+    // surrogate pair -- exactly the failure case from the issue.
+    const family = '\u{1F468}‍\u{1F469}‍\u{1F467}‍\u{1F466}';
+    const targetText = 'a'.repeat(9) + family + 'end';
+    const {result} = renderHook(() => useStreamingText(targetText, true));
+
+    expect(rafCallbacks.length).toBeGreaterThan(0);
+    const cb = rafCallbacks.pop()!;
+    act(() => cb(performance.now() + 20));
+
+    // Without the fix this would be 'a'.repeat(9) + a lone high surrogate
+    // (renders as U+FFFD). With the fix, the whole not-yet-complete family
+    // cluster is held back rather than rendering a broken glyph.
+    expect(result.current).toBe('a'.repeat(9));
+  });
+});
+
+describe('snapToGraphemeBoundary', () => {
+  it('does not split a surrogate pair', () => {
+    const text = 'a\u{1F389}b'; // 🎉 is a surrogate pair: indices 1 (high) and 2 (low)
+    expect(snapToGraphemeBoundary(text, 2)).toBe(1);
+    expect(snapToGraphemeBoundary(text, 1)).toBe(1);
+  });
+
+  it('does not split a ZWJ emoji sequence', () => {
+    const family = '\u{1F468}‍\u{1F469}‍\u{1F467}‍\u{1F466}';
+    const text = 'x' + family + 'y';
+    const familyStart = 1;
+    const familyEnd = 1 + family.length;
+    for (let offset = familyStart + 1; offset < familyEnd; offset++) {
+      expect(snapToGraphemeBoundary(text, offset)).toBe(familyStart);
+    }
+  });
+
+  it('leaves boundary offsets (start, end, plain-ASCII midpoints) unchanged', () => {
+    const text = 'hello';
+    expect(snapToGraphemeBoundary(text, 0)).toBe(0);
+    expect(snapToGraphemeBoundary(text, 5)).toBe(5);
+    expect(snapToGraphemeBoundary(text, 3)).toBe(3);
+  });
 });

package/src/hooks/useStreamingText.ts

@@ -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
@@ -68,6 +71,43 @@ const CHARS_PER_TICK = {
   instant: Infinity,
 } as const;
 
+// 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: number): boolean {
+  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: string, offset: number): number {
+  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.
  *
@@ -76,9 +116,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
  * ```
@@ -191,5 +233,5 @@ export function useStreamingText(
     return targetText;
   }
 
-  return targetText.slice(0, displayedLen);
+  return targetText.slice(0, snapToGraphemeBoundary(targetText, displayedLen));
 }

package/src/hooks/useTreeFocus.test.tsx

@@ -261,4 +261,54 @@ describe('useTreeFocus activation + typeahead', () => {
     fireEvent.keyDown(tree, {key: 'c'});
     expect(screen.getByTestId('c')).toHaveFocus();
   });
+
+  it('typeahead cycles through same-letter matches on repeated presses', () => {
+    const nodes: Node[] = [
+      {id: 'apple', label: 'Apple', level: 1},
+      {id: 'apricot', label: 'Apricot', level: 1},
+      {id: 'avocado', label: 'Avocado', level: 1},
+    ];
+    render(<Tree collapsed={nodes} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('apple').focus();
+
+    fireEvent.keyDown(tree, {key: 'a'});
+    expect(screen.getByTestId('apricot')).toHaveFocus();
+
+    // A repeat must cycle, not extend the query to "aa" (as useTypeahead does).
+    fireEvent.keyDown(tree, {key: 'a'});
+    expect(screen.getByTestId('avocado')).toHaveFocus();
+  });
+
+  it('typeahead searches from the top when no treeitem has focus', () => {
+    const nodes: Node[] = [
+      {id: 'apple', label: 'Apple', level: 1},
+      {id: 'banana', label: 'Banana', level: 1},
+      {id: 'avocado', label: 'Avocado', level: 1},
+    ];
+    render(<Tree collapsed={nodes} />);
+    const tree = screen.getByRole('tree');
+
+    // No .focus() call: with no current item, the first match must win.
+    fireEvent.keyDown(tree, {key: 'a'});
+    expect(screen.getByTestId('apple')).toHaveFocus();
+  });
+
+  it('typeahead keeps focus on an item that still matches the refined buffer', () => {
+    const nodes: Node[] = [
+      {id: 'apple', label: 'Apple', level: 1},
+      {id: 'banana', label: 'Banana', level: 1},
+      {id: 'apricot', label: 'Apricot', level: 1},
+    ];
+    render(<Tree collapsed={nodes} />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('apple').focus();
+
+    fireEvent.keyDown(tree, {key: 'a'});
+    expect(screen.getByTestId('apricot')).toHaveFocus();
+
+    // "ap" refines the search; Apricot still matches, so focus holds.
+    fireEvent.keyDown(tree, {key: 'p'});
+    expect(screen.getByTestId('apricot')).toHaveFocus();
+  });
 });

package/src/hooks/useTreeFocus.ts

@@ -377,14 +377,25 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(
       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) as unknown as number;
 
       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) &&

package/src/hooks/useTypeahead.test.tsx

@@ -106,4 +106,154 @@ describe('useTypeahead', () => {
     expect(api.onKeyDown(key(' '))).toBe(false);
     expect(onMatch).not.toHaveBeenCalled();
   });
+
+  it('extends a live buffer with a space', () => {
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Newark', 'New York'],
+        onMatch,
+      }),
+    );
+    for (const k of 'new ') {
+      result.current.onKeyDown(key(k));
+    }
+    result.current.onKeyDown(key('y'));
+    // "new y" reaches New York; a space that ended the buffer instead would
+    // leave "newy", which matches nothing.
+    expect(onMatch).toHaveBeenLastCalledWith(1);
+  });
+
+  it('ignores a Space chorded with ctrl or meta even mid-buffer', () => {
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Melon', 'New York'],
+        onMatch,
+      }),
+    );
+    expect(result.current.onKeyDown(key('n'))).toBe(true);
+    expect(onMatch).toHaveBeenLastCalledWith(1);
+
+    // A chord is not typing. Consuming it would append a raw space and leave
+    // the buffer as "n ", poisoning every keystroke until the reset window.
+    expect(
+      result.current.onKeyDown(
+        new KeyboardEvent('keydown', {key: ' ', ctrlKey: true}),
+      ),
+    ).toBe(false);
+    expect(
+      result.current.onKeyDown(
+        new KeyboardEvent('keydown', {key: ' ', metaKey: true}),
+      ),
+    ).toBe(false);
+
+    result.current.onKeyDown(key('e'));
+    expect(onMatch).toHaveBeenCalledTimes(2);
+    expect(onMatch).toHaveBeenLastCalledWith(1);
+  });
+
+  it('starts a fresh single-character search after the current item', () => {
+    const {onMatch, api} = setup({current: 0}); // Apple is current
+    api.onKeyDown(key('a'));
+    // A single-character search begins at current + 1, so pressing the current
+    // item's own initial advances instead of re-matching it into a dead key.
+    expect(onMatch).toHaveBeenCalledWith(1); // Apricot
+  });
+
+  it('searches from the top when there is no current item', () => {
+    // The last item also matches, so this distinguishes "from the top" from
+    // wrapping backwards off -1 and hitting the bottom of the list first.
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Apple', 'Berry', 'Avocado'],
+        onMatch,
+        getCurrentIndex: () => -1,
+      }),
+    );
+    result.current.onKeyDown(key('a'));
+    expect(onMatch).toHaveBeenCalledWith(0); // Apple, not Avocado
+  });
+
+  it('keeps the current item in range once the buffer is multi-character', () => {
+    const {onMatch, api} = setup({current: 0});
+    api.onKeyDown(key('a')); // single char: advances to Apricot
+    expect(onMatch).toHaveBeenLastCalledWith(1);
+    api.onKeyDown(key('p')); // "ap" refines, so Apple is a candidate again
+    expect(onMatch).toHaveBeenLastCalledWith(0);
+  });
+
+  it('skips unmatchable label slots without shifting the reported index', () => {
+    // Callers may pass null/empty entries to keep the index mapping 1:1 with
+    // their own items — menus pass el.textContent, which can be null.
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => [null, '', '   ', undefined, 'Apple'],
+        onMatch,
+      }),
+    );
+    result.current.onKeyDown(key('a'));
+    expect(onMatch).toHaveBeenCalledWith(4);
+  });
+
+  it('treats any negative or stale current index safely', () => {
+    // A sentinel other than -1, and an index left over from a longer list:
+    // neither may search backwards or report an index outside the list.
+    const fromBelowZero = vi.fn();
+    const {result: below} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => LABELS,
+        onMatch: fromBelowZero,
+        getCurrentIndex: () => -5,
+      }),
+    );
+    below.current.onKeyDown(key('a'));
+    expect(fromBelowZero).toHaveBeenCalledWith(0); // Apple, from the top
+
+    const fromStale = vi.fn();
+    const {result: stale} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => LABELS,
+        onMatch: fromStale,
+        getCurrentIndex: () => 7,
+      }),
+    );
+    stale.current.onKeyDown(key('b'));
+    expect(fromStale).toHaveBeenCalledWith(2); // Banana, in range
+  });
+
+  it('wraps onto the only item when the list has one entry', () => {
+    // "Advance past the current item" is about cycling; with one item the
+    // cycle is itself. The caller decides whether that is a no-op.
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Apple'],
+        onMatch,
+        getCurrentIndex: () => 0,
+      }),
+    );
+    expect(result.current.onKeyDown(key('a'))).toBe(true);
+    expect(onMatch).toHaveBeenCalledWith(0);
+  });
+
+  it('matches characters composed with Option/Alt', () => {
+    const onMatch = vi.fn();
+    const {result} = renderHook(() =>
+      useTypeahead({
+        getItemLabels: () => ['Ångström', 'Berlin'],
+        onMatch,
+        getCurrentIndex: () => -1,
+      }),
+    );
+    // Option+a on macOS emits a printable 'å' with altKey set. Excluding it
+    // makes accented labels untypeable; real chords still carry ctrl/meta.
+    const handled = result.current.onKeyDown(
+      new KeyboardEvent('keydown', {key: 'å', altKey: true}),
+    );
+    expect(handled).toBe(true);
+    expect(onMatch).toHaveBeenCalledWith(0);
+  });
 });

package/src/hooks/useTypeahead.ts

@@ -32,8 +32,9 @@ export interface UseTypeaheadOptions {
 
   /**
    * 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;
 
@@ -67,9 +68,12 @@ export interface UseTypeaheadReturn {
 function isPrintableCharacter(e: React.KeyboardEvent | KeyboardEvent): boolean {
   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 &&
-    !e.altKey &&
     // A lone space is used for activation in menus, not typeahead-from-empty.
     e.key !== ' '
   );
@@ -133,8 +137,14 @@ export function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn {
   const onKeyDown = useCallback(
     (e: React.KeyboardEvent | KeyboardEvent): boolean => {
       // 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;
       }
@@ -154,11 +164,16 @@ export function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn {
       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;

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -40,7 +40,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Set the `dir` attribute on `<html>` (or a wrapping element) yourself — the provider does not set it. Astryx components mirror layout and directional icons from the DOM `dir`, so an RTL locale won\'t visually mirror without it. Use `getLocaleDirection(locale)` to derive the value for both the provider and the DOM.',
+          'Set the `dir` attribute on `<html>` (or a wrapping element) yourself; the provider does not set it. Astryx components mirror layout and directional icons from the DOM `dir`, so an RTL locale won\'t visually mirror without it. Use `getLocaleDirection(locale)` to derive the value for both the provider and the DOM.',
       },
       {
         guidance: false,
@@ -76,7 +76,7 @@ export const docs = {
       type: "'ltr' | 'rtl'",
       required: false,
       description:
-        'Explicit text-direction override for the context. When omitted, direction is derived from `locale` via `Intl.Locale.getTextInfo()`. This sets the direction Astryx reads, but it does NOT set the DOM `dir` attribute — you must set `dir` on `<html>` (or a wrapping element) yourself, since Astryx components mirror layout and directional icons from the DOM `dir`, not from this prop. Set both to the same value and keep them in sync.',
+        'Explicit text-direction override for the context. When omitted, direction is derived from `locale` via `Intl.Locale.getTextInfo()`. This sets the direction Astryx reads, but it does NOT set the DOM `dir` attribute; you must set `dir` on `<html>` (or a wrapping element) yourself, since Astryx components mirror layout and directional icons from the DOM `dir`, not from this prop. Set both to the same value and keep them in sync.',
     },
     {
       name: 'children',
@@ -163,6 +163,11 @@ export const docsDense = {
         description:
           'Use real BCP 47 tags like `fr`, `pt-BR`, or `ar`; regional locales fall back to base language before English.',
       },
+      {
+        guidance: true,
+        description:
+          'Set `dir` on `<html>` (or a wrapper) yourself; the provider does not. Astryx mirrors layout and directional icons from the DOM `dir`, so an RTL locale will not mirror without it. Use `getLocaleDirection(locale)` for both the provider and the DOM.',
+      },
       {
         guidance: false,
         description:

package/src/index.ts

@@ -68,6 +68,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/src/theme/defineTheme.ts

@@ -31,6 +31,7 @@
  */
 
 import type {IconRegistry} from '../Icon/globalIconRegistry';
+import type {IndicatorRegistry} from '../Indicator/types';
 import type {TypographyConfig, FontWeight} from './types';
 import {
   resolveOnMedia,
@@ -41,6 +42,7 @@ import {
   colorDefaults,
   spacingDefaults,
   sizeDefaults,
+  focusDefaults,
   radiusDefaults,
   shadowDefaults,
   durationDefaults,
@@ -73,6 +75,7 @@ export type CoreTokenName =
   | keyof typeof colorDefaults
   | keyof typeof spacingDefaults
   | keyof typeof sizeDefaults
+  | keyof typeof focusDefaults
   | keyof typeof radiusDefaults
   | keyof typeof shadowDefaults
   | keyof typeof durationDefaults
@@ -280,6 +283,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
@@ -329,6 +345,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;
   /**
@@ -361,6 +379,7 @@ export const tokenDefaults: Record<string, string> = {
   ...colorDefaults,
   ...spacingDefaults,
   ...sizeDefaults,
+  ...focusDefaults,
   ...radiusDefaults,
   ...shadowDefaults,
   ...durationDefaults,
@@ -622,11 +641,19 @@ export function defineTheme(input: DefineThemeInput): DefinedTheme {
       ? {...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: DefinedTheme = {
     name: input.name,
     tokens,
     components,
     icons,
+    indicators,
     __inputTokens: input.tokens,
     __onDark,
     __onLight,