@astryxdesign/core 0.4.0 → 0.4.1

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/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';
+}