@hirobius/design-system 0.20.0 → 0.22.0

package/scripts/eslint-plugin-hds/rules/prefer-hds-layout-primitive.mjs

@@ -0,0 +1,54 @@
+/**
+ * hds/prefer-hds-layout-primitive
+ *
+ * Warns (never errors) on ad-hoc `display: 'flex' | 'grid'` inside an
+ * inline `style={{ ... }}` object, where a named HDS layout primitive
+ * (Stack for flex, Grid for grid — see src/app/components/box.tsx's
+ * "reach for Stack/Grid/Container first" guidance) likely fits better than
+ * a one-off flex/grid container. Intentionally a warning: ad-hoc flex is
+ * sometimes the right call (e.g. deeply nested one-off alignment), so this
+ * nudges rather than blocks.
+ */
+import { attrName, jsxObjectExpression, propName, stringLiteralValue } from './utils.mjs';
+
+const FLEX_GRID_RE = /^(?:inline-)?(flex|grid)$/;
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Warn on ad-hoc display:flex/grid in inline style where a named HDS layout primitive (Stack/Grid) likely fits.',
+      recommended: true,
+      url: 'https://github.com/hirobius/hds/blob/main/scripts/eslint-plugin-hds/README.md#hdsprefer-hds-layout-primitive',
+    },
+    schema: [],
+    messages: {
+      preferPrimitive:
+        'Ad-hoc "display: {{display}}" in inline style — consider the named HDS layout primitive (Stack for flex, Grid for grid) instead of a one-off flex/grid container.',
+    },
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        if (attrName(node) !== 'style') return;
+        const obj = jsxObjectExpression(node.value);
+        if (!obj) return;
+
+        const displayProp = obj.properties.find(
+          (p) => p.type === 'Property' && propName(p.key) === 'display',
+        );
+        if (!displayProp) return;
+
+        const value = stringLiteralValue(displayProp.value);
+        if (value != null && FLEX_GRID_RE.test(value)) {
+          context.report({
+            node: displayProp.value,
+            messageId: 'preferPrimitive',
+            data: { display: value },
+          });
+        }
+      },
+    };
+  },
+};

package/scripts/eslint-plugin-hds/rules/sx-token-first.mjs

@@ -0,0 +1,111 @@
+/**
+ * hds/sx-token-first
+ *
+ * Errors on raw hex colors or raw px strings inside a `sx={{ ... }}` prop
+ * (Box's token-first layout engine — src/app/components/box.tsx). `sx` is
+ * the sanctioned escape hatch specifically because it forces spacing/color
+ * through HDS tokens. The spacing shorthands (`p`, `m`, `gap`, ...) take the
+ * t-shirt scale by name ('xs' | 'sm' | 'md' | 'lg' | 'xl', hds#206), and the
+ * fix this rule offers on them points there. No other key resolves those names
+ * (`width: 'md'` is invalid CSS), so a px string anywhere else is pointed at a
+ * token (`hds.space.*` or a `var(--...)`). Bare numbers still resolve off the
+ * 4px space scale (`p: 4` is 16px), so this rule does NOT flag them — only
+ * values that prove the author reached past the token system (hex strings,
+ * explicit 'Npx' strings). Nested objects (responsive `{ xs, sm, ... }` and
+ * `&`-selector blocks) are walked recursively since sx supports both; a value
+ * in a responsive map is reported against the key the map sits on.
+ */
+import { attrName, jsxObjectExpression, propName, stringLiteralValue } from './utils.mjs';
+
+const HEX_RE = /#[0-9a-fA-F]{3,4}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{8}\b/;
+const PX_STRING_RE = /-?\d+(?:\.\d+)?px/;
+
+// The Box sx keys whose values go through the spacing resolver, the only
+// keys that take the t-shirt names (box-sx.ts SPACING_PROP_MAP).
+const SPACING_KEYS = new Set([
+  'm',
+  'mt',
+  'mr',
+  'mb',
+  'ml',
+  'mx',
+  'my',
+  'p',
+  'pt',
+  'pr',
+  'pb',
+  'pl',
+  'px',
+  'py',
+  'gap',
+  'rowGap',
+  'columnGap',
+]);
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow raw hex/px string values inside Box sx — sx must resolve colors and spacing through HDS token keys.',
+      recommended: true,
+      url: 'https://github.com/hirobius/hds/blob/main/scripts/eslint-plugin-hds/README.md#hdssx-token-first',
+    },
+    schema: [],
+    messages: {
+      rawHexInSx:
+        'Raw hex color "{{value}}" in sx prop "{{prop}}" bypasses HDS color tokens. Use a dotted token key (e.g. "content.primary", "surface.raised", "accent").',
+      rawPxInSx:
+        'Raw px string "{{value}}" in sx prop "{{prop}}" bypasses the HDS spacing scale. Use a t-shirt step: "xs" | "sm" | "md" | "lg" | "xl" (8/16/24/32/48px at comfortable density; compact tightens them).',
+      rawPxInSxNonSpacing:
+        'Raw px string "{{value}}" in sx prop "{{prop}}" bypasses HDS tokens. Use a token: an hds.space.* value or a var(--...) such as "var(--primitive-space-4)". Spacing step names apply to the spacing props (p, m, gap, ...) only.',
+    },
+  },
+  create(context) {
+    /**
+     * @param objExpr an sx object, an `&`-selector block, or a responsive map
+     * @param mapKey the key a responsive map sits on (null for an sx object or
+     *   an `&` block, whose keys are real sx keys)
+     */
+    function walk(objExpr, mapKey = null) {
+      for (const prop of objExpr.properties) {
+        if (prop.type !== 'Property') continue; // skip SpreadElement
+        const name = propName(prop.key) ?? '?';
+
+        if (prop.value.type === 'ObjectExpression') {
+          // '&'-selector nesting holds sx keys again; anything else is a
+          // responsive { xs, sm, ... } map on this key.
+          walk(prop.value, name.startsWith('&') ? null : (mapKey ?? name));
+          continue;
+        }
+
+        const value = stringLiteralValue(prop.value);
+        if (value == null) continue;
+        const key = mapKey ?? name;
+
+        if (HEX_RE.test(value)) {
+          context.report({
+            node: prop.value,
+            messageId: 'rawHexInSx',
+            data: { value, prop: key },
+          });
+        } else if (PX_STRING_RE.test(value)) {
+          context.report({
+            node: prop.value,
+            messageId: SPACING_KEYS.has(key) ? 'rawPxInSx' : 'rawPxInSxNonSpacing',
+            data: { value, prop: key },
+          });
+        }
+      }
+    }
+
+    return {
+      JSXAttribute(node) {
+        if (attrName(node) !== 'sx') return;
+        const obj = jsxObjectExpression(node.value);
+        if (!obj) return;
+        walk(obj);
+      },
+    };
+  },
+};

