@astryxdesign/cli 0.2.0 → 0.3.0

package/assets/codemods/transforms/v0.0.15/migrate-theme-selectors-to-data-attrs.mjs

@@ -0,0 +1,239 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate legacy bare XDS theme selectors to data attributes.
+ *
+ * Converts selectors like:
+ *   .xds-button.primary.sm:hover
+ * to:
+ *   .xds-button[data-variant="primary"][data-size="sm"]:hover
+ *
+ * The transform is intentionally conservative: it only rewrites component/value
+ * pairs where the prop/state axis is known. Unknown component classes and
+ * ambiguous values are left unchanged.
+ */
+
+export const meta = {
+  title: 'Migrate XDS theme selectors to data attributes',
+  description:
+    'Rewrites legacy bare prop/state class selectors such as `.xds-button.primary` ' +
+    'to preferred data-attribute selectors such as `.xds-button[data-variant="primary"]`.',
+  fileExtensions: [
+    '.css',
+    '.scss',
+    '.sass',
+    '.less',
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+  ],
+};
+
+const COLOR_VALUES = new Set([
+  'primary',
+  'secondary',
+  'disabled',
+  'placeholder',
+  'active',
+  'accent',
+  'success',
+  'warning',
+  'error',
+  'info',
+  'neutral',
+  'red',
+  'orange',
+  'yellow',
+  'green',
+  'teal',
+  'cyan',
+  'blue',
+  'purple',
+  'pink',
+  'gray',
+]);
+
+const STATE_VALUES = new Set([
+  'active',
+  'checked',
+  'disabled',
+  'expanded',
+  'focused',
+  'hidden',
+  'indeterminate',
+  'invalid',
+  'open',
+  'pressed',
+  'selected',
+  'today',
+  'visible',
+]);
+
+const STATUS_VALUES = new Set([
+  'info',
+  'neutral',
+  'success',
+  'warning',
+  'error',
+]);
+const SIZE_VALUES = new Set([
+  'xs',
+  'sm',
+  'md',
+  'lg',
+  'xl',
+  'small',
+  'medium',
+  'large',
+]);
+const TEXT_TYPES = new Set([
+  'body',
+  'large',
+  'label',
+  'code',
+  'supporting',
+  'display-1',
+  'display-2',
+  'display-3',
+]);
+const APP_SHELL_VARIANTS = new Set(['wash', 'surface', 'section', 'elevated']);
+const SECTION_VARIANTS = new Set(['section', 'transparent', 'muted']);
+const DIVIDER_VARIANTS = new Set(['subtle', 'strong']);
+const ORIENTATIONS = new Set(['horizontal', 'vertical']);
+
+function attr(/** @type {any} */ name, /** @type {any} */ value) {
+  return `[data-${name}="${value}"]`;
+}
+
+function valueToAttr(/** @type {any} */ component, /** @type {any} */ value) {
+  // Numeric-prefixed classes emitted as prop-value (level-2, gap-4, cols-3).
+  let match = value.match(/^level-(\d+)$/);
+  if (match) return attr('level', match[1]);
+
+  match = value.match(/^gap-(\d+(?:-\d+)?)$/);
+  if (match) return attr('gap', match[1].replace('-', '.'));
+
+  match = value.match(/^(?:columns|cols)-(\d+)$/);
+  if (match) return attr('columns', match[1]);
+
+  switch (component) {
+    case 'xds-button':
+      if (SIZE_VALUES.has(value)) return attr('size', value);
+      // Button variants are extensible, so unknown non-size values are most
+      // likely custom variants.
+      return attr('variant', value);
+
+    case 'xds-badge':
+    case 'xds-statusdot':
+    case 'xds-avatar-status-dot':
+    case 'xds-card':
+    case 'xds-clickable-card':
+      return attr('variant', value);
+
+    case 'xds-app-shell':
+    case 'xds-app-shell-header':
+    case 'xds-app-shell-sidenav':
+      if (APP_SHELL_VARIANTS.has(value)) return attr('variant', value);
+      return null;
+
+    case 'xds-section':
+      if (SECTION_VARIANTS.has(value)) return attr('variant', value);
+      return null;
+
+    case 'xds-heading':
+      if (TEXT_TYPES.has(value)) return attr('type', value);
+      if (COLOR_VALUES.has(value)) return attr('color', value);
+      return null;
+
+    case 'xds-text':
+      if (TEXT_TYPES.has(value)) return attr('type', value);
+      if (COLOR_VALUES.has(value)) return attr('color', value);
+      return null;
+
+    case 'xds-link':
+      if (COLOR_VALUES.has(value)) return attr('color', value);
+      return null;
+
+    case 'xds-icon':
+      if (SIZE_VALUES.has(value)) return attr('size', value);
+      if (COLOR_VALUES.has(value)) return attr('color', value);
+      return null;
+
+    case 'xds-divider':
+      if (DIVIDER_VARIANTS.has(value)) return attr('variant', value);
+      if (ORIENTATIONS.has(value)) return attr('orientation', value);
+      return null;
+
+    case 'xds-stack':
+      if (ORIENTATIONS.has(value)) return attr('direction', value);
+      if (value === 'wrap' || value === 'nowrap') return attr('wrap', value);
+      return null;
+
+    case 'xds-grid':
+      if (['start', 'center', 'end', 'stretch'].includes(value))
+        return attr('align', value);
+      return null;
+
+    case 'xds-banner':
+    case 'xds-banner-icon':
+    case 'xds-banner-content':
+      if (STATUS_VALUES.has(value)) return attr('status', value);
+      if (['card', 'inline'].includes(value)) return attr('container', value);
+      return null;
+
+    case 'xds-spinner':
+      if (SIZE_VALUES.has(value)) return attr('size', value);
+      if (['default', 'onMedia', 'subtle'].includes(value))
+        return attr('shade', value);
+      return null;
+
+    case 'xds-progressbar':
+    case 'xds-progressbar-fill':
+      if (STATUS_VALUES.has(value) || value === 'accent')
+        return attr('variant', value);
+      return null;
+
+    case 'xds-tab':
+    case 'xds-side-nav-item':
+    case 'xds-segmented-control-item':
+    case 'xds-switch':
+      if (STATE_VALUES.has(value)) return attr(value, value);
+      return null;
+
+    default:
+      if (STATE_VALUES.has(value)) return attr(value, value);
+      return null;
+  }
+}
+
+const SELECTOR_RE = /\.((?:xds-[a-z0-9-]+))(\.(?:-?[_a-zA-Z][_a-zA-Z0-9-]*))+/g;
+
+export function migrateThemeSelectors(/** @type {any} */ source) {
+  return source.replace(SELECTOR_RE, (/** @type {any} */ full, /** @type {any} */ component) => {
+    const classChain = full.slice(component.length + 1);
+    const values = classChain.split('.').filter(Boolean);
+
+    const attrs = [];
+    for (const value of values) {
+      // Preserve additional xds-* classes; those are not bare variant/state values.
+      if (value.startsWith('xds-')) return full;
+      const converted = valueToAttr(component, value);
+      if (!converted) return full;
+      attrs.push(converted);
+    }
+
+    return `.${component}${attrs.join('')}`;
+  });
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file) {
+  const result = migrateThemeSelectors(file.source);
+  return result === file.source ? undefined : result;
+}

