@livenetworks/ashlar 1.3.2

package/js/ln-autosave/src/ln-autosave.js

@@ -0,0 +1,147 @@
+import { dispatch, dispatchCancelable, serializeForm, populateForm, registerComponent } from '../../ln-core';
+
+(function () {
+	const DOM_SELECTOR = 'data-ln-autosave';
+	const DOM_ATTRIBUTE = 'lnAutosave';
+	const CLEAR_SELECTOR = 'data-ln-autosave-clear';
+	const DEBOUNCE_SELECTOR = 'data-ln-autosave-debounce-input';
+	const STORAGE_PREFIX = 'ln-autosave:';
+	const DEFAULT_DEBOUNCE_MS = 1000;
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+	// ─── Component ─────────────────────────────────────────────
+
+	function _component(form) {
+		const key = _getStorageKey(form);
+		if (!key) {
+			console.warn('ln-autosave: form needs an id or data-ln-autosave value', form);
+			return;
+		}
+
+		this.dom = form;
+		this.key = key;
+
+		let inputTimer = null;
+
+		// Closure-scoped helpers (NOT on prototype — internal only)
+		function _save() {
+			const data = serializeForm(form);
+			try { localStorage.setItem(key, JSON.stringify(data)); }
+			catch (e) { return; }
+			dispatch(form, 'ln-autosave:saved', { target: form, data: data });
+		}
+
+		function _restore() {
+			let raw;
+			try { raw = localStorage.getItem(key); } catch (e) { return; }
+			if (!raw) return;
+			let data;
+			try { data = JSON.parse(raw); } catch (e) { return; }
+			const before = dispatchCancelable(form, 'ln-autosave:before-restore', { target: form, data: data });
+			if (before.defaultPrevented) return;
+			const restored = populateForm(form, data);
+			for (let k = 0; k < restored.length; k++) {
+				restored[k].dispatchEvent(new Event('input', { bubbles: true }));
+				restored[k].dispatchEvent(new Event('change', { bubbles: true }));
+			}
+			dispatch(form, 'ln-autosave:restored', { target: form, data: data });
+		}
+
+		function _clear() {
+			try { localStorage.removeItem(key); } catch (e) { return; }
+			dispatch(form, 'ln-autosave:cleared', { target: form });
+		}
+
+		// Listener handlers (held on `this` for symmetric removal in destroy)
+		this._onFocusout = function (e) {
+			const el = e.target;
+			if (_isFormField(el) && el.name) _save();
+		};
+
+		this._onChange = function (e) {
+			const el = e.target;
+			if (_isFormField(el) && el.name) _save();
+		};
+
+		this._onSubmit = function () { _clear(); };
+
+		this._onReset = function () { _clear(); };
+
+		this._onClearClick = function (e) {
+			const btn = e.target.closest('[' + CLEAR_SELECTOR + ']');
+			if (btn) _clear();
+		};
+
+		form.addEventListener('focusout', this._onFocusout);
+		form.addEventListener('change',   this._onChange);
+		form.addEventListener('submit',   this._onSubmit);
+		form.addEventListener('reset',    this._onReset);
+		form.addEventListener('click',    this._onClearClick);
+
+		// Optional debounced input listener (opt-in via data-ln-autosave-debounce-input)
+		const debounceMs = _resolveDebounceMs(form);
+		if (debounceMs > 0) {
+			this._onInput = function (e) {
+				const el = e.target;
+				if (!_isFormField(el) || !el.name) return;
+				if (inputTimer !== null) clearTimeout(inputTimer);
+				inputTimer = setTimeout(_save, debounceMs);
+			};
+			form.addEventListener('input', this._onInput);
+		}
+
+		// Thunk so destroy() can reach the closure-scoped inputTimer
+		this._getInputTimer = function () { return inputTimer; };
+
+		_restore();
+
+		return this;
+	}
+
+	_component.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+		this.dom.removeEventListener('focusout', this._onFocusout);
+		this.dom.removeEventListener('change',   this._onChange);
+		this.dom.removeEventListener('submit',   this._onSubmit);
+		this.dom.removeEventListener('reset',    this._onReset);
+		this.dom.removeEventListener('click',    this._onClearClick);
+		if (this._onInput) {
+			this.dom.removeEventListener('input', this._onInput);
+			const t = this._getInputTimer();
+			if (t !== null) clearTimeout(t);
+		}
+		dispatch(this.dom, 'ln-autosave:destroyed', { target: this.dom });
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	// ─── Helpers ───────────────────────────────────────────────
+
+	function _getStorageKey(form) {
+		const value = form.getAttribute(DOM_SELECTOR);
+		const identifier = value || form.id;
+		if (!identifier) return null;
+		return STORAGE_PREFIX + window.location.pathname + ':' + identifier;
+	}
+
+	function _isFormField(el) {
+		const tag = el.tagName;
+		return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT';
+	}
+
+	function _resolveDebounceMs(form) {
+		if (!form.hasAttribute(DEBOUNCE_SELECTOR)) return 0;
+		const raw = form.getAttribute(DEBOUNCE_SELECTOR);
+		if (raw === '' || raw === null) return DEFAULT_DEBOUNCE_MS;
+		const ms = parseInt(raw, 10);
+		if (isNaN(ms) || ms < 0) {
+			console.warn('ln-autosave: invalid debounce value, using default', form);
+			return DEFAULT_DEBOUNCE_MS;
+		}
+		return ms;
+	}
+
+	// ─── Init ──────────────────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-autosave');
+})();

