@astryxdesign/core 0.6.0 → 0.6.1

package/src/utils/themeProps.test.ts

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
+import {describe, expect, it} from 'vitest';
 import {themeDataAttributes, themeProps} from './themeProps';
 
 describe('themeProps', () => {
@@ -8,19 +8,38 @@ describe('themeProps', () => {
     expect(themeProps('card').className).toBe('astryx-card');
   });
 
-  it('does not emit bare prop-value classes', () => {
+  it('continues to emit released bare prop and state classes through 0.7.0', () => {
     expect(
       themeProps('button', {variant: 'secondary', size: 'sm'}).className,
-    ).toBe('astryx-button');
-    expect(themeProps('heading', {level: 1}).className).toBe('astryx-heading');
+    ).toBe('astryx-button secondary sm');
+    expect(themeProps('switch', {checked: 'checked'}).className).toBe(
+      'astryx-switch checked',
+    );
+  });
+
+  it('prefixes numeric compatibility classes with the prop name', () => {
+    expect(themeProps('heading', {level: 1}).className).toBe(
+      'astryx-heading level-1',
+    );
+    expect(themeProps('heading', {level: '3'}).className).toBe(
+      'astryx-heading level-3',
+    );
+  });
+
+  it('skips nullish compatibility classes', () => {
+    expect(
+      themeProps('button', {variant: 'primary', size: undefined}).className,
+    ).toBe('astryx-button primary');
   });
 
   it('continues to emit deprecated target-name aliases when requested', () => {
     expect(
-      themeProps('progress-bar', undefined, {
-        legacyNames: ['progressbar'],
-      }).className,
-    ).toBe('astryx-progress-bar astryx-progressbar');
+      themeProps(
+        'progress-bar',
+        {variant: 'positive'},
+        {legacyNames: ['progressbar']},
+      ).className,
+    ).toBe('astryx-progress-bar positive astryx-progressbar');
   });
 
   it('reflects visual props as data attributes', () => {
@@ -45,9 +64,9 @@ describe('themeProps', () => {
     });
   });
 
-  it('returns the target class and data attributes together', () => {
+  it('returns compatibility classes and canonical data attributes together', () => {
     expect(themeProps('button', {variant: 'primary', size: 'sm'})).toEqual({
-      className: 'astryx-button',
+      className: 'astryx-button primary sm',
       'data-variant': 'primary',
       'data-size': 'sm',
     });

package/src/utils/themeProps.ts

@@ -11,13 +11,20 @@ export function themeDataAttributeName(prop: string): `data-${string}` {
   return `data-${prop.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}`;
 }
 
+function legacyClassTokenForPropValue(prop: string, value: string): string {
+  // CSS classes cannot start with a digit, so preserve the released prop prefix.
+  return /^\d/.test(value) ? `${prop}-${value}` : value;
+}
+
 /**
  * Build the stable astryx-* class name string for a component.
  *
  * Every component renders one stable target class (`astryx-button`,
- * `astryx-card`, etc.). Visual props and runtime states are reflected only as
- * data attributes (`data-variant`, `data-size`, `data-selected`, etc.), which
- * preserve the axis name and cannot collide when two axes share a value.
+ * `astryx-card`, etc.). Visual props and runtime states use explicit data
+ * attributes (`data-variant`, `data-size`, `data-selected`, etc.) as their
+ * canonical selector surface. Released bare value/state classes remain on the
+ * same element as deprecated compatibility aliases until their 0.7.0 removal
+ * window.
  *
  * The `astryx-` prefix comes from the centralized naming module
  * (`packages/core/src/naming.ts`) so the namespace lives in one place.
@@ -26,10 +33,22 @@ export function themeDataAttributeName(prop: string): `data-${string}` {
  * <!-- SYNC: packages/core/src/utils/parseStyleKey.ts -->
  *
  * @param component - Component name in lowercase (e.g. 'button', 'card')
- * @returns Stable class name (e.g. "astryx-button")
+ * @param props - Visual prop values whose released bare classes remain aliases
+ * @returns Stable target and deprecated compatibility classes
  */
-function buildClassName(component: string): string {
-  return stableClassName(component);
+function buildClassName(component: string, props?: ClassProps): string {
+  const classes = [stableClassName(component)];
+
+  if (props) {
+    for (const [prop, value] of Object.entries(props)) {
+      if (value == null) {
+        continue;
+      }
+      classes.push(legacyClassTokenForPropValue(prop, String(value)));
+    }
+  }
+
+  return classes.join(' ');
 }
 
 /**
@@ -58,12 +77,13 @@ export function themeDataAttributes(props?: ClassProps): ThemeDataAttributes {
  * Build the props object components should spread onto the same element that
  * receives the stable Astryx class name.
  *
- * This emits one stable astryx target class plus data-attribute reflection for
- * visual props and runtime states. For example:
+ * This emits one stable Astryx target, deprecated bare compatibility classes,
+ * and canonical data-attribute reflection for visual props and runtime states.
+ * For example:
  *
  * ```ts
  * themeProps('button', { variant: 'primary', size: 'sm' })
- * // → { className: 'astryx-button', data-variant: 'primary', data-size: 'sm' }
+ * // → { className: 'astryx-button primary sm', data-variant: 'primary', data-size: 'sm' }
  * ```
  */
 /**
@@ -71,17 +91,16 @@ export function themeDataAttributes(props?: ClassProps): ThemeDataAttributes {
  */
 export type ThemePropsOptions = {
   /**
-   * Stable class names to emit ALONGSIDE the component's own, for targets that
-   * have been renamed.
+   * Stable target names to emit alongside the canonical target for backwards
+   * compatibility.
    *
    * A theme target is public API: renaming one silently breaks every theme
-   * that styles it. Emitting the old name beside the new one keeps those
-   * themes working through a deprecation window, at the cost of one extra
-   * class on the element until the old name is dropped in a major.
+   * that styles it. Keep aliases emitted unless a separate compatibility
+   * decision explicitly retires them.
    *
    * Pass plain string literals — the theming guards scan for them statically.
-   * Document the old name with `deprecated` in the component's
-   * `theming.targets` so the docsite says which to use.
+   * Document each old name with `deprecatedFor` in the component's
+   * `theming.targets` so discovery and diagnostics name the replacement.
    */
   legacyNames?: ReadonlyArray<string>;
 };
@@ -91,7 +110,7 @@ export function themeProps(
   props?: ClassProps,
   options?: ThemePropsOptions,
 ): ThemeProps {
-  const className = buildClassName(component);
+  const className = buildClassName(component, props);
   const legacy = options?.legacyNames?.map(name => stableClassName(name)) ?? [];
 
   return {