@astryxdesign/core 0.4.0 → 0.4.1-canary.1ce0b4c

package/src/theme/index.ts

@@ -90,6 +90,7 @@ export {
   spacingDefaults,
   sizeDefaults,
   borderDefaults,
+  focusDefaults,
   radiusDefaults,
   shadowDefaults,
   durationDefaults,
@@ -102,6 +103,7 @@ export {
   spacingVars,
   sizeVars,
   borderVars,
+  focusVars,
   radiusVars,
   shadowVars,
   durationVars,

package/src/theme/themingTargets.test.ts

@@ -26,7 +26,7 @@
 
 import {describe, it, expect} from 'vitest';
 import {readdirSync, readFileSync} from 'node:fs';
-import {join} from 'node:path';
+import {join, relative} from 'node:path';
 import ts from 'typescript';
 import {stableClassName} from '../naming';
 
@@ -45,6 +45,61 @@ interface ThemeTargetSite {
   isOpaque: boolean;
 }
 
+/**
+ * Keys of a spread whose operand is a conditional object literal:
+ * `...(cond && {a})`, `...(cond ? {a} : null)`, `...(cond || {a})`.
+ * Returns null when the operand is anything else (a bag like `...rest`, or an
+ * object with a computed key), which the caller treats as opaque.
+ */
+function conditionalSpreadKeys(expression: ts.Expression): string[] | null {
+  const unwrap = (node: ts.Expression): ts.Expression =>
+    ts.isParenthesizedExpression(node) ? unwrap(node.expression) : node;
+
+  const expr = unwrap(expression);
+  const branches: ts.Expression[] = [];
+  if (
+    ts.isBinaryExpression(expr) &&
+    (expr.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ||
+      expr.operatorToken.kind === ts.SyntaxKind.BarBarToken)
+  ) {
+    branches.push(expr.right);
+  } else if (ts.isConditionalExpression(expr)) {
+    branches.push(expr.whenTrue, expr.whenFalse);
+  } else if (ts.isObjectLiteralExpression(expr)) {
+    branches.push(expr);
+  } else {
+    return null;
+  }
+
+  const keys: string[] = [];
+  for (const branch of branches) {
+    const object = unwrap(branch);
+    // A falsy filler arm (`null`, `undefined`) contributes no keys; anything
+    // else that is not an object literal hides its keys, so give up.
+    if (
+      object.kind === ts.SyntaxKind.NullKeyword ||
+      (ts.isIdentifier(object) && object.text === 'undefined')
+    ) {
+      continue;
+    }
+    if (!ts.isObjectLiteralExpression(object)) {
+      return null;
+    }
+    for (const prop of object.properties) {
+      const name = prop.name;
+      if (
+        name != null &&
+        (ts.isIdentifier(name) || ts.isStringLiteralLike(name))
+      ) {
+        keys.push(name.text);
+      } else {
+        return null;
+      }
+    }
+  }
+  return keys;
+}
+
 /**
  * Extract every `themeProps('name', {...})` call from a source file.
  *
@@ -88,8 +143,16 @@ function extractThemeTargets(
           if (ts.isObjectLiteralExpression(propsArg)) {
             for (const prop of propsArg.properties) {
               if (ts.isSpreadAssignment(prop)) {
-                // {...rest} — keys unknown at parse time.
-                site.isOpaque = true;
+                // A conditional spread of an object literal — `...(type &&
+                // {type})` — has statically known keys. Treating it as opaque
+                // is how `astryx-heading`'s `type` stayed undocumented: the
+                // same drift this file exists to catch (#3652, #3680).
+                const spreadKeys = conditionalSpreadKeys(prop.expression);
+                if (spreadKeys == null) {
+                  site.isOpaque = true;
+                } else {
+                  site.propKeys.push(...spreadKeys);
+                }
                 continue;
               }
               const name = prop.name;
@@ -194,12 +257,35 @@ describe('extractThemeTargets', () => {
     ]);
   });
 
+  it('reads the keys of a conditional spread', () => {
+    // Heading's real call site: `{level, color, ...(type && {type})}`.
+    const [site] = extractThemeTargets(
+      `themeProps('heading', {level, color, ...(type && {type})})`,
+    );
+    expect(site.propKeys).toEqual(['level', 'color', 'type']);
+    expect(site.isOpaque).toBe(false);
+  });
+
+  it('reads both arms of a ternary spread', () => {
+    const [site] = extractThemeTargets(
+      `themeProps('card', {...(isOpen ? {expanded} : {collapsed})})`,
+    );
+    expect(site.propKeys).toEqual(['expanded', 'collapsed']);
+    expect(site.isOpaque).toBe(false);
+  });
+
   it('marks a spread props bag opaque rather than guessing its keys', () => {
     const [site] = extractThemeTargets(`themeProps('card', {...rest})`);
     expect(site.isOpaque).toBe(true);
     expect(site.propKeys).toEqual([]);
   });
 
+  it('marks a conditional spread of a non-literal opaque', () => {
+    const [site] = extractThemeTargets(`themeProps('card', {...(on && rest)})`);
+    expect(site.isOpaque).toBe(true);
+    expect(site.propKeys).toEqual([]);
+  });
+
   it('marks a non-literal props bag opaque', () => {
     const [site] = extractThemeTargets(`themeProps('card', visualProps)`);
     expect(site.isOpaque).toBe(true);
@@ -231,7 +317,37 @@ interface ComponentInfo {
   dir: string;
   sites: ThemeTargetSite[];
   /** The doc blocks that carry theming.targets, by the key they live under. */
-  docBlocks: {key: 'docs' | 'docsZh'; targets: DocTarget[]}[];
+  docBlocks: {key: 'docs' | 'docsZh'; file: string; targets: DocTarget[]}[];
+}
+
+/**
+ * Every `*.doc.mjs` under src that declares a theming target for one of
+ * `classNames`. Lets a component be checked against the doc that documents it,
+ * wherever that file lives.
+ *
+ * Reads the file as text rather than requiring it: this runs for directories
+ * that have no doc of their own, so most candidates are misses.
+ */
+function docFilesDocumenting(classNames: Set<string>): string[] {
+  const matches: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, {withFileTypes: true})) {
+      const p = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(p);
+      } else if (entry.name.endsWith('.doc.mjs')) {
+        const source = readFileSync(p, 'utf-8');
+        for (const className of classNames) {
+          if (source.includes(`'${className}'`)) {
+            matches.push(p);
+            break;
+          }
+        }
+      }
+    }
+  };
+  walk(SRC_DIR);
+  return matches;
 }
 
 function discoverComponents(): ComponentInfo[] {
@@ -262,27 +378,37 @@ function discoverComponents(): ComponentInfo[] {
       continue;
     }
 
-    // Match the on-disk listing rather than existsSync: on case-insensitive
-    // filesystems existsSync would match a differently-cased doc file that CI
-    // never checks. (Same guard as derivedVarRegistry.test.ts.)
-    if (!dirEntries.includes(`${dir}.doc.mjs`)) {
-      continue;
-    }
-
-    let mod: ComponentDocModule;
-    try {
-      mod = require(join(dirPath, `${dir}.doc.mjs`)) as ComponentDocModule;
-    } catch {
+    // A component's doc file usually sits beside its source, but not always:
+    // `Heading/Heading.tsx` is documented by `Text/Text.doc.mjs`. Requiring a
+    // same-directory doc silently exempted every such component — Heading
+    // among them. Fall back to whichever doc file documents the classes this
+    // directory renders.
+    //
+    // Both paths match the on-disk listing rather than existsSync: on
+    // case-insensitive filesystems existsSync would match a differently-cased
+    // doc file that CI never checks. (Same guard as derivedVarRegistry.test.ts.)
+    const docFiles = dirEntries.includes(`${dir}.doc.mjs`)
+      ? [join(dirPath, `${dir}.doc.mjs`)]
+      : docFilesDocumenting(new Set(sites.map(s => s.className)));
+    if (docFiles.length === 0) {
       continue;
     }
 
     const docBlocks: ComponentInfo['docBlocks'] = [];
-    for (const key of ['docs', 'docsZh'] as const) {
-      const targets = mod[key]?.theming?.targets;
-      // Only blocks that already document a theming surface are held to it —
-      // a doc with no theming block at all is a separate (documentation) gap.
-      if (targets != null) {
-        docBlocks.push({key, targets});
+    for (const docFile of docFiles) {
+      let mod: ComponentDocModule;
+      try {
+        mod = require(docFile) as ComponentDocModule;
+      } catch {
+        continue;
+      }
+      for (const key of ['docs', 'docsZh'] as const) {
+        const targets = mod[key]?.theming?.targets;
+        // Only blocks that already document a theming surface are held to it —
+        // a doc with no theming block at all is a separate (documentation) gap.
+        if (targets != null) {
+          docBlocks.push({key, file: relative(SRC_DIR, docFile), targets});
+        }
       }
     }
     if (docBlocks.length === 0) {
@@ -309,22 +435,22 @@ describe('theming.targets matches the themeProps() call sites', () => {
   for (const {dir, sites, docBlocks} of components) {
     const renderedClasses = [...new Set(sites.map(s => s.className))].sort();
 
-    for (const {key, targets} of docBlocks) {
+    for (const {key, file, targets} of docBlocks) {
       const documented = new Set(targets.map(t => t.className));
 
-      it(`${dir} (${key}): every rendered class is documented`, () => {
+      it(`${dir} (${file} ${key}): every rendered class is documented`, () => {
         const undocumented = renderedClasses.filter(c => !documented.has(c));
         expect(
           undocumented,
           `${dir} renders ${undocumented.length} astryx-* class(es) that ` +
-            `${dir}.doc.mjs ${key}.theming.targets does not document: ` +
+            `${file} ${key}.theming.targets does not document: ` +
             `${undocumented.join(', ')}. An undocumented class is an ` +
             `unthemeable element — theme authors and codegen read targets[] ` +
             `to learn which selectors exist. Add {className: '...'} entries.`,
         ).toEqual([]);
       });
 
-      it(`${dir} (${key}): every visual prop passed to themeProps is documented`, () => {
+      it(`${dir} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {
         const missing: string[] = [];
         for (const site of sites) {
           const target = targets.find(t => t.className === site.className);
@@ -343,7 +469,7 @@ describe('theming.targets matches the themeProps() call sites', () => {
         }
         expect(
           [...new Set(missing)],
-          `${dir} passes prop keys to themeProps() that ${dir}.doc.mjs ` +
+          `${dir} passes prop keys to themeProps() that ${file} ` +
             `${key}.theming.targets does not list under visualProps/states. ` +
             `Each one is a [data-*] selector consumers cannot discover.`,
         ).toEqual([]);

package/src/theme/tokens.stylex.ts

@@ -193,6 +193,24 @@ export const borderVars = stylex.defineVars(borderDefaults);
 
 export type BorderVarName = keyof typeof borderDefaults;
 
+// =============================================================================
+// Focus Tokens
+// =============================================================================
+// The keyboard focus ring, as one definition for the whole system. Values come
+// from Design Conventions §User Interaction States: 2px --color-accent at 3px
+// offset. Components read these through utils/focusOutline.stylex.ts; the
+// `:focus-visible` condition stays in core, so a theme can restyle the ring
+// but cannot show it to pointer users.
+
+export const focusDefaults = {
+  '--focus-outline-width': '2px',
+  '--focus-outline-style': 'solid',
+  '--focus-outline-color': 'var(--color-accent)',
+  '--focus-outline-offset': '3px',
+} as const;
+
+export const focusVars = stylex.defineVars(focusDefaults);
+
 // =============================================================================
 // Radius Tokens
 // =============================================================================

package/src/theme/tokens.test.ts

@@ -280,3 +280,40 @@ describe('resolveThemeTokens — generated themes end to end', () => {
     expect(light['--color-icon-accent']).toBe(light['--color-accent']);
   });
 });
+
+describe('focus outline tokens', () => {
+  it('default to the accent ring from Design Conventions', () => {
+    const tokens = resolveThemeTokens(null, {mode: 'light'});
+
+    expect(tokens['--focus-outline-width']).toBe('2px');
+    expect(tokens['--focus-outline-style']).toBe('solid');
+    expect(tokens['--focus-outline-offset']).toBe('3px');
+    // Tracks the theme's accent unless a theme says otherwise.
+    expect(tokens['--focus-outline-color']).toBe(tokens['--color-accent']);
+  });
+
+  it('follows a theme accent without an explicit focus override', () => {
+    const theme = defineTheme({name: 'brand', color: {accent: '#AA0000'}});
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+
+    expect(tokens['--focus-outline-color']).toBe(tokens['--color-accent']);
+    expect(tokens['--focus-outline-color']).not.toContain('var(');
+  });
+
+  it('takes an explicit ring over the accent', () => {
+    const theme = defineTheme({
+      name: 'brand',
+      color: {accent: '#AA0000'},
+      tokens: {
+        '--focus-outline-color': '#00FF00',
+        '--focus-outline-width': '4px',
+        '--focus-outline-offset': '0px',
+      },
+    });
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+
+    expect(tokens['--focus-outline-color']).toBe('#00FF00');
+    expect(tokens['--focus-outline-width']).toBe('4px');
+    expect(tokens['--focus-outline-offset']).toBe('0px');
+  });
+});

package/src/utils/focusOutline.stylex.ts

@@ -7,28 +7,42 @@
  * @position Internal utility for consistent keyboard focus outlines across core components
  *
  * Centralizes the standard Astryx focus outline, shown only for keyboard focus.
- * Every focusable surface drew the same 2px accent ring at 2px offset already;
- * writing it per component meant five identical definitions to keep in step.
+ * Every focusable surface drew the same 2px accent ring already; writing it per
+ * component meant dozens of identical definitions to keep in step, and they did
+ * not stay in step — offsets drifted and one ring was a border-width thick.
  *
- * These are utility styles, deliberately NOT a theme target. A shared
- * `astryx-focus-outline` class was tried and pulled: a theme can only override
- * the ring unconditionally through it (`generateThemeRules` mangles
- * `:focus-visible` into `.focus-visible` and truncates `:has(:focus-visible)`
- * at the paren), so the one thing such a target exists for — restyling a
- * STATE — is exactly what it cannot express. Making focus outlines themeable
- * is worth doing on top of this consolidation, once that is fixed.
+ * Every ring in core and lab is drawn from here, with one exception recorded in
+ * Switch: its condition is a component-scoped ancestor marker, which cannot be
+ * shared without leaking focus state between components. A component may still
+ * override the OFFSET (a ring that must sit inset, or clear of a field border);
+ * width, style and color are not restated anywhere.
+ *
+ * Every value comes from the `--focus-outline-*` tokens, which is how a theme
+ * restyles the ring: one override reaches every component at once. The
+ * `:focus-visible` condition is not themeable and stays here, so a theme can
+ * change what the ring looks like but cannot show it to pointer users.
  */
 
 import * as stylex from '@stylexjs/stylex';
-import {colorVars} from '../theme/tokens.stylex';
+import {focusVars} from '../theme/tokens.stylex';
+
+const FOCUS_OUTLINE_WIDTH = focusVars['--focus-outline-width'];
+const FOCUS_OUTLINE_STYLE = focusVars['--focus-outline-style'];
+const FOCUS_OUTLINE_COLOR = focusVars['--focus-outline-color'];
+
+const FOCUS_OUTLINE_OFFSET = focusVars['--focus-outline-offset'];
 
-const FOCUS_OUTLINE_WIDTH = '2px';
-// 3px, per Design Conventions §User Interaction States: "2px --color-accent
-// outline at 3px offset". Most components had drifted to 2px; Button, Calendar,
-// Dialog and Pagination were the ones matching the spec, so the consolidation
-// takes their value rather than the majority's.
-const FOCUS_OUTLINE_OFFSET = '3px';
-const FOCUS_OUTLINE_COLOR = colorVars['--color-accent'];
+/**
+ * The ring as a single `outline` value, for reading it at runtime — an
+ * assertion, or an element styled imperatively.
+ *
+ * NOT usable inside another file's `stylex.create`: StyleX resolves imported
+ * `defineVars` and nothing else, so a component whose condition
+ * {@link focusOutlineStyles} cannot express (Switch, whose ring keys off a
+ * component-scoped ancestor marker) has to compose the `focusVars` tokens
+ * itself.
+ */
+export const FOCUS_OUTLINE = `${FOCUS_OUTLINE_WIDTH} ${FOCUS_OUTLINE_STYLE} ${FOCUS_OUTLINE_COLOR}`;
 
 /**
  * Written as longhands rather than the `outline` shorthand.
@@ -40,7 +54,7 @@ const FOCUS_OUTLINE_COLOR = colorVars['--color-accent'];
  */
 const focusOutlineLonghands = {
   outlineWidth: FOCUS_OUTLINE_WIDTH,
-  outlineStyle: 'solid',
+  outlineStyle: FOCUS_OUTLINE_STYLE,
   outlineColor: FOCUS_OUTLINE_COLOR,
 } as const;
 
@@ -53,8 +67,8 @@ const focusOutlineLonghands = {
  * Longhands, not the `outline` shorthand, for the same reason the styles are:
  * a shorthand resets every longhand it covers, so a caller could not re-color
  * the ring without restating its width and style. Split, each part is
- * independently overridable — and `--color-accent` stays a var, so a theme's
- * accent still flows through.
+ * independently overridable — and every part stays a var, so a theme's
+ * `--focus-outline-*` overrides still flow through.
  *
  * Keys are camelCase to match `HTMLElement.style`, so this spreads straight
  * onto an element:
@@ -66,7 +80,7 @@ const focusOutlineLonghands = {
  */
 export const FOCUS_OUTLINE_PARTS = {
   outlineWidth: FOCUS_OUTLINE_WIDTH,
-  outlineStyle: 'solid',
+  outlineStyle: FOCUS_OUTLINE_STYLE,
   outlineColor: FOCUS_OUTLINE_COLOR,
   outlineOffset: FOCUS_OUTLINE_OFFSET,
 } as const;
@@ -113,7 +127,7 @@ export const focusOutlineStyles = stylex.create({
   publishFocusVisibleVars: {
     '--_focus-outline': {
       default: 'none',
-      ':focus-visible': `${FOCUS_OUTLINE_WIDTH} solid ${FOCUS_OUTLINE_COLOR}`,
+      ':focus-visible': FOCUS_OUTLINE,
     },
     '--_focus-outline-offset': {
       default: '0',
@@ -123,7 +137,7 @@ export const focusOutlineStyles = stylex.create({
   focusWithinOrPublished: {
     outline: {
       default: 'var(--_focus-outline, none)',
-      ':has(:focus-visible)': `${FOCUS_OUTLINE_WIDTH} solid ${FOCUS_OUTLINE_COLOR}`,
+      ':has(:focus-visible)': FOCUS_OUTLINE,
     },
     outlineOffset: {
       default: 'var(--_focus-outline-offset, 0)',

package/src/utils/index.ts

@@ -101,3 +101,7 @@ export type {RGBA} from './color';
 export {devWarn, devError, warnOnce, formatDevMessage} from './devWarning';
 
 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';

package/src/utils/interactionModality.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file interactionModality.ts
+ * @input Global pointerdown/keydown events
+ * @output `getInteractionModality()` — how the user last interacted
+ * @position Internal utility; used where `:focus-visible` alone is too broad
+ *
+ * `:focus-visible` is the right selector for a focus ring and should stay the
+ * condition that draws one. It is not, on its own, "focused by keyboard":
+ * per CSS Selectors 4 a pointer-focused element that supports text entry
+ * matches it too, deliberately, so that a clicked text field still shows where
+ * typing will go. Measured in Chromium — a bare `<input>` clicked with a mouse
+ * matches `:focus-visible`.
+ *
+ * A component that wants a ring for keyboard focus ONLY therefore needs one bit
+ * `:focus-visible` cannot give it: which device moved focus. This records that,
+ * to be used as a gate ALONGSIDE `:focus-visible`, never as a replacement for
+ * it — the browser's heuristic still decides everything else, including
+ * `focus({focusVisible: true})`.
+ *
+ * Listeners are registered once for the document, in the capture phase so they
+ * run before the focus they explain, and are never removed: two passive
+ * listeners for the whole app, versus a pair per mounted input.
+ */
+
+export type InteractionModality = 'keyboard' | 'pointer';
+
+// Default to keyboard: with no interaction yet, focus arrived programmatically
+// or from the browser restoring it, and showing a ring is the safe error.
+let modality: InteractionModality = 'keyboard';
+let isListening = false;
+
+function onPointerDown(): void {
+  modality = 'pointer';
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  // Modifier-only presses are not navigation — holding Shift before a click
+  // must not turn that click into "keyboard".
+  if (event.metaKey || event.altKey || event.ctrlKey) {
+    return;
+  }
+  modality = 'keyboard';
+}
+
+/**
+ * Start tracking, once per document. Safe to call repeatedly and on the server
+ * (where it does nothing).
+ */
+export function trackInteractionModality(): void {
+  if (isListening || typeof document === 'undefined') {
+    return;
+  }
+  isListening = true;
+  document.addEventListener('pointerdown', onPointerDown, {
+    capture: true,
+    passive: true,
+  });
+  document.addEventListener('keydown', onKeyDown, {
+    capture: true,
+    passive: true,
+  });
+}
+
+/** How the user last interacted with the page. */
+export function getInteractionModality(): InteractionModality {
+  return modality;
+}
+
+/** Test-only: restore the initial state between cases. */
+export function __resetInteractionModalityForTest(): void {
+  modality = 'keyboard';
+}