@astryxdesign/core 0.4.2 → 0.4.3-canary.0a9618e

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';