@kerfjs/ui 5.0.0-beta.18 → 5.0.0-beta.22

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

@@ -0,0 +1,246 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-catalog-v2.schema.json",
+  "title": "Kerf UI composition catalog v2",
+  "type": "object",
+  "required": ["schemaVersion", "package", "compatibility", "entries"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 2 },
+    "package": { "type": "string", "minLength": 1 },
+    "compatibility": {
+      "type": "object",
+      "required": ["v1Catalog", "identity"],
+      "properties": {
+        "v1Catalog": { "type": "string", "minLength": 1 },
+        "identity": { "const": "package:id" }
+      },
+      "additionalProperties": false
+    },
+    "entries": { "type": "array", "items": { "$ref": "#/$defs/entry" } }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "cardinality": {
+      "type": "object",
+      "required": ["min", "max"],
+      "properties": {
+        "min": { "type": "integer", "minimum": 0 },
+        "max": {
+          "anyOf": [
+            { "type": "integer", "minimum": 1 },
+            { "const": "unbounded" }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "zone": {
+      "type": "object",
+      "required": ["id", "accepts", "cardinality", "exclusiveWith"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "accepts": { "$ref": "#/$defs/stringList" },
+        "cardinality": { "$ref": "#/$defs/cardinality" },
+        "exclusiveWith": { "$ref": "#/$defs/stringList" }
+      },
+      "additionalProperties": false
+    },
+    "state": {
+      "type": "object",
+      "required": ["id", "owner", "required"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "owner": { "enum": ["application", "controlled", "component"] },
+        "required": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "diagnostic": {
+      "type": "object",
+      "required": ["id", "severity", "when", "message"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^KUI-C[0-9]{3}$" },
+        "severity": { "enum": ["error", "warning"] },
+        "when": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "entry": {
+      "type": "object",
+      "required": [
+        "key",
+        "package",
+        "id",
+        "name",
+        "kind",
+        "source",
+        "parents",
+        "contexts",
+        "zones",
+        "children",
+        "state",
+        "wiring",
+        "responsive",
+        "layout",
+        "accessibility",
+        "boundaries",
+        "diagnostics",
+        "provenance"
+      ],
+      "properties": {
+        "key": { "type": "string", "minLength": 3 },
+        "package": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["component", "composition", "recipe"] },
+        "purpose": { "type": "string", "minLength": 1 },
+        "publicExports": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "subpath"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "subpath": { "type": "string", "pattern": "^\\." }
+            },
+            "additionalProperties": false
+          },
+          "minItems": 1
+        },
+        "sourceLinks": { "$ref": "#/$defs/stringList" },
+        "source": { "type": "string", "minLength": 1 },
+        "parents": {
+          "type": "object",
+          "required": ["mode", "entries"],
+          "properties": {
+            "mode": { "enum": ["any", "root", "listed"] },
+            "entries": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "contexts": { "$ref": "#/$defs/stringList" },
+        "zones": { "type": "array", "items": { "$ref": "#/$defs/zone" } },
+        "children": {
+          "type": "object",
+          "required": ["mode", "concepts", "requiredConcepts"],
+          "properties": {
+            "mode": { "enum": ["any", "none", "listed"] },
+            "concepts": { "$ref": "#/$defs/stringList" },
+            "requiredConcepts": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "state": { "type": "array", "items": { "$ref": "#/$defs/state" } },
+        "wiring": {
+          "type": "object",
+          "required": ["required", "helpers", "obligations"],
+          "properties": {
+            "required": { "type": "boolean" },
+            "helpers": { "$ref": "#/$defs/stringList" },
+            "obligations": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "responsive": {
+          "type": "object",
+          "required": ["owner", "behaviors"],
+          "properties": {
+            "owner": {
+              "enum": ["application", "component", "shared", "not-applicable"]
+            },
+            "behaviors": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "layout": {
+          "type": "object",
+          "required": ["roles", "geometry"],
+          "properties": {
+            "roles": { "$ref": "#/$defs/stringList" },
+            "geometry": {
+              "type": "object",
+              "required": ["margin", "border", "padding"],
+              "properties": {
+                "margin": {
+                  "enum": [
+                    "self",
+                    "parent",
+                    "child",
+                    "none",
+                    "conditional",
+                    "composed"
+                  ]
+                },
+                "border": {
+                  "enum": [
+                    "self",
+                    "parent",
+                    "child",
+                    "none",
+                    "conditional",
+                    "composed"
+                  ]
+                },
+                "padding": {
+                  "enum": [
+                    "self",
+                    "parent",
+                    "child",
+                    "none",
+                    "conditional",
+                    "composed"
+                  ]
+                },
+                "notes": { "$ref": "#/$defs/stringList" }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        },
+        "accessibility": {
+          "type": "object",
+          "required": ["obligations"],
+          "properties": { "obligations": { "$ref": "#/$defs/stringList" } },
+          "additionalProperties": false
+        },
+        "boundaries": {
+          "type": "object",
+          "required": ["rootClass", "publicClasses", "publicTokens"],
+          "properties": {
+            "rootClass": {
+              "oneOf": [
+                { "type": "string", "minLength": 1 },
+                { "type": "null" }
+              ]
+            },
+            "publicClasses": { "$ref": "#/$defs/stringList" },
+            "publicTokens": { "$ref": "#/$defs/stringList" }
+          },
+          "additionalProperties": false
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/diagnostic" }
+        },
+        "provenance": {
+          "type": "object",
+          "required": ["selection", "composition"],
+          "properties": {
+            "selection": { "type": "string", "minLength": 1 },
+            "composition": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/ai/component-catalog.json

@@ -303,10 +303,6 @@
         "kui-content-item--pill",
         "kui-control-cluster",
         "kui-inline-metadata",
-        "kui-pane",
-        "kui-pane__content",
-        "kui-pane__footer",
-        "kui-pane__toolbar",
         "kui-scroll-owner"
       ],
       "publicTokens": [
@@ -325,6 +321,155 @@
         "recipe": "docs/layout.md#public-roles-and-tokens"
       }
     },
+    {
+      "id": "pane",
+      "name": "Pane",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "An unpadded application column with optional vertical header/footer slots, one scrolling vertical content stack, and independent logical-edge separators.",
+      "uses": [],
+      "purpose": "Organize a sidebar, main area, inspector, or dialog column into fixed vertical header/footer chrome around one scrolling content owner.",
+      "publicExports": [
+        "Pane"
+      ],
+      "useWhen": [
+        "An application column needs shared header, content, and optional footer organization with exactly one scrolling content owner.",
+        "A pane boundary needs an opt-in separator on any combination of logical sides."
+      ],
+      "avoidWhen": [
+        "Do not use Pane as a padded card or add a competing scroll owner around its content slot.",
+        "Do not enable separators merely as decoration; use them only where the pane owns a real boundary."
+      ],
+      "alternatives": [
+        {
+          "id": "layout",
+          "relationship": "composes-with",
+          "when": "Use the layout content-item and control classes inside Pane when children need shared geometry."
+        }
+      ],
+      "appOwns": [
+        "root and content semantics",
+        "accessible labels",
+        "header, content, and footer children",
+        "which logical boundaries show separators",
+        "responsive placement and visibility"
+      ],
+      "variants": [
+        "content only",
+        "header + content",
+        "header + content + footer",
+        "block-start separator",
+        "block-end separator",
+        "inline-start separator",
+        "inline-end separator"
+      ],
+      "accessibility": [
+        "Choose semantic root and content elements that match the region and provide labels for landmark elements.",
+        "Keep fixed header/footer chrome outside the single scrolling content slot so reading and focus order remain coherent."
+      ],
+      "geometry": {
+        "margin": "child",
+        "border": "conditional",
+        "padding": "child",
+        "notes": [
+          "The pane is unpadded; separators are independently opt-in on logical edges and default off."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/pane",
+        "manualCssImport": "@kerfjs/ui/pane.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-pane",
+        "kui-pane__content",
+        "kui-pane__footer",
+        "kui-pane__header",
+        "kui-pane__toolbar"
+      ],
+      "publicTokens": [
+        "--kui-pane-separator-color",
+        "--kui-pane-separator-width"
+      ],
+      "links": {
+        "catalogRoute": "?component=pane",
+        "documentation": "docs/component-selection.md",
+        "recipe": "docs/layout.md#anatomy"
+      }
+    },
+    {
+      "id": "sunken-panel",
+      "name": "SunkenPanel",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A lowered application surface with one compact inset and a vertical content stack.",
+      "uses": [],
+      "purpose": "Group a vertical list of application content on a visually lowered surface with one owned 8px inset.",
+      "publicExports": [
+        "SunkenPanel"
+      ],
+      "useWhen": [
+        "A main content region or nested work area needs a darker/lowered background and one compact inset around a vertical stack."
+      ],
+      "avoidWhen": [
+        "Do not use it merely to add padding, as a substitute for Pane anatomy, or around children that already own the same outer surface."
+      ],
+      "alternatives": [
+        {
+          "id": "layout",
+          "relationship": "composes-with",
+          "when": "Use layout roles for pane, toolbar, scroll, and ordinary content-stack ownership."
+        }
+      ],
+      "appOwns": [
+        "region semantics and accessible name",
+        "scroll ownership",
+        "child ordering and content"
+      ],
+      "variants": [
+        "unnamed surface",
+        "named region"
+      ],
+      "accessibility": [
+        "Pass ariaLabel only when the surface is a distinct named region; otherwise it remains a non-landmark grouping."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "self",
+        "notes": [
+          "The root owns one 8px inset and vertical gap; children own their borders and internal geometry."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/sunken-panel",
+        "manualCssImport": "@kerfjs/ui/sunken-panel.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-sunken-panel"
+      ],
+      "publicTokens": [
+        "--kui-sunken-panel-background",
+        "--kui-sunken-panel-foreground",
+        "--kui-sunken-panel-gap",
+        "--kui-sunken-panel-padding",
+        "--kui-sunken-panel-radius"
+      ],
+      "links": {
+        "catalogRoute": "?component=sunken-panel",
+        "documentation": "docs/sunken-panel.md",
+        "recipe": "docs/sunken-panel.md#ownership"
+      }
+    },
     {
       "id": "toolbar",
       "name": "Toolbar",
@@ -894,8 +1039,7 @@
       "wiring": [],
       "publicClasses": [
         "kui-content",
-        "kui-content-item",
-        "kui-pane"
+        "kui-content-item"
       ],
       "publicTokens": [
         "--kui-layout-content-gap",