@kerfjs/ui 5.0.0-beta.10 → 5.0.0-beta.101

package/analyzer/selectors.mjs

@@ -0,0 +1,212 @@
+/**
+ * Selector parsing shared by the package stylesheet ownership check
+ * (`scripts/lib/css-ownership.mjs`, `npm run check:css-ownership`) and the
+ * downstream component-ownership diagnostics in `kerf-ui-analyze`
+ * (`component-ownership.mjs`). Pure string work over one selector list: no
+ * PostCSS, no filesystem. One copy means the package rule and the consumer
+ * rule agree on which compound a selector styles.
+ */
+
+export function ownsClass(rootClass, candidate) {
+  return (
+    candidate === rootClass ||
+    candidate.startsWith(`${rootClass}__`) ||
+    candidate.startsWith(`${rootClass}--`)
+  );
+}
+
+/**
+ * Split a selector list into its complex selectors, and each complex selector
+ * into compounds, ignoring commas and combinators nested inside parentheses,
+ * attribute brackets, or quotes. Each compound records the combinator that
+ * joins it to the previous one (`''` for the first).
+ */
+export function complexSelectorParts(selectorList) {
+  const selectors = [];
+  let compounds = [];
+  let current = '';
+  let combinator = '';
+  let pending = '';
+  let depth = 0;
+  let quote = null;
+  const endCompound = () => {
+    if (current.trim()) {
+      compounds.push({ combinator, compound: current.trim() });
+      combinator = '';
+    }
+    current = '';
+  };
+  for (const char of selectorList) {
+    if (quote) {
+      current += char;
+      if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      current += char;
+    } else if (char === '(' || char === '[') {
+      depth += 1;
+      current += char;
+    } else if (char === ')' || char === ']') {
+      depth -= 1;
+      current += char;
+    } else if (depth === 0 && char === ',') {
+      endCompound();
+      selectors.push(compounds);
+      compounds = [];
+      pending = '';
+    } else if (depth === 0 && /[\s>+~]/.test(char)) {
+      const hadCompound = current.trim() !== '';
+      endCompound();
+      if (/[>+~]/.test(char)) pending = char;
+      else if (!pending && (hadCompound || compounds.length > 0)) pending = ' ';
+    } else {
+      if (!current && compounds.length > 0) {
+        combinator = pending || ' ';
+        pending = '';
+      }
+      current += char;
+    }
+  }
+  endCompound();
+  selectors.push(compounds);
+  return selectors;
+}
+
+/** Complex selectors as arrays of compound strings. */
+export function complexSelectors(selectorList) {
+  return complexSelectorParts(selectorList).map((parts) =>
+    parts.map(({ compound }) => compound),
+  );
+}
+
+export function kuiClasses(selector) {
+  return [...selector.matchAll(/\.((?:kui)-[a-z0-9_-]+)/gi)].map(
+    ([, name]) => name,
+  );
+}
+
+/** Every class name a selector names, in any namespace. */
+export function classNames(selector) {
+  return [...selector.matchAll(/\.(-?[_a-zA-Z][_a-zA-Z0-9-]*)/g)].map(
+    ([, name]) => name,
+  );
+}
+
+export function dataComponents(selector) {
+  return [
+    ...selector.matchAll(
+      /\[data-component\s*=\s*["']?([a-z0-9-]+)["']?\s*\]/gi,
+    ),
+  ].map(([, name]) => name);
+}
+
+/**
+ * Remove the arguments of every pseudo-class named in `names` from a
+ * compound, keeping the empty call.
+ */
+export function withoutPseudoArguments(compound, names) {
+  const opener = new RegExp(`^:(?:${names.join('|')})\\(`, 'i');
+  let result = '';
+  let skipDepth = 0;
+  for (let index = 0; index < compound.length; index += 1) {
+    if (skipDepth === 0) {
+      const match = opener.exec(compound.slice(index));
+      if (match) {
+        result += match[0];
+        skipDepth = 1;
+        index += match[0].length - 1;
+      } else result += compound[index];
+    } else if (compound[index] === '(') skipDepth += 1;
+    else if (compound[index] === ')') {
+      skipDepth -= 1;
+      if (skipDepth === 0) result += ')';
+    }
+  }
+  return result;
+}
+
+/**
+ * Remove the arguments of every `:has()` and `:not()` in a compound. A parent
+ * may key its own styles on a composed child's state
+ * (`:has(> .kui-select[open])`) or exclude a kerf child it does not own
+ * (`wa-dropdown:not(.kui-popup-menu)`): neither styles that child.
+ */
+export function withoutRelationalArguments(compound) {
+  return withoutPseudoArguments(compound, ['has', 'not']);
+}
+
+/** The top-level arguments of each `:name(...)` call in a compound. */
+export function pseudoArguments(compound, name) {
+  const args = [];
+  const opener = new RegExp(`:${name}\\(`, 'gi');
+  for (const match of compound.matchAll(opener)) {
+    let depth = 1;
+    let index = match.index + match[0].length;
+    const start = index;
+    for (; index < compound.length && depth > 0; index += 1) {
+      if (compound[index] === '(') depth += 1;
+      else if (compound[index] === ')') depth -= 1;
+    }
+    args.push(compound.slice(start, index - 1));
+  }
+  return args;
+}
+
+export function splitTopLevel(list) {
+  const parts = [];
+  let depth = 0;
+  let current = '';
+  for (const char of list) {
+    if (char === '(' || char === '[') depth += 1;
+    else if (char === ')' || char === ']') depth -= 1;
+    if (char === ',' && depth === 0) {
+      parts.push(current.trim());
+      current = '';
+    } else current += char;
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}
+
+/**
+ * The element types a subject compound can match: its own type selector and
+ * the subject types inside its `:is()` / `:where()` arguments. `null` means the
+ * compound places no type constraint (universal).
+ */
+export function subjectTypes(compound) {
+  const bare = withoutPseudoArguments(compound, [
+    'has',
+    'not',
+    'is',
+    'where',
+    'part',
+    'nth-child',
+    'nth-last-child',
+    'nth-of-type',
+    'nth-last-of-type',
+  ]);
+  const own = /^([a-z][a-z0-9-]*)/i.exec(bare);
+  if (own) return [own[1].toLowerCase()];
+  const types = [];
+  for (const name of ['is', 'where']) {
+    for (const args of pseudoArguments(
+      withoutRelationalArguments(compound),
+      name,
+    )) {
+      for (const arg of splitTopLevel(args)) {
+        const parts = complexSelectors(arg)[0] ?? [];
+        const last = parts.at(-1);
+        if (!last) return null;
+        const inner = subjectTypes(last);
+        if (inner === null) {
+          // A class-only argument constrains nothing by type, but it names an
+          // element that must carry that class.
+          if (kuiClasses(withoutRelationalArguments(last)).length > 0) continue;
+          return null;
+        }
+        types.push(...inner);
+      }
+    }
+  }
+  return types.length > 0 ? types : null;
+}

package/catalog-projection-cli.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { projectConsumerCatalog } from './catalog-projection.mjs';
+
+const usage =
+  'Usage: kerf-catalog-demo --extension <catalog.json> --out <catalog.generated.ts> --repo-base <blob-url> [--kerf-catalog <catalog.json>] [--category <name>] [--source-template <path>] [--demo-template <path>] [--documentation-template <path>] [--design-template <path>] (--write|--check)';
+
+function parseArgs(argv) {
+  const options = {};
+  const values = new Map([
+    ['--extension', 'extension'],
+    ['--out', 'out'],
+    ['--repo-base', 'repoBase'],
+    ['--kerf-catalog', 'kerfCatalog'],
+    ['--category', 'category'],
+    ['--source-template', 'sourceTemplate'],
+    ['--demo-template', 'demoTemplate'],
+    ['--documentation-template', 'documentationTemplate'],
+    ['--design-template', 'designTemplate'],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--check' || arg === '--write') {
+      if (options.mode)
+        throw new Error('Choose exactly one of --write or --check');
+      options.mode = arg;
+    } else if (values.has(arg)) {
+      const value = argv[++index];
+      if (!value || value.startsWith('--'))
+        throw new Error(`${arg} needs a value`);
+      options[values.get(arg)] = value;
+    } else {
+      throw new Error(`Unknown option ${arg}`);
+    }
+  }
+  if (!options.mode || !options.extension || !options.out || !options.repoBase)
+    throw new Error(usage);
+  if (!/^https?:\/\//.test(options.repoBase))
+    throw new Error('--repo-base must be an HTTP(S) URL');
+  return options;
+}
+
+export function renderConsumerCatalog(rows, repoBase) {
+  const base = repoBase.endsWith('/') ? repoBase : `${repoBase}/`;
+  return (
+    '// Generated by kerf-catalog-demo. Do not edit.\n' +
+    `export const catalogRepositoryBlobUrl = ${JSON.stringify(base)} as const;\n` +
+    `export const generatedConsumerCatalog = ${JSON.stringify(rows, null, 2)} as const;\n`
+  );
+}
+
+export async function runCatalogProjection(argv) {
+  const options = parseArgs(argv);
+  const extension = JSON.parse(
+    await readFile(resolve(options.extension), 'utf8'),
+  );
+  const kerfCatalog = JSON.parse(
+    await readFile(
+      options.kerfCatalog
+        ? resolve(options.kerfCatalog)
+        : new URL('./ai/component-catalog.json', import.meta.url),
+      'utf8',
+    ),
+  );
+  const rows = projectConsumerCatalog(extension, kerfCatalog, options);
+  const output = renderConsumerCatalog(rows, options.repoBase);
+  const outputPath = resolve(options.out);
+  if (options.mode === '--write') {
+    await writeFile(outputPath, output);
+    process.stdout.write(`Wrote ${outputPath}\n`);
+  } else {
+    let current;
+    try {
+      current = await readFile(outputPath, 'utf8');
+    } catch {
+      // A missing generated file is the same drift as stale content.
+    }
+    if (current !== output)
+      throw new Error(`${outputPath} is stale; run kerf-catalog-demo --write`);
+    process.stdout.write(`${outputPath} is in sync.\n`);
+  }
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  runCatalogProjection(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`kerf-catalog-demo: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/catalog-projection.d.mts

@@ -0,0 +1,55 @@
+export interface CatalogProjectionRow {
+  id: string;
+  name: string;
+  category: string;
+  kind: string;
+  source: string;
+  description: string;
+  recommendation?: string;
+  uses: readonly string[];
+  demoSource: string;
+  componentSource?: string;
+  designTemplate?: string;
+  documentation?: string;
+}
+
+export interface CatalogProjectionEntry {
+  id: string;
+  name: string;
+  kind: string;
+  purpose: string;
+  category?: string;
+  source?: string;
+  demoSource?: string;
+  documentation?: string;
+  recommendation?: string;
+  uses?: string[];
+}
+
+export interface CatalogProjectionOptions {
+  identity?: (entry: CatalogProjectionEntry) => string;
+  category?: (entry: CatalogProjectionEntry) => string;
+  componentSource?: (entry: CatalogProjectionEntry) => string | undefined;
+  demoSource?: (entry: CatalogProjectionEntry) => string | undefined;
+  documentation?: (entry: CatalogProjectionEntry) => string | undefined;
+  designTemplate?: (entry: CatalogProjectionEntry) => string | undefined;
+}
+
+export interface ConsumerProjectionOptions {
+  category?: string;
+  sourceTemplate?: string;
+  demoTemplate?: string;
+  documentationTemplate?: string;
+  designTemplate?: string;
+}
+
+export function projectCatalogEntries(
+  entries: readonly CatalogProjectionEntry[],
+  options?: CatalogProjectionOptions,
+): CatalogProjectionRow[];
+
+export function projectConsumerCatalog(
+  extension: { package: string; entries: CatalogProjectionEntry[] },
+  kerfCatalog: { entries: { id: string }[] },
+  options?: ConsumerProjectionOptions,
+): CatalogProjectionRow[];

package/catalog-projection.mjs

@@ -0,0 +1,62 @@
+import {
+  isRepositoryPath,
+  validateCatalogExtensionReferences,
+} from './scripts/component-catalog-extension-validation.mjs';
+
+const substitute = (template, entry, packageName) =>
+  template.replace(/\{(id|name|kind|package)\}/g, (_, field) =>
+    field === 'package' ? packageName : entry[field],
+  );
+
+/** Project catalog entries into the row shape used by a UX demo. */
+export function projectCatalogEntries(entries, options = {}) {
+  return entries.map((entry) => {
+    const componentSource = options.componentSource?.(entry);
+    const designTemplate = options.designTemplate?.(entry);
+    return {
+      id: entry.id,
+      name: entry.name,
+      category: options.category?.(entry) ?? entry.category ?? 'Application',
+      kind: entry.kind,
+      source: options.identity?.(entry) ?? entry.source ?? 'consumer',
+      description: entry.purpose,
+      ...(entry.recommendation ? { recommendation: entry.recommendation } : {}),
+      uses: entry.uses ?? [],
+      demoSource: options.demoSource?.(entry) ?? entry.demoSource,
+      ...(componentSource ? { componentSource } : {}),
+      ...(designTemplate ? { designTemplate } : {}),
+      documentation: options.documentation?.(entry) ?? entry.documentation,
+    };
+  });
+}
+
+/** Project a validated consumer extension alongside Kerf's reference catalog. */
+export function projectConsumerCatalog(extension, kerfCatalog, options = {}) {
+  const failures = validateCatalogExtensionReferences(extension, kerfCatalog);
+  if (failures.length) throw new Error(failures.join('\n'));
+  const fill = (template, entry) =>
+    template ? substitute(template, entry, extension.package) : undefined;
+  const rows = projectCatalogEntries(extension.entries, {
+    identity: () => 'consumer',
+    category: () => options.category ?? 'Application',
+    componentSource: (entry) =>
+      entry.source ?? fill(options.sourceTemplate, entry),
+    demoSource: (entry) =>
+      entry.demoSource ??
+      fill(options.demoTemplate ?? 'ux-demo/demos/{id}.tsx', entry),
+    documentation: (entry) =>
+      entry.documentation ?? fill(options.documentationTemplate, entry),
+    designTemplate: (entry) => fill(options.designTemplate, entry),
+  });
+  for (const row of rows) {
+    if (!isRepositoryPath(row.demoSource))
+      throw new Error(`${row.id} requires a repository-relative demoSource`);
+    if (row.componentSource && !isRepositoryPath(row.componentSource))
+      throw new Error(`${row.id} has an invalid repository-relative source`);
+    if (!row.documentation)
+      throw new Error(
+        `${row.id} requires documentation or documentationTemplate`,
+      );
+  }
+  return rows;
+}

package/dist/anchored-surface.d.ts

@@ -0,0 +1,69 @@
+import { PopoverOptions, OverlayContent, OverlayHandle } from 'kerfjs/overlay';
+
+/** App-facing options for a non-modal, arbitrary-content help surface. */
+interface AnchoredSurfaceOptions extends Pick<PopoverOptions, 'placement' | 'align' | 'gap' | 'dismiss' | 'initialFocus' | 'onDismiss' | 'outsideIgnore' | 'container'> {
+    /** Accessible name for the non-modal dialog. */
+    label: string;
+    /**
+     * Gutter in px kept between the surface and the viewport edges when it is
+     * clamped horizontally and fitted vertically. Default `8`, the same gutter as
+     * the surface's maximum size.
+     */
+    viewportMargin?: number;
+    /**
+     * Where to append the surface. Default: inside the anchor's open modal
+     * dialog — a native `<dialog>`'s host slot, or a slot kerf creates in a
+     * `wa-dialog` / `wa-drawer` — so the surface stays interactive there;
+     * otherwise `document.body`. Pass an element only for a modal context kerf
+     * cannot resolve; an element inside an open modal closes the surface with it.
+     */
+    container?: Element;
+    /**
+     * Surface tone. `'default'` follows the anchor's color scheme. `'dark'` is
+     * the loud, inverse tone of a `ToolbarControlGroup` / `ToolbarText`
+     * `tone="dark"`, for a popup anchored to dark media chrome (a volume popup
+     * over a video preview): dark beside a light page and light beside a dark
+     * one, so the popup matches the control group that opened it. The surface
+     * takes the opposite of the anchor's color scheme, so it and every Kerf UI
+     * or Web Awesome component inside it resolve the same semantic
+     * `light-dark()` tokens to the other side: no new colors, no child
+     * overrides. While open it follows a live switch of that scheme (the OS
+     * preference, or an app theme class or attribute on an ancestor). Default
+     * `'default'`.
+     */
+    tone?: AnchoredSurfaceTone;
+}
+/** {@link AnchoredSurfaceOptions.tone}: follow the anchor's scheme, or invert it. */
+type AnchoredSurfaceTone = 'default' | 'dark';
+/** A viewport pointer location; `context` is the element under the pointer. */
+interface AnchoredSurfacePoint {
+    x: number;
+    y: number;
+    /**
+     * Pass the event target when opening from inside a modal dialog, native or
+     * Web Awesome (`wa-dialog`, `wa-drawer`). The dark tone also reads its
+     * color scheme from `context`, so a region with its own `color-scheme` is
+     * honored; without it the scheme is the modal scope's (or the page's).
+     */
+    context?: Element;
+}
+/**
+ * Open app-owned content beside an element. The surface owns its Kerf UI chrome;
+ * kerfjs/overlay owns positioning, top-layer/modal hosting, focus, and dismissal.
+ * The surface stays `viewportMargin` inside the viewport edges and fits its
+ * height to the room beside the anchor (the roomier side when neither holds it),
+ * scrolling its content; `--kui-anchored-surface-available-height` exposes that
+ * room to the content, updated as the page scrolls or resizes.
+ * The caller owns content, action policy, and calling `close()` when an action
+ * completes. `initialFocus` defaults to the first focusable descendant; set it
+ * to `false` for read-only help that should leave focus on its trigger.
+ */
+declare function openAnchoredSurface(anchor: Element, content: OverlayContent, options: AnchoredSurfaceOptions): OverlayHandle;
+/**
+ * Open the same surface at pointer coordinates. The temporary anchor has no
+ * layout or hit target. `context` keeps a surface opened inside a modal dialog
+ * in that dialog's interactive host slot; it is removed on close or failure.
+ */
+declare function openAnchoredSurfaceAt(point: AnchoredSurfacePoint, content: OverlayContent, options: AnchoredSurfaceOptions): OverlayHandle;
+
+export { type AnchoredSurfaceOptions, type AnchoredSurfacePoint, type AnchoredSurfaceTone, openAnchoredSurface, openAnchoredSurfaceAt };

package/dist/anchored-surface.js

@@ -0,0 +1,3 @@
+export { openAnchoredSurface, openAnchoredSurfaceAt } from './chunk-3WYREXW4.js';
+
+//# sourceMappingURL=anchored-surface.js.map

package/dist/anchored-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"anchored-surface.js"}

package/dist/app-tab.d.ts

@@ -1,4 +1,5 @@
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type AppTabRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -7,15 +8,36 @@ type AppTabRootAttributes = Readonly<Record<`data-${string}`, string | undefined
     'data-selected'?: never;
     'data-tab-dragging'?: never;
     'data-tab-drop-position'?: never;
+    'data-attention'?: never;
+    'data-drop-target'?: never;
+    'data-name-overflow'?: never;
+    'data-pinned'?: never;
 }>;
+type AppTabPresentation = 'pill' | 'segmented' | 'icon-only';
+type AppTabSize = 'default' | 'compact';
+type AppTabNameOverflow = 'ellipsis' | 'visible';
 interface AppTabProps {
     id: string;
     name: string;
     selected?: boolean;
+    /** Emphasize the visible tab name with the attention color token. */
+    attention?: boolean;
+    /** Highlight this tab as the target of a drag over its content. */
+    dropTarget?: boolean;
+    /** Keep the leading tab visible within its TabBar tablist while peers scroll. */
+    pinned?: boolean;
     closable?: boolean;
     draggable?: boolean;
-    leading?: SafeHtml;
-    trailing?: SafeHtml;
+    leading?: KerfUiContent;
+    trailing?: KerfUiContent;
+    /** Visual treatment within a TabBar. Icon-only tabs retain `name` as their accessible name. */
+    presentation?: AppTabPresentation;
+    /** Compact tabs use the 32px application-rail height. */
+    size?: AppTabSize;
+    /** Maximum visible label width in CSS pixels before ellipsis. */
+    labelMaxWidth?: number;
+    /** Keep the full name visible for an inline loading treatment. */
+    nameOverflow?: AppTabNameOverflow;
     /** Decorative dormant content for the close button. Must not contain interactive descendants. */
     closeIcon?: SafeHtml;
     selectAction?: string;
@@ -23,8 +45,21 @@ interface AppTabProps {
     className?: string;
     /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
     placeholder?: boolean;
+    /**
+     * Named and still opening: the tab is known but its content is loading.
+     * Keeps `name` visible in the quiet text color and as the tab's accessible
+     * name, shows `trailing` (for example a `LoadingSpinner`), and marks the
+     * tab `aria-busy`. Unlike `placeholder` it stays selectable — the
+     * application shows placeholder content in its panel until loading
+     * completes — while close and dragging stay disabled. Same pill geometry
+     * as the live tab, so swapping it in place does not shift the bar.
+     * `placeholder` wins when both are set.
+     */
+    pending?: boolean;
     rootAttributes?: AppTabRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, attention, dropTarget, pinned, closable, draggable, leading, trailing, presentation, size, labelMaxWidth, nameOverflow, closeIcon, selectAction, closeAction, className, placeholder, pending, rootAttributes, slot, }: AppTabProps): SafeHtml;
 
-export { AppTab, type AppTabProps };
+export { AppTab, type AppTabNameOverflow, type AppTabPresentation, type AppTabProps, type AppTabSize };

package/dist/app-tab.js

@@ -1,4 +1,5 @@
-export { AppTab } from './chunk-2Z5TWHKQ.js';
+export { AppTab } from './chunk-TGLUDQP2.js';
+