@ai-matrx/design-system 0.60.1 → 0.60.6

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.60.6
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/design-system/v0.60.1..npm/design-system/v0.60.6 -- apps/shared/design-system`).
+No source changes intended and no consumer action required.
+
+## 0.60.5
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/design-system/v0.60.1..npm/design-system/v0.60.5 -- apps/shared/design-system`).
+No source changes intended and no consumer action required.
+
+## 0.60.4
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/design-system/v0.60.1..npm/design-system/v0.60.4 -- apps/shared/design-system`).
+No source changes intended and no consumer action required.
+
+## 0.60.3
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/design-system/v0.60.1..npm/design-system/v0.60.3 -- apps/shared/design-system`).
+No source changes intended and no consumer action required.
+
+## 0.60.2
+### Unreleased
+
+- **THE DESKTOP STANDARD (`./desktop`, `./desktop.css`, `./desktop/lint`).** An opt-in macOS-class
+  layer for desktop apps (Matrx 2): the named scale (text styles, label levels, surfaces, fills,
+  tint, system colours, 22/28/32 controls, 24/28/36/48 rows, 16 px icons, 6/10/12 radii) and the
+  components built only from it — Text, Button, IconButton, TextField, SearchField, TextArea,
+  Select, Segmented, Page, PageHeader, Toolbar, Section, Row, DataTable, SourceList, StateView,
+  Banner, Meter, Tag, StatusLight, Kbd, Spinner, plus display formatters. `./desktop/lint` is the
+  ESLint plugin that holds desktop apps to it. Rules: `src/desktop/DESKTOP.md`. Guard:
+  `src/desktop/desktop-law.test.ts`.
+
+### Consumer action
+
+- None for the web: nothing loads `desktop.css` unless a host imports it; no existing component
+  changed.
+
 ## 0.60.1
 
 - **A declared actions column is as wide as its controls.** A `customActions` column with no

package/dist/desktop-lint.mjs