package/assets/codemods/transforms/v0.0.15/rename-date-picker-to-input.mjs

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename DateTimePicker → DateTimeInput, DateRangePicker → DateRangeInput
+ *
+ * Renames components, types, and import paths for consistency with other
+ * input components (DateInput, TextInput, NumberInput).
+ *
+ * Handles:
+ * 1. Import source paths: '@xds/core/DateTimePicker' → '@xds/core/DateTimeInput'
+ * 2. Named imports/exports: XDSDateTimePicker → XDSDateTimeInput, etc.
+ * 3. JSX element names: <XDSDateTimePicker /> → <XDSDateTimeInput />
+ * 4. Type references: XDSDateTimePickerProps → XDSDateTimeInputProps, etc.
+ * 5. displayName strings
+ */
+
+export const meta = {
+  title: 'Rename DateTimePicker/DateRangePicker → DateTimeInput/DateRangeInput',
+  description:
+    'Renames `XDSDateTimePicker` to `XDSDateTimeInput` and `XDSDateRangePicker` to `XDSDateRangeInput`, ' +
+    'including props types, import paths, and JSX usage.',
+};
+
+const IMPORT_PATH_RENAMES = new Map([
+  ['@xds/core/DateTimePicker', '@xds/core/DateTimeInput'],
+  ['@xds/core/DateRangePicker', '@xds/core/DateRangeInput'],
+]);
+
+const IDENTIFIER_RENAMES = new Map([
+  // Components
+  ['XDSDateTimePicker', 'XDSDateTimeInput'],
+  ['XDSDateRangePicker', 'XDSDateRangeInput'],
+  // Props types
+  ['XDSDateTimePickerProps', 'XDSDateTimeInputProps'],
+  ['XDSDateRangePickerProps', 'XDSDateRangeInputProps'],
+  // Size types
+  ['XDSDateTimePickerSize', 'XDSDateTimeInputSize'],
+  ['XDSDateRangePickerSize', 'XDSDateRangeInputSize'],
+  // Hour format type
+  ['XDSDateTimePickerHourFormat', 'XDSDateTimeInputHourFormat'],
+  // Status types
+  ['XDSDateTimePickerStatus', 'XDSDateTimeInputStatus'],
+  ['XDSDateTimePickerStatusType', 'XDSDateTimeInputStatusType'],
+  ['XDSDateRangePickerStatus', 'XDSDateRangeInputStatus'],
+  ['XDSDateRangePickerStatusType', 'XDSDateRangeInputStatusType'],
+]);
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // 1. Rename import/export source paths
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    const source = path.node.source.value;
+    const renamed = IMPORT_PATH_RENAMES.get(source);
+    if (renamed) {
+      path.node.source.value = renamed;
+      hasChanges = true;
+    }
+  });
+
+  root.find(j.ExportNamedDeclaration).forEach((/** @type {any} */ path) => {
+    if (path.node.source) {
+      const source = path.node.source.value;
+      const renamed = IMPORT_PATH_RENAMES.get(source);
+      if (renamed) {
+        path.node.source.value = renamed;
+        hasChanges = true;
+      }
+    }
+  });
+
+  // 2. Rename all identifiers (covers imports, type refs, variable names)
+  root.find(j.Identifier).forEach((/** @type {any} */ path) => {
+    const renamed = IDENTIFIER_RENAMES.get(path.node.name);
+    if (renamed) {
+      path.node.name = renamed;
+      hasChanges = true;
+    }
+  });
+
+  // 3. Rename JSX element names
+  root.find(j.JSXIdentifier).forEach((/** @type {any} */ path) => {
+    const renamed = IDENTIFIER_RENAMES.get(path.node.name);
+    if (renamed) {
+      path.node.name = renamed;
+      hasChanges = true;
+    }
+  });
+
+  // 4. Rename string literals (covers displayName assignments)
+  root.find(j.StringLiteral).forEach((/** @type {any} */ path) => {
+    const renamed = IDENTIFIER_RENAMES.get(path.node.value);
+    if (renamed) {
+      path.node.value = renamed;
+      hasChanges = true;
+    }
+  });
+
+  // Also handle Literal nodes (parser-dependent)
+  root.find(j.Literal).forEach((/** @type {any} */ path) => {
+    if (typeof path.node.value === 'string') {
+      const renamed = IDENTIFIER_RENAMES.get(path.node.value);
+      if (renamed) {
+        path.node.value = renamed;
+        if (path.node.raw) path.node.raw = undefined;
+        hasChanges = true;
+      }
+    }
+  });
+
+  return hasChanges ? root.toSource() : undefined;
+}

