@staffbase/design 18.8.0 → 19.0.0

package/codemods/v19-migrate-button/README.md

@@ -0,0 +1,94 @@
+# v19 — Migrate to the new Button
+
+This codemod automatically migrates your code from the four deprecated button components in `@staffbase/design` v18 to the new unified `Button` in v19.
+
+## What it transforms
+
+| Before (v18)                        | After (v19)                                       |
+| ----------------------------------- | ------------------------------------------------- |
+| `<Button variant="primary">`        | `<Button>`                                        |
+| `<Button variant="secondary">`      | `<Button color="neutral">`                        |
+| `<Button variant="critical">`       | `<Button color="critical">`                       |
+| `<GhostButton variant="primary">`   | `<Button variant="ghost">`                        |
+| `<GhostButton variant="secondary">` | `<Button variant="ghost" color="neutral">`        |
+| `<IconButton icon={<X />} />`       | `<Button iconOnly><X /></Button>`                 |
+| `<IconGhostButton icon={<X />} />`  | `<Button variant="ghost" iconOnly><X /></Button>` |
+| `<ButtonDeprecated …>`              | `<Button …>`                                      |
+
+**Icon props are moved into children:**
+
+```tsx
+// Before
+<Button icon={<SaveIcon />} iconPosition="leading">Save</Button>
+
+// After
+<Button><SaveIcon />Save</Button>
+```
+
+```tsx
+// Before
+<GhostButton icon={<ShareIcon />} iconPosition="trailing">Share</GhostButton>
+
+// After
+<Button variant="ghost">Share<ShareIcon /></Button>
+```
+
+**Imports are updated automatically:**
+
+```tsx
+// Before
+import {Button, GhostButton, IconButton, IconGhostButton} from '@staffbase/design';
+
+// After
+import {Button} from '@staffbase/design';
+```
+
+## Usage
+
+### Step 1 — Install jscodeshift
+
+```bash
+npm install --save-dev jscodeshift
+# or
+pnpm add -D jscodeshift
+```
+
+### Step 2 — Run the codemod
+
+Point the `--transform` flag at this file inside your `node_modules`:
+
+```bash
+npx jscodeshift@latest \
+  --transform node_modules/@staffbase/design/codemods/v19-migrate-button/transform.js \
+  --extensions tsx,ts \
+  --parser tsx \
+  src/
+```
+
+Run a **dry run** first to preview changes without writing files:
+
+```bash
+npx jscodeshift@latest \
+  --transform node_modules/@staffbase/design/codemods/v19-migrate-button/transform.js \
+  --extensions tsx,ts \
+  --parser tsx \
+  --dry \
+  --print \
+  src/
+```
+
+### Step 3 — Review and commit
+
+1. Run your type-checker to catch anything the codemod couldn't handle statically:
+   ```bash
+   npx tsc --noEmit
+   ```
+2. Run your tests.
+3. Commit the result.
+
+## What the codemod does NOT handle
+
+- **Dynamic `variant` expressions** — e.g. `variant={someVariable}`. The original `variant` prop is preserved so TypeScript will surface a type error at that location. Update these manually.
+- **Spread props** — e.g. `<Button {...buttonProps} />`. The spread is preserved; if `buttonProps` contains old-style variant/icon fields those object shapes need updating manually.
+- **Type annotations** — `ButtonDeprecatedProps`, `GhostButtonProps`, etc. are removed from imports. If you use these types in your own interfaces or function signatures, TypeScript errors will point you to the right places.
+- **Non-JSX prop passing** — e.g. `React.createElement(Button, {variant: 'secondary'})`. Only JSX syntax is transformed.

package/codemods/v19-migrate-button/transform.js

