Skip to main content

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.

// Correct
element.setAttribute('aria-expanded', 'true');

// Wrong
element.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 MutationObserver scoped 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 in init() and disconnected in destroy().
  • Attribute-filtered observers - a MutationObserver with attributeFilter: [...] watching for attribute changes (e.g. collapsible.js re-initializing when a consumer resets data-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, through window.Semetrika._globals(install, uninstall) per Rule 45.13. The helper counts what the module owns, so a subtree destroy(root) or an explicit destroyAll() 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).


Enforced by

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.