@livenetworks/ashlar 1.4.1 → 1.6.0

package/js/ln-sort/README.md

@@ -0,0 +1,170 @@
+# ln-sort
+
+A zero-dependency, event-driven **Sort Control Primitive** that announces a sort intent on a
+target element via a cancelable event, letting tables, lists, or custom integrations intercept
+it or fall back to a built-in DOM-reorder default.
+
+It follows the same contract shape as `ln-search`: dispatch-only-to-target, cancelable,
+default-DOM-behaviour fallback. Unlike `ln-filter`, it never dual-dispatches to itself.
+
+---
+
+## 🧭 Philosophy & Architecture
+
+1. **No cycle logic in JS.** A click reads `data-ln-sort-dir` off the clicked button, writes it to
+   `data-ln-sort-state` on the root, and dispatches. The circular order
+   `none → asc → desc → none` is produced entirely by CSS — only one `<button data-ln-sort-dir>`
+   is visible at a time, selected by `[data-ln-sort-state]` on the root. See
+   `scss/config/mixins/_sort.scss`.
+2. **Field is optional.** Author `data-ln-sort-field="name"` when the target is data-driven
+   (server needs a name, not an index). Omit it inside a `<th>` to fall back to
+   `th.cellIndex` — SSR/DOM-only, resolved once at construction, never bridged to `field`.
+   The dispatched payload always carries both keys, exactly one non-null:
+   `{ field: string|null, column: number|null, direction, targetId }`.
+3. **Single sort, mutual exclusion via the target.** Every instance listens for
+   `ln-sort:change` on its OWN target (not on itself — events bubble up, listening on self would
+   never hear a sibling). When an incoming event's field/column doesn't match this instance's own,
+   it resets its own `data-ln-sort-state` to `"none"`. No registry, no sibling awareness.
+4. **Type is inferred once per sort, not per pair.** `ln-core.detectValueType` scans the current
+   value set; if every non-empty value is a finite number, comparison is numeric, else
+   `localeCompare` via `ln-core.getLocale`. Per-pair type inference breaks comparator
+   transitivity and produces wrong ordering — never do it.
+
+---
+
+## ✅ Canonical Markup
+
+```html
+<th>
+	<span>Name</span>
+	<ul data-ln-sort="users-table" data-ln-sort-field="name" data-ln-sort-state="none">
+		<li><button type="button" data-ln-sort-dir="asc" aria-label="Sort ascending"><svg class="ln-icon" aria-hidden="true"><use href="#ln-icon-arrows-sort"></use></svg></button></li>
+		<li><button type="button" data-ln-sort-dir="desc" aria-label="Sort descending"><svg class="ln-icon" aria-hidden="true"><use href="#ln-icon-arrow-up"></use></svg></button></li>
+		<li><button type="button" data-ln-sort-dir="none" aria-label="Remove sort"><svg class="ln-icon" aria-hidden="true"><use href="#ln-icon-arrow-down"></use></svg></button></li>
+	</ul>
+</th>
+```
+
+**Icon convention — READ BEFORE COPYING THIS MARKUP.** Each button carries the icon of the sort
+STATE it is visible in, never the icon of the direction it sets:
+
+| Button | Visible when `data-ln-sort-state` = | Icon it carries |
+|---|---|---|
+| `data-ln-sort-dir="asc"` | `none` | `#ln-icon-arrows-sort` |
+| `data-ln-sort-dir="desc"` | `asc` | `#ln-icon-arrow-up` |
+| `data-ln-sort-dir="none"` | `desc` | `#ln-icon-arrow-down` |
+
+**This is not a typo.** The `dir="desc"` button contains an UP arrow. The visible button always
+performs the NEXT action (clicking `dir="desc"` sorts descending), but its icon always reports the
+CURRENT state (the column is currently ascending — hence the up arrow). If the icon instead
+matched the button's own `data-ln-sort-dir`, the header would visually lie about its own sort
+order the instant the column reaches `state="asc"`: the user would see a down-arrow next to a
+column that is actually sorted up. Do not "fix" the icons to match `data-ln-sort-dir` when
+hand-authoring markup — that reintroduces the exact bug this convention exists to prevent. `content`
+cannot substitute for this — these icons are an SVG sprite via `<use href>`, not a font glyph a
+`::before { content }` rule could swap (see `docs/architecture/reference.md` §Icons).
+
+- **SSR table column** — omit `data-ln-sort-field`; the `<ul>` must be a descendant of the `<th>`
+  so the `th.cellIndex` fallback resolves. `data-ln-sort-field` and the SSR index path are never
+  bridged — setting a field on an SSR-table column leaves `column` null and `ln-table`'s SSR sort
+  has nothing to key off. Don't do both.
+- **Data-driven table column** — set `data-ln-sort-field` to the same value as the `<th>`'s
+  `data-ln-table-col`.
+- **Plain list** — target a generic `<ul>`/`<li>` container by `id`; set
+  `data-ln-sort-items="<selector>"` for deep targeting (mirrors `data-ln-search-items`).
+
+---
+
+## 🛠️ Declarative API Contract
+
+### HTML Attributes
+
+| Attribute | Elements | Description |
+| :--- | :--- | :--- |
+| `data-ln-sort` | `<ul>` (root) | Component root. Value is the `id` of the target being sorted. |
+| `data-ln-sort-field` | Same as root | Opt-in. The record field name (data-driven). Omit for the `th.cellIndex` fallback (SSR/DOM only). |
+| `data-ln-sort-state` | Same as root | *State*. `"none" \| "asc" \| "desc"`. Drives which trigger button is visible via CSS. |
+| `data-ln-sort-items` | Same as root | Opt-in. Deep CSS selector for default-DOM-behaviour reordering (mirrors `data-ln-search-items`). |
+| `data-ln-sort-dir` | `<button>` (inside root) | `"asc" \| "desc" \| "none"`. Identifies which action this trigger performs. |
+| `data-ln-persist` | Same as root | Opt-in. Persists `{ field, column, direction }` to `localStorage`. Give each `[data-ln-sort]` its own value (or `id`) — persistence is per-instance, not per-table. |
+
+### JavaScript API (`el.lnSort`)
+
+| Member | Type | Description |
+| :--- | :--- | :--- |
+| `targetId` | `string` | The `id` of the target element. |
+| `field` | `string \| null` | The authored field name, or `null`. |
+| `column` | `number \| null` | The resolved `th.cellIndex` fallback, or `null`. |
+| `destroy()` | `() => void` | Removes listeners and tears down the instance. |
+
+---
+
+## ⚡ DOM Events
+
+### `ln-sort:change`
+
+Dispatched on the **target** element (never on the sort control itself) whenever a trigger button
+is clicked, or on persisted-state restore.
+- **Cancelable**: Yes. `e.preventDefault()` disables the default DOM-reorder and hands the intent
+  fully to the consumer (e.g. `ln-table`, `ln-list`).
+- **Payload (`detail`)**: `{ field: string|null, column: number|null, direction: 'asc'|'desc'|'none', targetId: string }`.
+
+---
+
+## ⚠️ Common Pitfalls
+
+- **Setting both `data-ln-sort-field` and expecting the index fallback to also work.** They are
+  never bridged. Pick one per instance based on the mode (SSR → index fallback; data-driven →
+  field).
+- **Multi-column sort.** Not supported — single sort only. Multiple `[data-ln-sort]` instances
+  targeting the same target enforce mutual exclusion automatically (see Philosophy §3).
+- **Expecting JS to own the click cycle.** It doesn't — the circular order is CSS-driven via
+  `[data-ln-sort-state]`. If the three trigger buttons aren't authored per the canonical markup,
+  the cycle breaks visually even though the JS click handling still works.
+- **Persisting without a stable key.** `data-ln-persist` with no value falls back to `el.id`; a
+  bare `<ul data-ln-sort data-ln-persist>` with no `id` silently skips persistence
+  (see `ln-core.persistGet`/`persistSet` — `console.warn`s once).
+
+---
+
+## 🔧 Internals
+
+Source: `js/ln-sort/ln-sort.js`. One instance per `[data-ln-sort]`, stored at `element.lnSort`.
+
+### The three-step click (no cycle logic)
+
+`_onClick` reads `data-ln-sort-dir` off the clicked button and calls `_apply(direction)`, which:
+writes `data-ln-sort-state` on the root, dispatches `ln-sort:change` on the target, and — only if
+not prevented — runs `_defaultSort`. There is no `if (current === 'asc') then 'desc'` branch
+anywhere in this file; the SCSS cycle in `scss/config/mixins/_sort.scss` decides which button is
+even clickable next.
+
+### Mutual exclusion
+
+Each instance adds its `ln-sort:change` listener to the resolved **target** element (captured once
+at construction as `this._target`), not to itself. A self-originated dispatch also re-enters this
+same listener (dispatch is synchronous and the listener is on the same target) — but the
+field/column comparison naturally evaluates "same" for a self-dispatch, so it's a safe no-op, not
+an explicit self-check.
+
+### Default DOM behaviour
+
+Only runs when the consumer does not call `preventDefault()`. Reorders `target.children` (or
+`data-ln-sort-items` matches) by moving nodes into a `DocumentFragment` and re-appending — a single
+reflow, not N individual moves. Value extraction: `readValue` on the `[data-ln-field="<field>"]`
+descendant if `field` is set, else `readValue(item)` directly. The `column` index fallback is
+**never** consulted here — it exists solely to populate the event payload for SSR/DOM table
+consumers; see README "Field is optional" above.
+
+### Persistence
+
+`data-ln-persist` on the root, restored in the constructor via `persistGet('sort', dom)` and
+applied via `_apply(saved.direction, true)` — the `skipPersist` flag prevents re-writing the value
+just read (same pattern as `ln-filter`'s restore). Cleared by setting `direction: 'none'`
+(`persistSet('sort', dom, null)`).
+
+### Destroy
+
+Removes the click listener (root) and the `ln-sort:change` listener (target, if resolved). Does
+not restore the DOM to its pre-sort order — that's a rendering side effect, not the component's
+own teardown responsibility (same doctrine as `ln-search.destroy()`).

package/js/ln-sort/ln-sort-dev.scss

@@ -0,0 +1,8 @@
+@use '../../scss/config/mixins' as *;
+
+[data-ln-debug] {
+	// 1. Sort Target Check: an empty target id resolves to getElementById('') → null, so the control is silently inert
+	[data-ln-sort=""] {
+		@include dev-inline-error("data-ln-sort target is empty");
+	}
+}

package/js/ln-sort/ln-sort.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 S={};function B(t,e){S[t]||(S[t]=document.querySelector('[data-ln-template="'+t+'"]'));const n=S[t];return n?n.content.cloneNode(!0):(console.warn("["+(e||"ln-core")+'] Template "'+t+'" not found'),null)}function j(t,e,n){const i=new CustomEvent(e,{bubbles:!0,cancelable:!0,detail:n||{}});return t.dispatchEvent(i),i}function L(t,e){if(!t||!e)return t;const n=t.querySelectorAll("[data-ln-field]");for(let l=0;l<n.length;l++){const o=n[l],c=o.getAttribute("data-ln-field");e[c]!=null&&(o.textContent=e[c])}const i=t.querySelectorAll("[data-ln-attr]");for(let l=0;l<i.length;l++){const o=i[l],c=o.getAttribute("data-ln-attr").split(",");for(let r=0;r<c.length;r++){const u=c[r].trim().split(":");if(u.length!==2)continue;const s=u[0].trim(),d=u[1].trim();e[d]!=null&&o.setAttribute(s,e[d])}}const f=t.querySelectorAll("[data-ln-show]");for(let l=0;l<f.length;l++){const o=f[l],c=o.getAttribute("data-ln-show");c in e&&o.classList.toggle("hidden",!e[c])}const a=t.querySelectorAll("[data-ln-class]");for(let l=0;l<a.length;l++){const o=a[l],c=o.getAttribute("data-ln-class").split(",");for(let r=0;r<c.length;r++){const u=c[r].trim().split(":");if(u.length!==2)continue;const s=u[0].trim(),d=u[1].trim();d in e&&o.classList.toggle(s,!!e[d])}}return t}function K(t,e){t.matches&&t.matches("[data-ln-form], [data-ln-fillable]")&&t.dispatchEvent(new CustomEvent("ln-fill",{detail:e??null,bubbles:!0}));const n=t.querySelectorAll("[data-ln-form], [data-ln-fillable]");for(let i=0;i<n.length;i++)n[i].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)L(t.target,t.detail);else{const e=t.target.querySelectorAll("[data-ln-field]");for(let n=0;n<e.length;n++)e[n].textContent=""}})));function E(t,e){if(!t||!e)return t;const n=document.createTreeWalker(t,NodeFilter.SHOW_TEXT);for(;n.nextNode();){const a=n.currentNode;a.textContent.indexOf("{{")!==-1&&(a.textContent=a.textContent.replace(/\{\{\s*(\w+)\s*\}\}/g,function(l,o){return e[o]!==void 0?e[o]:""}))}const i=function(a,l){return e[l]!==void 0?e[l]:""},f=Array.from(t.querySelectorAll("*"));t.nodeType===1&&f.push(t);for(let a=0;a<f.length;a++){const l=f[a],o=l.attributes;for(let c=0;c<o.length;c++){const r=o[c];r.value.indexOf("{{")!==-1&&l.setAttribute(r.name,r.value.replace(/\{\{\s*(\w+)\s*\}\}/g,i))}}return t}function W(t,e,n,i,f,a){const l={};for(let c=0;c<t.children.length;c++){const r=t.children[c],u=r.getAttribute("data-ln-key");u&&(l[u]=r)}const o=document.createDocumentFragment();for(let c=0;c<e.length;c++){const r=e[c],u=String(i(r));let s=l[u];if(s)f(s,r,c);else{const d=B(n,a);if(!d||(E(d,r),s=d.firstElementChild,!s))continue;s.setAttribute("data-ln-key",u),f(s,r,c)}o.appendChild(s)}t.textContent="",t.appendChild(o)}function T(t,e){if(!document.body){document.addEventListener("DOMContentLoaded",function(){T(t,e)}),console.warn("["+e+'] Script loaded before <body> — add "defer" to your <script> tag');return}t()}function _(t,e,n,i){if(t.nodeType!==1)return;const a=e.indexOf("[")!==-1||e.indexOf(".")!==-1||e.indexOf("#")!==-1?e:"["+e+"]",l=Array.from(t.querySelectorAll(a));t.matches&&t.matches(a)&&l.push(t);for(const o of l)o[n]||(o[n]=new i(o))}const x={mk:"mk-MK",de:"de-DE",fr:"fr-FR",es:"es-ES",it:"it-IT",nl:"nl-NL",pt:"pt-PT",ru:"ru-RU",bg:"bg-BG",hr:"hr-HR",sr:"sr-RS",sq:"sq-AL",el:"el-GR",en:"en-US"};function U(t){const e=t?t.closest("[lang]"):null,n=(e?e.getAttribute("lang")||e.lang:null)||(document.documentElement?document.documentElement.getAttribute("lang")||document.documentElement.lang:null)||navigator.language;if(!n)return"en-US";const i=n.trim().toLowerCase();return i.indexOf("-")===-1&&x[i]?x[i]:n}function k(t){return t.hasAttribute("data-ln-value")?t.getAttribute("data-ln-value"):t.textContent.trim()}function G(t){let e=!1;for(let n=0;n<t.length;n++){const i=t[n];if(!(i===""||i==null)&&(e=!0,!Number.isFinite(Number(i))))return"string"}return e?"number":"string"}function V(t,e,n,i){if(n==="number"){const l=parseFloat(t),o=parseFloat(e);return(isNaN(l)?0:l)-(isNaN(o)?0:o)}const f=t!=null?String(t):"",a=e!=null?String(e):"";return i?i.compare(f,a):f<a?-1:f>a?1:0}function P(t,e,n,i,f={}){const a=f.extraAttributes||[],l=f.onAttributeChange||null,o=f.onInit||null;function c(r){const u=r||document.body;_(u,t,e,n),o&&o(u)}return T(function(){const r=new MutationObserver(function(s){for(let d=0;d<s.length;d++){const h=s[d];if(h.type==="childList"){for(let p=0;p<h.addedNodes.length;p++){const g=h.addedNodes[p];g.nodeType===1&&(_(g,t,e,n),o&&o(g))}for(let p=0;p<h.removedNodes.length;p++){const g=h.removedNodes[p];if(g.nodeType===1){const A=t.indexOf("[")!==-1||t.indexOf(".")!==-1||t.indexOf("#")!==-1?t:"["+t+"]",b=Array.from(g.querySelectorAll(A));g.matches&&g.matches(A)&&b.push(g);for(let w=0;w<b.length;w++){const y=b[w];if(!document.contains(y)){const C=y[e];C&&typeof C.destroy=="function"&&C.destroy()}}}}}else h.type==="attributes"&&(l&&h.target[e]?l(h.target,h.attributeName):(_(h.target,t,e,n),o&&o(h.target)))}});let u=[];if(t.indexOf("[")!==-1){const s=/\[([\w-]+)/g;let d;for(;(d=s.exec(t))!==null;)u.push(d[1])}else u.push(t);r.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:u.concat(a)})},i),window[e]=c,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){c(document.body)}):c(document.body),c}const I={};function H(t,e){I[t]=e}function J(t){return I[t]||{ingress:e=>e,egress:e=>e}}const O={};function q(t,e){if(!t||typeof e!="object")return;const n=t.toLowerCase().split("-")[0];O[n]=e}function X(t){if(!t)return null;const e=t.toLowerCase().split("-")[0];return O[e]||null}q("mk",{monthsLong:["јануари","февруари","март","април","мај","јуни","јули","август","септември","октомври","ноември","декември"],monthsShort:["јан","фев","мар","апр","мај","јун","јул","авг","септ","окт","ноем","дек"],daysLong:["недела","понеделник","вторник","среда","четврток","петок","сабота"],daysShort:["нед","пон","вт","ср","чет","пет","саб"]}),typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=H,window.lnCore.getDataMapper=J,window.lnCore.registerLocaleFallback=q,window.lnCore.getLocaleFallback=X,window.lnCore.fillTemplate=E,window.lnCore.fill=L,window.lnCore.lnFill=K,window.lnCore.renderList=W);const $="ln:";let m=null;function N(){if(m!==null)return m;try{if(typeof localStorage>"u")return m=!1,!1;const t="__ln_test__";localStorage.setItem(t,t),localStorage.removeItem(t),m=!0}catch{m=!1}return m}function z(){return location.pathname.replace(/\/+$/,"").toLowerCase()||"/"}function D(t,e){const n=e.getAttribute("data-ln-persist"),i=n!==null&&n!==""?n:e.id;return i?$+t+":"+z()+":"+i:(console.warn('[ln-persist] Element requires id or data-ln-persist="key"',e),null)}function Q(t,e){if(!N())return null;const n=D(t,e);if(!n)return null;try{const i=localStorage.getItem(n);return i!==null?JSON.parse(i):null}catch{return null}}function R(t,e,n){if(!N())return;const i=D(t,e);if(i)try{n==null?localStorage.removeItem(i):localStorage.setItem(i,JSON.stringify(n))}catch{}}function F(t){return(t||"").replace(/^#/,"")}function v(t){const e=t===void 0?location.hash:t,n={},i=F(e);if(!i)return n;const f=i.split("&");for(let a=0;a<f.length;a++){const l=f[a];if(!l)continue;const o=l.indexOf(":"),c=o>-1?l.slice(0,o):l,r=o>-1?l.slice(o+1):"";if(c)try{n[c]=decodeURIComponent(r)}catch{n[c]=r}}return n}function Y(t){if(!t)return null;const e=v();return t in e?e[t]:null}function Z(t,e){if(!t)return;const n=v();e==null?delete n[t]:n[t]=String(e);const f=Object.keys(n).map(function(a){const l=n[a];return l===""?a:a+":"+encodeURIComponent(l)}).join("&");F(location.hash)!==f&&(location.hash=f)}function tt(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=v,window.lnCore.hashGet=Y,window.lnCore.hashSet=Z,window.lnCore.hashLinkClick=tt),(function(){const t="data-ln-sort",e="lnSort",n="data-ln-sort-field",i="data-ln-sort-state",f="data-ln-sort-dir",a="data-ln-sort-items";if(window[e]!==void 0)return;function l(r,u){if(u){const s=r.querySelector('[data-ln-field="'+u+'"]');if(s)return k(s)}return k(r)}function o(r){this.dom=r,this.targetId=r.getAttribute(t),this.field=r.getAttribute(n)||null;const u=r.closest("th");this.column=!this.field&&u?u.cellIndex:null,this.itemsSelector=r.getAttribute(a)||null,this._initialOrder=null;const s=document.getElementById(this.targetId);s&&(this._initialOrder=this.itemsSelector?Array.from(s.querySelectorAll(this.itemsSelector)):Array.from(s.children)),this._target=s;const d=this;if(this._onClick=function(h){const p=h.target.closest("["+f+"]");p&&d._apply(p.getAttribute(f))},r.addEventListener("click",this._onClick),this._onTargetChange=function(h){(d.field?h.detail.field===d.field:h.detail.column===d.column)||(r.setAttribute(i,"none"),r.hasAttribute("data-ln-persist")&&R("sort",r,null))},s&&s.addEventListener("ln-sort:change",this._onTargetChange),r.hasAttribute("data-ln-persist")){const h=Q("sort",r);h&&h.direction&&queueMicrotask(function(){d._apply(h.direction,!0)})}return this}o.prototype._apply=function(r,u){this.dom.setAttribute(i,r);const s=this._target||document.getElementById(this.targetId);if(!s)return;const d={field:this.field,column:this.column,direction:r,targetId:this.targetId};!u&&this.dom.hasAttribute("data-ln-persist")&&R("sort",this.dom,r==="none"?null:d),!j(s,"ln-sort:change",d).defaultPrevented&&this._defaultSort(s,r)},o.prototype._defaultSort=function(r,u){const s=this.itemsSelector?Array.from(r.querySelectorAll(this.itemsSelector)):Array.from(r.children);if(!s.length)return;const d=s[0].parentNode;let h;if(u==="none")h=(this._initialOrder||s).filter(function(g){return g.parentNode===d});else{const g=this.field,M=s.map(function(y){return l(y,g)}),A=G(M),b=typeof Intl<"u"?new Intl.Collator(U(this.dom),{sensitivity:"base"}):null,w=u==="desc"?-1:1;h=s.slice().sort(function(y,C){return V(l(y,g),l(C,g),A,b)*w})}const p=document.createDocumentFragment();for(let g=0;g<h.length;g++)p.appendChild(h[g]);d.appendChild(p)},o.prototype.destroy=function(){this.dom[e]&&(this.dom.removeEventListener("click",this._onClick),this._target&&this._target.removeEventListener("ln-sort:change",this._onTargetChange),delete this.dom[e])};function c(r,u){const s=r[e];if(s)if(u===n){s.field=r.getAttribute(n)||null;const d=r.closest("th");s.column=!s.field&&d?d.cellIndex:null}else u===a&&(s.itemsSelector=r.getAttribute(a)||null)}P(t,e,o,"ln-sort",{extraAttributes:[n,a],onAttributeChange:c})})()})();

package/js/ln-sort/src/ln-sort.js

@@ -0,0 +1,178 @@
+import { dispatchCancelable, readValue, getLocale, detectValueType, compareValues, registerComponent, persistGet, persistSet } from '../../ln-core';
+
+(function () {
+	const DOM_SELECTOR = 'data-ln-sort';
+	const DOM_ATTRIBUTE = 'lnSort';
+	const FIELD_ATTR = 'data-ln-sort-field';
+	const STATE_ATTR = 'data-ln-sort-state';
+	const DIR_ATTR = 'data-ln-sort-dir';
+	const ITEMS_ATTR = 'data-ln-sort-items';
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+	// Read the value a default-DOM sort compares by: field-matched descendant
+	// first, else the item itself. Never the column-index fallback — that
+	// path is SSR/DOM-payload only (see README "No index/field bridge").
+	function _readItemValue(item, field) {
+		if (field) {
+			const el = item.querySelector('[data-ln-field="' + field + '"]');
+			if (el) return readValue(el);
+		}
+		return readValue(item);
+	}
+
+	// ─── Component ─────────────────────────────────────────────
+
+	function _component(dom) {
+		this.dom = dom;
+		this.targetId = dom.getAttribute(DOM_SELECTOR);
+		this.field = dom.getAttribute(FIELD_ATTR) || null;
+
+		// Index fallback — resolved once, only when no field is authored.
+		// SSR/DOM-payload path only; never bridged back to `field`.
+		const th = dom.closest('th');
+		this.column = (!this.field && th) ? th.cellIndex : null;
+
+		this.itemsSelector = dom.getAttribute(ITEMS_ATTR) || null;
+
+		// Snapshot the pre-sort DOM order once — the only state this
+		// component holds, needed to restore direction "none".
+		this._initialOrder = null;
+		const target = document.getElementById(this.targetId);
+		if (target) {
+			this._initialOrder = this.itemsSelector
+				? Array.from(target.querySelectorAll(this.itemsSelector))
+				: Array.from(target.children);
+		}
+		this._target = target;
+
+		const self = this;
+
+		this._onClick = function (e) {
+			const btn = e.target.closest('[' + DIR_ATTR + ']');
+			if (!btn) return;
+			self._apply(btn.getAttribute(DIR_ATTR));
+		};
+		dom.addEventListener('click', this._onClick);
+
+		// Mutual exclusion — listen on the TARGET (not self). A sibling
+		// ln-sort instance targeting the same target wins; this instance
+		// resets to "none". Self-originated events naturally compare equal
+		// (own field/column always matches itself) and no-op here.
+		this._onTargetChange = function (e) {
+			const same = self.field
+				? e.detail.field === self.field
+				: e.detail.column === self.column;
+			if (same) return;
+			dom.setAttribute(STATE_ATTR, 'none');
+			// Single-sort invariant holds in storage too — a losing instance
+			// must drop its key, else two non-null keys race on next load.
+			if (dom.hasAttribute('data-ln-persist')) persistSet('sort', dom, null);
+		};
+		if (target) target.addEventListener('ln-sort:change', this._onTargetChange);
+
+		// ─── Restore persisted sort ─────────────────────────────
+		// Deferred — same hazard as ln-search's form-restore dispatch
+		// (js/ln-search/src/ln-search.js): _apply() dispatches synchronously,
+		// and a consumer (ln-table/ln-list) targeting the same id may not
+		// have bound its ln-sort:change listener yet if it constructs later
+		// in this same init sweep. queueMicrotask waits for that sweep to
+		// finish first.
+		if (dom.hasAttribute('data-ln-persist')) {
+			const saved = persistGet('sort', dom);
+			if (saved && saved.direction) {
+				queueMicrotask(function () {
+					self._apply(saved.direction, true);
+				});
+			}
+		}
+
+		return this;
+	}
+
+	_component.prototype._apply = function (direction, skipPersist) {
+		this.dom.setAttribute(STATE_ATTR, direction);
+
+		const target = this._target || document.getElementById(this.targetId);
+		if (!target) return;
+
+		const detail = {
+			field: this.field,
+			column: this.column,
+			direction: direction,
+			targetId: this.targetId
+		};
+
+		if (!skipPersist && this.dom.hasAttribute('data-ln-persist')) {
+			persistSet('sort', this.dom, direction === 'none' ? null : detail);
+		}
+
+		const evt = dispatchCancelable(target, 'ln-sort:change', detail);
+		if (evt.defaultPrevented) return;
+
+		this._defaultSort(target, direction);
+	};
+
+	// ─── Default DOM behaviour (no consumer claimed the event) ────
+
+	_component.prototype._defaultSort = function (target, direction) {
+		const items = this.itemsSelector
+			? Array.from(target.querySelectorAll(this.itemsSelector))
+			: Array.from(target.children);
+		if (!items.length) return;
+		const parent = items[0].parentNode;
+
+		let ordered;
+		if (direction === 'none') {
+			ordered = (this._initialOrder || items).filter(function (el) {
+				return el.parentNode === parent;
+			});
+		} else {
+			const field = this.field;
+			const values = items.map(function (el) { return _readItemValue(el, field); });
+			const type = detectValueType(values);
+			const collator = typeof Intl !== 'undefined'
+				? new Intl.Collator(getLocale(this.dom), { sensitivity: 'base' })
+				: null;
+			const multiplier = direction === 'desc' ? -1 : 1;
+
+			ordered = items.slice().sort(function (a, b) {
+				return compareValues(_readItemValue(a, field), _readItemValue(b, field), type, collator) * multiplier;
+			});
+		}
+
+		const frag = document.createDocumentFragment();
+		for (let i = 0; i < ordered.length; i++) frag.appendChild(ordered[i]);
+		parent.appendChild(frag);
+	};
+
+	// ─── Destroy ───────────────────────────────────────────────
+
+	_component.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+		this.dom.removeEventListener('click', this._onClick);
+		if (this._target) this._target.removeEventListener('ln-sort:change', this._onTargetChange);
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	// ─── Attribute Sync ────────────────────────────────────────
+
+	function _syncAttribute(el, attrName) {
+		const instance = el[DOM_ATTRIBUTE];
+		if (!instance) return;
+		if (attrName === FIELD_ATTR) {
+			instance.field = el.getAttribute(FIELD_ATTR) || null;
+			const th = el.closest('th');
+			instance.column = (!instance.field && th) ? th.cellIndex : null;
+		} else if (attrName === ITEMS_ATTR) {
+			instance.itemsSelector = el.getAttribute(ITEMS_ATTR) || null;
+		}
+	}
+
+	// ─── Init ──────────────────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-sort', {
+		extraAttributes: [FIELD_ATTR, ITEMS_ATTR],
+		onAttributeChange: _syncAttribute
+	});
+})();

