@livenetworks/ashlar 1.6.1 → 2.0.1

package/components/ln-picklist/src/ln-picklist.js

@@ -0,0 +1,228 @@
+import { registerComponent, dispatch, dispatchCancelable } from '../../ln-core';
+
+(function () {
+	'use strict';
+
+	const DOM_SELECTOR = 'data-ln-picklist';
+	const DOM_ATTRIBUTE = 'lnPicklist';
+	const LIST_ATTR = 'data-ln-picklist-list';
+	const MAX_ATTR = 'data-ln-picklist-max';
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+	// ─── Attribute Contract (SSOT) ──────────────────────────
+	const ATTRIBUTES = {
+		'data-ln-picklist':      { type: 'enum', values: ['enabled', 'disabled'], fallback: 'enabled', effect: _syncEnabled, description: 'Controls enabled/disabled state of the dual-list picklist' },
+		'data-ln-picklist-max':  { type: 'integer', fallback: Infinity, min: 1, effect: _syncMax, description: 'Maximum selectable items in the selected list' },
+		'data-ln-picklist-list': { type: 'enum', values: ['available', 'selected'], description: 'Role marker for available or selected picklist columns' }
+	};
+
+	// ─── Component ─────────────────────────────────────────────
+	//
+	// The checkbox IS the state. Its `checked` property and the list the item
+	// currently sits in are the same fact, and `name`/`value` carry the
+	// selection to the server natively — unchecked boxes are not submitted.
+	// Hence no hidden inputs, no state attribute and no JS mirror.
+
+	function _component(dom) {
+		this.dom = dom;
+		this.isEnabled = dom.getAttribute(DOM_SELECTOR) !== 'disabled';
+		this.max = _readMax(dom);
+
+		this.available = dom.querySelector('[' + LIST_ATTR + '="available"]');
+		this.selected = dom.querySelector('[' + LIST_ATTR + '="selected"]');
+
+		// Report the gap rather than failing on the first click.
+		if (!this.available || !this.selected) {
+			console.warn('[ln-picklist] requires both [' + LIST_ATTR + '="available"] and [' + LIST_ATTR + '="selected"]', dom);
+			return this;
+		}
+
+		// Bound once so destroy() can detach the same reference.
+		this._onChange = this._onChange.bind(this);
+		dom.addEventListener('change', this._onChange);
+
+		// Snapshot the authored items in document order.
+		this._initial = [];
+		for (const list of [this.available, this.selected]) {
+			for (const item of list.children) {
+				this._initial.push(item);
+			}
+		}
+
+		// Initial sync: transfer checked items to selected, unchecked to available.
+		this.sync();
+
+		this._form = dom.closest('form');
+		if (this._form) {
+			this._onFormReset = this._onFormReset.bind(this);
+			this._form.addEventListener('reset', this._onFormReset);
+		}
+
+		return this;
+	}
+
+	// ─── Lifecycle ─────────────────────────────────────────────
+
+	_component.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+		this._destroyed = true;
+		if (this._onChange) this.dom.removeEventListener('change', this._onChange);
+		if (this._form) this._form.removeEventListener('reset', this._onFormReset);
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	// ─── Instance API ──────────────────────────────────────────
+
+	_component.prototype.enable = function () {
+		this.dom.setAttribute(DOM_SELECTOR, '');
+	};
+
+	_component.prototype.disable = function () {
+		this.dom.setAttribute(DOM_SELECTOR, 'disabled');
+	};
+
+	_component.prototype.sync = function () {
+		if (!this.available || !this.selected) return;
+
+		// Include any dynamically added items not yet tracked
+		const currentItems = Array.from(this.available.children).concat(Array.from(this.selected.children));
+		for (let i = 0; i < currentItems.length; i++) {
+			if (!this._initial.includes(currentItems[i])) {
+				this._initial.push(currentItems[i]);
+			}
+		}
+
+		let selectedCount = 0;
+		for (let i = 0; i < this._initial.length; i++) {
+			const item = this._initial[i];
+			if (!item.isConnected) continue;
+			const checkbox = item.querySelector('input[type="checkbox"]');
+			if (!checkbox) continue;
+
+			let targetList;
+			if (checkbox.checked) {
+				if (this.max === null || selectedCount < this.max) {
+					targetList = this.selected;
+					selectedCount++;
+				} else {
+					checkbox.checked = false;
+					targetList = this.available;
+				}
+			} else {
+				targetList = this.available;
+			}
+			targetList.appendChild(item);
+		}
+	};
+
+	// ─── Form Reset ────────────────────────────────────────────
+	//
+	// Resetting a form restores every control to its default SILENTLY — the
+	// spec fires no `change` and no `input` for them, only `reset` on the form
+	// itself. Re-syncing in recorded order rebuilds both lists according to
+	// defaultChecked.
+
+	_component.prototype._onFormReset = function (e) {
+		const self = this;
+
+		// `reset` fires BEFORE the controls are restored, and it is cancelable,
+		// so the work is deferred and re-checked — the same shape ln-editor
+		// uses to re-read its textarea.
+		setTimeout(function () {
+			if (self._destroyed || e.defaultPrevented) return;
+			self.sync();
+		}, 0);
+	};
+
+	// ─── Change Handler ────────────────────────────────────────
+
+	_component.prototype._onChange = function (e) {
+		// `change` bubbles, so anything the author composes inside the root —
+		// an ln-search input, a select — reaches this listener. Filter hard.
+		const checkbox = e.target.closest('input[type="checkbox"]');
+		if (!checkbox) return;
+
+		const item = checkbox.closest('li');
+		if (!item) return;
+
+		const from = item.parentElement;
+		if (from !== this.available && from !== this.selected) return;
+
+		// The browser has already toggled the box by the time this runs, so a
+		// bare return would leave it checked while the item stays put — which
+		// is exactly the contradiction this component exists to avoid.
+		if (!this.isEnabled) {
+			checkbox.checked = !checkbox.checked;
+			return;
+		}
+
+		const to = checkbox.checked ? this.selected : this.available;
+
+		// Inconsistent authored markup (a checked item rendered on the left),
+		// or a synthetic change that did not flip the box, would otherwise
+		// re-append in place and emit a move that never happened.
+		if (from === to) return;
+
+		// Enforce maximum selection limit if configured
+		if (to === this.selected && this.max !== null && this.selected.children.length >= this.max) {
+			checkbox.checked = !checkbox.checked;
+			dispatch(this.dom, 'ln-picklist:max-reached', {
+				max: this.max,
+				item: item,
+				checkbox: checkbox,
+				count: this.selected.children.length
+			});
+			return;
+		}
+
+		// One record, both events — they describe the same move.
+		const detail = { item: item, from: from, to: to, checkbox: checkbox };
+
+		if (dispatchCancelable(this.dom, 'ln-picklist:before-move', detail).defaultPrevented) {
+			checkbox.checked = !checkbox.checked;
+			return;
+		}
+
+		// Re-parenting a node that holds focus blurs it to <body> in Chromium.
+		// Only restore when the focus really was here: a synthetic change from
+		// a script must not steal focus away from whatever the user is using.
+		const hadFocus = document.activeElement === checkbox;
+
+		to.appendChild(item);
+
+		if (hadFocus) checkbox.focus();
+
+		dispatch(this.dom, 'ln-picklist:move', detail);
+	};
+
+	// ─── Attribute Sync ────────────────────────────────────────
+
+	function _readMax(el) {
+		const raw = el.getAttribute(MAX_ATTR);
+		if (raw === null || raw === '') return null;
+		const parsed = parseInt(raw, 10);
+		return isNaN(parsed) || parsed < 0 ? null : parsed;
+	}
+
+	function _syncEnabled(el) {
+		const instance = el[DOM_ATTRIBUTE];
+		if (!instance) return;
+		const shouldBeEnabled = el.getAttribute(DOM_SELECTOR) !== 'disabled';
+		if (shouldBeEnabled === instance.isEnabled) return;
+		instance.isEnabled = shouldBeEnabled;
+		dispatch(el, shouldBeEnabled ? 'ln-picklist:enabled' : 'ln-picklist:disabled', { target: el });
+	}
+
+	function _syncMax(el) {
+		const instance = el[DOM_ATTRIBUTE];
+		if (!instance) return;
+		instance.max = _readMax(el);
+	}
+
+	// ─── Init ──────────────────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-picklist', {
+		attributes: ATTRIBUTES
+	});
+})();

