@adia-ai/adia-ui-forge 0.8.59 → 0.8.60

package/skills/primitive-authoring/references/yaml-contract.md

@@ -89,13 +89,26 @@ check) is unaffected either way — it only checks for a slot literally named
 ## `a2ui.allowedParents:` / `a2ui.allowedChildren:` — composition constraints (SPEC REQ-011, gh#1353)
 
 Optional keys inside the `a2ui:` block, alongside `rules:`. Each is a
-non-empty list of catalog `component:` names (NOT tags) naming the direct
-parents this component may sit under / the direct children it may contain.
-The reserved name `Surface` (the A2UI v1.0 implicit root container) is legal
+non-empty list of catalog `component:` names (NOT tags) naming the parents
+this component may sit under / the direct children it may contain. The
+reserved name `Surface` (the A2UI v1.0 implicit root container) is legal
 only in `allowedParents` and means "may sit at the surface root". **Omitted
 means unconstrained** — never write an empty list (that would mean "allowed
 nowhere"; the build refuses it).
 
+`allowedParents` matches the nearest custom-element ancestor, not the
+immediate DOM parent (gh#3310): the generated lint rule's
+`compositionFindings()` walks up past native (non-hyphenated) wrapper
+elements — `section`, `div`, `td`, `tr`, `tbody`, and any other plain HTML
+tag — until it finds a real catalog component tag or reaches the surface
+root. This mirrors Light DOM's own composition reality (AGENTS.md: CSS
+positions by tag + ancestor + DOM order) — a wrapper interposed for layout
+or semantics (a `<section>` inside a card, a `<td>` in a table body) doesn't
+change a component's logical host. `allowedChildren`, by contrast, still
+matches DIRECT children only — a named-slot child that should be exempt
+from the default-slot list is a separate, open gap (gh#3308), not addressed
+by this semantics change.
+
 ```yaml
 a2ui:
   allowedParents:
@@ -112,6 +125,35 @@ children). A parent that adopts items through wrappers (menu.class.js's
 deliberate descendant query) must NOT constrain — a declared constraint
 stricter than the source is a defect, not documentation.
 
+**`allowedChildren` is a default-slot-only check (gh#3308).** A direct
+child carrying ANY `slot=` attribute is a sibling-level named slot, not a
+default-slot member — the lint-side matcher (`compositionFindings`)
+exempts it from `allowedChildren` entirely, regardless of the slot's name.
+This is why menu-ui can declare `allowedChildren: [MenuItem, MenuDivider,
+MenuLabel]` for its default slot while still accepting an arbitrary
+focusable element on `slot="trigger"` ("typically button-ui, but any
+focusable element works") without a false positive. When a named slot
+*should* be constrained too (rare — most named slots exist precisely
+because their content varies), add an `allowedChildrenBySlot:` map
+alongside `allowedChildren:`, keyed by slot name, same catalog-name-list
+shape:
+
+```yaml
+a2ui:
+  allowedChildren:
+    - MenuItem
+    - MenuDivider
+    - MenuLabel
+  allowedChildrenBySlot:
+    trigger:               # only if the trigger slot ITSELF needs constraining
+      - ButtonUI
+```
+
+A slot with no entry in `allowedChildrenBySlot` (or the key omitted
+entirely) stays unconstrained by design — this is the common case, and
+matches "omitted means unconstrained" for `allowedChildren`/`allowedParents`
+above.
+
 Pipeline: `components.mjs` validates the shape per-yaml, cross-checks every
 referenced name against the full catalog on a full build, and forwards the
 lists onto `x-adiaui` → `catalog-a2ui_1_0.json`.
@@ -122,16 +164,71 @@ per gh#2116) across the five opt-out-scoped catalogs (`adia.core.json`,
 `adia.shells.json`, gh#2211/ADR-0093), where the vendored `@genui/core`
 validator enforces them (`UNALLOWED_PARENT`/`UNALLOWED_CHILD`). Module-tier
 yamls (web-modules) now carry a v1.0 sidecar too and land in `adia.shells`.
-
-Once a component earns a `component.md` (both `screenReader:` and
-`behavioral:` authored, gh#2615), a non-empty `allowedParents`/
-`allowedChildren` also generates an enforced lint rule (LLD-0016 §C4,
-gh#2647): `scripts/build/gen-composition-rules.mjs` emits `scripts/lint/
+`allowedChildrenBySlot` (gh#3308) is NOT part of this catalog/sidecar
+pipeline — `components.mjs` never reads it, it never lands in
+`x-adiaui`/`catalog-a2ui_1_0.json`, and the A2UI v1.0 protocol validator
+never enforces it. It exists purely for the lint-side check below.
+
+A non-empty `allowedParents`/`allowedChildren`/`allowedChildrenBySlot`
+generates an enforced lint rule (LLD-0016 §C4, gh#2647):
+`scripts/build/gen-composition-rules.mjs` emits `scripts/lint/
 rules/generated/composition/<name>.mjs`, which flags a markup file where
-the tag nests under (or contains) a non-declared tag. Advisory (`warn`)
+the tag nests under (or contains) a non-declared tag — `allowedChildren`
+checked against default-slot children only, `allowedChildrenBySlot`
+against the matching named-slot children (see above). Advisory (`warn`)
 until a corpus-wide rollout promotes it (`npm run build:composition-rules`
 / `check:composition-rules-fresh`).
 
+### `a2ui.noCompositionConstraint:`: the audited "no contract needed" verdict (lld-0029 C2a, PR #3456)
+
+The third disposition a yaml can carry. Where `allowedParents` /
+`allowedChildren` declare a containment edge, `noCompositionConstraint`
+records that the authoring-rule audit above was actually run (read
+`<name>.class.js` for `querySelector` / `closest` / `this.children`
+child-tag expectations, then test any parent/child hypothesis against real
+markup in `apps/`, `site/`, `catalog/`, `packages/web-components/patterns/`)
+and found no constraint worth declaring. Its whole purpose is to let a
+reader, or a gate, tell "audited, categorically needs none" apart from
+"never audited". Do not write it as a shortcut: if the audit turns up a
+real constraint, the fix is a genuine `allowedParents` / `allowedChildren`
+addition, not this marker.
+
+Shape (`scripts/schemas/component.yaml.schema.json`, `a2ui.noCompositionConstraint`):
+an object with two required keys and nothing else. `reason` is the verdict
+quoted from the disposition table (schema `minLength: 8`); `ticket` is the
+issue whose table recorded it (`^gh#[0-9]+$`). As with every other schema
+constraint (ADR-0057), the shape is IDE-visible only: `compileComponent()`
+never reads this key, so a malformed block does not stop the build.
+
+Real example, `packages/web-components/components/badge/badge.yaml`:
+
+```yaml
+a2ui:
+  noCompositionConstraint:
+    reason: 'Referenced generically from a dozen+ unrelated components, not scoped to one parent; own rule says positioning, not ancestry.'
+    ticket: 'gh#3270'
+  rules:
+    - 'Use for small status/count labels attached to another element (notification counts, status pills, version tags).'
+```
+
+Relationship to the two lists. A yaml carries either the marker or a
+containment list, never both. This is now enforced (gh#3497), not just
+convention: `component.yaml.schema.json` declares the two mutually
+exclusive via the `a2ui` object's own `not` clause, and
+`compileCompositionConstraints()` in `scripts/build/components.mjs` throws
+at build time, naming the file and the offending field, when a yaml
+declares both. `npm run check:components-valid` (part of `npm run
+build:components`) is where that throw surfaces.
+
+Pipeline: none. The marker is a yaml-only annotation with no sidecar,
+`x-adiaui`, catalog, or generated-lint-rule forwarding (lld-0029 C2a, by
+design), so a PR that only adds it changes no derived artifact and commits
+no regen. The planned `check:composition-coverage` gate (lld-0029 C3,
+`scripts/verify/check-composition-coverage.mjs`, not landed as of
+2026-09-04) fails any yaml whose `a2ui` block has none of `allowedParents`,
+`allowedChildren`, or `noCompositionConstraint`, so the marker counts as
+coverage exactly as either list does.
+
 ---
 
 ## `examples:` field — a2ui example ids (semantic-id grammar, gh#2492)