@camunda/design-system 0.62.0 → 0.64.0

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.62.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/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": {