@instruments/materia-ui 0.4.1 → 0.4.3

package/dist/styles/index.css

@@ -13,7 +13,6 @@
 @import "./fonts.css";
 
 @plugin "tailwindcss-animate";
-@plugin "@tailwindcss/typography";
 
 @custom-variant dark (&:is(.dark *));
 

package/dist/utils/cn-theme.js

@@ -1,4 +1,4 @@
-// GENERATED by scripts/generate-cn-theme.mjs - do not edit.
+// GENERATED by scripts/generate-cn-theme.ts - do not edit.
 // Regenerate with `pnpm generate:cn-theme` after changing index.css; the
 // cn test fails when a token or utility there no longer merges.
 /** The house tokens and utilities `cn` resolves conflicts between. */

package/lint/README.md

@@ -11,7 +11,7 @@ Guardrails that keep app code inside the design system. The four rules below are
 
 The import restrictions are Oxlint config fragments because every unit in this repo lints with `@howells/lint` (oxlint). The hex and arbitrary-value rules scan class strings, which no import-level linter can see, so they run as a small Node script.
 
-The two fragments live at the repo root rather than in this package: they are repo-local policy, extended by each unit's own `oxlint.config.ts`, and each carries the `@doctrine` sentence and the published ban message that `lint/doctrine-rules.mjs` and `scripts/generate-docs-manifest.mjs` hydrate the doctrine page from.
+The two fragments live at the repo root rather than in this package: they are repo-local policy, extended by each unit's own `oxlint.config.ts`, and each carries the `@doctrine` sentence and the published ban message that `lint/doctrine-rules.mjs` and `scripts/generate-docs-manifest.ts` hydrate the doctrine page from.
 
 ## Rollout - enable per rule, not all-or-nothing
 
