An open source design system that's fully customizable and agent ready
TypeScript
feat(theme)!: remove the deprecated theme compatibility surface (0.7.0) (#7302)
Cindy Zhanga1a6a636f3d3
diff --git a/.changeset/remove-deprecated-theming-compat.md b/.changeset/remove-deprecated-theming-compat.mdnew file mode 100644index 0000000000..e105b6066a--- /dev/null+++ b/.changeset/remove-deprecated-theming-compat.md@@ -0,0 +1,42 @@+---+'@astryxdesign/core': minor+'@astryxdesign/cli': minor+---++[breaking] Remove the deprecated component-theming compatibility surface scheduled for 0.7.0. Components now emit only canonical target classes and reflected `data-*` prop/state selectors. Theme discovery and build output no longer expose deprecated targets, and `ThemePropsOptions` plus `ComponentThemingTarget.deprecatedFor` are removed. The `theme targets --json` response drops the `ThemeTargetEntry.deprecatedFor` field, because no target it lists is deprecated.++Migration: run the required codemod `migrate-deprecated-theme-surface` with `astryx upgrade --from <your 0.6 version> --apply --path .` after upgrading. There is no prior deprecation patch (`DEP-0013`/`CLN-0022` and `DEP-0014`/`CLN-0023`, no prior transition).++The codemod renames removed target keys inside theme `components` maps (an imported `defineTheme()` call, an object typed as an Astryx theme, or a theme object with a static `name`), renames target classes in CSS, and replaces target-qualified bare prop/value/state classes with reflected `data-*` selectors, using every bare class the final 0.6 release emitted. It leaves dynamic/computed theme keys, unqualified or unknown classes, and CSS embedded in JavaScript/TypeScript strings for manual review. It adds `TODO(astryx upgrade)` when old and canonical keys coexist, and when a bare class Astryx once emitted has no known meaning on the target it qualifies.++The four per-component clear-icon aliases all become the shared `input-clear-icon`, which styles every input's clear icon. In CSS the codemod keeps each rule on its component with `:where(.astryx-<component> *)`, which adds no specificity. Theme keys cannot carry that scope, so the codemod adds a TODO naming the CSS selector to use.++Code that passed `{legacyNames}` to `themeProps()` or set `deprecatedFor` in a component doc should delete that argument or field; the canonical target is unchanged.++Rename theme keys and CSS target classes with this complete mapping:++- `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`++For custom CSS, replace removed bare selectors with the corresponding reflected attribute on a canonical target—for example, `.astryx-button.primary.sm` becomes `.astryx-button[data-variant="primary"][data-size="sm"]`, and `.astryx-switch.checked` becomes `.astryx-switch[data-checked="checked"]`. Review unqualified classes such as `.primary` manually because they may be application-owned.++@cixzhangdiff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex 182981e365..99e960e25c 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -1068,8 +1068,6 @@ export interface ThemingTarget {className: string;visualProps?: string[];states?: string[];- /** Old name of a renamed target; the class superseding it. */- deprecatedFor?: string;}export interface ComponentVar {diff --git a/apps/docsite/src/__tests__/theming-helpers.test.ts b/apps/docsite/src/__tests__/theming-helpers.test.tsindex 4da8d500d1..393e53a433 100644--- a/apps/docsite/src/__tests__/theming-helpers.test.ts+++ b/apps/docsite/src/__tests__/theming-helpers.test.ts@@ -35,7 +35,7 @@ describe('theming helpers — data attributes', () => {it('reflects both visual props and states', () => {expect(targetDataAttributes({- className: 'astryx-checkbox',+ className: 'astryx-checkbox-indicator',visualProps: ['size'],states: ['checked', 'disabled'],}),@@ -97,21 +97,6 @@ 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/components/component-detail/Theming.tsx b/apps/docsite/src/components/component-detail/Theming.tsxindex 960c400ddc..a0e65ac438 100644--- a/apps/docsite/src/components/component-detail/Theming.tsx+++ b/apps/docsite/src/components/component-detail/Theming.tsx@@ -66,11 +66,6 @@ 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(', ')}@@ -98,7 +93,6 @@ 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,@@ -132,19 +126,6 @@ function TargetsTable({targets, props}: TargetsTableProps) {</Text>),},- {- key: 'deprecatedFor',- header: 'Status',- width: pixel(180),- renderCell: (item: Record<string, unknown>) => {- const replacement = item.deprecatedFor as string;- return replacement ? (- <Text color="secondary">Deprecated: use {replacement}</Text>- ) : (- <Text color="secondary">Current</Text>- );- },- },{key: 'dataAttrs',header: 'Data attributes',diff --git a/apps/docsite/src/components/component-detail/themingHelpers.ts b/apps/docsite/src/components/component-detail/themingHelpers.tsindex 2668771332..406a68d578 100644--- a/apps/docsite/src/components/component-detail/themingHelpers.ts+++ b/apps/docsite/src/components/component-detail/themingHelpers.ts@@ -75,17 +75,13 @@ 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 = canonicalTargets(theming);+ const targets = theming.targets;if (!targets.length) {return '';}diff --git a/docs/architecture/component-theming-surface.md b/docs/architecture/component-theming-surface.mdindex 7c7277c119..143578fd91 100644--- a/docs/architecture/component-theming-surface.md+++ b/docs/architecture/component-theming-surface.md@@ -199,17 +199,12 @@ but acceptance alone is best effort, not a compatibility promise.painters. By contract, those variables must not be authored directly or reliedon 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 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.+- **INV12 — Aliases are compatibility, not anatomy.** Removed target aliases do+ not count as current semantic parts. Starting in 0.7.0, runtime target emission,+ component metadata, CLI discovery, theme build, and generated docs expose only+ canonical targets. Maintained themes, CLI templates, and copyable examples use+ canonical keys. The breaking release preserves the complete old-to-new mapping+ and migration path below under `spec:AST-017`.- **INV13 — Family ownership is explicit.** A family document may own a sharedtarget for several components, but local docs link to that owner rather thanleaving ownership to inference.@@ -232,13 +227,11 @@ but acceptance alone is best effort, not a compatibility promise.authoritative; it is not a permanent adaptation exemption or an extensionpoint.-## Approved deprecated-surface removal window+## Approved deprecated-surface removal-Version **0.7.0** is the first release authorized to remove the deprecated-component-theming compatibility surface in this section. Before 0.7.0, every item-below remains a supported compatibility path. Removal is a breaking change under-`spec:AST-017`: it requires a `[breaking]` Changeset, the exact old-to-new mapping,-and a usable migration path or instructions.+Version **0.7.0** removes the deprecated component-theming compatibility surface+in this section. This is a breaking change under `spec:AST-017`; the release+includes the exact old-to-new mapping and a staged migration codemod.The approved target-alias migration is:@@ -266,19 +259,18 @@ The approved target-alias migration is:| `statusdot` | `status-dot` || `textarea` | `text-area` |-The same 0.7.0 window covers the compatibility machinery used only to preserve-those aliases: the `themeProps(..., {legacyNames})` option,+The 0.7.0 removal also deletes the compatibility machinery used only for those+aliases: the `themeProps(..., {legacyNames})` option,`ThemePropsOptions.legacyNames`, `ComponentThemingTarget.deprecatedFor`, and-filtering or discovery behavior whose only purpose is to include or exclude-those deprecated targets.+alias-only filtering or discovery behavior.-It also covers deprecated bare prop/value and state selector classes emitted by-the theming pipeline, such as `.primary`, `.sm`, and `.checked`, where the stable-replacement is the canonical `astryx-*` target plus its explicit reflected-`data-*` attribute. Semantic `defineTheme({components})` keys remain unchanged.-Because a bare class does not identify its prop/state axis and may be consumer--authored, this CSS migration may require explicit instructions rather than a-global codemod.+Deprecated bare prop/value and state selector classes such as `.primary`, `.sm`,+and `.checked` are no longer emitted. Their stable replacement is the canonical+`astryx-*` target plus its explicit reflected `data-*` attribute. Semantic+`defineTheme({components})` keys remain supported; only the 21 deprecated target+spellings in the table above move to their canonical keys. Because an unqualified+bare class does not identify its prop/state axis and may be consumer-authored, the+codemod leaves it for manual review.Canonical target names, semantic component keys, reflected `data-*` selectors,and current target behavior are outside this removal authorization and remain@@ -350,16 +342,11 @@ how themes become output, or the design rationale for a component's appearance.## Change coupling- 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. 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- the exact alias and bare-selector migration evidence named above.+ `.doc.mjs` public target metadata, generated/CLI discovery, and validation+ together. Copyable examples and maintained themes use canonical keys.+- The 0.7.0 deprecated-surface removal preserves every canonical target and+ semantic key, migrates built-in/generated themes first, and supplies the exact+ alias and bare-selector migration evidence named above.- Adding consumer anatomy requires a deliberate component-spec mapping to atarget, inheritance, delegation, or factual `none`. It does not automaticallycreate CSS API. A `none` entry classifies the current state as `intentional`,@@ -391,11 +378,10 @@ how themes become output, or the design rationale for a component's appearance.- Component `.doc.mjs` `usage.anatomy[]` owns the consumer-facing semantic partinventory and contains no theming disposition or maintainer rationale.-- Component `.doc.mjs` `theming.targets[]` owns discoverable public targets and- their visual prop/state selector axes. 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.+- Component `.doc.mjs` `theming.targets[]` owns discoverable canonical public+ targets and their visual prop/state selector axes. Removed aliases are not+ present in this metadata and do not count as 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@@ -408,10 +394,10 @@ how themes become output, or the design rationale for a component's appearance.migration, checked against consumer anatomy, and excluded from generatedconsumer docs. Nearby component-spec prose owns non-obvious rationale,exceptions, and links.-- Runtime `themeProps()` calls emit the 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.+- Runtime `themeProps()` calls emit one canonical target and reflected `data-*`+ state/prop selectors.+- CLI discovery and theme build consume canonical target metadata; copyable+ examples omit removed aliases.- `scripts/check-knowledge.mjs`, `themingTargets.test.ts`,`extensibleAxes.test.ts`, and `derivedVarRegistry.test.ts` enforce thesource/metadata/generated relationship. `extensibleAxes.test.ts` proves only@@ -432,18 +418,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 | 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 |+| 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 | Canonical-only runtime emission and discovery, removed-alias rejection, complete codemod mapping/tests, canonical maintained-theme/template inventory, and family-owner fixtures | A removed alias is emitted or discovered, the migration mapping is incomplete, canonical targets change, removed compatibility metadata survives, 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/README.md b/packages/cli/README.mdindex 3230c6f0e2..49419feaef 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -466,7 +466,7 @@ Every response has a `type` discriminant. The full set is below (generated from| `theme.app` | The app theme record after add, remove, or use. It includes every added theme and its built imports, the default slug, generated module path, and the command change. After add, the envelope package names the npm package that owns the added theme; a local theme has none. || `theme.eject` | A local source-fork receipt with the resolved slug, displayName, source theme maintained flag, source-selector package, outputDir, source entry, exportName, and every file written, including the descriptor. The written local descriptor always uses maintained: false. || `theme.template` | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success. |-| `theme.targets` | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key. |+| `theme.targets` | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states}, where props and states are its legal override keys. || `theme.palette.generate` | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result. || `upgrade.list` | Every available codemod, oldest→newest, as {name, package, title, version, optional}; returned for --list without running anything. || `upgrade.registry` | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items. |diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjsindex 13573fe8bc..8b79f5db10 100644--- a/packages/cli/api/theme/build/build.mjs+++ b/packages/cli/api/theme/build/build.mjs@@ -72,7 +72,7 @@ import {logger} from '../../logger.mjs';import {loadComponentDoc} from '../../../foundation/discovery/component-loader.mjs';import {collectThemingTargets,- targetValidationRegistry,+ targetsByKey,} from '../../../foundation/discovery/theming-targets.mjs';import {collectUnloadedFonts,@@ -752,10 +752,8 @@ const _augmentationTargetCache = new Map();* Resolve a rendered theme class token (the key without `astryx-`) to candidate* public core subpaths and interface prefixes that may own its augmentable prop* maps. Some tokens are subtargets documented by a parent component- * (`avatar-status-dot` augments `@astryxdesign/core/Avatar`), and some- * deprecated tokens still omit word separators (`progressbar`, `statusdot`)- * while the public API keeps `ProgressBar`/`StatusDot` casing. Component docs- * are the source of truth for the target token → owning component relationship.+ * (`avatar-status-dot` augments `@astryxdesign/core/Avatar`). Component docs are+ * the source of truth for the target token → owning component relationship.** @param {string} componentName* @returns {Promise<Array<{moduleName: string, interfacePrefix: string}>>}@@ -832,8 +830,7 @@ async function resolveAugmentationTargetCandidates(componentName) {// Try the exact rendered token first for documented subtargets such as// avatar-status-dot → AvatarStatusDotVariantMap, then the owning public- // component name for the deprecated unhyphenated tokens such as- // progressbar → ProgressBarVariantMap/statusdot → StatusDotVariantMap.+ // component name (for example, ProgressBar for progress-bar-fill).addCandidate(moduleName, toPascalCase(componentName));addCandidate(moduleName, moduleName);if (Array.isArray(doc?.components)) {@@ -1991,30 +1988,25 @@ export declare const ${iconInfo.exportName}: IconRegistry;/*** Load known theme target keys from core component docs: the visual props AND- * 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.+ * runtime states each target reflects. Returns null when docs are unavailable so+ * validation skips warnings rather than guessing from a second registry.*- * @returns {Promise<{propsByKey: Record<string, string[]>, deprecatedByKey: Record<string, string>} | null>}+ * @returns {Promise<{propsByKey: 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 registry = targetValidationRegistry(- await collectThemingTargets(coreSrc),- );- return Object.keys(registry.propsByKey).length > 0 ? registry : null;+ const propsByKey = targetsByKey(await collectThemingTargets(coreSrc));+ return Object.keys(propsByKey).length > 0 ? {propsByKey} : null;}-/** @type {{propsByKey: Record<string, string[]>, deprecatedByKey: Record<string, string>} | null | undefined} */+/** @type {{propsByKey: Record<string, string[]>} | null | undefined} */let knownComponentsCache;/**- * @returns {Promise<{propsByKey: Record<string, string[]>, deprecatedByKey: Record<string, string>} | null>}+ * @returns {Promise<{propsByKey: Record<string, string[]>} | null>}*/async function getKnownComponents() {if (knownComponentsCache === undefined) {@@ -2027,7 +2019,7 @@ async function getKnownComponents() {* 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+ * @param {{propsByKey: Record<string, string[]>}} knownComponents* @returns {string[]}*/export function validateComponentOverridesAgainstRegistry(@@ -2053,9 +2045,8 @@ export function validateComponentOverridesAgainstRegistry(}}- for (const {name: layerName, components} of layers) {+ for (const {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 => {@@ -2081,13 +2072,6 @@ export function validateComponentOverridesAgainstRegistry(continue;}- 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;@@ -2114,7 +2098,7 @@ export function validateComponentOverridesAgainstRegistry(/*** Validate component overrides in a theme definition.- * Warns on unknown component names, deprecated targets, and unknown prop names.+ * Warns on unknown component and 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[]>}diff --git a/packages/cli/api/theme/build/build.test.mjs b/packages/cli/api/theme/build/build.test.mjsindex 35e2a2239a..4cf02b8c53 100644--- a/packages/cli/api/theme/build/build.test.mjs+++ b/packages/cli/api/theme/build/build.test.mjs@@ -547,26 +547,17 @@ describe('themeBuild() — component override validation', () => {]);});- it('warns with the exact replacement for deprecated root and media targets', () => {+ it('deduplicates removed aliases as unknown across root and conditional layers', () => {const registry = {- propsByKey: {- 'old-target': ['variant'],- 'new-target': ['variant'],- },- deprecatedByKey: {'old-target': 'new-target'},+ propsByKey: {'new-target': ['variant']},};expect(validateComponentOverridesAgainstRegistry({- components: {- 'old-target': {base: {color: 'red'}},- 'new-target': {base: {color: 'blue'}},- },+ components: {'old-target': {base: {color: 'red'}}},onDark: {- components: {- 'old-target': {'variant:quiet': {color: 'pink'}},- },+ components: {'old-target': {'variant:quiet': {color: 'pink'}}},},adaptations: {rules: [@@ -583,31 +574,27 @@ describe('themeBuild() — component override validation', () => {},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.',- ]);+ ).toEqual(['Unknown component "old-target".']);});- it('warns with the exact replacement for a supported deprecated target', async () => {- const themeFile = path.join(tmpDir, 'deprecated-target.mjs');+ it('reports a removed target alias as an unknown component key', async () => {+ const themeFile = path.join(tmpDir, 'removed-target.mjs');fs.writeFileSync(themeFile,`export default {- name: 'deprecated-target',+ name: 'removed-target',tokens: {},components: {progressbar: {base: {color: 'red'}}},};\n`,);- const result = await themeBuild('deprecated-target.mjs', {}, {cwd: tmpDir});+ const result = await themeBuild('removed-target.mjs', {}, {cwd: tmpDir});expect(result?.data.warnings).toContain(- 'Deprecated component target "progressbar". Use "progress-bar" instead.',+ 'Unknown component "progressbar". Did you mean: progress-bar?',);expect(- fs.readFileSync(path.join(tmpDir, 'deprecated-target.css'), 'utf8'),+ fs.readFileSync(path.join(tmpDir, 'removed-target.css'), 'utf8'),).toContain('.astryx-progressbar');});});diff --git a/packages/cli/api/theme/targets/targets.test.mjs b/packages/cli/api/theme/targets/targets.test.mjsindex 39eac1904e..2a3835b92a 100644--- a/packages/cli/api/theme/targets/targets.test.mjs+++ b/packages/cli/api/theme/targets/targets.test.mjs@@ -19,7 +19,6 @@ describe('themeTargets (api/theme/targets)', () => {const allowedKeys = new Set(['className','component',- 'deprecatedFor','key','props','states',@@ -35,9 +34,6 @@ describe('themeTargets (api/theme/targets)', () => {expect(Object.keys(target).filter(key => !allowedKeys.has(key))).toEqual([],);- if (target.deprecatedFor !== undefined) {- expect(target.deprecatedFor).toEqual(expect.any(String));- }}}, 60_000);diff --git a/packages/cli/api/theme/theme.type.mjs b/packages/cli/api/theme/theme.type.mjsindex 7ac9464053..b7f2e373e8 100644--- a/packages/cli/api/theme/theme.type.mjs+++ b/packages/cli/api/theme/theme.type.mjs@@ -140,7 +140,6 @@* @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/themeTargets.doc.mjs b/packages/cli/api/theme/themeTargets.doc.mjsindex b7969ab5e8..f1e5767b46 100644--- a/packages/cli/api/theme/themeTargets.doc.mjs+++ b/packages/cli/api/theme/themeTargets.doc.mjs@@ -17,9 +17,8 @@ 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, 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 ' ++ '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 ' +'(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 case-insensitive substring search over each target's key, class and component.",@@ -55,7 +54,7 @@ export const doc = {{type: 'theme.targets',description:- 'The echoed filter, how many components are represented, and the targets: each {key, className, component, props, states, deprecatedFor?}.',+ 'The echoed filter, how many components are represented, and the targets: each {key, className, component, props, states}.',},],throws: [diff --git a/packages/cli/assets/codemods/transforms/next/__tests__/migrate-deprecated-theme-surface.test.mjs b/packages/cli/assets/codemods/transforms/next/__tests__/migrate-deprecated-theme-surface.test.mjsnew file mode 100644index 0000000000..8df169d86f--- /dev/null+++ b/packages/cli/assets/codemods/transforms/next/__tests__/migrate-deprecated-theme-surface.test.mjs@@ -0,0 +1,322 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it} from 'vitest';+import jscodeshift from 'jscodeshift';+import manifest from '../index.mjs';+import transform, {+ DEPRECATED_THEME_TARGETS,+} from '../migrate-deprecated-theme-surface.mjs';++const j = jscodeshift.withParser('tsx');+const api = {jscodeshift: j, stats: () => {}, report: () => {}};++const IMPORT = "import {defineTheme} from '@astryxdesign/core/theme';\n";++function apply(source, filePath = 'theme.ts') {+ return transform({source, path: filePath}, api) ?? source;+}++const EXPECTED_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',+};++describe('migrate-deprecated-theme-surface', () => {+ it('is staged as a required next-release code codemod', () => {+ const entry = manifest.find(+ candidate => candidate.name === 'migrate-deprecated-theme-surface',+ );+ expect(entry).toBeDefined();+ expect(entry?.optional).not.toBe(true);+ expect(entry?.meta.fileExtensions).toContain('.css');+ expect(entry?.meta.fileExtensions).toContain('.ts');+ });++ it('owns the complete approved 21-target mapping', () => {+ expect(DEPRECATED_THEME_TARGETS).toEqual(EXPECTED_TARGETS);+ expect(Object.keys(DEPRECATED_THEME_TARGETS)).toHaveLength(21);+ });++ it.each(Object.entries(EXPECTED_TARGETS))(+ 'renames static target key %s to %s inside a components map',+ (oldKey, newKey) => {+ const output = apply(+ `export default {name: 'brand', components: {${JSON.stringify(oldKey)}: {base: {color: 'red'}}}};`,+ );++ expect(output).not.toContain(`${JSON.stringify(oldKey)}:`);+ expect(output).toContain(`'${newKey}':`);+ },+ );++ it('renames root, mode, and adaptation component maps', () => {+ const output = apply(`${IMPORT}const theme = defineTheme({+ components: {progressbar: {base: {color: 'red'}}},+ onDark: {components: {'statusdot': {base: {color: 'white'}}}},+ adaptations: {rules: [{value: {components: {'popover-surface': {base: {padding: 8}}}}}]},+});`);++ expect(output).toContain("'progress-bar':");+ expect(output).toContain("'status-dot':");+ expect(output).toContain("'popover':");+ expect(output).not.toMatch(/(?:progressbar|statusdot|popover-surface)\s*:/);+ });++ it('renames a statically declared components variable used by defineTheme', () => {+ const output =+ apply(`${IMPORT}const components = {textarea: {base: {color: 'red'}}};+export const theme = defineTheme({name: 'brand', components});`);+ expect(output).toContain("'text-area':");+ });++ it('does not rewrite an unrelated object property named components', () => {+ const input = `const registry = {components: {checkbox: Checkbox}};`;+ expect(apply(input)).toBe(input);+ });++ it('does not rewrite a default-exported application component registry', () => {+ for (const input of [+ `export default {components: {checkbox: Checkbox, textarea: TextArea}};`,+ `export default {name: 'app', components: {checkbox: Checkbox}};`,+ `const theme = {components: {checkbox: {base: {color: 'red'}}}};`,+ ]) {+ expect(apply(input)).toBe(input);+ }+ });++ it('does not treat a defineTheme from another library as an Astryx theme', () => {+ const input = `import {defineTheme} from 'other-ui';+export default defineTheme({components: {checkbox: {base: {color: 'red'}}}});`;+ expect(apply(input)).toBe(input);+ });++ it.each([+ [+ 'an aliased defineTheme import',+ `import {defineTheme as makeTheme} from '@astryxdesign/core';+export default makeTheme({name: 'brand', components: {navicon: {base: {}}}});`,+ ],+ [+ 'a namespace defineTheme call',+ `import * as astryx from '@astryxdesign/core/theme';+export default astryx.defineTheme({components: {navicon: {base: {}}}});`,+ ],+ [+ 'a satisfies-typed theme object',+ `import type {DefineThemeInput} from '@astryxdesign/core';+export default {components: {navicon: {base: {}}}} satisfies DefineThemeInput;`,+ ],+ [+ 'an as-typed theme object',+ `import type {DefineThemeInput} from '@astryxdesign/core';+export default ({components: {navicon: {base: {}}}}) as DefineThemeInput;`,+ ],+ [+ 'an annotated theme variable',+ `import type {DefineThemeInput} from '@astryxdesign/core';+const brand: DefineThemeInput = {name: 'brand', components: {navicon: {base: {}}}};`,+ ],+ ])('recognizes %s', (_name, input) => {+ const output = apply(input);+ expect(output).toContain("'nav-icon':");+ expect(output).not.toMatch(/navicon\s*:/);+ });++ it('renames a clear-icon alias with a TODO naming the owner scope it loses', () => {+ const output = apply(+ `export default {name: 'brand', components: {'selector-clear-icon': {base: {color: 'red'}}}};`,+ );+ expect(output).toContain("'input-clear-icon':");+ expect(output).toContain(+ 'TODO(astryx upgrade): `selector-clear-icon` became `input-clear-icon`',+ );+ expect(output).toContain(+ '.astryx-input-clear-icon:where(.astryx-selector *)',+ );+ });++ it('flags two clear-icon aliases that collapse onto the shared target', () => {+ const output = apply(`export default {name: 'brand', components: {+ 'selector-clear-icon': {base: {color: 'red'}},+ 'date-input-clear-icon': {base: {color: 'blue'}},+}};`);+ expect(output).toContain("'input-clear-icon':");+ expect(output).toContain(+ 'merge deprecated theme target `date-input-clear-icon` into `input-clear-icon`',+ );+ expect(output).toContain("'date-input-clear-icon':");+ });++ it('uses lexical scope when a theme components variable shadows a registry', () => {+ const input = `${IMPORT}const components = {checkbox: Checkbox};+function makeTheme() {+ const components = {textarea: {base: {color: 'red'}}};+ return defineTheme({components});+}`;+ const output = apply(input);+ expect(output).toContain('const components = {checkbox: Checkbox};');+ expect(output).toContain("'text-area':");+ });++ it('does not rename matching keys outside a components map or dynamic keys', () => {+ const input = `const labels = {progressbar: 'Progress'};+const oldTarget = 'progressbar';+const theme = {name: 'brand', components: {[oldTarget]: {base: {color: 'red'}}}};`;+ expect(apply(input)).toBe(input);+ });++ it('flags a static old/new collision instead of silently dropping either rule', () => {+ const input = `${IMPORT}const theme = defineTheme({name: 'brand', components: {+ progressbar: {base: {color: 'red'}},+ 'progress-bar': {base: {backgroundColor: 'blue'}},+}});`;+ const output = apply(input);+ expect(output).toContain('TODO(astryx upgrade)');+ expect(output).toContain('merge deprecated theme target `progressbar`');+ expect(output).toContain('progressbar:');+ expect(output).toContain("'progress-bar':");+ expect(apply(output)).toBe(output);+ });++ it('renames every removed target class in CSS selectors', () => {+ const input = Object.keys(EXPECTED_TARGETS)+ .map(key => `.astryx-${key} { color: red; }`)+ .join('\n');+ const output = apply(input, 'theme.css');++ for (const [oldKey, newKey] of Object.entries(EXPECTED_TARGETS)) {+ expect(output).not.toMatch(+ new RegExp(+ `\\.astryx-${oldKey.replace(/[.*+?^${}()|[\\]\\]/g, '\\$&')}(?![a-z0-9-])`,+ ),+ );+ expect(output).toContain(`.astryx-${newKey}`);+ }+ });++ it('replaces target-qualified bare classes with reflected data selectors', () => {+ const output = apply(+ `.astryx-button.primary.sm:hover { color: red; }+.astryx-heading.level-2 { margin: 0; }+.astryx-switch.checked { opacity: 1; }+.astryx-grid.center { place-content: center; }`,+ 'theme.css',+ );++ expect(output).toContain(+ '.astryx-button:is([data-variant="primary"]):is([data-size="sm"]):hover',+ );+ expect(output).toContain('.astryx-heading:is([data-level="2"])');+ expect(output).toContain('.astryx-switch:is([data-checked="checked"])');+ expect(output).toContain(+ '.astryx-grid:is([data-align="center"],[data-justify="center"])',+ );+ expect(output).not.toMatch(+ /\.(?:primary|sm|level-2|checked|center)(?![a-z0-9_-])/,+ );+ });++ it('canonicalizes aliases before emitting data-attribute selectors', () => {+ const output = apply(+ '.astryx-progressbar.success > .astryx-progressbar-mark.fill {}',+ 'theme.css',+ );+ expect(output).toContain(+ '.astryx-progress-bar:is([data-variant="success"])',+ );+ expect(output).toContain(+ '.astryx-progress-bar-mark:is([data-placement="fill"])',+ );+ expect(output).not.toContain('astryx-progressbar');+ expect(output).not.toMatch(/\.(?:success|fill)(?![a-z0-9_-])/);+ });++ it('finishes selectors produced by the 0.6 compatibility codemod', () => {+ const output = apply(+ '.astryx-button:is(.primary,[data-variant="primary"]) {}',+ 'theme.css',+ );+ expect(output).toContain('.astryx-button:is([data-variant="primary"])');+ expect(output).not.toContain('.primary');+ });++ it('keeps the owner scope of clear-icon aliases in CSS without adding specificity', () => {+ const output = apply(+ `.astryx-selector-clear-icon:hover { color: red; }+.astryx-date-range-input-clear-icon { color: blue; }`,+ 'theme.css',+ );+ expect(output).toContain(+ '.astryx-input-clear-icon:where(.astryx-selector *):hover',+ );+ expect(output).toContain(+ '.astryx-input-clear-icon:where(.astryx-date-range-input *)',+ );+ expect(output).not.toMatch(/-clear-icon(?!:where)/);+ });++ it('migrates bare classes that first shipped after 0.5.4', () => {+ const output = apply('.astryx-heading.bold { color: red; }', 'theme.css');+ expect(output).toContain('.astryx-heading:is([data-weight="bold"])');+ expect(output).not.toMatch(/\.bold(?![a-z0-9_-])/);+ });++ it('flags a known bare class that has no 0.6 meaning on its target', () => {+ const input = '.astryx-button.checked { color: red; }';+ const output = apply(input, 'theme.css');+ expect(output).toContain(+ 'TODO(astryx upgrade): Astryx 0.7 no longer emits',+ );+ expect(output).toContain('.checked had no known 0.6 meaning');+ expect(output).toContain('.astryx-button.checked');+ expect(apply(output, 'theme.css')).toBe(output);+ });++ it('leaves unqualified and unknown consumer classes unchanged', () => {+ const input = `.primary { color: red; }+.astryx-button.brand { color: blue; }`;+ expect(apply(input, 'theme.css')).toBe(input);+ });++ it('does not remove a data-selector union from a different selector compound', () => {+ const output = apply(+ '.astryx-button.primary .consumer:is(.primary,[data-custom="x"]) {}',+ 'theme.css',+ );+ expect(output).toContain('.astryx-button:is([data-variant="primary"])');+ expect(output).toContain('.consumer:is(.primary,[data-custom="x"])');+ });++ it('never rewrites CSS examples in JavaScript strings', () => {+ const input = `const selector = '.astryx-progressbar.success';`;+ expect(apply(input)).toBe(input);+ });++ it('is byte-idempotent after JavaScript and CSS migration', () => {+ const js = `export default {name: 'brand', components: {statusdot: {base: {color: 'red'}}, 'selector-clear-icon': {base: {color: 'red'}}}};`;+ const css = '.astryx-textarea.sm {}';+ const jsOnce = apply(js);+ const cssOnce = apply(css, 'theme.css');+ expect(apply(jsOnce)).toBe(jsOnce);+ expect(apply(cssOnce, 'theme.css')).toBe(cssOnce);+ });+});diff --git a/packages/cli/assets/codemods/transforms/next/index.mjs b/packages/cli/assets/codemods/transforms/next/index.mjsindex 2af3bdfcf0..db5cf9c6eb 100644--- a/packages/cli/assets/codemods/transforms/next/index.mjs+++ b/packages/cli/assets/codemods/transforms/next/index.mjs@@ -7,4 +7,14 @@* this file into the resolved version folder.*/-export default [];+import migrateDeprecatedThemeSurface, {+ meta as migrateDeprecatedThemeSurfaceMeta,+} from './migrate-deprecated-theme-surface.mjs';++export default [+ {+ name: 'migrate-deprecated-theme-surface',+ transform: migrateDeprecatedThemeSurface,+ meta: migrateDeprecatedThemeSurfaceMeta,+ },+];diff --git a/packages/cli/assets/codemods/transforms/next/migrate-deprecated-theme-surface-v0.6-data.mjs b/packages/cli/assets/codemods/transforms/next/migrate-deprecated-theme-surface-v0.6-data.mjsnew file mode 100644index 0000000000..21de54111a--- /dev/null+++ b/packages/cli/assets/codemods/transforms/next/migrate-deprecated-theme-surface-v0.6-data.mjs@@ -0,0 +1,229 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * Frozen bare-class selector data for the final 0.6 runtime contract.+ *+ * Through 0.6, themeProps(target, props) emitted one bare class per visual prop+ * or state value (a numeric value kept its prop prefix, such as `level-2`) and+ * repeated them on every legacy alias target. This table is the union of:+ *+ * - every public 0.6 themeProps() callsite in @astryxdesign/core, with each+ * value enumerated from the literal-union type that reaches it; and+ * - the 0.5.4 table, which also records same-element primitive composition.+ *+ * Each bare class token maps to every [axis, value] it can mean. Unbounded+ * values are listed separately. Keep the table release-specific: later source+ * no longer emits bare classes, so it must never be regenerated from it.+ */+// Keep one target per line so reviewers can compare the frozen release snapshot.+/** @type {Record<string, Record<string, [string, string] | Array<[string, string]>>>} */+// prettier-ignore+export const V06_THEME_SELECTOR_TARGETS = {+ "alert-dialog": {"standard":["variant","standard"]},+ "app-shell": {"elevated":["variant","elevated"],"section":["variant","section"],"surface":["variant","surface"],"wash":["variant","wash"]},+ "app-shell-header": {"elevated":["variant","elevated"],"section":["variant","section"],"surface":["variant","surface"],"wash":["variant","wash"]},+ "app-shell-sidenav": {"elevated":["variant","elevated"],"section":["variant","section"],"surface":["variant","surface"],"wash":["variant","wash"]},+ "aspect-ratio": {"ellipse":["shape","ellipse"],"rectangle":["shape","rectangle"]},+ "avatar": {"circle":["shape","circle"],"lg":["size","lg"],"md":["size","md"],"rounded":["shape","rounded"],"size-128":["size","128"],"size-144":["size","144"],"size-16":["size","16"],"size-180":["size","180"],"size-20":["size","20"],"size-24":["size","24"],"size-32":["size","32"],"size-36":["size","36"],"size-40":["size","40"],"size-48":["size","48"],"size-60":["size","60"],"size-64":["size","64"],"size-72":["size","72"],"size-96":["size","96"],"sm":["size","sm"],"square":["shape","square"],"xl":["size","xl"],"xsm":["size","xsm"]},+ "avatar-fallback": {"lg":["size","lg"],"md":["size","md"],"size-128":["size","128"],"size-144":["size","144"],"size-16":["size","16"],"size-180":["size","180"],"size-20":["size","20"],"size-24":["size","24"],"size-32":["size","32"],"size-36":["size","36"],"size-40":["size","40"],"size-48":["size","48"],"size-60":["size","60"],"size-64":["size","64"],"size-72":["size","72"],"size-96":["size","96"],"sm":["size","sm"],"xl":["size","xl"],"xsm":["size","xsm"]},+ "avatar-group": {"circle":["shape","circle"],"lg":["size","lg"],"md":["size","md"],"rounded":["shape","rounded"],"size-128":["size","128"],"size-144":["size","144"],"size-16":["size","16"],"size-180":["size","180"],"size-20":["size","20"],"size-24":["size","24"],"size-32":["size","32"],"size-36":["size","36"],"size-40":["size","40"],"size-48":["size","48"],"size-60":["size","60"],"size-64":["size","64"],"size-72":["size","72"],"size-96":["size","96"],"sm":["size","sm"],"square":["shape","square"],"xl":["size","xl"],"xsm":["size","xsm"]},+ "avatar-group-overflow": {"circle":["shape","circle"],"lg":["size","lg"],"md":["size","md"],"rounded":["shape","rounded"],"size-128":["size","128"],"size-144":["size","144"],"size-16":["size","16"],"size-180":["size","180"],"size-20":["size","20"],"size-24":["size","24"],"size-32":["size","32"],"size-36":["size","36"],"size-40":["size","40"],"size-48":["size","48"],"size-60":["size","60"],"size-64":["size","64"],"size-72":["size","72"],"size-96":["size","96"],"sm":["size","sm"],"square":["shape","square"],"xl":["size","xl"],"xsm":["size","xsm"]},+ "avatar-status-dot": {"error":["variant","error"],"neutral":["variant","neutral"],"success":["variant","success"]},+ "avatar-status-dot-glyph": {"minus":["shape","minus"],"ring":["shape","ring"]},+ "badge": {"blue":["variant","blue"],"cyan":["variant","cyan"],"error":["variant","error"],"green":["variant","green"],"info":["variant","info"],"neutral":["variant","neutral"],"orange":["variant","orange"],"pink":["variant","pink"],"purple":["variant","purple"],"red":["variant","red"],"success":["variant","success"],"teal":["variant","teal"],"warning":["variant","warning"],"yellow":["variant","yellow"]},+ "banner": {"card":["container","card"],"error":["status","error"],"info":["status","info"],"section":["container","section"],"success":["status","success"],"warning":["status","warning"]},+ "banner-content": {"card":["container","card"],"error":["status","error"],"info":["status","info"],"section":["container","section"],"success":["status","success"],"warning":["status","warning"]},+ "banner-frame": {"card":["container","card"],"high":["elevation","high"],"low":["elevation","low"],"med":["elevation","med"],"none":["elevation","none"],"section":["container","section"]},+ "banner-icon": {"accent":["color","accent"],"error":[["color","error"],["status","error"]],"info":["status","info"],"md":["size","md"],"success":[["color","success"],["status","success"]],"warning":[["color","warning"],["status","warning"]]},+ "breadcrumb-item": {"default":["variant","default"],"supporting":["variant","supporting"]},+ "breadcrumb-item-menu-trigger": {"default":["variant","default"],"supporting":["variant","supporting"]},+ "breadcrumbs": {"default":["variant","default"],"supporting":["variant","supporting"]},+ "button": {"destructive":["variant","destructive"],"ghost":["variant","ghost"],"high":["elevation","high"],"lg":["size","lg"],"low":["elevation","low"],"md":["size","md"],"med":["elevation","med"],"none":["elevation","none"],"primary":["variant","primary"],"secondary":["variant","secondary"],"sm":["size","sm"]},+ "button-group": {"high":["elevation","high"],"horizontal":["orientation","horizontal"],"lg":["size","lg"],"low":["elevation","low"],"md":["size","md"],"med":["elevation","med"],"none":["elevation","none"],"sm":["size","sm"],"vertical":["orientation","vertical"]},+ "calendar": {"range":["mode","range"],"single":["mode","single"]},+ "calendar-day": {"disabled":["disabled","disabled"],"in-range":["in-range","in-range"],"selected":["selected","selected"],"today":["today","today"],"today-in-range":["marker","today-in-range"],"today-only":["marker","today-only"]},+ "calendar-nav": {"disabled":["disabled","disabled"],"ghost":["variant","ghost"],"lg":["size","lg"],"md":["size","md"],"next":["nav","next"],"none":["elevation","none"],"prev":["nav","prev"],"sm":["size","sm"]},+ "card": {"blue":["variant","blue"],"cyan":["variant","cyan"],"default":["variant","default"],"gray":["variant","gray"],"green":["variant","green"],"high":["elevation","high"],"low":["elevation","low"],"med":["elevation","med"],"muted":["variant","muted"],"none":["elevation","none"],"orange":["variant","orange"],"pink":["variant","pink"],"purple":["variant","purple"],"red":["variant","red"],"teal":["variant","teal"],"transparent":["variant","transparent"],"yellow":["variant","yellow"]},+ "carousel-scroller": {"edge-fade":["edgeFade","edge-fade"],"gap-0":["gap","0"],"gap-0.5":["gap","0.5"],"gap-1":["gap","1"],"gap-1.5":["gap","1.5"],"gap-2":["gap","2"],"gap-3":["gap","3"],"gap-4":["gap","4"],"padding-0":["padding","0"],"padding-0.5":["padding","0.5"],"padding-1":["padding","1"],"padding-1.5":["padding","1.5"],"padding-10":["padding","10"],"padding-2":["padding","2"],"padding-3":["padding","3"],"padding-4":["padding","4"],"padding-5":["padding","5"],"padding-6":["padding","6"],"padding-8":["padding","8"],"snap":["snap","snap"]},+ "center": {"both":["axis","both"],"horizontal":["axis","horizontal"],"vertical":["axis","vertical"]},+ "chat-composer": {"balanced":["density","balanced"],"compact":["density","compact"],"spacious":["density","spacious"]},+ "chat-composer-drawer": {"collapsed":["collapsed","collapsed"]},+ "chat-layout": {"balanced":["density","balanced"],"compact":["density","compact"],"spacious":["density","spacious"]},+ "chat-message": {"assistant":["sender","assistant"],"balanced":["density","balanced"],"compact":["density","compact"],"spacious":["density","spacious"],"system":["sender","system"],"user":["sender","user"]},+ "chat-message-bubble": {"assistant":["sender","assistant"],"balanced":["density","balanced"],"compact":["density","compact"],"filled":["variant","filled"],"ghost":["variant","ghost"],"spacious":["density","spacious"],"system":["sender","system"],"user":["sender","user"]},+ "chat-message-list": {"balanced":["density","balanced"],"compact":["density","compact"],"spacious":["density","spacious"]},+ "chat-send-button": {"md":["size","md"],"none":["elevation","none"],"primary":["variant","primary"],"secondary":["variant","secondary"],"sm":["size","sm"]},+ "chat-system-message": {"default":["variant","default"],"divider":["variant","divider"]},+ "checkbox": {"checked":["checked","checked"],"disabled":["disabled","disabled"],"indeterminate":["checked","indeterminate"],"md":["size","md"],"sm":["size","sm"]},+ "checkbox-indicator": {"checked":["checked","checked"],"disabled":["disabled","disabled"],"indeterminate":["checked","indeterminate"],"md":["size","md"],"sm":["size","sm"]},+ "checkbox-indicator-check": {"md":["size","md"],"sm":["size","sm"]},+ "checkbox-indicator-dash": {"md":["size","md"],"sm":["size","sm"]},+ "checkbox-input": {"md":["size","md"],"sm":["size","sm"]},+ "citation": {"label":["variant","label"],"number":["variant","number"]},+ "clickable-card": {"blue":["variant","blue"],"cyan":["variant","cyan"],"default":["variant","default"],"gray":["variant","gray"],"green":["variant","green"],"high":["elevation","high"],"low":["elevation","low"],"med":["elevation","med"],"muted":["variant","muted"],"none":["elevation","none"],"orange":["variant","orange"],"pink":["variant","pink"],"purple":["variant","purple"],"red":["variant","red"],"teal":["variant","teal"],"transparent":["variant","transparent"],"yellow":["variant","yellow"]},+ "code": {"inherit":["color","inherit"],"primary":["color","primary"],"secondary":["color","secondary"]},+ "code-block": {"card":["container","card"],"md":["size","md"],"section":["container","section"],"sm":["size","sm"]},+ "code-block-copy-button": {"ghost":["variant","ghost"],"none":["elevation","none"],"sm":["size","sm"]},+ "code-block-header": {"card":["container","card"],"md":["size","md"],"section":["container","section"],"sm":["size","sm"]},+ "code-block-title": {"md":["size","md"],"sm":["size","sm"]},+ "codeblock": {"card":["container","card"],"md":["size","md"],"section":["container","section"],"sm":["size","sm"]},+ "codeblock-copy-button": {"ghost":["variant","ghost"],"none":["elevation","none"],"sm":["size","sm"]},+ "codeblock-header": {"card":["container","card"],"md":["size","md"],"section":["container","section"],"sm":["size","sm"]},+ "codeblock-title": {"md":["size","md"],"sm":["size","sm"]},+ "collapsible": {"balanced":["density","balanced"],"compact":["density","compact"],"divided":["divided","divided"],"spacious":["density","spacious"]},+ "collapsible-content": {"balanced":["density","balanced"],"compact":["density","compact"],"open":["open","open"],"spacious":["density","spacious"]},+ "collapsible-group": {"balanced":["density","balanced"],"compact":["density","compact"],"spacious":["density","spacious"]},+ "collapsible-trigger": {"balanced":["density","balanced"],"compact":["density","compact"],"disabled":["disabled","disabled"],"end":["chevronPosition","end"],"open":["open","open"],"spacious":["density","spacious"],"start":["chevronPosition","start"]},+ "complex-selector": {"error":["status","error"],"ghost":["variant","ghost"],"input":["variant","input"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "complex-selector-indicator-icon": {"collapsed":["state","collapsed"],"expanded":["state","expanded"],"secondary":["color","secondary"],"sm":["size","sm"]},+ "date-input": {"disabled":["disabled","disabled"],"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "date-input-clear-icon": {"secondary":["color","secondary"],"sm":["size","sm"]},+ "date-input-toggle-icon": {"collapsed":["state","collapsed"],"expanded":["state","expanded"],"secondary":["color","secondary"],"sm":["size","sm"]},+ "date-range-input": {"disabled":["disabled","disabled"],"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "date-range-input-clear-icon": {"secondary":["color","secondary"],"sm":["size","sm"]},+ "date-range-input-preset": {"disabled":["disabled","disabled"],"selected":["selected","selected"]},+ "date-range-input-toggle-icon": {"collapsed":["state","collapsed"],"expanded":["state","expanded"],"secondary":["color","secondary"],"sm":["size","sm"]},+ "date-time-input": {"disabled":["disabled","disabled"],"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "date-time-input-clock-icon": {"secondary":["color","secondary"],"sm":["size","sm"]},+ "date-time-input-date-segment": {"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "date-time-input-time-segment": {"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "date-time-input-toggle-icon": {"collapsed":["state","collapsed"],"expanded":["state","expanded"],"secondary":["color","secondary"],"sm":["size","sm"]},+ "dialog": {"fullscreen":["variant","fullscreen"],"standard":["variant","standard"]},+ "divider": {"horizontal":["orientation","horizontal"],"strong":["variant","strong"],"subtle":["variant","subtle"],"vertical":["orientation","vertical"]},+ "dropdown-menu": {"bottom-sheet":["presentation","bottom-sheet"]},+ "dropdown-menu-divider": {"horizontal":["orientation","horizontal"],"subtle":["variant","subtle"]},+ "dropdown-menu-indicator-icon": {"secondary":["color","secondary"],"sm":["size","sm"]},+ "dropdown-menu-item": {"balanced":["density","balanced"],"center":["align","center"],"destructive":["variant","destructive"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"]},+ "dropdown-menu-radio": {"checked":["checked","checked"],"disabled":["disabled","disabled"],"md":["size","md"],"sm":["size","sm"]},+ "empty-state": {"compact":["variant","compact"]},+ "empty-state-description": {"compact":["variant","compact"]},+ "empty-state-title": {"compact":["variant","compact"]},+ "field": {"horizontal-labels":["layout","horizontal-labels"]},+ "field-status": {"attached":["variant","attached"],"detached":["variant","detached"],"error":["type","error"],"success":["type","success"],"tooltip":["variant","tooltip"],"warning":["type","warning"]},+ "field-status-icon": {"error":["type","error"],"inherit":["color","inherit"],"sm":["size","sm"],"success":["type","success"],"warning":["type","warning"]},+ "file-input": {"dropzone":["mode","dropzone"],"error":["status","error"],"input":["mode","input"],"success":["status","success"],"warning":["status","warning"]},+ "file-input-icon": {"dropzone":["mode","dropzone"],"input":["mode","input"]},+ "form-layout": {"horizontal":["direction","horizontal"],"horizontal-labels":["direction","horizontal-labels"],"vertical":["direction","vertical"]},+ "grid": {"center":[["align","center"],["justify","center"]],"end":[["align","end"],["justify","end"]],"gap-0":["gap","0"],"gap-0.5":["gap","0.5"],"gap-1":["gap","1"],"gap-1.5":["gap","1.5"],"gap-10":["gap","10"],"gap-2":["gap","2"],"gap-3":["gap","3"],"gap-4":["gap","4"],"gap-5":["gap","5"],"gap-6":["gap","6"],"gap-8":["gap","8"],"start":[["align","start"],["justify","start"]],"stretch":[["align","stretch"],["justify","stretch"]]},+ "heading": {"accent":["color","accent"],"bold":["weight","bold"],"disabled":["color","disabled"],"display-1":["type","display-1"],"display-2":["type","display-2"],"display-3":["type","display-3"],"hero":["type","hero"],"inherit":["color","inherit"],"level-1":["level","1"],"level-2":["level","2"],"level-3":["level","3"],"level-4":["level","4"],"level-5":["level","5"],"level-6":["level","6"],"medium":["weight","medium"],"normal":["weight","normal"],"placeholder":["color","placeholder"],"primary":["color","primary"],"secondary":["color","secondary"],"semibold":["weight","semibold"]},+ "icon": {"accent":["color","accent"],"blue":["color","blue"],"cyan":["color","cyan"],"disabled":["color","disabled"],"error":["color","error"],"gray":["color","gray"],"green":["color","green"],"inherit":["color","inherit"],"lg":["size","lg"],"md":["size","md"],"orange":["color","orange"],"pink":["color","pink"],"primary":["color","primary"],"purple":["color","purple"],"red":["color","red"],"secondary":["color","secondary"],"sm":["size","sm"],"success":["color","success"],"teal":["color","teal"],"tertiary":["color","tertiary"],"warning":["color","warning"],"xsm":["size","xsm"],"yellow":["color","yellow"]},+ "input-clear-button": {"ghost":["variant","ghost"],"none":["elevation","none"],"sm":["size","sm"]},+ "input-clear-icon": {"secondary":["color","secondary"],"sm":["size","sm"]},+ "input-group": {"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "input-status-icon": {"error":[["color","error"],["status","error"]],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":[["color","success"],["status","success"]],"warning":[["color","warning"],["status","warning"]],"xsm":["size","xsm"]},+ "item": {"balanced":["density","balanced"],"center":["align","center"],"compact":["density","compact"],"spacious":["density","spacious"],"start":["align","start"]},+ "item-swipe-action": {"accent":["variant","accent"],"destructive":["variant","destructive"],"neutral":["variant","neutral"]},+ "item-swipe-panel": {"leading":["side","leading"],"trailing":["side","trailing"]},+ "layout": {"auto":["height","auto"],"fill":["height","fill"]},+ "link": {"accent":["color","accent"],"disabled":["color","disabled"],"inherit":["color","inherit"],"placeholder":["color","placeholder"],"primary":["color","primary"],"secondary":["color","secondary"]},+ "list": {"balanced":["density","balanced"],"circle":["listStyle","circle"],"compact":["density","compact"],"decimal":["listStyle","decimal"],"disc":["listStyle","disc"],"none":["listStyle","none"],"spacious":["density","spacious"]},+ "list-item": {"balanced":["density","balanced"],"center":["align","center"],"compact":["density","compact"],"spacious":["density","spacious"]},+ "markdown": {"compact":["density","compact"],"default":["density","default"]},+ "markdown-blockquote": {"compact":["density","compact"],"default":["density","default"]},+ "markdown-codeblock": {"compact":["density","compact"],"default":["density","default"]},+ "markdown-heading": {"compact":["density","compact"],"default":["density","default"],"level-1":["level","1"],"level-2":["level","2"],"level-3":["level","3"],"level-4":["level","4"],"level-5":["level","5"],"level-6":["level","6"]},+ "markdown-hr": {"compact":["density","compact"],"default":["density","default"]},+ "markdown-image": {"compact":["density","compact"],"default":["density","default"]},+ "markdown-list": {"compact":["density","compact"],"default":["density","default"]},+ "markdown-paragraph": {"compact":["density","compact"],"default":["density","default"]},+ "markdown-table": {"compact":["density","compact"],"default":["density","default"]},+ "metadata-list": {"horizontal":["orientation","horizontal"],"multi":["columns","multi"],"single":["columns","single"],"vertical":["orientation","vertical"]},+ "mobile-nav": {"end":["side","end"],"start":["side","start"]},+ "more-menu": {"bottom-sheet":["presentation","bottom-sheet"]},+ "multi-selector": {"disabled":["disabled","disabled"],"error":["status","error"],"ghost":["variant","ghost"],"input":["variant","input"],"lg":["size","lg"],"md":["size","md"],"readonly":["readonly","readonly"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "multi-selector-clear-icon": {"secondary":["color","secondary"],"sm":["size","sm"]},+ "multi-selector-indicator-icon": {"collapsed":["state","collapsed"],"expanded":["state","expanded"]},+ "multi-selector-option": {"disabled":["disabled","disabled"],"lg":["size","lg"],"md":["size","md"],"select-all":["select-all","select-all"],"selected":["selected","selected"],"sm":["size","sm"]},+ "nav-heading-menu": {"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"]},+ "nav-heading-menu-item": {"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"]},+ "number-input": {"disabled":["disabled","disabled"],"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"readonly":["readonly","readonly"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "outline": {"compact":["density","compact"],"default":["density","default"]},+ "outline-item": {"active":["active","active"]},+ "overlay-scrim": {"bottom":["position","bottom"],"fill":["position","fill"],"top":["position","top"]},+ "pagination": {"compact":["variant","compact"],"count":["variant","count"],"dots":["variant","dots"],"input":["variant","input"],"md":["size","md"],"none":["variant","none"],"pages":["variant","pages"],"sm":["size","sm"]},+ "pagination-dot": {"active":["active","active"],"md":["size","md"],"sm":["size","sm"]},+ "pagination-input-label": {"md":["size","md"],"sm":["size","sm"]},+ "pagination-input-total": {"md":["size","md"],"sm":["size","sm"]},+ "progress-bar": {"accent":["variant","accent"],"error":["variant","error"],"neutral":["variant","neutral"],"success":["variant","success"],"warning":["variant","warning"]},+ "progress-bar-fill": {"accent":["variant","accent"],"disabled":["variant","disabled"],"error":["variant","error"],"neutral":["variant","neutral"],"success":["variant","success"],"warning":["variant","warning"]},+ "progress-bar-mark": {"accent":["variant","accent"],"disabled":["variant","disabled"],"error":["variant","error"],"fill":["placement","fill"],"neutral":["variant","neutral"],"success":["variant","success"],"track":["placement","track"],"warning":["variant","warning"]},+ "progressbar": {"accent":["variant","accent"],"error":["variant","error"],"neutral":["variant","neutral"],"success":["variant","success"],"warning":["variant","warning"]},+ "progressbar-fill": {"accent":["variant","accent"],"disabled":["variant","disabled"],"error":["variant","error"],"neutral":["variant","neutral"],"success":["variant","success"],"warning":["variant","warning"]},+ "progressbar-mark": {"accent":["variant","accent"],"disabled":["variant","disabled"],"error":["variant","error"],"fill":["placement","fill"],"neutral":["variant","neutral"],"success":["variant","success"],"track":["placement","track"],"warning":["variant","warning"]},+ "radio": {"checked":["checked","checked"],"disabled":["disabled","disabled"],"md":["size","md"],"sm":["size","sm"]},+ "radio-dot": {"md":["size","md"],"sm":["size","sm"]},+ "radio-indicator": {"checked":["checked","checked"],"disabled":["disabled","disabled"],"md":["size","md"],"sm":["size","sm"]},+ "radio-indicator-dot": {"md":["size","md"],"sm":["size","sm"]},+ "radio-list": {"horizontal":["orientation","horizontal"],"md":["size","md"],"sm":["size","sm"],"vertical":["orientation","vertical"]},+ "radio-list-item": {"balanced":["density","balanced"],"center":["align","center"],"disabled":["disabled","disabled"],"md":["size","md"],"selected":["selected","selected"],"sm":["size","sm"]},+ "scrollable-area": {"block":["axis","block"],"both":["axis","both"],"inline":["axis","inline"]},+ "section": {"muted":["variant","muted"],"section":["variant","section"],"transparent":["variant","transparent"]},+ "segmented-control": {"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"]},+ "segmented-control-item": {"disabled":["disabled","disabled"],"lg":["size","lg"],"md":["size","md"],"selected":["selected","selected"],"sm":["size","sm"]},+ "selectable-card": {"blue":["variant","blue"],"cyan":["variant","cyan"],"default":["variant","default"],"false":["selected","false"],"gray":["variant","gray"],"green":["variant","green"],"high":["elevation","high"],"low":["elevation","low"],"med":["elevation","med"],"muted":["variant","muted"],"none":["elevation","none"],"orange":["variant","orange"],"pink":["variant","pink"],"purple":["variant","purple"],"red":["variant","red"],"teal":["variant","teal"],"transparent":["variant","transparent"],"true":["selected","true"],"yellow":["variant","yellow"]},+ "selector": {"disabled":["disabled","disabled"],"error":["status","error"],"ghost":["variant","ghost"],"input":["variant","input"],"lg":["size","lg"],"md":["size","md"],"readonly":["readonly","readonly"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "selector-check": {"accent":["color","accent"],"checked":["checked","checked"],"disabled":[["color","disabled"],["disabled","disabled"]],"sm":["size","sm"]},+ "selector-clear-icon": {"secondary":["color","secondary"],"sm":["size","sm"]},+ "selector-indicator-icon": {"collapsed":["state","collapsed"],"expanded":["state","expanded"]},+ "selector-option": {"balanced":["density","balanced"],"center":["align","center"]},+ "selector-option-row": {"disabled":["disabled","disabled"],"lg":["size","lg"],"md":["size","md"],"selected":["selected","selected"],"sm":["size","sm"]},+ "side-nav": {"topbar":["mode","topbar"]},+ "side-nav-item": {"disabled":["disabled","disabled"],"lg":["size","lg"],"md":["size","md"],"selected":["selected","selected"],"sm":["size","sm"]},+ "slider": {"disabled":["disabled","disabled"],"horizontal":["orientation","horizontal"],"vertical":["orientation","vertical"]},+ "slider-control": {"disabled":["disabled","disabled"],"horizontal":["orientation","horizontal"],"vertical":["orientation","vertical"]},+ "slider-thumb": {"disabled":["disabled","disabled"],"horizontal":["orientation","horizontal"],"vertical":["orientation","vertical"]},+ "slider-track": {"horizontal":["orientation","horizontal"],"vertical":["orientation","vertical"]},+ "spinner": {"default":["shade","default"],"inherit":["shade","inherit"],"lg":["size","lg"],"md":["size","md"],"onMedia":["shade","onMedia"],"sm":["size","sm"],"subtle":["shade","subtle"],"xl":["size","xl"]},+ "stack": {"gap-0":["gap","0"],"gap-0.5":["gap","0.5"],"gap-1":["gap","1"],"gap-1.5":["gap","1.5"],"gap-10":["gap","10"],"gap-2":["gap","2"],"gap-3":["gap","3"],"gap-4":["gap","4"],"gap-5":["gap","5"],"gap-6":["gap","6"],"gap-8":["gap","8"],"horizontal":["direction","horizontal"],"nowrap":["wrap","nowrap"],"vertical":["direction","vertical"],"wrap":["wrap","wrap"],"wrap-reverse":["wrap","wrap-reverse"]},+ "stack-item": {"fill":["size","fill"],"static":["size","static"]},+ "status-dot": {"accent":["variant","accent"],"error":["variant","error"],"neutral":["variant","neutral"],"success":["variant","success"],"warning":["variant","warning"]},+ "statusdot": {"accent":["variant","accent"],"error":["variant","error"],"neutral":["variant","neutral"],"success":["variant","success"],"warning":["variant","warning"]},+ "step": {"accent":["status","accent"],"completed":["progress","completed"],"error":["status","error"],"in-progress":["progress","in-progress"],"not-started":["progress","not-started"],"success":["status","success"],"warning":["status","warning"]},+ "step-description": {"accent":["status","accent"],"completed":["progress","completed"],"error":["status","error"],"in-progress":["progress","in-progress"],"not-started":["progress","not-started"],"success":["status","success"],"warning":["status","warning"]},+ "step-indicator": {"accent":["status","accent"],"completed":["progress","completed"],"error":["status","error"],"in-progress":["progress","in-progress"],"not-started":["progress","not-started"],"success":["status","success"],"warning":["status","warning"]},+ "step-label": {"accent":["status","accent"],"completed":["progress","completed"],"disabled":["disabled","disabled"],"error":["status","error"],"in-progress":["progress","in-progress"],"not-started":["progress","not-started"],"success":["status","success"],"warning":["status","warning"]},+ "stepper": {"horizontal":["orientation","horizontal"],"on-track":["indicatorPosition","on-track"],"separated":["indicatorPosition","separated"],"vertical":["orientation","vertical"]},+ "switch": {"checked":["checked","checked"],"disabled":["disabled","disabled"],"md":["size","md"],"sm":["size","sm"]},+ "switch-field": {"spread":["labelSpacing","spread"],"start":["labelPosition","start"]},+ "switch-thumb": {"checked":["checked","checked"],"md":["size","md"],"sm":["size","sm"]},+ "tab": {"selected":["selected","selected"]},+ "tab-indicator": {"selected":["selected","selected"]},+ "tab-list": {"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"]},+ "table-cell": {"balanced":["density","balanced"],"compact":["density","compact"],"spacious":["density","spacious"]},+ "table-header-cell": {"balanced":["density","balanced"],"compact":["density","compact"],"spacious":["density","spacious"]},+ "text": {"accent":["color","accent"],"base":["size","base"],"body":["type","body"],"code":["type","code"],"disabled":["color","disabled"],"display-1":["type","display-1"],"display-2":["type","display-2"],"display-3":["type","display-3"],"inherit":[["color","inherit"],["type","inherit"]],"label":["type","label"],"large":["type","large"],"lg":["size","lg"],"placeholder":["color","placeholder"],"primary":["color","primary"],"secondary":["color","secondary"],"size-2xl":["size","2xl"],"size-2xs":["size","2xs"],"size-3xl":["size","3xl"],"size-3xs":["size","3xs"],"size-4xl":["size","4xl"],"size-4xs":["size","4xs"],"sm":["size","sm"],"supporting":["type","supporting"],"xl":["size","xl"],"xsm":["size","xsm"]},+ "text-area": {"disabled":["disabled","disabled"],"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"readonly":["readonly","readonly"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "text-input": {"disabled":["disabled","disabled"],"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"readonly":["readonly","readonly"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "textarea": {"disabled":["disabled","disabled"],"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"readonly":["readonly","readonly"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "time-input": {"disabled":["disabled","disabled"],"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "timestamp": {"accent":["color","accent"],"base":["size","base"],"body":["type","body"],"code":["type","code"],"date":["format","date"],"date_long":["format","date_long"],"date_time":["format","date_time"],"date_weekday":["format","date_weekday"],"disabled":["color","disabled"],"display-1":["type","display-1"],"display-2":["type","display-2"],"display-3":["type","display-3"],"inherit":[["color","inherit"],["type","inherit"]],"label":["type","label"],"large":["type","large"],"lg":["size","lg"],"placeholder":["color","placeholder"],"primary":["color","primary"],"relative":["format","relative"],"relative_short":["format","relative_short"],"secondary":["color","secondary"],"size-2xl":["size","2xl"],"size-2xs":["size","2xs"],"size-3xl":["size","3xl"],"size-3xs":["size","3xs"],"size-4xl":["size","4xl"],"size-4xs":["size","4xs"],"sm":["size","sm"],"supporting":["type","supporting"],"system_date":["format","system_date"],"system_date_time":["format","system_date_time"],"system_time":["format","system_time"],"time":["format","time"],"unix_seconds":["format","unix_seconds"],"xl":["size","xl"],"xsm":["size","xsm"]},+ "timestamp-copy-button": {"ghost":["variant","ghost"],"none":["elevation","none"],"sm":["size","sm"]},+ "toast": {"error":["type","error"],"info":["type","info"]},+ "toggle-button": {"false":["isPressed","false"],"ghost":["variant","ghost"],"high":["elevation","high"],"lg":["size","lg"],"low":["elevation","low"],"md":["size","md"],"med":["elevation","med"],"none":["elevation","none"],"sm":["size","sm"],"true":["isPressed","true"]},+ "token": {"blue":["color","blue"],"cyan":["color","cyan"],"default":["color","default"],"gray":["color","gray"],"green":["color","green"],"lg":["size","lg"],"md":["size","md"],"orange":["color","orange"],"pink":["color","pink"],"purple":["color","purple"],"red":["color","red"],"sm":["size","sm"],"teal":["color","teal"],"yellow":["color","yellow"]},+ "tokenizer": {"disabled":["disabled","disabled"],"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+ "toolbar": {"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"]},+ "top-nav": {"mobile-bar":["mode","mobile-bar"]},+ "top-nav-item": {"drawer":["mode","drawer"],"selected":["selected","selected"]},+ "top-nav-mega-menu": {"drawer":["mode","drawer"]},+ "top-nav-mega-menu-item": {"drawer":["mode","drawer"]},+ "tree-list": {"balanced":["density","balanced"],"compact":["density","compact"],"lineGuides":["variant","lineGuides"],"noGuides":["variant","noGuides"],"spacious":["density","spacious"]},+ "tree-list-chevron": {"collapsed":["state","collapsed"],"expanded":["state","expanded"]},+ "tree-list-item": {"balanced":["density","balanced"],"compact":["density","compact"],"disabled":["disabled","disabled"],"selected":["selected","selected"],"spacious":["density","spacious"]},+ "tree-list-item-label": {"selected":["selected","selected"]},+ "typeahead": {"error":["status","error"],"lg":["size","lg"],"md":["size","md"],"sm":["size","sm"],"success":["status","success"],"warning":["status","warning"]},+};++/** @type {Record<string, Array<{axis: string, token: 'class-value' | 'prefixed', prefix?: string}>>} */+// prettier-ignore+export const V06_THEME_SELECTOR_DYNAMIC_AXES = {+ "code-block": [{"axis":"language","token":"class-value"}],+ "code-block-header": [{"axis":"language","token":"class-value"}],+ "code-block-title": [{"axis":"language","token":"class-value"}],+ "codeblock": [{"axis":"language","token":"class-value"}],+ "codeblock-header": [{"axis":"language","token":"class-value"}],+ "codeblock-title": [{"axis":"language","token":"class-value"}],+ "grid": [{"axis":"columns","token":"prefixed","prefix":"columns-"}],+ "metadata-list": [{"axis":"columns","token":"prefixed","prefix":"columns-"},{"axis":"columns","token":"class-value"}],+ "outline-item": [{"axis":"level","token":"prefixed","prefix":"level-"}],+};diff --git a/packages/cli/assets/codemods/transforms/next/migrate-deprecated-theme-surface.mjs b/packages/cli/assets/codemods/transforms/next/migrate-deprecated-theme-surface.mjsnew file mode 100644index 0000000000..096505bb55--- /dev/null+++ b/packages/cli/assets/codemods/transforms/next/migrate-deprecated-theme-surface.mjs@@ -0,0 +1,624 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Migrate the component-theming compatibility surface removed in 0.7.+ *+ * Static keys directly inside a theme's `components` object move to their+ * canonical target. A theme is a `defineTheme()` call imported from Astryx, an+ * object typed as an Astryx theme (annotation, `as`, or `satisfies`), or a+ * direct theme object with a static `name` whose component entries are style+ * objects. CSS selectors move the same target classes, keep the owner scope of+ * the per-component clear-icon aliases, and replace target-qualified bare+ * prop/state classes with reflected `data-*` selectors using the final 0.6+ * runtime contract. A known bare class that cannot be classified for its target+ * gets a TODO. Dynamic theme keys, unqualified classes, declarations, comments,+ * and strings containing CSS are left for manual review.+ */++import path from 'node:path';+import postcss from 'postcss';+import selectorParser from 'postcss-selector-parser';+import {migrateAstryxThemeSelectors} from '../v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs';+import {+ V06_THEME_SELECTOR_DYNAMIC_AXES,+ V06_THEME_SELECTOR_TARGETS,+} from './migrate-deprecated-theme-surface-v0.6-data.mjs';++/** @type {Readonly<Record<string, string>>} */+export const DEPRECATED_THEME_TARGETS = Object.freeze({+ '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',+});++/**+ * Clear-icon aliases each styled one owner's clear glyph. The shared target+ * styles every input's clear glyph, so CSS keeps the owner as an ancestor scope.+ * @type {Readonly<Record<string, string>>}+ */+export const SCOPED_CLEAR_ICON_OWNERS = Object.freeze({+ 'date-input-clear-icon': 'date-input',+ 'date-range-input-clear-icon': 'date-range-input',+ 'multi-selector-clear-icon': 'multi-selector',+ 'selector-clear-icon': 'selector',+});++const SELECTOR_DATA = {+ targets: V06_THEME_SELECTOR_TARGETS,+ dynamicAxes: V06_THEME_SELECTOR_DYNAMIC_AXES,+};++export const meta = {+ title: 'Migrate removed component theme aliases and selectors',+ description:+ 'Renames all 21 removed component target aliases in static theme maps and CSS, and replaces target-qualified bare prop/state classes with reflected data attributes.',+ fileExtensions: ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs', '.css'],+};++const TODO_PREFIX = ' TODO(astryx upgrade): merge deprecated theme target ';+const SCOPE_TODO_PREFIX = ' TODO(astryx upgrade): ';+const KNOWN_SELECTOR_TARGETS = new Set([+ ...Object.keys(V06_THEME_SELECTOR_TARGETS),+ ...Object.keys(V06_THEME_SELECTOR_DYNAMIC_AXES),+]);+/** Every bare class token any 0.6 target emitted. */+const KNOWN_BARE_TOKENS = new Set(+ Object.values(V06_THEME_SELECTOR_TARGETS).flatMap(tokens =>+ Object.keys(tokens),+ ),+);++/** @param {string} target @param {string} token */+function targetEmittedBareClass(target, token) {+ if (V06_THEME_SELECTOR_TARGETS[target]?.[token] != null) return true;+ return (V06_THEME_SELECTOR_DYNAMIC_AXES[target] ?? []).some(rule =>+ rule.token === 'class-value'+ ? true+ : typeof rule.prefix === 'string' &&+ token.startsWith(rule.prefix) &&+ /^\d/.test(token.slice(rule.prefix.length)),+ );+}++/** @param {any} pseudo @returns {Set<string>} */+function compoundTargetsForPseudo(pseudo) {+ const parent = pseudo.parent;+ if (parent?.type !== 'selector' || !Array.isArray(parent.nodes)) {+ return new Set();+ }++ const index = parent.nodes.indexOf(pseudo);+ const compound = [];+ for (let cursor = index - 1; cursor >= 0; cursor--) {+ const node = parent.nodes[cursor];+ if (node.type === 'combinator') break;+ compound.push(node);+ }+ for (let cursor = index + 1; cursor < parent.nodes.length; cursor++) {+ const node = parent.nodes[cursor];+ if (node.type === 'combinator') break;+ compound.push(node);+ }++ const targets = new Set();+ for (const node of compound) {+ if (node.type !== 'class' || !node.value.startsWith('astryx-')) continue;+ const target = node.value.slice('astryx-'.length);+ if (KNOWN_SELECTOR_TARGETS.has(target)) targets.add(target);+ }+ return targets;+}++/** @param {any} selector */+function finishSelectorMigration(selector) {+ selector.walkPseudos((/** @type {any} */ pseudo) => {+ if (pseudo.value !== ':is' || !Array.isArray(pseudo.nodes)) return;+ const targets = compoundTargetsForPseudo(pseudo);+ if (targets.size === 0) return;+ const hasAttributeArm = pseudo.nodes.some(+ (/** @type {any} */ arm) =>+ arm.type === 'selector' &&+ arm.nodes.some((/** @type {any} */ node) => node.type === 'attribute'),+ );+ if (!hasAttributeArm) return;++ for (const arm of [...pseudo.nodes]) {+ if (arm.type !== 'selector' || arm.nodes.length !== 1) continue;+ const only = arm.nodes[0];+ if (+ only.type !== 'class' ||+ only.value.startsWith('astryx-') ||+ ![...targets].some(target => targetEmittedBareClass(target, only.value))+ ) {+ continue;+ }+ arm.remove();+ }+ });++ selector.walkClasses((/** @type {any} */ classNode) => {+ if (!classNode.value.startsWith('astryx-')) return;+ const oldKey = classNode.value.slice('astryx-'.length);+ const newKey = DEPRECATED_THEME_TARGETS[oldKey];+ if (!newKey) return;+ classNode.value = `astryx-${newKey}`;+ const owner = SCOPED_CLEAR_ICON_OWNERS[oldKey];+ if (owner) classNode.parent.insertAfter(classNode, ownerScope(owner));+ });+}++/**+ * `:where(.astryx-<owner> *)` keeps the alias's owner scope without changing+ * the selector's specificity.+ * @param {string} owner+ */+function ownerScope(owner) {+ return selectorParser.pseudo({+ value: ':where',+ nodes: [+ selectorParser.selector({+ value: '',+ nodes: [+ selectorParser.className({value: `astryx-${owner}`}),+ selectorParser.combinator({value: ' '}),+ selectorParser.universal({value: '*'}),+ ],+ }),+ ],+ });+}++/**+ * Bare classes that still qualify a known target after migration and that some+ * 0.6 target emitted. They can no longer match Astryx output.+ * @param {string} selectorText+ * @returns {string[]}+ */+function unclassifiedBareClasses(selectorText) {+ /** @type {Set<string>} */+ const found = new Set();+ selectorParser(selectors => {+ selectors.walk((/** @type {any} */ node) => {+ if (node.type !== 'selector') return;+ /** @type {any[][]} */+ const compounds = [[]];+ for (const child of node.nodes) {+ if (child.type === 'combinator') compounds.push([]);+ else compounds[compounds.length - 1].push(child);+ }+ for (const compound of compounds) {+ const hasTarget = compound.some(+ child =>+ child.type === 'class' &&+ child.value.startsWith('astryx-') &&+ KNOWN_SELECTOR_TARGETS.has(child.value.slice('astryx-'.length)),+ );+ if (!hasTarget) continue;+ for (const child of compound) {+ if (+ child.type === 'class' &&+ !child.value.startsWith('astryx-') &&+ KNOWN_BARE_TOKENS.has(child.value)+ ) {+ found.add(child.value);+ }+ }+ }+ });+ }).processSync(selectorText, {lossless: true});+ return [...found].sort();+}++/** @param {string} selector */+function finishSelectorText(selector) {+ return selectorParser(selectors => {+ selectors.each(finishSelectorMigration);+ }).processSync(selector, {lossless: true});+}++/** @param {string} params */+function finishScopeParams(params) {+ let result = '';+ let last = 0;+ let depth = 0;+ let groupStart = -1;+ let quote = '';+ let escaped = false;++ for (let index = 0; index < params.length; index++) {+ const char = params[index];+ if (escaped) {+ escaped = false;+ continue;+ }+ if (char === '\\') {+ escaped = true;+ continue;+ }+ if (quote) {+ if (char === quote) quote = '';+ continue;+ }+ if (char === '"' || char === "'") {+ quote = char;+ continue;+ }+ if (char === '(') {+ if (depth === 0) {+ result += params.slice(last, index + 1);+ groupStart = index + 1;+ }+ depth++;+ continue;+ }+ if (char === ')' && depth > 0) {+ depth--;+ if (depth === 0 && groupStart >= 0) {+ result += finishSelectorText(params.slice(groupStart, index));+ result += ')';+ last = index + 1;+ groupStart = -1;+ }+ }+ }+ return result + params.slice(last);+}++/** @param {string} source @param {string} from */+function migrateCss(source, from) {+ const migrated = migrateAstryxThemeSelectors(source, from, SELECTOR_DATA);+ const root = postcss.parse(migrated, {from});+ /** @type {Set<string>} */+ const existingComments = new Set();+ root.walkComments(comment => {+ existingComments.add(comment.text.trim());+ });+ root.walkRules(rule => {+ rule.selector = finishSelectorText(rule.selector);+ const tokens = unclassifiedBareClasses(rule.selector);+ if (tokens.length === 0) return;+ const list = tokens.map(token => `.${token}`).join(', ');+ const text =+ `${SCOPE_TODO_PREFIX}Astryx 0.7 no longer emits bare prop/state classes, and ${list} had no known 0.6 meaning on this target. Replace it with the target's data-* attribute or remove it.`.trim();+ if (existingComments.has(text)) return;+ rule.before(postcss.comment({text}));+ existingComments.add(text);+ });+ root.walkAtRules('scope', atRule => {+ atRule.params = finishScopeParams(atRule.params);+ });+ return root.toString();+}++/** @param {any} property @returns {string | null} */+function staticPropertyName(property) {+ const key = property?.key;+ if (!key) return null;+ if (!property.computed && key.type === 'Identifier') return key.name;+ if (+ (key.type === 'StringLiteral' || key.type === 'Literal') &&+ typeof key.value === 'string'+ ) {+ return key.value;+ }+ return null;+}++const ASTRYX_MODULE = /^@astryxdesign\//u;+const THEME_TYPE_NAMES = new Set([+ 'DefineThemeInput',+ 'DefinedTheme',+ 'ResolvedDefinedTheme',+]);+const TS_WRAPPERS = new Set([+ 'TSAsExpression',+ 'TSSatisfiesExpression',+ 'TSNonNullExpression',+ 'TSTypeAssertion',+ 'TypeCastExpression',+ 'ParenthesizedExpression',+]);++/**+ * Local names that refer to Astryx's `defineTheme`, its theme types, or an+ * Astryx namespace import.+ * @param {any} root @param {any} j+ */+function astryxThemeBindings(root, j) {+ const bindings = {+ defineTheme: new Set(),+ themeTypes: new Set(),+ namespaces: new Set(),+ };+ root.find(j.ImportDeclaration).forEach((/** @type {any} */ importPath) => {+ const source = importPath.node.source?.value;+ if (typeof source !== 'string' || !ASTRYX_MODULE.test(source)) return;+ for (const specifier of importPath.node.specifiers ?? []) {+ const local = specifier.local?.name;+ if (!local) continue;+ if (specifier.type === 'ImportNamespaceSpecifier') {+ bindings.namespaces.add(local);+ } else if (specifier.type === 'ImportSpecifier') {+ const imported = specifier.imported?.name ?? specifier.imported?.value;+ if (imported === 'defineTheme') bindings.defineTheme.add(local);+ if (THEME_TYPE_NAMES.has(imported)) bindings.themeTypes.add(local);+ }+ }+ });+ return bindings;+}++/** @param {any} name @param {Set<string>} locals @param {Set<string>} namespaces @param {Set<string>} members */+function namesBinding(name, locals, namespaces, members) {+ if (name?.type === 'Identifier') return locals.has(name.name);+ const object = name?.object ?? name?.left;+ const property = name?.property ?? name?.right;+ return (+ object?.type === 'Identifier' &&+ namespaces.has(object.name) &&+ property?.type === 'Identifier' &&+ members.has(property.name)+ );+}++/** @param {any} typeNode @param {ReturnType<typeof astryxThemeBindings>} bindings */+function isAstryxThemeType(typeNode, bindings) {+ const node = typeNode?.typeAnnotation ?? typeNode;+ return (+ node?.type === 'TSTypeReference' &&+ namesBinding(+ node.typeName,+ bindings.themeTypes,+ bindings.namespaces,+ THEME_TYPE_NAMES,+ )+ );+}++/**+ * True for a theme object whose shape alone identifies it: a static string+ * `name` beside a `components` map whose entries are all style objects.+ * @param {any} node+ */+function isDirectThemeObject(node) {+ const properties = node.properties ?? [];+ const name = properties.find(+ (/** @type {any} */ property) => staticPropertyName(property) === 'name',+ );+ if (!(+ (name?.value?.type === 'StringLiteral' ||+ name?.value?.type === 'Literal') &&+ typeof name.value.value === 'string'+ )) {+ return false;+ }+ const components = properties.find(+ (/** @type {any} */ property) =>+ staticPropertyName(property) === 'components',+ );+ const map = components?.value;+ if (map?.type === 'Identifier') return true;+ return (+ map?.type === 'ObjectExpression' &&+ map.properties.every(+ (/** @type {any} */ entry) =>+ entry.type === 'SpreadElement' ||+ entry.value?.type === 'ObjectExpression',+ )+ );+}++/**+ * True when this object literal is an Astryx theme: the argument of an+ * imported `defineTheme()`, typed as an Astryx theme, or a direct theme object.+ * @param {any} objectPath @param {ReturnType<typeof astryxThemeBindings>} bindings+ */+function isThemeRoot(objectPath, bindings) {+ let child = objectPath;+ let parent = objectPath.parent;+ while (parent != null && TS_WRAPPERS.has(parent.node.type)) {+ if (isAstryxThemeType(parent.node.typeAnnotation, bindings)) return true;+ child = parent;+ parent = parent.parent;+ }+ const node = parent?.node;+ if (+ node?.type === 'CallExpression' &&+ node.arguments?.[0] === child.node &&+ namesBinding(+ node.callee,+ bindings.defineTheme,+ bindings.namespaces,+ new Set(['defineTheme']),+ )+ ) {+ return true;+ }+ if (+ node?.type === 'VariableDeclarator' &&+ isAstryxThemeType(node.id?.typeAnnotation, bindings)+ ) {+ return true;+ }+ return isDirectThemeObject(objectPath.node);+}++/**+ * Walk outward from the object that owns a `components` property, through+ * nested theme sections such as `onDark` and `adaptations.rules[].value`,+ * until reaching a theme root. Leaving literal object/array structure ends+ * the search.+ * @param {any} ownerPath @param {ReturnType<typeof astryxThemeBindings>} bindings+ */+function hasThemeContext(ownerPath, bindings) {+ for (let current = ownerPath; current != null;) {+ if (current.node.type === 'ObjectExpression') {+ if (isThemeRoot(current, bindings)) return true;+ }+ let parent = current.parent;+ while (parent != null && TS_WRAPPERS.has(parent.node.type)) {+ parent = parent.parent;+ }+ const type = parent?.node.type;+ if (type === 'ObjectProperty' || type === 'Property') {+ current = parent.parent;+ } else if (type === 'ArrayExpression') {+ current = parent;+ } else {+ return false;+ }+ }+ return false;+}++/** @param {any} objectPath @param {any} root @param {any} j @param {ReturnType<typeof astryxThemeBindings>} bindings */+function componentsVariableFeedsTheme(objectPath, root, j, bindings) {+ const parent = objectPath.parent?.node;+ if (+ parent?.type !== 'VariableDeclarator' ||+ parent.id?.type !== 'Identifier' ||+ parent.id.name !== 'components'+ ) {+ return false;+ }++ const bindingScope = objectPath.scope.lookup('components');+ let feedsTheme = false;+ root.find(j.ObjectProperty).forEach((/** @type {any} */ propertyPath) => {+ if (feedsTheme) return;+ const property = propertyPath.node;+ if (+ staticPropertyName(property) !== 'components' ||+ property.value?.type !== 'Identifier' ||+ property.value.name !== 'components'+ ) {+ return;+ }+ if (+ bindingScope != null &&+ propertyPath.scope.lookup('components') !== bindingScope+ ) {+ return;+ }+ if (hasThemeContext(propertyPath.parent, bindings)) feedsTheme = true;+ });+ return feedsTheme;+}++/** @param {any} path @param {any} root @param {any} j @param {ReturnType<typeof astryxThemeBindings>} bindings */+function isComponentsMap(path, root, j, bindings) {+ let parentPath = path.parent;+ while (parentPath != null && TS_WRAPPERS.has(parentPath.node.type)) {+ parentPath = parentPath.parent;+ }+ const parent = parentPath?.node;+ if (+ (parent?.type === 'ObjectProperty' || parent?.type === 'Property') &&+ staticPropertyName(parent) === 'components'+ ) {+ return hasThemeContext(parentPath.parent, bindings);+ }+ return componentsVariableFeedsTheme(path, root, j, bindings);+}++/** @param {any} property @param {string} oldKey @param {string} newKey @param {any} j */+function addCollisionTodo(property, oldKey, newKey, j) {+ const message = `${TODO_PREFIX}\`${oldKey}\` into \`${newKey}\`; both keys are present. `;+ if (+ property.comments?.some(+ (/** @type {any} */ comment) => comment.value === message,+ )+ )+ return;+ property.comments = [+ ...(property.comments ?? []),+ j.commentBlock(message, true, false),+ ];+}++/**+ * A theme key cannot carry an ancestor scope, so a renamed clear-icon alias now+ * styles every input's clear icon. Say so where the rename happened.+ * @param {any} property @param {string} oldKey @param {string} owner @param {any} j+ */+function addScopeTodo(property, oldKey, owner, j) {+ const message = `${SCOPE_TODO_PREFIX}\`${oldKey}\` became \`input-clear-icon\`, which styles the clear icon of every input. To keep these styles on one component, move them to CSS under \`.astryx-input-clear-icon:where(.astryx-${owner} *)\`. `;+ property.comments = [+ ...(property.comments ?? []),+ j.commentBlock(message, true, false),+ ];+}++/** @param {string} source @param {any} j */+function migrateStaticThemeKeys(source, j) {+ const root = j(source);+ const bindings = astryxThemeBindings(root, j);+ let changed = false;++ root.find(j.ObjectExpression).forEach((/** @type {any} */ objectPath) => {+ if (!isComponentsMap(objectPath, root, j, bindings)) return;+ const properties = objectPath.node.properties ?? [];+ const staticKeys = new Set(+ properties.map(staticPropertyName).filter(Boolean),+ );++ for (const property of properties) {+ if (property.type !== 'ObjectProperty' && property.type !== 'Property') {+ continue;+ }+ const oldKey = staticPropertyName(property);+ const newKey = oldKey ? DEPRECATED_THEME_TARGETS[oldKey] : undefined;+ if (!oldKey || !newKey) continue;++ if (staticKeys.has(newKey)) {+ const before = property.comments?.length ?? 0;+ addCollisionTodo(property, oldKey, newKey, j);+ if ((property.comments?.length ?? 0) !== before) changed = true;+ continue;+ }++ property.key = j.stringLiteral(newKey);+ property.computed = false;+ property.shorthand = false;+ const owner = SCOPED_CLEAR_ICON_OWNERS[oldKey];+ if (owner) addScopeTodo(property, oldKey, owner, j);+ staticKeys.delete(oldKey);+ staticKeys.add(newKey);+ changed = true;+ }+ });++ return changed ? root.toSource({quote: 'single'}) : undefined;+}++/**+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api+ * @returns {string | null | undefined}+ */+export default function migrateDeprecatedThemeSurface(file, api) {+ const extension = path.extname(file.path).toLowerCase();+ if (extension === '.css') {+ const result = migrateCss(file.source, file.path);+ return result === file.source ? undefined : result;+ }+ return migrateStaticThemeKeys(file.source, api.jscodeshift);+}diff --git a/packages/cli/assets/codemods/transforms/v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs b/packages/cli/assets/codemods/transforms/v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjsindex bd8086d74a..3b2175e1cf 100644--- a/packages/cli/assets/codemods/transforms/v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs+++ b/packages/cli/assets/codemods/transforms/v0.6.0/migrate-astryx-theme-selectors-to-data-attrs.mjs@@ -30,10 +30,16 @@ export const meta = {/** @typedef {[string, string]} AttributeCandidate *//** @typedef {AttributeCandidate | AttributeCandidate[]} CandidateEntry */+/** @typedef {Record<string, Array<{axis: string, token: 'class-value' | 'prefixed', prefix?: string}>>} DynamicAxes */+/** @typedef {{targets: Record<string, Record<string, CandidateEntry>>, dynamicAxes: DynamicAxes}} SelectorData */++// The selector tables in effect for the current synchronous migration. They+// default to the 0.5.4 snapshot this codemod shipped with; a later release can+// pass a newer frozen snapshot to migrateAstryxThemeSelectors()./** @type {Record<string, Record<string, CandidateEntry>>} */-const TARGETS = V054_THEME_SELECTOR_TARGETS;-/** @type {Record<string, Array<{axis: string, token: 'class-value' | 'prefixed', prefix?: string}>>} */-const DYNAMIC_AXES = V054_THEME_SELECTOR_DYNAMIC_AXES;+let TARGETS = V054_THEME_SELECTOR_TARGETS;+/** @type {DynamicAxes} */+let DYNAMIC_AXES = V054_THEME_SELECTOR_DYNAMIC_AXES;const SAME_ELEMENT_FUNCTIONAL_PSEUDOS = new Set([':is', ':where', ':not']);/** @param {string} axis */@@ -108,7 +114,10 @@ function candidatesFor(target, token) {function dedupeCandidates(candidates) {return [...new Map(- candidates.map(candidate => [`${candidate[0]}\0${candidate[1]}`, candidate]),+ candidates.map(candidate => [+ `${candidate[0]}\0${candidate[1]}`,+ candidate,+ ]),).values(),];}@@ -410,10 +419,7 @@ function migrateCompound(const selectorArms = node.nodes.filter((/** @type {any} */ selector) => selector.type === 'selector',);- if (- completedArms.size > 0 &&- completedArms.size === selectorArms.length- ) {+ if (completedArms.size > 0 && completedArms.size === selectorArms.length) {continue;}if (node.value === ':nth-child' || node.value === ':nth-last-child') {@@ -427,11 +433,7 @@ function migrateCompound(: [];for (const selector of selectorArms) {if (completedArms.has(selector)) continue;- migrateSelectorNode(- selector,- nestedTargets,- nestedConditionalTargets,- );+ migrateSelectorNode(selector, nestedTargets, nestedConditionalTargets);}}@@ -490,9 +492,7 @@ function combineSelectorListContexts(contexts) {);return {guaranteed,- possible: [- ...new Set(contexts.flatMap(context => context.possible)),- ],+ possible: [...new Set(contexts.flatMap(context => context.possible))],};}@@ -655,8 +655,28 @@ function migrateScopeParams(params) {return result + params.slice(last);}+/**+ * @param {string} source+ * @param {string} [from]+ * @param {SelectorData} [data] frozen selector tables; defaults to 0.5.4+ * @returns {string}+ */+export function migrateAstryxThemeSelectors(source, from = 'styles.css', data) {+ if (data == null) return migrateWithActiveTables(source, from);+ const previousTargets = TARGETS;+ const previousAxes = DYNAMIC_AXES;+ TARGETS = data.targets;+ DYNAMIC_AXES = data.dynamicAxes;+ try {+ return migrateWithActiveTables(source, from);+ } finally {+ TARGETS = previousTargets;+ DYNAMIC_AXES = previousAxes;+ }+}+/** @param {string} source @param {string} from @returns {string} */-export function migrateAstryxThemeSelectors(source, from = 'styles.css') {+function migrateWithActiveTables(source, from) {const root = postcss.parse(source, {from});const existingComments = new Set();root.walkComments(comment => {@@ -683,7 +703,7 @@ export function migrateAstryxThemeSelectors(source, from = 'styles.css') {}const parentContext =parent?.type === 'rule'- ? ruleContexts.get(parent) ?? {guaranteed: [], possible: []}+ ? (ruleContexts.get(parent) ?? {guaranteed: [], possible: []}): {guaranteed: [], possible: []};try {const migrated = migrateSelectorTextWithContext(diff --git a/packages/cli/assets/docs/tree/styling-advanced.doc.mjs b/packages/cli/assets/docs/tree/styling-advanced.doc.mjsindex 7f8c91c3aa..57eb724dab 100644--- a/packages/cli/assets/docs/tree/styling-advanced.doc.mjs+++ b/packages/cli/assets/docs/tree/styling-advanced.doc.mjs@@ -14,11 +14,11 @@ export const docs = {placement: {parent: 'namespace:styling', slot: 'guides', order: 20},category: 'guide',description:- 'Compound component styling, data-attribute selectors, deprecated bare prop/state classes, and common anti-patterns.',+ 'Compound component styling, data-attribute selectors, migrating removed theme compatibility selectors, and common anti-patterns.',keywords: ['compound','data attributes',- 'deprecated',+ 'removed classes','selector','astryx-button','data-variant',@@ -114,28 +114,35 @@ const overrides = stylex.create({},{id: 'deprecated-classes',- title: 'Deprecated: Bare Prop and State Classes',+ title: 'Migrating Removed Theme Compatibility Selectors',content: [{type: 'prose',- text: 'Astryx still emits the deprecated bare classes (`.primary`, `.sm`, `.level-2`, `.checked`) and will remove them in a later release. Use data attributes for new CSS; `astryx upgrade --from <old version> --apply` rewrites qualified selectors in `.css` files.',+ text: 'Astryx 0.7 emits canonical `astryx-*` target classes and reflected `data-*` attributes only. Run `astryx upgrade --from <your 0.6 version> --apply --path .` to rename removed target keys inside theme `components` maps and to migrate CSS selectors. The CSS migration renames removed target classes and replaces target-qualified bare prop/value/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` with their reflected `data-*` selectors.',},{type: 'code',lang: 'css',- code: `/* The upgrade preserves old consumer classes and adds the v0.6 prop match */-.my-app .astryx-button:is(.primary, [data-variant="primary"]) {- /* primary buttons or a consumer-supplied .primary class */-}+ code: `/* Before */+.astryx-progressbar.success > .astryx-progressbar-mark.fill {}+.astryx-selector-clear-icon { color: red; }-/* Numeric values stay literal in data attributes */-.my-app .astryx-heading:is(.level-2, [data-level="2"]) {- /* level 2 headings or a consumer-supplied .level-2 class */-}`,+/* After */+.astryx-progress-bar:is([data-variant="success"]) >+ .astryx-progress-bar-mark:is([data-placement="fill"]) {}+.astryx-input-clear-icon:where(.astryx-selector *) { color: red; }`,+ },+ {+ type: 'prose',+ text: 'Removed target mappings: `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`, `date-range-input-clear-icon`, `multi-selector-clear-icon`, and `selector-clear-icon` → `input-clear-icon`; `hovercard` → `hover-card`; `navicon` → `nav-icon`; `popover-surface` → `popover`; `progressbar`, `progressbar-fill`, `progressbar-mark`, and `progressbar-track` → their hyphenated `progress-bar*` forms; `radio` → `radio-indicator`; `radio-dot` → `radio-indicator-dot`; `statusdot` → `status-dot`; `textarea` → `text-area`.',+ },+ {+ type: 'prose',+ text: '`input-clear-icon` styles the clear icon of every input. In CSS the upgrade keeps each old clear-icon rule on its component with `:where(.astryx-<component> *)`. A theme key cannot carry that scope, so the upgrade renames the key and adds a `TODO(astryx upgrade)` that names the CSS selector to use instead.',},{type: 'prose',- text: 'The upgrade rewrites a selector only when an `.astryx-*` component class qualifies it, turning the old class into an `:is(...)` union of that class and the data attributes it stood for. The union keeps the selector\'s specificity and your own `className` matches, and keeps matching once the bare classes are gone; the `.astryx-*` classes themselves stay. It leaves unqualified classes (a bare `.primary`), unknown classes, and selectors in JavaScript or TypeScript alone: migrate those by hand, and only where they target Astryx.',+ text: 'The upgrade treats a `components` map as a theme when it belongs to a `defineTheme()` call imported from Astryx, an object typed as an Astryx theme, or a theme object with a static `name` whose component entries are style objects. It leaves computed theme keys, unqualified classes, unknown consumer classes, declarations, comments, and CSS inside JavaScript or TypeScript strings unchanged. It adds `TODO(astryx upgrade)` when a map has both an old and a canonical key, and when a bare class Astryx once emitted has no known meaning on the target it qualifies. Review each TODO by hand.',},],},@@ -150,7 +157,7 @@ const overrides = stylex.create({'Hardcoded colors (#fff, rgb(...)). Use var(--color-*) tokens or Tailwind semantic classes (text-primary, bg-surface).','Hardcoded spacing (16px, 1rem). Use var(--spacing-*) tokens or Tailwind spacing utilities (p-4, gap-3).','Wrapping a component in a <div> just to add margin. Use xstyle with stylex.create on the component.',- 'Using !important. If styles aren\'t applying, check specificity; xstyle is merged last.',+ "Using !important. If styles aren't applying, check specificity; xstyle is merged last.",],},],diff --git a/packages/cli/authoring/doctypes/base/type.ts b/packages/cli/authoring/doctypes/base/type.tsindex c57b53f190..d4de617954 100644--- a/packages/cli/authoring/doctypes/base/type.ts+++ b/packages/cli/authoring/doctypes/base/type.ts@@ -500,15 +500,6 @@ 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 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; deprecation alone does not authorize- * removing either this metadata or runtime support. */- deprecatedFor?: string;}/**diff --git a/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs b/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjsindex 5e51474b1f..0c74b83af1 100644--- a/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs+++ b/packages/cli/clients/cli/commands/build-theme.ascii-output.test.mjs@@ -86,7 +86,7 @@ describe('theme command human output is plain ASCII', () => {expect(result.code).toBe(0);expect(result.stdout).toContain('[ok] ocean.css');- expect(result.stderr).toContain('[warn] Deprecated component target');+ expect(result.stderr).toContain('[warn] Unknown component "progressbar"');expect(result.stderr).toContain('[error] Component "button"');expect(result.stdout).toContain('note: Font "Inter"');expect(result.stdout).toContain('[note] Theme "ocean" names fonts');diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjsindex ba8aca66ed..8ee87bb24d 100644--- a/packages/cli/clients/cli/commands/build-theme.mjs+++ b/packages/cli/clients/cli/commands/build-theme.mjs@@ -1062,22 +1062,11 @@ export function registerTheme(program) {emit(section('Theming targets',- `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}\n(key - component - props - states - className - deprecatedFor)`,+ `${targets.length} across ${componentCount} component${componentCount === 1 ? '' : 's'}\n(key - component - props - states - className)`,),records(targets, {- fields: [- 'key',- 'component',- 'props',- 'states',- 'className',- 'deprecatedFor',- ],+ fields: ['key', 'component', 'props', 'states', 'className'],layout: 'inline',- format: {- deprecatedFor: (/** @type {string|null} */ v) =>- v ? `deprecated; use ${v}` : '',- },}),text([diff --git a/packages/cli/clients/cli/commands/build-theme.registry.test.mjs b/packages/cli/clients/cli/commands/build-theme.registry.test.mjsindex d1c9045890..93a5970cbb 100644--- a/packages/cli/clients/cli/commands/build-theme.registry.test.mjs+++ b/packages/cli/clients/cli/commands/build-theme.registry.test.mjs@@ -83,16 +83,6 @@ function renderedClassLiterals() {while ((sm = surfaceRe.exec(text)) !== null) {classes.add(sm[1]);}- // Renamed targets emit their old name too, via themeProps'- // `legacyNames`. Those classes are just as rendered as the primary- // one, so a doc entry for the old name is still backed by real output.- const legacyRe = /legacyNames:\s*\[([^\]]*)\]/g;- let lm;- while ((lm = legacyRe.exec(text)) !== null) {- for (const nm of lm[1].matchAll(/'([^']+)'/g)) {- classes.add(nm[1]);- }- }}}};diff --git a/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs b/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjsindex b650224e6d..5c6d243ec4 100644--- a/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs+++ b/packages/cli/clients/cli/commands/theme-targets.behavior.test.mjs@@ -18,19 +18,21 @@ describe('astryx theme targets', () => {expect(status).toBe(0);// Inline layout: key component - props - states - className- expect(stdout).toMatch(/^switch\s+Switch - size - checked, disabled - astryx-switch$/m);- expect(stdout).toMatch(/^switch-thumb\s+Switch - size - checked - astryx-switch-thumb$/m);+ expect(stdout).toMatch(+ /^switch\s+Switch - size - checked, disabled - astryx-switch$/m,+ );+ expect(stdout).toMatch(+ /^switch-thumb\s+Switch - size - checked - astryx-switch-thumb$/m,+ );expect(stdout).toMatch(/4 across 1 component/);});- it('labels deprecated targets with their exact canonical replacement', async () => {+ it('omits removed aliases from the target list', 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\s{2,}Popover - astryx-popover-surface - deprecated; use popover$/m,- );+ expect(stdout).not.toContain('popover-surface');});it('lists the whole surface when unfiltered', async () => {diff --git a/packages/cli/clients/cli/lib/component-format.mjs b/packages/cli/clients/cli/lib/component-format.mjsindex daa44a4da5..e4d5baf3a5 100644--- a/packages/cli/clients/cli/lib/component-format.mjs+++ b/packages/cli/clients/cli/lib/component-format.mjs@@ -4,7 +4,11 @@* @file Component doc formatting — render ComponentDoc objects to text*/-import {discoverComponents, findComponentReadme, resolveImportPath} from '../../../foundation/discovery/component-discovery.mjs';+import {+ discoverComponents,+ findComponentReadme,+ resolveImportPath,+} from '../../../foundation/discovery/component-discovery.mjs';import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';@@ -26,15 +30,6 @@ 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()}`;@@ -117,7 +112,9 @@ function formatSubComponent(comp) {if (table) {out.push(table + '\n');} else {- out.push(`See \`${getCliInvocation()} component ${comp.name}\` for props and usage.\n`);+ out.push(+ `See \`${getCliInvocation()} component ${comp.name}\` for props and usage.\n`,+ );}return out;}@@ -136,8 +133,10 @@ function getTargetVariants(target, docs) {// If variant is a visualProp, try to resolve the actual variant values from propsif (target.visualProps.includes('variant')) {- const allProps = docs.props || (docs.components?.[0]?.props) || [];- const variantProp = allProps.find((/** @type {any} */ p) => p.name === 'variant');+ const allProps = docs.props || docs.components?.[0]?.props || [];+ const variantProp = allProps.find(+ (/** @type {any} */ p) => p.name === 'variant',+ );if (variantProp && variantProp.type.includes('|')) {return variantProp.type.replace(/['"]/g, '')@@ -172,8 +171,12 @@ function formatTargetsTable(docs, themeData) {/** @type {string[]} */const lines = [];- lines.push('| Component class | Preferred data attributes | Props | States |');- lines.push('|-----------------|---------------------------|-------|--------|');+ lines.push(+ '| Component class | Preferred data attributes | Props | States |',+ );+ lines.push(+ '|-----------------|---------------------------|-------|--------|',+ );for (const target of docs.theming.targets) {const coreVariants = getTargetVariants(target, docs);@@ -194,11 +197,11 @@ function formatTargetsTable(docs, themeData) {const statesStr = states.length > 0 ? states.join(', ') : '-';const dataAttrs = getTargetDataAttributes(target);const dataAttrsStr =- dataAttrs.length > 0 ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '-';+ dataAttrs.length > 0+ ? dataAttrs.map(attr => `\`${attr}\``).join(', ')+ : '-';- const className = target.deprecatedFor- ? `\`${target.className}\` _(deprecated; use \`${target.deprecatedFor}\`)_`- : `\`${target.className}\``;+ const className = `\`${target.className}\``;lines.push(`| ${className} | ${dataAttrsStr} | ${variantsStr} | ${statesStr} |`,);@@ -229,7 +232,9 @@ export function formatFull(docs, options = {}) {// agents to conflate the primary with a sub-component and hallucinate props// (origin/main #2860). Bare name per the un-prefix migration (P5a).const displayName = docs.name;- sections.push(`**Import:** \`import {${displayName}} from '${options.importHint}';\`\n`);+ sections.push(+ `**Import:** \`import {${displayName}} from '${options.importHint}';\`\n`,+ );}if (docs.usage?.anatomy?.length) {@@ -238,7 +243,9 @@ export function formatFull(docs, options = {}) {sections.push('|---------|----------|-------------|');for (const el of docs.usage.anatomy) {const req = el.required ? 'Yes' : 'No';- sections.push(`| ${mdCell(el.name)} | ${req} | ${mdCell(el.description)} |`);+ sections.push(+ `| ${mdCell(el.name)} | ${req} | ${mdCell(el.description)} |`,+ );}sections.push('');}@@ -246,7 +253,7 @@ export function formatFull(docs, options = {}) {if (docs.usage?.bestPractices?.length) {sections.push('## Best Practices\n');for (const bp of docs.usage.bestPractices) {- const badge = bp.guidance ? '**Do:**' : '**Don\'t:**';+ const badge = bp.guidance ? '**Do:**' : "**Don't:**";sections.push(`- ${badge} ${bp.description}`);}sections.push('');@@ -283,24 +290,30 @@ export function formatFull(docs, options = {}) {}if (docs.theming) {- const { themeData = null } = options;+ const {themeData = null} = options;sections.push('## Theming\n');-// Targets table with theme variant merging+ // Targets table with theme variant mergingif (docs.theming.targets?.length) {const targetsTable = formatTargetsTable(docs, themeData);sections.push(targetsTable + '\n');// Note about theme variants if any are presentif (themeData?.variants) {- const componentKeys = docs.theming.targets.map((/** @type {any} */ t) => targetKey(t));- const hasThemeVariants = componentKeys.some((/** @type {any} */ k) => themeData.variants[k]?.length > 0);+ const componentKeys = docs.theming.targets.map((/** @type {any} */ t) =>+ targetKey(t),+ );+ const hasThemeVariants = componentKeys.some(+ (/** @type {any} */ k) => themeData.variants[k]?.length > 0,+ );if (hasThemeVariants) {- sections.push(`_\\* = custom variant from ${themeData.name || 'active'} theme_\n`);+ sections.push(+ `_\\* = custom variant from ${themeData.name || 'active'} theme_\n`,+ );}}// Generate defineTheme example with canonical component selectors only.- const exampleTargets = canonicalTargets(docs.theming.targets);+ const exampleTargets = docs.theming.targets;if (exampleTargets.length > 0) {const exampleLines = ['Override in defineTheme:\n```ts\ncomponents: {'];const rootTarget = exampleTargets[0];@@ -309,7 +322,9 @@ export function formatFull(docs, options = {}) {exampleLines.push(` base: { /* CSS properties */ },`);if (rootTarget.visualProps?.length) {const firstVariant = rootTarget.visualProps[0];- exampleLines.push(` '${firstVariant}:value': { /* variant-specific */ },`);+ exampleLines.push(+ ` '${firstVariant}:value': { /* variant-specific */ },`,+ );}if (rootTarget.states?.length) {const firstState = rootTarget.states[0];@@ -339,10 +354,14 @@ export function formatFull(docs, options = {}) {// Component CSS vars — split into public (directly settable) and private (set via derived)if (docs.theming?.vars?.length) {- const publicVars = docs.theming.vars.filter((/** @type {any} */ v) => !v.private && !v.derived);+ const publicVars = docs.theming.vars.filter(+ (/** @type {any} */ v) => !v.private && !v.derived,+ );if (publicVars.length > 0) {- sections.push('**Themeable CSS variables** - additional properties that can be overridden in `defineTheme` component overrides.\n');+ sections.push(+ '**Themeable CSS variables** - additional properties that can be overridden in `defineTheme` component overrides.\n',+ );const varLines = [];varLines.push('| CSS Variable | Default | Description |');varLines.push('|-------------|---------|-------------|');@@ -356,25 +375,37 @@ export function formatFull(docs, options = {}) {// Show derived property examples — the recommended way to themeif (docs.theming?.derived?.length) {- const canonical = canonicalTargets(docs.theming.targets || []);- const varsKey = canonical.length ? targetKey(canonical[0]) : docs.theming.componentKey || '';+ const canonical = 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}: '...',`).join('\n');const expandExamples = docs.theming.derived.filter((/** @type {any} */ d) => d.expand === 'container')- .map((/** @type {any} */ d) => ` ${d.property}: '...', // expands to container layout tokens`)+ .map(+ (/** @type {any} */ d) =>+ ` ${d.property}: '...', // expands to container layout tokens`,+ )+ .join('\n');+ const allExamples = [derivedExamples, expandExamples]+ .filter(Boolean).join('\n');- const allExamples = [derivedExamples, expandExamples].filter(Boolean).join('\n');if (allExamples) {- sections.push('Some properties are set via standard CSS in component overrides:\n```ts\ncomponents: {\n ' + varsKey + ': {\n base: {\n' + allExamples + '\n },\n },\n}\n```\n');+ sections.push(+ 'Some properties are set via standard CSS in component overrides:\n```ts\ncomponents: {\n ' ++ varsKey ++ ': {\n base: {\n' ++ allExamples ++ '\n },\n },\n}\n```\n',+ );}}}}-return sections.join('\n');}@@ -401,21 +432,29 @@ export function formatCompact(docs, componentName, importHint) {sections.push(desc + '\n');if (docs.usage?.anatomy?.length) {- sections.push('Anatomy: ' + docs.usage.anatomy.map((/** @type {any} */ el) => {- const req = el.required ? '' : ' (optional)';- return `${el.name}${req}`;- }).join(', ') + '\n');+ sections.push(+ 'Anatomy: ' ++ docs.usage.anatomy+ .map((/** @type {any} */ el) => {+ const req = el.required ? '' : ' (optional)';+ return `${el.name}${req}`;+ })+ .join(', ') ++ '\n',+ );}if (importHint) {sections.push('## Import\n');- sections.push(`\`\`\`tsx\nimport { ${displayName} } from '${importHint}';\n\`\`\`\n`);+ sections.push(+ `\`\`\`tsx\nimport { ${displayName} } from '${importHint}';\n\`\`\`\n`,+ );}if (docs.usage?.bestPractices?.length) {sections.push('## Best Practices\n');for (const bp of docs.usage.bestPractices) {- const badge = bp.guidance ? '**Do:**' : '**Don\'t:**';+ const badge = bp.guidance ? '**Do:**' : "**Don't:**";sections.push(`- ${badge} ${bp.description}`);}sections.push('');@@ -453,7 +492,12 @@ export function formatCompact(docs, componentName, importHint) {propLines.push('| CSS Property | Sets |');propLines.push('|-------------|------|');for (const d of docs.theming.derived) {- const target = d.expand === 'container' ? 'container layout tokens' : (d.vars || []).map((/** @type {any} */ v) => `\`${mdCell(v)}\``).join(', ');+ const target =+ d.expand === 'container'+ ? 'container layout tokens'+ : (d.vars || [])+ .map((/** @type {any} */ v) => `\`${mdCell(v)}\``)+ .join(', ');propLines.push(`| \`${mdCell(d.property)}\` | ${target} |`);}sections.push(propLines.join('\n') + '\n');@@ -504,7 +548,9 @@ export function formatBrief(docs, componentName, importHint, options = {}) {if ('props' in docs) {props = docs.props;} else if ('components' in docs) {- const entry = docs.components.find((/** @type {any} */ c) => c.name === displayName);+ const entry = docs.components.find(+ (/** @type {any} */ c) => c.name === displayName,+ );if (entry) {props = entry.props;description = entry.description;@@ -549,9 +595,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {// Description (shortened)if (description) {const shortDesc =- description.length > 80- ? description.slice(0, 77) + '...'- : description;+ description.length > 80 ? description.slice(0, 77) + '...' : description;output.push(` ${shortDesc}`);}@@ -569,25 +613,33 @@ export function formatBrief(docs, componentName, importHint, options = {}) {// Derived properties (if any)if (docs.theming?.derived?.length) {const derivedNames = docs.theming.derived- .map((/** @type {any} */ d) => d.expand === 'container' ? `${d.property} -> container tokens` : `${d.property} -> ${(d.vars || []).join(', ')}`)+ .map((/** @type {any} */ d) =>+ d.expand === 'container'+ ? `${d.property} -> container tokens`+ : `${d.property} -> ${(d.vars || []).join(', ')}`,+ ).join('; ');output.push(` Derived: ${derivedNames}`);}-// Theme targets (component class, preferred data attrs, props, states) with theme variant merging+ // Theme targets (component class, preferred data attrs, props, states) with theme variant mergingif (docs.theming?.targets?.length) {- const { themeData = null } = 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(', ')}`);+ if (dataAttrs.length)+ parts.push(`preferred attrs: ${dataAttrs.join(', ')}`);+ if (t.visualProps?.length)+ parts.push(`variants: ${t.visualProps.join(', ')}`);if (t.states?.length) parts.push(`states: ${t.states.join(', ')}`);// Merge theme variantsconst componentKey = targetKey(t);const themeVars = themeData?.variants?.[componentKey];- if (themeVars?.length) parts.push(`theme: ${themeVars.map((/** @type {any} */ v) => v + '*').join(', ')}`);+ if (themeVars?.length)+ parts.push(+ `theme: ${themeVars.map((/** @type {any} */ v) => v + '*').join(', ')}`,+ );return parts.join(' ');});output.push(` Targets: ${targetParts.join(' | ')}`);@@ -602,7 +654,9 @@ export function formatBrief(docs, componentName, importHint, options = {}) {if (examples.length > 0) {const code = examples[0].code;const codeLine =- code.split('\n').find((/** @type {string} */ l) => l.trim().startsWith('<XDS')) ||+ code+ .split('\n')+ .find((/** @type {string} */ l) => l.trim().startsWith('<XDS')) ||code.split('\n')[0];output.push(` ${codeLine.trim()}`);}@@ -682,7 +736,7 @@ export async function formatBriefAll(if (readmePath && readmePath.endsWith('.doc.mjs')) {const docs = await loadDocs(readmePath, {zh, lang});const importPath = resolveImportPath(coreDir, comp);- output.push(formatBrief(docs, comp, importPath, { themeData }));+ output.push(formatBrief(docs, comp, importPath, {themeData}));} else {output.push(`${comp}\n (no docs)\n`);}diff --git a/packages/cli/clients/cli/lib/component-format.test.mjs b/packages/cli/clients/cli/lib/component-format.test.mjsindex 5bf87830b0..4025319c71 100644--- a/packages/cli/clients/cli/lib/component-format.test.mjs+++ b/packages/cli/clients/cli/lib/component-format.test.mjs@@ -9,7 +9,10 @@ describe('component accessibility guidance', () => {description: 'An action.',usage: {accessibility: [- {name: 'Loading', description: 'Expose aria-busy and block duplicate activation.'},+ {+ name: 'Loading',+ description: 'Expose aria-busy and block duplicate activation.',+ },],},props: [],@@ -18,7 +21,9 @@ describe('component accessibility guidance', () => {it('renders a dedicated section in full output', () => {const out = formatFull(docs);expect(out).toContain('## Accessibility');- expect(out).toContain('- **Loading:** Expose aria-busy and block duplicate activation.');+ expect(out).toContain(+ '- **Loading:** Expose aria-busy and block duplicate activation.',+ );});it('keeps accessibility guidance in compact agent output', () => {@@ -32,11 +37,16 @@ describe('component accessibility guidance', () => {});it('ignores legacy non-array accessibility content', () => {- const legacyDocs = {...docs, usage: {accessibility: 'Follow WCAG guidance.'}};+ const legacyDocs = {+ ...docs,+ usage: {accessibility: 'Follow WCAG guidance.'},+ };expect(() => formatFull(legacyDocs)).not.toThrow();expect(formatFull(legacyDocs)).not.toContain('## Accessibility');- expect(formatCompact(legacyDocs, 'Button')).not.toContain('## Accessibility');+ expect(formatCompact(legacyDocs, 'Button')).not.toContain(+ '## Accessibility',+ );});});@@ -56,7 +66,9 @@ describe('formatFull sub-component rendering', () => {expect(out).toContain('### XDSRadioListItem');expect(out).not.toContain('undefined');// Points the reader at the sub-component's own docs instead of a blank.- expect(out).toMatch(/(?:astryx|@astryxdesign\/cli) component XDSRadioListItem/);+ expect(out).toMatch(+ /(?:astryx|@astryxdesign\/cli) component XDSRadioListItem/,+ );});it('renders a full props table for a sub-component that has inline props', () => {@@ -100,7 +112,9 @@ describe('formatFull theming override keys', () => {const docs = {name: 'Button',description: 'A button.',- theming: {targets: [{className: 'astryx-button', visualProps: ['variant']}]},+ theming: {+ targets: [{className: 'astryx-button', visualProps: ['variant']}],+ },};const out = formatFull(docs);@@ -131,37 +145,6 @@ describe('formatFull theming override keys', () => {});});-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;@@ -236,7 +219,11 @@ describe('formatBrief signature stays terse', () => {type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',description: 'Gap.',},- {name: 'wrap', type: "'nowrap' | 'wrap' | 'wrap-reverse'", description: 'Wrap.'},+ {+ name: 'wrap',+ type: "'nowrap' | 'wrap' | 'wrap-reverse'",+ description: 'Wrap.',+ },{name: 'hAlign',type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",@@ -248,7 +235,9 @@ describe('formatBrief signature stays terse', () => {// Short enums still earn their place in the signature.expect(signature).toContain('wrap: nowrap|wrap|wrap-reverse');- expect(signature).toContain('hAlign: start|center|end|between|around|evenly');+ expect(signature).toContain(+ 'hAlign: start|center|end|between|around|evenly',+ );// The long scale does not.expect(signature).not.toContain('0|0.5|1|1.5|2|3|4|5|6|8|10');// But the prop is still named, so it is not lost.diff --git a/packages/cli/clients/cli/lib/doc-text-ascii.test.mjs b/packages/cli/clients/cli/lib/doc-text-ascii.test.mjsindex 21a01dce2e..7e2f4cf552 100644--- a/packages/cli/clients/cli/lib/doc-text-ascii.test.mjs+++ b/packages/cli/clients/cli/lib/doc-text-ascii.test.mjs@@ -42,7 +42,7 @@ const componentDoc = {{property: 'radius', vars: ['--widget-radius']},],targets: [- {className: 'astryx-widget', deprecatedFor: 'astryx-widget-v2'},+ {className: 'astryx-widget'},{className: 'astryx-widget-v2', visualProps: ['variant']},],},@@ -63,7 +63,10 @@ describe('component text output is ASCII', () => {it.each([['formatFull', () => formatFull(componentDoc)],['formatCompact', () => formatCompact(componentDoc, 'Widget')],- ['formatBrief', () => formatBrief(componentDoc, 'Widget', '@astryxdesign/core/Widget')],+ [+ 'formatBrief',+ () => formatBrief(componentDoc, 'Widget', '@astryxdesign/core/Widget'),+ ],['formatProps', () => formatProps(componentDoc, 'Widget')],])('%s', (_name, render) => {expect(nonAscii(render())).toEqual([]);diff --git a/packages/cli/foundation/discovery/theming-targets.mjs b/packages/cli/foundation/discovery/theming-targets.mjsindex adbea41ff1..fb7f7cece9 100644--- a/packages/cli/foundation/discovery/theming-targets.mjs+++ b/packages/cli/foundation/discovery/theming-targets.mjs@@ -28,7 +28,6 @@ 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*//**@@ -55,13 +54,9 @@ function targetKey(className) {* not take out theme validation or the listing.** @param {string} coreSrc - absolute path to `<core>/src`- * @param {{includeDeprecated?: boolean}} [options] - preserve the CLI's full listing by default; ownership checks can request active targets only* @returns {Promise<ThemingTarget[]>}*/-export async function collectThemingTargets(- coreSrc,- {includeDeprecated = true} = {},-) {+export async function collectThemingTargets(coreSrc) {if (!coreSrc || !fs.existsSync(coreSrc)) return [];/** @type {Array<ThemingTarget & {parent: string|null}>} */@@ -92,7 +87,6 @@ export async function collectThemingTargets(: path.basename(path.dirname(full));for (const target of doc?.theming?.targets || []) {- if (!includeDeprecated && target?.deprecatedFor != null) continue;const className = target?.className;if (typeof className !== 'string') continue;const key = targetKey(className);@@ -105,9 +99,6 @@ 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}- : {}),});}}@@ -158,7 +149,6 @@ function canonicalizeParentTargets(targets) {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);}@@ -252,33 +242,6 @@ export function targetsByKey(targets) {return byKey;}-/**- * Build the component-validation registry from the same target rows used by- * `theme targets`. Deprecated keys stay accepted during their compatibility- * window, while the replacement map lets theme build issue exact guidance.- *- * @param {ThemingTarget[]} targets- * @returns {{propsByKey: Record<string, string[]>, deprecatedByKey: Record<string, string>}}- */-export function targetValidationRegistry(targets) {- const propsByKey = targetsByKey(targets);- /** @type {Record<string, string>} */- const deprecatedByKey = {};-- for (const target of targets) {- if (target.deprecatedFor == null) continue;- const existing = deprecatedByKey[target.key];- if (existing != null && existing !== target.deprecatedFor) {- throw new Error(- `Deprecated theme target "${target.key}" has conflicting replacements: "${existing}" and "${target.deprecatedFor}".`,- );- }- deprecatedByKey[target.key] = target.deprecatedFor;- }-- return {propsByKey, deprecatedByKey};-}-/*** @param {unknown} value* @returns {string[]}diff --git a/packages/cli/foundation/discovery/theming-targets.test.mjs b/packages/cli/foundation/discovery/theming-targets.test.mjsindex 34c24500ca..fadc22fbc4 100644--- a/packages/cli/foundation/discovery/theming-targets.test.mjs+++ b/packages/cli/foundation/discovery/theming-targets.test.mjs@@ -25,6 +25,7 @@ import {describe, it, expect} from 'vitest';import * as fs from 'node:fs';import * as path from 'node:path';import {findCoreDir} from '../fs/paths.mjs';+import {DEPRECATED_THEME_TARGETS} from '../../assets/codemods/transforms/next/migrate-deprecated-theme-surface.mjs';import {discoverComponents,findComponentReadme,@@ -34,69 +35,13 @@ 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);-/** @type {Promise<import('./theming-targets.mjs').ThemingTarget[]>} */-const activeEnumerated = collectThemingTargets(coreSrc, {- includeDeprecated: false,-});describe('collectThemingTargets', () => {it('enumerates the whole surface, not a handful', async () => {@@ -112,126 +57,15 @@ describe('collectThemingTargets', () => {}});- it('can limit ownership checks to active targets', async () => {- const all = await enumerated;- const active = await activeEnumerated;- expect(- all.some(t => t.component === 'CodeBlock' && t.key === 'codeblock'),- ).toBe(true);- expect(- active.some(t => t.component === 'CodeBlock' && t.key === 'codeblock'),- ).toBe(false);- expect(- active.some(t => t.component === 'CodeBlock' && t.key === 'code-block'),- ).toBe(true);- });-- it('keeps the deprecated Popover alias enumerable but out of active ownership', async () => {- const allPopoverKeys = (await enumerated)- .filter(target => target.component === 'Popover')- .map(target => target.key);- const activePopoverKeys = (await activeEnumerated)- .filter(target => target.component === 'Popover')- .map(target => target.key);- const doc = await loadComponentDoc(- path.join(coreSrc, 'Popover', 'Popover.doc.mjs'),- );-- expect(allPopoverKeys).toEqual(['popover', 'popover-surface']);- expect(activePopoverKeys).toEqual(['popover']);- expect(doc.theming.targets).toContainEqual({- className: 'astryx-popover-surface',- deprecatedFor: 'popover',- });- });-- 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'),+ it('does not enumerate any removed target alias', async () => {+ const keys = new Set((await enumerated).map(target => target.key));+ for (const removed of Object.keys(DEPRECATED_THEME_TARGETS)) {+ expect(keys, `${removed} must not remain discoverable`).not.toContain(+ removed,);- 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({@@ -318,13 +152,13 @@ describe('collectThemingTargets', () => {it('collapses to the override keys, merging the components that share one', async () => {const byKey = targetsByKey(await enumerated);expect(byKey['switch']).toEqual(['size', 'checked', 'disabled']);- // `radio` is documented by two unrelated owners. Parent/child+ // `radio-indicator` is documented by two unrelated owners. Parent/child// canonicalization must not collapse a shared target across families.- const radio = (await enumerated).filter(t => t.key === 'radio');+ const radio = (await enumerated).filter(t => t.key === 'radio-indicator');expect(radio.map(t => t.component)).toEqual(['Indicator', 'RadioList']);for (const t of radio) {for (const name of [...t.props, ...t.states]) {- expect(byKey['radio']).toContain(name);+ expect(byKey['radio-indicator']).toContain(name);}}});diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex 34e99d2a1d..2a2bee8fac 100644--- a/packages/cli/foundation/response/response-types.doc.mjs+++ b/packages/cli/foundation/response/response-types.doc.mjs@@ -50,11 +50,13 @@ export const doc = {},{value: 'component.detail.props',- description: "Just one component's props table (ComponentPropDoc[]). The envelope's package names the npm package that owns the component.",+ description:+ "Just one component's props table (ComponentPropDoc[]). The envelope's package names the npm package that owns the component.",},{value: 'component.detail.source',- description: "One component's source file, as {component, source}. The envelope's package names the npm package that owns the component.",+ description:+ "One component's source file, as {component, source}. The envelope's package names the npm package that owns the component.",},{value: 'component.detail.showcase',@@ -86,7 +88,7 @@ export const doc = {{value: 'docs.detail.section',description:- 'One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it). The envelope\'s package names the npm package that wrote the section.',+ "One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it). The envelope's package names the npm package that wrote the section.",},{value: 'docs.node',@@ -161,7 +163,7 @@ export const doc = {{value: 'swizzle.copy',description:- 'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling. The envelope\'s package names the same owning package.',+ "An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling. The envelope's package names the same owning package.",},// gap reports@@ -194,7 +196,7 @@ export const doc = {{value: 'template.copy',description:- 'A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing). The envelope\'s package names the npm package that owns the template.',+ "A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing). The envelope's package names the npm package that owns the template.",},{@@ -207,7 +209,7 @@ export const doc = {{value: 'hook.list',description:- 'The hook catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. The envelope\'s package is @astryxdesign/core, the only package that ships hooks.',+ "The hook catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry. The envelope's package is @astryxdesign/core, the only package that ships hooks.",},{value: 'hook.detail',@@ -264,7 +266,7 @@ export const doc = {{value: 'theme.targets',description:- 'The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key.',+ 'The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states}, where props and states are its legal override keys.',},{value: 'theme.palette.generate',diff --git a/packages/cli/foundation/response/response-types.doc.test.mjs b/packages/cli/foundation/response/response-types.doc.test.mjsindex e9abd92f97..33e98b0df0 100644--- a/packages/cli/foundation/response/response-types.doc.test.mjs+++ b/packages/cli/foundation/response/response-types.doc.test.mjs@@ -14,7 +14,8 @@ import {doc} from './response-types.doc.mjs';import {runCli} from '../../test-utils/run-cli.mjs';/** @param {string} type */-const describedAs = (type) => doc.members.find((m) => m.value === type)?.description ?? '';+const describedAs = type =>+ doc.members.find(m => m.value === type)?.description ?? '';/** @param {string} text @param {string} field */const names = (text, field) => new RegExp(`(^|\\W)${field}(\\W|$)`).test(text);@@ -27,7 +28,7 @@ const names = (text, field) => new RegExp(`(^|\\W)${field}(\\W|$)`).test(text);function fieldsOf(value, depth = 2) {const out = new Set();const visit = (/** @type {unknown} */ v, /** @type {number} */ d) => {- if (Array.isArray(v)) return v.forEach((item) => visit(item, d));+ if (Array.isArray(v)) return v.forEach(item => visit(item, d));if (!v || typeof v !== 'object' || d < 0) return;for (const [key, child] of Object.entries(v)) {out.add(key);@@ -40,7 +41,10 @@ function fieldsOf(value, depth = 2) {/** @param {string[]} args @param {string} [cwd] */async function data(args, cwd) {- const {status, stdout} = await runCli(['--json', ...args], cwd ? {cwd} : undefined);+ const {status, stdout} = await runCli(+ ['--json', ...args],+ cwd ? {cwd} : undefined,+ );expect(status, stdout).toBe(0);return JSON.parse(stdout);}@@ -48,7 +52,7 @@ async function data(args, cwd) {/** @param {string} type @param {Iterable<string>} fields */function expectNamed(type, fields) {const text = describedAs(type);- const missing = [...fields].filter((f) => !names(text, f));+ const missing = [...fields].filter(f => !names(text, f));expect(missing, `${type} omits`).toEqual([]);}@@ -99,8 +103,13 @@ describe('response-types EnumDoc names every field', () => {it('search, across component, hook, template, and doc results', async () => {const mixed = await data(['search', 'dashboard', '--limit', '50']);const docsOnly = await data(['search', 'tokens', '--type', 'doc']);- expect(new Set(mixed.data.results.map((r) => r.domain))).toContain('template');- expectNamed('search', new Set([...fieldsOf(mixed.data), ...fieldsOf(docsOnly.data)]));+ expect(new Set(mixed.data.results.map(r => r.domain))).toContain(+ 'template',+ );+ expectNamed(+ 'search',+ new Set([...fieldsOf(mixed.data), ...fieldsOf(docsOnly.data)]),+ );});it('build.kit, including the hint a thin kit carries', async () => {@@ -112,25 +121,38 @@ describe('response-types EnumDoc names every field', () => {expectNamed('build.kit', fields);});- it('theme.targets, including deprecatedFor', async () => {+ it('theme.targets', async () => {const res = await data(['theme', 'targets']);- const fields = fieldsOf(res.data);- expect(fields).toContain('deprecatedFor');- expectNamed('theme.targets', fields);+ expectNamed('theme.targets', fieldsOf(res.data));});it('gap-report.file, including each delivery', async () => {- const res = await data(['gap-report', 'Button', '--category', 'docs_gap', '--reason', 'probe']);+ const res = await data([+ 'gap-report',+ 'Button',+ '--category',+ 'docs_gap',+ '--reason',+ 'probe',+ ]);expect(res.type).toBe('gap-report.file');expect(res.data.deliveries.length).toBeGreaterThan(0);expectNamed('gap-report.file', fieldsOf(res.data));});it('theme.build, including notices', async () => {- const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-response-types-'));- fs.writeFileSync(path.join(cwd, 'package.json'), '{"name":"app","version":"1.0.0"}');+ const cwd = fs.mkdtempSync(+ path.join(os.tmpdir(), 'astryx-response-types-'),+ );+ fs.writeFileSync(+ path.join(cwd, 'package.json'),+ '{"name":"app","version":"1.0.0"}',+ );await data(['theme', 'template', 'starter.ts'], cwd);- const res = await data(['theme', 'build', 'starter.ts', '--out', 'starter.css'], cwd);+ const res = await data(+ ['theme', 'build', 'starter.ts', '--out', 'starter.css'],+ cwd,+ );expect(res.type).toBe('theme.build');expectNamed('theme.build', fieldsOf(res.data));});diff --git a/packages/core/src/Banner/Banner.test.tsx b/packages/core/src/Banner/Banner.test.tsxindex 98f4de9e2c..ec2a540443 100644--- a/packages/core/src/Banner/Banner.test.tsx+++ b/packages/core/src/Banner/Banner.test.tsx@@ -531,9 +531,9 @@ describe('Banner', () => {);const frame = container.firstElementChild;expect(frame).toHaveClass('astryx-banner-frame');- // 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);+ // Visual axes are reflected only as canonical data attributes.+ expect(frame).not.toHaveClass(containerType);+ expect(frame).not.toHaveClass(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/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjsindex ae95364d87..67108fc97b 100644--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs@@ -7,13 +7,20 @@ export const docs = {displayName: 'Checkbox Input',group: 'Checkbox',category: 'Form Controls',- keywords: ["checkbox","check","toggle","tick","indeterminate","boolean","tristate"],+ keywords: [+ 'checkbox',+ 'check',+ 'toggle',+ 'tick',+ 'indeterminate',+ 'boolean',+ 'tristate',+ ],props: [{name: 'ref',type: 'React.Ref<HTMLInputElement>',- description:- 'Ref forwarded to the underlying <input> element.',+ description: 'Ref forwarded to the underlying <input> element.',},{name: 'label',@@ -25,7 +32,8 @@ export const docs = {{name: 'isLabelHidden',type: 'boolean',- description: 'Whether to visually hide the label (still accessible to screen readers).',+ description:+ 'Whether to visually hide the label (still accessible to screen readers).',default: 'false',},{@@ -54,7 +62,8 @@ export const docs = {{name: 'isLoading',type: 'boolean',- description: 'Whether the checkbox is in a loading state. Shows spinner and prevents interaction.',+ description:+ 'Whether the checkbox is in a loading state. Shows spinner and prevents interaction.',default: 'false',},{@@ -85,19 +94,22 @@ export const docs = {{name: 'isOptional',type: 'boolean',- description: 'Whether the field is optional. Mutually exclusive with isRequired.',+ description:+ 'Whether the field is optional. Mutually exclusive with isRequired.',default: 'false',},{name: 'isRequired',type: 'boolean',- description: 'Whether the checkbox is required. Mutually exclusive with isOptional.',+ description:+ 'Whether the checkbox is required. Mutually exclusive with isOptional.',default: 'false',},{name: 'size',type: "'sm' | 'md'",- description: 'The size of the checkbox. sm for compact layouts, md for default.',+ description:+ 'The size of the checkbox. sm for compact layouts, md for default.',default: "'md'",},{@@ -132,8 +144,11 @@ export const docs = {theming: {targets: [{className: 'astryx-checkbox-input', visualProps: ['size']},- {className: 'astryx-checkbox-indicator', visualProps: ['size'], states: ['checked', 'disabled']},- {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled'], deprecatedFor: 'checkbox-indicator'},+ {+ className: 'astryx-checkbox-indicator',+ visualProps: ['size'],+ states: ['checked', 'disabled'],+ },{className: 'astryx-checkbox-label'},],},@@ -149,20 +164,64 @@ export const docs = {'The box edge (unchecked) and fill (checked) must have at least 3:1 contrast with the surface behind them. For Hover and Pointer down, measure the final colors after the tint and the pressed overlay are applied.',},],- description: 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',+ description:+ 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',bestPractices: [- { guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },- { guidance: true, description: 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.' },- { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },- { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },- { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },- { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.',+ },+ {+ guidance: true,+ description:+ 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.',+ },+ {+ guidance: true,+ description:+ 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.',+ },+ {+ guidance: false,+ description:+ 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.',+ },+ {+ guidance: false,+ description:+ 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- { name: 'Checkbox', required: true, description: 'The check box itself: unchecked, checked, or indeterminate.' },- { name: 'Label', required: true, description: 'Text describing what the checkbox controls. Always present for accessibility.' },- { name: 'Description', required: false, description: 'Helper text below the label with additional context.' },- { name: 'Status message', required: false, description: 'An error, warning, or success message below the checkbox.' },+ {+ name: 'Checkbox',+ required: true,+ description:+ 'The check box itself: unchecked, checked, or indeterminate.',+ },+ {+ name: 'Label',+ required: true,+ description:+ 'Text describing what the checkbox controls. Always present for accessibility.',+ },+ {+ name: 'Description',+ required: false,+ description: 'Helper text below the label with additional context.',+ },+ {+ name: 'Status message',+ required: false,+ description:+ 'An error, warning, or success message below the checkbox.',+ },],},};@@ -172,56 +231,163 @@ export const docsZh = {name: 'CheckboxInput',displayName: 'Checkbox Input',usage: {- description: 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',+ description:+ 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',bestPractices: [- { guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },- { guidance: true, description: 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.' },- { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },- { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },- { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },- { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.',+ },+ {+ guidance: true,+ description:+ 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.',+ },+ {+ guidance: true,+ description:+ 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.',+ },+ {+ guidance: false,+ description:+ 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.',+ },+ {+ guidance: false,+ description:+ 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},props: [- {name: 'ref', type: 'React.Ref<HTMLInputElement>', description: '转发至底层 <input> 元素的 ref。'},- {name: 'label', type: 'string', description: '复选框的标签文本(始终为无障碍性而渲染)。', required: true},- {name: 'isLabelHidden', type: 'boolean', description: '是否视觉隐藏标签(屏幕阅读器仍可访问)。', default: 'false'},- {name: 'description', type: 'string', description: '显示在标签下方的描述文本。'},- {name: 'value', type: "boolean | 'indeterminate'", description: '复选框是否为选中、未选中或不确定状态。', required: true},- {name: 'onChange', type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void', description: '复选框状态变更时触发的回调。'},+ {+ name: 'ref',+ type: 'React.Ref<HTMLInputElement>',+ description: '转发至底层 <input> 元素的 ref。',+ },+ {+ name: 'label',+ type: 'string',+ description: '复选框的标签文本(始终为无障碍性而渲染)。',+ required: true,+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: '是否视觉隐藏标签(屏幕阅读器仍可访问)。',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: '显示在标签下方的描述文本。',+ },+ {+ name: 'value',+ type: "boolean | 'indeterminate'",+ description: '复选框是否为选中、未选中或不确定状态。',+ required: true,+ },+ {+ name: 'onChange',+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void',+ description: '复选框状态变更时触发的回调。',+ },{name: 'changeAction',- type:- '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',- description: '异步变更操作。在 onChange 之后触发(未被阻止时)。等待期间显示加载旋转器。',- },- {name: 'isLoading', type: 'boolean', description: '复选框是否处于加载状态。显示旋转器并阻止交互。', default: 'false'},- {name: 'isDisabled', type: 'boolean', description: '复选框是否禁用。', default: 'false'},- {name: 'htmlName', type: 'string', description: '底层复选框输入的 HTML name 属性,用于表单提交(勾选时提交 "on")。'},- {name: 'disabledMessage', type: 'string', description: 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip: disabled controls swallow the hover events an external Tooltip needs.'},- {name: 'isReadOnly', type: 'boolean', description: '复选框是否为只读。以完整不透明度显示当前状态但阻止交互。与 isDisabled 不同,只读复选框不会变暗。', default: 'false'},- {name: 'isOptional', type: 'boolean', description: '字段是否可选。与 isRequired 互斥。', default: 'false'},- {name: 'isRequired', type: 'boolean', description: '复选框是否必填。与 isOptional 互斥。', default: 'false'},- {name: 'size', type: "'sm' | 'md'", description: '复选框尺寸。sm 用于紧凑布局,md 为默认。', default: "'md'"},- {name: 'onFocus', type: '(e: FocusEvent<HTMLInputElement>) => void', description: '复选框获得焦点时触发的回调。'},- {name: 'onBlur', type: '(e: FocusEvent<HTMLInputElement>) => void', description: '复选框失去焦点时触发的回调。'},- {name: 'labelIcon', type: 'ReactNode | IconType', description: '标签文本前显示的语义图标名称或自定义内容。'},+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',+ description:+ '异步变更操作。在 onChange 之后触发(未被阻止时)。等待期间显示加载旋转器。',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: '复选框是否处于加载状态。显示旋转器并阻止交互。',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: '复选框是否禁用。',+ default: 'false',+ },+ {+ name: 'htmlName',+ type: 'string',+ description:+ '底层复选框输入的 HTML name 属性,用于表单提交(勾选时提交 "on")。',+ },+ {+ name: 'disabledMessage',+ type: 'string',+ description:+ 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip: disabled controls swallow the hover events an external Tooltip needs.',+ },+ {+ name: 'isReadOnly',+ type: 'boolean',+ description:+ '复选框是否为只读。以完整不透明度显示当前状态但阻止交互。与 isDisabled 不同,只读复选框不会变暗。',+ default: 'false',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: '字段是否可选。与 isRequired 互斥。',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: '复选框是否必填。与 isOptional 互斥。',+ default: 'false',+ },+ {+ name: 'size',+ type: "'sm' | 'md'",+ description: '复选框尺寸。sm 用于紧凑布局,md 为默认。',+ default: "'md'",+ },+ {+ name: 'onFocus',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: '复选框获得焦点时触发的回调。',+ },+ {+ name: 'onBlur',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: '复选框失去焦点时触发的回调。',+ },+ {+ name: 'labelIcon',+ type: 'ReactNode | IconType',+ description: '标签文本前显示的语义图标名称或自定义内容。',+ },{name: 'status',type: "{ type: 'error' | 'warning' | 'success', message: string }",- description: '状态指示器。在复选框下方显示彩色消息框,错误时设置 aria-invalid。',+ description:+ '状态指示器。在复选框下方显示彩色消息框,错误时设置 aria-invalid。',},],theming: {targets: [{className: 'astryx-checkbox-input',- visualProps: [- 'size',- ],+ visualProps: ['size'],+ },+ {+ className: 'astryx-checkbox-indicator',+ visualProps: ['size'],+ states: ['checked', 'disabled'],},- {className: 'astryx-checkbox-indicator', visualProps: ['size'], states: ['checked', 'disabled']},- {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled'], deprecatedFor: 'checkbox-indicator'},{className: 'astryx-checkbox-label'},],},@@ -231,14 +397,39 @@ export const docsZh = {export const docsDense = {description: 'single on/off toggle for settings, terms, and opt-in choices',usage: {- description: 'CheckboxInput toggles a single on/off value. Use for settings, terms acceptance, opt-in choices. Use CheckboxList for groups.',+ description:+ 'CheckboxInput toggles a single on/off value. Use for settings, terms acceptance, opt-in choices. Use CheckboxList for groups.',bestPractices: [- { guidance: true, description: 'Always provide a visible label so user knows what they\'re toggling. Use isLabelHidden only when surrounding context makes it obvious.' },- { guidance: true, description: 'Add a description for choices that need extra context, e.g. what "Share usage data" actually shares.' },- { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },- { guidance: false, description: 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.' },- { guidance: false, description: 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.' },- { guidance: false, description: 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ "Always provide a visible label so user knows what they're toggling. Use isLabelHidden only when surrounding context makes it obvious.",+ },+ {+ guidance: true,+ description:+ 'Add a description for choices that need extra context, e.g. what "Share usage data" actually shares.',+ },+ {+ guidance: true,+ description:+ 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.',+ },+ {+ guidance: false,+ description:+ 'Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.',+ },+ {+ guidance: false,+ description:+ 'Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],},propDescriptions: {@@ -248,7 +439,8 @@ export const docsDense = {description: 'text below label',value: 'checked, unchecked, or indeterminate',onChange: 'callback on state change',- changeAction: 'async action; fires after onChange, shows spinner while pending',+ changeAction:+ 'async action; fires after onChange, shows spinner while pending',isLoading: 'shows spinner + prevents interaction',isDisabled: 'disable checkbox',htmlName: 'HTML name attr for the checkbox; submits "on" when checked.',diff --git a/packages/core/src/CodeBlock/CodeBlock.doc.mjs b/packages/core/src/CodeBlock/CodeBlock.doc.mjsindex 5f61c0db74..6db8b5abdb 100644--- a/packages/core/src/CodeBlock/CodeBlock.doc.mjs+++ b/packages/core/src/CodeBlock/CodeBlock.doc.mjs@@ -6,10 +6,19 @@ export const docs = {displayName: 'Code Block',category: 'Content',keywords: [- 'code', 'syntax', 'highlight', 'snippet', 'prism', 'shiki',- 'pre', 'monospace', 'codeblock', 'inline',+ 'code',+ 'syntax',+ 'highlight',+ 'snippet',+ 'prism',+ 'shiki',+ 'pre',+ 'monospace',+ 'codeblock',+ 'inline',],- description: 'Fenced code block with syntax highlighting. Use for multi-line code snippets.',+ description:+ 'Fenced code block with syntax highlighting. Use for multi-line code snippets.',props: [{name: 'code',@@ -20,7 +29,8 @@ export const docs = {{name: 'language',type: 'string',- description: 'Language for syntax highlighting. Use "plaintext" to disable.',+ description:+ 'Language for syntax highlighting. Use "plaintext" to disable.',default: "'plaintext'",},{@@ -31,7 +41,8 @@ export const docs = {{name: 'hasLanguageLabel',type: 'boolean',- description: 'Show the language name in the header bar. Hidden when language is "plaintext".',+ description:+ 'Show the language name in the header bar. Hidden when language is "plaintext".',default: 'true',},{@@ -76,13 +87,15 @@ export const docs = {{name: 'width',type: 'string',- description: "Width of the code block. Any CSS width value. 'fit-content' (default) shrinks to longest line. '100%' fills parent width.",+ description:+ "Width of the code block. Any CSS width value. 'fit-content' (default) shrinks to longest line. '100%' fills parent width.",default: "'fit-content'",},{name: 'container',type: "'card' | 'section'",- description: "Container presentation style. 'card' (default): border and radius with the muted syntax background for a standalone card look. 'section': no border or radius and a transparent background so the block blends into the card or panel it's embedded in.",+ description:+ "Container presentation style. 'card' (default): border and radius with the muted syntax background for a standalone card look. 'section': no border or radius and a transparent background so the block blends into the card or panel it's embedded in.",default: "'card'",},{@@ -93,7 +106,8 @@ export const docs = {{name: 'syntaxTheme',type: 'SyntaxThemeDefinition',- description: 'Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors.',+ description:+ 'Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors.',},{name: 'highlightMode',@@ -104,13 +118,15 @@ export const docs = {{name: 'isCollapsible',type: 'boolean',- description: 'Allow collapsing the code body into just the header bar. Starts expanded; a visible header becomes clickable when the code exceeds collapsibleThreshold lines. Headerless blocks never collapse, and removing the header expands a previously collapsed block.',+ description:+ 'Allow collapsing the code body into just the header bar. Starts expanded; a visible header becomes clickable when the code exceeds collapsibleThreshold lines. Headerless blocks never collapse, and removing the header expands a previously collapsed block.',default: 'false',},{name: 'collapsibleThreshold',type: 'number',- description: 'Minimum number of lines before the collapse toggle appears. Below this threshold the code block renders normally even when isCollapsible is true.',+ description:+ 'Minimum number of lines before the collapse toggle appears. Below this threshold the code block renders normally even when isCollapsible is true.',default: '10',},{@@ -121,12 +137,14 @@ export const docs = {{name: 'xstyle',type: 'StyleXStyles',- description: 'StyleX styles for layout customization. Must be a stylex.create() value.',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',},{name: 'className',type: 'string',- description: 'CSS class name for the root element. Prefer xstyle for styling.',+ description:+ 'CSS class name for the root element. Prefer xstyle for styling.',},{name: 'style',@@ -139,49 +157,102 @@ export const docs = {description: 'Test selector for automated testing frameworks.',},],- components: [- {name: 'Code'},- ],+ components: [{name: 'Code'}],playground: {defaults: {- code: "import {Button} from '@astryxdesign/core/Button';\n\nexport function App() {\n return <Button label=\"Hello\" variant=\"primary\" />;\n}",+ code: 'import {Button} from \'@astryxdesign/core/Button\';\n\nexport function App() {\n return <Button label="Hello" variant="primary" />;\n}',language: 'tsx',hasCopyButton: true,},},theming: {targets: [- {className: 'astryx-code-block', visualProps: ['size', 'language', 'container']},- {className: 'astryx-code-block-header', visualProps: ['size', 'language', 'container']},+ {+ className: 'astryx-code-block',+ visualProps: ['size', 'language', 'container'],+ },+ {+ className: 'astryx-code-block-header',+ visualProps: ['size', 'language', 'container'],+ },{className: 'astryx-code-block-title', visualProps: ['size', 'language']},{className: 'astryx-code-block-copy-button'},- // 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'},- {className: 'astryx-codeblock-copy-button', deprecatedFor: 'code-block-copy-button'},],vars: [- {name: '--_codeblock-gutter-width', description: 'Width of the line-number gutter, computed from the digit count of the last line so the code column starts at a stable offset.', default: '2ch', private: true},+ {+ name: '--_codeblock-gutter-width',+ description:+ 'Width of the line-number gutter, computed from the digit count of the last line so the code column starts at a stable offset.',+ default: '2ch',+ private: true,+ },],},usage: {- description: 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use CodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use Code for inline references to function names, variables, or CLI flags within body text.',+ description:+ 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use CodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use Code for inline references to function names, variables, or CLI flags within body text.',bestPractices: [- {guidance: true, description: 'Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown.'},- {guidance: true, description: 'Add a title when the code represents a file. It gives readers context and appears in the header bar alongside the copy button.'},- {guidance: true, description: 'Use Code for short inline references like function names or CLI flags, and CodeBlock for standalone multi-line snippets.'},- {guidance: false, description: 'Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation.'},- {guidance: false, description: 'Nest a code block inside a scrollable container. Use the maxHeight prop instead, which handles overflow natively.'},+ {+ guidance: true,+ description:+ 'Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown.',+ },+ {+ guidance: true,+ description:+ 'Add a title when the code represents a file. It gives readers context and appears in the header bar alongside the copy button.',+ },+ {+ guidance: true,+ description:+ 'Use Code for short inline references like function names or CLI flags, and CodeBlock for standalone multi-line snippets.',+ },+ {+ guidance: false,+ description:+ 'Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation.',+ },+ {+ guidance: false,+ description:+ 'Nest a code block inside a scrollable container. Use the maxHeight prop instead, which handles overflow natively.',+ },],anatomy: [- {name: 'Header Bar', required: false, description: 'Shows the title, visible language label, and copy button when a header is present. A title or visible language label creates the header; the copy button alone floats at the top-end of a headerless block.'},- {name: 'Header Title', required: false, description: 'Groups the optional title, visible language label, and collapsible chevron inside the header bar.'},- {name: 'Line Numbers', required: false, description: 'Numbered gutter along the left edge. Enable with hasLineNumbers.'},- {name: 'Code Body', required: true, description: 'The syntax-highlighted code content.'},- {name: 'Highlighted Lines', required: false, description: 'Background accent on specific lines to draw attention.'},- {name: 'Copy Button', required: false, description: 'Copies the code string to the clipboard. Shown by default.'},+ {+ name: 'Header Bar',+ required: false,+ description:+ 'Shows the title, visible language label, and copy button when a header is present. A title or visible language label creates the header; the copy button alone floats at the top-end of a headerless block.',+ },+ {+ name: 'Header Title',+ required: false,+ description:+ 'Groups the optional title, visible language label, and collapsible chevron inside the header bar.',+ },+ {+ name: 'Line Numbers',+ required: false,+ description:+ 'Numbered gutter along the left edge. Enable with hasLineNumbers.',+ },+ {+ name: 'Code Body',+ required: true,+ description: 'The syntax-highlighted code content.',+ },+ {+ name: 'Highlighted Lines',+ required: false,+ description: 'Background accent on specific lines to draw attention.',+ },+ {+ name: 'Copy Button',+ required: false,+ description:+ 'Copies the code string to the clipboard. Shown by default.',+ },],},};@@ -189,27 +260,66 @@ export const docs = {/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */export const docsZh = {usage: {- description: 'CodeBlock displays syntax-highlighted code snippets with optional line numbers, copy button, and collapsible sections. Use CodeBlock for fenced multi-line code and Code for inline code within prose.',+ description:+ 'CodeBlock displays syntax-highlighted code snippets with optional line numbers, copy button, and collapsible sections. Use CodeBlock for fenced multi-line code and Code for inline code within prose.',bestPractices: [- { guidance: true, description: 'Set the language prop to enable syntax highlighting. Use "plaintext" when the language is unknown or not supported.' },- { guidance: true, description: 'Use Code for short inline code references within body text, and CodeBlock for standalone multi-line snippets.' },- { guidance: false, description: 'Enable line numbers for short snippets where they add visual noise without aiding comprehension.' },- { guidance: false, description: 'Wrap code blocks in a scrollable container when isWrapped or maxHeight already handles overflow.' },+ {+ guidance: true,+ description:+ 'Set the language prop to enable syntax highlighting. Use "plaintext" when the language is unknown or not supported.',+ },+ {+ guidance: true,+ description:+ 'Use Code for short inline code references within body text, and CodeBlock for standalone multi-line snippets.',+ },+ {+ guidance: false,+ description:+ 'Enable line numbers for short snippets where they add visual noise without aiding comprehension.',+ },+ {+ guidance: false,+ description:+ 'Wrap code blocks in a scrollable container when isWrapped or maxHeight already handles overflow.',+ },],},};/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */export const docsDense = {- description: 'syntax-highlighted code block via CSS Custom Highlight API (0-DOM overhead); span-based fallback; Code for inline code in prose',+ description:+ 'syntax-highlighted code block via CSS Custom Highlight API (0-DOM overhead); span-based fallback; Code for inline code in prose',usage: {- description: 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use CodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use Code for inline references to function names, variables, or CLI flags within body text.',+ description:+ 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use CodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use Code for inline references to function names, variables, or CLI flags within body text.',bestPractices: [- {guidance: true, description: 'Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown.'},- {guidance: true, description: 'Add a title when the code represents a file. It gives readers context and appears in the header bar alongside the copy button.'},- {guidance: true, description: 'Use Code for short inline references like function names or CLI flags, and CodeBlock for standalone multi-line snippets.'},- {guidance: false, description: 'Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation.'},- {guidance: false, description: 'Nest a code block inside a scrollable container. Use the maxHeight prop instead, which handles overflow natively.'},+ {+ guidance: true,+ description:+ 'Set the language prop to match the code content so syntax highlighting is accurate. Use "plaintext" when the language is unknown.',+ },+ {+ guidance: true,+ description:+ 'Add a title when the code represents a file. It gives readers context and appears in the header bar alongside the copy button.',+ },+ {+ guidance: true,+ description:+ 'Use Code for short inline references like function names or CLI flags, and CodeBlock for standalone multi-line snippets.',+ },+ {+ guidance: false,+ description:+ 'Enable line numbers on short snippets (under 5 lines) where they add clutter without helping navigation.',+ },+ {+ guidance: false,+ description:+ 'Nest a code block inside a scrollable container. Use the maxHeight prop instead, which handles overflow natively.',+ },],},};diff --git a/packages/core/src/CodeBlock/CodeBlock.test.tsx b/packages/core/src/CodeBlock/CodeBlock.test.tsxindex 66c93db722..4afc8fd647 100644--- a/packages/core/src/CodeBlock/CodeBlock.test.tsx+++ b/packages/core/src/CodeBlock/CodeBlock.test.tsx@@ -131,7 +131,7 @@ describe('CodeBlock', () => {const copyButton = screen.getByRole('button', {name: 'Copy code'});// Theme seam: a design system can restyle the copy control via this class// without turning the button off and re-implementing it.- expect(copyButton).toHaveClass('astryx-codeblock-copy-button');+ expect(copyButton).toHaveClass('astryx-code-block-copy-button');// The button carries a visible "Copy code" hover/focus hint (tooltip),// wired through aria-describedby — a bare <button> could not.expect(copyButton).toHaveAttribute('aria-describedby');@@ -430,7 +430,7 @@ describe('CodeBlock', () => {});describe('header theming targets', () => {- it('puts astryx-codeblock-header on the header row when a header shows', () => {+ it('puts astryx-code-block-header on the header row when a header shows', () => {const {container} = render(<CodeBlockcode="const x = 1;"@@ -439,11 +439,11 @@ describe('CodeBlock', () => {/>,);expect(- container.querySelector('.astryx-codeblock-header'),+ container.querySelector('.astryx-code-block-header'),).not.toBeNull();});- it('puts astryx-codeblock-title on the header title element', () => {+ it('puts astryx-code-block-title on the header title element', () => {const {container} = render(<CodeBlockcode="const x = 1;"@@ -451,7 +451,7 @@ describe('CodeBlock', () => {title="example.js"/>,);- const titleEl = container.querySelector('.astryx-codeblock-title');+ const titleEl = container.querySelector('.astryx-code-block-title');expect(titleEl).not.toBeNull();// The language label + title text live in this element.expect(titleEl).toHaveTextContent('example.js');@@ -463,8 +463,8 @@ describe('CodeBlock', () => {const {container} = render(<CodeBlock code="const x = 1;" language="plaintext" />,);- expect(container.querySelector('.astryx-codeblock-header')).toBeNull();- expect(container.querySelector('.astryx-codeblock-title')).toBeNull();+ expect(container.querySelector('.astryx-code-block-header')).toBeNull();+ expect(container.querySelector('.astryx-code-block-title')).toBeNull();});it('keeps copy available when a known language label is hidden', async () => {@@ -498,17 +498,17 @@ describe('CodeBlock', () => {const theme = defineTheme({name: 'codeblock-header-target-test',components: {- 'codeblock-header': {+ 'code-block-header': {base: {paddingBlock: 'var(--spacing-1)'},},- 'codeblock-title': {+ 'code-block-title': {base: {fontSize: 'var(--text-body-size)'},},},});const css = generateThemeTestCSS(theme);- expect(css).toContain('.astryx-codeblock-header');- expect(css).toContain('.astryx-codeblock-title');+ expect(css).toContain('.astryx-code-block-header');+ expect(css).toContain('.astryx-code-block-title');});});@@ -535,7 +535,7 @@ describe('CodeBlock', () => {});describe('CodeBlock theme target names', () => {- it('renders the deprecated classes beside the current ones', () => {+ it('renders only the canonical target classes', () => {const {container} = render(<CodeBlockcode="const x = 1;"@@ -544,17 +544,21 @@ describe('CodeBlock theme target names', () => {/>,);expect(container.querySelector('.astryx-code-block')).toHaveClass(- 'astryx-codeblock',+ 'astryx-code-block',);expect(container.querySelector('.astryx-code-block-header')).toHaveClass(- 'astryx-codeblock-header',+ 'astryx-code-block-header',);expect(container.querySelector('.astryx-code-block-title')).toHaveClass(- 'astryx-codeblock-title',+ 'astryx-code-block-title',);expect(screen.getByRole('button', {name: 'Copy code'})).toHaveClass('astryx-code-block-copy-button',);+ expect(container.querySelector('.astryx-codeblock')).toBeNull();+ expect(container.querySelector('.astryx-codeblock-header')).toBeNull();+ expect(container.querySelector('.astryx-codeblock-title')).toBeNull();+ expect(container.querySelector('.astryx-codeblock-copy-button')).toBeNull();});it('reaches the header and title through the current defineTheme keys', () => {diff --git a/packages/core/src/CodeBlock/CodeBlock.tsx b/packages/core/src/CodeBlock/CodeBlock.tsxindex dc0a2b6e9b..24963203aa 100644--- a/packages/core/src/CodeBlock/CodeBlock.tsx+++ b/packages/core/src/CodeBlock/CodeBlock.tsx@@ -308,7 +308,7 @@ const styles = stylex.create({// The copy control is a ghost IconButton (Button owns its own padding,// radius, and hover surface); this only tints the resting glyph to the// muted syntax-comment colour so it blends into the header/corner. A theme- // reaches it via the `codeblock-copy-button` target on the Button.+ // reaches it via the `code-block-copy-button` target on the Button.color: 'var(--color-syntax-comment)',},copyButtonAbsolute: {@@ -828,20 +828,14 @@ export function CodeBlock({void handleCopy();}}xstyle={[styles.copyButton, !showHeader && styles.copyButtonAbsolute]}- {...themeProps('code-block-copy-button', undefined, {- legacyNames: ['codeblock-copy-button'],- })}+ {...themeProps('code-block-copy-button')}/>) : null;const headerEl = showHeader ? (<div{...mergeProps(- themeProps(- 'code-block-header',- {size, language, container},- {legacyNames: ['codeblock-header']},- ),+ themeProps('code-block-header', {size, language, container}),stylex.props(styles.headerRow,hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,@@ -874,11 +868,7 @@ export function CodeBlock({)}><span{...mergeProps(- themeProps(- 'code-block-title',- {size, language},- {legacyNames: ['codeblock-title']},- ),+ themeProps('code-block-title', {size, language}),stylex.props(styles.headerTitle),)}>{canCollapse && (@@ -950,13 +940,7 @@ export function CodeBlock({<preref={ref}{...mergeProps(- themeProps(- 'code-block',- {size, language, container},- // `codeblock` ran the compound name together; keep it emitted so- // existing themes continue to work.- {legacyNames: ['codeblock']},- ),+ themeProps('code-block', {size, language, container}),stylex.props(styles.root,dynamicStyles.width(widthProp),diff --git a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx b/packages/core/src/ComplexSelector/ComplexSelector.test.tsxindex 8ef223dc53..e0138e6dc1 100644--- a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx+++ b/packages/core/src/ComplexSelector/ComplexSelector.test.tsx@@ -390,7 +390,7 @@ describe('ComplexSelector popup theme target', () => {// that inner box cannot paint the popup's background or radius, which is// what a theme reaches for this class to do.expect(popup).toHaveAttribute('role', 'dialog');- expect(popup).toHaveClass('astryx-popover-surface');+ expect(popup).toHaveClass('astryx-popover');expect(popup.querySelector('[id]')).not.toBeNull();expect(popup).toContainElement(screen.getByRole('button', {name: 'Done', ...h}),diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjsindex 3e140bb5df..456d987d53 100644--- a/packages/core/src/DateInput/DateInput.doc.mjs+++ b/packages/core/src/DateInput/DateInput.doc.mjs@@ -191,10 +191,6 @@ export const docs = {states: ['disabled'],},{className: 'astryx-date-input-toggle-icon', states: ['state']},- {- className: 'astryx-date-input-clear-icon',- deprecatedFor: 'input-clear-icon',- },],},usage: {@@ -500,10 +496,6 @@ export const docsZh = {states: ['disabled'],},{className: 'astryx-date-input-toggle-icon', states: ['state']},- {- className: 'astryx-date-input-clear-icon',- deprecatedFor: 'input-clear-icon',- },],},};diff --git a/packages/core/src/DateInput/DateInput.test.tsx b/packages/core/src/DateInput/DateInput.test.tsxindex f621f25241..eb29105481 100644--- a/packages/core/src/DateInput/DateInput.test.tsx+++ b/packages/core/src/DateInput/DateInput.test.tsx@@ -1139,7 +1139,7 @@ describe('DateInput clear icon theme target', () => {return icon as HTMLElement;};- it('renders the astryx-input-clear-icon target (plus the legacy alias) on the clear glyph', () => {+ it('renders only the astryx-input-clear-icon target on the clear glyph', () => {render(<DateInputlabel="Date"@@ -1151,11 +1151,10 @@ 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 remains as a compatibility- // alias.+ // color/size.const icon = getClearIcon();expect(icon).toHaveClass('astryx-input-clear-icon');- expect(icon).toHaveClass('astryx-date-input-clear-icon');+ expect(icon).not.toHaveClass('astryx-date-input-clear-icon');expect(icon).toHaveClass('astryx-icon');});@@ -1175,13 +1174,12 @@ describe('DateInput clear icon theme target', () => {expect(onChange).toHaveBeenCalledWith(undefined);});- 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 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.+ it('routes the clear glyph through the shared clear button', () => {+ // The clear affordance composes the shared InputClearButton (a ghost Button+ // with a secondary/sm glyph), so the icon carries the canonical+ // `astryx-input-clear-icon` target. Aside from that target class it matches+ // the shared button's own `close`/`sm`/`secondary` glyph exactly, so the+ // default look is defined in one place.render(<DateInputlabel="Date"@@ -1192,7 +1190,7 @@ describe('DateInput clear icon theme target', () => {);const icon = getClearIcon();expect(icon).toHaveClass('astryx-input-clear-icon');- expect(icon).toHaveClass('astryx-date-input-clear-icon');+ expect(icon).not.toHaveClass('astryx-date-input-clear-icon');const {container: refContainer} = render(<Icon icon="close" size="sm" color="secondary" />,@@ -1202,26 +1200,22 @@ describe('DateInput clear icon theme target', () => {const styleClasses = (el: HTMLElement) =>el.className.split(' ')- .filter(- c =>- c !== 'astryx-input-clear-icon' &&- c !== 'astryx-date-input-clear-icon',- )+ .filter(c => c !== 'astryx-input-clear-icon').sort();expect(styleClasses(icon)).toEqual(styleClasses(refIcon));});- it('exposes date-input-clear-icon so a theme reaches the icon color, size, and hover', () => {+ it('uses input-clear-icon so a theme reaches the icon color, size, and hover', () => {// jsdom cannot resolve the @layer cascade, so the DOM-class assertion above// (target lands on the icon element) plus this generation assertion (the// theme emits same-element icon rules in @layer astryx-theme) together// prove the seam: a same-element theme rule wins over the icon's own// base-layer color/size.const theme = defineTheme({- name: 'date-input-clear-icon-test',+ name: 'date-input-shared-clear-icon-test',components: {- 'date-input-clear-icon': {+ 'input-clear-icon': {base: {width: '12px',height: '12px',@@ -1233,10 +1227,10 @@ describe('DateInput clear icon theme target', () => {},});const css = generateThemeTestCSS(theme);- expect(css).toContain('.astryx-date-input-clear-icon {');+ expect(css).toContain('.astryx-input-clear-icon {');expect(css).toContain('width: 12px');expect(css).toContain('height: 12px');- expect(css).toContain('.astryx-date-input-clear-icon:hover');+ expect(css).toContain('.astryx-input-clear-icon:hover');expect(css).toContain('color: var(--color-icon-primary)');});});diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsxindex ba20f5ca06..03f0183a7d 100644--- a/packages/core/src/DateInput/DateInput.tsx+++ b/packages/core/src/DateInput/DateInput.tsx@@ -191,7 +191,6 @@ import type {BaseProps} from '../BaseProps';import type {SizeValue} from '../utils/types';import {themeProps} from '../utils/themeProps';import {focusOutlineStyles} from '../utils/focusOutline.stylex';-import {stableClassName} from '../naming';import {useLocale, useTranslator} from '../i18n';import {useMergedRefs} from '../hooks/useMergedRefs';@@ -874,7 +873,6 @@ function PointerDateField({<InputClearButtonlabel={t('@astryx.dateInput.clear', {label})}onClick={handleClear}- iconClassName={stableClassName('date-input-clear-icon')}/>)}{isBusy && <Spinner size="sm" />}diff --git a/packages/core/src/DateInput/NativeDateField.tsx b/packages/core/src/DateInput/NativeDateField.tsxindex 6edcf65310..a9cdc3a04a 100644--- a/packages/core/src/DateInput/NativeDateField.tsx+++ b/packages/core/src/DateInput/NativeDateField.tsx@@ -54,7 +54,6 @@ import {Icon} from '../Icon';import {useLocale, useTranslator} from '../i18n';import {useInputGroup} from '../InputGroup';import {groupStyles} from '../InputGroup/groupStyles';-import {stableClassName} from '../naming';import {useSize} from '../SizeContext';import {Spinner} from '../Spinner';import {@@ -647,7 +646,6 @@ export function NativeDateField({<InputClearButtonlabel={t('@astryx.dateInput.clear', {label})}onClick={handleClear}- iconClassName={stableClassName('date-input-clear-icon')}/>)}{isBusy && <Spinner size="sm" />}diff --git a/packages/core/src/DateInput/TouchDateField.tsx b/packages/core/src/DateInput/TouchDateField.tsxindex c8a7a9d3ac..b817e3087b 100644--- a/packages/core/src/DateInput/TouchDateField.tsx+++ b/packages/core/src/DateInput/TouchDateField.tsx@@ -78,7 +78,6 @@ import {IconButton} from '../IconButton';import {useLocale, useTranslator} from '../i18n';import {useInputGroup} from '../InputGroup';import {groupStyles} from '../InputGroup/groupStyles';-import {stableClassName} from '../naming';import {useSize} from '../SizeContext';import {Spinner} from '../Spinner';import {@@ -1261,7 +1260,6 @@ export function TouchDateField({<InputClearButtonlabel={t('@astryx.dateInput.clear', {label})}onClick={handleClear}- iconClassName={stableClassName('date-input-clear-icon')}/>)}{isBusy && <Spinner size="sm" />}diff --git a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjsindex cf93d11c45..11074031ba 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs+++ b/packages/core/src/DateRangeInput/DateRangeInput.doc.mjs@@ -184,10 +184,6 @@ export const docs = {states: ['disabled'],},{className: 'astryx-date-range-input-toggle-icon', states: ['state']},- {- className: 'astryx-date-range-input-clear-icon',- deprecatedFor: 'input-clear-icon',- },{className: 'astryx-date-range-input-presets'},{className: 'astryx-date-range-input-preset',diff --git a/packages/core/src/DateRangeInput/DateRangeInput.spec.md b/packages/core/src/DateRangeInput/DateRangeInput.spec.mdindex 02917874eb..34305b8795 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.spec.md+++ b/packages/core/src/DateRangeInput/DateRangeInput.spec.md@@ -34,11 +34,14 @@ presets beside that calendar.## Compatibility and migration-- Released default preserved: `yes`-- Compatibility class: additive theme targets plus corrected preset constraint- enforcement; default appearance, DOM semantics, and public props remain unchanged+- Released default preserved: `yes`; canonical DateRangeInput behavior is unchanged+- 0.7.0 removes the `date-range-input-clear-icon` alias; the shared clear glyph+ remains available through `input-clear-icon`+- The preset constraint correction remains unchanged- Controlled/uncontrolled behavior: unchanged; DateRangeInput remains controlled-- Migration decision: none+- Migration decision: replace the removed theme key and CSS class with+ `input-clear-icon` and `.astryx-input-clear-icon`, or run+ `astryx upgrade --from 0.6.3 --apply --path .`Consumer migration instructions belong in consumer docs and release notes.@@ -159,9 +162,6 @@ No new performance or resource constraint is introduced.}```-The deprecated `date-range-input-clear-icon` alias remains compatibility metadata;-the shared `input-clear-icon` target owns the current glyph contract.-## Family and system relationships- `family:input-fields` owns field sizing, status placement, loading, disableddiff --git a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx b/packages/core/src/DateRangeInput/DateRangeInput.test.tsxindex f6e9d4e7cf..7b86625cd8 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.test.tsx+++ b/packages/core/src/DateRangeInput/DateRangeInput.test.tsx@@ -771,7 +771,7 @@ describe('DateRangeInput icon theme targets', () => {return icon as HTMLElement;};- it('renders astryx-input-clear-icon (plus the legacy alias) on the clear glyph', () => {+ it('renders only astryx-input-clear-icon on the clear glyph', () => {render(<DateRangeInputlabel="Range"@@ -783,11 +783,10 @@ 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 remains as a compatibility- // alias.+ // color/size.const icon = iconIn(getButton('Clear Range'));expect(icon).toHaveClass('astryx-input-clear-icon');- expect(icon).toHaveClass('astryx-date-range-input-clear-icon');+ expect(icon).not.toHaveClass('astryx-date-range-input-clear-icon');expect(icon).toHaveClass('astryx-icon');});@@ -803,8 +802,9 @@ describe('DateRangeInput icon theme targets', () => {it('routes the clear glyph through the shared clear button (default look unchanged)', () => {// Default-look guard for the clear affordance. It now composes the shared// InputClearButton (a ghost Button with a secondary/sm glyph), so aside- // from its target classes the glyph matches a standalone `secondary`/`sm`- // close icon — the default clear look is defined once, in InputClearButton.+ // from its canonical target class the glyph matches a standalone+ // `secondary`/`sm` close icon — the default clear look is defined once, in+ // InputClearButton.// (The calendar-toggle glyph is covered separately.)render(<DateRangeInput@@ -826,11 +826,7 @@ describe('DateRangeInput icon theme targets', () => {const styleClasses = (el: HTMLElement) =>el.className.split(' ')- .filter(- c =>- c !== 'astryx-input-clear-icon' &&- c !== 'astryx-date-range-input-clear-icon',- )+ .filter(c => c !== 'astryx-input-clear-icon').sort();expect(styleClasses(clearIcon)).toEqual(styleClasses(clearRefIcon));@@ -845,7 +841,7 @@ describe('DateRangeInput icon theme targets', () => {const theme = defineTheme({name: 'date-range-input-icon-test',components: {- 'date-range-input-clear-icon': {+ 'input-clear-icon': {base: {width: '12px',height: '12px',@@ -860,7 +856,7 @@ describe('DateRangeInput icon theme targets', () => {},});const css = generateThemeTestCSS(theme);- expect(css).toContain('.astryx-date-range-input-clear-icon');+ expect(css).toContain('.astryx-input-clear-icon');expect(css).toContain('.astryx-date-range-input-toggle-icon');expect(css).toContain(':hover');expect(css).toContain('12px');diff --git a/packages/core/src/DateRangeInput/DateRangeInput.tsx b/packages/core/src/DateRangeInput/DateRangeInput.tsxindex b6ae06ddd8..eb8dcb4353 100644--- a/packages/core/src/DateRangeInput/DateRangeInput.tsx+++ b/packages/core/src/DateRangeInput/DateRangeInput.tsx@@ -66,7 +66,6 @@ import {useInputStatusIcon} from '../hooks/useInputStatusIcon';import {useResolvedRequired} from '../hooks/useResolvedRequired';import {themeProps} from '../utils/themeProps';import {focusOutlineStyles} from '../utils/focusOutline.stylex';-import {stableClassName} from '../naming';import {useLocale, useTranslator} from '../i18n';import type {Locale} from '../i18n/types';@@ -711,7 +710,6 @@ export function DateRangeInput({<InputClearButtonlabel={t('@astryx.dateInput.clear', {label})}onClick={handleClear}- iconClassName={stableClassName('date-range-input-clear-icon')}/>)}{isBusy && <Spinner size="sm" />}diff --git a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx b/packages/core/src/DateTimeInput/DateTimeInput.test.tsxindex f6d862a458..39fc0f4006 100644--- a/packages/core/src/DateTimeInput/DateTimeInput.test.tsx+++ b/packages/core/src/DateTimeInput/DateTimeInput.test.tsx@@ -2377,11 +2377,10 @@ 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, 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.+ // The targets are purely additive: the stable target class and reflected+ // state 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 that theme metadata.const {container} = render(<DateTimeInput label="Meeting" onChange={() => {}} />,);diff --git a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsxindex aaa7fe78e5..56131df9ad 100644--- a/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx@@ -188,8 +188,8 @@ export function DropdownMenuCheckboxItem({onPointerMove={handlePointerMove}marker={// No wrapper, and no menu-specific theme target: the shared- // `astryx-checkbox` target is already on this element (main reached- // the menu checkbox through it too), so the menu adds only its own+ // `astryx-checkbox-indicator` target is already on this element (main+ // reached the menu checkbox through it too), so the menu adds only its own// placement rules. A wrapper here would have duplicated the// indicator's control size and moved nothing themeable.<CheckboxControldiff --git a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx b/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsxindex 5c0369084f..9a7ccd3585 100644--- a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx@@ -88,8 +88,8 @@ describe('DropdownMenuCheckboxItem', () => {expect(row.querySelector('input[type="checkbox"]')).toBeNull();// The shared checkbox target, directly on the row — no wrapper, and no// menu-specific target added for it (main reached this element through- // `astryx-checkbox` too).- const marker = row.querySelector('.astryx-checkbox');+ // `astryx-checkbox-indicator` too).+ const marker = row.querySelector('.astryx-checkbox-indicator');expect(marker).toBeInTheDocument();expect(marker).toHaveAttribute('aria-hidden', 'true');expect(marker).toHaveAttribute('data-checked', 'checked');@@ -142,21 +142,25 @@ describe('DropdownMenuRadioGroup / RadioItem', () => {// circle, so menu radios and RadioList radios theme together and a theme// never has to reach through a wrapper.const box = checked.querySelector('.astryx-dropdown-menu-radio');- expect(box).toHaveClass('astryx-radio');+ expect(box).toHaveClass('astryx-radio-indicator');expect(box).toHaveAttribute('data-size', 'md');expect(box).toHaveAttribute('data-checked', 'checked');- expect(box?.querySelector('.astryx-radio-dot')).toBeInTheDocument();+ expect(+ box?.querySelector('.astryx-radio-indicator-dot'),+ ).toBeInTheDocument();// The unchecked radio still draws its circle, without the dot.const unchecked = screen.getByRole('menuitemradio', {name: 'Oldest',hidden: true,});- const uncheckedIndicator = unchecked.querySelector('.astryx-radio');+ const uncheckedIndicator = unchecked.querySelector(+ '.astryx-radio-indicator',+ );expect(uncheckedIndicator).toBeInTheDocument();expect(uncheckedIndicator).not.toHaveAttribute('data-checked');expect(- uncheckedIndicator?.querySelector('.astryx-radio-dot'),+ uncheckedIndicator?.querySelector('.astryx-radio-indicator-dot'),).not.toBeInTheDocument();});diff --git a/packages/core/src/Field/InputClearButton.test.tsx b/packages/core/src/Field/InputClearButton.test.tsxindex d74ecfbf7c..4eadda11bb 100644--- a/packages/core/src/Field/InputClearButton.test.tsx+++ b/packages/core/src/Field/InputClearButton.test.tsx@@ -169,20 +169,17 @@ describe('InputClearButton', () => {expect(screen.getByRole('button')).toHaveAccessibleName('Clear');});- it('merges an extra iconClassName beside the canonical target', () => {- // Consumers that shipped a component-specific target before the family- // converged pass it through here to keep emitting it for a deprecation- // window.+ it('merges a consumer iconClassName beside the canonical target', () => {render(<InputClearButtonlabel="Clear"onClick={() => {}}- iconClassName="astryx-date-input-clear-icon"+ iconClassName="consumer-clear-icon"/>,);const glyph = getGlyph();expect(glyph).toHaveClass('astryx-input-clear-icon');- expect(glyph).toHaveClass('astryx-date-input-clear-icon');+ expect(glyph).toHaveClass('consumer-clear-icon');});it('exposes input-clear-icon so a theme reaches the glyph color, size, and hover', () => {diff --git a/packages/core/src/Field/InputClearButton.tsx b/packages/core/src/Field/InputClearButton.tsxindex f3e67bb326..85912bc295 100644--- a/packages/core/src/Field/InputClearButton.tsx+++ b/packages/core/src/Field/InputClearButton.tsx@@ -71,13 +71,7 @@ export interface InputClearButtonProps {label: string;onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;xstyle?: stylex.StyleXStyles;- /**- * 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 backwards- * compatibility; new callers don't need it.- */+ /** Extra class names merged onto the clear glyph beside its canonical target. */iconClassName?: string;}diff --git a/packages/core/src/FormLayout/__snapshots__/FormLayout.test.tsx.snap b/packages/core/src/FormLayout/__snapshots__/FormLayout.test.tsx.snapindex 4e55cedf22..49649ffba3 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 horizontal FormLayout__styles.base xdt5ytf x18g69wz FormLayout__styles.horizontal xrvj5dj x1mt1orb xu6a5m6"+ class="astryx-form-layout 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 horizontal-labels FormLayout__styles.base xdt5ytf FormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"+ class="astryx-form-layout 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 vertical FormLayout__styles.base x78zum5 xdt5ytf x18g69wz"+ class="astryx-form-layout FormLayout__styles.base x78zum5 xdt5ytf x18g69wz"data-direction="vertical"data-testid="layout">diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjsindex e613a8766c..610ef70a21 100644--- a/packages/core/src/HoverCard/HoverCard.doc.mjs+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs@@ -7,33 +7,49 @@ export const docs = {displayName: 'Hover Card',group: 'HoverCard',category: 'Overlay',- keywords: ["hovercard","hover card","popover","tooltip","preview card","flyout","overlay","hover popup"],+ keywords: [+ 'hovercard',+ 'hover card',+ 'popover',+ 'tooltip',+ 'preview card',+ 'flyout',+ 'overlay',+ 'hover popup',+ ],playground: {defaults: {- content: {__element: 'Text', props: {type: 'body'}, children: 'Additional details shown on hover.'},- children: {__element: 'Link', props: {href: '#'}, children: 'Hover for details'},+ content: {+ __element: 'Text',+ props: {type: 'body'},+ children: 'Additional details shown on hover.',+ },+ children: {+ __element: 'Link',+ props: {href: '#'},+ children: 'Hover for details',+ },},},theming: {- targets: [- {className: 'astryx-hover-card'},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {className: 'astryx-hovercard', deprecatedFor: 'hover-card'},- ],+ targets: [{className: 'astryx-hover-card'}],vars: [- {name: '--_hovercard-radius', description: 'Border radius of the hover card', default: 'var(--radius-container)', private: true},- ],- derived: [- {property: 'borderRadius', vars: ['--_hovercard-radius']},+ {+ name: '--_hovercard-radius',+ description: 'Border radius of the hover card',+ default: 'var(--radius-container)',+ private: true,+ },],+ derived: [{property: 'borderRadius', vars: ['--_hovercard-radius']}],},components: [{name: 'HoverCard',displayName: 'Hover Card',description:- 'Component wrapper for hover card display: a richer, larger overlay triggered on hover or focus.', props: [+ 'Component wrapper for hover card display: a richer, larger overlay triggered on hover or focus.',+ props: [{name: 'children',type: 'ReactNode',@@ -44,18 +60,26 @@ export const docs = {type: 'ReactNode',description: 'Hover card content.',required: true,- slotElements: [{__element: 'Text', props: {type: 'body'}, children: 'Content text'}],+ slotElements: [+ {+ __element: 'Text',+ props: {type: 'body'},+ children: 'Content text',+ },+ ],},{name: 'placement',type: "'above' | 'below' | 'start' | 'end'",- description: "Position relative to the anchor element. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",+ description:+ "Position relative to the anchor element. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",default: "'above'",},{name: 'alignment',type: "'start' | 'center' | 'end'",- description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",+ description:+ "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",default: "'center'",},{@@ -110,7 +134,8 @@ export const docs = {{name: 'isDefaultOpen',type: 'boolean',- description: 'Whether the hover card should be shown on mount. Still dismissible.',+ description:+ 'Whether the hover card should be shown on mount. Still dismissible.',},{name: 'isOpen',@@ -121,22 +146,75 @@ export const docs = {},],usage: {- description: 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',+ description:+ 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',bestPractices: [- { guidance: true, description: 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.' },- { guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },- { guidance: true, description: 'Use the hook API (useHoverCard) when you need more control over timing or placement.' },- { guidance: true, description: 'Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.' },- { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },- { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },- { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },- { guidance: true, description: 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.' },+ {+ guidance: true,+ description:+ 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.',+ },+ {+ guidance: true,+ description:+ 'Provide a dashed underline on text triggers so users know the element is hoverable.',+ },+ {+ guidance: true,+ description:+ 'Use the hook API (useHoverCard) when you need more control over timing or placement.',+ },+ {+ guidance: true,+ description:+ 'Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.',+ },+ {+ guidance: false,+ description:+ 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.',+ },+ {+ guidance: false,+ description:+ 'Use a hover card when a simple Tooltip or Popover would suffice.',+ },+ {+ guidance: false,+ description:+ 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.',+ },+ {+ guidance: true,+ description:+ 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.',+ },],anatomy: [- {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},- {name: 'Card', required: true, description: 'The floating overlay with the preview content, anchored to the trigger.'},- {name: 'Body', required: true, description: 'The main content area: profile info, link summary, or any rich content.'},- {name: 'Actions', required: false, description: 'Optional buttons inside the card for follow-up actions like Follow or Message.'},+ {+ name: 'Trigger',+ required: true,+ description:+ 'The element that opens the hover card on hover or focus: a button, link, or inline text.',+ },+ {+ name: 'Card',+ required: true,+ description:+ 'The floating overlay with the preview content, anchored to the trigger.',+ },+ {+ name: 'Body',+ required: true,+ description:+ 'The main content area: profile info, link summary, or any rich content.',+ },+ {+ name: 'Actions',+ required: false,+ description:+ 'Optional buttons inside the card for follow-up actions like Follow or Message.',+ },],},};@@ -146,18 +224,16 @@ export const docsZh = {name: 'HoverCard',displayName: 'Hover Card',theming: {- targets: [- {className: 'astryx-hover-card'},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {className: 'astryx-hovercard', deprecatedFor: 'hover-card'},- ],+ targets: [{className: 'astryx-hover-card'}],vars: [- {name: '--_hovercard-radius', description: 'Border radius of the hover card', default: 'var(--radius-container)', private: true},- ],- derived: [- {property: 'borderRadius', vars: ['--_hovercard-radius']},+ {+ name: '--_hovercard-radius',+ description: 'Border radius of the hover card',+ default: 'var(--radius-container)',+ private: true,+ },],+ derived: [{property: 'borderRadius', vars: ['--_hovercard-radius']}],},components: [{@@ -180,13 +256,15 @@ export const docsZh = {{name: 'placement',type: "'above' | 'below' | 'start' | 'end'",- description: '相对于锚点元素的位置。逻辑值:start/end 根据弹出层自身继承的方向解析(RTL 镜像)。',+ description:+ '相对于锚点元素的位置。逻辑值:start/end 根据弹出层自身继承的方向解析(RTL 镜像)。',default: "'above'",},{name: 'alignment',type: "'start' | 'center' | 'end'",- description: '沿放置轴的对齐方式。逻辑值:start/end 根据弹出层自身继承的方向解析(RTL 镜像)。',+ description:+ '沿放置轴的对齐方式。逻辑值:start/end 根据弹出层自身继承的方向解析(RTL 镜像)。',default: "'center'",},{@@ -247,16 +325,49 @@ export const docsZh = {},],usage: {- description: 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',+ description:+ 'HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.',bestPractices: [- { guidance: true, description: 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.' },- { guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },- { guidance: true, description: 'Use the hook API (useHoverCard) when you need more control over timing or placement.' },- { guidance: true, description: 'Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.' },- { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },- { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },- { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },- { guidance: true, description: 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.' },+ {+ guidance: true,+ description:+ 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.',+ },+ {+ guidance: true,+ description:+ 'Provide a dashed underline on text triggers so users know the element is hoverable.',+ },+ {+ guidance: true,+ description:+ 'Use the hook API (useHoverCard) when you need more control over timing or placement.',+ },+ {+ guidance: true,+ description:+ 'Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.',+ },+ {+ guidance: false,+ description:+ 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.',+ },+ {+ guidance: false,+ description:+ 'Use a hover card when a simple Tooltip or Popover would suffice.',+ },+ {+ guidance: false,+ description:+ 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.',+ },+ {+ guidance: true,+ description:+ 'Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.',+ },],},};@@ -266,35 +377,74 @@ export const docsDense = {description:'Hover/focus triggered overlay for displaying rich, interactive content anchored to trigger element.',usage: {- description: 'HoverCard shows additional info on hover/focus. Use for profile cards, link summaries, inline definitions.',+ description:+ 'HoverCard shows additional info on hover/focus. Use for profile cards, link summaries, inline definitions.',bestPractices: [- { guidance: true, description: 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.' },- { guidance: true, description: 'Provide a dashed underline on text triggers so users know the element is hoverable.' },- { guidance: true, description: 'Use the hook API (useHoverCard) when you need more control over timing or placement.' },- { guidance: true, description: 'Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.' },- { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },- { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },- { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },- { guidance: true, description: 'Prefer a block context over a direct <p>, heading, or link placement. Those placements work when necessary through a corrective portal, but DOM/tab order may differ.' },+ {+ guidance: true,+ description:+ 'Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.',+ },+ {+ guidance: true,+ description:+ 'Provide a dashed underline on text triggers so users know the element is hoverable.',+ },+ {+ guidance: true,+ description:+ 'Use the hook API (useHoverCard) when you need more control over timing or placement.',+ },+ {+ guidance: true,+ description:+ 'Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.',+ },+ {+ guidance: false,+ description:+ 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.',+ },+ {+ guidance: false,+ description:+ 'Use a hover card when a simple Tooltip or Popover would suffice.',+ },+ {+ guidance: false,+ description:+ 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.',+ },+ {+ guidance: true,+ description:+ 'Prefer a block context over a direct <p>, heading, or link placement. Those placements work when necessary through a corrective portal, but DOM/tab order may differ.',+ },],},components: [{name: 'HoverCard',displayName: 'Hover Card',- description: 'Component wrapper for hover card overlay; richer overlay triggered on hover/focus.',+ description:+ 'Component wrapper for hover card overlay; richer overlay triggered on hover/focus.',propDescriptions: {children: 'Trigger element; must accept ref.',content: 'Hover card content.',- placement: 'Position relative to anchor element. Logical: start/end follow the popover\'s inherited direction (RTL mirrors).',- alignment: 'Alignment along placement axis. Logical: start/end follow the popover\'s inherited direction (RTL mirrors).',+ placement:+ "Position relative to anchor element. Logical: start/end follow the popover's inherited direction (RTL mirrors).",+ alignment:+ "Alignment along placement axis. Logical: start/end follow the popover's inherited direction (RTL mirrors).",delay: 'Show delay in ms.',hideDelay: 'Hide delay in ms.',focusTrigger: 'Controls when focus events trigger hover card.',- touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control); tap = always opens; none = never on touch. Tap-opened cards close on a tap outside.',+ touchTrigger:+ 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control); tap = always opens; none = never on touch. Tap-opened cards close on a tap outside.',isEnabled: 'Enable/disable hover + focus triggers.',- label: 'Accessible name for the popup. With label: named role="dialog"; without: role="group".',- onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',+ label:+ 'Accessible name for the popup. With label: named role="dialog"; without: role="group".',+ onOpenChange:+ 'Callback when visibility changes; true=shown, false=hidden.',hasHoverIndication: 'Dashed underline on trigger element.',isDefaultOpen: 'Show hover card on mount. Still dismissible.',},diff --git a/packages/core/src/HoverCard/HoverCard.test.tsx b/packages/core/src/HoverCard/HoverCard.test.tsxindex 4dbfaa5523..12a0e80d7a 100644--- a/packages/core/src/HoverCard/HoverCard.test.tsx+++ b/packages/core/src/HoverCard/HoverCard.test.tsx@@ -256,7 +256,7 @@ describe('HoverCard', () => {const innerTheme = defineTheme({name: 'hovercard-inner-test',components: {- hovercard: {base: {borderWidth: '7px'}},+ 'hover-card': {base: {borderWidth: '7px'}},button: {base: {fontWeight: '700'}},},});@@ -1129,7 +1129,7 @@ describe('HoverCard', () => {});describe('HoverCard theme target names', () => {- it('renders the deprecated class beside the current one on the card surface', async () => {+ it('renders only the canonical target class on the card surface', async () => {render(<HoverCard content={<span>Card content</span>} delay={0}><button type="button">Trigger</button>@@ -1140,7 +1140,7 @@ describe('HoverCard theme target names', () => {await waitFor(() => {const layer = screen.getByText('Card content').closest('[popover]');expect(layer).toHaveClass('astryx-hover-card');- expect(layer).toHaveClass('astryx-hovercard');+ expect(layer).not.toHaveClass('astryx-hovercard');});});});diff --git a/packages/core/src/HoverCard/useHoverCard.tsx b/packages/core/src/HoverCard/useHoverCard.tsxindex 24c60ed90e..b8c6929fa9 100644--- a/packages/core/src/HoverCard/useHoverCard.tsx+++ b/packages/core/src/HoverCard/useHoverCard.tsx@@ -608,11 +608,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {props?: Omit<ContextRenderProps, 'positioning'>,): ReactNode => {const renderPlacement = props?.placement ?? placement;- const themeClassName = themeProps('hover-card', undefined, {- // `hovercard` ran the compound name together; keep it emitted so- // existing themes continue to work.- legacyNames: ['hovercard'],- }).className;+ const themeClassName = themeProps('hover-card').className;const renderProps = {placement: renderPlacement,alignment: props?.alignment ?? alignment,diff --git a/packages/core/src/Indicator/CheckIndicator.tsx b/packages/core/src/Indicator/CheckIndicator.tsxindex 3d0200e55b..6841402d2d 100644--- a/packages/core/src/Indicator/CheckIndicator.tsx+++ b/packages/core/src/Indicator/CheckIndicator.tsx@@ -24,9 +24,10 @@* host passes (`selector-check`, say) lands on the same element as* `astryx-icon` — one element carrying the mark and its theme target, per* the wrapper reduction in #4838/#4846.- * - It adds NO theme target of its own. `astryx-checkbox` and `astryx-radio`- * exist because those indicators draw chrome that needs styling; a check- * is an icon, and `astryx-icon` plus the host's target already reach it.+ * - It adds NO theme target of its own. `astryx-checkbox-indicator` and+ * `astryx-radio-indicator` exist because those indicators draw chrome that+ * needs styling; a check is an icon, and `astryx-icon` plus the host's+ * target already reach it.*/import * as stylex from '@stylexjs/stylex';diff --git a/packages/core/src/Indicator/CheckboxIndicator.tsx b/packages/core/src/Indicator/CheckboxIndicator.tsxindex e9a3688dbd..a6b623626d 100644--- a/packages/core/src/Indicator/CheckboxIndicator.tsx+++ b/packages/core/src/Indicator/CheckboxIndicator.tsx@@ -195,21 +195,15 @@ export function CheckboxIndicator({ref={ref}aria-hidden="true"{...mergeProps(- themeProps(- 'checkbox-indicator',- {- size,- checked: isChecked- ? 'checked'- : isIndeterminate- ? 'indeterminate'- : null,- disabled: isDisabled ? 'disabled' : null,- },- // `checkbox` was the target before indicators existed; keep it- // emitted so existing themes continue to work.- {legacyNames: ['checkbox']},- ),+ themeProps('checkbox-indicator', {+ size,+ checked: isChecked+ ? 'checked'+ : isIndeterminate+ ? 'indeterminate'+ : null,+ disabled: isDisabled ? 'disabled' : null,+ }),stylex.props(styles.box,boxSizeStyles[size],diff --git a/packages/core/src/Indicator/Indicator.doc.mjs b/packages/core/src/Indicator/Indicator.doc.mjsindex e49310afe3..4853a3892e 100644--- a/packages/core/src/Indicator/Indicator.doc.mjs+++ b/packages/core/src/Indicator/Indicator.doc.mjs@@ -122,8 +122,7 @@ export const docs = {{name: 'children',type: 'ReactNode',- description:- 'Rendered inside the chrome INSTEAD of the state mark.',+ description: 'Rendered inside the chrome INSTEAD of the state mark.',},],},@@ -143,25 +142,6 @@ export const docs = {states: ['checked', 'disabled'],},{className: 'astryx-radio-indicator-dot', visualProps: ['size']},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {- className: 'astryx-checkbox',- visualProps: ['size'],- states: ['checked', 'disabled'],- deprecatedFor: 'checkbox-indicator',- },- {- className: 'astryx-radio',- visualProps: ['size'],- states: ['checked', 'disabled'],- deprecatedFor: 'radio-indicator',- },- {- className: 'astryx-radio-dot',- visualProps: ['size'],- deprecatedFor: 'radio-indicator-dot',- },],},examples: [@@ -261,17 +241,17 @@ defineTheme({name: 'brand', indicators: {check: RadioIndicator}});`,{guidance: true,description:- 'Render a single root ELEMENT, and let it keep the border-radius you want the focus ring to follow. A control whose real input is visually hidden cannot show focus on that input, so the owner paints the standard ring onto the indicator element itself at focus time (useIndicatorFocusRing), and `outline` then picks up that element\'s radius. A replacement needs no cooperation and can forget nothing: the ring is never missing (WCAG 2.4.7), it is only the wrong shape if the root has no radius of its own. Do not draw a focus ring yourself; the owner already did.',+ "Render a single root ELEMENT, and let it keep the border-radius you want the focus ring to follow. A control whose real input is visually hidden cannot show focus on that input, so the owner paints the standard ring onto the indicator element itself at focus time (useIndicatorFocusRing), and `outline` then picks up that element's radius. A replacement needs no cooperation and can forget nothing: the ring is never missing (WCAG 2.4.7), it is only the wrong shape if the root has no radius of its own. Do not draw a focus ring yourself; the owner already did.",},{guidance: false,description:- 'Thread hover or pressed state in as props. Interaction state reaches an indicator through the owner\'s CSS ancestor marker, so hovering the row tints the control with no props involved.',+ "Thread hover or pressed state in as props. Interaction state reaches an indicator through the owner's CSS ancestor marker, so hovering the row tints the control with no props involved.",},{guidance: false,description:- 'Assume you are only mounted when selected. The host renders its indicator unconditionally and passes `state`, in every state; that is what lets a replacement draw where the default draws nothing (a radio\'s empty circle on an unchosen row). Drawing nothing in a state is a decision the indicator makes, not one the host makes for it.',+ "Assume you are only mounted when selected. The host renders its indicator unconditionally and passes `state`, in every state; that is what lets a replacement draw where the default draws nothing (a radio's empty circle on an unchosen row). Drawing nothing in a state is a decision the indicator makes, not one the host makes for it.",},],anatomy: [@@ -299,13 +279,41 @@ export const docsDense = {description:'Componentized selection visuals shared by CheckboxInput, RadioList, and menu rows. Decorative: the owner keeps input/role/name/focus/keyboard; the indicator turns state into a picture. That split makes them themeable: restyle via class targets or replace the component.',bestPractices: [- { guidance: true, description: "Prefer the canonical `components['checkbox-indicator']` override first. Replacing the component is the heavier path, for when the shape itself is wrong." },- { guidance: true, description: 'Match the shipped replacement-content branch with `isRenderable(children)`, not `children != null` or `children ?? mark`. The helper is shallow: it excludes nullish values, booleans, and the empty string, while React elements and containers take the replacement path even when their descendants render nothing. The owner passes `children={isBusy && <Spinner/>}`, so a nullish check deletes the state mark whenever the value is `false` (#4893).' },- { guidance: true, description: 'A replacement must set aria-hidden. The owner supplies role and accessible name; a visible indicator would be announced twice.' },- { guidance: true, description: 'Use theme tokens for every color, radius, and border width in a replacement. Run `npx @astryxdesign/cli docs tokens` for the set.' },- { guidance: true, description: 'Render a single root ELEMENT with the border-radius the focus ring should follow. The owner paints the standard ring onto the indicator at focus time (useIndicatorFocusRing) and outline picks up its radius; the ring is never missing (WCAG 2.4.7), only mis-shaped if the root lacks a radius. Do not draw a focus ring yourself.' },- { guidance: false, description: 'Thread hover or pressed state in as props. Interaction state reaches an indicator through the owner\'s CSS ancestor marker.' },- { guidance: false, description: 'Assume you are only mounted when selected. The host renders the indicator unconditionally and passes `state` in every state; that is what lets a replacement draw where the default draws nothing (a radio\'s empty circle on an unchosen row).' },+ {+ guidance: true,+ description:+ "Prefer the canonical `components['checkbox-indicator']` override first. Replacing the component is the heavier path, for when the shape itself is wrong.",+ },+ {+ guidance: true,+ description:+ 'Match the shipped replacement-content branch with `isRenderable(children)`, not `children != null` or `children ?? mark`. The helper is shallow: it excludes nullish values, booleans, and the empty string, while React elements and containers take the replacement path even when their descendants render nothing. The owner passes `children={isBusy && <Spinner/>}`, so a nullish check deletes the state mark whenever the value is `false` (#4893).',+ },+ {+ guidance: true,+ description:+ 'A replacement must set aria-hidden. The owner supplies role and accessible name; a visible indicator would be announced twice.',+ },+ {+ guidance: true,+ description:+ 'Use theme tokens for every color, radius, and border width in a replacement. Run `npx @astryxdesign/cli docs tokens` for the set.',+ },+ {+ guidance: true,+ description:+ 'Render a single root ELEMENT with the border-radius the focus ring should follow. The owner paints the standard ring onto the indicator at focus time (useIndicatorFocusRing) and outline picks up its radius; the ring is never missing (WCAG 2.4.7), only mis-shaped if the root lacks a radius. Do not draw a focus ring yourself.',+ },+ {+ guidance: false,+ description:+ "Thread hover or pressed state in as props. Interaction state reaches an indicator through the owner's CSS ancestor marker.",+ },+ {+ guidance: false,+ description:+ "Assume you are only mounted when selected. The host renders the indicator unconditionally and passes `state` in every state; that is what lets a replacement draw where the default draws nothing (a radio's empty circle on an unchosen row).",+ },],},components: [@@ -315,10 +323,13 @@ export const docsDense = {description:'Checkbox visual: a square box with a checkmark or indeterminate bar. Decorative (aria-hidden); the owner keeps input/role/name/focus/keyboard.',propDescriptions: {- state: "which state to draw. An indicator draws in EVERY state: unchecked is an empty box, not nothing.",+ state:+ 'which state to draw. An indicator draws in EVERY state: unchecked is an empty box, not nothing.',size: 'control size: 20px or 24px.',- isDisabled: 'whether the owner is disabled. Purely visual; the owner keeps the real disabled semantics.',- children: 'rendered inside the chrome INSTEAD of the state mark. CheckboxInput passes its loading Spinner through while a change action is pending, so a replacement must render children when present or the busy visual is lost.',+ isDisabled:+ 'whether the owner is disabled. Purely visual; the owner keeps the real disabled semantics.',+ children:+ 'rendered inside the chrome INSTEAD of the state mark. CheckboxInput passes its loading Spinner through while a change action is pending, so a replacement must render children when present or the busy visual is lost.',},},{@@ -327,10 +338,13 @@ export const docsDense = {description:'The mark on a chosen option: a checkmark by default, nothing when unchosen. Map to RadioIndicator for radio visuals on single-selection marks. Renders no chrome of its own (it IS the glyph), so a theme target lands on the same element as astryx-icon.',propDescriptions: {- state: 'which state to draw. The default renders nothing when unchecked; a replacement may draw in both states.',+ state:+ 'which state to draw. The default renders nothing when unchecked; a replacement may draw in both states.',size: 'control size, matching the other indicators.',- isDisabled: 'whether the owning row is disabled. Purely visual; the owner keeps the real disabled semantics.',- children: 'rendered INSTEAD of the mark, in every state; a host showing a pending Spinner passes it through whether or not the row is chosen.',+ isDisabled:+ 'whether the owning row is disabled. Purely visual; the owner keeps the real disabled semantics.',+ children:+ 'rendered INSTEAD of the mark, in every state; a host showing a pending Spinner passes it through whether or not the row is chosen.',},},{@@ -339,9 +353,11 @@ export const docsDense = {description:'Radio visual: a circle with a filled inner dot when selected. Draws in both states; an unselected radio is an empty circle, which is what lets it stand in for a checkmark in a selection slot.',propDescriptions: {- state: 'which state to draw. Radio belongs to the singleSelection family, which has no partial state.',+ state:+ 'which state to draw. Radio belongs to the singleSelection family, which has no partial state.',size: 'control size: 20px or 24px.',- isDisabled: 'whether the owner is disabled. Purely visual; the owner keeps the real disabled semantics.',+ isDisabled:+ 'whether the owner is disabled. Purely visual; the owner keeps the real disabled semantics.',children: 'rendered inside the chrome INSTEAD of the state mark.',},},diff --git a/packages/core/src/Indicator/Indicator.test.tsx b/packages/core/src/Indicator/Indicator.test.tsxindex eb144b71e4..bf7bb29a58 100644--- a/packages/core/src/Indicator/Indicator.test.tsx+++ b/packages/core/src/Indicator/Indicator.test.tsx@@ -23,7 +23,7 @@ describe('default indicators', () => {it('renders the checkbox theme target with state and size', () => {render(<CheckboxIndicator state="indeterminate" size="sm" />);- const box = document.querySelector('.astryx-checkbox');+ const box = document.querySelector('.astryx-checkbox-indicator');expect(box).toBeInTheDocument();expect(box).toHaveAttribute('data-checked', 'indeterminate');expect(box).toHaveAttribute('data-size', 'sm');@@ -36,12 +36,18 @@ describe('default indicators', () => {// The circle draws in the unchecked state — this is what lets a radio act// as a selection indicator where an icon would render nothing.- expect(document.querySelector('.astryx-radio')).toBeInTheDocument();- expect(document.querySelector('.astryx-radio-dot')).not.toBeInTheDocument();+ expect(+ document.querySelector('.astryx-radio-indicator'),+ ).toBeInTheDocument();+ expect(+ document.querySelector('.astryx-radio-indicator-dot'),+ ).not.toBeInTheDocument();rerender(<RadioIndicator state="checked" />);- expect(document.querySelector('.astryx-radio-dot')).toBeInTheDocument();- expect(document.querySelector('.astryx-radio')).toHaveAttribute(+ expect(+ document.querySelector('.astryx-radio-indicator-dot'),+ ).toBeInTheDocument();+ expect(document.querySelector('.astryx-radio-indicator')).toHaveAttribute('data-checked','checked',);@@ -60,7 +66,7 @@ describe('default indicators', () => {it('reflects the disabled state for theme targeting', () => {render(<RadioIndicator state="checked" isDisabled />);- expect(document.querySelector('.astryx-radio')).toHaveAttribute(+ expect(document.querySelector('.astryx-radio-indicator')).toHaveAttribute('data-disabled','disabled',);@@ -340,54 +346,44 @@ 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 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.- */-describe('renamed theme targets stay non-breaking', () => {+/** Canonical target names are the only component classes emitted in 0.7. */+describe('indicator theme target names', () => {const cases = [{name: 'CheckboxIndicator',render: () => <CheckboxIndicator state="checked" />,current: 'astryx-checkbox-indicator',- legacy: 'astryx-checkbox',+ removed: 'astryx-checkbox',},{name: 'RadioIndicator',render: () => <RadioIndicator state="checked" />,current: 'astryx-radio-indicator',- legacy: 'astryx-radio',+ removed: 'astryx-radio',},] as const;- for (const {name, render: renderCase, current, legacy} of cases) {- it(`${name} emits both the current and the legacy target`, () => {+ for (const {name, render: renderCase, current, removed} of cases) {+ it(`${name} emits only the canonical target`, () => {const {container} = render(renderCase());const el = container.querySelector(`.${current}`);expect(el, `${name} should render ${current}`).toBeInTheDocument();- expect(el, `${name} must keep emitting ${legacy}`).toHaveClass(legacy);+ expect(el, `${name} must not render ${removed}`).not.toHaveClass(removed);});}- it('keeps the legacy dot target on the radio mark', () => {+ it('uses only the canonical dot target on the radio mark', () => {const {container} = render(<RadioIndicator state="checked" />);const dot = container.querySelector('.astryx-radio-indicator-dot');expect(dot).toBeInTheDocument();- expect(dot).toHaveClass('astryx-radio-dot');+ expect(dot).not.toHaveClass('astryx-radio-dot');});- it('puts both names on ONE element, so either selector wins equally', () => {- // If the legacy class were moved to a wrapper instead, an old theme's- // rules would land on a different box than a new theme's — same-element- // is what makes the two names interchangeable.+ it('renders one canonical checkbox target element', () => {const {container} = render(<CheckboxIndicator state="unchecked" />);- expect(container.querySelectorAll('.astryx-checkbox')).toHaveLength(1);- expect(container.querySelector('.astryx-checkbox')).toBe(- container.querySelector('.astryx-checkbox-indicator'),- );+ expect(+ container.querySelectorAll('.astryx-checkbox-indicator'),+ ).toHaveLength(1);+ expect(container.querySelector('.astryx-checkbox')).toBeNull();});});diff --git a/packages/core/src/Indicator/RadioIndicator.tsx b/packages/core/src/Indicator/RadioIndicator.tsxindex 03b08b1f38..86f726d3f8 100644--- a/packages/core/src/Indicator/RadioIndicator.tsx+++ b/packages/core/src/Indicator/RadioIndicator.tsx@@ -127,7 +127,8 @@ const dotSizeStyles = stylex.create({* Decorative and non-interactive — it renders `aria-hidden` and owns no input,* role, or focus behavior. Themes replace it wholesale through* `defineTheme({indicators: {radio: MyRadio}})`, or restyle it through the- * `radio` / `radio-dot` theme targets like any other component.+ * `radio-indicator` / `radio-indicator-dot` theme targets like any other+ * component.** Unlike an icon, a radio draws in *both* states — an empty circle when* unchecked. That is what makes it usable as a selection indicator in@@ -163,17 +164,11 @@ export function RadioIndicator({ref={ref}aria-hidden="true"{...mergeProps(- themeProps(- 'radio-indicator',- {- size,- checked: isChecked ? 'checked' : null,- disabled: isDisabled ? 'disabled' : null,- },- // `radio` was the target before indicators existed; keep it emitted- // so existing themes continue to work.- {legacyNames: ['radio']},- ),+ themeProps('radio-indicator', {+ size,+ checked: isChecked ? 'checked' : null,+ disabled: isDisabled ? 'disabled' : null,+ }),stylex.props(styles.circle,circleSizeStyles[size],@@ -190,11 +185,7 @@ export function RadioIndicator({: isChecked && (<span{...mergeProps(- themeProps(- 'radio-indicator-dot',- {size},- {legacyNames: ['radio-dot']},- ),+ themeProps('radio-indicator-dot', {size}),stylex.props(styles.dot, dotSizeStyles[size]),)}/>diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjsindex b7334d1f82..912d0e8df6 100644--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs@@ -147,10 +147,6 @@ export const docs = {visualProps: ['variant', 'size', 'status'],states: ['disabled', 'readonly'],},- {- className: 'astryx-multi-selector-clear-icon',- deprecatedFor: 'input-clear-icon',- },{className: 'astryx-multi-selector-empty-state'},{className: 'astryx-multi-selector-search'},{className: 'astryx-multi-selector-section-heading'},diff --git a/packages/core/src/MultiSelector/MultiSelector.spec.md b/packages/core/src/MultiSelector/MultiSelector.spec.mdindex 8a0a466f26..e134a36ee5 100644--- a/packages/core/src/MultiSelector/MultiSelector.spec.md+++ b/packages/core/src/MultiSelector/MultiSelector.spec.md@@ -65,7 +65,11 @@ behavior.calls are unchanged.- Controlled/uncontrolled behavior: unchanged. Open state stays owned by thecomponent; `handleRef` drives it and `onOpenChange` reports it.-- Migration decision: none+- 0.7.0 removes the `multi-selector-clear-icon` alias; the shared clear glyph+ remains available through `input-clear-icon`.+- Migration decision: replace the removed theme key and CSS class with+ `input-clear-icon` and `.astryx-input-clear-icon`, or run+ `astryx upgrade --from 0.6.3 --apply --path .`Consumer migration instructions belong in consumer docs and release notes.@@ -118,7 +122,7 @@ syntax and examples remain in `MultiSelector.doc.mjs`.| FR3 | Trigger, Indicator icon, Search row, Option row, Section heading, Empty state, and Pointer popup carry the seven current non-deprecated MultiSelector targets documented in `MultiSelector.doc.mjs`. | Current source, docs, and tests | Verified current behavior; no target change || FR4 | When present, Field, shared clear actions, option checkbox indicators, public Option dividers, general icons, Touch sheet heading, and Touch sheet retain their Field, CheckboxInput, Divider, Icon, Text, and BottomSheet theming owners. | Current composition and owners | Verified current behavior; no target change || FR5 | Pointer popup and Touch sheet are separate surface anatomy rows, but both host the same `panelContent` tree; the Touch sheet additionally renders its Heading. Changing presentation does not create a second search, option, divider, section, or empty-state content model. | Current source and tests | Verified current behavior; no normalization |-| FR6 | `multi-selector-clear-icon` remains a deprecated compatibility alias for `input-clear-icon`; it is not a current target and does not claim a separate anatomy part. | Current public target metadata | Verified current compatibility state |+| FR6 | Clear glyphs delegate exclusively to the shared `input-clear-icon` target; removed per-component aliases do not claim anatomy. | Current public target metadata | Verified canonical ownership || FR7 | While `isReadOnly` is true, selected values remain focusable and form-submittable, while the selection surface, clear action, disclosure indicator, and every value-change path are unavailable. | `spec:AST-011`, docs, and tests | Accepted read-only behavior || FR8 | With `renderTrigger`, the caller-rendered control receives `ref`, `id`, `onClick`, `onKeyDown`, `onFocus`, `aria-haspopup`, `aria-expanded`, `aria-controls`, and `aria-busy`; the panel is anchored to it, focus returns to it on close, the listbox is named by `label`, and the listbox takes focus and owns the keyboard on open. No Field, status, clear action, spinner, or indicator renders. `handleRef` exposes `open`, `close`, `toggle`, `isOpen`; `onOpenChange` fires on every open and close. | DEC-1, docs, and tests | Proposed; awaiting owner approval || FR9 | With `hasSearch` and `hasCreate`, once options have loaded, a `Create "<query>"` row leads the list when the trimmed query equals no option label under the search's own case-insensitive matching. Picking it, or Enter with nothing highlighted, calls `onChange` with the query appended to the value and a `{type: 'create', query}` descriptor, clears the search, and announces the creation; every other change passes no descriptor. The row has no checkbox, is never selected, is excluded from select-all and from `renderOption`, and is announced instead of the empty message when it is the only result. While `isLoading`, no row is offered and Enter commits nothing. `hasCreate` without `hasSearch` warns in development and offers nothing. | `spec:AST-056` FR5 / DEC-3, `component:Tokenizer` `hasCreate`, docs, and tests | Proposed; awaiting owner approval |@@ -278,7 +282,7 @@ empty-state content remains one shared tree.- `architecture:public-component-api` and `spec:AST-011/DEC-1` own the additiveread-only API and its cross-input meaning.- `architecture:component-theming-surface` owns anatomy qualification, local- target mapping, delegation, and exclusion of deprecated aliases.+ target mapping, delegation, and exclusion of removed aliases.- `architecture:layer-runtime` owns the current Popover host and the distinctionbetween browser popover and native-dialog sheet presentation.- `family:overlay-dismissal` owns shared Escape and platform-close ordering. The@@ -292,7 +296,7 @@ empty-state content remains one shared tree.| Contract | Verification | Representative states | Mutation or failure expectation | Audit section || ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- || FR1, FR2 | `MultiSelector.test.tsx` render, search, divider, grouping, status, select-all, and empty-state suites plus InputGroup source inspection | Standalone/InputGroup, search, divided, selected, empty, status | Removing a documented part or misreporting Field presence conflicts with existing structure, content assertions, or source. | `audit:MultiSelector/anatomy` |-| FR3, FR6 | Component target suites, source inspection, and public target inventory | All seven current targets and deprecated alias | A current target is missed, invented, moved, or confused with the deprecated clear-icon alias. | `audit:MultiSelector/theming` |+| FR3, FR6 | Component target suites, source inspection, and public target inventory | All seven canonical local targets and shared clear-icon delegation | A current target is missed, invented, moved, or the clear glyph stops delegating to `input-clear-icon`. | `audit:MultiSelector/theming` || FR4 | Composed owner source/tests for Field, CheckboxInput, Divider, Icon, Text, and BottomSheet | Field omission/presence, clear actions, checkbox, divider, icons, heading, sheet | A shared part gains the wrong local owner or its documented owner no longer renders it. | `audit:MultiSelector/theming` || FR5 | `MultiSelector.test.tsx` presentation suites and `panelContent` source inspection | Explicit popover, explicit sheet, adaptive touch | A presentation stops using its owner or receives a divergent panel-content implementation. | `audit:MultiSelector/overlay` || FR7 | read-only interaction, form, ARIA, and theme-state tests | search/non-search, clearable, open→read-only, disabled precedence | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent. | `audit:MultiSelector/accessibility` |diff --git a/packages/core/src/MultiSelector/MultiSelector.test.tsx b/packages/core/src/MultiSelector/MultiSelector.test.tsxindex ffca832eac..3f6e3e6c93 100644--- a/packages/core/src/MultiSelector/MultiSelector.test.tsx+++ b/packages/core/src/MultiSelector/MultiSelector.test.tsx@@ -2475,7 +2475,7 @@ describe('MultiSelector clear icon theme target', () => {return icon as HTMLElement;};- it('renders the astryx-input-clear-icon target (plus the legacy alias) on the clear glyph', () => {+ it('renders only the astryx-input-clear-icon target on the clear glyph', () => {render(<MultiSelectorlabel="Fruit"@@ -2488,11 +2488,10 @@ 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 remains as a compatibility- // alias.+ // color/size.const icon = getClearIcon();expect(icon).toHaveClass('astryx-input-clear-icon');- expect(icon).toHaveClass('astryx-multi-selector-clear-icon');+ expect(icon).not.toHaveClass('astryx-multi-selector-clear-icon');expect(icon).toHaveClass('astryx-icon');});@@ -2513,13 +2512,12 @@ describe('MultiSelector clear icon theme target', () => {expect(onChange).toHaveBeenCalledWith([]);});- 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 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.+ it('routes the clear glyph through the shared clear button', () => {+ // The clear affordance composes the shared InputClearButton (a ghost Button+ // with a secondary/sm glyph), so the icon carries the canonical+ // `astryx-input-clear-icon` target. Aside from that target class it matches+ // the shared button's own `close`/`sm`/`secondary` glyph exactly, so the+ // default look is defined in one place.render(<MultiSelectorlabel="Fruit"@@ -2531,7 +2529,7 @@ describe('MultiSelector clear icon theme target', () => {);const icon = getClearIcon();expect(icon).toHaveClass('astryx-input-clear-icon');- expect(icon).toHaveClass('astryx-multi-selector-clear-icon');+ expect(icon).not.toHaveClass('astryx-multi-selector-clear-icon');const {container: refContainer} = render(<Icon icon="close" size="sm" color="secondary" />,@@ -2541,26 +2539,22 @@ describe('MultiSelector clear icon theme target', () => {const styleClasses = (el: HTMLElement) =>el.className.split(' ')- .filter(- c =>- c !== 'astryx-input-clear-icon' &&- c !== 'astryx-multi-selector-clear-icon',- )+ .filter(c => c !== 'astryx-input-clear-icon').sort();expect(styleClasses(icon)).toEqual(styleClasses(refIcon));});- it('exposes multi-selector-clear-icon so a theme reaches the icon color, size, and hover', () => {+ it('uses input-clear-icon so a theme reaches the icon color, size, and hover', () => {// jsdom cannot resolve the @layer cascade, so the DOM-class assertion above// (target lands on the icon element) plus this generation assertion (the// theme emits same-element icon rules in @layer astryx-theme) together// prove the seam: a same-element theme rule wins over the icon's own// base-layer color/size.const theme = defineTheme({- name: 'multi-selector-clear-icon-test',+ name: 'multi-selector-shared-clear-icon-test',components: {- 'multi-selector-clear-icon': {+ 'input-clear-icon': {base: {width: '12px',height: '12px',@@ -2572,10 +2566,10 @@ describe('MultiSelector clear icon theme target', () => {},});const css = generateThemeTestCSS(theme);- expect(css).toContain('.astryx-multi-selector-clear-icon {');+ expect(css).toContain('.astryx-input-clear-icon {');expect(css).toContain('width: 12px');expect(css).toContain('height: 12px');- expect(css).toContain('.astryx-multi-selector-clear-icon:hover');+ expect(css).toContain('.astryx-input-clear-icon:hover');expect(css).toContain('color: var(--color-icon-primary)');});});@@ -3186,7 +3180,7 @@ describe('MultiSelector popup theme target', () => {'.astryx-multi-selector-popup',) as HTMLElement;expect(popup).not.toBeNull();- expect(popup).toHaveClass('astryx-popover-surface');+ expect(popup).toHaveClass('astryx-popover');// The scrolling list is a descendant, not the target itself.expect(popup.querySelector('[role="listbox"]')).not.toBeNull();expect(popup.getAttribute('role')).toBeNull();diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsxindex 7cade1685c..a8c9778c20 100644--- a/packages/core/src/MultiSelector/MultiSelector.tsx+++ b/packages/core/src/MultiSelector/MultiSelector.tsx@@ -85,7 +85,6 @@ import {themeProps} from '../utils/themeProps';import {focusOutlineStyles} from '../utils/focusOutline.stylex';import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';import {usePressFeedback} from '../hooks/usePressFeedback';-import {stableClassName} from '../naming';import {groupStyles} from '../InputGroup/groupStyles';import {useInputGroup} from '../InputGroup/InputGroupContext';import {VisuallyHidden} from '../VisuallyHidden';@@ -2443,7 +2442,6 @@ export function MultiSelector<T extends MultiSelectorOptionType>({{...keepOpenProps}label={t('@astryx.multiSelector.clearAll', {label})}onClick={handleClear}- iconClassName={stableClassName('multi-selector-clear-icon')}/>)}{/*diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjsindex 5a994e3f2b..191ff57357 100644--- a/packages/core/src/NavIcon/NavIcon.doc.mjs+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs@@ -10,7 +10,8 @@ const anatomy = [{name: 'Icon',required: true,- description: 'Caller-supplied visual content rendered inside the container.',+ description:+ 'Caller-supplied visual content rendered inside the container.',},];@@ -23,7 +24,13 @@ export const docs = {category: 'Navigation',isHiddenFromOverview: true,hidden: false,- keywords: ["navicon","iconbutton","toolbar icon","appbar icon","nav button"],+ keywords: [+ 'navicon',+ 'iconbutton',+ 'toolbar icon',+ 'appbar icon',+ 'nav button',+ ],props: [{name: 'icon',@@ -35,21 +42,28 @@ export const docs = {},],theming: {- targets: [- {className: 'astryx-nav-icon'},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {className: 'astryx-navicon', deprecatedFor: 'nav-icon'},- ],+ targets: [{className: 'astryx-nav-icon'}],},usage: {anatomy,description:'NavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.',bestPractices: [- { guidance: true, description: 'Use in navigation headers to provide a recognizable visual anchor for the section.' },- { guidance: true, description: 'Pass an Icon or similarly sized icon component to ensure proper proportions.' },- { guidance: false, description: 'Use NavIcon for interactive purposes; it is a display-only container, not a button.' },+ {+ guidance: true,+ description:+ 'Use in navigation headers to provide a recognizable visual anchor for the section.',+ },+ {+ guidance: true,+ description:+ 'Pass an Icon or similarly sized icon component to ensure proper proportions.',+ },+ {+ guidance: false,+ description:+ 'Use NavIcon for interactive purposes; it is a display-only container, not a button.',+ },],},};@@ -62,27 +76,33 @@ export const docsZh = {{name: 'icon',type: 'ReactNode',- description:- '在圆形背景内渲染的图标元素。应为 Icon 或类似的图标组件。',+ description: '在圆形背景内渲染的图标元素。应为 Icon 或类似的图标组件。',required: true,},],theming: {- targets: [- {className: 'astryx-nav-icon'},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {className: 'astryx-navicon', deprecatedFor: 'nav-icon'},- ],+ targets: [{className: 'astryx-nav-icon'}],},usage: {anatomy,description:'NavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.',bestPractices: [- { guidance: true, description: 'Use in navigation headers to provide a recognizable visual anchor for the section.' },- { guidance: true, description: 'Pass an Icon or similarly sized icon component to ensure proper proportions.' },- { guidance: false, description: 'Use NavIcon for interactive purposes; it is a display-only container, not a button.' },+ {+ guidance: true,+ description:+ 'Use in navigation headers to provide a recognizable visual anchor for the section.',+ },+ {+ guidance: true,+ description:+ 'Pass an Icon or similarly sized icon component to ensure proper proportions.',+ },+ {+ guidance: false,+ description:+ 'Use NavIcon for interactive purposes; it is a display-only container, not a button.',+ },],},};@@ -96,9 +116,21 @@ export const docsDense = {description:'NavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.',bestPractices: [- { guidance: true, description: 'Use in navigation headers to provide a recognizable visual anchor for the section.' },- { guidance: true, description: 'Pass an Icon or similarly sized icon component to ensure proper proportions.' },- { guidance: false, description: 'Use NavIcon for interactive purposes; it is a display-only container, not a button.' },+ {+ guidance: true,+ description:+ 'Use in navigation headers to provide a recognizable visual anchor for the section.',+ },+ {+ guidance: true,+ description:+ 'Pass an Icon or similarly sized icon component to ensure proper proportions.',+ },+ {+ guidance: false,+ description:+ 'Use NavIcon for interactive purposes; it is a display-only container, not a button.',+ },],},propDescriptions: {diff --git a/packages/core/src/NavIcon/NavIcon.spec.md b/packages/core/src/NavIcon/NavIcon.spec.mdindex ebc1a411a4..224a753496 100644--- a/packages/core/src/NavIcon/NavIcon.spec.md+++ b/packages/core/src/NavIcon/NavIcon.spec.md@@ -26,16 +26,16 @@ system_specs: []## IntentNavIcon renders caller-supplied icon content inside a circular navigation-container. This draft records the current consumer anatomy and theming ownership-without changing runtime behavior or target compatibility.+container. This record preserves that runtime behavior while 0.7.0 removes the+deprecated `navicon` theming alias.## Compatibility and migration-- Released default preserved: `yes`-- Compatibility class: additive documentation only; runtime, DOM, styling,- targets, aliases, and public API remain unchanged+- Released default preserved: `yes`; canonical `nav-icon` behavior is unchanged+- Removed alias: 0.7.0 stops emitting `navicon`- Controlled/uncontrolled behavior: not applicable-- Migration decision: none+- Migration decision: replace `navicon` theme keys and `.astryx-navicon` selectors+ with `nav-icon` and `.astryx-nav-icon`, or run `astryx upgrade --from 0.6.3 --apply --path .`Consumer migration instructions belong in consumer docs and release notes.@@ -57,10 +57,10 @@ in `NavIcon.doc.mjs`.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ------------------------------------------------------------------------------------------------ | ------------------------------- | -------------------------------------------------- |-| FR1 | The current render contains a circular container and the caller-supplied icon content. | Current source, docs, and tests | Verified current behavior; no new behavior decided |-| FR2 | The container carries `nav-icon`; the deprecated `navicon` alias remains compatibility metadata. | Current source, docs, and tests | Verified current behavior; no target change |+| ID | Candidate invariant | Basis | Draft review state |+| --- | -------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |+| FR1 | The current render contains a circular container and the caller-supplied icon content. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| FR2 | The container carries the canonical `nav-icon` target. | Current source, docs, and tests | Verified canonical behavior; 0.7 alias removed |### Allowed variation@@ -90,9 +90,6 @@ This draft does not change or extend NavIcon's existing accessibility behavior.| Container | Presents the current circular painted surface. | Current source and public docs | Supporting | FR1, FR2 || Icon | Presents caller-supplied visual content. | Caller-supplied content | Context-dependent | FR1 |-The deprecated `navicon` alias is compatibility metadata, not a separate anatomy-part or current target.-### Theming anatomy<!-- anatomy-theming:v1 -->@@ -108,16 +105,15 @@ part or current target.This draft references the current shared owners without restating their rules:`architecture:component-theming-surface` and-`architecture:public-component-api`. The deprecated `navicon` alias remains-compatibility metadata rather than separate anatomy.+`architecture:public-component-api`.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------- |-| FR1 | `NavIcon.test.tsx` content suite | Caller-supplied icon | Removing the container or supplied content fails existing render and ref assertions. | `audit:NavIcon/anatomy` |-| FR2 | `NavIcon.test.tsx` target-name suite | Current and deprecated target classes | Removing either emitted compatibility class fails the existing target assertion. | `audit:NavIcon/theming` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:NavIcon/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------- | ----------------------- |+| FR1 | `NavIcon.test.tsx` content suite | Caller-supplied icon | Removing the container or supplied content fails existing render and ref assertions. | `audit:NavIcon/anatomy` |+| FR2 | `NavIcon.test.tsx` target-name suite | Canonical target class | Missing or renamed canonical target fails the target assertion. | `audit:NavIcon/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:NavIcon/theming` |## Decision logdiff --git a/packages/core/src/NavIcon/NavIcon.test.tsx b/packages/core/src/NavIcon/NavIcon.test.tsxindex 7394adc5b9..ea96b48d68 100644--- a/packages/core/src/NavIcon/NavIcon.test.tsx+++ b/packages/core/src/NavIcon/NavIcon.test.tsx@@ -32,10 +32,10 @@ describe('NavIcon', () => {});describe('NavIcon theme target names', () => {- it('renders the deprecated class beside the current one', () => {+ it('renders only the canonical target class', () => {render(<NavIcon icon={<span>Icon</span>} data-testid="nav-icon" />);const root = screen.getByTestId('nav-icon');expect(root).toHaveClass('astryx-nav-icon');- expect(root).toHaveClass('astryx-navicon');+ expect(root).not.toHaveClass('astryx-navicon');});});diff --git a/packages/core/src/NavIcon/NavIcon.tsx b/packages/core/src/NavIcon/NavIcon.tsxindex 1aecbc55ad..44ffb9e723 100644--- a/packages/core/src/NavIcon/NavIcon.tsx+++ b/packages/core/src/NavIcon/NavIcon.tsx@@ -79,11 +79,7 @@ export function NavIcon({<spanref={ref}{...mergeProps(- themeProps('nav-icon', undefined, {- // `navicon` ran the compound name together; keep it emitted so- // existing themes continue to work.- legacyNames: ['navicon'],- }),+ themeProps('nav-icon'),stylex.props(styles.base, xstyle),className,style,diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjsindex 846f528782..408f4e700e 100644--- a/packages/core/src/Popover/Popover.doc.mjs+++ b/packages/core/src/Popover/Popover.doc.mjs@@ -200,12 +200,6 @@ export const docs = {targets: [// Canonical broad target for the painted Popover surface.{className: 'astryx-popover'},- // Deprecated compatibility alias. Existing themes remain supported;- // new themes target `popover`.- {- className: 'astryx-popover-surface',- deprecatedFor: 'popover',- },],vars: [{@@ -234,7 +228,7 @@ export const docs = {{guidance: true,description:- 'Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.',+ 'Theme the painted surface through the canonical popover target.',},{guidance: false,@@ -263,7 +257,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 supported as a deprecated compatibility alias.',+ 'Painted surface owned and themed by Popover through the canonical popover target.',},{name: 'Popover content',@@ -410,12 +404,6 @@ export const docsZh = {targets: [// Canonical broad target for the painted Popover surface.{className: 'astryx-popover'},- // Deprecated compatibility alias. Existing themes remain supported;- // new themes target `popover`.- {- className: 'astryx-popover-surface',- deprecatedFor: 'popover',- },],vars: [{@@ -444,7 +432,7 @@ export const docsZh = {{guidance: true,description:- 'Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.',+ 'Theme the painted surface through the canonical popover target.',},{guidance: false,@@ -473,7 +461,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 supported as a deprecated compatibility alias.',+ 'Painted surface owned and themed by Popover through the canonical popover target.',},{name: 'Popover content',@@ -511,7 +499,7 @@ export const docsDense = {{guidance: true,description:- 'Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.',+ 'Theme the painted surface through the canonical popover target.',},{guidance: false,@@ -540,7 +528,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 supported as a deprecated compatibility alias.',+ 'Painted surface owned and themed by Popover through the canonical popover target.',},{name: 'Popover content',diff --git a/packages/core/src/Popover/Popover.spec.md b/packages/core/src/Popover/Popover.spec.mdindex 668d9c3af3..27b0a67301 100644--- a/packages/core/src/Popover/Popover.spec.md+++ b/packages/core/src/Popover/Popover.spec.md@@ -49,8 +49,8 @@ direction settled by Cindy Zhang on 2026-08-31, the focus/opening correctionapproved by Cindy Zhang on 2026-09-07, and the move of viewport fitting to thelayer runtime decided by Cindy Zhang on 2026-10-03 (`spec:AST-059`). Public API signatures and release statusremain 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.+`Popover.doc.mjs` and `usePopover.doc.mjs`. The canonical `popover` target is the+only broad Popover surface target.DEC-4 below (pending owner review) adds one public concept: the surface paddingrung, so a caller whose content owns its own edges can ask for a flush surface.@@ -58,25 +58,15 @@ rung, so a caller whose content owns its own edges can ask for a flush surface.## Compatibility and migration- Released default preserved: `yes`-- 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 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+ `<Popover>` and public `usePopover` compositions+- Removed alias: 0.7.0 removes `popover-surface`; themes and CSS selectors migrate+ it to `popover` with `astryx upgrade --from 0.6.3 --apply --path .`- Composed components: component-specific surface targets such as- `selector-popup` and `multi-selector-popup` remain authoritative refinements;- the broad canonical and compatibility targets remain underneath+ `selector-popup` and `multi-selector-popup` remain authoritative refinements+ beside the broad canonical target- 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: maintained themes and copyable new examples use `popover`;- compatibility discovery and runtime support for `popover-surface` continue--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.+ reachability provides and documents an owned `surfaceTarget`## Ownership boundary@@ -181,16 +171,16 @@ 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 | Retired. Viewport and safe-area capping is the layer runtime's (`spec:AST-059` FR2, FR3); Popover clamps its preferred size with the runtime's cap and caps its painted surface with the same definition. | `spec:AST-059`, owner direction 2026-10-03 | Retired; see `architecture:layer-runtime` INV11 and the `Core/Layer` viewport-inset stories |-| 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 |-| FR8 | The surface padding is one spacing-scale rung applied on the painted surface. Popover defaults to step 3 (the released inset); `0` paints a flush surface; a direct `usePopover` composition paints none unless it asks for a rung. The rung sits where a theme's `padding` on the `popover` target replaces it. | PR #6683 and its Popover tests; `architecture:container-padding/INV8` (padding alone does not enroll) | Pending owner review (DEC-4); implemented and covered by the Popover surface-padding suite |+| 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 | Retired. Viewport and safe-area capping is the layer runtime's (`spec:AST-059` FR2, FR3); Popover clamps its preferred size with the runtime's cap and caps its painted surface with the same definition. | `spec:AST-059`, owner direction 2026-10-03 | Retired; see `architecture:layer-runtime` INV11 and the `Core/Layer` viewport-inset stories |+| 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`; composed components may add one authoritative component-specific refinement target. | Owner direction on 2026-08-31 plus current target inventory | Accepted canonical contract; covered by focused target tests |+| FR8 | The surface padding is one spacing-scale rung applied on the painted surface. Popover defaults to step 3 (the released inset); `0` paints a flush surface; a direct `usePopover` composition paints none unless it asks for a rung. The rung sits where a theme's `padding` on the `popover` target replaces it. | PR #6683 and its Popover tests; `architecture:container-padding/INV8` (padding alone does not enroll) | Pending owner review (DEC-4); implemented and covered by the Popover surface-padding suite |### Allowed variation@@ -305,24 +295,11 @@ table owns their semantic effect.}```-### Deprecated compatibility target--`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 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.+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`.## Family and system relationships@@ -336,25 +313,24 @@ removal.focus-indicator visibility. Popover owns semantic focus entry and fallback;pointer input does not select a different destination merely to hide an outline.- `architecture:component-theming-surface` owns anatomy qualification and target- placement. `popover` is the one broad target on the painted surface;- `popover-surface` is only its deprecated compatibility alias. Caller content- adds no target, the fallback close control delegates to Button's target, and- composed components own any additional surface refinement target.+ placement. `popover` is the one broad target on the painted surface. Caller+ content adds no target, the fallback close control delegates to Button's target,+ and composed components own any additional surface refinement target.- `family:overlay-dismissal` owns topmost Escape and platform-close ordering.Popover participates through the shared layer owner while retaining its localfocus, outside-dismiss, and open-state behavior.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |-| Public boundary, FR1 | `Popover.test.tsx` compile-time public-surface assertions plus package/barrel inspection | Unchanged public signatures and same-gesture rejection across Popover-family openings | A public type changes or a same-gesture request reaches visibility state. | `audit:Popover/api` |-| FR2, AR2–AR4 | `Popover.test.tsx` focus/role suites and `useFocusTrap.test.tsx` container-entry suites | Pointer, keyboard/AT-style, read-only, neutral role, no autofocus, controlled, Tab/Shift+Tab, Escape, focus return | Changing semantic destination by modality, selecting fallback close initially, losing shared indication, or allowing focus escape fails assertions. | `audit:Popover/accessibility` |-| ORD2, FR4 | `Popover.test.tsx` sizing/overflow suites; `Popover.stories.tsx` match-trigger and overflow scenarios; geometry under `Core/Layer` viewport-inset stories | Explicit width clamped to the viewport, trigger matching, fitting and overflowing content | Reversing width precedence, capping to the span beside the trigger, or always enabling scroll fails emitted-style or overflow assertions. | `audit:Popover/layout` |-| FR8 | `Popover.test.tsx` surface-padding suite | Default rung, `0`, an explicit rung, a direct hook composition with and without a rung | A default other than step 3, a rung landing on a box inside the surface, or the hook painting a rung it was not given fails the suite. | `audit:Popover/theming` |-| FR5 | `Popover.test.tsx` scheduling and observer-lifecycle suites | Closed, opened, repeated signals, cleanup | Constructing observers while closed or measuring more than once per pending frame fails lifecycle assertions. | `audit:Popover/resources` |-| FR6, FR7 and theming anatomy | `Popover.test.tsx`, `Popover.doc.mjs`, `usePopover.doc.mjs`, `astryx theme targets Popover --json`, and `scripts/check-knowledge.mjs` | One real surface with canonical `popover`; deprecated alias on that element; composed-component refinements | A fake anatomy part, loss of compatibility output, missing deprecation metadata, or an active target without a real owner fails review or validation. | `audit:Popover/theming` |-| AR5 | `Popover.stories.tsx` manual-AT fixture and PR #5373 test record | Read-only dialog manual-AT fixture; no recorded NVDA/VoiceOver announcement result | A fixture without recorded AT/browser observations cannot be cited as announcement proof. | `audit:Popover/at-evidence` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |+| Public boundary, FR1 | `Popover.test.tsx` compile-time public-surface assertions plus package/barrel inspection | Unchanged public signatures and same-gesture rejection across Popover-family openings | A public type changes or a same-gesture request reaches visibility state. | `audit:Popover/api` |+| FR2, AR2–AR4 | `Popover.test.tsx` focus/role suites and `useFocusTrap.test.tsx` container-entry suites | Pointer, keyboard/AT-style, read-only, neutral role, no autofocus, controlled, Tab/Shift+Tab, Escape, focus return | Changing semantic destination by modality, selecting fallback close initially, losing shared indication, or allowing focus escape fails assertions. | `audit:Popover/accessibility` |+| ORD2, FR4 | `Popover.test.tsx` sizing/overflow suites; `Popover.stories.tsx` match-trigger and overflow scenarios; geometry under `Core/Layer` viewport-inset stories | Explicit width clamped to the viewport, trigger matching, fitting and overflowing content | Reversing width precedence, capping to the span beside the trigger, or always enabling scroll fails emitted-style or overflow assertions. | `audit:Popover/layout` |+| FR8 | `Popover.test.tsx` surface-padding suite | Default rung, `0`, an explicit rung, a direct hook composition with and without a rung | A default other than step 3, a rung landing on a box inside the surface, or the hook painting a rung it was not given fails the suite. | `audit:Popover/theming` |+| FR5 | `Popover.test.tsx` scheduling and observer-lifecycle suites | Closed, opened, repeated signals, cleanup | Constructing observers while closed or measuring more than once per pending frame fails lifecycle assertions. | `audit:Popover/resources` |+| FR6, FR7 and theming anatomy | `Popover.test.tsx`, `Popover.doc.mjs`, `usePopover.doc.mjs`, `astryx theme targets Popover --json`, and `scripts/check-knowledge.mjs` | One real surface with canonical `popover` plus composed-component refinements | A fake anatomy part, missing canonical output, or an active target without a real owner fails review or validation. | `audit:Popover/theming` |+| AR5 | `Popover.stories.tsx` manual-AT fixture and PR #5373 test record | Read-only dialog manual-AT fixture; no recorded NVDA/VoiceOver announcement result | A fixture without recorded AT/browser observations cannot be cited as announcement proof. | `audit:Popover/at-evidence` |## Decision log@@ -379,16 +355,16 @@ focus indication, while Popover owns semantic focus placement.**Decider:** Cindy Zhang, 2026-08-31`popover` is the broad canonical theming baseline automatically owned by every-painted surface created by `<Popover>` or public `usePopover`.-`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`.+painted surface created by `<Popover>` or public `usePopover`. The temporary+`popover-surface` compatibility name is removed in 0.7.0 under+`architecture:component-theming-surface`; existing themes migrate that key and+selector to `popover`.Composed components keep authoritative refinement targets such as`selector-popup` and `multi-selector-popup`. Optional `surfaceTarget` adds thatowned refinement on the same surface; it does not replace the broad `popover`baseline. New direct hook consumers that need distinct reachability provide and-document an owned target rather than depending on `popover-surface`.+document an owned target.Rejected: treating `popover` and `popover-surface` as two durable sibling targets,or inventing a “Shared hook surface” anatomy part to satisfy inventory coverage.diff --git a/packages/core/src/Popover/Popover.test.tsx b/packages/core/src/Popover/Popover.test.tsxindex 0eef0b77ae..a0c4cdbe97 100644--- a/packages/core/src/Popover/Popover.test.tsx+++ b/packages/core/src/Popover/Popover.test.tsx@@ -85,7 +85,7 @@ describe('usePopover public return type', () => {expect(hasInternalFocusTarget).toBe(false);});- it('emits canonical and deprecated surface targets for direct hook consumers', () => {+ it('emits only the canonical surface target for direct hook consumers', () => {function HeadlessPopover() {const popover = usePopover({dialogLabel: 'Headless popover'});return (@@ -110,7 +110,7 @@ describe('usePopover public return type', () => {hidden: true,});expect(surface).toHaveClass('astryx-popover');- expect(surface).toHaveClass('astryx-popover-surface');+ expect(surface).not.toHaveClass('astryx-popover-surface');});});@@ -1061,7 +1061,8 @@ describe('Popover', () => {expect(target).not.toBeNull();// The surface paints background, radius and elevation; a target on the// content box inside it would style a box that paints nothing.- expect(target).toHaveClass('astryx-popover-surface');+ expect(target).toHaveClass('astryx-popover');+ expect(target).not.toHaveClass('astryx-popover-surface');expect(target).toHaveClass('consumer-popover');expect(target).toHaveStyle({padding: '0'});expect(target).toContainElement(screen.getByTestId('content'));diff --git a/packages/core/src/Popover/usePopover.doc.mjs b/packages/core/src/Popover/usePopover.doc.mjsindex 917b7f259a..2aa85bafaa 100644--- a/packages/core/src/Popover/usePopover.doc.mjs+++ b/packages/core/src/Popover/usePopover.doc.mjs@@ -103,7 +103,7 @@ export const docs = {name: 'surfaceTarget',type: 'string',description:- 'Optional component-owned refinement target on the painted surface, without the astryx- prefix. Use and document one when a direct hook composition needs distinct theme reachability. Do not use popover-surface; it is a deprecated compatibility alias of the canonical popover target.',+ 'Optional component-owned refinement target on the painted surface, without the astryx- prefix. Use and document one when a direct hook composition needs distinct theme reachability.',},],returns: [@@ -165,7 +165,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. 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.',+ '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. A custom composition needing a distinct stable seam should pass and document its own surfaceTarget.',bestPractices: [{guidance: true,@@ -179,8 +179,7 @@ export const docs = {},{guidance: true,- description:- 'Use popover as the broad surface target. Popover-surface remains supported compatibility output, but new theme source uses the canonical key.',+ description: 'Use popover as the broad canonical surface target.',},{guidance: true,@@ -203,7 +202,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. Every surface emits canonical popover plus deprecated popover-surface compatibility output. Custom compositions needing a distinct seam pass/document an owned surfaceTarget.',+ 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Every surface emits the canonical popover target. 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.',@@ -221,7 +220,7 @@ export const docsDense = {hasSurface: 'apply default surface background/radius/shadow.',padding: 'spacing-scale padding on the painted surface; omit for none.',surfaceTarget:- 'optional owned refinement target; document it and do not use deprecated popover-surface.',+ 'optional owned refinement target; document it when distinct reachability is needed.',},returnDescriptions: {triggerRef: 'trigger ref for CSS anchor positioning.',@@ -237,7 +236,7 @@ export const docsDense = {},usage: {description:- '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.',+ 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Every surface emits the canonical popover target. Custom compositions needing a distinct seam pass/document an owned surfaceTarget.',bestPractices: [{guidance: true,@@ -252,7 +251,7 @@ export const docsDense = {{guidance: true,description:- 'Use canonical popover for broad surface theming; deprecated popover-surface is compatibility output only.',+ 'Use the canonical popover target for broad surface theming.',},{guidance: true,diff --git a/packages/core/src/Popover/usePopover.tsx b/packages/core/src/Popover/usePopover.tsxindex f7cbb94cf3..83b09d458e 100644--- a/packages/core/src/Popover/usePopover.tsx+++ b/packages/core/src/Popover/usePopover.tsx@@ -258,9 +258,8 @@ 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 canonical `astryx-popover` target and deprecated- * `astryx-popover-surface` compatibility alias are always present alongside- * any component-owned refinement target.+ * The canonical `astryx-popover` target is always present alongside any+ * component-owned refinement target.*/surfaceTarget?: string;}@@ -505,9 +504,7 @@ 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', undefined, {- legacyNames: ['popover-surface'],- });+ const surfaceProps = themeProps('popover');const surfaceClassName =surfaceTarget != null && surfaceTarget !== 'popover'? `${surfaceProps.className} ${stableClassName(surfaceTarget)}`diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjsindex 1aa3e5a83d..3e3de808d7 100644--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs@@ -132,27 +132,6 @@ export const docs = {className: 'astryx-progress-bar-mark',visualProps: ['variant', 'placement'],},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {- className: 'astryx-progressbar',- visualProps: ['variant'],- deprecatedFor: 'progress-bar',- },- {- className: 'astryx-progressbar-fill',- visualProps: ['variant'],- deprecatedFor: 'progress-bar-fill',- },- {- className: 'astryx-progressbar-track',- deprecatedFor: 'progress-bar-track',- },- {- className: 'astryx-progressbar-mark',- visualProps: ['variant', 'placement'],- deprecatedFor: 'progress-bar-mark',- },],vars: [{@@ -297,27 +276,6 @@ export const docsZh = {className: 'astryx-progress-bar-mark',visualProps: ['variant', 'placement'],},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {- className: 'astryx-progressbar',- visualProps: ['variant'],- deprecatedFor: 'progress-bar',- },- {- className: 'astryx-progressbar-fill',- visualProps: ['variant'],- deprecatedFor: 'progress-bar-fill',- },- {- className: 'astryx-progressbar-track',- deprecatedFor: 'progress-bar-track',- },- {- className: 'astryx-progressbar-mark',- visualProps: ['variant', 'placement'],- deprecatedFor: 'progress-bar-mark',- },],vars: [{diff --git a/packages/core/src/ProgressBar/ProgressBar.spec.md b/packages/core/src/ProgressBar/ProgressBar.spec.mdindex 9196221698..391009c1b0 100644--- a/packages/core/src/ProgressBar/ProgressBar.spec.md+++ b/packages/core/src/ProgressBar/ProgressBar.spec.md@@ -40,17 +40,18 @@ from remaining progress without depending on visible text rendered elsewhere.External text may supplement the bar, but it is not a prerequisite for the barto be correct.-This draft now also records the current consumer anatomy and exact theming-ownership. It still does not choose a visual treatment or change runtime-behavior.+This record also captures the current consumer anatomy and exact theming+ownership. It does not choose a visual treatment; 0.7.0 only removes the four+deprecated `progressbar*` theming aliases.## Compatibility and migration-- Released default preserved: `yes`; this draft changes no runtime behavior.-- Compatibility class: additive documentation only; no public API, DOM, style,- target, or alias is added, removed, or changed.+- Released default preserved: `yes`; canonical ProgressBar behavior is unchanged.+- Removed aliases: 0.7.0 stops emitting `progressbar`, `progressbar-track`,+ `progressbar-fill`, and `progressbar-mark`.- Controlled/uncontrolled behavior: unchanged.-- Migration decision: `component:ProgressBar/DEC-1`.+- Migration decision: replace those theme keys and CSS target classes with their+ `progress-bar*` forms, or run `astryx upgrade --from 0.6.3 --apply --path .`.Consumer migration instructions belong in consumer docs and release notes.@@ -197,9 +198,8 @@ invent its form.```The `Label` and `Value text` gaps are current facts, not decisions that those-parts should remain untargeted. Deprecated `progressbar*` aliases are-compatibility metadata, not separate anatomy or current targets. This map does-not select a standalone visual treatment or resolve OQ1.+parts should remain untargeted. This map does not select a standalone visual+treatment or resolve OQ1.## Family and system relationships@@ -224,7 +224,7 @@ not select a standalone visual treatment or resolve OQ1.| FR1, AR1 | Real-browser visual and contrast evidence across shipped themes and color modes | Partial determinate progress for each semantic variant | A completed or remaining segment becomes indistinguishable without text | Future ProgressBar visual audit || FR2, FR3, AR3 | Public type and consumer-doc review | No value text, built-in value text, external composed text | A caller signal is credited with correctness the component cannot verify | Future ProgressBar API tests || AR2 | `ProgressBar.test.tsx` | Determinate, indeterminate, hidden label, custom value text | Accessible name or value semantics disappear when visuals change | Future ProgressBar accessibility audit |-| FR6 | `ProgressBar.test.tsx` and `themingTargets.test.ts` | Current and deprecated target classes | Source, metadata, or compatibility target placement drifts | `audit:ProgressBar/theming` |+| FR6 | `ProgressBar.test.tsx` and `themingTargets.test.ts` | Four canonical target classes | Canonical placement remains covered after the 0.7 alias removal | `audit:ProgressBar/theming` || Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and four current targets | Missing, extra, prefixed, stale, alias-backed, or unclaimed mappings fail | `audit:ProgressBar/theming` || Theming | Theme-target metadata checks plus browser evidence | Shipped themes, light and dark modes | A theme override bypasses the standalone distinction | Future ProgressBar theming audit |diff --git a/packages/core/src/ProgressBar/ProgressBar.test.tsx b/packages/core/src/ProgressBar/ProgressBar.test.tsxindex 3d62dfab32..f626295ba3 100644--- a/packages/core/src/ProgressBar/ProgressBar.test.tsx+++ b/packages/core/src/ProgressBar/ProgressBar.test.tsx@@ -266,7 +266,7 @@ describe('ProgressBar', () => {// Target marksdescribe('target marks', () => {- const MARK = '.astryx-progressbar-mark';+ const MARK = '.astryx-progress-bar-mark';// The StyleX atomic classes on an element, without the stable astryx-*// theme classes and the bare variant/placement tokens — so a comparison@@ -668,7 +668,7 @@ describe('ProgressBar', () => {const progressbar = screen.getByRole('progressbar');const fill = progressbar.firstElementChild as HTMLElement;expect(fill.style.width).toBe('50%');- expect(fill.classList.contains('astryx-progressbar-mark')).toBe(false);+ expect(fill.classList.contains('astryx-progress-bar-mark')).toBe(false);const mark = container.querySelector<HTMLElement>(MARK)!;expect(progressbar).not.toContainElement(mark);expect(container.querySelectorAll(MARK)).toHaveLength(1);@@ -757,7 +757,7 @@ describe('ProgressBar', () => {it('sizes the mark through the derived vars, so a theme override cannot lose the cascade', () => {// width/height are declared as `var(--_progressbar-mark-*)` and nothing// else declares those vars, so the value a theme sets on the- // `progressbar-mark` target lands even in a consumer whose StyleX is+ // `progress-bar-mark` target lands even in a consumer whose StyleX is// unlayered and would otherwise outrank `@layer astryx-theme`.const {container} = render(<ProgressBar@@ -794,9 +794,9 @@ describe('ProgressBar', () => {);});- it('renders the mark on the stable progressbar-mark target, centered for symmetric overhang', () => {+ it('renders the mark on the stable progress-bar-mark target, centered for symmetric overhang', () => {// The mark's width/height/color are directly overridable via the- // `progressbar-mark` theme target. It is centered+ // `progress-bar-mark` theme target. It is centered// on the track (translate -50%,-50%) so a themed taller tick overhangs the// bar symmetrically above and below without being clipped.const {container} = render(@@ -807,7 +807,7 @@ describe('ProgressBar', () => {/>,);const mark = container.querySelector<HTMLElement>(MARK)!;- expect(mark.className).toContain('astryx-progressbar-mark');+ expect(mark.className).toContain('astryx-progress-bar-mark');let css = '';for (const sheet of Array.from(document.styleSheets)) {try {@@ -829,7 +829,7 @@ describe('ProgressBar', () => {});describe('ProgressBar theme target names', () => {- it('renders the deprecated classes beside the current ones', () => {+ it('renders only the canonical target classes', () => {const {container} = render(<ProgressBarvalue={50}@@ -838,16 +838,20 @@ describe('ProgressBar theme target names', () => {/>,);expect(container.querySelector('.astryx-progress-bar')).toHaveClass(- 'astryx-progressbar',+ 'astryx-progress-bar',);expect(container.querySelector('.astryx-progress-bar-track')).toHaveClass(- 'astryx-progressbar-track',+ 'astryx-progress-bar-track',);expect(container.querySelector('.astryx-progress-bar-fill')).toHaveClass(- 'astryx-progressbar-fill',+ 'astryx-progress-bar-fill',);expect(container.querySelector('.astryx-progress-bar-mark')).toHaveClass(- 'astryx-progressbar-mark',+ 'astryx-progress-bar-mark',);+ expect(container.querySelector('.astryx-progressbar')).toBeNull();+ expect(container.querySelector('.astryx-progressbar-track')).toBeNull();+ expect(container.querySelector('.astryx-progressbar-fill')).toBeNull();+ expect(container.querySelector('.astryx-progressbar-mark')).toBeNull();});});diff --git a/packages/core/src/ProgressBar/ProgressBar.tsx b/packages/core/src/ProgressBar/ProgressBar.tsxindex a9368e0f74..7588994aa3 100644--- a/packages/core/src/ProgressBar/ProgressBar.tsx+++ b/packages/core/src/ProgressBar/ProgressBar.tsx@@ -396,7 +396,7 @@ function defaultFormatValueLabel(value: number, max: number): string {* ```** A mark's height, width, and color are directly themeable via the- * `progressbar-mark` target. The target reflects `data-placement`+ * `progress-bar-mark` target. The target reflects `data-placement`* (`"fill"` when the mark sits inside the filled area, `"track"` when it is* still out on the bare track) and `data-variant` (the fill's variant), so a* theme can style the two cases separately — e.g. a taller "goal flag" tick@@ -407,7 +407,7 @@ function defaultFormatValueLabel(value: number, max: number): string {* defineTheme({* name: 'campaign',* components: {- * 'progressbar-mark': {base: {height: '16px', backgroundColor: 'red'}},+ * 'progress-bar-mark': {base: {height: '16px', backgroundColor: 'red'}},* },* });* ```@@ -475,13 +475,7 @@ export function ProgressBar({<divref={ref}{...mergeProps(- themeProps(- 'progress-bar',- {variant},- // `progressbar` ran the compound name together; keep it emitted so- // existing themes continue to work.- {legacyNames: ['progressbar']},- ),+ themeProps('progress-bar', {variant}),stylex.props(styles.container, xstyle),className,style,@@ -523,19 +517,13 @@ export function ProgressBar({aria-labelledby={labelId}aria-valuetext={isIndeterminate ? undefined : valueText}{...mergeProps(- themeProps('progress-bar-track', undefined, {- legacyNames: ['progressbar-track'],- }),+ themeProps('progress-bar-track'),stylex.props(styles.track, isIndeterminate && styles.trackClipped),)}>{isIndeterminate ? (<div{...mergeProps(- themeProps(- 'progress-bar-fill',- {variant: fillVariant},- {legacyNames: ['progressbar-fill']},- ),+ themeProps('progress-bar-fill', {variant: fillVariant}),stylex.props(styles.indeterminateFill,variantStyles[fillVariant],@@ -545,11 +533,7 @@ export function ProgressBar({) : (<div{...mergeProps(- themeProps(- 'progress-bar-fill',- {variant: fillVariant},- {legacyNames: ['progressbar-fill']},- ),+ themeProps('progress-bar-fill', {variant: fillVariant}),stylex.props(styles.fill, variantStyles[fillVariant]),)}style={{width: `${percentage}%`}}@@ -566,20 +550,16 @@ export function ProgressBar({//// `placement` is reflected as `data-placement` (and a class) so a// theme can style the two cases separately on the- // `progressbar-mark` target; `variant` mirrors the fill's variant+ // `progress-bar-mark` target; `variant` mirrors the fill's variant// for the same reason.const markEl = (<spantabIndex={0}{...mergeProps(- themeProps(- 'progress-bar-mark',- {- variant: fillVariant,- placement: mark.isOnFill ? 'fill' : 'track',- },- {legacyNames: ['progressbar-mark']},- ),+ themeProps('progress-bar-mark', {+ variant: fillVariant,+ placement: mark.isOnFill ? 'fill' : 'track',+ }),stylex.props(focusOutlineStyles.focusVisible,styles.mark,diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjsindex b34cc6295a..dc5cb57e1a 100644--- a/packages/core/src/RadioList/RadioList.doc.mjs+++ b/packages/core/src/RadioList/RadioList.doc.mjs@@ -7,23 +7,39 @@ export const docs = {displayName: 'Radio List',group: 'Radio',category: 'Form Controls',- keywords: ["radiolist","radio","radiogroup","radiobutton","optionlist","singlechoice","choicelist"],+ keywords: [+ 'radiolist',+ 'radio',+ 'radiogroup',+ 'radiobutton',+ 'optionlist',+ 'singlechoice',+ 'choicelist',+ ],theming: {targets: [{className: 'astryx-radio-list', visualProps: ['orientation', 'size']},- {className: 'astryx-radio-list-item', visualProps: ['size'], states: ['selected', 'disabled']},- {className: 'astryx-radio-indicator', visualProps: ['size'], states: ['checked', 'disabled']},+ {+ className: 'astryx-radio-list-item',+ visualProps: ['size'],+ states: ['selected', 'disabled'],+ },+ {+ className: 'astryx-radio-indicator',+ visualProps: ['size'],+ states: ['checked', 'disabled'],+ },{className: 'astryx-radio-indicator-dot', visualProps: ['size']},- {className: 'astryx-radio', visualProps: ['size'], states: ['checked', 'disabled'], deprecatedFor: 'radio-indicator'},- {className: 'astryx-radio-dot', visualProps: ['size'], deprecatedFor: 'radio-indicator-dot'},],},- description: 'Radio group container with field integration for label, description, and status.',+ description:+ 'Radio group container with field integration for label, description, and status.',props: [{name: 'label',type: 'string',- description: 'Label text for the radio group (always rendered for accessibility).',+ description:+ 'Label text for the radio group (always rendered for accessibility).',required: true,},{@@ -97,7 +113,8 @@ export const docs = {{name: 'isOptional',type: 'boolean',- description: 'Whether the field is optional (mutually exclusive with isRequired).',+ description:+ 'Whether the field is optional (mutually exclusive with isRequired).',default: 'false',},{@@ -125,12 +142,11 @@ export const docs = {{name: 'xstyle',type: 'StyleXStyles',- description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',+ description:+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',},],- components: [- {name: 'RadioListItem'},- ],+ components: [{name: 'RadioListItem'}],usage: {accessibility: [{@@ -146,18 +162,58 @@ export const docs = {description:'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',bestPractices: [- { guidance: true, description: 'Keep the number of options small: typically 2 to 7 choices.' },- { guidance: true, description: 'Use clear, concise labels that differentiate each option at a glance.' },- { guidance: true, description: "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional." },- { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },- { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },- { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },- { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ 'Keep the number of options small: typically 2 to 7 choices.',+ },+ {+ guidance: true,+ description:+ 'Use clear, concise labels that differentiate each option at a glance.',+ },+ {+ guidance: true,+ description:+ "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional.",+ },+ {+ guidance: false,+ description:+ 'Use when multiple selections are needed; use CheckboxList instead.',+ },+ {+ guidance: false,+ description:+ 'Use for long lists; use Selector for better discoverability.',+ },+ {+ guidance: false,+ description:+ 'Use horizontal layout with more than 4 options; it wraps awkwardly.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- {name: 'Header', required: false, description: 'Optional heading above the radio list.'},- {name: 'Children', required: true, description: 'The radio list items rendered as selectable options.'},- {name: 'Label/Value', required: true, description: 'The text label and associated value for each radio item.'},+ {+ name: 'Header',+ required: false,+ description: 'Optional heading above the radio list.',+ },+ {+ name: 'Children',+ required: true,+ description: 'The radio list items rendered as selectable options.',+ },+ {+ name: 'Label/Value',+ required: true,+ description: 'The text label and associated value for each radio item.',+ },],},};@@ -168,18 +224,58 @@ export const docsZh = {description:'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',bestPractices: [- { guidance: true, description: 'Keep the number of options small: typically 2 to 7 choices.' },- { guidance: true, description: 'Use clear, concise labels that differentiate each option at a glance.' },- { guidance: true, description: "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional." },- { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },- { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },- { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },- { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ 'Keep the number of options small: typically 2 to 7 choices.',+ },+ {+ guidance: true,+ description:+ 'Use clear, concise labels that differentiate each option at a glance.',+ },+ {+ guidance: true,+ description:+ "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional.",+ },+ {+ guidance: false,+ description:+ 'Use when multiple selections are needed; use CheckboxList instead.',+ },+ {+ guidance: false,+ description:+ 'Use for long lists; use Selector for better discoverability.',+ },+ {+ guidance: false,+ description:+ 'Use horizontal layout with more than 4 options; it wraps awkwardly.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- {name: 'Header', required: false, description: 'Optional heading above the radio list.'},- {name: 'Children', required: true, description: 'The radio list items rendered as selectable options.'},- {name: 'Label/Value', required: true, description: 'The text label and associated value for each radio item.'},+ {+ name: 'Header',+ required: false,+ description: 'Optional heading above the radio list.',+ },+ {+ name: 'Children',+ required: true,+ description: 'The radio list items rendered as selectable options.',+ },+ {+ name: 'Label/Value',+ required: true,+ description: 'The text label and associated value for each radio item.',+ },],},};@@ -192,18 +288,58 @@ export const docsDense = {description:'A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.',bestPractices: [- { guidance: true, description: 'Keep the number of options small: typically 2 to 7 choices.' },- { guidance: true, description: 'Use clear, concise labels that differentiate each option at a glance.' },- { guidance: true, description: "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional." },- { guidance: false, description: 'Use when multiple selections are needed; use CheckboxList instead.' },- { guidance: false, description: 'Use for long lists; use Selector for better discoverability.' },- { guidance: false, description: 'Use horizontal layout with more than 4 options; it wraps awkwardly.' },- { guidance: false, description: 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.' },+ {+ guidance: true,+ description:+ 'Keep the number of options small: typically 2 to 7 choices.',+ },+ {+ guidance: true,+ description:+ 'Use clear, concise labels that differentiate each option at a glance.',+ },+ {+ guidance: true,+ description:+ "Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional.",+ },+ {+ guidance: false,+ description:+ 'Use when multiple selections are needed; use CheckboxList instead.',+ },+ {+ guidance: false,+ description:+ 'Use for long lists; use Selector for better discoverability.',+ },+ {+ guidance: false,+ description:+ 'Use horizontal layout with more than 4 options; it wraps awkwardly.',+ },+ {+ guidance: false,+ description:+ 'Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',+ },],anatomy: [- {name: 'Header', required: false, description: 'Optional heading above the radio list.'},- {name: 'Children', required: true, description: 'The radio list items rendered as selectable options.'},- {name: 'Label/Value', required: true, description: 'The text label and associated value for each radio item.'},+ {+ name: 'Header',+ required: false,+ description: 'Optional heading above the radio list.',+ },+ {+ name: 'Children',+ required: true,+ description: 'The radio list items rendered as selectable options.',+ },+ {+ name: 'Label/Value',+ required: true,+ description: 'The text label and associated value for each radio item.',+ },],},};diff --git a/packages/core/src/RadioList/RadioListItem.tsx b/packages/core/src/RadioList/RadioListItem.tsxindex 34e7d91128..406d71e7ac 100644--- a/packages/core/src/RadioList/RadioListItem.tsx+++ b/packages/core/src/RadioList/RadioListItem.tsx@@ -265,7 +265,8 @@ export function RadioListItem({const hasDescription = isRenderable(description);const size = context.size;// The radio visual is an indicator: a theme can restyle it through the- // `radio` / `radio-dot` targets or replace the component outright.+ // `radio-indicator` / `radio-indicator-dot` targets or replace the component+ // outright.const RadioControl = useIndicator('radio');// See CheckboxInput: the ring goes on the indicator's own element, because// the native input is visually hidden and only the indicator knows its shape.diff --git a/packages/core/src/ScrollableArea/ScrollableArea.test.tsx b/packages/core/src/ScrollableArea/ScrollableArea.test.tsxindex 82b7e543e9..e3e0f75c8a 100644--- a/packages/core/src/ScrollableArea/ScrollableArea.test.tsx+++ b/packages/core/src/ScrollableArea/ScrollableArea.test.tsx@@ -155,7 +155,7 @@ describe('ScrollableArea', () => {);const viewport = screen.getByTestId('viewport');const content = viewport.firstElementChild as HTMLElement;- const inlineViewportClass = viewport.className;+ expect(viewport).toHaveAttribute('data-axis', 'inline');expect(viewport.style.overflowInline).toBe('');expect(viewport.style.overflowBlock).toBe('');const inlineContentClass = content.className;@@ -167,7 +167,7 @@ describe('ScrollableArea', () => {Timeline</ScrollableArea>,);- expect(viewport.className).not.toBe(inlineViewportClass);+ expect(viewport).toHaveAttribute('data-axis', 'block');expect(viewport.style.overflowInline).toBe('');expect(viewport.style.overflowBlock).toBe('');expect(content.className).not.toBe(inlineContentClass);diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjsindex 64c02c3173..dae7b0889c 100644--- a/packages/core/src/Selector/Selector.doc.mjs+++ b/packages/core/src/Selector/Selector.doc.mjs@@ -157,10 +157,6 @@ export const docs = {{className: 'astryx-selector-search'},{className: 'astryx-selector-section-heading'},{className: 'astryx-selector-empty-state'},- {- className: 'astryx-selector-clear-icon',- deprecatedFor: 'input-clear-icon',- },{className: 'astryx-selector-indicator-icon', states: ['state']},{className: 'astryx-selector-check'},{className: 'astryx-selector-popup'},diff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.mdindex 7a0fc511ad..04a1e9cd19 100644--- a/packages/core/src/Selector/Selector.spec.md+++ b/packages/core/src/Selector/Selector.spec.md@@ -61,6 +61,11 @@ connection between the closed trigger and its selection surface.value, focus, and form participation while removing selection-surface andediting affordances. `isDisabled` takes precedence when both are set.- `spec:AST-004/DEC-1` governs the state-derived indicator-space behavior in FR3.+- 0.7.0 removes the `selector-clear-icon` alias; the shared clear glyph remains+ available through `input-clear-icon`.+- Migration decision: replace the removed theme key and CSS class with+ `input-clear-icon` and `.astryx-input-clear-icon`, or run+ `astryx upgrade --from 0.6.3 --apply --path .`.### DEP-0011 — Deprecate the `popover` default presentation@@ -289,8 +294,7 @@ Icon-rendered start content delegates to Icon; arbitrary `ReactNode` start conteis caller-owned. The default renderer and custom `renderOption` functions thatreturn `SelectorOption` retain its target; only bare caller-rendered optioncontent stays outside that target, while the targeted option row remains.-`selector-clear-icon` remains a deprecated compatibility alias and does not own a-current anatomy row.+`input-clear-icon` is the shared canonical target for the clear glyph.This map records only shipped reachability. It does not treat the accepted,unimplemented option-source behavior in `spec:AST-001` as current runtime behavior.diff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsxindex ea7faf5d88..41c29fd626 100644--- a/packages/core/src/Selector/Selector.test.tsx+++ b/packages/core/src/Selector/Selector.test.tsx@@ -423,12 +423,12 @@ describe('Selector', () => {// Every row has a radio, selected or not.for (const option of options) {- expect(option.querySelector('.astryx-radio')).not.toBeNull();+ expect(option.querySelector('.astryx-radio-indicator')).not.toBeNull();}// And exactly the selected one is filled.const filled = options.filter(- o => o.querySelector('.astryx-radio-dot') != null,+ o => o.querySelector('.astryx-radio-indicator-dot') != null,);expect(filled).toHaveLength(1);expect(filled[0]).toHaveTextContent('Banana');@@ -3136,7 +3136,7 @@ describe('Selector clear icon theme target', () => {return icon as HTMLElement;};- it('renders the astryx-input-clear-icon target (plus the legacy alias) on the clear glyph', () => {+ it('renders only the astryx-input-clear-icon target on the clear glyph', () => {render(<Selectorlabel="Fruit"@@ -3149,11 +3149,10 @@ 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 remains as a compatibility- // alias.+ // color/size.const icon = getClearIcon();expect(icon).toHaveClass('astryx-input-clear-icon');- expect(icon).toHaveClass('astryx-selector-clear-icon');+ expect(icon).not.toHaveClass('astryx-selector-clear-icon');expect(icon).toHaveClass('astryx-icon');});@@ -3174,13 +3173,12 @@ describe('Selector clear icon theme target', () => {expect(onChange).toHaveBeenCalledWith(null);});- 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 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.+ it('routes the clear glyph through the shared clear button', () => {+ // The clear affordance composes the shared InputClearButton (a ghost Button+ // with a secondary/sm glyph), so the icon carries the canonical+ // `astryx-input-clear-icon` target. Aside from that target class it matches+ // the shared button's own `close`/`sm`/`secondary` glyph exactly, so the+ // default look is defined in one place.render(<Selectorlabel="Fruit"@@ -3192,7 +3190,7 @@ describe('Selector clear icon theme target', () => {);const icon = getClearIcon();expect(icon).toHaveClass('astryx-input-clear-icon');- expect(icon).toHaveClass('astryx-selector-clear-icon');+ expect(icon).not.toHaveClass('astryx-selector-clear-icon');const {container: refContainer} = render(<Icon icon="close" size="sm" color="secondary" />,@@ -3202,26 +3200,22 @@ describe('Selector clear icon theme target', () => {const styleClasses = (el: HTMLElement) =>el.className.split(' ')- .filter(- c =>- c !== 'astryx-input-clear-icon' &&- c !== 'astryx-selector-clear-icon',- )+ .filter(c => c !== 'astryx-input-clear-icon').sort();expect(styleClasses(icon)).toEqual(styleClasses(refIcon));});- it('exposes selector-clear-icon so a theme reaches the icon color, size, and hover', () => {+ it('uses input-clear-icon so a theme reaches the icon color, size, and hover', () => {// jsdom cannot resolve the @layer cascade, so the DOM-class assertion above// (target lands on the icon element) plus this generation assertion (the// theme emits same-element icon rules in @layer astryx-theme) together// prove the seam: a same-element theme rule wins over the icon's own// base-layer color/size.const theme = defineTheme({- name: 'selector-clear-icon-test',+ name: 'selector-shared-clear-icon-test',components: {- 'selector-clear-icon': {+ 'input-clear-icon': {base: {width: '12px',height: '12px',@@ -3233,10 +3227,10 @@ describe('Selector clear icon theme target', () => {},});const css = generateThemeTestCSS(theme);- expect(css).toContain('.astryx-selector-clear-icon {');+ expect(css).toContain('.astryx-input-clear-icon {');expect(css).toContain('width: 12px');expect(css).toContain('height: 12px');- expect(css).toContain('.astryx-selector-clear-icon:hover');+ expect(css).toContain('.astryx-input-clear-icon:hover');expect(css).toContain('color: var(--color-icon-primary)');});});@@ -3898,7 +3892,7 @@ describe('Selector indicatorPosition', () => {indicatorPosition === 'start'? row.firstElementChild: row.lastElementChild;- const radio = row.querySelector('.astryx-radio');+ const radio = row.querySelector('.astryx-radio-indicator');const content = row.querySelector('.astryx-selector-option');expect(markColumn).toHaveStyle({display: 'inline-flex'});expect(radio).not.toBeNull();@@ -3945,7 +3939,7 @@ describe('Selector popup theme target', () => {const popup = document.querySelector('.astryx-selector-popup');expect(popup).not.toBeNull();- expect(popup).toHaveClass('astryx-popover-surface');+ expect(popup).toHaveClass('astryx-popover');expect(popup?.querySelector('[role="listbox"]')).not.toBeNull();},);diff --git a/packages/core/src/Selector/Selector.tsx b/packages/core/src/Selector/Selector.tsxindex 147fda18f4..3583931513 100644--- a/packages/core/src/Selector/Selector.tsx+++ b/packages/core/src/Selector/Selector.tsx@@ -87,7 +87,6 @@ import {themeProps} from '../utils/themeProps';import {focusOutlineStyles} from '../utils/focusOutline.stylex';import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';import {usePressFeedback} from '../hooks/usePressFeedback';-import {stableClassName} from '../naming';import {groupStyles} from '../InputGroup/groupStyles';import {useInputGroup} from '../InputGroup/InputGroupContext';import {VisuallyHidden} from '../VisuallyHidden';@@ -1917,7 +1916,6 @@ export function Selector<T extends SelectorOptionType>({...keepOpenProps}label={t('@astryx.selector.clearLabel', {label})}onClick={handleClear}- iconClassName={stableClassName('selector-clear-icon')}/>)}{/*diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjsindex efa5f0edc9..f609513b84 100644--- a/packages/core/src/StatusDot/StatusDot.doc.mjs+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs@@ -5,7 +5,8 @@ const anatomy = [{name: 'Dot',required: true,- description: 'Painted status dot that carries the selected semantic variant.',+ description:+ 'Painted status dot that carries the selected semantic variant.',},{name: 'Status icon',@@ -20,7 +21,17 @@ export const docs = {name: 'StatusDot',displayName: 'Status Dot',category: 'Feedback & Status',- keywords: ["statusdot","dot","indicator","status","signal","presence","availability","online","pip"],+ keywords: [+ 'statusdot',+ 'dot',+ 'indicator',+ 'status',+ 'signal',+ 'presence',+ 'availability',+ 'online',+ 'pip',+ ],props: [{name: 'variant',@@ -44,14 +55,13 @@ export const docs = {{name: 'tooltip',type: 'string',- description:- 'Tooltip text shown on hover to explain the status meaning.',+ description: 'Tooltip text shown on hover to explain the status meaning.',},{name: 'icon',type: 'ReactNode',description:- 'Optional icon rendered centered inside the dot, painted in currentColor (the variant\'s ink). Gives the status a non-color mark, so use a different icon per status. Booleans and empty strings are ignored, so `cond && <Icon />` is safe. Same contract as AvatarStatusDot.',+ "Optional icon rendered centered inside the dot, painted in currentColor (the variant's ink). Gives the status a non-color mark, so use a different icon per status. Booleans and empty strings are ignored, so `cond && <Icon />` is safe. Same contract as AvatarStatusDot.",},{name: 'xstyle',@@ -61,25 +71,48 @@ export const docs = {},],theming: {- targets: [- {className: 'astryx-status-dot', visualProps: ['variant']},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {className: 'astryx-statusdot', visualProps: ['variant'], deprecatedFor: 'status-dot'},- ],+ targets: [{className: 'astryx-status-dot', visualProps: ['variant']}],},usage: {anatomy,description:'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',bestPractices: [- { guidance: true, description: 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.' },- { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },- { guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },- { guidance: true, description: 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.' },- { guidance: true, description: 'If you can\'t add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).' },- { guidance: false, description: 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.' },- { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },+ {+ guidance: true,+ description:+ 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.',+ },+ {+ guidance: true,+ description:+ 'Always pair with a visible text label so status is not conveyed by color alone.',+ },+ {+ guidance: true,+ description:+ 'Provide a descriptive `label` prop for screen reader accessibility.',+ },+ {+ guidance: true,+ description:+ 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.',+ },+ {+ guidance: true,+ description:+ "If you can't add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).",+ },+ {+ guidance: false,+ description:+ 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.',+ },+ {+ guidance: false,+ description:+ 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.',+ },],},};@@ -104,8 +137,7 @@ export const docsZh = {{name: 'isPulsing',type: 'boolean',- description:- '启用脉冲动画;尊重 prefers-reduced-motion: reduce 设置。',+ description: '启用脉冲动画;尊重 prefers-reduced-motion: reduce 设置。',default: 'false',},{@@ -122,44 +154,96 @@ export const docsZh = {},],theming: {- targets: [- {className: 'astryx-status-dot', visualProps: ['variant']},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {className: 'astryx-statusdot', visualProps: ['variant'], deprecatedFor: 'status-dot'},- ],+ targets: [{className: 'astryx-status-dot', visualProps: ['variant']}],},usage: {anatomy,description:'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',bestPractices: [- { guidance: true, description: 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.' },- { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },- { guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },- { guidance: true, description: 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.' },- { guidance: true, description: 'If you can\'t add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).' },- { guidance: false, description: 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.' },- { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },+ {+ guidance: true,+ description:+ 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.',+ },+ {+ guidance: true,+ description:+ 'Always pair with a visible text label so status is not conveyed by color alone.',+ },+ {+ guidance: true,+ description:+ 'Provide a descriptive `label` prop for screen reader accessibility.',+ },+ {+ guidance: true,+ description:+ 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.',+ },+ {+ guidance: true,+ description:+ "If you can't add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).",+ },+ {+ guidance: false,+ description:+ 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.',+ },+ {+ guidance: false,+ description:+ 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.',+ },],},};/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */export const docsDense = {- description: 'Small colored dot indicator for status display (online/offline, severity, etc).',+ description:+ 'Small colored dot indicator for status display (online/offline, severity, etc).',usage: {anatomy,description:'A small colored dot that communicates status like online/offline presence or severity levels. Supports five semantic variants and an optional pulse animation. Always pair with a visible text label, as color alone should not carry meaning.',bestPractices: [- { guidance: true, description: 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.' },- { guidance: true, description: 'Always pair with a visible text label so status is not conveyed by color alone.' },- { guidance: true, description: 'Provide a descriptive `label` prop for screen reader accessibility.' },- { guidance: true, description: 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.' },- { guidance: true, description: 'If you can\'t add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).' },- { guidance: false, description: 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.' },- { guidance: false, description: 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.' },+ {+ guidance: true,+ description:+ 'Use StatusDot as a binary present/absent signal; avoid encoding many distinct states in a single dot, since color and size alone cannot reliably distinguish them.',+ },+ {+ guidance: true,+ description:+ 'Always pair with a visible text label so status is not conveyed by color alone.',+ },+ {+ guidance: true,+ description:+ 'Provide a descriptive `label` prop for screen reader accessibility.',+ },+ {+ guidance: true,+ description:+ 'Pair the dot with an icon that carries the status as a distinct shape when it must stand on its own without adjacent text, so meaning survives without color.',+ },+ {+ guidance: true,+ description:+ "If you can't add a label or an icon, make sure the status is conveyed elsewhere accessibly (e.g. adjacent text, a table column, or a live region).",+ },+ {+ guidance: false,+ description:+ 'Rely on color alone to communicate status; StatusDot is not fully accessible in isolation, so the builder must make the status distinguishable in context via a label, an icon, or an accessible alternative.',+ },+ {+ guidance: false,+ description:+ 'Use the pulse animation for purely decorative purposes; reserve it for states that require immediate attention.',+ },],},propDescriptions: {@@ -170,4 +254,4 @@ export const docsDense = {icon: 'Optional ReactNode rendered centered in the dot (currentColor ink); a non-color mark for the status, use a different icon per status. Booleans/empty strings ignored (safe for cond && <Icon/>). Same contract as AvatarStatusDot.',xstyle: 'StyleX layout styles; must be stylex.create() value.',},-};\ No newline at end of file+};diff --git a/packages/core/src/StatusDot/StatusDot.spec.md b/packages/core/src/StatusDot/StatusDot.spec.mdindex 970a7b9a04..b47991741e 100644--- a/packages/core/src/StatusDot/StatusDot.spec.md+++ b/packages/core/src/StatusDot/StatusDot.spec.md@@ -25,16 +25,17 @@ system_specs: []## IntentStatusDot renders a compact painted status signal with an optional status icon.-This draft records the current consumer anatomy and theming ownership without-changing runtime behavior, target compatibility, or public API.+This record preserves that runtime behavior while 0.7.0 removes the deprecated+`statusdot` theming alias.## Compatibility and migration-- Released default preserved: `yes`-- Compatibility class: additive documentation only; runtime, DOM, styling,- targets, aliases, and public API remain unchanged+- Released default preserved: `yes`; canonical `status-dot` behavior is unchanged+- Removed alias: 0.7.0 stops emitting `statusdot`- Controlled/uncontrolled behavior: not applicable-- Migration decision: none+- Migration decision: replace `statusdot` theme keys and `.astryx-statusdot`+ selectors with `status-dot` and `.astryx-status-dot`, or run+ `astryx upgrade --from 0.6.3 --apply --path .`Consumer migration instructions belong in consumer docs and release notes.@@ -59,11 +60,11 @@ in `StatusDot.doc.mjs`.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------- | -------------------------------------------------- |-| FR1 | The current render always contains one painted dot carrying the `status-dot` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |-| FR2 | When renderable icon content is supplied, it appears in an assistive-technology-hidden wrapper inside the dot. | Current source and tests | Verified current behavior; no new behavior decided |-| FR3 | The deprecated `statusdot` class remains emitted beside `status-dot` for compatibility but is not current anatomy. | Current source, docs, and tests | Verified current behavior; no target change |+| ID | Candidate invariant | Basis | Draft review state |+| --- | -------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |+| FR1 | The current render always contains one painted dot carrying the `status-dot` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| FR2 | When renderable icon content is supplied, it appears in an assistive-technology-hidden wrapper inside the dot. | Current source and tests | Verified current behavior; no new behavior decided |+| FR3 | The painted dot emits only the canonical `status-dot` target. | Current source, docs, and tests | Verified canonical behavior; 0.7 alias removed |### Allowed variation@@ -96,9 +97,6 @@ reduced-motion, or decorative-icon behavior.| Dot | Presents the current painted semantic-status signal. | Current source and public docs | Supporting | FR1, FR3 || Status icon | Presents optional caller-supplied artwork inside the dot. | Current source and tests | Supporting | FR2 |-The deprecated `statusdot` alias is compatibility metadata, not a separate-anatomy part or current target.-### Theming anatomy<!-- anatomy-theming:v1 -->@@ -113,15 +111,15 @@ anatomy part or current target.## Family and system relationships- `architecture:component-theming-surface` owns anatomy qualification,- inheritance, and deprecated-alias exclusion.+ inheritance, and canonical target naming.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | -------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------- |-| FR1, FR2 | `StatusDot.test.tsx` render and custom-icon suites | Plain dot and dot with supplied icon | Removing the dot or changing optional icon rendering fails existing DOM assertions. | `audit:StatusDot/anatomy` |-| FR3 | `StatusDot.test.tsx` theme-target-name suite | Current and deprecated target classes | Removing either emitted compatibility class fails the existing target assertion. | `audit:StatusDot/theming` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:StatusDot/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | -------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------- | ------------------------- |+| FR1, FR2 | `StatusDot.test.tsx` render and custom-icon suites | Plain dot and dot with supplied icon | Removing the dot or changing optional icon rendering fails existing DOM assertions. | `audit:StatusDot/anatomy` |+| FR3 | `StatusDot.test.tsx` theme-target-name suite | Canonical target class | Missing or renamed canonical target fails the target assertion. | `audit:StatusDot/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:StatusDot/theming` |## Decision logdiff --git a/packages/core/src/StatusDot/StatusDot.test.tsx b/packages/core/src/StatusDot/StatusDot.test.tsxindex 4eabfbdb97..3a9f7767f5 100644--- a/packages/core/src/StatusDot/StatusDot.test.tsx+++ b/packages/core/src/StatusDot/StatusDot.test.tsx@@ -191,10 +191,10 @@ describe('StatusDot', () => {});describe('StatusDot theme target names', () => {- it('renders the deprecated class beside the current one', () => {+ it('renders only the canonical target class', () => {render(<StatusDot variant="success" label="Online" />);const dot = screen.getByRole('img', {name: 'Online'});expect(dot).toHaveClass('astryx-status-dot');- expect(dot).toHaveClass('astryx-statusdot');+ expect(dot).not.toHaveClass('astryx-statusdot');});});diff --git a/packages/core/src/StatusDot/StatusDot.tsx b/packages/core/src/StatusDot/StatusDot.tsxindex 793c8b4a4b..eae1b0af7d 100644--- a/packages/core/src/StatusDot/StatusDot.tsx+++ b/packages/core/src/StatusDot/StatusDot.tsx@@ -200,13 +200,7 @@ export function StatusDot({role="img"aria-label={label}{...mergeProps(- themeProps(- 'status-dot',- {variant},- // `statusdot` ran the compound name together; keep it emitted so- // existing themes continue to work.- {legacyNames: ['statusdot']},- ),+ themeProps('status-dot', {variant}),stylex.props(styles.base,variants[variant],diff --git a/packages/core/src/Table/BaseTable.tsx b/packages/core/src/Table/BaseTable.tsxindex fa4153ad2f..92ce3b827c 100644--- a/packages/core/src/Table/BaseTable.tsx+++ b/packages/core/src/Table/BaseTable.tsx@@ -536,12 +536,7 @@ function BaseTableInner<T extends Record<string, unknown>>({{...(ariaRowCount != null ? {'aria-rowcount': ariaRowCount} : null)}{...tableRenderProps.htmlProps}{...mergeProps(- themeProps('table', undefined, {- // `base-table` was a second root on the same <table> element that- // `table` names; themes styling it keep working until the next- // major.- legacyNames: ['base-table'],- }),+ themeProps('table'),stylex.props(...tableRenderProps.xstyle, xstyle),[tableRenderProps.htmlProps.className, className].filter(Boolean)diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjsindex 966817700c..62540e0d10 100644--- a/packages/core/src/Table/Table.doc.mjs+++ b/packages/core/src/Table/Table.doc.mjs@@ -142,9 +142,6 @@ export const docs = {{className: 'astryx-table-row'},{className: 'astryx-table-cell', visualProps: ['density']},{className: 'astryx-table-header-cell', visualProps: ['density']},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {className: 'astryx-base-table', deprecatedFor: 'table'},],},description:diff --git a/packages/core/src/Table/Table.spec.md b/packages/core/src/Table/Table.spec.mdindex c5c7239e01..2c34356a67 100644--- a/packages/core/src/Table/Table.spec.md+++ b/packages/core/src/Table/Table.spec.md@@ -56,10 +56,13 @@ generated anatomy, accessibility, migration, and evidence belong to each listedthan collapsing toward zero. A column overrides that floor with`proportional(value, {minWidth})`. When those floors no longer fit, the existing Table Scrollregion overflows horizontally. Explicit pixel and proportional widths are unchanged.-- Compatibility class: standards-conformance bug fix; no public prop, target, alias,- semantic Table element, or Scroll-region behavior changes.+- Compatibility class: standards-conformance bug fix; no public prop, semantic+ Table element, or Scroll-region behavior changes. 0.7.0 removes the deprecated+ `base-table` target alias while preserving `table`.- Controlled/uncontrolled behavior: unchanged-- Migration decision: `spec:AST-025` FR12, FR14, FR19, FR21, and DEC-1+- Migration decision: `spec:AST-025` FR12, FR14, FR19, FR21, and DEC-1; replace+ `base-table` theme keys and `.astryx-base-table` selectors with `table` and+ `.astryx-table`, or run `astryx upgrade --from 0.6.3 --apply --path .`Consumer migration instructions belong in consumer docs and release notes.@@ -284,17 +287,16 @@ by its transforms; the shared pipeline does not confer correctness on module out}```-The exact map records all eight current non-deprecated Table targets once. The-legacy `base-table` alias is compatibility, not anatomy. TableHeader, TableBody,-TableFooter, TableRow, TableCell, and TableHeaderCell retain direct docs linked by-`subComponentOf: 'Table'`; they do not need independent component specs for this-aggregate ownership.+The exact map records all eight canonical Table targets once. TableHeader,+TableBody, TableFooter, TableRow, TableCell, and TableHeaderCell retain direct docs+linked by `subComponentOf: 'Table'`; they do not need independent component specs+for this aggregate ownership.## Family and system relationships- `architecture:component-theming-surface` owns anatomy qualification, exacttarget mapping, delegation, inheritance, factual `none` classifications, and- the rule that deprecated aliases do not count as anatomy.+ canonical target naming.- `architecture:container-padding` owns the inherited inset protocol consumed bythe Scroll region and Cell edge compensation. This container-systemparticipation does not make Table a structural member of@@ -322,7 +324,7 @@ aggregate ownership.| FR12, PR1 | `Table.perf.test.tsx` plus `useBaseTablePlugins.ts` source inspection | Same plugin references, recreated record, and changed plugin value | Unchanged plugin values must preserve the resolved array and representative no-op row-update budgets; focused named-record identity coverage remains partial. | `audit:Table/performance` || FR13, PR3 | `Table.test.tsx`, `plugins/columnResize/useTableColumnResize.test.tsx`, `plugins/stickyColumns/useTableStickyColumns.test.tsx`, and `Table.stories.tsx` ResponsiveScroll play assertions | Width-less columns with empty, short, and long-token rows; mixed explicit widths; pinned columns; narrow and fitting containers | Removing the 60px floor, deriving it from row content, changing explicit width semantics, desynchronizing resize bounds or sticky offsets, or preventing the existing Scroll region from activating fails focused unit or real-browser geometry assertions. | `audit:Table/layout` || Module backlink | `scripts/check-knowledge.mjs` | Active parent and colocated module record | A missing, duplicate, mis-parented, wrong-kind, misnamed, or undiscovered module record fails knowledge validation. | `audit:Table/modules` |-| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`, and CLI parent-aware target discovery tests | Canonical anatomy, eight current targets, legacy alias | Missing, extra, duplicated, prefixed, stale, alias-backed, or independently owned member mappings fail repository validation or discovery coverage. | `audit:Table/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs`, `themingTargets.test.ts`, and CLI parent-aware target discovery tests | Canonical anatomy and eight current targets | Missing, extra, duplicated, prefixed, stale, or independently owned member mappings fail repository validation or discovery coverage. | `audit:Table/theming` |## Decision logdiff --git a/packages/core/src/Table/Table.test.tsx b/packages/core/src/Table/Table.test.tsxindex c6348d7f71..398e5de277 100644--- a/packages/core/src/Table/Table.test.tsx+++ b/packages/core/src/Table/Table.test.tsx@@ -513,11 +513,11 @@ describe('BaseTable', () => {);});- it('keeps the astryx theme classes alongside a consumer className', () => {+ it('keeps the canonical theme class alongside a consumer className', () => {render(<Table data={users} columns={columns} className="custom-table" />);const table = screen.getByRole('table');- expect(table.className).toContain('astryx-base-table');expect(table.className).toContain('astryx-table');+ expect(table.className).not.toContain('astryx-base-table');expect(table.className).toContain('custom-table');});diff --git a/packages/core/src/Table/Table.tsx b/packages/core/src/Table/Table.tsxindex 07a7653245..14cb8ef8bb 100644--- a/packages/core/src/Table/Table.tsx+++ b/packages/core/src/Table/Table.tsx@@ -195,8 +195,8 @@ function buildTableStylePlugin<return {transformTable(props: TableRenderProps): TableRenderProps {// The `astryx-table` class itself comes from BaseTable, which renders- // the <table> element and now names it `table` (with `base-table` as its- // legacy name). Adding it here too would put the token on twice.+ // the <table> element and names it with the canonical `table` target.+ // Adding it here too would put the token on twice.return {...props,xstyle: [...props.xstyle, tableStyles.base],diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjsindex 7baddc7bfd..c7c40d17a8 100644--- a/packages/core/src/TextArea/TextArea.doc.mjs+++ b/packages/core/src/TextArea/TextArea.doc.mjs@@ -277,14 +277,6 @@ export const docs = {},{className: 'astryx-text-area-control'},{className: 'astryx-text-area-counter'},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {- className: 'astryx-textarea',- visualProps: ['size', 'status'],- states: ['disabled', 'readonly'],- deprecatedFor: 'text-area',- },],vars: [{@@ -533,14 +525,6 @@ export const docsZh = {},{className: 'astryx-text-area-control'},{className: 'astryx-text-area-counter'},- // Retained beside the canonical names for backwards compatibility.- // New themes use the canonical targets above.- {- className: 'astryx-textarea',- visualProps: ['size', 'status'],- states: ['disabled', 'readonly'],- deprecatedFor: 'text-area',- },],vars: [{@@ -689,7 +673,8 @@ export const docsDense = {htmlName: 'HTML name attr for form submissions.',onFocus: 'Callback on focus.',onBlur: 'Callback on blur.',- autoComplete: 'Native autocomplete attr, forwarded unchanged. Does not affect the controlled value.',+ autoComplete:+ 'Native autocomplete attr, forwarded unchanged. Does not affect the controlled value.',xstyle:'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',},diff --git a/packages/core/src/TextArea/TextArea.spec.md b/packages/core/src/TextArea/TextArea.spec.mdindex 1d30a3122e..9885d0d409 100644--- a/packages/core/src/TextArea/TextArea.spec.md+++ b/packages/core/src/TextArea/TextArea.spec.md@@ -28,17 +28,19 @@ system_specs: []## Intent-TextArea presents a labeled multi-line text field. This draft records its current-consumer anatomy and the theming ownership of parts rendered by TextArea, Field,-FieldStatus, and Spinner. It changes no runtime behavior or public API.+TextArea presents a labeled multi-line text field. This record preserves its+current consumer anatomy and the theming ownership of parts rendered by TextArea,+Field, FieldStatus, and Spinner while 0.7.0 removes the deprecated `textarea`+theming alias.## Compatibility and migration-- Released default preserved: `yes`-- Compatibility class: additive documentation only; runtime, DOM, styling,- targets, aliases, and public API remain unchanged+- Released default preserved: `yes`; canonical `text-area` behavior is unchanged+- Removed alias: 0.7.0 stops emitting `textarea`- Controlled/uncontrolled behavior: unchanged; TextArea remains controlled-- Migration decision: none+- Migration decision: replace `textarea` theme keys and `.astryx-textarea`+ selectors with `text-area` and `.astryx-text-area`, or run+ `astryx upgrade --from 0.6.3 --apply --path .`Consumer migration instructions belong in consumer docs and release notes.@@ -59,7 +61,6 @@ Consumer migration instructions belong in consumer docs and release notes.by `component:Icon` and `component:Field`, respectively.- Loading-indicator presentation — owned by `component:Spinner`.- Caller-provided custom start content outside Icon's supported source forms.-- The deprecated `textarea` alias as separate anatomy.## Public concepts@@ -164,8 +165,6 @@ values render through Icon and delegate to its `icon` target; arbitrary ReactNodstart content is caller-provided and intentionally stays outside TextArea'spublic theming ownership. Attached and detached status messages delegate toFieldStatus, while the tooltip variant delegates its rendered surface to Tooltip.-The deprecated `textarea` alias is compatibility evidence only and does not-appear in the map.## Family and system relationships@@ -179,16 +178,15 @@ appear in the map.| Contract | Verification | Representative states | Mutation or failure expectation | Audit section || ------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ || FR1, FR4 | `TextArea.test.tsx` structure and counter suites | Default, placeholder, counter, over limit | Removing or regrouping stable parts breaks existing role, content, or DOM assertions. | `audit:TextArea/anatomy` |-| FR2 | `TextArea.test.tsx` root-target suite and `themingTargets.test.ts` | Current and deprecated root names; current targets | Removing root compatibility classes fails focused coverage; source/docs drift fails the target guard. | `audit:TextArea/theming` |+| FR2 | `TextArea.test.tsx` root-target suite and `themingTargets.test.ts` | Three canonical local targets | Missing canonical classes or source/docs drift fails focused coverage after the 0.7 alias removal. | `audit:TextArea/theming` || FR3 | `TextArea.test.tsx`, `useInputStatusIcon.test.tsx`, and source inspection of `renderIconSlot` | Standard/custom start content; Spinner; attached/detached/tooltip status | Removing or rerouting composed content breaks existing icon, spinner, tooltip, message, or association assertions. | `audit:TextArea/anatomy` || Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local targets | Canonical-key drift, invalid dispositions or target spelling, alias-backed local claims, or an unclaimed current local target fails validation. | `audit:TextArea/theming` |-The focused TextArea suite pins the current and deprecated root classes, but does-not separately assert the exact `text-area-control` or `text-area-counter` class-placement. The source/metadata target guard covers those local declarations. No-current repository check resolves `delegatesTo` owner/target pairs; the pairs in-this draft were verified manually, so semantic delegation drift remains a-validation gap.+The focused TextArea suite pins the canonical root class, but does not separately+assert the exact `text-area-control` or `text-area-counter` class placement. The+source/metadata target guard covers those local declarations. No current repository+check resolves `delegatesTo` owner/target pairs; the pairs in this draft were+verified manually, so semantic delegation drift remains a validation gap.## Decision logdiff --git a/packages/core/src/TextArea/TextArea.test.tsx b/packages/core/src/TextArea/TextArea.test.tsxindex 656d4726c2..d6f33a8d7c 100644--- a/packages/core/src/TextArea/TextArea.test.tsx+++ b/packages/core/src/TextArea/TextArea.test.tsx@@ -1146,7 +1146,7 @@ describe('TextArea disabled theme state', () => {const {container} = render(<TextArea label="Description" value="" onChange={() => {}} isDisabled />,);- const root = container.querySelector('.astryx-textarea');+ const root = container.querySelector('.astryx-text-area');expect(root).toHaveAttribute('data-disabled', 'disabled');});@@ -1154,7 +1154,7 @@ describe('TextArea disabled theme state', () => {const {container} = render(<TextArea label="Description" value="" onChange={() => {}} />,);- const root = container.querySelector('.astryx-textarea');+ const root = container.querySelector('.astryx-text-area');expect(root).not.toHaveAttribute('data-disabled');});});@@ -1164,7 +1164,7 @@ describe('TextArea readonly theme state', () => {const {container} = render(<TextArea label="Notes" value="" onChange={() => {}} isReadOnly />,);- const root = container.querySelector('.astryx-textarea');+ const root = container.querySelector('.astryx-text-area');expect(root).toHaveAttribute('data-readonly', 'readonly');});@@ -1172,18 +1172,19 @@ describe('TextArea readonly theme state', () => {const {container} = render(<TextArea label="Notes" value="" onChange={() => {}} />,);- const root = container.querySelector('.astryx-textarea');+ const root = container.querySelector('.astryx-text-area');expect(root).not.toHaveAttribute('data-readonly');});});describe('TextArea theme target names', () => {- it('renders the deprecated class beside the current one', () => {+ it('renders only the canonical target class', () => {const {container} = render(<TextArea label="Notes" value="" onChange={() => {}} />,);const root = container.querySelector('.astryx-text-area');expect(root).not.toBeNull();- expect(root).toHaveClass('astryx-textarea');+ expect(root).toHaveClass('astryx-text-area');+ expect(root).not.toHaveClass('astryx-textarea');});});diff --git a/packages/core/src/TextArea/TextArea.tsx b/packages/core/src/TextArea/TextArea.tsxindex fa5d000155..8de2179c22 100644--- a/packages/core/src/TextArea/TextArea.tsx+++ b/packages/core/src/TextArea/TextArea.tsx@@ -568,18 +568,12 @@ export function TextArea({onClick={handleWrapperClick}onMouseUp={handleWrapperMouseUp}{...mergeProps(- themeProps(- 'text-area',- {- size,- status: status?.type ?? null,- disabled: isDisabled ? 'disabled' : null,- readonly: isReadOnly ? 'readonly' : null,- },- // `textarea` ran the compound name together; keep it emitted so- // existing themes continue to work.- {legacyNames: ['textarea']},- ),+ themeProps('text-area', {+ size,+ status: status?.type ?? null,+ disabled: isDisabled ? 'disabled' : null,+ readonly: isReadOnly ? 'readonly' : null,+ }),stylex.props(inputWrapperStyles.base,styles.wrapper,diff --git a/packages/core/src/theme/defineTheme.test.ts b/packages/core/src/theme/defineTheme.test.tsindex c7642ba895..3de6afde45 100644--- a/packages/core/src/theme/defineTheme.test.ts+++ b/packages/core/src/theme/defineTheme.test.ts@@ -877,7 +877,7 @@ describe('pseudo-class overrides in components', () => {const theme = defineTheme({name: 'pseudo',components: {- radio: {+ 'radio-indicator': {base: {borderColor: '#8F9296',':hover': {@@ -889,11 +889,11 @@ describe('pseudo-class overrides in components', () => {});const css = generateThemeTestCSS(theme);// Base rule- expect(css).toContain('.astryx-radio {');+ expect(css).toContain('.astryx-radio-indicator {');expect(css).toContain('border-color: #8F9296');// Pseudo rule — separate selectorexpect(css).toContain(- '.astryx-radio:hover:where(:not(:disabled,[aria-disabled="true"])) {',+ '.astryx-radio-indicator:hover:where(:not(:disabled,[aria-disabled="true"])) {',);expect(css).toContain('border-color: color-mix(in srgb, #8F9296, black 20%)',diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.tsindex 72423a3338..dd28d50900 100644--- a/packages/core/src/theme/defineTheme.ts+++ b/packages/core/src/theme/defineTheme.ts@@ -171,7 +171,7 @@ export type StyleOverrides = Record<string, string | Record<string, string>>;* badge: {* 'variant:ghost': { border: '1px solid var(--color-border)' },* },- * radio: {+ * 'radio-indicator': {* base: {* borderColor: '#8F9296',* ':hover': { borderColor: 'color-mix(in srgb, #8F9296, black 20%)' },diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.tsindex a9eae14e26..60a98b46d8 100644--- a/packages/core/src/theme/derivedVarRegistry.test.ts+++ b/packages/core/src/theme/derivedVarRegistry.test.ts@@ -476,38 +476,29 @@ describe('getDerivedVars', () => {expect(getDerivedVars('unknown', 'borderRadius')).toEqual([]);});- it('resolves a deprecated key to the entries of the key that replaced it', () => {- // A theme written against the old spelling still selects the element (the- // component emits both classes), so its derived vars must still expand —- // otherwise the rule lands and the var half of it silently does nothing.- expect(getDerivedVars('hovercard', 'borderRadius')).toEqual(- getDerivedVars('hover-card', 'borderRadius'),- );- expect(getDerivedVars('textarea', 'paddingInline')).toEqual(- getDerivedVars('text-area', 'paddingInline'),- );- expect(getDerivedVars('progressbar-mark', 'width')).toEqual(- getDerivedVars('progress-bar-mark', 'width'),- );+ it('does not resolve removed target aliases', () => {+ expect(getDerivedVars('hovercard', 'borderRadius')).toEqual([]);+ expect(getDerivedVars('textarea', 'paddingInline')).toEqual([]);+ expect(getDerivedVars('progressbar-mark', 'width')).toEqual([]);});it('returns empty for unregistered property', () => {expect(getDerivedVars('card', 'color')).toEqual([]);});- it('marks textarea paddingInline as replacing the source property', () => {- const result = getDerivedVars('textarea', 'paddingInline');+ it('marks text-area paddingInline as replacing the source property', () => {+ const result = getDerivedVars('text-area', 'paddingInline');expect(result).toHaveLength(1);expect(result[0].vars).toEqual(['--_textarea-inline-padding']);expect(result[0].replaces).toBe(true);});- it('marks progressbar-mark width and height as replacing the source property', () => {+ it('marks progress-bar-mark width and height as replacing the source property', () => {for (const [property, varName] of [['width', '--_progressbar-mark-width'],['height', '--_progressbar-mark-height'],]) {- const result = getDerivedVars('progressbar-mark', property);+ const result = getDerivedVars('progress-bar-mark', property);expect(result).toHaveLength(1);expect(result[0].vars).toEqual([varName]);expect(result[0].replaces).toBe(true);diff --git a/packages/core/src/theme/derivedVarRegistry.ts b/packages/core/src/theme/derivedVarRegistry.tsindex 77e554c972..ba74058ecf 100644--- a/packages/core/src/theme/derivedVarRegistry.ts+++ b/packages/core/src/theme/derivedVarRegistry.ts@@ -97,33 +97,11 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {],};-/**- * Deprecated component keys → the key that superseded them.- *- * A renamed target keeps emitting its old class, so a theme written against- * the old key still selects the element. Without this the rule would land but- * its derived vars would not expand, and the half that travels through a var- * (a hover card's radius, a text area's inline padding) would silently do- * nothing. Keep these aliases aligned with the emitted compatibility classes.- */-const DEPRECATED_REGISTRY_KEYS: Record<string, string> = {- hovercard: 'hover-card',- 'progressbar-mark': 'progress-bar-mark',- textarea: 'text-area',-};--/**- * Look up derived var entries for a component + CSS property.- * Returns matching entries in priority order, or empty array if none.- */export function getDerivedVars(component: string,property: string,): DerivedVarEntry[] {- const renamedTo = DEPRECATED_REGISTRY_KEYS[component];- const entries =- derivedVarRegistry[component] ??- (renamedTo ? derivedVarRegistry[renamedTo] : undefined);+ const entries = derivedVarRegistry[component];if (!entries) {return [];}diff --git a/packages/core/src/theme/generateThemeRules.test.ts b/packages/core/src/theme/generateThemeRules.test.tsindex 3a2aa3542d..6131c763d2 100644--- a/packages/core/src/theme/generateThemeRules.test.ts+++ b/packages/core/src/theme/generateThemeRules.test.ts@@ -184,9 +184,9 @@ describe('generateThemeRules', () => {expect(buttonRule).toContain('light-dark(rgba(5, 54, 89, 0.1)');});- it('applies pseudo-class suffixes to both compat selector prefixes', () => {+ it('applies pseudo-class suffixes to the canonical selector', () => {const pseudoTheme = defineTheme({- name: 'pseudo-compat',+ name: 'pseudo-canonical',components: {button: {base: {@@ -1115,13 +1115,13 @@ describe('derived var expansion', () => {const theme = defineTheme({name: 'test-derived-textarea',components: {- textarea: {+ 'text-area': {base: {paddingInline: 'var(--app-input-padding-x)'},},},});const rules = generateThemeRules(theme);- const rule = rules.find(r => r.includes('.astryx-textarea'));+ const rule = rules.find(r => r.includes('.astryx-text-area'));expect(rule).toBeDefined();// Value flows to the inner <textarea> via the var…expect(rule).toContain(@@ -1180,13 +1180,13 @@ describe('derived var expansion', () => {const theme = defineTheme({name: 'test-derived-progressbar-mark',components: {- 'progressbar-mark': {+ 'progress-bar-mark': {base: {width: '2px', height: '12px'},},},});const rules = generateThemeRules(theme);- const rule = rules.find(r => r.includes('.astryx-progressbar-mark'));+ const rule = rules.find(r => r.includes('.astryx-progress-bar-mark'));expect(rule).toBeDefined();expect(rule).toContain('--_progressbar-mark-width: 2px');expect(rule).toContain('--_progressbar-mark-height: 12px');@@ -1326,16 +1326,14 @@ describe('physical padding longhands', () => {});});-describe('renamed theme targets', () => {- // The renamed targets emit both classes, so a rule written against either- // key selects the element. What is easy to miss is the derived-var half: a- // key the registry does not know still emits a rule, minus every var the- // component actually reads — the same silent nothing a misspelled key gives.- it('expands derived vars for a renamed key and its deprecated spelling', () => {+describe('canonical theme targets', () => {+ // Removed aliases still pass through the generic CSS generator, but they no+ // longer receive canonical derived-variable expansion.+ it('expands derived vars only for canonical target keys', () => {const rules = (component: string, styles: Record<string, string>) =>generateThemeRules(defineTheme({- name: `test-renamed-${component}`,+ name: `test-target-${component}`,components: {[component]: {base: styles}},}),).join('\n');@@ -1343,21 +1341,21 @@ describe('renamed theme targets', () => {const hoverCard = rules('hover-card', {borderRadius: '9px'});expect(hoverCard).toContain('.astryx-hover-card');expect(hoverCard).toContain('--_hovercard-radius: 9px');- expect(rules('hovercard', {borderRadius: '9px'})).toContain(+ expect(rules('hovercard', {borderRadius: '9px'})).not.toContain('--_hovercard-radius: 9px',);const textArea = rules('text-area', {paddingInline: '11px'});expect(textArea).toContain('.astryx-text-area');expect(textArea).toContain('--_textarea-inline-padding: 11px');- expect(rules('textarea', {paddingInline: '11px'})).toContain(+ expect(rules('textarea', {paddingInline: '11px'})).not.toContain('--_textarea-inline-padding: 11px',);const mark = rules('progress-bar-mark', {width: '3px'});expect(mark).toContain('.astryx-progress-bar-mark');expect(mark).toContain('--_progressbar-mark-width: 3px');- expect(rules('progressbar-mark', {width: '3px'})).toContain(+ expect(rules('progressbar-mark', {width: '3px'})).not.toContain('--_progressbar-mark-width: 3px',);});diff --git a/packages/core/src/theme/publicThemeHelperContract.test.ts b/packages/core/src/theme/publicThemeHelperContract.test.tsindex 22ea0e2fb5..918d357109 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 canonical data attributes alongside bare compatibility classes', () => {+ it('keeps canonical data attributes without bare compatibility classes', () => {expect(themeProps('button', {variant: 'primary', size: 'sm'})).toEqual({- className: 'astryx-button primary sm',+ className: 'astryx-button','data-variant': 'primary','data-size': 'sm',});diff --git a/packages/core/src/theme/themingTargets.test.ts b/packages/core/src/theme/themingTargets.test.tsindex a09852ef3b..aea8e3b597 100644--- a/packages/core/src/theme/themingTargets.test.ts+++ b/packages/core/src/theme/themingTargets.test.ts@@ -214,32 +214,32 @@ function extractThemeTargets(describe('extractThemeTargets', () => {it('reads a bare call with no props', () => {- expect(extractThemeTargets(`themeProps('progressbar-track')`)).toEqual([- {className: 'astryx-progressbar-track', propKeys: [], isOpaque: false},+ expect(extractThemeTargets(`themeProps('progress-bar-track')`)).toEqual([+ {className: 'astryx-progress-bar-track', propKeys: [], isOpaque: false},]);});it('reads shorthand props', () => {- expect(extractThemeTargets(`themeProps('progressbar', {variant})`)).toEqual(- [- {- className: 'astryx-progressbar',- propKeys: ['variant'],- isOpaque: false,- },- ],- );+ expect(+ extractThemeTargets(`themeProps('progress-bar', {variant})`),+ ).toEqual([+ {+ className: 'astryx-progress-bar',+ propKeys: ['variant'],+ isOpaque: false,+ },+ ]);});it('records the KEY, not the value, when a prop is renamed', () => {// The trap a regex falls into: `fillVariant` is a local, not a prop.expect(extractThemeTargets(- `themeProps('progressbar-fill', {variant: fillVariant})`,+ `themeProps('progress-bar-fill', {variant: fillVariant})`,),).toEqual([{- className: 'astryx-progressbar-fill',+ className: 'astryx-progress-bar-fill',propKeys: ['variant'],isOpaque: false,},diff --git a/packages/core/src/utils/themeProps.test.ts b/packages/core/src/utils/themeProps.test.tsindex c4b87212c1..59ec41e36b 100644--- a/packages/core/src/utils/themeProps.test.ts+++ b/packages/core/src/utils/themeProps.test.ts@@ -8,38 +8,26 @@ describe('themeProps', () => {expect(themeProps('card').className).toBe('astryx-card');});- it('continues to emit released bare prop and state classes through 0.7.0', () => {+ it('emits only the stable target class while reflecting props and state', () => {expect(themeProps('button', {variant: 'secondary', size: 'sm'}).className,- ).toBe('astryx-button secondary sm');+ ).toBe('astryx-button');expect(themeProps('switch', {checked: 'checked'}).className).toBe(- 'astryx-switch checked',+ 'astryx-switch',);});- it('prefixes numeric compatibility classes with the prop name', () => {- expect(themeProps('heading', {level: 1}).className).toBe(- 'astryx-heading level-1',- );+ it('does not turn numeric values into classes', () => {+ expect(themeProps('heading', {level: 1}).className).toBe('astryx-heading');expect(themeProps('heading', {level: '3'}).className).toBe(- 'astryx-heading level-3',+ 'astryx-heading',);});- it('skips nullish compatibility classes', () => {+ it('ignores nullish reflected values in the class name', () => {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',- {variant: 'positive'},- {legacyNames: ['progressbar']},- ).className,- ).toBe('astryx-progress-bar positive astryx-progressbar');+ ).toBe('astryx-button');});it('reflects visual props as data attributes', () => {@@ -64,9 +52,9 @@ describe('themeProps', () => {});});- it('returns compatibility classes and canonical data attributes together', () => {+ it('returns the stable target and canonical data attributes together', () => {expect(themeProps('button', {variant: 'primary', size: 'sm'})).toEqual({- className: 'astryx-button primary sm',+ className: 'astryx-button','data-variant': 'primary','data-size': 'sm',});diff --git a/packages/core/src/utils/themeProps.ts b/packages/core/src/utils/themeProps.tsindex 41d2fd5344..7b1800b026 100644--- a/packages/core/src/utils/themeProps.ts+++ b/packages/core/src/utils/themeProps.ts@@ -11,44 +11,21 @@ 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.+ * Build the stable Astryx target class name for a component.*- * Every component renders one stable target class (`astryx-button`,- * `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+ * Visual props and runtime states are reflected only as explicit `data-*`+ * attributes. The `astryx-` prefix comes from the centralized naming module* (`packages/core/src/naming.ts`) so the namespace lives in one place.** <!-- SYNC: packages/core/src/naming.ts (namespace prefix source of truth) -->* <!-- SYNC: packages/core/src/utils/parseStyleKey.ts -->** @param component - Component name in lowercase (e.g. 'button', 'card')- * @param props - Visual prop values whose released bare classes remain aliases- * @returns Stable target and deprecated compatibility classes+ * @returns Stable target class*/-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(' ');+function buildClassName(component: string): string {+ return stableClassName(component);}/**@@ -77,44 +54,17 @@ 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, deprecated bare compatibility classes,- * and canonical data-attribute reflection for visual props and runtime states.- * For example:+ * This emits one stable Astryx target plus canonical data-attribute reflection+ * for visual props and runtime states. For example:** ```ts* themeProps('button', { variant: 'primary', size: 'sm' })- * // → { className: 'astryx-button primary sm', data-variant: 'primary', data-size: 'sm' }+ * // → { className: 'astryx-button', data-variant: 'primary', data-size: 'sm' }* ```*/-/**- * Options for {@link themeProps}.- */-export type ThemePropsOptions = {- /**- * 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. Keep aliases emitted unless a separate compatibility- * decision explicitly retires them.- *- * Pass plain string literals — the theming guards scan for them statically.- * Document each old name with `deprecatedFor` in the component's- * `theming.targets` so discovery and diagnostics name the replacement.- */- legacyNames?: ReadonlyArray<string>;-};--export function themeProps(- component: string,- props?: ClassProps,- options?: ThemePropsOptions,-): ThemeProps {- const className = buildClassName(component, props);- const legacy = options?.legacyNames?.map(name => stableClassName(name)) ?? [];-+export function themeProps(component: string, props?: ClassProps): ThemeProps {return {- className: legacy.length > 0 ? [className, ...legacy].join(' ') : className,+ className: buildClassName(component),...themeDataAttributes(props),};}diff --git a/packages/themes/probe/src/probeTheme.ts b/packages/themes/probe/src/probeTheme.tsindex a3a4098dce..a73162d4f2 100644--- a/packages/themes/probe/src/probeTheme.ts+++ b/packages/themes/probe/src/probeTheme.ts@@ -6,7 +6,7 @@// test fixture. Regenerate with: pnpm visual:probe-theme//// defineTheme takes six things and this covers all six:-// components 288 targets, 923 selectors (generated from the docs)+// components 269 targets, 865 selectors (generated from the docs)// tokens custom properties, read back off the themed element// icons every registry entry swapped for a marked glyph// indicators check / radio / checkbox swapped — the swap that reaches furthest@@ -662,14 +662,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(303.5 82% 25%)',},},- 'base-table': {- base: {- backgroundColor: 'hsl(215.5 83% 51%)',- color: 'hsl(194.1 81% 12%)',- borderColor: 'hsl(30.7 76% 25%)',- outlineColor: 'hsl(299.1 76% 25%)',- },- },blockquote: {base: {backgroundColor: 'hsl(281.1 79% 50%)',@@ -1172,38 +1164,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(338.0 72% 25%)',},},- checkbox: {- base: {- backgroundColor: 'hsl(107.2 78% 56%)',- color: 'hsl(185.0 77% 12%)',- borderColor: 'hsl(132.4 86% 25%)',- outlineColor: 'hsl(333.1 88% 25%)',- },- 'size:sm': {- backgroundColor: 'hsl(280.8 82% 55%)',- color: 'hsl(6.5 72% 12%)',- borderColor: 'hsl(301.2 82% 25%)',- outlineColor: 'hsl(187.0 80% 25%)',- },- 'size:md': {- backgroundColor: 'hsl(94.9 83% 55%)',- color: 'hsl(1.8 77% 12%)',- borderColor: 'hsl(2.1 86% 25%)',- outlineColor: 'hsl(103.4 88% 25%)',- },- checked: {- backgroundColor: 'hsl(275.1 80% 56%)',- color: 'hsl(250.8 90% 12%)',- borderColor: 'hsl(349.2 88% 25%)',- outlineColor: 'hsl(309.3 71% 25%)',- },- disabled: {- backgroundColor: 'hsl(194.2 93% 47%)',- color: 'hsl(236.0 75% 12%)',- borderColor: 'hsl(219.5 92% 25%)',- outlineColor: 'hsl(219.2 88% 25%)',- },- },'checkbox-indicator': {base: {backgroundColor: 'hsl(238.5 76% 55%)',@@ -1401,6 +1361,24 @@ export const probeTheme = defineTheme({borderColor: 'hsl(154.6 86% 25%)',outlineColor: 'hsl(60.5 83% 25%)',},+ 'color:primary': {+ backgroundColor: 'hsl(145.0 73% 46%)',+ color: 'hsl(114.2 80% 12%)',+ borderColor: 'hsl(331.0 88% 25%)',+ outlineColor: 'hsl(175.6 93% 25%)',+ },+ 'color:secondary': {+ backgroundColor: 'hsl(1.9 72% 47%)',+ color: 'hsl(106.2 76% 12%)',+ borderColor: 'hsl(173.6 85% 25%)',+ outlineColor: 'hsl(174.2 89% 25%)',+ },+ 'color:inherit': {+ backgroundColor: 'hsl(143.9 89% 56%)',+ color: 'hsl(36.0 88% 12%)',+ borderColor: 'hsl(295.4 70% 25%)',+ outlineColor: 'hsl(5.9 75% 25%)',+ },},'code-block': {base: {@@ -1494,98 +1472,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(241.4 86% 25%)',},},- codeblock: {- base: {- backgroundColor: 'hsl(298.9 80% 64%)',- color: 'hsl(23.4 70% 12%)',- borderColor: 'hsl(63.4 73% 25%)',- outlineColor: 'hsl(352.0 88% 25%)',- },- 'size:sm': {- backgroundColor: 'hsl(299.7 82% 45%)',- color: 'hsl(173.7 88% 12%)',- borderColor: 'hsl(227.3 77% 25%)',- outlineColor: 'hsl(35.6 82% 25%)',- },- 'size:md': {- backgroundColor: 'hsl(113.8 83% 45%)',- color: 'hsl(360.0 73% 12%)',- borderColor: 'hsl(166.3 73% 25%)',- outlineColor: 'hsl(312.0 90% 25%)',- },- 'container:card': {- backgroundColor: 'hsl(179.7 71% 53%)',- color: 'hsl(295.1 71% 12%)',- borderColor: 'hsl(223.3 86% 25%)',- outlineColor: 'hsl(266.3 79% 25%)',- },- 'container:section': {- backgroundColor: 'hsl(319.8 93% 63%)',- color: 'hsl(201.5 82% 12%)',- borderColor: 'hsl(31.0 88% 25%)',- outlineColor: 'hsl(81.1 92% 25%)',- },- },- 'codeblock-copy-button': {- base: {- backgroundColor: 'hsl(120.9 81% 45%)',- color: 'hsl(269.6 73% 12%)',- borderColor: 'hsl(93.0 91% 25%)',- outlineColor: 'hsl(0.8 94% 25%)',- },- },- 'codeblock-header': {- base: {- backgroundColor: 'hsl(67.0 72% 59%)',- color: 'hsl(217.7 88% 12%)',- borderColor: 'hsl(103.5 77% 25%)',- outlineColor: 'hsl(172.7 85% 25%)',- },- 'size:sm': {- backgroundColor: 'hsl(313.4 91% 50%)',- color: 'hsl(223.0 85% 12%)',- borderColor: 'hsl(171.2 91% 25%)',- outlineColor: 'hsl(103.4 94% 25%)',- },- 'size:md': {- backgroundColor: 'hsl(127.4 92% 50%)',- color: 'hsl(310.7 76% 12%)',- borderColor: 'hsl(68.1 94% 25%)',- outlineColor: 'hsl(19.8 76% 25%)',- },- 'container:card': {- backgroundColor: 'hsl(123.6 85% 54%)',- color: 'hsl(312.2 72% 12%)',- borderColor: 'hsl(290.2 92% 25%)',- outlineColor: 'hsl(200.6 82% 25%)',- },- 'container:section': {- backgroundColor: 'hsl(163.1 94% 49%)',- color: 'hsl(229.9 78% 12%)',- borderColor: 'hsl(209.7 88% 25%)',- outlineColor: 'hsl(340.0 76% 25%)',- },- },- 'codeblock-title': {- base: {- backgroundColor: 'hsl(197.0 86% 59%)',- color: 'hsl(8.6 85% 12%)',- borderColor: 'hsl(329.1 80% 25%)',- outlineColor: 'hsl(209.9 83% 25%)',- },- 'size:sm': {- backgroundColor: 'hsl(157.6 78% 61%)',- color: 'hsl(168.3 73% 12%)',- borderColor: 'hsl(13.6 79% 25%)',- outlineColor: 'hsl(79.6 79% 25%)',- },- 'size:md': {- backgroundColor: 'hsl(331.7 79% 61%)',- color: 'hsl(5.3 88% 12%)',- borderColor: 'hsl(225.7 81% 25%)',- outlineColor: 'hsl(4.0 79% 25%)',- },- },collapsible: {base: {backgroundColor: 'hsl(223.9 82% 62%)',@@ -1593,6 +1479,12 @@ export const probeTheme = defineTheme({borderColor: 'hsl(86.7 85% 25%)',outlineColor: 'hsl(193.0 92% 25%)',},+ divided: {+ backgroundColor: 'hsl(59.7 88% 63%)',+ color: 'hsl(285.1 70% 12%)',+ borderColor: 'hsl(53.0 70% 25%)',+ outlineColor: 'hsl(43.2 73% 25%)',+ },},'collapsible-content': {base: {@@ -1601,6 +1493,12 @@ export const probeTheme = defineTheme({borderColor: 'hsl(150.3 86% 25%)',outlineColor: 'hsl(8.4 83% 25%)',},+ open: {+ backgroundColor: 'hsl(61.9 92% 57%)',+ color: 'hsl(344.5 93% 12%)',+ borderColor: 'hsl(91.5 89% 25%)',+ outlineColor: 'hsl(34.0 73% 25%)',+ },},'collapsible-group': {base: {@@ -1617,6 +1515,30 @@ export const probeTheme = defineTheme({borderColor: 'hsl(115.8 83% 25%)',outlineColor: 'hsl(179.2 89% 25%)',},+ 'chevronPosition:start': {+ backgroundColor: 'hsl(72.1 87% 50%)',+ color: 'hsl(2.4 77% 12%)',+ borderColor: 'hsl(354.3 70% 25%)',+ outlineColor: 'hsl(198.5 73% 25%)',+ },+ 'chevronPosition:end': {+ backgroundColor: 'hsl(314.4 89% 52%)',+ color: 'hsl(252.5 90% 12%)',+ borderColor: 'hsl(324.1 78% 25%)',+ outlineColor: 'hsl(194.0 81% 25%)',+ },+ open: {+ backgroundColor: 'hsl(61.4 94% 58%)',+ color: 'hsl(352.8 88% 12%)',+ borderColor: 'hsl(175.6 82% 25%)',+ outlineColor: 'hsl(222.5 87% 25%)',+ },+ disabled: {+ backgroundColor: 'hsl(87.3 86% 49%)',+ color: 'hsl(187.8 70% 12%)',+ borderColor: 'hsl(99.4 77% 25%)',+ outlineColor: 'hsl(137.0 93% 25%)',+ },},'command-palette-empty': {base: {@@ -1762,14 +1684,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(208.8 80% 25%)',},},- 'date-input-clear-icon': {- base: {- backgroundColor: 'hsl(37.6 81% 50%)',- color: 'hsl(279.5 93% 12%)',- borderColor: 'hsl(11.3 71% 25%)',- outlineColor: 'hsl(188.1 88% 25%)',- },- },'date-input-toggle-icon': {base: {backgroundColor: 'hsl(301.2 73% 54%)',@@ -1834,14 +1748,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(266.0 72% 25%)',},},- 'date-range-input-clear-icon': {- base: {- backgroundColor: 'hsl(15.2 89% 54%)',- color: 'hsl(48.6 88% 12%)',- borderColor: 'hsl(6.5 76% 25%)',- outlineColor: 'hsl(139.1 73% 25%)',- },- },'date-range-input-preset': {base: {backgroundColor: 'hsl(47.5 89% 45%)',@@ -2624,14 +2530,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(295.0 82% 25%)',},},- hovercard: {- base: {- backgroundColor: 'hsl(126.0 74% 54%)',- color: 'hsl(297.6 84% 12%)',- borderColor: 'hsl(57.0 92% 25%)',- outlineColor: 'hsl(170.1 90% 25%)',- },- },icon: {base: {backgroundColor: 'hsl(11.5 74% 54%)',@@ -2820,6 +2718,22 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(100.2 90% 25%)',},},+ 'item-swipe-action': {+ base: {+ backgroundColor: 'hsl(161.2 82% 58%)',+ color: 'hsl(56.1 83% 12%)',+ borderColor: 'hsl(348.8 82% 25%)',+ outlineColor: 'hsl(23.8 85% 25%)',+ },+ },+ 'item-swipe-panel': {+ base: {+ backgroundColor: 'hsl(283.1 74% 62%)',+ color: 'hsl(101.6 79% 12%)',+ borderColor: 'hsl(38.4 91% 25%)',+ outlineColor: 'hsl(232.5 84% 25%)',+ },+ },kbd: {base: {backgroundColor: 'hsl(35.2 83% 46%)',@@ -3210,14 +3124,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(214.5 74% 25%)',},},- 'multi-selector-clear-icon': {- base: {- backgroundColor: 'hsl(127.8 77% 59%)',- color: 'hsl(323.8 74% 12%)',- borderColor: 'hsl(339.7 70% 25%)',- outlineColor: 'hsl(100.8 88% 25%)',- },- },'multi-selector-empty-state': {base: {backgroundColor: 'hsl(130.1 92% 46%)',@@ -3350,14 +3256,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(88.3 86% 25%)',},},- navicon: {- base: {- backgroundColor: 'hsl(265.8 94% 48%)',- color: 'hsl(53.0 93% 12%)',- borderColor: 'hsl(202.2 81% 25%)',- outlineColor: 'hsl(207.1 70% 25%)',- },- },'number-input': {base: {backgroundColor: 'hsl(126.9 71% 57%)',@@ -3617,14 +3515,6 @@ export const probeTheme = defineTheme({borderRadius: '32px',},},- 'popover-surface': {- base: {- backgroundColor: 'hsl(51.9 87% 47%)',- color: 'hsl(120.8 82% 12%)',- borderColor: 'hsl(94.4 91% 25%)',- outlineColor: 'hsl(42.1 87% 25%)',- },- },'power-search': {base: {backgroundColor: 'hsl(123.6 94% 47%)',@@ -3755,180 +3645,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(165.7 92% 25%)',},},- progressbar: {- base: {- backgroundColor: 'hsl(146.3 73% 50%)',- color: 'hsl(332.3 75% 12%)',- borderColor: 'hsl(169.1 71% 25%)',- outlineColor: 'hsl(40.3 86% 25%)',- },- 'variant:accent': {- backgroundColor: 'hsl(311.5 93% 62%)',- color: 'hsl(293.0 79% 12%)',- borderColor: 'hsl(255.4 71% 25%)',- outlineColor: 'hsl(173.8 84% 25%)',- },- 'variant:success': {- backgroundColor: 'hsl(237.1 93% 62%)',- color: 'hsl(100.8 86% 12%)',- borderColor: 'hsl(228.3 75% 25%)',- outlineColor: 'hsl(70.2 89% 25%)',- },- 'variant:warning': {- backgroundColor: 'hsl(256.5 88% 55%)',- color: 'hsl(294.1 84% 12%)',- borderColor: 'hsl(133.0 89% 25%)',- outlineColor: 'hsl(339.4 91% 25%)',- },- 'variant:error': {- backgroundColor: 'hsl(95.2 76% 50%)',- color: 'hsl(212.2 90% 12%)',- borderColor: 'hsl(73.5 91% 25%)',- outlineColor: 'hsl(148.0 78% 25%)',- },- 'variant:neutral': {- backgroundColor: 'hsl(19.0 74% 51%)',- color: 'hsl(336.6 77% 12%)',- borderColor: 'hsl(172.6 94% 25%)',- outlineColor: 'hsl(201.3 74% 25%)',- },- },- 'progressbar-fill': {- base: {- backgroundColor: 'hsl(227.5 80% 61%)',- color: 'hsl(38.3 88% 12%)',- borderColor: 'hsl(167.6 72% 25%)',- outlineColor: 'hsl(172.3 82% 25%)',- },- 'variant:accent': {- backgroundColor: 'hsl(82.3 88% 63%)',- color: 'hsl(278.0 92% 12%)',- borderColor: 'hsl(245.1 72% 25%)',- outlineColor: 'hsl(128.6 81% 25%)',- },- 'variant:success': {- backgroundColor: 'hsl(309.7 89% 57%)',- color: 'hsl(167.0 71% 12%)',- borderColor: 'hsl(273.4 78% 25%)',- outlineColor: 'hsl(144.7 78% 25%)',- },- 'variant:warning': {- backgroundColor: 'hsl(95.0 75% 62%)',- color: 'hsl(201.9 76% 12%)',- borderColor: 'hsl(272.2 79% 25%)',- outlineColor: 'hsl(344.1 89% 25%)',- },- 'variant:error': {- backgroundColor: 'hsl(230.4 92% 47%)',- color: 'hsl(356.3 81% 12%)',- borderColor: 'hsl(165.7 74% 25%)',- outlineColor: 'hsl(288.5 81% 25%)',- },- 'variant:neutral': {- backgroundColor: 'hsl(205.9 91% 60%)',- color: 'hsl(291.1 80% 12%)',- borderColor: 'hsl(320.6 84% 25%)',- outlineColor: 'hsl(122.1 81% 25%)',- },- },- 'progressbar-mark': {- base: {- backgroundColor: 'hsl(124.3 70% 58%)',- color: 'hsl(329.4 79% 12%)',- borderColor: 'hsl(98.9 81% 25%)',- outlineColor: 'hsl(164.1 77% 25%)',- },- 'variant:accent': {- backgroundColor: 'hsl(130.7 74% 58%)',- color: 'hsl(10.7 82% 12%)',- borderColor: 'hsl(266.2 75% 25%)',- outlineColor: 'hsl(16.0 82% 25%)',- },- 'variant:success': {- backgroundColor: 'hsl(343.7 89% 57%)',- color: 'hsl(189.2 87% 12%)',- borderColor: 'hsl(120.3 80% 25%)',- outlineColor: 'hsl(131.1 86% 25%)',- },- 'variant:warning': {- backgroundColor: 'hsl(117.4 80% 45%)',- color: 'hsl(224.1 92% 12%)',- borderColor: 'hsl(121.6 79% 25%)',- outlineColor: 'hsl(357.7 81% 25%)',- },- 'variant:error': {- backgroundColor: 'hsl(170.9 82% 49%)',- color: 'hsl(150.4 83% 12%)',- borderColor: 'hsl(143.5 83% 25%)',- outlineColor: 'hsl(222.9 90% 25%)',- },- 'variant:neutral': {- backgroundColor: 'hsl(239.9 91% 61%)',- color: 'hsl(313.4 71% 12%)',- borderColor: 'hsl(184.0 78% 25%)',- outlineColor: 'hsl(42.6 83% 25%)',- },- },- 'progressbar-track': {- base: {- backgroundColor: 'hsl(268.2 85% 64%)',- color: 'hsl(333.6 84% 12%)',- borderColor: 'hsl(287.6 75% 25%)',- outlineColor: 'hsl(266.4 70% 25%)',- },- },- radio: {- base: {- backgroundColor: 'hsl(77.2 76% 57%)',- color: 'hsl(331.4 70% 12%)',- borderColor: 'hsl(230.0 94% 25%)',- outlineColor: 'hsl(129.5 71% 25%)',- },- checked: {- backgroundColor: 'hsl(71.5 89% 59%)',- color: 'hsl(151.6 75% 12%)',- borderColor: 'hsl(39.8 92% 25%)',- outlineColor: 'hsl(184.3 91% 25%)',- },- disabled: {- backgroundColor: 'hsl(330.5 76% 60%)',- color: 'hsl(251.8 80% 12%)',- borderColor: 'hsl(265.6 79% 25%)',- outlineColor: 'hsl(213.2 86% 25%)',- },- 'size:sm': {- backgroundColor: 'hsl(77.2 91% 58%)',- color: 'hsl(267.3 82% 12%)',- borderColor: 'hsl(351.8 87% 25%)',- outlineColor: 'hsl(61.9 75% 25%)',- },- 'size:md': {- backgroundColor: 'hsl(251.2 92% 58%)',- color: 'hsl(262.6 87% 12%)',- borderColor: 'hsl(52.7 91% 25%)',- outlineColor: 'hsl(21.7 82% 25%)',- },- },- 'radio-dot': {- base: {- backgroundColor: 'hsl(6.3 81% 48%)',- color: 'hsl(74.3 87% 12%)',- borderColor: 'hsl(223.6 88% 25%)',- outlineColor: 'hsl(70.5 71% 25%)',- },- 'size:sm': {- backgroundColor: 'hsl(341.8 74% 55%)',- color: 'hsl(128.8 70% 12%)',- borderColor: 'hsl(47.6 91% 25%)',- outlineColor: 'hsl(40.5 70% 25%)',- },- 'size:md': {- backgroundColor: 'hsl(167.7 74% 55%)',- color: 'hsl(44.8 91% 12%)',- borderColor: 'hsl(251.4 70% 25%)',- outlineColor: 'hsl(54.3 94% 25%)',- },- },'radio-indicator': {base: {backgroundColor: 'hsl(155.0 87% 53%)',@@ -4339,14 +4055,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(201.7 71% 25%)',},},- 'selector-clear-icon': {- base: {- backgroundColor: 'hsl(48.3 90% 54%)',- color: 'hsl(112.3 83% 12%)',- borderColor: 'hsl(207.8 82% 25%)',- outlineColor: 'hsl(332.4 85% 25%)',- },- },'selector-empty-state': {base: {backgroundColor: 'hsl(319.4 83% 54%)',@@ -4699,44 +4407,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(312.9 91% 25%)',},},- statusdot: {- base: {- backgroundColor: 'hsl(350.7 91% 54%)',- color: 'hsl(237.1 89% 12%)',- borderColor: 'hsl(159.5 87% 25%)',- outlineColor: 'hsl(283.2 78% 25%)',- },- 'variant:success': {- backgroundColor: 'hsl(12.2 87% 49%)',- color: 'hsl(116.4 93% 12%)',- borderColor: 'hsl(158.2 81% 25%)',- outlineColor: 'hsl(50.1 75% 25%)',- },- 'variant:warning': {- backgroundColor: 'hsl(121.5 70% 49%)',- color: 'hsl(151.2 73% 12%)',- borderColor: 'hsl(203.1 83% 25%)',- outlineColor: 'hsl(0.5 86% 25%)',- },- 'variant:error': {- backgroundColor: 'hsl(213.6 84% 58%)',- color: 'hsl(257.5 87% 12%)',- borderColor: 'hsl(216.3 76% 25%)',- outlineColor: 'hsl(121.2 82% 25%)',- },- 'variant:accent': {- backgroundColor: 'hsl(147.6 70% 61%)',- color: 'hsl(96.9 91% 12%)',- borderColor: 'hsl(164.6 91% 25%)',- outlineColor: 'hsl(294.5 78% 25%)',- },- 'variant:neutral': {- backgroundColor: 'hsl(116.0 84% 46%)',- color: 'hsl(240.5 78% 12%)',- borderColor: 'hsl(102.5 74% 25%)',- outlineColor: 'hsl(138.6 78% 25%)',- },- },step: {base: {backgroundColor: 'hsl(95.5 75% 59%)',@@ -5393,62 +5063,6 @@ export const probeTheme = defineTheme({outlineColor: 'hsl(135.1 81% 25%)',},},- textarea: {- base: {- backgroundColor: 'hsl(294.7 91% 54%)',- color: 'hsl(254.9 89% 12%)',- borderColor: 'hsl(327.1 85% 25%)',- outlineColor: 'hsl(281.6 78% 25%)',- },- 'size:sm': {- backgroundColor: 'hsl(204.5 73% 58%)',- color: 'hsl(142.6 84% 12%)',- borderColor: 'hsl(129.0 86% 25%)',- outlineColor: 'hsl(132.6 87% 25%)',- },- 'size:md': {- backgroundColor: 'hsl(18.6 74% 58%)',- color: 'hsl(147.3 79% 12%)',- borderColor: 'hsl(68.0 82% 25%)',- outlineColor: 'hsl(216.2 80% 25%)',- },- 'size:lg': {- backgroundColor: 'hsl(268.8 74% 58%)',- color: 'hsl(191.3 88% 12%)',- borderColor: 'hsl(207.4 70% 25%)',- outlineColor: 'hsl(145.5 70% 25%)',- },- 'status:warning': {- backgroundColor: 'hsl(209.6 74% 51%)',- color: 'hsl(302.3 75% 12%)',- borderColor: 'hsl(77.5 71% 25%)',- outlineColor: 'hsl(111.2 72% 25%)',- },- 'status:error': {- backgroundColor: 'hsl(304.8 74% 49%)',- color: 'hsl(197.9 89% 12%)',- borderColor: 'hsl(65.3 74% 25%)',- outlineColor: 'hsl(291.0 90% 25%)',- },- 'status:success': {- backgroundColor: 'hsl(195.1 91% 48%)',- color: 'hsl(92.6 70% 12%)',- borderColor: 'hsl(76.2 72% 25%)',- outlineColor: 'hsl(17.6 70% 25%)',- },- disabled: {- backgroundColor: 'hsl(337.3 94% 50%)',- color: 'hsl(17.8 90% 12%)',- borderColor: 'hsl(78.3 80% 25%)',- outlineColor: 'hsl(285.4 89% 25%)',- },- readonly: {- backgroundColor: 'hsl(322.2 72% 49%)',- color: 'hsl(205.4 85% 12%)',- borderColor: 'hsl(12.3 73% 25%)',- outlineColor: 'hsl(220.7 76% 25%)',- },- },thumbnail: {base: {backgroundColor: 'hsl(190.7 87% 47%)',diff --git a/scripts/check-knowledge.mjs b/scripts/check-knowledge.mjsindex 8d21f3cd72..a02a344b0e 100644--- a/scripts/check-knowledge.mjs+++ b/scripts/check-knowledge.mjs@@ -1206,9 +1206,11 @@ function loadComponentContract(root, specPath, componentName) {problem: `${path.relative(root, docPath)}: ${componentName} has no canonical English usage.anatomy.`,};}- const targets = (candidate.theming?.targets ?? doc.theming?.targets ?? [])- .filter(target => target.deprecatedFor == null)- .map(target => target.className.replace(/^astryx-/, ''));+ const targets = (+ candidate.theming?.targets ??+ doc.theming?.targets ??+ []+ ).map(target => target.className.replace(/^astryx-/, ''));return {contract: {anatomy: anatomy.map(part => part.name),@@ -1275,9 +1277,9 @@ function loadModuleContract(root, specPath, moduleName) {problem: `${path.relative(root, docPath)}: ${moduleName} has no canonical English usage.anatomy; module records never inherit parent aggregate anatomy.`,};}- const targets = (doc.theming?.targets ?? [])- .filter(target => target.deprecatedFor == null)- .map(target => target.className.replace(/^astryx-/, ''));+ const targets = (doc.theming?.targets ?? []).map(target =>+ target.className.replace(/^astryx-/, ''),+ );return {contract: {anatomy: doc.usage.anatomy.map(part => part.name),@@ -1771,7 +1773,6 @@ export async function validateKnowledgeRoot(root = DEFAULT_ROOT) {const canonicalTargets = await collectThemingTargets(path.join(root, 'packages/core/src'),- {includeDeprecated: false},);problems.push(...validateDelegations(delegations, canonicalTargets, activeFamilies),