@livenetworks/ashlar 1.6.0 → 2.0.0

package/components/ln-core/dom.js

@@ -0,0 +1,115 @@
+// ─── Guard Body ────────────────────────────────────────
+
+export function guardBody(setupFn, componentTag) {
+	if (!document.body) {
+		document.addEventListener('DOMContentLoaded', function () {
+			guardBody(setupFn, componentTag);
+		});
+		console.warn('[' + componentTag + '] Script loaded before <body> — add "defer" to your <script> tag');
+		return;
+	}
+	setupFn();
+}
+
+// ─── Visibility Check ─────────────────────────────────────
+
+export function isVisible(el) {
+	return !!(el.offsetWidth || el.offsetHeight || el.getClientRects().length);
+}
+
+/**
+ * Determines whether a mouse click event should be ignored (modified click or non-primary button).
+ * @param {MouseEvent|Object} [event]
+ * @returns {boolean}
+ */
+export function shouldIgnoreClick(event) {
+	if (!event) return true;
+	if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) return true;
+	if (typeof event.button === 'number' && event.button !== 0) return true;
+	return false;
+}
+
+/**
+ * Checks if a target element is an active editable field or contenteditable element.
+ * @param {Element|Object} [target]
+ * @returns {boolean}
+ */
+export function isEditableTarget(target) {
+	if (!target) return false;
+	if (typeof target.closest === 'function') {
+		return Boolean(target.closest('input, textarea, select, [contenteditable]:not([contenteditable="false"])'));
+	}
+	const tag = String(target.tagName || '').toLowerCase();
+	return tag === 'input' || tag === 'textarea' || tag === 'select' || Boolean(target.isContentEditable);
+}
+
+/**
+ * Checks if a target element is disabled, aria-disabled, or inside an inert container.
+ * @param {Element|Object} [target]
+ * @returns {boolean}
+ */
+export function isTargetDisabled(target) {
+	if (!target) return true;
+	if (target.disabled || (typeof target.getAttribute === 'function' && target.getAttribute('aria-disabled') === 'true')) {
+		return true;
+	}
+	if (typeof target.closest === 'function' && target.closest('[inert]')) {
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Checks if a target element is connected, enabled, not inert, visible, and optionally supports an action method.
+ * @param {Element} target
+ * @param {string} [action]
+ * @returns {boolean}
+ */
+export function isUsableTarget(target, action) {
+	if (!target || !document.contains(target)) return false;
+	if (isTargetDisabled(target)) return false;
+	if (action && typeof target[action] !== 'function') return false;
+	return isVisible(target);
+}
+
+/**
+ * Checks if a link click should be intercepted by client-side routing.
+ * Must be standard navigation click (left button, no modifiers), same origin,
+ * not mailto/tel, and not pure hash/empty.
+ *
+ * @param {MouseEvent} event
+ * @param {HTMLAnchorElement} anchor
+ * @returns {boolean}
+ */
+export function shouldInterceptLink(event, anchor) {
+	if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey || event.button !== 0) {
+		return false;
+	}
+	if (!anchor) return false;
+	const href = anchor.getAttribute('href');
+	if (!href) return false;
+	if (anchor.getAttribute('target') === '_blank') return false;
+	if (anchor.hasAttribute('download')) return false;
+	if (href.startsWith('mailto:') || href.startsWith('tel:')) return false;
+	if (href === '#' || href.startsWith('#')) return false;
+	if (anchor.hostname && anchor.hostname !== window.location.hostname) return false;
+	return true;
+}
+
+/**
+ * Read the raw machine value behind a formatted cell/item display.
+ * Returns the `data-ln-value` attribute if present, else trimmed textContent.
+ * Single read path for value-based sort/filter across components.
+ */
+export function readValue(el) {
+	if (el.hasAttribute('data-ln-value')) {
+		return el.getAttribute('data-ln-value');
+	}
+	if (el.tagName === 'TIME' && el.hasAttribute('datetime')) {
+		return el.getAttribute('datetime');
+	}
+	if (el.tagName === 'DATA' && el.hasAttribute('value')) {
+		return el.getAttribute('value');
+	}
+	return el.textContent.trim();
+}

package/components/ln-core/events.js

@@ -0,0 +1,122 @@
+// ─── Environment & Debug Gates ─────────────────────────────
+
+export function hasActiveDebug() {
+	if (typeof window === 'undefined') return false;
+	if (window.lnDebug === true) return true;
+	if (window.lnCore && window.lnCore._debugSink) return true;
+	if (typeof document !== 'undefined' && document.body) {
+		return document.body.hasAttribute('data-ln-debug') || document.body.querySelector('[data-ln-debug]') !== null;
+	}
+	return false;
+}
+
+export function isDevMode(el) {
+	if (typeof window === 'undefined') return false;
+	if (window.lnDebug === true) return true;
+
+	// Authoritative gate check when ln-debug is active
+	if (window.lnCore && window.lnCore._debugIsContained) {
+		if (el) return window.lnCore._debugIsContained(el);
+		return window.lnCore._debugSink !== null;
+	}
+
+	// Direct DOM containment fallback (e.g. standalone tests or before gate boots)
+	if (el && el.closest) {
+		const host = el.closest('[data-ln-debug]');
+		if (!host || (typeof document !== 'undefined' && host === document.documentElement)) {
+			return false;
+		}
+		return true;
+	}
+	if (typeof document !== 'undefined' && document.body) {
+		return document.body.hasAttribute('data-ln-debug');
+	}
+	return false;
+}
+
+// ─── Global Console Warning Interceptor (Production Mode) ──
+if (typeof window !== 'undefined') {
+	window.lnCore = window.lnCore || {};
+	if (!window.lnCore._warnBound) {
+		window.lnCore._warnBound = true;
+		const originalWarn = console.warn;
+		console.warn = function (...args) {
+			const isLibraryWarning = typeof args[0] === 'string' &&
+				(args[0].startsWith('[ln-') || args[0].startsWith('[lnCore'));
+
+			if (isLibraryWarning) {
+				let el = null;
+				for (let i = 1; i < args.length; i++) {
+					if (args[i] && args[i].nodeType === 1) {
+						el = args[i];
+						break;
+					}
+				}
+				if (!isDevMode(el)) {
+					return;
+				}
+			}
+			originalWarn.apply(console, args);
+		};
+	}
+}
+
+// ─── Event Dispatch & Sinks ────────────────────────────────
+
+// Nullable console-observation sink. Installed/removed only by ln-debug's
+// gate (components/ln-debug/src/gate.js). window.lnCore is guaranteed already
+// initialized by the module-load-time block above (_warnBound),
+// so the hot-path read needs no defensive "window.lnCore &&" guard.
+export function setDebugSink(sink, isContained) {
+	window.lnCore = window.lnCore || {};
+	window.lnCore._debugSink = sink;
+	window.lnCore._debugIsContained = isContained || null;
+}
+
+// Nullable persist restore/save sink. Installed/removed only by ln-persist
+// (components/ln-persist/src/ln-persist.js) — mirrors setDebugSink exactly.
+export function setPersistSink(sink) {
+	window.lnCore = window.lnCore || {};
+	window.lnCore._persistSink = sink;
+}
+
+export function dispatch(element, eventName, detail) {
+	const payload = detail || {};
+	if (window.lnCore._debugSink) window.lnCore._debugSink('event', eventName, element, payload);
+	element.dispatchEvent(new CustomEvent(eventName, {
+		bubbles: true,
+		detail: payload
+	}));
+}
+
+export function dispatchCancelable(element, eventName, detail) {
+	const payload = detail || {};
+	if (window.lnCore._debugSink) window.lnCore._debugSink('event', eventName, element, payload);
+	const event = new CustomEvent(eventName, {
+		bubbles: true,
+		cancelable: true,
+		detail: payload
+	});
+	element.dispatchEvent(event);
+	return event;
+}
+
+/**
+ * Re-filter / re-sort / re-render a data-driven list-like component, then
+ * notify the coordinator that fresh data is requested.
+ */
+export function requestData(component, eventName, keyName) {
+	component._applyFilterAndSort();
+	component._vStart = -1;
+	component._vEnd = -1;
+	component._render();
+	component._updateFooter();
+
+	const detail = {
+		sort: component.currentSort,
+		filters: component.currentFilters,
+		search: component.currentSearch
+	};
+	detail[keyName] = component.name;
+	dispatch(component.dom, eventName, detail);
+}

package/components/ln-core/form.js

@@ -0,0 +1,136 @@
+// ─── Form Method Resolution ────────────────────────────────
+
+export function resolveFormMethod(form) {
+	const methodInput = form.querySelector('input[name="_method"]');
+	const raw = (methodInput && methodInput.value !== '') ? methodInput.value : form.method;
+	return (raw || '').toUpperCase();
+}
+
+// ─── Form Serialization ───────────────────────────────────
+
+export function serializeForm(form, opts) {
+	const typed = !!(opts && opts.typed);
+	const exclude = opts && opts.exclude;
+	const data = {};
+	const elements = form.elements;
+
+	const checkboxCounts = {};
+	if (typed) {
+		for (let i = 0; i < elements.length; i++) {
+			const el = elements[i];
+			if (el.name && el.type === 'checkbox' && !el.disabled) {
+				checkboxCounts[el.name] = (checkboxCounts[el.name] || 0) + 1;
+			}
+		}
+	}
+
+	for (let i = 0; i < elements.length; i++) {
+		const el = elements[i];
+		if (!el.name || el.disabled || el.type === 'file' || el.type === 'submit' || el.type === 'button') continue;
+		if (exclude && el.matches && el.matches(exclude)) continue;
+
+		if (el.type === 'checkbox') {
+			if (typed && checkboxCounts[el.name] === 1) {
+				data[el.name] = el.checked;
+			} else {
+				if (!data[el.name]) data[el.name] = [];
+				if (el.checked) data[el.name].push(el.value);
+			}
+		} else if (el.type === 'radio') {
+			if (el.checked) data[el.name] = el.value;
+		} else if (el.type === 'select-multiple') {
+			data[el.name] = [];
+			for (let j = 0; j < el.options.length; j++) {
+				if (el.options[j].selected) data[el.name].push(el.options[j].value);
+			}
+		} else if (typed && el.type === 'hidden') {
+			data[el.name] = el.value;
+		} else if (typed && (el.type === 'number' || el.type === 'range')) {
+			const n = Number(el.value);
+			data[el.name] = (el.value === '' || isNaN(n)) ? null : n;
+		} else {
+			data[el.name] = el.value;
+		}
+	}
+
+	return data;
+}
+
+// ─── Form Population ──────────────────────────────────────
+
+function _coerceBool(value) {
+	if (typeof value !== 'string') return !!value;
+	const v = value.trim().toLowerCase();
+	return v !== 'false' && v !== '0' && v !== '' && v !== 'off' && v !== 'no';
+}
+
+export function populateForm(form, data) {
+	const elements = form.elements;
+	const filled = [];
+
+	const checkboxCounts = {};
+	for (let i = 0; i < elements.length; i++) {
+		const el = elements[i];
+		if (el.name && el.type === 'checkbox') {
+			checkboxCounts[el.name] = (checkboxCounts[el.name] || 0) + 1;
+		}
+	}
+
+	for (let i = 0; i < elements.length; i++) {
+		const el = elements[i];
+		if (el.type === 'file' || el.type === 'submit' || el.type === 'button') continue;
+
+		const matchKey = el.getAttribute('data-ln-fill-as') || el.name;
+		if (!matchKey || !(matchKey in data)) continue;
+
+		const value = data[matchKey];
+
+		if (el.type === 'checkbox') {
+			if (Array.isArray(value)) {
+				el.checked = value.indexOf(el.value) !== -1;
+			} else if (checkboxCounts[el.name] > 1) {
+				const list = String(value).split(',').map(function (s) { return s.trim(); });
+				el.checked = list.indexOf(el.value) !== -1;
+			} else {
+				el.checked = _coerceBool(value);
+			}
+			filled.push(el);
+		} else if (el.type === 'radio') {
+			el.checked = el.value === String(value);
+			filled.push(el);
+		} else if (el.type === 'select-multiple') {
+			if (Array.isArray(value)) {
+				for (let j = 0; j < el.options.length; j++) {
+					el.options[j].selected = value.indexOf(el.options[j].value) !== -1;
+				}
+			}
+			filled.push(el);
+		} else {
+			el.value = value;
+			filled.push(el);
+		}
+	}
+
+	return filled;
+}
+
+// ─── Value Property Interception ───────────────────────────
+
+export function interceptValueProperty(dom, descriptor, { get, set }) {
+	Object.defineProperty(dom, 'value', {
+		get: function () {
+			if (get) {
+				return get.call(this);
+			}
+			return descriptor.get.call(this);
+		},
+		set: function (val) {
+			if (set) {
+				set.call(this, val, (originalVal) => descriptor.set.call(this, originalVal));
+			} else {
+				descriptor.set.call(this, val);
+			}
+		},
+		configurable: true
+	});
+}

package/{js → components}/ln-core/hash.js

@@ -1,92 +1,149 @@
-// ─── Hash codec (URL fragment as namespaced state) ─────────
-//
-// Grammar:  #nsA:valA&nsB:valB
-// Each component owns ONE namespace, ignores all others, and PRESERVES
-// foreign segments on write — this is what makes component isolation work.
-//
-// Three-state value model:
-//   absent        → hashGet returns null   (e.g. closed)
-//   #ns           → hashGet returns ''      (present, no value — e.g. "new")
-//   #ns:val       → hashGet returns 'val'   (present, with param)
-//
-// Write mechanism: `location.hash =` (fires hashchange; identical value is a
-// no-op so there are no loops). Never pushState here.
-
-function _strip(str) {
-	return (str || '').replace(/^#/, '');
-}
-
-export function hashParse(str) {
-	const raw = (str === undefined) ? location.hash : str;
-	const map = {};
-	const h = _strip(raw);
-	if (!h) return map;
-	const parts = h.split('&');
-	for (let i = 0; i < parts.length; i++) {
-		const part = parts[i];
-		if (!part) continue;
-		const sep = part.indexOf(':');
-		const ns = (sep > -1 ? part.slice(0, sep) : part);
-		const val = (sep > -1 ? part.slice(sep + 1) : '');
-		if (!ns) continue;
-		try { map[ns] = decodeURIComponent(val); }
-		catch (e) { map[ns] = val; }
-	}
-	return map;
-}
-
-export function hashGet(ns) {
-	if (!ns) return null;
-	const map = hashParse();
-	return (ns in map) ? map[ns] : null;
-}
-
-export function hashSet(ns, value) {
-	if (!ns) return;
-	const map = hashParse();
-	if (value === null || value === undefined) {
-		delete map[ns];
-	} else {
-		map[ns] = String(value);
-	}
-	const keys = Object.keys(map);
-	const next = keys.map(function (k) {
-		const v = map[k];
-		return (v === '') ? k : (k + ':' + encodeURIComponent(v));
-	}).join('&');
-	// Setting an identical hash is a no-op (no hashchange) → no loops.
-	if (_strip(location.hash) === next) return;
-	location.hash = next;
-}
-
-// ─── Hash-link click guard (shared by ln-tabs & ln-modal) ──
-//
-// A "hash link" is an <a href="#…"> whose click a component wants to drive
-// through the codec instead of native fragment navigation (native nav replaces
-// the WHOLE fragment and wipes foreign segments). Both ln-tabs and ln-modal
-// funnel their own anchor clicks through here so the guard + preventDefault
-// live in ONE place.
-//
-// Returns:
-//   false → modifier / middle / shift-click: caller must return and let the
-//           browser do native open-in-new-tab / new-window. No preventDefault.
-//   true  → ordinary click: preventDefault() has been called; caller proceeds
-//           with its OWN write (hashSet merge, or a component-specific branch
-//           such as ln-tabs' already-current setAttribute).
-//
-// Deliberately does NOT call hashSet — ln-tabs needs an "already-current value
-// → setAttribute active directly (no hash write)" branch, so the write differs
-// per component. The shared, reusable surface is the guard + preventDefault.
-export function hashLinkClick(e) {
-	if (e.button === 1 || e.ctrlKey || e.metaKey || e.shiftKey) return false;
-	e.preventDefault();
-	return true;
-}
-
-if (typeof window !== 'undefined') {
-	window.lnCore = window.lnCore || {};
-	window.lnCore.hashParse = hashParse;
-	window.lnCore.hashGet = hashGet;
-	window.lnCore.hashSet = hashSet;
-	window.lnCore.hashLinkClick = hashLinkClick;
-}
+// ─── Hash codec (URL fragment as namespaced state) ─────────
+//
+// Grammar:  #nsA:valA&nsB:valB
+// Each component owns ONE namespace, ignores all others, and PRESERVES
+// foreign segments on write — this is what makes component isolation work.
+//
+// Three-state value model:
+//   absent        → hashGet returns null   (e.g. closed)
+//   #ns           → hashGet returns ''      (present, no value — e.g. "new")
+//   #ns:val       → hashGet returns 'val'   (present, with param)
+//
+// Write mechanism: `location.hash =` (fires hashchange; identical value is a
+// no-op so there are no loops). Never pushState here.
+
+function _strip(str) {
+	return (str || '').replace(/^#/, '');
+}
+
+export function hashParse(str) {
+	const raw = (str === undefined) ? location.hash : str;
+	const map = {};
+	const h = _strip(raw);
+	if (!h) return map;
+	const parts = h.split('&');
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (!part) continue;
+		const sep = part.indexOf(':');
+		const ns = (sep > -1 ? part.slice(0, sep) : part);
+		const val = (sep > -1 ? part.slice(sep + 1) : '');
+		if (!ns) continue;
+		try { map[ns] = decodeURIComponent(val); }
+		catch (e) { map[ns] = val; }
+	}
+	return map;
+}
+
+export function hashGet(ns) {
+	if (!ns) return null;
+	const map = hashParse();
+	return (ns in map) ? map[ns] : null;
+}
+
+export function hashSet(ns, value) {
+	if (!ns) return;
+	const map = hashParse();
+	if (value === null || value === undefined) {
+		delete map[ns];
+	} else {
+		map[ns] = String(value);
+	}
+	const keys = Object.keys(map);
+	const next = keys.map(function (k) {
+		const v = map[k];
+		return (v === '') ? k : (k + ':' + encodeURIComponent(v));
+	}).join('&');
+	// Setting an identical hash is a no-op (no hashchange) → no loops.
+	if (_strip(location.hash) === next) return;
+	location.hash = next;
+}
+
+// ─── Hash-link click guard (shared by ln-tabs & ln-modal) ──
+//
+// A "hash link" is an <a href="#…"> whose click a component wants to drive
+// through the codec instead of native fragment navigation (native nav replaces
+// the WHOLE fragment and wipes foreign segments). Both ln-tabs and ln-modal
+// funnel their own anchor clicks through here so the guard + preventDefault
+// live in ONE place.
+//
+// Returns:
+//   false → modifier / middle / shift-click: caller must return and let the
+//           browser do native open-in-new-tab / new-window. No preventDefault.
+//   true  → ordinary click: preventDefault() has been called; caller proceeds
+//           with its OWN write (hashSet merge, or a component-specific branch
+//           such as ln-tabs' already-current setAttribute).
+//
+// Deliberately does NOT call hashSet — ln-tabs needs an "already-current value
+// → setAttribute active directly (no hash write)" branch, so the write differs
+// per component. The shared, reusable surface is the guard + preventDefault.
+export function hashLinkClick(e) {
+	if (e.button === 1 || e.ctrlKey || e.metaKey || e.shiftKey) return false;
+	e.preventDefault();
+	return true;
+}
+
+// ─── Hash Helpers for Controls (ln-sort, ln-search, ln-filter) ──
+
+export function resolveHashNamespace(el, defaultSuffix) {
+	if (!el || !el.hasAttribute('data-ln-hash')) return null;
+	const explicit = el.getAttribute('data-ln-hash');
+	if (explicit && explicit.trim() !== '') return explicit.trim();
+	const targetId = el.getAttribute('data-ln-sort')
+		|| el.getAttribute('data-ln-search-for')
+		|| el.getAttribute('data-ln-search')
+		|| el.getAttribute('data-ln-filter')
+		|| el.id;
+	if (targetId) {
+		return defaultSuffix ? (targetId + '-' + defaultSuffix) : targetId;
+	}
+	return defaultSuffix || null;
+}
+
+export function hashSortEncode(fieldOrColumn, direction) {
+	if (!direction || direction === 'none' || fieldOrColumn === null || fieldOrColumn === undefined) return null;
+	return String(fieldOrColumn) + '.' + direction;
+}
+
+export function hashSortDecode(val) {
+	if (!val || typeof val !== 'string') return null;
+	if (val.endsWith('.asc')) {
+		return { fieldOrColumn: val.slice(0, -4), direction: 'asc' };
+	}
+	if (val.endsWith('.desc')) {
+		return { fieldOrColumn: val.slice(0, -5), direction: 'desc' };
+	}
+	return null;
+}
+
+export function hashFilterEncode(key, values) {
+	if (!key || !Array.isArray(values) || values.length === 0) return null;
+	return key + ':' + values.map(encodeURIComponent).join(',');
+}
+
+export function hashFilterDecode(val) {
+	if (!val || typeof val !== 'string') return null;
+	const colon = val.indexOf(':');
+	if (colon === -1) return null;
+	const key = val.slice(0, colon);
+	const rawValues = val.slice(colon + 1);
+	const values = rawValues ? rawValues.split(',').map(function (v) {
+		try { return decodeURIComponent(v); }
+		catch (e) { return v; }
+	}).filter(Boolean) : [];
+	return { key: key, values: values };
+}
+
+if (typeof window !== 'undefined') {
+	window.lnCore = window.lnCore || {};
+	window.lnCore.hashParse = hashParse;
+	window.lnCore.hashGet = hashGet;
+	window.lnCore.hashSet = hashSet;
+	window.lnCore.hashLinkClick = hashLinkClick;
+	window.lnCore.resolveHashNamespace = resolveHashNamespace;
+	window.lnCore.hashSortEncode = hashSortEncode;
+	window.lnCore.hashSortDecode = hashSortDecode;
+	window.lnCore.hashFilterEncode = hashFilterEncode;
+	window.lnCore.hashFilterDecode = hashFilterDecode;
+}
+

package/components/ln-core/helpers.js

@@ -0,0 +1,33 @@
+// ==========================================================================
+// ln-core — Shared Helpers & Runtime Kernel Facade (Barrel File)
+// ==========================================================================
+// All primitives are modularized into cohesive single-responsibility modules.
+// This barrel re-exports the entire public surface with 100% backward
+// compatibility. Evaluation order preserves module initialization invariants:
+// events.js evaluates first to ensure window.lnCore and console warning
+// interception are established before subsequent modules load.
+// ==========================================================================
+
+// Events & Debug
+export { dispatch, dispatchCancelable, requestData, setDebugSink, setPersistSink, hasActiveDebug, isDevMode } from './events.js';
+
+// DOM & Target Predicates
+export { guardBody, isVisible, shouldIgnoreClick, isEditableTarget, isTargetDisabled, isUsableTarget, shouldInterceptLink, readValue } from './dom.js';
+
+// Form Utilities
+export { resolveFormMethod, serializeForm, populateForm, interceptValueProperty } from './form.js';
+
+// HTTP & Data Mappers
+export { buildUrl, getHeaders, parseHeaders, registerDataMapper, getDataMapper } from './http.js';
+
+// Locale & i18n
+export { getLocale, ensureLocaleObserver, registerLocaleFallback, getLocaleFallback } from './locale.js';
+
+// Templates & DOM Fill
+export { cloneTemplate, cloneTemplateScoped, fill, lnFill, fillTemplate, renderList, buildDict } from './template.js';
+
+// Lifecycle & Kernel Registration
+export { findElements, holdInit, releaseInit, pendingCount, queueBoot, observeAttributes, registerComponent } from './lifecycle.js';
+
+// Value Comparison Primitives (re-exported from compare.js for backward compatibility)
+export { compareValues, detectValueType } from './compare.js';