@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/hooks/useMergedRefs.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useMergedRefs.ts
+ * @input React refs to combine into one stable callback ref
+ * @output Exports useMergedRefs
+ * @position Core hook; use when one element must receive multiple refs
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useMergedRefs.doc.mjs
+ * - /packages/core/src/hooks/useMergedRefs.test.tsx
+ */
+
+import {useMemo, type Ref, type RefCallback} from 'react';
+import {mergeRefs} from '../utils/mergeRefs';
+
+/**
+ * Combine up to six refs into a callback ref whose identity changes only when
+ * one of the input refs changes.
+ */
+export function useMergedRefs<T>(
+  refA?: Ref<T>,
+  refB?: Ref<T>,
+  refC?: Ref<T>,
+  refD?: Ref<T>,
+  refE?: Ref<T>,
+  refF?: Ref<T>,
+): RefCallback<T> {
+  return useMemo(
+    () => mergeRefs(refA, refB, refC, refD, refE, refF),
+    [refA, refB, refC, refD, refE, refF],
+  );
+}

package/src/hooks/useTypeahead.doc.mjs

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useTypeahead',
+  displayName: 'useTypeahead',
+  keywords: [
+    'typeahead',
+    'type to focus',
+    'first character',
+    'keyboard',
+    'search',
+    'jump',
+    'menu',
+    'listbox',
+    'select',
+    'apg',
+    'accessibility',
+    'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseTypeaheadOptions',
+      description: 'Configuration object.',
+      required: true,
+    },
+    {
+      name: 'options.getItemLabels',
+      type: '() => ReadonlyArray<string | null | undefined>',
+      description:
+        "Returns the item labels in DOM order. A null or empty entry marks a non-matchable slot and keeps indices aligned with the caller's items.",
+      required: true,
+    },
+    {
+      name: 'options.onMatch',
+      type: '(index: number) => void',
+      description:
+        "Called with the index of the matched item so the caller can focus or select it; typically useListFocus's focusItem.",
+      required: true,
+    },
+    {
+      name: 'options.getCurrentIndex',
+      type: '() => number',
+      description:
+        'The index to search from, usually the focused item, so repeated presses of one letter cycle through matches. A negative value means nothing is current.',
+      default: '() => -1',
+    },
+    {
+      name: 'options.resetMs',
+      type: 'number',
+      description:
+        'Milliseconds of inactivity after which the typed buffer resets.',
+      default: '750',
+    },
+    {
+      name: 'options.isDisabled',
+      type: '(index: number) => boolean',
+      description: 'Whether an index should be skipped, e.g. disabled items.',
+    },
+  ],
+  returns: [
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent | KeyboardEvent) => boolean',
+      description:
+        'Keydown handler. Returns true when it consumed a printable character, so the caller can stop its own key handling.',
+    },
+    {
+      name: 'reset',
+      type: '() => void',
+      description:
+        'Clears the pending buffer, e.g. when the collection closes.',
+    },
+  ],
+  usage: {
+    description:
+      "Adds APG type-to-focus search to a collection: printable keystrokes are buffered (resetting after a pause), and the first item whose label starts with the buffer is reported through onMatch. Pressing the same letter repeatedly cycles through the matches rather than filtering deeper. It moves nothing itself; pair it with the collection's own focus management, most often useListFocus or useGridFocus.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Wire onMatch to the focus manager you already have (useListFocus.focusItem) instead of moving focus yourself.',
+      },
+      {
+        guidance: true,
+        description:
+          'Let it see the key event first and fall through to arrow-key navigation only when it returns false.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass getCurrentIndex so repeated presses of one letter walk through matches instead of sticking on the first.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use it on a text input; the field already receives the characters, and typeahead would fight the value.',
+      },
+    ],
+  },
+  relatedComponents: ['DropdownMenu', 'Selector', 'TreeList'],
+  relatedHooks: ['useListFocus', 'useGridFocus', 'useTreeFocus'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'focus',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'APG type-to-focus search for a collection. Buffers printable keys (resets after pause), matches labels by prefix, reports index via onMatch. Same letter pressed repeatedly cycles matches. Moves nothing itself; pair w/ useListFocus / useGridFocus.',
+  paramDescriptions: {
+    options: 'config.',
+    'options.getItemLabels':
+      'item labels in DOM order; null / empty = non-matchable slot, indices stay aligned.',
+    'options.onMatch':
+      'called w/ matched index so caller focuses / selects (e.g. useListFocus focusItem).',
+    'options.getCurrentIndex':
+      'index to search from (usually focused item) so repeat presses cycle. negative = nothing current.',
+    'options.resetMs': 'ms of inactivity before typed buffer resets.',
+    'options.isDisabled': 'whether an index is skipped (e.g. disabled items).',
+  },
+  returnDescriptions: {
+    onKeyDown:
+      'keydown handler; true = consumed a printable char, caller can stop its own handling.',
+    reset: 'clears pending buffer (e.g. on close).',
+  },
+  usage: {
+    description:
+      'Type-to-jump for menus / listboxes / trees. Buffered prefix match w/ APG same-letter cycling; reports index, caller owns focus.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Wire onMatch to existing focus manager (useListFocus.focusItem), do not move focus yourself.',
+      },
+      {
+        guidance: true,
+        description:
+          'Give it the key event first; fall through to arrow navigation when it returns false.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass getCurrentIndex so repeat presses walk matches instead of sticking on first.',
+      },
+      {
+        guidance: false,
+        description: 'Use on a text input; field already gets the characters.',
+      },
+    ],
+  },
+};