package/js/ln-sortable/README.md

@@ -1,95 +1,133 @@
-# ln-sortable
-
-A zero-dependency, high-performance **Drag & Drop Reordering Primitive** driven by browser Pointer Events APIs, designed for seamless mouse and touch interactions.
-
-It focuses strictly on visual DOM restructuring, delegating server-side synchronization, database persistence, and list state saves completely to the parent coordinator via telemetry events.
-
----
-
-## 🧭 Philosophy & Architecture
-
-1. **Pointer Concurrency:** Built natively on Pointer Events APIs (`pointerdown`, `pointermove`, `pointerup`). It replaces heavy HTML5 Drag & Drop frameworks, offering high-performance dragging and layout shifts across desktop, mobile, and hybrid touch displays.
-2. **Visual Isolation:** The primitive does not import or inject inline styles or layout rules. Instead, it exposes CSS state hooks (e.g. `.ln-sortable--dragging`) on active elements, leaving transitions and placeholders fully to the stylesheet.
-3. **HTML Attribute as Single Source of Truth:** Component states are governed entirely by the `data-ln-sortable` attribute. Standard JS API calls (`enable()`, `disable()`) write directly to the attribute, which is observed via `MutationObserver` to coordinate internals.
-
----
-
-## 📦 Minimal Blueprint
-
-### Drag Anywhere List
-Mark the container list directly with `data-ln-sortable`. All direct children become instantly sortable.
-```html
-<ul data-ln-sortable>
-  <li>First Item</li>
-  <li>Second Item</li>
-  <li>Third Item</li>
-</ul>
-```
-
-### Handles-Only List (Premium Touch-Safe)
-For touch screens, limit drag triggers to a specific nested grab handle via `data-ln-sortable-handle`.
-```html
-<ol data-ln-sortable>
-  <li>
-    <span data-ln-sortable-handle>
-      <svg class="ln-icon" aria-hidden="true"><use href="#ln-menu"></use></svg>
-    </span>
-    <span>Dashboard</span>
-  </li>
-  <li>
-    <span data-ln-sortable-handle>
-      <svg class="ln-icon" aria-hidden="true"><use href="#ln-menu"></use></svg>
-    </span>
-    <span>Users</span>
-  </li>
-</ol>
-```
-
----
-
-## 🛠️ Declarative API Contract
-
-### HTML Attributes
-
-| Attribute | Elements | Description |
-| :--- | :--- | :--- |
-| `data-ln-sortable` | Container (`<ul>`, `<ol>`, etc.) | Component root. Can be empty (enabled) or `"disabled"`. |
-| `data-ln-sortable-handle` | Descendant of list item | Identifies drag trigger. When present, pointer clicks outside fail to drag. |
-
-### CSS Class Hooks
-
-The component toggles these visual state classes at runtime:
-
-| Class | Element | Description |
-| :--- | :--- | :--- |
-| `.ln-sortable--active` | Container | Drag session in progress. Pointer events on text selection are locked. |
-| `.ln-sortable--dragging` | Dragged item | The item currently being dragged. Typically styled with reduced opacity. |
-| `.ln-sortable--drop-before` | Neighbor item | Target item top-half placeholder. Highlight top border. |
-| `.ln-sortable--drop-after` | Neighbor item | Target item bottom-half placeholder. Highlight bottom border. |
-
----
-
-## ⚡ DOM Events
-
-All events bubble from the container element.
-
-### `ln-sortable:before-drag`
-Fired when pointer down triggers drag.
-- **Cancelable**: Yes. Call `e.preventDefault()` to cancel the drag action (e.g. list is locked).
-- **Payload (`detail`)**: `{ item: HTMLElement, index: number }`
-
-### `ln-sortable:reordered`
-Fired when an item drop successfully changes the DOM index order.
-- **Payload (`detail`)**: `{ item: HTMLElement, oldIndex: number, newIndex: number }`
-
----
-
-## ⚠️ Common Pitfalls
-
-- **Missing `touch-action: none`:** Drag handles must carry `touch-action: none` in CSS. Failing to add this prevents mobile browsers from scrolling, causing the browser to capture pointer tracks and breaking touch drags.
-- **Auto-Sync Assumptions:** The primitive does not call servers automatically. You must wire an `ln-sortable:reordered` listener and dispatch your sync request (e.g. via `ln-http`):
-  ```javascript
-  document.addEventListener('ln-sortable:reordered', function(e) {
-    saveNewListOrder(e.target.id, e.detail.oldIndex, e.detail.newIndex);
-  });
-  ```
+# ln-sortable
+
+A zero-dependency, high-performance **Drag & Drop Reordering Primitive** driven by browser Pointer Events APIs, designed for seamless mouse and touch interactions.
+
+It focuses strictly on visual DOM restructuring, delegating server-side synchronization, database persistence, and list state saves completely to the parent coordinator via telemetry events.
+
+---
+
+## 🧭 Philosophy & Architecture
+
+1. **Pointer Concurrency:** Built natively on Pointer Events APIs (`pointerdown`, `pointermove`, `pointerup`). It replaces heavy HTML5 Drag & Drop frameworks, offering high-performance dragging and layout shifts across desktop, mobile, and hybrid touch displays.
+2. **Visual Isolation:** The primitive does not import or inject inline styles or layout rules. Instead, it exposes CSS state hooks (e.g. `.ln-sortable--dragging`) on active elements, leaving transitions and placeholders fully to the stylesheet.
+3. **HTML Attribute as Single Source of Truth:** Component states are governed entirely by the `data-ln-sortable` attribute. Standard JS API calls (`enable()`, `disable()`) write directly to the attribute, which is observed via `MutationObserver` to coordinate internals.
+
+---
+
+## 📦 Minimal Blueprint
+
+### Drag Anywhere List
+Mark the container list directly with `data-ln-sortable`. All direct children become instantly sortable.
+```html
+<ul data-ln-sortable>
+  <li>First Item</li>
+  <li>Second Item</li>
+  <li>Third Item</li>
+</ul>
+```
+
+### Handles-Only List (Premium Touch-Safe)
+For touch screens, limit drag triggers to a specific nested grab handle via `data-ln-sortable-handle`.
+```html
+<ol data-ln-sortable>
+  <li>
+    <span data-ln-sortable-handle>
+      <svg class="ln-icon" aria-hidden="true"><use href="#ln-icon-menu"></use></svg>
+    </span>
+    <span>Dashboard</span>
+  </li>
+  <li>
+    <span data-ln-sortable-handle>
+      <svg class="ln-icon" aria-hidden="true"><use href="#ln-icon-menu"></use></svg>
+    </span>
+    <span>Users</span>
+  </li>
+</ol>
+```
+
+---
+
+## 🛠️ Declarative API Contract
+
+### HTML Attributes
+
+| Attribute | Elements | Description |
+| :--- | :--- | :--- |
+| `data-ln-sortable` | Container (`<ul>`, `<ol>`, etc.) | Component root. Can be empty (enabled) or `"disabled"`. |
+| `data-ln-sortable-handle` | Descendant of list item | Identifies drag trigger. When present, pointer clicks outside fail to drag. |
+
+### CSS Class Hooks
+
+The component toggles these visual state classes at runtime:
+
+| Class | Element | Description |
+| :--- | :--- | :--- |
+| `.ln-sortable--active` | Container | Drag session in progress. Pointer events on text selection are locked. |
+| `.ln-sortable--dragging` | Dragged item | The item currently being dragged. Typically styled with reduced opacity. |
+| `.ln-sortable--drop-before` | Neighbor item | Target item top-half placeholder. Highlight top border. |
+| `.ln-sortable--drop-after` | Neighbor item | Target item bottom-half placeholder. Highlight bottom border. |
+
+---
+
+## ⚡ DOM Events
+
+All events bubble from the container element.
+
+### `ln-sortable:before-drag`
+Fired when pointer down triggers drag.
+- **Cancelable**: Yes. Call `e.preventDefault()` to cancel the drag action (e.g. list is locked).
+- **Payload (`detail`)**: `{ item: HTMLElement, index: number }`
+
+### `ln-sortable:drag-start`
+Fired right after a drag is committed (after `before-drag` passes, capture is set, and drag classes are applied).
+- **Payload (`detail`)**: `{ item: HTMLElement, index: number }`
+
+### `ln-sortable:reordered`
+Fired when an item drop successfully changes the DOM index order.
+- **Payload (`detail`)**: `{ item: HTMLElement, oldIndex: number, newIndex: number }`
+
+### `ln-sortable:enabled` / `ln-sortable:disabled`
+Fired when `data-ln-sortable` toggles between enabled and `"disabled"` (via `enable()`/`disable()` or a direct attribute write, picked up by the shared `MutationObserver`).
+- **Payload (`detail`)**: `{ target: HTMLElement }`
+
+### `ln-sortable:destroyed`
+Fired inside `destroy()`, after the `pointerdown` listener is removed.
+- **Payload (`detail`)**: `{ target: HTMLElement }`
+
+---
+
+## ⚠️ Common Pitfalls
+
+- **Missing `touch-action: none`:** Drag handles must carry `touch-action: none` in CSS. Failing to add this prevents mobile browsers from scrolling, causing the browser to capture pointer tracks and breaking touch drags.
+- **Auto-Sync Assumptions:** The primitive does not call servers automatically. You must wire an `ln-sortable:reordered` listener and dispatch your sync request (e.g. via `ln-http`):
+  ```javascript
+  document.addEventListener('ln-sortable:reordered', function(e) {
+    saveNewListOrder(e.target.id, e.detail.oldIndex, e.detail.newIndex);
+  });
+  ```
+
+---
+
+## 🔧 Internals
+
+Source: `js/ln-sortable/ln-sortable.js`. Each `[data-ln-sortable]` container gets a `_component` instance at `element.lnSortable` (`dom`, `isEnabled`, `_dragging` — the child currently being dragged, or `null` — and the bound `pointerdown` handler).
+
+### Handle resolution
+
+On `pointerdown`: if the target (or an ancestor) carries `data-ln-sortable-handle`, walk up from the handle to the direct container child — that's the drag item. If no handle is under the pointer but handles exist elsewhere in the container, abort (click was outside a handle). If no handles exist anywhere in the container, the clicked child itself is the handle. Either way the resolved item is validated as a direct child of the container before drag starts.
+
+### Pointer lifecycle
+
+`pointerdown` → resolve item → dispatch cancelable `ln-sortable:before-drag` (abort on `preventDefault()`, before any class or capture is applied) → `setPointerCapture` on the handle → set `_dragging`, apply `.ln-sortable--active`/`--dragging`, `aria-grabbed` → attach `pointermove`/`pointerup`/`pointercancel` on the handle.
+
+`pointermove` (repeated): clear all `--drop-before`/`--drop-after` classes, then for each sibling (skipping the dragged element) compare `clientY` to the sibling's vertical midpoint — upper half gets `--drop-before`, lower half gets `--drop-after`. Loop breaks after the first match, so only one sibling ever carries a drop indicator.
+
+`pointerup`/`pointercancel`: find the sibling still carrying a drop class, strip all classes + `aria-grabbed`, and if a valid drop target exists, reorder with a single `insertBefore` (`container.insertBefore(item, dropTarget)` for `--drop-before`, or before `dropTarget.nextElementSibling` for `--drop-after`) then dispatch `ln-sortable:reordered`. This is pure DOM manipulation — no data model is touched; the event is the only signal for consumers to persist order.
+
+### Attribute-driven enable/disable
+
+`data-ln-sortable` (absent value) = enabled, `data-ln-sortable="disabled"` = disabled. `enable()`/`disable()` write the attribute; the shared `MutationObserver` picks up the change, updates `isEnabled` inline, and dispatches `ln-sortable:enabled`/`ln-sortable:disabled`. No cancelable before-event for enable/disable — the state change is immediate.
+
+### MutationObserver
+
+One global observer on `document.body`: `childList` (subtree) auto-initializes new `[data-ln-sortable]` containers; `attributes` on `data-ln-sortable` re-syncs `isEnabled` on existing instances.