package/assets/codemods/transforms/v0.0.15/rename-imperative-ref-to-handleRef.mjs

@@ -0,0 +1,72 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename imperative ref props to handleRef
+ *
+ * XDS components reserve `ref` for DOM elements. Components with imperative
+ * handles now expose those handles through `handleRef`.
+ *
+ * Handles:
+ * - JSX prop: `ref` → `handleRef` on XDSCalendar, XDSChatComposerInput,
+ *   XDSPowerSearch, XDSTokenizer, and XDSChartStreamGL
+ * - JSX prop: `sideNavRef` → `handleRef` on XDSSideNavCollapseButton
+ */
+
+export const meta = {
+  title: 'Rename imperative ref props to handleRef',
+  description:
+    'Renames imperative `ref` usages to `handleRef` on components whose ' +
+    '`ref` prop now points at the root DOM element. Also renames ' +
+    '`XDSSideNavCollapseButton` `sideNavRef` to `handleRef`.',
+  issue: '#2359',
+};
+
+const IMPERATIVE_REF_COMPONENTS = new Set([
+  'XDSCalendar',
+  'XDSChatComposerInput',
+  'XDSPowerSearch',
+  'XDSTokenizer',
+  'XDSChartStreamGL',
+]);
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (componentName == null) return;
+
+    for (const attr of path.node.attributes) {
+      if (attr.type !== 'JSXAttribute') continue;
+
+      if (
+        IMPERATIVE_REF_COMPONENTS.has(componentName) &&
+        attr.name?.type === 'JSXIdentifier' &&
+        attr.name.name === 'ref'
+      ) {
+        attr.name.name = 'handleRef';
+        hasChanges = true;
+      }
+
+      if (
+        componentName === 'XDSSideNavCollapseButton' &&
+        attr.name?.type === 'JSXIdentifier' &&
+        attr.name.name === 'sideNavRef'
+      ) {
+        attr.name.name = 'handleRef';
+        hasChanges = true;
+      }
+    }
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/assets/codemods/transforms/v0.0.15/rename-isStreaming-to-isStopShown.mjs

