@getdom/studio 0.1.1 → 0.2.1

package/src/pages/components/dialog/DomDialog.vue

@@ -1,5 +1,5 @@
 <script setup>
-import { computed, onMounted, ref, useId, watch } from 'vue';
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, useId, useSlots, watch } from 'vue';
 
 defineOptions({
 	__doc: {
@@ -9,28 +9,30 @@ defineOptions({
 		slots: [
 			{ name: 'trigger', description: 'Optional. Element that opens the dialog when clicked — omit when using v-model, a template ref, or commandfor on an external button.' },
 			{ name: '(default)', description: 'Dialog body — rendered inside the card below the title and description.' },
-			{ name: 'header', payload: '{ title, description, titleId, descriptionId }', description: 'Replace the default title and description block. Apply the provided IDs to custom heading and description elements to preserve the dialog accessibility relationships.' },
+			{ name: 'header', payload: '{ title, description, titleId, descriptionId, companionOpen, companionMode, companionTriggerProps, toggleCompanion }', description: 'Replace the default title and description block. Apply the provided IDs to custom heading and description elements to preserve the dialog accessibility relationships. Companion helpers wire an in-dialog toggle when the companion slot is present.' },
 			{ name: 'footer', description: 'Action buttons. Add `data-close` on a control to dismiss the dialog.' },
+			{ name: 'companion', payload: '{ open, mode, closeCompanion, toggleCompanion }', description: 'Optional contextual surface shown beside the dialog on wide screens and over it below companionBreakpoint.' },
 		],
 		events: [
 			{ name: 'update:modelValue', payload: '(open: boolean)', description: 'Emitted when the dialog opens or closes.' },
 			{ name: 'before-open', description: 'Emitted immediately before the dialog opens; prepare draft data or item snapshots here.' },
+			{ name: 'update:companionOpen', payload: '(open: boolean)', description: 'Emitted when the companion surface opens or closes.' },
 			{ name: 'close', description: 'Emitted when the dialog is dismissed.' },
 			{ name: 'close-complete', description: 'Emitted after the close transition completes; clear retained dialog data here.' },
 		],
 		keyboard: [
-			{ keys: 'Esc', action: 'Closes the topmost open dialog unless `static` is set.' },
+			{ keys: 'Esc', action: 'Closes an open companion first, then closes the dialog unless `static` is set.' },
 			{ keys: 'Tab / Shift+Tab', action: 'Focus stays within the dialog while open (native top-layer).' },
 			{ keys: 'Click backdrop', action: 'Dismisses the dialog unless `static` is set.' },
 		],
 	},
 });
 
-const dialogWidthClasses = {
-	sm: 'w-[min(calc(100vw-2rem),24rem)]',
-	md: 'w-[min(calc(100vw-2rem),28rem)]',
-	lg: 'w-[min(calc(100vw-2rem),44rem)]',
-	xl: 'w-[min(calc(100vw-2rem),56rem)]',
+const dialogWidthValues = {
+	sm: '24rem',
+	md: '28rem',
+	lg: '44rem',
+	xl: '56rem',
 };
 
 const props = defineProps({
@@ -83,24 +85,62 @@ const props = defineProps({
 		default: true,
 		_edit: { description: 'Show the footer region and default Close action when no footer slot is provided.' },
 	},
+	companionOpen: {
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Whether the optional companion slot is visible.' },
+	},
+	companionWidth: {
+		type: [String, Number],
+		default: '24rem',
+		_edit: { description: 'Desktop width of the companion surface.' },
+	},
+	companionBreakpoint: {
+		type: [String, Number],
+		default: '56.25rem',
+		_edit: { description: 'Viewport width at which the companion switches from a side-by-side surface to a covering dialog.' },
+	},
+	companionLabel: {
+		type: String,
+		default: 'Companion panel',
+		_edit: { description: 'Accessible name for the companion surface.' },
+	},
 });
-const emit = defineEmits(['update:modelValue', 'before-open', 'close', 'close-complete']);
+const emit = defineEmits(['update:modelValue', 'update:companionOpen', 'before-open', 'close', 'close-complete']);
 
 const root = ref(null);
+const mainPanel = ref(null);
+const companionPanel = ref(null);
+const slots = useSlots();
 const uniqueId = useId();
+const companionId = `dom-dialog-${uniqueId}-companion`;
 const titleId = computed(() => (props.title ? `dom-dialog-${uniqueId}-title` : ''));
 const descriptionId = computed(() => (props.description ? `dom-dialog-${uniqueId}-description` : ''));
-const dialogWidthClass = computed(() => dialogWidthClasses[props.size] || dialogWidthClasses.md);
+const hasCompanion = computed(() => Boolean(slots.companion));
+const companionActive = computed(() => hasCompanion.value && props.companionOpen);
+const companionOverlay = ref(false);
+const companionMode = computed(() => companionOverlay.value ? 'overlay' : 'beside');
+const companionTriggerProps = computed(() => ({
+	'aria-controls': companionId,
+	'aria-expanded': String(companionActive.value),
+	'aria-haspopup': companionOverlay.value ? 'dialog' : undefined,
+}));
+const dialogShellStyle = computed(() => ({
+	'--dom-dialog-panel-width': normalizeDialogDimension(props.width)
+		|| dialogWidthValues[props.size]
+		|| dialogWidthValues.md,
+	'--dom-dialog-companion-width': normalizeDialogDimension(props.companionWidth) || '24rem',
+}));
 const dialogPanelStyle = computed(() => {
-	const width = normalizeDialogDimension(props.width);
 	const height = normalizeDialogDimension(props.height);
 
 	return {
-		width: width || undefined,
 		height: height || undefined,
 		maxHeight: height || undefined,
 	};
 });
+let companionMediaQuery = null;
+let companionReturnFocus = null;
 
 /**
  * Normalize a CSS dimension prop into an inline style value.
@@ -114,6 +154,105 @@ function normalizeDialogDimension(value) {
 	return '';
 }
 
+/**
+ * Build the viewport query used to switch the companion into overlay mode.
+ *
+ * @returns {string} A max-width media query.
+ */
+function companionMediaQueryText() {
+	const breakpoint = normalizeDialogDimension(props.companionBreakpoint) || '56.25rem';
+	return `(max-width: ${breakpoint})`;
+}
+
+/**
+ * Synchronize the responsive companion mode from a MediaQueryList.
+ *
+ * @param {MediaQueryList|MediaQueryListEvent} query Current media-query state.
+ * @returns {void}
+ */
+function updateCompanionMode(query) {
+	companionOverlay.value = Boolean(query?.matches);
+}
+
+/**
+ * Replace the active companion breakpoint listener.
+ *
+ * @returns {void}
+ */
+function setupCompanionMediaQuery() {
+	teardownCompanionMediaQuery();
+	if (typeof window === 'undefined') return;
+	companionMediaQuery = window.matchMedia(companionMediaQueryText());
+	updateCompanionMode(companionMediaQuery);
+	companionMediaQuery.addEventListener('change', updateCompanionMode);
+}
+
+/**
+ * Remove the active companion breakpoint listener.
+ *
+ * @returns {void}
+ */
+function teardownCompanionMediaQuery() {
+	companionMediaQuery?.removeEventListener('change', updateCompanionMode);
+	companionMediaQuery = null;
+}
+
+/**
+ * Focus the preferred control inside the companion surface.
+ *
+ * @returns {void}
+ */
+function focusCompanion() {
+	const panel = companionPanel.value;
+	if (!panel) return;
+	const preferred = panel.querySelector('[autofocus], [data-companion-focus], textarea, input, select, button, [href], [tabindex]:not([tabindex="-1"])');
+	(preferred || panel).focus({ preventScroll: true });
+}
+
+/**
+ * Restore focus to the element that opened the companion when possible.
+ *
+ * @returns {void}
+ */
+function restoreCompanionFocus() {
+	const target = companionReturnFocus;
+	companionReturnFocus = null;
+	if (target instanceof HTMLElement && target.isConnected && !target.closest('[inert]')) {
+		target.focus({ preventScroll: true });
+		return;
+	}
+	mainPanel.value?.focus({ preventScroll: true });
+}
+
+/**
+ * Emit a controlled companion visibility update.
+ *
+ * @param {boolean} open Desired companion visibility.
+ * @returns {void}
+ */
+function setCompanionOpen(open) {
+	if (!hasCompanion.value) return;
+	emit('update:companionOpen', Boolean(open));
+}
+
+/**
+ * Close the companion without closing the parent dialog.
+ *
+ * @returns {void}
+ */
+function closeCompanion() {
+	setCompanionOpen(false);
+}
+
+/**
+ * Toggle the companion surface.
+ *
+ * @returns {void}
+ */
+function toggleCompanion() {
+	setCompanionOpen(!companionActive.value);
+}
+
 /**
  * Synchronize the headless dialog host with the controlled Vue model.
  *
@@ -156,6 +295,7 @@ function onHeadlessOpen(event) {
  */
 function onHeadlessClose(event) {
 	if (event.target !== root.value) return;
+	if (companionActive.value) setCompanionOpen(false);
 	emit('update:modelValue', false);
 	emit('close');
 }
@@ -171,21 +311,53 @@ function onHeadlessCloseComplete(event) {
 	emit('close-complete');
 }
 
+/**
+ * Let the companion consume Escape before the parent dialog closes.
+ *
+ * @param {CustomEvent<{ reason: string }>} event Cancellable headless close request.
+ * @returns {void}
+ */
+function onHeadlessRequestClose(event) {
+	if (event.target !== root.value) return;
+	if (event.detail?.reason !== 'escape' || !companionActive.value) return;
+	event.preventDefault();
+	closeCompanion();
+}
+
 onMounted(async () => {
 	await import('../../lib/headless/dialog.js');
+	setupCompanionMediaQuery();
 	root.value?.addEventListener('dom:before-open', onHeadlessBeforeOpen);
 	root.value?.addEventListener('dom:open', onHeadlessOpen);
+	root.value?.addEventListener('dom:request-close', onHeadlessRequestClose);
 	root.value?.addEventListener('dom:close', onHeadlessClose);
 	root.value?.addEventListener('dom:close-complete', onHeadlessCloseComplete);
 	if (props.modelValue) setOpen(true);
 });
 
 watch(() => props.modelValue, setOpen);
+watch(() => props.companionBreakpoint, setupCompanionMediaQuery);
+watch(() => props.companionOpen, async (open, previousOpen) => {
+	if (!hasCompanion.value || open === previousOpen) return;
+	if (open) {
+		companionReturnFocus = document.activeElement;
+		await nextTick();
+		focusCompanion();
+	} else {
+		await nextTick();
+		restoreCompanionFocus();
+	}
+});
+
+onBeforeUnmount(teardownCompanionMediaQuery);
 
 defineExpose({
 	open: () => setOpen(true),
 	close: () => setOpen(false),
 	toggle: () => root.value?.toggle(),
+	openCompanion: () => setCompanionOpen(true),
+	closeCompanion,
+	toggleCompanion,
 	get element() { return root.value; },
 });
 </script>
@@ -209,40 +381,76 @@ defineExpose({
 			<slot name="trigger" />
 		</span>
 		<div
-			class="skin-overlay flex max-h-[calc(100dvh-2rem)] flex-col overflow-hidden rounded-2xl p-6 outline-none"
-			:class="dialogWidthClass"
-			:style="dialogPanelStyle"
+			class="dom-dialog-shell"
+			:class="{ 'dom-dialog-shell--open': companionActive }"
+			:data-companion-mode="companionMode"
+			:style="dialogShellStyle"
 		>
-			<slot
-				name="header"
-				:title="title"
-				:description="description"
-				:title-id="titleId"
-				:description-id="descriptionId"
+			<div
+				ref="mainPanel"
+				class="skin-overlay flex min-w-0 flex-1 flex-col overflow-hidden rounded-2xl p-6 outline-none"
+				:style="dialogPanelStyle"
+				:inert="companionOverlay && companionActive"
+				:aria-hidden="companionOverlay && companionActive ? 'true' : undefined"
+				tabindex="-1"
 			>
-				<div v-if="title || description" class="shrink-0 space-y-2">
-					<h2 v-if="title" :id="titleId" class="text-lg font-semibold tracking-tight">{{ title }}</h2>
-					<p v-if="description" :id="descriptionId" class="text-sm text-muted-fg">{{ description }}</p>
-				</div>
-			</slot>
-			<div class="-mx-1 -mb-1 min-h-0 overflow-y-auto px-1 pb-1" :class="($slots.header || title || description) ? 'mt-3 pt-1' : '-mt-1 pt-1'">
-				<slot />
-			</div>
-			<div v-if="footer || $slots.footer" class="mt-6 flex shrink-0 items-center justify-end gap-2">
-				<slot name="footer">
-					<button
-						data-close
-						type="button"
-						class="skin-action inline-flex h-9 items-center rounded-full px-4 text-sm font-medium hover:opacity-90"
-					>Close</button>
+				<slot
+					name="header"
+					:title="title"
+					:description="description"
+					:title-id="titleId"
+					:description-id="descriptionId"
+					:companion-open="companionActive"
+					:companion-mode="companionMode"
+					:companion-trigger-props="companionTriggerProps"
+					:toggle-companion="toggleCompanion"
+				>
+					<div v-if="title || description" class="shrink-0 space-y-2">
+						<h2 v-if="title" :id="titleId" class="text-lg font-semibold tracking-tight">{{ title }}</h2>
+						<p v-if="description" :id="descriptionId" class="text-sm text-muted-fg">{{ description }}</p>
+					</div>
 				</slot>
+				<div class="-mx-1 -mb-1 min-h-0 flex-1 overflow-y-auto px-1 pb-1" :class="($slots.header || title || description) ? 'mt-3 pt-1' : '-mt-1 pt-1'">
+					<slot />
+				</div>
+				<div v-if="footer || $slots.footer" class="mt-6 flex shrink-0 items-center justify-end gap-2">
+					<slot name="footer">
+						<button
+							data-close
+							type="button"
+							class="skin-action inline-flex h-9 items-center rounded-full px-4 text-sm font-medium hover:opacity-90"
+						>Close</button>
+					</slot>
+				</div>
 			</div>
+			<Transition name="dom-dialog-companion">
+				<div v-if="hasCompanion" v-show="companionActive" class="dom-dialog-companion-track">
+					<aside
+						:id="companionId"
+						ref="companionPanel"
+						class="dom-dialog-companion skin-overlay"
+						:role="companionOverlay ? 'dialog' : 'region'"
+						:aria-modal="companionOverlay ? 'true' : undefined"
+						:aria-label="companionLabel"
+						tabindex="-1"
+					>
+						<slot
+							name="companion"
+							:open="companionActive"
+							:mode="companionMode"
+							:close-companion="closeCompanion"
+							:toggle-companion="toggleCompanion"
+						/>
+					</aside>
+				</div>
+			</Transition>
 		</div>
 	</dom-dialog>
 </template>
 
 <style scoped>
 .dom-dialog::part(dialog) {
+	width: 100vw;
 	opacity: 0;
 	transform: translateY(10px) scale(0.96);
 	transform-origin: center;
@@ -255,6 +463,100 @@ defineExpose({
 		display 240ms allow-discrete;
 }
 
+.dom-dialog-shell {
+	position: relative;
+	display: flex;
+	align-items: center;
+	gap: 0;
+	width: 100%;
+	max-width: var(--dom-dialog-panel-width);
+	margin-inline: auto;
+	transition: max-width 280ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.dom-dialog-shell--open[data-companion-mode="beside"] {
+	max-width: calc(var(--dom-dialog-panel-width) + var(--dom-dialog-companion-width) + 0.875rem);
+}
+
+.dom-dialog-companion-track {
+	display: flex;
+	flex: 0 0 calc(var(--dom-dialog-companion-width) + 0.875rem);
+	min-width: 0;
+	overflow: clip;
+}
+
+.dom-dialog-companion {
+	display: flex;
+	flex: 0 0 var(--dom-dialog-companion-width);
+	width: var(--dom-dialog-companion-width);
+	min-height: 20rem;
+	max-height: calc(100dvh - 2rem);
+	margin-left: 0.875rem;
+	overflow: hidden;
+	border-radius: 1rem;
+	outline: none;
+}
+
+.dom-dialog-companion-enter-active,
+.dom-dialog-companion-leave-active {
+	transition: flex-basis 280ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.dom-dialog-companion-enter-active .dom-dialog-companion,
+.dom-dialog-companion-leave-active .dom-dialog-companion {
+	transition:
+		opacity 180ms ease,
+		transform 280ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.dom-dialog-companion-enter-from,
+.dom-dialog-companion-leave-to {
+	flex-basis: 0;
+}
+
+.dom-dialog-companion-enter-from .dom-dialog-companion,
+.dom-dialog-companion-leave-to .dom-dialog-companion {
+	opacity: 0;
+	transform: translateX(2rem);
+}
+
+.dom-dialog-shell--open[data-companion-mode="overlay"] {
+	gap: 0;
+	max-width: var(--dom-dialog-panel-width);
+}
+
+[data-companion-mode="overlay"] .dom-dialog-companion-track {
+	position: absolute;
+	inset: 0;
+	z-index: 1;
+	display: flex;
+	overflow: hidden;
+}
+
+[data-companion-mode="overlay"] .dom-dialog-companion {
+	flex-basis: 100%;
+	width: auto;
+	min-height: 0;
+	max-height: none;
+	margin-left: 0;
+}
+
+[data-companion-mode="overlay"] .dom-dialog-companion-enter-from .dom-dialog-companion,
+[data-companion-mode="overlay"] .dom-dialog-companion-leave-to .dom-dialog-companion {
+	opacity: 1;
+	transform: translateX(100%);
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.dom-dialog-shell,
+	.dom-dialog-companion-enter-active,
+	.dom-dialog-companion-leave-active,
+	.dom-dialog-companion-enter-active .dom-dialog-companion,
+	.dom-dialog-companion-leave-active .dom-dialog-companion {
+		transition-duration: 0s;
+	}
+}
+
 .dom-dialog[open]::part(dialog) {
 	opacity: 1;
 	transform: none;

package/src/pages/components/icon-button/DomIconButton.vue

@@ -1,5 +1,6 @@
 <script setup>
 import { computed, useAttrs } from 'vue';
+import { buttonInteraction } from '../button/buttonStyles.js';
 
 defineOptions({
 	inheritAttrs: false,
@@ -55,6 +56,11 @@ const props = defineProps({
 		default: false,
 		_edit: { description: 'Show active/selected state.' },
 	},
+	pressed: {
+		type: Boolean,
+		default: false,
+		_edit: { description: 'Show native press feedback for an external activation, such as a keyboard shortcut. Does not represent toggle selection.' },
+	},
 	loading: {
 		type: Boolean,
 		default: false,
@@ -67,7 +73,6 @@ const props = defineProps({
 	},
 });
 const attrs = useAttrs();
-const interaction = 'select-none active:bg-[linear-gradient(rgb(0_0_0/6%)_0_0)] active:scale-[0.97] active:shadow-[inset_0_2px_4px_rgba(0,0,0,0.3)] motion-reduce:active:scale-100';
 
 const variants = {
 	ghost: 'text-muted-fg hover:bg-secondary hover:text-canvas-fg',
@@ -98,7 +103,7 @@ const iconSizes = {
 };
 
 const classes = computed(() => [
-	interaction,
+	buttonInteraction,
 	'inline-grid shrink-0 place-items-center rounded-full outline-none transition',
 	'focus-visible:ring-2 focus-visible:ring-ring/60 focus-visible:ring-offset-2 focus-visible:ring-offset-canvas',
 	props.active
@@ -137,6 +142,7 @@ const iconComponent = computed(() => (typeof props.icon === 'string' ? null : pr
 		:aria-pressed="active ? 'true' : undefined"
 		:aria-disabled="!isNativeButton && disabledState ? 'true' : undefined"
 		:data-active="active ? 'true' : null"
+		:data-pressed="pressed ? '' : undefined"
 		:disabled="isNativeButton && disabledState ? true : undefined"
 		:type="isNativeButton ? 'button' : undefined"
 	>

package/src/pages/components/menu-stack/DomMenuStack.vue

@@ -0,0 +1,111 @@
+<script setup>
+import { computed } from 'vue';
+import { RouterLink } from 'vue-router';
+import DomAppStack from '../../mobile/stack/DomAppStack.vue';
+import DomAppStackScreen from '../../mobile/stack/AppStackScreen.vue';
+import DomAppListItem from '../../mobile/list-item/DomAppListItem.vue';
+import { buildMenuScreens, hasMenuPage } from './menuTree.js';
+
+defineOptions({
+	__doc: {
+		name: 'Menu stack',
+		tag: '<DomMenuStack>',
+		description: 'Nested navigation that slides inside its container on mobile and desktop. Reuses App stack transitions, retained page state, scrolling, and focus. Each item has a unique id and label, plus children, a component and props, or a named slot for richer pages. Leaf items accept to or href, or emit select for application actions.',
+		slots: [
+			{ name: 'root', payload: '{ screen, stack }', description: 'Content above the root menu rows.' },
+			{ name: '(item.slot)', payload: '{ screen, stack }', description: 'Page content above child rows. Set an item’s slot to this slot name; components receive screen and stack props too.' },
+		],
+		events: [
+			{ name: 'select', payload: '(item)', description: 'A leaf was selected. Close the containing popover here if desired.' },
+			{ name: 'update:path', payload: '(path: string[])', description: 'Two-way stack path, starting with root.' },
+			{ name: 'navigate', payload: '({ path, previousPath, direction, screen, reason })', description: 'A contained page opened or returned.' },
+		],
+		keyboard: [
+			{ keys: 'Tab / Shift+Tab', action: 'Move between visible links, rows, Back, and custom page controls.' },
+			{ keys: 'Enter / Space', action: 'Activate a focused button. Enter follows links.' },
+		],
+		playground: { initial: { title: 'Workspace', items: [
+			{ id: 'account', label: 'Account', children: [{ id: 'preferences', label: 'Preferences', children: [{ id: 'language', label: 'English (UK)' }] }] },
+			{ id: 'help', label: 'Help' },
+		] } },
+	},
+});
+
+const props = defineProps({
+	items: { type: Array, default: () => [], _edit: { description: 'Nested items: unique id, label, description, meta, disabled, children, component, props, slot, to, or href. Page items open their children; use a leaf for a route or action.' } },
+	title: { type: String, default: 'Menu', _edit: { description: 'Root page heading.' } },
+	height: { type: String, default: 'min(24rem, calc(100dvh - 6rem))', _edit: { description: 'Bounded container height. Use 100% in an explicitly sized parent.' } },
+	path: { type: Array, default: null, _edit: { description: 'Controlled path of page ids starting with root. Bind with v-model:path.' } },
+	animate: { type: Boolean, default: true, _edit: { description: 'Enable sliding transitions; reduced-motion preferences are respected.' } },
+});
+const emit = defineEmits(['select', 'update:path', 'navigate']);
+const screens = computed(() => buildMenuScreens(props.items, props.title));
+
+/**
+ * Opens a contained page or reports a leaf selection to the application.
+ * @param {object} item Menu item activated by pointer or keyboard.
+ * @param {object} stack Shared App stack navigation helpers.
+ */
+function activate(item, stack) {
+	if (item.disabled) return;
+	if (hasMenuPage(item)) stack.push(item.id);
+	else emit('select', item);
+}
+
+/** Returns a native button for pages/actions or the appropriate link component. */
+function rowElement(item) {
+	if (item.disabled || hasMenuPage(item)) return 'button';
+	return item.to ? RouterLink : item.href ? 'a' : 'button';
+}
+/**
+ * Supplies only attributes owned by the chosen row element. In particular, an
+ * undefined href must not fall through to RouterLink and erase its resolved URL.
+ */
+function rowAttributes(item) {
+	if (item.disabled || hasMenuPage(item)) return { type: 'button', disabled: item.disabled || undefined };
+	if (item.to) return { to: item.to };
+	if (item.href) return { href: item.href };
+	return { type: 'button' };
+}
+
+</script>
+
+<template>
+	<DomAppStack
+		data-dom-menu-stack
+		class="rounded-lg border border-border [--dom-safe-area-top:0px] [--dom-safe-area-bottom:0px] [--dom-safe-area-left:0px] [--dom-safe-area-right:0px]"
+		root="root"
+		layout="mobile"
+		:height="height"
+		:path="path"
+		:animate="animate"
+		mobile-panel-class="p-2!"
+		@update:path="emit('update:path', $event)"
+		@navigate="emit('navigate', $event)"
+	>
+		<DomAppStackScreen v-for="screen in screens" :key="screen.id" :id="screen.id" :title="screen.title" :parent="screen.parent">
+			<template #default="stack">
+				<slot v-if="screen.slot" :name="screen.slot" :screen="screen" :stack="stack">
+					<component v-if="screen.component" :is="screen.component" v-bind="screen.props" :screen="screen" :stack="stack" />
+				</slot>
+				<component v-else-if="screen.component" :is="screen.component" v-bind="screen.props" :screen="screen" :stack="stack" />
+				<nav v-if="screen.items.length" :aria-label="screen.title">
+					<ul class="space-y-1">
+						<li v-for="item in screen.items" :key="item.id">
+							<component
+								:is="rowElement(item)"
+								v-bind="rowAttributes(item)"
+								:aria-label="item.label || item.title || item.id"
+								class="block w-full overflow-hidden rounded-lg text-left hover:bg-secondary focus-visible:outline-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50"
+								@click="activate(item, stack)"
+							>
+								<DomAppListItem as="div" class="bg-transparent!" :label="item.label || item.title || item.id" :description="item.description" :meta="item.meta" :chevron="hasMenuPage(item)" />
+							</component>
+						</li>
+					</ul>
+				</nav>
+				<p v-else-if="!screen.component && (!screen.slot || screen.id === 'root') && !$slots[screen.slot]" class="p-4 text-sm text-muted-fg">No menu items.</p>
+			</template>
+		</DomAppStackScreen>
+	</DomAppStack>
+</template>

package/src/pages/components/menu-stack/menuTree.js

@@ -0,0 +1,35 @@
+/**
+ * Reports whether an item opens a contained page instead of selecting a leaf.
+ * @param {object} item Application-owned menu item.
+ * @returns {boolean} Whether the item supplies child navigation or page content.
+ */
+export function hasMenuPage(item) {
+	return Array.isArray(item.children) || !!item.component || !!item.slot;
+}
+
+/**
+ * Flattens nested menu pages for DomAppStack without mutating application data.
+ * Every item needs a unique, non-empty string id; "root" is reserved.
+ * @param {Array<object>} items Nested links, actions, and pages.
+ * @param {string} title Root page title.
+ * @returns {Array<object>} Stack screen registrations with original child items.
+ */
+export function buildMenuScreens(items, title) {
+	const screens = [{ id: 'root', title, items, slot: 'root' }];
+	const ids = new Set(['root']);
+	/** Validates each item once and registers its page under its parent. */
+	function visit(children, parent) {
+		for (const item of children) {
+			if (!item || typeof item.id !== 'string' || !item.id.trim() || ids.has(item.id)) {
+				throw new Error('DomMenuStack items require unique non-empty string ids; "root" is reserved.');
+			}
+			ids.add(item.id);
+			if (!hasMenuPage(item)) continue;
+			const nested = Array.isArray(item.children) ? item.children : [];
+			screens.push({ ...item, title: item.title || item.label || item.id, parent, items: nested });
+			visit(nested, item.id);
+		}
+	}
+	visit(items, 'root');
+	return screens;
+}