@kerfjs/ui 5.0.0-beta.8 → 5.0.0-beta.80

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

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/application-ui-profile.schema.json",
+  "title": "Kerf application UI profile",
+  "type": "object",
+  "required": ["schemaVersion", "scope"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "scope": { "enum": ["package", "workspace", "directory"] },
+    "catalogs": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/catalog" },
+      "uniqueItems": true
+    },
+    "preferences": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
+      "additionalProperties": { "$ref": "#/$defs/preference" }
+    },
+    "theme": { "$ref": "#/$defs/theme" },
+    "tokens": {
+      "type": "object",
+      "propertyNames": { "pattern": "^--kui-[a-z0-9-]+$" },
+      "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" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "stringList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "catalogLocation": {
+      "type": "object",
+      "required": ["path", "schemaVersion"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "schemaVersion": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "catalog": {
+      "type": "object",
+      "required": ["package", "composition"],
+      "properties": {
+        "package": { "type": "string", "minLength": 1 },
+        "selection": { "$ref": "#/$defs/catalogLocation" },
+        "composition": { "$ref": "#/$defs/catalogLocation" }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "required": ["package"],
+            "properties": { "package": { "const": "@kerfjs/ui" } }
+          },
+          "then": { "required": ["selection"] }
+        }
+      ]
+    },
+    "preference": {
+      "type": "object",
+      "required": ["preferred"],
+      "properties": {
+        "preferred": { "type": "string", "pattern": "^.+:.+$" },
+        "avoid": { "$ref": "#/$defs/stringList" },
+        "rationale": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "theme": {
+      "type": "object",
+      "properties": {
+        "colorScheme": { "enum": ["light", "dark", "invert", "system"] },
+        "allowedColorSchemes": {
+          "type": "array",
+          "items": { "enum": ["light", "dark", "invert", "system"] },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "density": { "enum": ["standard", "compact"] },
+        "allowedDensities": {
+          "type": "array",
+          "items": { "enum": ["standard", "compact"] },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "layout": {
+      "type": "object",
+      "properties": {
+        "shell": { "type": "string", "pattern": "^.+:.+$" },
+        "pane": { "type": "string", "pattern": "^.+:.+$" },
+        "responsiveStrategy": {
+          "enum": ["device-class", "container", "application"]
+        },
+        "compactNavigation": {
+          "enum": ["nav-stack", "tab-scaffold", "application"]
+        },
+        "scrollOwnership": { "enum": ["one-per-pane", "application"] },
+        "spacingScale": { "enum": ["kerf-five-step", "application"] }
+      },
+      "additionalProperties": false
+    },
+    "exception": {
+      "type": "object",
+      "required": ["id", "rules", "target", "rationale"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "rules": { "$ref": "#/$defs/stringList" },
+        "target": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))(?!.*[?*]).+"
+        },
+        "rationale": { "type": "string", "minLength": 12 }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/ai/catalog-authoring.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "./catalog-authoring.schema.json",
+  "schemaVersion": 2,
+  "package": "@kerfjs/ui",
+  "scope": "catalog-demo-authoring",
+  "authoritativeGuide": "docs/catalog.md#catalog-demo-authoring-contract",
+  "apiSignatures": "ai/public-api-signatures-v1.md#kerfjsuicatalog",
+  "imports": {
+    "layout": "@kerfjs/ui/catalog",
+    "wiring": "@kerfjs/ui/wire-catalog"
+  },
+  "helpers": [
+    "Catalog",
+    "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"
+  }
+}

package/ai/catalog-authoring.schema.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/catalog-authoring.schema.json",
+  "title": "Kerf UI Catalog authoring discovery",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "package",
+    "scope",
+    "authoritativeGuide",
+    "apiSignatures",
+    "imports",
+    "helpers",
+    "taxonomy",
+    "metadata"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 2 },
+    "package": { "const": "@kerfjs/ui" },
+    "scope": { "const": "catalog-demo-authoring" },
+    "authoritativeGuide": { "type": "string", "minLength": 1 },
+    "apiSignatures": { "type": "string", "minLength": 1 },
+    "imports": {
+      "type": "object",
+      "required": ["layout", "wiring"],
+      "properties": {
+        "layout": { "const": "@kerfjs/ui/catalog" },
+        "wiring": { "const": "@kerfjs/ui/wire-catalog" }
+      },
+      "additionalProperties": false
+    },
+    "helpers": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "Catalog",
+          "CatalogExample",
+          "CatalogExampleStack",
+          "wireCatalog",
+          "wireCatalogGeometryOverlay",
+          "revealCatalogEntry"
+        ]
+      },
+      "minItems": 6,
+      "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"],
+      "properties": {
+        "slot": { "const": "rootAttributes" },
+        "demo": { "const": "data-demo" },
+        "geometryOverlaySkip": {
+          "const": "data-catalog-geometry-overlay-skip"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,149 @@
+{
+  "$schema": "./compile-time-contracts-v1.schema.json",
+  "schemaVersion": 1,
+  "package": "@kerfjs/ui",
+  "fixture": "tests/consumer-types/contracts/consumer.ts",
+  "contracts": [
+    {
+      "id": "KUI-T001",
+      "catalogKey": "@kerfjs/ui:list-header",
+      "publicImport": "@kerfjs/ui/list-header",
+      "symbols": ["ListHeaderProps"],
+      "kind": "discriminated-union",
+      "summary": "ListHeader passive, trailing-action, and disclosure modes require only the inputs their rendered behavior uses."
+    },
+    {
+      "id": "KUI-T002",
+      "catalogKey": "@kerfjs/ui:select",
+      "publicImport": "@kerfjs/ui/select",
+      "symbols": ["SelectProps"],
+      "kind": "accessible-name",
+      "summary": "Select requires either a visible label or an explicit ARIA label."
+    },
+    {
+      "id": "KUI-T003",
+      "catalogKey": "@kerfjs/ui:select",
+      "publicImport": "@kerfjs/ui/select",
+      "symbols": ["SelectChoice", "SelectProps"],
+      "kind": "literal-identity",
+      "summary": "Literal Select values are constrained to the declared choice values; dynamic integrations may widen the generic to string."
+    },
+    {
+      "id": "KUI-T004",
+      "catalogKey": "@kerfjs/ui:segmented-control",
+      "publicImport": "@kerfjs/ui/segmented-control",
+      "symbols": ["SegmentedControlChoice", "SegmentedControlProps"],
+      "kind": "literal-identity",
+      "summary": "Literal SegmentedControl values are constrained to the declared choice values; dynamic integrations may widen the generic to string."
+    },
+    {
+      "id": "KUI-T005",
+      "catalogKey": "@kerfjs/ui:token-search-field",
+      "publicImport": "@kerfjs/ui/token-search-field",
+      "symbols": ["TokenSearchFieldProps"],
+      "kind": "discriminated-union",
+      "summary": "Expanded state and expand-action inputs exist only for collapsible TokenSearchField variants."
+    },
+    {
+      "id": "KUI-T006",
+      "catalogKey": "@kerfjs/ui:token-search-field",
+      "publicImport": "@kerfjs/ui/token-search-field",
+      "symbols": ["TokenSearchEditorAttributes"],
+      "kind": "protected-attributes",
+      "summary": "TokenSearchField editor metadata cannot replace component-owned identity, morph, count, or placeholder attributes."
+    },
+    {
+      "id": "KUI-T007",
+      "catalogKey": "@kerfjs/ui:toolbar-text",
+      "publicImport": "@kerfjs/ui/toolbar-text",
+      "symbols": ["ToolbarTextProps"],
+      "kind": "conditional-property",
+      "summary": "ToolbarText maxLines is accepted only when wrapping is enabled."
+    },
+    {
+      "id": "KUI-T008",
+      "publicImport": "@kerfjs/ui/tab-navigator",
+      "symbols": ["TabNavigatorTab", "TabNavigatorProps"],
+      "kind": "literal-identity",
+      "summary": "Literal TabNavigator active ids are constrained to the declared tab ids; dynamic integrations may widen the generic to string."
+    },
+    {
+      "id": "KUI-T009",
+      "catalogKey": "@kerfjs/ui:token-search-field",
+      "publicImport": "@kerfjs/ui/wire-token-search-fields",
+      "symbols": ["TokenSearchKeyboardOptions", "WireTokenSearchFieldsOptions"],
+      "kind": "controlled-callback",
+      "summary": "Adjacent-token removal requires the callback that commits removal to application-owned state."
+    },
+    {
+      "id": "KUI-T010",
+      "publicImport": "@kerfjs/ui",
+      "symbols": [
+        "Sides",
+        "StateBannerUrgency",
+        "TabActivation",
+        "TextVariant",
+        "ToolbarControlGroupAppearance",
+        "ToolbarControlGroupButtonAppearance",
+        "ToolbarControlGroupShape",
+        "ToolbarControlGroupTone"
+      ],
+      "kind": "finite-vocabulary",
+      "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

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/compile-time-contracts-v1.schema.json",
+  "title": "Kerf UI compile-time contracts",
+  "type": "object",
+  "required": ["schemaVersion", "package", "fixture", "contracts"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "package": { "const": "@kerfjs/ui" },
+    "fixture": { "type": "string", "minLength": 1 },
+    "contracts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "publicImport", "symbols", "kind", "summary"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^KUI-T[0-9]{3}$" },
+          "catalogKey": { "type": "string", "minLength": 1 },
+          "publicImport": {
+            "type": "string",
+            "pattern": "^@kerfjs/ui(?:/[-a-z]+)?$"
+          },
+          "symbols": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "kind": {
+            "enum": [
+              "accessible-name",
+              "conditional-property",
+              "controlled-callback",
+              "discriminated-union",
+              "finite-vocabulary",
+              "explicit-native-attribute",
+              "literal-identity",
+              "property-specific-css-value",
+              "protected-attributes",
+              "recursive-semantic-content"
+            ]
+          },
+          "summary": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-catalog-extension.schema.json",
+  "title": "Kerf UI consumer component catalog extension",
+  "type": "object",
+  "required": ["schemaVersion", "package", "description", "entries"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "package": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/entry" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "required": [
+        "id",
+        "name",
+        "kind",
+        "purpose",
+        "useWhen",
+        "avoidWhen",
+        "geometry"
+      ],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["component", "composition"] },
+        "purpose": { "type": "string", "minLength": 1 },
+        "useWhen": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "avoidWhen": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "publicClasses": {
+          "type": "array",
+          "items": { "type": "string" },
+          "uniqueItems": true
+        },
+        "publicTokens": {
+          "type": "array",
+          "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 }
+      },
+      "additionalProperties": false
+    },
+    "geometry": {
+      "type": "object",
+      "required": ["margin", "border", "padding"],
+      "properties": {
+        "margin": { "$ref": "#/$defs/geometryOwner" },
+        "border": { "$ref": "#/$defs/geometryOwner" },
+        "padding": { "$ref": "#/$defs/geometryOwner" },
+        "notes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "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._-]+)*$"
+    }
+  }
+}