@@ -0,0 +1,218 @@
+/**
+ * THE DESKTOP CLASS LAW — the one checker behind the package test and the desktop app's ESLint rule.
+ *
+ * Desktop UI uses the named scale from desktop.css and nothing else. A class is refused when it:
+ *   - carries an arbitrary value (`h-[39px]`, `text-[12px]`, `bg-[#fff]`, `w-[var(--x)]`, `z-[9]`)
+ *   - uses a Tailwind font size, line height or letter spacing (the text styles carry them)
+ *   - uses Tailwind's colour palette or black/white (semantic colours only)
+ *   - uses the web token vocabulary (`text-muted-foreground`, `bg-primary` …) instead of the
+ *     desktop one (`text-label-secondary`, `bg-tint` …)
+ *   - uses a radius or shadow outside the named set
+ *   - sets a font weight other than medium/normal (the text styles carry their weight)
+ *
+ * Variant prefixes (`hover:`, `data-[state=on]:`, `[&_svg]:`) are allowed; only the utility after
+ * the last top-level `:` is judged. Plain JavaScript so ESLint configs and tests can both load it.
+ */
+
+const PALETTE =
+  "slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|black|white";
+const COLOR_UTILS = "bg|text|border|border-[trblxy]|ring|ring-offset|outline|fill|stroke|from|via|to|divide|decoration|accent|caret|placeholder|shadow";
+const WEB_TOKENS =
+  "foreground|background|muted|muted-foreground|primary|primary-foreground|secondary|secondary-foreground|accent|accent-foreground|destructive|destructive-foreground|card|card-foreground|popover|popover-foreground|input|ring|border|info|warning|success|chrome";
+
+const RULES = [
+  [/\[/, "arbitrary value: use a named size or colour from desktop.css"],
+  [/^text-(xs|sm|base|lg|xl|[2-9]xl)$/, "Tailwind font size: use a text style (text-body, text-callout, text-headline …) or <Text variant>"],
+  [/^(leading|tracking)-/, "line height / letter spacing: the text styles carry them"],
+  [/^font-(thin|extralight|light|semibold|bold|extrabold|black)$/, "font weight: titles and headline carry their weight; use font-medium for emphasis"],
+  [new RegExp(`^(${COLOR_UTILS})-(${PALETTE})(-\\d+)?(\\/\\d+)?$`), "palette colour: use a semantic colour (label, fill, separator, tint, system-red …)"],
+  [new RegExp(`^(${COLOR_UTILS})-(${WEB_TOKENS})(\\/\\d+)?$`), "web token: use the desktop vocabulary (text-label-secondary, bg-fill, border-separator, bg-tint …)"],
+  [/^rounded(-[trblse]{1,2})?-(xs|sm|md|lg|xl|[2-4]xl)$/, "radius: use rounded-control, rounded-group, rounded-panel or rounded-full"],
+  [/^rounded(-[trblse]{1,2})?$/, "radius: use rounded-control, rounded-group, rounded-panel or rounded-full"],
+  [/^shadow-(2xs|xs|sm|md|lg|xl|2xl|inner)$/, "shadow: use shadow-control, shadow-raised or shadow-popover"],
+  [/^shadow$/, "shadow: use shadow-control, shadow-raised or shadow-popover"],
+  [/^z-\d+$/, "z-index: layering belongs to the overlay primitives"],
+];
+
+/** The utility a class token applies, with variant prefixes and the `!`/`-` modifiers removed. */
+export function utilityOf(token) {
+  let depth = 0;
+  let cut = 0;
+  for (let i = 0; i < token.length; i += 1) {
+    const ch = token[i];
+    if (ch === "[" || ch === "(") depth += 1;
+    else if (ch === "]" || ch === ")") depth -= 1;
+    else if (ch === ":" && depth === 0) cut = i + 1;
+  }
+  return token.slice(cut).replace(/^!/, "").replace(/!$/, "").replace(/^-/, "");
+}
+
+/** Returns the reason a class token breaks the law, or null when it is lawful. */
+export function classViolation(token) {
+  const utility = utilityOf(token);
+  if (!utility) return null;
+  for (const [pattern, reason] of RULES) {
+    if (pattern.test(utility)) return reason;
+  }
+  return null;
+}
+
+/** Every unlawful token in a class string, with its reason. */
+export function classViolations(classString) {
+  return classString
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((token) => ({ token, reason: classViolation(token) }))
+    .filter((v) => v.reason !== null);
+}
+
+const CLASS_CALLEES = new Set(["cn", "cva", "clsx", "twMerge"]);
+
+function stringsUnder(node, out) {
+  if (!node || typeof node !== "object") return out;
+  if (node.type === "Literal" && typeof node.value === "string") out.push(node);
+  else if (node.type === "TemplateElement") out.push(node);
+  for (const key of Object.keys(node)) {
+    if (key === "parent" || key === "loc" || key === "range") continue;
+    const child = node[key];
+    if (Array.isArray(child)) child.forEach((c) => stringsUnder(c, out));
+    else if (child && typeof child === "object" && typeof child.type === "string") stringsUnder(child, out);
+  }
+  return out;
+}
+
+function report(context, node) {
+  const text = node.type === "TemplateElement" ? node.value.cooked ?? node.value.raw : node.value;
+  for (const { token, reason } of classViolations(text)) {
+    context.report({ node, message: `"${token}" — ${reason}.` });
+  }
+}
+
+/** ESLint rule: class strings in className / class attributes and cn()/cva()/clsx() calls. */
+export const desktopClassRule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Desktop UI uses only the named scale of @ai-matrx/design-system/desktop.css" },
+    schema: [],
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        const name = node.name && node.name.name;
+        if ((name === "className" || name === "class") && node.value) stringsUnder(node.value, []).forEach((s) => report(context, s));
+      },
+      CallExpression(node) {
+        if (node.callee.type === "Identifier" && CLASS_CALLEES.has(node.callee.name)) {
+          // cva's second argument is a config object; its keys are variant names, its values classes.
+          node.arguments.forEach((arg) => stringsUnder(arg, []).forEach((s) => report(context, s)));
+        }
+      },
+    };
+  },
+};
+
+/** ESLint rule: no inline style values (colours, pixel sizes); computed widths/positions pass. */
+export const desktopInlineStyleRule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Desktop UI takes no literal colours or pixel sizes in style={{}}" },
+    schema: [],
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        if (node.name?.name !== "style" || node.value?.type !== "JSXExpressionContainer") return;
+        const expr = node.value.expression;
+        if (expr.type !== "ObjectExpression") return;
+        for (const prop of expr.properties) {
+          if (prop.type !== "Property") continue;
+          const v = prop.value;
+          const literal = v.type === "Literal" ? v.value : v.type === "TemplateLiteral" && v.expressions.length === 0 ? v.quasis[0].value.cooked : undefined;
+          if (literal === undefined) continue;
+          if (typeof literal === "number" || /(#[0-9a-f]{3,8}\b|\brgba?\(|\bhsla?\(|\d+px)/i.test(String(literal))) {
+            context.report({ node: prop, message: "Literal style value: use a named size or colour from desktop.css." });
+          }
+        }
+      },
+    };
+  },
+};
+
+/** The raw elements a desktop screen never draws itself, and the component that replaces each. */
+export const RAW_ELEMENTS = {
+  button: "Button, IconButton, Row (onSelect) or SourceListItem",
+  input: "TextField, SearchField, Switch or Checkbox",
+  select: "Select",
+  textarea: "TextArea",
+  table: "DataTable",
+  progress: "Meter",
+  h1: "PageHeader or <Text as=\"h1\">",
+  h2: "Section title or <Text as=\"h2\">",
+  h3: "<Text as=\"h3\">",
+};
+
+/** ESLint rule: no raw controls, tables or headings in desktop screens. */
+export const desktopRawElementRule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Desktop screens compose design-system components, never raw controls" },
+    schema: [],
+  },
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        const name = node.name.type === "JSXIdentifier" ? node.name.name : null;
+        if (name && Object.hasOwn(RAW_ELEMENTS, name)) {
+          context.report({ node, message: `Raw <${name}>: use ${RAW_ELEMENTS[name]} from @ai-matrx/design-system/desktop.` });
+        }
+      },
+    };
+  },
+};
+
+const CELL_CONTROLS = new Set(["Button", "IconButton", "DropdownMenu", "button"]);
+
+function jsxNamesUnder(node, out) {
+  if (!node || typeof node !== "object") return out;
+  if (node.type === "JSXOpeningElement" && node.name.type === "JSXIdentifier") out.push(node);
+  for (const key of Object.keys(node)) {
+    if (key === "parent" || key === "loc" || key === "range") continue;
+    const child = node[key];
+    if (Array.isArray(child)) child.forEach((c) => jsxNamesUnder(c, out));
+    else if (child && typeof child === "object" && typeof child.type === "string") jsxNamesUnder(child, out);
+  }
+  return out;
+}
+
+/** ESLint rule: a DataTable column's `cell` never draws a control — row actions go through the
+ *  table's `rowAction` / `rowMenu` slots, so every table's actions look and behave the same. */
+export const desktopCellControlRule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Table row actions go through DataTable rowAction / rowMenu, never a control in a cell" },
+    schema: [],
+  },
+  create(context) {
+    return {
+      Property(node) {
+        if (node.key?.type !== "Identifier" || node.key.name !== "cell") return;
+        for (const el of jsxNamesUnder(node.value, [])) {
+          if (CELL_CONTROLS.has(el.name.name)) {
+            context.report({ node: el, message: `<${el.name.name}> in a table cell: use DataTable rowAction (one small button) or rowMenu (everything else).` });
+          }
+        }
+      },
+    };
+  },
+};
+
+/** The ESLint plugin a desktop app registers: `plugins: { desktop: desktopLintPlugin }`. */
+export const desktopLintPlugin = {
+  meta: { name: "@ai-matrx/design-system/desktop-lint" },
+  rules: {
+    "class-law": desktopClassRule,
+    "no-literal-style": desktopInlineStyleRule,
+    "no-raw-elements": desktopRawElementRule,
+    "no-cell-controls": desktopCellControlRule,
+  },
+};