@astryxdesign/core 0.3.0 → 0.4.0

package/src/theme/expandColorScale.ts

@@ -71,7 +71,9 @@ export interface ColorScaleConfig {
   neutralStyle?: 'warm' | 'cool' | 'neutral';
 
   /**
-   * Contrast level. Affects tone assignments for text and UI elements.
+   * Contrast level. `'high'` pulls text, icons, and borders toward stronger
+   * tones (and thickens the subtle border's alpha) so structural and textual
+   * boundaries stay perceivable.
    * @default 'standard'
    */
   contrast?: 'standard' | 'high';
@@ -190,17 +192,25 @@ export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
   const textSecondaryLightTone = isHigh ? 20 : 30;
   const textSecondaryDarkTone = isHigh ? 80 : 70;
 
+  // Borders track contrast the same way text does: high contrast pulls the
+  // emphasized border tone toward mid-scale (stronger against both the near-
+  // white light surface and the near-black dark surface) and thickens the
+  // otherwise-decorative subtle hairline by doubling its alpha, so structural
+  // boundaries stay perceivable for users who opt into high contrast.
+  const borderSubtleAlpha = isHigh ? 0.2 : 0.1;
+
   // Emphasized borders outline form controls (CheckboxInput, Selector), so
   // they are non-text UI boundaries under WCAG 1.4.11 and must reach 3:1
-  // against the surface they sit on. The preferred tones (70 light /
-  // 30 dark) land around 2.2:1 / 1.8:1, so bump the tone toward the
-  // opposing extreme until the ratio passes. Text tones need no such loop:
-  // their spacing guarantees >= 4.5:1 for any hue/chroma (see file header).
+  // against the surface they sit on. High contrast starts at a more
+  // aggressive tone (50 vs 70/30), guaranteeing a stronger result; standard
+  // contrast starts at 70/30 and walks toward mid-scale only as far as needed.
+  const borderEmphasizedStartLight = isHigh ? 50 : 70;
+  const borderEmphasizedStartDark = isHigh ? 50 : 30;
   const borderEmphasized = ld(
     ensureContrastTone(
       seedHue,
       neutralVariantChroma,
-      70,
+      borderEmphasizedStartLight,
       -1,
       N[99],
       NON_TEXT_MIN_CONTRAST,
@@ -208,7 +218,7 @@ export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
     ensureContrastTone(
       seedHue,
       neutralVariantChroma,
-      30,
+      borderEmphasizedStartDark,
       1,
       N[10],
       NON_TEXT_MIN_CONTRAST,
@@ -276,8 +286,13 @@ export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
     '--color-background-inverted': ld(N[10], N[99]),
 
     // Border
-    // Decorative hairline (~1.1:1 by design) — not a WCAG 1.4.11 boundary.
-    '--color-border': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[95], 0.1)),
+    // Border
+    // Decorative hairline — not a WCAG 1.4.11 boundary. High contrast
+    // doubles the alpha so structural boundaries stay perceivable.
+    '--color-border': ld(
+      hexWithAlpha(N[10], borderSubtleAlpha),
+      hexWithAlpha(N[95], borderSubtleAlpha),
+    ),
     '--color-border-emphasized': borderEmphasized,
 
     // Effects

package/src/theme/expandTypeScale.test.ts

@@ -305,4 +305,47 @@ describe('generateTypeScaleComponents', () => {
       'var(--text-body-leading)',
     );
   });
+
+  it('generates rules for all 3 heading display types', () => {
+    const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+    for (const type of ['display-1', 'display-2', 'display-3']) {
+      expect(components.heading).toHaveProperty(`type:${type}`);
+    }
+  });
+
+  it('heading display-type rules reference the display semantic tokens', () => {
+    const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+    const display1 = components.heading['type:display-1'];
+    expect(display1.fontFamily).toBe('var(--font-family-heading)');
+    expect(display1.fontSize).toBe('var(--text-display-1-size)');
+    expect(display1.lineHeight).toBe('var(--text-display-1-leading)');
+    // fontWeight is intentionally omitted here, matching the `text` branch's
+    // type-keyed rules — see defaultWeightByTypeStyles for how weight is
+    // applied instead.
+    expect(display1.fontWeight).toBeUndefined();
+  });
+
+  it('emits heading type:display-N rules after level:N rules, so type wins at equal specificity', () => {
+    // Heading renders both a `level:N` and a `type:display-N` class on the
+    // same element simultaneously when `type` is set (see Heading.tsx).
+    // Both produce single-class-selector CSS rules of equal specificity, so
+    // CSS's own "last rule wins" tiebreak is what makes `type` take
+    // precedence over `level` -- which only holds if type rules are emitted
+    // strictly after all level rules in this object's (and therefore the
+    // generated stylesheet's) key order. This regression-tests #4829,
+    // where type-keyed heading rules didn't exist at all and level always
+    // won by default, silently discarding the `type` prop under any theme
+    // with a typography.scale.
+    const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+    const keys = Object.keys(components.heading);
+    const lastLevelIndex = Math.max(
+      ...[1, 2, 3, 4, 5, 6].map(level => keys.indexOf(`level:${level}`)),
+    );
+    const firstTypeIndex = Math.min(
+      ...['display-1', 'display-2', 'display-3'].map(type =>
+        keys.indexOf(`type:${type}`),
+      ),
+    );
+    expect(firstTypeIndex).toBeGreaterThan(lastLevelIndex);
+  });
 });

