Rule 44 - JS: Spec contract for hooks, states, and events
A component's JavaScript exposes API surface beyond its twig + CSS:
the hooks consumers wire up, the states the JS toggles for
CSS to read, and the custom events it dispatches or subscribes
to. Rule 44 keeps those surfaces in lock-step with the
{name}.spec.js contract.
These surfaces are declared as facets of a behavioral capability,
not as standalone spec fields. A component either references a shared
behavioral capability (e.g. Capability.Close) or declares its own
inline inside the capabilities array:
capability('drawer', {kind: CapabilityKind.behavioral,description: 'Edge-anchored sliding panel.',hooks: [hook('init', { description: 'Marks a drawer root.', required: true }), hook('backdrop', { description: 'Opts in to a backdrop.' })],states: [state('backdrop-open', { description: 'Set on the backdrop while the drawer is open.' })],emits: [emit('opened', { description: 'Fired on the drawer element after it opens.' })],listens: [listen(Close.emitRefs.dismiss, { description: 'Closes when a descendant close button fires.' })],});
Each facet carries a semantic name (init, backdrop, opened)
and a description. The data-* attribute or event name the JS
actually uses is derived from the capability name and the facet
name - it is never authored. The producer emits the derived wire and
the linter checks the JS against it, both reading the same Derive
conventions in semetrika-spec so they cannot disagree.
Rules
Behavior facets
44.7. A behavioral capability MAY declare four facet buckets:
hooks- consumer-set markers / opt-ins. Semantic name is a noun naming the marker or the option it carries (init,backdrop,selector,min,close_on_escape). Each entry is built byhook(name, options).states- JS-managed runtime markers consumed by CSS / style hooks per Rule 24. Semantic name is an adjective or past participle (expanded,scrolled), a value noun where the state carries one (color,color-scheme), or a{part}-{adjective}compound where it qualifies a named part (backdrop-open,scroll-lock). Each entry is built bystate(name, options).emits- custom DOM events the JS dispatches. The semantic name follows Rule 43.9: a past participle for a notification (opened,changed), the base form for a cancelable intent (dismiss,change). Each entry is built byemit(name, options).listens- custom DOM events the JS subscribes to. Each entry is built bylisten(ref, options), whererefis another capability's emit reference (Close.emitRefs.dismiss) or a local event name.
SIGNATURES.md lists the options each facet factory reads - description, required, values on hooks and states, detail on emits and listens, and wire - with their types.
A hook MUST be required: true when every element its component or utility renders or enhances carries it. A drawer template always renders data-drawer, and an element opts into the cycle utility only through data-cycle, so both are required. A hook only some of those elements carry stays optional:
- one the template renders behind a prop -
data-announcementmarks only an announcement withhas_closeset; - one variant among several -
data-chipmarks only the dismissible chip, anddata-tooltiponly the CSS-only hint; - one the behavior can do without -
revealalso animatessection,articleand the other semantic blocks that carry no attribute.
All four facet factories follow the (identifier, options) call shape of Rule 53.23.
44.8. Every facet name within one behavioral capability MUST be unique across hooks, states, emits, and listens. The buckets share a namespace so the matrix and twig docblock can list any behavior by name without ambiguity.
44.9. Wire strings are derived from the capability name and the facet name by the Derive conventions in semetrika-spec, never authored:
- hook →
data-{capability}when the name isinit, otherwisedata-{capability}-{name}. - state →
data-{capability}-{name}. - emit / listen →
{capability}-{name}(alistenthat references another capability's emit inherits that emit's wire).
A facet MAY pass { wire: '…' } to override the derived value when it borrows a wire owned by another capability (e.g. a component that reuses the shared close utility's data-close attribute), when it reads a foundation attribute (data-color-scheme), or when the attribute is part of the component's markup contract and shorter than the derivation (data-action and data-url on actions, data-announcements, data-autoclose). The override keeps the linter from flagging the wire as undeclared. An override equal to the derived value is redundant and MUST be dropped.
Drift detection (sub-rules)
44.1. Every event name passed to new CustomEvent(...) in a
component or utility's JS MUST match the derived wire of an emit
facet on one of the component's behavioral capabilities.
// drawer.jsdrawer.dispatchEvent(new CustomEvent('drawer-opened', { bubbles: true, cancelable: false }));// drawer.spec.js - inside the 'drawer' behavioral capabilityemits: [emit('opened', { description: 'Fired on the drawer element after it opens.' })];// → derived wire: 'drawer-opened'
44.2. Every emit facet's derived wire MUST be dispatched as a
string-literal new CustomEvent('<wire>', …) somewhere in the
component's JS. No tolerance for wrapper indirection - Rule 43.11
ensures every dispatch uses a literal name.
44.3. Every event name passed to addEventListener(name, …) whose
name matches the Rule 43 custom-event regex
(^[a-z][a-z0-9]*-[a-z][a-z0-9-]*$) MUST match the derived wire of
a listen facet. Standard DOM event names (click, keydown,
transitionend, …) lack the hyphen-action shape and are not subject
to the check.
44.4. Every listen facet's derived wire MUST be bound via
addEventListener somewhere in the component's JS.
44.5. Every data-… attribute the component's JS reads, writes,
selects on, or matches MUST match the derived wire of a hook or
state facet. Tracked references:
el.getAttribute('data-foo')/setAttribute/hasAttribute/removeAttribute.el.dataset.fooBar(camelCase →data-foo-bar).- CSS attribute selectors inside
el.matches('[data-foo]'),querySelector('[data-foo=…]'),querySelectorAll('…'),el.closest('[data-foo]'). - The attribute name passed to
window.Semetrika._numberAttr(el, 'data-foo', …), the shared numeric option reader of Rule 45.12. - The selector passed to
window.Semetrika._collect(root, …)/window.Semetrika._register(name, …), whether written as a literal or hoisted into a module-level constant.
Init markers (attribute names ending in -init) are JS-internal
bookkeeping and MUST NOT be declared; they are filtered out before
this check runs. Outside the _collect / _register selector slot,
an attribute name stored in a const and used through the variable
(const ATTR = 'data-foo'; el.setAttribute(ATTR, '…')) is NOT
detected - reference the attribute literal at the call site.
// toc.jsvar selector = el.getAttribute('data-toc-selector') || 'h2';// toc.spec.js - inside the 'toc' behavioral capabilityhooks: [hook('selector', { description: 'CSS selector for the headings the TOC indexes.' })];// → derived wire: 'data-toc-selector'
44.6. Every hook / state facet whose derived wire is a data-…
attribute MUST be referenced in at least one of the tracked
positions listed in 44.5.
44.1, 44.2, 44.3, 44.4, 44.5, 44.6, 44.9 by yarn cli 44 (findUnspecifiedEmittedEvents, findUnimplementedEmittedEvents, findUnspecifiedListenedEvents, findUnimplementedListenedEvents, findUnspecifiedAttributes, findUnimplementedAttributes, findRedundantWireOverrides in packages/cli/src/rules/44.js). 44.7, 44.8 are review only. See enforcement.md.