@astryxdesign/core 0.2.0 → 0.3.0-canary.1b8b3f2

package/src/hooks/useTreeFocus.test.tsx

@@ -35,10 +35,12 @@ function Tree({
   collapsed = NO_NODES,
   expanded = NO_NODES,
   onActivate,
+  dir,
 }: {
   collapsed?: Node[];
   expanded?: Node[];
   onActivate?: (id: string | undefined) => boolean | undefined;
+  dir?: 'ltr' | 'rtl';
 }) {
   const [isOpen, setIsOpen] = useState(false);
   const nodes = isOpen && expanded.length > 0 ? expanded : collapsed;
@@ -47,7 +49,7 @@ function Tree({
     onActivate: onActivate ? (_item, id) => onActivate(id) : undefined,
   });
   return (
-    <ul ref={treeRef} role="tree" onKeyDown={handleKeyDown}>
+    <ul ref={treeRef} role="tree" dir={dir} onKeyDown={handleKeyDown}>
       {nodes.map(n => (
         <li
           key={n.id}
@@ -172,6 +174,56 @@ describe('useTreeFocus tree semantics (Arrow Left/Right)', () => {
   });
 });
 
+describe('useTreeFocus RTL tree semantics (WAI-ARIA Tree View)', () => {
+  const COLLAPSED: Node[] = [
+    {id: 'p', label: 'Parent', level: 1, expanded: false},
+  ];
+  const EXPANDED: Node[] = [
+    {id: 'p', label: 'Parent', level: 1, expanded: true},
+    {id: 'c1', label: 'Child 1', level: 2},
+    {id: 'c2', label: 'Child 2', level: 2},
+  ];
+
+  it('auto-detects dir="rtl": ArrowLeft expands a collapsed parent, then enters the first child', () => {
+    render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} dir="rtl" />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('p').focus();
+
+    expect(screen.queryByTestId('c1')).not.toBeInTheDocument();
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // RTL: descend → expand
+    expect(screen.getByTestId('c1')).toBeInTheDocument();
+    expect(screen.getByTestId('p')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // RTL: descend → into first child
+    expect(screen.getByTestId('c1')).toHaveFocus();
+  });
+
+  it('auto-detects dir="rtl": ArrowRight moves to parent, then collapses', () => {
+    render(<Tree collapsed={COLLAPSED} expanded={EXPANDED} dir="rtl" />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('p').focus();
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // expand
+    fireEvent.keyDown(tree, {key: 'ArrowLeft'}); // into child 1
+    expect(screen.getByTestId('c1')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowRight'}); // RTL: ascend → child leaf → parent
+    expect(screen.getByTestId('p')).toHaveFocus();
+
+    fireEvent.keyDown(tree, {key: 'ArrowRight'}); // RTL: ascend → expanded parent → collapse
+    expect(screen.queryByTestId('c1')).not.toBeInTheDocument();
+  });
+
+  it('vertical keys (ArrowDown/ArrowUp) are unaffected by RTL', () => {
+    render(<Tree collapsed={FLAT} dir="rtl" />);
+    const tree = screen.getByRole('tree');
+    screen.getByTestId('a').focus();
+    fireEvent.keyDown(tree, {key: 'ArrowDown'});
+    expect(screen.getByTestId('b')).toHaveFocus();
+    fireEvent.keyDown(tree, {key: 'ArrowUp'});
+    expect(screen.getByTestId('a')).toHaveFocus();
+  });
+});
+
 describe('useTreeFocus activation + typeahead', () => {
   it('Enter/Space call onActivate for the focused item', () => {
     const onActivate = vi.fn(() => true);

package/src/hooks/useTreeFocus.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useTreeFocus.ts
- * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect
+ * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect, isRtlElement
  * @output Exports useTreeFocus hook for WAI-ARIA tree keyboard navigation
  * @position Core hook; used by TreeList for roving tabindex + APG tree keyboard model
  *
@@ -16,6 +16,7 @@
 
 import {useCallback, useRef} from 'react';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+import {isRtlElement} from './isRtlElement';
 
 /** Keys handled by the tree keyboard model (used to gate typeahead). */
 const NAVIGATION_KEYS = new Set([
@@ -429,7 +430,17 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(
         return;
       }
 
-      switch (e.key) {
+      // Under RTL, swap the horizontal arrows to a logical key so the
+      // expand/collapse case bodies (written LTR-first) stay unchanged.
+      let key = e.key;
+      if (key === 'ArrowLeft' || key === 'ArrowRight') {
+        const rtl = isRtlElement(treeRef.current);
+        if (rtl) {
+          key = key === 'ArrowLeft' ? 'ArrowRight' : 'ArrowLeft';
+        }
+      }
+
+      switch (key) {
         case 'ArrowDown': {
           e.preventDefault();
           focusEnabledFrom(items, currentIndex < 0 ? 0 : currentIndex + 1, 1);

package/src/i18n/InternationalizationProvider.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'InternationalizationProvider',
@@ -37,6 +37,11 @@ export const docs = {
         description:
           'Use real BCP 47 tags such as `fr`, `pt-BR`, or `ar`; regional locales fall back to their base language before English.',
       },
+      {
+        guidance: true,
+        description:
+          'Set the `dir` attribute on `<html>` (or a wrapping element) yourself — the provider does not set it. Astryx components mirror layout and directional icons from the DOM `dir`, so an RTL locale won\'t visually mirror without it. Use `getLocaleDirection(locale)` to derive the value for both the provider and the DOM.',
+      },
       {
         guidance: false,
         description:
@@ -66,6 +71,13 @@ export const docs = {
       description:
         'Sparse per-locale key overrides applied on top of shipped defaults. Overrides are locale-keyed so a runtime locale swap picks up the correct set.',
     },
+    {
+      name: 'dir',
+      type: "'ltr' | 'rtl'",
+      required: false,
+      description:
+        'Explicit text-direction override for the context. When omitted, direction is derived from `locale` via `Intl.Locale.getTextInfo()`. This sets the direction Astryx reads, but it does NOT set the DOM `dir` attribute — you must set `dir` on `<html>` (or a wrapping element) yourself, since Astryx components mirror layout and directional icons from the DOM `dir`, not from this prop. Set both to the same value and keep them in sync.',
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -128,7 +140,7 @@ export function AppI18n({children}: {children: ReactNode}) {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Wraps app to set active locale and (optionally) merge translation catalogs + per-locale overrides. Astryx components resolve strings against this context; missing keys fall back to shipped English.',

package/src/i18n/InternationalizationProvider.tsx

@@ -61,6 +61,12 @@ export interface InternationalizationProviderProps {
    * from `locale` via `Intl.Locale.getTextInfo()`. Provide this to force a
    * direction (e.g. RTL layout testing under an English catalog) or to skip the
    * derivation when you already know the direction.
+   *
+   * This sets the direction astryx reads via context; it does NOT set the DOM
+   * `dir` attribute. You must set `dir` on `<html>` (or a wrapping element)
+   * yourself — astryx components mirror layout and directional icons from the
+   * DOM `dir`, so an RTL locale won't visually mirror without it. Keep the two
+   * in sync (e.g. `dir={getLocaleDirection(locale)}` on both).
    */
   dir?: 'ltr' | 'rtl';
   children: ReactNode;

package/src/i18n/useDirection.ts

@@ -10,9 +10,12 @@
  *   when called outside a provider (matches the silent-en-fallback pattern of
  *   useTranslator).
  *
- * Use this in components that need to swap directional icons, mirror
- * behavioral logic (slider math, keyboard nav), or apply direction-specific
- * styling that CSS logical properties can't express.
+ * Render-time last resort. Prefer, in order: CSS logical properties; the shared
+ * `rtlStyles.mirror` for directional icons (CSS scaleX, not a JS icon-name
+ * swap); and lazy DOM reads (`isRtlElement`) for behavioral logic like keyboard
+ * nav or drag math. Reach for this hook only when you need the direction value
+ * during render and none of those fit — note it can mismatch on hydration if
+ * the provider's direction disagrees with the actual `<html dir>`.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/i18n/InternationalizationContext.ts

package/src/i18n/useTranslator.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useTranslator',
   displayName: 'useTranslator',
@@ -31,7 +31,7 @@ export const docs = {
   importPath: '@astryxdesign/core',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Hook returning a translator function bound to the current InternationalizationProvider context. Call with an ICU MessageFormat key and values to get the formatted string for the active locale.',

package/src/index.ts

@@ -33,6 +33,7 @@ export * from './Calendar';
 export * from './Center';
 export * from './CodeBlock';
 export * from './CommandPalette';
+export * from './ComplexSelector';
 export * from './Chat';
 export * from './Markdown';
 export * from './Citation';
@@ -168,25 +169,8 @@ export * from './hooks';
 export * from './utils';
 
 // Theme
+export type {TextColorMap} from './Text';
 export * from './theme';
 
 // Internationalization
 export * from './i18n';
-
-// Doc types — for external library authors writing .doc.mjs files
-export type {
-  ComponentDoc,
-  SingleComponentDoc,
-  MultiComponentDoc,
-  PropDoc,
-  ComponentEntry,
-  ThemingTarget,
-  ComponentVar,
-  DerivedVar,
-  TranslationDoc,
-  GroupDoc,
-  ReferenceDoc,
-  ReferenceSection,
-  ContentBlock,
-  TokenPreviewType,
-} from './docs-types';

package/src/theme/MediaTheme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'MediaTheme',
@@ -100,7 +100,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/SyntaxTheme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'SyntaxTheme',
@@ -74,7 +74,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/Theme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Theme',
@@ -86,7 +86,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/Theme.tsx

@@ -41,8 +41,8 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import type {ThemeMode} from './types';
 import {colorVars, typographyVars} from './tokens.stylex';
-import {registerIcons} from '../Icon/globalIconRegistry';
 import {generateThemeCSS, type DefinedTheme} from './defineTheme';
+import {registerTheme} from './themeRegistry';
 import {dataAttr} from '../naming';
 import {ThemeContext} from './useTheme';
 import {warnOnce} from '../utils/devWarning';
@@ -243,6 +243,8 @@ export function Theme({
 }: ThemeProps): React.ReactElement {
   const isNested = use(ThemeNestingContext);
 
+  registerTheme(theme);
+
   useThemeStyleInjection(theme);
   useRootThemeSync(isNested, mode, theme.name);
 
@@ -254,12 +256,6 @@ export function Theme({
         ? wrapperStyles.light
         : wrapperStyles.system;
 
-  // Icons — register globally (works in both server and client environments)
-  const icons = theme.icons;
-  if (icons != null) {
-    registerIcons(icons);
-  }
-
   // Memoize the context value to prevent unnecessary re-renders
   const ctxValue = useMemo(() => ({theme, mode}), [theme, mode]);
 

package/src/theme/contrast.test.ts

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {relativeLuminance, compositeOver, contrastRatio} from './contrast';
+import {parseColor} from '../utils/color';
+
+describe('relativeLuminance', () => {
+  it('is 0 for black and 1 for white', () => {
+    expect(relativeLuminance({r: 0, g: 0, b: 0, a: 1})).toBe(0);
+    expect(relativeLuminance({r: 255, g: 255, b: 255, a: 1})).toBeCloseTo(
+      1,
+      10,
+    );
+  });
+
+  it('weights channels per WCAG (green brightest, blue darkest)', () => {
+    const red = relativeLuminance({r: 255, g: 0, b: 0, a: 1});
+    const green = relativeLuminance({r: 0, g: 255, b: 0, a: 1});
+    const blue = relativeLuminance({r: 0, g: 0, b: 255, a: 1});
+    expect(red).toBeCloseTo(0.2126, 4);
+    expect(green).toBeCloseTo(0.7152, 4);
+    expect(blue).toBeCloseTo(0.0722, 4);
+  });
+});
+
+describe('contrastRatio', () => {
+  it('is 21 for black on white and 1 for identical colors', () => {
+    expect(contrastRatio('#000000', '#FFFFFF')).toBeCloseTo(21, 5);
+    expect(contrastRatio('#3B82F6', '#3B82F6')).toBe(1);
+  });
+
+  it('is symmetric in fg/bg for opaque colors', () => {
+    expect(contrastRatio('#0064E0', '#FCFDFE')).toBeCloseTo(
+      contrastRatio('#FCFDFE', '#0064E0'),
+      10,
+    );
+  });
+
+  it('matches the canonical 4.5:1 boundary gray (#767676 on white)', () => {
+    const ratio = contrastRatio('#767676', '#FFFFFF');
+    expect(ratio).toBeGreaterThanOrEqual(4.5);
+    expect(ratio).toBeLessThan(4.6);
+  });
+
+  it('composites a translucent foreground over the background', () => {
+    // 50% black over white paints as mid-gray, not black.
+    const composited = contrastRatio('rgba(0, 0, 0, 0.5)', '#FFFFFF');
+    expect(composited).toBeLessThan(contrastRatio('#000000', '#FFFFFF'));
+    expect(composited).toBeCloseTo(
+      contrastRatio('rgb(127.5, 127.5, 127.5)', '#FFFFFF'),
+      10,
+    );
+  });
+
+  it('rejects a translucent background', () => {
+    expect(() => contrastRatio('#000000', '#FFFFFF80')).toThrow(
+      /background must be opaque/,
+    );
+  });
+
+  it('rejects unparseable colors', () => {
+    expect(() => contrastRatio('var(--color-accent)', '#FFFFFF')).toThrow(
+      /could not parse foreground/,
+    );
+    expect(() => contrastRatio('#000000', 'oklch(0.5 0.1 200)')).toThrow(
+      /could not parse background/,
+    );
+  });
+});
+
+describe('compositeOver', () => {
+  it('returns the foreground when opaque and the backdrop at alpha 0', () => {
+    const fg = parseColor('#123456');
+    const bg = parseColor('#FFFFFF');
+    if (fg === null || bg === null) {
+      throw new Error('fixture colors must parse');
+    }
+    expect(compositeOver(fg, bg)).toEqual({...fg, a: 1});
+    expect(compositeOver({...fg, a: 0}, bg)).toEqual({...bg, a: 1});
+  });
+
+  it('blends in gamma-encoded sRGB space like CSS', () => {
+    const fg = parseColor('rgba(0, 0, 0, 0.5)');
+    const bg = parseColor('#FFFFFF');
+    if (fg === null || bg === null) {
+      throw new Error('fixture colors must parse');
+    }
+    const out = compositeOver(fg, bg);
+    expect(out.r).toBeCloseTo(127.5, 5);
+    expect(out.g).toBeCloseTo(127.5, 5);
+    expect(out.b).toBeCloseTo(127.5, 5);
+    expect(out.a).toBe(1);
+  });
+});

package/src/theme/contrast.ts

@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contrast.ts
+ * @input CSS color strings (hex, rgb()/rgba()) or parsed RGBA values
+ * @output WCAG 2.x relative luminance and contrast ratios
+ * @position Theme utility; consumed by expandColorScale.ts and theme tests
+ *
+ * Dependency-free WCAG 2.x contrast math. Backs the contrast guarantees
+ * for generated color tokens (WCAG 1.4.3 text contrast >= 4.5:1,
+ * WCAG 1.4.11 non-text contrast >= 3:1).
+ *
+ * Semi-transparent foregrounds are composited over their backdrop in
+ * gamma-encoded sRGB space (matching CSS alpha compositing) before the
+ * ratio is measured — a translucent token has no contrast of its own,
+ * only against what it renders on.
+ */
+
+import type {RGBA} from '../utils/color';
+import {parseColor} from '../utils/color';
+
+/**
+ * WCAG 2.x relative luminance of an sRGB color (alpha ignored).
+ * 0 = black, 1 = white.
+ *
+ * https://www.w3.org/WAI/WCAG22/Techniques/general/G18
+ */
+export function relativeLuminance(color: RGBA): number {
+  const channel = (c: number): number => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return (
+    0.2126 * channel(color.r) +
+    0.7152 * channel(color.g) +
+    0.0722 * channel(color.b)
+  );
+}
+
+/**
+ * Composite a (possibly translucent) foreground over an opaque backdrop
+ * using standard source-over alpha blending in gamma-encoded sRGB space,
+ * matching how CSS paints translucent tokens. Returns an opaque color.
+ */
+export function compositeOver(foreground: RGBA, backdrop: RGBA): RGBA {
+  const a = foreground.a;
+  return {
+    r: foreground.r * a + backdrop.r * (1 - a),
+    g: foreground.g * a + backdrop.g * (1 - a),
+    b: foreground.b * a + backdrop.b * (1 - a),
+    a: 1,
+  };
+}
+
+function resolve(value: string | RGBA, label: string): RGBA {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  const parsed = parseColor(value);
+  if (parsed === null) {
+    throw new TypeError(`contrastRatio: could not parse ${label} "${value}"`);
+  }
+  return parsed;
+}
+
+/**
+ * WCAG 2.x contrast ratio between a foreground and an opaque background.
+ * Returns a value in [1, 21].
+ *
+ * A translucent foreground is composited over the background first.
+ * A translucent background is rejected — composite it over its own
+ * backdrop before calling, since its rendered color is unknowable here.
+ *
+ * @example
+ * ```
+ * contrastRatio('#000000', '#FFFFFF'); // 21
+ * contrastRatio('#0D131A', '#FCFDFE') >= 4.5; // text-on-surface check
+ * ```
+ */
+export function contrastRatio(
+  foreground: string | RGBA,
+  background: string | RGBA,
+): number {
+  const bg = resolve(background, 'background');
+  if (bg.a < 1) {
+    throw new TypeError(
+      'contrastRatio: background must be opaque — composite it over its backdrop first',
+    );
+  }
+  let fg = resolve(foreground, 'foreground');
+  if (fg.a < 1) {
+    fg = compositeOver(fg, bg);
+  }
+  const lumA = relativeLuminance(fg);
+  const lumB = relativeLuminance(bg);
+  const lighter = Math.max(lumA, lumB);
+  const darker = Math.min(lumA, lumB);
+  return (lighter + 0.05) / (darker + 0.05);
+}