@livenetworks/ashlar 1.5.1 → 1.6.0

package/js/COMPONENTS.md

@@ -169,9 +169,8 @@ _component.prototype.open = function () {
 While utilizing an `<input type="checkbox">` and the CSS sibling selector (`:checked ~ .menu`) is a common "pure CSS" pattern for toggling dropdowns or modals, it is **off-doctrine** for `ln-ashlar` components and must not be used:
 
 1. **Non-Observable Programmatic Updates:** Changing `.checked = true` programmatically via JavaScript **does not** dispatch native browser `'change'` or `'input'` events. It also **does not** trigger the `MutationObserver` (which only watches attribute modifications in the HTML markup). This completely breaks the reactive attribute-driven bridge.
-2. **Teleportation Conflict:** `ln-ashlar` components regularly teleport overlays to `document.body` (e.g., dropdown menus, modals) to prevent parent `z-index` and `overflow: hidden` issues. Teleportation immediately breaks the CSS sibling/child relationships required for CSS-only checkbox selectors.
-3. **Broken Encapsulation:** A checkbox lives inside or beside the component. To read or write state, external coordinators or other components would have to query the internal DOM structure (e.g., `modal.querySelector('input[type="checkbox"]').checked`), exposing private details.
-4. **Accessibility (ARIA) Semantic Mismatch:** Modals, dropdown triggers, and popovers require specific ARIA roles (e.g., `role="dialog"`, `aria-haspopup="menu"`, `aria-expanded`). A checkbox natively announces itself as a checkbox, which confuses screen readers and causes accessibility regressions.
+2. **Broken Encapsulation:** A checkbox lives inside or beside the component. To read or write state, external coordinators or other components would have to query the internal DOM structure (e.g., `modal.querySelector('input[type="checkbox"]').checked`), exposing private details.
+3. **Accessibility (ARIA) Semantic Mismatch:** Modals, dropdown triggers, and popovers require specific ARIA roles (e.g., `role="dialog"`, `aria-haspopup="menu"`, `aria-expanded`). A checkbox natively announces itself as a checkbox, which confuses screen readers and causes accessibility regressions.
 
 ---
 
@@ -279,7 +278,7 @@ Use reactive rendering when a component has **2+ state properties** that togethe
 
 **Don't use it for:**
 - Single boolean state — `this.isOpen = true; dom.classList.toggle(...)` is simpler
-- Event-driven rendering — components that receive data via `set-data` events (ln-data-table)
+- Event-driven rendering — components that receive data via `set-data` events (ln-table)
 - One-shot renders — clone template + fill once, no ongoing state
 
 ### Used in
@@ -555,7 +554,7 @@ Do NOT standardize to one pattern — each exists for architectural reasons.
 | DOM instance | `element.ln{Name}` | `el.lnToggle` |
 | Custom event | `ln-{name}:{action}` | `ln-toggle:open` |
 | CSS class | `.ln-{name}__{element}` | `.ln-toggle__backdrop` |
-| Initialized flag | `data-ln-{name}-initialized` | `data-ln-toggle-for-initialized` |
+| Initialized flag | `element.ln{Name}` | `el.lnToggle` |
 | Private function | `_functionName` | `_render`, `_attachTriggers` |
 
 ---
@@ -625,6 +624,17 @@ nav.dispatchEvent(new CustomEvent('ln-profile:request-create', {
 | **Command** (changes state) | request event | `nav.dispatchEvent(new CustomEvent('ln-profile:request-remove', { detail: { id } }))` |
 | **Query** (reads state) | direct access | `nav.lnProfile.currentId`, `sidebar.lnPlaylist.getTrack(idx)` |
 
+### Request-Reply / Collector Pattern (Sync Gathering)
+
+For commands that require synchronous feedback or list gathering (such as batch validation before submit):
+- **Format:** `ln-{name}:request-{action}` with `e.detail` containing a mutable data structure (like an array).
+- **Example:** `ln-validate:request-validate` with `detail: { invalidFields: [] }`.
+- **Mechanism:** The caller dispatches the event on a common ancestor (like `<form>`). Listeners catch it synchronously, evaluate their state, and push results/references directly to the mutable array in `e.detail`.
+- **Bubbling:** `true` (to allow components/listeners attached to form or ancestor nodes to catch it).
+
+### Form Scoping and Validation Rules
+- **Novalidate:** `ln-validate` injects `novalidate` on its host `<form>` automatically — the moment a form contains at least one `data-ln-validate` field, native browser bubbles are silenced in favor of inline error lists. Authors never write `novalidate` by hand; a form with zero `data-ln-validate` fields keeps native browser validation as the default.
+
 ---
 
 ## Coordinator — Full Example
@@ -653,20 +663,11 @@ nav.dispatchEvent(new CustomEvent('ln-profile:request-create', {
             }
         });
 
-        // 2. Form submit → request event
-        document.addEventListener('ln-form:submit', function (e) {
-            if (e.target.getAttribute('data-ln-form') !== 'new-profile') return;
-            const input = document.querySelector('[data-ln-field="new-profile-name"]');
-            const name = input ? input.value.trim() : '';
-            if (!name) return;
-
-            const nav = _getNav();
-            if (nav) {
-                nav.dispatchEvent(new CustomEvent('ln-profile:request-create', {
-                    detail: { name: name }
-                }));
-            }
-            input.value = '';
+        // 2. Local-first write form → ln-data-coordinator claims the native
+        // submit (preventDefault); react to the store outcome instead.
+        // <form data-ln-form data-ln-form-scope="profiles" method="post" action="/api/profiles">
+        document.addEventListener('ln-data-store:created', function (e) {
+            if (e.detail.store !== 'profiles') return;
             document.getElementById('modal-new-profile').setAttribute('data-ln-modal', 'close');
         });
 
@@ -828,14 +829,14 @@ Beyond text, `fill()` binds attributes (`data-ln-attr`) and toggles classes (`da
     <li class="ln-upload__item"
         data-ln-class="ln-upload__item--uploading:uploading, ln-upload__item--error:error, ln-upload__item--deleting:deleting">
         <svg class="ln-icon" aria-hidden="true">
-            <use data-ln-attr="href:iconHref" href="#ln-file"></use>
+            <use data-ln-attr="href:iconHref" href="#ln-icon-file"></use>
         </svg>
         <span class="ln-upload__name" data-ln-field="name"></span>
         <span class="ln-upload__size" data-ln-field="sizeText"></span>
         <button type="button" class="ln-upload__remove"
                 data-ln-upload-action="remove"
                 data-ln-attr="aria-label:removeLabel, title:removeLabel">
-            <svg class="ln-icon" aria-hidden="true"><use href="#ln-x"></use></svg>
+            <svg class="ln-icon" aria-hidden="true"><use href="#ln-icon-x"></use></svg>
         </button>
         <div class="ln-upload__progress">
             <div class="ln-upload__progress-bar"></div>
@@ -851,7 +852,7 @@ li.setAttribute('data-file-id', localId);
 fill(li, {
     name: file.name,
     sizeText: '0%',
-    iconHref: '#' + iconId,    // → <use href="#lnc-file-pdf">
+    iconHref: '#' + iconId,    // → <use href="#ln-icon-custom-file-pdf">
     removeLabel: dict.remove,  // → aria-label + title on button
     uploading: true,           // → adds ln-upload__item--uploading
     error: false,
@@ -875,14 +876,14 @@ One `fill()` call handles all three binding types at once:
 - **`data-ln-attr="href:iconHref"`** → one or more attributes per element (`href` on `<use>`, `aria-label` + `title` on the button)
 - **`data-ln-class="ln-upload__item--uploading:uploading, ..."`** → conditional class toggles driven by booleans
 
-State transitions are just successive `fill()` calls with different values — no imperative `classList.add/remove`, no manual `setAttribute`. The icon swap via `data-ln-attr="href:iconHref"` on a `<use>` element works because `ln-icons` runs a MutationObserver on `<use href>` changes and auto-fetches the new sprite — the component never touches the icon loader directly.
+State transitions are just successive `fill()` calls with different values — no imperative `classList.add/remove`, no manual `setAttribute`. The icon swap via `data-ln-attr="href:iconHref"` on a `<use>` element works because `ln-icon` runs a MutationObserver on `<use href>` changes and auto-fetches the new sprite — the component never touches the icon loader directly.
 
 **Behavioral hooks live on attributes, not classes** — `data-ln-upload-action="remove"` is a JS query hook, not a fill slot. Delegated click handlers on `.ln-upload__list` use `e.target.closest('[data-ln-upload-action="remove"]')` to locate the button, which also matches when the click lands on a nested `<svg>` / `<use>`. Keeping behavioral hooks off CSS class names means a project can rename or restyle classes without breaking JS.
 
 **Imperative escape hatches** — two things `fill()` can't express cleanly:
 
 1. `removeBtn.disabled = !uploaded` — the `disabled` boolean attribute doesn't round-trip through `data-ln-attr` (setting vs. removing).
-2. `progressBar.style.width = percent + '%'` — a continuous animation value, not discrete state. Same precedent as `ln-data-table` virtual-scroll spacer heights.
+2. `progressBar.style.width = percent + '%'` — a continuous animation value, not discrete state. Same precedent as `ln-table` virtual-scroll spacer heights.
 
 Both are one-line assignments right after the `fill()` call and are the only non-declarative touches in the render path.
 
@@ -900,7 +901,7 @@ Both are one-line assignments right after the `fill()` call and are the only non
         <li class="ln-upload__item"
             data-ln-class="ln-upload__item--uploading:uploading, ln-upload__item--error:error, ln-upload__item--deleting:deleting">
             <svg class="ln-icon ln-icon--lg" aria-hidden="true">
-                <use data-ln-attr="href:iconHref" href="#ln-file"></use>
+                <use data-ln-attr="href:iconHref" href="#ln-icon-file"></use>
             </svg>
             <article>
                 <p class="ln-upload__name" data-ln-field="name"></p>
@@ -909,7 +910,7 @@ Both are one-line assignments right after the `fill()` call and are the only non
             <button type="button" class="ln-upload__remove"
                     data-ln-upload-action="remove"
                     data-ln-attr="aria-label:removeLabel, title:removeLabel">
-                <svg class="ln-icon" aria-hidden="true"><use href="#ln-x"></use></svg>
+                <svg class="ln-icon" aria-hidden="true"><use href="#ln-icon-x"></use></svg>
             </button>
             <div class="ln-upload__progress"><div class="ln-upload__progress-bar"></div></div>
         </li>
@@ -956,7 +957,7 @@ The component calls `_ensureDefaultItemTemplate()` at the top of `_initUpload()`
 | Component | Template(s) | Lookup | Notes |
 |---|---|---|---|
 | **ln-upload** | `ln-upload-item` | `cloneTemplateScoped` | Scoped → global → auto-injected default on first init |
-| **ln-data-table** | `{name}-row`, `{name}-empty`, `{name}-empty-filtered`, `column-filter` (also falls back to `{name}-column-filter`) | `cloneTemplateScoped` | Scoped-first per table instance |
+| **ln-table** | `{name}-row`, `{name}-empty`, `{name}-empty-filtered`, `column-filter` (also falls back to `{name}-column-filter`) | `cloneTemplateScoped` | Scoped-first per table instance |
 | **ln-translations** | `ln-translations-menu-item`, `ln-translations-badge` | `cloneTemplate` | Single global template, no per-instance override |
 
 ### Rules
@@ -983,10 +984,10 @@ The component calls `_ensureDefaultItemTemplate()` at the top of `_initUpload()`
 
 | Component | Pattern | Data Attr | Description |
 |-----------|---------|-----------|------|
-| ln-core | Shared module | — | cloneTemplate, cloneTemplateScoped, dispatch, dispatchCancelable, fill, fillTemplate, renderList, buildDict, guardBody, findElements, reactiveState, deepReactive, createBatcher |
+| ln-core | Shared module | — | cloneTemplate, cloneTemplateScoped, dispatch, dispatchCancelable, fill, fillTemplate, renderList, buildDict, guardBody, findElements, reactiveState, deepReactive, createBatcher, createWindowCache |
 | ln-toggle | Instance | `data-ln-toggle` | Generic toggle (sidebar, collapse) |
 | ln-accordion | Instance | `data-ln-accordion` | Wrapper — only one toggle open at a time |
-| ln-tabs | Instance | `data-ln-tabs` | Hash-aware tab navigation |
+| ln-tabs | Instance | `data-ln-tabs` | Tab navigation — URL hash (anchor triggers) or localStorage persist (button triggers) |
 | ln-nav | Instance | `data-ln-nav` | Active link highlighter |
 | ln-modal | Instance | `data-ln-modal` | Modal dialog |
 | ln-toast | Functional | `data-ln-toast` | Toast notifications |
@@ -996,8 +997,8 @@ The component calls `_ensureDefaultItemTemplate()` at the top of `_initUpload()`
 | ln-circular-progress | Instance | `data-ln-circular-progress` | Circular (ring) progress indicator |
 | ln-search | Instance | `data-ln-search` | Generic search (textContent filter) |
 | ln-filter | Instance | `data-ln-filter` | Generic filter (data attribute filter) |
-| ln-table | Instance | `data-ln-table` | Data table (search, filter, sort, virtual scroll) |
-| ln-table-sort | Instance | `data-ln-sort` | Sort header handler (companion to ln-table) |
+| ln-table | Instance | `data-ln-table` | Data table (search, filter, sort, virtual scroll; opt-in server-side windowed virtualization via `data-ln-table-window`) |
+| ln-sort | Instance | `data-ln-sort` | Sort control primitive — 3-trigger cycle (none→asc→desc→none), search-precedent cancelable event; targets ln-table, ln-list, or plain lists |
 | ln-sortable | Instance | `data-ln-sortable` | Drag & drop reorder |
 | ln-dropdown | Instance | `data-ln-dropdown` | Positioned dropdown menu (wraps ln-toggle) |
 | ln-popover | Instance | `data-ln-popover` | Rich popover with viewport-aware positioning and ESC-stack management |
@@ -1049,42 +1050,47 @@ own attribute (`data-ln-modal`, `data-ln-popover`, `data-ln-tabs-active`).
 The "attribute is the single source of truth" pattern is shared; the
 specific attribute is not.
 
-### Form family — ln-form coordinates siblings
+### Form family — ln-validate owns the submit gate
 
 ```
-ln-form  (catches submit, reads ln-validate events)
-  ├── ln-validate   dispatches ln-validate:valid / ln-validate:invalid,
-  │                 which ln-form listens for
-  └── ln-autosave   stores form state in localStorage; writes on blur/change
-                    independently of ln-form
+ln-validate  (first field per form attaches the submit gate;
+              every field self-registers its own request-validate
+              listener)
+
+ln-form      (populate + RESTful action routing only — no submit
+              listener, no validation awareness)
+
+ln-autosave  stores form state in localStorage; writes on blur/change,
+             independently of both ln-form and ln-validate
 ```
 
-ln-form never calls `lnValidate.isValid()` or reads TomSelect state
-directly. It listens to the validation events and lets each sibling
-manage its own internals.
+None of the three import each other or call cross-instance methods.
+`ln-form.fill()` dispatches synthetic `input`/`change` on populated
+fields; `ln-validate`'s own field listeners react to those exactly as
+they would to real user input. `ln-autosave` does the same on restore.
 
-### Data family — ln-data-table ↔ ln-store through the coordinator
+### Data family — ln-table ↔ ln-store through the coordinator
 
 ```
-ln-data-table                              ln-store
+ln-table                                   ln-store
       │                                        │
-      │  ln-data-table:request-data  ─────────▶│
+      │  ln-table:request-data  ──────────────▶│
       │  (sort, filters, search)               │  (reads IndexedDB)
       │                                        │
-      │◀───────  ln-data-table:set-data        │
+      │◀───────  ln-table:set-data             │
       │          (rows + totals)               │
       │                                        │
-      │◀───────  ln-store:synced               │
+      │◀───────  ln-data-store:synced          │
       │          (coordinator re-queries)      │
                        ▲
                        │
                 project coordinator
 ```
 
-`ln-data-table` never imports or queries `ln-store`. It emits a request
+`ln-table` never imports or queries `ln-store`. It emits a request
 event; the project coordinator catches it, calls `storeEl.lnStore.getAll(...)`,
-and dispatches `ln-data-table:set-data` back. See
-[docs/js/component-guide.md](../docs/js/component-guide.md#data-flow-with-ln-store)
+and dispatches `ln-table:set-data` back. See
+[docs/architecture/component-guide.md](../docs/architecture/component-guide.md#data-flow-with-ln-store)
 for the full handshake.
 
 ### Rule
@@ -1099,4 +1105,4 @@ whole stack.
 ---
 
 > For the latest component skeleton and checklist →
-> see [docs/js/component-guide.md](../docs/js/component-guide.md)
+> see [docs/architecture/component-guide.md](../docs/architecture/component-guide.md)

package/js/index.js

@@ -3,8 +3,19 @@ import '../scss/ln-ashlar.scss';
 
 // JS Components
 import './ln-http/src/ln-http.js';
+import './ln-form/src/ln-form.js';
+// ln-validate must attach its submit listener before ln-ajax's: a <form>
+// can carry both data-ln-validate fields and data-ln-ajax, and
+// same-target same-event listeners fire in registration order.
+// ln-validate's validation gate has to run first so ln-ajax can see
+// e.defaultPrevented. ln-data-coordinator's own write-claim listener is
+// unaffected by this ordering — it lives on `document` (bubble phase),
+// strictly after every listener registered directly on the form itself.
+import './ln-validate/src/ln-validate.js';
 import './ln-ajax/src/ln-ajax.js';
+import './ln-router/src/ln-router.js';
 import './ln-modal/src/ln-modal.js';
+import './ln-modal-coordinator/src/ln-modal-coordinator.js';
 import './ln-number/src/ln-number.js';
 import './ln-date/src/ln-date.js';
 import './ln-nav/src/ln-nav.js';
@@ -21,21 +32,27 @@ import './ln-link/src/ln-link.js';
 import './ln-progress/src/ln-progress.js';
 import './ln-filter/src/ln-filter.js';
 import './ln-search/src/ln-search.js';
-import './ln-table/src/ln-table-sort.js';
+import './ln-sort/src/ln-sort.js';
 import './ln-table/src/ln-table.js';
+import './ln-table-coordinator/src/ln-table-coordinator.js';
+import './ln-list/src/ln-list.js';
 import './ln-circular-progress/src/ln-circular-progress.js';
 import './ln-sortable/src/ln-sortable.js';
 import './ln-confirm/src/ln-confirm.js';
 import './ln-translations/src/ln-translations.js';
 import './ln-autosave/src/ln-autosave.js';
 import './ln-autoresize/src/ln-autoresize.js';
-import './ln-validate/src/ln-validate.js';
-import './ln-form/src/ln-form.js';
+import './ln-editor/src/ln-editor.js';
+import './ln-fill/src/ln-fill.js';
+import './ln-slug/src/ln-slug.js';
 import './ln-time/src/ln-time.js';
 import './ln-data-store/src/ln-data-store.js';
 import './ln-api-connector/src/ln-api-connector.js';
 import './ln-couchdb-connector/src/ln-couchdb-connector.js';
 import './ln-data-coordinator/src/ln-data-coordinator.js';
-import './ln-data-table/src/ln-data-table.js';
-import './ln-icons/src/ln-icons.js';
+import './ln-api-queue/src/ln-api-queue.js';
+import './ln-options/src/ln-options.js';
+import './ln-stat/src/ln-stat.js';
+import './ln-icon/src/ln-icon.js';
+import './ln-debug/src/ln-debug.js';
 

package/js/ln-accordion/README.md

@@ -1,137 +1,186 @@
-# ln-accordion
-
-> A lightweight, stateless **Coordinator** that enforces a single-open rule across a list of independent `ln-toggle` panels.
-
----
-
-## 1. Philosophy & The Coordinator Mindset
-
-In traditional frontend architectures, an accordion is a heavy, monolithic component that owns click events, height transitions, ARIA states, active-panel state, and storage persistence. 
-
-In `ln-ashlar`, `ln-accordion` is fundamentally different: **it is a pure coordinator**. It contains only 38 lines of JavaScript, carries zero internal state, and coordinates other highly-specialized primitives.
-
-Every accordion is a perfect synchronization of three orthogonal concerns:
-
-1. **State Primitive (`ln-toggle`)**: Each panel is an independent `ln-toggle` instance. It owns the binary `open`/`close` state, coordinates trigger buttons, synchronizes `aria-expanded`/`aria-controls`, and handles per-panel localStorage persistence (`data-ln-persist`). It is completely oblivious to the other panels or the fact that it is inside an accordion.
-2. **Animation Engine (CSS `.collapsible`)**: The height transition is handled entirely in Vanilla CSS via the `.collapsible` mixin (transitioning `grid-template-rows` from `0fr` to `1fr`). No JS framerate stuttering or inline height hacks.
-3. **The Coordinator (`ln-accordion`)**: Lives on the wrapper element. It enforces a single rule: *"When one panel opens, all other open panels in this group must close."*
-
----
-
-## 2. Minimal Blueprint
-
-This is the standard HTML structure. The pairing of triggers and panels is by ID, keeping layout and proximity decoupled.
-
-```html
-<ul data-ln-accordion>
-    <li>
-        <!-- The Trigger -->
-        <header data-ln-toggle-for="panel1">
-            Section 1
-            <svg class="ln-icon ln-chevron" aria-hidden="true"><use href="#ln-arrow-down"></use></svg>
-        </header>
-        <!-- The Collapsible Panel -->
-        <section id="panel1" data-ln-toggle="open" class="collapsible">
-            <article class="collapsible-body">
-                <p>Content 1 (Starts open).</p>
-            </article>
-        </section>
-    </li>
-    <li>
-        <header data-ln-toggle-for="panel2">
-            Section 2
-            <svg class="ln-icon ln-chevron" aria-hidden="true"><use href="#ln-arrow-down"></use></svg>
-        </header>
-        <section id="panel2" data-ln-toggle class="collapsible">
-            <article class="collapsible-body">
-                <p>Content 2 (Starts closed).</p>
-            </article>
-        </section>
-    </li>
-</ul>
-```
-
-### Key Anatomy Rules
-- **The Wrapper (`data-ln-accordion`)**: Markers for the coordinator. Listens for bubbled events and coordinates siblings.
-- **The Trigger (`data-ln-toggle-for`)**: Click target that toggles the target panel ID. The chevron rotates automatically driven by `aria-expanded`.
-- **The Panel (`data-ln-toggle`)**: Creates the `ln-toggle` state instance. Value `open` or empty.
-- **The Body (`.collapsible-body`)**: Wraps actual content. Padding and margins must live here, not on the parent `.collapsible` (which needs zero padding to collapse to exactly `0px` height).
-
----
-
-## 3. The Decoupled State & API Contract
-
-The coordinator has **zero public state** in JavaScript. The DOM is the source of truth, and **the HTML attribute is the sole contract**.
-
-### Attributes
-- `data-ln-accordion` on the wrapper creates the coordinator instance. It takes no values.
-
-### Events
-- **`ln-accordion:change`**: Dispatched on the wrapper after a panel opens and siblings close.
-  - `event.detail.target`: The HTML element of the panel that just opened.
-  ```js
-  document.addEventListener('ln-accordion:change', (e) => {
-      console.log('Active panel ID:', e.detail.target.id);
-  });
-  ```
-
-### Programmatic Control
-There are no `open()` or `close()` methods on the coordinator instance. To programmatically change panels, write directly to the target panel's attribute:
-
-```js
-// The coordinator catches the bubbled event and closes all siblings automatically.
-document.getElementById('panel2').setAttribute('data-ln-toggle', 'open');
-```
-
----
-
-## 4. Integration Patterns
-
-### A. All-Closed by Default
-Simply omit the `="open"` value from all panels in the markup.
-```html
-<section id="panel1" data-ln-toggle class="collapsible">...</section>
-```
-
-### B. Persistent Accordion State (Across Page Reloads)
-Add `data-ln-persist` to the panels. Each panel saves its state in `localStorage` individually. The coordinator stays completely oblivious. On page load, whichever panel restores as `open` bubbles an event, and the coordinator handles the rest.
-```html
-<section id="panel1" data-ln-toggle data-ln-persist class="collapsible">...</section>
-```
-
-### C. Zero-Configuration Multi-Open
-If your requirements change and you want a "multi-open accordion" (where panels toggle independently without closing others), **you do not need any JavaScript options or class re-configuration**. Simply *remove the `data-ln-accordion` attribute* from the wrapper. The individual panels continue to work perfectly.
-
-### D. Nested Accordions
-Supported natively out of the box. Scoping is determined by DOM ancestry (using `element.closest('[data-ln-accordion]')`). Opening an inner accordion panel bubbles upwards, but the outer coordinator ignores it, allowing infinite nesting depth without any configuration.
-
----
-
-## 5. Common Implementation Pitfalls
-
-### 1. Padding on `.collapsible` directly
-The `.collapsible` container must have zero padding so it can transition to exactly `0px` height. Placing padding directly on `.collapsible` will cause a thin strip of content to remain visible even when closed. **Padding must live on the `.collapsible-body` child**.
-
-### 2. Double-Binding Attributes
-Never place `data-ln-toggle` and `data-ln-toggle-for` on the same element. One element is either a trigger or a panel, never both.
-
----
-
-## 6. Integration & Source Files
-
-- **Unified Bundle**: Loaded automatically with the main bundle:
-  ```html
-  <script src="dist/ln-ashlar.iife.js" defer></script>
-  ```
-- **Standalone IIFE**: For lightweight pages, load the standalone, self-registering IIFE version:
-  ```html
-  <script src="js/ln-accordion/ln-accordion.js" defer></script>
-  ```
-- **Active Source (ESM)**: Development source is located at [js/ln-accordion/src/ln-accordion.js](file:///c:/laragon/www/ln-ashlar/js/ln-accordion/src/ln-accordion.js).
-
----
-
-## Related
-- **[`ln-toggle`](../ln-toggle/README.md)** — Binary state primitive.
-- **Architecture deep-dive** — [`docs/js/accordion.md`](../../docs/js/accordion.md).
-- **Cross-component principles** — [`docs/architecture/data-flow.md`](../../docs/architecture/data-flow.md).
+# ln-accordion
+
+> A lightweight, stateless **Coordinator** that enforces a single-open rule across a list of independent `ln-toggle` panels.
+
+---
+
+## 1. Philosophy & The Coordinator Mindset
+
+In traditional frontend architectures, an accordion is a heavy, monolithic component that owns click events, height transitions, ARIA states, active-panel state, and storage persistence. 
+
+In `ln-ashlar`, `ln-accordion` is fundamentally different: **it is a pure coordinator**. It contains only 38 lines of JavaScript, carries zero internal state, and coordinates other highly-specialized primitives.
+
+Every accordion is a perfect synchronization of three orthogonal concerns:
+
+1. **State Primitive (`ln-toggle`)**: Each panel is an independent `ln-toggle` instance. It owns the binary `open`/`close` state, coordinates trigger buttons, synchronizes `aria-expanded`/`aria-controls`, and handles per-panel localStorage persistence (`data-ln-persist`). It is completely oblivious to the other panels or the fact that it is inside an accordion.
+2. **Animation Engine (CSS `.collapsible`)**: The height transition is handled entirely in Vanilla CSS via the `.collapsible` mixin (transitioning `grid-template-rows` from `0fr` to `1fr`). No JS framerate stuttering or inline height hacks.
+3. **The Coordinator (`ln-accordion`)**: Lives on the wrapper element. It enforces a single rule: *"When one panel opens, all other open panels in this group must close."*
+
+---
+
+## 2. Minimal Blueprint
+
+This is the standard HTML structure. The pairing of triggers and panels is by ID, keeping layout and proximity decoupled.
+
+```html
+<ul data-ln-accordion>
+    <li>
+        <!-- The Trigger -->
+        <header data-ln-toggle-for="panel1">
+            Section 1
+            <svg class="ln-icon ln-chevron" aria-hidden="true"><use href="#ln-icon-arrow-down"></use></svg>
+        </header>
+        <!-- The Collapsible Panel -->
+        <section id="panel1" data-ln-toggle="open" class="collapsible">
+            <article class="collapsible-body">
+                <p>Content 1 (Starts open).</p>
+            </article>
+        </section>
+    </li>
+    <li>
+        <header data-ln-toggle-for="panel2">
+            Section 2
+            <svg class="ln-icon ln-chevron" aria-hidden="true"><use href="#ln-icon-arrow-down"></use></svg>
+        </header>
+        <section id="panel2" data-ln-toggle class="collapsible">
+            <article class="collapsible-body">
+                <p>Content 2 (Starts closed).</p>
+            </article>
+        </section>
+    </li>
+</ul>
+```
+
+### Key Anatomy Rules
+- **The Wrapper (`data-ln-accordion`)**: Markers for the coordinator. Listens for bubbled events and coordinates siblings.
+- **The Trigger (`data-ln-toggle-for`)**: Click target that toggles the target panel ID. The chevron rotates automatically driven by `aria-expanded`.
+- **The Panel (`data-ln-toggle`)**: Creates the `ln-toggle` state instance. Value `open` or empty.
+- **The Body (`.collapsible-body`)**: Wraps actual content. Padding and margins must live here, not on the parent `.collapsible` (which needs zero padding to collapse to exactly `0px` height).
+
+---
+
+## 3. The Decoupled State & API Contract
+
+The coordinator has **zero public state** in JavaScript. The DOM is the source of truth, and **the HTML attribute is the sole contract**.
+
+### Attributes
+- `data-ln-accordion` on the wrapper creates the coordinator instance. It takes no values.
+
+### Events
+- **`ln-accordion:change`**: Dispatched on the wrapper after a panel opens and siblings close.
+  - `event.detail.target`: The HTML element of the panel that just opened.
+  ```js
+  document.addEventListener('ln-accordion:change', (e) => {
+      console.log('Active panel ID:', e.detail.target.id);
+  });
+  ```
+
+### Programmatic Control
+There are no `open()` or `close()` methods on the coordinator instance. To programmatically change panels, write directly to the target panel's attribute:
+
+```js
+// The coordinator catches the bubbled event and closes all siblings automatically.
+document.getElementById('panel2').setAttribute('data-ln-toggle', 'open');
+```
+
+---
+
+## 4. Integration Patterns
+
+### A. All-Closed by Default
+Simply omit the `="open"` value from all panels in the markup.
+```html
+<section id="panel1" data-ln-toggle class="collapsible">...</section>
+```
+
+### B. Persistent Accordion State (Across Page Reloads)
+Add `data-ln-persist` to the panels. Each panel saves its state in `localStorage` individually. The coordinator stays completely oblivious. On page load, whichever panel restores as `open` bubbles an event, and the coordinator handles the rest.
+```html
+<section id="panel1" data-ln-toggle data-ln-persist class="collapsible">...</section>
+```
+
+### C. Zero-Configuration Multi-Open
+If your requirements change and you want a "multi-open accordion" (where panels toggle independently without closing others), **you do not need any JavaScript options or class re-configuration**. Simply *remove the `data-ln-accordion` attribute* from the wrapper. The individual panels continue to work perfectly.
+
+### D. Nested Accordions
+Supported natively out of the box. Scoping is determined by DOM ancestry (using `element.closest('[data-ln-accordion]')`). Opening an inner accordion panel bubbles upwards, but the outer coordinator ignores it, allowing infinite nesting depth without any configuration.
+
+---
+
+## 5. Common Implementation Pitfalls
+
+### 1. Padding on `.collapsible` directly
+The `.collapsible` container must have zero padding so it can transition to exactly `0px` height. Placing padding directly on `.collapsible` will cause a thin strip of content to remain visible even when closed. **Padding must live on the `.collapsible-body` child**.
+
+### 2. Double-Binding Attributes
+Never place `data-ln-toggle` and `data-ln-toggle-for` on the same element. One element is either a trigger or a panel, never both.
+
+---
+
+## 6. Integration & Source Files
+
+- **Unified Bundle**: Loaded automatically with the main bundle:
+  ```html
+  <script src="dist/ln-ashlar.iife.js" defer></script>
+  ```
+- **Standalone IIFE**: For lightweight pages, load the standalone, self-registering IIFE version:
+  ```html
+  <script src="js/ln-accordion/ln-accordion.js" defer></script>
+  ```
+- **Active Source (ESM)**: Development source is located at [js/ln-accordion/src/ln-accordion.js](file:///c:/laragon/www/ln-ashlar/js/ln-accordion/src/ln-accordion.js).
+
+---
+
+## Related
+- **[`ln-toggle`](../ln-toggle/README.md)** — Binary state primitive.
+- **Cross-component principles** — [`docs/architecture/data-flow.md`](../../docs/architecture/data-flow.md).
+
+---
+
+## 🔧 Internals
+
+Source: `js/ln-accordion/ln-accordion.js`. Does not import or require any other component at runtime — it only needs `ln-toggle` loaded so the events it listens for exist (a consumer-side load-order coupling, not a source dependency).
+
+### Instance state
+
+| Field | Set by | Read by |
+|---|---|---|
+| `dom` | constructor argument | `destroy` (dispatch target, listener detach) |
+| `_onToggleOpen` | constructor | `addEventListener`/`removeEventListener` |
+
+That's the entirety of it — no cached toggle list, no active-panel pointer, no DOM reference cache. `dom.querySelectorAll('[data-ln-toggle]')` is re-run on every `ln-toggle:open` instead of cached, since the DOM is small and the event is user-driven (one per click).
+
+### Init
+
+`registerComponent` scans for `[data-ln-accordion]`, instantiates `_component(el)` per match, and reruns the scan via `MutationObserver` on `childList` add / `data-ln-accordion` attribute mutation. `_component(dom)` stores `dom`, binds `_onToggleOpen`, and listens for `ln-toggle:open` on `dom`. No initial DOM read, no event dispatched at init.
+
+### Reaction to a panel opening
+
+`ln-toggle` dispatches `ln-toggle:open` on the panel, which bubbles to the wrapper:
+
+1. `dom.querySelectorAll('[data-ln-toggle]')` — every toggle in the subtree.
+2. For each toggle that is not the one just opened and is currently `"open"`: `setAttribute('data-ln-toggle', 'close')`.
+3. Each write triggers that toggle's own `MutationObserver`-driven close pipeline (`before-close` cancelable event, class removal, `aria-expanded` sync, persistence write, `ln-toggle:close`) — the accordion never runs this logic itself, it only flips the attribute.
+4. After the loop: dispatch `ln-accordion:change` on the wrapper, `detail.target` = the panel that opened.
+
+The accordion is reactive, not a gate: cancelable toggle events are the toggle's own responsibility, and `:change` fires regardless of whether a `before-close` on a sibling gets cancelled.
+
+### Destroy
+
+Guards double-destroy, removes the `ln-toggle:open` listener, dispatches `ln-accordion:destroyed` (`detail.target` = the wrapper), deletes the instance reference. Child `ln-toggle` instances are untouched and keep working independently.
+
+### Event lifecycle
+
+| Event | Direction | `detail` | Notes |
+|---|---|---|---|
+| `ln-toggle:open` | in (bubble) | — | Only inbound event; `ln-toggle:close` is not listened to |
+| `ln-accordion:change` | out | `{ target }` = opened panel | Fires on every open, even if no sibling needed closing |
+| `ln-accordion:destroyed` | out | `{ target }` = wrapper | Inside `destroy()` |
+
+### Nested accordions
+
+Two `closest('[data-ln-accordion]')` ownership checks in `_onToggleOpen`: an early exit if the bubbled event's nearest accordion isn't `dom` (so an outer wrapper ignores an inner panel's open), and a per-candidate filter in the cascade scan (so nested-accordion toggles are skipped when closing siblings). Ownership is DOM ancestry, not JS bookkeeping — each accordion stays oblivious to any other accordion in the tree, supporting arbitrary nesting depth.
+
+### Why a separate `ln-toggle`
+
+Most toggle use cases (sidebars, dropdowns, expandable cards) aren't accordions. Splitting single-open coordination out keeps `ln-toggle` a pure individual-state primitive and lets `ln-accordion` opt in to the extra behavior at the wrapper level, driven entirely by attribute writes rather than instance method calls.