@livenetworks/ashlar 1.3.2

package/js/ln-api-connector/README.md

@@ -0,0 +1,150 @@
+# `data-ln-api-connector`
+
+A zero-dependency, Local-First sync transport component that implements the Transport Gateway pattern of `ln-ashlar`.
+
+This component encapsulates all connection parameters (base URLs, auth tokens, headers, paths) and provides a declarative, event-driven, or programmatic way to talk to any RESTful or JSON API backend. It isolates networking concerns completely, making your cache store (`data-ln-data-store`) and visual presentation layers fully network-agnostic.
+
+---
+
+## Declarative DOM Setup
+
+Place the connector inside your parent coordinator element alongside your store:
+
+```html
+<div data-ln-data-coordinator="documents">
+    <!-- Storage Layer Cache (Blind to networking) -->
+    <div data-ln-data-store 
+         data-ln-store-indexes="status,updated_at">
+    </div>
+
+    <!-- Transport Gateway (REST / API Connector) -->
+    <div data-ln-api-connector
+         data-ln-api-base-url="https://api.livenetworks.com/v1"
+         data-ln-api-path="/documents"
+         data-ln-api-headers='{"Authorization": "Bearer tok_123"}'>
+    </div>
+</div>
+```
+
+---
+
+## Attributes
+
+All attributes are dynamically observed. Any runtime changes to these attributes instantly update the connector's internal configurations.
+
+| Attribute | Category | Description |
+|-----------|----------|-------------|
+| `data-ln-api-connector` | Selector | Creates the component instance. Optional value serves as name. |
+| `data-ln-api-base-url` | Connection | The base URL of the API gateway (e.g. `https://api.example.com/v1` or `/api`). Fallback: `data-ln-api-connector-base-url`, `data-ln-rest-base-url`. |
+| `data-ln-api-path` | Connection | Resource path endpoint (e.g. `/documents`). Fallback: `data-ln-api-connector-path`, `data-ln-rest-path`. |
+| `data-ln-api-headers` | Credentials | JSON-formatted string of request headers (e.g. `{"Authorization": "Bearer tok_123"}`). Fallback: `data-ln-api-connector-headers`, `data-ln-rest-headers`. |
+
+---
+
+## JavaScript API Methods
+
+You can access the instance methods directly on the element via the `.lnApiConnector` or `.lnConnector` properties:
+
+```javascript
+const connectorEl = document.querySelector('[data-ln-api-connector]');
+const connector = connectorEl.lnApiConnector; // or connectorEl.lnConnector
+
+// 1. Fetch changed records since a Unix timestamp (delta protocol)
+connector.fetchDelta(1736952600)
+    .then(data => console.log('Sync arrays loaded:', data));
+
+// 2. Create a new record
+connector.create({ title: 'New Document', status: 'Draft' })
+    .then(record => console.log('Created record:', record));
+
+// 3. Update an existing record
+connector.update(42, { title: 'Updated Title' })
+    .then(record => console.log('Updated record:', record));
+
+// 4. Delete a record
+connector.delete(42)
+    .then(res => console.log('Deleted:', res));
+
+// 5. Bulk Delete records
+connector.bulkDelete([17, 23])
+    .then(res => console.log('Bulk deleted:', res));
+```
+
+---
+
+## DOM Events
+
+### Commands (Dispatched TO the connector)
+
+You can trigger mutations and fetches asynchronously by dispatching standard events directly on the connector DOM element. All events are supported in both `ln-api-connector` and legacy `ln-rest-connector` namespaces.
+
+| Event | `detail` Payload | Description |
+|-------|------------------|-------------|
+| `ln-api-connector:request-sync` | `{ since }` | Triggers a delta fetch request. |
+| `ln-api-connector:request-create` | `{ data, tempId }` | Triggers a creation request. |
+| `ln-api-connector:request-update` | `{ id, data, expected_version }` | Triggers a PUT update (supports 409 conflict checks). |
+| `ln-api-connector:request-delete` | `{ id }` | Triggers a deletion request. |
+| `ln-api-connector:request-bulk-delete` | `{ ids }` | Triggers a bulk-deletion request. |
+
+### Notifications (Emitted BY the connector)
+
+The connector dispatches bubbles-enabled events to notify parent coordinators of response states.
+
+| Event | `detail` Payload | Description |
+|-------|------------------|-------------|
+| `ln-api-connector:fetched` | `{ data, since }` | Dispatched upon successful fetch completion. |
+| `ln-api-connector:created` | `{ record, tempId }` | Dispatched upon successful server record confirmation. |
+| `ln-api-connector:updated` | `{ record, id }` | Dispatched upon successful server update confirmation. |
+| `ln-api-connector:deleted` | `{ response, id }` | Dispatched upon successful server deletion. |
+| `ln-api-connector:bulk-deleted`| `{ response, ids }` | Dispatched upon successful server bulk deletion. |
+| `ln-api-connector:error` | `{ action, error, status, ... }` | Dispatched on failures. Includes `conflictData` if status is 409. |
+| `ln-api-connector:config-changed` | `{ baseUrl, path, headers }` | Dispatched when configuration attributes are mutated. |
+
+---
+
+## 3-Tier Integration Architecture (Coordinator Example)
+
+Here is how a parent Coordinator links a Cache Store and the API Connector using standard DOM events:
+
+```javascript
+(function () {
+    const parent = document.querySelector('[data-ln-data-coordinator="documents"]');
+    const storeEl = parent.querySelector('[data-ln-data-store]');
+    const connectorEl = parent.querySelector('[data-ln-api-connector]');
+
+    if (!storeEl || !connectorEl) return;
+
+    // 1. Storage needs remote sync -> forward request to Connector
+    storeEl.addEventListener('ln-store:request-remote-sync', function (e) {
+        connectorEl.dispatchEvent(new CustomEvent('ln-api-connector:request-sync', {
+            detail: { since: e.detail.since }
+        }));
+    });
+
+    // 2. Connector finishes sync -> feed delta back to Storage
+    connectorEl.addEventListener('ln-api-connector:fetched', function (e) {
+        const payload = e.detail.data;
+        storeEl.lnStore.applySync(payload.data, payload.deleted || [], payload.synced_at);
+    });
+
+    // 3. Storage requests remote creation -> forward payload to Connector
+    storeEl.addEventListener('ln-store:request-remote-create', function (e) {
+        connectorEl.dispatchEvent(new CustomEvent('ln-api-connector:request-create', {
+            detail: { data: e.detail.data, tempId: e.detail.tempId }
+        }));
+    });
+
+    // 4. Connector confirms creation -> swap optimistic temp records in Storage
+    connectorEl.addEventListener('ln-api-connector:created', function (e) {
+        storeEl.lnStore.confirmMutation(e.detail.tempId, e.detail.record, 'create');
+    });
+
+    // 5. In case of network errors -> trigger rollback in Cache Store
+    connectorEl.addEventListener('ln-api-connector:error', function (e) {
+        if (e.detail.action === 'create') {
+            storeEl.lnStore.revertMutation(e.detail.tempId, 'create', e.detail.error);
+        }
+        // ... handle updates and deletions similarly
+    });
+})();
+```

