@astryxdesign/core 0.3.0 → 0.4.0-canary.3112e99

package/src/utils/focusOutline.stylex.ts

@@ -0,0 +1,177 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file focusOutline.stylex.ts
+ * @input Uses StyleX and theme color tokens
+ * @output Exports shared focus-outline prop builders
+ * @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 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.
+ *
+ * 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 {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'];
+
+/**
+ * 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.
+ *
+ * A shorthand resets every longhand it covers, so `outline: 2px solid accent`
+ * would clobber a later `outlineColor` no matter the order — which is how
+ * destructive buttons silently lost their red ring. With longhands, a variant
+ * can re-color the ring and inherit width, style and offset.
+ */
+const focusOutlineLonghands = {
+  outlineWidth: FOCUS_OUTLINE_WIDTH,
+  outlineStyle: FOCUS_OUTLINE_STYLE,
+  outlineColor: FOCUS_OUTLINE_COLOR,
+} as const;
+
+/**
+ * The standard focus ring as plain CSS values, for the one case that has to
+ * apply it imperatively: a control whose focusable input is visually hidden and
+ * whose ring must land on a *themeable indicator* beside it (see
+ * `useIndicatorFocusRing`). Everything else should use the styles above.
+ *
+ * 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 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:
+ *
+ * ```ts
+ * Object.assign(el.style, FOCUS_OUTLINE_PARTS);        // draw
+ * Object.assign(el.style, FOCUS_OUTLINE_PARTS_NONE);   // clear
+ * ```
+ */
+export const FOCUS_OUTLINE_PARTS = {
+  outlineWidth: FOCUS_OUTLINE_WIDTH,
+  outlineStyle: FOCUS_OUTLINE_STYLE,
+  outlineColor: FOCUS_OUTLINE_COLOR,
+  outlineOffset: FOCUS_OUTLINE_OFFSET,
+} as const;
+
+/** Clears {@link FOCUS_OUTLINE_PARTS}, one key per part so nothing lingers. */
+export const FOCUS_OUTLINE_PARTS_NONE = {
+  outlineWidth: '',
+  outlineStyle: '',
+  outlineColor: '',
+  outlineOffset: '',
+} as const;
+
+export const focusOutlineStyles = stylex.create({
+  focusVisible: {
+    outlineWidth: {
+      default: '0',
+      ':focus-visible': focusOutlineLonghands.outlineWidth,
+    },
+    outlineStyle: {
+      default: 'none',
+      ':focus-visible': focusOutlineLonghands.outlineStyle,
+    },
+    outlineColor: {
+      default: null,
+      ':focus-visible': focusOutlineLonghands.outlineColor,
+    },
+    outlineOffset: {default: '0', ':focus-visible': FOCUS_OUTLINE_OFFSET},
+  },
+  focusWithin: {
+    outlineWidth: {
+      default: '0',
+      ':has(:focus-visible)': focusOutlineLonghands.outlineWidth,
+    },
+    outlineStyle: {
+      default: 'none',
+      ':has(:focus-visible)': focusOutlineLonghands.outlineStyle,
+    },
+    outlineColor: {
+      default: null,
+      ':has(:focus-visible)': focusOutlineLonghands.outlineColor,
+    },
+    outlineOffset: {default: '0', ':has(:focus-visible)': FOCUS_OUTLINE_OFFSET},
+  },
+  publishFocusVisibleVars: {
+    '--_focus-outline': {
+      default: 'none',
+      ':focus-visible': FOCUS_OUTLINE,
+    },
+    '--_focus-outline-offset': {
+      default: '0',
+      ':focus-visible': FOCUS_OUTLINE_OFFSET,
+    },
+  },
+  focusWithinOrPublished: {
+    outline: {
+      default: 'var(--_focus-outline, none)',
+      ':has(:focus-visible)': FOCUS_OUTLINE,
+    },
+    outlineOffset: {
+      default: 'var(--_focus-outline-offset, 0)',
+      ':has(:focus-visible)': FOCUS_OUTLINE_OFFSET,
+    },
+  },
+});
+
+// StyleX does not expose a stable public input type for stylex.props();
+// keep this helper permissive so it mirrors stylex.props() itself.
+type StyleXPropsArg = unknown;
+
+function makeFocusOutlineProps(style: StyleXPropsArg) {
+  return (...styles: StyleXPropsArg[]) =>
+    // Caller styles LAST, so a component can deliberately re-color its ring —
+    // destructive buttons ring in error red, not accent. StyleX is last-wins,
+    // and reversing this to protect the ring silently ate that override.
+    //
+    // The hazard in this direction is the opposite one: a caller whose base
+    // style carries `outline: 'none'` wipes the ring out entirely (TreeList
+    // did, and shipped a focusable row with no visible focus). Two things
+    // guard it — this file states the rule, and the ring is written as
+    // LONGHANDS, so an override has to name `outlineStyle`/`outlineWidth`
+    // explicitly rather than erasing them through the `outline` shorthand.
+    stylex.props(style as never, ...(styles as never[]));
+}
+
+export const focusOutlineProps = {
+  focusVisible: makeFocusOutlineProps(focusOutlineStyles.focusVisible),
+  focusWithin: makeFocusOutlineProps(focusOutlineStyles.focusWithin),
+  publishFocusVisibleVars: makeFocusOutlineProps(
+    focusOutlineStyles.publishFocusVisibleVars,
+  ),
+  focusWithinOrPublished: makeFocusOutlineProps(
+    focusOutlineStyles.focusWithinOrPublished,
+  ),
+} as const;

package/src/utils/focusReturn.test.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, afterEach} from 'vitest';
+import {isFocusDetached} from './focusReturn';
+
+describe('isFocusDetached', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  it('is true when focus rests on the body (Escape / empty-space dismiss)', () => {
+    // Nothing focused → activeElement is <body>.
+    (document.activeElement as HTMLElement | null)?.blur();
+    expect(isFocusDetached()).toBe(true);
+  });
+
+  it('is false when a real element holds focus (the user moved focus there)', () => {
+    const input = document.createElement('input');
+    document.body.appendChild(input);
+    input.focus();
+    expect(document.activeElement).toBe(input);
+    expect(isFocusDetached()).toBe(false);
+  });
+
+  it('treats the documentElement as detached', () => {
+    const doc = {
+      activeElement: document.documentElement,
+      body: document.body,
+      documentElement: document.documentElement,
+    } as unknown as Document;
+    expect(isFocusDetached(doc)).toBe(true);
+  });
+
+  it('treats a null activeElement as detached', () => {
+    const doc = {
+      activeElement: null,
+      body: document.body,
+      documentElement: document.documentElement,
+    } as unknown as Document;
+    expect(isFocusDetached(doc)).toBe(true);
+  });
+});