package/src/theme/expandTypeScale.ts

@@ -368,6 +368,23 @@ export function generateTypeScaleComponents(
       lineHeight: `var(--text-heading-${level}-leading)`,
     };
   }
+  // `Heading` renders both a `level:N` and, when set, a `type:display-N`
+  // visual-prop class simultaneously (type sizing takes precedence over
+  // level sizing — see Heading.tsx's own `type ? sizeByTypeStyles[type] :
+  // sizeByLevelStyles[level]`). Without a `type:display-N` rule here, the
+  // `level:N` rule is the only one that matches, so it silently wins
+  // regardless of `type` once a theme supplies a type scale. Emitting these
+  // after the level rules keeps them later in source order, so they take
+  // precedence at equal specificity, matching the component's own logic.
+  // fontWeight is intentionally omitted, mirroring the `text` branch below
+  // and preserving `defaultWeightByTypeStyles`.
+  for (const type of ['display-1', 'display-2', 'display-3']) {
+    headingRules[`type:${type}`] = {
+      fontFamily: 'var(--font-family-heading)',
+      fontSize: `var(--text-${type}-size)`,
+      lineHeight: `var(--text-${type}-leading)`,
+    };
+  }
   components.heading = headingRules;
 
   const textRules: Record<string, Record<string, string>> = {};

package/src/theme/generateThemeRules.test.ts

@@ -385,46 +385,46 @@ describe('derived var expansion', () => {
     expect(rule).toContain('--_button-radius: 8px');
   });
 
