@kerfjs/ui 5.0.0-beta.6 → 5.0.0-beta.61

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.6` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.61` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';
@@ -28,7 +28,11 @@ declare module 'kerfjs/jsx-runtime' {
                 'aria-label'?: string;
                 value?: string;
                 placeholder?: string;
+                hint?: string;
                 disabled?: boolean;
+                size?: 'xs' | 's' | 'm' | 'l' | 'xl';
+                appearance?: 'filled' | 'outlined' | 'filled-outlined';
+                placement?: 'top' | 'bottom';
             };
             'wa-option': KerfCustomElement & {
                 value?: string;
@@ -44,7 +48,9 @@ declare module 'kerfjs/jsx-runtime' {
             'wa-comparison': KerfCustomElement;
             'wa-copy-button': KerfCustomElement;
             'wa-details': KerfCustomElement;
-            'wa-divider': KerfCustomElement;
+            'wa-divider': KerfCustomElement & {
+                orientation?: 'horizontal' | 'vertical';
+            };
             'wa-dialog': KerfCustomElement;
             'wa-drawer': KerfCustomElement;
             'wa-button': KerfCustomElement & {
@@ -55,6 +61,7 @@ declare module 'kerfjs/jsx-runtime' {
             };
             'wa-dropdown': KerfCustomElement & {
                 placement?: string;
+                size?: 'xs' | 's' | 'm' | 'l' | 'xl';
             };
             'wa-dropdown-item': KerfCustomElement;
             'wa-format-bytes': KerfCustomElement;

package/analyzer/cli.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import console from 'node:console';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+
+import {
+  analyzeUiProject,
+  formatUiAnalysisSarif,
+  formatUiAnalysisText,
+} from './index.mjs';
+
+const args = process.argv.slice(2);
+const take = (name) => {
+  const index = args.indexOf(name);
+  if (index < 0) return undefined;
+  const value = args[index + 1];
+  args.splice(index, 2);
+  return value;
+};
+const root = resolve(take('--root') ?? process.cwd());
+const format = take('--format') ?? 'text';
+const output = take('--output');
+const profile = take('--profile');
+const failOnReview = args.includes('--fail-on-review');
+const adoption = args.includes('--adoption');
+const paths = args.filter(
+  (argument) => !argument.startsWith('--') && argument !== '--adoption',
+);
+
+if (!['text', 'json', 'sarif'].includes(format)) {
+  console.error(`Unknown --format ${format}; expected text, json, or sarif.`);
+  process.exitCode = 2;
+} else {
+  const report = await analyzeUiProject({ root, paths, profile, adoption });
+  const rendered =
+    format === 'text'
+      ? formatUiAnalysisText(report)
+      : JSON.stringify(
+          format === 'sarif' ? formatUiAnalysisSarif(report) : report,
+          null,
+          2,
+        );
+  if (output) await writeFile(resolve(root, output), `${rendered}\n`);
+  else console.log(rendered);
+  if (report.summary.errors || (failOnReview && report.summary.review))
+    process.exitCode = 1;
+}

package/analyzer/component-ownership.d.mts

@@ -0,0 +1,56 @@
+export interface OwnershipCatalogEntry {
+  key: string;
+  package: string;
+  id: string;
+  name: string;
+  source?: string;
+  boundaries?: {
+    rootClass?: string | null;
+    publicClasses?: string[];
+    publicTokens?: string[];
+  };
+  cssValueProps?: Array<{ path: string; examples?: string[] }>;
+}
+
+export interface ComponentOwnershipFacts {
+  classOwners: Map<string, OwnershipCatalogEntry>;
+  dataComponentOwners: Map<string, OwnershipCatalogEntry>;
+  tagOwners: Map<string, OwnershipCatalogEntry>;
+  privatePrefixes: Array<{ prefix: string; entry: OwnershipCatalogEntry }>;
+  typedTokens: Map<string, { entry: OwnershipCatalogEntry; path: string }>;
+}
+
+export interface RestyledComponent {
+  entry: OwnershipCatalogEntry;
+  via: 'class' | 'data-component' | 'tag';
+  name: string;
+}
+
+export function componentOwnershipFacts(
+  entries: Iterable<OwnershipCatalogEntry>,
+): ComponentOwnershipFacts;
+export function restyledComponents(
+  selectorList: string,
+  facts: ComponentOwnershipFacts,
+  isForeign: (entry: OwnershipCatalogEntry) => boolean,
+): RestyledComponent[];
+export function privateVariableOwner(
+  property: string,
+  facts: ComponentOwnershipFacts,
+): OwnershipCatalogEntry | null | undefined;
+export function typedPropForToken(
+  token: string,
+  facts: ComponentOwnershipFacts,
+): { entry: OwnershipCatalogEntry; path: string } | undefined;
+export function configurationFor(
+  entry: OwnershipCatalogEntry | null | undefined,
+): string;
+export function reportGap(
+  entry: OwnershipCatalogEntry | null | undefined,
+): string;
+export function componentName(
+  entry: OwnershipCatalogEntry | null | undefined,
+): string;
+export function componentLabel(
+  entry: OwnershipCatalogEntry | null | undefined,
+): string;

package/analyzer/component-ownership.mjs

@@ -0,0 +1,184 @@
+/**
+ * Downstream component-ownership facts for `kerf-ui-analyze` (`KUI-L019` –
+ * `KUI-L022`): the consumer-side form of the package's own
+ * `check:css-ownership` rules.
+ *
+ * Components own their styles and are configured, never overridden. An
+ * application or component package may style its own elements, including in a
+ * cataloged component's context (`.kui-toolbar > .my-widget` lives in the
+ * application's stylesheet), but it never makes another package's component
+ * the subject of a rule, writes that component's private variables, overrides
+ * a token its typed prop configures, or restyles it through a hook class on
+ * its root. Every fact here comes from the loaded composition catalogs, so
+ * third-party component packages get the same protection as `@kerfjs/ui`.
+ */
+import {
+  classNames,
+  complexSelectorParts,
+  dataComponents,
+  subjectTypes,
+  withoutRelationalArguments,
+} from './selectors.mjs';
+
+const kebab = (value) =>
+  value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+function isWebAwesomeTagEntry(entry) {
+  return entry.source === 'webawesome' && /^wa-[a-z0-9-]+$/.test(entry.id);
+}
+
+/**
+ * Index the loaded catalog entries by every handle a stylesheet can use to
+ * reach them: public classes, `data-component` values, Web Awesome tags the
+ * package themes, private-variable prefixes, and component tokens a typed
+ * prop configures.
+ */
+export function componentOwnershipFacts(entries) {
+  const classOwners = new Map();
+  const dataComponentOwners = new Map();
+  const tagOwners = new Map();
+  const privatePrefixes = [];
+  const typedTokens = new Map();
+  const setOnce = (map, key, entry) => {
+    if (!map.has(key)) map.set(key, entry);
+  };
+  for (const entry of entries) {
+    const boundaries = entry.boundaries ?? {};
+    for (const className of boundaries.publicClasses ?? []) {
+      setOnce(classOwners, className, entry);
+      if (
+        className.startsWith('kui-') &&
+        !className.includes('__') &&
+        !className.includes('--')
+      )
+        setOnce(dataComponentOwners, className.slice('kui-'.length), entry);
+    }
+    if (entry.id && !isWebAwesomeTagEntry(entry))
+      setOnce(dataComponentOwners, entry.id, entry);
+    if (isWebAwesomeTagEntry(entry)) setOnce(tagOwners, entry.id, entry);
+    // Every root-like public class names the component (Toolbar Control
+    // Group's first class is its action link, not the group).
+    const roots = [
+      ...new Set(
+        [boundaries.rootClass, ...(boundaries.publicClasses ?? [])].filter(
+          (name) => name && !name.includes('__') && !name.includes('--'),
+        ),
+      ),
+    ];
+    const tokens = new Set(boundaries.publicTokens ?? []);
+    for (const root of roots) {
+      privatePrefixes.push({ prefix: `--_${root}`, entry });
+      for (const contract of entry.cssValueProps ?? []) {
+        const [head] = contract.path.split('[].');
+        const token = `--${root}-${kebab(head)}`;
+        if (tokens.has(token))
+          setOnce(typedTokens, token, { entry, path: contract.path });
+      }
+    }
+  }
+  privatePrefixes.sort((a, b) => b.prefix.length - a.prefix.length);
+  return {
+    classOwners,
+    dataComponentOwners,
+    tagOwners,
+    privatePrefixes,
+    typedTokens,
+  };
+}
+
+/**
+ * The cataloged components a selector list makes its subject: the rightmost
+ * compound of each complex selector, with `:has()` / `:not()` arguments
+ * removed because keying on or excluding a component does not style it. A
+ * subject that is a `::part()` is left to the shadow-part rule (`KUI-L011`).
+ * Returns `{ entry, via, name }` records; `isForeign(entry)` decides which
+ * entries the stylesheet does not own.
+ */
+export function restyledComponents(selectorList, facts, isForeign) {
+  const found = [];
+  const seen = new Set();
+  const add = (entry, via, name) => {
+    if (!entry || !isForeign(entry)) return;
+    const key = `${entry.key}|${via}|${name}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    found.push({ entry, via, name });
+  };
+  for (const parts of complexSelectorParts(selectorList)) {
+    const subject = parts.at(-1)?.compound;
+    if (!subject || /::part\(/i.test(subject)) continue;
+    const bare = withoutRelationalArguments(subject);
+    for (const className of classNames(bare))
+      add(facts.classOwners.get(className), 'class', `.${className}`);
+    for (const value of dataComponents(bare))
+      add(
+        facts.dataComponentOwners.get(value),
+        'data-component',
+        `[data-component="${value}"]`,
+      );
+    // An application class on the subject scopes a Web Awesome tag to the
+    // application's own element; a component package never places one there.
+    if (classNames(bare).some((name) => !facts.classOwners.has(name))) continue;
+    for (const type of subjectTypes(subject) ?? [])
+      add(facts.tagOwners.get(type), 'tag', type);
+  }
+  return found;
+}
+
+/** The catalog entry whose private `--_<root>-*` variable `property` is. */
+export function privateVariableOwner(property, facts) {
+  if (!property.startsWith('--_')) return undefined;
+  const owner = facts.privatePrefixes.find(
+    ({ prefix }) => property === prefix || property.startsWith(`${prefix}-`),
+  );
+  if (owner) return owner.entry;
+  return property.startsWith('--_kui-') ? null : undefined;
+}
+
+/** The typed prop that configures a component token, if one does. */
+export function typedPropForToken(token, facts) {
+  return facts.typedTokens.get(token);
+}
+
+/** Every configuration seam an entry publishes, as prose. */
+export function configurationFor(entry) {
+  if (!entry) return 'its documented props and variants';
+  if (isWebAwesomeTagEntry(entry))
+    return `<${entry.id}>'s documented attributes and ${entry.package}'s Web Awesome theme tokens`;
+  const props = (entry.cssValueProps ?? []).map(({ path }) => `\`${path}\``);
+  const rootClass = entry.boundaries?.rootClass;
+  const tokens = (entry.boundaries?.publicTokens ?? []).filter(
+    (token) => rootClass && token.startsWith(`--${rootClass}-`),
+  );
+  const seams = [
+    ...(props.length ? [`its props (${props.join(', ')})`] : []),
+    ...(tokens.length
+      ? [
+          `its public tokens (${tokens.map((item) => `\`${item}\``).join(', ')})`,
+        ]
+      : []),
+  ];
+  return seams.length
+    ? `${seams.join(' or ')}, or its documented variants`
+    : 'its documented props and variants';
+}
+
+/** The shared closing guidance: a missing seam is a component gap. */
+export function reportGap(entry) {
+  const owner = entry?.package ?? '@kerfjs/ui';
+  return `If no configuration covers this need, report the component gap to ${owner} (open a feature request) instead of overriding it.`;
+}
+
+/** A component's short name: its export, or its Web Awesome tag. */
+export function componentName(entry) {
+  if (!entry) return 'a Kerf component';
+  return isWebAwesomeTagEntry(entry) ? `<${entry.id}>` : entry.name;
+}
+
+/** A component's name with its catalog key. */
+export function componentLabel(entry) {
+  if (!entry) return 'a Kerf component';
+  return isWebAwesomeTagEntry(entry)
+    ? `<${entry.id}>`
+    : `${entry.name} (${entry.key})`;
+}

package/analyzer/index.d.mts

@@ -0,0 +1,49 @@
+export type UiAnalysisSeverity = 'error' | 'review';
+
+export interface UiAnalysisDiagnostic {
+  ruleId: `KUI-L${string}`;
+  severity: UiAnalysisSeverity;
+  message: string;
+  location: { file: string; line: number; column: number };
+  evidence?: unknown;
+  chain?: unknown;
+}
+
+export interface UiAnalysisProfileDiagnostic {
+  code: `KUI-P${string}`;
+  source?: string;
+  path: string;
+  message: string;
+}
+
+export interface UiAnalysisReport {
+  schemaVersion: 1;
+  tool: { name: string; version: 1 };
+  root: '.';
+  files: string[];
+  profile: {
+    files?: string[];
+    diagnostics: UiAnalysisProfileDiagnostic[];
+  };
+  diagnostics: UiAnalysisDiagnostic[];
+  summary: { errors: number; review: number; suppressed: number };
+}
+
+export const UI_ANALYSIS_SCHEMA_VERSION: 1;
+export const UI_ANALYSIS_RULES: Readonly<
+  Record<`KUI-L${string}`, { severity: UiAnalysisSeverity; title: string }>
+>;
+
+/** The doctor's repair action for rules whose fix is more specific than the default. */
+export const UI_ANALYSIS_ACTIONS: Readonly<Record<`KUI-L${string}`, string>>;
+
+export function analyzeUiProject(options?: {
+  root?: string;
+  paths?: string[];
+  profile?: string;
+  knownRules?: Iterable<string>;
+  adoption?: boolean;
+}): Promise<UiAnalysisReport>;
+
+export function formatUiAnalysisText(report: UiAnalysisReport): string;
+export function formatUiAnalysisSarif(report: UiAnalysisReport): object;