package/src/index.ts

@@ -55,6 +55,7 @@ export * from './NavIcon';
 export * from './NavMenu';
 export * from './Slider';
 export * from './Stack';
+export * from './Stepper';
 export * from './Switch';
 export * from './DateInput';
 export * from './DateTimeInput';

package/src/raw-import.d.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Ambient module declaration for Vite's `?raw` imports.
+ *
+ * numberParser.docblock.test.ts reads its own subject's source as text, to
+ * check the prose in it against the parser's behaviour. Vite serves that with
+ * the `?raw` query; without this declaration TypeScript fails with TS2307.
+ */
+
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

package/src/theme/MediaTheme.doc.mjs

@@ -68,7 +68,7 @@ export const docs = {
       {
         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.',
+          '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. It can even decide that a surface needs no media context at all.',
       },
       {
         guidance: true,
@@ -93,14 +93,14 @@ export const docs = {
       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), 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.',
+        '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 at 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.',
+        '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',
@@ -126,7 +126,7 @@ export const docsDense = {
       {
         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.',
+          '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,
@@ -148,6 +148,6 @@ 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), 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',
+      'side auto uses when surface is unmeasurable (SSR, first frame, background-image, which needs useImageMode sampling); ignored unless mode is auto',
   },
 };

package/src/theme/Theme.test.tsx

@@ -1,10 +1,22 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {render, cleanup} from '@testing-library/react';
 import React from 'react';
 import {Theme} from './Theme';
 import {defineTheme} from './defineTheme';
+import {dataTokenDefaults} from './domainTokens';
+import type * as DefineThemeModule from './defineTheme';
+
+const {generateThemeCSSSpy} = vi.hoisted(() => ({
+  generateThemeCSSSpy: vi.fn(),
+}));
+
+vi.mock('./defineTheme', async importOriginal => {
+  const actual = await importOriginal<typeof DefineThemeModule>();
+  generateThemeCSSSpy.mockImplementation(actual.generateThemeCSS);
+  return {...actual, generateThemeCSS: generateThemeCSSSpy};
+});
 
 const testTheme = defineTheme({
   name: 'test',
@@ -25,6 +37,7 @@ describe('Theme', () => {
     // Clean up documentElement state before each test
     document.documentElement.removeAttribute('data-theme');
     document.documentElement.removeAttribute('data-astryx-theme');
+    generateThemeCSSSpy.mockClear();
   });
 
   afterEach(() => {
@@ -120,7 +133,9 @@ describe('Theme', () => {
       'test',
     );
     unmount();
-    expect(document.documentElement.hasAttribute('data-astryx-theme')).toBe(false);
+    expect(document.documentElement.hasAttribute('data-astryx-theme')).toBe(
+      false,
+    );
   });
 
   // =========================================================================
@@ -166,4 +181,91 @@ describe('Theme', () => {
     expect(nestedWrapper).toBeTruthy();
     expect(nestedWrapper?.getAttribute('data-theme')).toBe('light');
   });
+
+  // =========================================================================
+  // Data token defaults — one shared :root block, not one per theme scope
+  // =========================================================================
+
+  const baseTags = () =>
+    Array.from(document.head.querySelectorAll('style[data-astryx-theme-base]'));
+
+  it('injects the data token defaults into @layer astryx-base', () => {
+    render(
+      <Theme theme={testTheme}>
+        <span>child</span>
+      </Theme>,
+    );
+
+    expect(baseTags()).toHaveLength(1);
+    const css = baseTags()[0].textContent ?? '';
+    expect(css).toContain('@layer astryx-base {');
+    expect(css).toContain(':root {');
+    expect(css).toContain(
+      `--color-data-categorical-blue: ${dataTokenDefaults['--color-data-categorical-blue']};`,
+    );
+  });
+
+  it('injects one shared block for nested themes, not one per scope', () => {
+    render(
+      <Theme theme={testTheme}>
+        <Theme theme={altTheme}>
+          <span>nested</span>
+        </Theme>
+      </Theme>,
+    );
+
+    expect(baseTags()).toHaveLength(1);
+
+    // The nested theme declares no --color-data-* of its own, so nothing
+    // shadows a value the parent theme set: that is what lets the override
+    // inherit through the ordinary cascade.
+    const themeTags = Array.from(
+      document.head.querySelectorAll('style[data-astryx-theme]'),
+    );
+    for (const tag of themeTags) {
+      expect(tag.textContent).not.toContain('--color-data-');
+    }
+  });
+
+  it('keeps the defaults while any theme is still mounted', () => {
+    const outer = render(
+      <Theme theme={testTheme}>
+        <span>a</span>
+      </Theme>,
+    );
+    render(
+      <Theme theme={altTheme}>
+        <span>b</span>
+      </Theme>,
+    );
+
+    outer.unmount();
+    expect(baseTags()).toHaveLength(1);
+
+    cleanup();
+    expect(baseTags()).toHaveLength(0);
+  });
+
+  it('generates a theme once across nested and sibling mounts', () => {
+    render(
+      <Theme theme={testTheme}>
+        <Theme theme={testTheme}>
+          <span>nested</span>
+        </Theme>
+      </Theme>,
+    );
+    render(
+      <Theme theme={testTheme}>
+        <span>sibling</span>
+      </Theme>,
+    );
+
+    expect(generateThemeCSSSpy).toHaveBeenCalledTimes(1);
+    expect(baseTags()).toHaveLength(1);
+
+    const injected = Array.from(document.querySelectorAll('style'))
+      .map(tag => tag.textContent ?? '')
+      .join('\n');
+    expect(injected.match(/:root\s*\{/g)).toHaveLength(1);
+  });
 });

package/src/theme/Theme.tsx

@@ -42,6 +42,7 @@ import * as stylex from '@stylexjs/stylex';
 import type {ThemeMode} from './types';
 import {colorVars, typographyVars} from './tokens.stylex';
 import {generateThemeCSS, type DefinedTheme} from './defineTheme';
+import {generateDataTokenDefaultsCSS} from './generateThemeRules';
 import {registerTheme} from './themeRegistry';
 import {dataAttr} from '../naming';
 import {ThemeContext} from './useTheme';
@@ -98,6 +99,16 @@ ThemeNestingContext.displayName = 'ThemeNestingContext';
 /** Track which themes have already been injected */
 const injectedThemes = new Set<string>();
 
+/**
+ * How many mounted `Theme`s are relying on the injected data-token defaults.
+ *
+ * The defaults are one document-wide `:root` block, shared by every theme, so
+ * they are injected once and removed only when the last theme that took a
+ * reference unmounts — tearing them down with whichever provider happened to
+ * inject them would strip the palette from the providers still mounted.
+ */
+let dataTokenDefaultsRefCount = 0;
+
 /**
  * Hook to inject theme CSS into the document.
  * Built themes (from `astryx theme build`) skip injection — their CSS
@@ -112,6 +123,8 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
       return;
     }
 
+    // Second and later `Theme`s using this theme do no work at all —
+    // generation included. Its CSS is document-wide and identical for each.
     const themeKey = `astryx-theme-${theme.name}`;
     if (injectedThemes.has(themeKey)) {
       return;
@@ -130,8 +143,26 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
     );
 
     const {prose, component} = generateThemeCSS(theme);
-    if (!prose && !component) {
-      return;
+    const base = generateDataTokenDefaultsCSS();
+    injectedThemes.add(themeKey);
+    const cleanups: (() => void)[] = [() => injectedThemes.delete(themeKey)];
+
+    // Data token defaults go into @layer astryx-base, where StyleX puts the
+    // core token defaults, so a theme's own `--color-data-*` outranks them by
+    // layer. Appended (never prepended) so it cannot register `astryx-base`
+    // ahead of `reset` and invert the layer order.
+    if (base) {
+      if (dataTokenDefaultsRefCount++ === 0) {
+        const baseStyle = document.createElement('style');
+        baseStyle.setAttribute(dataAttr('theme-base'), '');
+        baseStyle.textContent = `@layer astryx-base {\n${base}\n}`;
+        document.head.appendChild(baseStyle);
+      }
+      cleanups.push(() => {
+        if (--dataTokenDefaultsRefCount === 0) {
+          document.querySelector(`style[${dataAttr('theme-base')}]`)?.remove();
+        }
+      });
     }
 
     // Prose defaults go into @layer reset — lowest priority, scoped to
@@ -154,20 +185,24 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
       document.head.appendChild(compStyle);
     }
 
-    injectedThemes.add(themeKey);
+    if (prose || component) {
+      cleanups.push(() => {
+        // Matched by the astryx id marker, which is always written above.
+        const proseEl = document.querySelector(
+          `style[${dataAttr('theme-prose')}="${theme.name}"][${dataAttr('id')}="${id}"]`,
+        );
+        const compEl = document.querySelector(
+          `style[${dataAttr('theme')}="${theme.name}"][${dataAttr('id')}="${id}"]`,
+        );
+        proseEl?.remove();
+        compEl?.remove();
+      });
+    }
 
     return () => {
-      // Remove both prose and component style tags (matched by the new
-      // astryx id marker, which is always written above).
-      const proseEl = document.querySelector(
-        `style[${dataAttr('theme-prose')}="${theme.name}"][${dataAttr('id')}="${id}"]`,
-      );
-      const compEl = document.querySelector(
-        `style[${dataAttr('theme')}="${theme.name}"][${dataAttr('id')}="${id}"]`,
-      );
-      proseEl?.remove();
-      compEl?.remove();
-      injectedThemes.delete(themeKey);
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
     };
   }, [theme, id]);
 }

package/src/theme/defineTheme.test.ts

@@ -116,6 +116,29 @@ describe('generateThemeCSS', () => {
     expect(css).toContain('font-family: var(--font-family-heading)');
   });
 
+  it('keeps the data palette out of a theme that never mentions it', () => {
+    // That the palette IS declared is covered by `seeds the whole palette
+    // once, at :root` in generateThemeRules.test.ts. It is theme-independent,
+    // so there is nothing about it a theme can be used to assert.
+    const {component} = generateThemeCSS(defineTheme({name: 'chartless'}));
+    expect(component).not.toContain('--color-data-');
+  });
+
+  it('puts only the named data token in the theme block, not its siblings', () => {
+    const theme = defineTheme({
+      name: 'brand-charts',
+      tokens: {'--color-data-categorical-blue': '#00A3FF'},
+    });
+    const {component} = generateThemeCSS(theme);
+    expect(component).toContain('--color-data-categorical-blue: #00A3FF;');
+    // Leaving the siblings out of the theme's own block is what lets a nested
+    // theme inherit a parent's override instead of shadowing it.
+    expect(component).not.toContain('--color-data-categorical-orange');
+    // Defaults reach the stylesheet without entering the theme's own tokens,
+    // which are what `astryx theme build` reports as overrides.
+    expect(theme.tokens['--color-data-categorical-orange']).toBeUndefined();
+  });
+
   it('splits prose into reset layer and components into astryx-theme', () => {
     const theme = defineTheme({
       name: 'split-test',

package/src/theme/derivedVarRegistry.test.ts

@@ -213,6 +213,7 @@ function discoverComponents(): ComponentInfo[] {
 // ---------------------------------------------------------------------------
 
 const DIR_TO_REGISTRY_KEY: Record<string, string> = {
+  Avatar: 'avatar',
   Banner: 'banner',
   Button: 'button',
   Card: 'card',
@@ -221,13 +222,13 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
   Dialog: 'dialog',
   DropdownMenu: 'dropdown-menu',
   Field: 'field',
-  HoverCard: 'hovercard',
+  HoverCard: 'hover-card',
   NumberInput: 'number-input',
   Popover: 'popover',
-  ProgressBar: 'progressbar-mark',
+  ProgressBar: 'progress-bar-mark',
   Section: 'section',
   SegmentedControl: 'segmented-control',
-  TextArea: 'textarea',
+  TextArea: 'text-area',
 };
 
 /**
@@ -279,6 +280,9 @@ const VARS_WITHOUT_DERIVED_MAPPING = new Set([
   '--_thumbnail-hit-inset',
   '--_input-clear-hit-inset',
   '--_input-clear-hit-content',
+  // Placement-driven motion is private Toast behavior. A theme author controls
+  // the surface transform as a whole, not this one offset within it.
+  '--_toast-slide-y',
   // 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,
@@ -292,6 +296,10 @@ const VARS_WITHOUT_DERIVED_MAPPING = new Set([
   // other.
   '--_card-elevation',
   '--_card-ring',
+  // The colour inside that composed ring, for a variant only a theme knows.
+  // It is one component of one shadow in the list, so no standard property
+  // maps onto it either — a theme sets it beside the fill it has to contrast.
+  '--selectable-card-ring-color',
 ]);
 
 // ---------------------------------------------------------------------------
@@ -418,6 +426,21 @@ describe('getDerivedVars', () => {
     expect(getDerivedVars('unknown', 'borderRadius')).toEqual([]);
   });
 
+  it('resolves a deprecated key to the entries of the key that replaced it', () => {
+    // A theme written against the old spelling still selects the element (the
+    // component emits both classes), so its derived vars must still expand —
+    // otherwise the rule lands and the var half of it silently does nothing.
+    expect(getDerivedVars('hovercard', 'borderRadius')).toEqual(
+      getDerivedVars('hover-card', 'borderRadius'),
+    );
+    expect(getDerivedVars('textarea', 'paddingInline')).toEqual(
+      getDerivedVars('text-area', 'paddingInline'),
+    );
+    expect(getDerivedVars('progressbar-mark', 'width')).toEqual(
+      getDerivedVars('progress-bar-mark', 'width'),
+    );
+  });
+
   it('returns empty for unregistered property', () => {
     expect(getDerivedVars('card', 'color')).toEqual([]);
   });

package/src/theme/derivedVarRegistry.ts

@@ -43,6 +43,7 @@ export interface DerivedVarEntry {
  * entries share the same property.
  */
 export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
+  avatar: [{property: 'borderRadius', vars: ['--_avatar-radius']}],
   banner: [{property: 'borderRadius', vars: ['--_banner-radius']}],
   button: [{property: 'borderRadius', vars: ['--_button-radius']}],
   card: [
@@ -66,13 +67,13 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
     {property: 'padding', vars: ['--_dropdown-menu-padding']},
   ],
   field: [{property: 'borderRadius', vars: ['--_field-radius']}],
-  hovercard: [{property: 'borderRadius', vars: ['--_hovercard-radius']}],
+  'hover-card': [{property: 'borderRadius', vars: ['--_hovercard-radius']}],
   'number-input': [
     {property: 'padding', expand: 'container'},
     {property: 'borderRadius', vars: ['--_field-radius']},
   ],
   popover: [{property: 'borderRadius', vars: ['--_popover-radius']}],
-  'progressbar-mark': [
+  'progress-bar-mark': [
     {property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},
     {property: 'height', vars: ['--_progressbar-mark-height'], replaces: true},
   ],
@@ -81,7 +82,7 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
     {property: 'borderRadius', vars: ['--_segmented-control-radius']},
     {property: 'padding', vars: ['--_segmented-control-padding']},
   ],
-  textarea: [
+  'text-area': [
     {
       property: 'paddingInline',
       vars: ['--_textarea-inline-padding'],
@@ -90,6 +91,21 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
   ],
 };
 
+/**
+ * Deprecated component keys → the key that superseded them.
+ *
+ * A renamed target keeps emitting its old class, so a theme written against
+ * the old key still selects the element. Without this the rule would land but
+ * its derived vars would not expand, and the half that travels through a var
+ * (a hover card's radius, a text area's inline padding) would silently do
+ * nothing. Drop these with the classes, in the next major.
+ */
+const DEPRECATED_REGISTRY_KEYS: Record<string, string> = {
+  hovercard: 'hover-card',
+  'progressbar-mark': 'progress-bar-mark',
+  textarea: 'text-area',
+};
+
 /**
  * Look up derived var entries for a component + CSS property.
  * Returns matching entries in priority order, or empty array if none.
@@ -98,7 +114,10 @@ export function getDerivedVars(
   component: string,
   property: string,
 ): DerivedVarEntry[] {
-  const entries = derivedVarRegistry[component];
+  const renamedTo = DEPRECATED_REGISTRY_KEYS[component];
+  const entries =
+    derivedVarRegistry[component] ??
+    (renamedTo ? derivedVarRegistry[renamedTo] : undefined);
   if (!entries) {
     return [];
   }