phoenix_duskmoon 10.0.3 → 10.0.4

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+# [10.0.4](https://github.com/duskmoon-dev/phoenix-duskmoon-ui/compare/v10.0.3...v10.0.4) (2026-10-16)
+
+### Added
+
+- Extend `dm_left_menu` with a collapsible icon rail, fixed header/footer, native
+  link tooltips and optional saved collapse preference.
+- Own persistent sidebar LiveViews and active-page synchronization through the
+  `sticky` data API, preserving scroll and group state across LiveView navigation,
+  browser history and reconnects. Document CSS sticky positioning and reload limits.
+
+### Changed
+
+- Use the public left-menu component for the Storybook Components gallery,
+  retaining all 68 destinations and their active states through LiveView navigation.
+- Keep the sidebar toggle visible below the app bar on narrow and short viewports,
+  and handle pagination, chip removal, chat sends and theme selection in the demos.
+
+### Validation
+
+- Cover component data contracts, persistent-child lifecycle, hook synchronization,
+  accessible icon rails, tooltips, every gallery route and interactive demo events.
+
 # [10.0.3](https://github.com/duskmoon-dev/phoenix-duskmoon-ui/compare/v10.0.2...v10.0.3) (2026-10-15)
 
 ### Fixed

package/assets/js/hooks/index.d.ts

@@ -3,7 +3,9 @@ export type HookEventPayload = unknown;
 export type HookEventCallback = (reply: unknown, ref: number) => void;
 
 /** The LiveView-owned context supplied as `this` to hook callbacks. */
