phoenix_duskmoon 10.0.3 → 10.0.5

package/CHANGELOG.md

@@ -1,3 +1,41 @@
+# [10.0.5](https://github.com/duskmoon-dev/phoenix-duskmoon-ui/compare/v10.0.4...v10.0.5) (2026-10-18)
+
+### Added
+
+- Add `dm_split_pane` and the public `DuskmoonSplitPane` hook for pointer and
+  keyboard resizing, accessible separator ranges, container-aware bounds and
+  stacked panes on narrow containers, resolving [#203](https://github.com/duskmoon-dev/phoenix-duskmoon-ui/issues/203).
+
+### Fixed
+
+- Expose opt-in left-menu user collapse events and an external state-setting
+  event. Support host-owned collapse state without remounting sticky menus or
+  replaying stale state during active-page updates, resolving [#204](https://github.com/duskmoon-dev/phoenix-duskmoon-ui/issues/204).
+- Keep session storage in the host application and preserve the default
+  client-owned and optional localStorage behavior.
+
+# [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/css/phoenix_duskmoon.css

@@ -12,6 +12,7 @@
 @import "@duskmoon-dev/core/themes/moonlight";
 @import "@duskmoon-dev/core/components";
 @import "./element-theme-bridge.css";
+@import "./split-pane.css";
 
 /* CSS Art — decorative/animated visual effects from @duskmoon-dev/css-art */
 @import "@duskmoon-dev/css-art/dist/art/atom.css";

package/assets/css/split-pane.css

@@ -0,0 +1,42 @@
+/* Native HEEx layout and interaction states; Core owns the divider appearance. */
+@layer components {
+  .dm-split-pane {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    min-width: 0;
+    min-height: 0;
+  }
+
+  .dm-split-pane[data-split-pane-stacked="false"] {
+    grid-template-columns: var(--dm-split-pane-width) 16px minmax(0, 1fr);
+  }
+
+  .dm-split-pane-primary,
+  .dm-split-pane-secondary {
+    min-width: 0;
+    min-height: 0;
+    overflow: auto;
+  }
+
+  .dm-split-pane > .dm-split-pane-handle {
+    width: 16px;
+    margin: 0;
+    cursor: col-resize;
+    touch-action: none;
+    user-select: none;
+  }
+
+  .dm-split-pane > .dm-split-pane-handle[hidden] {
+    display: none;
+  }
+
+  .dm-split-pane-handle:focus-visible {
+    outline: 2px solid var(--color-primary);
+    outline-offset: -2px;
+  }
+
+  .dm-split-pane[data-split-pane-dragging] {
+    cursor: col-resize;
+    user-select: none;
+  }
+}

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,18 @@ 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>;
+
+/** User collapse_event detail emitted by dm_left_menu. */
+export interface LeftMenuCollapseDetail {
+	id: string;
+	collapsed: boolean;
+}
+
+/** Synchronizes active-page and controlled collapse state with the sticky left-menu child. */
+export declare const DuskmoonLeftMenuNavigation: LiveViewHook<HTMLElement>;
+
+/** Pointer and keyboard pane sizing retained across LiveView patches. */
+export declare const DuskmoonSplitPane: LiveViewHook<HTMLElement>;

package/assets/js/hooks/index.js

@@ -23,13 +23,19 @@
  * - 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
+ * - DuskmoonSplitPane: Accessible client-owned split-pane resizing
  */
 
 // 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";
+export { DuskmoonSplitPane } from "./split_pane.js";

package/assets/js/hooks/left_menu.js

@@ -0,0 +1,220 @@
+const navigationKinds = new Set(["redirect", "patch", "initial"]);
+
+/** Collapse integration, group state, and scroll restoration for dm_left_menu. */
+export const DuskmoonLeftMenu = {
+	mounted() {
+		this.menuWindow = this.el.ownerDocument.defaultView;
+		this.collapsed = this.el.dataset.collapsed === "true";
+		this.lastServerCollapsed = this.el.dataset.serverCollapsed;
+		this.groupStates = new Map();
+		this.navigationScrollTop = null;
+		this.scrollTop = this.menuScroller().scrollTop;
+		this.captureGroups();
+
+		try {
+			const stored =
+				this.lastServerCollapsed === undefined && 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;
+			this.setMenuCollapsed(!this.collapsed);
+			try {
+				if (
+					this.el.dataset.serverCollapsed === undefined &&
+					this.el.dataset.storageKey
+				) {
+					this.menuWindow.localStorage.setItem(
+						this.el.dataset.storageKey,
+						String(this.collapsed),
+					);
+				}
+			} catch {
+				// Persistence is optional.
+			}
+			if (this.el.dataset.collapseEvent) {
+				this.el.dispatchEvent(
+					new this.menuWindow.CustomEvent(this.el.dataset.collapseEvent, {
+						bubbles: true,
+						detail: { id: this.el.id, collapsed: this.collapsed },
+					}),
+				);
+			}
+		};
+		this.handleSetCollapsed = (event) => {
+			if (
+				event.target !== this.el ||
+				typeof event.detail?.collapsed !== "boolean"
+			)
+				return;
+			this.setMenuCollapsed(event.detail.collapsed);
+		};
+		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.el.addEventListener(
+			"duskmoon:left-menu:set-collapsed",
+			this.handleSetCollapsed,
+		);
+		this.menuWindow.addEventListener(
+			"phx:page-loading-start",
+			this.handleNavigationStart,
+		);
+		this.menuWindow.addEventListener(
+			"phx:page-loading-stop",
+			this.handleNavigationStop,
+		);
+		this.applyMenuState();
+	},
+
+	setMenuCollapsed(collapsed) {
+		const scrollTop = this.navigationScrollTop ?? this.menuScroller().scrollTop;
+		if (!this.collapsed && collapsed) this.captureGroups();
+		this.collapsed = collapsed;
+		this.applyMenuState();
+		this.restoreMenuScroll(scrollTop);
+	},
+
+	syncServerCollapsed(force = false) {
+		const value = this.el.dataset.serverCollapsed;
+		if (
+			(value !== "true" && value !== "false") ||
+			(!force && value === this.lastServerCollapsed)
+		)
+			return;
+		this.lastServerCollapsed = value;
+		this.setMenuCollapsed(value === "true");
+	},
+
+	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.syncServerCollapsed();
+		this.restoreMenuScroll(this.navigationScrollTop ?? this.scrollTop);
+	},
+
+	reconnected() {
+		this.applyMenuState();
+		this.syncServerCollapsed(true);
+		if (this.navigationScrollTop !== null) {
+			this.restoreMenuScroll(this.navigationScrollTop);
+		}
+	},
+
+	destroyed() {
+		this.el.removeEventListener("click", this.handleMenuClick);
+		this.el.removeEventListener(
+			"duskmoon:left-menu:set-collapsed",
+			this.handleSetCollapsed,
+		);
+		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,100 @@
+/** 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.lastCollapse = null;
+		this.syncActiveNav();
+		this.syncCollapse();
+	},
+	updated() {
+		this.syncActiveNav();
+		this.syncCollapse();
+	},
+	reconnected() {
+		this.lastNavigation = null;
+		this.navigationRequest = null;
+		this.lastCollapse = null;
+		this.syncActiveNav();
+		this.syncCollapse();
+	},
+	syncCollapse() {
+		if (this.navigationDestroyed) return;
+		const { sidebarId, collapseState } = this.el.dataset;
+		const target = sidebarId
+			? this.el.ownerDocument.getElementById(sidebarId)
+			: null;
+		if (!target || (collapseState !== "true" && collapseState !== "false")) {
+			this.lastCollapse = null;
+			return;
+		}
+		if (
+			this.lastCollapse?.target === target &&
+			this.lastCollapse.collapseState === collapseState
+		)
+			return;
+		this.lastCollapse = { target, collapseState };
+		target.dispatchEvent(
+			new target.ownerDocument.defaultView.CustomEvent(
+				"duskmoon:left-menu:set-collapsed",
+				{
+					detail: { collapsed: collapseState === "true" },
+				},
+			),
+		);
+	},
+	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;
+		this.lastCollapse = null;
+	},
+};

package/assets/js/hooks/split_pane.js

@@ -0,0 +1,125 @@
+/** Client-owned horizontal pane sizing; no resize events are sent to LiveView. */
+export const DuskmoonSplitPane = {
+	mounted() {
+		this.splitWindow = this.el.ownerDocument.defaultView;
+		this.preferredWidth = Number(this.el.dataset.initialWidth);
+		this.onSplitPointerDown = (event) => {
+			const handle = this.splitHandle();
+			if (
+				this.splitDrag || this.splitStacked || event.button !== 0 ||
+				!event.isPrimary || event.target.closest?.("[data-split-pane-handle]") !== handle
+			) return;
+			event.preventDefault();
+			handle.focus({ preventScroll: true });
+			this.splitDrag = {
+				pointerId: event.pointerId,
+				x: event.clientX,
+				width: this.currentWidth,
+				preferredWidth: this.preferredWidth,
+				direction: this.splitWindow.getComputedStyle(this.el).direction === "rtl" ? -1 : 1,
+				handle,
+			};
+			handle.setPointerCapture(event.pointerId);
+			this.el.dataset.splitPaneDragging = "true";
+		};
+		this.onSplitPointerMove = (event) => {
+			const drag = this.splitDrag;
+			if (!drag || event.pointerId !== drag.pointerId) return;
+			this.setSplitWidth(drag.width + (event.clientX - drag.x) * drag.direction);
+		};
+		this.onSplitPointerUp = (event) => {
+			if (event.pointerId === this.splitDrag?.pointerId) this.finishSplitDrag(false);
+		};
+		this.onSplitPointerCancel = (event) => {
+			if (event.pointerId === this.splitDrag?.pointerId) this.finishSplitDrag(true);
+		};
+		this.onSplitKeyDown = (event) => {
+			if (this.splitStacked || event.target !== this.splitHandle()) return;
+			const direction = this.splitWindow.getComputedStyle(this.el).direction === "rtl" ? -1 : 1;
+			const widths = {
+				ArrowLeft: this.currentWidth - 10 * direction,
+				ArrowRight: this.currentWidth + 10 * direction,
+				Home: this.splitMin,
+				End: this.splitMax,
+			};
+			if (!Object.hasOwn(widths, event.key)) return;
+			event.preventDefault();
+			this.finishSplitDrag(false);
+			this.setSplitWidth(widths[event.key]);
+		};
+		this.splitListeners = {
+			pointerdown: this.onSplitPointerDown,
+			pointermove: this.onSplitPointerMove,
+			pointerup: this.onSplitPointerUp,
+			pointercancel: this.onSplitPointerCancel,
+			lostpointercapture: this.onSplitPointerCancel,
+			keydown: this.onSplitKeyDown,
+		};
+		for (const [type, listener] of Object.entries(this.splitListeners)) {
+			this.el.addEventListener(type, listener);
+		}
+		this.splitObserver = new this.splitWindow.ResizeObserver(() => this.applySplitPane());
+		this.splitObserver.observe(this.el);
+		this.applySplitPane();
+	},
+
+	splitHandle() {
+		return this.el.querySelector(":scope > [data-split-pane-handle]");
+	},
+
+	setSplitWidth(width) {
+		this.preferredWidth = Math.max(this.splitMin, Math.min(this.splitMax, Math.round(width)));
+		this.applySplitPane();
+	},
+
+	applySplitPane() {
+		const { minWidth, maxWidth, minSecondaryWidth, stackAt } = this.el.dataset;
+		const style = this.splitWindow.getComputedStyle(this.el);
+		const available = this.el.clientWidth - (parseFloat(style.paddingLeft) || 0) -
+			(parseFloat(style.paddingRight) || 0);
+		this.splitMin = Number(minWidth);
+		const availableMax = Math.floor(available - 16 - Number(minSecondaryWidth));
+		this.splitMax = Math.max(this.splitMin, Math.min(Number(maxWidth), availableMax));
+		this.splitStacked = available < Number(stackAt) || availableMax < this.splitMin;
+		if (this.splitStacked && this.splitDrag) this.finishSplitDrag(true);
+		this.currentWidth = Math.max(this.splitMin, Math.min(this.splitMax, this.preferredWidth));
+		this.el.style.setProperty("--dm-split-pane-width", `${this.currentWidth}px`);
+		this.el.dataset.splitPaneStacked = String(this.splitStacked);
+		const handle = this.splitHandle();
+		handle.hidden = this.splitStacked;
+		handle.tabIndex = this.splitStacked ? -1 : 0;
+		handle.setAttribute("aria-valuemin", String(this.splitMin));
+		handle.setAttribute("aria-valuemax", String(this.splitMax));
+		handle.setAttribute("aria-valuenow", String(this.currentWidth));
+		handle.setAttribute("aria-valuetext", `${this.currentWidth} pixels`);
+	},
+
+	finishSplitDrag(cancelled, refresh = true) {
+		const drag = this.splitDrag;
+		if (!drag) return;
+		this.splitDrag = null;
+		if (cancelled) this.preferredWidth = drag.preferredWidth;
+		delete this.el.dataset.splitPaneDragging;
+		if (drag.handle.hasPointerCapture(drag.pointerId)) {
+			drag.handle.releasePointerCapture(drag.pointerId);
+		}
+		if (refresh) this.applySplitPane();
+	},
+
+	beforeUpdate() {
+		// Release capture before morphing, retaining the latest client-owned width.
+		this.finishSplitDrag(false);
+	},
+
+	updated() {
+		this.applySplitPane();
+	},
+
+	destroyed() {
+		this.finishSplitDrag(false, false);
+		this.splitObserver.disconnect();
+		for (const [type, listener] of Object.entries(this.splitListeners)) {
+			this.el.removeEventListener(type, listener);
+		}
+	},
+};

package/package.json

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