@@ -0,0 +1,277 @@
+/**
+ * Jscodeshift codemod: Migrate deprecated Button components to the new unified Button.
+ *
+ * Transforms:
+ *   Button (old)      → Button (new API)
+ *   ButtonDeprecated  → Button (new API)
+ *   GhostButton       → Button variant="ghost"
+ *   IconButton        → Button iconOnly
+ *   IconGhostButton   → Button variant="ghost" iconOnly
+ *
+ * Old variant prop mapping:
+ *   variant="primary"   → (omit – default)
+ *   variant="secondary" → color="neutral"
+ *   variant="critical"  → color="critical"
+ *
+ * Old icon/iconPosition props are moved into children:
+ *   icon={<X />} iconPosition="leading"  → <Button><X />text</Button>
+ *   icon={<X />} iconPosition="trailing" → <Button>text<X /></Button>
+ *
+ * Usage:
+ *   npx jscodeshift@latest \
+ *     --transform node_modules/@staffbase/design/codemods/v19-migrate-button/transform.js \
+ *     --extensions tsx,ts \
+ *     --parser tsx \
+ *     src/
+ */
+
+const DESIGN_PKG = '@staffbase/design';
+
+// Each deprecated component and how it maps to the new Button.
+const DEPRECATED = {
+  /** Old solid Button. Only transformed when old-style props are detected. */
+  Button: {},
+  ButtonDeprecated: {},
+  GhostButton: {addVariant: 'ghost'},
+  IconButton: {addIconOnly: true, iconContentOnly: true},
+  IconGhostButton: {addVariant: 'ghost', addIconOnly: true, iconContentOnly: true},
+};
+
+// Old variant value → new color value. null = default primary, omit the prop.
+const VARIANT_TO_COLOR = {
+  primary: null,
+  secondary: 'neutral',
+  critical: 'critical',
+};
+
+// Presence of any of these props on <Button> indicates v18 API usage.
+const OLD_API_PROPS = new Set(['icon', 'iconPosition']);
+const OLD_API_VARIANT_VALUES = new Set(['primary', 'secondary', 'critical']);
+
+// ── Entry point ──────────────────────────────────────────────────────────────
+
+export default function transform(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let dirty = false;
+
+  // 1. Find @staffbase/design import.
+  const designImports = root.find(j.ImportDeclaration, {source: {value: DESIGN_PKG}});
+  if (!designImports.length) return undefined;
+
+  // 2. Collect deprecated component imports: localName → { importedName, config }
+  const deprecated = new Map();
+  let buttonAlreadyImported = false;
+
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    const importedName = spec.node.imported.name;
+    const localName = spec.node.local ? spec.node.local.name : importedName;
+    const config = DEPRECATED[importedName];
+
+    if (config !== undefined) {
+      deprecated.set(localName, {importedName, config});
+    } else if (importedName === 'Button') {
+      buttonAlreadyImported = true;
+    }
+  });
+
+  if (!deprecated.size) return undefined;
+
+  // 3. Transform JSX usages.
+  deprecated.forEach(({importedName, config}, localName) => {
+    root.find(j.JSXElement, {openingElement: {name: {name: localName}}}).forEach((path) => {
+      if (migrateElement(j, path, importedName, config)) dirty = true;
+    });
+  });
+
+  if (!dirty) return undefined;
+
+  // 4. Update import specifiers.
+  //    Remove deprecated ones (except old "Button" which maps to the new Button).
+  const toRemove = new Set();
+  deprecated.forEach(({importedName}) => {
+    if (importedName !== 'Button') toRemove.add(importedName);
+  });
+
+  if (toRemove.size) {
+    designImports.find(j.ImportSpecifier).forEach((spec) => {
+      if (toRemove.has(spec.node.imported.name)) j(spec).remove();
+    });
+  }
+
+  // Add Button specifier if none of the migrated components already provide it.
+  const buttonWasMigrated = deprecated.has('Button') || deprecated.has('ButtonDeprecated');
+  if (!buttonAlreadyImported && !buttonWasMigrated) {
+    designImports.get().node.specifiers.push(j.importSpecifier(j.identifier('Button')));
+  }
+
+  // 5. Remove type imports for deprecated types (TypeScript projects).
+  const deprecatedTypes = new Set([
+    'ButtonDeprecatedProps',
+    'BaseButtonProps',
+    'ButtonVariant',
+    'ButtonIconPosition',
+    'GhostButtonProps',
+    'BaseGhostButtonProps',
+    'GhostButtonVariant',
+    'GhostButtonIconPosition',
+    'IconGhostButtonProps',
+    'IconButtonProps',
+  ]);
+
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    if (deprecatedTypes.has(spec.node.imported.name)) j(spec).remove();
+  });
+
+  return root.toSource({quote: 'single'});
+}
+
+// ── Element migration ────────────────────────────────────────────────────────
+
+function migrateElement(j, path, importedName, config) {
+  const {openingElement, closingElement} = path.node;
+  const existingAttrs = openingElement.attributes;
+
+  // For the old solid `Button`, only migrate if old-style props are present.
+  // This avoids touching any usages that are already on the new API.
+  if (importedName === 'Button') {
+    const hasOldStyleProps = existingAttrs.some((attr) => {
+      if (attr.type !== 'JSXAttribute') return false;
+      const name = attr.name.name;
+      if (OLD_API_PROPS.has(name)) return true;
+      if (name === 'variant') {
+        const val = getStringValue(attr.value);
+        return val !== null && OLD_API_VARIANT_VALUES.has(val);
+      }
+      return false;
+    });
+    if (!hasOldStyleProps) return false;
+  }
+
+  // Index attributes by name.
+  const attrByName = new Map();
+  const spreadAttrs = [];
+
+  for (const attr of existingAttrs) {
+    if (attr.type === 'JSXSpreadAttribute') {
+      spreadAttrs.push(attr);
+    } else {
+      attrByName.set(attr.name.name, attr);
+    }
+  }
+
+  const variantAttr = attrByName.get('variant');
+  const iconAttr = attrByName.get('icon');
+  const iconPositionAttr = attrByName.get('iconPosition');
+
+  // Resolve new color prop.
+  let newColor = null; // null = use default primary, omit prop
+  let dynamicVariant = false;
+
+  if (variantAttr) {
+    const staticVal = getStringValue(variantAttr.value);
+    if (staticVal !== null && Object.prototype.hasOwnProperty.call(VARIANT_TO_COLOR, staticVal)) {
+      newColor = VARIANT_TO_COLOR[staticVal];
+    } else if (variantAttr.value && variantAttr.value.type === 'JSXExpressionContainer') {
+      // Dynamic variant — preserve the original attr and let TypeScript surface the error.
+      dynamicVariant = true;
+    }
+  }
+
+  // Resolve icon placement.
+  const iconPosition =
+    getStringValue(iconPositionAttr ? iconPositionAttr.value : null) === 'trailing' ? 'trailing' : 'leading';
+
+  // Build new attribute list.
+  const newAttrs = [];
+
+  if (config.addVariant) {
+    newAttrs.push(j.jsxAttribute(j.jsxIdentifier('variant'), j.stringLiteral(config.addVariant)));
+  }
+
+  if (newColor) {
+    newAttrs.push(j.jsxAttribute(j.jsxIdentifier('color'), j.stringLiteral(newColor)));
+  }
+
+  if (config.addIconOnly) {
+    newAttrs.push(j.jsxAttribute(j.jsxIdentifier('iconOnly'), null));
+  }
+
+  // Pass all other props through unchanged.
+  const DROP = new Set(['variant', 'icon', 'iconPosition']);
+  for (const [name, attr] of attrByName) {
+    if (!DROP.has(name)) newAttrs.push(attr);
+  }
+
+  // Preserve spread attributes.
+  newAttrs.push(...spreadAttrs);
+
+  // Dynamic variant: keep the original attr so TS surfaces the error to the developer.
+  if (dynamicVariant && variantAttr) newAttrs.push(variantAttr);
+
+  // Build new children.
+  let newChildren = [...path.node.children];
+
+  if (iconAttr) {
+    const iconNode = unwrapIcon(j, iconAttr);
+    if (iconNode) {
+      if (config.iconContentOnly) {
+        newChildren = [iconNode];
+      } else if (iconPosition === 'trailing') {
+        newChildren = [...newChildren, iconNode];
+      } else {
+        newChildren = [iconNode, ...newChildren];
+      }
+    }
+  }
+
+  // Apply changes.
+  openingElement.name.name = 'Button';
+  openingElement.attributes = newAttrs;
+
+  if (newChildren.length === 0) {
+    openingElement.selfClosing = true;
+    path.node.closingElement = null;
+  } else {
+    openingElement.selfClosing = false;
+    path.node.children = newChildren;
+    if (closingElement) {
+      closingElement.name.name = 'Button';
+    } else {
+      // Was self-closing (IconButton / IconGhostButton) — add closing tag.
+      path.node.closingElement = j.jsxClosingElement(j.jsxIdentifier('Button'));
+    }
+  }
+
+  return true;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Returns the string value if node is a string literal, otherwise null. */
+function getStringValue(node) {
+  if (!node) return null;
+  // variant="primary"
+  if (node.type === 'StringLiteral' || node.type === 'Literal') return node.value;
+  // variant={"primary"}
+  if (node.type === 'JSXExpressionContainer') {
+    const expr = node.expression;
+    if (expr.type === 'StringLiteral' || expr.type === 'Literal') return expr.value;
+  }
+  return null;
+}
+
+/**
+ * Extracts the icon from an `icon={…}` JSX attribute as a JSX child node.
+ * Returns null if the value cannot be resolved.
+ */
+function unwrapIcon(j, iconAttr) {
+  const val = iconAttr.value;
+  if (!val || val.type !== 'JSXExpressionContainer') return null;
+
+  const expr = val.expression;
+  // icon={<SomeIcon />} — expression is a JSXElement, use it directly as child.
+  if (expr.type === 'JSXElement' || expr.type === 'JSXFragment') return expr;
+  // icon={someVariable} — wrap in expression container so it stays valid as a child.
+  return j.jsxExpressionContainer(expr);
+}