package/js/ln-api-connector/ln-api-connector.js

@@ -0,0 +1 @@
+(function(){"use strict";function c(i,o,d){i.dispatchEvent(new CustomEvent(o,{bubbles:!0,detail:d||{}}))}function E(i,o){if(!document.body){document.addEventListener("DOMContentLoaded",function(){E(i,o)}),console.warn("["+o+'] Script loaded before <body> — add "defer" to your <script> tag');return}i()}function y(i,o,d,u){if(i.nodeType!==1)return;const p=o.indexOf("[")!==-1||o.indexOf(".")!==-1||o.indexOf("#")!==-1?o:"["+o+"]",e=Array.from(i.querySelectorAll(p));i.matches&&i.matches(p)&&e.push(i);for(const n of e)n[d]||(n[d]=new u(n))}function T(i,o,d,u,h={}){const p=h.extraAttributes||[],e=h.onAttributeChange||null,n=h.onInit||null;function t(r){const a=r||document.body;y(a,i,o,d),n&&n(a)}return E(function(){const r=new MutationObserver(function(s){for(let f=0;f<s.length;f++){const l=s[f];if(l.type==="childList")for(let w=0;w<l.addedNodes.length;w++){const g=l.addedNodes[w];g.nodeType===1&&(y(g,i,o,d),n&&n(g))}else l.type==="attributes"&&(e&&l.target[o]?e(l.target,l.attributeName):(y(l.target,i,o,d),n&&n(l.target)))}});let a=[];if(i.indexOf("[")!==-1){const s=/\[([\w-]+)/g;let f;for(;(f=s.exec(i))!==null;)a.push(f[1])}else a.push(i);r.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:a.concat(p)})},u),window[o]=t,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){t(document.body)}):t(document.body),t}function m(...i){return i.filter(o=>o!=null&&o!=="").map((o,d)=>d===0?o.replace(/\/+$/,""):o.replace(/^\/+/,"").replace(/\/+$/,"")).filter(Boolean).join("/")}function b(i,o){return Object.assign({"Content-Type":"application/json",Accept:"application/json"},i,null)}function L(i,o="ln-core"){try{return i?JSON.parse(i):{}}catch(d){return console.error(`[${o}] Invalid headers JSON:`,d),{}}}const v={};function _(i,o){v[i]=o}function C(i){return v[i]||{ingress:o=>o,egress:o=>o}}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=_,window.lnCore.getDataMapper=C),(function(){const i="data-ln-api-connector",o="lnApiConnector",d="lnConnector";if(window[o]!==void 0)return;function u(e){return this.dom=e,e[o]=this,e[d]=this,this.refreshConfig(),this._handlers=null,h(this),this}u.prototype.refreshConfig=function(){const e=this.dom;this.baseUrl=e.getAttribute("data-ln-api-base-url")||"",this.path=e.getAttribute("data-ln-api-path")||"",this.credentials="same-origin";const n=e.getAttribute("data-ln-api-headers")||"";this.headers=L(n,"ln-api-connector"),(n.toLowerCase().includes("authorization")||n.toLowerCase().includes("bearer")||n.toLowerCase().includes("basic"))&&console.warn("[ln-api-connector] Security Warning: Sensitive authorization credentials detected in data-ln-api-headers attribute. Storing secrets in HTML DOM attributes is highly discouraged and vulnerable to XSS credential extraction. Please use HttpOnly session cookies or a Backend Proxy Gateway instead."),c(e,"ln-api-connector:config-changed",{baseUrl:this.baseUrl,path:this.path,headers:this.headers})},u.prototype.fetchDelta=function(e){const n=this;let t=m(n.baseUrl,n.path);return e!=null&&e!==""&&(t+=(t.indexOf("?")!==-1?"&":"?")+"since="+encodeURIComponent(e)),window.fetch(t,{method:"GET",headers:b(n.headers),credentials:n.credentials}).then(r=>{if(!r.ok)throw new Error("HTTP "+r.status+": "+r.statusText);return r.json()})},u.prototype.create=function(e){const n=this;return window.fetch(m(n.baseUrl,n.path),{method:"POST",headers:b(n.headers),credentials:n.credentials,body:JSON.stringify(e)}).then(t=>{if(!t.ok)throw new Error("HTTP "+t.status+": "+t.statusText);return t.json()})},u.prototype.update=function(e,n){const t=this;return window.fetch(m(t.baseUrl,t.path,e),{method:"PUT",headers:b(t.headers),credentials:t.credentials,body:JSON.stringify(n)}).then(r=>{if(r.ok)return r.json();if(r.status===409)return r.json().then(a=>{const s=new Error("Conflict");throw s.status=409,s.data=a,s});throw new Error("HTTP "+r.status+": "+r.statusText)})},u.prototype.delete=function(e){const n=this;return window.fetch(m(n.baseUrl,n.path,e),{method:"DELETE",headers:b(n.headers),credentials:n.credentials}).then(t=>{if(!t.ok)throw new Error("HTTP "+t.status+": "+t.statusText);return t.json()})},u.prototype.bulkDelete=function(e){const n=this;return window.fetch(m(n.baseUrl,n.path)+"/bulk-delete",{method:"DELETE",headers:b(n.headers),credentials:n.credentials,body:JSON.stringify({ids:e})}).then(t=>{if(!t.ok)throw new Error("HTTP "+t.status+": "+t.statusText);return t.json()})};function h(e){e._handlers={sync:function(t){const r=t.detail||{};e.fetchDelta(r.since).then(function(a){c(e.dom,"ln-api-connector:fetched",{data:a,since:r.since})}).catch(function(a){c(e.dom,"ln-api-connector:error",{action:"sync",error:a.message,status:a.status||0,since:r.since})})},create:function(t){const r=t.detail||{};e.create(r.data).then(function(a){c(e.dom,"ln-api-connector:created",{record:a,tempId:r.tempId})}).catch(function(a){c(e.dom,"ln-api-connector:error",{action:"create",error:a.message,status:a.status||0,tempId:r.tempId})})},update:function(t){const r=t.detail||{},a=Object.assign({},r.data);r.expected_version!==void 0&&(a.expected_version=r.expected_version),e.update(r.id,a).then(function(s){c(e.dom,"ln-api-connector:updated",{record:s,id:r.id})}).catch(function(s){c(e.dom,"ln-api-connector:error",{action:"update",error:s.message,status:s.status||0,id:r.id,conflictData:s.status===409?s.data:null})})},delete:function(t){const r=t.detail||{};e.delete(r.id).then(function(a){c(e.dom,"ln-api-connector:deleted",{response:a,id:r.id})}).catch(function(a){c(e.dom,"ln-api-connector:error",{action:"delete",error:a.message,status:a.status||0,id:r.id})})},bulkDelete:function(t){const r=t.detail||{};e.bulkDelete(r.ids).then(function(a){c(e.dom,"ln-api-connector:bulk-deleted",{response:a,ids:r.ids})}).catch(function(a){c(e.dom,"ln-api-connector:error",{action:"bulk-delete",error:a.message,status:a.status||0,ids:r.ids})})}},["ln-api-connector","ln-rest-connector"].forEach(function(t){e.dom.addEventListener(t+":request-sync",e._handlers.sync),e.dom.addEventListener(t+":request-fetch",e._handlers.sync),e.dom.addEventListener(t+":request-create",e._handlers.create),e.dom.addEventListener(t+":request-update",e._handlers.update),e.dom.addEventListener(t+":request-delete",e._handlers.delete),e.dom.addEventListener(t+":request-bulk-delete",e._handlers.bulkDelete)})}u.prototype.destroy=function(){if(!this.dom[o])return;const e=this;e._handlers&&(["ln-api-connector","ln-rest-connector"].forEach(function(t){e.dom.removeEventListener(t+":request-sync",e._handlers.sync),e.dom.removeEventListener(t+":request-fetch",e._handlers.sync),e.dom.removeEventListener(t+":request-create",e._handlers.create),e.dom.removeEventListener(t+":request-update",e._handlers.update),e.dom.removeEventListener(t+":request-delete",e._handlers.delete),e.dom.removeEventListener(t+":request-bulk-delete",e._handlers.bulkDelete)}),e._handlers=null),c(this.dom,"ln-api-connector:destroyed",{target:this.dom}),delete this.dom[o],delete this.dom[d]};function p(e){const n=e[o];n&&n.refreshConfig()}T(i,o,u,"ln-api-connector",{extraAttributes:["data-ln-api-base-url","data-ln-api-path","data-ln-api-headers"],onAttributeChange:p})})()})();

