@astryxdesign/cli 0.1.1-canary.a514b99 → 0.1.1-canary.a7d67d0

package/src/codemods/transforms/v0.1.2/__tests__/rename-text-color-active-to-accent.test.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} =
+    await import('../rename-text-color-active-to-accent.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('rename-text-color-active-to-accent', () => {
+  it('renames Text color="active" to color="accent"', async () => {
+    const input = `<Text color="active">Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Heading color="active" to color="accent"', async () => {
+    const input = `<Heading level={2} color="active">Title</Heading>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Link color="active" to color="accent"', async () => {
+    const input = `<Link href="/x" color="active">Go</Link>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Timestamp color="active" to color="accent"', async () => {
+    const input = `<Timestamp value={d} color="active" />`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it("renames expression-container color={'active'}", async () => {
+    const input = `<Text color={'active'}>Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('renames active inside a ternary color expression', async () => {
+    const input = `<Text color={isOn ? 'active' : 'secondary'}>Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).toContain("'secondary'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('does not change other color values', async () => {
+    const input = `<Text color="secondary">Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch color="active" on non-target components', async () => {
+    const input = `<StatusDot color="active" />`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch unrelated "active" string literals', async () => {
+    const input = `const node = {id: 'active', label: 'Active Users'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch a status enum value named active', async () => {
+    const input = `const filters = {status: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames object color prop in files importing a target component', async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const cfg = {color: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("color: 'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it("renames color: 'active' as const in files importing a target component", async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const COLORS = [{color: 'active' as const, description: 'Accent'}];`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent' as const");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('does not rename object color prop when no target component is imported', async () => {
+    const input = `const cfg = {color: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames active in Storybook color argTypes options', async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const meta = {argTypes: {color: {control: 'select', options: ['primary', 'active', 'inherit']}}};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('returns undefined (no change) when nothing matches', async () => {
+    const input = `<Text color="primary">Hi</Text>`;
+    const output = await applyTransform(input);
+    // applyTransform falls back to source when transform returns undefined
+    expect(output).toBe(input);
+  });
+});

package/src/codemods/transforms/v0.1.2/index.mjs

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.2 transform manifest
+ *
+ * Lists all codemods for the v0.1.2 release in the order they should run.
+ */
+
+import renameTextColorActiveToAccent, {
+  meta as renameTextColorActiveToAccentMeta,
+} from './rename-text-color-active-to-accent.mjs';
+
+export default [
+  {
+    name: 'rename-text-color-active-to-accent',
+    transform: renameTextColorActiveToAccent,
+    meta: renameTextColorActiveToAccentMeta,
+  },
+];

package/src/codemods/transforms/v0.1.2/rename-text-color-active-to-accent.mjs

@@ -0,0 +1,136 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename Text/Heading/Link/Timestamp color "active" to "accent"
+ * @see https://github.com/facebook/astryx/issues/2863
+ *
+ * The `active` text-color value is renamed to `accent` and now maps to the
+ * dedicated `--color-text-accent` token (legible accent ink) instead of
+ * `--color-accent` (the interactive/base accent surface). This gives a
+ * first-class, type-safe way to render accent-colored text and resolves the
+ * gap reported in #2863.
+ *
+ * Transforms (scoped to Text, Heading, Link, and Timestamp):
+ * - <Text color="active" />            → <Text color="accent" />
+ * - <Heading color={'active'} />       → <Heading color={'accent'} />
+ * - <Text color={cond ? 'active' : x}> → <Text color={cond ? 'accent' : x}>
+ * - Storybook argTypes: color: { options: [..., 'active', ...] }
+ *     → replaces 'active' with 'accent' (files importing a target component)
+ * - Object properties: { color: 'active' } / { color: 'active' as const }
+ *     → { color: 'accent' } (files importing a target component)
+ *
+ * The transform deliberately does NOT touch bare `'active'` strings that are
+ * not a `color` value (e.g. status enums, ids, filter values), so it is safe
+ * to run across an entire codebase.
+ */
+
+export const meta = {
+  title: 'Rename Text/Heading/Link/Timestamp color "active" to "accent"',
+  description:
+    'Renames the `color="active"` value to `color="accent"` on Text, Heading, ' +
+    'Link, and Timestamp. The `accent` value maps to `--color-text-accent` ' +
+    '(the dedicated accent text ink). Also updates Storybook color argTypes ' +
+    'options and object-literal `color` props in files that import a target component.',
+  pr: '#2863',
+};
+
+const OLD_VALUE = 'active';
+const NEW_VALUE = 'accent';
+
+/** Components whose `color` prop accepts a TextColor value. */
+const TARGET_COMPONENTS = new Set(['Text', 'Heading', 'Link', 'Timestamp']);
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  /** Rewrite a string-literal node when it equals the old value. */
+  function renameStringLiteral(node) {
+    if (!node) return false;
+    if (
+      (node.type === 'StringLiteral' || node.type === 'Literal') &&
+      node.value === OLD_VALUE
+    ) {
+      node.value = NEW_VALUE;
+      if (node.raw) node.raw = `'${NEW_VALUE}'`;
+      return true;
+    }
+    return false;
+  }
+
+  /** Recursively rewrite the old value inside ternary/logical expressions. */
+  function renameInExpression(node) {
+    if (!node) return false;
+    let changed = false;
+    if (node.type === 'StringLiteral' || node.type === 'Literal') {
+      changed = renameStringLiteral(node) || changed;
+    } else if (node.type === 'ConditionalExpression') {
+      changed = renameInExpression(node.consequent) || changed;
+      changed = renameInExpression(node.alternate) || changed;
+    } else if (node.type === 'LogicalExpression') {
+      changed = renameInExpression(node.left) || changed;
+      changed = renameInExpression(node.right) || changed;
+    } else if (node.type === 'TSAsExpression') {
+      // `'active' as const` → rewrite the inner expression
+      changed = renameInExpression(node.expression) || changed;
+    }
+    return changed;
+  }
+
+  // --- 1. JSX attribute: color="active" / color={'active'} on target components ---
+  root.find(j.JSXOpeningElement).forEach(path => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !TARGET_COMPONENTS.has(componentName)) return;
+
+    path.node.attributes.forEach(attr => {
+      if (attr.type !== 'JSXAttribute') return;
+      if (!attr.name || attr.name.name !== 'color') return;
+
+      const value = attr.value;
+      if (!value) return;
+
+      if (value.type === 'StringLiteral' || value.type === 'Literal') {
+        if (renameStringLiteral(value)) hasChanges = true;
+      } else if (value.type === 'JSXExpressionContainer') {
+        if (renameInExpression(value.expression)) hasChanges = true;
+      }
+    });
+  });
+
+  // Object-property / argTypes transforms only run in files that use a target
+  // component — keeps unrelated `{ color: 'active' }` / `'active'` strings safe.
+  const importsTarget =
+    root
+      .find(j.ImportSpecifier)
+      .filter(p => TARGET_COMPONENTS.has(p.node.imported?.name))
+      .size() > 0;
+
+  if (importsTarget) {
+    const PropertyType = j.ObjectProperty ?? j.Property;
+
+    // --- 2. Object property: { color: 'active' } / { color: 'active' as const } ---
+    root.find(PropertyType, {key: {name: 'color'}}).forEach(path => {
+      if (renameInExpression(path.node.value)) hasChanges = true;
+    });
+
+    // --- 3. Storybook argTypes: color: { options: [..., 'active', ...] } ---
+    root.find(PropertyType, {key: {name: 'color'}}).forEach(path => {
+      const value = path.node.value;
+      if (!value || value.type !== 'ObjectExpression') return;
+
+      const optionsProp = value.properties.find(
+        p => p.key && (p.key.name === 'options' || p.key.value === 'options'),
+      );
+      if (optionsProp && optionsProp.value.type === 'ArrayExpression') {
+        optionsProp.value.elements.forEach(el => {
+          if (renameStringLiteral(el)) hasChanges = true;
+        });
+      }
+    });
+  }
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/src/commands/gap-report.mjs

@@ -132,7 +132,7 @@ export function registerGapReport(program) {
     .action(async () => {
       p.intro('Gap report setup');
 
-      const config = loadGapReportConfig();
+      const config = await loadGapReportConfig();
       const currentMode = !config.enabled
         ? 'disabled'
         : config.command
@@ -252,9 +252,14 @@ export function registerGapReport(program) {
         return;
       }
 
-      const config = loadGapReportConfig();
+      const config = await loadGapReportConfig();
       if (!config.enabled) {
-        if (json) return jsonError('Gap reporting is disabled', undefined, ERROR_CODES.ERR_GAP_REPORT_FAILED);
+        if (json)
+          return jsonError(
+            'Gap reporting is disabled',
+            undefined,
+            ERROR_CODES.ERR_GAP_REPORT_FAILED,
+          );
         humanLog(
           `Gap reporting is disabled (ASTRYX_GAP_REPORT=off or astryx.config.mjs).\n` +
             `Run \`${getRunPrefix()} astryx gap-report setup\` to configure.`,
@@ -295,7 +300,7 @@ export function registerGapReport(program) {
           return;
         }
 
-        const preview = buildGapReportPreview({
+        const preview = await buildGapReportPreview({
           component: options.component,
           category: options.category,
           intention: options.reason,
@@ -326,7 +331,7 @@ export function registerGapReport(program) {
         }
 
         try {
-          const url = createGapReport({
+          const url = await createGapReport({
             component: options.component,
             category: options.category,
             intention: options.reason,
@@ -343,7 +348,9 @@ export function registerGapReport(program) {
             humanLog('\nGap reporting is disabled via configuration.\n');
           }
         } catch (err) {
-          cliError(`Filing gap report failed: ${err.message}`, {code: ERROR_CODES.ERR_GAP_REPORT_FAILED});
+          cliError(`Filing gap report failed: ${err.message}`, {
+            code: ERROR_CODES.ERR_GAP_REPORT_FAILED,
+          });
           return;
         }
         return;
@@ -386,7 +393,8 @@ export function registerGapReport(program) {
           placeholder:
             'e.g. "Need a compact variant for use in dense data tables"',
           validate: val => {
-            if (!val.trim()) return 'Please describe what you were trying to do';
+            if (!val.trim())
+              return 'Please describe what you were trying to do';
           },
         }),
       );
@@ -406,7 +414,7 @@ export function registerGapReport(program) {
         source: 'interactive',
       };
 
-      const preview = buildGapReportPreview(previewArgs);
+      const preview = await buildGapReportPreview(previewArgs);
 
       // Always show the user exactly what would be filed before sending.
       p.note(
@@ -440,7 +448,7 @@ export function registerGapReport(program) {
       s.start('Filing gap report');
 
       try {
-        const url = createGapReport(previewArgs);
+        const url = await createGapReport(previewArgs);
         s.stop(url ? 'Gap report filed' : 'Gap reporting is disabled');
         if (url) {
           p.log.success(url);

package/src/commands/gap-report.test.mjs

@@ -40,9 +40,9 @@ describe('shouldActuallyFile', () => {
   });
 
   it('--dry-run wins over --commit (safety)', () => {
-    expect(
-      shouldActuallyFile({isTTY: true, commit: true, dryRun: true}),
-    ).toBe(false);
+    expect(shouldActuallyFile({isTTY: true, commit: true, dryRun: true})).toBe(
+      false,
+    );
   });
 });
 
@@ -54,7 +54,9 @@ describe('formatPreview', () => {
       title: '[gap] Button: missing compact variant',
       body: '## User Intention\n\nNeed a compact variant',
     });
-    expect(out).toContain('Would file GitHub issue on facebookexperimental/xds');
+    expect(out).toContain(
+      'Would file GitHub issue on facebookexperimental/xds',
+    );
     expect(out).toContain('[gap] Button');
     expect(out).toContain('Need a compact variant');
     expect(out).toContain('Labels: gap-report');
@@ -91,13 +93,14 @@ describe('ASTRYX_GAP_REPORT=off env var', () => {
   it('disables gap reporting when set to "off"', async () => {
     process.env.ASTRYX_GAP_REPORT = 'off';
     vi.resetModules();
-    const {loadGapReportConfig, createGapReport} = await import(
-      '../utils/github.mjs'
-    );
-    expect(loadGapReportConfig().enabled).toBe(false);
+    const {loadGapReportConfig, createGapReport} =
+      await import('../utils/github.mjs');
+    await expect(loadGapReportConfig()).resolves.toMatchObject({
+      enabled: false,
+    });
 
     // createGapReport must return null and never invoke gh.
-    const result = createGapReport({
+    const result = await createGapReport({
       component: 'Button',
       category: 'other',
       intention: 'test',
@@ -109,12 +112,16 @@ describe('ASTRYX_GAP_REPORT=off env var', () => {
     process.env.ASTRYX_GAP_REPORT = 'false';
     vi.resetModules();
     let mod = await import('../utils/github.mjs');
-    expect(mod.loadGapReportConfig().enabled).toBe(false);
+    await expect(mod.loadGapReportConfig()).resolves.toMatchObject({
+      enabled: false,
+    });
 
     process.env.ASTRYX_GAP_REPORT = '0';
     vi.resetModules();
     mod = await import('../utils/github.mjs');
-    expect(mod.loadGapReportConfig().enabled).toBe(false);
+    await expect(mod.loadGapReportConfig()).resolves.toMatchObject({
+      enabled: false,
+    });
   });
 });
 
@@ -133,16 +140,14 @@ describe('buildGapReportPreview', () => {
   it('renders title and body without invoking gh', async () => {
     vi.resetModules();
     const {buildGapReportPreview} = await import('../utils/github.mjs');
-    const preview = buildGapReportPreview({
+    const preview = await buildGapReportPreview({
       component: 'Button',
       category: 'missing_variant',
       intention: 'Need compact variant for tables',
     });
     expect(preview.mode).toBe('github');
     expect(preview.enabled).toBe(true);
-    expect(preview.title).toBe(
-      '[gap] Button: Need compact variant for tables',
-    );
+    expect(preview.title).toBe('[gap] Button: Need compact variant for tables');
     expect(preview.body).toContain('| **Component** | Button |');
     expect(preview.body).toContain('Need compact variant for tables');
     expect(preview.repo).toBe('facebookexperimental/xds');
@@ -152,7 +157,7 @@ describe('buildGapReportPreview', () => {
     process.env.ASTRYX_GAP_REPORT = 'off';
     vi.resetModules();
     const {buildGapReportPreview} = await import('../utils/github.mjs');
-    const preview = buildGapReportPreview({
+    const preview = await buildGapReportPreview({
       component: 'Button',
       category: 'other',
       intention: 'x',

package/src/commands/init.mjs

@@ -29,6 +29,37 @@ import {requireInteractive} from '../utils/interactive.mjs';
 const VALID_FEATURES = ['agents', 'theme', 'template'];
 const run = getRunPrefix();
 
+/**
+ * Build the "Next steps" lines printed at the end of `astryx init`.
+ *
+ * Theme guidance must match the runtime recommendation emitted by core's
+ * <Theme> component (packages/core/src/theme/Theme.tsx): the pre-built theme
+ * path (`/built` import + `theme.css`) plus the base CSS import, so users
+ * don't end up with an unstyled app or the slower runtime style-injection
+ * path. See https://github.com/facebook/astryx/issues/3080.
+ *
+ * Exported for testing.
+ *
+ * @param {string} runPrefix package-manager run prefix (e.g. `npx`)
+ * @returns {string[]} ordered list of human-facing lines
+ */
+export function getNextSteps(runPrefix) {
+  return [
+    '',
+    '  Next steps:',
+    "    1. Import base styles: import '@astryxdesign/core/reset.css'",
+    "       and import '@astryxdesign/core/astryx.css'",
+    "    2. Import components: import { Button } from '@astryxdesign/core'",
+    '    3. Optionally add a theme (use the pre-built path for performance):',
+    "       import { neutralTheme } from '@astryxdesign/theme-neutral/built'",
+    "       import '@astryxdesign/theme-neutral/theme.css'",
+    '       <Theme theme={neutralTheme}>...</Theme>',
+    `       For custom themes, run \`${runPrefix} astryx theme build <file>\` to generate the built artifacts.`,
+    `    4. ${runPrefix} astryx --help for all commands`,
+    '',
+  ];
+}
+
 function isCancel(value) {
   if (p.isCancel(value)) {
     p.cancel('Setup cancelled.');
@@ -250,13 +281,8 @@ export function registerInit(program) {
       // Outro
       p.outro('Design system initialized!');
 
-      humanLog('');
-      humanLog('  Next steps:');
-      humanLog("    1. Import components: import { Button } from '@astryxdesign/core'");
-      humanLog('    2. Optionally add a theme:');
-      humanLog("       import { neutralTheme } from '@astryxdesign/theme-neutral'");
-      humanLog('       <Theme theme={neutralTheme}>...</Theme>');
-      humanLog(`    3. ${run} astryx --help for all commands`);
-      humanLog('');
+      for (const line of getNextSteps(run)) {
+        humanLog(line);
+      }
     });
 }

package/src/commands/init.next-steps.test.mjs

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for `astryx init` "Next steps" theme guidance.
+ *
+ * The init command previously steered users toward the slower runtime
+ * style-injection path:
+ *
+ *   import { neutralTheme } from '@astryxdesign/theme-neutral'
+ *   <Theme theme={neutralTheme}>...</Theme>
+ *
+ * ...which contradicted the runtime console warning emitted by core's
+ * <Theme> component (packages/core/src/theme/Theme.tsx) recommending the
+ * pre-built path, and left users with an unstyled app because the base CSS
+ * imports were never mentioned (facebook/astryx#3080).
+ *
+ * These assertions lock in the corrected guidance: base CSS imports, the
+ * pre-built (`/built` + `theme.css`) theme path, and the custom-theme build
+ * command.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {getNextSteps} from './init.mjs';
+
+describe('init Next steps theme guidance', () => {
+  const text = getNextSteps('npx').join('\n');
+
+  it('mentions the base CSS imports so the app is not left unstyled', () => {
+    expect(text).toContain("'@astryxdesign/core/reset.css'");
+    expect(text).toContain("'@astryxdesign/core/astryx.css'");
+  });
+
+  it('uses the pre-built theme path matching the runtime recommendation', () => {
+    expect(text).toContain("'@astryxdesign/theme-neutral/built'");
+    expect(text).toContain("'@astryxdesign/theme-neutral/theme.css'");
+  });
+
+  it('mentions building custom themes via `astryx theme build`', () => {
+    expect(text).toContain('astryx theme build <file>');
+  });
+
+  it('does not steer users to the runtime style-injection import', () => {
+    // The bare source import (no `/built`) is the slow runtime-injection path.
+    expect(text).not.toContain("from '@astryxdesign/theme-neutral'");
+  });
+});