@livenetworks/ashlar 1.3.2

package/js/ln-toast/README.md

@@ -0,0 +1,122 @@
+# ln-toast
+
+> Service-style non-blocking status notifications, managed reactively via window events.
+
+---
+
+## 1. Philosophy & The Toast Mindset
+
+In `ln-ashlar`, the core design principle is **decoupling**. Toasts are a pure application-level service.
+
+1. **Zero-Markup Dispatch (JavaScript)**: Components and pages never import toast files or call imperative layout methods directly. To show a notification, any script or controller simply dispatches an `ln-toast:enqueue` event to the global `window` object.
+2. **Central Coordination (The Service)**: A single viewport container (`[data-ln-toast]`) listens for these window-level events, builds card elements dynamically from templates, coordinates automatic 6-second exit timers, pauses timers on mouse hover, and destroys elements after animations.
+3. **Decoupled Styling (CSS)**: Visual alert chrome, slide-in animations, and side-accent status colors are handled in Vanilla CSS. The library ships mixins like `@include toast-container` and `@include toast-card` for styling.
+
+---
+
+## 2. Minimal Blueprint
+
+To enable toasts, simply place a single container `<ul>` in your HTML layout (typically right before the closing `</body>` tag).
+
+```html
+<!-- The Central Toast Container -->
+<ul data-ln-toast data-ln-toast-timeout="6000" data-ln-toast-max="5"></ul>
+```
+
+### Key Anatomy Rules
+- **The Container (`data-ln-toast`)**: Creates the toast listener service.
+- **Auto-Dismiss Timeout (`data-ln-toast-timeout="6000"`)**: Default dismissal duration in milliseconds. Use `0` for persistent notifications.
+- **Max Stack size (`data-ln-toast-max="5"`)**: Evicts the oldest toast when the count exceeds the threshold.
+
+---
+
+## 3. The Window API Contract
+
+Toasts are triggered exclusively by dispatching CustomEvents on the global `window` object. **The window event is the sole contract.**
+
+```js
+// Dispatch a success notification
+window.dispatchEvent(new CustomEvent('ln-toast:enqueue', {
+    detail: { 
+        type: 'success', 
+        title: 'Saved', 
+        message: 'Changes have been saved successfully.' 
+    }
+}));
+```
+
+### Enqueue Event Options (`ln-toast:enqueue`)
+Pass options inside the event's `detail` object:
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | `success\|error\|warn\|info` | Toast category. Drives accents, aria-live roles, and default titles. |
+| `title` | string | Optional card title. |
+| `message` | string \| string[] | Card body content. Pass an array of strings to render a bulleted validation error list. |
+| `timeout` | number | Dismissal timeout in ms. Use `0` to make it persistent. |
+
+### Clear Event (`ln-toast:clear`)
+Dismiss all active toasts in the viewport:
+```js
+window.dispatchEvent(new CustomEvent('ln-toast:clear'));
+```
+
+---
+
+## 4. Toast Types & Default Accessibility
+
+ARIA roles and accessibility live-regions are injected automatically by the component depending on the category:
+
+| Category | Default Title | `aria-live` | `role` |
+|---|---|---|---|
+| `success` | Success | `polite` | `status` |
+| `error` | Error | `assertive` | `alert` |
+| `warn` | Warning | `polite` | `status` |
+| `info` | Information | `polite` | `status` |
+
+---
+
+## 5. Integration Patterns
+
+### A. SSR-Rendered Flash Messages (Hydration)
+For server-side frameworks (like Laravel, Rails, or ASP.NET), you can place initial toast cards inside the container. The component will hydrate and auto-dismiss them on load:
+```html
+<ul data-ln-toast>
+    <li data-ln-toast-item data-type="success" data-title="Saved">
+        Changes have been saved successfully.
+    </li>
+</ul>
+```
+
+### B. Bulleted Validation Error Maps
+To display a list of form validation errors inside a single toast, pass an array of strings to `message`:
+```js
+window.dispatchEvent(new CustomEvent('ln-toast:enqueue', {
+    detail: {
+        type: 'error',
+        title: 'Validation Failed',
+        message: ['Email is required.', 'Password is too short.']
+    }
+}));
+```
+
+---
+
+## 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-toast/ln-toast.js" defer></script>
+  ```
+- **Active Source (ESM)**: Development source is located at [js/ln-toast/src/ln-toast.js](file:///c:/laragon/www/ln-ashlar/js/ln-toast/src/ln-toast.js).
+
+---
+
+## Related
+- **[`ln-modal`](../ln-modal/README.md)** — Viewport-blocking focus-gated dialogs.
+- **[`ln-confirm`](../ln-confirm/README.md)** — Lightweight inline action confirmations.
+- **Architecture deep-dive** — [`docs/js/toast.md`](../../docs/js/toast.md).

package/js/ln-toast/ln-toast.js

@@ -0,0 +1,15 @@
+(function(){"use strict";const A={};function q(o,r){A[o]||(A[o]=document.querySelector('[data-ln-template="'+o+'"]'));const u=A[o];return u?u.content.cloneNode(!0):(console.warn("["+r+'] Template "'+o+'" not found'),null)}function M(o,r){if(!o||!r)return o;const u=o.querySelectorAll("[data-ln-field]");for(let i=0;i<u.length;i++){const a=u[i],c=a.getAttribute("data-ln-field");r[c]!=null&&(a.textContent=r[c])}const _=o.querySelectorAll("[data-ln-attr]");for(let i=0;i<_.length;i++){const a=_[i],c=a.getAttribute("data-ln-attr").split(",");for(let f=0;f<c.length;f++){const m=c[f].trim().split(":");if(m.length!==2)continue;const y=m[0].trim(),d=m[1].trim();r[d]!=null&&a.setAttribute(y,r[d])}}const g=o.querySelectorAll("[data-ln-show]");for(let i=0;i<g.length;i++){const a=g[i],c=a.getAttribute("data-ln-show");c in r&&a.classList.toggle("hidden",!r[c])}const h=o.querySelectorAll("[data-ln-class]");for(let i=0;i<h.length;i++){const a=h[i],c=a.getAttribute("data-ln-class").split(",");for(let f=0;f<c.length;f++){const m=c[f].trim().split(":");if(m.length!==2)continue;const y=m[0].trim(),d=m[1].trim();d in r&&a.classList.toggle(y,!!r[d])}}return o}function b(o,r){if(!document.body){document.addEventListener("DOMContentLoaded",function(){b(o,r)}),console.warn("["+r+'] Script loaded before <body> — add "defer" to your <script> tag');return}o()}function x(o,r,u){if(o){const _=o.querySelector('[data-ln-template="'+r+'"]');if(_)return _.content.cloneNode(!0)}return q(r,u)}const w={};function N(o,r){w[o]=r}function D(o){return w[o]||{ingress:r=>r,egress:r=>r}}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=N,window.lnCore.getDataMapper=D);const I=`<li class="ln-toast__item">\r
+	<div class="ln-toast__card" data-ln-attr="role:role, aria-live:ariaLive">\r
+		<div class="ln-toast__side">\r
+			<svg class="ln-icon" aria-hidden="true"><use href=""></use></svg>\r
+		</div>\r
+		<div class="ln-toast__content">\r
+			<div class="ln-toast__head">\r
+				<strong class="ln-toast__title" data-ln-field="title"></strong>\r
+			</div>\r
+			<button type="button" class="ln-toast__close" aria-label="Close"><svg class="ln-icon" aria-hidden="true"><use href="#ln-x"></use></svg></button>\r
+			<div class="ln-toast__body" data-ln-show="hasBody"></div>\r
+		</div>\r
+	</div>\r
+</li>\r
+`;(function(){const o="data-ln-toast",r="lnToast",u="ln-toast-item",_={success:"circle-check",error:"circle-x",warn:"alert-triangle",info:"info-circle"},g={success:"success",error:"error",warn:"warning",info:"info"},h={success:"Success",error:"Error",warn:"Warning",info:"Information"};if(window.__lnToastLoaded)return;window.__lnToastLoaded=!0;function i(){if(document.querySelector('[data-ln-template="ln-toast-item"]')||!document.body)return;const t=document.createElement("template");t.setAttribute("data-ln-template","ln-toast-item"),t.innerHTML=I,document.body.appendChild(t)}function a(t){if(!t||t.nodeType!==1)return;const e=Array.from(t.querySelectorAll("["+o+"]"));t.hasAttribute&&t.hasAttribute(o)&&e.push(t);for(const n of e)n[r]||new c(n)}function c(t){this.dom=t,t[r]=this,this.timeoutDefault=parseInt(t.getAttribute("data-ln-toast-timeout")||"6000",10),this.max=parseInt(t.getAttribute("data-ln-toast-max")||"5",10);for(const e of Array.from(t.querySelectorAll("[data-ln-toast-item]")))B(e,t);return this}c.prototype.destroy=function(){if(this.dom[r]){for(const t of Array.from(this.dom.children))d(t);delete this.dom[r]}};function f(t,e){const n=((t.type||"info")+"").toLowerCase(),l=x(e,u,"ln-toast");if(!l)return console.warn('[ln-toast] Template "'+u+'" not found'),null;const s=l.firstElementChild;if(!s)return null;const p=!!(t.message||t.data&&t.data.errors);M(s,{title:t.title||h[n]||h.info,role:n==="error"?"alert":"status",ariaLive:n==="error"?"assertive":"polite",hasBody:p});const v=s.querySelector(".ln-toast__card");v&&v.classList.add(g[n]||"info");const T=s.querySelector(".ln-toast__side");if(T){const S=T.querySelector("use");S&&S.setAttribute("href","#ln-"+(_[n]||_.info))}const L=s.querySelector(".ln-toast__body");L&&p&&m(L,t);const E=s.querySelector(".ln-toast__close");return E&&E.addEventListener("click",function(){d(s)}),s}function m(t,e){if(e.message)if(Array.isArray(e.message)){const n=document.createElement("ul");for(const l of e.message){const s=document.createElement("li");s.textContent=l,n.appendChild(s)}t.appendChild(n)}else{const n=document.createElement("p");n.textContent=e.message,t.appendChild(n)}if(e.data&&e.data.errors){const n=document.createElement("ul");for(const l of Object.values(e.data.errors).flat()){const s=document.createElement("li");s.textContent=l,n.appendChild(s)}t.appendChild(n)}}function y(t,e){for(;t.dom.children.length>=t.max;)t.dom.removeChild(t.dom.firstElementChild);t.dom.appendChild(e),requestAnimationFrame(()=>e.classList.add("ln-toast__item--in"))}function d(t){!t||!t.parentNode||(clearTimeout(t._timer),t.classList.remove("ln-toast__item--in"),t.classList.add("ln-toast__item--out"),setTimeout(()=>{t.parentNode&&t.parentNode.removeChild(t)},200))}function C(t){let e=t&&t.container;return typeof e=="string"&&(e=document.querySelector(e)),e instanceof HTMLElement||(e=document.querySelector("["+o+"]")||document.getElementById("ln-toast-container")),e||null}function B(t,e){const n=((t.getAttribute("data-type")||"info")+"").toLowerCase(),l=t.getAttribute("data-title"),s=(t.innerText||t.textContent||"").trim(),p=f({type:n,title:l,message:s||void 0},e);p&&(t.parentNode&&t.parentNode.replaceChild(p,t),requestAnimationFrame(()=>p.classList.add("ln-toast__item--in")))}function O(t){const e=t.detail||{},n=C(e);if(!n){console.warn("[ln-toast] No toast container found");return}const l=n[r]||new c(n),s=f(e,n);if(!s)return;const p=Number.isFinite(e.timeout)?e.timeout:l.timeoutDefault;y(l,s),p>0&&(s._timer=setTimeout(()=>d(s),p))}function F(t){const e=t&&t.detail||{};if(e.container){const n=C(e);if(n)for(const l of Array.from(n.children))d(l)}else{const n=document.querySelectorAll("["+o+"]");for(const l of Array.from(n))for(const s of Array.from(l.children))d(s)}}b(function(){i(),window.addEventListener("ln-toast:enqueue",O),window.addEventListener("ln-toast:clear",F),new MutationObserver(function(e){for(const n of e){if(n.type==="attributes"){a(n.target);continue}for(const l of n.addedNodes)a(l)}}).observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:[o]}),a(document.body)},"ln-toast")})()})();

package/js/ln-toast/src/ln-toast.js

@@ -0,0 +1,210 @@
+/* Live Networks — ln-toast (side-accent with icons) */
+import { guardBody, cloneTemplateScoped, fill } from '../../ln-core';
+import DEFAULT_TEMPLATE_HTML from '../template.html?raw';
+
+(function () {
+	const DOM_SELECTOR = "data-ln-toast";
+	const DOM_ATTRIBUTE = "lnToast";
+	const TEMPLATE_NAME = "ln-toast-item";
+
+	const TYPE_ICON = { success: 'circle-check', error: 'circle-x', warn: 'alert-triangle', info: 'info-circle' };
+
+	const STATUS_CLASS = { success: 'success', error: 'error', warn: 'warning', info: 'info' };
+
+	const DEFAULT_TITLES = { success: 'Success', error: 'Error', warn: 'Warning', info: 'Information' };
+
+	if (window.__lnToastLoaded) return;
+	window.__lnToastLoaded = true;
+
+	function _ensureTemplate() {
+		if (document.querySelector('[data-ln-template="ln-toast-item"]')) return;
+		if (!document.body) return;
+		const tmpl = document.createElement('template');
+		// Trust boundary: DEFAULT_TEMPLATE_HTML is a hardcoded library constant resolved at build time via ?raw import.
+		tmpl.setAttribute('data-ln-template', 'ln-toast-item');
+		tmpl.innerHTML = DEFAULT_TEMPLATE_HTML;
+		document.body.appendChild(tmpl);
+	}
+
+	function _findContainers(root) {
+		if (!root || root.nodeType !== 1) return;
+		const items = Array.from(root.querySelectorAll("[" + DOM_SELECTOR + "]"));
+		if (root.hasAttribute && root.hasAttribute(DOM_SELECTOR)) items.push(root);
+		for (const el of items) {
+			if (!el[DOM_ATTRIBUTE]) new _Component(el);
+		}
+	}
+
+	function _Component(dom) {
+		this.dom = dom;
+		dom[DOM_ATTRIBUTE] = this;
+		this.timeoutDefault = parseInt(dom.getAttribute("data-ln-toast-timeout") || "6000", 10);
+		this.max = parseInt(dom.getAttribute("data-ln-toast-max") || "5", 10);
+
+		for (const li of Array.from(dom.querySelectorAll("[data-ln-toast-item]"))) {
+			_hydrateLI(li, dom);
+		}
+		return this;
+	}
+
+	_Component.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+		for (const li of Array.from(this.dom.children)) {
+			_dismiss(li);
+		}
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	function _buildItem(opts, container) {
+		const type = ((opts.type || "info") + "").toLowerCase();
+		const fragment = cloneTemplateScoped(container, TEMPLATE_NAME, 'ln-toast');
+		if (!fragment) {
+			console.warn('[ln-toast] Template "' + TEMPLATE_NAME + '" not found');
+			return null;
+		}
+		const li = fragment.firstElementChild;
+		if (!li) return null;
+
+		const hasBody = !!(opts.message || (opts.data && opts.data.errors));
+
+		fill(li, {
+			title: opts.title || DEFAULT_TITLES[type] || DEFAULT_TITLES.info,
+			role: type === 'error' ? 'alert' : 'status',
+			ariaLive: type === 'error' ? 'assertive' : 'polite',
+			hasBody: hasBody
+		});
+
+		const card = li.querySelector('.ln-toast__card');
+		if (card) card.classList.add(STATUS_CLASS[type] || 'info');
+
+		const side = li.querySelector('.ln-toast__side');
+		if (side) {
+			const useEl = side.querySelector('use');
+			if (useEl) useEl.setAttribute('href', '#ln-' + (TYPE_ICON[type] || TYPE_ICON.info));
+		}
+
+		const bodyEl = li.querySelector('.ln-toast__body');
+		if (bodyEl && hasBody) _renderBody(bodyEl, opts);
+
+		const closeBtn = li.querySelector('.ln-toast__close');
+		if (closeBtn) closeBtn.addEventListener('click', function () { _dismiss(li); });
+
+		return li;
+	}
+
+	function _renderBody(bodyEl, opts) {
+		if (opts.message) {
+			if (Array.isArray(opts.message)) {
+				const ul = document.createElement("ul");
+				for (const msg of opts.message) {
+					const lie = document.createElement("li");
+					lie.textContent = msg;
+					ul.appendChild(lie);
+				}
+				bodyEl.appendChild(ul);
+			} else {
+				const p = document.createElement("p");
+				p.textContent = opts.message;
+				bodyEl.appendChild(p);
+			}
+		}
+		if (opts.data && opts.data.errors) {
+			const ul = document.createElement("ul");
+			for (const err of Object.values(opts.data.errors).flat()) {
+				const lie = document.createElement("li");
+				lie.textContent = err;
+				ul.appendChild(lie);
+			}
+			bodyEl.appendChild(ul);
+		}
+	}
+
+	function _append(cmp, li) {
+		while (cmp.dom.children.length >= cmp.max) cmp.dom.removeChild(cmp.dom.firstElementChild);
+		cmp.dom.appendChild(li);
+		requestAnimationFrame(() => li.classList.add("ln-toast__item--in"));
+	}
+
+	function _dismiss(li) {
+		if (!li || !li.parentNode) return;
+		clearTimeout(li._timer);
+		li.classList.remove("ln-toast__item--in");
+		li.classList.add("ln-toast__item--out");
+		setTimeout(() => { li.parentNode && li.parentNode.removeChild(li); }, 200);
+	}
+
+	function _resolveContainer(detail) {
+		let container = detail && detail.container;
+		if (typeof container === "string") container = document.querySelector(container);
+		if (!(container instanceof HTMLElement)) {
+			container = document.querySelector("[" + DOM_SELECTOR + "]") || document.getElementById("ln-toast-container");
+		}
+		return container || null;
+	}
+
+	function _hydrateLI(li, container) {
+		const type = ((li.getAttribute("data-type") || "info") + "").toLowerCase();
+		const titleA = li.getAttribute("data-title");
+		const msgText = (li.innerText || li.textContent || "").trim();
+
+		const built = _buildItem({
+			type: type,
+			title: titleA,
+			message: msgText || undefined
+		}, container);
+
+		if (!built) return;
+
+		li.parentNode && li.parentNode.replaceChild(built, li);
+		requestAnimationFrame(() => built.classList.add("ln-toast__item--in"));
+	}
+
+	function _onEnqueue(e) {
+		const detail = e.detail || {};
+		const container = _resolveContainer(detail);
+		if (!container) {
+			console.warn('[ln-toast] No toast container found');
+			return;
+		}
+		const cmp = container[DOM_ATTRIBUTE] || new _Component(container);
+		const li = _buildItem(detail, container);
+		if (!li) return;
+		const timeout = Number.isFinite(detail.timeout) ? detail.timeout : cmp.timeoutDefault;
+		_append(cmp, li);
+		if (timeout > 0) li._timer = setTimeout(() => _dismiss(li), timeout);
+	}
+
+	function _onClear(e) {
+		const detail = (e && e.detail) || {};
+		if (detail.container) {
+			const el = _resolveContainer(detail);
+			if (el) {
+				for (const child of Array.from(el.children)) _dismiss(child);
+			}
+		} else {
+			const containers = document.querySelectorAll("[" + DOM_SELECTOR + "]");
+			for (const el of Array.from(containers)) {
+				for (const child of Array.from(el.children)) _dismiss(child);
+			}
+		}
+	}
+
+	guardBody(function () {
+		_ensureTemplate();
+
+		window.addEventListener('ln-toast:enqueue', _onEnqueue);
+		window.addEventListener('ln-toast:clear', _onClear);
+
+		const observer = new MutationObserver(function (muts) {
+			for (const m of muts) {
+				if (m.type === 'attributes') { _findContainers(m.target); continue; }
+				for (const n of m.addedNodes) {
+					_findContainers(n);
+				}
+			}
+		});
+		observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: [DOM_SELECTOR] });
+
+		_findContainers(document.body);
+	}, 'ln-toast');
+})();

package/js/ln-toast/template.html

@@ -0,0 +1,14 @@
+<li class="ln-toast__item">
+	<div class="ln-toast__card" data-ln-attr="role:role, aria-live:ariaLive">
+		<div class="ln-toast__side">
+			<svg class="ln-icon" aria-hidden="true"><use href=""></use></svg>
+		</div>
+		<div class="ln-toast__content">
+			<div class="ln-toast__head">
+				<strong class="ln-toast__title" data-ln-field="title"></strong>
+			</div>
+			<button type="button" class="ln-toast__close" aria-label="Close"><svg class="ln-icon" aria-hidden="true"><use href="#ln-x"></use></svg></button>
+			<div class="ln-toast__body" data-ln-show="hasBody"></div>
+		</div>
+	</div>
+</li>

package/js/ln-toggle/README.md

@@ -0,0 +1,137 @@
+# ln-toggle
+
+> The smallest reactive primitive in `ln-ashlar` — a highly-specialized binary state machine. 
+
+---
+
+## 1. Philosophy & The Primitive Mindset
+
+In `ln-ashlar`, the core design principle is **orthogonality**. Rather than creating heavy components that mix state, visual presentation, and layout, we separate them into isolated concerns:
+
+1. **The State Machine (JavaScript)**: The `ln-toggle` component (145 lines) only manages binary `open` / `close` state in the DOM and synchronizes ARIA accessibility. It does not own animations or visual geometries.
+2. **The Visual Presentation (CSS)**: Visual transitions are handled in Vanilla CSS. The component simply toggles the `.open` class on the panel. CSS reads this class and runs transitions (e.g. height collapse or sliding drawers).
+3. **Decoupled Binding (HTML)**: Triggers and panels are matched purely by ID. They can live anywhere in the DOM. Multiple triggers pointing to a single panel are supported natively, and all triggers stay perfectly synchronized.
+
+---
+
+## 2. Minimal Blueprint
+
+Triggers and panels are bound via ID. A panel must have a unique `id` and the `data-ln-toggle` attribute.
+
+```html
+<!-- Trigger anywhere -->
+<button data-ln-toggle-for="example-panel">Toggle Options</button>
+
+<!-- Panel anywhere -->
+<section id="example-panel" data-ln-toggle class="collapsible">
+    <article class="collapsible-body">
+        <p>This is smooth collapsible content.</p>
+    </article>
+</section>
+```
+
+### Key Anatomy Rules
+- **The Panel (`data-ln-toggle`)**: The value `open` represents open; anything else (empty or `close`) represents closed.
+- **The Trigger (`data-ln-toggle-for="id"`)**: Automatically intercepts clicks to toggle the panel. 
+- **The Close Trigger (`data-ln-toggle-action="close"`)**: Forces the trigger to only close the panel (e.g. an "X" button inside a sidebar drawer).
+- **The Body (`.collapsible-body`)**: Holds all padding and margins. The parent `.collapsible` container must have zero padding so it can transition to exactly `0px` height cleanly.
+
+---
+
+## 3. The Declarative API & State Contract
+
+There are no imperative JavaScript methods (like `open()` or `close()`) on the component instance. **The HTML attribute is the sole contract.** 
+
+Triggers, sibling components, external scripts, and manual DevTools edits all change state by writing the attribute:
+
+```js
+const panel = document.getElementById('example-panel');
+
+// Open the panel
+panel.setAttribute('data-ln-toggle', 'open');
+
+// Close the panel
+panel.setAttribute('data-ln-toggle', 'close');
+
+// Read-only state query
+panel.lnToggle.isOpen; // Returns true/false
+```
+
+### Attributes
+- `data-ln-toggle`: Placed on the panel to create the toggle instance.
+- `data-ln-toggle-for`: Placed on triggers referencing the panel ID.
+- `data-ln-toggle-action="open|close"`: Forces a trigger button to only open or only close the target.
+- `data-ln-persist`: Saves the panel state individually in `localStorage`. 
+  - storage key: `ln:toggle:{pagePath}:{id}`. Same IDs on different pages store separately.
+
+---
+
+## 4. Transition Events
+
+All events bubble. `event.detail.target` is always the panel element.
+
+| Event | Cancelable | Dispatched When |
+|---|---|---|
+| **`ln-toggle:before-open`** | **Yes** | After attribute flips to `"open"`, before transition starts. Calling `event.preventDefault()` cancels the transition and reverts the attribute. |
+| **`ln-toggle:open`** | No | After panel is fully open, classes added, and ARIA synced. |
+| **`ln-toggle:before-close`** | **Yes** | After attribute flips to `"close"`, before transition starts. Calling `event.preventDefault()` cancels the close and reverts the attribute. |
+| **`ln-toggle:close`** | No | After panel is fully closed, classes removed, and ARIA synced. |
+
+```js
+// Example: Cancel open transition for unauthorized users
+document.addEventListener('ln-toggle:before-open', (e) => {
+    if (e.detail.target.id === 'secure-panel' && !currentUser.isAdmin) {
+        e.preventDefault(); // Reverts attribute back to "close"
+    }
+});
+```
+
+---
+
+## 5. Integration Patterns
+
+### A. Sidebar Drawer
+Combine the panel with the library's `@mixin sidebar-drawer` and add a close button inside the sidebar:
+```html
+<aside id="menu" data-ln-toggle data-ln-persist class="sidebar">
+    <button data-ln-toggle-for="menu" data-ln-toggle-action="close">×</button>
+</aside>
+```
+
+### B. Smooth Height Collapsible
+Combine the panel with the library's `@mixin collapsible` and `.collapsible-body` wrapper to animate height cleanly:
+```html
+<section id="panel" data-ln-toggle class="collapsible">
+    <div class="collapsible-body">Content goes here...</div>
+</section>
+```
+
+### C. Dismissible Alert
+Combine the alert card with `data-ln-persist` so that once the user closes the alert, it stays closed across page reloads:
+```html
+<div class="alert" id="promo-banner" data-ln-toggle="open" data-ln-persist>
+    <p>Promo code active!</p>
+    <button data-ln-toggle-for="promo-banner" data-ln-toggle-action="close">×</button>
+</div>
+```
+
+---
+
+## 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-toggle/ln-toggle.js" defer></script>
+  ```
+- **Active Source (ESM)**: Development source is located at [js/ln-toggle/src/ln-toggle.js](file:///c:/laragon/www/ln-ashlar/js/ln-toggle/src/ln-toggle.js).
+
+---
+
+## Related
+- **[`ln-accordion`](../ln-accordion/README.md)** — Single-open coordinator for toggle panels.
+- **[`ln-dropdown`](../ln-dropdown/README.md)** — Menu wrapper adding click-outside/teleportation.
+- **Architecture deep-dive** — [`docs/js/toggle.md`](../../docs/js/toggle.md).

package/js/ln-toggle/ln-toggle.js

@@ -0,0 +1 @@
+(function(){"use strict";function h(n,t,o){n.dispatchEvent(new CustomEvent(t,{bubbles:!0,detail:o||{}}))}function A(n,t,o){const i=new CustomEvent(t,{bubbles:!0,cancelable:!0,detail:o||{}});return n.dispatchEvent(i),i}function m(n,t){if(!document.body){document.addEventListener("DOMContentLoaded",function(){m(n,t)}),console.warn("["+t+'] Script loaded before <body> — add "defer" to your <script> tag');return}n()}function y(n,t,o,i){if(n.nodeType!==1)return;const b=t.indexOf("[")!==-1||t.indexOf(".")!==-1||t.indexOf("#")!==-1?t:"["+t+"]",e=Array.from(n.querySelectorAll(b));n.matches&&n.matches(b)&&e.push(n);for(const r of e)r[o]||(r[o]=new i(r))}function E(n,t,o,i,g={}){const b=g.extraAttributes||[],e=g.onAttributeChange||null,r=g.onInit||null;function s(a){const l=a||document.body;y(l,n,t,o),r&&r(l)}return m(function(){const a=new MutationObserver(function(f){for(let u=0;u<f.length;u++){const c=f[u];if(c.type==="childList")for(let d=0;d<c.addedNodes.length;d++){const p=c.addedNodes[d];p.nodeType===1&&(y(p,n,t,o),r&&r(p))}else c.type==="attributes"&&(e&&c.target[t]?e(c.target,c.attributeName):(y(c.target,n,t,o),r&&r(c.target)))}});let l=[];if(n.indexOf("[")!==-1){const f=/\[([\w-]+)/g;let u;for(;(u=f.exec(n))!==null;)l.push(u[1])}else l.push(n);a.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:l.concat(b)})},i),window[t]=s,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){s(document.body)}):s(document.body),s}const w={};function C(n,t){w[n]=t}function L(n){return w[n]||{ingress:t=>t,egress:t=>t}}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=C,window.lnCore.getDataMapper=L);const T="ln:";function x(){return location.pathname.replace(/\/+$/,"").toLowerCase()||"/"}function v(n,t){const o=t.getAttribute("data-ln-persist"),i=o!==null&&o!==""?o:t.id;return i?T+n+":"+x()+":"+i:(console.warn('[ln-persist] Element requires id or data-ln-persist="key"',t),null)}function S(n,t){const o=v(n,t);if(!o)return null;try{const i=localStorage.getItem(o);return i!==null?JSON.parse(i):null}catch{return null}}function O(n,t,o){const i=v(n,t);if(i)try{localStorage.setItem(i,JSON.stringify(o))}catch{}}(function(){const n="data-ln-toggle",t="lnToggle";if(window[t]!==void 0)return;function o(e){const r=Array.from(e.querySelectorAll("[data-ln-toggle-for]"));e.hasAttribute&&e.hasAttribute("data-ln-toggle-for")&&r.push(e);for(const s of r){if(s[t+"Trigger"])continue;const a=function(u){if(u.ctrlKey||u.metaKey||u.button===1)return;u.preventDefault();const c=s.getAttribute("data-ln-toggle-for"),d=document.getElementById(c);if(!d||!d[t])return;const p=s.getAttribute("data-ln-toggle-action")||"toggle";if(p==="open")d.setAttribute(n,"open");else if(p==="close")d.setAttribute(n,"close");else if(p==="toggle"){const I=d.getAttribute(n);d.setAttribute(n,I==="open"?"close":"open")}};s.addEventListener("click",a),s[t+"Trigger"]=a;const l=s.getAttribute("data-ln-toggle-for"),f=document.getElementById(l);f&&f[t]&&s.setAttribute("aria-expanded",f[t].isOpen?"true":"false")}}function i(e,r){const s=document.querySelectorAll('[data-ln-toggle-for="'+e.id+'"]');for(const a of s)a.setAttribute("aria-expanded",r?"true":"false")}function g(e){if(this.dom=e,e.hasAttribute("data-ln-persist")){const r=S("toggle",e);r!==null&&e.setAttribute(n,r)}return this.isOpen=e.getAttribute(n)==="open",this.isOpen&&e.classList.add("open"),i(e,this.isOpen),this}g.prototype.destroy=function(){if(!this.dom[t])return;h(this.dom,"ln-toggle:destroyed",{target:this.dom});const e=document.querySelectorAll('[data-ln-toggle-for="'+this.dom.id+'"]');for(const r of e)r[t+"Trigger"]&&(r.removeEventListener("click",r[t+"Trigger"]),delete r[t+"Trigger"]);delete this.dom[t]};function b(e){const r=e[t];if(!r)return;const a=e.getAttribute(n)==="open";if(a!==r.isOpen)if(a){if(A(e,"ln-toggle:before-open",{target:e}).defaultPrevented){e.setAttribute(n,"close");return}r.isOpen=!0,e.classList.add("open"),i(e,!0),h(e,"ln-toggle:open",{target:e}),e.hasAttribute("data-ln-persist")&&O("toggle",e,"open")}else{if(A(e,"ln-toggle:before-close",{target:e}).defaultPrevented){e.setAttribute(n,"open");return}r.isOpen=!1,e.classList.remove("open"),i(e,!1),h(e,"ln-toggle:close",{target:e}),e.hasAttribute("data-ln-persist")&&O("toggle",e,"close")}}E(n,t,g,"ln-toggle",{extraAttributes:["data-ln-toggle-for"],onAttributeChange:b,onInit:o})})()})();