package/js/ln-api-connector/src/ln-api-connector.js

@@ -0,0 +1,265 @@
+import { registerComponent, dispatch, buildUrl, getHeaders, parseHeaders } from '../../ln-core';
+
+(function () {
+	const DOM_SELECTOR = 'data-ln-api-connector';
+	const DOM_ATTRIBUTE = 'lnApiConnector';
+	const DOM_ALIAS = 'lnConnector';
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+	// ─── Component Constructor ─────────────────────────────
+
+	function _component(dom) {
+		this.dom = dom;
+		dom[DOM_ATTRIBUTE] = this;
+		dom[DOM_ALIAS] = this; // Set alias for compatibility
+
+		this.refreshConfig();
+		this._handlers = null;
+		_bindEvents(this);
+
+		return this;
+	}
+
+	// ─── Refresh Config from DOM Attributes ─────────────────
+
+	_component.prototype.refreshConfig = function () {
+		const dom = this.dom;
+
+		this.baseUrl = dom.getAttribute('data-ln-api-base-url') || '';
+		this.path = dom.getAttribute('data-ln-api-path') || '';
+		this.credentials = 'same-origin';
+
+		const rawHeaders = dom.getAttribute('data-ln-api-headers') || '';
+		this.headers = parseHeaders(rawHeaders, 'ln-api-connector');
+
+		if (rawHeaders.toLowerCase().includes('authorization') || rawHeaders.toLowerCase().includes('bearer') || rawHeaders.toLowerCase().includes('basic')) {
+			console.warn('[ln-api-connector] Security Warning: Sensitive authorization credentials detected in data-ln-api-headers attribute. Storing secrets in HTML DOM attributes is highly discouraged and vulnerable to XSS credential extraction. Please use HttpOnly session cookies or a Backend Proxy Gateway instead.');
+		}
+
+		dispatch(dom, 'ln-api-connector:config-changed', {
+			baseUrl: this.baseUrl,
+			path: this.path,
+			headers: this.headers
+		});
+	};
+
+	// ─── JS API Methods (Promises) ──────────────────────────
+
+	_component.prototype.fetchDelta = function (since) {
+		const self = this;
+		let url = buildUrl(self.baseUrl, self.path);
+
+		if (since !== undefined && since !== null && since !== '') {
+			url += (url.indexOf('?') !== -1 ? '&' : '?') + 'since=' + encodeURIComponent(since);
+		}
+
+		return window.fetch(url, { method: 'GET', headers: getHeaders(self.headers), credentials: self.credentials })
+			.then(res => {
+				if (!res.ok) throw new Error('HTTP ' + res.status + ': ' + res.statusText);
+				return res.json();
+			});
+	};
+
+	_component.prototype.create = function (payload) {
+		const self = this;
+		return window.fetch(buildUrl(self.baseUrl, self.path), {
+			method: 'POST',
+			headers: getHeaders(self.headers),
+			credentials: self.credentials,
+			body: JSON.stringify(payload)
+		})
+		.then(res => {
+			if (!res.ok) throw new Error('HTTP ' + res.status + ': ' + res.statusText);
+			return res.json();
+		});
+	};
+
+	_component.prototype.update = function (id, payload) {
+		const self = this;
+		return window.fetch(buildUrl(self.baseUrl, self.path, id), {
+			method: 'PUT',
+			headers: getHeaders(self.headers),
+			credentials: self.credentials,
+			body: JSON.stringify(payload)
+		})
+		.then(res => {
+			if (res.ok) return res.json();
+			if (res.status === 409) return res.json().then(data => {
+				const err = new Error('Conflict');
+				err.status = 409;
+				err.data = data;
+				throw err;
+			});
+			throw new Error('HTTP ' + res.status + ': ' + res.statusText);
+		});
+	};
+
+	_component.prototype.delete = function (id) {
+		const self = this;
+		return window.fetch(buildUrl(self.baseUrl, self.path, id), {
+			method: 'DELETE',
+			headers: getHeaders(self.headers),
+			credentials: self.credentials
+		})
+		.then(res => {
+			if (!res.ok) throw new Error('HTTP ' + res.status + ': ' + res.statusText);
+			return res.json();
+		});
+	};
+
+	_component.prototype.bulkDelete = function (ids) {
+		const self = this;
+		return window.fetch(buildUrl(self.baseUrl, self.path) + '/bulk-delete', {
+			method: 'DELETE',
+			headers: getHeaders(self.headers),
+			credentials: self.credentials,
+			body: JSON.stringify({ ids: ids })
+		})
+		.then(res => {
+			if (!res.ok) throw new Error('HTTP ' + res.status + ': ' + res.statusText);
+			return res.json();
+		});
+	};
+
+	// ─── DOM Event Routing ────────────────────────────────────
+
+	function _bindEvents(self) {
+		self._handlers = {
+			sync: function (e) {
+				const detail = e.detail || {};
+				self.fetchDelta(detail.since)
+					.then(function (data) {
+						dispatch(self.dom, 'ln-api-connector:fetched', { data: data, since: detail.since });
+					})
+					.catch(function (err) {
+						dispatch(self.dom, 'ln-api-connector:error', {
+							action: 'sync',
+							error: err.message,
+							status: err.status || 0,
+							since: detail.since
+						});
+					});
+			},
+			create: function (e) {
+				const detail = e.detail || {};
+				self.create(detail.data)
+					.then(function (record) {
+						dispatch(self.dom, 'ln-api-connector:created', { record: record, tempId: detail.tempId });
+					})
+					.catch(function (err) {
+						dispatch(self.dom, 'ln-api-connector:error', {
+							action: 'create',
+							error: err.message,
+							status: err.status || 0,
+							tempId: detail.tempId
+						});
+					});
+			},
+			update: function (e) {
+				const detail = e.detail || {};
+				// Merge expected_version into payload for conflict checking
+				const payload = Object.assign({}, detail.data);
+				if (detail.expected_version !== undefined) {
+					payload.expected_version = detail.expected_version;
+				}
+				self.update(detail.id, payload)
+					.then(function (record) {
+						dispatch(self.dom, 'ln-api-connector:updated', { record: record, id: detail.id });
+					})
+					.catch(function (err) {
+						dispatch(self.dom, 'ln-api-connector:error', {
+							action: 'update',
+							error: err.message,
+							status: err.status || 0,
+							id: detail.id,
+							conflictData: err.status === 409 ? err.data : null
+						});
+					});
+			},
+			delete: function (e) {
+				const detail = e.detail || {};
+				self.delete(detail.id)
+					.then(function (res) {
+						dispatch(self.dom, 'ln-api-connector:deleted', { response: res, id: detail.id });
+					})
+					.catch(function (err) {
+						dispatch(self.dom, 'ln-api-connector:error', {
+							action: 'delete',
+							error: err.message,
+							status: err.status || 0,
+							id: detail.id
+						});
+					});
+			},
+			bulkDelete: function (e) {
+				const detail = e.detail || {};
+				self.bulkDelete(detail.ids)
+					.then(function (res) {
+						dispatch(self.dom, 'ln-api-connector:bulk-deleted', { response: res, ids: detail.ids });
+					})
+					.catch(function (err) {
+						dispatch(self.dom, 'ln-api-connector:error', {
+							action: 'bulk-delete',
+							error: err.message,
+							status: err.status || 0,
+							ids: detail.ids
+						});
+					});
+			}
+		};
+
+		// Support both general and REST namespaces for incoming requests
+		const namespaces = ['ln-api-connector', 'ln-rest-connector'];
+		namespaces.forEach(function (ns) {
+			self.dom.addEventListener(ns + ':request-sync', self._handlers.sync);
+			self.dom.addEventListener(ns + ':request-fetch', self._handlers.sync);
+			self.dom.addEventListener(ns + ':request-create', self._handlers.create);
+			self.dom.addEventListener(ns + ':request-update', self._handlers.update);
+			self.dom.addEventListener(ns + ':request-delete', self._handlers.delete);
+			self.dom.addEventListener(ns + ':request-bulk-delete', self._handlers.bulkDelete);
+		});
+	}
+
+	_component.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+
+		const self = this;
+		if (self._handlers) {
+			const namespaces = ['ln-api-connector', 'ln-rest-connector'];
+			namespaces.forEach(function (ns) {
+				self.dom.removeEventListener(ns + ':request-sync', self._handlers.sync);
+				self.dom.removeEventListener(ns + ':request-fetch', self._handlers.sync);
+				self.dom.removeEventListener(ns + ':request-create', self._handlers.create);
+				self.dom.removeEventListener(ns + ':request-update', self._handlers.update);
+				self.dom.removeEventListener(ns + ':request-delete', self._handlers.delete);
+				self.dom.removeEventListener(ns + ':request-bulk-delete', self._handlers.bulkDelete);
+			});
+			self._handlers = null;
+		}
+
+		dispatch(this.dom, 'ln-api-connector:destroyed', { target: this.dom });
+
+		delete this.dom[DOM_ATTRIBUTE];
+		delete this.dom[DOM_ALIAS];
+	};
+
+	// ─── Attribute Sync ────────────────────────────────────────
+
+	function _syncAttribute(el) {
+		const instance = el[DOM_ATTRIBUTE];
+		if (!instance) return;
+		instance.refreshConfig();
+	}
+
+	// ─── Registration ──────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-api-connector', {
+		extraAttributes: [
+			'data-ln-api-base-url',
+			'data-ln-api-path',
+			'data-ln-api-headers'
+		],
+		onAttributeChange: _syncAttribute
+	});
+})();

