@vadimcomanescu/nadicode-design-system 2.0.0

package/eslint-rules/nadicode/rules/require-sidebar-trigger.js

@@ -0,0 +1,52 @@
+import { getFilename, isTestFile } from "../utils.js";
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require SidebarTrigger when SidebarProvider is used. Without it, the sidebar is unreachable on mobile where it renders as a Sheet.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const filename = getFilename(context);
+
+    // Skip test files and the Sidebar component source itself
+    if (isTestFile(filename) || filename.endsWith("/Sidebar.tsx")) return {};
+
+    let providerImportNode = null;
+    let hasTriggerImport = false;
+
+    return {
+      ImportDeclaration(node) {
+        // Match any import path ending with /Sidebar (e.g. @/components/ui/Sidebar)
+        if (!/\/Sidebar$/.test(node.source.value)) return;
+
+        for (const spec of node.specifiers) {
+          if (spec.type !== "ImportSpecifier") continue;
+          const name = spec.imported.name;
+
+          if (name === "SidebarProvider") {
+            providerImportNode = node;
+          }
+          if (name === "SidebarTrigger") {
+            hasTriggerImport = true;
+          }
+        }
+      },
+
+      "Program:exit"() {
+        if (providerImportNode && !hasTriggerImport) {
+          context.report({
+            node: providerImportNode,
+            message:
+              "File imports SidebarProvider but not SidebarTrigger. On mobile the sidebar renders as a Sheet with no way to open it. Import and render SidebarTrigger (typically in a md:hidden header).",
+          });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/nadicode/rules/require-sizes-on-fill-image.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Require `sizes` prop on next/image when `fill` is used.
+ *
+ * Without `sizes`, a fill image defaults to `sizes="100vw"`, which means the
+ * browser downloads the largest srcset candidate on every viewport. This wastes
+ * bandwidth and hurts LCP.
+ */
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require 'sizes' prop on next/image components that use 'fill'.",
+    },
+    schema: [],
+  },
+  create(context) {
+    let imageLocalName = null;
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value !== "next/image") return;
+
+        for (const specifier of node.specifiers) {
+          if (specifier.type === "ImportDefaultSpecifier") {
+            imageLocalName = specifier.local.name;
+          }
+        }
+      },
+
+      JSXOpeningElement(node) {
+        if (!imageLocalName) return;
+
+        const elementName =
+          node.name.type === "JSXIdentifier" ? node.name.name : null;
+        if (elementName !== imageLocalName) return;
+
+        const hasFill = node.attributes.some(
+          (attr) =>
+            attr.type === "JSXAttribute" &&
+            attr.name.type === "JSXIdentifier" &&
+            attr.name.name === "fill",
+        );
+        if (!hasFill) return;
+
+        const hasSizes = node.attributes.some(
+          (attr) =>
+            attr.type === "JSXAttribute" &&
+            attr.name.type === "JSXIdentifier" &&
+            attr.name.name === "sizes",
+        );
+        if (hasSizes) return;
+
+        context.report({
+          node,
+          message:
+            "next/image with 'fill' must include a 'sizes' prop. Without it the browser downloads the largest image variant for every viewport.",
+        });
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/nadicode/rules/require-stagger-on-metric-grid.js

@@ -0,0 +1,74 @@
+import { getClassTokensFromAttribute } from "../utils.js";
+
+const METRIC_COMPONENTS = new Set(["MetricCard"]);
+
+const GRID_COLS_PATTERN = /grid-cols-/;
+
+function getClassNameText(node) {
+  for (const attr of node.openingElement.attributes) {
+    const tokens = getClassTokensFromAttribute(attr);
+    if (tokens.length > 0) return tokens.join(" ");
+  }
+  return "";
+}
+
+function hasStaggerChildrenAncestor(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === "JSXElement" &&
+      current.openingElement.name.type === "JSXIdentifier" &&
+      current.openingElement.name.name === "StaggerChildren"
+    ) {
+      return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
+function countMetricChildren(node) {
+  let count = 0;
+  for (const child of node.children) {
+    if (
+      child.type === "JSXElement" &&
+      child.openingElement.name.type === "JSXIdentifier" &&
+      METRIC_COMPONENTS.has(child.openingElement.name.name)
+    ) {
+      count++;
+    }
+  }
+  return count;
+}
+
+const rule = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Require StaggerChildren wrapper on grids with 3+ metric/card children",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      JSXElement(node) {
+        const classText = getClassNameText(node);
+        if (!GRID_COLS_PATTERN.test(classText)) return;
+
+        const metricCount = countMetricChildren(node);
+        if (metricCount < 3) return;
+
+        if (hasStaggerChildrenAncestor(node)) return;
+
+        context.report({
+          node: node.openingElement,
+          message:
+            "Metric grids with 3+ cards should be wrapped in <StaggerChildren> for entrance animation.",
+        });
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/nadicode/rules/require-touch-target-on-interactive.js

@@ -0,0 +1,146 @@
+import { getClassTokensFromAttribute } from "../utils.js";
+
+const UNDERSIZED_HEIGHTS = new Set([
+  "h-1",
+  "h-2",
+  "h-3",
+  "h-4",
+  "h-5",
+  "h-6",
+  "h-7",
+  "h-8",
+]);
+const UNDERSIZED_WIDTHS = new Set([
+  "w-1",
+  "w-2",
+  "w-3",
+  "w-4",
+  "w-5",
+  "w-6",
+  "w-7",
+  "w-8",
+]);
+const UNDERSIZED_SIZES = new Set([
+  "size-1",
+  "size-2",
+  "size-3",
+  "size-4",
+  "size-5",
+  "size-6",
+  "size-7",
+  "size-8",
+]);
+const COMPENSATING = new Set([
+  "h-10",
+  "h-11",
+  "h-12",
+  "w-10",
+  "w-11",
+  "w-12",
+  "size-10",
+  "size-11",
+  "size-12",
+  "min-h-10",
+  "min-h-11",
+  "min-h-12",
+  "min-w-10",
+  "min-w-11",
+  "min-w-12",
+  "min-h-[40px]",
+  "min-h-[44px]",
+  "min-w-[40px]",
+  "min-w-[44px]",
+  "after:-inset-2",
+  "after:-inset-[6px]",
+  "after:-inset-[8px]",
+  "before:-inset-2",
+  "before:-inset-[6px]",
+  "before:-inset-[8px]",
+]);
+
+function isInteractive(node) {
+  const name = node.name;
+  if (name.type !== "JSXIdentifier") return false;
+
+  const tagName = name.name;
+  const isButton = tagName === "button";
+  const isAnchor = tagName === "a";
+  const hasOnClick = node.attributes.some(
+    (attr) =>
+      attr.type === "JSXAttribute" &&
+      attr.name.type === "JSXIdentifier" &&
+      attr.name.name === "onClick",
+  );
+  const hasTabIndex = node.attributes.some(
+    (attr) =>
+      attr.type === "JSXAttribute" &&
+      attr.name.type === "JSXIdentifier" &&
+      attr.name.name === "tabIndex",
+  );
+  const isButtonRole = node.attributes.some(
+    (attr) =>
+      attr.type === "JSXAttribute" &&
+      attr.name.type === "JSXIdentifier" &&
+      attr.name.name === "role" &&
+      attr.value?.type === "Literal" &&
+      attr.value.value === "button",
+  );
+
+  return isButton || isAnchor || hasOnClick || hasTabIndex || isButtonRole;
+}
+
+function getClassTokens(node) {
+  const classAttr = node.attributes.find(
+    (attr) =>
+      attr.type === "JSXAttribute" &&
+      attr.name.type === "JSXIdentifier" &&
+      (attr.name.name === "className" || attr.name.name === "class"),
+  );
+
+  if (!classAttr) return { classAttr: null, classes: [] };
+
+  const tokens = getClassTokensFromAttribute(classAttr);
+  return {
+    classAttr,
+    classes: tokens.join(" ").split(/\s+/).filter(Boolean),
+  };
+}
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow interactive elements with undersized hit areas unless they declare an explicit larger touch target",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        if (!isInteractive(node)) return;
+
+        const { classAttr, classes } = getClassTokens(node);
+        if (!classAttr) return;
+
+        const hasUndersizedHeight = classes.some((cls) => UNDERSIZED_HEIGHTS.has(cls));
+        const hasUndersizedWidth = classes.some((cls) => UNDERSIZED_WIDTHS.has(cls));
+        const hasUndersizedSize = classes.some((cls) => UNDERSIZED_SIZES.has(cls));
+        const hasUndersized =
+          hasUndersizedHeight || hasUndersizedWidth || hasUndersizedSize;
+        if (!hasUndersized) return;
+
+        const hasCompensating = classes.some((cls) => COMPENSATING.has(cls));
+        if (hasCompensating) return;
+
+        context.report({
+          node: classAttr,
+          message:
+            "Interactive element uses an undersized touch target class (h-1..h-8, w-1..w-8, or size-1..size-8). Add a 40-44px minimum target (`min-h-10`, `min-w-10`, `min-h-[44px]`, `min-w-[44px]`) or an explicit expanded hit area such as `after:-inset-2`.",
+        });
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/nadicode/rules/require-usememo-for-render-filter-sort.js

@@ -0,0 +1,172 @@
+const ARRAY_METHODS = new Set(["filter", "sort", "find", "reduce"]);
+const HOOK_WRAPPERS = new Set([
+  "useMemo",
+  "useCallback",
+  "useEffect",
+  "useLayoutEffect",
+]);
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require useMemo for .filter()/.sort()/.find()/.reduce() in the render path of function components",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isTargetArrayMethod(node)) return;
+        if (!isInComponentBody(node, context)) return;
+        if (isInsideHookWrapper(node)) return;
+        if (isInsideEventHandler(node)) return;
+
+        const methodName = node.callee.property.name;
+        context.report({
+          node,
+          message: `Wrap .${methodName}() in useMemo when operating on props or state to avoid unnecessary recomputation on every render.`,
+        });
+      },
+    };
+  },
+};
+
+function isTargetArrayMethod(node) {
+  return (
+    node.callee.type === "MemberExpression" &&
+    node.callee.property.type === "Identifier" &&
+    ARRAY_METHODS.has(node.callee.property.name) &&
+    !node.callee.computed
+  );
+}
+
+/**
+ * Check if the node is inside a function component body (top-level statements).
+ * A function component is a function whose name starts with an uppercase letter
+ * or is exported default.
+ */
+function isInComponentBody(node, context) {
+  const ancestors = context.getAncestors
+    ? context.getAncestors()
+    : context.sourceCode.getAncestors(node);
+
+  // Must be inside at least one function
+  let componentFunction = null;
+
+  for (const ancestor of ancestors) {
+    if (isComponentFunction(ancestor)) {
+      componentFunction = ancestor;
+      break;
+    }
+  }
+
+  return componentFunction !== null;
+}
+
+function isComponentFunction(node) {
+  // function MyComponent() {}
+  if (
+    node.type === "FunctionDeclaration" &&
+    node.id?.name &&
+    /^[A-Z]/.test(node.id.name)
+  ) {
+    return true;
+  }
+
+  // const MyComponent = () => {} or const MyComponent = function() {}
+  if (
+    node.type === "VariableDeclarator" &&
+    node.id?.type === "Identifier" &&
+    /^[A-Z]/.test(node.id.name) &&
+    node.init &&
+    (node.init.type === "ArrowFunctionExpression" ||
+      node.init.type === "FunctionExpression")
+  ) {
+    return true;
+  }
+
+  // Also catch the arrow/function expression itself when parent is a matching VariableDeclarator
+  if (
+    (node.type === "ArrowFunctionExpression" ||
+      node.type === "FunctionExpression") &&
+    node.parent?.type === "VariableDeclarator" &&
+    node.parent.id?.type === "Identifier" &&
+    /^[A-Z]/.test(node.parent.id.name)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if node is inside a useMemo, useCallback, useEffect, or useLayoutEffect callback.
+ */
+function isInsideHookWrapper(node) {
+  let current = node.parent;
+  while (current) {
+    if (
+      (current.type === "ArrowFunctionExpression" ||
+        current.type === "FunctionExpression") &&
+      current.parent?.type === "CallExpression"
+    ) {
+      const calleeNode = current.parent.callee;
+      const hookName =
+        calleeNode.type === "Identifier"
+          ? calleeNode.name
+          : calleeNode.type === "MemberExpression" &&
+              calleeNode.property.type === "Identifier"
+            ? calleeNode.property.name
+            : null;
+
+      if (hookName && HOOK_WRAPPERS.has(hookName)) return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
+/**
+ * Check if node is inside an event handler (on* prop or function assigned to on* variable).
+ */
+function isInsideEventHandler(node) {
+  let current = node.parent;
+  while (current) {
+    // JSX event handler: onClick={() => items.filter(...)}
+    if (
+      current.type === "JSXExpressionContainer" &&
+      current.parent?.type === "JSXAttribute" &&
+      current.parent.name?.type === "JSXIdentifier" &&
+      /^on[A-Z]/.test(current.parent.name.name)
+    ) {
+      return true;
+    }
+
+    // Function assigned to a handler variable: const handleClick = () => { ... }
+    if (
+      (current.type === "ArrowFunctionExpression" ||
+        current.type === "FunctionExpression") &&
+      current.parent?.type === "VariableDeclarator" &&
+      current.parent.id?.type === "Identifier" &&
+      /^(handle|on)[A-Z]/.test(current.parent.id.name)
+    ) {
+      return true;
+    }
+
+    // Named function declaration: function handleClick() { ... }
+    if (
+      current.type === "FunctionDeclaration" &&
+      current.id?.name &&
+      /^(handle|on)[A-Z]/.test(current.id.name)
+    ) {
+      return true;
+    }
+
+    current = current.parent;
+  }
+  return false;
+}
+
+export default rule;

package/eslint-rules/nadicode/rules/require-usesyncexternalstore-for-subscriptions.js

@@ -0,0 +1,117 @@
+const SUBSCRIBE_METHODS = new Set(["addEventListener", "subscribe", "on"]);
+const UNSUBSCRIBE_METHODS = new Set([
+  "removeEventListener",
+  "unsubscribe",
+  "off",
+]);
+
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require useSyncExternalStore instead of useEffect for subscribing to external stores",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!isUseEffectCall(node)) return;
+
+        const callback = node.arguments[0];
+        if (
+          !callback ||
+          (callback.type !== "ArrowFunctionExpression" &&
+            callback.type !== "FunctionExpression")
+        ) {
+          return;
+        }
+
+        const body = callback.body;
+        if (body.type !== "BlockStatement") return;
+
+        const hasSubscribe = containsSubscribeCall(body);
+        const hasCleanupUnsubscribe = hasUnsubscribeInReturn(body);
+
+        if (hasSubscribe && hasCleanupUnsubscribe) {
+          context.report({
+            node,
+            message:
+              "Use useSyncExternalStore instead of useEffect for subscribing to external stores.",
+          });
+        }
+      },
+    };
+  },
+};
+
+function isUseEffectCall(node) {
+  const callee = node.callee;
+  return (
+    (callee.type === "Identifier" && callee.name === "useEffect") ||
+    (callee.type === "MemberExpression" &&
+      callee.property.type === "Identifier" &&
+      callee.property.name === "useEffect")
+  );
+}
+
+function containsSubscribeCall(blockStatement) {
+  for (const stmt of blockStatement.body) {
+    if (hasMatchingCall(stmt, SUBSCRIBE_METHODS)) return true;
+  }
+  return false;
+}
+
+function hasUnsubscribeInReturn(blockStatement) {
+  for (const stmt of blockStatement.body) {
+    if (stmt.type !== "ReturnStatement" || !stmt.argument) continue;
+
+    const returnExpr = stmt.argument;
+
+    // return () => { ... removeEventListener ... }
+    if (
+      returnExpr.type === "ArrowFunctionExpression" ||
+      returnExpr.type === "FunctionExpression"
+    ) {
+      const cleanupBody =
+        returnExpr.body.type === "BlockStatement"
+          ? returnExpr.body.body
+          : [{ type: "ExpressionStatement", expression: returnExpr.body }];
+
+      for (const cleanupStmt of cleanupBody) {
+        if (hasMatchingCall(cleanupStmt, UNSUBSCRIBE_METHODS)) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function hasMatchingCall(node, methodSet) {
+  if (!node) return false;
+
+  // ExpressionStatement wrapping a call
+  if (node.type === "ExpressionStatement") {
+    return hasMatchingCall(node.expression, methodSet);
+  }
+
+  // Direct call: window.addEventListener(...) or store.subscribe(...)
+  if (node.type === "CallExpression" && node.callee.type === "MemberExpression") {
+    const propName =
+      node.callee.property.type === "Identifier"
+        ? node.callee.property.name
+        : null;
+    if (propName && methodSet.has(propName)) return true;
+  }
+
+  // VariableDeclaration: const unsub = store.subscribe(...)
+  if (node.type === "VariableDeclaration") {
+    for (const decl of node.declarations) {
+      if (decl.init && hasMatchingCall(decl.init, methodSet)) return true;
+    }
+  }
+
+  return false;
+}
+
+export default rule;