@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/ai/component-composition-rules.json

@@ -0,0 +1,570 @@
+{
+  "@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:text": {
+    "_source": "docs/disclosure.md#embedded-in-a-content-item",
+    "insetFreeWhen": [
+      { "prop": "flush", "equals": true },
+      { "prop": "variant", "equals": "span" }
+    ]
+  },
+  "@kerfjs/ui:disclosure": {
+    "_source": "docs/disclosure.md#embedded-in-a-content-item",
+    "insetFreeChildren": [{ "prop": "appearance", "equals": "embedded" }]
+  },
+  "@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": ["tab-bar-item"],
+      "requiredConcepts": ["tab-bar-item"]
+    },
+    "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", "button", "wa-button"],
+        "cardinality": { "min": 0, "max": 1 },
+        "exclusiveWith": []
+      },
+      {
+        "id": "end",
+        "jsx": { "prop": "end" },
+        "accepts": ["toolbar-control-group", "button", "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:message-composer": {
+    "_source": "docs/accessibility.md#messagecomposer",
+    "contexts": ["chat-composer", "dialog-floating-footer"],
+    "zones": [
+      {
+        "id": "leading",
+        "jsx": { "prop": "leading" },
+        "accepts": ["KerfUiContent"],
+        "cardinality": { "min": 0, "max": "unbounded" },
+        "exclusiveWith": []
+      },
+      {
+        "id": "trailing",
+        "jsx": { "prop": "trailing" },
+        "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:search-field": {
+    "_source": "docs/accessibility.md#searchfield",
+    "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": ["wireSearchFields"],
+      "obligations": [
+        "Retain and invoke the disposer.",
+        "Use readSearchField for DOM-owned text.",
+        "With a managed model, read model.state.peek() (never model.state.value) in the host render and bind model.result as a signal hole; the field itself re-renders only when model.structure changes, not per keystroke."
+      ]
+    },
+    "diagnostics": [
+      {
+        "id": "KUI-C105",
+        "severity": "error",
+        "when": "wireSearchFields is absent",
+        "message": "SearchField 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."
+      }
+    ]
+  }
+}