@livenetworks/ashlar 1.5.1 → 1.6.0

package/js/ln-date/src/ln-date.js

@@ -1,4 +1,4 @@
-import { dispatch, getLocale, registerComponent, interceptValueProperty } from '../../ln-core';
+import { dispatch, getLocale, registerComponent, interceptValueProperty, getLocaleFallback, registerLocaleFallback, buildDict } from '../../ln-core';
 
 (function () {
 	const DOM_SELECTOR = 'data-ln-date';
@@ -50,11 +50,30 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 		const hours = date.getHours();
 		const minutes = date.getMinutes();
 
+		let mmmmVal, mmmVal;
+		const fallback = getLocaleFallback(locale);
+		const langPrefix = (locale || '').toLowerCase().split('-')[0];
+		const formatter = _getFormatter(locale, { month: 'long' });
+		const resolvedLocale = formatter.resolvedOptions().locale.toLowerCase().split('-')[0];
+		const isFallbackNeeded = fallback && resolvedLocale !== langPrefix;
+
+		if (isFallbackNeeded && fallback.monthsLong) {
+			mmmmVal = fallback.monthsLong[month];
+		} else {
+			mmmmVal = _getFormatter(locale, { month: 'long' }).format(date);
+		}
+
+		if (isFallbackNeeded && fallback.monthsShort) {
+			mmmVal = fallback.monthsShort[month];
+		} else {
+			mmmVal = _getFormatter(locale, { month: 'short' }).format(date);
+		}
+
 		const tokens = {
 			'yyyy': String(year),
 			'yy':   String(year).slice(-2),
-			'MMMM': _getFormatter(locale, { month: 'long' }).format(date),
-			'MMM':  _getFormatter(locale, { month: 'short' }).format(date),
+			'MMMM': mmmmVal,
+			'MMM':  mmmVal,
 			'MM':   String(month + 1).padStart(2, '0'),
 			'M':    String(month + 1),
 			'dd':   String(day).padStart(2, '0'),
@@ -71,29 +90,158 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 	function _formatDate(date, format, locale) {
 		const intlOptions = _getIntlOptions(format);
 		if (intlOptions) {
-			return _getFormatter(locale, intlOptions).format(date);
+			const formatter = _getFormatter(locale, intlOptions);
+			const langPrefix = (locale || '').toLowerCase().split('-')[0];
+			const resolvedLocale = formatter.resolvedOptions().locale.toLowerCase().split('-')[0];
+			const fallback = getLocaleFallback(locale);
+
+			if (fallback && resolvedLocale !== langPrefix) {
+				return _formatCustom(date, 'dd.MM.yyyy', locale);
+			}
+			return formatter.format(date);
 		}
 		return _formatCustom(date, format, locale);
 	}
 
+	// ─── Component Helpers ────────────────────────────────────
+
+	function _toISO(date) {
+		if (!date) 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;
+	}
+
+	function _notifyChange(self, iso, date) {
+		dispatch(self.dom, 'ln-date:change', {
+			value: iso,
+			formatted: self.dom.value,
+			date: date
+		});
+		self.dom.dispatchEvent(new Event('change', { bubbles: true }));
+	}
+
+	function _updateState(self, iso, date, formattedText) {
+		self._setHiddenRaw(iso);
+		_inputValueDesc.set.call(self._picker, iso);
+		self._lastISO = iso;
+		if (formattedText !== undefined) {
+			self._isFormatting = true;
+			self.dom.value = formattedText;
+			self._isFormatting = false;
+		} else if (date) {
+			self._displayFormatted(date);
+		}
+		_notifyChange(self, iso, date);
+	}
+
+	function _clearState(self) {
+		self._setHiddenRaw('');
+		_inputValueDesc.set.call(self._picker, '');
+		self._isFormatting = true;
+		self.dom.value = '';
+		self._isFormatting = false;
+		self._lastISO = '';
+		_notifyChange(self, '', null);
+	}
+
 	// ─── Component ────────────────────────────────────────────
 
-	function _component(dom) {
-		if (dom.tagName !== 'INPUT') {
-			console.warn('[ln-date] Can only be applied to <input>, got:', dom.tagName);
-			return this;
+	// ─── Component ────────────────────────────────────────────
+
+	_component.prototype._initTextElement = function () {
+		const dom = this.dom;
+		let valAttr = dom.getAttribute('data-ln-value');
+		let dateAttr = dom.getAttribute('data-ln-date');
+		let datetimeAttr = dom.getAttribute('datetime');
+
+		let candidate = null;
+		if (valAttr !== null && valAttr !== '') {
+			candidate = valAttr;
+		} else if (datetimeAttr !== null && datetimeAttr !== '') {
+			candidate = datetimeAttr;
+		} else if (dateAttr !== null && dateAttr !== '' && dateAttr !== 'true' && !KEYWORD_RE.test(dateAttr)) {
+			candidate = dateAttr;
+		} else {
+			candidate = dom.textContent.trim();
+		}
+
+		let date = _parseISO(candidate) || _parseTyped(candidate);
+		if (!date && candidate) {
+			if (!isNaN(candidate)) {
+				const num = Number(candidate);
+				date = new Date(num > 1e11 ? num : num * 1000);
+			} else {
+				date = new Date(candidate);
+			}
+		}
+		if (date && !isNaN(date.getTime())) {
+			const iso = _toISO(date);
+			this._rawValue = iso;
+			if (!dom.hasAttribute('data-ln-value')) {
+				dom.setAttribute('data-ln-value', iso);
+			}
+			this._formatTextContent();
+		} else {
+			this._rawValue = null;
+		}
+	};
+
+	_component.prototype._formatTextContent = function () {
+		if (this._rawValue) {
+			const date = _parseISO(this._rawValue);
+			if (date) {
+				const formatAttr = this.dom.getAttribute('data-ln-date-format');
+				let format = formatAttr;
+				if (!format) {
+					const dateAttr = this.dom.getAttribute('data-ln-date');
+					if (dateAttr && KEYWORD_RE.test(dateAttr)) {
+						format = dateAttr;
+					}
+				}
+				const locale = getLocale(this.dom);
+				this.dom.textContent = _formatDate(date, format || 'medium', locale);
+			}
 		}
+	};
 
+	function _component(dom) {
 		if (dom[DOM_ATTRIBUTE]) return dom[DOM_ATTRIBUTE];
 		dom[DOM_ATTRIBUTE] = this;
 
 		this.dom = dom;
+
+		if (dom.tagName !== 'INPUT') {
+			this.isTextElement = true;
+			this._initTextElement();
+			return this;
+		}
+
+		this.isTextElement = false;
 		const self = this;
 
 		// ── Read initial state ──────────────────────────────
-		const initialValue = dom.value; // ISO string (YYYY-MM-DD) or empty
+		const initialValue = dom.value;
 		const name = dom.name;
 
+		// Check for declarative HTML dictionary nearby
+		const container = dom.closest('.form-element, form') || dom.parentNode;
+		const dictEls = container.querySelectorAll('[data-ln-date-dict]');
+		for (let i = 0; i < dictEls.length; i++) {
+			const lang = dictEls[i].getAttribute('data-ln-date-dict');
+			if (lang) {
+				const dictData = buildDict(dictEls[i], 'data-ln-date-dict-key');
+				if (dictData['months-long']) {
+					dictData.monthsLong = dictData['months-long'].split(',').map(s => s.trim());
+				}
+				if (dictData['months-short']) {
+					dictData.monthsShort = dictData['months-short'].split(',').map(s => s.trim());
+				}
+				registerLocaleFallback(lang, dictData);
+			}
+		}
+
 		// ── Wrap field: replace dom with <span data-ln-date-field> and move dom inside ──
 		const wrapper = document.createElement('span');
 		wrapper.setAttribute('data-ln-date-field', '');
@@ -106,6 +254,9 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 		hidden.type = 'hidden';
 		hidden.name = name;
 		dom.removeAttribute('name');
+		if (dom.hasAttribute('data-ln-fill-as')) {
+			hidden.setAttribute('data-ln-fill-as', dom.getAttribute('data-ln-fill-as'));
+		}
 		dom.insertAdjacentElement('afterend', hidden);
 		this._hidden = hidden;
 
@@ -123,13 +274,13 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 		// ── Create calendar button ──────────────────────────
 		const btn = document.createElement('button');
 		btn.type = 'button';
-		btn.setAttribute('aria-label', 'Open date picker');
-		btn.innerHTML = '<svg class="ln-icon" aria-hidden="true"><use href="#ln-calendar"></use></svg>';
+		btn.setAttribute('aria-label', dom.getAttribute('data-ln-date-label') || 'Open date picker');
+		btn.innerHTML = '<svg class="ln-icon" aria-hidden="true"><use href="#ln-icon-calendar"></use></svg>';
 		picker.insertAdjacentElement('afterend', btn);
 		this._btn = btn;
 		this._lastISO = '';
 
-		// ── Intercept programmatic value sets on hidden input
+		// ── Intercept programmatic value sets on hidden input ──
 		Object.defineProperty(hidden, 'value', {
 			get: function () {
 				return _inputValueDesc.get.call(hidden);
@@ -138,27 +289,9 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 				_inputValueDesc.set.call(hidden, val);
 				if (val && val !== '') {
 					const date = _parseISO(val);
-					if (date) {
-						self._displayFormatted(date);
-						_inputValueDesc.set.call(picker, val);
-						self._lastISO = val;
-						dispatch(self.dom, 'ln-date:change', {
-							value: val,
-							formatted: self.dom.value,
-							date: date
-						});
-						self.dom.dispatchEvent(new Event('change', { bubbles: true }));
-					}
+					if (date) _updateState(self, val, date);
 				} else if (val === '') {
-					self.dom.value = '';
-					_inputValueDesc.set.call(picker, '');
-					self._lastISO = '';
-					dispatch(self.dom, 'ln-date:change', {
-						value: '',
-						formatted: '',
-						date: null
-					});
-					self.dom.dispatchEvent(new Event('change', { bubbles: true }));
+					_clearState(self);
 				}
 			}
 		});
@@ -175,84 +308,34 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 				}
 				if (!val || val === '') {
 					originalSet('');
-					self._setHiddenRaw('');
-					_inputValueDesc.set.call(self._picker, '');
-					self._lastISO = '';
-					dispatch(dom, 'ln-date:change', {
-						value: '',
-						formatted: '',
-						date: null
-					});
-					dom.dispatchEvent(new Event('change', { bubbles: true }));
+					_clearState(self);
 					return;
 				}
 
-				// Programmatic value could be an ISO string (YYYY-MM-DD) or a formatted date string
-				let date = _parseISO(val);
-				if (!date) {
-					date = _parseTyped(val);
-				}
+				const date = _parseISO(val) || _parseTyped(val);
 
 				if (date) {
-					const y = date.getFullYear();
-					const m = String(date.getMonth() + 1).padStart(2, '0');
-					const d = String(date.getDate()).padStart(2, '0');
-					const iso = y + '-' + m + '-' + d;
-
-					self._setHiddenRaw(iso);
-					_inputValueDesc.set.call(self._picker, iso);
-					self._lastISO = iso;
-
+					const iso = _toISO(date);
 					const format = dom.getAttribute(DOM_SELECTOR) || '';
 					const locale = getLocale(dom);
 					const formatted = _formatDate(date, format, locale);
 					originalSet(formatted);
-
-					dispatch(dom, 'ln-date:change', {
-						value: iso,
-						formatted: formatted,
-						date: date
-					});
-					dom.dispatchEvent(new Event('change', { bubbles: true }));
+					_updateState(self, iso, date, formatted);
 				} else {
 					originalSet(String(val));
-					self._setHiddenRaw('');
-					_inputValueDesc.set.call(self._picker, '');
-					self._lastISO = '';
-					dispatch(dom, 'ln-date:change', {
-						value: '',
-						formatted: String(val),
-						date: null
-					});
-					dom.dispatchEvent(new Event('change', { bubbles: true }));
+					_clearState(self);
 				}
 			}
 		});
 
 		// ── Bind events ─────────────────────────────────────
 		this._onPickerChange = function () {
-			const val = picker.value; // ISO YYYY-MM-DD
+			const val = picker.value;
 			if (val) {
 				const date = _parseISO(val);
-				if (date) {
-					self._setHiddenRaw(val);
-					self._displayFormatted(date);
-					self._lastISO = val;
-					dispatch(self.dom, 'ln-date:change', {
-						value: val,
-						formatted: self.dom.value,
-						date: date
-					});
-				}
+				if (date) _updateState(self, val, date);
 			} else {
-				self._setHiddenRaw('');
-				self.dom.value = '';
-				self._lastISO = '';
-				dispatch(self.dom, 'ln-date:change', {
-					value: '',
-					formatted: '',
-					date: null
-				});
+				_clearState(self);
 			}
 		};
 		picker.addEventListener('change', this._onPickerChange);
@@ -260,51 +343,25 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 		this._onBlur = function () {
 			const typed = self.dom.value.trim();
 
-			// Empty input — clear if there was a value
 			if (typed === '') {
-				if (self._lastISO !== '') {
-					self._setHiddenRaw('');
-					_inputValueDesc.set.call(self._picker, '');
-					self.dom.value = '';
-					self._lastISO = '';
-					dispatch(self.dom, 'ln-date:change', {
-						value: '',
-						formatted: '',
-						date: null
-					});
-				}
+				if (self._lastISO !== '') _clearState(self);
 				return;
 			}
 
-			// Check if text is unchanged from current formatted display
 			if (self._lastISO) {
 				const currentDate = _parseISO(self._lastISO);
 				if (currentDate) {
 					const format = self.dom.getAttribute(DOM_SELECTOR) || '';
 					const locale = getLocale(self.dom);
-					const currentFormatted = _formatDate(currentDate, format, locale);
-					if (typed === currentFormatted) return;
+					if (typed === _formatDate(currentDate, format, locale)) return;
 				}
 			}
 
-			// Try to parse the typed value
 			const parsed = _parseTyped(typed);
 			if (parsed) {
-				const y = parsed.getFullYear();
-				const m = String(parsed.getMonth() + 1).padStart(2, '0');
-				const d = String(parsed.getDate()).padStart(2, '0');
-				const iso = y + '-' + m + '-' + d;
-				self._setHiddenRaw(iso);
-				_inputValueDesc.set.call(self._picker, iso);
-				self._displayFormatted(parsed);
-				self._lastISO = iso;
-				dispatch(self.dom, 'ln-date:change', {
-					value: iso,
-					formatted: self.dom.value,
-					date: parsed
-				});
+				const iso = _toISO(parsed);
+				_updateState(self, iso, parsed);
 			} else {
-				// Invalid input — revert to previous display
 				if (self._lastISO) {
 					const prevDate = _parseISO(self._lastISO);
 					if (prevDate) self._displayFormatted(prevDate);
@@ -323,27 +380,15 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 		// ── Handle pre-filled value ─────────────────────────
 		if (initialValue && initialValue !== '') {
 			const date = _parseISO(initialValue);
-			if (date) {
-				this._setHiddenRaw(initialValue);
-				_inputValueDesc.set.call(picker, initialValue);
-				this._displayFormatted(date);
-				this._lastISO = initialValue;
-				dispatch(dom, 'ln-date:change', {
-					value: initialValue,
-					formatted: dom.value,
-					date: date
-				});
-				dom.dispatchEvent(new Event('change', { bubbles: true }));
-			}
+			if (date) _updateState(self, initialValue, date);
 		}
 
 		return this;
 	}
 
-	// ─── Helpers ──────────────────────────────────────────────
+	// ─── Parsing Helpers ──────────────────────────────────────
 
 	function _parseISO(str) {
-		// Parse YYYY-MM-DD (and optionally YYYY-MM-DDTHH:mm)
 		if (!str || typeof str !== 'string') return null;
 		const parts = str.split('T');
 		const dateParts = parts[0].split('-');
@@ -359,7 +404,6 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 			min = parseInt(timeParts[1], 10) || 0;
 		}
 		const date = new Date(y, m, d, h, min);
-		// Validate the date is real (e.g., Feb 30 would roll over)
 		if (date.getFullYear() !== y || date.getMonth() !== m || date.getDate() !== d) return null;
 		return date;
 	}
@@ -367,19 +411,15 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 	function _parseTyped(str) {
 		if (!str || typeof str !== 'string') return null;
 		str = str.trim();
-		if (str.length < 6) return null; // minimum: d.M.yy
+		if (str.length < 6) return null;
 
-		// Detect separator
 		let sep, parts;
 		if (str.indexOf('.') !== -1) {
-			sep = '.';
-			parts = str.split('.');
+			sep = '.'; parts = str.split('.');
 		} else if (str.indexOf('/') !== -1) {
-			sep = '/';
-			parts = str.split('/');
+			sep = '/'; parts = str.split('/');
 		} else if (str.indexOf('-') !== -1) {
-			sep = '-';
-			parts = str.split('-');
+			sep = '-'; parts = str.split('-');
 		} else {
 			return null;
 		}
@@ -393,15 +433,11 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 		}
 
 		let day, month, year;
-
 		if (sep === '.') {
-			// dd.MM.yyyy (European)
 			day = nums[0]; month = nums[1]; year = nums[2];
 		} else if (sep === '/') {
-			// MM/dd/yyyy (US)
 			month = nums[0]; day = nums[1]; year = nums[2];
 		} else {
-			// dash: yyyy-MM-dd if first part is 4 digits, else dd-MM-yyyy
 			if (parts[0].length === 4) {
 				year = nums[0]; month = nums[1]; day = nums[2];
 			} else {
@@ -409,12 +445,10 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 			}
 		}
 
-		// Two-digit year pivot
 		if (year < 100) {
 			year += (year < 50) ? 2000 : 1900;
 		}
 
-		// Validate via Date constructor roundtrip
 		const date = new Date(year, month - 1, day);
 		if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) {
 			return null;
@@ -427,7 +461,6 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 			try {
 				this._picker.showPicker();
 			} catch (e) {
-				// showPicker() can throw if not triggered by user gesture
 				this._picker.click();
 			}
 		} else {
@@ -451,27 +484,34 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 
 	Object.defineProperty(_component.prototype, 'value', {
 		get: function () {
+			if (this.isTextElement) {
+				return this._rawValue || '';
+			}
 			return _inputValueDesc.get.call(this._hidden);
 		},
 		set: function (isoStr) {
+			if (this.isTextElement) {
+				if (!isoStr || isoStr === '') {
+					this._rawValue = null;
+					this.dom.removeAttribute('data-ln-value');
+					this.dom.textContent = '';
+					return;
+				}
+				const date = _parseISO(isoStr) || _parseTyped(isoStr);
+				if (!date) return;
+				const iso = _toISO(date);
+				this._rawValue = iso;
+				this.dom.setAttribute('data-ln-value', iso);
+				this._formatTextContent();
+				return;
+			}
 			if (!isoStr || isoStr === '') {
-				this._setHiddenRaw('');
-				_inputValueDesc.set.call(this._picker, '');
-				this.dom.value = '';
-				this._lastISO = '';
+				_clearState(this);
 				return;
 			}
 			const date = _parseISO(isoStr);
 			if (!date) return;
-			this._setHiddenRaw(isoStr);
-			_inputValueDesc.set.call(this._picker, isoStr);
-			this._displayFormatted(date);
-			this._lastISO = isoStr;
-			dispatch(this.dom, 'ln-date:change', {
-				value: isoStr,
-				formatted: this.dom.value,
-				date: date
-			});
+			_updateState(this, isoStr, date);
 		}
 	});
 
@@ -486,38 +526,40 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 				this.value = '';
 				return;
 			}
-			const y = dateObj.getFullYear();
-			const m = String(dateObj.getMonth() + 1).padStart(2, '0');
-			const d = String(dateObj.getDate()).padStart(2, '0');
-			this.value = y + '-' + m + '-' + d;
+			this.value = _toISO(dateObj);
 		}
 	});
 
 	Object.defineProperty(_component.prototype, 'formatted', {
 		get: function () {
+			if (this.isTextElement) {
+				return this.dom.textContent;
+			}
 			return this.dom.value;
 		}
 	});
 
 	_component.prototype.destroy = function () {
 		if (!this.dom[DOM_ATTRIBUTE]) return;
+		if (this.isTextElement) {
+			dispatch(this.dom, 'ln-date:destroyed', { target: this.dom });
+			delete this.dom[DOM_ATTRIBUTE];
+			return;
+		}
 		this._picker.removeEventListener('change', this._onPickerChange);
 		this.dom.removeEventListener('blur', this._onBlur);
 		this._btn.removeEventListener('click', this._onBtnClick);
-		// Restore original input
-		this.dom.name = this._hidden.name;
-		this.dom.type = 'date';
 		const isoVal = this.value;
-		// Remove created elements
 		this._hidden.remove();
 		this._picker.remove();
 		this._btn.remove();
-		// Unwrap: move dom back out and drop the wrapper
 		if (this._wrapper && this._wrapper.parentNode) {
 			this._wrapper.parentNode.insertBefore(this.dom, this._wrapper);
 			this._wrapper.remove();
 		}
-		// Restore value
+		delete this.dom.value;
+		this.dom.name = this._hidden.name;
+		this.dom.type = 'date';
 		if (isoVal) this.dom.value = isoVal;
 		dispatch(this.dom, 'ln-date:destroyed', { target: this.dom });
 		delete this.dom[DOM_ATTRIBUTE];
@@ -530,16 +572,32 @@ import { dispatch, getLocale, registerComponent, interceptValueProperty } from '
 			const els = document.querySelectorAll('[' + DOM_SELECTOR + ']');
 			for (let i = 0; i < els.length; i++) {
 				const inst = els[i][DOM_ATTRIBUTE];
-				if (inst && inst.value) {
-					const date = _parseISO(inst.value);
-					if (date) inst._displayFormatted(date);
+				if (inst) {
+					if (inst.isTextElement) {
+						inst._formatTextContent();
+					} else if (inst.value) {
+						const date = _parseISO(inst.value);
+						if (date) inst._displayFormatted(date);
+					}
 				}
 			}
-		}).observe(document.documentElement, { attributes: true, attributeFilter: ['lang'] });
+		}).observe(document.documentElement, { attributes: true, attributeFilter: ['lang'], subtree: true });
 	}
 
 	// ─── Init ─────────────────────────────────────────────────
 
