@kerfjs/ui 5.0.0-beta.4 → 5.0.0-beta.41

package/ai/component-catalog-v2-overrides.json

@@ -0,0 +1,496 @@
+{
+  "@kerfjs/ui:toolbar": {
+    "_source": "docs/component-selection.md#toolbar-composition",
+    "contexts": [
+      "application-chrome",
+      "page-header",
+      "panel-header",
+      "dialog-header"
+    ],
+    "zones": [
+      {
+        "id": "leading",
+        "jsx": { "prop": "leading" },
+        "accepts": ["toolbar-text", "toolbar-control-group"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "center",
+        "jsx": { "prop": "center" },
+        "accepts": ["toolbar-text", "toolbar-control-group"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing",
+        "jsx": { "prop": "trailing" },
+        "accepts": ["toolbar-text", "toolbar-control-group"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ],
+    "children": {
+      "mode": "listed",
+      "concepts": ["toolbar-text", "toolbar-control-group"],
+      "requiredConcepts": []
+    },
+    "diagnostics": [
+      {
+        "id": "KUI-C101",
+        "severity": "error",
+        "when": "a direct zone child is neither ToolbarText nor ToolbarControlGroup",
+        "message": "Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup are direct zone children."
+      }
+    ]
+  },
+  "@kerfjs/ui:pane": {
+    "_source": "docs/layout.md#anatomy",
+    "contexts": [
+      "application-column",
+      "sidebar",
+      "main-content",
+      "inspector",
+      "dialog-column"
+    ],
+    "zones": [
+      {
+        "id": "header",
+        "jsx": { "prop": "header" },
+        "accepts": ["fixed-chrome"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "content",
+        "jsx": { "prop": "children" },
+        "accepts": ["pane-content"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "footer",
+        "jsx": { "prop": "footer" },
+        "accepts": ["fixed-chrome"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:toolbar-control-group": {
+    "_source": "docs/component-selection.md#toolbar-composition",
+    "parents": {
+      "mode": "listed",
+      "entries": ["@kerfjs/ui:toolbar"]
+    },
+    "contexts": ["toolbar-zone"],
+    "zones": [
+      {
+        "id": "controls",
+        "accepts": ["control"],
+        "cardinality": { "min": 1, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ],
+    "children": {
+      "mode": "listed",
+      "concepts": ["control"],
+      "requiredConcepts": ["control"]
+    }
+  },
+  "@kerfjs/ui:row": {
+    "_source": "docs/layout.md#row-and-list-alignment",
+    "contexts": ["application-ui", "horizontal-layout"],
+    "children": {
+      "mode": "any",
+      "concepts": [],
+      "requiredConcepts": []
+    },
+    "zones": []
+  },
+  "@kerfjs/ui:list": {
+    "_source": "docs/component-selection.md#problem-to-component-matrix",
+    "contexts": ["application-ui", "navigation-list", "vertical-layout"],
+    "children": {
+      "mode": "any",
+      "concepts": [],
+      "requiredConcepts": []
+    },
+    "zones": []
+  },
+  "@kerfjs/ui:list-header": {
+    "_source": "docs/accessibility.md#shared-rules",
+    "contexts": ["navigation-list"],
+    "state": [{ "id": "expanded", "owner": "controlled", "required": false }],
+    "accessibility": {
+      "obligations": [
+        "When toggle mode is used, the application reveals matching content and keeps expanded state synchronized.",
+        "The owning control retains a stable accessible name."
+      ]
+    },
+    "diagnostics": [
+      {
+        "id": "KUI-C103",
+        "severity": "error",
+        "when": "toggle mode does not reveal matching controlled content",
+        "message": "ListHeader expanded state must match real revealed content."
+      }
+    ]
+  },
+  "@kerfjs/ui:tab-bar": {
+    "_source": "docs/accessibility.md#tabs",
+    "contexts": ["tabpanel-navigation"],
+    "children": {
+      "mode": "listed",
+      "concepts": ["app-tab"],
+      "requiredConcepts": ["app-tab"]
+    },
+    "zones": [
+      {
+        "id": "tabs",
+        "jsx": { "prop": "children" },
+        "accepts": ["tabs"],
+        "cardinality": { "min": 1, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "leading",
+        "jsx": { "prop": "leading" },
+        "accepts": ["toolbar-control-group"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing",
+        "jsx": { "prop": "trailing" },
+        "accepts": ["toolbar-control-group"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ],
+    "state": [
+      { "id": "selected-tab", "owner": "controlled", "required": true }
+    ],
+    "wiring": {
+      "required": true,
+      "helpers": ["wireTabBars"],
+      "obligations": [
+        "Retain and invoke the disposer.",
+        "Apply onReorder to application-owned order."
+      ]
+    },
+    "accessibility": {
+      "obligations": [
+        "Each tab controls a matching tabpanel.",
+        "Selection and focus behavior follow the configured activation mode."
+      ]
+    },
+    "diagnostics": [
+      {
+        "id": "KUI-C104",
+        "severity": "error",
+        "when": "wireTabBars is absent",
+        "message": "TabBar requires wireTabBars for keyboard and reorder behavior."
+      }
+    ]
+  },
+  "@kerfjs/ui:tabs": {
+    "_source": "docs/accessibility.md#tabs",
+    "parents": {
+      "mode": "listed",
+      "entries": ["@kerfjs/ui:tab-bar"]
+    },
+    "contexts": ["tabpanel-navigation"],
+    "zones": [
+      {
+        "id": "leading-decoration",
+        "jsx": { "prop": "leading" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing-decoration",
+        "jsx": { "prop": "trailing" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "close-icon",
+        "jsx": { "prop": "closeIcon" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:segmented-control": {
+    "_source": "docs/accessibility.md#segmentedcontrol",
+    "contexts": ["compact-exclusive-choice"],
+    "state": [{ "id": "value", "owner": "controlled", "required": true }],
+    "accessibility": {
+      "obligations": [
+        "Every enabled choice remains in sequential tab order.",
+        "Every choice has a meaningful label."
+      ]
+    }
+  },
+  "@kerfjs/ui:token-search-field": {
+    "_source": "docs/accessibility.md#tokensearchfield",
+    "contexts": ["structured-search-editor"],
+    "zones": [
+      {
+        "id": "leading-decoration",
+        "jsx": { "prop": "leading" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing-control",
+        "jsx": { "prop": "trailing" },
+        "accepts": ["control"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ],
+    "state": [
+      { "id": "tokens", "owner": "controlled", "required": true },
+      { "id": "text", "owner": "component", "required": true },
+      { "id": "expanded", "owner": "controlled", "required": false }
+    ],
+    "wiring": {
+      "required": true,
+      "helpers": ["wireTokenSearchFields"],
+      "obligations": [
+        "Retain and invoke the disposer.",
+        "Use readTokenSearchField for DOM-owned text."
+      ]
+    },
+    "diagnostics": [
+      {
+        "id": "KUI-C105",
+        "severity": "error",
+        "when": "wireTokenSearchFields is absent",
+        "message": "TokenSearchField requires its public wiring helper for keyboard and collapsible behavior."
+      }
+    ]
+  },
+  "@kerfjs/ui:state-banner": {
+    "_source": "docs/component-selection.md#problem-to-component-matrix",
+    "contexts": ["persistent-status", "recoverable-error"],
+    "zones": [
+      {
+        "id": "icon",
+        "jsx": { "prop": "icon" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "action",
+        "jsx": { "prop": "action" },
+        "accepts": ["control"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:empty-state": {
+    "_source": "docs/component-selection.md#problem-to-component-matrix",
+    "contexts": ["empty-content", "busy-content"],
+    "zones": [
+      {
+        "id": "icon",
+        "jsx": { "prop": "icon" },
+        "accepts": ["dormant-decoration"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "action",
+        "jsx": { "prop": "action" },
+        "accepts": ["control"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:split-view": {
+    "_source": "docs/split-view.md#split-view-list-detail",
+    "contexts": ["list-detail", "responsive-master-detail"],
+    "zones": [
+      {
+        "id": "list",
+        "jsx": { "prop": "list" },
+        "accepts": ["list-region"],
+        "cardinality": { "min": 1, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "detail",
+        "jsx": { "prop": "detail" },
+        "accepts": ["detail-region"],
+        "cardinality": { "min": 1, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:workbench": {
+    "_source": "docs/workbench.md#workbench",
+    "contexts": ["desktop-application-shell"],
+    "zones": [
+      {
+        "id": "main",
+        "jsx": { "prop": "main" },
+        "accepts": ["workspace-region"],
+        "cardinality": { "min": 1, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "left-rail",
+        "accepts": ["panel-region"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "right-rail",
+        "accepts": ["panel-region"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "bottom-drawer",
+        "accepts": ["panel-region"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:resize": {
+    "_source": "docs/accessibility.md#resizableregion",
+    "contexts": ["adjustable-pane-boundary"],
+    "state": [{ "id": "size", "owner": "controlled", "required": true }],
+    "wiring": {
+      "required": true,
+      "helpers": ["wireResizableRegions"],
+      "obligations": [
+        "Retain and invoke the disposer.",
+        "Persist committed size in the application when persistence is required."
+      ]
+    },
+    "diagnostics": [
+      {
+        "id": "KUI-C106",
+        "severity": "error",
+        "when": "wireResizableRegions is absent",
+        "message": "ResizableRegion requires wireResizableRegions for pointer and keyboard operation."
+      }
+    ]
+  },
+  "@kerfjs/ui:select": {
+    "_source": "README.md#web-awesome-theme",
+    "contexts": ["controlled-value-selection"],
+    "state": [{ "id": "value", "owner": "controlled", "required": true }],
+    "wiring": {
+      "required": true,
+      "helpers": ["@kerfjs/ui/select/register"],
+      "obligations": ["Import the registration module once in the application."]
+    },
+    "diagnostics": [
+      {
+        "id": "KUI-C107",
+        "severity": "error",
+        "when": "the registration import is absent",
+        "message": "Select requires @kerfjs/ui/select/register once per application."
+      }
+    ]
+  },
+  "@kerfjs/ui:wa-accordion": {
+    "_source": "docs/webawesome-theme.md#coverage",
+    "children": {
+      "mode": "listed",
+      "concepts": ["wa-accordion-item"],
+      "requiredConcepts": ["wa-accordion-item"]
+    },
+    "zones": [
+      {
+        "id": "items",
+        "accepts": ["wa-accordion-item"],
+        "cardinality": { "min": 1, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:wa-dialog": {
+    "_source": "docs/webawesome-theme.md#coverage",
+    "boundaries": {
+      "rootClass": null,
+      "publicClasses": ["hide-actions"],
+      "publicTokens": []
+    }
+  },
+  "@kerfjs/ui:wa-radio-group": {
+    "_source": "docs/webawesome-theme.md#coverage",
+    "children": {
+      "mode": "listed",
+      "concepts": ["wa-radio"],
+      "requiredConcepts": ["wa-radio"]
+    },
+    "zones": [
+      {
+        "id": "options",
+        "accepts": ["wa-radio"],
+        "cardinality": { "min": 1, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:wa-select": {
+    "_source": "docs/webawesome-theme.md#coverage",
+    "children": {
+      "mode": "listed",
+      "concepts": ["wa-option"],
+      "requiredConcepts": ["wa-option"]
+    },
+    "zones": [
+      {
+        "id": "options",
+        "accepts": ["wa-option"],
+        "cardinality": { "min": 1, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ]
+  },
+  "@kerfjs/ui:wa-tab-group": {
+    "_source": "docs/webawesome-theme.md#coverage",
+    "children": {
+      "mode": "listed",
+      "concepts": ["wa-tab", "wa-tab-panel"],
+      "requiredConcepts": ["wa-tab", "wa-tab-panel"]
+    },
+    "zones": [
+      {
+        "id": "tabs",
+        "accepts": ["wa-tab"],
+        "cardinality": { "min": 1, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "panels",
+        "accepts": ["wa-tab-panel"],
+        "cardinality": { "min": 1, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ],
+    "diagnostics": [
+      {
+        "id": "KUI-C108",
+        "severity": "error",
+        "when": "tab and panel name sets differ",
+        "message": "Every wa-tab must identify a matching wa-tab-panel and vice versa."
+      }
+    ]
+  }
+}

package/ai/component-catalog-v2.d.ts

@@ -0,0 +1,90 @@
+export type CatalogQualifiedKey = `${string}:${string}`;
+export type CatalogCardinality = {
+  min: number;
+  max: number | 'unbounded';
+};
+export type CatalogDiagnostic = {
+  id: `KUI-C${number}`;
+  severity: 'error' | 'warning';
+  when: string;
+  message: string;
+};
+export type CatalogCssValueProp = {
+  path: string;
+  grammar:
+    | 'length'
+    | 'size'
+    | 'flex'
+    | 'color'
+    | 'declarations'
+    | 'media-query'
+    | 'pixels';
+  helpers: string[];
+  nonStandaloneHelpers?: string[];
+  shorthands: string[];
+  canonicalShorthands: string[];
+  exceptionalShorthands: string[];
+  rawPolicy: 'forbid' | 'allow' | 'unsafe-only';
+  unsafeHelper?: string;
+  examples: string[];
+};
+export interface CatalogCompositionEntryV2 {
+  key: CatalogQualifiedKey;
+  package: string;
+  id: string;
+  name: string;
+  kind: 'component' | 'composition' | 'recipe';
+  purpose?: string;
+  publicExports?: Array<{ name: string; subpath: string }>;
+  sourceLinks?: string[];
+  source: string;
+  parents: { mode: 'any' | 'root' | 'listed'; entries: CatalogQualifiedKey[] };
+  contexts: string[];
+  zones: Array<{
+    id: string;
+    /** Static JSX binding when this zone is supplied by a public prop. */
+    jsx?: { prop: string };
+    accepts: string[];
+    cardinality: CatalogCardinality;
+    exclusiveWith: string[];
+  }>;
+  children: {
+    mode: 'any' | 'none' | 'listed';
+    concepts: string[];
+    requiredConcepts: string[];
+  };
+  state: Array<{
+    id: string;
+    owner: 'application' | 'controlled' | 'component';
+    required: boolean;
+  }>;
+  wiring: { required: boolean; helpers: string[]; obligations: string[] };
+  responsive: {
+    owner: 'application' | 'component' | 'shared' | 'not-applicable';
+    behaviors: string[];
+  };
+  layout: {
+    roles: string[];
+    geometry: Record<
+      'margin' | 'border' | 'padding',
+      'self' | 'parent' | 'child' | 'none' | 'conditional' | 'composed'
+    > & { notes?: string[] };
+  };
+  accessibility: { obligations: string[] };
+  boundaries: {
+    rootClass: string | null;
+    publicClasses: string[];
+    publicTokens: string[];
+    publicParts?: string[];
+  };
+  cssValueProps?: CatalogCssValueProp[];
+  diagnostics: CatalogDiagnostic[];
+  provenance: { selection: string; composition: string };
+}
+export interface ComponentCatalogV2 {
+  $schema?: string;
+  schemaVersion: 2;
+  package: string;
+  compatibility: { v1Catalog: string; identity: 'package:id' };
+  entries: CatalogCompositionEntryV2[];
+}