@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/ai/application-ui-diagnostic-ids-v1.json

@@ -29,6 +29,10 @@
     "KUI-D010",
     "KUI-D011",
     "KUI-D020",
+    "KUI-D030",
+    "KUI-D031",
+    "KUI-D032",
+    "KUI-D040",
     "KUI-L001",
     "KUI-L002",
     "KUI-L003",
@@ -38,9 +42,23 @@
     "KUI-L007",
     "KUI-L008",
     "KUI-L009",
+    "KUI-L010",
+    "KUI-L011",
+    "KUI-L012",
+    "KUI-L013",
+    "KUI-L014",
+    "KUI-L015",
+    "KUI-L016",
+    "KUI-L017",
+    "KUI-L018",
+    "KUI-L019",
+    "KUI-L020",
+    "KUI-L021",
+    "KUI-L022",
     "KUI-L090",
     "KUI-L101",
     "KUI-L102",
+    "KUI-L103",
     "KUI-L201",
     "KUI-L202",
     "KUI-L203",
@@ -88,5 +106,9 @@
     "KUI-T009",
     "KUI-T010",
     "KUI-T011"
-  ]
+  ],
+  "retired": {
+    "KUI-C101": "Toolbar zones accept KerfUiContent directly; grouping is a recommended presentation choice, not a composition requirement. Kept in ids so existing profile exceptions still load.",
+    "KUI-L005": "Folded into KUI-L019: any application rule whose subject is a cataloged component, forced dimensions included. Kept in ids so existing profile exceptions that name it still load."
+  }
 }

package/ai/application-ui-profile-sync.cjs

@@ -28,7 +28,7 @@ function mergeApplicationUiProfiles(layers) {
       catalogs.set(catalog.package, catalog);
       provenance[`$catalogs.${catalog.package}`] = source;
     }
