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

package/ai/component-composition.schema.json

@@ -0,0 +1,444 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-composition.schema.json",
+  "title": "Kerf UI composition catalog",
+  "type": "object",
+  "required": ["schemaVersion", "package", "compatibility", "entries"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": {
+      "const": 1,
+      "description": "Version of the composition catalog format itself, independent of component-catalog.json's own schemaVersion."
+    },
+    "package": { "type": "string", "minLength": 1 },
+    "compatibility": {
+      "type": "object",
+      "required": ["componentCatalog", "identity"],
+      "properties": {
+        "componentCatalog": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Relative path to the component (selection) catalog this composition layer describes, or \"not-applicable\" when the package publishes none."
+        },
+        "identity": { "const": "package:id" }
+      },
+      "additionalProperties": false
+    },
+    "entries": { "type": "array", "items": { "$ref": "#/$defs/entry" } }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "stateAttribute": {
+      "type": "object",
+      "required": ["name", "on", "helper", "meaning"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^data-[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "on": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The element that carries it: a public class, or the element passed to the helper."
+        },
+        "helper": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The helper, one of wiring.helpers, that writes it."
+        },
+        "meaning": {
+          "type": "string",
+          "minLength": 1,
+          "description": "What its presence or value means."
+        }
+      },
+      "additionalProperties": false
+    },
+    "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 },
+        "jsx": {
+          "type": "object",
+          "required": ["prop"],
+          "properties": {
+            "prop": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        },
+        "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": {
+          "description": "Each export's name and the package.json#exports subpath that serves it. An entry from a private application omits subpath: the application is bundled, never imported by package name, so the name resolves through the entry's source file.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "subpath": { "type": "string", "pattern": "^\\." }
+            },
+            "additionalProperties": false
+          },
+          "minItems": 1
+        },
+        "sourceLinks": { "$ref": "#/$defs/stringList" },
+        "source": { "type": "string", "minLength": 1 },
+        "styleSources": {
+          "description": "Stylesheets owned by this component, relative to the catalog package root. Required for an entry to own its CSS in opt-in component ownership mode when no selection catalog supplies it.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*\\.css$"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "insetFreeChildren": {
+          "description": "Prop values under which the entry's direct JSX children must bring no content-item inset. While any condition holds, a child whose layout.geometry owns its margin, border, and padding (self on all three) double-insets the entry's own geometry unless one of the child's insetFreeWhen conditions holds; eslint-plugin-kerfjs reports it as KUI-L204.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/propCondition" },
+          "minItems": 1
+        },
+        "insetFreeWhen": {
+          "description": "Prop values that render this inset-bearing entry with no margin, border, or padding of its own (Text flush). Any one condition makes the element inset-free.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/propCondition" },
+          "minItems": 1
+        },
+        "rendersAs": {
+          "description": "For a wrapper component: the cataloged roots it renders (package-qualified keys), any one of them or nothing. Composition checks treat an element of this entry as each declared root: a zone accepts it only if it accepts every root, and each root's parent contract applies to where it is placed.",
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[^:]+:[^:]+$" },
+          "uniqueItems": true
+        },
+        "jsxExports": {
+          "description": "Placement contracts for additional JSX exports from one selection entry. These exports do not stand for the entry's root or its zones.",
+          "type": "object",
+          "propertyNames": { "pattern": "^[A-Z][A-Za-z0-9]*$" },
+          "additionalProperties": {
+            "type": "object",
+            "required": ["parents"],
+            "properties": {
+              "parents": {
+                "type": "object",
+                "required": ["mode", "entries"],
+                "properties": {
+                  "mode": { "enum": ["any", "root", "listed"] },
+                  "entries": { "$ref": "#/$defs/stringList" }
+                },
+                "additionalProperties": false
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "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" },
+            "scope": { "enum": ["application", "module"] },
+            "helpers": { "$ref": "#/$defs/stringList" },
+            "sources": {
+              "description": "Application-owned helper exports and their defining source files, relative to the catalog package root.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["export", "source"],
+                "properties": {
+                  "export": { "type": "string", "minLength": 1 },
+                  "source": { "type": "string", "minLength": 1 }
+                },
+                "additionalProperties": false
+              }
+            },
+            "actions": {
+              "description": "data-action values the application must handle with a root-delegated listener (delegate or delegateActions) instead of a named helper. Required wiring names at least one helper or action.",
+              "$ref": "#/$defs/stringList"
+            },
+            "obligations": { "$ref": "#/$defs/stringList" },
+            "stateAttributes": {
+              "description": "Wiring-owned state attributes: data-* attributes a wiring helper writes at runtime, which the application must not render, remove, or treat as its own state. Optional for extension catalogs; first-party entries always list it, empty when their helpers write none.",
+              "type": "array",
+              "items": { "$ref": "#/$defs/stateAttribute" }
+            }
+          },
+          "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
+        },
+        "cssValueProps": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/cssValueProp" }
+        },
+        "boundaries": {
+          "type": "object",
+          "required": ["rootClass", "publicClasses", "publicTokens"],
+          "properties": {
+            "rootClass": {
+              "oneOf": [
+                { "type": "string", "minLength": 1 },
+                { "type": "null" }
+              ]
+            },
+            "publicClasses": { "$ref": "#/$defs/stringList" },
+            "placeableClasses": {
+              "$ref": "#/$defs/stringList",
+              "description": "The subset of publicClasses an application may place on its own elements. Absent means none: every public class is the component's rendered anatomy, reached by rendering the component."
+            },
+            "rootElement": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+              "description": "The intrinsic element the component renders at its root. It identifies composed child roots for ownership checks; a placeableClasses class on a plain element of this tag recreates the component, while the class stays placeable on another carrier."
+            },
+            "descendantElements": {
+              "$ref": "#/$defs/stringList",
+              "description": "Intrinsic element tags that can appear below the component root."
+            },
+            "descendantRootAttribute": {
+              "type": "string",
+              "pattern": "^data-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+              "description": "Root data attribute anchoring ownership of arbitrary unclassed descendants."
+            },
+            "publicTokens": { "$ref": "#/$defs/stringList" },
+            "publicParts": { "$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
+    },
+    "propCondition": {
+      "type": "object",
+      "required": ["prop", "equals"],
+      "properties": {
+        "prop": {
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9]*$",
+          "description": "A JSX prop of the element."
+        },
+        "equals": {
+          "anyOf": [
+            { "type": "string" },
+            { "type": "number" },
+            { "type": "boolean" }
+          ],
+          "description": "The statically written value that satisfies the condition. A bare boolean prop (<Text flush />) equals true."
+        }
+      },
+      "additionalProperties": false
+    },
+    "cssValueProp": {
+      "type": "object",
+      "required": [
+        "path",
+        "grammar",
+        "helpers",
+        "shorthands",
+        "canonicalShorthands",
+        "exceptionalShorthands",
+        "rawPolicy",
+        "examples"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "pattern": "^(?:[A-Za-z][A-Za-z0-9]*(?:\\[\\])?\\.)*[A-Za-z][A-Za-z0-9]*$"
+        },
+        "grammar": {
+          "enum": [
+            "length",
+            "size",
+            "flex",
+            "color",
+            "declarations",
+            "media-query",
+            "pixels"
+          ]
+        },
+        "helpers": { "$ref": "#/$defs/stringList" },
+        "nonStandaloneHelpers": { "$ref": "#/$defs/stringList" },
+        "shorthands": { "$ref": "#/$defs/stringList" },
+        "canonicalShorthands": { "$ref": "#/$defs/stringList" },
+        "exceptionalShorthands": { "$ref": "#/$defs/stringList" },
+        "rawPolicy": { "enum": ["forbid", "allow", "unsafe-only"] },
+        "unsafeHelper": { "type": "string", "minLength": 1 },
+        "examples": { "$ref": "#/$defs/stringList" }
+      },
+      "additionalProperties": false
+    }
+  }
+}