@kerfjs/ui 4.4.1 → 4.5.0-beta.1

package/analyzer/report.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/analyzer/report.schema.json",
+  "title": "Kerf UI static analysis report",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "tool",
+    "root",
+    "files",
+    "profile",
+    "diagnostics",
+    "summary"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "integer" }
+      },
+      "additionalProperties": false
+    },
+    "root": { "type": "string" },
+    "files": { "type": "array", "items": { "type": "string" } },
+    "profile": { "type": "object" },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["ruleId", "severity", "message", "location"],
+        "properties": {
+          "ruleId": { "pattern": "^KUI-L[0-9]{3}$" },
+          "severity": { "enum": ["error", "review"] },
+          "message": { "type": "string" },
+          "location": {
+            "type": "object",
+            "required": ["file", "line", "column"],
+            "properties": {
+              "file": { "type": "string" },
+              "line": { "type": "integer", "minimum": 1 },
+              "column": { "type": "integer", "minimum": 1 }
+            },
+            "additionalProperties": false
+          },
+          "evidence": {},
+          "chain": {}
+        },
+        "additionalProperties": false
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["errors", "review", "suppressed"],
+      "properties": {
+        "errors": { "type": "integer", "minimum": 0 },
+        "review": { "type": "integer", "minimum": 0 },
+        "suppressed": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/dist/app-tab.d.ts

@@ -1,5 +1,13 @@
 import { SafeHtml } from 'kerfjs';
 
+type AppTabRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-action'?: never;
+    'data-tab-id'?: never;
+    'data-selected'?: never;
+    'data-tab-dragging'?: never;
+    'data-tab-drop-position'?: never;
+}>;
 interface AppTabProps {
     id: string;
     name: string;
@@ -8,11 +16,15 @@ interface AppTabProps {
     draggable?: boolean;
     leading?: SafeHtml;
     trailing?: SafeHtml;
+    /** Decorative dormant content for the close button. Must not contain interactive descendants. */
+    closeIcon?: SafeHtml;
     selectAction?: string;
     closeAction?: string;
     className?: string;
-    rootAttributes?: Readonly<Record<`data-${string}`, string>>;
+    /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
+    placeholder?: boolean;
+    rootAttributes?: AppTabRootAttributes;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, selectAction, closeAction, className, rootAttributes }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes, }: AppTabProps): SafeHtml;
 
 export { AppTab, type AppTabProps };

package/dist/app-tab.js

@@ -1,3 +1,5 @@
-export { AppTab } from './chunk-T5XNMVOI.js';
+export { AppTab } from './chunk-Y45PPBDV.js';
+
+
 
 //# sourceMappingURL=app-tab.js.map

package/dist/browser/app-tab.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/app-tab.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/app-tab.css';
 export * from '../app-tab.js';

package/dist/browser/disclosure-arrow.js

@@ -0,0 +1,4 @@
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/disclosure-arrow.css';
+export * from '../disclosure-arrow.js';

package/dist/browser/empty-state.js

@@ -1,4 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/loading-spinner.css';
-import '../../src/empty-state.css';
+import '../styles/foundation.css';
+import '../styles/loading-spinner.css';
+import '../styles/empty-state.css';
 export * from '../empty-state.js';

package/dist/browser/floating-toolbar.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/floating-toolbar.css';
+export * from '../floating-toolbar.js';

package/dist/browser/list-action-row.js

@@ -0,0 +1,4 @@
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/list-action-row.css';
+export * from '../list-action-row.js';

package/dist/browser/list-header.js

@@ -0,0 +1,6 @@
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/disclosure-arrow.css';
+import '../styles/skeleton.css';
+import '../styles/list-header.css';
+export * from '../list-header.js';

package/dist/browser/list-inset-control.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/list-inset-control.css';
+export * from '../list-inset-control.js';

package/dist/browser/list-inset-text.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/list-inset-text.css';
+export * from '../list-inset-text.js';

package/dist/browser/list-item.js

@@ -0,0 +1,4 @@
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/list-item.css';
+export * from '../list-item.js';

package/dist/browser/list.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/list.css';
+export * from '../list.js';

package/dist/browser/loading-spinner.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/loading-spinner.css';
+import '../styles/foundation.css';
+import '../styles/loading-spinner.css';
 export * from '../loading-spinner.js';

package/dist/browser/lucide-icon.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/lucide-icon.css';
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
 export * from '../lucide-icon.js';

package/dist/browser/pane.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/pane.css';
+export * from '../pane.js';

package/dist/browser/panel-header.js

@@ -0,0 +1,7 @@
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/toolbar.css';
+import '../styles/toolbar-control-group.css';
+import '../styles/toolbar-text.css';
+import '../styles/panel-header.css';
+export * from '../panel-header.js';

