Skip to main content

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 by hook(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 by state(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 by emit(name, options).
  • listens - custom DOM events the JS subscribes to. Each entry is built by listen(ref, options), where ref is 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-announcement marks only an announcement with has_close set;
  • one variant among several - data-chip marks only the dismissible chip, and data-tooltip only the CSS-only hint;
  • one the behavior can do without - reveal also animates section, article and 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 is init, otherwise data-{capability}-{name}.
  • state → data-{capability}-{name}.
  • emit / listen → {capability}-{name} (a listen that 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.js
drawer.dispatchEvent(new CustomEvent('drawer-opened', { bubbles: true, cancelable: false }));
// drawer.spec.js - inside the 'drawer' behavioral capability
emits: [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.js
var selector = el.getAttribute('data-toc-selector') || 'h2';
// toc.spec.js - inside the 'toc' behavioral capability
hooks: [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.


Enforced by

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.