package/js/ln-circular-progress/README.md

@@ -0,0 +1,161 @@
+# ln-circular-progress
+
+> Attribute-driven SVG ring renderer. Set `data-ln-circular-progress="75"` on an
+> empty host; the component builds the SVG, watches the attribute, and redraws on every change. The attribute IS the state — no imperative setter.
+
+## Quick start
+
+```html
+<div data-ln-circular-progress="75" class="success"></div>
+```
+
+One attribute on an empty host element. The constructor creates an `<svg>` with a
+track circle and fill circle, creates a `<strong>` label, and appends both to the
+host. The SVG fills the host's dimensions via CSS (`width: 100%`, `height: 100%`),
+so size comes from the host — or from a size class (`.sm`, `.lg`, `.xl`).
+
+The host element must be empty at init — the constructor `appendChild`s the SVG and label; pre-existing children stay in the DOM and overlap the ring.
+
+## Attributes
+
+| Attribute | On | Description |
+|---|---|---|
+| `data-ln-circular-progress="N"` | host element | Current value. Creates the instance. Number; negative or above-max values are allowed — the rendered percentage clamps to 0–100, but the attribute is left as-written. Empty / non-numeric strings render as 0%. |
+| `data-ln-circular-progress-max="N"` | host element | Maximum value. Default `100`. Used as denominator in `(value / max) × 100`. `max="0"` forces 0% (avoids divide-by-zero). |
+| `data-ln-circular-progress-label="text"` | host element | Custom centre label, replaces the auto-computed percentage. Read inside `_render`, but **NOT in the MutationObserver filter** — mutating this attribute alone does not trigger a re-render. Update the label alongside a value or max write. |
+
+`data-ln-circular-progress-initialized=""` is set by the constructor and removed by `destroy()`. It is an internal marker — do not read it from project code; use `el.lnCircularProgress` instead.
+
+**Size variants** — apply a class to the host: `.sm` (2.5 rem), default (4 rem), `.lg` (6 rem), `.xl` (8 rem). Each rebinds the label font-size.
+
+**Colour variants** — `.success`, `.warning`, `.error` override the fill stroke via `scss/components/_circular-progress.scss`. The default fill reads `--color-accent` and follows the active theme.
+
+## Events
+
+| Event | Bubbles | Cancelable | `detail` |
+|---|---|---|---|
+| `ln-circular-progress:change` | yes | no | `{ target, value, max, percentage }` |
+
+`detail.value` is the raw `parseFloat` of the attribute — unclamped. `detail.percentage` is clamped 0–100. A value of 150 on a max-100 ring produces `value: 150, percentage: 100`. Read `detail.value` to detect overshoot; read `detail.percentage` to match the visible arc.
+
+`detail.target` is the host element — useful when a single document-level listener handles multiple rings:
+
+```js
+document.addEventListener('ln-circular-progress:change', function (e) {
+	const { target, percentage } = e.detail;
+	if (percentage >= 100) {
+		target.classList.add('done');
+	}
+});
+```
+
+The event fires on the initial render at construction, as well as on every subsequent value or max attribute change. A document-level listener sees a `:change` for every ring on the page during init.
+
+## Accessibility
+
+The component sets `aria-hidden="true"` on the constructed `<svg>` — screen readers skip the SVG element. The component does **not** write `role`, `aria-valuenow`, `aria-valuemin`, or `aria-valuemax` on the host. Consumer owns the accessibility tree:
+
+```html
+<div data-ln-circular-progress="75"
+     role="progressbar"
+     aria-valuenow="75"
+     aria-valuemin="0"
+     aria-valuemax="100"
+     aria-label="Upload progress"
+     class="success">
+</div>
+```
+
+Keep `aria-valuenow` in sync when writing `data-ln-circular-progress` — the component does not do this automatically.
+
+## API
+
+`el.lnCircularProgress` on a constructed host element:
+
+| Property | Type | Description |
+|---|---|---|
+| `dom` | `HTMLElement` | Back-reference to the host element |
+| `svg` | `SVGSVGElement` | The constructed `<svg>` |
+| `trackCircle` | `SVGCircleElement` | Background circle (stroke = `--color-border`) |
+| `progressCircle` | `SVGCircleElement` | Fill circle — `stroke-dashoffset` carries the progress |
+| `labelEl` | `HTMLElement` | The `<strong>` element holding the percentage or custom label text |
+| `destroy()` | method | Disconnects the attribute observer, removes the SVG and label from DOM, removes `data-ln-circular-progress-initialized`, deletes `el.lnCircularProgress`. Leaves the value attribute, colour class, and size class in place — setting the value attribute again re-instantiates. |
+
+`window.lnCircularProgress(root)` re-runs the init scan over `root`. The shared `registerComponent` observer already covers AJAX inserts; call this manually only for Shadow DOM roots or foreign documents the observer cannot reach.
+
+## Examples
+
+### Minimal
+
+```html
+<div data-ln-circular-progress="75" class="success"></div>
+```
+
+75% green ring with the default 4 rem diameter. The centre label reads "75%" automatically. No JS required.
+
+### Reactive — button-driven
+
+```html
+<div id="ring" data-ln-circular-progress="0" class="lg"></div>
+<button id="advance">+10%</button>
+```
+
+```js
+let pct = 0;
+document.getElementById('advance').addEventListener('click', function () {
+	pct = Math.min(100, pct + 10);
+	document.getElementById('ring').setAttribute('data-ln-circular-progress', pct);
+});
+```
+
+Each attribute write triggers a re-render and a `:change` event. The CSS
+transition animates the arc from the previous offset to the new one.
+
+### Custom max + label
+
+```html
+<!-- 7 out of 10 — arc fills to 70%, label shows the count -->
+<div data-ln-circular-progress="7"
+     data-ln-circular-progress-max="10"
+     data-ln-circular-progress-label="7/10"
+     class="lg success">
+</div>
+```
+
+`max="10"` shifts the denominator so 7 maps to 70% of the arc. `label="7/10"` overrides the centre text — without it, the centre would read "70%". Both attributes are usually set together for non-percentage scales.
+
+## What it does NOT do
+
+- No indeterminate / spinner mode. An empty value renders 0% (empty track). For an indeterminate spinner use `@mixin loader`.
+- No automatic ARIA. Consumer adds `role="progressbar"` and keeps `aria-valuenow` in sync.
+- No debounce on rapid attribute writes — each write triggers a synchronous render and a `:change` event.
+- No `setValue()` / `setMax()` / imperative API. `el.setAttribute('data-ln-circular-progress', n)` is the canonical update path.
+
+## Integration and Source Files
+
+This component can be loaded either as part of the unified Ashlar bundle or as a standalone zero-dependency script.
+
+### 1. In-Bundle (Standard Integration)
+Include the main Ashlar bundle in your HTML. This bundle registers all Ashlar components, including `ln-circular-progress`:
+```html
+<script src="dist/ln-ashlar.iife.js" defer></script>
+```
+
+### 2. Standalone (Zero-Dependency IIFE)
+If you only need circular progress indicators without the rest of the Ashlar library, load the component's standalone IIFE script:
+```html
+<script src="js/ln-circular-progress/ln-circular-progress.js" defer></script>
+```
+
+### 3. Source & Reference
+* **Active Development Source**: [js/ln-circular-progress/src/ln-circular-progress.js](file:///c:/laragon/www/ln-ashlar/js/ln-circular-progress/src/ln-circular-progress.js) — The source of truth containing the ES module implementation.
+* **Compiled Standalone Release**: [js/ln-circular-progress/ln-circular-progress.js](file:///c:/laragon/www/ln-ashlar/js/ln-circular-progress/ln-circular-progress.js) — The compiled IIFE distribution file.
+
+## See also
+
+- `@mixin circular-progress` (`scss/config/mixins/_circular-progress.scss`) — SVG layout, fill/track stroke tokens, motion-safe transition, size variant mixins.
+- `scss/components/_circular-progress.scss` — default selector application and the `.success` / `.warning` / `.error` colour variant rules.
+- [`ln-progress`](../ln-progress/README.md) — linear sibling. Same contract shape (`data-ln-progress` + `-max`); supports parent-track shared max.
+- [`docs/js/circular-progress.md`](../../docs/js/circular-progress.md) — architecture reference: SVG geometry constants, render flow, MutationObserver filter, performance notes.
+- `@mixin loader` (`scss/config/mixins/_loader.scss`) — indeterminate spinner for operations with no known fraction.
+- [`docs/architecture/data-flow.md`](../../docs/architecture/data-flow.md) — passive renderer pattern used by this component.

package/js/ln-circular-progress/ln-circular-progress.js

@@ -0,0 +1 @@
+(function(){"use strict";function C(e,t,l){e.dispatchEvent(new CustomEvent(t,{bubbles:!0,detail:l||{}}))}function m(e,t){if(!document.body){document.addEventListener("DOMContentLoaded",function(){m(e,t)}),console.warn("["+t+'] Script loaded before <body> — add "defer" to your <script> tag');return}e()}function b(e,t,l,o){if(e.nodeType!==1)return;const c=t.indexOf("[")!==-1||t.indexOf(".")!==-1||t.indexOf("#")!==-1?t:"["+t+"]",h=Array.from(e.querySelectorAll(c));e.matches&&e.matches(c)&&h.push(e);for(const s of h)s[l]||(s[l]=new o(s))}function w(e,t,l,o,u={}){const c=u.extraAttributes||[],h=u.onAttributeChange||null,s=u.onInit||null;function f(p){const d=p||document.body;b(d,e,t,l),s&&s(d)}return m(function(){const p=new MutationObserver(function(n){for(let i=0;i<n.length;i++){const r=n[i];if(r.type==="childList")for(let a=0;a<r.addedNodes.length;a++){const g=r.addedNodes[a];g.nodeType===1&&(b(g,e,t,l),s&&s(g))}else r.type==="attributes"&&(h&&r.target[t]?h(r.target,r.attributeName):(b(r.target,e,t,l),s&&s(r.target)))}});let d=[];if(e.indexOf("[")!==-1){const n=/\[([\w-]+)/g;let i;for(;(i=n.exec(e))!==null;)d.push(i[1])}else d.push(e);p.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:d.concat(c)})},o),window[t]=f,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){f(document.body)}):f(document.body),f}const v={};function y(e,t){v[e]=t}function E(e){return v[e]||{ingress:t=>t,egress:t=>t}}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=y,window.lnCore.getDataMapper=E),(function(){const e="data-ln-circular-progress",t="lnCircularProgress";if(window[t]!==void 0)return;const l="http://www.w3.org/2000/svg",o=36,u=16,c=2*Math.PI*u;function h(n){return this.dom=n,this.svg=null,this.trackCircle=null,this.progressCircle=null,this.labelEl=null,this._attrObserver=null,f.call(this),d.call(this),p.call(this),n.setAttribute("data-ln-circular-progress-initialized",""),this}h.prototype.destroy=function(){this.dom[t]&&(this._attrObserver&&this._attrObserver.disconnect(),this.svg&&this.svg.remove(),this.labelEl&&this.labelEl.remove(),this.dom.removeAttribute("data-ln-circular-progress-initialized"),delete this.dom[t])};function s(n,i){const r=document.createElementNS(l,n);for(const a in i)r.setAttribute(a,i[a]);return r}function f(){this.svg=s("svg",{viewBox:"0 0 "+o+" "+o,"aria-hidden":"true"}),this.trackCircle=s("circle",{cx:o/2,cy:o/2,r:u,fill:"none","stroke-width":"3"}),this.trackCircle.classList.add("ln-circular-progress__track"),this.progressCircle=s("circle",{cx:o/2,cy:o/2,r:u,fill:"none","stroke-width":"3","stroke-linecap":"round","stroke-dasharray":c,"stroke-dashoffset":c,transform:"rotate(-90 "+o/2+" "+o/2+")"}),this.progressCircle.classList.add("ln-circular-progress__fill"),this.svg.appendChild(this.trackCircle),this.svg.appendChild(this.progressCircle),this.labelEl=document.createElement("strong"),this.labelEl.classList.add("ln-circular-progress__label"),this.dom.appendChild(this.svg),this.dom.appendChild(this.labelEl)}function p(){const n=this,i=new MutationObserver(function(r){for(const a of r)(a.attributeName==="data-ln-circular-progress"||a.attributeName==="data-ln-circular-progress-max")&&d.call(n)});i.observe(this.dom,{attributes:!0,attributeFilter:["data-ln-circular-progress","data-ln-circular-progress-max"]}),this._attrObserver=i}function d(){const n=parseFloat(this.dom.getAttribute("data-ln-circular-progress"))||0,i=parseFloat(this.dom.getAttribute("data-ln-circular-progress-max"))||100;let r=i>0?n/i*100:0;r<0&&(r=0),r>100&&(r=100);const a=c-r/100*c;this.progressCircle.setAttribute("stroke-dashoffset",a);const g=this.dom.getAttribute("data-ln-circular-progress-label");this.labelEl.textContent=g!==null?g:Math.round(r)+"%",C(this.dom,"ln-circular-progress:change",{target:this.dom,value:n,max:i,percentage:r})}w(e,t,h,"ln-circular-progress")})()})();

