@astryxdesign/core 0.4.2 → 0.4.3-canary.551a8de

package/src/PowerSearch/PowerSearch.test.tsx

@@ -158,6 +158,41 @@ describe('PowerSearch', () => {
     expect(screen.getByRole('combobox')).toHaveFocus();
   });
 
+  describe('token value truncation (#4759)', () => {
+    it('truncates token values by characters, not code units', () => {
+      const truncConfig: PowerSearchConfig = {
+        name: 'trunc',
+        fields: [
+          {
+            key: 'status',
+            label: 'Status',
+            operators: [{key: 'is', label: 'is', value: {type: 'string'}}],
+          },
+        ],
+      };
+      // 14 emoji = 28 code units but 14 user-perceived characters.
+      // adjustedMaxLength = max(15 - 'Status'.length - 'is'.length, 10) = 10,
+      // so the value truncates only past 13 characters, cutting at 10.
+      render(
+        <PowerSearch
+          config={truncConfig}
+          filters={[
+            {
+              field: 'status',
+              operator: 'is',
+              value: {type: 'string', value: '\u{1F600}'.repeat(14)},
+            },
+          ]}
+          onChange={() => {}}
+          maxTokenLength={15}
+        />,
+      );
+      expect(
+        screen.getByText('\u{1F600}'.repeat(10) + '...'),
+      ).toBeInTheDocument();
+    });
+  });
+
   describe('startIcon', () => {
     it('does not render a start icon when omitted', () => {
       render(<PowerSearch config={config} filters={[]} onChange={() => {}} />);
@@ -425,11 +460,15 @@ describe('PowerSearch', () => {
   });
 });
 
-
 describe('PowerSearch statusVariant forwarding', () => {
   it('defaults to attached (status renders with data-variant="attached")', () => {
     const {container} = render(
-      <PowerSearch config={config} filters={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+      <PowerSearch
+        config={config}
+        filters={[]}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',
@@ -439,7 +478,13 @@ describe('PowerSearch statusVariant forwarding', () => {
 
   it('forwards statusVariant="detached" to the underlying Field status', () => {
     const {container} = render(
-      <PowerSearch config={config} filters={[]} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+      <PowerSearch
+        config={config}
+        filters={[]}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+        statusVariant="detached"
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',

package/src/PowerSearch/PowerSearch.tsx

@@ -54,6 +54,7 @@ import {formatFilterValue} from './formatFilterValue';
 import {PowerSearchEditPopover} from './PowerSearchEditPopover';
 import {resolveOperatorLabel} from './resolveOperatorLabel';
 import {themeProps} from '../utils/themeProps';
+import {truncateCharacters} from '../utils/characters';
 import {useTranslator} from '../i18n';
 import type {
   PowerSearchConfig,
@@ -117,7 +118,9 @@ const resultCountStyles = stylex.create({
 });
 
 function truncateString(value: string, limit: number): string {
-  return value.length > limit + 3 ? value.slice(0, limit) + '...' : value;
+  // Same semantics as before — strings within limit + 3 pass through, longer
+  // ones cut to limit + '...' — but counted in characters, not code units.
+  return truncateCharacters(value, limit + 3, '...');
 }
 
 function getEnumLabel(values: ReadonlyArray<EnumItem>, value: string): string {

package/src/PowerSearch/formatFilterValue.test.ts

@@ -62,6 +62,28 @@ describe('formatFilterValue', () => {
         'abcde',
       );
     });
+
+    it('truncates by characters, never splitting an emoji (#4759)', () => {
+      // Four surrogate-pair emoji: 8 code units, 4 user-perceived characters.
+      // The exact-string assertion also proves no surrogate pair was split.
+      const out = fmt(
+        {type: 'string'},
+        {type: 'string', value: '\u{1F600}'.repeat(4)},
+        3,
+      );
+      expect(out).toBe('\u{1F600}'.repeat(2) + ELLIPSIS);
+    });
+
+    it('keeps multi-unit characters within maxLength intact (#4759)', () => {
+      // Three emoji are 6 code units but only 3 user-perceived characters.
+      expect(
+        fmt(
+          {type: 'string'},
+          {type: 'string', value: '\u{1F600}'.repeat(3)},
+          3,
+        ),
+      ).toBe('\u{1F600}'.repeat(3));
+    });
   });
 
   describe('integer / float', () => {

package/src/PowerSearch/formatFilterValue.ts

@@ -13,12 +13,10 @@
 import type {OperatorValue, FilterValue, EnumItem} from './types';
 import type {InternalConfig} from './useInternalConfig';
 import type {TranslatorFn} from '../i18n';
+import {truncateCharacters} from '../utils/characters';
 
 function truncate(str: string, maxLength: number): string {
-  if (str.length <= maxLength) {
-    return str;
-  }
-  return str.slice(0, maxLength - 1) + '\u2026';
+  return truncateCharacters(str, maxLength);
 }
 
 function formatEnumLabel(

package/src/Switch/Switch.test.tsx

@@ -262,6 +262,22 @@ describe('Switch', () => {
     expect(screen.getByLabelText('Toggle row')).toBeInTheDocument();
   });
 
+  it('drops the label gap when isLabelHidden so the row is only as wide as the track', () => {
+    const {rerender} = render(
+      <Switch
+        label="Toggle row"
+        isLabelHidden
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+    const row = screen.getByRole('switch').parentElement!.parentElement!;
+    expect(getComputedStyle(row).gap).toMatch(/^0(px)?$/);
+
+    rerender(<Switch label="Toggle row" value={false} onChange={() => {}} />);
+    expect(getComputedStyle(row).gap).not.toMatch(/^0(px)?$/);
+  });
+
   it('keeps description linked via aria-describedby when isLabelHidden', () => {
     render(
       <Switch

package/src/Switch/Switch.tsx

@@ -135,6 +135,12 @@ const styles = stylex.create({
     alignItems: 'center',
     gap: spacingVars['--spacing-2'],
   },
+  // A hidden label is sr-only, so its wrapper is a zero-width flex item — the
+  // row gap would still be painted beside the track, making the field box
+  // wider than the control it contains. Matches CheckboxInput.
+  containerLabelHidden: {
+    gap: 0,
+  },
   containerSpread: {
     justifyContent: 'space-between',
     width: '100%',
@@ -655,6 +661,7 @@ export function Switch({
         }}
         {...stylex.props(
           styles.container,
+          isLabelHidden && styles.containerLabelHidden,
           labelSpacing === 'spread' && styles.containerSpread,
           !isDisabled && switchScope,
         )}>

package/src/Table/Table.test.tsx

@@ -95,6 +95,12 @@ describe('columnUtils', () => {
     it('handles single character', () => {
       expect(capitalize('a')).toBe('A');
     });
+
+    it('uppercases an astral-plane letter without splitting it (#4759)', () => {
+      // Deseret 𐐨 (U+10428) uppercases to 𐐀 (U+10400); charAt(0) would grab
+      // half the surrogate pair and leave the string unchanged.
+      expect(capitalize('\u{10428}pple')).toBe('\u{10400}pple');
+    });
   });
 
   describe('generateColumns', () => {

package/src/Table/columnUtils.ts

@@ -13,6 +13,7 @@
 
 import type {CSSProperties, ReactNode} from 'react';
 import type {TableColumn, ProportionalWidth, PixelWidth} from './types';
+import {firstCharacter} from '../utils/characters';
 
 /** Default minimum width (in px) for proportional columns. */
 export const DEFAULT_MIN_COLUMN_WIDTH = 120;
@@ -168,7 +169,8 @@ export function capitalize(str: string): string {
   if (str.length === 0) {
     return str;
   }
-  return str.charAt(0).toUpperCase() + str.slice(1);
+  const first = firstCharacter(str);
+  return first.toUpperCase() + str.slice(first.length);
 }
 
 /**

package/src/TextArea/TextArea.doc.mjs

@@ -105,7 +105,7 @@ export const docs = {
       name: 'maxLength',
       type: 'number',
       description:
-        'Maximum number of characters allowed. When set, a character counter (current/max) is displayed inside the input container, anchored to the bottom-right beneath the text. Does not enforce the limit natively; when exceeded the counter turns red and shows a warning icon (a non-color cue), and screen-reader users hear the remaining/over-limit count announced.',
+        'Maximum number of characters allowed, counted as user-perceived characters — an emoji or flag sequence counts as one. When set, a character counter (current/max) is displayed inside the input container, anchored to the bottom-right beneath the text. Does not enforce the limit natively; when exceeded the counter turns red and shows a warning icon (a non-color cue), and screen-reader users hear the remaining/over-limit count announced. Consumers validating the limit should count with characterCount (exported from the package) so enforcement matches the displayed count.',
     },
     {
       name: 'status',

package/src/TextArea/TextArea.test.tsx

@@ -504,6 +504,33 @@ describe('TextArea', () => {
       expect(screen.getByRole('textbox')).not.toHaveAttribute('maxlength');
     });
 
+    it('counts user-perceived characters, not code units (#4759)', () => {
+      // Two surrogate-pair emoji: 4 code units, but 2 user-perceived characters.
+      render(
+        <TextArea
+          label="Description"
+          value={'\u{1F600}\u{1F600}'}
+          onChange={() => {}}
+          maxLength={5}
+        />,
+      );
+      expect(screen.getByText('2/5')).toBeInTheDocument();
+    });
+
+    it('measures the over-limit state in characters (#4759)', () => {
+      // Three ZWJ family emoji: 33 code units, 3 user-perceived characters.
+      const family = '\u{1F468}‍\u{1F469}‍\u{1F467}‍\u{1F466}';
+      render(
+        <TextArea
+          label="Description"
+          value={family.repeat(3)}
+          onChange={() => {}}
+          maxLength={2}
+        />,
+      );
+      expect(screen.getByText('3/2')).toBeInTheDocument();
+    });
+
     it('counter updates as user types (controlled)', async () => {
       const user = userEvent.setup();
       function Wrapper() {
@@ -570,6 +597,51 @@ describe('TextArea', () => {
       });
     });
 
+    it('announces zone transitions using character counts (#4759)', async () => {
+      function Wrapper() {
+        const [val, setVal] = useState('x'.repeat(7));
+        return (
+          <TextArea
+            label="Description"
+            value={val}
+            onChange={setVal}
+            maxLength={10}
+          />
+        );
+      }
+      render(<Wrapper />);
+      // Appending two emoji makes 9 characters (11 code units): near the limit
+      // with 1 remaining. Code-unit counting would call this over the limit
+      // and announce assertively instead.
+      fireEvent.change(screen.getByRole('textbox'), {
+        target: {value: 'x'.repeat(7) + '\u{1F600}\u{1F600}'},
+      });
+      const politeRegion = () =>
+        document.querySelector('[data-astryx-live-region="polite"]');
+      const assertiveRegion = () =>
+        document.querySelector('[data-astryx-live-region="assertive"]');
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('1 character remaining');
+      });
+      expect(assertiveRegion()).not.toHaveTextContent('over the limit');
+    });
+
+    it('does not flag over-limit while characters fit, even when code units exceed (#4759)', () => {
+      // Three emoji: 6 code units but 3 user-perceived characters — within a
+      // maxLength of 4, so no error state anywhere.
+      render(
+        <TextArea
+          label="Description"
+          value={'\u{1F600}'.repeat(3)}
+          onChange={() => {}}
+          maxLength={4}
+        />,
+      );
+      const counter = screen.getByText('3/4');
+      expect(counter.querySelector('svg')).toBeNull();
+      expect(screen.getByRole('textbox')).not.toHaveAttribute('aria-invalid');
+    });
+
     it('shows a non-color over-limit indicator icon when exceeded', () => {
       const {container} = render(
         <TextArea

package/src/TextArea/TextArea.tsx

@@ -22,6 +22,7 @@ import {
   useTransition,
   useRef,
   useCallback,
+  useMemo,
   type ChangeEvent,
   type ClipboardEvent,
   type FocusEvent,
@@ -53,6 +54,7 @@ import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
+import {characterCount} from '../utils/characters';
 import {useTranslator} from '../i18n';
 
 const COUNTER_WARNING_THRESHOLD = 0.8;
@@ -312,10 +314,13 @@ export interface TextAreaProps extends Omit<
    */
   onPaste?: (e: ClipboardEvent<HTMLTextAreaElement>) => void;
   /**
-   * Maximum number of characters allowed.
-   * When set, displays a character counter below the textarea.
+   * Maximum number of characters allowed, counted as user-perceived
+   * characters — an emoji or flag sequence counts as one. When set,
+   * displays a character counter below the textarea.
    * Does not enforce the limit natively — the counter shows error styling
-   * when exceeded, and the consumer can validate via onChange.
+   * when exceeded, and the consumer can validate via onChange. Validate with
+   * `characterCount` (exported from this package) rather than `value.length`
+   * so enforcement matches the displayed count.
    */
   maxLength?: number;
   /**
@@ -482,7 +487,11 @@ export function TextArea({
       return;
     }
     const newValue = e.target.value;
-    announceCounter(newValue.length);
+    // Guarded here, not just inside announceCounter, so textareas without a
+    // maxLength never pay for segmenting the whole value on each keystroke.
+    if (maxLength != null) {
+      announceCounter(characterCount(newValue));
+    }
     onChange?.(newValue, e);
     if (changeAction && !e.defaultPrevented) {
       startTransition(async () => {
@@ -492,6 +501,15 @@ export function TextArea({
     }
   };
 
+  // Counter semantics count user-perceived characters, so an emoji or flag
+  // sequence counts as one character, not its code units.
+  // Only measured when a counter exists — segmentation is O(value length),
+  // and memoized so re-renders that keep the same value skip it entirely.
+  const valueLength = useMemo(
+    () => (maxLength != null ? characterCount(optimisticValue) : 0),
+    [maxLength, optimisticValue],
+  );
+
   const effectivelyDisabled = isDisabled || isBusy;
 
   // Focus textarea when clicking anywhere on the wrapper (icons, padding, etc.)
@@ -583,7 +601,7 @@ export function TextArea({
           aria-required={isRequired && !isOptional ? 'true' : undefined}
           aria-invalid={
             status?.type === 'error' ||
-            (maxLength != null && optimisticValue.length > maxLength)
+            (maxLength != null && valueLength > maxLength)
               ? 'true'
               : undefined
           }
@@ -614,15 +632,15 @@ export function TextArea({
             id={counterID}
             {...stylex.props(
               styles.counter,
-              optimisticValue.length > maxLength && styles.counterError,
+              valueLength > maxLength && styles.counterError,
             )}>
-            {optimisticValue.length > maxLength && (
+            {valueLength > maxLength && (
               // Non-color cue so the over-limit state isn't conveyed by the red
               // color alone (WCAG 1.4.1). Decorative — the count text and the
               // live-region announcement carry the meaning.
               <Icon icon="warning" size="sm" />
             )}
-            {optimisticValue.length}/{maxLength}
+            {valueLength}/{maxLength}
           </div>
         )}
       </div>

package/src/TreeList/TreeList.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-tree-list', visualProps: ['density']},
+      {className: 'astryx-tree-list', visualProps: ['density', 'variant']},
       {className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
       {className: 'astryx-tree-list-chevron', states: ['state']},
       {className: 'astryx-tree-list-item-label', states: ['selected']},
@@ -104,7 +104,7 @@ export const docsZh = {
   group: 'TreeList',
   theming: {
     targets: [
-      {className: 'astryx-tree-list', visualProps: ['density']},
+      {className: 'astryx-tree-list', visualProps: ['density', 'variant']},
       {className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},
       {className: 'astryx-tree-list-chevron', states: ['state']},
       {className: 'astryx-tree-list-item-label', states: ['selected']},

package/src/TreeList/TreeList.tsx

@@ -332,7 +332,7 @@ export function TreeList({
       ref={ref}
       data-testid={testId}
       {...mergeProps(
-        themeProps('tree-list', {density}),
+        themeProps('tree-list', {density, variant}),
         stylex.props(styles.root, xstyle),
         className,
         style,

package/src/__tests__/stubMatchMedia.test.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file stubMatchMedia.test.ts
+ * @input Uses vitest, stubMatchMedia
+ * @output Unit coverage for the shared query-aware matchMedia stub
+ * @position Testing; guards the helper other suites trust to route queries
+ *
+ * The helper exists because a stub that ignores its query silently reroutes
+ * code branching on a different one — the failure mode leaves every test
+ * green. A helper sold on that promise has to be held to it, so these assert
+ * the routing itself rather than any component behaviour.
+ */
+
+import {describe, it, expect, afterEach, vi} from 'vitest';
+import {stubMatchMedia} from './stubMatchMedia';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('stubMatchMedia', () => {
+  it('routes prefers-reduced-motion independently of every other query', () => {
+    // The exact combination the blanket stub could not express: below a
+    // breakpoint (matches) while motion is NOT reduced.
+    stubMatchMedia({reduceMotion: false, matches: true});
+
+    expect(matchMedia('(prefers-reduced-motion: reduce)').matches).toBe(false);
+    expect(matchMedia('(max-width: 768px)').matches).toBe(true);
+  });
+
+  it('answers no-preference as the opposite of reduce', () => {
+    // Two spellings, opposite meanings. A substring test on
+    // 'prefers-reduced-motion' alone would hand both the same answer.
+    stubMatchMedia({reduceMotion: true});
+
+    expect(matchMedia('(prefers-reduced-motion: reduce)').matches).toBe(true);
+    expect(matchMedia('(prefers-reduced-motion: no-preference)').matches).toBe(
+      false,
+    );
+  });
+
+  it('treats the bare preference query as reduce', () => {
+    stubMatchMedia({reduceMotion: true});
+    expect(matchMedia('(prefers-reduced-motion)').matches).toBe(true);
+
+    stubMatchMedia({reduceMotion: false});
+    expect(matchMedia('(prefers-reduced-motion)').matches).toBe(false);
+  });
+
+  it('defaults to full motion and matching everything else', () => {
+    stubMatchMedia();
+
+    expect(matchMedia('(prefers-reduced-motion: reduce)').matches).toBe(false);
+    expect(matchMedia('(max-width: 768px)').matches).toBe(true);
+  });
+
+  it('lets a non-motion query be answered false', () => {
+    // Above the breakpoint, motion still reduced — the other axis of the
+    // combination, so neither knob can be quietly driving both.
+    stubMatchMedia({reduceMotion: true, matches: false});
+
+    expect(matchMedia('(prefers-reduced-motion: reduce)').matches).toBe(true);
+    expect(matchMedia('(max-width: 768px)').matches).toBe(false);
+  });
+
+  it('echoes the query and exposes the listener API components subscribe to', () => {
+    stubMatchMedia();
+    const mql = matchMedia('(max-width: 768px)');
+
+    // useMediaQuery subscribes; a stub without these throws on mount rather
+    // than failing an assertion, which reads as an unrelated crash.
+    expect(mql.media).toBe('(max-width: 768px)');
+    expect(typeof mql.addEventListener).toBe('function');
+    expect(typeof mql.removeEventListener).toBe('function');
+    expect(typeof mql.addListener).toBe('function');
+    expect(typeof mql.removeListener).toBe('function');
+  });
+});

package/src/__tests__/stubMatchMedia.ts

@@ -0,0 +1,95 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file stubMatchMedia.ts
+ * @input Uses vitest
+ * @output stubMatchMedia — a query-aware window.matchMedia stub
+ * @position Shared test helper; imported by component tests that render below
+ *   a breakpoint while also exercising motion-sensitive behaviour
+ *
+ * jsdom has no matchMedia, so tests stub it. The usual stub answers every query
+ * with one boolean:
+ *
+ *   vi.stubGlobal('matchMedia', vi.fn().mockReturnValue({matches: true, ...}))
+ *
+ * That is enough to put AppShell below its breakpoint — and it silently also
+ * matches `prefers-reduced-motion`, rerouting any code that branches on motion.
+ * MobileNav's close delay is capped at 0 under reduced motion, so a suite using
+ * the blanket stub runs against an immediate close while its test names claim
+ * it is exercising the real delay. The failure mode is invisible: every test
+ * still passes.
+ *
+ * So the two answers are separate knobs here. `reduceMotion` answers
+ * `prefers-reduced-motion` only; `matches` answers everything else (breakpoint
+ * width queries, which tests below a breakpoint want to be true).
+ *
+ * SYNC: When modified, update this header.
+ */
+
+import {vi} from 'vitest';
+
+export interface StubMatchMediaOptions {
+  /** Whether the user prefers reduced motion. */
+  reduceMotion?: boolean;
+  /** Answer for every other query — width breakpoints, hover, etc. */
+  matches?: boolean;
+}
+
+/**
+ * Answer a `prefers-reduced-motion` query, or null if it isn't one.
+ *
+ * The preference has two spellings and they are opposites, so a single
+ * `includes('prefers-reduced-motion')` would answer `no-preference` with the
+ * value meant for `reduce` — the same answer-without-reading mistake this
+ * helper exists to prevent. Core only queries `reduce` today (MobileNav,
+ * Carousel); handling both is what keeps that true if one changes.
+ */
+function answerReducedMotion(
+  query: string,
+  reduceMotion: boolean,
+): boolean | null {
+  if (query.includes('prefers-reduced-motion: reduce')) {
+    return reduceMotion;
+  }
+  if (query.includes('prefers-reduced-motion: no-preference')) {
+    return !reduceMotion;
+  }
+  // Bare `(prefers-reduced-motion)` is true for any value other than
+  // no-preference, i.e. the same as `reduce`.
+  if (query.includes('prefers-reduced-motion')) {
+    return reduceMotion;
+  }
+  return null;
+}
+
+/**
+ * Install a `window.matchMedia` stub whose answer depends on the query.
+ *
+ * Call from `beforeEach` (or inside a test that needs different motion
+ * settings) and pair with `vi.unstubAllGlobals()` in `afterEach`.
+ *
+ * @example
+ * ```
+ * beforeEach(() => {
+ *   stubMatchMedia({reduceMotion: false});
+ * });
+ * ```
+ */
+export function stubMatchMedia({
+  reduceMotion = false,
+  matches = true,
+}: StubMatchMediaOptions = {}): void {
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn((query: string) => ({
+      matches: answerReducedMotion(query, reduceMotion) ?? matches,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+}