Skip to main content

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.

// ✅ Correct
new 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 separator
new CustomEvent('close.dismiss');
// ❌ Wrong - colon separator
new CustomEvent('collapsible:expand');
// ❌ Wrong - camelCase (inline `on*` handlers lowercase the name)
new CustomEvent('carouselSlideStart');
// ❌ Wrong - no component prefix
new 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 honor defaultPrevented: 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.


Enforced by

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.