@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename isStreaming → isStopShown on XDSChatComposer and XDSChatSendButton
+ *
+ * The `isStreaming` prop on chat components was too narrow — it implied only
+ * text streaming, but it actually controls whether the stop button is shown.
+ * Renamed to `isStopShown` for clarity.
+ *
+ * Handles:
+ * - JSX prop: `isStreaming` → `isStopShown` on XDSChatComposer and XDSChatSendButton
+ *
+ * Does NOT rename:
+ * - `isStreaming` on other components (XDSMarkdown, XDSChatReasoning)
+ * - Local variables, object properties, or state named `isStreaming`
+ */
+
+export const meta = {
+  title: 'Rename ChatComposer/ChatSendButton isStreaming to isStopShown',
+  description:
+    'Renames the `isStreaming` prop to `isStopShown` on `XDSChatComposer` and ' +
+    '`XDSChatSendButton`. The prop controls whether the stop button is shown — ' +
+    'the new name describes the affordance rather than implying a streaming state.',
+  issue: '#2328',
+};
+
+const TARGET_COMPONENTS = new Set(['XDSChatComposer', 'XDSChatSendButton']);
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // Rename JSX prop on target components only
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!TARGET_COMPONENTS.has(componentName)) return;
+
+    const attrs = path.node.attributes;
+    for (const attr of attrs) {
+      if (attr.type === 'JSXAttribute' && attr.name?.name === 'isStreaming') {
+        attr.name.name = 'isStopShown';
+        hasChanges = true;
+      }
+    }
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/assets/codemods/transforms/v0.0.15/rename-stack-element-to-as.mjs

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename `element` prop to `as` on Stack components
+ */
+
+export const meta = {
+  title: 'Rename element → as on Stack components',
+  description:
+    'Renames the `element` prop to `as` on XDSStack, XDSHStack, XDSVStack, and XDSStackItem for consistency with other polymorphic components.',
+};
+
+const TARGET_COMPONENTS = new Set([
+  'XDSStack',
+  'XDSHStack',
+  'XDSVStack',
+  'XDSStackItem',
+]);
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  root
+    .find(j.JSXOpeningElement)
+    .filter((/** @type {any} */ path) => {
+      const name = path.node.name;
+      return name.type === 'JSXIdentifier' && TARGET_COMPONENTS.has(name.name);
+    })
+    .forEach((/** @type {any} */ path) => {
+      path.node.attributes.forEach((/** @type {any} */ attr) => {
+        if (attr.type === 'JSXAttribute' && attr.name.name === 'element') {
+          attr.name.name = 'as';
+          hasChanges = true;
+        }
+      });
+    });
+
+  return hasChanges ? root.toSource({quote: 'single'}) : undefined;
+}