@@ -112,5 +112,9 @@ Run the scanner as part of your lint script. It is exposed as the `materia-ui-li
 | `--all` | enable both rules |
 | `--no-hex` | disable the hex rule |
 | `--exclude <substr>` | skip any file whose path contains `<substr>` (repeatable) |
+| `--json` | print one JSON document, `{ violations, rules, files }`, instead of text lines |
+| `--help` | print usage and exit |
 
-The scanner scopes detection to class strings only: `class`/`className` attribute values and the argument lists of `cn` / `clsx` / `cva` / `tv` / `twMerge` / `twJoin` / `classNames`. Inline `style={{ … }}` colours and ordinary colour constants are not flagged. It exits non-zero and prints `file:line:col  rule  value  message` for each violation.
+The scanner scopes detection to class strings only: `class`/`className` attribute values and the argument lists of `cn` / `clsx` / `cva` / `tv` / `twMerge` / `twJoin` / `classNames`. Inline `style={{ … }}` colours and ordinary colour constants are not flagged. It prints `file:line:col  rule  value  message` for each violation.
+
+Exit codes: `0` clean, `1` violations found, `2` usage error (unknown flag, no paths), `3` a path could not be read.

package/lint/doctrine-rules.mjs

@@ -6,7 +6,7 @@
  * layer matrix, one api-drift gate) with NO single source file. This module is
  * the one place that names them as a coherent set. It carries only the stable
  * editorial framing (id / name / one-line statement / which gates enforce it);
- * `scripts/generate-docs-manifest.mjs` HYDRATES each rule at build time with the
+ * `scripts/generate-docs-manifest.ts` HYDRATES each rule at build time with the
  * live data it must never restate by hand:
  *
  *   - `restrictedImports` - the import bans read straight out of the repo's
@@ -14,7 +14,7 @@
  *     `{ group, message }` (see `IMPORT_BAN_SOURCES`). A rule opts in via
  *     `banMatch`, a substring matched against those live messages.
  *   - `matrix` / `layers` - the layer dependency matrix imported from
- *     scripts/layer-matrix.mjs's exported `LAYERS` / `ALLOWED`.
+ *     scripts/layer-matrix.ts's exported `LAYERS` / `ALLOWED`.
  *   - per-gate `doctrine` prose - the single `@doctrine` sentinel line in each
  *     gate script's header, extracted by a strict tag-line parse.
  *
@@ -92,7 +92,7 @@ export const DOCTRINE_RULES = [
     kind: "layer-matrix",
     statement:
       "The six src layers form a strict one-directional dependency matrix (data ← tokens ← utils ← hooks ← components ← compositions); tokens additionally take no external packages.",
-    gates: ["packages/ui/scripts/layer-matrix.mjs"],
+    gates: ["packages/ui/scripts/layer-matrix.ts"],
   },
   {
     id: "no-naked-element",
@@ -106,6 +106,6 @@ export const DOCTRINE_RULES = [
     name: "API surface drift gate",
     statement:
       "The full public export surface is captured as resolved-type hashes in api-report.md; any change to a public signature flips a hash and fails the gate until the report is regenerated and reviewed.",
-    gates: ["packages/ui/scripts/generate-api-report.mjs"],
+    gates: ["packages/ui/scripts/generate-api-report.ts"],
   },
 ];

package/lint/oxlint/index.d.mts

@@ -1,12 +1,19 @@
-/** One rule of the plugin: its metadata and the visitor factory oxlint calls. */
+// GENERATED by scripts/generate-lint-types.ts from the JSDoc in lint/oxlint/index.mjs - do not edit.
+// Regenerate with `pnpm --filter @instruments/materia-ui generate:lint-types`.
+
+/**
+ * One rule of the plugin: its metadata and the visitor factory oxlint calls.
+ */
 export interface MateriaRule {
   readonly meta: {
     readonly type: "problem";
-    readonly docs: { readonly description: string };
+    readonly docs: {
+      readonly description: string;
+    };
     readonly messages: Readonly<Record<string, string>>;
     readonly schema: readonly unknown[];
   };
-  readonly create: (context: unknown) => Record<string, unknown>;
+  readonly create: (context: never) => object;
 }
 
 /**
@@ -14,11 +21,12 @@ export interface MateriaRule {
  * rules as `materia-ui/no-naked-element` and `materia-ui/no-render-layout-as`.
  */
 declare const plugin: {
-  readonly meta: { readonly name: "materia-ui" };
+  readonly meta: {
+    readonly name: "materia-ui";
+  };
   readonly rules: {
     readonly "no-naked-element": MateriaRule;
     readonly "no-render-layout-as": MateriaRule;
   };
 };
-
 export default plugin;

package/lint/oxlint/index.mjs

@@ -1,6 +1,32 @@
 import { rule as noNakedElement } from "./no-naked-element.mjs";
 import { rule as noRenderLayoutAs } from "./no-render-layout-as.mjs";
 
+/**
+ * One rule of the plugin: its metadata and the visitor factory oxlint calls.
+ *
+ * @typedef {{
+ *   readonly meta: {
+ *     readonly type: "problem";
+ *     readonly docs: { readonly description: string };
+ *     readonly messages: Readonly<Record<string, string>>;
+ *     readonly schema: readonly unknown[];
+ *   };
+ *   readonly create: (context: never) => object;
+ * }} MateriaRule
+ */
+
+/**
+ * The `materia-ui` oxlint plugin. Load it through `jsPlugins` and enable its
+ * rules as `materia-ui/no-naked-element` and `materia-ui/no-render-layout-as`.
+ *
+ * @type {{
+ *   readonly meta: { readonly name: "materia-ui" };
+ *   readonly rules: {
+ *     readonly "no-naked-element": MateriaRule;
+ *     readonly "no-render-layout-as": MateriaRule;
+ *   };
+ * }}
+ */
 const plugin = {
   meta: {
     name: "materia-ui",

package/lint/oxlint/no-naked-element.mjs

@@ -10,6 +10,20 @@
 //
 // @doctrine Application markup renders only design-system components - every raw lowercase HTML host element is lint-banned, leaving the closed polymorphic `as` vocabulary and a tokens-policed className as the only routes to the metal.
 
+/** @typedef {Parameters<import("oxlint/plugins-dev").RuleTester["run"]>[1]} Rule */
+/** @typedef {NonNullable<Rule["create"]>} Create */
+/** @typedef {Parameters<Create>[0]} Context */
+/** @typedef {ReturnType<Create>} Visitor */
+/** @typedef {Parameters<NonNullable<Visitor["JSXOpeningElement"]>>[0]} OpeningElement */
+/** @typedef {Extract<OpeningElement["attributes"][number], { type: "JSXAttribute" }>} Attribute */
+/** @typedef {NonNullable<Attribute["value"]>} AttributeValue */
+/** @typedef {Extract<AttributeValue, { type: "JSXExpressionContainer" }>["expression"]} Expression */
+/** @typedef {Extract<Expression, { type: "CallExpression" }>["arguments"][number]} Argument */
+/** @typedef {Extract<Expression, { type: "TemplateLiteral" }>} TemplateLiteral */
+/** @typedef {Extract<Expression, { type: "Literal"; value: string }>} StringLiteral */
+/** @typedef {Context["options"][number]} OptionValue */
+/** @typedef {Extract<OptionValue, Record<string, OptionValue>>} OptionObject */
+
 /**
  * Map of raw HTML tag → the design-system replacement guidance surfaced in the
  * diagnostic. Every member of the tokens `LAYOUT_ELEMENTS` / `TEXT_ELEMENTS`
@@ -67,14 +81,16 @@ const ESCAPE_HATCH =
  * Build the diagnostic message for a banned raw tag.
  *
  * @param {string} tag lowercase HTML tag name
- * @returns {string}
+ * @returns {string} The message naming the sanctioned replacement.
  */
-export function messageFor(tag) {
-  const guidance = REPLACEMENTS[tag]
-    ? `Use ${REPLACEMENTS[tag]} instead.`
-    : "Use a @instruments/materia-ui component instead.";
+export const messageFor = (tag) => {
+  const replacement = REPLACEMENTS[tag];
+  const guidance =
+    replacement === undefined
+      ? "Use a @instruments/materia-ui component instead."
+      : `Use ${replacement} instead.`;
   return `Raw <${tag}> is banned in the LLM-safe design system. ${guidance} ${ESCAPE_HATCH}`;
-}
+};
 
 /**
  * Hosts a layout primitive can emit through `as` - the tokens `LAYOUT_ELEMENTS`
@@ -110,26 +126,27 @@ const LAYOUT_UTILITY_SET = new Set(LAYOUT_UTILITIES);
  *
  * @param {string} tag lowercase HTML tag name
  * @param {string} utility the layout utility found in its classes
- * @returns {string}
+ * @returns {string} The message naming the layout primitive to use.
  */
-export function layoutMessageFor(tag, utility) {
+export const layoutMessageFor = (tag, utility) => {
   const primitive = utility.endsWith("grid")
     ? "Grid | SimpleGrid"
     : "Flex | Stack | Group | Center";
   const as = tag === "div" ? "" : ` with as="${tag}"`;
   return `Raw <${tag}> with \`${utility}\` is a hand-rolled layout. Use ${primitive}${as} instead. ${ESCAPE_HATCH}`;
