mnfst 0.5.163 → 0.5.164

package/lib/manifest.datepicker.js

@@ -1,37 +1,14 @@
-/*  Manifest Date Picker
+/*  Manifest Date Picker — modular date/time picker behind one `x-date` directive
 /*  By Andrew Matlock under MIT license
 /*  https://manifestx.dev
-/*
-/*  A fully modular date (and time) picker behind one `x-date` directive.
-/*
-/*  The element decides its role — no role modifiers needed:
-/*    <input x-date>                       field with auto-generated dropdown calendar
-/*    <input x-date type="date">           same, degrades to the native picker without JS
-/*    <input x-date type="time">           standalone time picker
-/*    <input x-date type="datetime-local"> date + time, degrades natively without JS
-/*    <button x-date="cal-id">             button trigger for an authored calendar
-/*    <div x-date>                         inline calendar
-/*    <menu popover x-date> / <dialog x-date>  dropdown / modal calendar
-/*
-/*  Selection modes are modifiers: x-date.range, x-date.multiple, x-date.time
-/*  (x-date.time on a date field appends a time-of-day control).
-/*
-/*  The value is polymorphic, mirroring the color picker's swatch:
-/*    string  → the id of an authored calendar element (fields only)
-/*    object  → reactive config: { months, min, max, disabled, presets }
 */
 
 (function () {
 	'use strict';
 
-	/* ------------------------------------------------------------------ *
-	 * Shared global: ManifestDates — in-house, dependency-free date math.
-	 * Operates on date-only values anchored at noon local time, which makes
-	 * every add/subtract immune to DST shifts (a ±1h move never crosses a
-	 * calendar day from noon). All formatting/localization is delegated to
-	 * Intl, so we never parse locale-formatted strings — the one place a date
-	 * library would earn its weight. Thin by design: swappable for Temporal.
-	 * ------------------------------------------------------------------ */
+	/* Shared global: ManifestDates — dependency-free date math, noon-anchored to
+	 * dodge DST shifts. Formatting/localization delegated to Intl (never parses
+	 * locale strings). */
 	if (!window.ManifestDates) {
 		const pad = (n) => String(n).padStart(2, '0');
 		const D = {
@@ -78,24 +55,13 @@
 		window.ManifestDates = D;
 	}
 
-	/* ------------------------------------------------------------------ *
-	 * Shared global: ManifestUI — universal `_ui` text resolver.
-	 * Any Manifest element with baked-in default chrome (kept intentionally
-	 * rare) can localize/override that text without rebuilding the element.
-	 * `_ui` is a reserved, self-identifying key: any loaded data source may
-	 * carry a top-level `_ui` object, namespaced per element, e.g.
-	 *   _ui: { date: { today: …, clear: … }, colorpicker: { … } }
-	 * No manifest flag — overrides piggyback on the normal local-data/
-	 * localization model and can be colocated with author content. Values may
-	 * be plain strings or $x/$locale references (locale-reactive). resolve()
-	 * deep-merges every loaded source's `_ui[component]` onto the plugin's
-	 * English fallbacks. Defensive: any failure returns the fallbacks untouched.
-	 * Kept byte-identical across the colorpicker / charts copies.
-	 * ------------------------------------------------------------------ */
+	/* Shared global: ManifestUI — `_ui` text resolver. A loaded data source may carry
+	 * a top-level `_ui` object namespaced per component (_ui.date, _ui.colorpicker, …);
+	 * resolve() deep-merges it onto the plugin's English fallbacks. Locale-reactive via
+	 * $x/$locale. Kept byte-identical across the colorpicker / charts copies. */
 	if (!window.ManifestUI) {
 		window.ManifestUI = {
-			/* Names of data sources that have loaded (current locale). Enumerates loaded
-			 * sources only — never force-loads others just to scan them for `_ui`. */
+			/* Loaded data-source names only — never force-loads others to scan them. */
 			_loadedSourceNames() {
 				try {
 					const store = window.ManifestDataStore && window.ManifestDataStore.rawDataStore;
@@ -103,8 +69,7 @@
 				} catch (_) { }
 				return [];
 			},
-			/* Deep-merge every loaded source's `_ui[component]` onto `fallbacks`.
-			 * Reads inside the caller's Alpine effect (if any) so $x/$locale make it reactive. */
+			/* Deep-merge every loaded source's `_ui[component]` onto `fallbacks`. */
 			resolve(component, fallbacks) {
 				const merged = JSON.parse(JSON.stringify(fallbacks || {}));
 				try {
@@ -141,8 +106,7 @@
 		const Alpine = window.Alpine;
 		const D = window.ManifestDates;
 
-		// Reactive registry: id -> api, so $date('id') resolves even when the
-		// calendar mounts after the reader binds.
+		// Reactive registry id -> api, so $date('id') resolves across mount order.
 		const _registry = Alpine.reactive ? Alpine.reactive({}) : {};
 		let _uid = 0;
 
@@ -188,9 +152,7 @@
 			return (!isNaN(n) && n >= 0 && n <= 6) ? n : null;
 		}
 
-		// Intl gives typographically-correct names ("juin", "lun."), but chrome
-		// labels should read like an author wrote them: capitalized, no
-		// abbreviation periods. aria-labels keep the untouched Intl output.
+		// Capitalize + strip trailing periods for chrome labels; aria-labels keep raw Intl output.
 		function tidy(s, locale) {
 			if (!s) return s;
 			let out = s.replace(/\.+$/, '');
@@ -302,9 +264,8 @@
 					return { start: s, end: e };
 				},
 
-				// (Re)apply selection/today state to a day button. Selection and
-				// today are ARIA attributes (aria-selected / aria-current="date");
-				// range shape has no ARIA equivalent, so plain state classes.
+				// (Re)apply selection/today to a day button — ARIA for selection/today,
+				// plain classes for range shape (no ARIA equivalent).
 				applyDayState(btn, date) {
 					btn.classList.remove('range-start', 'range-end', 'in-range');
 					btn.removeAttribute('aria-selected');
@@ -331,10 +292,7 @@
 
 				select(date) {
 					if (!date || this.isDisabled(date)) return;
-					// Keep the viewed months as-is when the picked date is already
-					// visible (matters in multi-month: clicking a day in the 2nd
-					// month must not scroll it into the 1st). Only jump when the
-					// date falls outside the visible [view.m … view.m+count-1] window.
+					// Jump the view only when the picked date is outside the visible month window.
 					const count = Math.max(1, this.monthCount || 1);
 					const idx = (date.getFullYear() * 12 + date.getMonth()) - (this.view.y * 12 + (this.view.m - 1));
 					if (idx < 0 || idx >= count) this.view = { y: date.getFullYear(), m: date.getMonth() + 1 };
@@ -361,8 +319,7 @@
 					this.selected = date;
 					if (this.withTime) this.timeSet = true;
 					this.syncOut(); this.bump(); this.render();
-					// With a time control, keep the dropdown open so the user can set
-					// the time after picking the day.
+					// With a time control, stay open so the user can set the time.
 					if (this.mode === 'menu' && !this.withTime) this.close();
 				},
 
@@ -418,17 +375,13 @@
 					const disp = this.displayValue();
 					if (this.field && this.field.tagName === 'INPUT' && this.field.type !== 'hidden') {
 						this.field.value = disp;
-						// Alpine's own x-model on the input writes the RAW model value
-						// into it during the same reactive flush — re-assert the
-						// human-readable display after that write settles.
+						// Re-assert the display after x-model writes the raw value back this flush.
 						if (this.field.hasAttribute('x-model')) {
 							const f = this.field;
 							setTimeout(() => { f.value = this.displayValue(); }, 0);
 						}
 					} else if (this.field && !this.field.firstElementChild) {
-						// Text-only triggers swap their text for the selection.
-						// Triggers with element children (icons, custom layout) own
-						// their content — authors bind $date(id) for display.
+						// Text-only triggers swap their text; triggers with element children own theirs.
 						this.field.textContent = disp || this.fieldPlaceholder;
 					}
 				},
@@ -467,13 +420,8 @@
 					}
 				},
 
-				// Only the plugin-generated dropdown (for an <input> field, which
-				// can't carry popovertarget without becoming a button) is opened
-				// here. We still fire native showPopover() — so the menu rides the
-				// reset.css popover transitions, dropdown.css anchor positioning
-				// (anchor-name/position-anchor are wired in wireField), light-
-				// dismiss, and nested-popover cascade. Authored <div>/<menu>/
-				// <dialog> calendars are inline; native HTML owns their visibility.
+				// Only the plugin-generated dropdown opens here; native showPopover() rides
+				// the reset.css/dropdown.css popover wiring. Authored calendars are inline.
 				open() {
 					if (this.mode !== 'menu') return;
 					this.viewMode = 'days';
@@ -718,17 +666,10 @@
 			return wrap;
 		}
 
-		/* ---- Time of day ---------------------------------------------
-		 * No native time input (its picker UI is unstylable). Two shapes:
-		 *  • Standalone (timeOnly): the dropdown IS the time picker, so the
-		 *    hour/minute/(AM-PM) columns render inline — no nested menu. Now and
-		 *    Clear (configurable) sit in the actions column.
-		 *  • Date+time: a ghost row of typed segments inside the calendar, with a
-		 *    columns picker opened by a popovertarget chevron. That menu is
-		 *    appended to <body> so the calendar's overflow can't clip it, yet the
-		 *    in-calendar invoker keeps it nested (it won't dismiss the calendar).
-		 * setTime never triggers a full re-render (that would blur the segments).
-		 * ---------------------------------------------------------------- */
+		/* ---- Time of day — no native time input (unstylable). Standalone: columns
+		 * render inline in the dropdown. Date+time: typed segments + a body-appended
+		 * columns menu (nested under an in-calendar invoker). setTime avoids a full
+		 * re-render to keep segment focus. */
 		function renderTime(state, shell, locale, ui) {
 			const h12 = uses12h(locale);
 			const cur = () => { const [h, mi] = state.time.split(':').map(Number); return { h: h || 0, mi: mi || 0 }; };
@@ -823,9 +764,8 @@
 			if (h12) { apBtn = document.createElement('button'); apBtn.type = 'button'; apBtn.setAttribute('aria-label', 'AM or PM'); fieldBox.appendChild(apBtn); }
 			segs = { hIn, mIn, apBtn };
 
-			// Columns menu — auto popover appended to <body> so the calendar's
-			// overflow can't clip it. The popovertarget chevron lives inside the
-			// calendar, so the menu nests under it (won't dismiss it on interaction).
+			// Columns menu — body-appended popover so the calendar's overflow can't clip it,
+			// yet nests under the in-calendar invoker (won't dismiss the calendar).
 			const menu = buildColumns(document.createElement('menu'), false);
 			menu.setAttribute('popover', '');
 			menu.id = 'mnfst-dp-time-' + (++_uid);
@@ -839,8 +779,7 @@
 			trigger.setAttribute('popovertarget', menu.id);
 			trigger.setAttribute('aria-label', ui.time);
 			fieldBox.appendChild(trigger);
-			// The "Time" label is a native invoker too: label activation forwards
-			// the click to its associated button, whose popovertarget opens the menu.
+			// The "Time" label is an invoker too (htmlFor forwards activation to the button).
 			lab.htmlFor = trigger.id;
 
 			const timeAnchor = '--datepicker-time-' + _uid;
@@ -961,11 +900,8 @@
 		}
 
 		/* ---- Config: the directive's value --------------------------- */
-		// An object value is reactive config: { months, min, max, disabled,
-		// presets }. min/max also read from the element's native attributes
-		// (an input's own min/max are semantic). Modal/dropdown opening of
-		// authored calendars is native HTML's job (popovertarget), so the value
-		// is no longer used to link a field to a calendar by id.
+		// An object value is reactive config: { months, min, max, disabled, presets }.
+		// min/max also read the element's native attributes.
 		function applyAttrConfig(state, el) {
 			const min = el.getAttribute('min');
 			const max = el.getAttribute('max');
@@ -990,14 +926,8 @@
 				if (dirty) { state.bump(); if (state._mounted) state.render(); }
 			});
 		}
-		/* ---- Reactive chrome ------------------------------------------
-		 * Re-render when locale, direction, or the resolved `_ui` text actually
-		 * changes. An Alpine effect tracking $locale + the data store's version
-		 * heartbeat covers async locale-source reloads settling after a switch,
-		 * and `_ui` sources that finish loading post-mount. The resolved-output
-		 * comparison keeps high-frequency _dataVersion bumps (e.g. realtime
-		 * plugins) from re-rendering a calendar that didn't change.
-		 * ---------------------------------------------------------------- */
+		/* ---- Reactive chrome — re-render when locale, direction, or resolved `_ui`
+		 * text changes. Output comparison skips no-op _dataVersion bumps. */
 		function bindReactiveRender(state) {
 			if (state._uiEffectBound) return;
 			state._uiEffectBound = true;
@@ -1019,10 +949,7 @@
 			const read = Alpine.evaluateLater(el, modelExpr);
 			state.modelGet = (cb) => { let out; read(v => { out = v; if (cb) cb(v); }); return out; };
 			state.modelSet = (v) => { try { Alpine.evaluate(el, `${modelExpr} = ${JSON.stringify(v)}`); } catch (_) { } };
-			// React to external model changes. Compare against the full primary
-			// value (date+time when withTime) and re-sync the field display —
-			// syncOut writes the same value back to the model, which Alpine
-			// treats as a no-op, so this cannot loop.
+			// React to external model changes; syncOut writes the same value back (no loop).
 			Alpine.effect(() => { read(v => { const iso = (v instanceof Date) ? D.toISO(v) : v; const cur = state._primaryValue(); if (typeof iso === 'string' && iso !== cur) { const tm = iso.match(/T(\d{2}:\d{2})/); if (tm) state.time = tm[1]; const d = D.fromISO(iso); state.selected = d; if (d) state.view = { y: d.getFullYear(), m: d.getMonth() + 1 }; state.bump(); if (state._mounted) { state.render(); state.syncOut(); } } }); });
 		}
 
@@ -1034,11 +961,9 @@
 			return menu;
 		}
 
-		/* ---- Wiring an <input>/<button> field to a generated dropdown -
-		 * The plugin generates and OWNS this menu's open/close because a text
-		 * <input> can't be a native popover invoker. It's a dropdown, not a
-		 * modal — authored <dialog>/<menu> calendars are inline and opened
-		 * natively (popovertarget). */
+		/* ---- Wiring an <input>/<button> field to a generated dropdown — the plugin
+		 * owns this menu's open/close (a text <input> can't be a native popover
+		 * invoker). Authored <dialog>/<menu> calendars are inline. */
 		function wireField(fieldEl, expression, modifiers, cleanup) {
 			const calendar = createDefaultMenu(fieldEl);
 			const state = (calendar._dateState = createState(calendar));
@@ -1048,8 +973,7 @@
 			else if (modifiers.includes('multiple')) state.selectionMode = 'multiple';
 			if (modifiers.includes('time')) state.withTime = true;
 
-			// Piggyback the input's authored type: it declares the format AND is
-			// the no-JS fallback (native picker). We capture it, then take over
+			// Piggyback the input's authored type (format + no-JS fallback), then take over
 			// with text+readonly so the styled calendar owns the UX.
 			if (fieldEl.tagName === 'INPUT') {
 				const authored = (fieldEl.getAttribute('type') || '').toLowerCase();
@@ -1060,19 +984,15 @@
 				fieldEl.readOnly = true; fieldEl.autocomplete = 'off';
 			} else {
 				applyAttrConfig(state, fieldEl);
-				// Text-only triggers: the authored text is the placeholder the
-				// selection swaps in and out of. Triggers with element children
-				// are left untouched (syncOut skips them).
+				// Text-only triggers: authored text is the placeholder the selection swaps.
 				state.fieldPlaceholder = fieldEl.firstElementChild ? '' : fieldEl.textContent.trim();
 			}
 
 			// Object config in the value.
 			bindConfigValue(state, fieldEl, expression);
 
-			// Synthesize a hidden input for form participation if the field carries
-			// a name. The name moves to the hidden (ISO) input — otherwise the
-			// visible field would submit its display text under the same key.
-			// No-JS fallback is unaffected: this only runs once the plugin has.
+			// Move the name onto a synthesized hidden (ISO) input so the form submits the
+			// value, not the display text.
 			const nameAttr = fieldEl.getAttribute('name');
 			if (nameAttr && !state.hiddenInput) {
 				const hidden = document.createElement('input');
@@ -1092,10 +1012,8 @@
 			// Also resolve $date(fieldId) when the calendar is an auto-generated menu.
 			if (fieldEl.id) _registry[fieldEl.id] = state.api;
 
-			// CSS anchor positioning (same wiring as the dropdowns plugin): the
-			// field is the anchor, dropdown.css positions the menu bottom-start
-			// with auto-flip fallbacks. We only fire showPopover() on click since
-			// a text <input> can't carry popovertarget.
+			// CSS anchor positioning (as in the dropdowns plugin); showPopover() on click
+			// since a text <input> can't carry popovertarget.
 			const anchorName = '--datepicker-' + (++_uid);
 			fieldEl.style.setProperty('anchor-name', `${anchorName}, var(--co-anchor, --no-anchor)`);
 			fieldEl.style.setProperty('--trigger-anchor', anchorName);
@@ -1106,8 +1024,7 @@
 			calendar.addEventListener('toggle', (e) => fieldEl.setAttribute('aria-expanded', e.newState === 'open' ? 'true' : 'false'));
 			fieldEl.addEventListener('click', () => state.open());
 
-			// Reactive chrome re-render (locale, direction, _ui). Auto-generated
-			// menus never run the calendar-element path, so wire it here too.
+			// Reactive chrome re-render (locale, direction, _ui).
 			bindReactiveRender(state);
 
 			if (cleanup) cleanup(() => {
@@ -1128,9 +1045,7 @@
 				return;
 			}
 
-			// Authored calendar — <div>, <menu popover>, <dialog popover>. Always
-			// inline: the plugin renders into it; native HTML owns any
-			// open/close (popovertarget, light-dismiss).
+			// Authored calendar (<div>/<menu>/<dialog>) — always inline; native HTML owns open/close.
 			const state = el._dateState || (el._dateState = createState(el));
 			state.mode = 'inline';
 			if (modifiers.includes('range')) state.selectionMode = 'range';

package/lib/manifest.dropdowns.js

@@ -1,18 +1,14 @@
 /* Manifest Dropdowns */
 
-// Track the user's most recent input modality so we only move focus into a menu
-// (and surface a :focus-visible ring) for keyboard opens. Capture-phase so we
-// see the event before any handler can stop it. This mirrors the heuristic the
-// browser uses for :focus-visible, but lets us decide whether to focus at all.
+// Most recent input modality, so we only move focus into a menu for keyboard opens.
+// Capture-phase so no handler can stop it first.
 let lastInputModality = 'mouse';
 document.addEventListener('keydown', () => { lastInputModality = 'keyboard'; }, true);
 document.addEventListener('pointerdown', () => { lastInputModality = 'mouse'; }, true);
 
-// Initialize plugin when either DOM is ready or Alpine is ready
 function initializeDropdownPlugin() {
-    // Ensure Alpine.js context exists for directives to work. Keep the scope
-    // empty — seeding properties here collides with author state and the
-    // tabs plugin's page-level `tab` property.
+    // Ensure an Alpine context exists. Keep the scope empty — seeding properties
+    // collides with author state and the tabs plugin's `tab` property.
     function ensureAlpineContext() {
         const body = document.body;
         if (!body.hasAttribute('x-data')) {
@@ -186,14 +182,9 @@ function initializeDropdownPlugin() {
                         el.addEventListener('keydown', (e) => { if (e.key === 'Enter' || e.key === ' ') pointMenuHere(); });
                     }
 
-                    // ----- A11y wiring (WAI-ARIA Menu Button pattern) -----
-                    // The trigger needs `aria-haspopup="menu"`, `aria-controls`, and a
-                    // dynamic `aria-expanded` that follows the popover's open state.
-                    // The menu element gets `role="menu"` and each list item gets
-                    // `role="menuitem"` so screen readers announce the relationship.
-                    //
-                    // We don't apply these for `.context` dropdowns invoked by right-
-                    // click — they're not button-triggered popups in the APG sense.
+                    // A11y wiring (WAI-ARIA Menu Button): trigger gets aria-haspopup/
+                    // controls/expanded, menu gets role=menu, items role=menuitem. Skipped
+                    // for .context (right-click) — not button-triggered popups per APG.
                     if (!modifiers.includes('context')) {
                         if (!menu.id) menu.id = 'mnfst-dropdown-' + Math.random().toString(36).slice(2, 9);
                         el.setAttribute('aria-haspopup', 'menu');
@@ -257,9 +248,7 @@ function initializeDropdownPlugin() {
                             if (menu.matches(':popover-open')) menu.hidePopover();
                         };
 
-                        // Bind the right-click trigger once per element. Without
-                        // the guard, reprocessing (router re-walks, re-init) would
-                        // stack duplicate handlers.
+                        // Bind once per element (reprocessing would stack duplicates).
                         if (!el.__mnfstContextTriggerBound) {
                             el.__mnfstContextTriggerBound = true;
                             el.addEventListener('contextmenu', (e) => {
@@ -291,10 +280,8 @@ function initializeDropdownPlugin() {
                             });
                         }
 
-                        // Document-level dismiss listeners are GLOBAL — re-binding
-                        // them on every reprocess leaks listeners on `document`.
-                        // Bind once per menu, tied to an AbortController so they
-                        // share one removable signal.
+                        // Document-level dismiss listeners are global — bind once per
+                        // menu via an AbortController so reprocessing can't leak them.
                         if (!menu.__mnfstContextDismissBound) {
                             menu.__mnfstContextDismissBound = true;
                             const ctxAbort = new AbortController();
@@ -394,14 +381,11 @@ function initializeDropdownPlugin() {
                             if (firstLi && !menu.querySelector('button, [href], input, select, textarea, [tabindex="0"]')) {
                                 firstLi.setAttribute('tabindex', '0');
                                 if (lastInputModality === 'keyboard') {
-                                    // Keyboard open (APG menu pattern): focus the first item;
-                                    // :focus-visible correctly paints the ring.
+                                    // Keyboard open: focus the first item (rings correctly).
                                     firstLi.focus();
                                 } else {
-                                    // Pointer open: park focus on the menu itself so arrow
-                                    // keys still enter the list, without forcing a
-                                    // focus-visible ring on an item the user didn't reach
-                                    // by keyboard.
+                                    // Pointer open: park focus on the menu so arrow keys enter
+                                    // the list without ringing an item the user didn't reach.
                                     if (!menu.hasAttribute('tabindex')) menu.setAttribute('tabindex', '-1');
                                     menu.focus();
                                 }
@@ -446,11 +430,9 @@ function initializeDropdownPlugin() {
     });
 }
 
-// Track initialization to prevent duplicates
 let dropdownPluginInitialized = false;
 
-// True once Alpine has completed its initial DOM walk. Listener is bound at
-// module load so we never miss the event, whatever the script order.
+// True once Alpine finished its initial walk. Bound at load so we never miss it.
 let alpineHasWalked = false;
 document.addEventListener('alpine:initialized', () => { alpineHasWalked = true; });
 
@@ -465,13 +447,10 @@ function ensureDropdownPluginInitialized() {
     dropdownPluginInitialized = true;
     initializeDropdownPlugin();
 
-    // Only walk existing [x-dropdown] subtrees ourselves when Alpine has ALREADY
-    // finished its initial walk (i.e. this plugin loaded late). In the normal
-    // flow we register the directive during `alpine:init`, before Alpine's one
-    // boot walk — so Alpine processes every dropdown with all sibling directives
-    // (x-icon, x-tooltip, …) already registered. Walking here during boot would
-    // re-init those subtrees before the other directives exist, permanently
-    // dropping nested plugin content (e.g. a trailing x-icon in a menu button).
+    // Walk existing [x-dropdown] subtrees only if Alpine already finished its boot
+    // walk (late load). During boot, let Alpine's own walk handle them with all
+    // sibling directives registered — walking here would drop nested plugin content
+    // (e.g. a trailing x-icon in a menu button).
     if (alpineHasWalked && typeof window.Alpine.initTree === 'function') {
         document.querySelectorAll('[x-dropdown]').forEach(el => {
             if (!el.__x) {