@staffbase/design 19.1.0 → 20.0.0

package/codemods/v17-migrate-spacing/README.md

@@ -0,0 +1,72 @@
+# v17 — Migrate Tailwind spacing tokens
+
+This codemod automatically migrates spacing tokens to the standard Tailwind v4 scale (`1 = 0.25rem`) introduced as a breaking change in `@staffbase/design` v17.
+
+The previous custom spacing scale used `1 = 1px`. Dividing all integer spacing tokens by 4 maps each value to the same physical size in the new scale.
+
+## What it transforms
+
+Affected utilities: **margins**, **padding**, **gap**, **left**, **right**, **bottom**, **top** (and their axis/side variants, negative variants, and responsive/state prefixes).
+
+**Not** affected: `space` (`space-x`, `space-y`), `width` (`w-`), `height` (`h-`), `size`.
+
+### Common examples
+
+| Before       | After       | Value |
+| ------------ | ----------- | ----- |
+| `p-4`        | `p-1`       | 4px   |
+| `p-8`        | `p-2`       | 8px   |
+| `p-16`       | `p-4`       | 16px  |
+| `p-24`       | `p-6`       | 24px  |
+| `p-2`        | `p-0.5`     | 2px   |
+| `p-6`        | `p-1.5`     | 6px   |
+| `m-32`       | `m-8`       | 32px  |
+| `mx-16`      | `mx-4`      | 16px  |
+| `pt-8`       | `pt-2`      | 8px   |
+| `gap-16`     | `gap-4`     | 16px  |
+| `gap-x-8`    | `gap-x-2`   | 8px   |
+| `left-24`    | `left-6`    | 24px  |
+| `inset-x-16` | `inset-x-4` | 16px  |
+| `-mt-8`      | `-mt-2`     | 8px   |
+
+### Responsive and state variants are handled
+
+| Before        | After         |
+| ------------- | ------------- |
+| `sm:p-16`     | `sm:p-4`      |
+| `hover:-mt-4` | `hover:-mt-1` |
+| `lg:gap-8`    | `lg:gap-2`    |
+
+### Works in string literals and template literals
+
+```tsx
+// className string
+<div className="mt-8 gap-4 p-16" />;
+// → <div className="p-4 mt-2 gap-1" />
+
+// clsx / cn call
+clsx('p-16', isActive && 'mt-8')
+// → clsx('p-4', isActive && 'mt-2')
+
+// template literal (static segments only)
+`flex p-16 ${dynamic}`;
+// → `flex p-4 ${dynamic}`
+```
+
+## Limitations
+
+- **Dynamic values** — template literal expressions (e.g. `` `p-${size}` ``) cannot be statically transformed; these will remain unchanged and will surface as visual regressions to fix manually.
+- **Decimal values** — classes that already use a decimal token (e.g. `p-0.5`) are intentionally left untouched, so the codemod is safe to run incrementally on partially-migrated code.
+- **CSS files** — this codemod only processes JS/TS/JSX/TSX files. Tailwind utility classes in `.css` files must be migrated manually.
+
+## Usage
+
+```bash
+npx jscodeshift@latest \
+  --transform node_modules/@staffbase/design/codemods/v17-migrate-spacing/transform.js \
+  --extensions tsx,ts,jsx,js \
+  --parser tsx \
+  src/
+```
+
+Add `--dry` to preview changes without writing files, and `--print` to print changed source to stdout.

package/codemods/v17-migrate-spacing/transform.js

