@hirobius/design-system 0.19.1 → 0.21.0

package/scripts/eslint-plugin-hds/rules/no-raw-px-spacing.mjs

@@ -0,0 +1,125 @@
+/**
+ * hds/no-raw-px-spacing
+ *
+ * Disallows raw pixel strings (`'16px'`) or bare numeric literals (`16`) on
+ * margin/padding/gap family properties inside a JSX `style={{ ... }}`
+ * object. Zero is exempt (a reset has no scale to violate). Mirrors the
+ * intent of scripts/check-hardcoded-spacing.mjs for consumer app code.
+ *
+ * The fix it offers is the t-shirt scale token, and, where Box `sx` has a
+ * key for the same CSS property, that key with a step name. Box `sx` resolves
+ * step names on its spacing keys only (`mb: 'md'`); a long-hand key
+ * (`marginBottom: 'md'`) passes through as invalid CSS and renders no
+ * spacing, so the message names the shorthand, never the flagged prop.
+ */
+import {
+  attrName,
+  jsxObjectExpression,
+  numberLiteralValue,
+  propName,
+  stringLiteralValue,
+} from './utils.mjs';
+
+const SPACING_PROPS = new Set([
+  'margin',
+  'marginTop',
+  'marginBottom',
+  'marginLeft',
+  'marginRight',
+  'marginBlock',
+  'marginInline',
+  'marginBlockStart',
+  'marginBlockEnd',
+  'marginInlineStart',
+  'marginInlineEnd',
+  'padding',
+  'paddingTop',
+  'paddingBottom',
+  'paddingLeft',
+  'paddingRight',
+  'paddingBlock',
+  'paddingInline',
+  'paddingBlockStart',
+  'paddingBlockEnd',
+  'paddingInlineStart',
+  'paddingInlineEnd',
+  'gap',
+  'rowGap',
+  'columnGap',
+]);
+
+// Long-hand style prop → the Box sx key that sets the same CSS property and
+// resolves t-shirt steps (src/app/components/box-sx.ts SPACING_PROP_MAP).
+// Logical props have none: sx `mx`/`my`/`px`/`py` set physical sides, which
+// match `*Inline`/`*Block` only in horizontal writing modes.
+const SX_SHORTHAND = {
+  margin: 'm',
+  marginTop: 'mt',
+  marginBottom: 'mb',
+  marginLeft: 'ml',
+  marginRight: 'mr',
+  padding: 'p',
+  paddingTop: 'pt',
+  paddingBottom: 'pb',
+  paddingLeft: 'pl',
+  paddingRight: 'pr',
+  gap: 'gap',
+  rowGap: 'rowGap',
+  columnGap: 'columnGap',
+};
+
+const PX_STRING_RE = /^-?\d+(?:\.\d+)?px$/;
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow raw px strings or bare numbers on margin/padding/gap in inline style — use an HDS spacing token.',
+      recommended: true,
+      url: 'https://github.com/hirobius/hds/blob/main/scripts/eslint-plugin-hds/README.md#hdsno-raw-px-spacing',
+    },
+    schema: [],
+    messages: {
+      rawPxSpacing:
+        'Raw spacing value "{{value}}" on "{{prop}}" bypasses the HDS spacing scale. Use hds.semantic.space.scale.* (var(--semantic-space-scale-*)), or Box sx prop "{{sxProp}}" with a t-shirt step such as "md".',
+      rawPxSpacingNoSxShorthand:
+        'Raw spacing value "{{value}}" on "{{prop}}" bypasses the HDS spacing scale. Use hds.semantic.space.scale.* (var(--semantic-space-scale-*)). Box sx has no shorthand for "{{prop}}", so its t-shirt steps do not apply.',
+    },
+  },
+  create(context) {
+    function report(node, prop, value) {
+      const sxProp = Object.hasOwn(SX_SHORTHAND, prop) ? SX_SHORTHAND[prop] : undefined;
+      context.report(
+        sxProp
+          ? { node, messageId: 'rawPxSpacing', data: { prop, value, sxProp } }
+          : { node, messageId: 'rawPxSpacingNoSxShorthand', data: { prop, value } },
+      );
+    }
+
+    return {
+      JSXAttribute(node) {
+        if (attrName(node) !== 'style') return;
+        const obj = jsxObjectExpression(node.value);
+        if (!obj) return;
+
+        for (const prop of obj.properties) {
+          if (prop.type !== 'Property') continue;
+          const name = propName(prop.key);
+          if (!name || !SPACING_PROPS.has(name)) continue;
+
+          const strVal = stringLiteralValue(prop.value);
+          if (strVal != null && PX_STRING_RE.test(strVal)) {
+            report(prop.value, name, strVal);
+            continue;
+          }
+
+          const numVal = numberLiteralValue(prop.value);
+          if (numVal != null && numVal !== 0) {
+            report(prop.value, name, String(numVal));
+          }
+        }
+      },
+    };
+  },
+};

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