@livenetworks/ashlar 1.3.2

package/js/ln-tabs/README.md

@@ -0,0 +1,137 @@
+# ln-tabs
+
+> N-way exclusive panel selection on a single container, managed reactively via the DOM.
+
+---
+
+## 1. Philosophy & The Tabs Mindset
+
+In `ln-ashlar`, the core design principle is **orthogonality**. Rather than creating heavy components that mix state, visual presentation, and layout, `ln-tabs` separates them into isolated concerns:
+
+1. **State & ARIA (JavaScript)**: The `ln-tabs` component (145 lines) only manages the active tab key in the DOM, maps namespace URL hashes, handles optional `localStorage` persistence, and synchronizes ARIA accessibility. It possesses zero visual styles.
+2. **Visual Presentation (CSS)**: Visual layouts, borders, alignments, and active indicator designs are handled in Vanilla CSS. The library ships mixins like `@mixin tabs-nav`, `@mixin tabs-tab`, and `@mixin tabs-panel` to handle this elegantly.
+3. **Decoupled Binding (HTML)**: Tab triggers and panels are paired purely by string keys (`data-ln-tab="key"` and `data-ln-panel="key"`), decoupled from their relative DOM positions.
+
+### Why not built on `ln-toggle`?
+While similar on the surface, their contracts diverge. `ln-toggle` is a binary disclosure primitive (using `aria-expanded`). `ln-tabs` is an N-way exclusive tablist (using `aria-selected` and `aria-hidden`) that supports advanced, namespace-scoped URL deep-linking out of the box.
+
+---
+
+## 2. Minimal Blueprint
+
+Triggers and panels are bound via matching keys inside a wrapper. Inactive panels must carry `class="hidden"` to prevent a layout flash before initialization.
+
+```html
+<section id="user-tabs" data-ln-tabs data-ln-tabs-default="info">
+    <!-- Tab list (triggers) -->
+    <nav>
+        <button type="button" data-ln-tab="info">Information</button>
+        <button type="button" data-ln-tab="settings">Settings</button>
+    </nav>
+
+    <!-- Tab panels -->
+    <section data-ln-panel="info">
+        <p>This is the info panel.</p>
+    </section>
+    <section data-ln-panel="settings" class="hidden">
+        <p>This is the settings panel.</p>
+    </section>
+</section>
+```
+
+### Key Anatomy Rules
+- **The Wrapper (`data-ln-tabs`)**: Creates the tabs root instance.
+- **The Trigger (`data-ln-tab="key"`)**: Marks the element as a click target. Must be a `<button>` (with `type="button"` inside forms) or an `<a>` anchor.
+- **The Panel (`data-ln-panel="key"`)**: Matches the trigger by key. Inactive panels must carry `class="hidden"`.
+
+---
+
+## 3. The Declarative API & State Contract
+
+There are no imperative JavaScript methods (like `activate()` or `open()`) on the component instance. **The HTML attribute is the sole contract.** 
+
+Clicks, URL hash changes, localStorage restorations, and external scripts all change state by writing the active attribute on the wrapper:
+
+```js
+const tabs = document.getElementById('user-tabs');
+
+// Canonical write — switches the active tab
+tabs.setAttribute('data-ln-tabs-active', 'settings');
+
+// Read-only state query
+tabs.getAttribute('data-ln-tabs-active'); // Returns currently active key
+```
+
+### Attributes
+- `data-ln-tabs`: Placed on the wrapper to create the instance.
+- `data-ln-tabs-active`: Currently active key (written by the component, watched by the observer).
+- `data-ln-tabs-default="key"`: Default key selected on load. Falls back to the first tab trigger if omitted.
+- `data-ln-tabs-focus="false"`: Opt out of auto-focusing the first focusable element inside the active panel. Default: enabled.
+- `data-ln-tabs-key="name"`: Hash namespace. Falls back to wrapper `id` if omitted.
+- `id="name"`: Enables hash sync. The wrapper `id` acts as the URL namespace key.
+- `data-ln-persist`: Saves the active tab key in `localStorage` (effective only when hash sync is OFF).
+
+---
+
+## 4. Transition Events
+
+All events bubble. The dispatch target is the wrapper element.
+
+| Event | Cancelable | `detail` | Dispatched When |
+|---|---|---|---|
+| **`ln-tabs:change`** | No | `{ key, tab, panel }` | After the active panel is swapped, ARIA synced, focus moved (if enabled), and localStorage updated. |
+| **`ln-tabs:destroyed`** | No | `{ target }` | Inside `destroy()`, after removing click and hashchange listeners. |
+
+```js
+// Example: Listen for tab changes
+document.addEventListener('ln-tabs:change', (e) => {
+    console.log(`Active tab in ${e.target.id} changed to: ${e.detail.key}`);
+});
+```
+
+---
+
+## 5. Integration Patterns
+
+### A. Hash-Deep-Linkable Tabs (URL-as-State)
+Add an `id` to the wrapper. Clicking tabs automatically writes to the URL hash (e.g. `#user-tabs:settings`). Sharing, bookmarking, or using back/forward buttons restores the active tab on load.
+```html
+<section id="user-tabs" data-ln-tabs data-ln-tabs-default="info">...</section>
+```
+
+### B. Anchor Triggers (Deep Links)
+Use `<a>` triggers with matching `href` format and boolean `data-ln-tab` attributes. Right-click copy link and middle-click "open in new tab" work out of the box.
+```html
+<a href="#user-tabs:info" data-ln-tab>Information</a>
+<a href="#user-tabs:settings" data-ln-tab>Settings</a>
+```
+
+### C. Multiple Independent Tabsets
+Multiple independent tabsets on the same page will coexist cleanly in the URL hash, namespaced by their respective wrapper `id`s (e.g., `#user-tabs:settings&project-tabs:members`).
+
+### D. Persistent Tabs (Without URL Hash)
+Omit the wrapper `id` and add `data-ln-persist="key"` to remember the active tab in `localStorage` without changing the URL hash.
+```html
+<section data-ln-tabs data-ln-persist="settings-tabs" data-ln-tabs-default="general">...</section>
+```
+
+---
+
+## 6. Integration & Source Files
+
+- **Unified Bundle**: Loaded automatically with the main bundle:
+  ```html
+  <script src="dist/ln-ashlar.iife.js" defer></script>
+  ```
+- **Standalone IIFE**: For lightweight pages, load the standalone, self-registering IIFE version:
+  ```html
+  <script src="js/ln-tabs/ln-tabs.js" defer></script>
+  ```
+- **Active Source (ESM)**: Development source is located at [js/ln-tabs/src/ln-tabs.js](file:///c:/laragon/www/ln-ashlar/js/ln-tabs/src/ln-tabs.js).
+
+---
+
+## Related
+- **[`ln-toggle`](../ln-toggle/README.md)** — Binary disclosure state primitive.
+- **[`ln-accordion`](../ln-accordion/README.md)** — Single-open coordinator built on `ln-toggle`.
+- **Architecture deep-dive** — [`docs/js/tabs.md`](../../docs/js/tabs.md).

package/js/ln-tabs/ln-tabs.js

@@ -0,0 +1 @@
+(function(){"use strict";function g(i,n,r){i.dispatchEvent(new CustomEvent(n,{bubbles:!0,detail:r||{}}))}function y(i,n){if(!document.body){document.addEventListener("DOMContentLoaded",function(){y(i,n)}),console.warn("["+n+'] Script loaded before <body> — add "defer" to your <script> tag');return}i()}function m(i,n,r,l){if(i.nodeType!==1)return;const p=n.indexOf("[")!==-1||n.indexOf(".")!==-1||n.indexOf("#")!==-1?n:"["+n+"]",e=Array.from(i.querySelectorAll(p));i.matches&&i.matches(p)&&e.push(i);for(const t of e)t[r]||(t[r]=new l(t))}function v(i,n,r,l,h={}){const p=h.extraAttributes||[],e=h.onAttributeChange||null,t=h.onInit||null;function s(a){const o=a||document.body;m(o,i,n,r),t&&t(o)}return y(function(){const a=new MutationObserver(function(u){for(let d=0;d<u.length;d++){const c=u[d];if(c.type==="childList")for(let f=0;f<c.addedNodes.length;f++){const b=c.addedNodes[f];b.nodeType===1&&(m(b,i,n,r),t&&t(b))}else c.type==="attributes"&&(e&&c.target[n]?e(c.target,c.attributeName):(m(c.target,i,n,r),t&&t(c.target)))}});let o=[];if(i.indexOf("[")!==-1){const u=/\[([\w-]+)/g;let d;for(;(d=u.exec(i))!==null;)o.push(d[1])}else o.push(i);a.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:o.concat(p)})},l),window[n]=s,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){s(document.body)}):s(document.body),s}const w={};function C(i,n){w[i]=n}function E(i){return w[i]||{ingress:n=>n,egress:n=>n}}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=C,window.lnCore.getDataMapper=E);const L="ln:";function T(){return location.pathname.replace(/\/+$/,"").toLowerCase()||"/"}function A(i,n){const r=n.getAttribute("data-ln-persist"),l=r!==null&&r!==""?r:n.id;return l?L+i+":"+T()+":"+l:(console.warn('[ln-persist] Element requires id or data-ln-persist="key"',n),null)}function _(i,n){const r=A(i,n);if(!r)return null;try{const l=localStorage.getItem(r);return l!==null?JSON.parse(l):null}catch{return null}}function x(i,n,r){const l=A(i,n);if(l)try{localStorage.setItem(l,JSON.stringify(r))}catch{}}(function(){const i="data-ln-tabs",n="lnTabs";if(window[n]!==void 0&&window[n]!==null)return;function r(){const e=(location.hash||"").replace("#",""),t={};if(!e)return t;for(const s of e.split("&")){const a=s.indexOf(":");a>0&&(t[s.slice(0,a)]=s.slice(a+1))}return t}function l(e,t){const s=(e.getAttribute("data-ln-tab")||"").toLowerCase().trim();if(s)return s;if(e.tagName!=="A")return"";const a=e.getAttribute("href")||"";if(!a.startsWith("#"))return"";const o=a.slice(1);if(!o)return"";const u=o.split("&");if(t)for(const f of u){const b=f.indexOf(":");if(b>0&&f.slice(0,b).toLowerCase().trim()===t)return f.slice(b+1).toLowerCase().trim()}const d=u[u.length-1]||"",c=d.indexOf(":");return(c>0?d.slice(c+1):d).toLowerCase().trim()}function h(e){return this.dom=e,p.call(this),this}function p(){this.tabs=Array.from(this.dom.querySelectorAll("[data-ln-tab]")),this.panels=Array.from(this.dom.querySelectorAll("[data-ln-panel]")),this.nsKey=(this.dom.getAttribute("data-ln-tabs-key")||this.dom.id||"").toLowerCase().trim(),this.hashEnabled=!!this.nsKey,this.mapTabs={},this.mapPanels={};for(const t of this.tabs){const s=l(t,this.nsKey);s?this.mapTabs[s]=t:console.warn('[ln-tabs] Trigger has no resolvable key — needs `data-ln-tab="key"` or `<a href="#…">`.',t)}for(const t of this.panels){const s=(t.getAttribute("data-ln-panel")||"").toLowerCase().trim();s&&(this.mapPanels[s]=t)}this.defaultKey=(this.dom.getAttribute("data-ln-tabs-default")||"").toLowerCase().trim()||Object.keys(this.mapTabs)[0]||"",this.autoFocus=(this.dom.getAttribute("data-ln-tabs-focus")||"true").toLowerCase()!=="false";const e=this;this._clickHandlers=[];for(const t of this.tabs){if(t[n+"Trigger"])continue;const s=function(a){if(a.ctrlKey||a.metaKey||a.button===1)return;const o=l(t,e.nsKey);if(o)if(t.tagName==="A"&&a.preventDefault(),e.hashEnabled){const u=r();u[e.nsKey]=o;const d=Object.keys(u).map(function(c){return c+":"+u[c]}).join("&");location.hash==="#"+d?e.dom.setAttribute("data-ln-tabs-active",o):location.hash=d}else e.dom.setAttribute("data-ln-tabs-active",o)};t.addEventListener("click",s),t[n+"Trigger"]=s,e._clickHandlers.push({el:t,handler:s})}if(this._hashHandler=function(){if(!e.hashEnabled)return;const t=r();e.dom.setAttribute("data-ln-tabs-active",e.nsKey in t?t[e.nsKey]:e.defaultKey)},this.hashEnabled)window.addEventListener("hashchange",this._hashHandler),this._hashHandler();else{let t=this.defaultKey;if(this.dom.hasAttribute("data-ln-persist")&&!this.hashEnabled){const s=_("tabs",this.dom);s!==null&&s in this.mapPanels&&(t=s)}this.dom.setAttribute("data-ln-tabs-active",t)}}h.prototype._applyActive=function(e){var t;(!e||!(e in this.mapPanels))&&(e=this.defaultKey);for(const s in this.mapTabs){const a=this.mapTabs[s];s===e?(a.setAttribute("data-active",""),a.setAttribute("aria-selected","true")):(a.removeAttribute("data-active"),a.setAttribute("aria-selected","false"))}for(const s in this.mapPanels){const a=this.mapPanels[s],o=s===e;a.classList.toggle("hidden",!o),a.setAttribute("aria-hidden",o?"false":"true")}if(this.autoFocus){const s=(t=this.mapPanels[e])==null?void 0:t.querySelector('input,button,select,textarea,[tabindex]:not([tabindex="-1"])');s&&setTimeout(()=>s.focus({preventScroll:!0}),0)}g(this.dom,"ln-tabs:change",{key:e,tab:this.mapTabs[e],panel:this.mapPanels[e]}),this.dom.hasAttribute("data-ln-persist")&&!this.hashEnabled&&x("tabs",this.dom,e)},h.prototype.destroy=function(){if(this.dom[n]){for(const{el:e,handler:t}of this._clickHandlers)e.removeEventListener("click",t),delete e[n+"Trigger"];this.hashEnabled&&window.removeEventListener("hashchange",this._hashHandler),g(this.dom,"ln-tabs:destroyed",{target:this.dom}),delete this.dom[n]}},v(i,n,h,"ln-tabs",{extraAttributes:["data-ln-tabs-active"],onAttributeChange:function(e){const t=e.getAttribute("data-ln-tabs-active");e[n]._applyActive(t)}})})()})();

