@livenetworks/ashlar 1.6.1 → 2.0.0

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

@@ -0,0 +1,486 @@
+import {
+	buildDict,
+	dispatch,
+	ensureLocaleObserver,
+	formatDateToISO,
+	getLocale,
+	getLocaleFallback,
+	interceptValueProperty,
+	parseDateInput,
+	registerComponent,
+	registerLocaleFallback
+} from '../../ln-core';
+
+import {
+	formatDateValue,
+	KEYWORD_RE,
+	parseTypedDate
+} from './date-model.js';
+
+(function () {
+	const DOM_SELECTOR = 'data-ln-date';
+	const DOM_ATTRIBUTE = 'lnDate';
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+	function _syncAttribute(el) {
+		const inst = el[DOM_ATTRIBUTE];
+		if (!inst) return;
+		if (inst.isTextElement) {
+			inst._initTextElement();
+		} else if (inst.value) {
+			const date = parseDateInput(inst.value);
+			if (date) inst._displayFormatted(date);
+		}
+	}
+
+	// ─── Attribute Contract (SSOT) ──────────────────────────
+	const ATTRIBUTES = {
+		'data-ln-date':          { type: 'enum', values: ['short', 'medium', 'long', 'full', 'iso'], fallback: 'medium', effect: _syncAttribute, description: 'Date display style preset or activator' },
+		'data-ln-date-format':   { type: 'string', effect: _syncAttribute, description: 'Custom Intl.DateTimeFormat pattern or options' },
+		'data-ln-date-locale':   { type: 'string', effect: _syncAttribute, description: 'BCP 47 language tag override for date formatting' },
+		'data-ln-value':         { type: 'string', effect: _syncAttribute, description: 'Raw ISO date string or timestamp for non-time elements (td, span)' },
+		'data-ln-date-dict':     { type: 'marker', description: 'Container for date translation dictionary' },
+		'data-ln-date-dict-key': { type: 'string', description: 'Dictionary key for relative time or custom date formatting' },
+		'data-ln-date-field':    { type: 'string', description: 'Field name mapping for date record binding' },
+		'data-ln-date-label':    { type: 'string', description: 'Accessible label text for the date input' }
+	};
+
+	const _inputValueDesc = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value');
+
+	// ─── Component Helpers ────────────────────────────────────
+
+	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 Constructor & Methods ──────────────────────
+
+	function _component(dom) {
+		if (dom[DOM_ATTRIBUTE]) return dom[DOM_ATTRIBUTE];
+		dom[DOM_ATTRIBUTE] = this;
+
+		this.dom = dom;
+		const self = this;
+
+		// Subscribe to global locale changes
+		this._onLocaleChange = function () {
+			if (self.isTextElement) {
+				self._formatTextContent();
+			} else if (self.value) {
+				const date = parseDateInput(self.value);
+				if (date) self._displayFormatted(date);
+			}
+		};
+		ensureLocaleObserver();
+		document.addEventListener('ln-core:locale-change', this._onLocaleChange);
+
+		if (dom.tagName !== 'INPUT') {
+			this.isTextElement = true;
+			this._initTextElement();
+			return this;
+		}
+
+		this.isTextElement = false;
+
+		// Read initial state
+		const initialValue = dom.value;
+		const name = dom.name;
+
+		// Check for declarative HTML dictionary nearby
+		const container = dom.closest('.form-element, form') || dom.parentNode;
+		if (container) {
+			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: <span data-ln-date-field>
+		const wrapper = document.createElement('span');
+		wrapper.setAttribute('data-ln-date-field', '');
+		dom.parentNode.insertBefore(wrapper, dom);
+		wrapper.appendChild(dom);
+		this._wrapper = wrapper;
+
+		// Create hidden input for form submission
+		const hidden = document.createElement('input');
+		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;
+
+		// Create hidden date input for native picker
+		const picker = document.createElement('input');
+		picker.type = 'date';
+		picker.tabIndex = -1;
+		picker.setAttribute('tabindex', '-1');
+		picker.setAttribute('aria-hidden', 'true');
+		picker.setAttribute('aria-label', dom.getAttribute('data-ln-date-label') || 'Date picker');
+		picker.style.cssText = 'position:absolute;opacity:0;width:0;height:0;overflow:hidden;pointer-events:none';
+		hidden.insertAdjacentElement('afterend', picker);
+		this._picker = picker;
+
+		// Transform visible input to text
+		dom.type = 'text';
+
+		// Create calendar button
+		const btn = document.createElement('button');
+		btn.type = 'button';
+		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
+		Object.defineProperty(hidden, 'value', {
+			get: function () {
+				return _inputValueDesc.get.call(hidden);
+			},
+			set: function (val) {
+				_inputValueDesc.set.call(hidden, val);
+				if (val && val !== '') {
+					const date = parseDateInput(val);
+					if (date) _updateState(self, val, date);
+				} else if (val === '') {
+					_clearState(self);
+				}
+			}
+		});
+
+		// Intercept programmatic value sets on visible input (2-way binding)
+		interceptValueProperty(dom, _inputValueDesc, {
+			get: function () {
+				return _inputValueDesc.get.call(dom);
+			},
+			set: function (val, originalSet) {
+				if (self._isFormatting) {
+					originalSet(val);
+					return;
+				}
+				if (!val || val === '') {
+					originalSet('');
+					_clearState(self);
+					return;
+				}
+
+				const date = parseDateInput(val) || parseTypedDate(val);
+				if (date) {
+					const iso = formatDateToISO(date);
+					const format = dom.getAttribute(DOM_SELECTOR) || '';
+					const locale = getLocale(dom);
+					const fallback = getLocaleFallback(locale);
+					const formatted = formatDateValue(date, format, locale, fallback);
+					originalSet(formatted);
+					_updateState(self, iso, date, formatted);
+				} else {
+					originalSet(String(val));
+					_clearState(self);
+				}
+			}
+		});
+
+		// Bind events
+		this._onPickerChange = function () {
+			const val = picker.value;
+			if (val) {
+				const date = parseDateInput(val);
+				if (date) _updateState(self, val, date);
+			} else {
+				_clearState(self);
+			}
+		};
+		picker.addEventListener('change', this._onPickerChange);
+
+		this._onBlur = function () {
+			const typed = self.dom.value.trim();
+
+			if (typed === '') {
+				if (self._lastISO !== '') _clearState(self);
+				return;
+			}
+
+			if (self._lastISO) {
+				const currentDate = parseDateInput(self._lastISO);
+				if (currentDate) {
+					const format = self.dom.getAttribute(DOM_SELECTOR) || '';
+					const locale = getLocale(self.dom);
+					const fallback = getLocaleFallback(locale);
+					if (typed === formatDateValue(currentDate, format, locale, fallback)) return;
+				}
+			}
+
+			const parsed = parseTypedDate(typed);
+			if (parsed) {
+				const iso = formatDateToISO(parsed);
+				_updateState(self, iso, parsed);
+			} else {
+				if (self._lastISO) {
+					const prevDate = parseDateInput(self._lastISO);
+					if (prevDate) self._displayFormatted(prevDate);
+				} else {
+					self.dom.value = '';
+				}
+			}
+		};
+		dom.addEventListener('blur', this._onBlur);
+
+		this._onBtnClick = function () {
+			self._openPicker();
+		};
+		btn.addEventListener('click', this._onBtnClick);
+
+		// Handle form reset
+		const form = dom.form;
+		if (form) {
+			this._form = form;
+			this._onFormReset = function () {
+				setTimeout(function () {
+					const val = self.dom.value;
+					if (val) {
+						const date = parseDateInput(val) || parseTypedDate(val);
+						if (date) {
+							const iso = formatDateToISO(date);
+							_updateState(self, iso, date);
+							return;
+						}
+					}
+					_clearState(self);
+				}, 0);
+			};
+			form.addEventListener('reset', this._onFormReset);
+		}
+
+		// Handle initial pre-filled value
+		if (initialValue && initialValue !== '') {
+			const date = parseDateInput(initialValue);
+			if (date) _updateState(self, initialValue, date);
+		}
+
+		return this;
+	}
+
+	_component.prototype._initTextElement = function () {
+		const dom = this.dom;
+		const valAttr = dom.getAttribute('data-ln-value');
+		const dateAttr = dom.getAttribute('data-ln-date');
+		const datetimeAttr = dom.getAttribute('datetime');
+
+		let candidate = null;
+		if (dom.tagName === 'TIME' && datetimeAttr !== null && datetimeAttr !== '') {
+			candidate = datetimeAttr;
+		} else 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();
+		}
+
+		const date = parseDateInput(candidate) || parseTypedDate(candidate);
+		if (date && !isNaN(date.getTime())) {
+			const iso = formatDateToISO(date);
+			this._rawValue = iso;
+			if (dom.tagName !== 'TIME' && !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 = parseDateInput(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);
+				const fallback = getLocaleFallback(locale);
+				this.dom.textContent = formatDateValue(date, format || 'medium', locale, fallback);
+			}
+		}
+	};
+
+	_component.prototype._openPicker = function () {
+		if (typeof this._picker.showPicker === 'function') {
+			try {
+				this._picker.showPicker();
+			} catch (e) {
+				this._picker.click();
+			}
+		} else {
+			this._picker.click();
+		}
+	};
+
+	_component.prototype._setHiddenRaw = function (val) {
+		_inputValueDesc.set.call(this._hidden, val);
+	};
+
+	_component.prototype._displayFormatted = function (date) {
+		const format = this.dom.getAttribute(DOM_SELECTOR) || '';
+		const locale = getLocale(this.dom);
+		const fallback = getLocaleFallback(locale);
+		this._isFormatting = true;
+		this.dom.value = formatDateValue(date, format, locale, fallback);
+		this._isFormatting = false;
+	};
+
+	// ─── Public API ───────────────────────────────────────────
+
+	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');
+					if (this.dom.tagName === 'TIME') {
+						this.dom.removeAttribute('datetime');
+					}
+					this.dom.textContent = '';
+					return;
+				}
+				const date = parseDateInput(isoStr) || parseTypedDate(isoStr);
+				if (!date) return;
+				const iso = formatDateToISO(date);
+				this._rawValue = iso;
+				if (this.dom.tagName === 'TIME') {
+					this.dom.setAttribute('datetime', iso);
+				} else {
+					this.dom.setAttribute('data-ln-value', iso);
+				}
+				this._formatTextContent();
+				return;
+			}
+			if (!isoStr || isoStr === '') {
+				_clearState(this);
+				return;
+			}
+			const date = parseDateInput(isoStr);
+			if (!date) return;
+			_updateState(this, isoStr, date);
+		}
+	});
+
+	Object.defineProperty(_component.prototype, 'date', {
+		get: function () {
+			const val = this.value;
+			if (!val) return null;
+			return parseDateInput(val);
+		},
+		set: function (dateObj) {
+			if (!dateObj || !(dateObj instanceof Date) || isNaN(dateObj.getTime())) {
+				this.value = '';
+				return;
+			}
+			this.value = formatDateToISO(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) {
+			delete this.dom[DOM_ATTRIBUTE];
+			return;
+		}
+		if (this._form && this._onFormReset) {
+			this._form.removeEventListener('reset', this._onFormReset);
+		}
+		this._picker.removeEventListener('change', this._onPickerChange);
+		this.dom.removeEventListener('blur', this._onBlur);
+		this._btn.removeEventListener('click', this._onBtnClick);
+		const isoVal = this.value;
+		this._hidden.remove();
+		this._picker.remove();
+		this._btn.remove();
+		if (this._wrapper && this._wrapper.parentNode) {
+			this._wrapper.parentNode.insertBefore(this.dom, this._wrapper);
+			this._wrapper.remove();
+		}
+		delete this.dom.value;
+		this.dom.name = this._hidden.name;
+		this.dom.type = 'date';
+		if (isoVal) this.dom.value = isoVal;
+		if (this._onLocaleChange) {
+			document.removeEventListener('ln-core:locale-change', this._onLocaleChange);
+		}
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	// ─── Init ─────────────────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-date', {
+		attributes: ATTRIBUTES,
+		extraAttributes: ['datetime', 'lang'],
+		onAttributeChange: _syncAttribute
+	});
+})();

