@camunda/design-system 0.63.0 → 0.64.0

package/eslint-rules/require-browsable-link.js

@@ -0,0 +1,236 @@
+/**
+ * Requires real, browsable links (href — hover, Cmd/middle-click, "open in new
+ * tab", announced as a link) on the elements where navigation is expected:
+ * links in text, navigation items, and tables. Anything else (a generic
+ * `<div>`, `Card`, plain `Button`) is never checked.
+ *
+ * Flags, with no guessing:
+ *   - links with no destination: `<a onClick>` without `href`; DS `Link` /
+ *     `BreadcrumbLink` without `href` or `asChild`.
+ *   - scoped elements whose click handler visibly navigates (see
+ *     navigation.js): DS `Button variant="link"`, `NavBreadcrumbItem` without
+ *     `linkProps`, `DropdownMenuItem` without `asChild`, `DataTable` without
+ *     `rowHref`, `TableRow`/`TableCell`, and DS descriptor objects (sidebar
+ *     items, breadcrumb segments, switcher entries, notifications) without
+ *     `linkProps`/`href`.
+ *
+ * The unclear case — a click prop with no link prop whose intent isn't
+ * visible — belongs to `prefer-link-props` (warn), not here.
+ */
+import {
+  findAttribute,
+  hasActiveAttribute,
+  hasSpread,
+  staticString,
+  trackDsImports,
+} from "./ds-imports.js";
+import {
+  attributeNavigation,
+  descriptorRoots,
+  findNavigation,
+  forEachLinklessDescriptor,
+  isBuiltinNavigation,
+  navigationSchemaProperties,
+  resolveFunction,
+} from "./navigation.js";
+
+const LINK_COMPONENTS = new Set(["Link", "BreadcrumbLink"]);
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Links in text, navigation items and tables must render real links (href), not click-only elements.",
+    },
+    hasSuggestions: true,
+    messages: {
+      anchorWithoutHref:
+        '<a> with `onClick` but no `href` is not a link: no hover URL, no Cmd/middle-click, no open in new tab. Add `href` (or use a <button type="button"> if it doesn\'t navigate).',
+      linkWithoutHref:
+        "<{{component}}> has no `href` and no `asChild`, so it goes nowhere. Pass `href`, or `asChild` around your router's link. If it doesn't navigate (select all, expand, …), use <Button variant=\"link\"> instead.",
+      buttonLinkNavigates:
+        '<Button variant="link"> navigates from `onClick`. Use the DS <Link href> (or <Link asChild> around your router\'s link) so it is a real link.',
+      menuItemNavigates:
+        "<DropdownMenuItem> navigates from `{{click}}`. Use `asChild` around a link (`<DropdownMenuItem asChild><Link to=…>`) so the entry is a real link.",
+      tableNavigates:
+        "<{{component}}> navigates from `onClick`. Render the destination as a link in the row's primary cell (or use DataTable `rowHref`).",
+      missingLinkProp:
+        "<{{component}}> navigates from `{{click}}` but has no `{{link}}`, so it renders a button. Pass `{{link}}`; the link navigates on its own, so remove the navigation from `{{click}}` (keep it only for side effects such as analytics).",
+      descriptorNavigates:
+        "This item's `{{click}}` navigates but it has no `linkProps`/`href`, so it renders a button. Add the link prop; the link navigates on its own, so remove the navigation from `{{click}}` (keep it only for side effects such as analytics).",
+      suggestRowHref:
+        "Replace `onRowClick` with `rowHref` pointing at the same destination.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          importSources: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            uniqueItems: true,
+          },
+          ...navigationSchemaProperties,
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const ds = trackDsImports(context);
+    const source = context.sourceCode;
+
+    function report(node, messageId, data, suggest) {
+      context.report({ node, messageId, data, suggest });
+    }
+
+    // Suggestion for `onRowClick={(row) => navigate(url(row))}`: replace it
+    // with `rowHref={(row) => url(row)}`. DataTable's anchor still calls
+    // onRowClick, so keeping a navigating handler would navigate twice — the
+    // suggestion is offered only when the handler is nothing but the
+    // navigation, and only for a plain one-URL push (see below).
+    function rowHrefSuggestion(node, attr, target) {
+      // A (disabled) rowHref already present would end up duplicated.
+      if (findAttribute(node, "rowHref")) return undefined;
+      const handler = attr.value.expression;
+      if (resolveFunction(context, handler) !== handler) return undefined;
+      // App helpers take routes/params, not URLs — no safe rowHref to offer.
+      if (!isBuiltinNavigation(target)) return undefined;
+      // A plain anchor can only push one URL: no new tab (window.open), no
+      // history replace, no router state/options (a second argument).
+      if (target.type === "CallExpression") {
+        const method = target.callee.property?.name;
+        if (method === "open" || method === "replace") return undefined;
+        if (target.arguments.length !== 1) return undefined;
+      }
+      const body = handler.body;
+      const onlyNavigation =
+        body === target ||
+        (body.type === "BlockStatement" &&
+          body.body.length === 1 &&
+          body.body[0].type === "ExpressionStatement" &&
+          body.body[0].expression === target);
+      if (!onlyNavigation) return undefined;
+      const dest =
+        target.type === "AssignmentExpression"
+          ? target.right
+          : target.arguments[0];
+      if (!dest || dest.type === "SpreadElement") return undefined;
+      const params = handler.params.map((p) => source.getText(p)).join(", ");
+      return [
+        {
+          messageId: "suggestRowHref",
+          fix: (fixer) =>
+            fixer.replaceText(
+              attr,
+              `rowHref={(${params}) => ${source.getText(dest)}}`,
+            ),
+        },
+      ];
+    }
+
+    function checkJsx(node) {
+      const name = node.name;
+      if (name.type === "JSXIdentifier" && name.name === "a") {
+        if (
+          findAttribute(node, "onClick") &&
+          !hasActiveAttribute(node, "href") &&
+          !hasSpread(node)
+        ) {
+          report(node, "anchorWithoutHref");
+        }
+        return;
+      }
+      const component = ds.importedName(name);
+      if (!component || hasSpread(node)) return;
+
+      if (LINK_COMPONENTS.has(component)) {
+        if (
+          !hasActiveAttribute(node, "href") &&
+          !hasActiveAttribute(node, "asChild")
+        ) {
+          report(node, "linkWithoutHref", { component });
+        }
+        return;
+      }
+      if (component === "Button") {
+        const variant = staticString(findAttribute(node, "variant")?.value);
+        if (
+          variant === "link" &&
+          !hasActiveAttribute(node, "asChild") &&
+          attributeNavigation(context, findAttribute(node, "onClick"))
+        ) {
+          report(node, "buttonLinkNavigates");
+        }
+        return;
+      }
+      if (component === "DropdownMenuItem") {
+        if (hasActiveAttribute(node, "asChild")) return;
+        for (const click of ["onSelect", "onClick"]) {
+          if (attributeNavigation(context, findAttribute(node, click))) {
+            report(node, "menuItemNavigates", { click });
+            return;
+          }
+        }
+        return;
+      }
+      if (component === "TableRow" || component === "TableCell") {
+        if (attributeNavigation(context, findAttribute(node, "onClick"))) {
+          report(node, "tableNavigates", { component });
+        }
+        return;
+      }
+      if (component === "NavBreadcrumbItem") {
+        if (hasActiveAttribute(node, "linkProps")) return;
+        if (attributeNavigation(context, findAttribute(node, "onClick"))) {
+          report(node, "missingLinkProp", {
+            component,
+            click: "onClick",
+            link: "linkProps",
+          });
+        }
+        return;
+      }
+      if (component === "DataTable") {
+        if (hasActiveAttribute(node, "rowHref")) return;
+        const attr = findAttribute(node, "onRowClick");
+        const target = attributeNavigation(context, attr);
+        if (target) {
+          report(
+            node,
+            "missingLinkProp",
+            { component, click: "onRowClick", link: "rowHref" },
+            rowHrefSuggestion(node, attr, target),
+          );
+        }
+      }
+    }
+
+    // One `const items = [...]` can feed several components — report once.
+    const reported = new Set();
+    function checkDescriptors(node) {
+      for (const root of descriptorRoots(ds, node)) {
+        forEachLinklessDescriptor(context, root, (_obj, click) => {
+          if (reported.has(click)) return;
+          if (findNavigation(context, click.value)) {
+            reported.add(click);
+            report(click, "descriptorNavigates", {
+              click: click.key.name ?? click.key.value,
+            });
+          }
+        });
+      }
+    }
+
+    return {
+      ImportDeclaration: ds.ImportDeclaration,
+      JSXOpeningElement(node) {
+        checkJsx(node);
+        checkDescriptors(node);
+      },
+      CallExpression: checkDescriptors,
+    };
+  },
+};

