An open source design system that's fully customizable and agent ready
TypeScript
fix(theme): preserve deprecated target compatibility (#6126)
Cindy Zhang41ab6db2a5d1
diff --git a/.changeset/deprecated-theme-target-guidance.md b/.changeset/deprecated-theme-target-guidance.mdnew file mode 100644index 0000000000..e971c2fd68--- /dev/null+++ b/.changeset/deprecated-theme-target-guidance.md@@ -0,0 +1,11 @@+---+'@astryxdesign/cli': patch+'@astryxdesign/core': patch+'@astryxdesign/theme-neutral': patch+'@astryxdesign/theme-butter': patch+'@astryxdesign/theme-stone': patch+---++[fix] Prefer canonical component target names in maintained themes and new examples while preserving deprecated runtime aliases and released bare prop/state selector classes through the 0.7.0 removal window. Theme discovery labels deprecated targets, theme build warns with each exact canonical replacement, and `astryx upgrade --apply` provides the forward-compatible bare-selector migration.++@cixzhangdiff --git a/apps/docsite/src/__tests__/theming-helpers.test.ts b/apps/docsite/src/__tests__/theming-helpers.test.tsindex c4c4444ded..4da8d500d1 100644--- a/apps/docsite/src/__tests__/theming-helpers.test.ts+++ b/apps/docsite/src/__tests__/theming-helpers.test.ts@@ -97,6 +97,21 @@ describe('theming helpers — buildDefineThemeExample', () => {expect(example).toContain("'status': {");});+ it('excludes deprecated targets from copyable examples', () => {+ const theming: ThemingDoc = {+ targets: [+ {+ className: 'astryx-progressbar-fill',+ deprecatedFor: 'progress-bar-fill',+ },+ {className: 'astryx-progress-bar-fill'},+ ],+ };+ const example = buildDefineThemeExample(theming);+ expect(example).not.toContain("'progressbar-fill'");+ expect(example).toContain("'progress-bar-fill'");+ });+it('returns empty string with no targets', () => {expect(buildDefineThemeExample({targets: []})).toBe('');});diff --git a/apps/docsite/src/app/playground/themeEditor/constants.ts b/apps/docsite/src/app/playground/themeEditor/constants.tsindex 74d73c2c3f..8ad9eda2f7 100644--- a/apps/docsite/src/app/playground/themeEditor/constants.ts+++ b/apps/docsite/src/app/playground/themeEditor/constants.ts@@ -283,7 +283,7 @@ export const COMPONENT_VAR_TO_OVERRIDE: Record<'--card-padding': [{component: 'card', cssProperty: 'padding'}],'--input-radius': [{component: 'text-input', cssProperty: '--_field-radius'},- {component: 'textarea', cssProperty: '--_field-radius'},+ {component: 'text-area', cssProperty: '--_field-radius'},{component: 'selector', cssProperty: '--_field-radius'},],'--banner-radius': [{component: 'banner', cssProperty: 'borderRadius'}],@@ -301,7 +301,9 @@ export const COMPONENT_VAR_TO_OVERRIDE: Record<'--dropdown-padding': [{component: 'dropdown-menu', cssProperty: 'padding'}],'--section-padding': [{component: 'section', cssProperty: 'padding'}],'--popover-radius': [{component: 'popover', cssProperty: 'borderRadius'}],- '--hovercard-radius': [{component: 'hovercard', cssProperty: 'borderRadius'}],+ '--hovercard-radius': [+ {component: 'hover-card', cssProperty: 'borderRadius'},+ ],'--composer-radius': [{component: 'chat-composer', cssProperty: '--_chat-composer-radius'},],@@ -326,9 +328,9 @@ export const ALL_COMPONENT_NAMES = ['chat-composer','chat-message','chat-message-bubble',- 'checkbox',+ 'checkbox-indicator','clickable-card',- 'codeblock',+ 'code-block','collapsible','dialog','divider',@@ -336,14 +338,14 @@ export const ALL_COMPONENT_NAMES = ['empty-state','field','heading',- 'hovercard',+ 'hover-card','icon','link','list','markdown','popover',- 'progressbar',- 'radio',+ 'progress-bar',+ 'radio-indicator','section','segmented-control','selector',@@ -357,7 +359,7 @@ export const ALL_COMPONENT_NAMES = ['table','text','text-input',- 'textarea',+ 'text-area','toast','token','tooltip',diff --git a/apps/docsite/src/components/component-detail/Theming.tsx b/apps/docsite/src/components/component-detail/Theming.tsxindex a0e65ac438..960c400ddc 100644--- a/apps/docsite/src/components/component-detail/Theming.tsx+++ b/apps/docsite/src/components/component-detail/Theming.tsx@@ -66,6 +66,11 @@ function TargetsTable({targets, props}: TargetsTableProps) {<Text type="code" color="secondary">.{target.className}</Text>+ {target.deprecatedFor && (+ <Text type="supporting" color="secondary">+ Deprecated: use {target.deprecatedFor}+ </Text>+ )}{dataAttrs.length > 0 && (<Text type="supporting" color="secondary">Data attrs: {dataAttrs.map(a => `[${a}]`).join(', ')}@@ -93,6 +98,7 @@ function TargetsTable({targets, props}: TargetsTableProps) {const data = targets.map(target => ({key: configKey(target) as unknown,className: target.className as unknown,+ deprecatedFor: (target.deprecatedFor ?? '') as unknown,dataAttrs: targetDataAttributes(target) as unknown,props: targetPropValues(target, props) as unknown,states: (target.states ?? []) as unknown,@@ -126,6 +132,19 @@ function TargetsTable({targets, props}: TargetsTableProps) {</Text>),},+ {+ key: 'deprecatedFor',+ header: 'Status',+ width: pixel(180),+ renderCell: (item: Record<string, unknown>) => {+ const replacement = item.deprecatedFor as string;+ return replacement ? (+ <Text color="secondary">Deprecated: use {replacement}</Text>+ ) : (+ <Text color="secondary">Current</Text>+ );+ },+ },{key: 'dataAttrs',header: 'Data attributes',diff --git a/apps/docsite/src/components/component-detail/themingHelpers.ts b/apps/docsite/src/components/component-detail/themingHelpers.tsindex 406a68d578..2668771332 100644--- a/apps/docsite/src/components/component-detail/themingHelpers.ts+++ b/apps/docsite/src/components/component-detail/themingHelpers.ts@@ -75,13 +75,17 @@ export function targetPropValues(return target.visualProps;}+export function canonicalTargets(theming: ThemingDoc): ThemingTarget[] {+ return theming.targets.filter(target => !target.deprecatedFor);+}+/*** Build the `defineTheme` `components` example, showing the root target's* `base` + a representative prop/state key, plus one sub-element target if the* component exposes more than one. Mirrors the CLI's generated snippet.*/export function buildDefineThemeExample(theming: ThemingDoc): string {- const targets = theming.targets;+ const targets = canonicalTargets(theming);if (!targets.length) {return '';}diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex af2a0913ac..e2058b554b 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -144,5 +144,21 @@{"component": "core/Dialog","reason": "Dialog uses logical inline offsets, logical container spacing, and direction-aware safe-area fallbacks. Its native modal lifecycle, focus entry and return, backdrop, and close glyph are direction-neutral; the directional entry translation follows the invoker's physical viewport position rather than reading direction. Dialog owns no left/right glyph swap, inline reordering, directional scroll or drag action, or horizontal keyboard behavior for the RTL audit to compare."+ },+ {+ "component": "core/HoverCard",+ "reason": "HoverCard delegates anchor geometry and logical placement to Layer and renders a direction-neutral preview surface. It owns no directional glyph, side-specific content order, horizontal scroll or drag behavior, or directional keyboard interaction."+ },+ {+ "component": "core/Indicator",+ "reason": "Indicator renders centered checkbox, radio, check, and indeterminate marks. Their geometry and state transitions are intrinsic and direction-neutral; the component has no inline-axis placement, content ordering, scrolling, dragging, overlay, or keyboard behavior."+ },+ {+ "component": "core/NavIcon",+ "reason": "NavIcon is a centered circular container for caller-owned artwork. The container has symmetric geometry and no inline-axis placement, order, transform, scroll, drag, overlay, or keyboard behavior; directional meaning belongs to the supplied icon."+ },+ {+ "component": "core/StatusDot",+ "reason": "StatusDot is a symmetric painted circle with an optional centered caller-owned icon. Its pulse animation is radial, and it has no inline-axis placement, order, scrolling, dragging, overlay, or directional keyboard behavior."}]diff --git a/apps/storybook/stories/CheckboxInput.stories.tsx b/apps/storybook/stories/CheckboxInput.stories.tsxindex a7bb3d63c9..64e3385584 100644--- a/apps/storybook/stories/CheckboxInput.stories.tsx+++ b/apps/storybook/stories/CheckboxInput.stories.tsx@@ -543,12 +543,12 @@ export const ThemedIndicator: Story = {),};-// Restyling without replacing: the indicator renders the `checkbox` theme-// target, so ordinary component overrides reach it.+// Restyling without replacing: the indicator renders the+// `checkbox-indicator` theme target, so ordinary component overrides reach it.const roundCheckboxTheme = defineTheme({name: 'checkbox-round-demo',components: {- checkbox: {+ 'checkbox-indicator': {base: {borderRadius: 'var(--radius-full)'},checked: {backgroundColor: 'var(--color-positive)',diff --git a/apps/storybook/stories/DateInput.stories.tsx b/apps/storybook/stories/DateInput.stories.tsxindex 1091208f7f..ddba116062 100644--- a/apps/storybook/stories/DateInput.stories.tsx+++ b/apps/storybook/stories/DateInput.stories.tsx@@ -554,16 +554,16 @@ export const StatusVariantComparison: Story = {/*** Theme the clear glyph precisely via `defineTheme`.*- * `components['date-input-clear-icon'].base` scopes overrides to the clear- * icon itself (via the `astryx-date-input-clear-icon` target), so a theme can+ * `components['input-clear-icon'].base` scopes overrides to the clear+ * icon itself (via the `astryx-input-clear-icon` target), so a theme can* recolor it, morph its color on hover, and resize it — without a fragile* descendant selector or raw CSS. Same-element rules in `@layer astryx-theme`* win over the icon's own base color/size.*/const clearIconTheme = defineTheme({- name: 'date-input-clear-icon-demo',+ name: 'input-clear-icon-demo',components: {- 'date-input-clear-icon': {+ 'input-clear-icon': {base: {width: '12px',height: '12px',diff --git a/apps/storybook/stories/DateRangeInput.stories.tsx b/apps/storybook/stories/DateRangeInput.stories.tsxindex 4ae6cf1a63..8a4e7d3b93 100644--- a/apps/storybook/stories/DateRangeInput.stories.tsx+++ b/apps/storybook/stories/DateRangeInput.stories.tsx@@ -387,7 +387,7 @@ export const StatusVariantComparison: Story = {/*** Theme the clear and calendar-toggle glyphs precisely via `defineTheme`.- * `components['date-range-input-clear-icon'].base` and+ * `components['input-clear-icon'].base` and* `components['date-range-input-toggle-icon'].base` scope overrides to the* icons themselves (via the `astryx-date-range-input-*-icon` targets), so a* theme can recolor, hover-morph, and resize them — without a fragile@@ -397,7 +397,7 @@ export const StatusVariantComparison: Story = {const iconTheme = defineTheme({name: 'date-range-input-icon-demo',components: {- 'date-range-input-clear-icon': {+ 'input-clear-icon': {base: {width: '12px',height: '12px',diff --git a/apps/storybook/stories/MultiSelector.stories.tsx b/apps/storybook/stories/MultiSelector.stories.tsxindex 6a712ffafc..0fb31a75c8 100644--- a/apps/storybook/stories/MultiSelector.stories.tsx+++ b/apps/storybook/stories/MultiSelector.stories.tsx@@ -603,8 +603,8 @@ export const StatusVariantComparison: Story = {/*** Theme the clear and chevron glyphs precisely via `defineTheme`.*- * - `components['multi-selector-clear-icon'].base` scopes overrides to the- * clear icon itself (via the `astryx-multi-selector-clear-icon` target), so a+ * - `components['input-clear-icon'].base` scopes overrides to the+ * clear icon itself (via the `astryx-input-clear-icon` target), so a* theme can recolor it, morph its color on hover, and resize it — without a* fragile descendant selector or raw CSS.* - `components['multi-selector-indicator-icon']` scopes overrides to the@@ -617,7 +617,7 @@ export const StatusVariantComparison: Story = {const iconTheme = defineTheme({name: 'multi-selector-icon-demo',components: {- 'multi-selector-clear-icon': {+ 'input-clear-icon': {base: {width: '12px',height: '12px',diff --git a/apps/storybook/stories/ProgressBar.stories.tsx b/apps/storybook/stories/ProgressBar.stories.tsxindex 16461940b4..7b45cae8a7 100644--- a/apps/storybook/stories/ProgressBar.stories.tsx+++ b/apps/storybook/stories/ProgressBar.stories.tsx@@ -314,7 +314,7 @@ export const MarksAcrossVariants: Story = {};export const ThemedMarks: Story = {- // Marks are themeable directly via the `progressbar-mark` target: a theme sets+ // Marks are themeable directly via the `progress-bar-mark` target: a theme sets// `backgroundColor`, `width`, and `height` on it with `defineTheme`. A taller// height overhangs the bar symmetrically above and below. The style block below// stands in for a full theme, in the shape `astryx theme build` emits — thediff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsxindex 10002628a9..48029ebce1 100644--- a/apps/storybook/stories/Selector.stories.tsx+++ b/apps/storybook/stories/Selector.stories.tsx@@ -990,8 +990,7 @@ export const StatusVariantComparison: Story = {* - `components['input-clear-icon'].base` scopes overrides to the clear icon* itself (via the shared canonical `astryx-input-clear-icon` target), so a* theme can recolor it, morph its color on hover, and resize it — without a- * fragile descendant selector or raw CSS. Selector still emits- * `astryx-selector-clear-icon` only as a deprecated compatibility alias.+ * fragile descendant selector or raw CSS.* - `components['selector-indicator-icon']` scopes overrides to the chevron,* and its `state:expanded` restyles the open state, which the icon reflects* as a `data-state` attribute.diff --git a/docs/architecture/component-theming-surface.md b/docs/architecture/component-theming-surface.mdindex 6b04cebde9..6fd0fc27f9 100644--- a/docs/architecture/component-theming-surface.md+++ b/docs/architecture/component-theming-surface.md@@ -177,9 +177,16 @@ but acceptance alone is best effort, not a compatibility promise.on by consumers. Exact mappings remain checked code/metadata, not copied prose;known enforcement gaps are recorded in `architecture:theme-compilation`.- **INV12 — Aliases are compatibility, not anatomy.** Deprecated target aliases- remain released compatibility paths until their approved removal release. They do- not count as current semantic parts. Removing an alias or its supporting metadata- follows `spec:AST-017` as a breaking compatibility change.+ remain released compatibility paths until their approved removal release and do+ not count as current semantic parts. Before removal, `themeProps(..., {legacyNames})` and `ComponentThemingTarget.deprecatedFor` remain generic+ compatibility mechanisms: alias metadata names the exact canonical replacement,+ CLI discovery labels the alias as deprecated, and theme build warns with that+ replacement whenever theme source uses the deprecated key. Maintained published+ Astryx themes, CLI templates, and copyable new examples use canonical keys;+ deprecated aliases remain discoverable for existing consumers but are excluded+ from new examples. Removing an alias or its supporting metadata follows+ `spec:AST-017` as a breaking compatibility change and is not authorized before+ the approved 0.7.0 window below.- **INV13 — Family ownership is explicit.** A family document may own a sharedtarget for several components, but local docs link to that owner rather thanleaving ownership to inference.@@ -263,7 +270,11 @@ how themes become output, or the design rationale for a component's appearance.- Adding or renaming a `themeProps()` target updates its component-spec map,`.doc.mjs` public target metadata, compatibility aliases when required,- generated/CLI discovery, and validation together.+ generated/CLI discovery, and validation together. Before removal, a deprecated+ alias records its exact canonical replacement, continues runtime emission and+ discovery, and produces actionable CLI and theme-build warnings for root and+ media-surface overrides. Maintained published theme sources, CLI templates, and+ copyable new examples use the canonical key and omit the deprecated alias.- Removing the approved deprecated cohort before 0.7.0 violates this record.Removing it in 0.7.0 or later follows `spec:AST-017`, preserves every canonicaltarget and semantic key, migrates built-in/generated themes first, and supplies@@ -300,8 +311,10 @@ how themes become output, or the design rationale for a component's appearance.- Component `.doc.mjs` `usage.anatomy[]` owns the consumer-facing semantic partinventory and contains no theming disposition or maintainer rationale.- Component `.doc.mjs` `theming.targets[]` owns discoverable public targets and- their visual prop/state selector axes. `visualProps` does not declare CSS- property support.+ their visual prop/state selector axes. Deprecated entries retain+ `deprecatedFor` with the exact canonical replacement; they remain discoverable+ compatibility metadata but do not count as current anatomy. `visualProps` does+ not declare CSS property support.- The approved property catalog is owned by this record. Target`guaranteedProperties` declarations will live in component `.doc.mjs``theming.targets[]` once the authoring schema supports them; there is not yet a@@ -314,7 +327,10 @@ how themes become output, or the design rationale for a component's appearance.migration, checked against consumer anatomy, and excluded from generatedconsumer docs. Nearby component-spec prose owns non-obvious rationale,exceptions, and links.-- Runtime `themeProps()` calls emit the target and state contract.+- Runtime `themeProps()` calls emit the canonical target and state contract, and+ their `legacyNames` entries continue emitting deprecated compatibility aliases.+- CLI discovery preserves and labels deprecated entries, while theme build warns+ with each exact canonical replacement and copyable new examples omit aliases.- `scripts/check-knowledge.mjs`, `themingTargets.test.ts`,`extensibleAxes.test.ts`, and `derivedVarRegistry.test.ts` enforce thesource/metadata/generated relationship. `extensibleAxes.test.ts` proves only@@ -335,18 +351,18 @@ how themes become output, or the design rationale for a component's appearance.## Verification-| Invariant | Evidence | Failure signal |-| ------------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| INV1 | Cross-package target/documentation inventory | An exported target in a participating package is invisible to metadata or CLI validation |-| INV2, INV3 | Bidirectional anatomy-disposition/target check | A current target has no semantic part owner, anatomy mechanically creates targets, or `none` silently becomes future policy |-| INV4, INV5 | Component review plus rendered DOM inspection | Public target lands on non-painting plumbing or aliases a child primitive without distinct semantics |-| INV6 | `themingTargets.test.ts` and `extensibleAxes.test.ts` | State/variant is invisible to the owner target or becomes an unnecessary parallel target |-| INV7, INV8 | Existing property fixtures (partial; gaps below) | A declared property is missing evidence, or an unlisted counterpart is treated as implied |-| INV9 | API docs and compatibility review | Generic property acceptance is presented as a supported compatibility promise |-| INV10, INV11 | Existing registry/public-var/runtime tests (partial; gaps below) | A public semantic var bypasses admission, or a consumer must write a private var to reach promised behavior |-| INV12, INV13 | Alias/window inventory, package export/runtime tests, migration mapping, and family-owner fixtures | An alias disappears before 0.7.0, the approved mapping is incomplete, canonical targets change, legacy metadata survives removal without an owner, or cross-doc ownership remains implicit |-| INV14 | Component contract, owner review, focused no-match fallback test, and structural `extensibleAxes.test.ts` coverage | An ineligible axis opens, a missing rule changes behavior unpredictably, or the map/reflection/docs wiring drifts |-| INV15 | Shared root/adaptation component-validation fixtures covering finite, open, enrolled, and unresolved domains | Root and adaptation disagree, a valid open value requires a root style, a rule conditionally enrolls a custom value, or unresolved behavior becomes adaptation-specific |+| Invariant | Evidence | Failure signal |+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| INV1 | Cross-package target/documentation inventory | An exported target in a participating package is invisible to metadata or CLI validation |+| INV2, INV3 | Bidirectional anatomy-disposition/target check | A current target has no semantic part owner, anatomy mechanically creates targets, or `none` silently becomes future policy |+| INV4, INV5 | Component review plus rendered DOM inspection | Public target lands on non-painting plumbing or aliases a child primitive without distinct semantics |+| INV6 | `themingTargets.test.ts` and `extensibleAxes.test.ts` | State/variant is invisible to the owner target or becomes an unnecessary parallel target |+| INV7, INV8 | Existing property fixtures (partial; gaps below) | A declared property is missing evidence, or an unlisted counterpart is treated as implied |+| INV9 | API docs and compatibility review | Generic property acceptance is presented as a supported compatibility promise |+| INV10, INV11 | Existing registry/public-var/runtime tests (partial; gaps below) | A public semantic var bypasses admission, or a consumer must write a private var to reach promised behavior |+| INV12, INV13 | Runtime alias emission, `legacyNames`/`deprecatedFor` metadata, labeled discovery, exact-replacement diagnostics, canonical maintained-theme/template inventory, copyable-example exclusion, migration mapping, and family-owner fixtures | An alias disappears before 0.7.0, lacks its exact replacement warning, appears in a copyable new example, the approved mapping is incomplete, canonical targets change, legacy metadata survives removal without an owner, or ownership stays implicit |+| INV14 | Component contract, owner review, focused no-match fallback test, and structural `extensibleAxes.test.ts` coverage | An ineligible axis opens, a missing rule changes behavior unpredictably, or the map/reflection/docs wiring drifts |+| INV15 | Shared root/adaptation component-validation fixtures covering finite, open, enrolled, and unresolved domains | Root and adaptation disagree, a valid open value requires a root style, a rule conditionally enrolls a custom value, or unresolved behavior becomes adaptation-specific |Known conformance and verification gaps:diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.mdindex a88b1d9e18..2436b83d2f 100644--- a/packages/cli/CHANGELOG.md+++ b/packages/cli/CHANGELOG.md@@ -548,7 +548,7 @@ Thanks to everyone who contributed to this release:Kept honest by a drift harness (docs vs the live CLI), `check:cli-structure` (each doc-type and `api/` leaf ships its full file set), and lint rules for the CLI's layering.- Add themeable indicators — the componentized check, checkbox, and radio visuals. `defineTheme({indicators: {check: RadioIndicator}})` replaces one by name, and every component drawing it follows. (#4712)- Theme targets now follow the component-name convention: `checkbox-indicator`, `radio-indicator`, `radio-indicator-dot`. The old names (`checkbox`, `radio`, `radio-dot`) are still emitted on the same element, so existing themes keep working — migrate at your convenience; they go away in the next major.+ Theme targets now follow the component-name convention: `checkbox-indicator`, `radio-indicator`, `radio-indicator-dot`. The old names (`checkbox`, `radio`, `radio-dot`) remain emitted on the same element so existing themes keep working. New themes should use the canonical names; deprecation does not set an automatic removal deadline.Migration: menu radios use those shared targets now. `dropdown-menu-radio-dot` is removed — target `radio-indicator-dot`; `astryx upgrade` rewrites it for you.diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjsindex c7e2d6fdfe..9c8d57b1db 100644--- a/packages/cli/api/theme/build/build.mjs+++ b/packages/cli/api/theme/build/build.mjs@@ -54,7 +54,7 @@ import {logger} from '../../logger.mjs';import {loadComponentDoc} from '../../../foundation/discovery/component-loader.mjs';import {collectThemingTargets,- targetsByKey,+ targetValidationRegistry,} from '../../../foundation/discovery/theming-targets.mjs';import {collectUnloadedFonts, formatFontLoadingHelp} from './font-warning.mjs';import {interceptCore} from './core-interception.mjs';@@ -1497,32 +1497,30 @@ ${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: DefinedThem/*** Load known theme target keys from core component docs: the visual props AND- * the runtime states each target reflects. Both are legal override keys — the- * Theming Infrastructure wiki documents `radio: {checked}` and- * `'calendar-day': {today, selected}` alongside `button: {'variant:secondary'}`- * — so validation has to know both or documented syntax warns as unknown.- * Returns null when docs are unavailable so validation can skip unknown-key- * warnings rather than guessing from a second registry.+ * runtime states each target reflects, plus canonical replacements for+ * deprecated target keys. Deprecated targets remain accepted for compatibility,+ * but every use receives actionable build guidance. Returns null when docs are+ * unavailable so validation skips warnings rather than guessing from a second+ * registry.*- * Shares its enumeration with `theme targets`, so what a theme author can list- * is exactly what this validator accepts.- *- * @returns {Promise<Record<string, string[]> | null>}+ * @returns {Promise<{propsByKey: Record<string, string[]>, deprecatedByKey: Record<string, string>} | null>}*/async function loadKnownComponents() {const coreRoot = resolveCoreRoot();const coreSrc = coreRoot ? path.join(coreRoot, 'src') : null;if (!coreSrc || !fs.existsSync(coreSrc)) return null;- const targets = targetsByKey(await collectThemingTargets(coreSrc));- return Object.keys(targets).length > 0 ? targets : null;+ const registry = targetValidationRegistry(+ await collectThemingTargets(coreSrc),+ );+ return Object.keys(registry.propsByKey).length > 0 ? registry : null;}-/** @type {Record<string, string[]> | null | undefined} */+/** @type {{propsByKey: Record<string, string[]>, deprecatedByKey: Record<string, string>} | null | undefined} */let knownComponentsCache;/**- * @returns {Promise<Record<string, string[]> | null>}+ * @returns {Promise<{propsByKey: Record<string, string[]>, deprecatedByKey: Record<string, string>} | null>}*/async function getKnownComponents() {if (knownComponentsCache === undefined) {@@ -1532,67 +1530,86 @@ async function getKnownComponents() {}/**- * Validate component overrides in a theme definition.- * Warns on unknown component names and unknown prop names.- * Returns array of warning strings.- * @param {{components?: Record<string, Record<string, unknown>>}} themeDef- * @returns {Promise<string[]>}+ * Validate component overrides against one discovered target registry.+ *+ * @param {{components?: Record<string, Record<string, unknown>>, onDark?: {components?: Record<string, Record<string, unknown>>}, onLight?: {components?: Record<string, Record<string, unknown>>}, __onDark?: {components?: Record<string, Record<string, unknown>>}, __onLight?: {components?: Record<string, Record<string, unknown>>}}} themeDef+ * @param {{propsByKey: Record<string, string[]>, deprecatedByKey: Record<string, string>}} knownComponents+ * @returns {string[]}*/-async function validateComponentOverrides(themeDef) {+export function validateComponentOverridesAgainstRegistry(+ themeDef,+ knownComponents,+) {/** @type {string[]} */const warnings = [];- const componentEntries = themedComponentEntries(themeDef);- if (componentEntries.length === 0) return warnings;+ /** @type {{name: string, components: Record<string, Record<string, unknown>>}[]} */+ const layers = [...getThemeComponentLayers(themeDef)];+ let adaptationIndex = 0;+ for (const value of adaptationRuleValues(themeDef)) {+ adaptationIndex++;+ if (+ value.components &&+ typeof value.components === 'object' &&+ Object.keys(value.components).length > 0+ ) {+ layers.push({+ name: `adaptation rule ${adaptationIndex}`,+ components: value.components,+ });+ }+ }- const knownComponents = await getKnownComponents();- if (knownComponents == null) return warnings;-- for (const [component, rules] of componentEntries) {- // Check component name- if (!(component in knownComponents)) {- const similar = Object.keys(knownComponents)- .filter(k => {- if (k.includes(component) || component.includes(k)) return true;- // Levenshtein distance 1-2 for short names- if (Math.abs(k.length - component.length) <= 2) {- let diff = 0;- const longer = k.length >= component.length ? k : component;- const shorter = k.length < component.length ? k : component;- let j = 0;- for (let i = 0; i < longer.length && diff <= 2; i++) {- if (longer[i] !== shorter[j]) diff++;- else j++;+ for (const {name: layerName, components} of layers) {+ for (const [component, rules] of Object.entries(components)) {+ const location = layerName === 'base' ? '' : ` in ${layerName}`;+ if (!(component in knownComponents.propsByKey)) {+ const similar = Object.keys(knownComponents.propsByKey)+ .filter(k => {+ if (k.includes(component) || component.includes(k)) return true;+ if (Math.abs(k.length - component.length) <= 2) {+ let diff = 0;+ const longer = k.length >= component.length ? k : component;+ const shorter = k.length < component.length ? k : component;+ let j = 0;+ for (let i = 0; i < longer.length && diff <= 2; i++) {+ if (longer[i] !== shorter[j]) diff++;+ else j++;+ }+ diff += shorter.length - j;+ return diff <= 2;}- diff += shorter.length - j;- return diff <= 2;- }- return false;- })- .slice(0, 3);- const hint =- similar.length > 0 ? ` Did you mean: ${similar.join(', ')}?` : '';- warnings.push(`Unknown component "${component}".${hint}`);- continue;- }+ return false;+ })+ .slice(0, 3);+ const hint =+ similar.length > 0 ? ` Did you mean: ${similar.join(', ')}?` : '';+ warnings.push(`Unknown component "${component}".${hint}`);+ continue;+ }- // Check prop/state names in the override keys. A key is either `base`, a- // `prop:value` pair (possibly `+`-joined), or a bare state name.- const knownProps = knownComponents[component];- for (const key of Object.keys(rules)) {- if (key === 'base') continue;-- // Parse prop:value pairs (e.g. 'variant:secondary' or 'variant:destructive+size:sm')- const pairs = key.split('+');- for (const pair of pairs) {- const [prop] = pair.split(':');- if (prop && !knownProps.includes(prop)) {- const hint =- knownProps.length > 0- ? ` Known props/states: ${knownProps.join(', ')}`- : ' This component has no variant props or states.';- warnings.push(- `Unknown prop "${prop}" on component "${component}".${hint}`,- );+ const replacement = knownComponents.deprecatedByKey[component];+ if (replacement != null) {+ warnings.push(+ `Deprecated component target "${component}"${location}. Use "${replacement}" instead.`,+ );+ }++ const knownProps = knownComponents.propsByKey[component];+ for (const key of Object.keys(rules)) {+ if (key === 'base') continue;++ const pairs = key.split('+');+ for (const pair of pairs) {+ const [prop] = pair.split(':');+ if (prop && !knownProps.includes(prop)) {+ const hint =+ knownProps.length > 0+ ? ` Known props/states: ${knownProps.join(', ')}`+ : ' This component has no variant props or states.';+ warnings.push(+ `Unknown prop "${prop}" on component "${component}".${hint}`,+ );+ }}}}@@ -1601,6 +1618,20 @@ async function validateComponentOverrides(themeDef) {return [...new Set(warnings)];}+/**+ * Validate component overrides in a theme definition.+ * Warns on unknown component names, deprecated targets, and unknown prop names.+ *+ * @param {{components?: Record<string, Record<string, unknown>>, onDark?: {components?: Record<string, Record<string, unknown>>}, onLight?: {components?: Record<string, Record<string, unknown>>}, __onDark?: {components?: Record<string, Record<string, unknown>>}, __onLight?: {components?: Record<string, Record<string, unknown>>}}} themeDef+ * @returns {Promise<string[]>}+ */+async function validateComponentOverrides(themeDef) {+ const knownComponents = await getKnownComponents();+ return knownComponents == null+ ? []+ : validateComponentOverridesAgainstRegistry(themeDef, knownComponents);+}+/*** Validate that themes don't set private (--_*) CSS custom properties directly.* Private vars are internal implementation details managed by the derived vardiff --git a/packages/cli/api/theme/build/build.test.mjs b/packages/cli/api/theme/build/build.test.mjsindex ff726d38af..f6306e1500 100644--- a/packages/cli/api/theme/build/build.test.mjs+++ b/packages/cli/api/theme/build/build.test.mjs@@ -23,7 +23,10 @@ import {generateThemeRulesSplit as mockGenerateThemeRulesSplit,generateOnMediaCSS as mockGenerateOnMediaCSS,} from '@astryxdesign/core/theme';-import {themeBuild} from './build.mjs';+import {+ themeBuild,+ validateComponentOverridesAgainstRegistry,+} from './build.mjs';// `themeBuild` captures core's generator once at module load. Wrap the two// CSS-emitting exports in vi.fn (call-through by default) so the receipt tests@@ -351,7 +354,7 @@ describe('themeBuild() — check mode', () => {describe('themeBuild() — component override validation', () => {it('accepts documented state keys without an "Unknown prop" warning', async () => {// The state-key syntax the Theming Infrastructure wiki documents —- // `radio: {checked}`, `calendar-day: {today, selected}` — is declared in+ // `radio-indicator: {checked}`, `calendar-day: {today, selected}` — is declared in// each component's doc under `theming.targets[].states`, not// `visualProps`. `loadKnownComponents()` read only `visualProps`, so every// one of these warned "Unknown prop": documented syntax that looked broken.@@ -362,7 +365,7 @@ describe('themeBuild() — component override validation', () => {name: 'states',tokens: {'--color-bg': '#0a0a0a'},components: {- radio: {+ 'radio-indicator': {checked: {borderColor: 'var(--color-accent)'},'checked+disabled': {opacity: '0.5'},},@@ -409,16 +412,82 @@ describe('themeBuild() — component override validation', () => {`export default {name: 'bogus',tokens: {'--color-bg': '#0a0a0a'},- components: {radio: {notAState: {opacity: '0.5'}}},+ components: {'radio-indicator': {notAState: {opacity: '0.5'}}},};\n`,);const result = await themeBuild('bogus.mjs', {}, {cwd: tmpDir});expect(result?.data.warnings).toEqual([- expect.stringContaining('Unknown prop "notAState" on component "radio"'),+ expect.stringContaining(+ 'Unknown prop "notAState" on component "radio-indicator"',+ ),+ ]);+ });++ it('warns with the exact replacement for deprecated root and media targets', () => {+ const registry = {+ propsByKey: {+ 'old-target': ['variant'],+ 'new-target': ['variant'],+ },+ deprecatedByKey: {'old-target': 'new-target'},+ };++ expect(+ validateComponentOverridesAgainstRegistry(+ {+ components: {+ 'old-target': {base: {color: 'red'}},+ 'new-target': {base: {color: 'blue'}},+ },+ onDark: {+ components: {+ 'old-target': {'variant:quiet': {color: 'pink'}},+ },+ },+ adaptations: {+ rules: [+ {+ when: {contrast: 'more'},+ value: {+ components: {+ 'old-target': {'variant:loud': {color: 'purple'}},+ },+ },+ },+ ],+ },+ },+ registry,+ ),+ ).toEqual([+ 'Deprecated component target "old-target". Use "new-target" instead.',+ 'Deprecated component target "old-target" in onDark. Use "new-target" instead.',+ 'Deprecated component target "old-target" in adaptation rule 1. Use "new-target" instead.',]);});++ it('warns with the exact replacement for a supported deprecated target', async () => {+ const themeFile = path.join(tmpDir, 'deprecated-target.mjs');+ fs.writeFileSync(+ themeFile,+ `export default {+ name: 'deprecated-target',+ tokens: {},+ components: {progressbar: {base: {color: 'red'}}},+ };\n`,+ );++ const result = await themeBuild('deprecated-target.mjs', {}, {cwd: tmpDir});++ expect(result?.data.warnings).toContain(+ 'Deprecated component target "progressbar". Use "progress-bar" instead.',+ );+ expect(+ fs.readFileSync(path.join(tmpDir, 'deprecated-target.css'), 'utf8'),+ ).toContain('.astryx-progressbar');+ });});describe('themeBuild() — the shipped theme template', () => {diff --git a/packages/cli/api/theme/targets/targets.test.mjs b/packages/cli/api/theme/targets/targets.test.mjsindex c5ca12ae93..39eac1904e 100644--- a/packages/cli/api/theme/targets/targets.test.mjs+++ b/packages/cli/api/theme/targets/targets.test.mjs@@ -16,14 +16,28 @@ describe('themeTargets (api/theme/targets)', () => {expect(result.data.filter).toBeNull();expect(result.data.targets.length).toBeGreaterThan(100);expect(result.data.componentCount).toBeGreaterThan(50);- for (const t of result.data.targets) {- expect(Object.keys(t).sort()).toEqual([- 'className',- 'component',- 'key',- 'props',- 'states',- ]);+ const allowedKeys = new Set([+ 'className',+ 'component',+ 'deprecatedFor',+ 'key',+ 'props',+ 'states',+ ]);+ for (const target of result.data.targets) {+ expect(target).toMatchObject({+ className: expect.any(String),+ component: expect.any(String),+ key: expect.any(String),+ props: expect.any(Array),+ states: expect.any(Array),+ });+ expect(Object.keys(target).filter(key => !allowedKeys.has(key))).toEqual(+ [],+ );+ if (target.deprecatedFor !== undefined) {+ expect(target.deprecatedFor).toEqual(expect.any(String));+ }}}, 60_000);diff --git a/packages/cli/api/theme/theme.type.mjs b/packages/cli/api/theme/theme.type.mjsindex 005fa1641f..f6d15cc2a7 100644--- a/packages/cli/api/theme/theme.type.mjs+++ b/packages/cli/api/theme/theme.type.mjs@@ -90,6 +90,7 @@* @property {string} component* @property {string[]} props* @property {string[]} states+ * @property {string} [deprecatedFor] - exact canonical replacement for a deprecated target*//**diff --git a/packages/cli/api/theme/themeBuild.doc.mjs b/packages/cli/api/theme/themeBuild.doc.mjsindex 354ab1c975..111231070f 100644--- a/packages/cli/api/theme/themeBuild.doc.mjs+++ b/packages/cli/api/theme/themeBuild.doc.mjs@@ -73,7 +73,7 @@ export const doc = {{type: 'theme.build',description:- 'Build receipt: theme name, token- and component-override counts, output size in KB, the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}, and any validation warnings. Resolves to null instead when the theme produced no CSS (nothing to build).',+ 'Build receipt: theme name, token- and component-override counts, output size in KB, the written outputs {css, js, dts, and variantsDts when custom prop values were augmented}, and validation warnings—including exact canonical replacements for deprecated component target keys. Resolves to null instead when the theme produced no CSS (nothing to build).',},{type: 'theme.build.check',diff --git a/packages/cli/api/theme/themeTargets.doc.mjs b/packages/cli/api/theme/themeTargets.doc.mjsindex cdae20f048..2e2a403130 100644--- a/packages/cli/api/theme/themeTargets.doc.mjs+++ b/packages/cli/api/theme/themeTargets.doc.mjs@@ -16,15 +16,25 @@ export const doc = {summary: 'List every component theming target a theme can override.',description:'Enumerates the whole themeable surface: each `defineTheme` components key, the stable ' +- 'class it paints, the component that declares it, and the props and states that are legal ' +- 'override keys under it. Same source as the Theming table `astryx component <Name>` prints ' ++ 'class it paints, the component that declares it, the props and states that are legal ' ++ 'override keys under it, and the canonical replacement when a listed target is deprecated. ' ++ 'Same source as the Theming table `astryx component <Name>` prints ' +'(the component docs), so the list cannot drift from the components, and `theme build` ' +'validates overrides against this exact set. A filter naming a component gives that ' +- 'component\'s set; anything else is a substring search over the keys.',+ "component's set; anything else is a substring search over the keys.",importPath: '@astryxdesign/cli/api',signature:'themeTargets(filter?: string, ctx?: {cwd?: string}): Promise<ThemeTargetsResponse>',- keywords: ['theme', 'targets', 'defineTheme', 'components', 'override', 'class', 'states', 'audit'],+ keywords: [+ 'theme',+ 'targets',+ 'defineTheme',+ 'components',+ 'override',+ 'class',+ 'states',+ 'audit',+ ],params: [{name: 'filter',@@ -35,18 +45,22 @@ export const doc = {{name: 'ctx.cwd',type: 'string',- description: 'Directory the project\'s @astryxdesign/core is resolved from.',+ description:+ "Directory the project's @astryxdesign/core is resolved from.",},],returns: [{type: 'theme.targets',description:- 'The echoed filter, how many components are represented, and the targets: each {key, className, component, props, states}.',+ 'The echoed filter, how many components are represented, and the targets: each {key, className, component, props, states, deprecatedFor?}.',},],throws: [- {code: 'ERR_CORE_NOT_FOUND', when: '@astryxdesign/core cannot be resolved from cwd'},+ {+ code: 'ERR_CORE_NOT_FOUND',+ when: '@astryxdesign/core cannot be resolved from cwd',+ },{code: 'ERR_UNKNOWN_COMPONENT', when: 'a filter matches no target'},],examples: [diff --git a/packages/cli/assets/docs/styling.doc.mjs b/packages/cli/assets/docs/styling.doc.mjsindex 1a3638ac12..34e8b77c5b 100644--- a/packages/cli/assets/docs/styling.doc.mjs+++ b/packages/cli/assets/docs/styling.doc.mjs@@ -268,12 +268,12 @@ const overrides = stylex.create({],},{- title: 'Removed: Bare Prop and State Classes',+ title: 'Deprecated: Bare Prop and State Classes',category: 'guide',content: [{type: 'prose',- text: 'Astryx no longer emits bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked`. Run `astryx upgrade --apply` to parse `.css` files and rewrite selectors qualified by a known Astryx target when the 0.5.4 target/value pair has one or more known meanings. Declarations, comments, JavaScript/TypeScript strings, and unqualified classes are never rewritten. Stable base target classes (`.astryx-button`, `.astryx-card`, etc.) remain unchanged.',+ text: 'Astryx continues to emit deprecated bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` through the 0.7.0 removal window. Prefer the explicit reflected data attributes for new CSS, and run `astryx upgrade --apply` before 0.7.0 to parse `.css` files and rewrite selectors qualified by a known Astryx target when the 0.5.4 target/value pair has one or more known meanings. Declarations, comments, JavaScript/TypeScript strings, and unqualified classes are never rewritten. Stable base target classes (`.astryx-button`, `.astryx-card`, etc.) remain unchanged.',},{type: 'code',@@ -290,7 +290,7 @@ const overrides = stylex.create({},{type: 'prose',- text: 'Each known old value becomes a specificity-preserving `:is(...)` union containing the original class arm plus every v0.5.4 data-attribute arm. The class arm preserves consumer-supplied `className` matches; the attribute arms match v0.6 props and states. Narrow the union later only when class provenance or prop-axis intent is known. Custom/unknown qualified classes and unqualified classes stay unchanged. Search for unqualified old values such as `.primary` or `.sm` and migrate only confirmed Astryx uses manually. Migrate selectors embedded in JavaScript or TypeScript manually with the same rules.',+ text: 'Each known old value becomes a specificity-preserving `:is(...)` union containing the original class arm plus every v0.5.4 data-attribute arm. Both arms match Astryx output during the deprecation window; the data-attribute arm continues matching after the bare compatibility classes are eligible for removal in 0.7.0. The class arm also preserves consumer-supplied `className` matches. Narrow the union later only when class provenance or prop-axis intent is known. Custom/unknown qualified classes and unqualified classes stay unchanged. Search for unqualified old values such as `.primary` or `.sm` and migrate only confirmed Astryx uses manually. Migrate selectors embedded in JavaScript or TypeScript manually with the same rules.',},],},diff --git a/packages/cli/assets/templates/themes/butter/butterTheme.ts b/packages/cli/assets/templates/themes/butter/butterTheme.tsindex 0b15bcb464..641db25868 100644--- a/packages/cli/assets/templates/themes/butter/butterTheme.ts+++ b/packages/cli/assets/templates/themes/butter/butterTheme.ts@@ -424,12 +424,12 @@ export const butterTheme = defineTheme({// Progress bar — white track in light, warm brown in dark. Vivid// semantic fills match the banner colors (Success / Warning / Error).- 'progressbar-track': {+ 'progress-bar-track': {base: {backgroundColor: 'light-dark(#e5e3d4, #725538)',},},- 'progressbar-fill': {+ 'progress-bar-fill': {'variant:success': {backgroundColor: '#91D143',},@@ -473,7 +473,7 @@ export const butterTheme = defineTheme({'status:warning': {'--color-warning': '#ffc502'},'status:error': {'--color-error': '#fc473b'},},- textarea: {+ 'text-area': {base: {paddingBlock: 'var(--spacing-2)',paddingInline: 'var(--spacing-3)',diff --git a/packages/cli/assets/templates/themes/neutral/neutralTheme.ts b/packages/cli/assets/templates/themes/neutral/neutralTheme.tsindex b14080171e..af615504cd 100644--- a/packages/cli/assets/templates/themes/neutral/neutralTheme.ts+++ b/packages/cli/assets/templates/themes/neutral/neutralTheme.ts@@ -348,7 +348,7 @@ export const neutralTheme = defineTheme({},},- statusdot: {+ 'status-dot': {'variant:success': {backgroundColor: statusFill.success},'variant:warning': {backgroundColor: statusFill.warning},'variant:error': {backgroundColor: statusFill.error},@@ -427,7 +427,7 @@ export const neutralTheme = defineTheme({},},- progressbar: {+ 'progress-bar': {base: {'--color-background-muted': 'var(--color-border-emphasized)',},diff --git a/packages/cli/assets/templates/themes/stone/stoneTheme.ts b/packages/cli/assets/templates/themes/stone/stoneTheme.tsindex e70386bde6..a1e5d2ef1d 100644--- a/packages/cli/assets/templates/themes/stone/stoneTheme.ts+++ b/packages/cli/assets/templates/themes/stone/stoneTheme.ts@@ -324,7 +324,7 @@ export const stoneTheme = defineTheme({// the same color family as the matching status surface). Dark = T70.// Hexes from the preview Tonal Palettes ramp. accent (default) +// indeterminate both route to blue for the in-progress / loading look.- 'progressbar-fill': {+ 'progress-bar-fill': {'variant:accent': {backgroundColor: 'light-dark(#d7e4f5, #a0acbc)', // Blue T90 / T70},@@ -341,7 +341,7 @@ export const stoneTheme = defineTheme({// Track default --color-background-muted reads near-body in stone;// redirect to --color-skeleton so the channel stays visible.- 'progressbar-track': {+ 'progress-bar-track': {base: {backgroundColor: 'var(--color-skeleton)',},@@ -373,7 +373,7 @@ export const stoneTheme = defineTheme({// Input status borders + icons across all 9 input components share the// same softer T60/T70 redirection. See INPUT_STATUS_VARS above.'text-input': INPUT_STATUS_VARS,- textarea: INPUT_STATUS_VARS,+ 'text-area': INPUT_STATUS_VARS,'number-input': INPUT_STATUS_VARS,'date-input': INPUT_STATUS_VARS,'time-input': INPUT_STATUS_VARS,diff --git a/packages/cli/assets/theme.template.ts b/packages/cli/assets/theme.template.tsindex 03b9b40ba7..6b18639a2d 100644--- a/packages/cli/assets/theme.template.ts+++ b/packages/cli/assets/theme.template.ts@@ -235,7 +235,7 @@ export const myTheme = defineTheme({//// Keys are the component's stable class minus the `astryx-` prefix// (`astryx-button` → `button`, `astryx-side-nav-item` → `side-nav-item`),- // including inner parts like `progressbar-fill`.+ // including inner parts like `progress-bar-fill`.//// `astryx component <Name>` IS THE REFERENCE HERE. It prints that// component's theming targets, the visual props and states you can key on,diff --git a/packages/cli/authoring/doctypes/base/type.ts b/packages/cli/authoring/doctypes/base/type.tsindex 80e31aacce..0db4167261 100644--- a/packages/cli/authoring/doctypes/base/type.ts+++ b/packages/cli/authoring/doctypes/base/type.ts@@ -457,14 +457,14 @@ export interface ComponentThemingTarget {* selectors such as `[data-checked="checked"]`. Omit if the element has no* state-driven selectors. */states?: string[];- /** Set when this target has been RENAMED and this entry is the old name.- * The component still emits the class (via `themeProps`'s `legacyNames`),- * so existing themes keep working, but the docsite should steer readers to- * the replacement. The value is the class name that supersedes this one,+ /** Set when this target has been renamed and this entry is the old name.+ * The component continues emitting the class through `themeProps`'s+ * `legacyNames`, so existing themes keep working while discovery and build+ * guidance prefer the replacement. The value is the canonical target key* without the `astryx-` prefix — e.g. `"checkbox-indicator"`.*- * A theme target is public API; renaming one without this is a silent- * break for every theme styling it. */+ * A theme target is public API; deprecation alone does not authorize+ * removing either this metadata or runtime support. */deprecatedFor?: string;}diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjsindex eebce7e52c..afec3af87a 100644--- a/packages/cli/clients/cli/commands/build-theme.mjs+++ b/packages/cli/clients/cli/commands/build-theme.mjs@@ -215,7 +215,9 @@ function printThemeList(themes) {*/function formatTargetsTable(targets) {const rows = targets.map(t => ({- key: t.key,+ key: t.deprecatedFor+ ? `${t.key} [deprecated; use ${t.deprecatedFor}]`+ : t.key,component: t.component,props: t.props.join(', ') || '-',states: t.states.join(', ') || '-',@@ -299,10 +301,13 @@ export function registerTheme(program) {name: command.name(),reason: 'available subcommand',}));- return cliError(`unknown subcommand 'theme palette ${String(extras[0])}'`, {- suggestions,- code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,- });+ return cliError(+ `unknown subcommand 'theme palette ${String(extras[0])}'`,+ {+ suggestions,+ code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,+ },+ );}palette.help();return NO_RESULT_SET;diff --git a/packages/cli/clients/cli/commands/build-theme.variants.test.mjs b/packages/cli/clients/cli/commands/build-theme.variants.test.mjsindex 6650c2eab1..1a386314d1 100644--- a/packages/cli/clients/cli/commands/build-theme.variants.test.mjs+++ b/packages/cli/clients/cli/commands/build-theme.variants.test.mjs@@ -143,22 +143,25 @@ describe('theme build custom-variant augmentations', () => {path.join(tmpDir, 'variants-theme.css'),'utf-8',);- const mainTypeIndex = css.indexOf(- '.astryx-heading[data-type="hero"]',- );+ const mainTypeIndex = css.indexOf('.astryx-heading[data-type="hero"]');const mainTypeWeightIndex = css.indexOf('font-weight: 300;', mainTypeIndex);- const mainWeightIndex = css.indexOf(- '.astryx-heading[data-weight="bold"]',+ const mainWeightIndex = css.indexOf('.astryx-heading[data-weight="bold"]');+ const mainWeightValueIndex = css.indexOf(+ 'font-weight: 900;',+ mainWeightIndex,);- const mainWeightValueIndex = css.indexOf('font-weight: 900;', mainWeightIndex);- const mediaTypeIndex = css.lastIndexOf(- '.astryx-heading[data-type="hero"]',+ const mediaTypeIndex = css.lastIndexOf('.astryx-heading[data-type="hero"]');+ const mediaTypeWeightIndex = css.indexOf(+ 'font-weight: 350;',+ mediaTypeIndex,);- const mediaTypeWeightIndex = css.indexOf('font-weight: 350;', mediaTypeIndex);const mediaWeightIndex = css.lastIndexOf('.astryx-heading[data-weight="bold"]',);- const mediaWeightValueIndex = css.indexOf('font-weight: 800;', mediaWeightIndex);+ const mediaWeightValueIndex = css.indexOf(+ 'font-weight: 800;',+ mediaWeightIndex,+ );expect(mainTypeWeightIndex).toBeGreaterThan(mainTypeIndex);expect(mainWeightValueIndex).toBeGreaterThan(mainWeightIndex);expect(mediaTypeWeightIndex).toBeGreaterThan(mediaTypeIndex);@@ -342,9 +345,9 @@ describe('theme build custom-variant augmentations', () => {divider: { 'variant:customDivider': { borderColor: 'currentColor' } },'field-status': { 'variant:customFieldStatus': { color: 'currentColor' } },pagination: { 'variant:customPagination': { color: 'currentColor' } },- progressbar: { 'variant:customProgressBar': { backgroundColor: 'transparent' } },+ 'progress-bar': { 'variant:customProgressBar': { backgroundColor: 'transparent' } },section: { 'variant:customSection': { backgroundColor: 'transparent' } },- statusdot: { 'variant:customStatusDot': { backgroundColor: 'transparent' } },+ 'status-dot': { 'variant:customStatusDot': { backgroundColor: 'transparent' } },heading: { 'type:customHeading': { fontSize: '3rem' } },text: { 'color:customTextColor': { color: 'currentColor' } },token: { 'color:customTokenColor': { backgroundColor: 'transparent' } },diff --git a/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs b/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjsindex b741725e10..d10d813822 100644--- a/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs+++ b/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs@@ -22,18 +22,35 @@ describe('astryx theme targets', () => {expect(stdout).toMatch(/4 across 1 component/);});+ it('labels deprecated targets with their exact canonical replacement', async () => {+ const {status, stdout} = await runCli(['theme', 'targets', 'Popover']);++ expect(status).toBe(0);+ expect(stdout).toMatch(/^popover\s{2,}Popover/m);+ expect(stdout).toMatch(+ /^popover-surface \[deprecated; use popover\]\s{2,}Popover/m,+ );+ });+it('lists the whole surface when unfiltered', async () => {const {status, stdout} = await runCli(['theme', 'targets']);expect(status).toBe(0);- const rows = stdout.split('\n').filter(l => /^[a-z][a-z0-9-]*\s{2,}/.test(l));+ const rows = stdout+ .split('\n')+ .filter(l => /^[a-z][a-z0-9-]*\s{2,}/.test(l));expect(rows.length).toBeGreaterThan(100);expect(stdout).toMatch(/^button\s/m);expect(stdout).toMatch(/^switch-thumb\s/m);}, 30_000);it('returns a theme.targets envelope under --json', async () => {- const {status, stdout} = await runCli(['--json', 'theme', 'targets', 'Switch']);+ const {status, stdout} = await runCli([+ '--json',+ 'theme',+ 'targets',+ 'Switch',+ ]);expect(status).toBe(0);const payload = JSON.parse(stdout);diff --git a/packages/cli/clients/cli/lib/component-format.mjs b/packages/cli/clients/cli/lib/component-format.mjsindex 972f16c86c..0fa16e2f66 100644--- a/packages/cli/clients/cli/lib/component-format.mjs+++ b/packages/cli/clients/cli/lib/component-format.mjs@@ -26,6 +26,15 @@ function targetKey(target) {return target.className.replace(/^astryx-/, '');}+/**+ * Keep deprecated targets visible in reference tables while excluding them from+ * snippets readers copy into newly authored themes.+ * @param {import('@astryxdesign/cli/authoring').ComponentThemingTarget[]} targets+ */+function canonicalTargets(targets) {+ return targets.filter(target => target.deprecatedFor == null);+}+/** @param {string} name @returns {string} */function dataAttrForName(name) {return `data-${name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}`;@@ -187,8 +196,11 @@ function formatTargetsTable(docs, themeData) {const dataAttrsStr =dataAttrs.length > 0 ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '—';+ const className = target.deprecatedFor+ ? `\`${target.className}\` _(deprecated; use \`${target.deprecatedFor}\`)_`+ : `\`${target.className}\``;lines.push(- `| \`${target.className}\` | ${dataAttrsStr} | ${variantsStr} | ${statesStr} |`,+ `| ${className} | ${dataAttrsStr} | ${variantsStr} | ${statesStr} |`,);}@@ -287,35 +299,37 @@ export function formatFull(docs, options = {}) {}}- // Generate defineTheme example with component selector targeting- const exampleLines = ['Override in defineTheme:\n```ts\ncomponents: {'];- const rootTarget = docs.theming.targets[0];- const rootKey = targetKey(rootTarget);- exampleLines.push(` '${rootKey}': {`);- exampleLines.push(` base: { /* CSS properties */ },`);- if (rootTarget.visualProps?.length) {- const firstVariant = rootTarget.visualProps[0];- exampleLines.push(` '${firstVariant}:value': { /* variant-specific */ },`);- }- if (rootTarget.states?.length) {- const firstState = rootTarget.states[0];- exampleLines.push(` '${firstState}': { /* state-specific */ },`);- }- exampleLines.push(` },`);- // Show sub-element example if there are multiple targets- if (docs.theming.targets.length > 1) {- const subTarget = docs.theming.targets[1];- const subKey = targetKey(subTarget);- exampleLines.push(` '${subKey}': {`);+ // Generate defineTheme example with canonical component selectors only.+ const exampleTargets = canonicalTargets(docs.theming.targets);+ if (exampleTargets.length > 0) {+ const exampleLines = ['Override in defineTheme:\n```ts\ncomponents: {'];+ const rootTarget = exampleTargets[0];+ const rootKey = targetKey(rootTarget);+ exampleLines.push(` '${rootKey}': {`);exampleLines.push(` base: { /* CSS properties */ },`);- if (subTarget.states?.length) {- const firstState = subTarget.states[0];+ if (rootTarget.visualProps?.length) {+ const firstVariant = rootTarget.visualProps[0];+ exampleLines.push(` '${firstVariant}:value': { /* variant-specific */ },`);+ }+ if (rootTarget.states?.length) {+ const firstState = rootTarget.states[0];exampleLines.push(` '${firstState}': { /* state-specific */ },`);}exampleLines.push(` },`);+ if (exampleTargets.length > 1) {+ const subTarget = exampleTargets[1];+ const subKey = targetKey(subTarget);+ exampleLines.push(` '${subKey}': {`);+ exampleLines.push(` base: { /* CSS properties */ },`);+ if (subTarget.states?.length) {+ const firstState = subTarget.states[0];+ exampleLines.push(` '${firstState}': { /* state-specific */ },`);+ }+ exampleLines.push(` },`);+ }+ exampleLines.push('}\n```\n');+ sections.push(exampleLines.join('\n'));}- exampleLines.push('}\n```\n');- sections.push(exampleLines.join('\n'));}// Legacy componentKey (for backward compatibility)@@ -342,7 +356,8 @@ export function formatFull(docs, options = {}) {// Show derived property examples — the recommended way to themeif (docs.theming?.derived?.length) {- const varsKey = docs.theming.targets?.length ? targetKey(docs.theming.targets[0]) : docs.theming.componentKey || '';+ const canonical = canonicalTargets(docs.theming.targets || []);+ const varsKey = canonical.length ? targetKey(canonical[0]) : docs.theming.componentKey || '';const derivedExamples = docs.theming.derived.filter((/** @type {any} */ d) => d.vars?.length).map((/** @type {any} */ d) => ` ${d.property}: '...',`)@@ -564,6 +579,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {const { themeData = null } = options;const targetParts = docs.theming.targets.map((/** @type {any} */ t) => {const parts = [t.className];+ if (t.deprecatedFor) parts.push(`deprecated→${t.deprecatedFor}`);const dataAttrs = getTargetDataAttributes(t);if (dataAttrs.length) parts.push(`preferred attrs: ${dataAttrs.join(', ')}`);if (t.visualProps?.length) parts.push(`variants: ${t.visualProps.join(', ')}`);diff --git a/packages/cli/clients/cli/lib/component-format.test.mjs b/packages/cli/clients/cli/lib/component-format.test.mjsindex 7699930fe0..510284627c 100644--- a/packages/cli/clients/cli/lib/component-format.test.mjs+++ b/packages/cli/clients/cli/lib/component-format.test.mjs@@ -115,7 +115,7 @@ describe('formatFull theming override keys', () => {description: 'A table.',theming: {targets: [- {className: 'astryx-base-table'},+ {className: 'astryx-table-header'},{className: 'astryx-table-cell'},],},@@ -123,14 +123,45 @@ describe('formatFull theming override keys', () => {const out = formatFull(docs);// Correct keys: class name minus the astryx- prefix.- expect(out).toContain("'base-table': {");+ expect(out).toContain("'table-header': {");expect(out).toContain("'table-cell': {");// The verbatim DOM class names must not be advertised as override keys.- expect(out).not.toContain("'astryx-base-table': {");+ expect(out).not.toContain("'astryx-table-header': {");expect(out).not.toContain("'astryx-table-cell': {");});});+describe('deprecated theming target guidance', () => {+ const docs = {+ name: 'Example',+ description: 'An example.',+ theming: {+ targets: [+ {className: 'astryx-old-target', deprecatedFor: 'new-target'},+ {className: 'astryx-new-target'},+ ],+ },+ };++ it('names the canonical replacement in full component docs', () => {+ expect(formatFull(docs)).toContain(+ '`astryx-old-target` _(deprecated; use `new-target`)_',+ );+ });++ it('excludes deprecated targets from copyable defineTheme examples', () => {+ const out = formatFull(docs);+ expect(out).not.toContain("'old-target': {");+ expect(out).toContain("'new-target': {");+ });++ it('keeps the replacement in brief agent guidance', () => {+ expect(formatBrief(docs, 'Example')).toContain(+ 'astryx-old-target deprecated→new-target',+ );+ });+});+/** Pipes that actually separate cells — a `\|` is content, not a separator. */function cellPipes(row) {return (row.match(/(?<!\\)\|/g) || []).length;diff --git a/packages/cli/foundation/discovery/theming-targets.mjs b/packages/cli/foundation/discovery/theming-targets.mjsindex 01da5bccb1..adbea41ff1 100644--- a/packages/cli/foundation/discovery/theming-targets.mjs+++ b/packages/cli/foundation/discovery/theming-targets.mjs@@ -28,6 +28,7 @@ const SKIP_DIRS = new Set(['node_modules', '__tests__']);* @property {string} component - the component whose doc declares it* @property {string[]} props - visual props the target reflects (`variant:value` keys)* @property {string[]} states - runtime states the target reflects (bare-name keys)+ * @property {string} [deprecatedFor] - canonical replacement key for a deprecated target*//**@@ -104,6 +105,9 @@ export async function collectThemingTargets(typeof doc?.subComponentOf === 'string' ? doc.subComponentOf : null,props: stringList(target.visualProps),states: stringList(target.states),+ ...(typeof target.deprecatedFor === 'string'+ ? {deprecatedFor: target.deprecatedFor}+ : {}),});}}@@ -113,7 +117,8 @@ export async function collectThemingTargets(const canonical = canonicalizeParentTargets(targets);canonical.sort(- (a, b) => a.key.localeCompare(b.key) || a.component.localeCompare(b.component),+ (a, b) =>+ a.key.localeCompare(b.key) || a.component.localeCompare(b.component),);return canonical;}@@ -146,12 +151,14 @@ function canonicalizeParentTargets(targets) {for (const target of targets) {if (target.parent == null) continue;const roots =- rootsByComponentAndClass.get(`${target.parent}\0${target.className}`) ?? [];+ rootsByComponentAndClass.get(`${target.parent}\0${target.className}`) ??+ [];if (roots.length !== 1) continue;const canonical = roots[0];canonical.props = [...new Set([...canonical.props, ...target.props])];canonical.states = [...new Set([...canonical.states, ...target.states])];+ canonical.deprecatedFor ??= target.deprecatedFor;duplicates.add(target);}@@ -238,11 +245,40 @@ export function targetsByKey(targets) {/** @type {Record<string, string[]>} */const byKey = {};for (const t of targets) {- byKey[t.key] = [...new Set([...(byKey[t.key] || []), ...t.props, ...t.states])];+ byKey[t.key] = [+ ...new Set([...(byKey[t.key] || []), ...t.props, ...t.states]),+ ];}return byKey;}+/**+ * Build the component-validation registry from the same target rows used by+ * `theme targets`. Deprecated keys stay accepted during their compatibility+ * window, while the replacement map lets theme build issue exact guidance.+ *+ * @param {ThemingTarget[]} targets+ * @returns {{propsByKey: Record<string, string[]>, deprecatedByKey: Record<string, string>}}+ */+export function targetValidationRegistry(targets) {+ const propsByKey = targetsByKey(targets);+ /** @type {Record<string, string>} */+ const deprecatedByKey = {};++ for (const target of targets) {+ if (target.deprecatedFor == null) continue;+ const existing = deprecatedByKey[target.key];+ if (existing != null && existing !== target.deprecatedFor) {+ throw new Error(+ `Deprecated theme target "${target.key}" has conflicting replacements: "${existing}" and "${target.deprecatedFor}".`,+ );+ }+ deprecatedByKey[target.key] = target.deprecatedFor;+ }++ return {propsByKey, deprecatedByKey};+}+/*** @param {unknown} value* @returns {string[]}diff --git a/packages/cli/foundation/discovery/theming-targets.test.mjs b/packages/cli/foundation/discovery/theming-targets.test.mjsindex 069b95177e..0377a1dae4 100644--- a/packages/cli/foundation/discovery/theming-targets.test.mjs+++ b/packages/cli/foundation/discovery/theming-targets.test.mjs@@ -34,10 +34,62 @@ import {collectThemingTargets,collectThemingVars,targetsByKey,+ targetValidationRegistry,} from './theming-targets.mjs';const coreDir = /** @type {string} */ (findCoreDir(process.cwd()));const coreSrc = path.join(coreDir, 'src');+const repoRoot = path.resolve(coreDir, '../..');++const DEPRECATED_TARGETS = {+ 'base-table': 'table',+ checkbox: 'checkbox-indicator',+ codeblock: 'code-block',+ 'codeblock-copy-button': 'code-block-copy-button',+ 'codeblock-header': 'code-block-header',+ 'codeblock-title': 'code-block-title',+ 'date-input-clear-icon': 'input-clear-icon',+ 'date-range-input-clear-icon': 'input-clear-icon',+ hovercard: 'hover-card',+ 'multi-selector-clear-icon': 'input-clear-icon',+ navicon: 'nav-icon',+ 'popover-surface': 'popover',+ progressbar: 'progress-bar',+ 'progressbar-fill': 'progress-bar-fill',+ 'progressbar-mark': 'progress-bar-mark',+ 'progressbar-track': 'progress-bar-track',+ radio: 'radio-indicator',+ 'radio-dot': 'radio-indicator-dot',+ 'selector-clear-icon': 'input-clear-icon',+ statusdot: 'status-dot',+ textarea: 'text-area',+};++/** Return the source text inside a static `components: {…}` object. */+function componentsObjectSource(source) {+ const match = /\bcomponents\s*:\s*\{/.exec(source);+ if (match == null) return '';+ const start = match.index + match[0].length - 1;+ let depth = 0;+ let quote = null;+ let escaped = false;+ for (let index = start; index < source.length; index++) {+ const char = source[index];+ if (quote != null) {+ if (escaped) escaped = false;+ else if (char === '\\') escaped = true;+ else if (char === quote) quote = null;+ continue;+ }+ if (char === "'" || char === '"' || char === '`') {+ quote = char;+ continue;+ }+ if (char === '{') depth++;+ if (char === '}' && --depth === 0) return source.slice(start + 1, index);+ }+ return '';+}/** @type {Promise<import('./theming-targets.mjs').ThemingTarget[]>} */const enumerated = collectThemingTargets(coreSrc);@@ -93,6 +145,93 @@ describe('collectThemingTargets', () => {});});+ it('keeps every deprecated target discoverable with its exact replacement', async () => {+ const targets = await enumerated;+ for (const [key, deprecatedFor] of Object.entries(DEPRECATED_TARGETS)) {+ expect(+ targets.some(+ target =>+ target.key === key && target.deprecatedFor === deprecatedFor,+ ),+ `${key} should remain discoverable as deprecated for ${deprecatedFor}`,+ ).toBe(true);+ }+ });++ it('keeps maintained themes and copyable sources on canonical keys', () => {+ const themeFiles = [+ 'packages/themes/butter/src/butterTheme.ts',+ 'packages/themes/chocolate/src/chocolateTheme.ts',+ 'packages/themes/gothic/src/gothicTheme.ts',+ 'packages/themes/matcha/src/matchaTheme.ts',+ 'packages/themes/neutral/src/neutralTheme.ts',+ 'packages/themes/stone/src/stoneTheme.ts',+ 'packages/themes/y2k/src/y2kTheme.ts',+ 'packages/cli/assets/templates/themes/butter/butterTheme.ts',+ 'packages/cli/assets/templates/themes/chocolate/chocolateTheme.ts',+ 'packages/cli/assets/templates/themes/gothic/gothicTheme.ts',+ 'packages/cli/assets/templates/themes/matcha/matchaTheme.ts',+ 'packages/cli/assets/templates/themes/neutral/neutralTheme.ts',+ 'packages/cli/assets/templates/themes/stone/stoneTheme.ts',+ 'packages/cli/assets/templates/themes/y2k/y2kTheme.ts',+ ];+ for (const relativePath of themeFiles) {+ const components = componentsObjectSource(+ fs.readFileSync(path.join(repoRoot, relativePath), 'utf8'),+ );+ for (const key of Object.keys(DEPRECATED_TARGETS)) {+ const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');+ expect(components, `${relativePath} still uses ${key}`).not.toMatch(+ new RegExp(`(?:^|[,\\n]\\s*)(?:['"]${escaped}['"]|${escaped})\\s*:`),+ );+ }+ }++ const editorSource = fs.readFileSync(+ path.join(+ repoRoot,+ 'apps/docsite/src/app/playground/themeEditor/constants.ts',+ ),+ 'utf8',+ );+ for (const key of Object.keys(DEPRECATED_TARGETS)) {+ expect(editorSource, `theme editor still exposes ${key}`).not.toContain(+ `'${key}'`,+ );+ }+ });++ it('keeps deprecated replacements in the validation registry', async () => {+ const registry = targetValidationRegistry(await enumerated);+ for (const [key, replacement] of Object.entries(DEPRECATED_TARGETS)) {+ expect(registry.propsByKey).toHaveProperty(key);+ expect(registry.deprecatedByKey[key]).toBe(replacement);+ }+ });++ it('rejects conflicting canonical replacements for one deprecated key', () => {+ expect(() =>+ targetValidationRegistry([+ {+ key: 'old-target',+ className: 'astryx-old-target',+ component: 'One',+ props: [],+ states: [],+ deprecatedFor: 'first-target',+ },+ {+ key: 'old-target',+ className: 'astryx-old-target',+ component: 'Two',+ props: [],+ states: [],+ deprecatedFor: 'second-target',+ },+ ]),+ ).toThrow(/conflicting replacements/);+ });+it('carries the props and states a target reflects', async () => {const targets = await enumerated;expect(targets.find(t => t.key === 'switch-thumb')).toEqual({diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.mdindex db1632dc76..e56774bf07 100644--- a/packages/core/CHANGELOG.md+++ b/packages/core/CHANGELOG.md@@ -595,7 +595,7 @@ Thanks to everyone who contributed to this release:Measured on hover, same story, before and after: `2` tooltips shown to the user, then `1`.-- Seven theme target roots that ran a compound component name together are deprecated onto the `<component-kebab>-<part>` spelling the component's name implies: `codeblock` → `code-block` (with `-copy-button`, `-header`, `-title`), `progressbar` → `progress-bar` (with `-fill`, `-mark`, `-track`), `hovercard` → `hover-card`, `statusdot` → `status-dot`, `textarea` → `text-area`, `navicon` → `nav-icon`, and Table's second root `base-table` → `table` (both named the same `<table>` element). A `defineTheme` key that matches no target fails silently — no error, no warning, the rule never emits — so someone who read `ProgressBar` and wrote `'progress-bar'` got nothing and no explanation. Nothing breaks: every component renders both classes and both keys resolve, including the derived vars a renamed key expands into. The old spellings drop in the next major. (#5449)+- Seven theme target roots that ran a compound component name together are deprecated onto the `<component-kebab>-<part>` spelling the component's name implies: `codeblock` → `code-block` (with `-copy-button`, `-header`, `-title`), `progressbar` → `progress-bar` (with `-fill`, `-mark`, `-track`), `hovercard` → `hover-card`, `statusdot` → `status-dot`, `textarea` → `text-area`, `navicon` → `nav-icon`, and Table's second root `base-table` → `table` (both named the same `<table>` element). A `defineTheme` key that matches no target fails silently — no error, no warning, the rule never emits — so someone who read `ProgressBar` and wrote `'progress-bar'` got nothing and no explanation. Nothing breaks: every component renders both classes and both keys resolve, including the derived vars a renamed key expands into. New themes should use the canonical spellings; the deprecated aliases remain supported. (#5449)- Toast fits narrow and safe-area viewports, aligns wrapped actions and dismissal, uses edge-directed entrance and exit motion, exposes the Notifications landmark only while populated, and keeps exactly the viewport gutter below the final toast (#5353, #5460)Inter-toast spacing is 8px, while the visual bottom no longer adds a trailing toast gap on top of viewport padding. Placement, visible-stack limits, auto-hide defaults, announcement semantics, and dismissal reasons are unchanged.- TreeList: forward `aria-label`/`aria-labelledby` to the `role="tree"` element so a tree can be named (#5493)@@ -1215,7 +1215,7 @@ Thanks to everyone who contributed to this release:- DateInput, DateRangeInput, and DateTimeInput now accept a `weekStartsOn` prop that sets the first day of the week in the calendar popover (0 = Sunday … 6 = Saturday, or a three-letter day name like `"mon"`). It forwards to the underlying Calendar, whose default stays Sunday, so existing usage is unchanged. (#4745)- Selector, MultiSelector and Typeahead expose their empty ("No results found") state as a themeable target (#4756, #4862) — `astryx-selector-empty-state`, `astryx-multi-selector-empty-state` and `astryx-typeahead-empty-state`. Themes can restyle the empty state without the fragile structural selectors consumers previously had to reach for. (The Selector search field is a TextInput, so its placeholder is reachable today via `.astryx-text-input::placeholder`; a Selector-scoped placeholder seam would require a TextInput change and is left as a possible follow-up.)- EmptyState: add `empty-state-title` and `empty-state-description` theme targets on the title heading and the description. A theme can now restyle the title and description directly (e.g. font size, color, per `variant`) instead of reaching them through structural `> div:has(> :is(h1..h6))` selectors that reverse-engineer which element is which. (#4942)-- Every clearable input now renders its clear (✕) affordance through the shared `InputClearButton`, so the glyph is themeable in one place via the `astryx-input-clear-icon` target instead of a per-component target or a fragile descendant selector. The component-specific `astryx-{date-input,date-range-input,selector,multi-selector}-clear-icon` targets still render for a deprecation window — migrate to `input-clear-icon`. The clear glyph is now a consistent secondary-color icon with a ghost-button hover affordance across the whole family. (#4876)+- Every clearable input now renders its clear (✕) affordance through the shared `InputClearButton`, so the glyph is themeable in one place via the `astryx-input-clear-icon` target instead of a per-component target or a fragile descendant selector. The component-specific `astryx-{date-input,date-range-input,selector,multi-selector}-clear-icon` targets remain supported as deprecated aliases; new themes should use `input-clear-icon`. The clear glyph is now a consistent secondary-color icon with a ghost-button hover affordance across the whole family. (#4876)- The input family (TextInput, NumberInput, DateInput, DateRangeInput, DateTimeInput, TimeInput, TextArea, Tokenizer) now reflects its disabled state on the root theming target as `data-disabled="disabled"` plus a `.disabled` variant (only when disabled), so a theme can gate its own hover/border treatment on the disabled state — mirroring the existing `status`/`size` reflection — instead of relying on structural `:has(input:disabled)` CSS. This closes a documented theming gap for downstream consumers. (#4794)- useLayer takes an `offset` for clearance from the anchor, derived from the resolved placement, and the layer wrappers stop hand-rolling it (#4803)- DropdownMenu rows take two new options (#4953). `DropdownMenuItem` takes `hasCloseOnSelect`, so a plain action can report its result on the item instead of closing the menu. `DropdownMenuItemData` and `DropdownMenuSection` take an optional `id`, the row's stable React key for a menu whose items reorder or filter (also reaching MoreMenu, ContextMenu and Breadcrumbs, which share the type).@@ -1229,7 +1229,7 @@ Thanks to everyone who contributed to this release:- Table: `contextMenuActions` now accept a `variant: 'destructive'` for dangerous row/column actions (e.g. Delete), rendered in the error color to match ContextMenu. (#4864)- TextArea: theme the text inset by writing `paddingInline` on the `textarea` component key — it now drives the internal `--_textarea-inline-padding` var instead of landing on the wrapper. The wrapper stays flush (`padding: 0`), so the native resize grip keeps its true-corner position and the start icon, status, and character counter stay aligned to the text. Adds a `replaces` option to derived var entries for the general "map a property onto a var without emitting it on the class element" case. (#4793)- Add themeable indicators — the componentized check, checkbox, and radio visuals. `defineTheme({indicators: {check: RadioIndicator}})` replaces one by name, and every component drawing it follows. (#4712)- Theme targets now follow the component-name convention: `checkbox-indicator`, `radio-indicator`, `radio-indicator-dot`. The old names (`checkbox`, `radio`, `radio-dot`) are still emitted on the same element, so existing themes keep working — migrate at your convenience; they go away in the next major.+ Theme targets now follow the component-name convention: `checkbox-indicator`, `radio-indicator`, `radio-indicator-dot`. The old names (`checkbox`, `radio`, `radio-dot`) remain emitted on the same element so existing themes keep working. New themes should use the canonical names; deprecation does not set an automatic removal deadline.Migration: menu radios use those shared targets now. `dropdown-menu-radio-dot` is removed — target `radio-indicator-dot`; `astryx upgrade` rewrites it for you.diff --git a/packages/core/src/Banner/Banner.test.tsx b/packages/core/src/Banner/Banner.test.tsxindex 0f0aa4db00..98f4de9e2c 100644--- a/packages/core/src/Banner/Banner.test.tsx+++ b/packages/core/src/Banner/Banner.test.tsx@@ -531,7 +531,9 @@ describe('Banner', () => {);const frame = container.firstElementChild;expect(frame).toHaveClass('astryx-banner-frame');- expect(frame).not.toHaveClass(containerType, elevation);+ // The data attributes are canonical; the released bare values remain+ // same-element compatibility classes through the 0.7.0 window.+ expect(frame).toHaveClass(containerType, elevation);expect(frame).toHaveAttribute('data-container', containerType);expect(frame).toHaveAttribute('data-elevation', elevation);expect(frame?.firstElementChild).toHaveClass('astryx-banner');diff --git a/packages/core/src/CodeBlock/CodeBlock.doc.mjs b/packages/core/src/CodeBlock/CodeBlock.doc.mjsindex 62502964d9..a1f10a0318 100644--- a/packages/core/src/CodeBlock/CodeBlock.doc.mjs+++ b/packages/core/src/CodeBlock/CodeBlock.doc.mjs@@ -151,8 +151,8 @@ export const docs = {{className: 'astryx-code-block-header', visualProps: ['size', 'language', 'container']},{className: 'astryx-code-block-title', visualProps: ['size', 'language']},{className: 'astryx-code-block-copy-button'},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-codeblock', visualProps: ['size', 'language', 'container'], deprecatedFor: 'code-block'},{className: 'astryx-codeblock-header', visualProps: ['size', 'language', 'container'], deprecatedFor: 'code-block-header'},{className: 'astryx-codeblock-title', visualProps: ['size', 'language'], deprecatedFor: 'code-block-title'},diff --git a/packages/core/src/CodeBlock/CodeBlock.tsx b/packages/core/src/CodeBlock/CodeBlock.tsxindex d8946d3d66..6bb384b70b 100644--- a/packages/core/src/CodeBlock/CodeBlock.tsx+++ b/packages/core/src/CodeBlock/CodeBlock.tsx@@ -930,8 +930,8 @@ export function CodeBlock({themeProps('code-block',{size, language, container},- // `codeblock` ran the compound name together; themes styling it keep- // working until the next major.+ // `codeblock` ran the compound name together; keep it emitted so+ // existing themes continue to work.{legacyNames: ['codeblock']},),stylex.props(diff --git a/packages/core/src/DateInput/DateInput.test.tsx b/packages/core/src/DateInput/DateInput.test.tsxindex fd50a8913a..b6e612432a 100644--- a/packages/core/src/DateInput/DateInput.test.tsx+++ b/packages/core/src/DateInput/DateInput.test.tsx@@ -1122,8 +1122,8 @@ describe('DateInput clear icon theme target', () => {// The canonical target lands on the icon element itself (not the button),// so a theme can restyle just this glyph (color, size, hover) via// `defineTheme` — a button-level target could not reach the icon's own- // color/size. The original per-component name rides along for a- // deprecation window.+ // color/size. The original per-component name remains as a compatibility+ // alias.const icon = getClearIcon();expect(icon).toHaveClass('astryx-input-clear-icon');expect(icon).toHaveClass('astryx-date-input-clear-icon');@@ -1149,8 +1149,8 @@ describe('DateInput clear icon theme target', () => {it('routes the clear glyph through the shared clear button, keeping the legacy target', () => {// The clear affordance now composes the shared InputClearButton (a ghost// Button with a secondary/sm glyph), so the icon carries the canonical- // `astryx-input-clear-icon` target and — for a deprecation window — the- // original `astryx-date-input-clear-icon`. Aside from those target classes+ // `astryx-input-clear-icon` target plus the supported compatibility alias+ // `astryx-date-input-clear-icon`. Aside from those target classes// it matches the shared button's own `close`/`sm`/`secondary` glyph// exactly, so the default look is defined in one place.render(diff --git a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx b/packages/core/src/DateRangeInput/DateRangeInput.test.tsxindex 98612ef137..b7e6db8e40 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx+++ b/packages/core/src/DateRangeInput/DateRangeInput.test.tsx@@ -628,8 +628,8 @@ describe('DateRangeInput icon theme targets', () => {// The canonical target lands on the icon element itself (not the button),// so a theme can restyle just this glyph (color, size, hover) via// defineTheme — a button-level target could not reach the icon's own- // color/size. The original per-component name rides along for a- // deprecation window.+ // color/size. The original per-component name remains as a compatibility+ // alias.const icon = iconIn(getButton('Clear Range'));expect(icon).toHaveClass('astryx-input-clear-icon');expect(icon).toHaveClass('astryx-date-range-input-clear-icon');diff --git a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx b/packages/core/src/DateTimeInput/DateTimeInput.test.tsxindex 10aef5f964..b52316df82 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx+++ b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx@@ -2346,10 +2346,11 @@ describe('DateTimeInput', () => {});it('leaves both leading glyphs byte-identical to a plain secondary/sm icon by default', () => {- // The targets are purely additive: the stable target class and its- // reflected state add nothing to the render until a theme targets them.- // Guard that by diffing each glyph's StyleX classes against a standalone- // secondary/sm icon, excluding only the additive target/state classes.+ // The targets are purely additive: the stable target class, reflected+ // state, and released bare-state compatibility class add nothing to the+ // render until a theme or consumer stylesheet targets them. Guard that by+ // diffing each glyph's StyleX classes against a standalone secondary/sm+ // icon, excluding only those additive theme metadata classes.const {container} = render(<DateTimeInput label="Meeting" onChange={() => {}} />,);@@ -2368,6 +2369,7 @@ describe('DateTimeInput', () => {const themeTargetClasses = new Set(['astryx-date-time-input-toggle-icon','astryx-date-time-input-clock-icon',+ 'collapsed','expanded',]);const styleClasses = (el: HTMLElement) =>diff --git a/packages/core/src/Field/InputClearButton.test.tsx b/packages/core/src/Field/InputClearButton.test.tsxindex 82f9ebfc2d..a2974f4c27 100644--- a/packages/core/src/Field/InputClearButton.test.tsx+++ b/packages/core/src/Field/InputClearButton.test.tsx@@ -357,4 +357,3 @@ describe('InputClearButton pointer and focus interactions', () => {expect(pointerDownEvent).toBe(false);});});-diff --git a/packages/core/src/Field/InputClearButton.tsx b/packages/core/src/Field/InputClearButton.tsxindex ab921acb7e..29dbc20571 100644--- a/packages/core/src/Field/InputClearButton.tsx+++ b/packages/core/src/Field/InputClearButton.tsx@@ -73,8 +73,8 @@ export interface InputClearButtonProps {* Extra class(es) for the clear glyph itself, merged onto the shared* `astryx-input-clear-icon` target. Used by inputs that shipped a* component-specific clear-icon target before the family converged here- * (e.g. `astryx-date-input-clear-icon`) to keep emitting it for a- * deprecation window; new callers don't need it.+ * (e.g. `astryx-date-input-clear-icon`) to keep emitting it for backwards+ * compatibility; new callers don't need it.*/iconClassName?: string;}diff --git a/packages/core/src/FormLayout/__snapshots__/FormLayout.test.tsx.snap b/packages/core/src/FormLayout/__snapshots__/FormLayout.test.tsx.snapindex 49649ffba3..4e55cedf22 100644--- a/packages/core/src/FormLayout/__snapshots__/FormLayout.test.tsx.snap+++ b/packages/core/src/FormLayout/__snapshots__/FormLayout.test.tsx.snap@@ -2,7 +2,7 @@exports[`FormLayout > matches snapshot for horizontal direction 1`] = `<div- class="astryx-form-layout FormLayout__styles.base xdt5ytf x18g69wz FormLayout__styles.horizontal xrvj5dj x1mt1orb xu6a5m6"+ class="astryx-form-layout horizontal FormLayout__styles.base xdt5ytf x18g69wz FormLayout__styles.horizontal xrvj5dj x1mt1orb xu6a5m6"data-direction="horizontal"data-testid="layout">@@ -17,7 +17,7 @@ exports[`FormLayout > matches snapshot for horizontal direction 1`] = `exports[`FormLayout > matches snapshot for horizontal-labels direction 1`] = `<div- class="astryx-form-layout FormLayout__styles.base xdt5ytf FormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"+ class="astryx-form-layout horizontal-labels FormLayout__styles.base xdt5ytf FormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"data-direction="horizontal-labels"data-testid="layout">@@ -32,7 +32,7 @@ exports[`FormLayout > matches snapshot for horizontal-labels direction 1`] = `exports[`FormLayout > matches snapshot for vertical direction 1`] = `<div- class="astryx-form-layout FormLayout__styles.base x78zum5 xdt5ytf x18g69wz"+ class="astryx-form-layout vertical FormLayout__styles.base x78zum5 xdt5ytf x18g69wz"data-direction="vertical"data-testid="layout">diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjsindex 283ab36643..e613a8766c 100644--- a/packages/core/src/HoverCard/HoverCard.doc.mjs+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs@@ -17,8 +17,8 @@ export const docs = {theming: {targets: [{className: 'astryx-hover-card'},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-hovercard', deprecatedFor: 'hover-card'},],vars: [@@ -148,8 +148,8 @@ export const docsZh = {theming: {targets: [{className: 'astryx-hover-card'},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-hovercard', deprecatedFor: 'hover-card'},],vars: [diff --git a/packages/core/src/HoverCard/useHoverCard.tsx b/packages/core/src/HoverCard/useHoverCard.tsxindex 7eadf5fbc1..24c60ed90e 100644--- a/packages/core/src/HoverCard/useHoverCard.tsx+++ b/packages/core/src/HoverCard/useHoverCard.tsx@@ -609,8 +609,8 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {): ReactNode => {const renderPlacement = props?.placement ?? placement;const themeClassName = themeProps('hover-card', undefined, {- // `hovercard` ran the compound name together; themes styling it keep- // working until the next major.+ // `hovercard` ran the compound name together; keep it emitted so+ // existing themes continue to work.legacyNames: ['hovercard'],}).className;const renderProps = {diff --git a/packages/core/src/Indicator/CheckboxIndicator.tsx b/packages/core/src/Indicator/CheckboxIndicator.tsxindex 494908cf4b..5d2f8535a0 100644--- a/packages/core/src/Indicator/CheckboxIndicator.tsx+++ b/packages/core/src/Indicator/CheckboxIndicator.tsx@@ -206,8 +206,8 @@ export function CheckboxIndicator({: null,disabled: isDisabled ? 'disabled' : null,},- // `checkbox` was the target before indicators existed; themes- // styling it keep working until the next major.+ // `checkbox` was the target before indicators existed; keep it+ // emitted so existing themes continue to work.{legacyNames: ['checkbox']},),stylex.props(diff --git a/packages/core/src/Indicator/Indicator.doc.mjs b/packages/core/src/Indicator/Indicator.doc.mjsindex 3270906503..57b6dc13c5 100644--- a/packages/core/src/Indicator/Indicator.doc.mjs+++ b/packages/core/src/Indicator/Indicator.doc.mjs@@ -143,8 +143,8 @@ export const docs = {states: ['checked', 'disabled'],},{className: 'astryx-radio-indicator-dot', visualProps: ['size']},- // Still emitted beside the names above, so themes written against them- // keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-checkbox',visualProps: ['size'],diff --git a/packages/core/src/Indicator/Indicator.test.tsx b/packages/core/src/Indicator/Indicator.test.tsxindex 046053e9ab..eb144b71e4 100644--- a/packages/core/src/Indicator/Indicator.test.tsx+++ b/packages/core/src/Indicator/Indicator.test.tsx@@ -344,7 +344,7 @@ describe('useIndicator', () => {* A theme target is public API. Renaming one to follow the* `<component>-kebab` convention (`checkbox` → `checkbox-indicator`) would* silently break every theme styling the old name — the CSS still compiles, it- * just stops matching. So both names are emitted for a deprecation window, and+ * just stops matching. So both names remain emitted for compatibility, and* these tests pin that promise from both ends: the new name exists, and the* old one has not quietly disappeared.*/diff --git a/packages/core/src/Indicator/RadioIndicator.tsx b/packages/core/src/Indicator/RadioIndicator.tsxindex 8dcf90fb57..03b08b1f38 100644--- a/packages/core/src/Indicator/RadioIndicator.tsx+++ b/packages/core/src/Indicator/RadioIndicator.tsx@@ -170,8 +170,8 @@ export function RadioIndicator({checked: isChecked ? 'checked' : null,disabled: isDisabled ? 'disabled' : null,},- // `radio` was the target before indicators existed; themes styling- // it keep working until the next major.+ // `radio` was the target before indicators existed; keep it emitted+ // so existing themes continue to work.{legacyNames: ['radio']},),stylex.props(diff --git a/packages/core/src/MultiSelector/MultiSelector.test.tsx b/packages/core/src/MultiSelector/MultiSelector.test.tsxindex fd9c68bcae..54c0e75886 100644--- a/packages/core/src/MultiSelector/MultiSelector.test.tsx+++ b/packages/core/src/MultiSelector/MultiSelector.test.tsx@@ -2433,8 +2433,8 @@ describe('MultiSelector clear icon theme target', () => {// The canonical target lands on the icon element itself (not the button),// so a theme can restyle just this glyph (color, size, hover) via// `defineTheme` — a button-level target could not reach the icon's own- // color/size. The original per-component name rides along for a- // deprecation window.+ // color/size. The original per-component name remains as a compatibility+ // alias.const icon = getClearIcon();expect(icon).toHaveClass('astryx-input-clear-icon');expect(icon).toHaveClass('astryx-multi-selector-clear-icon');@@ -2461,8 +2461,8 @@ describe('MultiSelector clear icon theme target', () => {it('routes the clear glyph through the shared clear button, keeping the legacy target', () => {// The clear affordance now composes the shared InputClearButton (a ghost// Button with a secondary/sm glyph), so the icon carries the canonical- // `astryx-input-clear-icon` target and — for a deprecation window — the- // original `astryx-multi-selector-clear-icon`. Aside from those target+ // `astryx-input-clear-icon` target plus the supported compatibility alias+ // `astryx-multi-selector-clear-icon`. Aside from those target// classes it matches the shared button's own `close`/`sm`/`secondary`// glyph exactly, so the default look is defined in one place.render(diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjsindex 2b3bf86e67..5a994e3f2b 100644--- a/packages/core/src/NavIcon/NavIcon.doc.mjs+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs@@ -37,8 +37,8 @@ export const docs = {theming: {targets: [{className: 'astryx-nav-icon'},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-navicon', deprecatedFor: 'nav-icon'},],},@@ -70,8 +70,8 @@ export const docsZh = {theming: {targets: [{className: 'astryx-nav-icon'},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-navicon', deprecatedFor: 'nav-icon'},],},diff --git a/packages/core/src/NavIcon/NavIcon.tsx b/packages/core/src/NavIcon/NavIcon.tsxindex 0c8482dcab..1aecbc55ad 100644--- a/packages/core/src/NavIcon/NavIcon.tsx+++ b/packages/core/src/NavIcon/NavIcon.tsx@@ -80,8 +80,8 @@ export function NavIcon({ref={ref}{...mergeProps(themeProps('nav-icon', undefined, {- // `navicon` ran the compound name together; themes styling it keep- // working until the next major.+ // `navicon` ran the compound name together; keep it emitted so+ // existing themes continue to work.legacyNames: ['navicon'],}),stylex.props(styles.base, xstyle),diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjsindex 5ec1ff2d05..6d00229ee5 100644--- a/packages/core/src/Popover/Popover.doc.mjs+++ b/packages/core/src/Popover/Popover.doc.mjs@@ -168,8 +168,8 @@ export const docs = {targets: [// Canonical broad target for the painted Popover surface.{className: 'astryx-popover'},- // Deprecated compatibility alias. Existing themes keep working during- // migration; new themes target `popover`.+ // Deprecated compatibility alias. Existing themes remain supported;+ // new themes target `popover`.{className: 'astryx-popover-surface',deprecatedFor: 'popover',@@ -202,7 +202,7 @@ export const docs = {{guidance: true,description:- 'Theme the painted surface through popover. Existing popover-surface overrides remain supported during migration, but new themes should not depend on that deprecated alias.',+ 'Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.',},{guidance: false,@@ -231,7 +231,7 @@ export const docs = {name: 'Popover surface',required: true,description:- 'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains only as a deprecated compatibility alias during migration.',+ 'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains supported as a deprecated compatibility alias.',},{name: 'Popover content',@@ -371,8 +371,8 @@ export const docsZh = {targets: [// Canonical broad target for the painted Popover surface.{className: 'astryx-popover'},- // Deprecated compatibility alias. Existing themes keep working during- // migration; new themes target `popover`.+ // Deprecated compatibility alias. Existing themes remain supported;+ // new themes target `popover`.{className: 'astryx-popover-surface',deprecatedFor: 'popover',@@ -405,7 +405,7 @@ export const docsZh = {{guidance: true,description:- 'Theme the painted surface through popover. Existing popover-surface overrides remain supported during migration, but new themes should not depend on that deprecated alias.',+ 'Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.',},{guidance: false,@@ -434,7 +434,7 @@ export const docsZh = {name: 'Popover surface',required: true,description:- 'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains only as a deprecated compatibility alias during migration.',+ 'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains supported as a deprecated compatibility alias.',},{name: 'Popover content',@@ -472,7 +472,7 @@ export const docsDense = {{guidance: true,description:- 'Theme the painted surface through popover. Existing popover-surface overrides remain supported during migration, but new themes should not depend on that deprecated alias.',+ 'Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.',},{guidance: false,@@ -501,7 +501,7 @@ export const docsDense = {name: 'Popover surface',required: true,description:- 'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains only as a deprecated compatibility alias during migration.',+ 'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains supported as a deprecated compatibility alias.',},{name: 'Popover content',diff --git a/packages/core/src/Popover/Popover.spec.md b/packages/core/src/Popover/Popover.spec.mdindex 233804b609..f8797bc897 100644--- a/packages/core/src/Popover/Popover.spec.md+++ b/packages/core/src/Popover/Popover.spec.md@@ -46,36 +46,33 @@ and rendering contract for custom compositions.This contract records the behavior present after[PR #5373](https://github.com/facebook/astryx/pull/5373), the Popover targetdirection settled by Cindy Zhang on 2026-08-31, and the focus/opening correction-approved by Cindy Zhang on 2026-09-07. Public API signatures, emitted classes,-and release status remain unchanged. Consumer syntax and complete signatures-remain owned by `Popover.doc.mjs` and `usePopover.doc.mjs`; automatic canonical--target emission and compatibility removal require separately reviewed runtime-work.+approved by Cindy Zhang on 2026-09-07. Public API signatures and release status+remain unchanged. Consumer syntax and complete signatures remain owned by+`Popover.doc.mjs` and `usePopover.doc.mjs`. The canonical `popover` target and+the deprecated `popover-surface` compatibility alias remain supported together.## Compatibility and migration- Released default preserved: `yes`-- Compatibility class: documentation-only target ownership clarification;- runtime, DOM, styling, emitted classes, and public API are unchanged+- Compatibility class: the canonical and deprecated targets are emitted together;+ runtime behavior, DOM shape, styling, and public API otherwise remain unchanged- Canonical target: `popover` owns the broad painted-surface contract for- `<Popover>` and public `usePopover` compositions-- Deprecated alias: `popover-surface` remains emitted so existing themes keep- working during a documented migration window; it is not a second anatomy part- or equal durable owner+ `<Popover>` and public `usePopover` compositions and is preferred in new themes+- Deprecated alias: `popover-surface` remains emitted, documented as deprecated,+ and discoverable with `popover` as its exact replacement so existing themes keep+ working; it is not a second anatomy part or equal durable owner- Composed components: component-specific surface targets such as`selector-popup` and `multi-selector-popup` remain authoritative refinements;- compatibility output may remain underneath until migration+ the broad canonical and compatibility targets remain underneath- New hook consumers: a direct `usePopover` composition that needs its own theme- reachability provides and documents an owned `surfaceTarget`; it does not- create a new dependency on `popover-surface`-- Migration decision: target ownership is settled; automatic `popover` emission- for every painted hook surface and eventual alias removal ship only through- separately reviewed runtime changes+ reachability provides and documents an owned `surfaceTarget`; it does not create+ a new dependency on `popover-surface`+- Migration decision: maintained themes and copyable new examples use `popover`;+ compatibility discovery and runtime support for `popover-surface` continue-The implementation migration must preserve `popover-surface` themes until its-announced removal window. Implementation and removal each update consumer-migration guidance, target inventory, focused tests, and changelog or release-documentation; this documentation-only PR does none of those runtime steps.+Deprecation does not implement or require alias removal. CLI and theme-build+surfaces label `popover-surface` as deprecated and warn with the exact `popover`+replacement when it is authored, while existing themes continue to work.## Ownership boundary@@ -117,16 +114,16 @@ surface, not the Layer entry point. There is no installable## Public concepts-| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid or unsupported behavior |-| ------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Trigger composition | Wrapped trigger, render-prop trigger, or referenced anchor | Supplies the anchor and the control that opens or closes the standard component | Popover | Wrapped trigger when children are supplied | `component:Popover` | Current public behavior | A referenced or wrapped anchor without a button or button role warns in development and receives no trigger handler; it does not throw. |-| Visibility ownership | Uncontrolled or externally controlled | Chooses whether Popover stores visibility or synchronizes to caller state | Popover | Uncontrolled | `component:Popover` | Current public behavior | Controlled changes are synchronized through show/hide; dismissal requests are reported to the caller rather than redefining the external source of truth. |-| Popup semantics | Dialog or neutral wrapper | Exposes dialog semantics or lets child menu/listbox semantics own the popup | Popover and hook | Dialog | `component:Popover` | Current public behavior | A dialog without a label warns in development. Neutral mode omits dialog role and modal semantics. |-| Focus entry | Automatic or caller-preserved | Focuses genuine caller content, falls back to the labeled dialog surface when none exists, or preserves current focus | Popover and hook | Automatic | `component:Popover` | Current public behavior | The injected fallback close control is excluded from initial-focus candidates and reveals only when reached sequentially. |-| Dismissal | Outside/Escape enabled or disabled within native constraints | Controls light dismiss and explicit Escape participation | Popover and hook | Both enabled | `component:Popover`; `family:overlay-dismissal` owns Escape/platform-close ordering | Current public behavior | Disabling Escape alone cannot override the native Escape behavior of an auto popover; explicit-dismiss behavior requires light dismiss to be disabled too. |-| Surface treatment | Default surface or caller-owned treatment | Applies the shared painted surface and optional consumer styling | Popover and hook | Default surface | `component:Popover` | Current public behavior | Custom styling does not change lifecycle, focus, or dismissal semantics. |-| Surface target ownership | Shared baseline or component-specific refinement | Assigns `popover` as the broad surface owner and lets a composed component add its own target on that same element | Popover and hook | `popover` baseline; no component-specific refinement | `component:Popover`; the composed component owns its refinement target | Accepted contract; runtime alignment pending | `popover-surface` is compatibility output, not a new target for consumers or a second anatomy owner. |-| Placement and fit | Logical placement/alignment plus preferred width | Positions the anchor surface and constrains it to available space | Popover and hook renderer | Below/start; Popover matches trigger minimum width when no width is supplied | `component:Popover` above `architecture:layer-runtime` | Current public behavior | Preferred width and trigger matching remain capped by viewport and safe-area availability. |+| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid or unsupported behavior |+| ------------------------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Trigger composition | Wrapped trigger, render-prop trigger, or referenced anchor | Supplies the anchor and the control that opens or closes the standard component | Popover | Wrapped trigger when children are supplied | `component:Popover` | Current public behavior | A referenced or wrapped anchor without a button or button role warns in development and receives no trigger handler; it does not throw. |+| Visibility ownership | Uncontrolled or externally controlled | Chooses whether Popover stores visibility or synchronizes to caller state | Popover | Uncontrolled | `component:Popover` | Current public behavior | Controlled changes are synchronized through show/hide; dismissal requests are reported to the caller rather than redefining the external source of truth. |+| Popup semantics | Dialog or neutral wrapper | Exposes dialog semantics or lets child menu/listbox semantics own the popup | Popover and hook | Dialog | `component:Popover` | Current public behavior | A dialog without a label warns in development. Neutral mode omits dialog role and modal semantics. |+| Focus entry | Automatic or caller-preserved | Focuses genuine caller content, falls back to the labeled dialog surface when none exists, or preserves current focus | Popover and hook | Automatic | `component:Popover` | Current public behavior | The injected fallback close control is excluded from initial-focus candidates and reveals only when reached sequentially. |+| Dismissal | Outside/Escape enabled or disabled within native constraints | Controls light dismiss and explicit Escape participation | Popover and hook | Both enabled | `component:Popover`; `family:overlay-dismissal` owns Escape/platform-close ordering | Current public behavior | Disabling Escape alone cannot override the native Escape behavior of an auto popover; explicit-dismiss behavior requires light dismiss to be disabled too. |+| Surface treatment | Default surface or caller-owned treatment | Applies the shared painted surface and optional consumer styling | Popover and hook | Default surface | `component:Popover` | Current public behavior | Custom styling does not change lifecycle, focus, or dismissal semantics. |+| Surface target ownership | Shared baseline or component-specific refinement | Assigns `popover` as the broad surface owner and lets a composed component add its own target on that same element | Popover and hook | `popover` baseline; no component-specific refinement | `component:Popover`; the composed component owns its refinement target | Current compatibility contract | `popover-surface` is compatibility output, not a new target for consumers or a second anatomy owner. |+| Placement and fit | Logical placement/alignment plus preferred width | Positions the anchor surface and constrains it to available space | Popover and hook renderer | Below/start; Popover matches trigger minimum width when no width is supplied | `component:Popover` above `architecture:layer-runtime` | Current public behavior | Preferred width and trigger matching remain capped by viewport and safe-area availability. |### Public `usePopover` semantic inputs@@ -173,15 +170,15 @@ table owns their semantic effect.## Behavioral and layout contract-| ID | Invariant | Basis | Acceptance and implementation state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |-| FR1 | Popover and public `usePopover` expose one visibility lifecycle with canonical show, hide, and toggle operations. Every opening path inherits same-gesture reopen protection without changing public signatures. | Current public package surface, `architecture:layer-runtime/INV7`, and owner approval on 2026-09-07 | Accepted; implemented and covered by focused Popover-family tests |-| FR2 | Popover derives semantic focus entry identically across activation modalities: first genuine caller content, then labeled dialog-surface fallback. The injected close control is excluded. Shared interaction modality controls focus indication, not destination. | PR #5373, `architecture:interaction-modality`, and owner approval on 2026-09-07 | Accepted; implemented and covered by Popover focus tests |-| FR3 | The preferred surface size is capped to logical viewport and safe-area availability before overflow is enabled. | PR #5373, current source, tests, and Storybook fixtures | Verified in unit/style evidence; real rendered viewport evidence remains a gap |-| FR4 | Popover enables internal scrolling only after measured overflow exceeds the current tolerance. Fitting content does not become a scroll container. | PR #5373 and current tests | Verified current behavior |-| FR5 | Overflow signals while open coalesce into at most one measurement per animation frame, and Popover owns no measurement observers while closed. | PR #5373 and current tests | Verified current resource behavior |-| FR6 | Component anatomy contains the caller trigger and content, one painted Popover surface, and the optional fallback close control. Popover owns no Header, Body, or separate shared-hook surface part. | Current source, docs target inventory, and tests | Accepted anatomy; stale consumer anatomy corrected by this contract |-| FR7 | The painted surface has one broad canonical target, `popover`. `popover-surface` is a deprecated compatibility alias on that same part; composed components may add one authoritative component-specific refinement target. | Owner direction on 2026-08-31 plus current target inventory | Accepted semantic contract; automatic hook-wide emission and compatibility removal remain separately reviewed runtime work |+| ID | Invariant | Basis | Acceptance and implementation state |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |+| FR1 | Popover and public `usePopover` expose one visibility lifecycle with canonical show, hide, and toggle operations. Every opening path inherits same-gesture reopen protection without changing public signatures. | Current public package surface, `architecture:layer-runtime/INV7`, and owner approval on 2026-09-07 | Accepted; implemented and covered by focused Popover-family tests |+| FR2 | Popover derives semantic focus entry identically across activation modalities: first genuine caller content, then labeled dialog-surface fallback. The injected close control is excluded. Shared interaction modality controls focus indication, not destination. | PR #5373, `architecture:interaction-modality`, and owner approval on 2026-09-07 | Accepted; implemented and covered by Popover focus tests |+| FR3 | The preferred surface size is capped to logical viewport and safe-area availability before overflow is enabled. | PR #5373, current source, tests, and Storybook fixtures | Verified in unit/style evidence; real rendered viewport evidence remains a gap |+| FR4 | Popover enables internal scrolling only after measured overflow exceeds the current tolerance. Fitting content does not become a scroll container. | PR #5373 and current tests | Verified current behavior |+| FR5 | Overflow signals while open coalesce into at most one measurement per animation frame, and Popover owns no measurement observers while closed. | PR #5373 and current tests | Verified current resource behavior |+| FR6 | Component anatomy contains the caller trigger and content, one painted Popover surface, and the optional fallback close control. Popover owns no Header, Body, or separate shared-hook surface part. | Current source, docs target inventory, and tests | Accepted anatomy; stale consumer anatomy corrected by this contract |+| FR7 | The painted surface has one broad canonical target, `popover`. `popover-surface` remains a deprecated compatibility alias on that same part; composed components may add one authoritative component-specific refinement target. | Owner direction on 2026-08-31 plus current target inventory | Accepted compatibility contract; both canonical and deprecated paths remain supported and covered |### Allowed variation@@ -297,21 +294,20 @@ table owns their semantic effect.`popover-surface` is a deprecated alias for `popover` on the same paintedsurface. It is not anatomy and has no independent conceptual ownership. The-component doc marks it with `deprecatedFor: 'popover'`, so the anatomy validator-excludes it from the active target inventory while the runtime keeps emitting-it for existing themes.--Every public `usePopover` painted surface belongs to the broad `popover` target.-A composed component may add its own authoritative refinement target, such as-`selector-popup` or `multi-selector-popup`, on that same element. New direct-hook consumers that need distinct theme reachability provide and document an-owned `surfaceTarget`; they do not use `popover-surface`.--Automatic hook-wide `popover` emission and eventual removal of the compatibility-alias are runtime migration work outside this contract. Existing-`popover-surface` themes remain supported until that separately reviewed-migration includes target-inventory and regression-test updates plus changelog-or release guidance.+component doc keeps `deprecatedFor: 'popover'`, discovery labels the alias with+that exact replacement, and runtime keeps emitting both names for existing+themes.++Every public `usePopover` painted surface belongs to the broad `popover` target+and retains the `popover-surface` compatibility alias. A composed component may+add its own authoritative refinement target, such as `selector-popup` or+`multi-selector-popup`, on that same element. New direct hook consumers that+need distinct theme reachability provide and document an owned `surfaceTarget`;+they use `popover` in new theme source rather than authoring the deprecated key.++Maintained themes, templates, and copyable new examples use `popover`. Existing+`popover-surface` themes remain supported; deprecation does not imply or require+removal.## Family and system relationships@@ -368,9 +364,9 @@ focus indication, while Popover owns semantic focus placement.`popover` is the broad canonical theming baseline automatically owned by everypainted surface created by `<Popover>` or public `usePopover`.-`popover-surface` is deprecated compatibility output on that same element, not a-second anatomy part or equal owner. Existing themes using it remain supported-through a documented migration window.+`popover-surface` remains deprecated compatibility output on that same element,+not a second anatomy part or equal owner. Existing themes using it remain+supported, while maintained and newly authored themes use `popover`.Composed components keep authoritative refinement targets such as`selector-popup` and `multi-selector-popup`. Optional `surfaceTarget` adds that@@ -415,18 +411,12 @@ not block acceptance of the semantic contract above.- **VG2 — AT announcement.** The current story provides manual instructions, butnamed NVDA + Chrome and VoiceOver + Safari results are absent. No announcementoutcome is claimed.-- **VG3 — Target migration.** Current runtime still emits `popover-surface` as- the automatic shared class and reaches `popover` through Popover's explicit- `surfaceTarget`. A separate implementation must make `popover` automatic for- every public hook surface while preserving the alias, then verify direct-hook- and composed-component target inventories before any later removal.## Open questionsNone. DEC-1 settles the visibility model, DEC-2 settles canonical targetownership, and DEC-3 settles semantic focus versus modality-aware indication.-The remaining items are verification or separately reviewed implementation work,-not human API questions.+The remaining items are verification work, not human API questions.## Content boundarydiff --git a/packages/core/src/Popover/Popover.test.tsx b/packages/core/src/Popover/Popover.test.tsxindex 11edfc5ce7..93ce1f4031 100644--- a/packages/core/src/Popover/Popover.test.tsx+++ b/packages/core/src/Popover/Popover.test.tsx@@ -17,6 +17,7 @@ import * as stylex from '@stylexjs/stylex';import {readFileSync} from 'node:fs';import React, {useRef} from 'react';import {Popover} from './Popover';+import {usePopover} from './usePopover';import type {UsePopoverReturn} from './usePopover';import {Dialog} from '../Dialog';import {SegmentedControl, SegmentedControlItem} from '../SegmentedControl';@@ -83,6 +84,34 @@ describe('usePopover public return type', () => {expect(publicToggleTakesNoOptions).toBe(true);expect(hasInternalFocusTarget).toBe(false);});++ it('emits canonical and deprecated surface targets for direct hook consumers', () => {+ function HeadlessPopover() {+ const popover = usePopover({dialogLabel: 'Headless popover'});+ return (+ <>+ <button+ type="button"+ ref={popover.triggerRef}+ onClick={() => popover.show()}+ {...popover.triggerProps}>+ Open headless+ </button>+ {popover.render(<span>Headless content</span>)}+ </>+ );+ }++ render(<HeadlessPopover />);+ fireEvent.click(screen.getByRole('button', {name: 'Open headless'}));++ const surface = screen.getByRole('dialog', {+ name: 'Headless popover',+ hidden: true,+ });+ expect(surface).toHaveClass('astryx-popover');+ expect(surface).toHaveClass('astryx-popover-surface');+ });});describe('Popover', () => {diff --git a/packages/core/src/Popover/usePopover.doc.mjs b/packages/core/src/Popover/usePopover.doc.mjsindex 612e04f3e4..dadd4da8fe 100644--- a/packages/core/src/Popover/usePopover.doc.mjs+++ b/packages/core/src/Popover/usePopover.doc.mjs@@ -159,7 +159,7 @@ export const docs = {],usage: {description:- 'Headless hook for click-triggered popovers with focus trapping. Combines useLayer with useFocusTrap, auto-focus, light dismiss, Escape handling, and an optional hidden close button for accessible dialog-like popover behavior. Use for custom interactive floating content that needs keyboard navigation. The canonical broad surface target is popover; automatic hook-wide emission is separate migration work, so current direct compositions needing a distinct stable seam should pass and document their own surfaceTarget instead of depending on deprecated popover-surface.',+ 'Headless hook for click-triggered popovers with focus trapping. Combines useLayer with useFocusTrap, auto-focus, light dismiss, Escape handling, and an optional hidden close button for accessible dialog-like popover behavior. Every painted surface emits the canonical popover target and deprecated popover-surface compatibility alias. A custom composition needing a distinct stable seam should pass and document its own surfaceTarget.',bestPractices: [{guidance: true,@@ -174,7 +174,7 @@ export const docs = {{guidance: true,description:- 'Use popover as the broad surface target. During migration, popover-surface remains compatibility output only; do not create new theme dependencies on it.',+ 'Use popover as the broad surface target. Popover-surface remains supported compatibility output, but new theme source uses the canonical key.',},{guidance: true,@@ -197,7 +197,7 @@ export const docs = {/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */export const docsDense = {description:- 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Canonical broad target is popover; automatic hook-wide emission is separate migration work. Current direct compositions needing a distinct seam pass/document an owned surfaceTarget; do not depend on deprecated popover-surface.',+ 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Every surface emits canonical popover plus deprecated popover-surface compatibility output. Custom compositions needing a distinct seam pass/document an owned surfaceTarget.',paramDescriptions: {onShow: 'fires when popover becomes visible.',onHide: 'fires when popover hides; use to return focus when needed.',@@ -230,7 +230,7 @@ export const docsDense = {},usage: {description:- 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Canonical broad target is popover; automatic hook-wide emission is separate migration work. Current direct compositions needing a distinct seam pass/document an owned surfaceTarget; do not depend on deprecated popover-surface.',+ 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Every surface emits canonical popover plus deprecated popover-surface compatibility output. Custom compositions needing a distinct seam pass/document an owned surfaceTarget.',bestPractices: [{guidance: true,diff --git a/packages/core/src/Popover/usePopover.tsx b/packages/core/src/Popover/usePopover.tsxindex 60eedb6cca..fa4fafdc4a 100644--- a/packages/core/src/Popover/usePopover.tsx+++ b/packages/core/src/Popover/usePopover.tsx@@ -240,8 +240,9 @@ export interface UsePopoverOptions {* or radius rule paints the wrong box. Name the surface through this option* and document the class in the component's `theming.targets`.*- * The shared `astryx-popover-surface` class is always present alongside it,- * so a theme can style every popup surface at once.+ * The canonical `astryx-popover` target and deprecated+ * `astryx-popover-surface` compatibility alias are always present alongside+ * any component-owned refinement target.*/surfaceTarget?: string;}@@ -485,9 +486,11 @@ function usePopoverImplementation(// `mergeProps` is positional — a third OBJECT argument is read as// `style`, not as more props — so the surface's classes are composed// into one props object before merging with the StyleX result.- const surfaceProps = themeProps('popover-surface');+ const surfaceProps = themeProps('popover', undefined, {+ legacyNames: ['popover-surface'],+ });const surfaceClassName =- surfaceTarget != null+ surfaceTarget != null && surfaceTarget !== 'popover'? `${surfaceProps.className} ${stableClassName(surfaceTarget)}`: surfaceProps.className;diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjsindex b4e2902f0b..1aa3e5a83d 100644--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs@@ -132,8 +132,8 @@ export const docs = {className: 'astryx-progress-bar-mark',visualProps: ['variant', 'placement'],},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-progressbar',visualProps: ['variant'],@@ -297,8 +297,8 @@ export const docsZh = {className: 'astryx-progress-bar-mark',visualProps: ['variant', 'placement'],},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-progressbar',visualProps: ['variant'],diff --git a/packages/core/src/ProgressBar/ProgressBar.tsx b/packages/core/src/ProgressBar/ProgressBar.tsxindex 94b05cbcbc..5c0293dfc7 100644--- a/packages/core/src/ProgressBar/ProgressBar.tsx+++ b/packages/core/src/ProgressBar/ProgressBar.tsx@@ -482,8 +482,8 @@ export function ProgressBar({themeProps('progress-bar',{variant},- // `progressbar` ran the compound name together; themes styling it- // keep working until the next major.+ // `progressbar` ran the compound name together; keep it emitted so+ // existing themes continue to work.{legacyNames: ['progressbar']},),stylex.props(styles.container, xstyle),diff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsxindex 2c7ce2c347..25471bca4c 100644--- a/packages/core/src/Selector/Selector.test.tsx+++ b/packages/core/src/Selector/Selector.test.tsx@@ -3032,8 +3032,8 @@ describe('Selector clear icon theme target', () => {// The canonical target lands on the icon element itself (not the button),// so a theme can restyle just this glyph (color, size, hover) via// `defineTheme` — a button-level target could not reach the icon's own- // color/size. The original per-component name rides along for a- // deprecation window.+ // color/size. The original per-component name remains as a compatibility+ // alias.const icon = getClearIcon();expect(icon).toHaveClass('astryx-input-clear-icon');expect(icon).toHaveClass('astryx-selector-clear-icon');@@ -3060,8 +3060,8 @@ describe('Selector clear icon theme target', () => {it('routes the clear glyph through the shared clear button, keeping the legacy target', () => {// The clear affordance now composes the shared InputClearButton (a ghost// Button with a secondary/sm glyph), so the icon carries the canonical- // `astryx-input-clear-icon` target and — for a deprecation window — the- // original `astryx-selector-clear-icon`. Aside from those target classes+ // `astryx-input-clear-icon` target plus the supported compatibility alias+ // `astryx-selector-clear-icon`. Aside from those target classes// it matches the shared button's own `close`/`sm`/`secondary` glyph// exactly, so the default look is defined in one place.render(diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjsindex e300ede1f3..efa5f0edc9 100644--- a/packages/core/src/StatusDot/StatusDot.doc.mjs+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs@@ -63,8 +63,8 @@ export const docs = {theming: {targets: [{className: 'astryx-status-dot', visualProps: ['variant']},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-statusdot', visualProps: ['variant'], deprecatedFor: 'status-dot'},],},@@ -124,8 +124,8 @@ export const docsZh = {theming: {targets: [{className: 'astryx-status-dot', visualProps: ['variant']},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-statusdot', visualProps: ['variant'], deprecatedFor: 'status-dot'},],},diff --git a/packages/core/src/StatusDot/StatusDot.tsx b/packages/core/src/StatusDot/StatusDot.tsxindex a3b3bdbeec..793c8b4a4b 100644--- a/packages/core/src/StatusDot/StatusDot.tsx+++ b/packages/core/src/StatusDot/StatusDot.tsx@@ -203,8 +203,8 @@ export function StatusDot({themeProps('status-dot',{variant},- // `statusdot` ran the compound name together; themes styling it keep- // working until the next major.+ // `statusdot` ran the compound name together; keep it emitted so+ // existing themes continue to work.{legacyNames: ['statusdot']},),stylex.props(diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjsindex aef706ba9d..eea0e4bbe9 100644--- a/packages/core/src/Table/Table.doc.mjs+++ b/packages/core/src/Table/Table.doc.mjs@@ -131,8 +131,8 @@ export const docs = {{className: 'astryx-table-row'},{className: 'astryx-table-cell', visualProps: ['density']},{className: 'astryx-table-header-cell', visualProps: ['density']},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-base-table', deprecatedFor: 'table'},],},diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjsindex e8dc7926bf..7baddc7bfd 100644--- a/packages/core/src/TextArea/TextArea.doc.mjs+++ b/packages/core/src/TextArea/TextArea.doc.mjs@@ -277,8 +277,8 @@ export const docs = {},{className: 'astryx-text-area-control'},{className: 'astryx-text-area-counter'},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-textarea',visualProps: ['size', 'status'],@@ -533,8 +533,8 @@ export const docsZh = {},{className: 'astryx-text-area-control'},{className: 'astryx-text-area-counter'},- // Still emitted beside the names above, so themes written against- // them keep working. Drop in the next major.+ // Retained beside the canonical names for backwards compatibility.+ // New themes use the canonical targets above.{className: 'astryx-textarea',visualProps: ['size', 'status'],diff --git a/packages/core/src/TextArea/TextArea.tsx b/packages/core/src/TextArea/TextArea.tsxindex d008ab1539..e8c29b6693 100644--- a/packages/core/src/TextArea/TextArea.tsx+++ b/packages/core/src/TextArea/TextArea.tsx@@ -571,8 +571,8 @@ export function TextArea({disabled: isDisabled ? 'disabled' : null,readonly: isReadOnly ? 'readonly' : null,},- // `textarea` ran the compound name together; themes styling it- // keep working until the next major.+ // `textarea` ran the compound name together; keep it emitted so+ // existing themes continue to work.{legacyNames: ['textarea']},),stylex.props(diff --git a/packages/core/src/TextInput/TextInput.test.tsx b/packages/core/src/TextInput/TextInput.test.tsxindex 45fb970e94..4213d0b304 100644--- a/packages/core/src/TextInput/TextInput.test.tsx+++ b/packages/core/src/TextInput/TextInput.test.tsx@@ -1113,4 +1113,3 @@ describe('TextInput clear button focus behavior', () => {rafSpy.mockRestore();});});-diff --git a/packages/core/src/theme/derivedVarRegistry.ts b/packages/core/src/theme/derivedVarRegistry.tsindex 6ff692d6fb..85001700c5 100644--- a/packages/core/src/theme/derivedVarRegistry.ts+++ b/packages/core/src/theme/derivedVarRegistry.ts@@ -98,7 +98,7 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {* 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.+ * nothing. Keep these aliases aligned with the emitted compatibility classes.*/const DEPRECATED_REGISTRY_KEYS: Record<string, string> = {hovercard: 'hover-card',diff --git a/packages/core/src/theme/publicThemeHelperContract.test.ts b/packages/core/src/theme/publicThemeHelperContract.test.tsindex 201168221b..22ea0e2fb5 100644--- a/packages/core/src/theme/publicThemeHelperContract.test.ts+++ b/packages/core/src/theme/publicThemeHelperContract.test.ts@@ -29,9 +29,9 @@ const theme = defineTheme({const selector = '.astryx-button[data-variant="primary"]';describe('public theme helper selector contract', () => {- it('keeps themeProps shape while removing bare value classes', () => {+ it('keeps canonical data attributes alongside bare compatibility classes', () => {expect(themeProps('button', {variant: 'primary', size: 'sm'})).toEqual({- className: 'astryx-button',+ className: 'astryx-button primary sm','data-variant': 'primary','data-size': 'sm',});diff --git a/packages/core/src/utils/themeProps.test.ts b/packages/core/src/utils/themeProps.test.tsindex d288d9183c..c4b87212c1 100644--- a/packages/core/src/utils/themeProps.test.ts+++ b/packages/core/src/utils/themeProps.test.ts@@ -1,6 +1,6 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {describe, it, expect} from 'vitest';+import {describe, expect, it} from 'vitest';import {themeDataAttributes, themeProps} from './themeProps';describe('themeProps', () => {@@ -8,19 +8,38 @@ describe('themeProps', () => {expect(themeProps('card').className).toBe('astryx-card');});- it('does not emit bare prop-value classes', () => {+ it('continues to emit released bare prop and state classes through 0.7.0', () => {expect(themeProps('button', {variant: 'secondary', size: 'sm'}).className,- ).toBe('astryx-button');- expect(themeProps('heading', {level: 1}).className).toBe('astryx-heading');+ ).toBe('astryx-button secondary sm');+ expect(themeProps('switch', {checked: 'checked'}).className).toBe(+ 'astryx-switch checked',+ );+ });++ it('prefixes numeric compatibility classes with the prop name', () => {+ expect(themeProps('heading', {level: 1}).className).toBe(+ 'astryx-heading level-1',+ );+ expect(themeProps('heading', {level: '3'}).className).toBe(+ 'astryx-heading level-3',+ );+ });++ it('skips nullish compatibility classes', () => {+ expect(+ themeProps('button', {variant: 'primary', size: undefined}).className,+ ).toBe('astryx-button primary');});it('continues to emit deprecated target-name aliases when requested', () => {expect(- themeProps('progress-bar', undefined, {- legacyNames: ['progressbar'],- }).className,- ).toBe('astryx-progress-bar astryx-progressbar');+ themeProps(+ 'progress-bar',+ {variant: 'positive'},+ {legacyNames: ['progressbar']},+ ).className,+ ).toBe('astryx-progress-bar positive astryx-progressbar');});it('reflects visual props as data attributes', () => {@@ -45,9 +64,9 @@ describe('themeProps', () => {});});- it('returns the target class and data attributes together', () => {+ it('returns compatibility classes and canonical data attributes together', () => {expect(themeProps('button', {variant: 'primary', size: 'sm'})).toEqual({- className: 'astryx-button',+ className: 'astryx-button primary sm','data-variant': 'primary','data-size': 'sm',});diff --git a/packages/core/src/utils/themeProps.ts b/packages/core/src/utils/themeProps.tsindex 423f542b2d..41d2fd5344 100644--- a/packages/core/src/utils/themeProps.ts+++ b/packages/core/src/utils/themeProps.ts@@ -11,13 +11,20 @@ export function themeDataAttributeName(prop: string): `data-${string}` {return `data-${prop.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}`;}+function legacyClassTokenForPropValue(prop: string, value: string): string {+ // CSS classes cannot start with a digit, so preserve the released prop prefix.+ return /^\d/.test(value) ? `${prop}-${value}` : value;+}+/*** Build the stable astryx-* class name string for a component.** Every component renders one stable target class (`astryx-button`,- * `astryx-card`, etc.). Visual props and runtime states are reflected only as- * data attributes (`data-variant`, `data-size`, `data-selected`, etc.), which- * preserve the axis name and cannot collide when two axes share a value.+ * `astryx-card`, etc.). Visual props and runtime states use explicit data+ * attributes (`data-variant`, `data-size`, `data-selected`, etc.) as their+ * canonical selector surface. Released bare value/state classes remain on the+ * same element as deprecated compatibility aliases until their 0.7.0 removal+ * window.** The `astryx-` prefix comes from the centralized naming module* (`packages/core/src/naming.ts`) so the namespace lives in one place.@@ -26,10 +33,22 @@ export function themeDataAttributeName(prop: string): `data-${string}` {* <!-- SYNC: packages/core/src/utils/parseStyleKey.ts -->** @param component - Component name in lowercase (e.g. 'button', 'card')- * @returns Stable class name (e.g. "astryx-button")+ * @param props - Visual prop values whose released bare classes remain aliases+ * @returns Stable target and deprecated compatibility classes*/-function buildClassName(component: string): string {- return stableClassName(component);+function buildClassName(component: string, props?: ClassProps): string {+ const classes = [stableClassName(component)];++ if (props) {+ for (const [prop, value] of Object.entries(props)) {+ if (value == null) {+ continue;+ }+ classes.push(legacyClassTokenForPropValue(prop, String(value)));+ }+ }++ return classes.join(' ');}/**@@ -58,12 +77,13 @@ export function themeDataAttributes(props?: ClassProps): ThemeDataAttributes {* Build the props object components should spread onto the same element that* receives the stable Astryx class name.*- * This emits one stable astryx target class plus data-attribute reflection for- * visual props and runtime states. For example:+ * This emits one stable Astryx target, deprecated bare compatibility classes,+ * and canonical data-attribute reflection for visual props and runtime states.+ * For example:** ```ts* themeProps('button', { variant: 'primary', size: 'sm' })- * // → { className: 'astryx-button', data-variant: 'primary', data-size: 'sm' }+ * // → { className: 'astryx-button primary sm', data-variant: 'primary', data-size: 'sm' }* ```*//**@@ -71,17 +91,16 @@ export function themeDataAttributes(props?: ClassProps): ThemeDataAttributes {*/export type ThemePropsOptions = {/**- * Stable class names to emit ALONGSIDE the component's own, for targets that- * have been renamed.+ * Stable target names to emit alongside the canonical target for backwards+ * compatibility.** A theme target is public API: renaming one silently breaks every theme- * that styles it. Emitting the old name beside the new one keeps those- * themes working through a deprecation window, at the cost of one extra- * class on the element until the old name is dropped in a major.+ * that styles it. Keep aliases emitted unless a separate compatibility+ * decision explicitly retires them.** Pass plain string literals — the theming guards scan for them statically.- * Document the old name with `deprecated` in the component's- * `theming.targets` so the docsite says which to use.+ * Document each old name with `deprecatedFor` in the component's+ * `theming.targets` so discovery and diagnostics name the replacement.*/legacyNames?: ReadonlyArray<string>;};@@ -91,7 +110,7 @@ export function themeProps(props?: ClassProps,options?: ThemePropsOptions,): ThemeProps {- const className = buildClassName(component);+ const className = buildClassName(component, props);const legacy = options?.legacyNames?.map(name => stableClassName(name)) ?? [];return {diff --git a/packages/themes/butter/src/butterTheme.ts b/packages/themes/butter/src/butterTheme.tsindex 0b15bcb464..641db25868 100644--- a/packages/themes/butter/src/butterTheme.ts+++ b/packages/themes/butter/src/butterTheme.ts@@ -424,12 +424,12 @@ export const butterTheme = defineTheme({// Progress bar — white track in light, warm brown in dark. Vivid// semantic fills match the banner colors (Success / Warning / Error).- 'progressbar-track': {+ 'progress-bar-track': {base: {backgroundColor: 'light-dark(#e5e3d4, #725538)',},},- 'progressbar-fill': {+ 'progress-bar-fill': {'variant:success': {backgroundColor: '#91D143',},@@ -473,7 +473,7 @@ export const butterTheme = defineTheme({'status:warning': {'--color-warning': '#ffc502'},'status:error': {'--color-error': '#fc473b'},},- textarea: {+ 'text-area': {base: {paddingBlock: 'var(--spacing-2)',paddingInline: 'var(--spacing-3)',diff --git a/packages/themes/neutral/src/neutralTheme.test.ts b/packages/themes/neutral/src/neutralTheme.test.tsindex b3d1756e6e..cfed792271 100644--- a/packages/themes/neutral/src/neutralTheme.test.ts+++ b/packages/themes/neutral/src/neutralTheme.test.ts@@ -310,7 +310,9 @@ describe('neutral theme-local status mappings', () => {expect(neutralTheme.components?.badge?.['variant:info']).toMatchObject({backgroundColor: statusFill.accent,});- expect(neutralTheme.components?.statusdot?.['variant:success']).toEqual({+ expect(+ neutralTheme.components?.['status-dot']?.['variant:success'],+ ).toEqual({backgroundColor: statusFill.success,});expect(@@ -319,7 +321,9 @@ describe('neutral theme-local status mappings', () => {expect(neutralTheme.components?.['step-indicator']?.['status:warning'],).toEqual({'--color-warning': statusFill.warning});- expect(neutralTheme.components?.progressbar?.['variant:accent']).toEqual({+ expect(+ neutralTheme.components?.['progress-bar']?.['variant:accent'],+ ).toEqual({'--color-accent': statusFill.accent,});});diff --git a/packages/themes/neutral/src/neutralTheme.ts b/packages/themes/neutral/src/neutralTheme.tsindex b14080171e..af615504cd 100644--- a/packages/themes/neutral/src/neutralTheme.ts+++ b/packages/themes/neutral/src/neutralTheme.ts@@ -348,7 +348,7 @@ export const neutralTheme = defineTheme({},},- statusdot: {+ 'status-dot': {'variant:success': {backgroundColor: statusFill.success},'variant:warning': {backgroundColor: statusFill.warning},'variant:error': {backgroundColor: statusFill.error},@@ -427,7 +427,7 @@ export const neutralTheme = defineTheme({},},- progressbar: {+ 'progress-bar': {base: {'--color-background-muted': 'var(--color-border-emphasized)',},diff --git a/packages/themes/stone/src/stoneTheme.ts b/packages/themes/stone/src/stoneTheme.tsindex e70386bde6..a1e5d2ef1d 100644--- a/packages/themes/stone/src/stoneTheme.ts+++ b/packages/themes/stone/src/stoneTheme.ts@@ -324,7 +324,7 @@ export const stoneTheme = defineTheme({// the same color family as the matching status surface). Dark = T70.// Hexes from the preview Tonal Palettes ramp. accent (default) +// indeterminate both route to blue for the in-progress / loading look.- 'progressbar-fill': {+ 'progress-bar-fill': {'variant:accent': {backgroundColor: 'light-dark(#d7e4f5, #a0acbc)', // Blue T90 / T70},@@ -341,7 +341,7 @@ export const stoneTheme = defineTheme({// Track default --color-background-muted reads near-body in stone;// redirect to --color-skeleton so the channel stays visible.- 'progressbar-track': {+ 'progress-bar-track': {base: {backgroundColor: 'var(--color-skeleton)',},@@ -373,7 +373,7 @@ export const stoneTheme = defineTheme({// Input status borders + icons across all 9 input components share the// same softer T60/T70 redirection. See INPUT_STATUS_VARS above.'text-input': INPUT_STATUS_VARS,- textarea: INPUT_STATUS_VARS,+ 'text-area': INPUT_STATUS_VARS,'number-input': INPUT_STATUS_VARS,'date-input': INPUT_STATUS_VARS,'time-input': INPUT_STATUS_VARS,