package/js/ln-tabs/src/ln-tabs.js

@@ -0,0 +1,171 @@
+/* Live Networks - lnTabs (hash-aware tabs — supports <button> and <a href="#nsKey:key"> triggers) */
+import { registerComponent, dispatch } from '../../ln-core';
+import { persistGet, persistSet } from '../../ln-core';
+
+(function () {
+	const DOM_SELECTOR = "data-ln-tabs";
+	const DOM_ATTRIBUTE = "lnTabs";
+
+	if (window[DOM_ATTRIBUTE] !== undefined && window[DOM_ATTRIBUTE] !== null) return;
+
+
+	function _parseHash() {
+		const h = (location.hash || "").replace("#", "");
+		const map = {};
+		if (!h) return map;
+		for (const part of h.split("&")) {
+			const sep = part.indexOf(":");
+			if (sep > 0) map[part.slice(0, sep)] = part.slice(sep + 1);
+		}
+		return map;
+	}
+
+	function _keyFromTrigger(t, nsKey) {
+		const explicit = (t.getAttribute("data-ln-tab") || "").toLowerCase().trim();
+		if (explicit) return explicit;
+		if (t.tagName !== "A") return "";
+		const href = t.getAttribute("href") || "";
+		if (!href.startsWith("#")) return "";
+		const raw = href.slice(1);
+		if (!raw) return "";
+		const fragments = raw.split("&");
+		if (nsKey) {
+			for (const frag of fragments) {
+				const sep = frag.indexOf(":");
+				if (sep > 0 && frag.slice(0, sep).toLowerCase().trim() === nsKey) {
+					return frag.slice(sep + 1).toLowerCase().trim();
+				}
+			}
+		}
+		const last = fragments[fragments.length - 1] || "";
+		const sep = last.indexOf(":");
+		return (sep > 0 ? last.slice(sep + 1) : last).toLowerCase().trim();
+	}
+
+	function _component(dom) { this.dom = dom; _init.call(this); return this; }
+
+	function _init() {
+		this.tabs   = Array.from(this.dom.querySelectorAll("[data-ln-tab]"));
+		this.panels = Array.from(this.dom.querySelectorAll("[data-ln-panel]"));
+
+		// nsKey/hashEnabled resolved BEFORE mapTabs build — anchor key
+		// derivation in _keyFromTrigger needs nsKey to pick the right
+		// fragment.
+		this.nsKey       = (this.dom.getAttribute("data-ln-tabs-key") || this.dom.id || "").toLowerCase().trim();
+		this.hashEnabled = !!this.nsKey;
+
+		this.mapTabs = {};
+		this.mapPanels = {};
+		for (const t of this.tabs) {
+			const key = _keyFromTrigger(t, this.nsKey);
+			if (key) {
+				this.mapTabs[key] = t;
+			} else {
+				console.warn('[ln-tabs] Trigger has no resolvable key — needs `data-ln-tab="key"` or `<a href="#…">`.', t);
+			}
+		}
+		for (const p of this.panels) {
+			const key = (p.getAttribute("data-ln-panel") || "").toLowerCase().trim();
+			if (key) this.mapPanels[key] = p;
+		}
+
+		this.defaultKey   = (this.dom.getAttribute("data-ln-tabs-default") || "").toLowerCase().trim()
+			|| Object.keys(this.mapTabs)[0] || "";
+		this.autoFocus    = (this.dom.getAttribute("data-ln-tabs-focus") || "true").toLowerCase() !== "false";
+
+		const self = this;
+		this._clickHandlers = [];
+		for (const t of this.tabs) {
+			if (t[DOM_ATTRIBUTE + 'Trigger']) continue;
+			const handler = function (e) {
+				if (e.ctrlKey || e.metaKey || e.button === 1) return;
+				const key = _keyFromTrigger(t, self.nsKey);
+				if (!key) return;
+				if (t.tagName === "A") e.preventDefault();
+				if (self.hashEnabled) {
+					const map = _parseHash();
+					map[self.nsKey] = key;
+					const newHash = Object.keys(map).map(function (k) { return k + ":" + map[k]; }).join("&");
+					if (location.hash === "#" + newHash) self.dom.setAttribute('data-ln-tabs-active', key);
+					else location.hash = newHash;
+				} else {
+					self.dom.setAttribute('data-ln-tabs-active', key);
+				}
+			};
+			t.addEventListener("click", handler);
+			t[DOM_ATTRIBUTE + 'Trigger'] = handler;
+			self._clickHandlers.push({ el: t, handler: handler });
+		}
+
+		this._hashHandler = function () {
+			if (!self.hashEnabled) return;
+			const map = _parseHash();
+			self.dom.setAttribute('data-ln-tabs-active', self.nsKey in map ? map[self.nsKey] : self.defaultKey);
+		};
+
+		if (this.hashEnabled) {
+			window.addEventListener("hashchange", this._hashHandler);
+			this._hashHandler();
+		} else {
+			let initialKey = this.defaultKey;
+			if (this.dom.hasAttribute('data-ln-persist') && !this.hashEnabled) {
+				const saved = persistGet('tabs', this.dom);
+				if (saved !== null && saved in this.mapPanels) {
+					initialKey = saved;
+				}
+			}
+			this.dom.setAttribute('data-ln-tabs-active', initialKey);
+		}
+	}
+
+	_component.prototype._applyActive = function (key) {
+		if (!key || !(key in this.mapPanels)) key = this.defaultKey;
+		for (const k in this.mapTabs) {
+			const btn = this.mapTabs[k];
+			if (k === key) {
+				btn.setAttribute("data-active", "");
+				btn.setAttribute("aria-selected", "true");
+			} else {
+				btn.removeAttribute("data-active");
+				btn.setAttribute("aria-selected", "false");
+			}
+		}
+		for (const k in this.mapPanels) {
+			const panel = this.mapPanels[k];
+			const show = (k === key);
+			panel.classList.toggle("hidden", !show);
+			panel.setAttribute("aria-hidden", show ? "false" : "true");
+		}
+		if (this.autoFocus) {
+			const first = this.mapPanels[key]?.querySelector('input,button,select,textarea,[tabindex]:not([tabindex="-1"])');
+			if (first) setTimeout(() => first.focus({ preventScroll: true }), 0);
+		}
+		dispatch(this.dom, 'ln-tabs:change', { key: key, tab: this.mapTabs[key], panel: this.mapPanels[key] });
+		if (this.dom.hasAttribute('data-ln-persist') && !this.hashEnabled) {
+			persistSet('tabs', this.dom, key);
+		}
+	};
+
+	_component.prototype.destroy = function () {
+		if (!this.dom[DOM_ATTRIBUTE]) return;
+		for (const { el, handler } of this._clickHandlers) {
+			el.removeEventListener("click", handler);
+			delete el[DOM_ATTRIBUTE + 'Trigger'];
+		}
+		if (this.hashEnabled) {
+			window.removeEventListener("hashchange", this._hashHandler);
+		}
+		dispatch(this.dom, 'ln-tabs:destroyed', { target: this.dom });
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	// ─── Init ──────────────────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _component, 'ln-tabs', {
+		extraAttributes: ['data-ln-tabs-active'],
+		onAttributeChange: function (el) {
+			const key = el.getAttribute('data-ln-tabs-active');
+			el[DOM_ATTRIBUTE]._applyActive(key);
+		}
+	});
+})();