-  it('emits internal vars for avatar fallback typography (base)', () => {
+  it('emits direct rules for avatar fallback background, color, and weight', () => {
     const theme = defineTheme({
-      name: 'test-derived-avatar',
+      name: 'test-avatar-fallback',
       components: {
-        avatar: {
+        'avatar-fallback': {
           base: {
-            fontWeight: 'var(--font-weight-normal)',
-            color: 'var(--color-text-secondary)',
             backgroundColor: 'var(--color-accent-muted)',
+            color: 'var(--color-text-secondary)',
+            fontWeight: 'var(--font-weight-normal)',
           },
         },
       },
     });
     const rules = generateThemeRules(theme);
-    const rule = rules.find(r => r.includes('.astryx-avatar'));
+    const rule = rules.find(r => r.includes('.astryx-avatar-fallback'));
     expect(rule).toBeDefined();
-    expect(rule).toContain(
-      '--_avatar-fallback-font-weight: var(--font-weight-normal)',
-    );
-    expect(rule).toContain(
-      '--_avatar-fallback-color: var(--color-text-secondary)',
-    );
-    expect(rule).toContain(
-      '--_avatar-fallback-background: var(--color-accent-muted)',
-    );
+    expect(rule).toContain('background-color: var(--color-accent-muted)');
+    expect(rule).toContain('color: var(--color-text-secondary)');
+    expect(rule).toContain('font-weight: var(--font-weight-normal)');
+    // These are direct class targets now, not internal derived vars.
+    expect(rule).not.toContain('--_avatar-fallback-background');
+    expect(rule).not.toContain('--_avatar-fallback-color');
+    expect(rule).not.toContain('--_avatar-fallback-font-weight');
   });
 
-  it('emits a per-size fallback font-size for avatar (size:sm)', () => {
+  it('emits a direct per-size font-size rule for the avatar fallback target', () => {
     const theme = defineTheme({
-      name: 'test-derived-avatar-size',
+      name: 'test-avatar-fallback-size',
       components: {
-        avatar: {
+        'avatar-fallback': {
           'size:sm': {fontSize: '9px'},
         },
       },
     });
     const rules = generateThemeRules(theme);
-    const rule = rules.find(r => r.includes('.astryx-avatar.sm'));
+    const rule = rules.find(r => r.includes('.astryx-avatar-fallback.sm'));
     expect(rule).toBeDefined();
-    expect(rule).toContain('--_avatar-fallback-font-size: 9px');
+    expect(rule).toContain('font-size: 9px');
+    // Direct class target now — no internal derived var.
+    expect(rule).not.toContain('--_avatar-fallback-font-size');
   });
 
   it('does not emit derived vars for components without registry entries', () => {
@@ -475,6 +475,47 @@ describe('derived var expansion', () => {
     expect(rule).toContain('border-radius: 16px');
     expect(rule).toContain('--_card-radius: 16px');
   });
+
+  it('replaces paddingInline with the var for textarea (no raw property)', () => {
+    const theme = defineTheme({
+      name: 'test-derived-textarea',
+      components: {
+        textarea: {
+          base: {paddingInline: 'var(--eps-input-padding-x)'},
+        },
+      },
+    });
+    const rules = generateThemeRules(theme);
+    const rule = rules.find(r => r.includes('.astryx-textarea'));
+    expect(rule).toBeDefined();
+    // Value flows to the inner <textarea> via the var…
+    expect(rule).toContain(
+      '--_textarea-inline-padding: var(--eps-input-padding-x)',
+    );
+    // …and must NOT land on the flush wrapper, which would re-inset the
+    // full-bleed textarea and push the native resize grip off the corner.
+    expect(rule).not.toContain('padding-inline: var(--eps-input-padding-x)');
+  });
+
+  it('replaces progressbar-mark width/height with vars (no raw properties)', () => {
+    const theme = defineTheme({
+      name: 'test-derived-progressbar-mark',
+      components: {
+        'progressbar-mark': {
+          base: {width: '2px', height: '12px'},
+        },
+      },
+    });
+    const rules = generateThemeRules(theme);
+    const rule = rules.find(r => r.includes('.astryx-progressbar-mark'));
+    expect(rule).toBeDefined();
+    expect(rule).toContain('--_progressbar-mark-width: 2px');
+    expect(rule).toContain('--_progressbar-mark-height: 12px');
+    // Raw dimensions would be a same-element fight with the mark's StyleX,
+    // which an unlayered consumer build wins — the vars have no competitor.
+    expect(rule).not.toMatch(/[{;]\s*width: 2px/);
+    expect(rule).not.toMatch(/[{;]\s*height: 12px/);
+  });
 });
 
 describe('brutalist-style derived expansion', () => {

package/src/theme/generateThemeRules.ts

@@ -350,9 +350,11 @@ function generateComponentRules(
       // Entries are processed in order (priority).
       // - `vars`: emit internal CSS custom property declarations
       // - `expand: 'container'`: expand padding to container layout tokens
+      // - `replaces: true`: emit only the var, dropping the source property
       let finalProps = props;
       const derivedProps: [string, string][] = [];
       let containerExpanded = false;
+      const replacedProps = new Set<string>();
 
       for (const [prop, value] of props) {
         const derived = getDerivedVars(component, prop);
@@ -366,6 +368,9 @@ function generateComponentRules(
           if (entry.expand === 'container' && PADDING_PROPS.has(prop)) {
             containerExpanded = true;
           }
+          if (entry.replaces) {
+            replacedProps.add(prop);
+          }
           if (entry.vars) {
             for (const varName of entry.vars) {
               derivedProps.push([varName, value]);
@@ -384,6 +389,12 @@ function generateComponentRules(
         finalProps = [...nonPaddingProps, ...containerTokens];
       }
 
+      // Drop properties whose derived entry set `replaces` — their value is
+      // carried by the emitted var and must not land on the class element.
+      if (replacedProps.size > 0) {
+        finalProps = finalProps.filter(([p]) => !replacedProps.has(p));
+      }
+
       if (derivedProps.length > 0) {
         finalProps = [...finalProps, ...derivedProps];
       }

package/src/theme/index.ts

@@ -130,6 +130,19 @@ export type {
 
 export {useTheme, useThemeName, ThemeContext} from './useTheme';
 export type {UseThemeReturn, ThemeContextValue} from './useTheme';
+
+export type {
+  IndicatorComponent,
+  IndicatorFamily,
+  IndicatorFamilyMap,
+  IndicatorMap,
+  IndicatorName,
+  IndicatorNameOfFamily,
+  IndicatorProps,
+  IndicatorRegistry,
+  IndicatorSize,
+  IndicatorState,
+} from '../Indicator';
 export {
   resolveThemeToken,
   resolveThemeTokens,

package/src/utils/focusOutline.stylex.ts

@@ -0,0 +1,163 @@
+// 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 at 2px offset already;
+ * writing it per component meant five identical definitions to keep in step.
+ *
+ * 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.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+
+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'];
+
+/**
+ * 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: 'solid',
+  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 `--color-accent` stays a var, so a theme's
+ * accent still flows 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: 'solid',
+  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_WIDTH} solid ${FOCUS_OUTLINE_COLOR}`,
+    },
+    '--_focus-outline-offset': {
+      default: '0',
+      ':focus-visible': FOCUS_OUTLINE_OFFSET,
+    },
+  },
+  focusWithinOrPublished: {
+    outline: {
+      default: 'var(--_focus-outline, none)',
+      ':has(:focus-visible)': `${FOCUS_OUTLINE_WIDTH} solid ${FOCUS_OUTLINE_COLOR}`,
+    },
+    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 {

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