package/dist/browser/resizable-region.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/resizable-region.css';
+import '../styles/foundation.css';
+import '../styles/resizable-region.css';
 export * from '../resizable-region.js';

package/dist/browser/segmented-control.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/segmented-control.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/segmented-control.css';
 export * from '../segmented-control.js';

package/dist/browser/select.js

@@ -1,4 +1,5 @@
-import '../../src/foundation.css';
-import '../../src/lucide-icon.css';
-import '../../src/select.css';
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/skeleton.css';
+import '../styles/select.css';
 export * from '../select.js';

package/dist/browser/skeleton.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+export * from '../skeleton.js';

package/dist/browser/state-banner.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/state-banner.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/state-banner.css';
 export * from '../state-banner.js';

package/dist/browser/sunken-panel.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/sunken-panel.css';
+export * from '../sunken-panel.js';

package/dist/browser/tab-bar.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/tab-bar.css';
+import '../styles/foundation.css';
+import '../styles/tab-bar.css';
 export * from '../tab-bar.js';

package/dist/browser/token-search-field.js

@@ -0,0 +1,4 @@
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/token-search-field.css';
+export * from '../token-search-field.js';

package/dist/browser/toolbar-control-group.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/toolbar-control-group.css';
+import '../styles/foundation.css';
+import '../styles/toolbar-control-group.css';
 export * from '../toolbar-control-group.js';

package/dist/browser/toolbar-text.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/toolbar-text.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/toolbar-text.css';
 export * from '../toolbar-text.js';

package/dist/browser/toolbar.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/toolbar.css';
+import '../styles/foundation.css';
+import '../styles/toolbar.css';
 export * from '../toolbar.js';

package/dist/browser/value-table.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/value-table.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/value-table.css';
 export * from '../value-table.js';

package/dist/catalog-resources.d.ts

@@ -0,0 +1,34 @@
+import { CatalogResource } from './catalog.js';
+import 'kerfjs';
+
+/**
+ * Standard resource labels for a Kerf catalog detail footer. Keep these labels
+ * stable across catalogs so people and AI-generated integrations see the same
+ * choices in the same vocabulary.
+ */
+type CatalogResourceKind = 'demoSource' | 'componentSource' | 'designTemplate' | 'guidance' | 'integrationGuidance';
+type CatalogGuidanceKind = 'guidance' | 'integrationGuidance';
+interface CatalogResourceTarget {
+    href: string;
+    /** Optional monospace detail, normally the repository-relative source path. */
+    detail?: string;
+}
+interface CatalogResourcesInput {
+    /** Required source for the runnable demonstration. */
+    demoSource: CatalogResourceTarget;
+    /** Source for the production component; omit for recipes and integrations. */
+    componentSource?: CatalogResourceTarget;
+    /** Optional design-tool template associated with the component. */
+    designTemplate?: CatalogResourceTarget;
+    /** Required UI or integration guidance. */
+    guidance: CatalogResourceTarget;
+    /** Use `integrationGuidance` when the component implementation is upstream. */
+    guidanceKind?: CatalogGuidanceKind;
+}
+/**
+ * Build the standard catalog resource group in its canonical order: demo,
+ * component, optional design template, then guidance.
+ */
+declare function catalogResources(input: CatalogResourcesInput): CatalogResource[];
+
+export { type CatalogGuidanceKind, type CatalogResourceKind, type CatalogResourceTarget, type CatalogResourcesInput, catalogResources };

package/dist/catalog-resources.js

@@ -0,0 +1,22 @@
+// src/catalog-resources.ts
+function catalogResources(input) {
+  const resources = [
+    { label: "Demo source", ...input.demoSource }
+  ];
+  if (input.componentSource)
+    resources.push({
+      label: "Component source",
+      ...input.componentSource
+    });
+  if (input.designTemplate)
+    resources.push({ label: "Design template", ...input.designTemplate });
+  resources.push({
+    label: input.guidanceKind === "integrationGuidance" ? "Integration guidance" : "Guidance",
+    ...input.guidance
+  });
+  return resources;
+}
+
+export { catalogResources };
+
+//# sourceMappingURL=catalog-resources.js.map

