@livenetworks/ashlar 1.5.1 → 1.6.0

package/js/ln-table-coordinator/README.md

@@ -0,0 +1,73 @@
+# ln-table-coordinator
+
+A zero-dependency, per-instance, host-scoped coordinator component that wires external search hosts (`ln-search`), column filter popovers (`ln-filter`), header filter indicators, and clear button triggers to a single `ln-table`.
+
+`ln-table` itself is a Layer 1 primitive: it manages internal data state, virtual scroll rendering, pagination/windowing cache, row template cloning, cell formatting, and selection DOM state. `ln-table-coordinator` is the Layer 2 policy and mediator that wires external UI controls to `ln-table`.
+
+---
+
+## 🧭 Philosophy & Architecture
+
+1. **Layer Separation.** `ln-table` manages its own internal table state and DOM subtree only — no external DOM querying, no external input mirroring, and no visual indicator class toggles on header buttons. `ln-table-coordinator` handles all project UI wiring on top.
+2. **Host-Scoped, Per-Instance.** The coordinator is a real component: `[data-ln-table-coordinator]` is a **required wrapper**. Its handlers are bound to its own host element (`self.dom`), not `document`. The table, its `[data-ln-filter]` popovers, and its clear button(s) must all be descendants of the same coordinator host — outside its own subtree, the coordinator does not exist and does not look.
+3. **Event-Driven Communication.** Communication with `ln-table` occurs strictly via CustomEvents (`ln-table:set-search`, `ln-table:set-filter`, `ln-table:request-clear-filters`).
+
+**Breaking change:** a data-driven table's search/filter/clear-all only works when wrapped in `[data-ln-table-coordinator]`. There is no page-wide fallback — the coordinator does not resolve a table by scanning the whole document.
+
+---
+
+## 🛠️ Declarative API & Wire Contract
+
+| Target / Trigger | Event / Trigger | Behavior |
+| :--- | :--- | :--- |
+| `[data-ln-search="tableId"]` (delivered by `ln-search` directly to the table) | `ln-search:change` | Guards `e.target` carries `data-ln-table` and `data-ln-table-source` (data-driven only), dispatches `ln-table:set-search`. |
+| `[data-ln-filter="tableId"]` (delivered by `ln-filter` directly to the table) | `ln-filter:changed` | Guards `e.target` carries `data-ln-table`, toggles `.ln-filter-active` indicator on filter button, dispatches `ln-table:set-filter`. |
+| `[data-ln-table-clear]`, `[data-ln-table-clear-all]` | `click` | Resolves the table structurally within this host, clears the linked search input and filter reset checkboxes, removes `.ln-filter-active` visual classes, dispatches `ln-table:request-clear-filters`. |
+| Document | `keydown` (`'/'`) | Focuses the search input inside the active coordinator wrapper on the page (or the first `[data-ln-search]` if none). |
+
+Column filters (`data-ln-table-filter-col`) and clear-all (`data-ln-table-clear` / `data-ln-table-clear-all`) route through `ln-table-coordinator` in both SSR and data-driven modes — an SSR table using them still requires the `[data-ln-table-coordinator]` wrapper, even though SSR search and sort do not (see below).
+
+Search is the one asymmetric control: the coordinator only intercepts search for **data-driven** tables. SSR tables self-bind `ln-search:change` directly (see [`js/ln-table/README.md`](../ln-table/README.md)) and never need the wrapper for search alone.
+
+---
+
+## ⚡ Consumed & Dispatched Events
+
+### Consumed Events
+- `ln-search:change` (on `self.dom`, the coordinator host)
+- `ln-filter:changed` (on `self.dom`)
+- `click` (on `self.dom` — targets `[data-ln-table-clear]` and `[data-ln-table-clear-all]`)
+- `keydown` (`document` — key `'/'`, the sole document-level exception, see below)
+
+### Dispatched Events
+- `ln-table:set-search` (Target: the table inside this host, Payload: `{ query, term, table }`)
+- `ln-table:set-filter` (Target: the table inside this host, Payload: `{ key, values, table }`)
+- `ln-table:request-clear-filters` (Target: the table inside this host, Payload: `{ table }`)
+
+The coordinator does not dispatch anything from its own host element — it has no outward/notification event. It only relays inward, to the table.
+
+---
+
+## 🔧 Internals
+
+Source: `js/ln-table-coordinator/src/ln-table-coordinator.js`. This is a real per-instance component: `_component(dom)` calls `_bindEvents(self)`, which stores its three listeners on `self._handlers` and attaches them to `self.dom` — mirroring the `js/ln-data-coordinator` idiom. `destroy()` removes all three symmetrically and clears `self._handlers`. `registerComponent` also supplies the `window.lnTableCoordinator` double-load guard.
+
+### Search
+
+`ln-search` dispatches `ln-search:change` directly on its resolved target (`document.getElementById(targetId)`) — when that target IS the table, `e.target` already carries `data-ln-table`. The coordinator does no ID resolution for search, only a guard: `e.target` must carry both `data-ln-table` and `data-ln-table-source` (data-driven). An SSR table caught by this listener is a markup mistake — it self-binds `ln-search:change` on its own, and wrapping it in `[data-ln-table-coordinator]` would double-fire; the `data-ln-table-source` guard prevents that.
+
+### Column-filter indicator
+
+`ln-filter` dispatches `ln-filter:changed` on both its own `<ul data-ln-filter>` root and, if different, directly on the table via `getElementById` — again, no ID resolution needed, only the `data-ln-table` guard. On a match, the coordinator finds the `th[data-ln-table-filter-col="key"]` and toggles `.ln-filter-active` on that header's `[data-ln-table-col-filter]` button based on `values.length > 0`, then dispatches `ln-table:set-filter`. This header-indicator class is Layer-2 policy — which is exactly why `ln-table` itself never sets it.
+
+### Clear
+
+A `click` on `[data-ln-table-clear]` / `[data-ln-table-clear-all]` has no ID binding of its own, so it resolves structurally: `clearBtn.closest('[data-ln-table]')`, falling back to `dom.querySelector('[data-ln-table]')` — always scoped to this host, never document-wide. It then runs: (1) strip `.ln-filter-active` off every filter button in the table, (2) blank the linked search input (scoped to this host), (3) check each linked filter popover's `[data-ln-filter-reset]` and fire a bubbling `change`, (4) dispatch `ln-table:request-clear-filters`.
+
+### `/` focus shortcut
+
+The sole deliberate exception to host-scoping. It remains a single `document`-level `keydown` listener registered once at module scope (outside `_component`/`_bindEvents`) — a page-level keyboard affordance, not coordination between a host and its children. Registering it per-instance would fire it once per coordinator on the page. It focuses the search input inside the active `[data-ln-table-coordinator]` wrapper, or the first `[data-ln-search]` on the page if none. Ignored when focus is already in an `INPUT`/`TEXTAREA`, or when the event was already `defaultPrevented`.
+
+### Multi-coordinator isolation
+
+Each `_component(dom)` instance closures its handlers over its own `dom`; `addEventListener` on a specific host node only fires for events whose bubble path passes through that node. Two coordinator hosts on the same page cannot see each other's descendants' events — no shared/global state exists to leak. The `/` shortcut is the sole intentional exception to this isolation — it is document-scoped by design.

