@astryxdesign/core 0.5.0 → 0.5.1-canary.046f6ea

package/src/hooks/useOverflow.ts

@@ -9,8 +9,9 @@
  * @position Core hook; used by OverflowList and consumers for overflow patterns
  *
  * Measures children rendered in a hidden container to determine how many fit
- * in the available width, without flickering. Uses ResizeObserver to react
- * to container size changes. Supports an optional item cap (`maxVisibleItems`)
+ * in the available width, without flickering. Observes both the visible and
+ * hidden measurement containers so changes to available width or measured child
+ * sizes recalculate the result. Supports an optional item cap (`maxVisibleItems`)
  * and bounded multi-row wrapping (`maxRows`); the fit/clamp/row-packing math
  * lives in the pure `computeOverflow` helper.
  *
@@ -136,6 +137,7 @@ export function useOverflow(
   const containerElRef = useRef<HTMLElement | null>(null);
   const measureElRef = useRef<HTMLElement | null>(null);
   const observedElRef = useRef<HTMLElement | null>(null);
+  const observedMeasureElRef = useRef<HTMLElement | null>(null);
 
   const calculate = useCallback(() => {
     const container = containerElRef.current;
@@ -236,10 +238,20 @@ export function useOverflow(
 
   const measureRef = useCallback(
     (el: HTMLElement | null) => {
+      if (observedMeasureElRef.current) {
+        unobserveResize(observedMeasureElRef.current);
+        observedMeasureElRef.current = null;
+      }
+
       measureElRef.current = el;
-      if (el) {
-        calculate();
+      if (!el) {
+        return;
       }
+
+      observeResize(el, () => {
+        calculate();
+      });
+      observedMeasureElRef.current = el;
     },
     [calculate],
   );

package/src/hooks/useTypeahead.doc.mjs

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useTypeahead',
+  displayName: 'useTypeahead',
+  keywords: [
+    'typeahead',
+    'type to focus',
+    'first character',
+    'keyboard',
+    'search',
+    'jump',
+    'menu',
+    'listbox',
+    'select',
+    'apg',
+    'accessibility',
+    'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseTypeaheadOptions',
+      description: 'Configuration object.',
+      required: true,
+    },
+    {
+      name: 'options.getItemLabels',
+      type: '() => ReadonlyArray<string | null | undefined>',
+      description:
+        "Returns the item labels in DOM order. A null or empty entry marks a non-matchable slot and keeps indices aligned with the caller's items.",
+      required: true,
+    },
+    {
+      name: 'options.onMatch',
+      type: '(index: number) => void',
+      description:
+        "Called with the index of the matched item so the caller can focus or select it; typically useListFocus's focusItem.",
+      required: true,
+    },
+    {
+      name: 'options.getCurrentIndex',
+      type: '() => number',
+      description:
+        'The index to search from, usually the focused item, so repeated presses of one letter cycle through matches. A negative value means nothing is current.',
+      default: '() => -1',
+    },
+    {
+      name: 'options.resetMs',
+      type: 'number',
+      description:
+        'Milliseconds of inactivity after which the typed buffer resets.',
+      default: '750',
+    },
+    {
+      name: 'options.isDisabled',
+      type: '(index: number) => boolean',
+      description: 'Whether an index should be skipped, e.g. disabled items.',
+    },
+  ],
+  returns: [
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent | KeyboardEvent) => boolean',
+      description:
+        'Keydown handler. Returns true when it consumed a printable character, so the caller can stop its own key handling.',
+    },
+    {
+      name: 'reset',
+      type: '() => void',
+      description:
+        'Clears the pending buffer, e.g. when the collection closes.',
+    },
+  ],
+  usage: {
+    description:
+      "Adds APG type-to-focus search to a collection: printable keystrokes are buffered (resetting after a pause), and the first item whose label starts with the buffer is reported through onMatch. Pressing the same letter repeatedly cycles through the matches rather than filtering deeper. It moves nothing itself; pair it with the collection's own focus management, most often useListFocus or useGridFocus.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Wire onMatch to the focus manager you already have (useListFocus.focusItem) instead of moving focus yourself.',
+      },
+      {
+        guidance: true,
+        description:
+          'Let it see the key event first and fall through to arrow-key navigation only when it returns false.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass getCurrentIndex so repeated presses of one letter walk through matches instead of sticking on the first.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use it on a text input; the field already receives the characters, and typeahead would fight the value.',
+      },
+    ],
+  },
+  relatedComponents: ['DropdownMenu', 'Selector', 'TreeList'],
+  relatedHooks: ['useListFocus', 'useGridFocus', 'useTreeFocus'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'focus',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'APG type-to-focus search for a collection. Buffers printable keys (resets after pause), matches labels by prefix, reports index via onMatch. Same letter pressed repeatedly cycles matches. Moves nothing itself; pair w/ useListFocus / useGridFocus.',
+  paramDescriptions: {
+    options: 'config.',
+    'options.getItemLabels':
+      'item labels in DOM order; null / empty = non-matchable slot, indices stay aligned.',
+    'options.onMatch':
+      'called w/ matched index so caller focuses / selects (e.g. useListFocus focusItem).',
+    'options.getCurrentIndex':
+      'index to search from (usually focused item) so repeat presses cycle. negative = nothing current.',
+    'options.resetMs': 'ms of inactivity before typed buffer resets.',
+    'options.isDisabled': 'whether an index is skipped (e.g. disabled items).',
+  },
+  returnDescriptions: {
+    onKeyDown:
+      'keydown handler; true = consumed a printable char, caller can stop its own handling.',
+    reset: 'clears pending buffer (e.g. on close).',
+  },
+  usage: {
+    description:
+      'Type-to-jump for menus / listboxes / trees. Buffered prefix match w/ APG same-letter cycling; reports index, caller owns focus.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Wire onMatch to existing focus manager (useListFocus.focusItem), do not move focus yourself.',
+      },
+      {
+        guidance: true,
+        description:
+          'Give it the key event first; fall through to arrow navigation when it returns false.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass getCurrentIndex so repeat presses walk matches instead of sticking on first.',
+      },
+      {
+        guidance: false,
+        description: 'Use on a text input; field already gets the characters.',
+      },
+    ],
+  },
+};