-export interface LiveViewHookContext<ElementType extends HTMLElement = HTMLElement> {
+export interface LiveViewHookContext<
+	ElementType extends HTMLElement = HTMLElement,
+> {
 	readonly el: ElementType;
 	handleEvent(
 		event: string,
@@ -25,7 +27,9 @@ export interface LiveViewHookContext<ElementType extends HTMLElement = HTMLEleme
 /** A Phoenix LiveView hook definition object. */
 export interface LiveViewHook<ElementType extends HTMLElement = HTMLElement> {
 	mounted?(this: LiveViewHookContext<ElementType>): void;
+	beforeUpdate?(this: LiveViewHookContext<ElementType>): void;
 	updated?(this: LiveViewHookContext<ElementType>): void;
+	reconnected?(this: LiveViewHookContext<ElementType>): void;
 	destroyed?(this: LiveViewHookContext<ElementType>): void;
 }
 
@@ -46,3 +50,9 @@ export declare const PageHeader: LiveViewHook;
 
 /** Synchronizes an explicitly controlled native popover with LiveView state. */
 export declare const DuskmoonPopover: LiveViewHook<HTMLElement>;
+
+/** Preserves left-menu collapse, group, and scroll state across LiveView patches. */
+export declare const DuskmoonLeftMenu: LiveViewHook<HTMLElement>;
+
+/** Synchronizes active-page state with the persistent sticky left-menu child. */
+export declare const DuskmoonLeftMenuNavigation: LiveViewHook<HTMLElement>;

package/assets/js/hooks/index.js

@@ -23,13 +23,17 @@
  * - Spotlight: Keyboard shortcut (Cmd/Ctrl+K) for spotlight search
  * - PageHeader: Intersection observer for scroll-based effects
  * - DuskmoonPopover: Optional server-controlled native popover state
+ * - DuskmoonLeftMenu: Collapsible sidebar with persistent group and scroll state
+ * - DuskmoonLeftMenuNavigation: Active-page synchronization for sticky left menus
  */
 
 // Core hooks for custom element integration
-export { WebComponentHook, FormElementHook } from '../phoenix_duskmoon.js';
+export { WebComponentHook, FormElementHook } from "../phoenix_duskmoon.js";
 
 // Component-specific hooks
-export { ThemeSwitcher } from './theme_switcher.js';
-export { Spotlight } from './spotlight.js';
-export { PageHeader } from './page_header.js';
-export { DuskmoonPopover } from './duskmoon_popover.js';
+export { ThemeSwitcher } from "./theme_switcher.js";
+export { Spotlight } from "./spotlight.js";
+export { PageHeader } from "./page_header.js";
+export { DuskmoonPopover } from "./duskmoon_popover.js";
+export { DuskmoonLeftMenu } from "./left_menu.js";
+export { DuskmoonLeftMenuNavigation } from "./left_menu_navigation.js";

package/assets/js/hooks/left_menu.js

@@ -0,0 +1,172 @@
+const navigationKinds = new Set(["redirect", "patch", "initial"]);
+
+/** Client-owned collapse, group, and scroll state for dm_left_menu. */
+export const DuskmoonLeftMenu = {
+	mounted() {
+		this.menuWindow = this.el.ownerDocument.defaultView;
+		this.collapsed = this.el.dataset.collapsed === "true";
+		this.groupStates = new Map();
+		this.navigationScrollTop = null;
+		this.scrollTop = this.menuScroller().scrollTop;
+		this.captureGroups();
+
+		try {
+			const stored = this.el.dataset.storageKey
+				? this.menuWindow.localStorage.getItem(this.el.dataset.storageKey)
+				: null;
+			if (stored === "true" || stored === "false") {
+				this.collapsed = stored === "true";
+			}
+		} catch {
+			// Storage can be disabled; in-page toggling remains available.
+		}
+
+		this.handleMenuClick = (event) => {
+			const toggle = event.target.closest?.("[data-left-menu-toggle]");
+			if (!toggle || !this.el.contains(toggle)) return;
+			if (!this.collapsed) this.captureGroups();
+			this.collapsed = !this.collapsed;
+			this.applyMenuState();
+			try {
+				if (this.el.dataset.storageKey) {
+					this.menuWindow.localStorage.setItem(
+						this.el.dataset.storageKey,
+						String(this.collapsed),
+					);
+				}
+			} catch {
+				// Persistence is optional.
+			}
+		};
+		this.handleNavigationStart = ({ detail }) => {
+			if (!navigationKinds.has(detail?.kind)) return;
+			if (this.navigationScrollTop !== null) return;
+			this.navigationScrollTop = this.menuScroller().scrollTop;
+		};
+		this.handleNavigationStop = ({ detail }) => {
+			if (!navigationKinds.has(detail?.kind)) return;
+			if (this.navigationScrollTop === null) return;
+			this.restoreMenuScroll(this.navigationScrollTop);
+			// The new root's initial patch can still follow redirect stop.
+			if (detail.kind !== "redirect") this.navigationScrollTop = null;
+		};
+		this.el.addEventListener("click", this.handleMenuClick);
+		this.menuWindow.addEventListener(
+			"phx:page-loading-start",
+			this.handleNavigationStart,
+		);
+		this.menuWindow.addEventListener(
+			"phx:page-loading-stop",
+			this.handleNavigationStop,
+		);
+		this.applyMenuState();
+	},
+
+	menuScroller() {
+		return this.el.querySelector("[data-left-menu-scroll]");
+	},
+
+	captureGroups() {
+		for (const group of this.el.querySelectorAll("details[id]")) {
+			this.groupStates.set(group.id, group.open);
+		}
+	},
+
+	applyMenuState() {
+		this.el.dataset.collapsed = String(this.collapsed);
+		for (const toggle of this.el.querySelectorAll("[data-left-menu-toggle]")) {
+			toggle.setAttribute("aria-expanded", String(!this.collapsed));
+			const label = this.collapsed
+				? this.el.dataset.expandLabel
+				: this.el.dataset.collapseLabel;
+			toggle.setAttribute("aria-label", label);
+			toggle.setAttribute("title", label);
+		}
+		const ids = new Set();
+		for (const group of this.el.querySelectorAll("details[id]")) {
+			ids.add(group.id);
+			if (!this.groupStates.has(group.id)) {
+				this.groupStates.set(group.id, group.open);
+			}
+			group.open = this.collapsed || this.groupStates.get(group.id);
+		}
+		for (const id of this.groupStates.keys()) {
+			if (!ids.has(id)) this.groupStates.delete(id);
+		}
+		this.applyMenuTooltips();
+	},
+
+	applyMenuTooltips() {
+		for (const link of this.el.querySelectorAll("[data-left-menu-tooltip]")) {
+			const tooltipId = link.dataset.leftMenuTooltip;
+			const anchor = link.dataset.leftMenuAnchor;
+			const title = link.dataset.leftMenuTooltipTitle;
+			const descriptions = new Set(
+				(link.getAttribute("aria-describedby") || "")
+					.split(/\s+/)
+					.filter(Boolean),
+			);
+			const anchors = new Set(
+				link.style
+					.getPropertyValue("anchor-name")
+					.split(",")
+					.map((value) => value.trim())
+					.filter(Boolean),
+			);
+			if (this.collapsed) {
+				link.setAttribute("interestfor", tooltipId);
+				descriptions.add(tooltipId);
+				if (anchor) anchors.add(anchor);
+				if (title) link.setAttribute("title", title);
+			} else {
+				if (link.getAttribute("interestfor") === tooltipId)
+					link.removeAttribute("interestfor");
+				descriptions.delete(tooltipId);
+				anchors.delete(anchor);
+				if (link.getAttribute("title") === title) link.removeAttribute("title");
+				const surface = this.el.ownerDocument.getElementById(tooltipId);
+				if (surface?.hidePopover && surface.matches(":popover-open"))
+					surface.hidePopover();
+			}
+			if (descriptions.size)
+				link.setAttribute("aria-describedby", [...descriptions].join(" "));
+			else link.removeAttribute("aria-describedby");
+			if (anchors.size)
+				link.style.setProperty("anchor-name", [...anchors].join(", "));
+			else link.style.removeProperty("anchor-name");
+		}
+	},
+
+	restoreMenuScroll(top) {
+		this.menuScroller().scrollTo({ top, behavior: "instant" });
+	},
+
+	beforeUpdate() {
+		if (!this.collapsed) this.captureGroups();
+		this.scrollTop = this.navigationScrollTop ?? this.menuScroller().scrollTop;
+	},
+
+	updated() {
+		this.applyMenuState();
+		this.restoreMenuScroll(this.navigationScrollTop ?? this.scrollTop);
+	},
+
+	reconnected() {
+		this.applyMenuState();
+		if (this.navigationScrollTop !== null) {
+			this.restoreMenuScroll(this.navigationScrollTop);
+		}
+	},
+
+	destroyed() {
+		this.el.removeEventListener("click", this.handleMenuClick);
+		this.menuWindow.removeEventListener(
+			"phx:page-loading-start",
+			this.handleNavigationStart,
+		);
+		this.menuWindow.removeEventListener(
+			"phx:page-loading-stop",
+			this.handleNavigationStop,
+		);
+	},
+};

package/assets/js/hooks/left_menu_navigation.js

@@ -0,0 +1,69 @@
+/** Synchronizes the page's active item with its sticky dm_left_menu child. */
+export const DuskmoonLeftMenuNavigation = {
+	mounted() {
+		this.navigationDestroyed = false;
+		this.lastNavigation = null;
+		this.navigationRequest = null;
+		this.syncActiveNav();
+	},
+	updated() {
+		this.syncActiveNav();
+	},
+	reconnected() {
+		this.lastNavigation = null;
+		this.navigationRequest = null;
+		this.syncActiveNav();
+	},
+	syncActiveNav() {
+		if (this.navigationDestroyed) return;
+		const { sidebarId, activeNav } = this.el.dataset;
+		const target = sidebarId
+			? this.el.ownerDocument.getElementById(sidebarId)
+			: null;
+		if (!target || typeof activeNav !== "string") {
+			this.lastNavigation = null;
+			this.navigationRequest = null;
+			return;
+		}
+		if (
+			this.lastNavigation?.sidebarId === sidebarId &&
+			this.lastNavigation.target === target &&
+			this.lastNavigation.activeNav === activeNav
+		)
+			return;
+		this.lastNavigation = { sidebarId, target, activeNav };
+		const request = {};
+		this.navigationRequest = request;
+		const failed = () => {
+			if (!this.navigationDestroyed && this.navigationRequest === request) {
+				this.lastNavigation = null;
+				this.navigationRequest = null;
+			}
+		};
+		try {
+			Promise.resolve(
+				this.pushEventTo(target, "set_active_nav", { active_nav: activeNav }),
+			)
+				.then((results) => {
+					if (
+						!Array.isArray(results) ||
+						!results.length ||
+						results.some(
+							(result) =>
+								result?.status !== "fulfilled" ||
+								result.value?.reply?.status !== "ok",
+						)
+					)
+						failed();
+				})
+				.catch(failed);
+		} catch {
+			failed();
+		}
+	},
+	destroyed() {
+		this.navigationDestroyed = true;
+		this.lastNavigation = null;
+		this.navigationRequest = null;
+	},
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phoenix_duskmoon",
-  "version": "10.0.3",
+  "version": "10.0.4",
   "type": "module",
   "exports": {
     ".": "./priv/static/assets/js/phoenix_duskmoon.js",