@ponchia/ui 0.6.12 → 0.8.0

package/bin/bronto-ui-check.mjs

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+/** Validate literal Bronto classes and CSS custom-property references in a consumer. */
+import { readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { extname, resolve, relative, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const classesManifest = JSON.parse(
+  readFileSync(resolve(packageRoot, 'classes/classes.json'), 'utf8'),
+);
+const tokensManifest = JSON.parse(readFileSync(resolve(packageRoot, 'tokens/index.json'), 'utf8'));
+
+const SOURCE_EXTENSIONS = new Set([
+  '.astro',
+  '.css',
+  '.html',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.svelte',
+  '.ts',
+  '.tsx',
+  '.vue',
+]);
+const SKIP_DIRS = new Set([
+  '.git',
+  '.astro',
+  '.next',
+  '.nuxt',
+  '.output',
+  '.pytest_cache',
+  '.svelte-kit',
+  '.tox',
+  '.vercel',
+  '.venv',
+  '.vite',
+  '__pycache__',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'out',
+  'playwright-report',
+  'public',
+  'storybook-static',
+  'test-results',
+  'vendor',
+  'venv',
+]);
+
+const knownClasses = new Set(classesManifest.classes);
+// CSS generic font-family keywords share the ui-* prefix but are never class
+// literals. Keep the scanner broad enough to catch JS-built class strings
+// while excluding these standardized non-class identifiers.
+const nonClassIdentifiers = new Set(['ui-monospace', 'ui-rounded', 'ui-sans-serif', 'ui-serif']);
+const knownTokens = new Set(
+  Object.values(tokensManifest.cssVars).flatMap((group) => Object.keys(group)),
+);
+for (const property of classesManifest.customProperties) knownTokens.add(property.name);
+for (const entry of readdirSync(resolve(packageRoot, 'dist/css'), { withFileTypes: true })) {
+  if (!entry.isFile() || extname(entry.name) !== '.css') continue;
+  const css = readFileSync(resolve(packageRoot, 'dist/css', entry.name), 'utf8');
+  for (const match of css.matchAll(/(--[a-z][\w-]*)\s*:/gi)) knownTokens.add(match[1]);
+}
+const reservedTokenPrefixes = new Set(
+  [...knownTokens].map((name) => `--${name.slice(2).split('-')[0]}`),
+);
+const LINE_COMMENT_EXTENSIONS = new Set([
+  '.astro',
+  '.html',
+  '.js',
+  '.jsx',
+  '.mjs',
+  '.svelte',
+  '.ts',
+  '.tsx',
+  '.vue',
+]);
+const HTML_COMMENT_EXTENSIONS = new Set(['.astro', '.html', '.svelte', '.vue']);
+
+const blankComment = (value) => value.replace(/[^\r\n]/g, ' ');
+
+function quoteEnd(text, start, quote) {
+  for (let index = start + 1; index < text.length; index += 1) {
+    if (text[index] === '\\') index += 1;
+    else if (text[index] === quote) return index + 1;
+  }
+  return text.length;
+}
+
+function stripSlashComments(text, lineComments) {
+  let output = '';
+  let index = 0;
+  while (index < text.length) {
+    const char = text[index];
+    const next = text[index + 1];
+    if (char === '"' || char === "'" || char === '`') {
+      const end = quoteEnd(text, index, char);
+      output += text.slice(index, end);
+      index = end;
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      const close = text.indexOf('*/', index + 2);
+      const end = close === -1 ? text.length : close + 2;
+      output += blankComment(text.slice(index, end));
+      index = end;
+      continue;
+    }
+    if (lineComments && char === '/' && next === '/') {
+      const newline = text.indexOf('\n', index + 2);
+      const end = newline === -1 ? text.length : newline;
+      output += blankComment(text.slice(index, end));
+      index = end;
+      continue;
+    }
+    output += char;
+    index += 1;
+  }
+  return output;
+}
+
+function sourceText(text, extension) {
+  const withoutHtml = HTML_COMMENT_EXTENSIONS.has(extension)
+    ? text.replace(/<!--[\s\S]*?-->/g, blankComment)
+    : text;
+  return stripSlashComments(withoutHtml, LINE_COMMENT_EXTENSIONS.has(extension));
+}
+
+function lineAt(text, index) {
+  return text.slice(0, index).split('\n').length;
+}
+
+function filesUnder(input) {
+  const absolute = resolve(input);
+  const stat = statSync(absolute);
+  if (stat.isFile()) return SOURCE_EXTENSIONS.has(extname(absolute)) ? [absolute] : [];
+  if (!stat.isDirectory()) return [];
+  const files = [];
+  for (const entry of readdirSync(absolute, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue;
+    const child = resolve(absolute, entry.name);
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) files.push(...filesUnder(child));
+    } else if (entry.isFile() && SOURCE_EXTENSIONS.has(extname(entry.name))) {
+      files.push(child);
+    }
+  }
+  return files;
+}
+
+function tokenPrefix(name) {
+  return `--${name.slice(2).split('-')[0]}`;
+}
+
+export function checkPaths(inputs, { allowClasses = [], allowTokens = [] } = {}) {
+  const allowedClasses = new Set([...knownClasses, ...allowClasses]);
+  const allowedTokens = new Set([...knownTokens, ...allowTokens]);
+  const files = [...new Set(inputs.flatMap(filesUnder))].sort();
+  const documents = files.map((file) => {
+    const text = readFileSync(file, 'utf8');
+    return { file, text, scanned: sourceText(text, extname(file)) };
+  });
+  const locallyDefinedTokens = new Set();
+  for (const { scanned } of documents) {
+    for (const match of scanned.matchAll(/(--[a-z][\w-]*)\s*:/gi)) {
+      locallyDefinedTokens.add(match[1]);
+    }
+  }
+
+  const findings = [];
+  const seen = new Set();
+  const add = (finding) => {
+    const key = `${finding.kind}:${finding.file}:${finding.line}:${finding.name}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    findings.push(finding);
+  };
+
+  for (const { file, text, scanned } of documents) {
+    for (const match of scanned.matchAll(/(?<![/\w-])ui-[a-z0-9](?:[\w-]*[a-z0-9])?(?![\w/-])/gi)) {
+      if (!allowedClasses.has(match[0]) && !nonClassIdentifiers.has(match[0])) {
+        add({ kind: 'class', file, line: lineAt(text, match.index), name: match[0] });
+      }
+    }
+    for (const match of scanned.matchAll(/var\(\s*(--[a-z][\w-]*)/gi)) {
+      const name = match[1];
+      if (
+        reservedTokenPrefixes.has(tokenPrefix(name)) &&
+        !allowedTokens.has(name) &&
+        !locallyDefinedTokens.has(name)
+      ) {
+        add({ kind: 'token', file, line: lineAt(text, match.index), name });
+      }
+    }
+  }
+
+  return { files: files.length, findings };
+}
+
+function usage() {
+  return (
+    `Usage: bronto-ui-check [options] [path ...]\n\n` +
+    `Validate literal ui-* classes and unresolved Bronto-like var(--*) references.\n\n` +
+    `Options:\n` +
+    `  --allow-class NAME   Allow one consumer-owned ui-* class (repeatable)\n` +
+    `  --allow-token NAME   Allow one consumer-owned --* token (repeatable)\n` +
+    `  --json               Print machine-readable JSON\n` +
+    `  --help               Show this help\n`
+  );
+}
+
+function parseArgs(args) {
+  const options = { allowClasses: [], allowTokens: [], json: false, paths: [] };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--help') return { ...options, help: true };
+    if (arg === '--json') options.json = true;
+    else if (arg === '--allow-class') {
+      const value = args[++index];
+      if (!/^ui-[a-z0-9][\w-]*$/i.test(value || '')) {
+        throw new Error('--allow-class requires one ui-* class name');
+      }
+      options.allowClasses.push(value);
+    } else if (arg === '--allow-token') {
+      const value = args[++index];
+      if (!/^--[a-z][\w-]*$/i.test(value || '')) {
+        throw new Error('--allow-token requires one --* custom-property name');
+      }
+      options.allowTokens.push(value);
+    } else if (arg.startsWith('--')) throw new Error(`Unknown option: ${arg}`);
+    else options.paths.push(arg);
+  }
+  return options;
+}
+
+function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message);
+    console.error(usage());
+    process.exitCode = 2;
+    return;
+  }
+  if (options.help) {
+    console.log(usage());
+    return;
+  }
+  const paths = options.paths.length ? options.paths : ['.'];
+  let result;
+  try {
+    result = checkPaths(paths, options);
+  } catch (error) {
+    console.error(`[bronto-ui-check] ${error.message}`);
+    process.exitCode = 2;
+    return;
+  }
+  const cwd = process.cwd();
+  const output = {
+    files: result.files,
+    findings: result.findings.map((finding) => ({
+      ...finding,
+      file: relative(cwd, finding.file) || '.',
+    })),
+  };
+  if (options.json) console.log(JSON.stringify(output, null, 2));
+  else if (output.findings.length) {
+    for (const finding of output.findings) {
+      console.error(
+        `${finding.file}:${finding.line} unknown Bronto ${finding.kind} ${finding.name}`,
+      );
+    }
+    console.error(
+      `[bronto-ui-check] ${output.findings.length} finding(s) in ${output.files} source file(s)`,
+    );
+  } else {
+    console.log(`[bronto-ui-check] ${output.files} source file(s) match the shipped contract`);
+  }
+  if (output.findings.length) process.exitCode = 1;
+}
+
+// npm installs bins as symlinks in node_modules/.bin. Compare their real path
+// so the CLI runs both through that public entrypoint and by its package path.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/classes/classes.json

@@ -1,8 +1,8 @@
 {
   "$comment": "@ponchia/ui class vocabulary as language-neutral data — validate emitted markup without executing the ESM cls map or parsing the .d.ts. Generated from classes/index.js — do not edit by hand; run `npm run classes:json:build`. Drift-checked in CI. `groups[].base` is null for a parts-only namespace (no standalone base class — do NOT emit it). A modifier whose name contains `__` (e.g. `ui-spark__bar--pos`) attaches to THAT part, not the base host. `states` is the author-applied `is-*` hooks (runtime/behavior-managed hooks are excluded); `behaviorAttributes` are the `data-bronto-*` wiring hooks the optional behaviors delegate on; `requiredAria` is the role/aria a generator must emit per component. `states` + `customProperties` are documented in docs/reference.md and ship outside `cls` by design.",
   "counts": {
-    "classes": 644,
-    "groups": 179
+    "classes": 669,
+    "groups": 183
   },
   "groups": {
     "ui-accordion": {
@@ -242,13 +242,16 @@
       "base": "ui-button",
       "modifiers": [
         "ui-button--danger",
+        "ui-button--dense",
         "ui-button--ghost",
         "ui-button--icon",
         "ui-button--lg",
         "ui-button--sm",
         "ui-button--subtle"
       ],
-      "parts": []
+      "parts": [
+        "ui-button__label"
+      ]
     },
     "ui-card": {
       "base": "ui-card",
@@ -545,8 +548,14 @@
     },
     "ui-empty-state": {
       "base": "ui-empty-state",
-      "modifiers": [],
-      "parts": []
+      "modifiers": [
+        "ui-empty-state--invite"
+      ],
+      "parts": [
+        "ui-empty-state__glyph",
+        "ui-empty-state__hint",
+        "ui-empty-state__lead"
+      ]
     },
     "ui-error-summary": {
       "base": "ui-error-summary",
@@ -910,6 +919,17 @@
         "ui-pagination__item"
       ]
     },
+    "ui-pane": {
+      "base": "ui-pane",
+      "modifiers": [],
+      "parts": [
+        "ui-pane__actions",
+        "ui-pane__body",
+        "ui-pane__head",
+        "ui-pane__title",
+        "ui-pane__title-input"
+      ]
+    },
     "ui-panel": {
       "base": "ui-panel",
       "modifiers": [],
@@ -1104,12 +1124,34 @@
     },
     "ui-selectionbar": {
       "base": "ui-selectionbar",
-      "modifiers": [],
+      "modifiers": [
+        "ui-selectionbar--anchor-block-end",
+        "ui-selectionbar--anchor-block-start",
+        "ui-selectionbar--anchored"
+      ],
       "parts": [
         "ui-selectionbar__actions",
         "ui-selectionbar__count"
       ]
     },
+    "ui-severity": {
+      "base": "ui-severity",
+      "modifiers": [],
+      "parts": []
+    },
+    "ui-severity-dot": {
+      "base": "ui-severity-dot",
+      "modifiers": [],
+      "parts": []
+    },
+    "ui-severity-row": {
+      "base": "ui-severity-row",
+      "modifiers": [],
+      "parts": [
+        "ui-severity-row__meta",
+        "ui-severity-row__title"
+      ]
+    },
     "ui-shortcut": {
       "base": "ui-shortcut",
       "modifiers": [],
@@ -1447,13 +1489,18 @@
     "ui-toolstrip": {
       "base": "ui-toolstrip",
       "modifiers": [
+        "ui-toolstrip--anchor-block-end",
+        "ui-toolstrip--anchor-block-start",
+        "ui-toolstrip--anchored",
         "ui-toolstrip--compact",
-        "ui-toolstrip--floating"
+        "ui-toolstrip--floating",
+        "ui-toolstrip--pane"
       ],
       "parts": [
         "ui-toolstrip__actions",
         "ui-toolstrip__brand",
         "ui-toolstrip__context",
+        "ui-toolstrip__fill",
         "ui-toolstrip__group",
         "ui-toolstrip__search"
       ]
@@ -1610,11 +1657,13 @@
     "ui-bullet__target",
     "ui-button",
     "ui-button--danger",
+    "ui-button--dense",
     "ui-button--ghost",
     "ui-button--icon",
     "ui-button--lg",
     "ui-button--sm",
     "ui-button--subtle",
+    "ui-button__label",
     "ui-card",
     "ui-card--accent",
     "ui-card--interactive",
@@ -1748,6 +1797,10 @@
     "ui-dotspinner--lg",
     "ui-dotspinner--sm",
     "ui-empty-state",
+    "ui-empty-state--invite",
+    "ui-empty-state__glyph",
+    "ui-empty-state__hint",
+    "ui-empty-state__lead",
     "ui-error-summary",
     "ui-error-summary__list",
     "ui-error-summary__title",
@@ -1907,6 +1960,12 @@
     "ui-pagehead__title",
     "ui-pagination",
     "ui-pagination__item",
+    "ui-pane",
+    "ui-pane__actions",
+    "ui-pane__body",
+    "ui-pane__head",
+    "ui-pane__title",
+    "ui-pane__title-input",
     "ui-panel",
     "ui-panel__head",
     "ui-popover",
@@ -1994,8 +2053,16 @@
     "ui-sel--on",
     "ui-select",
     "ui-selectionbar",
+    "ui-selectionbar--anchor-block-end",
+    "ui-selectionbar--anchor-block-start",
+    "ui-selectionbar--anchored",
     "ui-selectionbar__actions",
     "ui-selectionbar__count",
+    "ui-severity",
+    "ui-severity-dot",
+    "ui-severity-row",
+    "ui-severity-row__meta",
+    "ui-severity-row__title",
     "ui-shortcut",
     "ui-shortcut__sep",
     "ui-sidebar",
@@ -2124,11 +2191,16 @@
     "ui-tool-call__status",
     "ui-tool-log",
     "ui-toolstrip",
+    "ui-toolstrip--anchor-block-end",
+    "ui-toolstrip--anchor-block-start",
+    "ui-toolstrip--anchored",
     "ui-toolstrip--compact",
     "ui-toolstrip--floating",
+    "ui-toolstrip--pane",
     "ui-toolstrip__actions",
     "ui-toolstrip__brand",
     "ui-toolstrip__context",
+    "ui-toolstrip__fill",
     "ui-toolstrip__group",
     "ui-toolstrip__search",
     "ui-tooltip",
@@ -2791,6 +2863,13 @@
       "behavior": "initSplitter",
       "note": "keyboard + pointer ARIA window-splitter behavior; updates --splitter-pos and aria-valuenow, then emits bronto:splitter:resize. The host owns persistence and pane state."
     },
+    {
+      "name": "data-bronto-splitter-adjust",
+      "on": "a button inside a .ui-splitter host",
+      "value": "signed percentage-point delta, for example -10 or 10",
+      "behavior": "initSplitter",
+      "note": "single-pointer non-drag alternative to moving the separator; activation clamps to aria-valuemin/aria-valuemax and emits bronto:splitter:resize."
+    },
     {
       "name": "data-bronto-source-ref",
       "on": "a button/control that references a source card",

package/classes/index.d.ts

@@ -21,6 +21,8 @@ export declare const cls: {
   readonly buttonIcon: 'ui-button--icon';
   readonly buttonSm: 'ui-button--sm';
   readonly buttonLg: 'ui-button--lg';
+  readonly buttonDense: 'ui-button--dense';
+  readonly buttonLabel: 'ui-button__label';
   readonly card: 'ui-card';
   readonly cardHead: 'ui-card__head';
   readonly cardAccent: 'ui-card--accent';
@@ -54,6 +56,10 @@ export declare const cls: {
   readonly linkCta: 'ui-link--cta';
   readonly keyValue: 'ui-key-value';
   readonly emptyState: 'ui-empty-state';
+  readonly emptyStateInvite: 'ui-empty-state--invite';
+  readonly emptyStateGlyph: 'ui-empty-state__glyph';
+  readonly emptyStateLead: 'ui-empty-state__lead';
+  readonly emptyStateHint: 'ui-empty-state__hint';
   readonly dot: 'ui-dot';
   readonly dotAccent: 'ui-dot--accent';
   readonly dotSuccess: 'ui-dot--success';
@@ -560,6 +566,11 @@ export declare const cls: {
   readonly jobBlocked: 'ui-job--blocked';
   readonly jobFailed: 'ui-job--failed';
   readonly jobComplete: 'ui-job--complete';
+  readonly severity: 'ui-severity';
+  readonly severityDot: 'ui-severity-dot';
+  readonly severityRow: 'ui-severity-row';
+  readonly severityRowTitle: 'ui-severity-row__title';
+  readonly severityRowMeta: 'ui-severity-row__meta';
   readonly generated: 'ui-generated';
   readonly generatedLabel: 'ui-generated__label';
   readonly originLabel: 'ui-origin-label';
@@ -577,11 +588,22 @@ export declare const cls: {
   readonly toolstrip: 'ui-toolstrip';
   readonly toolstripFloating: 'ui-toolstrip--floating';
   readonly toolstripCompact: 'ui-toolstrip--compact';
+  readonly toolstripPane: 'ui-toolstrip--pane';
+  readonly toolstripAnchored: 'ui-toolstrip--anchored';
+  readonly toolstripAnchorBlockStart: 'ui-toolstrip--anchor-block-start';
+  readonly toolstripAnchorBlockEnd: 'ui-toolstrip--anchor-block-end';
   readonly toolstripBrand: 'ui-toolstrip__brand';
   readonly toolstripContext: 'ui-toolstrip__context';
   readonly toolstripGroup: 'ui-toolstrip__group';
   readonly toolstripActions: 'ui-toolstrip__actions';
+  readonly toolstripFill: 'ui-toolstrip__fill';
   readonly toolstripSearch: 'ui-toolstrip__search';
+  readonly pane: 'ui-pane';
+  readonly paneHead: 'ui-pane__head';
+  readonly paneTitle: 'ui-pane__title';
+  readonly paneTitleInput: 'ui-pane__title-input';
+  readonly paneActions: 'ui-pane__actions';
+  readonly paneBody: 'ui-pane__body';
   readonly segmentedButtons: 'ui-segmented-buttons';
   readonly segmentedButtonsButton: 'ui-segmented-buttons__button';
   readonly property: 'ui-property';
@@ -590,6 +612,9 @@ export declare const cls: {
   readonly selectionbar: 'ui-selectionbar';
   readonly selectionbarCount: 'ui-selectionbar__count';
   readonly selectionbarActions: 'ui-selectionbar__actions';
+  readonly selectionbarAnchored: 'ui-selectionbar--anchored';
+  readonly selectionbarAnchorBlockStart: 'ui-selectionbar--anchor-block-start';
+  readonly selectionbarAnchorBlockEnd: 'ui-selectionbar--anchor-block-end';
   readonly splitter: 'ui-splitter';
   readonly splitterVertical: 'ui-splitter--vertical';
   readonly splitterHorizontal: 'ui-splitter--horizontal';
@@ -666,7 +691,17 @@ export declare function cx(...parts: readonly ClassValue[]): string;
 export interface ButtonOpts {
   variant?: 'ghost' | 'subtle' | 'danger';
   icon?: boolean;
-  size?: 'sm' | 'lg';
+  size?: 'sm' | 'lg' | 'dense';
+}
+export interface EmptyStateOpts {
+  invite?: boolean;
+}
+export interface ToolstripOpts {
+  variant?: 'floating' | 'compact' | 'pane';
+  anchor?: 'block-start' | 'block-end';
+}
+export interface SelectionbarOpts {
+  anchor?: 'block-start' | 'block-end';
 }
 export interface CardOpts {
   accent?: boolean;
@@ -952,11 +987,28 @@ export interface Ui {
   state(opts?: StateOpts): string;
   job(opts?: JobOpts): string;
   originLabel(opts?: OriginLabelOpts): string;
+  emptyState(opts?: EmptyStateOpts): string;
+  toolstrip(opts?: ToolstripOpts): string;
+  selectionbar(opts?: SelectionbarOpts): string;
 }
 
 export declare const ui: Ui;
 export default ui;
 
+/** The canonical severity ladder, worst to best. `unknown` is deliberately not
+ *  a member: it means "not measured", not "nearly ok". */
+export declare const SEVERITY_LEVELS: readonly ['critical', 'error', 'warning', 'notice', 'ok'];
+
+export type SeverityLevel = (typeof SEVERITY_LEVELS)[number];
+
+/** Bundles `data-level` with the severity class so the attribute that carries
+ *  the meaning cannot be forgotten. An unrecognised level resolves to
+ *  `'unknown'`, which paints the neutral tone. */
+export declare function severity(
+  level: SeverityLevel | (string & {}) | null | undefined,
+  opts?: { part?: 'chip' | 'dot' | 'row' },
+): { class: string; 'data-level': string };
+
 /** Min/max for the value-bearing fills; defaults to 0–100. */
 export interface ValueRangeOpts {
   min?: number;