package/eslint-rules/require-shared-sidebar-provider.js

@@ -0,0 +1,165 @@
+/**
+ * Flags `<AppHeader>` and `<AppSidebar>` composed in the same file without a
+ * shared `<SidebarProvider>` ancestor. Without one, each reads a separate
+ * (or missing) sidebar context — `AppHeader`'s `isMobile` check silently
+ * reads `false` regardless of viewport, the mobile hamburger never renders,
+ * and `AppSidebar` renders its fixed desktop rail on a phone screen instead
+ * of the mobile Sheet overlay (issue #470).
+ *
+ * Either component used alone (no sidebar at all, or a sidebar-only shell)
+ * is a legitimate, documented composition and must never warn — this rule
+ * only fires when BOTH are present and don't share one provider instance.
+ *
+ * Same-file heuristic only: it cannot see a provider wrapping either
+ * component from a different file (e.g. a router rendering each at a
+ * different route level) — that case is covered by AppSidebar's own
+ * dev-mode runtime warning instead, not by static analysis.
+ *
+ * Optional `importSources`: when set, only `AppHeader`/`AppSidebar` imported
+ * from those modules count (aliases resolved), so a consumer's own component
+ * with the same name never trips it. `SidebarProvider` is still matched by
+ * bare name as well — a local re-export of the provider is a valid ancestor.
+ * Without the option (DS repo, relative imports) names match bare.
+ */
+import { importSourcesSchema, trackDsImports } from "./ds-imports.js";
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "AppHeader and AppSidebar must share one SidebarProvider ancestor when both are used.",
+    },
+    messages: {
+      missingSharedProvider:
+        "<{{name}}> is composed with <{{other}}> in this file but they don't share a <SidebarProvider> ancestor — the mobile hamburger/Sheet overlay will silently fail to work. Wrap both in one shared <SidebarProvider>.",
+    },
+    schema: [importSourcesSchema],
+  },
+  create(context) {
+    const scoped = Boolean(context.options[0]?.importSources);
+    const ds = trackDsImports(context);
+    const NAMES = ["AppHeader", "AppSidebar"];
+    const otherName = (name) =>
+      name === "AppHeader" ? "AppSidebar" : "AppHeader";
+    const FUNCTION_TYPES = new Set([
+      "FunctionDeclaration",
+      "FunctionExpression",
+      "ArrowFunctionExpression",
+    ]);
+
+    // Grouping key: the nearest enclosing COMPONENT-level function (each
+    // component is its own scope — an AppHeader in one component has nothing
+    // to do with an AppSidebar in an unrelated one, even in the same file).
+    // `null` = module top level, its own scope too.
+    // A plain helper function nested inside a component (e.g.
+    // `const header = () => <AppHeader />`) is NOT a new scope — it inherits
+    // its enclosing component's scope, so JSX it returns still gets grouped
+    // with siblings rendered directly in that component.
+    // key -> { AppHeader: [{node, providerAncestors}], AppSidebar: [...] }
+    const scopes = new Map();
+    const providerStack = [];
+    const functionStack = [];
+
+    function elementName(node) {
+      const n = node.openingElement.name;
+      if (n.type !== "JSXIdentifier") return null;
+      return scoped ? ds.importedName(n) : n.name;
+    }
+
+    function isProvider(node) {
+      const n = node.openingElement.name;
+      return (
+        (n.type === "JSXIdentifier" && n.name === "SidebarProvider") ||
+        elementName(node) === "SidebarProvider"
+      );
+    }
+
+    function currentScopeKey() {
+      return functionStack.length
+        ? functionStack[functionStack.length - 1]
+        : null;
+    }
+
+    function isComponentScope(node) {
+      if (
+        (node.type === "FunctionDeclaration" ||
+          node.type === "FunctionExpression") &&
+        node.id &&
+        /^[A-Z]/.test(node.id.name)
+      ) {
+        return true;
+      }
+      const parent = node.parent;
+      return (
+        parent?.type === "VariableDeclarator" &&
+        parent.id.type === "Identifier" &&
+        /^[A-Z]/.test(parent.id.name)
+      );
+    }
+
+    function pushFn(node) {
+      if (FUNCTION_TYPES.has(node.type) && isComponentScope(node)) {
+        functionStack.push(node);
+      }
+    }
+    function popFn(node) {
+      if (
+        FUNCTION_TYPES.has(node.type) &&
+        functionStack[functionStack.length - 1] === node
+      ) {
+        functionStack.pop();
+      }
+    }
+
+    return {
+      ImportDeclaration: ds.ImportDeclaration,
+      FunctionDeclaration: pushFn,
+      FunctionExpression: pushFn,
+      ArrowFunctionExpression: pushFn,
+      "FunctionDeclaration:exit": popFn,
+      "FunctionExpression:exit": popFn,
+      "ArrowFunctionExpression:exit": popFn,
+
+      JSXElement(node) {
+        const name = elementName(node);
+        if (isProvider(node)) providerStack.push(node);
+        if (!NAMES.includes(name)) return;
+
+        const key = currentScopeKey();
+        if (!scopes.has(key))
+          scopes.set(key, { AppHeader: [], AppSidebar: [] });
+        scopes.get(key)[name].push({
+          node,
+          providerAncestors: new Set(providerStack),
+        });
+      },
+      "JSXElement:exit"(node) {
+        if (isProvider(node)) providerStack.pop();
+      },
+      "Program:exit"() {
+        for (const occurrences of scopes.values()) {
+          for (const name of NAMES) {
+            const other = otherName(name);
+            if (occurrences[other].length === 0) continue; // used alone — fine
+
+            for (const occ of occurrences[name]) {
+              const sharesProvider = occurrences[other].some((otherOcc) =>
+                [...occ.providerAncestors].some((p) =>
+                  otherOcc.providerAncestors.has(p),
+                ),
+              );
+              if (!sharesProvider) {
+                context.report({
+                  node: occ.node,
+                  messageId: "missingSharedProvider",
+                  data: { name, other },
+                });
+              }
+            }
+          }
+        }
+      },
+    };
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camunda/design-system",
-  "version": "0.63.0",
+  "version": "0.64.0",
   "description": "Camunda's AI-first design system. shadcn + Tailwind components, design tokens aligned to Camunda's identity, and AI tooling for component authoring + migration.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,17 +29,28 @@
       "types": "./dist/carbon-compat/index.d.ts",
       "import": "./dist/carbon-compat/index.js"
     },