package/js/ln-circular-progress/src/ln-circular-progress.js

@@ -0,0 +1,133 @@
+import { dispatch, registerComponent } from '../../ln-core';
+
+(function () {
+	const DOM_SELECTOR = 'data-ln-circular-progress';
+	const DOM_ATTRIBUTE = 'lnCircularProgress';
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+	const SVG_NS = 'http://www.w3.org/2000/svg';
+	const VIEW_SIZE = 36;
+	const RADIUS = 16;
+	const CIRCUMFERENCE = 2 * Math.PI * RADIUS;
+
+	function _constructor(dom) {
+		this.dom = dom;
+		this.svg = null;
+		this.trackCircle = null;
+		this.progressCircle = null;
+		this.labelEl = null;
+		this._attrObserver = null;
+		_buildSvg.call(this);
+		_render.call(this);
+		_listenValues.call(this);
+		dom.setAttribute('data-ln-circular-progress-initialized', '');
+		return this;
+	}
+
+	_constructor.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+		if (this._attrObserver) {
+			this._attrObserver.disconnect();
+		}
+		if (this.svg) {
+			this.svg.remove();
+		}
+		if (this.labelEl) {
+			this.labelEl.remove();
+		}
+		this.dom.removeAttribute('data-ln-circular-progress-initialized');
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	function _createSvgElement(tag, attrs) {
+		const el = document.createElementNS(SVG_NS, tag);
+		for (const key in attrs) {
+			el.setAttribute(key, attrs[key]);
+		}
+		return el;
+	}
+
+	function _buildSvg() {
+		this.svg = _createSvgElement('svg', {
+			viewBox: '0 0 ' + VIEW_SIZE + ' ' + VIEW_SIZE,
+			'aria-hidden': 'true'
+		});
+
+		this.trackCircle = _createSvgElement('circle', {
+			cx: VIEW_SIZE / 2,
+			cy: VIEW_SIZE / 2,
+			r: RADIUS,
+			fill: 'none',
+			'stroke-width': '3'
+		});
+		this.trackCircle.classList.add('ln-circular-progress__track');
+
+		this.progressCircle = _createSvgElement('circle', {
+			cx: VIEW_SIZE / 2,
+			cy: VIEW_SIZE / 2,
+			r: RADIUS,
+			fill: 'none',
+			'stroke-width': '3',
+			'stroke-linecap': 'round',
+			'stroke-dasharray': CIRCUMFERENCE,
+			'stroke-dashoffset': CIRCUMFERENCE,
+			transform: 'rotate(-90 ' + (VIEW_SIZE / 2) + ' ' + (VIEW_SIZE / 2) + ')'
+		});
+		this.progressCircle.classList.add('ln-circular-progress__fill');
+
+		this.svg.appendChild(this.trackCircle);
+		this.svg.appendChild(this.progressCircle);
+
+		this.labelEl = document.createElement('strong');
+		this.labelEl.classList.add('ln-circular-progress__label');
+
+		this.dom.appendChild(this.svg);
+		this.dom.appendChild(this.labelEl);
+	}
+
+	function _listenValues() {
+		const self = this;
+		const observer = new MutationObserver(function (mutations) {
+			for (const mutation of mutations) {
+				if (mutation.attributeName === 'data-ln-circular-progress' ||
+					mutation.attributeName === 'data-ln-circular-progress-max') {
+					_render.call(self);
+				}
+			}
+		});
+
+		observer.observe(this.dom, {
+			attributes: true,
+			attributeFilter: ['data-ln-circular-progress', 'data-ln-circular-progress-max']
+		});
+
+		this._attrObserver = observer;
+	}
+
+	function _render() {
+		const value = parseFloat(this.dom.getAttribute('data-ln-circular-progress')) || 0;
+		const max = parseFloat(this.dom.getAttribute('data-ln-circular-progress-max')) || 100;
+		let percentage = (max > 0) ? (value / max) * 100 : 0;
+
+		if (percentage < 0) percentage = 0;
+		if (percentage > 100) percentage = 100;
+
+		const offset = CIRCUMFERENCE - (percentage / 100) * CIRCUMFERENCE;
+		this.progressCircle.setAttribute('stroke-dashoffset', offset);
+
+		const label = this.dom.getAttribute('data-ln-circular-progress-label');
+		this.labelEl.textContent = label !== null ? label : Math.round(percentage) + '%';
+
+		dispatch(this.dom, 'ln-circular-progress:change', {
+			target: this.dom,
+			value: value,
+			max: max,
+			percentage: percentage
+		});
+	}
+
+	// ─── Init ──────────────────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _constructor, 'ln-circular-progress');
+})();

