create-kerf-component 5.0.0-beta.50 → 5.0.0-beta.51

package/README.md

@@ -47,6 +47,13 @@ A ready-to-publish component package that encodes the rules from the kerf docs
   string/template/regular-expression literals cannot masquerade as public
   exports. The scaffold already declares TypeScript; run `npm install` before
   invoking its copied local checker in a fresh offline directory.
+  A component whose wiring helper writes runtime `data-*` state onto its DOM
+  can declare it under `composition.wiring.stateAttributes` — each item is
+  `{ name, on, helper, meaning }`, where `name` is a `data-*` name, `on` is the
+  element that carries it, and `helper` is one of `wiring.helpers`. Apps must
+  not render, remove, or treat those attributes as their own state. The field
+  is optional; names must be unique per component, and the checker rejects a
+  helper that is not listed in `wiring.helpers`.
 
 ## Layout produced
 

package/catalog.js

@@ -400,6 +400,32 @@ function validateComposition(component, at, diagnostics) {
     `${at}.composition.wiring.obligations`,
     diagnostics,
   );
+  const stateAttributes = composition.wiring?.stateAttributes;
+  if (stateAttributes !== undefined && !Array.isArray(stateAttributes))
+    diagnostics.push(
+      `${at}.composition.wiring.stateAttributes: expected an array`,
+    );
+  const stateAttributeNames = new Set();
+  for (const attribute of Array.isArray(stateAttributes)
+    ? stateAttributes
+    : []) {
+    const name = attribute?.name;
+    const attributeAt = `${at}.composition.wiring.stateAttributes.${name}`;
+    if (typeof name !== 'string' || !/^data-[a-z0-9]+(-[a-z0-9]+)*$/.test(name))
+      diagnostics.push(`${attributeAt}.name: expected a data-* attribute name`);
+    if (stateAttributeNames.has(name))
+      diagnostics.push(`${attributeAt}.name: declared more than once`);
+    stateAttributeNames.add(name);
+    for (const field of ['on', 'meaning'])
+      if (typeof attribute?.[field] !== 'string' || !attribute[field])
+        diagnostics.push(
+          `${attributeAt}.${field}: expected a non-empty string`,
+        );
+    if (!composition.wiring.helpers?.includes(attribute?.helper))
+      diagnostics.push(
+        `${attributeAt}.helper: ${attribute?.helper} is not listed in composition.wiring.helpers`,
+      );
+  }
   if (
     !['application', 'component', 'shared', 'not-applicable'].includes(
       composition.responsive?.owner,

package/component-catalog-v2.schema.json

@@ -21,6 +21,33 @@
   },
   "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 },
@@ -152,7 +179,12 @@
           "properties": {
             "required": { "type": "boolean" },
             "helpers": { "$ref": "#/$defs/stringList" },
-            "obligations": { "$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
         },

package/component-metadata.schema.json

@@ -15,6 +15,33 @@
   },
   "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 },
@@ -185,7 +212,12 @@
           "properties": {
             "required": { "type": "boolean" },
             "helpers": { "$ref": "#/$defs/stringList" },
-            "obligations": { "$ref": "#/$defs/stringList" }
+            "obligations": { "$ref": "#/$defs/stringList" },
+            "stateAttributes": {
+              "description": "Optional 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.",
+              "type": "array",
+              "items": { "$ref": "#/$defs/stateAttribute" }
+            }
           },
           "additionalProperties": false
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kerf-component",
-  "version": "5.0.0-beta.50",
+  "version": "5.0.0-beta.51",
   "description": "Scaffold a publishable kerf component package that already follows kerf's hard packaging rules.",
   "type": "module",
   "license": "MIT",

package/template/package.json

@@ -36,7 +36,7 @@
     "kerfjs": "^5.0.0-0"
   },
   "devDependencies": {
-    "kerfjs": "^5.0.0-beta.50",
+    "kerfjs": "^5.0.0-beta.51",
     "tsup": "^8",
     "typescript": "^5 || ^6"
   }