+    "./eslint-plugin": {
+      "types": "./eslint-plugin/index.d.ts",
+      "import": "./eslint-plugin/index.js"
+    },
     "./styles.css": "./dist/styles.css"
   },
   "typesVersions": {
     "*": {
       "carbon-compat": [
         "./dist/carbon-compat/index.d.ts"
+      ],
+      "eslint-plugin": [
+        "./eslint-plugin/index.d.ts"
       ]
     }
   },
   "files": [
     "dist",
+    "eslint-plugin",
+    "!eslint-plugin/*.test.mjs",
+    "eslint-rules",
+    "!eslint-rules/*.test.mjs",
     "README.md",
     "LICENSE",
     "NOTICE"
@@ -73,7 +84,7 @@
     "audit:conventions": "node scripts/audit-conventions.mjs",
     "mapping:build": "bash skills/migrate/scripts/build-mapping.sh",
     "mapping:check": "bash skills/migrate/scripts/build-mapping.sh --check",
-    "test:rules": "node eslint-rules/no-adhoc-typography.test.mjs && node eslint-rules/no-primitive-tailwind-colors.test.mjs && node eslint-rules/no-raw-color-in-classname.test.mjs && node eslint-rules/require-shared-sidebar-provider.test.mjs && node eslint-rules/no-direct-lucide-import.test.mjs && node eslint-rules/no-hardcoded-user-facing-string.test.mjs && node --test src/icons/registry.integrity.test.mjs src/lib/trigger-ref.integrity.test.mjs src/lib/i18n/dictionary.test.mjs src/lib/i18n/dictionary-usage.test.mjs src/lib/i18n/context.test.mjs",
+    "test:rules": "node eslint-rules/no-adhoc-typography.test.mjs && node eslint-rules/no-primitive-tailwind-colors.test.mjs && node eslint-rules/no-raw-color-in-classname.test.mjs && node eslint-rules/require-shared-sidebar-provider.test.mjs && node eslint-rules/no-hardcoded-user-facing-string.test.mjs && node eslint-rules/no-direct-lucide-import.test.mjs && node eslint-rules/no-deep-import.test.mjs && node eslint-rules/button-has-type.test.mjs && node eslint-rules/icon-button-needs-label.test.mjs && node eslint-rules/prefer-link-props.test.mjs && node eslint-rules/require-browsable-link.test.mjs && node eslint-rules/no-hardcoded-i18n-prop.test.mjs && node --test eslint-plugin/index.test.mjs src/icons/registry.integrity.test.mjs src/lib/trigger-ref.integrity.test.mjs src/lib/i18n/dictionary.test.mjs src/lib/i18n/dictionary-usage.test.mjs src/lib/i18n/context.test.mjs",
     "test:hooks": "python3 plugins/camunda-design-system/scripts/route-request.test.py",
     "prepare": "husky",
     "release": "changeset publish",
@@ -93,11 +104,15 @@
   "peerDependencies": {
     "@carbon/react": "^1.107.0",
     "react": ">=19.0.0 <20",
-    "react-dom": ">=19.0.0 <20"
+    "react-dom": ">=19.0.0 <20",
+    "eslint": ">=9.0.0"
   },
   "peerDependenciesMeta": {
     "@carbon/react": {
       "optional": true
+    },
+    "eslint": {
+      "optional": true
     }
   },
   "dependencies": {