@livenetworks/ashlar 1.6.0 → 2.0.0

package/components/ln-core/attrs.js

@@ -0,0 +1,273 @@
+// ─── Typed Live Attribute Readers ──────────────────────────
+//
+// Scanner constraint: attribute names passed into these readers, and into a
+// `defineAttrs` spec, must always be inline string literals or a `const`
+// bound to a literal — never concatenated or templated.
+// `scripts/sync-ln-schemas.mjs:22-23` is a raw regex over file text; a
+// constructed name is invisible to it and the CI docs gate breaks silently
+// (this already happened once — commit `3495690`).
+
+export function attrStr(el, name, fallback) {
+	const raw = el.getAttribute(name);
+	return raw === null ? fallback : raw;
+}
+
+// `0` stays `0` — unlike the `parseInt(...) || 1000` idiom this replaces.
+export function attrInt(el, name, fallback) {
+	const parsed = parseInt(el.getAttribute(name), 10);
+	return isNaN(parsed) ? fallback : parsed;
+}
+
+export function attrBool(el, name, fallback = false) {
+	const raw = el.getAttribute(name);
+	if (raw === null) return !!fallback;
+	const val = raw.trim().toLowerCase();
+	if (val === 'false' || val === '0') return false;
+	return true;
+}
+
+// Allocates a new array per read — do not call inside a per-row loop.
+export function attrList(el, name) {
+	return (el.getAttribute(name) || '').split(',').map(s => s.trim()).filter(Boolean);
+}
+
+const _enumReaderCache = new Map();
+
+/**
+ * Cached reader factory for enum attributes.
+ * @param {string[]} values - allowed values
+ * @param {*} fallback - default value
+ * @returns {function(Element, string): *}
+ */
+export function attrEnum(values, fallback) {
+	const key = (values ? values.join('|') : '') + '::' + fallback;
+	if (_enumReaderCache.has(key)) return _enumReaderCache.get(key);
+	const valSet = new Set(values || []);
+	const reader = function (el, name) {
+		const raw = el.getAttribute(name);
+		return (raw !== null && valSet.has(raw)) ? raw : fallback;
+	};
+	_enumReaderCache.set(key, reader);
+	return reader;
+}
+
+export function attrFloat(el, name, fallback) {
+	const parsed = parseFloat(el.getAttribute(name));
+	return isNaN(parsed) ? fallback : parsed;
+}
+
+export function attrJson(el, name, fallback) {
+	const raw = el.getAttribute(name);
+	if (!raw) return fallback;
+	try {
+		return JSON.parse(raw);
+	} catch (_) {
+		return fallback;
+	}
+}
+
+/**
+ * Validates a DOM attribute value against its declared schema entry.
+ * Logs a console.warn (with [componentTag] prefix) if the value is invalid.
+ *
+ * @param {Object} entry - { type, values, min, max, fallback, ... }
+ * @param {string|null} value - raw DOM attribute value (null if absent)
+ * @param {string} attrName - attribute name (e.g. 'data-ln-modal')
+ * @param {string} componentTag - component tag (e.g. 'ln-modal')
+ * @param {Element} [el] - optional DOM element carrying the attribute
+ * @returns {boolean} true if valid, false if invalid
+ */
+export function validateAttrValue(entry, value, attrName, componentTag, el) {
+	if (!entry || value === null) return true;
+	const tag = componentTag || 'ln-component';
+	const type = entry.type;
+
+	// valueless / unconstrained types
+	if (type === 'trigger' || type === 'marker' || type === 'string' || type === 'list' || !type) {
+		return true;
+	}
+
+	// Bare attributes (presence-only in HTML) with a declared fallback resolve to fallback in readers
+	if (value === '' && entry.fallback !== undefined) {
+		return true;
+	}
+
+	const logWarn = (msg) => {
+		if (el) console.warn(msg, el);
+		else console.warn(msg);
+	};
+
+	if (type === 'boolean') {
+		const lower = value.trim().toLowerCase();
+		if (lower !== '' && lower !== 'true' && lower !== 'false' && lower !== '1' && lower !== '0') {
+			logWarn(`[${tag}] Invalid value "${value}" for boolean attribute "${attrName}". Allowed: "true", "false", or presence-only.`);
+			return false;
+		}
+		return true;
+	}
+
+	if (type === 'enum') {
+		const allowed = entry.values || [];
+		if (!allowed.includes(value)) {
+			logWarn(`[${tag}] Invalid value "${value}" for attribute "${attrName}". Allowed: ${allowed.join(', ')}. Fallback: "${entry.fallback}".`);
+			return false;
+		}
+		return true;
+	}
+
+	if (type === 'integer') {
+		if (!/^-?\d+$/.test(value)) {
+			logWarn(`[${tag}] Invalid integer "${value}" for attribute "${attrName}". Fallback: ${entry.fallback}.`);
+			return false;
+		}
+		const num = parseInt(value, 10);
+		if (entry.min !== undefined && num < entry.min) {
+			logWarn(`[${tag}] Value ${num} for attribute "${attrName}" is less than min (${entry.min}).`);
+			return false;
+		}
+		if (entry.max !== undefined && num > entry.max) {
+			logWarn(`[${tag}] Value ${num} for attribute "${attrName}" is greater than max (${entry.max}).`);
+			return false;
+		}
+		return true;
+	}
+
+	if (type === 'float') {
+		if (isNaN(Number(value))) {
+			logWarn(`[${tag}] Invalid float "${value}" for attribute "${attrName}". Fallback: ${entry.fallback}.`);
+			return false;
+		}
+		return true;
+	}
+
+	if (type === 'json') {
+		try {
+			JSON.parse(value);
+			return true;
+		} catch (err) {
+			logWarn(`[${tag}] Invalid JSON for attribute "${attrName}": ${err.message}. Fallback: ${entry.fallback}.`);
+			return false;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * Define live getter-only properties on `instance`, each reading `dom` on
+ * every access. Nothing is copied into instance state, so there is no state
+ * to invalidate and no sync step.
+ *
+ * @param {Object} instance
+ * @param {Element} dom
+ * @param {Object} spec - { propName: [reader, attributeName, fallback] }
+ * @returns {Object} instance
+ */
+export function defineAttrs(instance, dom, spec) {
+	for (const propName in spec) {
+		const [reader, attributeName, fallback] = spec[propName];
+		Object.defineProperty(instance, propName, {
+			// Getter only, no setter — assignment throws in strict mode (ES
+			// modules are strict). Deliberate: it forbids a drifting copy.
+			get: function () {
+				return reader(dom, attributeName, fallback);
+			},
+			enumerable: true,
+			configurable: true
+		});
+	}
+	return instance;
+}
+
+/**
+ * One table per component is the single source of truth for its HOST
+ * attributes. Derivations below read it; nothing else declares an
+ * attribute name.
+ *
+ * Table entry shape:
+ *   'data-ln-x': { prop, read, type, values, fallback, min, max, effect, description } — any subset
+ *
+ * The scanner constraint at the top of this file applies to table KEYS:
+ * literal strings only. A computed key is invisible to
+ * scripts/sync-ln-schemas.mjs.
+ */
+export function attrSpec(table) {
+	const spec = {};
+	for (const name in table) {
+		const entry = table[name];
+		if (!entry || !entry.prop) continue;
+		let reader = entry.read;
+		if (!reader && entry.type) {
+			switch (entry.type) {
+				case 'enum':
+					reader = attrEnum(entry.values, entry.fallback);
+					break;
+				case 'integer':
+					reader = attrInt;
+					break;
+				case 'float':
+					reader = attrFloat;
+					break;
+				case 'boolean':
+					reader = attrBool;
+					break;
+				case 'list':
+					reader = attrList;
+					break;
+				case 'json':
+					reader = attrJson;
+					break;
+				case 'string':
+				default:
+					reader = attrStr;
+					break;
+			}
+		}
+		if (!reader) reader = attrStr;
+		spec[entry.prop] = [reader, name, entry.fallback];
+	}
+	return spec;
+}
+
+export function attrEffects(table) {
+	const effects = {};
+	for (const name in table) {
+		const entry = table[name];
+		if (!entry) continue;
+		if (entry.effect) effects[name] = entry.effect;
+	}
+	// null, not {} — `_registerAttrEntry` tests `entry.onAttrChange || entry.effects`,
+	// and an empty object is truthy. A table of pure getters would otherwise be
+	// pushed into `registry.reactive` and iterated on every data-ln-* mutation
+	// on the page while having nothing to run.
+	return Object.keys(effects).length ? effects : null;
+}
+
+/**
+ * The attribute names a registry entry should be indexed under, so the shared
+ * observer can reach it by name instead of walking every reactive entry.
+ *
+ * Note this reads `entry.effects` — the DERIVED table produced by
+ * `attrEffects` above — not the raw component table. An entry is indexed
+ * under every name it declares, which for a component like `ln-list` means
+ * the suffixed names (`data-ln-list-window`) and not only the selector.
+ *
+ * Internal to ln-core, and deliberately NOT re-exported from index.js: unlike
+ * `attrSpec` / `attrEffects`, which take the attribute table a component author
+ * writes, this takes a registry entry — a shape no author ever constructs.
+ * Publishing it would make the entry shape semver-load-bearing for no caller.
+ *
+ * @param {Object} entry - a registry entry: { effects, onAttrChange, declared }
+ * @returns {Set<string>|null} names to index under, or null for a wildcard —
+ *   `onAttrChange` without `declared` asks for EVERY data-ln-* mutation and
+ *   by definition cannot be keyed by name.
+ */
+export function reactiveNames(entry) {
+	if (entry.onAttrChange && !entry.declared) return null;
+
+	const names = new Set();
+	if (entry.effects) for (const n in entry.effects) names.add(n);
+	if (entry.onAttrChange && entry.declared) for (const n of entry.declared) names.add(n);
+	return names;
+}
+

package/components/ln-core/compare.js

@@ -0,0 +1,40 @@
+/**
+ * Detect the comparison type for a column/field from its current value set.
+ * Type is locked ONCE per sort operation (not per pair) — comparing types
+ * per-pair breaks comparator transitivity and produces wrong ordering.
+ * All non-empty values must be finite numbers for 'number'; otherwise 'string'.
+ * @param {Array<unknown>} values
+ * @returns {'number' | 'string'}
+ */
+export function detectValueType(values) {
+	let hasValue = false;
+	for (let i = 0; i < values.length; i++) {
+		const v = values[i];
+		if (v === '' || v == null) continue;
+		hasValue = true;
+		if (!Number.isFinite(Number(v))) return 'string';
+	}
+	return hasValue ? 'number' : 'string';
+}
+
+/**
+ * Compare two raw values given a pre-locked type (see detectValueType).
+ * Pass an Intl.Collator instance for locale-aware string comparison —
+ * built once by the caller outside the sort loop, never per pair.
+ * @param {unknown} a
+ * @param {unknown} b
+ * @param {'number' | 'string'} type
+ * @param {Intl.Collator|null} [collator]
+ * @returns {number}
+ */
+export function compareValues(a, b, type, collator) {
+	if (type === 'number') {
+		const na = parseFloat(a);
+		const nb = parseFloat(b);
+		return (isNaN(na) ? 0 : na) - (isNaN(nb) ? 0 : nb);
+	}
+	const strA = a != null ? String(a) : '';
+	const strB = b != null ? String(b) : '';
+	if (collator) return collator.compare(strA, strB);
+	return strA < strB ? -1 : strA > strB ? 1 : 0;
+}

package/components/ln-core/crypto.js

@@ -0,0 +1,265 @@
+// Web Crypto API Reusable Cryptographic Helpers
+let _cryptoKey = null;
+
+const DEFAULT_SALT = 'ln-ashlar:storage-salt:v1';
+const CHUNK_SIZE = 0x8000; // 32KB chunks for stack-safe Base64 conversion
+
+/**
+ * Encodes a Uint8Array to a Base64 string in chunks to prevent call-stack overflow on large payloads.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function uint8ToBase64(bytes) {
+	let binary = '';
+	const len = bytes.byteLength;
+	for (let i = 0; i < len; i += CHUNK_SIZE) {
+		binary += String.fromCharCode.apply(
+			null,
+			bytes.subarray(i, Math.min(i + CHUNK_SIZE, len))
+		);
+	}
+	return btoa(binary);
+}
+
+/**
+ * Decodes a Base64 string to a Uint8Array.
+ * @param {string} base64
+ * @returns {Uint8Array}
+ */
+export function base64ToUint8(base64) {
+	const binary = atob(base64);
+	const len = binary.length;
+	const bytes = new Uint8Array(len);
+	for (let i = 0; i < len; i++) {
+		bytes[i] = binary.charCodeAt(i);
+	}
+	return bytes;
+}
+
+/**
+ * Resolves key and options from overloaded arguments.
+ * Ensures an options object like { silent: true } is never passed to WebCrypto as a CryptoKey.
+ * @private
+ */
+function _resolveKeyAndOptions(keyOrOptions, maybeOptions) {
+	let key = _cryptoKey;
+	let options = {};
+
+	if (typeof CryptoKey !== 'undefined' && keyOrOptions instanceof CryptoKey) {
+		key = keyOrOptions;
+		if (maybeOptions && typeof maybeOptions === 'object') {
+			options = maybeOptions;
+		}
+	} else if (keyOrOptions && typeof keyOrOptions === 'object') {
+		options = keyOrOptions;
+		if (typeof CryptoKey !== 'undefined' && options.key instanceof CryptoKey) {
+			key = options.key;
+		}
+	}
+
+	return { key, options };
+}
+
+/**
+ * Derives a 256-bit AES-GCM CryptoKey using PBKDF2 or SHA-256.
+ * @param {string} secretString
+ * @param {Object} [options]
+ * @param {'pbkdf2'|'sha256'} [options.method='pbkdf2']
+ * @param {string|Uint8Array} [options.salt]
+ * @param {number} [options.iterations=100000]
+ * @returns {Promise<CryptoKey>}
+ */
+export async function deriveCryptoKey(secretString, options = {}) {
+	if (!secretString) {
+		throw new Error('[ln-crypto] Key derivation failed: Secret string is required');
+	}
+
+	const method = options.method || 'pbkdf2';
+	const enc = new TextEncoder();
+
+	if (method === 'sha256') {
+		const hash = await crypto.subtle.digest('SHA-256', enc.encode(secretString));
+		return crypto.subtle.importKey(
+			'raw',
+			hash,
+			{ name: 'AES-GCM' },
+			false,
+			['encrypt', 'decrypt']
+		);
+	}
+
+	// PBKDF2 mode
+	const saltStr = options.salt || DEFAULT_SALT;
+	const salt = typeof saltStr === 'string' ? enc.encode(saltStr) : saltStr;
+	const iterations = options.iterations || 100000;
+
+	const baseKey = await crypto.subtle.importKey(
+		'raw',
+		enc.encode(secretString),
+		'PBKDF2',
+		false,
+		['deriveKey']
+	);
+
+	return crypto.subtle.deriveKey(
+		{
+			name: 'PBKDF2',
+			salt,
+			iterations,
+			hash: 'SHA-256'
+		},
+		baseKey,
+		{ name: 'AES-GCM', length: 256 },
+		false,
+		['encrypt', 'decrypt']
+	);
+}
+
+/**
+ * Sets the active cryptographic key in module memory.
+ * Default method is 'sha256' for backward-compatibility with existing at-rest storage caches.
+ * Pass { method: 'pbkdf2' } to use PBKDF2.
+ * Passing empty/falsy clears the key.
+ * @param {string|null} secretString
+ * @param {Object} [options]
+ * @returns {Promise<void>}
+ */
+export async function setCryptoKey(secretString, options = {}) {
+	if (!secretString) {
+		_cryptoKey = null;
+		return;
+	}
+
+	try {
+		// Default to sha256 when called as setCryptoKey('secret') for backward compatibility
+		const method = options.method || 'sha256';
+		_cryptoKey = await deriveCryptoKey(secretString, { ...options, method });
+	} catch (err) {
+		console.error('[ln-core/crypto] Key derivation failed:', err);
+		_cryptoKey = null;
+		throw err;
+	}
+}
+
+/**
+ * Returns the currently active CryptoKey in module memory.
+ * @returns {CryptoKey|null}
+ */
+export function getCryptoKey() {
+	return _cryptoKey;
+}
+
+/**
+ * Clears the active cryptographic key in module memory.
+ */
+export function clearCryptoKey() {
+	_cryptoKey = null;
+}
+
+/**
+ * Checks if an active cryptographic key is set.
+ * @returns {boolean}
+ */
+export function hasCryptoKey() {
+	return _cryptoKey !== null;
+}
+
+/**
+ * Encrypts arbitrary data using AES-GCM (256-bit).
+ * Fail-closed: Throws an Error if no active key is provided or if encryption fails.
+ * @param {any} plainData
+ * @param {CryptoKey|Object} [keyOrOptions]
+ * @param {Object} [maybeOptions]
+ * @returns {Promise<Object>} Version 1 envelope: { v: 1, alg: 'AES-GCM', encrypted: true, iv, data }
+ */
+export async function encryptData(plainData, keyOrOptions, maybeOptions) {
+	const { key } = _resolveKeyAndOptions(keyOrOptions, maybeOptions);
+
+	if (plainData === undefined || plainData === null) {
+		return plainData;
+	}
+
+	if (!key) {
+		throw new Error('[ln-crypto] Encryption failed: No active cryptographic key provided');
+	}
+
+	try {
+		const enc = new TextEncoder();
+		const iv = crypto.getRandomValues(new Uint8Array(12));
+
+		const serialized = typeof plainData === 'string' ? plainData : JSON.stringify(plainData);
+		const encryptedBuffer = await crypto.subtle.encrypt(
+			{ name: 'AES-GCM', iv },
+			key,
+			enc.encode(serialized)
+		);
+
+		return {
+			v: 1,
+			alg: 'AES-GCM',
+			encrypted: true,
+			iv: uint8ToBase64(iv),
+			data: uint8ToBase64(new Uint8Array(encryptedBuffer))
+		};
+	} catch (err) {
+		console.error('[ln-core/crypto] Encryption failed:', err);
+		throw new Error('[ln-crypto] Encryption failed: ' + (err && err.message ? err.message : String(err)));
+	}
+}
+
+/**
+ * Decrypts an encrypted envelope using AES-GCM (256-bit).
+ * Fail-closed: Throws an Error if key is missing or decryption fails, unless { silent: true } is passed.
+ * Backwards compatible: Decrypts both v1 envelopes and legacy unversioned { encrypted: true, iv, data } payloads.
+ * @param {Object} encryptedObject
+ * @param {CryptoKey|Object} [keyOrOptions]
+ * @param {Object} [maybeOptions]
+ * @returns {Promise<any>}
+ */
+export async function decryptData(encryptedObject, keyOrOptions, maybeOptions) {
+	const { key, options } = _resolveKeyAndOptions(keyOrOptions, maybeOptions);
+	const silent = options.silent === true;
+
+	if (!encryptedObject || !encryptedObject.encrypted) {
+		return encryptedObject;
+	}
+
+	if (!key) {
+		if (silent) {
+			return { ...encryptedObject, decryptionError: true };
+		}
+		throw new Error('[ln-crypto] Decryption failed: No active cryptographic key provided');
+	}
+
+	if (!encryptedObject.iv || !encryptedObject.data) {
+		if (silent) {
+			return { ...encryptedObject, decryptionError: true };
+		}
+		throw new Error('[ln-crypto] Decryption failed: Malformed envelope (missing iv or data)');
+	}
+
+	try {
+		const dec = new TextDecoder();
+		const iv = base64ToUint8(encryptedObject.iv);
+		const encryptedBuffer = base64ToUint8(encryptedObject.data);
+
+		const decryptedBuffer = await crypto.subtle.decrypt(
+			{ name: 'AES-GCM', iv },
+			key,
+			encryptedBuffer
+		);
+
+		const decoded = dec.decode(decryptedBuffer);
+		try {
+			return JSON.parse(decoded);
+		} catch (_) {
+			return decoded;
+		}
+	} catch (err) {
+		if (silent) {
+			return { ...encryptedObject, decryptionError: true };
+		}
+		console.error('[ln-core/crypto] Decryption failed. Key may be incorrect or payload tampered:', err);
+		throw new Error('[ln-crypto] Decryption failed. Key may be incorrect or payload tampered: ' + (err && err.message ? err.message : String(err)));
+	}
+}

package/components/ln-core/date.js

@@ -0,0 +1,50 @@
+/**
+ * Parses raw input (Unix seconds, milliseconds, or ISO string) into a Date object.
+ * @param {unknown} raw
+ * @returns {Date|null}
+ */
+export function parseDateInput(raw) {
+	if (raw === null || raw === undefined || raw === '') return null;
+
+	if (raw instanceof Date) {
+		return isNaN(raw.getTime()) ? null : raw;
+	}
+
+	const num = Number(raw);
+	if (!isNaN(num) && num > 0) {
+		// If timestamp is in seconds (< 10^11), convert to ms
+		const ms = num < 1e11 ? num * 1000 : num;
+		const d = new Date(ms);
+		return isNaN(d.getTime()) ? null : d;
+	}
+
+	if (typeof raw === 'string') {
+		const str = raw.trim();
+		if (!str) return null;
+		// Date-only ISO parses as UTC midnight, which reads back as the previous day west of UTC.
+		const ymd = /^(\d{4})-(\d{2})-(\d{2})$/.exec(str);
+		if (ymd) {
+			const year = +ymd[1], month = +ymd[2], day = +ymd[3];
+			const local = new Date(year, month - 1, day);
+			if (local.getFullYear() !== year || local.getMonth() !== month - 1 || local.getDate() !== day) return null;
+			return local;
+		}
+		const d = new Date(str);
+		return isNaN(d.getTime()) ? null : d;
+	}
+
+	return null;
+}
+
+/**
+ * Formats a Date object to an ISO date string (YYYY-MM-DD).
+ * @param {Date} date
+ * @returns {string}
+ */
+export function formatDateToISO(date) {
+	if (!date || !(date instanceof Date) || isNaN(date.getTime())) return '';
+	const y = date.getFullYear();
+	const m = String(date.getMonth() + 1).padStart(2, '0');
+	const d = String(date.getDate()).padStart(2, '0');
+	return y + '-' + m + '-' + d;
+}