package/js/ln-table-coordinator/ln-table-coordinator.js

@@ -0,0 +1 @@
+(function(){"use strict";if(typeof window<"u"){const t=console.warn;console.warn=function(...e){typeof e[0]=="string"&&(e[0].startsWith("[ln-")||e[0].startsWith("[lnCore"))&&!(document.documentElement.hasAttribute("data-ln-debug")||document.body&&document.body.hasAttribute("data-ln-debug"))||t.apply(console,e)}}const b={};function O(t,e){b[t]||(b[t]=document.querySelector('[data-ln-template="'+t+'"]'));const i=b[t];return i?i.content.cloneNode(!0):(console.warn("["+(e||"ln-core")+'] Template "'+t+'" not found'),null)}function g(t,e,i){t.dispatchEvent(new CustomEvent(e,{bubbles:!0,detail:i||{}}))}function E(t,e){if(!t||!e)return t;const i=t.querySelectorAll("[data-ln-field]");for(let n=0;n<i.length;n++){const l=i[n],r=l.getAttribute("data-ln-field");e[r]!=null&&(l.textContent=e[r])}const f=t.querySelectorAll("[data-ln-attr]");for(let n=0;n<f.length;n++){const l=f[n],r=l.getAttribute("data-ln-attr").split(",");for(let a=0;a<r.length;a++){const d=r[a].trim().split(":");if(d.length!==2)continue;const u=d[0].trim(),c=d[1].trim();e[c]!=null&&l.setAttribute(u,e[c])}}const s=t.querySelectorAll("[data-ln-show]");for(let n=0;n<s.length;n++){const l=s[n],r=l.getAttribute("data-ln-show");r in e&&l.classList.toggle("hidden",!e[r])}const o=t.querySelectorAll("[data-ln-class]");for(let n=0;n<o.length;n++){const l=o[n],r=l.getAttribute("data-ln-class").split(",");for(let a=0;a<r.length;a++){const d=r[a].trim().split(":");if(d.length!==2)continue;const u=d[0].trim(),c=d[1].trim();c in e&&l.classList.toggle(u,!!e[c])}}return t}function D(t,e){t.matches&&t.matches("[data-ln-form], [data-ln-fillable]")&&t.dispatchEvent(new CustomEvent("ln-fill",{detail:e??null,bubbles:!0}));const i=t.querySelectorAll("[data-ln-form], [data-ln-fillable]");for(let f=0;f<i.length;f++)i[f].dispatchEvent(new CustomEvent("ln-fill",{detail:e??null,bubbles:!0}));return t}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore._fillBound||(window.lnCore._fillBound=!0,document.addEventListener("ln-fill",function(t){if(!(!t.target.matches||!t.target.matches("[data-ln-fillable]")))if(t.detail)E(t.target,t.detail);else{const e=t.target.querySelectorAll("[data-ln-field]");for(let i=0;i<e.length;i++)e[i].textContent=""}})));function S(t,e){if(!t||!e)return t;const i=document.createTreeWalker(t,NodeFilter.SHOW_TEXT);for(;i.nextNode();){const o=i.currentNode;o.textContent.indexOf("{{")!==-1&&(o.textContent=o.textContent.replace(/\{\{\s*(\w+)\s*\}\}/g,function(n,l){return e[l]!==void 0?e[l]:""}))}const f=function(o,n){return e[n]!==void 0?e[n]:""},s=Array.from(t.querySelectorAll("*"));t.nodeType===1&&s.push(t);for(let o=0;o<s.length;o++){const n=s[o],l=n.attributes;for(let r=0;r<l.length;r++){const a=l[r];a.value.indexOf("{{")!==-1&&n.setAttribute(a.name,a.value.replace(/\{\{\s*(\w+)\s*\}\}/g,f))}}return t}function I(t,e,i,f,s,o){const n={};for(let r=0;r<t.children.length;r++){const a=t.children[r],d=a.getAttribute("data-ln-key");d&&(n[d]=a)}const l=document.createDocumentFragment();for(let r=0;r<e.length;r++){const a=e[r],d=String(f(a));let u=n[d];if(u)s(u,a,r);else{const c=O(i,o);if(!c||(S(c,a),u=c.firstElementChild,!u))continue;u.setAttribute("data-ln-key",d),s(u,a,r)}l.appendChild(u)}t.textContent="",t.appendChild(l)}function L(t,e){if(!document.body){document.addEventListener("DOMContentLoaded",function(){L(t,e)}),console.warn("["+e+'] Script loaded before <body> — add "defer" to your <script> tag');return}t()}function y(t,e,i,f){if(t.nodeType!==1)return;const o=e.indexOf("[")!==-1||e.indexOf(".")!==-1||e.indexOf("#")!==-1?e:"["+e+"]",n=Array.from(t.querySelectorAll(o));t.matches&&t.matches(o)&&n.push(t);for(const l of n)l[i]||(l[i]=new f(l))}function M(t,e,i,f,s={}){const o=s.extraAttributes||[],n=s.onAttributeChange||null,l=s.onInit||null;function r(a){const d=a||document.body;y(d,t,e,i),l&&l(d)}return L(function(){const a=new MutationObserver(function(u){for(let c=0;c<u.length;c++){const m=u[c];if(m.type==="childList"){for(let h=0;h<m.addedNodes.length;h++){const p=m.addedNodes[h];p.nodeType===1&&(y(p,t,e,i),l&&l(p))}for(let h=0;h<m.removedNodes.length;h++){const p=m.removedNodes[h];if(p.nodeType===1){const _=t.indexOf("[")!==-1||t.indexOf(".")!==-1||t.indexOf("#")!==-1?t:"["+t+"]",C=Array.from(p.querySelectorAll(_));p.matches&&p.matches(_)&&C.push(p);for(let v=0;v<C.length;v++){const N=C[v];if(!document.contains(N)){const A=N[e];A&&typeof A.destroy=="function"&&A.destroy()}}}}}else m.type==="attributes"&&(n&&m.target[e]?n(m.target,m.attributeName):(y(m.target,t,e,i),l&&l(m.target)))}});let d=[];if(t.indexOf("[")!==-1){const u=/\[([\w-]+)/g;let c;for(;(c=u.exec(t))!==null;)d.push(c[1])}else d.push(t);a.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:d.concat(o)})},f),window[e]=r,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){r(document.body)}):r(document.body),r}const T={};function j(t,e){T[t]=e}function B(t){return T[t]||{ingress:e=>e,egress:e=>e}}const q={};function x(t,e){if(!t||typeof e!="object")return;const i=t.toLowerCase().split("-")[0];q[i]=e}function R(t){if(!t)return null;const e=t.toLowerCase().split("-")[0];return q[e]||null}x("mk",{monthsLong:["јануари","февруари","март","април","мај","јуни","јули","август","септември","октомври","ноември","декември"],monthsShort:["јан","фев","мар","апр","мај","јун","јул","авг","септ","окт","ноем","дек"],daysLong:["недела","понеделник","вторник","среда","четврток","петок","сабота"],daysShort:["нед","пон","вт","ср","чет","пет","саб"]}),typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=j,window.lnCore.getDataMapper=B,window.lnCore.registerLocaleFallback=x,window.lnCore.getLocaleFallback=R,window.lnCore.fillTemplate=S,window.lnCore.fill=E,window.lnCore.lnFill=D,window.lnCore.renderList=I);function k(t){return(t||"").replace(/^#/,"")}function w(t){const e=t===void 0?location.hash:t,i={},f=k(e);if(!f)return i;const s=f.split("&");for(let o=0;o<s.length;o++){const n=s[o];if(!n)continue;const l=n.indexOf(":"),r=l>-1?n.slice(0,l):n,a=l>-1?n.slice(l+1):"";if(r)try{i[r]=decodeURIComponent(a)}catch{i[r]=a}}return i}function W(t){if(!t)return null;const e=w();return t in e?e[t]:null}function F(t,e){if(!t)return;const i=w();e==null?delete i[t]:i[t]=String(e);const s=Object.keys(i).map(function(o){const n=i[o];return n===""?o:o+":"+encodeURIComponent(n)}).join("&");k(location.hash)!==s&&(location.hash=s)}function U(t){return t.button===1||t.ctrlKey||t.metaKey||t.shiftKey?!1:(t.preventDefault(),!0)}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.hashParse=w,window.lnCore.hashGet=W,window.lnCore.hashSet=F,window.lnCore.hashLinkClick=U),(function(){const t="data-ln-table-coordinator",e="lnTableCoordinator";if(window[e]!==void 0)return;document.addEventListener("keydown",function(s){if(s.key!=="/"||s.defaultPrevented||document.activeElement&&(document.activeElement.tagName==="INPUT"||document.activeElement.tagName==="TEXTAREA"))return;const o=document.querySelector("["+t+"] [data-ln-search]")||document.querySelector("[data-ln-search]");if(!o)return;const n=o.tagName==="INPUT"||o.tagName==="TEXTAREA"?o:o.querySelector('input[type="search"], input[type="text"], input');n&&(s.preventDefault(),n.focus())});function i(s){return this.dom=s,f(this),this}function f(s){const o=s.dom;s._handlers={search:function(n){const l=n.target;if(!l.hasAttribute||!l.hasAttribute("data-ln-table")||!l.lnTable||!l.hasAttribute("data-ln-table-source"))return;n.preventDefault();const r=n.detail&&n.detail.term!=null?n.detail.term:"",a=l.lnTable.name||l.id;g(l,"ln-table:set-search",{query:r,term:r,table:a})},filter:function(n){if(!n.detail)return;const l=n.target;if(!l.hasAttribute||!l.hasAttribute("data-ln-table")||!l.lnTable)return;const r=n.detail.key,a=n.detail.values||[],d=l.lnTable.name||l.id,u=l.querySelectorAll("th");for(let c=0;c<u.length;c++)if(u[c].getAttribute("data-ln-table-filter-col")===r){const m=u[c].querySelector("[data-ln-table-col-filter]");m&&m.classList.toggle("ln-filter-active",a.length>0);break}g(l,"ln-table:set-filter",{key:r,values:a,table:d})},clear:function(n){const l=n.target.closest("[data-ln-table-clear], [data-ln-table-clear-all]");if(!l)return;const r=l.closest("[data-ln-table]")||o.querySelector("[data-ln-table]");if(!r||!r.lnTable)return;const a=r.lnTable.name||r.id,d=r.querySelectorAll("th");for(let h=0;h<d.length;h++){const p=d[h].querySelector("[data-ln-table-col-filter]");p&&p.classList.remove("ln-filter-active")}const u=r.id,c=u&&o.querySelector('[data-ln-search="'+u+'"]')||o.querySelector("[data-ln-search]");if(c){const h=c.tagName==="INPUT"||c.tagName==="TEXTAREA"?c:c.querySelector("input");h&&(h.value="")}const m=u&&o.querySelectorAll('[data-ln-filter="'+u+'"]')||o.querySelectorAll("[data-ln-filter]");for(let h=0;h<m.length;h++){const p=m[h].querySelector("[data-ln-filter-reset]");p&&(p.checked=!0,p.dispatchEvent(new Event("change",{bubbles:!0})))}g(r,"ln-table:request-clear-filters",{table:a})}},o.addEventListener("ln-search:change",s._handlers.search),o.addEventListener("ln-filter:changed",s._handlers.filter),o.addEventListener("click",s._handlers.clear)}i.prototype.destroy=function(){this.dom[e]&&(this._handlers&&(this.dom.removeEventListener("ln-search:change",this._handlers.search),this.dom.removeEventListener("ln-filter:changed",this._handlers.filter),this.dom.removeEventListener("click",this._handlers.clear),this._handlers=null),delete this.dom[e])},M(t,e,i,"ln-table-coordinator")})()})();

package/js/ln-table-coordinator/src/ln-table-coordinator.js

@@ -0,0 +1,160 @@
+import { registerComponent, dispatch } from '../../ln-core';
+
+(function () {
+	const DOM_SELECTOR = 'data-ln-table-coordinator';
+	const DOM_ATTRIBUTE = 'lnTableCoordinator';
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+	// ─── Keyboard Navigation Search Focus ('/' shortcut) ──
+	// Deliberate, user-approved exception to host-scoping: this is a
+	// page-level keyboard affordance, not coordination between a host and
+	// its children, so it stays a single module-scope document listener
+	// exactly as it behaves today (unchanged resolution order). Registering
+	// it per-instance inside _bindEvents would fire it once per coordinator
+	// on the page — this is why it lives outside _component/_bindEvents.
+
+	document.addEventListener('keydown', function (e) {
+		if (e.key !== '/') return;
+		if (e.defaultPrevented) return;
+		if (document.activeElement && (document.activeElement.tagName === 'INPUT' || document.activeElement.tagName === 'TEXTAREA')) return;
+
+		// Resolve search input inside active coordinator wrapper or first visible search
+		const searchHost = document.querySelector('[' + DOM_SELECTOR + '] [data-ln-search]') || document.querySelector('[data-ln-search]');
+		if (!searchHost) return;
+
+		const input = (searchHost.tagName === 'INPUT' || searchHost.tagName === 'TEXTAREA')
+			? searchHost
+			: searchHost.querySelector('input[type="search"], input[type="text"], input');
+
+		if (input) {
+			e.preventDefault();
+			input.focus();
+		}
+	});
+
+	// ─── Component Constructor ─────────────────────────────
+
+	function _component(dom) {
+		this.dom = dom;
+		_bindEvents(this);
+		return this;
+	}
+
+	// ─── Event Binding (host-scoped — own subtree only) ────
+
+	function _bindEvents(self) {
+		const dom = self.dom;
+
+		self._handlers = {
+			// ln-search dispatches ln-search:change directly on its resolved
+			// target — when that target IS the table, e.target already carries
+			// data-ln-table. No ID resolution needed here, only a guard.
+			search: function (e) {
+				const table = e.target;
+				if (!table.hasAttribute || !table.hasAttribute('data-ln-table')) return;
+				if (!table.lnTable) return;
+				// SSR tables self-bind ln-search:change directly (see ln-table.js) —
+				// the coordinator only owns the data-driven path. A table wrapped
+				// here that happens to be SSR is a markup mistake (rule: coordinator
+				// is data-driven-only); this guard prevents a double-fire rather
+				// than silently mishandling it.
+				if (!table.hasAttribute('data-ln-table-source')) return;
+
+				e.preventDefault();
+				const term = e.detail && e.detail.term != null ? e.detail.term : '';
+				const name = table.lnTable.name || table.id;
+
+				dispatch(table, 'ln-table:set-search', { query: term, term: term, table: name });
+			},
+
+			// ln-filter dispatches ln-filter:changed on both its own <ul> root
+			// and (if different) directly on the table via getElementById — same
+			// reasoning: no ID resolution needed, only a guard.
+			filter: function (e) {
+				if (!e.detail) return;
+				const table = e.target;
+				if (!table.hasAttribute || !table.hasAttribute('data-ln-table')) return;
+				if (!table.lnTable) return;
+
+				const key = e.detail.key;
+				const values = e.detail.values || [];
+				const name = table.lnTable.name || table.id;
+
+				// Header filter-button indicator — Layer 2 policy; ln-table itself
+				// never sets this class.
+				const ths = table.querySelectorAll('th');
+				for (let i = 0; i < ths.length; i++) {
+					if (ths[i].getAttribute('data-ln-table-filter-col') === key) {
+						const btn = ths[i].querySelector('[data-ln-table-col-filter]');
+						if (btn) btn.classList.toggle('ln-filter-active', values.length > 0);
+						break;
+					}
+				}
+
+				dispatch(table, 'ln-table:set-filter', { key: key, values: values, table: name });
+			},
+
+			// Clear-all has no ID binding of its own — resolve structurally,
+			// scoped to this host only (never document-wide).
+			clear: function (e) {
+				const clearBtn = e.target.closest('[data-ln-table-clear], [data-ln-table-clear-all]');
+				if (!clearBtn) return;
+
+				const table = clearBtn.closest('[data-ln-table]') || dom.querySelector('[data-ln-table]');
+				if (!table || !table.lnTable) return;
+
+				const name = table.lnTable.name || table.id;
+
+				const ths = table.querySelectorAll('th');
+				for (let i = 0; i < ths.length; i++) {
+					const filterBtn = ths[i].querySelector('[data-ln-table-col-filter]');
+					if (filterBtn) filterBtn.classList.remove('ln-filter-active');
+				}
+
+				const tableId = table.id;
+				const searchEl = (tableId && dom.querySelector('[data-ln-search="' + tableId + '"]'))
+					|| dom.querySelector('[data-ln-search]');
+				if (searchEl) {
+					const input = (searchEl.tagName === 'INPUT' || searchEl.tagName === 'TEXTAREA')
+						? searchEl
+						: searchEl.querySelector('input');
+					if (input) input.value = '';
+				}
+
+				const filters = (tableId && dom.querySelectorAll('[data-ln-filter="' + tableId + '"]'))
+					|| dom.querySelectorAll('[data-ln-filter]');
+				for (let i = 0; i < filters.length; i++) {
+					const resetInput = filters[i].querySelector('[data-ln-filter-reset]');
+					if (resetInput) {
+						resetInput.checked = true;
+						resetInput.dispatchEvent(new Event('change', { bubbles: true }));
+					}
+				}
+
+				dispatch(table, 'ln-table:request-clear-filters', { table: name });
+			}
+		};
+
+		dom.addEventListener('ln-search:change', self._handlers.search);
+		dom.addEventListener('ln-filter:changed', self._handlers.filter);
+		dom.addEventListener('click', self._handlers.clear);
+	}
+
+	// ─── Destroy ────────────────────────────────────────────
+
+	_component.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+
+		if (this._handlers) {
+			this.dom.removeEventListener('ln-search:change', this._handlers.search);
+			this.dom.removeEventListener('ln-filter:changed', this._handlers.filter);
+			this.dom.removeEventListener('click', this._handlers.clear);
+			this._handlers = null;
+		}
+
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-table-coordinator');
+})();

package/js/ln-tabs/README.md

@@ -1,137 +1,221 @@
-# ln-tabs
-
-> N-way exclusive panel selection on a single container, managed reactively via the DOM.
-
----
-
-## 1. Philosophy & The Tabs Mindset
-
-In `ln-ashlar`, the core design principle is **orthogonality**. Rather than creating heavy components that mix state, visual presentation, and layout, `ln-tabs` separates them into isolated concerns:
-
-1. **State & ARIA (JavaScript)**: The `ln-tabs` component (145 lines) only manages the active tab key in the DOM, maps namespace URL hashes, handles optional `localStorage` persistence, and synchronizes ARIA accessibility. It possesses zero visual styles.
-2. **Visual Presentation (CSS)**: Visual layouts, borders, alignments, and active indicator designs are handled in Vanilla CSS. The library ships mixins like `@mixin tabs-nav`, `@mixin tabs-tab`, and `@mixin tabs-panel` to handle this elegantly.
-3. **Decoupled Binding (HTML)**: Tab triggers and panels are paired purely by string keys (`data-ln-tab="key"` and `data-ln-panel="key"`), decoupled from their relative DOM positions.
-
-### Why not built on `ln-toggle`?
-While similar on the surface, their contracts diverge. `ln-toggle` is a binary disclosure primitive (using `aria-expanded`). `ln-tabs` is an N-way exclusive tablist (using `aria-selected` and `aria-hidden`) that supports advanced, namespace-scoped URL deep-linking out of the box.
-
----
-
-## 2. Minimal Blueprint
-
-Triggers and panels are bound via matching keys inside a wrapper. Inactive panels must carry `class="hidden"` to prevent a layout flash before initialization.
-
-```html
-<section id="user-tabs" data-ln-tabs data-ln-tabs-default="info">
-    <!-- Tab list (triggers) -->
-    <nav>
-        <button type="button" data-ln-tab="info">Information</button>
-        <button type="button" data-ln-tab="settings">Settings</button>
-    </nav>
-
-    <!-- Tab panels -->
-    <section data-ln-panel="info">
-        <p>This is the info panel.</p>
-    </section>
-    <section data-ln-panel="settings" class="hidden">
-        <p>This is the settings panel.</p>
-    </section>
-</section>
-```
-
-### Key Anatomy Rules
-- **The Wrapper (`data-ln-tabs`)**: Creates the tabs root instance.
-- **The Trigger (`data-ln-tab="key"`)**: Marks the element as a click target. Must be a `<button>` (with `type="button"` inside forms) or an `<a>` anchor.
-- **The Panel (`data-ln-panel="key"`)**: Matches the trigger by key. Inactive panels must carry `class="hidden"`.
-
----
-
-## 3. The Declarative API & State Contract
-
-There are no imperative JavaScript methods (like `activate()` or `open()`) on the component instance. **The HTML attribute is the sole contract.** 
-
-Clicks, URL hash changes, localStorage restorations, and external scripts all change state by writing the active attribute on the wrapper:
-
-```js
-const tabs = document.getElementById('user-tabs');
-
-// Canonical write — switches the active tab
-tabs.setAttribute('data-ln-tabs-active', 'settings');
-
-// Read-only state query
-tabs.getAttribute('data-ln-tabs-active'); // Returns currently active key
-```
-
-### Attributes
-- `data-ln-tabs`: Placed on the wrapper to create the instance.
-- `data-ln-tabs-active`: Currently active key (written by the component, watched by the observer).
-- `data-ln-tabs-default="key"`: Default key selected on load. Falls back to the first tab trigger if omitted.
-- `data-ln-tabs-focus="false"`: Opt out of auto-focusing the first focusable element inside the active panel. Default: enabled.
-- `data-ln-tabs-key="name"`: Hash namespace. Falls back to wrapper `id` if omitted.
-- `id="name"`: Enables hash sync. The wrapper `id` acts as the URL namespace key.
-- `data-ln-persist`: Saves the active tab key in `localStorage` (effective only when hash sync is OFF).
-
----
-
-## 4. Transition Events
-
-All events bubble. The dispatch target is the wrapper element.
-
-| Event | Cancelable | `detail` | Dispatched When |
-|---|---|---|---|
-| **`ln-tabs:change`** | No | `{ key, tab, panel }` | After the active panel is swapped, ARIA synced, focus moved (if enabled), and localStorage updated. |
-| **`ln-tabs:destroyed`** | No | `{ target }` | Inside `destroy()`, after removing click and hashchange listeners. |
-
-```js
-// Example: Listen for tab changes
-document.addEventListener('ln-tabs:change', (e) => {
-    console.log(`Active tab in ${e.target.id} changed to: ${e.detail.key}`);
-});
-```
-
----
-
-## 5. Integration Patterns
-
-### A. Hash-Deep-Linkable Tabs (URL-as-State)
-Add an `id` to the wrapper. Clicking tabs automatically writes to the URL hash (e.g. `#user-tabs:settings`). Sharing, bookmarking, or using back/forward buttons restores the active tab on load.
-```html
-<section id="user-tabs" data-ln-tabs data-ln-tabs-default="info">...</section>
-```
-
-### B. Anchor Triggers (Deep Links)
-Use `<a>` triggers with matching `href` format and boolean `data-ln-tab` attributes. Right-click copy link and middle-click "open in new tab" work out of the box.
-```html
-<a href="#user-tabs:info" data-ln-tab>Information</a>
-<a href="#user-tabs:settings" data-ln-tab>Settings</a>
-```
-
-### C. Multiple Independent Tabsets
-Multiple independent tabsets on the same page will coexist cleanly in the URL hash, namespaced by their respective wrapper `id`s (e.g., `#user-tabs:settings&project-tabs:members`).
-
-### D. Persistent Tabs (Without URL Hash)
-Omit the wrapper `id` and add `data-ln-persist="key"` to remember the active tab in `localStorage` without changing the URL hash.
-```html
-<section data-ln-tabs data-ln-persist="settings-tabs" data-ln-tabs-default="general">...</section>
-```
-
----
-
-## 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-tabs/ln-tabs.js" defer></script>
-  ```
-- **Active Source (ESM)**: Development source is located at [js/ln-tabs/src/ln-tabs.js](file:///c:/laragon/www/ln-ashlar/js/ln-tabs/src/ln-tabs.js).
-
----
-
-## Related
-- **[`ln-toggle`](../ln-toggle/README.md)** — Binary disclosure state primitive.
-- **[`ln-accordion`](../ln-accordion/README.md)** — Single-open coordinator built on `ln-toggle`.
-- **Architecture deep-dive** — [`docs/js/tabs.md`](../../docs/js/tabs.md).
+# ln-tabs
+
+> N-way exclusive panel selection on a single container, managed reactively via the DOM.
+
+---
+
+## 1. Philosophy & The Tabs Mindset
+
+In `ln-ashlar`, the core design principle is **orthogonality**. Rather than creating heavy components that mix state, visual presentation, and layout, `ln-tabs` separates them into isolated concerns:
+
+1. **State & ARIA (JavaScript)**: The `ln-tabs` component (145 lines) only manages the active tab key in the DOM, maps namespace URL hashes, handles optional `localStorage` persistence, and synchronizes ARIA accessibility. It possesses zero visual styles.
+2. **Visual Presentation (CSS)**: Visual layouts, borders, alignments, and active indicator designs are handled in Vanilla CSS. The library ships mixins like `@mixin tabs-nav`, `@mixin tabs-tab`, and `@mixin tabs-panel` to handle this elegantly.
+3. **Decoupled Binding (HTML)**: Tab triggers and panels are paired purely by string keys (`data-ln-tab="key"` and `data-ln-panel="key"`), decoupled from their relative DOM positions.
+
+### Why not built on `ln-toggle`?
+While similar on the surface, their contracts diverge. `ln-toggle` is a binary disclosure primitive (using `aria-expanded`). `ln-tabs` is an N-way exclusive tablist (using `aria-selected` and `aria-hidden`) that supports advanced, namespace-scoped URL deep-linking out of the box.
+
+---
+
+## 2. Minimal Blueprint
+
+Triggers and panels are bound via matching keys inside a wrapper. Inactive panels must carry `class="hidden"` to prevent a layout flash before initialization.
+
+```html
+<section id="user-tabs" data-ln-tabs data-ln-tabs-default="info">
+    <!-- Tab list (triggers) -->
+    <nav>
+        <button type="button" data-ln-tab="info">Information</button>
+        <button type="button" data-ln-tab="settings">Settings</button>
+    </nav>
+
+    <!-- Tab panels -->
+    <section data-ln-panel="info">
+        <p>This is the info panel.</p>
+    </section>
+    <section data-ln-panel="settings" class="hidden">
+        <p>This is the settings panel.</p>
+    </section>
+</section>
+```
+
+### Key Anatomy Rules
+- **The Wrapper (`data-ln-tabs`)**: Creates the tabs root instance.
+- **The Trigger (`data-ln-tab="key"`)**: Marks the element as a click target. Must be a `<button>` (with `type="button"` inside forms) or an `<a>` anchor.
+- **The Panel (`data-ln-panel="key"`)**: Matches the trigger by key. Inactive panels must carry `class="hidden"`.
+
+---
+
+## 3. The Declarative API & State Contract
+
+There are no imperative JavaScript methods (like `activate()` or `open()`) on the component instance. **The HTML attribute is the sole contract.** 
+
+Clicks, URL hash changes, localStorage restorations, and external scripts all change state by writing the active attribute on the wrapper:
+
+```js
+const tabs = document.getElementById('user-tabs');
+
+// Canonical write — switches the active tab
+tabs.setAttribute('data-ln-tabs-active', 'settings');
+
+// Read-only state query
+tabs.getAttribute('data-ln-tabs-active'); // Returns currently active key
+```
+
+### Mode is set by the trigger type
+
+The wrapper runs in one of two modes, chosen by **what the triggers are** — not by any wrapper attribute:
+
+- **Anchor triggers** (`<a href="#…">`) → **URL hash sync**: shareable, bookmarkable, back/forward aware. Needs a namespace (`id` or `data-ln-tabs-key`) on the wrapper.
+- **Button triggers** (`<button>`) → **`localStorage` persist**, opt-in via `data-ln-persist`. The URL is never touched.
+
+Mixing both trigger types in one group falls back to persist mode and logs a console warning. An `id` on a button-driven group no longer forces hash mode — it is free to be a plain DOM id or the persist storage key.
+
+### Attributes
+- `data-ln-tabs`: Placed on the wrapper to create the instance.
+- `data-ln-tabs-active`: Currently active key (written by the component, watched by the observer).
+- `data-ln-tabs-default="key"`: Default key selected on load. Falls back to the first tab trigger if omitted.
+- `data-ln-tabs-focus="false"`: Opt out of auto-focusing the first focusable element inside the active panel. Default: enabled.
+- `data-ln-tabs-key="name"`: Hash namespace for anchor-trigger groups. Falls back to wrapper `id` if omitted.
+- `id="name"`: Doubles as the hash namespace for anchor-trigger groups when `data-ln-tabs-key` is absent. Does **not** select the mode — the trigger type does.
+- `data-ln-persist`: Saves the active tab key in `localStorage` for button-trigger groups. Boolean form keys off the wrapper `id`; explicit form is `data-ln-persist="custom-key"`.
+
+---
+
+## 4. Transition Events
+
+All events bubble. The dispatch target is the wrapper element.
+
+| Event | Cancelable | `detail` | Dispatched When |
+|---|---|---|---|
+| **`ln-tabs:change`** | No | `{ key, tab, panel }` | After the active panel is swapped, ARIA synced, focus moved (if enabled), and localStorage updated. |
+| **`ln-tabs:destroyed`** | No | `{ target }` | Inside `destroy()`, after removing click and hashchange listeners. |
+
+```js
+// Example: Listen for tab changes
+document.addEventListener('ln-tabs:change', (e) => {
+    console.log(`Active tab in ${e.target.id} changed to: ${e.detail.key}`);
+});
+```
+
+---
+
+## 5. Integration Patterns
+
+### A. Hash-Deep-Linkable Tabs (URL-as-State)
+Use **anchor triggers** and give the wrapper a namespace (`id` or `data-ln-tabs-key`). Clicking tabs writes to the URL hash (e.g. `#user-tabs:settings`); sharing, bookmarking, or using back/forward buttons restores the active tab on load.
+```html
+<section id="user-tabs" data-ln-tabs data-ln-tabs-default="info">
+    <nav>
+        <a href="#user-tabs:info" data-ln-tab>Information</a>
+        <a href="#user-tabs:settings" data-ln-tab>Settings</a>
+    </nav>
+    ...
+</section>
+```
+
+### B. Anchor Triggers (Deep Links)
+Use `<a>` triggers with matching `href` format and boolean `data-ln-tab` attributes. Right-click copy link and middle-click "open in new tab" work out of the box.
+```html
+<a href="#user-tabs:info" data-ln-tab>Information</a>
+<a href="#user-tabs:settings" data-ln-tab>Settings</a>
+```
+
+### C. Multiple Independent Tabsets
+Multiple independent tabsets on the same page will coexist cleanly in the URL hash, namespaced by their respective wrapper `id`s (e.g., `#user-tabs:settings&project-tabs:members`).
+
+### D. Persistent Tabs (Without URL Hash)
+Use **button triggers** and add `data-ln-persist="key"` to remember the active tab in `localStorage` without touching the URL. An `id` on the wrapper is fine — it no longer forces hash mode.
+```html
+<section data-ln-tabs data-ln-persist="settings-tabs" data-ln-tabs-default="general">
+    <nav>
+        <button type="button" data-ln-tab="general">General</button>
+        <button type="button" data-ln-tab="security">Security</button>
+    </nav>
+    ...
+</section>
+```
+
+---
+
+## 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-tabs/ln-tabs.js" defer></script>
+  ```
+- **Active Source (ESM)**: Development source is located at [js/ln-tabs/src/ln-tabs.js](file:///c:/laragon/www/ln-ashlar/js/ln-tabs/src/ln-tabs.js).
+
+---
+
+## Hash codec (ln-core shared)
+
+ln-tabs uses the shared ln-core hash codec (`hashGet` / `hashSet` /
+`hashParse` from `js/ln-core/hash.js`) instead of a private parser. The
+grammar and behaviour are unchanged — anchor-trigger groups still produce
+`#nsKey:activeKey` fragments, still respond to `hashchange`, and still
+support back/forward navigation.
+
+**Foreign-segment preservation.** Because `hashSet` is a
+read-modify-write that updates only the tabs namespace, switching a tab
+now preserves any hash segment written by another component. For example,
+if a hash-bound modal is open (`#demo-edit:5`), switching a tab produces
+`#demo-edit:5&demo-tab:members` — the modal segment is not cleared.
+
+No markup or API change — this is an internal implementation improvement.
+
+---
+
+## 🔧 Internals
+
+Source: `js/ln-tabs/ln-tabs.js`. Zero cross-component imports — only `ln-core/helpers.js` (`registerComponent`, `dispatch`) and `ln-core/persist.js`.
+
+### State
+
+Each instance caches `tabs[]`/`panels[]` and derived `mapTabs`/`mapPanels` (keyed by lowercase-trimmed `data-ln-tab` value, or the resolved hash fragment for boolean anchors) once at init — re-querying happens only through `destroy()` + re-init, never on every activation. `nsKey`/`hashEnabled` are resolved *before* `mapTabs` is built, because anchor key derivation needs the namespace to pick the right hash fragment.
+
+### Init flow
+
+1. `registerComponent` scans for `[data-ln-tabs]`, with `extraAttributes: ['data-ln-tabs-active']` so the shared observer also watches writes to the active-key attribute (the real state channel), not just the marker attribute.
+2. The constructor caches tabs/panels, detects mode, builds the maps, resolves `defaultKey` and `autoFocus`, wires click handlers (guarded against double-attach).
+3. It branches on mode: hash-enabled groups attach `hashchange` and seed from the current URL immediately; persist groups optionally restore from `localStorage` *before* the first attribute write, so there's no flash of default-then-restored.
+4. The resulting `setAttribute('data-ln-tabs-active', …)` is what triggers `_applyActive` through the observer — the write, not a direct call, is the single activation path.
+
+### Activation order (`_applyActive`)
+
+1. An invalid key (typo, removed panel) silently resolves to `defaultKey` — permissive by design, the component is downstream of attribute writes.
+2. Tab buttons flip `data-active`/`aria-selected` first, then panels flip `.hidden`/`aria-hidden` — natural read order for assistive tech.
+3. Auto-focus is deferred one `setTimeout(0)` (the panel was just un-hidden; layout hasn't settled) with `{ preventScroll: true }`.
+4. Event dispatch happens after all DOM/ARIA writes; persistence save happens last, only when `data-ln-persist` is present and hash mode is off.
+
+### The hash round-trip
+
+Clicking an already-active anchor tab does not fire `hashchange` (the browser dedupes identical hash writes), so the click handler special-cases `location.hash === '#' + newHash` and force-writes the attribute directly instead of relying on the event. The same edge applies at boot: `_hashHandler()` is invoked once manually to seed state from a hash already present in the URL.
+
+### Anchor key derivation
+
+A non-empty `data-ln-tab` value wins if present; otherwise the `href` is split on `&`, matched against `nsKey`, and the substring after `:` is used; an anchor with no resolvable key is skipped with `console.warn`.
+
+### Destroy
+
+Idempotent. Detaches every click handler and clears their double-attach guards, detaches `hashchange` only if hash-enabled, dispatches `ln-tabs:destroyed`, deletes `dom.lnTabs`. Does NOT reset visual state (`data-active`/`aria-selected` survive), clear `localStorage`, or remove `data-ln-tabs-active` — a future re-init resumes from whatever is left.
+
+### Failure modes
+
+| Scenario | Behavior |
+|---|---|
+| Active key has no matching panel | Falls back to `defaultKey` silently |
+| Mixed anchor + button triggers in one group | Falls back to persist mode, `console.warn` |
+| `location.hash` references a foreign namespace | Ignored — `_hashHandler` reads only its own `nsKey` |
+| `localStorage` write throws (quota, private mode) | Swallowed in `persistSet`'s `try/catch` |
+| Tab button missing `type="button"` inside a form | Page navigates on click — markup bug, not defendable |
+
+---
+
+## Related
+- **[`ln-toggle`](../ln-toggle/README.md)** — Binary disclosure state primitive.
+- **[`ln-accordion`](../ln-accordion/README.md)** — Single-open coordinator built on `ln-toggle`.