@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/src/reset.test.ts

@@ -57,4 +57,26 @@ describe('reset.css accessibility invariants', () => {
         .not.toMatch(/outline(?:-style|-width)?\s*:\s*(?:none|0)/);
     }
   });
+
+  /**
+   * A disabled control must not answer the pointer with an interactive
+   * cursor. The reset is the floor for any element that declares no cursor of
+   * its own — components declare theirs under the `disabled-cursor` lint
+   * rule, and the Chromium sweep measures the rendered result.
+   */
+  it('gives disabled elements the disabled cursor', () => {
+    const disabledBlocks = ruleBlocks.filter(
+      ({selector}) =>
+        selector.includes(':disabled') && !selector.includes(':not('),
+    );
+    expect(disabledBlocks.length).toBeGreaterThan(0);
+    for (const {selector, body} of disabledBlocks) {
+      expect(body, `disabled rule "${selector}"`).toMatch(/cursor:\s*default/);
+    }
+    // aria-disabled is how astryx keeps a disabled control focusable, so the
+    // reset has to cover it alongside the native state.
+    expect(
+      disabledBlocks.some(({selector}) => selector.includes('aria-disabled')),
+    ).toBe(true);
+  });
 });

package/src/theme/MediaTheme.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
   ],
   playground: {
     defaults: {
-      mode: 'dark',
+      mode: 'auto',
       children: {
         __element: 'Section',
         props: {
@@ -65,6 +65,11 @@ export const docs = {
         description:
           'Use for any content placed over a dark background (image overlays, video scrims, dark cards) or other inverted surfaces like toasts and tooltips.',
       },
+      {
+        guidance: true,
+        description:
+          'Prefer mode="auto" when the surface color comes from a theme token. A token named "inverted" is not guaranteed to be inverted, and auto measures what was actually painted instead of trusting the name — including deciding that a surface needs no media context at all.',
+      },
       {
         guidance: true,
         description:
@@ -85,10 +90,17 @@ export const docs = {
   props: [
     {
       name: 'mode',
-      type: "'dark' | 'light'",
+      type: "'dark' | 'light' | 'auto' | 'off'",
       required: true,
       description:
-        'Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions).',
+        'Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from the painted surface — no media context when the ambient text already reads on the surface (3:1), otherwise the side that reads better — and off to turn it off explicitly. The element renders either way, so a surface can switch contexts without remounting children.',
+    },
+    {
+      name: 'fallback',
+      type: "'dark' | 'light'",
+      default: "'dark'",
+      description:
+        'Which side auto uses when the surface cannot be measured: during SSR, on the first client frame, and whenever the backdrop is not knowable from CSS — most often a background-image, whose pixels need sampling (useImageMode) rather than a computed style. Ignored unless mode is auto.',
     },
     {
       name: 'children',
@@ -111,6 +123,11 @@ export const docsDense = {
         description:
           'Use for any content over dark background (image overlays, video scrims, dark cards) or other inverted surfaces like toasts/tooltips.',
       },
+      {
+        guidance: true,
+        description:
+          'Prefer mode="auto" when surface color comes from a theme token — a token named "inverted" is not guaranteed to be; auto measures what was painted.',
+      },
       {
         guidance: true,
         description:
@@ -129,6 +146,8 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    mode: 'surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions)',
+    mode: 'surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from painted surface (none if ambient text already reads at 3:1, else better-reading side), off to turn off explicitly (element still renders, so children never remount)',
+    fallback:
+      'side auto uses when surface is unmeasurable (SSR, first frame, background-image — those need useImageMode sampling); ignored unless mode is auto',
   },
 };

package/src/theme/MediaTheme.dom.test.tsx

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MediaTheme.dom.test.tsx
+ * @input MediaTheme rendered in jsdom
+ * @output Coverage for mode="auto" and mode="off" DOM behavior
+ * @position Companion to useAutoMediaMode.test.ts, which covers the pure pick
+ *
+ * jsdom applies no stylesheet and resolves no custom properties, so auto
+ * cannot measure here — which makes this the right place to pin the fallback
+ * behavior that an unmeasurable surface depends on.
+ *
+ * Named `.dom.test.tsx` rather than `.test.tsx`: a sibling `.test.ts` of the
+ * same basename collides in the TypeScript project service, and type-aware
+ * lint then cannot resolve either file.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {MediaTheme} from './MediaTheme';
+import type {MediaThemeMode} from './MediaTheme';
+
+function renderMode(mode: MediaThemeMode, fallback?: 'dark' | 'light') {
+  render(
+    <div style={{background: 'rgb(10, 19, 23)'}}>
+      <MediaTheme mode={mode} fallback={fallback}>
+        <span data-testid="child">content</span>
+      </MediaTheme>
+    </div>,
+  );
+  return screen.getByTestId('child').parentElement;
+}
+
+describe('MediaTheme', () => {
+  it.each(['dark', 'light'] as const)('applies mode=%s verbatim', mode => {
+    expect(renderMode(mode)?.getAttribute('data-astryx-media')).toBe(mode);
+  });
+
+  it('renders no media attribute for mode="off"', () => {
+    const wrapper = renderMode('off');
+    expect(wrapper?.hasAttribute('data-astryx-media')).toBe(false);
+  });
+
+  it('still renders its element for mode="off" so children never remount', () => {
+    expect(renderMode('off')?.tagName).toBe('DIV');
+  });
+
+  it('falls back to dark for an unmeasurable auto surface', () => {
+    expect(renderMode('auto')?.getAttribute('data-astryx-media')).toBe('dark');
+  });
+
+  it('honors an explicit fallback', () => {
+    expect(renderMode('auto', 'light')?.getAttribute('data-astryx-media')).toBe(
+      'light',
+    );
+  });
+
+  it('ignores fallback when the mode is explicit', () => {
+    expect(renderMode('dark', 'light')?.getAttribute('data-astryx-media')).toBe(
+      'dark',
+    );
+  });
+
+  it('leaves no probe element behind', () => {
+    const {container} = render(
+      <div style={{background: 'rgb(10, 19, 23)'}}>
+        <MediaTheme mode="auto">
+          <span>content</span>
+        </MediaTheme>
+      </div>,
+    );
+    expect(container.querySelectorAll('span')).toHaveLength(1);
+  });
+
+  // Regression: an earlier revision keyed the measurement to a dependency
+  // array, so a surface whose color changed by prop kept a stale mode until
+  // something unrelated re-ran the effect.
+  it('re-measures when the surface changes without the theme changing', () => {
+    function Harness({background}: {background: string}) {
+      return (
+        <div style={{background}}>
+          <MediaTheme mode="auto" fallback="dark">
+            <span data-testid="child">content</span>
+          </MediaTheme>
+        </div>
+      );
+    }
+    // jsdom resolves no custom properties, so the measured pick is always the
+    // fallback; what this pins is that the effect RUNS again — a stale
+    // implementation skips it entirely.
+    const {rerender} = render(<Harness background="rgb(10, 19, 23)" />);
+    const first = screen.getByTestId('child').parentElement;
+    rerender(<Harness background="rgb(255, 255, 255)" />);
+    expect(screen.getByTestId('child').parentElement).toBe(first);
+    expect(first?.getAttribute('data-astryx-media')).toBe('dark');
+  });
+});

package/src/theme/MediaTheme.tsx

@@ -4,13 +4,13 @@
 
 /**
  * @file MediaTheme.tsx
- * @input mode prop ("dark" | "light") + children
+ * @input mode prop ("dark" | "light" | "auto" | "off") + children
  * @output Wrapper div that creates an inverted theming context
  * @position Theme system component; sibling to Theme
  *
  * Provides semantic token overrides for content rendered on a surface
  * with a different luminance than the page background. Used by Toast,
- * Tooltip, and other components that render on inverted surfaces.
+ * Overlay, and other components that render on inverted surfaces.
  *
  * How it works:
  * 1. Sets `data-astryx-media="dark|light"` — the theme's generated CSS
@@ -22,11 +22,14 @@
  *    `onDark.components` / `onLight.components` in defineTheme().
  * 4. Children (Button, Link, Text, etc.) pick up inverted tokens
  *    naturally through CSS custom property inheritance
+ * 5. `mode="auto"` measures the painted surface and picks a side — or none;
+ *    `mode="off"` renders the same element with no media attribute, so
+ *    either can change without remounting children.
  *
  * @example
  * ```
  * <div style={{ backgroundColor: 'var(--color-background-inverted)' }}>
- *   <MediaTheme mode="dark">
+ *   <MediaTheme mode="auto">
  *     <Button label="Undo" variant="ghost" />
  *   </MediaTheme>
  * </div>
@@ -34,24 +37,46 @@
  */
 
 import * as React from 'react';
+import {useRef} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {colorVars} from './tokens.stylex';
 import {dataAttr} from '../naming';
+import {useAutoMediaMode} from '../hooks/useAutoMediaMode';
 
 const styles = stylex.create({
   root: {
     display: 'contents',
+  },
+  active: {
     color: colorVars['--color-text-primary'],
   },
 });
 
+/** Surface luminance context, or `"off"` for no media context at all. */
+export type MediaThemeMode = 'dark' | 'light' | 'auto' | 'off';
+
 export interface MediaThemeProps {
   /**
    * The surface luminance context for children.
    * - `"dark"` — children are on a dark background (get light text/icons)
    * - `"light"` — children are on a light background (get dark text/icons)
+   * - `"auto"` — measure the painted surface and use whichever side reads
+   *   better on it, or no media context at all when the surface's ambient
+   *   text already reads better than either
+   * - `"off"` — children keep the ambient theme; the surface needs no
+   *   inversion
    */
-  mode: 'dark' | 'light';
+  mode: MediaThemeMode;
+  /**
+   * Which side `mode="auto"` uses when the surface cannot be measured: on the
+   * server, on the first client frame, and whenever the backdrop is not
+   * knowable from CSS — most often a `background-image`, whose pixels need
+   * sampling (see `useImageMode`) rather than a computed style.
+   *
+   * Ignored unless `mode="auto"`.
+   * @default "dark"
+   */
+  fallback?: 'dark' | 'light';
   /** Content to render in the media context */
   children: React.ReactNode;
 }
@@ -65,13 +90,23 @@ export interface MediaThemeProps {
  */
 export function MediaTheme({
   mode,
+  fallback = 'dark',
   children,
 }: MediaThemeProps): React.ReactElement {
+  const ref = useRef<HTMLDivElement>(null);
+  // Measures this element's PARENT — see useAutoMediaMode. `display: contents`
+  // means the parent is the element that actually paints the surface.
+  const detected = useAutoMediaMode(ref, mode === 'auto');
+  const resolved = mode === 'auto' ? (detected ?? fallback) : mode;
+
+  // "off" keeps the element — and therefore the React tree and the DOM
+  // structure — identical, so a surface can switch its media context on and
+  // off without remounting its children.
   return (
     <div
-      {...{[dataAttr('media')]: mode}}
-      {...stylex.props(styles.root)}
-    >
+      ref={ref}
+      {...(resolved === 'off' ? null : {[dataAttr('media')]: resolved})}
+      {...stylex.props(styles.root, resolved !== 'off' && styles.active)}>
       {children}
     </div>
   );

package/src/theme/defineTheme.test.ts

@@ -738,7 +738,9 @@ describe('pseudo-class overrides in components', () => {
     expect(css).toContain('.astryx-radio {');
     expect(css).toContain('border-color: #8F9296');
     // Pseudo rule — separate selector
-    expect(css).toContain('.astryx-radio:hover {');
+    expect(css).toContain(
+      '.astryx-radio:hover:where(:not(:disabled,[aria-disabled="true"])) {',
+    );
     expect(css).toContain(
       'border-color: color-mix(in srgb, #8F9296, black 20%)',
     );
@@ -764,7 +766,9 @@ describe('pseudo-class overrides in components', () => {
     const css = generateThemeTestCSS(theme);
     expect(css).toContain('.astryx-button.primary-muted {');
     expect(css).toContain('background-color: #ECF5FF');
-    expect(css).toContain('.astryx-button.primary-muted:hover {');
+    expect(css).toContain(
+      '.astryx-button.primary-muted:hover:where(:not(:disabled,[aria-disabled="true"])) {',
+    );
     expect(css).toContain('background-color: #D6EBFF');
     expect(css).toContain('.astryx-button.primary-muted:focus-visible {');
     expect(css).toContain('outline: 2px solid var(--color-accent)');
@@ -787,7 +791,9 @@ describe('pseudo-class overrides in components', () => {
     // Should NOT emit an empty base rule
     expect(css).not.toMatch(/\.astryx-switch\s*\{\s*\}/);
     // Should emit the pseudo rule
-    expect(css).toContain('.astryx-switch:hover {');
+    expect(css).toContain(
+      '.astryx-switch:hover:where(:not(:disabled,[aria-disabled="true"])) {',
+    );
   });
 
   it('keeps non-pseudo string values as regular properties', () => {

package/src/theme/defineTheme.ts

@@ -113,6 +113,11 @@ export type TokenValue = string | [light: string, dark: string];
  * to the component selector. Supported pseudo-classes include `:hover`,
  * `:focus-visible`, `:active`, `:checked`, `:disabled`, etc.
  *
+ * A `:hover` override describes the ENABLED control: it is emitted with a
+ * guard that keeps it off disabled and `aria-disabled` elements, which
+ * `:hover` would otherwise still match. Style the disabled state through
+ * `:disabled` instead.
+ *
  * @example
  * ```ts
  * {

package/src/theme/derivedVarRegistry.test.ts

@@ -85,6 +85,9 @@ const STRUCTURAL_VARS = new Set([
   '--table-row-overlay',
   '--separator-display',
   '--astryx-section-padding',
+  // Private counterpart of the public token above: one ancestor Section's
+  // padding, propagated down the tree. Structural, never authored by a theme.
+  '--_section-padding-propagated',
 ]);
 
 /**
@@ -164,9 +167,6 @@ function discoverComponents(): ComponentInfo[] {
         allVars.add(v);
       }
     }
-    if (allVars.size === 0) {
-      continue;
-    }
 
     // Only check component directories (those with a doc file named after the
     // directory). Match against the on-disk listing rather than existsSync so
@@ -188,6 +188,16 @@ function discoverComponents(): ComponentInfo[] {
       /* skip */
     }
 
+    // A directory earns a check by declaring a var OR by documenting a
+    // derived[] entry. Bailing on the var count alone (as this did) hid every
+    // component that is themeable purely through an expansion strategy —
+    // `{property: 'padding', expand: 'container'}` names no var, so such a
+    // component declares nothing and its registry↔doc consistency check
+    // silently never ran.
+    if (allVars.size === 0 && docDerived.length === 0) {
+      continue;
+    }
+
     results.push({
       dir,
       sourceVars: [...allVars],
@@ -212,6 +222,7 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
   DropdownMenu: 'dropdown-menu',
   Field: 'field',
   HoverCard: 'hovercard',
+  NumberInput: 'number-input',
   Popover: 'popover',
   ProgressBar: 'progressbar-mark',
   Section: 'section',
@@ -262,9 +273,12 @@ const VARS_WITHOUT_DERIVED_MAPPING = new Set([
   '--_avatar-group-overlap',
   '--_codeblock-gutter-width',
   '--_tab-indicator-bottom',
-  // Hit-area outset on a ::after overlay — `inset` on a pseudo-element is not
-  // a property a theme author sets on the component.
+  // Hit-area outset on a ::after overlay, and whether that overlay is
+  // generated at all — `inset` and `content` on a pseudo-element are not
+  // properties a theme author sets on the component.
   '--_thumbnail-hit-inset',
+  '--_input-clear-hit-inset',
+  '--_input-clear-hit-content',
   // Indentation and row-spacing metrics: --tree-list-indent is the authorable
   // step, --_tree-indent the per-row distance TreeListItem computes from it.
   // --tree-list-row-gap is applied as half a padding-block on each row wrapper,

package/src/theme/derivedVarRegistry.ts

@@ -67,6 +67,10 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
   ],
   field: [{property: 'borderRadius', vars: ['--_field-radius']}],
   hovercard: [{property: 'borderRadius', vars: ['--_hovercard-radius']}],
+  'number-input': [
+    {property: 'padding', expand: 'container'},
+    {property: 'borderRadius', vars: ['--_field-radius']},
+  ],
   popover: [{property: 'borderRadius', vars: ['--_popover-radius']}],
   'progressbar-mark': [
     {property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},

package/src/theme/generateThemeRules.test.ts

@@ -160,6 +160,45 @@ describe('generateThemeRules', () => {
     ).toBe(true);
   });
 
+  // A theme authoring `:hover` is describing the ENABLED control. Without a
+  // guard the rule paints a disabled one too, because browsers suppress a
+  // disabled control's events, not its hover styling — and a theme override
+  // would then reintroduce, on every component at once, the defect the
+  // components' own styles were fixed for.
+  it('keeps a themed :hover off disabled elements', () => {
+    const hoverTheme = defineTheme({
+      name: 'hover-guard',
+      components: {
+        button: {
+          base: {
+            ':hover': {color: 'red'},
+            ':focus-visible': {outline: '2px solid blue'},
+          },
+        },
+      },
+    });
+    const hoverRules = generateThemeRules(hoverTheme);
+    const hoverRule = hoverRules.find(rule => rule.includes(':hover'));
+    expect(hoverRule).toBeDefined();
+    expect(hoverRule).toContain(
+      '.astryx-button:hover:where(:not(:disabled,[aria-disabled="true"]))',
+    );
+    // Every selector in a comma-separated list carries its own guard —
+    // a trailing pseudo does not distribute over a selector list. (Counted,
+    // not split: the guard contains a comma of its own.)
+    const selectorText = String(hoverRule).split('{')[0];
+    const hovers = selectorText.match(/:hover/g) || [];
+    const guards = selectorText.match(/:where\(:not\(:disabled/g) || [];
+    expect(hovers.length).toBeGreaterThan(0);
+    expect(guards.length).toBe(hovers.length);
+    // Other pseudo-classes are untouched: a disabled control can still be
+    // focused (that is the point of aria-disabled), and :focus-visible on it
+    // is correct.
+    const focusRule = hoverRules.find(rule => rule.includes(':focus-visible'));
+    expect(focusRule).toContain('.astryx-button:focus-visible {');
+    expect(focusRule).not.toContain('aria-disabled');
+  });
+
   // --- Prose rules ---
 
   it('includes prose heading rules with computed values', () => {
@@ -584,3 +623,82 @@ describe('brutalist-style derived expansion', () => {
     expect(rule).toContain('--_dropdown-menu-padding: 4px');
   });
 });
+
+describe('physical padding longhands', () => {
+  const ruleFor = (
+    component: string,
+    base: Record<string, string>,
+    name = 'test-physical-padding',
+  ) =>
+    generateThemeRules(
+      defineTheme({name, components: {[component]: {base}}}),
+    ).find(r => r.includes(`.astryx-${component}`));
+
+  // `padding-top`/`padding-bottom` ARE the block edges in every horizontal
+  // writing mode, so the expansion can normalize them with no direction
+  // assumption. Without that, the padding lands raw on the element and the
+  // component's internals — the NumberInput stepper column, container bleed —
+  // read the default instead of what the theme set.
+  it.each([
+    ['paddingTop', {paddingTop: '14px'}, 'block-start'],
+    ['paddingBottom', {paddingBottom: '14px'}, 'block-end'],
+  ])('routes %s through the container expansion', (_label, base, edge) => {
+    const rule = ruleFor('card', base);
+    expect(rule).toContain(`--astryx-card-padding-${edge}: 14px`);
+    expect(rule).not.toMatch(/[{;]\s*padding-(top|bottom):/);
+  });
+
+  it('normalizes both block edges together, asymmetrically', () => {
+    const rule = ruleFor('number-input', {
+      paddingTop: '14px',
+      paddingBottom: '6px',
+    });
+    expect(rule).toContain('--astryx-number-input-padding-block-start: 14px');
+    expect(rule).toContain('--astryx-number-input-padding-block-end: 6px');
+  });
+
+  it.each(['card', 'dialog', 'section', 'number-input'])(
+    'reaches %s, which expands its padding',
+    component => {
+      expect(ruleFor(component, {paddingTop: '14px'})).toContain(
+        `--astryx-${component}-padding-block-start: 14px`,
+      );
+    },
+  );
+
+  // THE RTL GUARD. `paddingLeft` is inline-start in LTR and inline-end in RTL,
+  // and the tokens are consumed by logical properties, so mapping it would
+  // silently move the padding to the other edge in RTL. It stays physical —
+  // which is what the author wrote — and does not reach the tokens.
+  it('leaves the direction-relative inline pair physical', () => {
+    const rule = ruleFor('card', {paddingLeft: '20px', paddingRight: '8px'});
+    expect(rule).toContain('padding-left: 20px');
+    expect(rule).toContain('padding-right: 8px');
+    expect(rule).not.toContain('--astryx-card-padding-inline');
+  });
+
+  it('expands the block edges while leaving left physical', () => {
+    const rule = ruleFor('card', {paddingTop: '14px', paddingLeft: '20px'});
+    expect(rule).toContain('--astryx-card-padding-block-start: 14px');
+    expect(rule).toContain('padding-left: 20px');
+  });
+
+  // The shorthand-plus-override case was the worst one: the tokens carried
+  // 10px while the element painted 14px on top, so every internal compensated
+  // by the wrong amount.
+  it('lets a physical longhand override the shorthand per edge', () => {
+    const rule = ruleFor('card', {padding: '10px', paddingTop: '14px'});
+    expect(rule).toContain('--astryx-card-padding-block-start: 14px');
+    expect(rule).toContain('--astryx-card-padding-block-end: 10px');
+    expect(rule).toContain('--astryx-card-padding-inline: 10px');
+    expect(rule).not.toMatch(/[{;]\s*padding(-top)?:/);
+  });
+
+  // A `vars` entry carries one value for the whole box, so a single physical
+  // edge must not feed it — only the container expansion takes these.
+  it('does not feed a single edge to a whole-box derived var', () => {
+    const rule = ruleFor('dropdown-menu', {paddingTop: '14px'});
+    expect(rule).toContain('padding-top: 14px');
+    expect(rule).not.toContain('--_dropdown-menu-padding');
+  });
+});