Rule 43 - JS: Custom event naming
Custom DOM events emitted by Semetrika components and utilities MUST follow a single, consistent naming convention: an all-lowercase, hyphen-separated identifier where the first segment is the component or utility name and the remaining segment(s) describe the action.
Rules
Event name format
43.1. Every custom event MUST use the format
<component>-<action>: lowercase letters, digits, and hyphens only.
The first segment is the component or utility slug (matching the
directory name in src/components/ or src/utilities/). The
remaining segments describe the action using one or more
hyphen-separated lowercase words.
// ✅ Correctnew CustomEvent('close-dismiss', { bubbles: true, cancelable: true });new CustomEvent('carousel-slide-started', { bubbles: true, cancelable: false, detail: { from, to } });new CustomEvent('loading-complete', { bubbles: true, cancelable: false });// ❌ Wrong - dot separatornew CustomEvent('close.dismiss');// ❌ Wrong - colon separatornew CustomEvent('collapsible:expand');// ❌ Wrong - camelCase (inline `on*` handlers lowercase the name)new CustomEvent('carouselSlideStart');// ❌ Wrong - no component prefixnew CustomEvent('dismiss');
43.2. Custom event names MUST match the regular expression
^[a-z][a-z0-9]*-[a-z][a-z0-9-]*$.
Why hyphen-separated, all-lowercase
43.3. Inline HTML event handlers (onmycomponent-event="...")
lowercase the event name on arrival - camelCase custom events
work with addEventListener but silently fail for inline handlers.
Hyphen-separated all-lowercase identifiers avoid this class of bug
entirely and mirror native DOM naming conventions (e.g.,
animationend, DOMContentLoaded).
43.4. The leading component prefix prevents collisions with both native events and events emitted by other libraries loaded on the same page.
Event emission
43.5. Custom events MUST be emitted via the CustomEvent
constructor, not Event. The detail property SHOULD be used for
payload rather than custom properties on the event instance.
el.dispatchEvent(new CustomEvent('carousel-slide-started', {bubbles: true,cancelable: false,detail: { from: 0, to: 1, reason: 'next' },}),);
43.6. Events that represent user-initiated actions with side effects
(e.g., close-dismiss, chip-dismiss) SHOULD be cancelable: true
so consumers can event.preventDefault() to suppress the default
behavior.
43.7. Events that need to reach ancestors for delegation SHOULD be
bubbles: true. Events that represent purely local lifecycle
changes MAY stay non-bubbling.
43.15. Every new CustomEvent(...) MUST pass bubbles and
cancelable explicitly.
Both properties default to false, and both defaults are wrong for
almost every event in this codebase - one leaves a delegated listener
on an ancestor silently unreachable, the other withdraws the
preventDefault hook 43.6 promises. An omission reads as neither a
decision nor a mistake, so it survives review; an explicit false
states that someone chose it.
// ✅ Correct.el.dispatchEvent(new CustomEvent('drawer-opened', { bubbles: true, cancelable: false }));// ❌ Wrong - cancelability is left to the constructor default.el.dispatchEvent(new CustomEvent('drawer-opened', { bubbles: true }));
43.16. detail MUST be omitted when the event carries no payload.
detail: {} and detail: null MUST NOT be written.
event.detail reads null on an event constructed all three ways, so
the two written forms state nothing the omission does not, while
suggesting a payload the consumer can destructure.
43.17. A cancelable: true event MUST be honored by whichever
module performs the default action - the emitter where it acts on its
own event (close.js returning focus, chip.js removing the chip),
the listener where the action belongs to it (popout.js opening a
panel on hoverintent-enter). An event no code checks MUST NOT be
cancelable.
Cancellation MUST be read as event.defaultPrevented on an event
held in a const. dispatchEvent's boolean return MUST NOT stand in
for it.
The flag is a promise that preventDefault() changes what happens
next. An event nothing checks makes that promise and breaks it
invisibly - the consumer's handler runs, the default action runs
anyway, and nothing is raised. The boolean return means
!defaultPrevented, which reads as "the dispatch succeeded" to
anyone who has not memorized that.
// ✅ Correct.const event = new CustomEvent('actions-print', { bubbles: true, cancelable: true, detail: { trigger } });trigger.dispatchEvent(event);if (!event.defaultPrevented) window.print();// ❌ Wrong - the return value stands in for the check.if (form.dispatchEvent(new CustomEvent('filter-change', { bubbles: true, cancelable: true, detail }))) {applyChange();}
43.18. Two detail keys are reserved across every event:
trigger- the element the interaction started from, always an element.reason- the string that says which path produced the event ('escape','next','reset'), always a string.
source MUST NOT be used as a detail key, and a component MUST NOT
name the originating element after itself (detail.chip). One key
holding an element in one component and a string in another cannot be
read without opening the dispatch site, and a key named after its own
component transfers to nothing.
// ✅ Correct.detail: { command, trigger };detail: { from, to, reason: 'next' };// ❌ Wrong - `source` holds an element here and a string one component over.detail: { command, source: trigger };
43.19. A component or utility module MUST NOT probe for
CustomEvent. typeof CustomEvent !== 'undefined' and equivalent
feature detections MUST NOT appear in one, whether or not a dispatch
sits inside them.
The supported engines all construct CustomEvent, so the branch
cannot be false, and a probe that guards nothing makes the same claim
without the branch. One module probing while the rest dispatch
directly says the environment contract is undecided rather than met.
43.20. In a {name}.spec.js, a listen on an event another
capability emits MUST reference that capability's emit symbol
(Close.emitRefs.dismiss), never a bare string with a { wire: … }
override. The override exists for borrowing a wire, and a string name
beside it is validated against nothing, so the declared name and the
wire it overrides to can differ without anything catching it.
Documentation
43.8. Every emitted custom event MUST be documented in the component
JSDoc header, listing the event name, when it fires, whether it
bubbles / is cancelable, and the shape of detail. The same surface
is also tracked in spec.events per
Rule 44, which drives the twig docblock
and the matrix.
Notification or intent
43.9. Every emitted event is exactly one of two kinds, and its name
and its cancelable flag MUST agree on which:
- Notification -
cancelable: false. The change has already happened, and the name states the state reached, in the past participle:drawer-opened,carousel-slide-ended,consent-accepted,loading-resolved. Where the event announces an occurrence rather than a state change, it names the occurrence as a noun:modal-command. - Intent -
cancelable: true. The action has not run yet, the name states it in the base form, and 43.17 requires the dispatching code to honordefaultPrevented:close-dismiss,chip-dismiss,actions-print,filter-change.
Tense on its own is a matter of taste; tied to cancelability it is a
claim about behavior. A base-form name on a notification invites a
preventDefault() that does nothing, and a past participle on an
intent describes a state the consumer can still prevent from being
reached.
The same verb therefore names both halves of a programmatic pair
without collision: a consumer dispatches collapsible-expand to
request an expansion, and the utility emits collapsible-expanded
once the panel is open.
/*** Carousel component.** Events:* carousel-slide-started - transition initiated.* bubbles: true, cancelable: false,* detail: { from: number, to: number, reason: 'prev'|'next'|'dot'|'key'|'autoplay' }* carousel-slide-ended - transition settled.* bubbles: true, cancelable: false, detail: { index: number }*/
Storybook event toaster
43.10. Every stories file that calls watchEvents(...) MUST declare a
debug_events arg on its default-export meta, defined in both
argTypes (as a boolean control) and args. For a utility story
the default value MUST be true so the event toaster is visible by
default: a utility's events are typically its only observable output,
so the toaster is the in-canvas documentation of what the behavior
emits, and a reader exploring the docs page MUST see the events fire
without first hunting for a toggle. For a component story the
default MAY be false - a component renders visible output of its
own, so the toaster is opt-in rather than essential documentation.
The one permitted exception to the utility default-on rule is a
utility whose events fire at high frequency (scroll, resize,
pointer-move), which MAY default the arg to false with a one-line
comment explaining why. The preview-level decorator translates the
arg into document.body[data-debug-events="true"], which the toast
helper checks before rendering.
43.10a. The toaster panel is labeled Debug events (a chrome-only
eyebrow on .story-event-toast-stack) so a reader never mistakes an
emitted-event toast for real, shipped behavior of the component.
The toaster is a Storybook development aid, never part of the
framework.
// Utility stories file that emits events - include the arg, default on.watchEvents(['collapsible-toggle']);export default {argTypes: {debug_events: {control: 'boolean',name: 'Debug events',description: 'Show a toast for each emitted event (development aid).',table: { category: 'Debug' },},},args: {debug_events: true,},};
No wrapper indirection
43.11. Events MUST be dispatched directly with a string-literal name:
// ✅ Correct - literal at the call site.el.dispatchEvent(new CustomEvent('drawer-opened', { bubbles: true, cancelable: false }));// ❌ Wrong - wrapper hides the event name from grep and from rule 44.function emit(target, type, detail) {target.dispatchEvent(new CustomEvent(type, { bubbles: true, cancelable: false, detail }));}emit(drawer, 'drawer-opened', {});
Wrappers like emit(target, type, detail) / dispatch(el, type, …) / fireEvent(el, type) that accept the event name as a dynamic parameter MUST NOT exist. They make event names invisible to a literal-based grep and to Rule 44's spec-contract check. The cost of inlining (a few extra characters per dispatch) is paid every time the file is read; the cost of the indirection is paid every time a developer searches for "who fires this event?".
Enforcement
43.12. The lint check findInvalidEventNames in
packages/cli/src/rules/43.js scans every JS file under the
src/components/ and src/utilities/ trees for string literals
passed as the first argument to new CustomEvent(...) and
validates them against the pattern in Rule 43.2.
43.13. The lint check findMissingDebugEventsArg (in the same
file) scans every *.stories.js file for a call to watchEvents(
and requires the file to declare a debug_events control in
argTypes and a default in args (or pass
withControls({ debugEvents: true }), or route the same opt-in
through storyFor(spec, { controls: { debugEvents: true } })). For a story under
src/utilities/ the default MUST be true; a false default is a
violation unless a one-line comment on the same line, or on the
non-blank line directly above it, justifies the high-frequency
exception. Component stories may default either way. Every violation
fails the lint step and blocks CI.
43.14. The lint check findDynamicEventDispatches (also in
packages/cli/src/rules/43.js) flags every new CustomEvent(IDENT, …)
call where the first argument is an identifier rather than a string
literal. Each such call indicates a wrapper function and is reported
as a 43.11 violation.
43.21. Five further checks in the same file read one dispatch at a
time and hold the mechanical half of the contract above:
findImplicitEventFlags (43.15), findEmptyEventDetail (43.16),
findDispatchReturnUsed (43.17), findBannedDetailKeys (43.18), and
findGuardedDispatch (43.19). Each scans the same component and
utility JS trees as 43.12 and fails the lint step on any finding.
Which module honors a cancelable event is judged at review.
43.1, 43.2, 43.10, 43.13, 43.11, 43.15, 43.16, 43.17, 43.18, 43.19 by yarn cli 43 (findInvalidEventNames, findMissingDebugEventsArg, findDynamicEventDispatches, findImplicitEventFlags, findEmptyEventDetail, findDispatchReturnUsed, findBannedDetailKeys, findGuardedDispatch in packages/cli/src/rules/43.js). 43.3-43.9, 43.12, 43.14, 43.20, 43.21 are review only. See enforcement.md.