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

package/src/theme/derivedVarRegistry.test.ts

@@ -186,7 +186,6 @@ function discoverComponents(): ComponentInfo[] {
 // ---------------------------------------------------------------------------
 
 const DIR_TO_REGISTRY_KEY: Record<string, string> = {
-  Avatar: 'avatar',
   Banner: 'banner',
   Button: 'button',
   Card: 'card',
@@ -196,8 +195,10 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
   Field: 'field',
   HoverCard: 'hovercard',
   Popover: 'popover',
+  ProgressBar: 'progressbar-mark',
   Section: 'section',
   SegmentedControl: 'segmented-control',
+  TextArea: 'textarea',
 };
 
 /**
@@ -340,4 +341,23 @@ describe('getDerivedVars', () => {
   it('returns empty for unregistered property', () => {
     expect(getDerivedVars('card', 'color')).toEqual([]);
   });
+
+  it('marks textarea paddingInline as replacing the source property', () => {
+    const result = getDerivedVars('textarea', 'paddingInline');
+    expect(result).toHaveLength(1);
+    expect(result[0].vars).toEqual(['--_textarea-inline-padding']);
+    expect(result[0].replaces).toBe(true);
+  });
+
+  it('marks progressbar-mark width and height as replacing the source property', () => {
+    for (const [property, varName] of [
+      ['width', '--_progressbar-mark-width'],
+      ['height', '--_progressbar-mark-height'],
+    ]) {
+      const result = getDerivedVars('progressbar-mark', property);
+      expect(result).toHaveLength(1);
+      expect(result[0].vars).toEqual([varName]);
+      expect(result[0].replaces).toBe(true);
+    }
+  });
 });

package/src/theme/derivedVarRegistry.ts

@@ -25,6 +25,14 @@ export interface DerivedVarEntry {
   vars?: string[];
   /** Named expansion strategy. 'container' expands padding to container tokens. */
   expand?: 'container';
+  /**
+   * Emit only the internal `vars`, dropping the source property from the rule.
+   * Use when the class-carrying element must NOT receive the standard property
+   * itself — the value is consumed by a child through the var instead. Without
+   * this, the property is emitted alongside the var (correct when the same
+   * element both reads the var and applies the property, e.g. Chat/DropdownMenu).
+   */
+  replaces?: boolean;
 }
 
 /**
@@ -35,12 +43,6 @@ export interface DerivedVarEntry {
  * entries share the same property.
  */
 export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
-  avatar: [
-    {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},
-    {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},
-    {property: 'color', vars: ['--_avatar-fallback-color']},
-    {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},
-  ],
   banner: [{property: 'borderRadius', vars: ['--_banner-radius']}],
   button: [{property: 'borderRadius', vars: ['--_button-radius']}],
   card: [
@@ -62,11 +64,22 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
   field: [{property: 'borderRadius', vars: ['--_field-radius']}],
   hovercard: [{property: 'borderRadius', vars: ['--_hovercard-radius']}],
   popover: [{property: 'borderRadius', vars: ['--_popover-radius']}],
+  'progressbar-mark': [
+    {property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},
+    {property: 'height', vars: ['--_progressbar-mark-height'], replaces: true},
+  ],
   section: [{property: 'padding', expand: 'container'}],
   'segmented-control': [
     {property: 'borderRadius', vars: ['--_segmented-control-radius']},
     {property: 'padding', vars: ['--_segmented-control-padding']},
   ],
+  textarea: [
+    {
+      property: 'paddingInline',
+      vars: ['--_textarea-inline-padding'],
+      replaces: true,
+    },
+  ],
 };
 
 /**

package/src/theme/expandColorScale.test.ts

@@ -100,6 +100,20 @@ describe('expandColorScale', () => {
       standard['--color-text-primary'],
     );
   });
+
+  it('contrast high strengthens both border tokens', () => {
+    const standard = expandColorScale({
+      accent: '#0064E0',
+      contrast: 'standard',
+    });
+    const high = expandColorScale({accent: '#0064E0', contrast: 'high'});
+    // Both the subtle hairline and the emphasized border shift under high
+    // contrast, so structural boundaries stay perceivable.
+    expect(high['--color-border']).not.toBe(standard['--color-border']);
+    expect(high['--color-border-emphasized']).not.toBe(
+      standard['--color-border-emphasized'],
+    );
+  });
 });
 
 describe('expandColorScale — neutral-only themes (#2279)', () => {

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

@@ -23,6 +23,23 @@ const defaultInput = {
   },
 };
 
+describe('focus outline tokens', () => {
+  it('emits a focus ring override into the theme scope', () => {
+    const theme = defineTheme({
+      name: 'brand',
+      tokens: {
+        '--focus-outline-color': '#FF00FF',
+        '--focus-outline-width': '4px',
+      },
+    });
+
+    const {component} = generateThemeCSS(theme);
+
+    expect(component).toContain('--focus-outline-color: #FF00FF;');
+    expect(component).toContain('--focus-outline-width: 4px;');
+  });
+});
+
 describe('generateThemeRules', () => {
   const theme = defineTheme(defaultInput);
   const rules = generateThemeRules(theme);
@@ -385,46 +402,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 +492,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

@@ -90,6 +90,7 @@ export {
   spacingDefaults,
   sizeDefaults,
   borderDefaults,
+  focusDefaults,
   radiusDefaults,
   shadowDefaults,
   durationDefaults,
@@ -102,6 +103,7 @@ export {
   spacingVars,
   sizeVars,
   borderVars,
+  focusVars,
   radiusVars,
   shadowVars,
   durationVars,
@@ -130,6 +132,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/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');
+  });
+});