package/dist/catalog-resources.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/catalog-resources.ts"],"names":[],"mappings":";AAuCO,SAAS,iBACd,KAAA,EACmB;AACnB,EAAA,MAAM,SAAA,GAA+B;AAAA,IACnC,EAAE,KAAA,EAAO,aAAA,EAAe,GAAG,MAAM,UAAA;AAAW,GAC9C;AACA,EAAA,IAAI,KAAA,CAAM,eAAA;AACR,IAAA,SAAA,CAAU,IAAA,CAAK;AAAA,MACb,KAAA,EAAO,kBAAA;AAAA,MACP,GAAG,KAAA,CAAM;AAAA,KACV,CAAA;AACH,EAAA,IAAI,KAAA,CAAM,cAAA;AACR,IAAA,SAAA,CAAU,KAAK,EAAE,KAAA,EAAO,mBAAmB,GAAG,KAAA,CAAM,gBAAgB,CAAA;AACtE,EAAA,SAAA,CAAU,IAAA,CAAK;AAAA,IACb,KAAA,EACE,KAAA,CAAM,YAAA,KAAiB,qBAAA,GACnB,sBAAA,GACA,UAAA;AAAA,IACN,GAAG,KAAA,CAAM;AAAA,GACV,CAAA;AACD,EAAA,OAAO,SAAA;AACT","file":"catalog-resources.js","sourcesContent":["import type { CatalogResource } from './catalog.js';\n\n/**\n * Standard resource labels for a Kerf catalog detail footer. Keep these labels\n * stable across catalogs so people and AI-generated integrations see the same\n * choices in the same vocabulary.\n */\nexport type CatalogResourceKind =\n  | 'demoSource'\n  | 'componentSource'\n  | 'designTemplate'\n  | 'guidance'\n  | 'integrationGuidance';\n\nexport type CatalogGuidanceKind = 'guidance' | 'integrationGuidance';\n\nexport interface CatalogResourceTarget {\n  href: string;\n  /** Optional monospace detail, normally the repository-relative source path. */\n  detail?: string;\n}\n\nexport interface CatalogResourcesInput {\n  /** Required source for the runnable demonstration. */\n  demoSource: CatalogResourceTarget;\n  /** Source for the production component; omit for recipes and integrations. */\n  componentSource?: CatalogResourceTarget;\n  /** Optional design-tool template associated with the component. */\n  designTemplate?: CatalogResourceTarget;\n  /** Required UI or integration guidance. */\n  guidance: CatalogResourceTarget;\n  /** Use `integrationGuidance` when the component implementation is upstream. */\n  guidanceKind?: CatalogGuidanceKind;\n}\n\n/**\n * Build the standard catalog resource group in its canonical order: demo,\n * component, optional design template, then guidance.\n */\nexport function catalogResources(\n  input: CatalogResourcesInput,\n): CatalogResource[] {\n  const resources: CatalogResource[] = [\n    { label: 'Demo source', ...input.demoSource },\n  ];\n  if (input.componentSource)\n    resources.push({\n      label: 'Component source',\n      ...input.componentSource,\n    });\n  if (input.designTemplate)\n    resources.push({ label: 'Design template', ...input.designTemplate });\n  resources.push({\n    label:\n      input.guidanceKind === 'integrationGuidance'\n        ? 'Integration guidance'\n        : 'Guidance',\n    ...input.guidance,\n  });\n  return resources;\n}\n"]}

package/dist/catalog.d.ts

