@instruments/materia-ui 0.1.0

package/lint/oxlint/index.d.mts

@@ -0,0 +1,24 @@
+/** 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 messages: Readonly<Record<string, string>>;
+    readonly schema: readonly unknown[];
+  };
+  readonly create: (context: unknown) => Record<string, unknown>;
+}
+
+/**
+ * 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`.
+ */
+declare const plugin: {
+  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

@@ -0,0 +1,14 @@
+import { rule as noNakedElement } from "./no-naked-element.mjs";
+import { rule as noRenderLayoutAs } from "./no-render-layout-as.mjs";
+
+const plugin = {
+  meta: {
+    name: "materia-ui",
+  },
+  rules: {
+    "no-naked-element": noNakedElement,
+    "no-render-layout-as": noRenderLayoutAs,
+  },
+};
+
+export default plugin;

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

@@ -0,0 +1,259 @@
+// The `no-naked-element` rule for the LLM-safe design system: raw lowercase JSX
+// host elements (<div>, <span>, <a>, <button>, …) are banned in application
+// markup. The model must pick from the authored, closed component vocabulary -
+// polymorphic `as` for semantics, a token-policed `className` as the only route
+// to the metal. Uppercase components, member expressions (Foo.Bar) and fragments
+// are always fine. The `allow` option exempts named tags (e.g. the Next root
+// shell's html/body). The `layoutOnly` option narrows the rule to hand-rolled
+// layout: a layout host (div, span, nav, ul, ...) whose unconditional classes
+// make it a flex or grid container, which a layout primitive already expresses.
+//
+// @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.
+
+/**
+ * Map of raw HTML tag → the design-system replacement guidance surfaced in the
+ * diagnostic. Every member of the tokens `LAYOUT_ELEMENTS` / `TEXT_ELEMENTS`
+ * closed unions MUST have an entry here (asserted by the parity test) so the
+ * rule can always point a banned host at its sanctioned primitive.
+ *
+ * @type {Record<string, string>}
+ */
+export const REPLACEMENTS = {
+  // Layout / structural hosts (LAYOUT_ELEMENTS)
+  div: "Box (decorative) / Stack | Flex | Grid (layout)",
+  span: 'Box as="span" (decorative) / Text as="span" (textual)',
+  main: 'Container as="main" / Box as="main"',
+  nav: 'Box as="nav"',
+  header: 'Box as="header"',
+  footer: 'Box as="footer"',
+  section: 'Box as="section" / Section',
+  article: 'Box as="article"',
+  aside: 'Box as="aside"',
+  ul: 'Stack as="ul"',
+  ol: 'Stack as="ol"',
+  li: 'Box as="li" / Text as="li"',
+  figure: 'Box as="figure"',
+  figcaption: 'Text as="figcaption"',
+  // Text hosts (TEXT_ELEMENTS)
+  p: "Text",
+  legend: 'Text as="legend"',
+  dt: 'Text as="dt"',
+  dd: 'Text as="dd"',
+  // Common non-union hosts the app still reaches for
+  a: "Anchor",
+  code: "Code",
+  pre: "Code block",
+  img: "GalleryImage",
+  iframe: "MediaFrameEmbed",
+  svg: "Icon",
+  h1: "Heading level={1}",
+  h2: "Heading level={2}",
+  h3: "Heading level={3}",
+  h4: "Heading level={4}",
+  h5: "Heading level={5}",
+  h6: "Heading level={6}",
+  button: "Button",
+  input: "Input",
+  textarea: "Textarea",
+  select: "Select",
+  label: "Label",
+  form: "Form",
+};
+
+const ESCAPE_HATCH =
+  "The only escape hatch is className on a primitive, policed by tokens-only.";
+
+/**
+ * Build the diagnostic message for a banned raw tag.
+ *
+ * @param {string} tag lowercase HTML tag name
+ * @returns {string}
+ */
+export function messageFor(tag) {
+  const guidance = REPLACEMENTS[tag]
+    ? `Use ${REPLACEMENTS[tag]} instead.`
+    : "Use a @instruments/materia-ui component 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`
+ * union, mirrored here because the plugin ships as plain JS (asserted equal by
+ * the parity test).
+ */
+export const LAYOUT_HOSTS = [
+  "div",
+  "span",
+  "main",
+  "nav",
+  "header",
+  "footer",
+  "section",
+  "article",
+  "aside",
+  "ul",
+  "ol",
+  "li",
+  "figure",
+  "figcaption",
+];
+
+/** Display utilities that turn a host into a container a primitive owns. */
+export const LAYOUT_UTILITIES = ["flex", "inline-flex", "grid", "inline-grid"];
+
+const LAYOUT_HOST_SET = new Set(LAYOUT_HOSTS);
+const LAYOUT_UTILITY_SET = new Set(LAYOUT_UTILITIES);
+
+/**
+ * Build the diagnostic message for a raw host acting as a flex or grid
+ * container.
+ *
+ * @param {string} tag lowercase HTML tag name
+ * @param {string} utility the layout utility found in its classes
+ * @returns {string}
+ */
+export function 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[]}
+ */
+function templateTokens(node) {
+  const tokens = [];
+  node.quasis.forEach((quasi, index) => {
+    const text = quasi.value.cooked ?? quasi.value.raw;
+    const parts = text.split(/\s+/u);
+    if (index > 0 && !/^\s/u.test(text)) {
+      parts.shift();
+    }
+    if (index < node.quasis.length - 1 && !/\s$/u.test(text)) {
+      parts.pop();
+    }
+    tokens.push(...parts);
+  });
+  return tokens;
+}
+
+/**
+ * Class tokens an expression always contributes: string and template literals,
+ * directly or as direct arguments of a class helper call (`cn("flex", …)`).
+ * 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[]}
+ */
+function unconditionalTokens(node, inCall = false) {
+  if (!node) {
+    return [];
+  }
+  if (node.type === "Literal" && typeof node.value === "string") {
+    return node.value.split(/\s+/u);
+  }
+  if (node.type === "TemplateLiteral") {
+    return templateTokens(node);
+  }
+  if (node.type === "CallExpression" && !inCall) {
+    return node.arguments.flatMap((arg) => unconditionalTokens(arg, true));
+  }
+  return [];
+}
+
+/**
+ * The first layout utility among a JSX element's unconditional classes.
+ *
+ * @param {any} openingElement
+ * @returns {string | undefined}
+ */
+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)
+    );
+  }
+  return;
+}
+
+/**
+ * ESLint-style rule factory. Visits every JSX opening element and reports raw
+ * lowercase host elements unless they appear in `options[0].allow`. With
+ * `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
+ */
+export function create(context) {
+  const allow = new Set(context.options?.[0]?.allow ?? []);
+  const layoutOnly = context.options?.[0]?.layoutOnly === true;
+
+  return {
+    JSXOpeningElement(node) {
+      const { name } = node;
+      // JSXMemberExpression (Foo.Bar) and JSXNamespacedName are never bare hosts.
+      if (name?.type !== "JSXIdentifier") {
+        return;
+      }
+      const tag = name.name;
+      // Uppercase → a component; only lowercase identifiers are raw HTML hosts.
+      if (!/^[a-z]/u.test(tag)) {
+        return;
+      }
+      if (allow.has(tag)) {
+        return;
+      }
+      if (!layoutOnly) {
+        context.report({ node: name, message: messageFor(tag) });
+        return;
+      }
+      if (!LAYOUT_HOST_SET.has(tag)) {
+        return;
+      }
+      const utility = layoutUtilityOf(node);
+      if (utility !== undefined) {
+        context.report({ node: name, message: layoutMessageFor(tag, utility) });
+      }
+    },
+  };
+}
+
+/** 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,
+      },
+    ],
+  },
+  create,
+};

package/lint/oxlint/no-naked-element.test.ts

@@ -0,0 +1,155 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { describe, expect, it } from "vitest";
+
+import { LAYOUT_ELEMENTS, TEXT_ELEMENTS } from "../../src/tokens/element";
+import { LAYOUT_HOSTS, REPLACEMENTS } from "./no-naked-element.mjs";
+
+const execFileAsync = promisify(execFile);
+
+const here = import.meta.dirname;
+const fixturesDir = path.join(here, "fixtures");
+const configPath = path.join(fixturesDir, "fixture.config.mjs");
+
+const RULE_CODE = "materia-ui(no-naked-element)";
+const ESCAPE_HATCH = "className on a primitive, policed by tokens-only";
+
+/** Walk up from the test dir to the workspace root's oxlint binary. */
+const resolveOxlintBin = (): string => {
+  let dir = here;
+  for (let i = 0; i < 12; i += 1) {
+    const candidate = path.join(dir, "node_modules", ".bin", "oxlint");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  throw new Error("could not resolve the oxlint binary from node_modules/.bin");
+};
+
+interface Diagnostic {
+  code: string;
+  message: string;
+  filename: string;
+  labels: { span: { line: number } }[];
+}
+
+const packageRoot = path.resolve(here, "..", "..");
+
+/**
+ * Run oxlint over the fixtures with the plugin config and return only our rule's
+ * diagnostics. oxlint exits non-zero when it reports, so read stdout off the
+ * thrown error too.
+ */
+const runRule = async (): Promise<Diagnostic[]> => {
+  const targets = [
+    "invalid.tsx",
+    "valid.tsx",
+    "allowed.tsx",
+    "layout-only.tsx",
+  ].map((f) => path.join(fixturesDir, f));
+  let stdout = "[]";
+  try {
+    const result = await execFileAsync(
+      resolveOxlintBin(),
+      ["--config", configPath, "--format", "json", ...targets],
+      { cwd: packageRoot }
+    );
+    ({ stdout } = result);
+  } catch (error) {
+    stdout = (error as { stdout?: string }).stdout ?? "";
+  }
+  const report = JSON.parse(stdout) as
+    | { diagnostics?: Diagnostic[] }
+    | Diagnostic[];
+  const diagnostics = Array.isArray(report)
+    ? report
+    : (report.diagnostics ?? []);
+  return diagnostics.filter((d) => d.code === RULE_CODE);
+};
+
+const diagnosticsPromise = runRule();
+
+const forFile = (diagnostics: Diagnostic[], basename: string) =>
+  diagnostics.filter((d) => path.basename(d.filename) === basename);
+
+// Every raw host authored in invalid.tsx, paired with a distinctive substring of
+// its REPLACEMENTS guidance that must appear in the diagnostic message.
+const INVALID_TAGS: [tag: string, hint: string][] = [
+  ["div", "Box"],
+  ["span", 'Text as="span"'],
+  ["a", "Anchor"],
+  ["main", 'Box as="main"'],
+  ["ul", 'Stack as="ul"'],
+  ["li", 'as="li"'],
+  ["code", "Code"],
+  ["pre", "Code block"],
+  ["img", "GalleryImage"],
+  ["svg", "Icon"],
+  ["button", "Button"],
+  ["input", "Input"],
+  ["label", "Label"],
+  ["p", "Text"],
+  ["section", "Section"],
+  ["h1", "Heading level={1}"],
+];
+
+describe("no-naked-element (oxlint integration)", () => {
+  it("reports every raw host in invalid.tsx with its REPLACEMENTS hint", async () => {
+    const invalid = forFile(await diagnosticsPromise, "invalid.tsx");
+    for (const [tag, hint] of INVALID_TAGS) {
+      const hit = invalid.find((d) => d.message.startsWith(`Raw <${tag}>`));
+      expect(hit, `expected a diagnostic for <${tag}>`).toBeDefined();
+      expect(hit?.message).toContain(hint);
+      expect(hit?.message).toContain(ESCAPE_HATCH);
+    }
+    // No stray reports beyond the authored tags.
+    expect(invalid).toHaveLength(INVALID_TAGS.length);
+  });
+
+  it("does not report components, member expressions, or fragments in valid.tsx", async () => {
+    expect(forFile(await diagnosticsPromise, "valid.tsx")).toHaveLength(0);
+  });
+
+  it("honors the allow option - proves context.options reaches the rule", async () => {
+    const allowed = forFile(await diagnosticsPromise, "allowed.tsx");
+    // html + body are suppressed by allow:["html","body"]; only the div remains.
+    expect(allowed).toHaveLength(1);
+    expect(allowed[0]?.message).toMatch(/^Raw <div>/u);
+    expect(allowed[0]?.labels[0]?.span.line).toBe(8);
+  });
+
+  it("layoutOnly reports only hosts whose unconditional classes are flex or grid", async () => {
+    const layout = forFile(await diagnosticsPromise, "layout-only.tsx");
+    // A plain div, an svg path, a conditional `flex`, a class glued to an
+    // interpolation, a flex <button> and `flex-1 flex-col` all stay quiet.
+    expect(layout.map((d) => d.labels[0]?.span.line)).toEqual([10, 11, 12, 13]);
+    expect(layout[0]?.message).toMatch(/^Raw <div> with `flex`/u);
+    expect(layout[1]?.message).toContain('as="span"');
+    expect(layout[2]?.message).toContain("Grid | SimpleGrid");
+  });
+});
+
+// Parity: every member of the closed layout/text unions must have a REPLACEMENTS
+// entry so the rule can always name a sanctioned replacement.
+describe("REPLACEMENTS parity with element unions", () => {
+  it("has a replacement for every LAYOUT_ELEMENT and TEXT_ELEMENT", () => {
+    const members = [...new Set([...LAYOUT_ELEMENTS, ...TEXT_ELEMENTS])];
+    const missing = members.filter((tag) => !(tag in REPLACEMENTS));
+    expect(
+      missing,
+      `missing REPLACEMENTS entries for: ${missing.join(", ")}`
+    ).toEqual([]);
+  });
+
+  it("mirrors LAYOUT_ELEMENTS in the rule's layout hosts", () => {
+    expect(LAYOUT_HOSTS).toEqual([...LAYOUT_ELEMENTS]);
+  });
+});

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

@@ -0,0 +1,106 @@
+// The `no-render-layout-as` rule: a layout primitive's `render` prop swaps in a
+// component (a router Link, say); `as` changes the tag. Writing
+// `<Stack render={<Box as="li" />} />` passes the tag through a component that was only
+// ever meant to be the element, so the outer primitive renders Box which renders
+// the tag - two layers for what `as` on the outer primitive does directly.
+//
+// @doctrine Use `as` to change a layout primitive's element; use `render` only to swap in a component, never `render={<Box as=.../>}`.
+
+/**
+ * Layout primitives that share the closed `as` / `render` contract. A
+ * `render={<Name as=... />}` on any prop is the mistake, so the set is every
+ * component that accepts `as`.
+ */
+export const LAYOUT_PRIMITIVES = new Set([
+  "AspectRatio",
+  "Box",
+  "Center",
+  "Container",
+  "Flex",
+  "Grid",
+  "GridCol",
+  "Group",
+  "HStack",
+  "MediaFrame",
+  "ScrollArea",
+  "Section",
+  "SectionHeader",
+  "SimpleGrid",
+  "Stack",
+  "VStack",
+]);
+
+/**
+ * Build the diagnostic message for a banned `render={<Primitive as=... />}`.
+ *
+ * @param {string} primitive component name used inside `render`
+ * @returns {string}
+ */
+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).`;
+}
+
+/**
+ * ESLint-style rule factory. Visits every layout primitive whose `render` prop
+ * is another layout-primitive element carrying an `as` attribute.
+ *
+ * @param {{ report: Function }} context
+ */
+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.
+      if (
+        opening.name?.type !== "JSXIdentifier" ||
+        !LAYOUT_PRIMITIVES.has(opening.name.name)
+      ) {
+        return;
+      }
+      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) });
+        }
+      }
+    },
+  };
+}
+
+/** 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.",
+    },
+    messages: {},
+    schema: [],
+  },
+  create,
+};

package/lint/oxlint/no-render-layout-as.test.ts

@@ -0,0 +1,81 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { describe, expect, it } from "vitest";
+
+const execFileAsync = promisify(execFile);
+
+const here = import.meta.dirname;
+const fixturesDir = path.join(here, "fixtures");
+const configPath = path.join(fixturesDir, "fixture.config.mjs");
+const packageRoot = path.resolve(here, "..", "..");
+const RULE_CODE = "materia-ui(no-render-layout-as)";
+
+const resolveOxlintBin = (): string => {
+  let dir = here;
+  for (let i = 0; i < 12; i += 1) {
+    const candidate = path.join(dir, "node_modules", ".bin", "oxlint");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  throw new Error("could not resolve the oxlint binary from node_modules/.bin");
+};
+
+interface Diagnostic {
+  code: string;
+  message: string;
+  filename: string;
+}
+
+const runRule = async (): Promise<Diagnostic[]> => {
+  const targets = ["render-as-invalid.tsx", "render-as-valid.tsx"].map((f) =>
+    path.join(fixturesDir, f)
+  );
+  let stdout = "[]";
+  try {
+    ({ stdout } = await execFileAsync(
+      resolveOxlintBin(),
+      ["--config", configPath, "--format", "json", ...targets],
+      { cwd: packageRoot }
+    ));
+  } catch (error) {
+    stdout = (error as { stdout?: string }).stdout ?? "";
+  }
+  const report = JSON.parse(stdout) as
+    | { diagnostics?: Diagnostic[] }
+    | Diagnostic[];
+  const diagnostics = Array.isArray(report)
+    ? report
+    : (report.diagnostics ?? []);
+  return diagnostics.filter((d) => d.code === RULE_CODE);
+};
+
+const diagnosticsPromise = runRule();
+
+describe("no-render-layout-as (oxlint integration)", () => {
+  it("reports every render={<Primitive as=... />} in the invalid fixture", async () => {
+    const invalid = (await diagnosticsPromise).filter(
+      (d) => path.basename(d.filename) === "render-as-invalid.tsx"
+    );
+    expect(invalid.map((d) => d.message.match(/<(\w+) as/u)?.[1])).toEqual([
+      "Box",
+      "Stack",
+      "Center",
+    ]);
+  });
+
+  it("leaves plain as, component render and non-layout elements alone", async () => {
+    const valid = (await diagnosticsPromise).filter(
+      (d) => path.basename(d.filename) === "render-as-valid.tsx"
+    );
+    expect(valid).toHaveLength(0);
+  });
+});

package/lint/scan-classes.d.mts

@@ -0,0 +1,5 @@
+/**
+ * The class-string scanner is a command, run as the `materia-ui-lint` bin. It
+ * exports nothing; importing it runs the scan.
+ */
+export {};