package/scripts/eslint-plugin-hds/rules/utils.mjs

@@ -0,0 +1,66 @@
+/**
+ * Shared AST helpers for the HDS ESLint rules. Deliberately AST-based (not
+ * regex-over-source-text like the repo's internal scripts/check-*.mjs
+ * guardrails) because this plugin runs inside consumers' own ESLint configs
+ * against arbitrary TSX, where a plain parser is already available and gives
+ * us exact node types for free.
+ */
+
+/** Resolve a JSXAttribute's name, e.g. `style` / `className` / `sx`. */
+export function attrName(node) {
+  return node.name && node.name.type === 'JSXIdentifier' ? node.name.name : null;
+}
+
+/** Resolve an ObjectExpression Property key to a plain string, or null. */
+export function propName(key) {
+  if (!key) return null;
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' && typeof key.value === 'string') return key.value;
+  return null;
+}
+
+/**
+ * Resolve a JSXAttribute's `{ ... }` expression to the ObjectExpression it
+ * wraps, e.g. `style={{ margin: 0 }}` -> the `{ margin: 0 }` ObjectExpression.
+ * Returns null for anything else (identifiers, spreads-only, conditional
+ * expressions, etc.) — this plugin only understands literal object props.
+ */
+export function jsxObjectExpression(attrValueNode) {
+  if (!attrValueNode || attrValueNode.type !== 'JSXExpressionContainer') return null;
+  const expr = attrValueNode.expression;
+  return expr && expr.type === 'ObjectExpression' ? expr : null;
+}
+
+/**
+ * Resolve a plain string literal value from a node — covers `'x'`/`"x"` and
+ * zero-interpolation template literals (`` `x` ``). Returns null for
+ * anything computed (identifiers, member expressions, interpolated
+ * templates) — this plugin only flags values it can prove are raw.
+ */
+export function stringLiteralValue(node) {
+  if (!node) return null;
+  if (node.type === 'Literal' && typeof node.value === 'string') return node.value;
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    return node.quasis.map((q) => q.value.cooked ?? '').join('');
+  }
+  return null;
+}
+
+/**
+ * Resolve a numeric literal value from a node, including unary-minus
+ * (`-8`), which the estree parser represents as UnaryExpression, not a
+ * negative Literal. Returns null for anything else.
+ */
+export function numberLiteralValue(node) {
+  if (!node) return null;
+  if (node.type === 'Literal' && typeof node.value === 'number') return node.value;
+  if (
+    node.type === 'UnaryExpression' &&
+    node.operator === '-' &&
+    node.argument.type === 'Literal' &&
+    typeof node.argument.value === 'number'
+  ) {
+    return -node.argument.value;
+  }
+  return null;
+}