@ekanos/sdk 0.6.0 → 0.7.0

package/eslint.design-rules.mjs

@@ -0,0 +1,437 @@
+/**
+ * The design-system rules the shadcn linter does not cover — eight of them,
+ * as one lint plugin object. The rules and their reasoning live in the design system's
+ * rules; each message names the rule.
+ *
+ * ── Why this file sits in a published package ────────────────────────────
+ * Two consumers need the same eight rules and neither may fork them:
+ *
+ *   - the host repo's own lint, as an oxlint JS plugin. `.oxlintrc.json`
+ *     still loads this plugin through a
+ *     two-line re-export of this file, so the plugin name, the rule names
+ *     and their severities are untouched.
+ *   - a partner's own lint, as an ESLint plugin, through
+ *     `@ekanos/sdk/eslint/design` (`eslint.design-preset.mjs`, its sibling
+ *     here), which a scaffolded project wires up by default.
+ *
+ * The host's tooling is not published, so the import can only run this
+ * direction: the rules live in the package a partner installs and the host
+ * repo's tooling reaches in. The host's capability lint already reads its
+ * preset out of `eslint.preset.mjs` the same way, only for the plugin rather
+ * than the config.
+ *
+ * ── What it may depend on ────────────────────────────────────────────────
+ * Nothing. Every rule below is plain JS over the ESTree/JSX AST with
+ * `context.report`, no oxlint-only API and no import of any kind, which is
+ * what lets one implementation satisfy both linters. Keep it that way: a
+ * dependency here would either break oxlint's plugin loader or grow the
+ * SDK's install for a lint plugin.
+ */
+
+/**
+ * The AST these rules read, typed in JSDoc because `eslint.design-preset.mjs`
+ * imports this file and that pulls it into the package's TypeScript program.
+ * Deliberately loose: a lint rule is handed whatever the parser produced and
+ * narrows on `type` itself, so one node type stands in for several families
+ * and every field is optional.
+ *
+ * @typedef {{ type?: string, name?: string }} AstName
+ *
+ * @typedef {object} Expression
+ * @property {string} [type]
+ * @property {string | number | boolean | null} [value]
+ * @property {Expression} [expression]
+ * @property {Expression[]} [arguments]
+ * @property {TemplateChunk[]} [quasis]
+ * @property {Expression} [left]
+ * @property {Expression} [right]
+ * @property {Expression} [consequent]
+ * @property {Expression} [alternate]
+ *
+ * @typedef {{ value: { cooked?: string | null } }} TemplateChunk
+ * @typedef {{ value?: string | number | boolean | null }} StringLiteral
+ *
+ * @typedef {object} JsxAttribute
+ * @property {string} [type]
+ * @property {AstName} [name]
+ * @property {Expression | null} [value]
+ *
+ * @typedef {object} JsxElement
+ * @property {AstName} [name]
+ * @property {JsxAttribute[]} [attributes]
+ * @property {JsxElement} [openingElement]
+ * @property {JsxElement} [parent]
+ * @property {string} [type]
+ *
+ * @typedef {{ report: (descriptor: { node: unknown, message: string }) => void }} RuleContext
+ */
+
+const FADED_MUTED = /(?:^|[\s:'"`])(?:[\w-]+:)*text-muted-foreground\/\d+/;
+
+/** `bg-white`, `text-black/50`, `dark:border-white`… — @shadcn/lint's
+ *  no-raw-colors covers the palette scales but not these two. */
+const ABSOLUTE_COLOR =
+  /(?:^|[\s'"`])(?:[\w-]+:)*(?:bg|text|border|ring|outline|divide|fill|stroke|from|via|to|decoration|placeholder|caret|accent|shadow)-(?:white|black)(?:\/\d+)?(?=$|[\s'"`])/;
+
+/**
+ * Visits every string and template chunk, so class names in `cn()`, cva
+ * maps and plain constants are all checked, not only `className=`.
+ *
+ * @param {RegExp} test
+ * @param {string} message
+ */
+function stringVisitors(test, message) {
+  /** @param {RuleContext} context */
+  return (context) => {
+    /** @param {unknown} node @param {unknown} value */
+    const check = (node, value) => {
+      if (typeof value === 'string' && test.test(value)) {
+        context.report({ node, message });
+      }
+    };
+
+    return {
+      /** @param {StringLiteral} node */
+      Literal: (node) => check(node, node.value),
+      /** @param {TemplateChunk} node */
+      TemplateElement: (node) => check(node, node.value.cooked),
+    };
+  };
+}
+
+const BADGE_TONES = new Set(['success', 'warning', 'info']);
+
+const TONE_BADGE_MESSAGE =
+  'A tone is not a Badge variant. A record\u2019s state is <StatusBadge tone="…"> from @kit/ui/status-badge, whose dot carries the tone so meaning never rides on hue alone; Badge is for counts, categories and short labels (design-system status-badge rule).';
+
+/** @param {Expression | null | undefined} value */
+function literalValue(value) {
+  if (!value) return null;
+  if (value.type === 'Literal') return value.value;
+  if (
+    value.type === 'JSXExpressionContainer' &&
+    value.expression?.type === 'Literal'
+  ) {
+    return value.expression.value;
+  }
+  return null;
+}
+
+/** @param {AstName | undefined} name */
+function jsxName(name) {
+  return name?.type === 'JSXIdentifier' ? name.name : null;
+}
+
+const OVERLAY_CONTENT = new Set([
+  'DialogContent',
+  'SheetContent',
+  'AlertDialogContent',
+  'DrawerContent',
+]);
+
+/**
+ * `max-w-md`, `sm:w-[560px]`… but not the mobile-width `w-full` / `w-auto`.
+ *
+ * A variant prefix may itself contain brackets (`data-[swipe-direction=right]:`),
+ * so the prefix group has to allow them — `[\w-]+:` alone stopped at the `[`
+ * and let `data-[swipe-direction=right]:sm:max-w-xl` through on two drawer
+ * shells for as long as the rule has existed.
+ */
+const OVERLAY_WIDTH =
+  /(?:^|\s)(?:(?:[\w-]+|\[[^\]]*\]|[\w-]+\[[^\]]*\])+:)*(?:max-w|min-w|w)-(?!full\b|auto\b)\S+/;
+
+const OVERLAY_WIDTH_MESSAGE =
+  'Never set an overlay’s width in className. Dialog, Sheet and Drawer take size="sm|md|lg|xl|2xl|3xl|full" from @kit/ui/overlay-size; AlertDialog takes size="sm" (design-system overlay rule).';
+
+/**
+ * Every string literal in a className value, including inside `cn(...)`.
+ *
+ * @param {Expression | null | undefined} value
+ * @returns {StringLiteral[]}
+ */
+function classNameStrings(value) {
+  if (!value) return [];
+  if (value.type === 'Literal') return [value];
+  if (value.type === 'JSXExpressionContainer') {
+    return classNameStrings(value.expression);
+  }
+  if (value.type === 'CallExpression') {
+    return (value.arguments ?? []).flatMap(classNameStrings);
+  }
+  if (value.type === 'TemplateLiteral') {
+    return (value.quasis ?? []).map((quasi) => ({
+      ...quasi,
+      value: quasi.value.cooked,
+    }));
+  }
+  if (value.type === 'LogicalExpression' || value.type === 'BinaryExpression') {
+    return [...classNameStrings(value.left), ...classNameStrings(value.right)];
+  }
+  if (value.type === 'ConditionalExpression') {
+    return [
+      ...classNameStrings(value.consequent),
+      ...classNameStrings(value.alternate),
+    ];
+  }
+  return [];
+}
+
+/** A rounded hover band with side padding: a row drawn as a pill. Square
+ *  icon buttons (`size-8`, `h-6 w-6`) are a different shape and pass, and so
+ *  does a bordered or filled tile, which is a card rather than a row. */
+/** @param {string} value */
+function isRoundedRowHover(value) {
+  if (/(?:^|\s)border(?=$|\s)/.test(value) || /(?:^|\s)bg-/.test(value)) {
+    return false;
+  }
+
+  if (
+    !/\brounded-(?:md|lg|xl)\b/.test(value) ||
+    !/(?:^|\s)hover:bg-/.test(value) ||
+    !/(?:^|\s)(?:[\w-]+:)*px-/.test(value) ||
+    !/(?:^|\s)(?:w-full|justify-between)(?=$|\s)/.test(value)
+  ) {
+    return false;
+  }
+
+  if (/(?:^|\s)(?:[\w-]+:)*size-/.test(value)) return false;
+
+  const height = /(?:^|\s)h-([\w.[\]]+)(?=$|\s)/.exec(value);
+  const width = /(?:^|\s)w-([\w.[\]]+)(?=$|\s)/.exec(value);
+
+  return !(height && width && height[1] === width[1]);
+}
+
+const CHIP_TONES = ['success', 'primary', 'warning', 'destructive', 'info'];
+
+const CHIP_SMALL_TEXT = /(?:^|\s)(?:[\w-]+:)*text-(?:xs|sm)(?=$|\s)/;
+
+/** Base-tone small text on a tint of the same tone. */
+/** @param {string} value */
+function isWeakTintedChip(value) {
+  if (!CHIP_SMALL_TEXT.test(value)) return false;
+
+  return CHIP_TONES.some(
+    (tone) =>
+      new RegExp(`(?:^|\\s)(?:[\\w-]+:)*bg-${tone}/\\d+`).test(value) &&
+      new RegExp(`(?:^|\\s)(?:[\\w-]+:)*text-${tone}(?![\\w-])`).test(value),
+  );
+}
+
+/**
+ * @param {(value: string) => boolean} predicate
+ * @param {string} message
+ */
+function predicateVisitors(predicate, message) {
+  /** @param {RuleContext} context */
+  return (context) => {
+    /** @param {unknown} node @param {unknown} value */
+    const check = (node, value) => {
+      if (typeof value === 'string' && predicate(value)) {
+        context.report({ node, message });
+      }
+    };
+
+    return {
+      /** @param {StringLiteral} node */
+      Literal: (node) => check(node, node.value),
+      /** @param {TemplateChunk} node */
+      TemplateElement: (node) => check(node, node.value.cooked),
+    };
+  };
+}
+
+/**
+ * A viewport breakpoint variant anywhere in a class token's variant chain:
+ * `sm:grid-cols-2`, `hover:md:flex`, `max-lg:hidden`. Container variants
+ * (`@sm/widget:`) start with `@` and pass.
+ */
+const VIEWPORT_BREAKPOINT =
+  /(?:^|\s)(?:[\w-]+:)*(?:max-)?(?:sm|md|lg|xl|2xl):[^\s:]/;
+
+const TOOLBAR_TAB_ELEMENTS = new Set(['TabsList', 'ScopePills', 'ScopeLinks']);
+const TOOLBARS = new Set(['PageToolbar', 'PageToolbarActions']);
+
+export default {
+  meta: { name: 'design' },
+  rules: {
+    'no-tone-badge-variant': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description:
+            'Disallow a status tone as a Badge variant; a record state is StatusBadge.',
+        },
+      },
+      /** @param {RuleContext} context */
+      create(context) {
+        return {
+          /** @param {JsxElement} node */
+          JSXOpeningElement(node) {
+            if (
+              node.name?.type !== 'JSXIdentifier' ||
+              node.name.name !== 'Badge'
+            ) {
+              return;
+            }
+
+            for (const attribute of node.attributes ?? []) {
+              if (
+                attribute.type !== 'JSXAttribute' ||
+                attribute.name?.name !== 'variant'
+              ) {
+                continue;
+              }
+
+              const value = literalValue(attribute.value);
+
+              if (typeof value === 'string' && BADGE_TONES.has(value)) {
+                context.report({
+                  node: attribute,
+                  message: TONE_BADGE_MESSAGE,
+                });
+              }
+            }
+          },
+        };
+      },
+    },
+    'no-faded-muted-text': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description:
+            'Disallow an opacity modifier on text-muted-foreground; every step below 100 fails contrast somewhere.',
+        },
+      },
+      create: stringVisitors(
+        FADED_MUTED,
+        'Opacity on text-muted-foreground fails WCAG AA: even /90 measures 4.18:1 on a dark card. Use plain text-muted-foreground, a smaller size if it must recede, or text-border for a decorative separator (design-system opacity-on-muted rule).',
+      ),
+    },
+    'no-absolute-colors': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description:
+            'Disallow white/black color utilities; they ignore the theme, dark mode and Source branding.',
+        },
+      },
+      create: stringVisitors(
+        ABSOLUTE_COLOR,
+        'white/black color utilities ignore the theme, dark mode and Source branding. Use a token: bg-card or bg-background for surfaces, text-foreground / text-primary-foreground for text. A modal scrim may stay black with a disable comment saying so (design-system theming rule).',
+      ),
+    },
+    'no-overlay-width-class': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description:
+            'Disallow width classes on overlay content; overlays take a size from the overlay-size scale.',
+        },
+      },
+      /** @param {RuleContext} context */
+      create(context) {
+        return {
+          /** @param {JsxElement} node */
+          JSXOpeningElement(node) {
+            if (!OVERLAY_CONTENT.has(jsxName(node.name) ?? '')) return;
+
+            for (const attribute of node.attributes ?? []) {
+              if (
+                attribute.type !== 'JSXAttribute' ||
+                attribute.name?.name !== 'className'
+              ) {
+                continue;
+              }
+
+              const flagged = classNameStrings(attribute.value).some(
+                (literal) =>
+                  typeof literal.value === 'string' &&
+                  OVERLAY_WIDTH.test(literal.value),
+              );
+
+              if (flagged) {
+                context.report({
+                  node: attribute,
+                  message: OVERLAY_WIDTH_MESSAGE,
+                });
+              }
+            }
+          },
+        };
+      },
+    },
+    'no-rounded-row-hover': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description:
+            'Disallow a rounded hover pill on a padded row; rows are flat edge-to-edge bands.',
+        },
+      },
+      create: predicateVisitors(
+        isRoundedRowHover,
+        'Rows are flat edge-to-edge bands: padding on the row (px-5 py-3), a flat hover:bg-accent/50, never a rounded pill with side padding (design-system edge-to-edge rows rule).',
+      ),
+    },
+    'tinted-chip-strong': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description:
+            'Require the -strong text step for small text on a tint of its own colour.',
+        },
+      },
+      create: predicateVisitors(
+        isWeakTintedChip,
+        'Small text on a tint of its own colour takes the -strong step: text-success-strong on bg-success/10, text-primary-strong on bg-primary/10. The base token fails AA once it sits on its own wash; it stays right for the fill and for icons (design-system tinted-chip rule).',
+      ),
+    },
+    'no-viewport-breakpoints-in-widgets': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description:
+            'Disallow viewport breakpoints in widget code; a widget sizes to its own container.',
+        },
+      },
+      create: stringVisitors(
+        VIEWPORT_BREAKPOINT,
+        'A widget sits in a half-width column, a full row or a tile, whatever the viewport, so sm:/md:/lg: misfire. Size to the card with container queries: Widget.Card is @container/widget, so write @sm/widget:grid-cols-2 (design-system widget rules).',
+      ),
+    },
+    'no-toolbar-tabs': {
+      meta: {
+        type: 'problem',
+        docs: {
+          description: 'Disallow tabs or scope pills inside a PageToolbar.',
+        },
+      },
+      /** @param {RuleContext} context */
+      create(context) {
+        return {
+          /** @param {JsxElement} node */
+          JSXOpeningElement(node) {
+            if (!TOOLBAR_TAB_ELEMENTS.has(jsxName(node.name) ?? '')) return;
+
+            for (let parent = node.parent; parent; parent = parent.parent) {
+              if (
+                parent.type === 'JSXElement' &&
+                parent !== node.parent &&
+                TOOLBARS.has(jsxName(parent.openingElement?.name) ?? '')
+              ) {
+                context.report({
+                  node,
+                  message:
+                    'No tabs inside a PageToolbar. View tabs go in PageTitleSection’s `tabs` prop; a filter over one list goes in that card’s ListMasthead (page-layout view-tabs rule).',
+                });
+                return;
+              }
+            }
+          },
+        };
+      },
+    },
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The official SDK for building Ekanos integrations.",
   "bugs": {
     "email": "npm@govastly.com"
@@ -12,7 +12,9 @@
     "README.md",
     "api-report.md",
     "LICENSE",
-    "eslint.preset.mjs"
+    "eslint.preset.mjs",
+    "eslint.design-preset.mjs",
+    "eslint.design-rules.mjs"
   ],
   "type": "module",
   "sideEffects": [
@@ -23,6 +25,9 @@
       "context": [
         "dist/context/index.d.ts"
       ],
+      "layout": [
+        "dist/layout/index.d.ts"
+      ],
       "testing": [
         "dist/testing/index.d.ts"
       ],
@@ -51,6 +56,10 @@
       "types": "./dist/context/index.d.ts",
       "default": "./dist/context/index.js"
     },
+    "./layout": {
+      "types": "./dist/layout/index.d.ts",
+      "default": "./dist/layout/index.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
@@ -59,14 +68,15 @@
       "types": "./dist/integration/index.d.ts",
       "default": "./dist/integration/index.js"
     },
-    "./eslint": "./eslint.preset.mjs"
+    "./eslint": "./eslint.preset.mjs",
+    "./eslint/design": "./eslint.design-preset.mjs"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@ekanos/integration-schema": "0.6.0",
-    "@ekanos/ui": "0.6.0",
+    "@ekanos/integration-schema": "0.7.0",
+    "@ekanos/ui": "0.7.0",
     "@supabase/supabase-js": "2.87.1",
     "server-only": "^0.0.1"
   },