@camunda/design-system 0.63.0 → 0.64.0

package/eslint-rules/no-adhoc-typography.js

@@ -0,0 +1,77 @@
+/**
+ * Flags ad-hoc typography that should use the DS <Heading>/<Text> primitives.
+ * Moderate scope: bare <h1>-<h6>, Carbon Heading/Section imports, and elements
+ * whose className string literal combines a font-size AND a font-weight utility.
+ * Only string-literal classNames are inspected (cn()/template-literals/cva not).
+ */
+import { classLiteral } from "./class-literal.js";
+
+const SIZE = /\btext-(xs|sm|base|lg|xl|[2-9]xl|\[[^\]]+\])\b/;
+const WEIGHT =
+  /\bfont-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black|\[\d+\])\b/;
+const HEADING_TAGS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
+const PRIMITIVE_NAMES = new Set(["Heading", "Text"]);
+const SVG_TEXT_ELEMENTS = new Set(["text", "tspan", "textPath"]);
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Use the DS Heading/Text primitives instead of bare headings or ad-hoc type-scale classes.",
+    },
+    messages: {
+      bareHeading:
+        'Use <Heading as="{{tag}}" variant="…"> instead of a bare <{{tag}}>.',
+      carbonImport:
+        "Use the DS <Heading> primitive; drop <Section>/<HeadingLevel> and set the level via `as`.",
+      adhocClasses:
+        "Use a <Heading>/<Text> variant instead of hand-written type-scale classes (font-size + font-weight combo).",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== "JSXIdentifier") return;
+        const name = node.name.name;
+        if (HEADING_TAGS.has(name)) {
+          context.report({
+            node,
+            messageId: "bareHeading",
+            data: { tag: name },
+          });
+          return;
+        }
+        if (PRIMITIVE_NAMES.has(name)) return;
+        // Ad-hoc type-scale only matters on raw HTML host elements. Capitalized React
+        // components (DS *Title composites that consume typographyVariants, and consumer
+        // components) own their className semantics — an override is deliberate, like the
+        // Heading/Text allowance. SVG text nodes can't host Heading/Text.
+        if (!/^[a-z]/.test(name) || SVG_TEXT_ELEMENTS.has(name)) return;
+        const classAttr = node.attributes.find(
+          (a) => a.type === "JSXAttribute" && a.name.name === "className",
+        );
+        if (!classAttr) return;
+        const raw = classLiteral(classAttr.value);
+        if (raw && SIZE.test(raw) && WEIGHT.test(raw)) {
+          // Anchor to the opening element (like `bareHeading`) so the audit
+          // gate prints a consistent line:col for both heading findings.
+          context.report({ node, messageId: "adhocClasses" });
+        }
+      },
+      ImportDeclaration(node) {
+        if (node.source.value !== "@carbon/react") return;
+        for (const spec of node.specifiers) {
+          if (
+            spec.type === "ImportSpecifier" &&
+            (spec.imported.name === "Heading" ||
+              spec.imported.name === "Section")
+          ) {
+            context.report({ node: spec, messageId: "carbonImport" });
+          }
+        }
+      },
+    };
+  },
+};

package/eslint-rules/no-deep-import.js