package/js/ln-toggle/src/ln-toggle.js

@@ -0,0 +1,139 @@
+import { registerComponent, dispatch, dispatchCancelable } from '../../ln-core';
+import { persistGet, persistSet } from '../../ln-core';
+
+(function () {
+	const DOM_SELECTOR = 'data-ln-toggle';
+	const DOM_ATTRIBUTE = 'lnToggle';
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+
+	function _attachTriggers(root) {
+		const triggers = Array.from(root.querySelectorAll('[data-ln-toggle-for]'));
+		if (root.hasAttribute && root.hasAttribute('data-ln-toggle-for')) {
+			triggers.push(root);
+		}
+		for (const btn of triggers) {
+			if (btn[DOM_ATTRIBUTE + 'Trigger']) continue;
+			const handler = function (e) {
+				if (e.ctrlKey || e.metaKey || e.button === 1) return;
+				e.preventDefault();
+				const targetId = btn.getAttribute('data-ln-toggle-for');
+				const target = document.getElementById(targetId);
+				if (!target || !target[DOM_ATTRIBUTE]) return;
+
+				const action = btn.getAttribute('data-ln-toggle-action') || 'toggle';
+				if (action === 'open') {
+					target.setAttribute(DOM_SELECTOR, 'open');
+				} else if (action === 'close') {
+					target.setAttribute(DOM_SELECTOR, 'close');
+				} else if (action === 'toggle') {
+					const current = target.getAttribute(DOM_SELECTOR);
+					target.setAttribute(DOM_SELECTOR, current === 'open' ? 'close' : 'open');
+				}
+				// unknown action — silent no-op
+			};
+			btn.addEventListener('click', handler);
+			btn[DOM_ATTRIBUTE + 'Trigger'] = handler;
+			const targetId = btn.getAttribute('data-ln-toggle-for');
+			const target = document.getElementById(targetId);
+			if (target && target[DOM_ATTRIBUTE]) {
+				btn.setAttribute('aria-expanded', target[DOM_ATTRIBUTE].isOpen ? 'true' : 'false');
+			}
+		}
+	}
+
+	function _syncTriggerAria(panelEl, isOpen) {
+		const triggers = document.querySelectorAll(
+			'[data-ln-toggle-for="' + panelEl.id + '"]'
+		);
+		for (const trigger of triggers) {
+			trigger.setAttribute('aria-expanded', isOpen ? 'true' : 'false');
+		}
+	}
+
+	// ─── Component ─────────────────────────────────────────────
+
+	function _component(dom) {
+		this.dom = dom;
+
+		// ─── Restore persisted state ──────────────────────────────
+		if (dom.hasAttribute('data-ln-persist')) {
+			const saved = persistGet('toggle', dom);
+			if (saved !== null) {
+				dom.setAttribute(DOM_SELECTOR, saved);
+			}
+		}
+
+		this.isOpen = dom.getAttribute(DOM_SELECTOR) === 'open';
+
+		if (this.isOpen) {
+			dom.classList.add('open');
+		}
+
+		_syncTriggerAria(dom, this.isOpen);
+
+		return this;
+	}
+
+	_component.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+		dispatch(this.dom, 'ln-toggle:destroyed', { target: this.dom });
+		const triggers = document.querySelectorAll('[data-ln-toggle-for="' + this.dom.id + '"]');
+		for (const btn of triggers) {
+			if (btn[DOM_ATTRIBUTE + 'Trigger']) {
+				btn.removeEventListener('click', btn[DOM_ATTRIBUTE + 'Trigger']);
+				delete btn[DOM_ATTRIBUTE + 'Trigger'];
+			}
+		}
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	// ─── Attribute Sync ────────────────────────────────────────
+
+	function _syncAttribute(el) {
+		const instance = el[DOM_ATTRIBUTE];
+		if (!instance) return;
+
+		const value = el.getAttribute(DOM_SELECTOR);
+		const shouldBeOpen = value === 'open';
+
+		if (shouldBeOpen === instance.isOpen) return;
+
+		if (shouldBeOpen) {
+			const before = dispatchCancelable(el, 'ln-toggle:before-open', { target: el });
+			if (before.defaultPrevented) {
+				el.setAttribute(DOM_SELECTOR, 'close');
+				return;
+			}
+			instance.isOpen = true;
+			el.classList.add('open');
+			_syncTriggerAria(el, true);
+			dispatch(el, 'ln-toggle:open', { target: el });
+			if (el.hasAttribute('data-ln-persist')) {
+				persistSet('toggle', el, 'open');
+			}
+		} else {
+			const before = dispatchCancelable(el, 'ln-toggle:before-close', { target: el });
+			if (before.defaultPrevented) {
+				el.setAttribute(DOM_SELECTOR, 'open');
+				return;
+			}
+			instance.isOpen = false;
+			el.classList.remove('open');
+			_syncTriggerAria(el, false);
+			dispatch(el, 'ln-toggle:close', { target: el });
+			if (el.hasAttribute('data-ln-persist')) {
+				persistSet('toggle', el, 'close');
+			}
+		}
+	}
+
+	// ─── Init ──────────────────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-toggle', {
+		extraAttributes: ['data-ln-toggle-for'],
+		onAttributeChange: _syncAttribute,
+		onInit: _attachTriggers
+	});
+})();