package/components/ln-debug/README.md

@@ -0,0 +1,132 @@
+# ln-debug
+
+> Activated via the `data-ln-debug` attribute on `<body>` (or an element inside `<body>`). It gates library console warnings (`[ln-`), listens to DOM mutations and `ln-*` CustomEvents, verifies cross-references (`data-ln-*-for`, `data-ln-*-source`), and flags misspelled library attributes against the schema manifest using Levenshtein distance. It introduces zero production overhead, remaining dormant or excluded outside development mode without modifying DOM structure.
+
+---
+
+## 1. Philosophy & Purpose
+
+In production, libraries should remain completely silent and zero-overhead. In development, however, missing templates, broken target IDs (`data-ln-toggle-for`), unresolved data stores (`data-ln-table-source`), and attribute spelling typos (`data-ln-tabl-source`) lead to silent failures and wasted debugging time.
+
+The `ln-debug` component solves this by providing:
+1. **Console Warning Filter**: Gates library warnings (`[ln-` / `[lnCore`) so they only print when debug mode is enabled.
+2. **Generic Cross-Reference Contract Verifier**:
+   - Validates that `data-ln-*-for` target IDs resolve to existing DOM elements.
+   - Validates that `data-ln-*-source` and `data-ln-*-store` consumers resolve to declared `[data-ln-data-store]` providers.
+   - Flags duplicate `[data-ln-data-store]` instances across the document.
+   - Detects misspelled `data-ln-*` attributes against the schema-generated attribute manifest.
+3. **Console Observation Layer**: Logs every `ln-*` CustomEvent dispatched through `ln-core`, and every library attribute mutation, to the console — the library's whole runtime life, visible on demand.
+4. **Zero Production Overhead**: Runs strictly in dev mode (`data-ln-debug` attribute or `dist/ln-ashlar-dev.js`).
+
+---
+
+## 2. Minimal Blueprint
+
+Add the `data-ln-debug` attribute to `<body>`, or to any element whose
+subtree should be observed:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <!-- Core library and Dev Verifier -->
+    <script src="dist/ln-ashlar.iife.js" defer></script>
+</head>
+<body data-ln-debug>
+    <!-- Broken references or typos will be reported clearly in the console -->
+    <button data-ln-toggle-for="sidebar-menu">Toggle</button>
+    <div id="sidebar-menu">Sidebar Content</div>
+</body>
+</html>
+```
+
+The console warning filter (§1), the cross-reference verifier (§3), and
+the console observation layer (§6) activate on elements inside `<body>`'s
+subtree — see §6 for the observation layer's host-containment rule.
+Placing `data-ln-debug` on `<html>` is unsupported and ignored.
+
+---
+
+## 3. Generic Resolvers & Diagnostic Rules
+
+| Rule | Pattern | Description | Example Warning |
+|---|---|---|---|
+| **ID References** | `data-ln-*-for="id"` | Verifies target `#id` exists in the document | `[ln-debug] Unresolved ID reference: <button data-ln-toggle-for="menu"> targets "#menu", but no element with id="menu" exists in the document.` |
+| **Store References** | `data-ln-*-source="store"` | Verifies `[data-ln-data-store="store"]` exists in the DOM | `[ln-debug] Unresolved store reference: <table data-ln-table-source="users"> targets store "users", but no [data-ln-data-store="users"] exists in the document.` |
+| **Store Uniqueness** | `[data-ln-data-store]` | Ensures store names are globally unique | `[ln-debug] Duplicate store name: Multiple elements declare data-ln-data-store="users". Store names must be unique across the document.` |
+| **Attribute Spelling** | `data-ln-*` | Checks against generated attribute manifest and suggests typos | `[ln-debug] Unknown attribute "data-ln-table-sorce" on <table>. Did you mean "data-ln-table-source"?` |
+
+---
+
+## 4. Programmatic API
+
+When debug mode is loaded, `window.lnDebug` is available for on-demand verification and testing:
+
+```javascript
+// Perform a synchronous scan of the document (or a specific subtree)
+const report = window.lnDebug.verify(document.body, { silent: false });
+
+console.log(`Found ${report.total} issue(s):`);
+console.log(report.idIssues);
+console.log(report.storeIssues);
+console.log(report.uniquenessIssues);
+console.log(report.spellingIssues);
+
+// Schedule a debounced verification that waits for lifecycle boot queue to settle
+window.lnDebug.schedule(document.body, 50, (report) => {
+    console.log('DOM verification completed:', report);
+});
+```
+
+---
+
+## 5. Lifecycle Coordination & False-Alarm Prevention
+
+The verifier hooks into `lnCore`'s `queueBoot` and `pendingCount()`:
+- If asynchronous initialization is in progress (`holdInit` > 0 from `ln-include` or router), verification is queued and executes only after boot holds are released.
+- Rapid DOM mutations are debounced to ensure sibling elements (e.g. stores and consumers) have fully settled before invariants are asserted.
+
+---
+
+## 6. Console Observation Layer
+
+While a host is active, `ln-core`'s `dispatch()`, `dispatchCancelable()`, and
+`lnFill()` log every `ln-*` CustomEvent they emit — event name, target
+element, and detail payload — to the console via `console.groupCollapsed`.
+The shared attribute observer likewise logs every mutation of a
+`data-ln-*` attribute, and of any attribute the library's reactive
+registry already observes (`lang`, `href`, `datetime`), as an `old →
+new` pair. Page attributes the library has no opinion on (`class`,
+`style`, `aria-*`) are never logged — this is the library's runtime life,
+not the page's.
+
+**Host containment.** A host is any element carrying `data-ln-debug`.
+Multiple hosts may be active at once. An event or attribute mutation is
+logged only when some active host `.contains()` the target element — this
+layer observes its own subtree, exactly like every other component in the
+library. Placing `data-ln-debug` on `<body>` observes the whole page;
+placing it on a smaller container scopes logging to that container's
+descendants only.
+
+**Page-wide exception.** A handful of `dispatch()` calls target `window` or
+`document` directly — `ln-toast:enqueue`, `ln-data-store:online` /
+`offline` / `quota-exceeded`, `ln-core:locale-change` — because no element
+subtree can contain a target that isn't an element. These log only when
+`document.body` itself is a host.
+
+**Scope.** `data-ln-debug` is read from elements inside `document.body`'s
+subtree via the shared attribute observer, and is re-evaluated on every
+mutation of that attribute — adding or removing it on any descendant of
+`<body>` (including `<body>` itself) takes effect immediately, without a
+reload, whether added, removed, or toggled in the DOM inspector. An element
+that already carries `data-ln-debug` at the moment it is inserted into the
+document — via `innerHTML`, `appendChild`, `ln-include`, or a router view
+swap — becomes an active host immediately on insertion, and stops being one
+the moment it is removed. `<html>` is not a supported host for this layer —
+unlike the console warning filter in §1, which still reads `data-ln-debug`
+from `<html>` or `<body>`. The two checks are independent and are not
+required to agree.
+
+Nothing is logged via `console.warn` or `console.debug` — `console.warn`
+is reserved for markup-error diagnostics (see above), and Chrome hides
+`console.debug` below its Verbose log level by default.