-}
+};
 
 /**
  * Whole class tokens of one template literal, dropping any token glued to an
  * interpolation (`size-${n}`), since only its static half is known.
  *
- * @param {{ quasis: Array<{ value: { cooked?: string, raw: string } }> }} node
- * @returns {string[]}
+ * @param {TemplateLiteral} node The template literal.
+ * @returns {string[]} The class tokens whose full text is known.
  */
-function templateTokens(node) {
+const templateTokens = (node) => {
+  /** @type {string[]} */
   const tokens = [];
-  node.quasis.forEach((quasi, index) => {
+  for (const [index, quasi] of node.quasis.entries()) {
     const text = quasi.value.cooked ?? quasi.value.raw;
     const parts = text.split(/\s+/u);
     if (index > 0 && !/^\s/u.test(text)) {
@@ -139,9 +156,16 @@ function templateTokens(node) {
       parts.pop();
     }
     tokens.push(...parts);
-  });
+  }
   return tokens;
-}
+};
+
+/**
+ * @param {Expression | Argument | AttributeValue} node A node that may be a literal.
+ * @returns {node is StringLiteral} Whether it is a string literal.
+ */
+const isStringLiteral = (node) =>
+  node.type === "Literal" && node.value?.constructor === String;
 
 /**
  * Class tokens an expression always contributes: string and template literals,
@@ -149,15 +173,15 @@ function templateTokens(node) {
  * Conditional branches are skipped - a host that is only sometimes a flex
  * container is not a fixed layout.
  *
- * @param {any} node
- * @param {boolean} [inCall]
- * @returns {string[]}
+ * @param {Expression | Argument | AttributeValue | null | undefined} node The class expression.
+ * @param {boolean} [inCall] Whether `node` is already an argument of a helper call.
+ * @returns {string[]} The class tokens that always apply.
  */
-function unconditionalTokens(node, inCall = false) {
+const unconditionalTokens = (node, inCall = false) => {
   if (!node) {
     return [];
   }
-  if (node.type === "Literal" && typeof node.value === "string") {
+  if (isStringLiteral(node)) {
     return node.value.split(/\s+/u);
   }
   if (node.type === "TemplateLiteral") {
@@ -167,31 +191,63 @@ function unconditionalTokens(node, inCall = false) {
     return node.arguments.flatMap((arg) => unconditionalTokens(arg, true));
   }
   return [];
-}
+};
+
+/**
+ * @param {OpeningElement["attributes"][number]} attribute A JSX attribute.
+ * @returns {attribute is Attribute} Whether it is `className`.
+ */
+const isClassName = (attribute) =>
+  attribute.type === "JSXAttribute" &&
+  attribute.name.type === "JSXIdentifier" &&
+  attribute.name.name === "className";
 
 /**
  * The first layout utility among a JSX element's unconditional classes.
  *
- * @param {any} openingElement
- * @returns {string | undefined}
+ * @param {OpeningElement} openingElement The element to inspect.
+ * @returns {string | undefined} The utility, if there is one.
  */
-function layoutUtilityOf(openingElement) {
-  for (const attribute of openingElement.attributes) {
-    if (
-      attribute.type !== "JSXAttribute" ||
-      attribute.name?.name !== "className"
-    ) {
-      continue;
-    }
-    const { value } = attribute;
-    const expression =
-      value?.type === "JSXExpressionContainer" ? value.expression : value;
-    return unconditionalTokens(expression).find((token) =>
-      LAYOUT_UTILITY_SET.has(token)
-    );
+const layoutUtilityOf = (openingElement) => {
+  const value = openingElement.attributes.find(isClassName)?.value;
+  const expression =
+    value?.type === "JSXExpressionContainer" ? value.expression : value;
+  return unconditionalTokens(expression).find((token) =>
+    LAYOUT_UTILITY_SET.has(token)
+  );
+};
+
+/**
+ * @param {OptionValue | undefined} value A rule option.
+ * @returns {value is OptionObject} Whether it is an options object.
+ */
+const isOptionObject = (value) =>
+  value instanceof Object && !Array.isArray(value);
+
+/**
+ * @param {OptionValue | undefined} value An entry of the `allow` option.
+ * @returns {value is string} Whether it is a tag name.
+ */
+const isTagName = (value) => value?.constructor === String;
+
+/**
+ * The rule's options as configured: `allow` names exempt tags and `layoutOnly`
+ * narrows the rule to hand-rolled layout.
+ *
+ * @param {Context} context The rule context.
+ * @returns {{ allow: Set<string>, layoutOnly: boolean }} The options with defaults applied.
+ */
+const readOptions = (context) => {
+  const [option] = context.options;
+  if (!isOptionObject(option)) {
+    return { allow: new Set(), layoutOnly: false };
   }
-  return;
-}
+  const { allow, layoutOnly } = option;
+  return {
+    allow: new Set(Array.isArray(allow) ? allow.filter(isTagName) : []),
+    layoutOnly: layoutOnly === true,
+  };
+};
 
 /**
  * ESLint-style rule factory. Visits every JSX opening element and reports raw
@@ -199,17 +255,17 @@ function layoutUtilityOf(openingElement) {
  * `options[0].layoutOnly`, only layout hosts whose unconditional classes carry
  * a flex or grid display utility report.
  *
- * @param {{ options?: Array<{ allow?: string[], layoutOnly?: boolean }>, report: Function }} context
+ * @param {Context} context The rule context.
+ * @returns {Visitor} The visitor oxlint runs over the file.
  */
-export function create(context) {
-  const allow = new Set(context.options?.[0]?.allow ?? []);
-  const layoutOnly = context.options?.[0]?.layoutOnly === true;
+export const create = (context) => {
+  const { allow, layoutOnly } = readOptions(context);
 
   return {
     JSXOpeningElement(node) {
       const { name } = node;
       // JSXMemberExpression (Foo.Bar) and JSXNamespacedName are never bare hosts.
-      if (name?.type !== "JSXIdentifier") {
+      if (name.type !== "JSXIdentifier") {
         return;
       }
       const tag = name.name;
@@ -233,27 +289,29 @@ export function create(context) {
       }
     },
   };
-}
+};
 
 /** Rule metadata + factory, ready to slot into the plugin's `rules` map. */
-export const rule = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "Disallow raw lowercase HTML host elements - use the design-system component vocabulary.",
-    },
-    messages: {},
-    schema: [
-      {
-        type: "object",
-        properties: {
-          allow: { type: "array", items: { type: "string" } },
-          layoutOnly: { type: "boolean" },
-        },
-        additionalProperties: false,
+export const rule =
+  /** @satisfies {Rule} */
+  ({
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Disallow raw lowercase HTML host elements - use the design-system component vocabulary.",
       },
-    ],
-  },
-  create,
-};
+      messages: {},
+      schema: [
+        {
+          type: "object",
+          properties: {
+            allow: { type: "array", items: { type: "string" } },
+            layoutOnly: { type: "boolean" },
+          },
+          additionalProperties: false,
+        },
+      ],
+    },
+    create,
+  });

package/lint/oxlint/no-render-layout-as.mjs

@@ -6,6 +6,11 @@
 //
 // @doctrine Use `as` to change a layout primitive's element; use `render` only to swap in a component, never `render={<Box as=.../>}`.
 
+/** @typedef {Parameters<import("oxlint/plugins-dev").RuleTester["run"]>[1]} Rule */
+/** @typedef {NonNullable<Rule["create"]>} Create */
+/** @typedef {Parameters<Create>[0]} Context */
+/** @typedef {ReturnType<Create>} Visitor */
+
 /**
  * Layout primitives that share the closed `as` / `render` contract. A
  * `render={<Name as=... />}` on any prop is the mistake, so the set is every
@@ -34,73 +39,73 @@ export const LAYOUT_PRIMITIVES = new Set([
  * Build the diagnostic message for a banned `render={<Primitive as=... />}`.
  *
  * @param {string} primitive component name used inside `render`
- * @returns {string}
+ * @returns {string} The message telling the author to pass `as` to the outer element.
  */
-export function messageFor(primitive) {
-  return `render={<${primitive} as=... />} nests a layout primitive only to set a tag. Pass \`as\` directly on the outer element; use \`render\` only to swap in a component (e.g. a router Link).`;
-}
+export const messageFor = (primitive) =>
+  `render={<${primitive} as=... />} nests a layout primitive only to set a tag. Pass \`as\` directly on the outer element; use \`render\` only to swap in a component (e.g. a router Link).`;
 
 /**
  * ESLint-style rule factory. Visits every layout primitive whose `render` prop
  * is another layout-primitive element carrying an `as` attribute.
  *
- * @param {{ report: Function }} context
+ * @param {Context} context The rule context.
+ * @returns {Visitor} The visitor oxlint runs over the file.
  */
-export function create(context) {
-  return {
-    JSXOpeningElement(opening) {
-      // Only a layout primitive as the OUTER element: it has `as`, so nesting is
-      // needless. A trigger that has no `as` (TooltipTrigger, say) legitimately
-      // takes `render={<Box as="span" />}` to get a tag.
+export const create = (context) => ({
+  JSXOpeningElement(opening) {
+    // Only a layout primitive as the OUTER element: it has `as`, so nesting is
+    // needless. A trigger that has no `as` (TooltipTrigger, say) legitimately
+    // takes `render={<Box as="span" />}` to get a tag.
+    if (
+      opening.name.type !== "JSXIdentifier" ||
+      !LAYOUT_PRIMITIVES.has(opening.name.name)
+    ) {
+      return;
+    }
+    for (const attribute of opening.attributes) {
       if (
-        opening.name?.type !== "JSXIdentifier" ||
-        !LAYOUT_PRIMITIVES.has(opening.name.name)
+        attribute.type !== "JSXAttribute" ||
+        attribute.name.type !== "JSXIdentifier" ||
+        attribute.name.name !== "render"
       ) {
-        return;
+        continue;
       }
-      for (const attribute of opening.attributes) {
-        if (
-          attribute.type !== "JSXAttribute" ||
-          attribute.name?.type !== "JSXIdentifier" ||
-          attribute.name.name !== "render"
-        ) {
-          continue;
-        }
-        const element = attribute.value?.expression;
-        if (element?.type !== "JSXElement") {
-          continue;
-        }
-        const {name} = element.openingElement;
-        if (
-          name?.type !== "JSXIdentifier" ||
-          !LAYOUT_PRIMITIVES.has(name.name)
-        ) {
-          continue;
-        }
-        const hasAs = element.openingElement.attributes.some(
-          (inner) =>
-            inner.type === "JSXAttribute" &&
-            inner.name?.type === "JSXIdentifier" &&
-            inner.name.name === "as"
-        );
-        if (hasAs) {
-          context.report({ node: element, message: messageFor(name.name) });
-        }
+      if (attribute.value?.type !== "JSXExpressionContainer") {
+        continue;
       }
-    },
-  };
-}
+      const element = attribute.value.expression;
+      if (element.type !== "JSXElement") {
+        continue;
+      }
+      const { name } = element.openingElement;
+      if (name.type !== "JSXIdentifier" || !LAYOUT_PRIMITIVES.has(name.name)) {
+        continue;
+      }
+      const hasAs = element.openingElement.attributes.some(
+        (inner) =>
+          inner.type === "JSXAttribute" &&
+          inner.name.type === "JSXIdentifier" &&
+          inner.name.name === "as"
+      );
+      if (hasAs) {
+        context.report({ node: element, message: messageFor(name.name) });
+      }
+    }
+  },
+});
 
 /** Rule metadata + factory, ready to slot into the plugin's `rules` map. */
-export const rule = {
-  meta: {
-    type: "problem",
-    docs: {
-      description:
-        "Disallow render={<Box as=... />}: pass `as` to the outer layout primitive instead.",
+export const rule =
+  /** @satisfies {Rule} */
+  ({
+    meta: {
+      type: "problem",
+      docs: {
+        description:
+          "Disallow render={<Box as=... />}: pass `as` to the outer layout primitive instead.",
+      },
+      messages: {},
+      schema: [],
     },
-    messages: {},
-    schema: [],
-  },
-  create,
-};
+    create,
+  });

package/lint/scan-classes.d.mts

@@ -1,5 +1,58 @@
-/**
- * The class-string scanner is a command, run as the `materia-ui-lint` bin. It
- * exports nothing; importing it runs the scan.
- */
-export {};
+// GENERATED by scripts/generate-lint-types.ts from the JSDoc in lint/scan-classes.mjs - do not edit.
+// Regenerate with `pnpm --filter @instruments/materia-ui generate:lint-types`.
+
+export interface Options {
+  /**
+   * Files and directories to scan.
+   */
+  paths: string[];
+  /**
+   * Path fragments to skip.
+   */
+  excludes: string[];
+  /**
+   * Whether the `hex` rule is on.
+   */
+  hex: boolean;
+  /**
+   * Whether the `arbitrary` rule is on.
+   */
+  arbitrary: boolean;
+  /**
+   * Whether to print a JSON document instead of text lines.
+   */
+  json: boolean;
+  /**
+   * Whether to print usage and stop.
+   */
+  help: boolean;
+}
+export type RuleName = "hex" | "arbitrary";
+export interface Region {
+  /**
+   * Offset of the region in the file.
+   */
+  start: number;
+  /**
+   * The region's text.
+   */
+  body: string;
+}
+export interface Violation {
+  /**
+   * The rule that matched.
+   */
+  rule: RuleName;
+  /**
+   * The offending text.
+   */
+  value: string;
+  /**
+   * One-based line of the match.
+   */
+  line: number;
+  /**
+   * One-based column of the match.
+   */
+  column: number;
+}