@@ -0,0 +1,152 @@
+/**
+ * Jscodeshift codemod: Migrate v17 Tailwind spacing tokens.
+ *
+ * In v17, the design system switched to Tailwind v4's standard spacing scale
+ * where 1 = 0.25rem. The previous custom scale used 1 = 1px, so all integer
+ * spacing tokens for the affected utilities must be divided by 4.
+ *
+ * Affected utilities:
+ *   margins    m, mx, my, mt, mb, ml, mr, ms, me (and negative variants)
+ *   padding    p, px, py, pt, pb, pl, pr, ps, pe
+ *   gap        gap, gap-x, gap-y
+ *   positional left, right, bottom, top, inset, inset-x, inset-y, inset-s, inset-e
+ *              (and negative variants)
+ *
+ * NOT affected: space (space-x, space-y), width (w), height (h), size.
+ *
+ * Examples:
+ *   p-4        → p-1        (4  / 4 = 1)
+ *   m-16       → m-4        (16 / 4 = 4)
+ *   pt-2       → pt-0.5     (2  / 4 = 0.5)
+ *   gap-8      → gap-2      (8  / 4 = 2)
+ *   gap-x-24   → gap-x-6    (24 / 4 = 6)
+ *   -mt-8      → -mt-2      (8  / 4 = 2)
+ *   left-32    → left-8     (32 / 4 = 8)
+ *   inset-x-16 → inset-x-4  (16 / 4 = 4)
+ *   sm:p-16    → sm:p-4     (16 / 4 = 4)
+ *   hover:-mt-4 → hover:-mt-1 (4 / 4 = 1)
+ *
+ * Only integer token values are transformed. Decimal values (e.g. p-0.5) are
+ * left untouched on the assumption they are already in v4 format, making the
+ * codemod safe to run incrementally.
+ *
+ * Usage:
+ *   npx jscodeshift@latest \
+ *     --transform node_modules/@staffbase/design/codemods/v17-migrate-spacing/transform.js \
+ *     --extensions tsx,ts,jsx,js \
+ *     --parser tsx \
+ *     src/
+ */
+
+// ── Spacing prefix list ───────────────────────────────────────────────────────
+
+// Sorted longest-first so alternation resolves correctly in the regex
+// (e.g. gap-x is tried before gap; px before p; inset-x before inset).
+const SPACING_PREFIXES = [
+  // Inset positional (longest first)
+  'inset-x',
+  'inset-y',
+  'inset-s',
+  'inset-e',
+  'inset',
+  // Gap
+  'gap-x',
+  'gap-y',
+  'gap',
+  // Margin variants (before bare m)
+  'mx',
+  'my',
+  'mt',
+  'mb',
+  'ml',
+  'mr',
+  'ms',
+  'me',
+  // Padding variants (before bare p)
+  'px',
+  'py',
+  'pt',
+  'pb',
+  'pl',
+  'pr',
+  'ps',
+  'pe',
+  // Bare margin and padding
+  'm',
+  'p',
+  // Positional
+  'left',
+  'right',
+  'bottom',
+  'top',
+];
+
+const prefixAlt = SPACING_PREFIXES.join('|');
+
+// Matches spacing utilities with integer values.
+//
+// (?<![a-zA-Z\d_-])
+//   Negative lookbehind: prevents matching inside compound names like
+//   "custom-p-4" (letter before) or "my-top-4" (dash before "top").
+//   Allows matches after a space, colon (variant prefix like sm:), or
+//   quote/start-of-string.
+//
+// (-?)
+//   Optional leading dash for negative utilities (-mt-4, -left-8, etc.).
+//
+// (prefix)
+//   The spacing utility prefix captured for reconstruction.
+//
+// -(\d+)
+//   Separator dash followed by an integer token value.
+//   Decimal values (e.g. p-0.5) are intentionally excluded so already-migrated
+//   code is not double-transformed.
+//
+// (?!\w)
+//   Ensures we do not partially match a longer token (e.g. p-4 inside p-40
+//   is avoided because \d+ greedily consumes all digits, and (?!\w) then
+//   confirms no more word characters follow).
+const SPACING_REGEX = new RegExp(`(?<![a-zA-Z\\d_-])(-?)(${prefixAlt})-(\\d+)(?!\\w)`, 'g');
+
+// ── Transformation helper ─────────────────────────────────────────────────────
+
+function divideByFour(str) {
+  return str.replace(SPACING_REGEX, (_match, neg, prefix, num) => {
+    const newVal = parseInt(num, 10) / 4;
+    // Number.isInteger distinguishes 2.0 (integer) from 0.5 (not).
+    // String() gives clean output: 2 → "2", 0.5 → "0.5", 1.5 → "1.5".
+    return `${neg}${prefix}-${String(newVal)}`;
+  });
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+export default function transform(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let dirty = false;
+
+  // Replace within all string literals (className props, clsx/cn args, constants, etc.).
+  root.find(j.StringLiteral).forEach((path) => {
+    const next = divideByFour(path.node.value);
+    if (next !== path.node.value) {
+      path.node.value = next;
+      dirty = true;
+    }
+  });
+
+  // Replace within the static parts of template literals.
+  root.find(j.TemplateElement).forEach((path) => {
+    const {raw, cooked} = path.node.value;
+    const nextRaw = divideByFour(raw);
+    if (nextRaw !== raw) {
+      path.node.value = {
+        raw: nextRaw,
+        cooked: cooked != null ? divideByFour(cooked) : cooked,
+      };
+      dirty = true;
+    }
+  });
+
+  return dirty ? root.toSource({quote: 'single'}) : undefined;
+}

package/codemods/v20-migrate-avatar/README.md

@@ -0,0 +1,71 @@
+# v20 — Breaking-change migrations
+
+This codemod handles all breaking changes introduced in v20 of `@staffbase/design`.
+
+## What it transforms
+
+### Avatar → AvatarDeprecated
+
+`Avatar` is now a compound component. The old single-element Avatar has been renamed to `AvatarDeprecated`.
+
+| Before (v19)                                      | After (v20)                                                 |
+| ------------------------------------------------- | ----------------------------------------------------------- |
+| `import { Avatar } from '@staffbase/design'`      | `import { AvatarDeprecated } from '@staffbase/design'`      |
+| `import { AvatarProps } from '@staffbase/design'` | `import { AvatarDeprecatedProps } from '@staffbase/design'` |
+| `<Avatar … />`                                    | `<AvatarDeprecated … />`                                    |
+| `const props: AvatarProps`                        | `const props: AvatarDeprecatedProps`                        |
+
+### Banner.CloseButton → Banner.Close
+
+`Banner.CloseButton` has been renamed to `Banner.Close`.
+
+| Before (v19)               | After (v20)          |
+| -------------------------- | -------------------- |
+| `<Banner.CloseButton … />` | `<Banner.Close … />` |
+
+Aliased imports are handled — only the imported binding is renamed, the local alias is preserved:
+
+```tsx
+// Before
+import { Avatar as UserAvatar } from '@staffbase/design';
+<UserAvatar … />
+
+// After (local alias unchanged)
+import { AvatarDeprecated as UserAvatar } from '@staffbase/design';
+<UserAvatar … />
+```
+
+## Usage
+
+### Step 1 — Install jscodeshift
+
+```bash
+npm install --save-dev jscodeshift
+# or
+pnpm add -D jscodeshift
+```
+
+### Step 2 — Run the codemod
+
+```bash
+npx jscodeshift@latest \
+  --transform node_modules/@staffbase/design/codemods/v20-migrate-avatar/transform.js \
+  --extensions tsx,ts \
+  --parser tsx \
+  src/
+```
+
+### Step 3 — Migrate to the new Avatar (optional but recommended)
+
+After running this codemod your code compiles again, but `AvatarDeprecated` will be removed in a future release. Migrate to the new compound component when you're ready:
+
+```tsx
+// Before (AvatarDeprecated)
+<AvatarDeprecated src="…" alt="Jane Doe" size="40" />
+
+// After (new Avatar)
+<Avatar.Root size={40}>
+  <Avatar.Image src="…" alt="Jane Doe" />
+  <Avatar.Fallback name="Jane Doe">JD</Avatar.Fallback>
+</Avatar.Root>
+```

package/codemods/v20-migrate-avatar/transform.js

@@ -0,0 +1,191 @@
+/**
+ * Jscodeshift codemod: v20 breaking-change migrations.
+ *
+ * 1. Rename old Avatar to AvatarDeprecated:
+ *   import { Avatar } from '@staffbase/design'
+ *   → import { AvatarDeprecated } from '@staffbase/design'
+ *
+ *   import { AvatarProps } from '@staffbase/design'
+ *   → import { AvatarDeprecatedProps } from '@staffbase/design'
+ *
+ *   <Avatar ... />  →  <AvatarDeprecated ... />
+ *
+ *   const props: AvatarProps  →  const props: AvatarDeprecatedProps
+ *
+ * 2. Rename Banner.CloseButton to Banner.Close:
+ *   <Banner.CloseButton ... />  →  <Banner.Close ... />
+ *
+ * 3. Remove CloseButtonProps import and replace type usages:
+ *   import { CloseButtonProps } from '@staffbase/design'
+ *   → (removed; use ComponentProps<typeof Banner.Close> from 'react' instead)
+ *
+ *   const props: CloseButtonProps  →  const props: ComponentProps<typeof Banner.Close>
+ *
+ * If Avatar/AvatarProps was aliased locally the local name is preserved:
+ *   import { Avatar as MyAvatar } → import { AvatarDeprecated as MyAvatar }
+ *
+ * Usage:
+ *   npx jscodeshift@latest \
+ *     --transform node_modules/@staffbase/design/codemods/v20-migrate-avatar/transform.js \
+ *     --extensions tsx,ts \
+ *     --parser tsx \
+ *     src/
+ */
+
+const DESIGN_PKG = '@staffbase/design';
+
+export default function transform(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let dirty = false;
+
+  // Bail early only if there are no @staffbase/design imports at all.
+  const designImports = root.find(j.ImportDeclaration, {source: {value: DESIGN_PKG}});
+  if (!designImports.length) return undefined;
+
+  // 1. Find the `Avatar` and `AvatarProps` import specifiers.
+  let localName = null;
+  let localPropsName = null;
+
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    const importedName = spec.node.imported.name;
+
+    if (importedName === 'Avatar') {
+      // Capture local alias (or fall back to imported name when no alias).
+      localName = spec.node.local ? spec.node.local.name : 'Avatar';
+      const hasAlias = localName !== 'Avatar';
+
+      spec.node.imported.name = 'AvatarDeprecated';
+
+      if (!hasAlias) {
+        spec.node.local = j.identifier('AvatarDeprecated');
+        localName = 'AvatarDeprecated';
+      }
+
+      dirty = true;
+    } else if (importedName === 'AvatarProps') {
+      localPropsName = spec.node.local ? spec.node.local.name : 'AvatarProps';
+      const hasAlias = localPropsName !== 'AvatarProps';
+
+      spec.node.imported.name = 'AvatarDeprecatedProps';
+
+      if (!hasAlias) {
+        spec.node.local = j.identifier('AvatarDeprecatedProps');
+        localPropsName = 'AvatarDeprecatedProps';
+      }
+
+      dirty = true;
+    }
+  });
+
+  // Remove the early-return guard here — Banner-only files must also be
+  // processed by the steps below.
+
+  // 2. Rename all JSX usages only when there was no alias (alias keeps its
+  //    local name unchanged, so no JSX rename is needed).
+  if (localName === 'AvatarDeprecated') {
+    root
+      .find(j.JSXIdentifier, {name: 'Avatar'})
+      .filter((path) => {
+        // Only rename opening/closing tags that refer to the Avatar import.
+        // Guard against unrelated components also named Avatar in other files.
+        return path.parent.node.type === 'JSXOpeningElement' || path.parent.node.type === 'JSXClosingElement';
+      })
+      .forEach((path) => {
+        path.node.name = 'AvatarDeprecated';
+      });
+  }
+
+  // 3. Rename AvatarProps type references when there was no alias.
+  if (localPropsName === 'AvatarDeprecatedProps') {
+    root.find(j.Identifier, {name: 'AvatarProps'}).forEach((path) => {
+      const parentType = path.parent.node.type;
+      if (
+        parentType === 'TSTypeReference' ||
+        parentType === 'TSTypeAliasDeclaration' ||
+        parentType === 'TSInterfaceHeritage'
+      ) {
+        path.node.name = 'AvatarDeprecatedProps';
+      }
+    });
+  }
+
+  // 5. Rename Banner.CloseButton → Banner.Close (JSXMemberExpression).
+  root
+    .find(j.JSXMemberExpression, {
+      object: {name: 'Banner'},
+      property: {name: 'CloseButton'},
+    })
+    .forEach((path) => {
+      path.node.property.name = 'Close';
+      dirty = true;
+    });
+
+  // 6. Remove CloseButtonProps from @staffbase/design import and replace all
+  //    type references with ComponentProps<typeof Banner.Close>.
+  let closeButtonPropsLocalName = null;
+
+  designImports.find(j.ImportSpecifier).forEach((spec) => {
+    if (spec.node.imported.name === 'CloseButtonProps') {
+      closeButtonPropsLocalName = spec.node.local ? spec.node.local.name : 'CloseButtonProps';
+
+      // Remove this specifier from the import declaration.
+      const importDecl = spec.parent.node;
+      importDecl.specifiers = importDecl.specifiers.filter((s) => s !== spec.node);
+
+      // Drop the entire import declaration if it is now empty.
+      if (importDecl.specifiers.length === 0) {
+        j(spec.parent).remove();
+      }
+
+      dirty = true;
+    }
+  });
+
+  if (closeButtonPropsLocalName) {
+    // Replace every type reference to the old local name with
+    // ComponentProps<typeof Banner.Close>.
+    const buildComponentPropsNode = () =>
+      j.tsTypeReference(
+        j.identifier('ComponentProps'),
+        j.tsTypeParameterInstantiation([
+          j.tsTypeQuery(j.tsQualifiedName(j.identifier('Banner'), j.identifier('Close'))),
+        ]),
+      );
+
+    root.find(j.Identifier, {name: closeButtonPropsLocalName}).forEach((path) => {
+      const parentType = path.parent.node.type;
+      if (
+        parentType === 'TSTypeReference' ||
+        parentType === 'TSTypeAliasDeclaration' ||
+        parentType === 'TSInterfaceHeritage'
+      ) {
+        j(path.parent).replaceWith(buildComponentPropsNode());
+      }
+    });
+
+    // Ensure `ComponentProps` is imported from 'react'.
+    const reactImports = root.find(j.ImportDeclaration, {source: {value: 'react'}});
+    if (reactImports.length) {
+      const reactImport = reactImports.get();
+      const alreadyImported = reactImport.node.specifiers.some(
+        (s) => s.imported && s.imported.name === 'ComponentProps',
+      );
+      if (!alreadyImported) {
+        const newSpec = j.importSpecifier(j.identifier('ComponentProps'));
+        newSpec.importKind = 'type';
+        reactImport.node.specifiers.push(newSpec);
+      }
+    } else {
+      // No existing react import — prepend one.
+      const newImport = j.importDeclaration(
+        [Object.assign(j.importSpecifier(j.identifier('ComponentProps')), {importKind: 'type'})],
+        j.literal('react'),
+      );
+      newImport.importKind = 'type';
+      root.find(j.ImportDeclaration).at(0).insertBefore(newImport);
+    }
+  }
+
+  return dirty ? root.toSource({quote: 'single'}) : undefined;
+}

package/dist/chunk-CDHmpCQf.cjs

@@ -0,0 +1,40 @@
+/*
+Copyright 2026, Staffbase SE and contributors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+Object.defineProperty(exports, "__toESM", {
+	enumerable: true,
+	get: function() {
+		return __toESM;
+	}
+});