@camunda/design-system 0.62.0 → 0.64.0

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,
+    };
+  },
+};

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,
+    };
+  },
+};