@astryxdesign/core 0.4.2 → 0.4.3-canary.00bed29

package/src/theme/onMediaTokens.ts

@@ -21,6 +21,7 @@
  */
 
 import type {TokenValue, ComponentStyleMap} from './defineTheme';
+import {deepMergeComponents} from './mergeComponents';
 
 /**
  * On-media theme overrides — same shape as the main theme but scoped
@@ -89,15 +90,21 @@ function resolveValue(value: TokenValue): string {
 /**
  * Resolve on-media overrides: merge user tokens with defaults,
  * pass through component overrides.
+ *
+ * `base` is the already-resolved surface of a theme being extended. It sits
+ * between the defaults and this theme's own input, so a child theme inherits
+ * the surface customizations of the theme it extends instead of silently
+ * reverting them to the defaults.
  */
 export function resolveOnMedia(
   surface: 'dark' | 'light',
   input?: OnMediaOverrides,
+  base?: ResolvedOnMedia,
 ): ResolvedOnMedia {
   const defaults =
     surface === 'dark' ? defaultOnDarkTokens : defaultOnLightTokens;
 
-  const tokens = {...defaults};
+  const tokens = {...defaults, ...base?.tokens};
 
   if (input?.tokens) {
     for (const [key, value] of Object.entries(input.tokens)) {
@@ -109,6 +116,6 @@ export function resolveOnMedia(
 
   return {
     tokens,
-    components: input?.components,
+    components: deepMergeComponents(base?.components, input?.components),
   };
 }

package/src/utils/characters.test.ts

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file characters.test.ts
+ * @input character-counting utilities
+ * @output Tests for characterCount, firstCharacter, truncateCharacters
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {characterCount, firstCharacter, truncateCharacters} from './characters';
+
+// Multi-code-unit fixtures: an emoji surrogate pair (2 units), a flag
+// sequence (4 units), a ZWJ family (11 units), and a combining mark (2 units).
+const EMOJI = '\u{1F600}'; // 😀
+const FLAG = '\u{1F1F9}\u{1F1F7}'; // 🇹🇷
+const FAMILY = '\u{1F468}‍\u{1F469}‍\u{1F467}‍\u{1F466}'; // 👨‍👩‍👧‍👦
+// é as base + combining mark, spelled as an escape so NFC-normalizing
+// tools cannot silently precompose the fixture into single-code-unit é.
+const E_ACUTE = 'e\u0301';
+
+describe('characterCount', () => {
+  it('returns 0 for the empty string', () => {
+    expect(characterCount('')).toBe(0);
+  });
+
+  it('counts ASCII one per character', () => {
+    expect(characterCount('hello')).toBe(5);
+  });
+
+  it('counts an emoji surrogate pair as one', () => {
+    expect(characterCount(EMOJI.repeat(2))).toBe(2);
+    expect(EMOJI.repeat(2).length).toBe(4); // sanity: code units differ
+  });
+
+  it('counts a flag sequence as one', () => {
+    expect(characterCount(FLAG)).toBe(1);
+  });
+
+  it('counts a ZWJ family emoji as one', () => {
+    expect(characterCount(FAMILY)).toBe(1);
+    expect(FAMILY.length).toBe(11); // sanity: code units differ
+  });
+
+  it('counts a combining-mark character as one', () => {
+    expect(characterCount(E_ACUTE)).toBe(1);
+    expect(E_ACUTE.length).toBe(2); // sanity: code units differ
+  });
+
+  it('counts mixed content by user-perceived characters', () => {
+    expect(characterCount(`a${EMOJI}b`)).toBe(3);
+  });
+});
+
+describe('firstCharacter', () => {
+  it('returns the empty string for the empty string', () => {
+    expect(firstCharacter('')).toBe('');
+  });
+
+  it('returns the first ASCII character', () => {
+    expect(firstCharacter('abc')).toBe('a');
+  });
+
+  it('returns a whole emoji, not half a surrogate pair', () => {
+    expect(firstCharacter(`${EMOJI}x`)).toBe(EMOJI);
+  });
+
+  it('returns a whole ZWJ family emoji', () => {
+    expect(firstCharacter(`${FAMILY}x`)).toBe(FAMILY);
+  });
+
+  it('keeps a combining mark attached to its base', () => {
+    expect(firstCharacter(`${E_ACUTE}cole`)).toBe(E_ACUTE);
+  });
+});
+
+describe('truncateCharacters', () => {
+  it('returns strings within max unchanged', () => {
+    expect(truncateCharacters('abc', 5)).toBe('abc');
+  });
+
+  it('returns strings exactly at max unchanged', () => {
+    expect(truncateCharacters('abcde', 5)).toBe('abcde');
+  });
+
+  it('truncates so the result, including the ellipsis, is max characters', () => {
+    expect(truncateCharacters('abcdefghij', 5)).toBe('abcd…');
+  });
+
+  it('counts a multi-character ellipsis against max', () => {
+    // "..." is 3 characters, so 5 content characters remain.
+    expect(truncateCharacters('aaaaaaaaaa', 8, '...')).toBe('aaaaa...');
+  });
+
+  it('passes strings within max through under a multi-character ellipsis', () => {
+    expect(truncateCharacters('aaaaaaaa', 8, '...')).toBe('aaaaaaaa');
+  });
+
+  it('cuts between characters, never splitting an emoji', () => {
+    // The exact-string assertion also proves no surrogate pair was split.
+    expect(truncateCharacters(EMOJI.repeat(4), 3)).toBe(`${EMOJI.repeat(2)}…`);
+  });
+
+  it('treats a ZWJ family emoji as a single unit when cutting', () => {
+    expect(truncateCharacters(`${FAMILY}abc`, 2)).toBe(`${FAMILY}…`);
+  });
+
+  it('returns the empty string unchanged', () => {
+    expect(truncateCharacters('', 5)).toBe('');
+  });
+
+  it('degrades to just the ellipsis when max is smaller than the ellipsis', () => {
+    // Documented degenerate behavior: no consumer passes max below the
+    // ellipsis length, but the clamp must stay predictable.
+    expect(truncateCharacters('abcdef', 2, '...')).toBe('...');
+    expect(truncateCharacters('abcdef', 0)).toBe('…');
+  });
+});
+
+describe('code-point fallback (no Intl.Segmenter)', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it('keeps surrogate pairs intact while counting by code points', async () => {
+    vi.resetModules();
+    // characters.ts only reads Intl.Segmenter, so a minimal stub suffices.
+    vi.stubGlobal('Intl', {Segmenter: undefined});
+    const fallback = await import('./characters');
+
+    expect(fallback.characterCount(EMOJI.repeat(2))).toBe(2);
+    expect(fallback.firstCharacter(`${EMOJI}x`)).toBe(EMOJI);
+    expect(fallback.firstCharacter('')).toBe('');
+    expect(fallback.truncateCharacters(EMOJI.repeat(4), 3)).toBe(
+      `${EMOJI.repeat(2)}…`,
+    );
+    // Documented degradation: a flag sequence splits into its two
+    // regional-indicator code points under the fallback.
+    expect(fallback.characterCount(FLAG)).toBe(2);
+  });
+});

package/src/utils/characters.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file characters.ts
+ * @input Strings that may contain characters made of several code units
+ *        (emoji, flags, joined emoji sequences, accented letters)
+ * @output Exports characterCount, firstCharacter, truncateCharacters —
+ *         replacements for .length / .charAt(0) / .slice(0, n) that measure
+ *         and cut user-visible strings the way a person reads them
+ * @position Shared utility; consumed by Avatar, TextArea, PowerSearch, Table
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/utils/characters.test.ts
+ * - /packages/core/src/utils/index.ts
+ */
+
+/**
+ * Reuse a single segmenter when the runtime supports Intl.Segmenter.
+ * `grapheme` is the Intl granularity name for a user-perceived character.
+ */
+const characterSegmenter =
+  typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, {granularity: 'grapheme'})
+    : null;
+
+/**
+ * Split a string into user-perceived characters. The code-point fallback
+ * keeps surrogate pairs intact but may split joined emoji sequences and flag
+ * pairs on runtimes without Intl.Segmenter.
+ */
+function splitCharacters(str: string): string[] {
+  if (characterSegmenter) {
+    return [...characterSegmenter.segment(str)].map(s => s.segment);
+  }
+  return [...str];
+}
+
+/**
+ * Number of characters in a string — the count a person would give, where one
+ * emoji, flag, or accented letter is one character. Replacement for `.length`
+ * on user-visible strings, which counts internal storage units instead.
+ */
+export function characterCount(str: string): number {
+  if (str === '') {
+    return 0;
+  }
+  return splitCharacters(str).length;
+}
+
+/**
+ * The first character of a string, or '' when empty. Replacement for
+ * `.charAt(0)`, which can return half of an emoji. Reads only the first
+ * character, so cost does not scale with the length of the string.
+ */
+export function firstCharacter(str: string): string {
+  if (characterSegmenter) {
+    const first = characterSegmenter.segment(str)[Symbol.iterator]().next();
+    return first.done ? '' : first.value.segment;
+  }
+  const codePoint = str.codePointAt(0);
+  return codePoint == null ? '' : String.fromCodePoint(codePoint);
+}
+
+/**
+ * Truncate to at most `max` characters, ellipsis included: strings within
+ * `max` characters pass through unchanged; longer strings are cut so the
+ * result — content plus `ellipsis` — is exactly `max` characters (or just the
+ * ellipsis, when `max` is smaller than the ellipsis itself). Replacement for
+ * `str.slice(0, n) + '…'`, which can cut an emoji in half.
+ *
+ * @example
+ * ```
+ * truncateCharacters('abcdefghij', 5) // 'abcd…'
+ * truncateCharacters('abcdefghij', 8, '...') // 'abcde...'
+ * ```
+ */
+export function truncateCharacters(
+  str: string,
+  max: number,
+  ellipsis = '…',
+): string {
+  const characters = splitCharacters(str);
+  if (characters.length <= max) {
+    return str;
+  }
+  const keep = Math.max(max - characterCount(ellipsis), 0);
+  return characters.slice(0, keep).join('') + ellipsis;
+}

package/src/utils/ime.test.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {isImeKeyEvent} from './ime';
+
+describe('isImeKeyEvent', () => {
+  it('detects the modern isComposing signal', () => {
+    expect(isImeKeyEvent({isComposing: true})).toBe(true);
+    expect(isImeKeyEvent({isComposing: true, keyCode: 13})).toBe(true);
+  });
+
+  it('detects the legacy keyCode 229 fallback (IME processing sentinel)', () => {
+    // Some IMEs / older Safari fire the composing keydown with isComposing
+    // not yet set to true but report keyCode 229.
+    expect(isImeKeyEvent({keyCode: 229})).toBe(true);
+    expect(isImeKeyEvent({isComposing: false, keyCode: 229})).toBe(true);
+  });
+
+  it('returns false for ordinary (non-composing) keydowns', () => {
+    expect(isImeKeyEvent({})).toBe(false);
+    expect(isImeKeyEvent({isComposing: false})).toBe(false);
+    expect(isImeKeyEvent({keyCode: 13})).toBe(false); // plain Enter
+    expect(isImeKeyEvent({keyCode: 27})).toBe(false); // plain Escape
+    expect(isImeKeyEvent({isComposing: false, keyCode: 13})).toBe(false);
+  });
+
+  it('only treats a literal `true` isComposing as composing', () => {
+    // Guards against truthy-but-not-true values leaking through.
+    // @ts-expect-error intentionally passing a non-boolean to assert strictness
+    expect(isImeKeyEvent({isComposing: 1})).toBe(false);
+  });
+});

package/src/utils/ime.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ime.ts
+ * @input Receives a keyboard event (React SyntheticEvent's `nativeEvent`, or a
+ *   native DOM KeyboardEvent) with optional `isComposing` / `keyCode`.
+ * @output Exports `isImeKeyEvent`, the canonical predicate for "this keydown is
+ *   part of an in-progress IME composition and must not be treated as a command".
+ * @position Shared low-level utility; consumed by every editable/overlay surface
+ *   that handles Enter/Escape/arrows in `onKeyDown` (Typeahead, PowerSearch,
+ *   Dialog, ContextMenu, Tooltip, Chat composer, focus-trap Escape, ...).
+ *
+ * ── Why this exists (read once, here — do not re-explain at call sites) ──
+ *
+ * When a CJK user (Korean / Japanese / Chinese) is composing text via an IME,
+ * the browser fires a `keydown` event to COMMIT or CANCEL the pending
+ * composition (Enter commits the highlighted candidate; Escape cancels it;
+ * ArrowUp/Down/Home/End navigate the candidate window). Crucially this
+ * `keydown` fires BEFORE the `compositionend` event that actually writes the
+ * committed text into the field. So a naive `onKeyDown` handler sees a bare
+ * "Enter" or "Escape" and misreads the composition-commit/cancel as an
+ * application command — accepting a typeahead suggestion, submitting a chat
+ * message, closing a dialog/menu/tooltip, or saving a filter — mid-composition.
+ * The fix is to detect the composing keydown and early-return before running
+ * any command logic.
+ *
+ * Two signals, both needed:
+ *
+ *  1. `event.isComposing === true` — the modern, spec'd signal
+ *     (https://www.w3.org/TR/uievents/#dom-keyboardevent-iscomposing). This is
+ *     the primary check and is reliable in current evergreen browsers.
+ *
+ *  2. `event.keyCode === 229` — the legacy fallback. `229` is the sentinel
+ *     keyCode browsers report for "the key event is being processed by an IME".
+ *     It is still load-bearing: some IMEs and older Safari fire the composing
+ *     `keydown` with `isComposing` NOT yet set to `true`, but DO report
+ *     keyCode 229. Keeping both makes the guard robust across the browser
+ *     matrix we support. Do not drop the 229 fallback without a browser-matrix
+ *     audit.
+ *
+ * ── Which event object to pass ──
+ *
+ * React's SyntheticEvent for KeyboardEvent *does* surface `isComposing`, but to
+ * avoid any cross-browser normalization gap prefer passing the *native* event
+ * (`e.nativeEvent`) from React handlers — that is what BaseTypeahead,
+ * PowerSearch, and the Chat composer do. Native DOM listeners (Dialog,
+ * ContextMenu, Tooltip, focus-trap) pass the DOM `KeyboardEvent` directly.
+ * The parameter is intentionally structurally typed so both shapes are accepted.
+ *
+ * Note: `keyCode` is deprecated on the DOM `KeyboardEvent` type but is still
+ * present at runtime; we read it defensively via the optional structural field.
+ */
+
+/**
+ * The sentinel `keyCode` browsers report while a key event is being processed
+ * by an IME (the composing keydown that fires before `compositionend`). See the
+ * file header for why this legacy signal is still load-bearing alongside
+ * `isComposing`.
+ */
+const IME_PROCESSING_KEY_CODE = 229;
+
+export function isImeKeyEvent(event: {
+  isComposing?: boolean;
+  keyCode?: number;
+}): boolean {
+  return (
+    event.isComposing === true || event.keyCode === IME_PROCESSING_KEY_CODE
+  );
+}

package/src/utils/index.ts

@@ -70,6 +70,8 @@ export type {ISOTimeString, ParsedTime} from './timeParser';
 export {parseStyleKey} from './parseStyleKey';
 export {getKey, type Key, type KeyFallback} from './getKey';
 
+export {characterCount, firstCharacter, truncateCharacters} from './characters';
+
 export {mergeProps} from './mergeProps';
 export {mergeRefs} from './mergeRefs';
 export {isFocusDetached} from './focusReturn';
@@ -105,3 +107,5 @@ export {rtlStyles} from './rtlStyles';
 // The shared focus ring, exported for @astryxdesign/lab — same reason
 // rtlStyles is: a style that must be identical across packages, not copied.
 export {focusOutlineStyles, focusOutlineProps} from './focusOutline.stylex';
+
+export {isImeKeyEvent} from './ime';