package/src/utils/focusReturn.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file focusReturn.ts
+ * @input The document's current active element.
+ * @output Whether focus is currently "detached" — on nothing in particular.
+ * @position Utility; used by overlay triggers (e.g. DateInput, DateTimeInput)
+ *   that return focus to their control when the overlay closes, but only when
+ *   the dismiss did not already move focus somewhere the user chose.
+ */
+
+/**
+ * True when focus rests on nothing in particular — no active element, or the
+ * document body / root element.
+ *
+ * An overlay (popover, calendar, dropdown) that restores focus to its trigger
+ * on close should do so ONLY when this is true. A native `popover="auto"`
+ * light-dismiss fires its close synchronously with the pointer event that
+ * moved focus, so by the time the close handler runs, focus has already
+ * landed on whatever the user clicked — another field, a button, anywhere.
+ * Restoring focus unconditionally would yank it back and fight that click.
+ * The one case the browser leaves unresolved is Escape or a click on
+ * non-focusable empty space, which drops focus to the body; that is exactly
+ * when the trigger should reclaim it.
+ */
+export function isFocusDetached(doc: Document = document): boolean {
+  const active = doc.activeElement;
+  return (
+    active == null || active === doc.body || active === doc.documentElement
+  );
+}

package/src/utils/index.ts