package/src/i18n/InternationalizationContext.ts

@@ -23,6 +23,7 @@
  */
 
 import {createContext} from 'react';
+import {getResolve} from './resolve';
 import type {Locale, MessagesByLocale, Overrides} from './types';
 
 export interface InternationalizationContextValue {
@@ -30,6 +31,7 @@ export interface InternationalizationContextValue {
   direction: 'ltr' | 'rtl';
   messages: MessagesByLocale;
   overrides?: Overrides;
+  translate: ReturnType<typeof getResolve>;
 }
 
 /**
@@ -41,5 +43,6 @@ export const InternationalizationContext =
     locale: 'en',
     direction: 'ltr',
     messages: {},
+    translate: getResolve('en', {}),
   });
 InternationalizationContext.displayName = 'InternationalizationContext';

package/src/i18n/InternationalizationProvider.tsx

@@ -23,6 +23,7 @@ import {useMemo, type ReactNode} from 'react';
 import {InternationalizationContext} from './InternationalizationContext';
 import {getLocaleDirection} from './getLocaleDirection';
 import type {Locale, MessagesByLocale, Overrides} from './types';
+import {getResolve} from './resolve';
 
 export interface InternationalizationProviderProps {
   /**
@@ -85,7 +86,13 @@ export function InternationalizationProvider({
 }: InternationalizationProviderProps) {
   const direction = dir ?? getLocaleDirection(locale);
   const value = useMemo(
-    () => ({locale, direction, messages: messages ?? {}, overrides}),
+    () => ({
+      locale,
+      direction,
+      messages: messages ?? {},
+      overrides,
+      translate: getResolve(locale, messages ?? {}, overrides),
+    }),
     [locale, direction, messages, overrides],
   );
   return (

package/src/i18n/__tests__/resolve.test.ts

@@ -9,9 +9,16 @@
  */
 
 import {describe, expect, test, beforeEach, vi} from 'vitest';
-import {__resetForTests, resolve, resolveLocaleChain} from '../resolve';
+import {__resetForTests, getResolve, resolveLocaleChain} from '../resolve';
 import type {Catalog, MessagesByLocale, Overrides} from '../types';
 
+const resolve = (
+  ...[key, values, locale, messages, overrides]: [
+    ...Parameters<ReturnType<typeof getResolve>>,
+    ...Parameters<typeof getResolve>,
+  ]
+) => getResolve(locale, messages, overrides)(key, values);
+
 // Reset caches between tests so warn-once and formatter cache don't bleed.
 beforeEach(() => {
   __resetForTests();
@@ -209,6 +216,21 @@ describe('resolve — overrides', () => {
     // Should fall through to en since fr has no messages and es override doesn't apply
     expect(out).toBe('Go to next page');
   });
+
+  test('override `pt` should take precedence over message `pt-BR`', () => {
+    const overrides: Overrides = {
+      pt: {key: 'override'},
+    };
+    const messages: MessagesByLocale = {
+      'pt-BR': {
+        key: {
+          defaultMessage: 'shipped',
+        },
+      },
+    };
+    const out = resolve('key', undefined, 'pt-BR', messages, overrides);
+    expect(out).toBe('override');
+  });
 });
 
 describe('resolve — ICU MessageFormat', () => {

package/src/i18n/resolve.ts

@@ -73,74 +73,71 @@ export function resolveLocaleChain(locale: Locale): Locale[] {
   return chain;
 }
 
-function lookup(
-  key: string,
+function getLookup(
   locale: Locale,
   messages: MessagesByLocale,
-  overrides: Overrides | undefined,
-): string | null {
+  overrides?: Overrides,
+): Record<string, string> {
+  const lookup: Record<string, string> = {};
   const chain = resolveLocaleChain(locale);
-
   // 1 + 2. Overrides (most specific to least specific in the chain)
   if (overrides !== undefined) {
     for (const tag of chain) {
-      const value = overrides[tag]?.[key];
-      if (value !== undefined) {
-        return value;
+      if (overrides[tag]) {
+        for (const [key, value] of Object.entries(overrides[tag])) {
+          if (lookup[key] === undefined && value !== null) {
+            lookup[key] = value;
+          }
+        }
       }
     }
   }
-
-  // 3 + 4. Shipped catalogs (most specific to least specific)
   for (const tag of chain) {
-    const entry = messages[tag]?.[key];
-    if (entry !== undefined) {
-      return entry.defaultMessage;
+    if (messages[tag]) {
+      for (const [key, value] of Object.entries(messages[tag])) {
+        if (lookup[key] === undefined && value?.defaultMessage !== null) {
+          lookup[key] = value?.defaultMessage;
+        }
+      }
     }
   }
 
-  // 5. Shipped en catalog — always present
-  const enEntry = EN_CATALOG[key];
-  if (enEntry !== undefined) {
-    return enEntry.defaultMessage;
-  }
-
-  // 6. Nothing found
-  return null;
+  return lookup;
 }
 
-export function resolve(
-  key: string,
-  values: Record<string, unknown> | undefined,
+export function getResolve(
   locale: Locale,
   messages: MessagesByLocale,
-  overrides: Overrides | undefined,
-): string {
-  const result = lookup(key, locale, messages, overrides);
-
-  if (result === null) {
-    // Fires ONLY when a key is missing from every source including the
-    // shipped `en` catalog — a real bug (typo, stale catalog, deleted key).
-    // Fallback to `en` from a non-en locale is expected and stays silent,
-    // matching the FormatJS / i18next default.
-    warnOnce(
-      `astryx-i18n:${locale}::${key}`,
-      'astryx-i18n',
-      `missing key: ${key} (locale: ${locale})`,
-    );
-    return key;
-  }
+  overrides?: Overrides,
+) {
+  const lookup = getLookup(locale, messages, overrides);
+
+  return (key: string, values: Record<string, unknown> | undefined) => {
+    const result = lookup[key] ?? EN_CATALOG[key]?.defaultMessage;
+    if (result === undefined) {
+      // Fires ONLY when a key is missing from every source including the
+      // shipped `en` catalog — a real bug (typo, stale catalog, deleted key).
+      // Fallback to `en` from a non-en locale is expected and stays silent,
+      // matching the FormatJS / i18next default.
+      warnOnce(
+        `astryx-i18n:${locale}::${key}`,
+        'astryx-i18n',
+        `missing key: ${key} (locale: ${locale})`,
+      );
+      return key;
+    }
 
-  if (values === undefined) {
-    // Static string — skip the parser entirely for the common case
-    return result;
-  }
+    if (values === undefined) {
+      // Static string — skip the parser entirely for the common case
+      return result;
+    }
 
-  const formatted = getFormatter(result, locale).format(values);
-  // IntlMessageFormat.format returns string | (string | React elements) — we
-  // only ever pass string values so it will be a string; assert for the type
-  // system.
-  return formatted as string;
+    const formatted = getFormatter(result, locale).format(values);
+    // IntlMessageFormat.format returns string | (string | React elements) — we
+    // only ever pass string values so it will be a string; assert for the type
+    // system.
+    return formatted as string;
+  };
 }
 
 /**

package/src/i18n/useTranslator.ts

@@ -19,9 +19,8 @@
  * - /packages/core/src/i18n/t.client.ts
  */
 
-import {use, useCallback} from 'react';
+import {use} from 'react';
 import {InternationalizationContext} from './InternationalizationContext';
-import {resolve} from './resolve';
 
 export type TranslatorFn = (
   key: string,
@@ -42,9 +41,5 @@ export type TranslatorFn = (
  */
 export function useTranslator(): TranslatorFn {
   const ctx = use(InternationalizationContext);
-  return useCallback(
-    (key: string, values?: Record<string, unknown>) =>
-      resolve(key, values, ctx.locale, ctx.messages, ctx.overrides),
-    [ctx.locale, ctx.messages, ctx.overrides],
-  );
+  return ctx.translate;
 }

package/src/index.ts

@@ -135,6 +135,8 @@ export type {
   ToastOptions,
   ToastDismissFn,
   ShowToastFn,
+  ToastContentRenderProps,
+  ToastContentRenderFn,
 } from './Toast';
 
 // Popover component and hook

package/src/raw-import.d.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Ambient module declaration for Vite's `?raw` imports.
+ *
+ * numberParser.docblock.test.ts reads its own subject's source as text, to
+ * check the prose in it against the parser's behaviour. Vite serves that with
+ * the `?raw` query; without this declaration TypeScript fails with TS2307.
+ */
+
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

package/src/theme/Theme.test.tsx

@@ -1,10 +1,22 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {render, cleanup} from '@testing-library/react';
 import React from 'react';
 import {Theme} from './Theme';
 import {defineTheme} from './defineTheme';
+import {dataTokenDefaults} from './domainTokens';
+import type * as DefineThemeModule from './defineTheme';
+
+const {generateThemeCSSSpy} = vi.hoisted(() => ({
+  generateThemeCSSSpy: vi.fn(),
+}));
+
+vi.mock('./defineTheme', async importOriginal => {
+  const actual = await importOriginal<typeof DefineThemeModule>();
+  generateThemeCSSSpy.mockImplementation(actual.generateThemeCSS);
+  return {...actual, generateThemeCSS: generateThemeCSSSpy};
+});
 
 const testTheme = defineTheme({
   name: 'test',
@@ -25,6 +37,7 @@ describe('Theme', () => {
     // Clean up documentElement state before each test
     document.documentElement.removeAttribute('data-theme');
     document.documentElement.removeAttribute('data-astryx-theme');
+    generateThemeCSSSpy.mockClear();
   });
 
   afterEach(() => {
@@ -120,7 +133,9 @@ describe('Theme', () => {
       'test',
     );
     unmount();
-    expect(document.documentElement.hasAttribute('data-astryx-theme')).toBe(false);
+    expect(document.documentElement.hasAttribute('data-astryx-theme')).toBe(
+      false,
+    );
   });
 
   // =========================================================================
@@ -166,4 +181,91 @@ describe('Theme', () => {
     expect(nestedWrapper).toBeTruthy();
     expect(nestedWrapper?.getAttribute('data-theme')).toBe('light');
   });
+
+  // =========================================================================
+  // Data token defaults — one shared :root block, not one per theme scope
+  // =========================================================================
+
+  const baseTags = () =>
+    Array.from(document.head.querySelectorAll('style[data-astryx-theme-base]'));
+
+  it('injects the data token defaults into @layer astryx-base', () => {
+    render(
+      <Theme theme={testTheme}>
+        <span>child</span>
+      </Theme>,
+    );
+
+    expect(baseTags()).toHaveLength(1);
+    const css = baseTags()[0].textContent ?? '';
+    expect(css).toContain('@layer astryx-base {');
+    expect(css).toContain(':root {');
+    expect(css).toContain(
+      `--color-data-categorical-blue: ${dataTokenDefaults['--color-data-categorical-blue']};`,
+    );
+  });
+
+  it('injects one shared block for nested themes, not one per scope', () => {
+    render(
+      <Theme theme={testTheme}>
+        <Theme theme={altTheme}>
+          <span>nested</span>
+        </Theme>
+      </Theme>,
+    );
+
+    expect(baseTags()).toHaveLength(1);
+
+    // The nested theme declares no --color-data-* of its own, so nothing
+    // shadows a value the parent theme set: that is what lets the override
+    // inherit through the ordinary cascade.
+    const themeTags = Array.from(
+      document.head.querySelectorAll('style[data-astryx-theme]'),
+    );
+    for (const tag of themeTags) {
+      expect(tag.textContent).not.toContain('--color-data-');
+    }
+  });
+
+  it('keeps the defaults while any theme is still mounted', () => {
+    const outer = render(
+      <Theme theme={testTheme}>
+        <span>a</span>
+      </Theme>,
+    );
+    render(
+      <Theme theme={altTheme}>
+        <span>b</span>
+      </Theme>,
+    );
+
+    outer.unmount();
+    expect(baseTags()).toHaveLength(1);
+
+    cleanup();
+    expect(baseTags()).toHaveLength(0);
+  });
+
+  it('generates a theme once across nested and sibling mounts', () => {
+    render(
+      <Theme theme={testTheme}>
+        <Theme theme={testTheme}>
+          <span>nested</span>
+        </Theme>
+      </Theme>,
+    );
+    render(
+      <Theme theme={testTheme}>
+        <span>sibling</span>
+      </Theme>,
+    );
+
+    expect(generateThemeCSSSpy).toHaveBeenCalledTimes(1);
+    expect(baseTags()).toHaveLength(1);
+
+    const injected = Array.from(document.querySelectorAll('style'))
+      .map(tag => tag.textContent ?? '')
+      .join('\n');
+    expect(injected.match(/:root\s*\{/g)).toHaveLength(1);
+  });
 });