package/js/ln-time/README.md

@@ -0,0 +1,81 @@
+# ln-time
+
+A zero-dependency, progressive **Timezone-Aware Timestamp Formatter** that localizes standard HTML `<time>` elements using native browser APIs.
+
+It replaces server-rendered fallback text with localized, timezone-aware date and time formats, performing automatic live updates for relative timestamps using a single shared timer scheduler.
+
+---
+
+## 🧭 Philosophy & Architecture
+
+1. **Progressive Enhancement:** Server layouts (e.g. Laravel Blade templates) render standard text fallbacks inside native `<time>` elements. If JavaScript fails or is blocked, the original text is preserved; when active, the component compiles and overwrites it.
+2. **Standard-Based API Concurrency:** Built entirely on standard browser APIs (`Intl.DateTimeFormat` and `Intl.RelativeTimeFormat`). It bypasses heavy date-parsing libraries, leveraging the browser's native locale and timezone mappings.
+3. **Shared Interval Loop:** Dynamic relative timestamps (e.g., "5 minutes ago") auto-update every 60 seconds. Instead of spinning up individual intervals, a single global interval manager coordinates all active elements, automatically purging detached nodes.
+4. **Reactive State Resolution:** All state changes are governed by native HTML attributes. Changing `datetime` or `data-ln-time` triggers automatic DOM re-renders via `MutationObserver` synchronization.
+
+---
+
+## 📦 Minimal Blueprint
+
+### Static Localized Date
+Provide a Unix timestamp (in seconds) via `datetime` and specify the formatting mode.
+```html
+<!-- Server renders a fallback, JS enhances with user timezone and locale -->
+<time data-ln-time="full" datetime="1736952600">January 15, 2025</time>
+```
+
+### Auto-Updating Relative Timestamp
+```html
+<!-- Automatically updates every 60s (e.g. "3 minutes ago") -->
+<time data-ln-time="relative" datetime="1736952600">Jan 15</time>
+```
+
+### Custom Localized Override
+```html
+<!-- Localizes the time string to Macedonian regardless of browser defaults -->
+<time data-ln-time="full" datetime="1736952600" data-ln-time-locale="mk">Јануари 15, 2025</time>
+```
+
+---
+
+## 🛠️ Declarative API Contract
+
+### HTML Attributes
+
+| Attribute | Elements | Description |
+| :--- | :--- | :--- |
+| `data-ln-time` | `<time>` | Format mode: `relative`, `short`, `full`, `date`, `time`. |
+| `datetime` | `<time>` | **Required**. Unix timestamp in **seconds** (not milliseconds). |
+| `data-ln-time-locale`| `<time>` | Opt-in. Force-overrides translation locale (e.g. `"de"`, `"mk"`). |
+
+### Format Modes
+
+| Mode | Output Example | Intl Engine |
+| :--- | :--- | :--- |
+| `relative` | `"3 hr. ago"`, `"just now"`, `"in 2 hr."` | `Intl.RelativeTimeFormat` |
+| `short` | `"Jan 15"` (current year) / `"Jan 15, 2024"` | `{ month: 'short', day: 'numeric' }` |
+| `full` | `"January 15, 2025 at 2:30 PM"` | `{ dateStyle: 'long', timeStyle: 'short' }` |
+| `date` | `"Jan 15, 2025"` | `{ dateStyle: 'medium' }` |
+| `time` | `"2:30 PM"` | `{ timeStyle: 'short' }` |
+
+---
+
+## ⚡ Live Relative Thresholds
+
+| Elapsed Time | Evaluated Unit | Output Example (English) |
+| :--- | :--- | :--- |
+| `< 10 seconds` | — | `"now"` |
+| `< 60 seconds` | `second` | `"45 sec. ago"` |
+| `< 60 minutes` | `minute` | `"5 min. ago"` |
+| `< 24 hours` | `hour` | `"3 hr. ago"` |
+| `< 7 days` | `day` | `"2 days ago"` |
+| `< 30 days` | `week` | `"2 wk. ago"` |
+| `>= 30 days` | — | Falls back to static `short` date. |
+
+---
+
+## ⚠️ Common Pitfalls
+
+- **Passing Millisecond Timestamps:** Standard database fields and JS date objects often return milliseconds (13 digits). `ln-time` maps strictly to Unix seconds (10 digits). Divide milliseconds by `1000` before rendering.
+- **Using ISO Strings:** `datetime="2025-01-15T14:30:00Z"` is not parsed. The component skips non-numeric values, leaving the original fallback text.
+- **Empty `datetime` Attributes:** If the `datetime` attribute is omitted or empty, the component will skip formatting to preserve server fallback strings.