package/js/ln-autoresize/README.md

@@ -0,0 +1,80 @@
+# ln-autoresize
+
+A zero-dependency, high-performance **UX Helper Primitive** (~47 lines of JavaScript) that dynamically resizes a `<textarea>` to track its content. It grows as the user types and collapses instantly as text is deleted.
+
+---
+
+## 🧭 Philosophy & Architecture
+
+1. **Platform-First Execution:** Instead of introducing heavy observers or layouts, `ln-autoresize` hooks directly into the browser's native layout engine. By resetting height to `auto` before reading `scrollHeight` inside the event loop, it forces a synchronous, flicker-free layout calculation.
+2. **Strict Concern Scope:** The primitive is stateless. Ceiling limits, minimum bounds, and manual resize handles are defined exclusively via standard CSS classes. The script only handles active observation.
+3. **Reactive Synchronization:** Data flows strictly through DOM events. Programmatic changes must trigger standard events (`input` / `change`) so that dependent primitives can adapt in synchrony.
+
+---
+
+## 📦 Minimal Blueprint
+
+```html
+<textarea data-ln-autoresize rows="1" placeholder="Type here..."></textarea>
+```
+
+To cap growth at a maximum height and enable scroll past it, pair the attribute with pure CSS:
+
+```scss
+textarea[data-ln-autoresize] {
+    resize: none;         // Removes conflicting manual drag handle
+    max-height: 6rem;     // Defines height ceiling
+    overflow-y: auto;     // Reveals scrollbar at ceiling
+}
+```
+
+> [!TIP]
+> Always set `rows="1"` on the HTML element. This ensures the initial empty height matches the post-initialization state and prevents visual snap-shut on first paint.
+
+---
+
+## 🛠️ Declarative API Contract
+
+### HTML Attributes
+
+| Attribute | Elements | Description |
+| :--- | :--- | :--- |
+| `data-ln-autoresize` | `<textarea>` | Observation marker. Presence creates the instance and runs initial measurement. |
+
+### JS API
+
+Access the utility instance directly via the `lnAutoresize` property on the textarea element:
+
+```javascript
+const textarea = document.getElementById('my-textarea');
+
+// 1. Force a manual re-measure (essential after parent reveals, font loads, etc.)
+textarea.lnAutoresize._resize();
+
+// 2. Tear down event listeners and clear inline styles
+textarea.lnAutoresize.destroy();
+```
+
+---
+
+## ⚡ DOM Events
+
+`ln-autoresize` does not emit custom events. It relies entirely on standard browser interactions:
+
+- **Listens to `input`:** Triggers `_resize()` on keystrokes, pastes, and deletes.
+- **Listens to `change`:** Triggers `_resize()` on value commits.
+
+---
+
+## ⚠️ Common Pitfalls
+
+- **Setting `textarea.value` directly:** Programmatic writes are silent in the DOM. The component will not detect value updates unless you dispatch a synthetic event:
+  ```javascript
+  textarea.value = 'New text content';
+  textarea.dispatchEvent(new Event('input', { bubbles: true }));
+  ```
+- **Mounting in hidden parents:** A textarea inside a `display: none` container measures `scrollHeight` as `0`. When revealed later, it will appear collapsed. Force a re-measure manually after reveal:
+  ```javascript
+  textarea.lnAutoresize._resize();
+  ```
+- **Conflicting manual drag handles:** By default, textareas may have `resize: vertical` applied. This lets users manual resize the input, which is instantly overridden by the script on the next keystroke. Set `resize: none` to clean up the interface.

