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

package/ai/component-composition-rules.json

@@ -0,0 +1,551 @@
+{
+  "@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": ["KerfUiContent"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "center",
+        "jsx": { "prop": "center" },
+        "accepts": ["KerfUiContent"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing",
+        "jsx": { "prop": "trailing" },
+        "accepts": ["KerfUiContent"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ],
+    "children": {
+      "mode": "any",
+      "concepts": [],
+      "requiredConcepts": []
+    }
+  },
+  "@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",
+    "jsxExports": {
+      "ToolbarActionLink": {
+        "parents": {
+          "mode": "listed",
+          "entries": ["@kerfjs/ui:toolbar-control-group"]
+        }
+      }
+    },
+    "parents": {
+      "mode": "listed",
+      "entries": [
+        "@kerfjs/ui:toolbar",
+        "@kerfjs/ui:floating-toolbar",
+        "@kerfjs/ui:tab-bar"
+      ]
+    },
+    "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", "wa-button"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "end",
+        "jsx": { "prop": "end" },
+        "accepts": ["toolbar-control-group", "wa-button"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      }
+    ],
+    "state": [
+      { "id": "selected-tab", "owner": "controlled", "required": true }
+    ],
+    "wiring": {
+      "required": true,
+      "helpers": ["wireTabBars", "wireScrollDividers"],
+      "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:choice-chips": {
+    "_source": "docs/accessibility.md#choicechips",
+    "contexts": ["wrapping-exclusive-choice", "wrapping-multiple-choice"],
+    "state": [{ "id": "value", "owner": "controlled", "required": false }],
+    "accessibility": {
+      "obligations": [
+        "Name the radio group (or, with multiple, the checkbox group) with label or with labelledBy pointing at a visible heading.",
+        "Every choice keeps a visible text label; a swatch or icon is decorative."
+      ]
+    }
+  },
+  "@kerfjs/ui:composer": {
+    "_source": "docs/accessibility.md#composer",
+    "contexts": ["chat-composer", "dialog-floating-footer"],
+    "zones": [
+      {
+        "id": "actions",
+        "jsx": { "prop": "actions" },
+        "accepts": ["KerfUiContent"],
+        "cardinality": { "min": 1, "max": "unbounded" },
+        "exclusiveWith": []
+      }
+    ],
+    "state": [{ "id": "value", "owner": "controlled", "required": false }],
+    "accessibility": {
+      "obligations": [
+        "Name the message field with label in title style; give it an id so a hint becomes its accessible description.",
+        "Give every trailing action a visible or accessible name, such as a Send button."
+      ]
+    }
+  },
+  "@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"],
+      "placeableClasses": ["hide-actions"],
+      "publicTokens": []
+    }
+  },
+  "@kerfjs/ui:wa-badge": {
+    "_source": "docs/webawesome-theme.md#badge-and-tag-guidance",
+    "boundaries": {
+      "rootClass": null,
+      "publicClasses": [],
+      "publicTokens": [
+        "--kui-wa-badge-accent-foreground",
+        "--kui-wa-badge-filled-background",
+        "--kui-wa-badge-filled-foreground"
+      ]
+    }
+  },
+  "@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-composition.d.ts

@@ -0,0 +1,132 @@
+export type CatalogQualifiedKey = `${string}:${string}`;
+/** A `data-*` attribute a wiring helper writes at runtime. The application
+ *  must not render, remove, or treat it as its own state. */
+export interface CatalogStateAttribute {
+  name: `data-${string}`;
+  /** The element that carries it: a public class, or the element passed to the helper. */
+  on: string;
+  /** The helper, one of `wiring.helpers`, that writes it. */
+  helper: string;
+  /** What its presence or value means. */
+  meaning: 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 CatalogCompositionEntry {
+  key: CatalogQualifiedKey;
+  package: string;
+  id: string;
+  name: string;
+  kind: 'component' | 'composition' | 'recipe';
+  purpose?: string;
+  publicExports?: Array<{ name: string; subpath: string }>;
+  sourceLinks?: string[];
+  source: string;
+  /** For a wrapper component: the cataloged roots it renders (any one of
+   *  them, or nothing). Composition checks treat its elements as each root. */
+  rendersAs?: CatalogQualifiedKey[];
+  /** Additional JSX exports in this selection entry with their own placement. */
+  jsxExports?: Record<
+    string,
+    {
+      parents: {
+        mode: 'any' | 'root' | 'listed';
+        entries: CatalogQualifiedKey[];
+      };
+    }
+  >;
+  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[];
+    /** Defining source files for application-owned helpers, relative to the catalog package root. */
+    sources?: Array<{ export: string; source: string }>;
+    /** `data-action` values the application handles with a root-delegated
+     *  listener (`delegate` / `delegateActions`) instead of a named helper. */
+    actions?: string[];
+    obligations: string[];
+    /** Wiring-owned `data-*` attributes a helper writes at runtime. Optional
+     *  for extension catalogs; first-party entries always list it. */
+    stateAttributes?: CatalogStateAttribute[];
+  };
+  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[];
+    /** Public classes an application may place on its own elements; absent means none. */
+    placeableClasses?: string[];
+    /** The intrinsic element the component renders at its root; a placeable class on a plain element of this tag recreates the component. */
+    rootElement?: string;
+    descendantElements?: string[];
+    descendantRootAttribute?: string;
+    publicTokens: string[];
+    publicParts?: string[];
+  };
+  cssValueProps?: CatalogCssValueProp[];
+  diagnostics: CatalogDiagnostic[];
+  provenance: { selection: string; composition: string };
+}
+export interface ComponentComposition {
+  $schema?: string;
+  schemaVersion: 1;
+  package: string;
+  compatibility: { componentCatalog: string; identity: 'package:id' };
+  entries: CatalogCompositionEntry[];
+}