-    for (const field of ['preferences', 'theme', 'tokens', 'layout'])
+    for (const field of ['preferences', 'theme', 'tokens', 'layout', 'wiring'])
       if (
         layer[field] &&
         typeof layer[field] === 'object' &&
@@ -166,6 +166,7 @@ function validateApplicationUiProfile(profile, options = {}) {
       'theme',
       'tokens',
       'layout',
+      'wiring',
       'exceptions',
     ],
     '$',
@@ -183,7 +184,25 @@ function validateApplicationUiProfile(profile, options = {}) {
   const theme = objectAt(profile.theme, '$.theme');
   const tokens = objectAt(profile.tokens, '$.tokens') ?? {};
   const layout = objectAt(profile.layout, '$.layout');
+  const wiring = objectAt(profile.wiring, '$.wiring');
   const exceptions = arrayAt(profile.exceptions, '$.exceptions');
+  rejectUnknown(wiring, ['entries'], '$.wiring');
+  if (wiring?.entries !== undefined) {
+    if (
+      !stringList(wiring.entries) ||
+      wiring.entries.some(
+        (entry) =>
+          isAbsolute(entry) ||
+          entry.split('/').includes('..') ||
+          /[*?]/.test(entry),
+      )
+    )
+      add(
+        'KUI-P030',
+        '$.wiring.entries',
+        'Wiring entries must be unique workspace-relative paths without traversal or wildcards.',
+      );
+  }
   const packages = new Set();
   for (const [index, catalog] of catalogs.entries()) {
     const path = `$.catalogs[${index}]`;
@@ -202,7 +221,7 @@ function validateApplicationUiProfile(profile, options = {}) {
       add(
         'KUI-P005',
         `${path}.selection`,
-        'The @kerfjs/ui catalog requires its v1 selection location.',
+        'The @kerfjs/ui catalog requires its component-catalog.json selection location.',
       );
     for (const kind of ['selection', 'composition']) {
       if (kind === 'selection' && !catalog[kind]) continue;

package/ai/application-ui-profile.d.ts

@@ -39,6 +39,10 @@ export interface ApplicationUiProfile {
     scrollOwnership?: 'one-per-pane' | 'application';
     spacingScale?: 'kerf-five-step' | 'application';
   };
+  wiring?: {
+    /** Static application entry modules, relative to the workspace root. */
+    entries?: string[];
+  };
   exceptions?: Array<{
     id: string;
     rules: string[];

package/ai/application-ui-profile.defaults.json

@@ -5,22 +5,77 @@
   "catalogs": [
     {
       "package": "@kerfjs/ui",
-      "selection": { "path": "./component-catalog.json", "schemaVersion": 1 },
+      "selection": {
+        "path": "./component-catalog.json",
+        "schemaVersion": 1
+      },
       "composition": {
-        "path": "./component-catalog-v2.json",
-        "schemaVersion": 2
+        "path": "./component-composition.json",
+        "schemaVersion": 1
       }
     }
   ],
   "preferences": {
-    "application-shell": { "preferred": "@kerfjs/ui:recipe-app-shell" },
+    "application-shell": {
+      "preferred": "@kerfjs/ui:recipe-app-shell"
+    },
+    "application-tabs": {
+      "preferred": "@kerfjs/ui:tab-bar",
+      "avoid": [
+        "@kerfjs/ui:wa-tab-group",
+        "@kerfjs/ui:wa-tab",
+        "@kerfjs/ui:wa-tab-panel"
+      ],
+      "rationale": "Render TabBar (or SegmentedControl for a view switch) instead of composing Web Awesome tabs directly."
+    },
+    "command-menu": {
+      "preferred": "@kerfjs/ui:popup-menu",
+      "avoid": ["@kerfjs/ui:wa-dropdown", "@kerfjs/ui:wa-dropdown-item"],
+      "rationale": "Render PopupMenu, which wraps wa-dropdown with the shared popup contract; use Select when choosing a value."
+    },
+    "embedded-media": {
+      "preferred": "@kerfjs/ui:content-item",
+      "avoid": [
+        "@kerfjs/ui:wa-animated-image",
+        "@kerfjs/ui:wa-comparison",
+        "@kerfjs/ui:wa-zoomable-frame"
+      ],
+      "rationale": "Keep media behavior application-owned: place a native img, video, or iframe in a ContentItem. Record a narrow KUI-L301 profile exception only when a concrete product requirement needs this Web Awesome element."
+    },
     "exclusive-choice": {
       "preferred": "@kerfjs/ui:segmented-control",
-      "avoid": ["@kerfjs/ui:wa-button-group"]
+      "avoid": ["@kerfjs/ui:wa-button-group"],
+      "rationale": "Render SegmentedControl for one-of-N choices instead of a Web Awesome button group."
+    },
+    "hierarchy-navigation": {
+      "preferred": "@kerfjs/ui:list",
+      "avoid": ["@kerfjs/ui:wa-tree", "@kerfjs/ui:wa-tree-item"],
+      "rationale": "Present hierarchy as List rows (or NavStack drill-in levels). Record a narrow KUI-L301 profile exception only when the product requires tree behavior."
+    },
+    "icon": {
+      "preferred": "@kerfjs/ui:lucide-icon",
+      "avoid": ["@kerfjs/ui:wa-icon"],
+      "rationale": "Render LucideIcon; Web Awesome icons are not part of the Kerf icon contract."
     },
-    "navigation-row": { "preferred": "@kerfjs/ui:list-item" },
-    "panel-heading": { "preferred": "@kerfjs/ui:panel-header" },
-    "structured-search": { "preferred": "@kerfjs/ui:token-search-field" }
+    "navigation-row": {
+      "preferred": "@kerfjs/ui:list-item"
+    },
+    "panel-heading": {
+      "preferred": "@kerfjs/ui:toolbar"
+    },
+    "resizable-pane": {
+      "preferred": "@kerfjs/ui:resize",
+      "avoid": ["@kerfjs/ui:wa-split-panel"],
+      "rationale": "Render ResizableRegion for application panes instead of a Web Awesome split panel."
+    },
+    "structured-search": {
+      "preferred": "@kerfjs/ui:token-search-field"
+    },
+    "value-selection": {
+      "preferred": "@kerfjs/ui:select",
+      "avoid": ["@kerfjs/ui:wa-select", "@kerfjs/ui:wa-option"],
+      "rationale": "Render Select, which wraps wa-select and wa-option with Kerf's popup and spacing contract."
+    }
   },
   "theme": {
     "colorScheme": "light",

package/ai/application-ui-profile.mjs

@@ -123,6 +123,14 @@ export function mergeApplicationUiProfiles(layers) {
       profile.layout = { ...profile.layout, ...layer.layout };
       recordProvenance(provenance, source, '$layout', layer.layout);
     }
+    if (
+      layer.wiring &&
+      typeof layer.wiring === 'object' &&
+      !Array.isArray(layer.wiring)
+    ) {
+      profile.wiring = { ...profile.wiring, ...layer.wiring };
+      recordProvenance(provenance, source, '$wiring', layer.wiring);
+    }
     for (const exception of Array.isArray(layer.exceptions)
       ? layer.exceptions
       : []) {
@@ -250,6 +258,7 @@ export function validateApplicationUiProfile(
       'theme',
       'tokens',
       'layout',
+      'wiring',
       'exceptions',
     ],
     '$',
@@ -269,7 +278,25 @@ export function validateApplicationUiProfile(
   const theme = objectAt(profile?.theme, '$.theme');
   const tokens = objectAt(profile?.tokens, '$.tokens') ?? {};
   const layout = objectAt(profile?.layout, '$.layout');
+  const wiring = objectAt(profile?.wiring, '$.wiring');
   const exceptions = arrayAt(profile?.exceptions, '$.exceptions');
+  rejectUnknown(wiring, ['entries'], '$.wiring');
+  if (wiring?.entries !== undefined) {
+    if (
+      !stringList(wiring.entries) ||
+      wiring.entries.some(
+        (entry) =>
+          isAbsolute(entry) ||
+          entry.split('/').includes('..') ||
+          /[*?]/.test(entry),
+      )
+    )
+      add(
+        'KUI-P030',
+        '$.wiring.entries',
+        'Wiring entries must be unique workspace-relative paths without traversal or wildcards.',
+      );
+  }
 
   const catalogPackages = new Set();
   for (const [index, catalog] of catalogs.entries()) {
@@ -289,7 +316,7 @@ export function validateApplicationUiProfile(
       add(
         'KUI-P005',
         `${path}.selection`,
-        'The @kerfjs/ui catalog requires its v1 selection location.',
+        'The @kerfjs/ui catalog requires its component-catalog.json selection location.',
       );
     for (const kind of ['selection', 'composition']) {
       if (kind === 'selection' && !catalog?.selection) continue;

package/ai/application-ui-profile.schema.json

@@ -25,6 +25,16 @@
       "additionalProperties": { "type": "string", "minLength": 1 }
     },
     "layout": { "$ref": "#/$defs/layout" },
+    "wiring": {
+      "type": "object",
+      "properties": {
+        "entries": {
+          "description": "Application entry modules, relative to the workspace root, where application-scoped wiring is installed.",
+          "$ref": "#/$defs/stringList"
+        }
+      },
+      "additionalProperties": false
+    },
     "exceptions": {
       "type": "array",
       "items": { "$ref": "#/$defs/exception" }

package/ai/catalog-authoring.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./catalog-authoring.schema.json",
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "package": "@kerfjs/ui",
   "scope": "catalog-demo-authoring",
   "authoritativeGuide": "docs/catalog.md#catalog-demo-authoring-contract",
@@ -14,12 +14,21 @@
     "CatalogExample",
     "CatalogExampleStack",
     "wireCatalog",
-    "wireCatalogGeometryOverlay",
     "revealCatalogEntry"
   ],
+  "taxonomy": {
+    "kinds": ["component", "composition", "recipe"],
+    "organization": {
+      "grouping": "functional-category",
+      "categoryOrder": "importance-descending",
+      "withinCategoryKindOrder": ["component", "composition"],
+      "withinKindOrder": ["importance-descending", "name-ascending"],
+      "recipes": "after-all-functional-groups"
+    },
+    "compositionTag": "Composition"
+  },
   "metadata": {
     "slot": "rootAttributes",
-    "demo": "data-demo",
-    "geometryOverlaySkip": "data-catalog-geometry-overlay-skip"
+    "demo": "data-demo"
   }
 }

package/ai/catalog-authoring.schema.json

@@ -11,11 +11,12 @@
     "apiSignatures",
     "imports",
     "helpers",
+    "taxonomy",
     "metadata"
   ],
   "properties": {
     "$schema": { "type": "string" },
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "package": { "const": "@kerfjs/ui" },
     "scope": { "const": "catalog-demo-authoring" },
     "authoritativeGuide": { "type": "string", "minLength": 1 },
@@ -37,22 +38,65 @@
           "CatalogExample",
           "CatalogExampleStack",
           "wireCatalog",
-          "wireCatalogGeometryOverlay",
           "revealCatalogEntry"
         ]
       },
-      "minItems": 6,
+      "minItems": 5,
       "uniqueItems": true
     },
+    "taxonomy": {
+      "type": "object",
+      "required": ["kinds", "organization", "compositionTag"],
+      "properties": {
+        "kinds": {
+          "type": "array",
+          "items": { "enum": ["component", "composition", "recipe"] },
+          "minItems": 3,
+          "maxItems": 3,
+          "uniqueItems": true
+        },
+        "organization": {
+          "type": "object",
+          "required": [
+            "grouping",
+            "categoryOrder",
+            "withinCategoryKindOrder",
+            "withinKindOrder",
+            "recipes"
+          ],
+          "properties": {
+            "grouping": { "const": "functional-category" },
+            "categoryOrder": { "const": "importance-descending" },
+            "withinCategoryKindOrder": {
+              "type": "array",
+              "items": { "enum": ["component", "composition"] },
+              "minItems": 2,
+              "maxItems": 2,
+              "uniqueItems": true
+            },
+            "withinKindOrder": {
+              "type": "array",
+              "items": {
+                "enum": ["importance-descending", "name-ascending"]
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "uniqueItems": true
+            },
+            "recipes": { "const": "after-all-functional-groups" }
+          },
+          "additionalProperties": false
+        },
+        "compositionTag": { "const": "Composition" }
+      },
+      "additionalProperties": false
+    },
     "metadata": {
       "type": "object",
-      "required": ["slot", "demo", "geometryOverlaySkip"],
+      "required": ["slot", "demo"],
       "properties": {
         "slot": { "const": "rootAttributes" },
-        "demo": { "const": "data-demo" },
-        "geometryOverlaySkip": {
-          "const": "data-catalog-geometry-overlay-skip"
-        }
+        "demo": { "const": "data-demo" }
       },
       "additionalProperties": false
     }

package/ai/compile-time-contracts-v1.json

@@ -54,14 +54,6 @@
     },
     {
       "id": "KUI-T007",
-      "catalogKey": "@kerfjs/ui:panel-header",
-      "publicImport": "@kerfjs/ui/panel-header",
-      "symbols": ["PanelHeaderProps"],
-      "kind": "conditional-property",
-      "summary": "PanelHeader summaryId cannot be supplied without rendered summary content."
-    },
-    {
-      "id": "KUI-T008",
       "catalogKey": "@kerfjs/ui:toolbar-text",
       "publicImport": "@kerfjs/ui/toolbar-text",
       "symbols": ["ToolbarTextProps"],
@@ -69,14 +61,14 @@
       "summary": "ToolbarText maxLines is accepted only when wrapping is enabled."
     },
     {
-      "id": "KUI-T009",
-      "publicImport": "@kerfjs/ui/tab-scaffold",
-      "symbols": ["TabScaffoldTab", "TabScaffoldProps"],
+      "id": "KUI-T008",
+      "publicImport": "@kerfjs/ui/tab-navigator",
+      "symbols": ["TabNavigatorTab", "TabNavigatorProps"],
       "kind": "literal-identity",
-      "summary": "Literal TabScaffold active ids are constrained to the declared tab ids; dynamic integrations may widen the generic to string."
+      "summary": "Literal TabNavigator active ids are constrained to the declared tab ids; dynamic integrations may widen the generic to string."
     },
     {
-      "id": "KUI-T010",
+      "id": "KUI-T009",
       "catalogKey": "@kerfjs/ui:token-search-field",
       "publicImport": "@kerfjs/ui/wire-token-search-fields",
       "symbols": ["TokenSearchKeyboardOptions", "WireTokenSearchFieldsOptions"],
@@ -84,19 +76,74 @@
       "summary": "Adjacent-token removal requires the callback that commits removal to application-owned state."
     },
     {
-      "id": "KUI-T011",
+      "id": "KUI-T010",
       "publicImport": "@kerfjs/ui",
       "symbols": [
-        "DividerSides",
+        "Sides",
         "StateBannerUrgency",
         "TabActivation",
+        "TextVariant",
         "ToolbarControlGroupAppearance",
         "ToolbarControlGroupButtonAppearance",
         "ToolbarControlGroupShape",
         "ToolbarControlGroupTone"
       ],
       "kind": "finite-vocabulary",
-      "summary": "Finite public variant vocabularies, including canonical divider-edge combinations, are named exported unions rather than anonymous string sets."
+      "summary": "Finite public variant vocabularies, including canonical edge combinations, are named exported unions rather than anonymous string sets."
+    },
+    {
+      "id": "KUI-T011",
+      "publicImport": "@kerfjs/ui",
+      "symbols": ["KerfUiContent"],
+      "kind": "recursive-semantic-content",
+      "summary": "Semantic UI content zones accept SafeHtml, runtime-empty boolean/nullish values, and readonly nested arrays while rejecting arbitrary strings, numbers, and signals."
+    },
+    {
+      "id": "KUI-T012",
+      "catalogKey": "@kerfjs/ui:list",
+      "publicImport": "@kerfjs/ui/css-values",
+      "symbols": [
+        "CssValue",
+        "CssLength",
+        "CssLengthExpression",
+        "UiSpaceName",
+        "space",
+        "plus",
+        "calc"
+      ],
+      "kind": "property-specific-css-value",
+      "summary": "List gap accepts finite spacing shorthands or branded complete length-percentage values, while raw CSS strings and non-standalone arithmetic expressions remain rejected."
+    },
+    {
+      "id": "KUI-T013",
+      "publicImport": "@kerfjs/ui/css-values",
+      "symbols": [
+        "CssFlex",
+        "CssSize",
+        "CssColor",
+        "CssForegroundColor",
+        "UiForegroundColorName",
+        "flex",
+        "uiColor",
+        "colorVar",
+        "foregroundColorVar"
+      ],
+      "kind": "property-specific-css-value",
+      "summary": "List flex, Skeleton dimensions, and Select icon colors use separate typed CSS grammars; Select icon colors accept only foreground colors, so fill aliases such as uiColor('success') and unqualified colorVar() values are rejected. Row declaration-string props are absent rather than sharing a generic CSS escape hatch."
+    },
+    {
+      "id": "KUI-T014",
+      "publicImport": "@kerfjs/ui",
+      "symbols": [
+        "BadgeProps",
+        "CatalogProps",
+        "CollapsiblePanelToggleProps",
+        "SelectProps",
+        "SkeletonProps",
+        "TextProps"
+      ],
+      "kind": "explicit-native-attribute",
+      "summary": "Stable single-root visual components accept an explicit native slot attribute; multi-root components and arbitrary native attribute spreading remain excluded."
     }
   ]
 }

package/ai/compile-time-contracts-v1.schema.json

@@ -35,8 +35,11 @@
               "controlled-callback",
               "discriminated-union",
               "finite-vocabulary",
+              "explicit-native-attribute",
               "literal-identity",
-              "protected-attributes"
+              "property-specific-css-value",
+              "protected-attributes",
+              "recursive-semantic-content"
             ]
           },
           "summary": { "type": "string", "minLength": 1 }

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

@@ -52,6 +52,26 @@
           "items": { "type": "string" },
           "uniqueItems": true
         },
+        "uses": {
+          "description": "Directly composed Kerf or consumer catalog entry ids.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "source": { "$ref": "#/$defs/repositoryPath" },
+        "styleSources": {
+          "description": "Stylesheets owned by this component, relative to the consumer package root. Used by Doctor's opt-in component ownership mode.",
+          "type": "array",
+          "items": {
+            "allOf": [
+              { "$ref": "#/$defs/repositoryPath" },
+              { "pattern": "\\.css$" }
+            ]
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "demoSource": { "$ref": "#/$defs/repositoryPath" },
         "geometry": { "$ref": "#/$defs/geometry" },
         "documentation": { "type": "string", "minLength": 1 }
       },
@@ -74,6 +94,11 @@
     },
     "geometryOwner": {
       "enum": ["self", "parent", "child", "none", "conditional"]
+    },
+    "repositoryPath": {
+      "description": "A repository-relative POSIX path without traversal or empty segments.",
+      "type": "string",
+      "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$"
     }
   }
 }