@astryxdesign/core 0.5.1 → 0.5.2-canary.0a6a1eb

package/src/hooks/useFocusReturnVisibility.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useFocusReturnVisibility.ts
+ * @input Uses the shared interaction-modality tracker
+ * @output Preserves returned focus while suppressing pointer-only focus rings
+ * @position Internal focus-return policy for adaptive overlays
+ */
+
+import {useCallback, useEffect, useState} from 'react';
+import {
+  getInteractionModality,
+  trackInteractionModality,
+} from '../utils/interactionModality';
+
+export function useFocusReturnVisibility() {
+  const [isFocusRingSuppressed, setIsFocusRingSuppressed] = useState(false);
+
+  useEffect(() => {
+    trackInteractionModality();
+  }, []);
+
+  const prepareFocusReturn = useCallback(() => {
+    setIsFocusRingSuppressed(getInteractionModality() === 'pointer');
+  }, []);
+
+  const resetFocusReturn = useCallback(() => {
+    setIsFocusRingSuppressed(false);
+  }, []);
+
+  const onFocusReturnTargetFocus = useCallback(() => {
+    if (getInteractionModality() === 'keyboard') {
+      setIsFocusRingSuppressed(false);
+    }
+  }, []);
+
+  return {
+    isFocusRingSuppressed,
+    onFocusReturnTargetFocus,
+    prepareFocusReturn,
+    resetFocusReturn,
+  };
+}

package/src/hooks/useFocusTrap.test.tsx

@@ -193,6 +193,46 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
     expect(screen.getByTestId('first')).toHaveFocus();
   });
 
+  it('moves from a programmatic container focus target into the tabbable cycle', () => {
+    render(
+      <Trap>
+        <button type="button" data-testid="first">
+          First
+        </button>
+        <button type="button" data-testid="last">
+          Last
+        </button>
+      </Trap>,
+    );
+    const trap = screen.getByTestId('trap');
+    trap.tabIndex = -1;
+    trap.focus();
+
+    fireEvent.keyDown(document, {key: 'Tab'});
+
+    expect(screen.getByTestId('first')).toHaveFocus();
+  });
+
+  it('moves backward from a programmatic container focus target to the last tabbable control', () => {
+    render(
+      <Trap>
+        <button type="button" data-testid="first">
+          First
+        </button>
+        <button type="button" data-testid="last">
+          Last
+        </button>
+      </Trap>,
+    );
+    const trap = screen.getByTestId('trap');
+    trap.tabIndex = -1;
+    trap.focus();
+
+    fireEvent.keyDown(document, {key: 'Tab', shiftKey: true});
+
+    expect(screen.getByTestId('last')).toHaveFocus();
+  });
+
   it('keeps a programmatic focus target when the trap has no tabbable controls', () => {
     render(
       <Trap>

package/src/hooks/useFocusTrap.ts

@@ -375,6 +375,19 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
         const first = focusable[0];
         const last = focusable[focusable.length - 1];
 
+        if (document.activeElement === container) {
+          // Programmatic initial focus can sit on the trap container itself
+          // (for example a dialog panel with no content controls). Move into
+          // the tabbable cycle instead of letting Tab escape to the page.
+          event.preventDefault();
+          if (event.shiftKey) {
+            last.focus();
+          } else {
+            first.focus();
+          }
+          return;
+        }
+
         if (event.shiftKey) {
           // Shift+Tab: if on first element, wrap to last
           if (document.activeElement === first) {

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