package/{js → components}/ln-popover/README.md

@@ -1,162 +1,164 @@
-# ln-popover
-
-> Viewport-aware click-triggered rich-content overlays, managed reactively via the DOM.
-
----
-
-## 1. Philosophy & Mindset
-
-In `ln-ashlar`, the core design principle is **orthogonality**. Rather than creating a heavy component that bundles state, positioning algorithms, LIFO click stacks, and styles, `ln-popover` splits them cleanly:
-
-1. **State & Positioning (JavaScript + native Popover API)**: The `ln-popover` script handles binary `open` / `closed` states in the DOM, bridged to the native Popover API (`popover="manual"`, `showPopover()`/`hidePopover()`) purely for top-layer rendering — no ancestor `overflow`/`z-index` can clip or bury it. Because `manual` mode has no native light-dismiss, the script still owns 100% of the behavior: viewport-boundary flip placement, keyboard focus save/restore, and the LIFO (Last-In, First-Out) ESC dismissal stack.
-2. **Visual Presentation (CSS)**: Visual layouts, background shadows, and borders are handled in Vanilla CSS. The library ships a premium `@mixin popover` to style popover cards.
-3. **Trigger decoupling (HTML)**: Triggers (`data-ln-popover-for="popoverId"`) and popover containers (`id="popoverId"`) are bound purely by ID, allowing the trigger button and the popup card to live anywhere in the document.
-
----
-
-## 2. Minimal Blueprint
-
-Triggers and popovers are paired by ID. Wrap content in a `div` carrying the `data-ln-popover` attribute.
-
-```html
-<!-- Trigger anywhere -->
-<button data-ln-popover-for="account-menu">Account</button>
-
-<!-- Popover anywhere — role="dialog", tabindex="-1", and popover="manual" are injected automatically -->
-<div data-ln-popover id="account-menu">
-    <p><strong>user@example.com</strong></p>
-    <nav>
-        <a href="/settings">Settings</a>
-        <a href="/logout">Sign out</a>
-    </nav>
-</div>
-```
-
-### Key Anatomy Rules
-- **The Popover wrapper (`data-ln-popover`)**: Driven by the value `"open"` (open) and `"closed"` or empty (closed).
-- **The Trigger (`data-ln-popover-for="id"`)**: Sets `aria-expanded` and manages focus automatically.
-- **Visual styling**: Re-apply `@mixin popover` in your SCSS on the popover element.
-
----
-
-## 3. Declarative API & State Contract
-
-The initialized instance is exposed as `dom.lnPopover`, with `open(trigger)`, `close()`, `toggle(trigger)`, and `destroy()` methods, plus `isOpen` and `trigger` properties. **The HTML attribute remains the primary contract** — the instance methods are thin wrappers that ultimately write the same attribute.
-
-Triggers, LIFO click outside handlers, viewport edge flips, and custom scripts all change state by writing the active attribute on the popover element:
-
-```js
-const popover = document.getElementById('account-menu');
-
-// Open the popover
-popover.setAttribute('data-ln-popover', 'open');
-
-// Close the popover
-popover.setAttribute('data-ln-popover', 'closed');
-
-// Equivalent imperative calls via the instance
-popover.lnPopover.open();
-popover.lnPopover.close();
-
-// Read-only state query
-popover.lnPopover.isOpen; // Returns true/false
-```
-
-### Attributes
-- `data-ln-popover`: Placed on the popover card. Value `"open"` = open; `"closed"` = closed.
-- `data-ln-popover-for="id"`: Placed on triggers referencing the popover ID.
-- `data-ln-popover-position="top|bottom|left|right"`: Preferred placement side. Default: `bottom`.
-- `data-ln-popover-placement`: Set automatically by JS to indicate the *actual* active side after auto-flip is resolved.
-
----
-
-## 4. Transition Events
-
-All events bubble. The dispatch target is the popover element itself.
-
-| Event | Cancelable | `detail` | Dispatched When |
-|---|---|---|---|
-| **`ln-popover:before-open`** | **Yes** | `{ popoverId, target, trigger }` | Before opening. `event.preventDefault()` cancels the transition and reverts the attribute. |
-| **`ln-popover:open`** | No | `{ popoverId, target, trigger }` | After popover is positioned, classes added, and focus moved. |
-| **`ln-popover:before-close`** | **Yes** | `{ popoverId, target, trigger }` | Before closing. `event.preventDefault()` cancels the close and reverts the attribute. |
-| **`ln-popover:close`** | No | `{ popoverId, target, trigger }` | After popover is closed and focus restored back to the trigger. |
-
-```js
-// Example: Cancel open transition for unauthorized zones
-document.addEventListener('ln-popover:before-open', (e) => {
-    if (e.detail.popoverId === 'admin-zone' && !currentUser.isAdmin) {
-        e.preventDefault(); // Reverts attribute back to "closed"
-    }
-});
-```
-
----
-
-## 5. Integration Patterns
-
-### A. Position Preferences & Auto-Flip
-Preferred placement is easily configured. If there isn't enough room in the viewport, the positioning engine flips the popover to the opposite side:
-```html
-<div data-ln-popover data-ln-popover-position="right" id="help-menu">...</div>
-```
-
-### B. Nested Popovers (A stays open when B opens)
-Opening B from inside A leaves A open. Pressing `ESC` once closes B first, and then A:
-```html
-<div data-ln-popover id="popover-a">
-    <button data-ln-popover-for="popover-b">Open B</button>
-</div>
-<div data-ln-popover id="popover-b">...</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-popover/ln-popover.js" defer></script>
-  ```
-- **Active Source (ESM)**: Development source is located at [js/ln-popover/src/ln-popover.js](file:///c:/laragon/www/ln-ashlar/js/ln-popover/src/ln-popover.js).
-
----
-
-## Related
-- **[`ln-dropdown`](../ln-dropdown/README.md)** — Menu wrapper adding click-outside/top-layer promotion.
-- **[`ln-toggle`](../ln-toggle/README.md)** — Binary disclosure state primitive.
-
----
-
-## 🔧 Internals
-
-Source: `js/ln-popover/ln-popover.js`.
-
-### Open-stack
-
-A module-level `openStack` array tracks all currently-open instances. It drives two behaviors: a single `document` `keydown` listener, registered only while the stack is non-empty, pops the top entry and calls `.close()` on it (LIFO Escape); and nested popovers stay independent because each owns its own outside-click listener scoped to its own subtree.
-
-### `_applyOpen(trigger)` — after the cancelable `before-open` passes
-
-Set `isOpen = true`, store `trigger` (`null` if opened via direct attribute mutation) and `document.activeElement` (for focus restore) → `teleportToBody(dom)` (moves the element to end of `<body>`, storing a restore function, so `position: fixed` coordinates are reliable regardless of ancestor `transform`/`contain`) → `measureHidden(dom)` for dimensions even if `display: none` → `computePlacement(triggerRect, size, preferred, 8)` writes `top`/`left` inline (unavoidable for floating UI) and `data-ln-popover-placement` → `aria-expanded="true"` on trigger → focus the first focusable child, or the container itself → outside-click listener registered one tick later via `setTimeout` (so the opening click itself doesn't immediately close it) → scroll/resize listeners for repositioning while open → push onto `openStack`, ensure ESC listener → dispatch `ln-popover:open`.
-
-### `_applyClose()` — mirror of `_applyOpen`
-
-Clears `isOpen`, removes the outside-click/scroll/resize listeners, clears inline `top`/`left` and the placement attribute, sets `aria-expanded="false"`, runs the teleport-restore function, splices itself from `openStack` (removing the ESC listener if the stack is now empty), then restores focus to the trigger **only if** the trigger was the previously-focused element (click→Escape, click→programmatic close) or `activeElement === document.body` (Escape from inside the popover, outside-click on inert whitespace) — an outside-click landing on another focusable element keeps that element's focus. Dispatches `ln-popover:close`.
-
-### Focus management
-
-A disclosure pattern, not a modal — no Tab trap. Because the popover is teleported to the end of `<body>`, Tab exits it into whatever follows in body order. `tabindex="-1"` and `role="dialog"` are set automatically at construction so the container itself is a valid focus target when there's no focusable child.
-
-### Nested popovers
-
-Outside-click tests `self.dom.contains(e.target)`, so a click inside A's subtree (including a button that opens B) never triggers A's close path. Both popovers land on `openStack`; LIFO Escape closes B first, then A on the next press. There is no "close all."
-
-### Observer & registration
-
-Single observer on `document.body` (`subtree`/`childList`/`attributes`, filtered to `data-ln-popover`/`data-ln-popover-for`): childList additions re-run `_findPopovers`/`_attachTriggers`; attribute mutations dispatch to `_syncAttribute` for existing instances or re-run discovery for new ones. Two separate `registerComponent` calls wire popover elements (`el.lnPopover`) and trigger elements (`el.lnPopoverTrigger`) independently — trigger init sets `aria-haspopup="dialog"`, `aria-expanded="false"`, `aria-controls`, once, on attach.
-
-`destroy()` on a popover instance closes it if open, removes its listeners, splices it from `openStack`, and dispatches `ln-popover:destroyed`. Trigger `destroy` is independent and only removes the trigger's click handler.
+# ln-popover
+
+> Applied to a container via `data-ln-popover id="..."`, paired with a `<button data-ln-popover-for="...">`.
+> On trigger `click`, it sets `popover="manual"` on the container, calls `showPopover()`, sets inline `top`/`left` coordinates, and writes `data-ln-popover="open"`.
+> On outside `click` or `Escape`, it calls `hidePopover()` and writes `data-ln-popover="closed"`.
+
+---
+
+## 1. Philosophy & Mindset
+
+In `ln-ashlar`, the core design principle is **orthogonality**. Rather than creating a heavy component that bundles state, positioning algorithms, LIFO click stacks, and styles, `ln-popover` splits them cleanly:
+
+1. **State & Positioning (JavaScript + native Popover API)**: The `ln-popover` script handles binary `open` / `closed` states in the DOM, bridged to the native Popover API (`popover="manual"`, `showPopover()`/`hidePopover()`) purely for top-layer rendering — no ancestor `overflow`/`z-index` can clip or bury it. Because `manual` mode has no native light-dismiss, the script still owns 100% of the behavior: viewport-boundary flip placement, keyboard focus save/restore, and the LIFO (Last-In, First-Out) ESC dismissal stack.
+2. **Visual Presentation (CSS)**: Visual layouts, background shadows, and borders are handled in Vanilla CSS. The library ships a premium `@mixin popover` to style popover cards.
+3. **Trigger decoupling (HTML)**: Triggers (`data-ln-popover-for="popoverId"`) and popover containers (`id="popoverId"`) are bound purely by ID, allowing the trigger button and the popup card to live anywhere in the document.
+
+---
+
+## 2. Minimal Blueprint
+
+Triggers and popovers are paired by ID. Wrap content in a `div` carrying the `data-ln-popover` attribute.
+
+```html
+<!-- Trigger anywhere -->
+<button data-ln-popover-for="account-menu">Account</button>
+
+<!-- Popover anywhere — role="dialog", tabindex="-1", and popover="manual" are injected automatically -->
+<div data-ln-popover id="account-menu">
+    <p><strong>user@example.com</strong></p>
+    <nav>
+        <a href="/settings">Settings</a>
+        <a href="/logout">Sign out</a>
+    </nav>
+</div>
+```
+
+### Key Anatomy Rules
+- **The Popover wrapper (`data-ln-popover`)**: Driven by the value `"open"` (open) and `"closed"` or empty (closed).
+- **The Trigger (`data-ln-popover-for="id"`)**: Sets `aria-expanded` and manages focus automatically.
+- **Visual styling**: Re-apply `@mixin popover` in your SCSS on the popover element.
+
+---
+
+## 3. Declarative API & State Contract
+
+The initialized instance is exposed as `dom.lnPopover`, with `open(trigger)`, `close()`, `toggle(trigger)`, and `destroy()` methods, plus `isOpen` and `trigger` properties. **The HTML attribute remains the primary contract** — the instance methods are thin wrappers that ultimately write the same attribute.
+
+Triggers, LIFO click outside handlers, viewport edge flips, and custom scripts all change state by writing the active attribute on the popover element:
+
+```js
+const popover = document.getElementById('account-menu');
+
+// Open the popover
+popover.setAttribute('data-ln-popover', 'open');
+
+// Close the popover
+popover.setAttribute('data-ln-popover', 'closed');
+
+// Equivalent imperative calls via the instance
+popover.lnPopover.open();
+popover.lnPopover.close();
+
+// Read-only state query
+popover.lnPopover.isOpen; // Returns true/false
+```
+
+### Attributes
+- `data-ln-popover`: Placed on the popover card. Value `"open"` = open; `"closed"` = closed.
+- `data-ln-popover-for="id"`: Placed on triggers referencing the popover ID.
+- `data-ln-popover-position="top|bottom|left|right"`: Preferred placement side. Default: `bottom`.
+- `data-ln-popover-placement`: Set automatically by JS to indicate the *actual* active side after auto-flip is resolved.
+
+---
+
+## 4. Transition Events
+
+All events bubble. The dispatch target is the popover element itself.
+
+| Event | Cancelable | `detail` | Dispatched When |
+|---|---|---|---|
+| **`ln-popover:before-open`** | **Yes** | `{ popoverId, target, trigger }` | Before opening. `event.preventDefault()` cancels the transition and reverts the attribute. |
+| **`ln-popover:open`** | No | `{ popoverId, target, trigger }` | After popover is positioned, classes added, and focus moved. |
+| **`ln-popover:before-close`** | **Yes** | `{ popoverId, target, trigger }` | Before closing. `event.preventDefault()` cancels the close and reverts the attribute. |
+| **`ln-popover:close`** | No | `{ popoverId, target, trigger }` | After popover is closed and focus restored back to the trigger. |
+
+```js
+// Example: Cancel open transition for unauthorized zones
+document.addEventListener('ln-popover:before-open', (e) => {
+    if (e.detail.popoverId === 'admin-zone' && !currentUser.isAdmin) {
+        e.preventDefault(); // Reverts attribute back to "closed"
+    }
+});
+```
+
+---
+
+## 5. Integration Patterns
+
+### A. Position Preferences & Auto-Flip
+Preferred placement is easily configured. If there isn't enough room in the viewport, the positioning engine flips the popover to the opposite side:
+```html
+<div data-ln-popover data-ln-popover-position="right" id="help-menu">...</div>
+```
+
+### B. Nested Popovers (A stays open when B opens)
+Opening B from inside A leaves A open. Pressing `ESC` once closes B first, and then A:
+```html
+<div data-ln-popover id="popover-a">
+    <button data-ln-popover-for="popover-b">Open B</button>
+</div>
+<div data-ln-popover id="popover-b">...</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="components/ln-popover/ln-popover.js" defer></script>
+  ```
+- **Active Source (ESM)**: Development source is located at [components/ln-popover/src/ln-popover.js](file:///c:/laragon/www/ln-ashlar/components/ln-popover/src/ln-popover.js).
+
+---
+
+## Related
+- **[`ln-dropdown`](../ln-dropdown/README.md)** — Menu wrapper adding click-outside/top-layer promotion.
+- **[`ln-toggle`](../ln-toggle/README.md)** — Binary disclosure state primitive.
+
+---
+
+## 🔧 Internals
+
+Source: `components/ln-popover/ln-popover.js`.
+
+### Open-stack
+
+A module-level `openStack` array tracks all currently-open instances. It drives two behaviors: a single `document` `keydown` listener, registered only while the stack is non-empty, pops the top entry and calls `.close()` on it (LIFO Escape); and nested popovers stay independent because each owns its own outside-click listener scoped to its own subtree.
+
+### `_applyOpen(trigger)` — after the cancelable `before-open` passes
+
+Set `isOpen = true`, store `trigger` (`null` if opened via direct attribute mutation) and `document.activeElement` (for focus restore) → promotes the element to the top layer via `showPopover()` (so `position: fixed` coordinates are reliable regardless of ancestor `transform`, `contain`, or `overflow: hidden`) → `measureHidden(dom)` for dimensions even if `display: none` → `computePlacement(triggerRect, size, preferred, 8)` writes `top`/`left` inline (unavoidable for floating UI) and `data-ln-popover-placement` → `aria-expanded="true"` on trigger → focus the first focusable child, or the container itself → outside-click listener registered one tick later via `setTimeout` (so the opening click itself doesn't immediately close it) → scroll/resize listeners for repositioning while open → push onto `openStack`, ensure ESC listener → dispatch `ln-popover:open`.
+
+### `_applyClose()` — mirror of `_applyOpen`
+
+Clears `isOpen`, removes the outside-click/scroll/resize listeners, clears inline `top`/`left` and the placement attribute, sets `aria-expanded="false"`, exits the top layer via `hidePopover()`, splices itself from `openStack` (removing the ESC listener if the stack is now empty), then restores focus to the trigger **only if** the trigger was the previously-focused element (click→Escape, click→programmatic close) or `activeElement === document.body` (Escape from inside the popover, outside-click on inert whitespace) — an outside-click landing on another focusable element keeps that element's focus. Dispatches `ln-popover:close`.
+
+### Focus management
+
+A disclosure pattern, not a modal — no Tab trap. Because the popover is promoted to the top layer purely for rendering, it remains in its authored DOM position, so Tab order follows the markup rather than jumping to the end of `<body>`. `tabindex="-1"` and `role="dialog"` are set automatically at construction so the container itself is a valid focus target when there's no focusable child.
+
+### Nested popovers
+
+Outside-click tests `self.dom.contains(e.target)`, so a click inside A's subtree (including a button that opens B) never triggers A's close path. Both popovers land on `openStack`; LIFO Escape closes B first, then A on the next press. There is no "close all."
+
+### Observer & registration
+
+Two separate `registerComponent` calls wire popover elements (`el.lnPopover`) and trigger elements (`el.lnPopoverTrigger`) independently — `registerComponent` handles DOM discovery and lifecycle. On attribute mutations to `data-ln-popover`, `registerComponent`'s `onAttributeChange` callback evaluates open/closed transitions and dispatches `before-open` / `before-close` events. Trigger init sets `aria-haspopup="dialog"`, `aria-expanded="false"`, and `aria-controls` once on attach.
+
+`destroy()` on a popover instance closes it if open, removes its listeners, and splices it from `openStack`. Trigger `destroy` is independent and only removes the trigger's click handler.

package/components/ln-popover/ln-popover-dev.scss

@@ -0,0 +1,13 @@
+@use '../../theme/config/mixins' as *;
+
+[data-ln-debug] {
+	// 1. Popover Missing ID: popovers controlled by data-ln-popover must have an id for trigger linking
+	[data-ln-popover]:not([id]) {
+		@include dev-dom-error("[data-ln-popover] is missing a required 'id' attribute for trigger linking.");
+	}
+
+	// 2. Popover Trigger Empty ID: trigger elements must point to a target popover ID
+	[data-ln-popover-for=""] {
+		@include dev-inline-error("data-ln-popover-for target ID cannot be empty");
+	}
+}