package/js/ln-autoresize/ln-autoresize.js

@@ -0,0 +1 @@
+(function(){"use strict";function y(e,t){if(!document.body){document.addEventListener("DOMContentLoaded",function(){y(e,t)}),console.warn("["+t+'] Script loaded before <body> — add "defer" to your <script> tag');return}e()}function h(e,t,n,r){if(e.nodeType!==1)return;const f=t.indexOf("[")!==-1||t.indexOf(".")!==-1||t.indexOf("#")!==-1?t:"["+t+"]",a=Array.from(e.querySelectorAll(f));e.matches&&e.matches(f)&&a.push(e);for(const i of a)i[n]||(i[n]=new r(i))}function b(e,t,n,r,s={}){const f=s.extraAttributes||[],a=s.onAttributeChange||null,i=s.onInit||null;function c(p){const d=p||document.body;h(d,e,t,n),i&&i(d)}return y(function(){const p=new MutationObserver(function(l){for(let u=0;u<l.length;u++){const o=l[u];if(o.type==="childList")for(let g=0;g<o.addedNodes.length;g++){const m=o.addedNodes[g];m.nodeType===1&&(h(m,e,t,n),i&&i(m))}else o.type==="attributes"&&(a&&o.target[t]?a(o.target,o.attributeName):(h(o.target,e,t,n),i&&i(o.target)))}});let d=[];if(e.indexOf("[")!==-1){const l=/\[([\w-]+)/g;let u;for(;(u=l.exec(e))!==null;)d.push(u[1])}else d.push(e);p.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:d.concat(f)})},r),window[t]=c,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){c(document.body)}):c(document.body),c}const w={};function x(e,t){w[e]=t}function A(e){return w[e]||{ingress:t=>t,egress:t=>t}}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=x,window.lnCore.getDataMapper=A),(function(){const e="data-ln-autoresize",t="lnAutoresize";if(window[t]!==void 0)return;function n(r){if(r.tagName!=="TEXTAREA")return console.warn("[ln-autoresize] Can only be applied to <textarea>, got:",r.tagName),this;this.dom=r;const s=this;return this._onInput=function(){s._resize()},r.addEventListener("input",this._onInput),this._resize(),this}n.prototype._resize=function(){this.dom.style.height="auto",this.dom.style.height=this.dom.scrollHeight+"px"},n.prototype.destroy=function(){this.dom[t]&&(this.dom.removeEventListener("input",this._onInput),this.dom.style.height="",delete this.dom[t])},b(e,t,n,"ln-autoresize")})()})();