@@ -0,0 +1,150 @@
+import { SafeHtml } from 'kerfjs';
+
+/** A reference link shown in the detail footer for the active entry. */
+interface CatalogResource {
+    label: string;
+    href: string;
+    /** Optional monospace detail (e.g. a file path) shown after the label. */
+    detail?: string;
+}
+/** A related entry offered in the detail footer's "Related entries" popup menu. */
+interface CatalogRelated {
+    id: string;
+    name: string;
+    /** Group heading in the menu, e.g. "Uses" / "Used by". */
+    group: string;
+}
+interface CatalogEntry {
+    id: string;
+    name: string;
+    description?: string;
+    /** Short metadata tags shown at the trailing edge of the sidebar row. */
+    tags?: readonly string[];
+    resources?: readonly CatalogResource[];
+    related?: readonly CatalogRelated[];
+}
+interface CatalogSection {
+    category: string;
+    entries: readonly CatalogEntry[];
+}
+/**
+ * A secondary group of sections shown below the primary sidebar sections with a
+ * quieter "ecosystem" treatment (e.g. third-party components). Optionally
+ * collapsible — the app owns `expanded` and toggles it from `wireCatalog`'s
+ * `onToggleSecondary`.
+ */
+interface CatalogSecondaryGroup {
+    label: string;
+    sections: readonly CatalogSection[];
+    /** When true, the group's label is a disclosure toggle controlling `expanded`. */
+    collapsible?: boolean;
+    /** Whether the group is expanded (controlled). Ignored unless `collapsible`. */
+    expanded?: boolean;
+}
+interface CatalogBrand {
+    title: string;
+    subtitle?: string;
+    /** Logo image URL (rendered decorative). Omit for a text-only brand. */
+    logoUrl?: string;
+}
+interface CatalogProps {
+    brand: CatalogBrand;
+    sections: readonly CatalogSection[];
+    /** The controlled active entry id — the app owns this signal. */
+    active: string;
+    /** The rendered preview for the active entry; the app computes it from `active`. */
+    content: SafeHtml;
+    /** Whether the sidebar is collapsed (controlled). */
+    collapsed?: boolean;
+    /** Current theme; when set, a theme toggle is shown that switches to the opposite. Omit to hide it. */
+    theme?: 'light' | 'dark';
+    /** Extra header controls placed before the theme toggle (each a `ToolbarControlGroup`). */
+    headerActions?: SafeHtml;
+    /** A secondary "ecosystem" group of sections below the primary category groups. */
+    secondarySections?: CatalogSecondaryGroup;
+    /** Extra sidebar content below the category groups (and the secondary group). */
+    sidebarFooter?: SafeHtml;
+    /** Status line content shown at the start of the detail footer. */
+    status?: SafeHtml;
+    /**
+     * Whether to highlight specimens' computed borders (or transparent outer
+     * bounds) and non-zero margins. Pass a boolean (rather than omitting the
+     * prop) when the active entry can switch between component and composition
+     * previews; `wireCatalogGeometryOverlay` keeps the overlay synchronized.
+     */
+    geometryOverlay?: boolean;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    /** Action fired by the secondary group's disclosure toggle (when collapsible). */
+    toggleSecondaryAction?: string;
+    className?: string;
+}
+/**
+ * A reusable component-catalog shell: a collapsible category sidebar, a titled
+ * detail stage that renders the active entry's preview, and a footer with
+ * reference links and a related-entry popup menu. Built entirely from public
+ * `@kerfjs/ui` primitives. Controlled and stateless — the app owns the `active`,
+ * `collapsed`, and `theme` signals and computes `content` from `active` in its own
+ * render; wire the sidebar/collapse/theme actions with `wireCatalog`.
+ */
+declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, }: CatalogProps): SafeHtml;
+/**
+ * How a {@link CatalogExample}'s content aligns its visible left edge with the
+ * example's `ListHeader` label (which sits 16px in — 8px title + 8px label):
+ * - `'glyph'` — a bare glyph/text specimen with no inline geometry insets the full 16px.
+ * - `'inline-control'` — a control that already carries ~8px of its own inline padding insets 8px so its content lands on the same line.
+ * - `'none'` — a content-item / composition that owns its geometry and already aligns; no inset (default).
+ */
+type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
+type CatalogExampleRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-catalog-example'?: never;
+    'data-catalog-example-stack'?: never;
+    'data-catalog-example-label'?: never;
+    'data-catalog-example-note'?: never;
+    'data-align'?: never;
+}>;
+type CatalogExampleStackRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-catalog-example'?: never;
+    'data-catalog-example-stack'?: never;
+    'data-catalog-example-label'?: never;
+    'data-catalog-example-note'?: never;
+    'data-align'?: never;
+}>;
+interface CatalogExampleProps {
+    /** The example's label, shown as a `ListHeader` above the specimen. Omit for a bare specimen. */
+    label?: string;
+    /** Optional explanatory note between the label and the specimen. */
+    note?: SafeHtml | string;
+    /** Alignment inset for the specimen — see {@link CatalogExampleAlign}. Default `'none'`. */
+    align?: CatalogExampleAlign;
+    /** Safe authoring `data-*` metadata for the rendered section. Helper-owned structural attributes remain protected. */
+    rootAttributes?: CatalogExampleRootAttributes;
+    className?: string;
+    children?: SafeHtml | readonly SafeHtml[];
+}
+/**
+ * One labeled example in a catalog preview: a `ListHeader` label, an optional
+ * note, and the specimen. `align` insets the specimen so its visible left edge
+ * lines up with the label text, encoding the catalog's alignment rules as a
+ * first-class prop instead of per-demo CSS. The inset is published as the
+ * `--kui-catalog-example-align` custom property so a debug overlay can exclude it
+ * from a specimen's measured margin.
+ */
+declare function CatalogExample({ label, note, align, rootAttributes, className, children, }: CatalogExampleProps): SafeHtml;
+interface CatalogExampleStackProps {
+    /** Accessible label for the stack region. */
+    label?: string;
+    /** Safe authoring `data-*` metadata for the rendered stack. Helper-owned structural attributes remain protected. */
+    rootAttributes?: CatalogExampleStackRootAttributes;
+    className?: string;
+    children?: SafeHtml | readonly SafeHtml[];
+}
+/**
+ * A vertically-stacked group of {@link CatalogExample}s with the catalog's
+ * example rhythm. The semantic `section` becomes a named `region` when `label`
+ * is supplied; an unlabeled stack remains an ordinary grouping.
+ */
+declare function CatalogExampleStack({ label, rootAttributes, className, children, }: CatalogExampleStackProps): SafeHtml;
+
+export { Catalog, type CatalogBrand, type CatalogEntry, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, type CatalogProps, type CatalogRelated, type CatalogResource, type CatalogSecondaryGroup, type CatalogSection };