package/js/ln-confirm/README.md

@@ -0,0 +1,86 @@
+# ln-confirm
+
+A zero-dependency, ultra-lightweight **Interaction Gate Primitive** (~109 lines of JavaScript) that creates a self-contained, two-click confirmation checkpoint on standard buttons. It intercepts accidental clicks, morphs in-place to reveal confirmation prompts, and passes the second click directly to native platform events.
+
+---
+
+## 🧭 Philosophy & Architecture
+
+1. **In-Place Morphing:** Instead of launching heavy, separate dialogs or using frozen, unstyleable `window.confirm()` scripts, confirmation lives **directly on the target button**. It preserves structural styling while using CSS mixins to display temporary labels or icon tooltips.
+2. **Platform Event Release:** `ln-confirm` does not implement a custom `accept` handler. The acceptance is the standard platform `click` event. On the second click, the component steps out of the way, allowing form submissions (`type="submit"`), links (`href`), or custom AJAX click listeners to execute natively.
+3. **Graceful Auto-Revert:** The gate is timed. When armed, a countdown timer is scheduled. If a second click does not arrive within the window, the button cleanly reverts to its idle text or icon state.
+
+---
+
+## 📦 Minimal Blueprint
+
+### Text-Button Mode
+
+```html
+<button data-ln-confirm="Are you sure you want to delete?">Delete account</button>
+```
+
+On click, the text replaces with the confirmation prompt in-place, and the button accent shifts to error red.
+
+### Icon-Only Mode
+
+```html
+<button aria-label="Delete item" data-ln-confirm="Confirm delete?">
+  <svg class="ln-icon"><use href="#ln-trash"></use></svg>
+</button>
+```
+
+On click, the trash icon swaps to `#ln-check`, a tooltip bubble is displayed above, and the prompt is announced for screen-readers.
+
+---
+
+## 🛠️ Declarative API Contract
+
+### HTML Attributes
+
+| Attribute | Elements | Description |
+| :--- | :--- | :--- |
+| `data-ln-confirm="Prompt"` | `<button>`, `<a>` | Action gate marker. Empty value defaults to `"Confirm?"`. |
+| `data-ln-confirm-timeout="3"` | `<button>`, `<a>` | Auto-revert delay in seconds (default `3`). |
+| `data-confirming="true"` | `<button>` (auto) | Managed state. Set during active confirmation; acts as public CSS hook. |
+| `data-tooltip-text="Prompt"` | `<button>` (auto) | Managed state. Displays tooltip bubble in icon-only mode. |
+
+### JS API
+
+Access the confirmation instance directly via the `lnConfirm` property on the button element:
+
+```javascript
+const button = document.getElementById('delete-btn');
+
+// 1. Check if armed (Boolean getter)
+if (button.lnConfirm.confirming) { ... }
+
+// 2. Disarm immediately, restore visual states, and unbind listeners
+button.lnConfirm.destroy();
+```
+
+---
+
+## ⚡ DOM Events
+
+### Emitted
+
+`ln-confirm` dispatches exactly one event during its lifecycle:
+
+| Event | Bubbles | Payload | Description |
+| :--- | :--- | :--- | :--- |
+| `ln-confirm:waiting` | Yes | `{ target }` | Fires on first click, right after the button arms. Useful for telemetry. |
+
+*Note: There is no `accept` event. Code execution on accept belongs on standard browser `click` or form `submit` handlers.*
+
+---
+
+## ⚠️ Common Pitfalls
+
+- **Listening for an `:accept` event:** There is no `ln-confirm:accept`. Destructive logic belongs in the button's native click handler or form submit listener — which are automatically gated.
+- **Double-Click Protection:** Once the second click executes the target action, the button returns to idle. If your custom AJAX handler takes time, the user can click again and execute duplicate actions. Disable the button on submit:
+  ```javascript
+  form.addEventListener('submit', () => submitButton.disabled = true);
+  ```
+- **GET Request Navigation (`<a>`):** While the script works on links, performing destructive actions via HTTP GET is a security risk (crawlers and pre-fetchers can trigger deletes). Always use `<form method="POST">` with submit buttons instead.
+- **Attachment Order:** `ln-confirm` intercepts first clicks via `stopImmediatePropagation()`. If custom click handlers are bound *before* the bundle loads, they will run on the first click anyway. Ensure scripts are defer-loaded.