package/js/ln-autoresize/src/ln-autoresize.js

@@ -0,0 +1,47 @@
+import { registerComponent } from '../../ln-core';
+
+(function () {
+	const DOM_SELECTOR = 'data-ln-autoresize';
+	const DOM_ATTRIBUTE = 'lnAutoresize';
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+	// ─── Component ─────────────────────────────────────────────
+
+	function _component(dom) {
+		if (dom.tagName !== 'TEXTAREA') {
+			console.warn('[ln-autoresize] Can only be applied to <textarea>, got:', dom.tagName);
+			return this;
+		}
+
+		this.dom = dom;
+
+		const self = this;
+		this._onInput = function () {
+			self._resize();
+		};
+
+		dom.addEventListener('input', this._onInput);
+
+		// Initial resize (content may be pre-filled)
+		this._resize();
+
+		return this;
+	}
+
+	_component.prototype._resize = function () {
+		this.dom.style.height = 'auto';
+		this.dom.style.height = this.dom.scrollHeight + 'px';
+	};
+
+	_component.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+		this.dom.removeEventListener('input', this._onInput);
+		this.dom.style.height = '';
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	// ─── Init ──────────────────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-autoresize');
+})();

package/js/ln-autosave/README.md

@@ -0,0 +1,92 @@
+# ln-autosave
+
+A zero-dependency, localStorage-backed **Draft Buffer Primitive** that prevents data loss by capturing form states. It automatically saves drafts on field boundaries, restores values on load, and clears them cleanly on submit, reset, or custom cancellations.
+
+---
+
+## 🧭 Philosophy & Architecture
+
+1. **Synchronous local storage:** Unlike async network databases, `ln-autosave` uses browser `localStorage`. This ensures drafts are written instantly on field blur/leave (`focusout` / `change`), eliminating race conditions during page changes.
+2. **Zero-Keystroke flood:** By default, writing only triggers on field blur. For continuous typing fields (like editors), an opt-in debounced input listener can be configured.
+3. **Decoupled Event Restoration:** restored values are applied by dispatching standard synthetic `input` and `change` events. This ensures sibling primitives (such as `ln-validate` and `ln-autoresize`) re-evaluate automatically.
+
+---
+
+## 📦 Minimal Blueprint
+
+```html
+<form id="profile-edit" data-ln-autosave>
+  <div class="form-element">
+    <label for="bio">Biography</label>
+    <textarea id="bio" name="bio" data-ln-autoresize rows="1"></textarea>
+  </div>
+  
+  <ul class="form-actions">
+    <li><button type="button" data-ln-autosave-clear>Cancel (clear draft)</button></li>
+    <li><button type="submit">Save</button></li>
+  </ul>
+</form>
+```
+
+> [!IMPORTANT]
+> The form **must** have a unique `id` or you must specify a custom identifier in `data-ln-autosave="identifier"`. The final storage key is scoped uniquely as `ln-autosave:{pathname}:{identifier}`.
+
+---
+
+## 🛠️ Declarative API Contract
+
+### HTML Attributes
+
+| Attribute | Elements | Description |
+| :--- | :--- | :--- |
+| `data-ln-autosave` | `<form>` | Persistence marker. Value overrides the form ID lookup. |
+| `data-ln-autosave-clear` | `<button>` | Click delegate. Instantly purges the localStorage entry. |
+| `data-ln-autosave-debounce-input="ms"` | `<form>` | Opt-in. Saves on idle keystrokes (defaults to 1000ms if empty). |
+
+### JS API
+
+Access the persistence instance directly via the `lnAutoresize` property on the form element:
+
+```javascript
+const form = document.getElementById('profile-edit');
+
+// 1. Back-reference properties
+const storageKey = form.lnAutosave.key; // "ln-autosave:/path:profile-edit"
+
+// 2. Clean up listeners and pending timers
+form.lnAutosave.destroy();
+```
+
+---
+
+## ⚡ DOM Events
+
+### Emitted
+
+| Event | Bubbles | Payload | Description |
+| :--- | :--- | :--- | :--- |
+| `ln-autosave:before-restore` | Yes (Cancelable) | `{ target, data }` | Fires before applying draft. Call `e.preventDefault()` to abort. |
+| `ln-autosave:restored` | Yes | `{ target, data }` | Dispatched after populated values and synthetic events are sent. |
+| `ln-autosave:saved` | Yes | `{ target, data }` | Dispatched on successful localStorage save. |
+| `ln-autosave:cleared` | Yes | `{ target }` | Dispatched after localStorage item removal. |
+
+---
+
+## ⚠️ Common Pitfalls
+
+- **Stale Drafts Overwriting Server Data:** On pages where the database has rendered new state, draft restores must be aborted:
+  ```javascript
+  document.addEventListener('ln-autosave:before-restore', function (e) {
+      if (e.target.dataset.hasServerData === 'true') {
+          e.preventDefault();
+          localStorage.removeItem(e.target.lnAutosave.key);
+      }
+  });
+  ```
+- **ESC Modal Dismissals:** If a user closes a modal using the ESC key, no click triggers on cancel buttons. Wire draft cleanup to the modal's closed event manually:
+  ```javascript
+  modal.addEventListener('ln-modal:closed', () => {
+      localStorage.removeItem(form.lnAutosave.key);
+  });
+  ```
+- **Nameless & File Inputs:** `ln-autosave` ignores disabled inputs, button elements, `type="file"`, and inputs missing a `name` attribute.

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