@@ -0,0 +1,59 @@
+/**
+ * Flags imports of `@camunda/design-system/<subpath>` where the subpath is not
+ * a public entry point (e.g. `/dist/src/icons`, `/src/components/ui/button`).
+ * Deep paths are internal layout and break on any refactor.
+ *
+ * The allowed subpaths are read from this package's own `exports` map at load
+ * time, so a new public entry point is allowed without touching this rule.
+ */
+import { createRequire } from "node:module";
+
+const PACKAGE = "@camunda/design-system";
+const pkg = createRequire(import.meta.url)("../package.json");
+const PUBLIC_SUBPATHS = new Set(
+  Object.keys(pkg.exports)
+    .filter((k) => k !== ".")
+    .map((k) => k.slice(2)),
+);
+
+function publicList() {
+  return [PACKAGE, ...[...PUBLIC_SUBPATHS].map((s) => `${PACKAGE}/${s}`)]
+    .map((s) => `"${s}"`)
+    .join(", ");
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: `Import ${PACKAGE} only through its public entry points.`,
+    },
+    messages: {
+      deepImport: `"{{source}}" is not a public entry point of ${PACKAGE}. Import from one of: {{allowed}}.`,
+    },
+    schema: [],
+  },
+  create(context) {
+    function checkSource(node) {
+      const source = node.source?.value;
+      if (typeof source !== "string" || !source.startsWith(`${PACKAGE}/`)) {
+        return;
+      }
+      if (PUBLIC_SUBPATHS.has(source.slice(PACKAGE.length + 1))) return;
+      context.report({
+        node: node.source,
+        messageId: "deepImport",
+        data: { source, allowed: publicList() },
+      });
+    }
+
+    return {
+      ImportDeclaration: checkSource,
+      ExportNamedDeclaration: checkSource,
+      ExportAllDeclaration: checkSource,
+      ImportExpression(node) {
+        if (node.source.type === "Literal") checkSource(node);
+      },
+    };
+  },
+};

package/eslint-rules/no-direct-lucide-import.js

@@ -0,0 +1,67 @@
+/**
+ * Flags any import or re-export sourced directly from "lucide-react" (or one of
+ * its subpaths). Glyphs must flow through the DS icon proxy instead, so the
+ * concrete glyph behind a name can be swapped centrally.
+ *
+ * Two variants share one implementation and differ only in the proxy path:
+ *   - default export: DS repo source, proxy is the internal "icons/lucide"
+ *     alias. The proxy module itself (src/icons/lucide.ts) is exempted via an
+ *     eslint.config.js block, not via logic in this rule.
+ *   - `consumerNoDirectLucideImport`: product repos, proxy is the public
+ *     "@camunda/design-system/icons" subpath. Shipped in the ESLint plugin.
+ *
+ * Autofix rewrites a bare "lucide-react" source to the proxy path — safe
+ * because the proxy re-exports the whole lucide-react surface (`export *`).
+ * Subpath sources ("lucide-react/dynamic", …) are reported but not fixed: the
+ * proxy only mirrors the package root.
+ */
+function createNoDirectLucideImport(proxyPath) {
+  return {
+    meta: {
+      type: "problem",
+      docs: {
+        description: `Import Lucide glyphs from the DS icon proxy (${proxyPath}), not lucide-react directly.`,
+      },
+      fixable: "code",
+      messages: {
+        noDirectLucideImport: `Import glyphs from the DS icon proxy ("${proxyPath}"), not lucide-react directly.`,
+      },
+      schema: [],
+    },
+    create(context) {
+      function checkSource(node) {
+        const source = node.source?.value;
+        if (typeof source !== "string") return;
+        if (source !== "lucide-react" && !source.startsWith("lucide-react/")) {
+          return;
+        }
+        context.report({
+          node,
+          messageId: "noDirectLucideImport",
+          fix:
+            source === "lucide-react"
+              ? (fixer) => {
+                  const quote = node.source.raw[0];
+                  return fixer.replaceText(
+                    node.source,
+                    `${quote}${proxyPath}${quote}`,
+                  );
+                }
+              : null,
+        });
+      }
+
+      return {
+        ImportDeclaration: checkSource,
+        ExportNamedDeclaration: checkSource,
+        ExportAllDeclaration: checkSource,
+      };
+    },
+  };
+}
+
+export const consumerNoDirectLucideImport = createNoDirectLucideImport(
+  "@camunda/design-system/icons",
+);
+
+export default createNoDirectLucideImport("icons/lucide");

package/eslint-rules/no-hardcoded-i18n-prop.js

