Rule 41 - JS: Progressive enhancement
JavaScript adds behavior; it MUST NOT enable base functionality.
Rules
41.1. Every component MUST work without JavaScript. No component MUST render empty or broken when JS is absent.
<!-- Correct: content visible without JS --><details><summary>FAQ Question</summary><p>Answer is visible when opened natively.</p></details><!-- Wrong: content hidden until JS runs --><div class="accordion" style="display:none"><p>Only visible after JS initializes.</p></div>
41.2. CSS-only behavior (:hover, :focus, <details>,
[open], ::after content) MUST be preferred over JS.
41.3. JS files MUST bind to markup via data-* attributes - see
Rule 12. Class selectors MUST NOT
be used for JS binding. Binding is the opt-in lookup that claims an
element; a bound module MAY locate a child its own template or script
renders by that child's class, and MAY read an author-set value class
the spec declares, because neither is a hook a consumer sets.
<!-- Correct --><div data-accordion="exclusive">...</div><!-- Wrong --><div class="js-accordion">...</div>
41.4. JS MUST NOT add inline styles. It MUST toggle attributes or
classes that CSS responds to. A custom property written through
style.setProperty('--…') is the one sanctioned inline write: it
carries a value JS measured to a declaration CSS owns, and the
component's stylesheet decides what the value does.
// Correctelement.setAttribute('aria-expanded', 'true');// Wrongelement.style.display = 'block';
41.5. Component / utility JS files MUST be self-contained scripts
wrapped in an IIFE that defines init(root?) and destroy(root?),
then registers with the orchestrator via
window.Semetrika._register(name, selector, init, destroy, destroySelector?).
They MUST NOT use ES module exports (export). They MUST NOT install
their own DOMContentLoaded listener. They MUST NOT install their own
childList MutationObserver on document.body - that dispatch is
owned by boot.js.
// Correct: scope-isolated IIFE, registers with the orchestrator.(() => {'use strict';const SELECTOR = '[data-foo]';const registry = new WeakMap();function initElement(el) {if (registry.has(el)) return;registry.set(el, {/* teardown state */});}function destroyElement(el) {if (!registry.has(el)) return;registry.delete(el);}function init(root) {window.Semetrika._collect(root, SELECTOR).forEach(initElement);}function destroy(root) {window.Semetrika._collect(root, SELECTOR).forEach(destroyElement);}window.Semetrika._register('foo', SELECTOR, init, destroy);})();// Wrong: self-booting on DOMContentLoaded.if (document.readyState === 'loading') {document.addEventListener('DOMContentLoaded', init);} else {init();}// Wrong: own childList MutationObserver on document.body.new MutationObserver(/* ... */).observe(document.body, { childList: true, subtree: true });
41.6. The orchestrator at src/boot.js owns the single
DOMContentLoaded handler and the single childList
MutationObserver for the entire bundle. It also exposes the
public bulk API: Semetrika.initAll(root?), Semetrika.destroyAll(root?),
and Semetrika.names(). A host that owns its own enhancement
lifecycle defers the automatic INITIAL boot by loading the bundle
with <script src="semetrika.js" data-skip-init>
and calls Semetrika.initAll(context) / Semetrika.destroyAll(context)
from that lifecycle instead. data-skip-init defers
ONLY the initial initAll(document) - the forward-binding observer
still installs, so DOM the host or its components build later (a
component generating markup another component binds to, AJAX
content) is enhanced as it is on a vanilla page. initAll() ensures
the observer is live before running its own inits, so one pass
reconciles a build-then-bind dependency (one component generating
the hooks another initializes) without the host re-running it.
<!-- Auto-boot (the page owns no lifecycle of its own): --><script src="semetrika.js"></script><!-- Manual boot (the host owns the enhancement lifecycle): --><script src="semetrika.js" data-skip-init></script><script>host.onMount = (context) => window.Semetrika.initAll(context);host.onUnmount = (context) => window.Semetrika.destroyAll(context);</script>
41.7. Registry entries are {name, selector, destroySelector, init, destroy}.
destroySelector defaults to selector when omitted from the
_register(...) call; pass it explicitly only when the init-side
selector and the destroy-side selector legitimately differ (avatar
is the canonical example - initializes on
[data-avatar-hash]:not([data-avatar-color]), destroys on
[data-avatar-hash][data-avatar-color]).
// Symmetric (most common).window.Semetrika._register('drawer', '[data-drawer]', init, destroy);// Asymmetric (avatar).window.Semetrika._register('avatar', '[data-avatar-hash]:not([data-avatar-color])', init, destroy, '[data-avatar-hash][data-avatar-color]');
41.8. Component-specific extras beyond plain childList dispatch stay file-local:
- Per-instance observers - a
MutationObserverscoped to one specific element (e.g. loading.js's per-wrapper child observer that waits for loadable descendants to appear) lives inside the per-element setup, allocated ininit()and disconnected indestroy(). - Attribute-filtered observers - a
MutationObserverwithattributeFilter: [...]watching for attribute changes (e.g. collapsible.js re-initializing when a consumer resetsdata-collapsible) lives in the component file.boot.js's observer is{ childList: true, subtree: true }only. - Document- or window-level listeners -
document.addEventListener('click', ...)for outside-click dismissal,window.addEventListener('resize', ...), etc. install with the module's first claimed element and release with its last, throughwindow.Semetrika._globals(install, uninstall)per Rule 45.13. The helper counts what the module owns, so a subtreedestroy(root)or an explicitdestroyAll()releases correctly where a document query would not.
// Pattern: install-once globals through the shared helper, released with the last instance.let globalAc = null;const globals = window.Semetrika._globals(() => {globalAc = new AbortController();document.addEventListener('click', handleGlobalClick, { signal: globalAc.signal });document.addEventListener('keydown', handleGlobalKeydown, { signal: globalAc.signal });},() => {globalAc.abort();globalAc = null;},);function initElement(el) {if (registry.has(el)) return;registry.set(el, { ac: new AbortController() });globals.acquire();}function destroyElement(el) {const entry = registry.get(el);if (!entry) return;entry.ac.abort();registry.delete(el);globals.release();}
41.9. init(root) MUST be idempotent on a given element: a per-instance
init guard - the WeakMap of Rule 45.5, or
the marker attribute of Rule 45.6 where
teardown or observation configuration must read it - MUST
short-circuit re-processing so that
boot.js, the host, and the per-instance child observer can all
call init() on overlapping subtrees without double-binding.
destroy(root) MUST similarly be safe on elements that were never
initialized (no-op rather than throw).
41.4, 41.5 by yarn cli 41 (findInlineStyleWrites, findInvalidRegistration in packages/cli/src/rules/41.js). 41.1-41.3, 41.6-41.9 are review only. See enforcement.md.