Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/apps/docsite/src/__tests__/theming-helpers.test.ts b/apps/docsite/src/__tests__/theming-helpers.test.ts
index 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.ts
index 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.tsx
index 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.ts
index 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.json
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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 — the
diff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsx
index 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.md
index 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 shared
target for several components, but local docs link to that owner rather than
leaving 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 canonical
target 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 part
inventory 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 generated
consumer 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 the
source/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.md
index 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.mjs
index 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 var
diff --git a/packages/cli/api/theme/build/build.test.mjs b/packages/cli/api/theme/build/build.test.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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 theme
if (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.mjs
index 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.mjs
index 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.mjs
index 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.md
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.snap
index 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.mjs
index 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.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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.md
index 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 target
direction 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 painted
surface. 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 every
painted 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, but
named NVDA + Chrome and VoiceOver + Safari results are absent. No announcement
outcome 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 questions
None. DEC-1 settles the visibility model, DEC-2 settles canonical target
ownership, 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 boundary
diff --git a/packages/core/src/Popover/Popover.test.tsx b/packages/core/src/Popover/Popover.test.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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.mjs
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,