package/js/ln-confirm/_ln-confirm.scss

@@ -0,0 +1,13 @@
+// ── JS state: confirm mode color override ──
+// When data-confirming is set (by JS), override --color-primary to error
+// so the button turns red. Tooltip-mode buttons handle color differently.
+[data-confirming]:not(.ln-confirm-tooltip) {
+	--color-primary: var(--color-error);
+}
+
+// ── Overflow escape: tooltip inside clipped containers ──
+// [data-ln-table] uses overflow:clip which clips the ::after tooltip.
+// Temporarily allow overflow when a confirm is active inside.
+[data-ln-table]:has([data-confirming]) {
+	overflow: visible;
+}

package/js/ln-confirm/ln-confirm.js

@@ -0,0 +1 @@
+(function(){"use strict";function A(e,t,s){e.dispatchEvent(new CustomEvent(t,{bubbles:!0,detail:s||{}}))}function p(e,t){if(!document.body){document.addEventListener("DOMContentLoaded",function(){p(e,t)}),console.warn("["+t+'] Script loaded before <body> — add "defer" to your <script> tag');return}e()}function h(e,t,s,u){if(e.nodeType!==1)return;const i=t.indexOf("[")!==-1||t.indexOf(".")!==-1||t.indexOf("#")!==-1?t:"["+t+"]",n=Array.from(e.querySelectorAll(i));e.matches&&e.matches(i)&&n.push(e);for(const o of n)o[s]||(o[s]=new u(o))}function v(e,t,s,u,r={}){const i=r.extraAttributes||[],n=r.onAttributeChange||null,o=r.onInit||null;function c(m){const l=m||document.body;h(l,e,t,s),o&&o(l)}return p(function(){const m=new MutationObserver(function(f){for(let d=0;d<f.length;d++){const a=f[d];if(a.type==="childList")for(let g=0;g<a.addedNodes.length;g++){const b=a.addedNodes[g];b.nodeType===1&&(h(b,e,t,s),o&&o(b))}else a.type==="attributes"&&(n&&a.target[t]?n(a.target,a.attributeName):(h(a.target,e,t,s),o&&o(a.target)))}});let l=[];if(e.indexOf("[")!==-1){const f=/\[([\w-]+)/g;let d;for(;(d=f.exec(e))!==null;)l.push(d[1])}else l.push(e);m.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:l.concat(i)})},u),window[t]=c,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){c(document.body)}):c(document.body),c}const T={};function y(e,t){T[e]=t}function C(e){return T[e]||{ingress:t=>t,egress:t=>t}}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=y,window.lnCore.getDataMapper=C),(function(){const e="data-ln-confirm",t="lnConfirm",s="data-ln-confirm-timeout";if(window[t]!==void 0)return;function r(i){this.dom=i,this.confirming=!1,this.originalText=i.textContent.trim(),this.confirmText=i.getAttribute(e)||"Confirm?",this.revertTimer=null,this._submitted=!1;const n=this;return this._onClick=function(o){if(!n.confirming)o.preventDefault(),o.stopImmediatePropagation(),n._enterConfirm();else{if(n._submitted)return;n._submitted=!0,n._reset()}},i.addEventListener("click",this._onClick),this}r.prototype._getTimeout=function(){const i=parseFloat(this.dom.getAttribute(s));return isNaN(i)||i<=0?3:i},r.prototype._enterConfirm=function(){this.confirming=!0,this.dom.setAttribute("data-confirming","true");var i=this.dom.querySelector("svg.ln-icon use");i&&this.originalText===""?(this.isIconButton=!0,this.originalIconHref=i.getAttribute("href"),i.setAttribute("href","#ln-check"),this.dom.classList.add("ln-confirm-tooltip"),this.dom.setAttribute("data-tooltip-text",this.confirmText),this.originalAriaLabel=this.dom.getAttribute("aria-label"),this.dom.setAttribute("aria-label",this.confirmText),this.alertNode=document.createElement("span"),this.alertNode.className="sr-only",this.alertNode.setAttribute("role","alert"),this.alertNode.textContent=this.confirmText,this.dom.appendChild(this.alertNode)):this.dom.textContent=this.confirmText,this._startTimer(),A(this.dom,"ln-confirm:waiting",{target:this.dom})},r.prototype._startTimer=function(){this.revertTimer&&clearTimeout(this.revertTimer);const i=this,n=this._getTimeout()*1e3;this.revertTimer=setTimeout(function(){i._reset()},n)},r.prototype._reset=function(){if(this._submitted=!1,this.confirming=!1,this.dom.removeAttribute("data-confirming"),this.isIconButton){var i=this.dom.querySelector("svg.ln-icon use");i&&this.originalIconHref&&i.setAttribute("href",this.originalIconHref),this.dom.classList.remove("ln-confirm-tooltip"),this.dom.removeAttribute("data-tooltip-text"),this.originalAriaLabel!==null&&this.originalAriaLabel!==void 0?this.dom.setAttribute("aria-label",this.originalAriaLabel):this.dom.removeAttribute("aria-label"),this.originalAriaLabel=null,this.alertNode&&this.alertNode.parentNode===this.dom&&this.dom.removeChild(this.alertNode),this.alertNode=null,this.isIconButton=!1,this.originalIconHref=null}else this.dom.textContent=this.originalText;this.revertTimer&&(clearTimeout(this.revertTimer),this.revertTimer=null)},r.prototype.destroy=function(){this.dom[t]&&(this._reset(),this.dom.removeEventListener("click",this._onClick),delete this.dom[t])},v(e,t,r,"ln-confirm")})()})();