package/js/ln-time/ln-time.js

@@ -0,0 +1 @@
+(function(){"use strict";function x(r,e){if(!document.body){document.addEventListener("DOMContentLoaded",function(){x(r,e)}),console.warn("["+e+'] Script loaded before <body> — add "defer" to your <script> tag');return}r()}function S(r,e,s,y){if(r.nodeType!==1)return;const m=e.indexOf("[")!==-1||e.indexOf(".")!==-1||e.indexOf("#")!==-1?e:"["+e+"]",g=Array.from(r.querySelectorAll(m));r.matches&&r.matches(m)&&g.push(r);for(const o of g)o[s]||(o[s]=new y(o))}function O(r,e,s,y,w={}){const m=w.extraAttributes||[],g=w.onAttributeChange||null,o=w.onInit||null;function d(p){const c=p||document.body;S(c,r,e,s),o&&o(c)}return x(function(){const p=new MutationObserver(function(_){for(let h=0;h<_.length;h++){const u=_[h];if(u.type==="childList")for(let A=0;A<u.addedNodes.length;A++){const M=u.addedNodes[A];M.nodeType===1&&(S(M,r,e,s),o&&o(M))}else u.type==="attributes"&&(g&&u.target[e]?g(u.target,u.attributeName):(S(u.target,r,e,s),o&&o(u.target)))}});let c=[];if(r.indexOf("[")!==-1){const _=/\[([\w-]+)/g;let h;for(;(h=_.exec(r))!==null;)c.push(h[1])}else c.push(r);p.observe(document.body,{childList:!0,subtree:!0,attributes:!0,attributeFilter:c.concat(m)})},y),window[e]=d,document.readyState==="loading"?document.addEventListener("DOMContentLoaded",function(){d(document.body)}):d(document.body),d}const I={};function T(r,e){I[r]=e}function k(r){return I[r]||{ingress:e=>e,egress:e=>e}}typeof window<"u"&&(window.lnCore=window.lnCore||{},window.lnCore.registerDataMapper=T,window.lnCore.getDataMapper=k),(function(){const r="data-ln-time",e="lnTime";if(window[e]!==void 0)return;const s={},y={};function w(t){return t.getAttribute("data-ln-time-locale")||document.documentElement.lang||void 0}function m(t,n){const f=(t||"")+"|"+JSON.stringify(n);return s[f]||(s[f]=new Intl.DateTimeFormat(t,n)),s[f]}function g(t){const n=t||"";return y[n]||(y[n]=new Intl.RelativeTimeFormat(t,{numeric:"auto",style:"narrow"})),y[n]}const o=new Set;let d=null;function p(){d||(d=setInterval(_,6e4))}function c(){d&&(clearInterval(d),d=null)}function _(){for(const t of o){if(!document.body.contains(t.dom)){o.delete(t);continue}D(t)}o.size===0&&c()}function h(t,n){return m(n,{dateStyle:"long",timeStyle:"short"}).format(t)}function u(t,n){const f=new Date,l={month:"short",day:"numeric"};return t.getFullYear()!==f.getFullYear()&&(l.year="numeric"),m(n,l).format(t)}function A(t,n){return m(n,{dateStyle:"medium"}).format(t)}function M(t,n){return m(n,{timeStyle:"short"}).format(t)}function E(t,n){const f=Math.floor(Date.now()/1e3),b=Math.floor(t.getTime()/1e3)-f,i=Math.abs(b);if(i<10)return g(n).format(0,"second");let a,v;if(i<60)a="second",v=b;else if(i<3600)a="minute",v=Math.round(b/60);else if(i<86400)a="hour",v=Math.round(b/3600);else if(i<604800)a="day",v=Math.round(b/86400);else if(i<2592e3)a="week",v=Math.round(b/604800);else return u(t,n);return g(n).format(v,a)}function D(t){const n=t.dom.getAttribute("datetime");if(!n)return;const f=Number(n);if(isNaN(f))return;const l=new Date(f*1e3),b=t.dom.getAttribute(r)||"short",i=w(t.dom);let a;switch(b){case"relative":a=E(l,i);break;case"full":a=h(l,i);break;case"date":a=A(l,i);break;case"time":a=M(l,i);break;default:a=u(l,i);break}t.dom.textContent=a,b!=="full"&&(t.dom.title=h(l,i))}function C(t){return this.dom=t,D(this),t.getAttribute(r)==="relative"&&(o.add(this),p()),this}C.prototype.render=function(){D(this)},C.prototype.destroy=function(){o.delete(this),o.size===0&&c(),delete this.dom[e]};function L(t){const n=t[e];if(!n)return;t.getAttribute(r)==="relative"?(o.add(n),p()):(o.delete(n),o.size===0&&c()),D(n)}function N(t){t.nodeType===1&&t.hasAttribute&&t.hasAttribute(r)&&t[e]&&D(t[e])}O(r,e,C,"ln-time",{extraAttributes:["datetime"],onAttributeChange:L,onInit:N})})()})();

package/js/ln-time/src/ln-time.js

@@ -0,0 +1,192 @@
+import { registerComponent } from '../../ln-core';
+
+(function () {
+	const DOM_SELECTOR = 'data-ln-time';
+	const DOM_ATTRIBUTE = 'lnTime';
+
+	if (window[DOM_ATTRIBUTE] !== undefined) return;
+
+	// ─── Formatter Cache ──────────────────────────────────────
+	const _formatters = {};
+	const _relativeFormatters = {};
+
+	function _getLocale(el) {
+		return el.getAttribute('data-ln-time-locale')
+			|| document.documentElement.lang
+			|| undefined;
+	}
+
+	function _getFormatter(locale, options) {
+		const key = (locale || '') + '|' + JSON.stringify(options);
+		if (!_formatters[key]) {
+			_formatters[key] = new Intl.DateTimeFormat(locale, options);
+		}
+		return _formatters[key];
+	}
+
+	function _getRelativeFormatter(locale) {
+		const key = locale || '';
+		if (!_relativeFormatters[key]) {
+			_relativeFormatters[key] = new Intl.RelativeTimeFormat(locale, { numeric: 'auto', style: 'narrow' });
+		}
+		return _relativeFormatters[key];
+	}
+
+	// ─── Auto-Update Pool ─────────────────────────────────────
+	const _relativeElements = new Set();
+	let _intervalId = null;
+
+	function _startInterval() {
+		if (_intervalId) return;
+		_intervalId = setInterval(_tickRelative, 60000);
+	}
+
+	function _stopInterval() {
+		if (_intervalId) {
+			clearInterval(_intervalId);
+			_intervalId = null;
+		}
+	}
+
+	function _tickRelative() {
+		for (const instance of _relativeElements) {
+			if (!document.body.contains(instance.dom)) {
+				_relativeElements.delete(instance);
+				continue;
+			}
+			_render(instance);
+		}
+		if (_relativeElements.size === 0) _stopInterval();
+	}
+
+	// ─── Formatting ───────────────────────────────────────────
+	function _formatFull(date, locale) {
+		return _getFormatter(locale, { dateStyle: 'long', timeStyle: 'short' }).format(date);
+	}
+
+	function _formatShort(date, locale) {
+		const now = new Date();
+		const options = { month: 'short', day: 'numeric' };
+		if (date.getFullYear() !== now.getFullYear()) {
+			options.year = 'numeric';
+		}
+		return _getFormatter(locale, options).format(date);
+	}
+
+	function _formatDate(date, locale) {
+		return _getFormatter(locale, { dateStyle: 'medium' }).format(date);
+	}
+
+	function _formatTime(date, locale) {
+		return _getFormatter(locale, { timeStyle: 'short' }).format(date);
+	}
+
+	function _formatRelative(date, locale) {
+		const nowSec = Math.floor(Date.now() / 1000);
+		const thenSec = Math.floor(date.getTime() / 1000);
+		const diff = thenSec - nowSec;
+		const absDiff = Math.abs(diff);
+
+		if (absDiff < 10) return _getRelativeFormatter(locale).format(0, 'second');
+
+		let unit, value;
+		if (absDiff < 60) {
+			unit = 'second'; value = diff;
+		} else if (absDiff < 3600) {
+			unit = 'minute'; value = Math.round(diff / 60);
+		} else if (absDiff < 86400) {
+			unit = 'hour'; value = Math.round(diff / 3600);
+		} else if (absDiff < 604800) {
+			unit = 'day'; value = Math.round(diff / 86400);
+		} else if (absDiff < 2592000) {
+			unit = 'week'; value = Math.round(diff / 604800);
+		} else {
+			return _formatShort(date, locale);
+		}
+
+		return _getRelativeFormatter(locale).format(value, unit);
+	}
+
+	// ─── Render ───────────────────────────────────────────────
+	function _render(instance) {
+		const raw = instance.dom.getAttribute('datetime');
+		if (!raw) return;
+
+		const timestamp = Number(raw);
+		if (isNaN(timestamp)) return;
+
+		const date = new Date(timestamp * 1000);
+		const mode = instance.dom.getAttribute(DOM_SELECTOR) || 'short';
+		const locale = _getLocale(instance.dom);
+		let text;
+
+		switch (mode) {
+			case 'relative': text = _formatRelative(date, locale); break;
+			case 'full':     text = _formatFull(date, locale);     break;
+			case 'date':     text = _formatDate(date, locale);     break;
+			case 'time':     text = _formatTime(date, locale);     break;
+			default:         text = _formatShort(date, locale);    break;
+		}
+
+		instance.dom.textContent = text;
+		if (mode !== 'full') {
+			instance.dom.title = _formatFull(date, locale);
+		}
+	}
+
+	// ─── Component ────────────────────────────────────────────
+	function _constructor(dom) {
+		this.dom = dom;
+		_render(this);
+
+		if (dom.getAttribute(DOM_SELECTOR) === 'relative') {
+			_relativeElements.add(this);
+			_startInterval();
+		}
+
+		return this;
+	}
+
+	_constructor.prototype.render = function () {
+		_render(this);
+	};
+
+	_constructor.prototype.destroy = function () {
+		_relativeElements.delete(this);
+		if (_relativeElements.size === 0) _stopInterval();
+		delete this.dom[DOM_ATTRIBUTE];
+	};
+
+	// ─── Attribute / Mutation Hooks ───────────────────────────
+
+	function _onAttributeChange(el) {
+		const instance = el[DOM_ATTRIBUTE];
+		if (!instance) return;
+		const mode = el.getAttribute(DOM_SELECTOR);
+		if (mode === 'relative') {
+			_relativeElements.add(instance);
+			_startInterval();
+		} else {
+			_relativeElements.delete(instance);
+			if (_relativeElements.size === 0) _stopInterval();
+		}
+		_render(instance);
+	}
+
+	function _onInit(node) {
+		// Re-render any data-ln-time element in the mutation target subtree.
+		// Covers `datetime` extra-attribute changes (extras don't fire onAttributeChange).
+		if (node.nodeType !== 1) return;
+		if (node.hasAttribute && node.hasAttribute(DOM_SELECTOR) && node[DOM_ATTRIBUTE]) {
+			_render(node[DOM_ATTRIBUTE]);
+		}
+	}
+
+	// ─── Registration ─────────────────────────────────────────
+
+	registerComponent(DOM_SELECTOR, DOM_ATTRIBUTE, _constructor, 'ln-time', {
+		extraAttributes: ['datetime'],
+		onAttributeChange: _onAttributeChange,
+		onInit: _onInit
+	});
+})();