ionbase-ui 0.16.0 → 0.18.0

package/dist/tokens/index.js

@@ -1092,7 +1092,7 @@ export const tokenValues = {
         "Value": "#401604"
     },
     "color/green/50": {
-        "Value": "#effbf6"
+        "Value": "#f8fefc"
     },
     "color/green/100": {
         "Value": "#e4f7f3"
@@ -1101,25 +1101,25 @@ export const tokenValues = {
         "Value": "#c6ebdc"
     },
     "color/green/300": {
-        "Value": "#8fdbbb"
+        "Value": "#82d8b4"
     },
     "color/green/400": {
-        "Value": "#50c38c"
+        "Value": "#39b378"
     },
     "color/green/500": {
-        "Value": "#12a154"
+        "Value": "#14994e"
     },
     "color/green/600": {
-        "Value": "#14994e"
+        "Value": "#0d7d38"
     },
     "color/green/700": {
-        "Value": "#0d7d38"
+        "Value": "#076426"
     },
     "color/green/800": {
-        "Value": "#076426"
+        "Value": "#054d1a"
     },
     "color/green/900": {
-        "Value": "#054d1a"
+        "Value": "#023c13"
     },
     "color/blue/50": {
         "Value": "#ebf7ff"

package/eslint-plugin/index.js

@@ -0,0 +1,64 @@
+/**
+ * ionbase-ui/eslint-plugin — the design system's rules, shipped.
+ *
+ *   // eslint.config.js
+ *   import ionbase from 'ionbase-ui/eslint-plugin';
+ *   export default [ionbase.configs.recommended];
+ *
+ * The premise of IonBase is that the code consuming it may be written by an
+ * agent with no developer reviewing the output. Guidance in a README does not
+ * survive that; a lint error naming the fix does.
+ *
+ * Every rule's data comes from dist/meta/components.json — deprecations,
+ * measured contrast failures, which components require an accessible name, the
+ * spacing scale, even Button's default variant. Nothing is hardcoded here, so
+ * when a defect is fixed in Figma the rule stops firing without anyone editing
+ * this package.
+ *
+ * Two rules from the plan are deliberately absent. `destructive-needs-confirm`
+ * wants to know whether a Modal wraps the action, which is almost always in
+ * another file — ESLint's per-file model would make it a false-positive
+ * generator. `no-nested-interactive` needs the same. Both belong in a checker
+ * with whole-tree visibility, or in the eval harness.
+ */
+import noDeprecatedProps from './rules/no-deprecated-props.js';
+import noKnownContrastFailure from './rules/no-known-contrast-failure.js';
+import noRawStyleValues from './rules/no-raw-style-values.js';
+import needsAccessibleName from './rules/needs-accessible-name.js';
+import onePrimaryAction from './rules/one-primary-action.js';
+
+const rules = {
+  'no-deprecated-props': noDeprecatedProps,
+  'no-known-contrast-failure': noKnownContrastFailure,
+  'no-raw-style-values': noRawStyleValues,
+  'needs-accessible-name': needsAccessibleName,
+  'one-primary-action': onePrimaryAction,
+};
+
+const plugin = { meta: { name: 'ionbase-ui' }, rules };
+
+plugin.configs = {
+  /** Everything, as errors. The defaults are what the system considers wrong. */
+  recommended: {
+    name: 'ionbase-ui/recommended',
+    plugins: { 'ionbase-ui': plugin },
+    rules: {
+      'ionbase-ui/no-deprecated-props': 'error',
+      'ionbase-ui/no-known-contrast-failure': 'error',
+      'ionbase-ui/no-raw-style-values': 'error',
+      'ionbase-ui/needs-accessible-name': 'error',
+      'ionbase-ui/one-primary-action': 'error',
+    },
+  },
+  /** Same rules, as warnings — for adopting the system in an existing app. */
+  warn: {
+    name: 'ionbase-ui/warn',
+    plugins: { 'ionbase-ui': plugin },
+    rules: Object.fromEntries(
+      Object.keys(rules).map((r) => [`ionbase-ui/${r}`, 'warn']),
+    ),
+  },
+};
+
+export default plugin;
+export { rules };

package/eslint-plugin/meta-data.js

@@ -0,0 +1,66 @@
+/**
+ * Rule data, read from the shipped component contracts.
+ *
+ * Nothing in this plugin hardcodes a component name, a prop, a deprecation or a
+ * contrast ratio. All of it comes from dist/meta/components.json, which is
+ * generated from the source and the stylesheets and gated by verify-meta.mjs and
+ * verify-contrast.mjs. A second hand-maintained copy here would drift, and a
+ * drifted lint rule is worse than none — it teaches the wrong thing confidently.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+let doc;
+try {
+  doc = JSON.parse(
+    readFileSync(join(HERE, '..', 'dist', 'meta', 'components.json'), 'utf8'),
+  );
+} catch {
+  // A source checkout before its first build. Rules degrade to no-ops rather
+  // than crashing the consumer's lint run.
+  doc = { components: {} };
+}
+
+export const components = doc.components ?? {};
+export const isComponent = (name) => Object.hasOwn(components, name);
+
+/** { Button: [{ prop, replacement, note }] } — only where the source really says @deprecated. */
+export const deprecations = Object.fromEntries(
+  Object.entries(components)
+    .filter(([, c]) => (c.deprecated ?? []).length)
+    .map(([n, c]) => [n, c.deprecated]),
+);
+
+/** Components whose contract says an accessible name is required. */
+export const needsAccessibleName = Object.entries(components)
+  .filter(([, c]) =>
+    (c.a11y?.requires ?? []).some((r) => /aria-label|accessible name/i.test(r)),
+  )
+  .map(([n]) => n);
+
+/** Measured contrast defects, with the prop combination that reaches them. */
+export const contrastIssues = Object.entries(components).flatMap(([n, c]) =>
+  (c.a11y?.knownIssues ?? [])
+    .filter((i) => i.appliesTo)
+    .map((i) => ({ component: n, ...i })),
+);
+
+/** The spacing rungs, for suggesting a token in place of a raw pixel value. */
+export const spacingScale = (() => {
+  try {
+    const css = readFileSync(
+      join(HERE, '..', 'dist', 'styles', 'tokens', 'base.css'),
+      'utf8',
+    );
+    const out = {};
+    for (const m of css.matchAll(/(--spacing-(\d+))\s*:\s*([\d.]+)px/g)) {
+      out[Number(m[3])] = m[1];
+    }
+    return out;
+  } catch {
+    return {};
+  }
+})();

package/eslint-plugin/rules/needs-accessible-name.js

@@ -0,0 +1,88 @@
+import { needsAccessibleName, isComponent } from '../meta-data.js';
+
+/**
+ * An icon-only control with no `aria-label` is announced as just "button".
+ *
+ * Which components require a name is not hardcoded — it is every component whose
+ * contract's `a11y.requires` says so. Adding that line to a new component's
+ * intent file is what turns this rule on for it.
+ *
+ * Only fires when the element demonstrably has no text: an expression child
+ * could be anything, so those are left alone rather than guessed at.
+ */
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require an accessible name on icon-only IonBase controls',
+    },
+    schema: [],
+    messages: {
+      unnamed:
+        '{{component}} has no text and no accessible name, so it is announced as just "{{role}}". Add `aria-label`, or give it visible text.',
+    },
+  },
+  create(context) {
+    const named = new Set(needsAccessibleName);
+
+    const hasText = (children) =>
+      children.some((c) => {
+        if (c.type === 'JSXText') return c.value.trim().length > 0;
+        // An expression child might render text — assume it does rather than
+        // report something we cannot see.
+        if (c.type === 'JSXExpressionContainer') return true;
+        return false;
+      });
+
+    /** A child element that is itself an IonBase component is not text. */
+    const onlyIcons = (children) =>
+      children
+        .filter((c) => c.type === 'JSXElement')
+        .every((c) => {
+          const n = c.openingElement.name;
+          return (
+            n.type === 'JSXIdentifier' &&
+            (n.name === 'Icon' || isComponent(n.name) === false)
+          );
+        });
+
+    return {
+      JSXElement(node) {
+        const open = node.openingElement;
+        if (open.name.type !== 'JSXIdentifier') return;
+        const name = open.name.name;
+        if (!named.has(name)) return;
+
+        const attrs = open.attributes.filter((a) => a.type === 'JSXAttribute');
+        // A spread could carry aria-label; do not second-guess it.
+        if (open.attributes.some((a) => a.type === 'JSXSpreadAttribute'))
+          return;
+
+        const attrName = (a) =>
+          a.name.type === 'JSXIdentifier' ? a.name.name : '';
+        if (attrs.some((a) => /^aria-(label|labelledby)$/.test(attrName(a))))
+          return;
+        // `title` on Modal, `label` on Input/Select — the contract's own naming.
+        if (attrs.some((a) => ['title', 'label'].includes(attrName(a)))) return;
+
+        if (hasText(node.children)) return;
+        if (!node.children.length) {
+          // Self-closing with no children and no name at all.
+          context.report({
+            node: open,
+            messageId: 'unnamed',
+            data: { component: name, role: name.toLowerCase() },
+          });
+          return;
+        }
+        if (onlyIcons(node.children)) {
+          context.report({
+            node: open,
+            messageId: 'unnamed',
+            data: { component: name, role: name.toLowerCase() },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint-plugin/rules/no-deprecated-props.js

@@ -0,0 +1,74 @@
+import { deprecations } from '../meta-data.js';
+
+/**
+ * `<Button disabled>` still type-checks — that is exactly why it needs a lint
+ * rule. A deprecation the compiler accepts is one an agent will keep emitting
+ * from whatever it learned before the rename.
+ */
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow props marked @deprecated in the IonBase contracts',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      deprecated:
+        '`{{prop}}` is deprecated on `{{component}}`. Use `{{replacement}}`.',
+      deprecatedNoFix: '`{{prop}}` is deprecated on `{{component}}`.{{note}}',
+    },
+  },
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== 'JSXIdentifier') return;
+        const list = deprecations[node.name.name];
+        if (!list) return;
+
+        for (const attr of node.attributes) {
+          if (
+            attr.type !== 'JSXAttribute' ||
+            attr.name.type !== 'JSXIdentifier'
+          )
+            continue;
+          const hit = list.find((d) => d.prop === attr.name.name);
+          if (!hit) continue;
+
+          if (hit.replacement) {
+            const already = node.attributes.some(
+              (a) =>
+                a.type === 'JSXAttribute' &&
+                a.name.type === 'JSXIdentifier' &&
+                a.name.name === hit.replacement,
+            );
+            context.report({
+              node: attr,
+              messageId: 'deprecated',
+              data: {
+                prop: hit.prop,
+                component: node.name.name,
+                replacement: hit.replacement,
+              },
+              // Only autofix when the replacement is not already present —
+              // renaming into a duplicate would change which value wins.
+              fix: already
+                ? undefined
+                : (fixer) => fixer.replaceText(attr.name, hit.replacement),
+            });
+          } else {
+            context.report({
+              node: attr,
+              messageId: 'deprecatedNoFix',
+              data: {
+                prop: hit.prop,
+                component: node.name.name,
+                note: hit.note ? ` ${hit.note}` : '',
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/eslint-plugin/rules/no-known-contrast-failure.js

@@ -0,0 +1,75 @@
+import { contrastIssues } from '../meta-data.js';
+
+/**
+ * Warn on prop combinations measured to fail WCAG AA.
+ *
+ * The data is whatever verify-contrast.mjs found this build — no list is
+ * maintained here. When a defect is fixed in Figma the measurement changes, the
+ * contract loses the entry, and this rule stops firing on its own.
+ */
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow IonBase prop combinations with measured contrast failures',
+    },
+    schema: [],
+    messages: {
+      fails:
+        '{{component}} {{combo}} measures {{ratio}}:1 against a {{required}}:1 requirement in {{mode}} mode (WCAG {{sc}}{{states}}). Known and not yet fixed.',
+    },
+  },
+  create(context) {
+    const literal = (attr) => {
+      if (!attr.value) return true; // bare prop = true
+      if (attr.value.type === 'Literal') return attr.value.value;
+      if (
+        attr.value.type === 'JSXExpressionContainer' &&
+        attr.value.expression.type === 'Literal'
+      ) {
+        return attr.value.expression.value;
+      }
+      return undefined; // dynamic — cannot judge, so do not
+    };
+
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== 'JSXIdentifier') return;
+        const name = node.name.name;
+
+        for (const issue of contrastIssues) {
+          if (issue.appliesTo.component !== name) continue;
+
+          const props = new Map();
+          for (const a of node.attributes) {
+            if (a.type !== 'JSXAttribute' || a.name.type !== 'JSXIdentifier')
+              continue;
+            props.set(a.name.name, literal(a));
+          }
+
+          const wanted = Object.entries(issue.appliesTo.props ?? {});
+          const matches = wanted.every(([k, v]) => props.get(k) === v);
+          if (!matches) continue;
+
+          context.report({
+            node,
+            messageId: 'fails',
+            data: {
+              component: name,
+              combo: wanted.map(([k, v]) => `${k}="${v}"`).join(' '),
+              ratio: String(issue.ratio),
+              required: String(issue.required),
+              mode: issue.mode,
+              sc: issue.sc,
+              states:
+                issue.states && !issue.states.includes('default')
+                  ? `, ${issue.states.join('/')} state`
+                  : '',
+            },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint-plugin/rules/no-raw-style-values.js

@@ -0,0 +1,107 @@
+import { spacingScale } from '../meta-data.js';
+
+const COLOUR_PROPS =
+  /^(color|backgroundColor|borderColor|border.*Color|outlineColor|fill|stroke)$/;
+const SPACE_PROPS =
+  /^(padding|margin|gap|rowGap|columnGap|(padding|margin)(Top|Right|Bottom|Left|Block|Inline)|borderRadius|top|right|bottom|left)$/;
+const RAW_COLOUR = /^(#[0-9a-f]{3,8}|rgba?\(|hsla?\()/i;
+
+/**
+ * An inline `style={{ color: '#1a73e8' }}` is the single most common way a
+ * generated UI drifts from the system: it type-checks, it renders, and it is
+ * invisible to every other check. It is also the thing a model reaches for when
+ * it cannot recall a token name.
+ *
+ * Spacing suggestions name the exact rung, because "use a token" is advice and
+ * "use var(--spacing-16)" is a fix.
+ */
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow raw colour and spacing values in inline style props',
+    },
+    schema: [],
+    messages: {
+      colour:
+        'Raw colour `{{value}}` in an inline style. Use an IonBase token — `var(--text-default)`, `var(--surface-default)` and the rest are listed in `ionbase-ui/tokens`.',
+      spacingExact:
+        'Raw spacing `{{value}}` in an inline style. That is `var({{token}})`.',
+      spacingOff:
+        'Raw spacing `{{value}}` in an inline style, and it is not on the scale. Nearest rungs are `var({{lower}})` and `var({{upper}})`.',
+    },
+  },
+  create(context) {
+    const rungs = Object.keys(spacingScale)
+      .map(Number)
+      .sort((a, b) => a - b);
+
+    const check = (prop) => {
+      if (prop.type !== 'Property' || prop.computed) return;
+      const key =
+        prop.key.type === 'Identifier'
+          ? prop.key.name
+          : prop.key.type === 'Literal'
+            ? String(prop.key.value)
+            : null;
+      if (!key) return;
+      const v = prop.value;
+      if (v.type !== 'Literal') return;
+
+      if (
+        COLOUR_PROPS.test(key) &&
+        typeof v.value === 'string' &&
+        RAW_COLOUR.test(v.value)
+      ) {
+        context.report({
+          node: v,
+          messageId: 'colour',
+          data: { value: v.value },
+        });
+        return;
+      }
+
+      if (SPACE_PROPS.test(key)) {
+        let px = null;
+        if (typeof v.value === 'number' && v.value !== 0) px = v.value;
+        else if (typeof v.value === 'string') {
+          const m = v.value.match(/^(\d+(?:\.\d+)?)px$/);
+          if (m && Number(m[1]) !== 0) px = Number(m[1]);
+        }
+        if (px === null || !rungs.length) return;
+
+        if (spacingScale[px]) {
+          context.report({
+            node: v,
+            messageId: 'spacingExact',
+            data: { value: String(v.value), token: spacingScale[px] },
+          });
+        } else {
+          const lower = [...rungs].reverse().find((r) => r < px) ?? rungs[0];
+          const upper = rungs.find((r) => r > px) ?? rungs[rungs.length - 1];
+          context.report({
+            node: v,
+            messageId: 'spacingOff',
+            data: {
+              value: String(v.value),
+              lower: spacingScale[lower],
+              upper: spacingScale[upper],
+            },
+          });
+        }
+      }
+    };
+
+    return {
+      JSXAttribute(node) {
+        if (node.name.type !== 'JSXIdentifier' || node.name.name !== 'style')
+          return;
+        if (node.value?.type !== 'JSXExpressionContainer') return;
+        const expr = node.value.expression;
+        if (expr.type !== 'ObjectExpression') return;
+        for (const p of expr.properties) check(p);
+      },
+    };
+  },
+};

package/eslint-plugin/rules/one-primary-action.js

@@ -0,0 +1,128 @@
+import { components } from '../meta-data.js';
+
+/**
+ * Two primary buttons in one dialog is the same as none — nothing indicates the
+ * expected action. Button's own contract says `limit: one per view or dialog`;
+ * this enforces it where it is checkable, which is inside a single Modal in a
+ * single file.
+ *
+ * The default variant counts. `<Button>Save</Button>` IS primary-brand, and that
+ * is exactly the case a reviewer misses, because neither button says "primary".
+ */
+export default {
+  meta: {
+    type: 'problem',
+    docs: { description: 'Allow at most one primary Button inside a Modal' },
+    schema: [],
+    messages: {
+      twoPrimaries:
+        'This Modal has {{count}} primary Buttons. Exactly one action should be primary — make the others `secondary` or `tertiary`.{{implicit}}',
+    },
+  },
+  create(context) {
+    // Read the default from the contract rather than assuming it.
+    const primary =
+      components.Button?.props?.variant?.default ?? 'primary-brand';
+
+    const variantOf = (open) => {
+      for (const a of open.attributes) {
+        if (a.type === 'JSXSpreadAttribute') return null; // unknowable
+        if (a.type !== 'JSXAttribute' || a.name.type !== 'JSXIdentifier')
+          continue;
+        if (a.name.name !== 'variant') continue;
+        if (a.value?.type === 'Literal') return a.value.value;
+        if (
+          a.value?.type === 'JSXExpressionContainer' &&
+          a.value.expression.type === 'Literal'
+        ) {
+          return a.value.expression.value;
+        }
+        return null; // dynamic
+      }
+      return primary; // omitted → the default, which is primary
+    };
+
+    /**
+     * Walk every JSX descendant, including through expression containers —
+     * `{isEditing && <Button/>}` and `{items.map(...)}` both render buttons.
+     * A hand-rolled walk rather than a serialiser: the AST carries circular
+     * `parent` references, so anything generic has to be told about them.
+     */
+    const collect = (node, found, seen = new Set()) => {
+      if (!node || typeof node !== 'object' || seen.has(node)) return;
+      seen.add(node);
+
+      if (node.type === 'JSXElement') {
+        const n = node.openingElement.name;
+        if (n.type === 'JSXIdentifier' && n.name === 'Button') {
+          const v = variantOf(node.openingElement);
+          if (v === primary) {
+            found.push({
+              node,
+              implicit: !node.openingElement.attributes.some(
+                (a) =>
+                  a.type === 'JSXAttribute' &&
+                  a.name.type === 'JSXIdentifier' &&
+                  a.name.name === 'variant',
+              ),
+            });
+          }
+        }
+        // Do not descend into a nested Modal — its buttons are its own problem.
+        if (n.type === 'JSXIdentifier' && n.name === 'Modal' && found.length)
+          return;
+      }
+
+      for (const [key, value] of Object.entries(node)) {
+        if (key === 'parent') continue;
+        if (Array.isArray(value))
+          for (const v of value) collect(v, found, seen);
+        else if (
+          value &&
+          typeof value === 'object' &&
+          typeof value.type === 'string'
+        ) {
+          collect(value, found, seen);
+        }
+      }
+    };
+
+    return {
+      JSXElement(node) {
+        const n = node.openingElement.name;
+        if (n.type !== 'JSXIdentifier' || n.name !== 'Modal') return;
+        const found = [];
+        // Every child, not just JSXElement ones — `{isEditing && <Button/>}` is
+        // a JSXExpressionContainer and renders a button just the same. Skipping
+        // those was the whole bug: the conditional action is exactly the one a
+        // reviewer does not count.
+        const seen = new Set();
+        for (const child of node.children) collect(child, found, seen);
+        // `footer={<>...</>}` is where Modal actions actually go.
+        for (const a of node.openingElement.attributes) {
+          if (
+            a.type === 'JSXAttribute' &&
+            a.value?.type === 'JSXExpressionContainer' &&
+            (a.value.expression.type === 'JSXElement' ||
+              a.value.expression.type === 'JSXFragment')
+          ) {
+            collect(a.value.expression, found, seen);
+          }
+        }
+        if (found.length > 1) {
+          const implicit = found.filter((f) => f.implicit).length;
+          context.report({
+            node: found[found.length - 1].node.openingElement,
+            messageId: 'twoPrimaries',
+            data: {
+              count: String(found.length),
+              implicit: implicit
+                ? ` ${implicit} of them has no \`variant\`, which defaults to \`${primary}\`.`
+                : '',
+            },
+          });
+        }
+      },
+    };
+  },
+};