@@ -72,6 +72,7 @@ export {getKey, type Key, type KeyFallback} from './getKey';
 
 export {mergeProps} from './mergeProps';
 export {mergeRefs} from './mergeRefs';
+export {isFocusDetached} from './focusReturn';
 export {composeEventHandlers} from './composeEventHandlers';
 export {themeProps, themeDataAttributes} from './themeProps';
 export type {
@@ -100,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/mergeRefs.test.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {createElement, createRef} from 'react';
+import {render} from '@testing-library/react';
+import {describe, expect, it, vi} from 'vitest';
+import {mergeRefs} from './mergeRefs';
+
+describe('mergeRefs', () => {
+  it('forwards the value to callback and object refs', () => {
+    const callbackRef = vi.fn();
+    const objectRef = createRef<HTMLDivElement>();
+
+    const {container} = render(
+      createElement('div', {ref: mergeRefs(callbackRef, objectRef)}),
+    );
+
+    expect(callbackRef).toHaveBeenCalledWith(container.firstElementChild);
+    expect(objectRef.current).toBe(container.firstElementChild);
+  });
+
+  it('runs callback cleanup and clears object refs', () => {
+    const cleanup = vi.fn();
+    const callbackRef = vi.fn(() => cleanup);
+    const objectRef = createRef<HTMLDivElement>();
+
+    const {unmount} = render(
+      createElement('div', {ref: mergeRefs(callbackRef, objectRef)}),
+    );
+    unmount();
+
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(callbackRef).toHaveBeenCalledTimes(1);
+    expect(objectRef.current).toBeNull();
+  });
+
+  it('passes null to callback refs that do not return cleanup functions', () => {
+    const callbackRef = vi.fn();
+
+    const {container, unmount} = render(
+      createElement('div', {ref: mergeRefs(callbackRef)}),
+    );
+    const element = container.firstElementChild;
+    unmount();
+
+    expect(callbackRef).toHaveBeenNthCalledWith(1, element);
+    expect(callbackRef).toHaveBeenNthCalledWith(2, null);
+  });
+});

package/src/utils/mergeRefs.ts

@@ -16,16 +16,22 @@ export function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): RefCallback<T> {
     for (const ref of refs) {
       if (typeof ref === 'function') {
         const cleanup = ref(value);
-        if (typeof cleanup === 'function') {
-          cleanups.push(cleanup);
-        }
+        cleanups.push(
+          typeof cleanup === 'function' ? cleanup : () => ref(null),
+        );
       } else if (ref != null) {
-        (ref as {current: T | null}).current = value;
+        const mutableRef = ref as {current: T | null};
+        mutableRef.current = value;
+        cleanups.push(() => {
+          mutableRef.current = null;
+        });
       }
     }
-    if (cleanups.length > 0) {
+    if (value != null && cleanups.length > 0) {
       return () => {
-        for (const cleanup of cleanups) {cleanup();}
+        for (const cleanup of cleanups) {
+          cleanup();
+        }
       };
     }
   };

package/src/utils/rtlStyles.ts

@@ -4,8 +4,8 @@
  * @file rtlStyles.ts
  * @input None
  * @output Shared StyleX style that horizontally mirrors an element under RTL
- * @position Core utility; applied to directional-icon wrappers in Calendar,
- *   Lightbox, and the Table expand/disclosure plugins
+ * @position Core utility; applied to directional icons in Calendar, Lightbox,
+ *   Pagination, Carousel and the Table expand/disclosure plugins
  *
  * `mirror` flips its element on the horizontal axis only when an ancestor
  * carries `dir="rtl"`. Using `scaleX(-1)` (not `scale(-1, -1)`) keeps the

package/src/utils/themeProps.ts

@@ -73,9 +73,7 @@ function buildClassName(component: string, props?: ClassProps): string {
  * literal prop values, including numeric values (`level: 1` → `data-level="1"`).
  * Nullish values are omitted.
  */
-export function themeDataAttributes(
-  props?: ClassProps,
-): ThemeDataAttributes {
+export function themeDataAttributes(props?: ClassProps): ThemeDataAttributes {
   const attrs: ThemeDataAttributes = {};
 
   if (props) {
@@ -102,12 +100,36 @@ export function themeDataAttributes(
  * // → { className: 'astryx-button primary sm', data-variant: 'primary', data-size: 'sm' }
  * ```
  */
+/**
+ * Options for {@link themeProps}.
+ */
+export type ThemePropsOptions = {
+  /**
+   * Stable class names to emit ALONGSIDE the component's own, for targets that
+   * have been renamed.
+   *
+   * A theme target is public API: renaming one silently breaks every theme
+   * that styles it. Emitting the old name beside the new one keeps those
+   * themes working through a deprecation window, at the cost of one extra
+   * class on the element until the old name is dropped in a major.
+   *
+   * Pass plain string literals — the theming guards scan for them statically.
+   * Document the old name with `deprecated` in the component's
+   * `theming.targets` so the docsite says which to use.
+   */
+  legacyNames?: ReadonlyArray<string>;
+};
+
 export function themeProps(
   component: string,
   props?: ClassProps,
+  options?: ThemePropsOptions,
 ): ThemeProps {
+  const className = buildClassName(component, props);
+  const legacy = options?.legacyNames?.map(name => stableClassName(name)) ?? [];
+
   return {
-    className: buildClassName(component, props),
+    className: legacy.length > 0 ? [className, ...legacy].join(' ') : className,
     ...themeDataAttributes(props),
   };
 }

package/dist/CheckboxInput/checkbox.markers.stylex.d.ts

@@ -1,9 +0,0 @@
-import * as stylex from '@stylexjs/stylex';
-/**
- * Scoped marker for CheckboxInput ancestor selectors.
- * Prevents focus-within and hover styles from leaking when
- * checkboxes are placed inside Popovers or other containers
- * that also have focus-within state.
- */
-export declare const checkboxScope: ReturnType<typeof stylex.defineMarker>;
-//# sourceMappingURL=checkbox.markers.stylex.d.ts.map

package/dist/CheckboxInput/checkbox.markers.stylex.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"checkbox.markers.stylex.d.ts","sourceRoot":"","sources":["../../src/CheckboxInput/checkbox.markers.stylex.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,YAAY,CAC1C,CAAC"}

package/dist/CheckboxInput/checkbox.markers.stylex.js

@@ -1,14 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import * as stylex from '@stylexjs/stylex';
-
-/**
- * Scoped marker for CheckboxInput ancestor selectors.
- * Prevents focus-within and hover styles from leaking when
- * checkboxes are placed inside Popovers or other containers
- * that also have focus-within state.
- */
-export const checkboxScope = {
-  x1tspnpo: "x1tspnpo",
-  $$css: true
-};

package/dist/RadioList/radio.markers.stylex.d.ts

@@ -1,7 +0,0 @@
-import * as stylex from '@stylexjs/stylex';
-/**
- * Scoped marker for RadioListItem ancestor selectors.
- * Prevents hover styles from leaking from parent containers.
- */
-export declare const radioScope: ReturnType<typeof stylex.defineMarker>;
-//# sourceMappingURL=radio.markers.stylex.d.ts.map

package/dist/RadioList/radio.markers.stylex.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"radio.markers.stylex.d.ts","sourceRoot":"","sources":["../../src/RadioList/radio.markers.stylex.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,YAAY,CACvC,CAAC"}

package/dist/RadioList/radio.markers.stylex.js

@@ -1,12 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import * as stylex from '@stylexjs/stylex';
-
-/**
- * Scoped marker for RadioListItem ancestor selectors.
- * Prevents hover styles from leaking from parent containers.
- */
-export const radioScope = {
-  xklqth5: "xklqth5",
-  $$css: true
-};