-	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-date');
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-date', {
+		extraAttributes: ['data-ln-date-format', 'data-ln-date-locale', 'data-ln-value', 'datetime', 'lang'],
+		onAttributeChange: function (el) {
+			const inst = el[DOM_ATTRIBUTE];
+			if (!inst) return;
+			if (inst.isTextElement) {
+				inst._initTextElement();
+			} else if (inst.value) {
+				const date = _parseISO(inst.value);
+				if (date) inst._displayFormatted(date);
+			}
+		}
+	});
 	_localeObserver();
 })();

package/js/ln-debug/README.md

@@ -0,0 +1,58 @@
+# ln-debug
+
+> The diagnostic component of `ln-ashlar` that enables verbose developer warnings in console logs during development.
+
+---
+
+## 1. Philosophy
+
+In production, libraries should remain silent and not pollute the browser console with developer-oriented warnings (such as template mismatch warnings or missing configuration parameters). 
+
+The `ln-debug` component solves this by acting as a global switch:
+- When active, all core validation warnings (prefixed with `[ln-` or `[lnCore`) are enabled.
+- When inactive, these developer warnings are safely suppressed, maintaining a clean production log.
+
+---
+
+## 2. Minimal Blueprint
+
+Add the `data-ln-debug` attribute to either the `<html>` or `<body>` element (or any element in the document) to enable debug logs:
+
+```html
+<!DOCTYPE html>
+<html lang="en" data-ln-debug>
+<head>
+    <script src="dist/ln-ashlar.iife.js" defer></script>
+</head>
+<body>
+    <!-- Warnings will be visible in the developer console -->
+</body>
+</html>
+```
+
+---
+
+## 3. DOM & State Management
+
+This component lives entirely at the level of the DOM. The single source of truth is the presence of the `data-ln-debug` attribute on `<html>` or `<body>`.
+
+### Checking the State via JS
+
+To check if debug mode is active in your scripts, query the DOM directly:
+
+```javascript
+const isDebug = document.documentElement.hasAttribute('data-ln-debug') || 
+                (document.body && document.body.hasAttribute('data-ln-debug'));
+```
+
+### Toggling the State
+
+To toggle debug mode at runtime, add or remove the attribute from the DOM:
+
+```javascript
+// Enable
+document.documentElement.setAttribute('data-ln-debug', '');
+
+// Disable
+document.documentElement.removeAttribute('data-ln-debug');
+```