@@ -0,0 +1,78 @@
+/**
+ * Flags a string literal passed to an i18n-overridable prop of a DS component
+ * (`<Dialog closeLabel="Close" />`). Every DS component already renders its
+ * own English default from the i18n dictionary; a literal there only restates
+ * it and blocks a future translation. Route the consumer's own translated
+ * value through the prop, or leave it unset.
+ *
+ * "Overridable" is matched by naming convention — the DS names every override
+ * prop `…Label`, `…LabelText`, `…Message`, `…Prefix` or `searchPlaceholder`
+ * (kept in sync with DS source by no-hardcoded-i18n-prop.test.mjs). Bare
+ * `label`/`title`/`placeholder` are deliberately excluded: on most components
+ * they carry caller content, not a DS default. So are the few convention-named
+ * content props listed in CONTENT_PROPS.
+ *
+ * Heuristic, so shipped at `warn`: a caller-specific message
+ * (`emptyMessage="No workspaces yet"`) is legitimate in an app without i18n.
+ */
+import {
+  importSourcesSchema,
+  staticString,
+  trackDsImports,
+} from "./ds-imports.js";
+
+const OVERRIDE_PROP = /^[a-z][A-Za-z]*(Label|LabelText|Message|Prefix)$/;
+const EXTRA_OVERRIDE_PROPS = new Set(["searchPlaceholder"]);
+// Match the naming convention but carry caller content with no DS default.
+const CONTENT_PROPS = new Set([
+  "centerLabel", // PieChart center text
+  "ctaLabel", // MultiStepDialog visual CTA
+  "secondaryLabel", // carbon-compat Tabs
+  "rangeLabel", // carbon-compat DatePicker field labels
+  "startLabel",
+  "endLabel",
+]);
+const HAS_WORDS = /\p{L}{2,}/u;
+
+export function isOverridableProp(name) {
+  if (CONTENT_PROPS.has(name)) return false;
+  return OVERRIDE_PROP.test(name) || EXTRA_OVERRIDE_PROPS.has(name);
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Don't hardcode string literals on DS i18n-overridable props (closeLabel, emptyMessage, …); pass a translated value or leave the DS default.",
+      heuristic: true,
+    },
+    messages: {
+      hardcoded:
+        '`{{prop}}="{{value}}"` hardcodes copy on a DS i18n-overridable prop. Pass your app\'s translated string instead, or omit the prop to fall back to the DS default where one exists.',
+    },
+    schema: [importSourcesSchema],
+  },
+  create(context) {
+    const ds = trackDsImports(context);
+    return {
+      ImportDeclaration: ds.ImportDeclaration,
+      JSXOpeningElement(node) {
+        if (!ds.importedName(node.name)) return;
+        for (const attr of node.attributes) {
+          if (attr.type !== "JSXAttribute") continue;
+          if (attr.name.type !== "JSXIdentifier") continue;
+          const prop = attr.name.name;
+          if (!isOverridableProp(prop)) continue;
+          const value = staticString(attr.value);
+          if (value === null || !HAS_WORDS.test(value)) continue;
+          context.report({
+            node: attr,
+            messageId: "hardcoded",
+            data: { prop, value },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint-rules/no-hardcoded-user-facing-string.js

@@ -0,0 +1,82 @@
+/**
+ * Flags hardcoded English copy that should be routed through the i18n
+ * dictionary (`useC4Dictionary()` / `t("key")`, see src/lib/i18n/dictionary.ts)
+ * instead of a raw string literal.
+ *
+ * Scope is narrow and precise, not exhaustive:
+ *   - JSX text content — a component rendering its own static prose.
+ *   - String-literal values on `aria-label` / `title` / `placeholder` / `alt`
+ *     — the four attributes whose native HTML/ARIA semantics guarantee the
+ *     value is always user-facing text, so no attribute-name allowlist is
+ *     needed to avoid false positives on structural props (`variant`,
+ *     `type`, `size`, `data-*`, ...).
+ *
+ * A value wrapped in a JSXExpressionContainer around anything other than a
+ * bare string Literal (a `t("key")` call, a prop, a variable, a ternary) is
+ * never flagged. Whitespace-only JSX text and text with no letters (glyphs,
+ * punctuation, numbers) are not flagged either — neither needs translation.
+ */
+const WATCHED_ATTRIBUTES = new Set([
+  "aria-label",
+  "title",
+  "placeholder",
+  "alt",
+]);
+
+// At least two letters — excludes whitespace-only text and bare punctuation/
+// glyphs/numbers ("…", "·", "42", "100%"), none of which need translation.
+const HAS_WORDS = /[A-Za-z]{2,}/;
+
+function isHardcodedLiteral(value) {
+  return typeof value === "string" && HAS_WORDS.test(value);
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Route user-facing copy through the i18n dictionary (useC4Dictionary()/t()) instead of a hardcoded string literal.",
+    },
+    messages: {
+      hardcodedText:
+        'Hardcoded text content — add a key to src/lib/i18n/dictionary.ts and render it via t("key") instead.',
+      hardcodedAttribute:
+        'Hardcoded "{{attr}}" string — add a key to src/lib/i18n/dictionary.ts and pass t("key") instead.',
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      JSXText(node) {
+        if (!isHardcodedLiteral(node.value)) return;
+        context.report({ node, messageId: "hardcodedText" });
+      },
+      JSXAttribute(node) {
+        if (node.name.type !== "JSXIdentifier") return;
+        if (!WATCHED_ATTRIBUTES.has(node.name.name)) return;
+        const value = node.value;
+        if (!value) return;
+        if (value.type === "Literal" && isHardcodedLiteral(value.value)) {
+          context.report({
+            node: value,
+            messageId: "hardcodedAttribute",
+            data: { attr: node.name.name },
+          });
+          return;
+        }
+        if (
+          value.type === "JSXExpressionContainer" &&
+          value.expression.type === "Literal" &&
+          isHardcodedLiteral(value.expression.value)
+        ) {
+          context.report({
+            node: value.expression,
+            messageId: "hardcodedAttribute",
+            data: { attr: node.name.name },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint-rules/no-primitive-tailwind-colors.js

@@ -0,0 +1,36 @@
+/**
+ * Flags primitive Tailwind color utilities (bg-blue-500, text-gray-100, …) in a
+ * className. DS components must use semantic tokens (bg-primary,
+ * text-neutral-foreground-subtle, …) so theming/dark-mode stay centralized.
+ * Only string-literal classNames are inspected (cn()/template-literals not).
+ */
+import { classLiteral } from "./class-literal.js";
+
+const PRIMITIVE_TW_PATTERN =
+  /\b(bg|text|border|ring|fill|stroke|outline|shadow|placeholder|accent|caret|divide)-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d+\b/;
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Use semantic color tokens instead of primitive Tailwind color classes.",
+    },
+    messages: {
+      primitiveColor:
+        "Primitive Tailwind color class forbidden. Use semantic tokens (bg-primary, text-neutral-foreground-subtle, …).",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        if (node.name.name !== "className") return;
+        const raw = classLiteral(node.value);
+        if (raw && PRIMITIVE_TW_PATTERN.test(raw)) {
+          context.report({ node, messageId: "primitiveColor" });
+        }
+      },
+    };
+  },
+};

package/eslint-rules/no-raw-color-in-classname.js

@@ -0,0 +1,34 @@
+/**
+ * Flags raw hex / rgb() color literals in a className (#ff0000, rgba(0,0,0,.5)).
+ * DS components must use semantic tokens from src/index.css so theming/dark-mode
+ * stay centralized. Only string-literal classNames are inspected.
+ */
+import { classLiteral } from "./class-literal.js";
+
+const HEX_RGB_PATTERN = /#[0-9a-fA-F]{3,8}\b|rgba?\s*\(/;
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Use semantic color tokens instead of raw hex/rgb() in className.",
+    },
+    messages: {
+      rawColor:
+        "Raw hex/rgb in className forbidden. Use semantic tokens from src/index.css.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        if (node.name.name !== "className") return;
+        const raw = classLiteral(node.value);
+        if (raw && HEX_RGB_PATTERN.test(raw)) {
+          context.report({ node, messageId: "rawColor" });
+        }
+      },
+    };
+  },
+};

package/eslint-rules/prefer-link-props.js

@@ -0,0 +1,107 @@
+/**
+ * Soft companion to `require-browsable-link`: flags DS components wired with a
+ * click prop but no link prop when the handler's intent is NOT visible (a prop,
+ * an imported function, a callback from context). Covers `DataTable`
+ * (`onRowClick` / `rowHref`), `NavBreadcrumbItem` (`onClick` / `linkProps`) and
+ * DS descriptor objects (sidebar items, breadcrumb segments, switcher entries,
+ * notifications: `onClick`|`navigate` / `linkProps`|`href`). Without the link
+ * prop the target renders as a `<button>` — no hoverable href, no
+ * Cmd/middle-click, no "open in new tab".
+ *
+ * When the handler visibly navigates, `require-browsable-link` reports it (as
+ * an error) and this rule stays silent, so a site is never reported twice.
+ * Heuristic, so shipped at `warn`: the click may legitimately not navigate
+ * (open a panel, select a row). Disable per line when that is the case.
+ * Elements with a spread are skipped — the link prop may be in it.
+ */
+import {
+  findAttribute,
+  hasActiveAttribute,
+  hasSpread,
+  trackDsImports,
+} from "./ds-imports.js";
+import {
+  attributeNavigation,
+  descriptorRoots,
+  findNavigation,
+  forEachLinklessDescriptor,
+  navigationSchemaProperties,
+} from "./navigation.js";
+
+// component -> [click prop, link prop]
+const PAIRS = {
+  DataTable: ["onRowClick", "rowHref"],
+  NavBreadcrumbItem: ["onClick", "linkProps"],
+};
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Prefer the link prop (rowHref / linkProps / href) over click-only handlers on DS components that support both.",
+      heuristic: true,
+    },
+    messages: {
+      preferLink:
+        "<{{component}}> has `{{click}}` but no `{{link}}`. If this navigates, pass `{{link}}` so it renders a real link (href, Cmd/middle-click, open in new tab), and remove the navigation from `{{click}}`.",
+      preferDescriptorLink:
+        "This item has `{{click}}` but no `linkProps`/`href`. If it navigates, add the link prop so it renders a real link, and remove the navigation from `{{click}}`.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          importSources: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            uniqueItems: true,
+          },
+          ...navigationSchemaProperties,
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const ds = trackDsImports(context);
+    const reported = new Set();
+
+    function checkDescriptors(node) {
+      for (const root of descriptorRoots(ds, node)) {
+        forEachLinklessDescriptor(context, root, (_obj, click) => {
+          if (reported.has(click)) return;
+          reported.add(click);
+          if (findNavigation(context, click.value)) return;
+          context.report({
+            node: click,
+            messageId: "preferDescriptorLink",
+            data: { click: click.key.name ?? click.key.value },
+          });
+        });
+      }
+    }
+
+    return {
+      ImportDeclaration: ds.ImportDeclaration,
+      JSXOpeningElement(node) {
+        checkDescriptors(node);
+        const component = ds.importedName(node.name);
+        const pair = component && PAIRS[component];
+        if (!pair) return;
+        const [click, link] = pair;
+        const clickAttr = findAttribute(node, click);
+        if (!clickAttr) return;
+        if (hasActiveAttribute(node, link) || hasSpread(node)) return;
+        if (attributeNavigation(context, clickAttr)) return;
+        context.report({
+          node,
+          messageId: "preferLink",
+          data: { component, click, link },
+        });
+      },
+      CallExpression: checkDescriptors,
+    };
+  },
+};