@@ -0,0 +1 @@
+(function(){"use strict";function E(o,e,u){o.dispatchEvent(new CustomEvent(e,{bubbles:!0,detail:u||{}}))}function A(o,e,u){const s=new CustomEvent(e,{bubbles:!0,cancelable:!0,detail:u||{}});return o.dispatchEvent(s),s}function C(o,e){if(!document.body){document.addEventListener("DOMContentLoaded",function(){C(o,e)}),console.warn("["+e+'] Script loaded before <body> — add "defer" to your <script> tag');return}o()}function y(o,e,u,s){if(o.nodeType!==1)return;const i=e.indexOf("[")!==-1||e.indexOf(".")!==-1||e.indexOf("#")!==-1?e:"["+e+"]",l=Array.from(o.querySelectorAll(i));o.matches&&o.matches(i)&&l.push(o);for(const c of l)c[u]||(c[u]=new s(c))}function O(o){const e={},u=o.elements;for(let s=0;s<u.length;s++){const n=u[s];if(!(!n.name||n.disabled||n.type==="file"||n.type==="submit"||n.type==="button"))if(n.type==="checkbox")e[n.name]||(e[n.name]=[]),n.checked&&e[n.name].push(n.value);else if(n.type==="radio")n.checked&&(e[n.name]=n.value);else if(n.type==="select-multiple"){e[n.name]=[];for(let i=0;i<n.options.length;i++)n.options[i].selected&&e[n.name].push(n.options[i].value)}else e[n.name]=n.value}return e}function S(o,e){const u=o.elements,s=[];for(let n=0;n<u.length;n++){const i=u[n];if(!i.name||!(i.name in e)||i.type==="file"||i.type==="submit"||i.type==="button")continue;const l=e[i.name];if(i.type==="checkbox")i.checked=Array.isArray(l)?l.indexOf(i.value)!==-1:!!l,s.push(i);else if(i.type==="radio")i.checked=i.value===String(l),s.push(i);else if(i.type==="select-multiple"){if(Array.isArray(l))for(let c=0;c<i.options.length;c++)i.options[c].selected=l.indexOf(i.options[c].value)!==-1;s.push(i)}else i.value=l,s.push(i)}return s}function T(o,e,u,s,n={}){const i=n.extraAttributes||[],l=n.onAttributeChange||null,c=n.onInit||null;function p(b){const t=b||document.body;y(t,o,e,u),c&&c(t)}return C(function(){const b=new MutationObserver(function(a){for(let r=0;r<a.length;r++){const h=a[r];if(h.type==="childList")for(let g=0;g<h.addedNodes.length;g++){const v=h.addedNodes[g];v.nodeType===1&&(y(v,o,e,u),c&&c(v))}else h.type==="attributes"&&(l&&h.target[e]?l(h.target,h.attributeName):(y(h.target,o,e,u),c&&c(h.target)))}});let t=[];if(o.indexOf("[")!==-1){const a=/\[([\w-]+)/g;let r;for(;(r=a.exec(o))!==null;)t.push(r[1])}else t.push(o);b.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:t.concat(i)})},s),window[e]=p,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){p(document.body)}):p(document.body),p}const w={};function D(o,e){w[o]=e}function I(o){return w[o]||{ingress:e=>e,egress:e=>e}}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=D,window.lnCore.getDataMapper=I),(function(){const o="data-ln-autosave",e="lnAutosave",u="data-ln-autosave-clear",s="data-ln-autosave-debounce-input",n="ln-autosave:";if(window[e]!==void 0)return;function l(t){const a=c(t);if(!a){console.warn("ln-autosave: form needs an id or data-ln-autosave value",t);return}this.dom=t,this.key=a;let r=null;function h(){const d=O(t);try{localStorage.setItem(a,JSON.stringify(d))}catch{return}E(t,"ln-autosave:saved",{target:t,data:d})}function g(){let d;try{d=localStorage.getItem(a)}catch{return}if(!d)return;let f;try{f=JSON.parse(d)}catch{return}if(A(t,"ln-autosave:before-restore",{target:t,data:f}).defaultPrevented)return;const _=S(t,f);for(let m=0;m<_.length;m++)_[m].dispatchEvent(new Event("input",{bubbles:!0})),_[m].dispatchEvent(new Event("change",{bubbles:!0}));E(t,"ln-autosave:restored",{target:t,data:f})}function v(){try{localStorage.removeItem(a)}catch{return}E(t,"ln-autosave:cleared",{target:t})}this._onFocusout=function(d){const f=d.target;p(f)&&f.name&&h()},this._onChange=function(d){const f=d.target;p(f)&&f.name&&h()},this._onSubmit=function(){v()},this._onReset=function(){v()},this._onClearClick=function(d){d.target.closest("["+u+"]")&&v()},t.addEventListener("focusout",this._onFocusout),t.addEventListener("change",this._onChange),t.addEventListener("submit",this._onSubmit),t.addEventListener("reset",this._onReset),t.addEventListener("click",this._onClearClick);const L=b(t);return L>0&&(this._onInput=function(d){const f=d.target;!p(f)||!f.name||(r!==null&&clearTimeout(r),r=setTimeout(h,L))},t.addEventListener("input",this._onInput)),this._getInputTimer=function(){return r},g(),this}l.prototype.destroy=function(){if(this.dom[e]){if(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),this._onInput){this.dom.removeEventListener("input",this._onInput);const t=this._getInputTimer();t!==null&&clearTimeout(t)}E(this.dom,"ln-autosave:destroyed",{target:this.dom}),delete this.dom[e]}};function c(t){const r=t.getAttribute(o)||t.id;return r?n+window.location.pathname+":"+r:null}function p(t){const a=t.tagName;return a==="INPUT"||a==="TEXTAREA"||a==="SELECT"}function b(t){if(!t.hasAttribute(s))return 0;const a=t.getAttribute(s);if(a===""||a===null)return 1e3;const r=parseInt(a,10);return isNaN(r)||r<0?(console.warn("ln-autosave: invalid debounce value, using default",t),1e3):r}T(o,e,l,"ln-autosave")})()})();