entasis 0.7.1 → 0.9.0

package/dist/components/Sidebar/Sidebar.svelte

@@ -18,6 +18,7 @@
 	import { SidebarResizeState } from './sidebar.resize.svelte.js';
 	import { SidebarStateController } from './sidebar.state.svelte.js';
 	import { useSidebarTheme } from './sidebar.theme.js';
+	import { SidebarViewsState } from './sidebar.views.svelte.js';
 	import { useDefaultColor } from '../Theme/theme.state.svelte.js';
 	let {
 		id: customId,
@@ -47,6 +48,10 @@
 		expandOnHover = false,
 		activityBar,
 		items,
+		views,
+		view = $bindable(),
+		defaultView,
+		onViewChange,
 		class: className,
 		collapseIcon = 'chevron',
 		tooltips = 'auto',
@@ -111,19 +116,26 @@
 	const navLabel = $derived(`${t.sidebar} ${t.navigation}`);
 	const classes = $derived(useSidebarTheme(theme));
 	const resolvedColor = $derived(useDefaultColor());
+	// Every view counts, not just the one on screen: icon collapse must not come and go as the
+	// view changes.
 	const canCollapseToIcon = $derived.by(() => {
-		if (content) return false;
+		const viewList = Object.values(views ?? {});
+		if (viewList.length ? viewList.some((entry) => entry.content) : content) return false;
 
-		const menuEntries = [
-			...(headerMenu ?? []),
-			...(items?.flatMap((group) => group.items ?? []) ?? []),
-			...(footerMenu ?? [])
-		];
+		const sources = [{ headerMenu, items, footerMenu, headerButton, footerButton }, ...viewList];
+		const menuEntries = sources.flatMap((source) => [
+			...(source.headerMenu ?? []),
+			...(source.items?.flatMap((group) => group.items ?? []) ?? []),
+			...(source.footerMenu ?? [])
+		]);
 
 		return (
 			menuEntries.every(hasIcon) &&
-			hasCollapsibleMedia(headerButton) &&
-			hasCollapsibleMedia(footerButton)
+			sources.every(
+				(source) =>
+					hasCollapsibleMedia(source.headerButton ?? undefined) &&
+					hasCollapsibleMedia(source.footerButton ?? undefined)
+			)
 		);
 	});
 	const resolvedCollapsible = $derived(
@@ -150,6 +162,32 @@
 			return onDisplayStateChange;
 		}
 	});
+	const panelViews = new SidebarViewsState({
+		get views() {
+			return views;
+		},
+		get view() {
+			return view;
+		},
+		get defaultView() {
+			return defaultView;
+		},
+		get onViewChange() {
+			return onViewChange;
+		},
+		get isMobile(): boolean {
+			return controller.isMobile;
+		},
+		get side() {
+			return side;
+		},
+		get root() {
+			return { headerButton, search, headerMenu, header, footerButton, footerMenu, footer };
+		},
+		setViewProp: (next) => {
+			view = next;
+		}
+	});
 	const controller = new SidebarStateController({
 		get mode() {
 			return mode;
@@ -169,7 +207,11 @@
 		get peeking() {
 			return hoverExpanded;
 		},
-		setDisplayState: displayStateBridge.setDisplayState
+		get view(): string | undefined {
+			return panelViews.current;
+		},
+		setDisplayState: displayStateBridge.setDisplayState,
+		setView: panelViews.setView
 	});
 	const resize = new SidebarResizeState({
 		get width() {
@@ -199,6 +241,9 @@
 		mode === 'panel' && controller.displayState === 'collapsed' ? widthIcon : width
 	);
 	const withBanner = $derived(!!banner);
+	// The page fills the frame only when nothing of the sidebar stays beside it: the panel is
+	// hidden and no activity bar remains on screen.
+	const pageFlush = $derived(controller.displayState === 'hidden' && !activityBar);
 	const rootClass = $derived(
 		classes.root({
 			variant,
@@ -251,6 +296,7 @@
 		{activeVariant}
 		{density}
 		label={navLabel}
+		views={panelViews.enabled ? panelViews : undefined}
 		{theme}
 	/>
 {/snippet}
@@ -309,6 +355,7 @@
 		data-size={size}
 		data-density={density}
 		data-activity-bar={activityBar ? 'true' : undefined}
+		data-page-flush={pageFlush ? 'true' : undefined}
 		data-width-prehydrating={resize.isWidthInitializing ? 'true' : undefined}
 		style:--sidebar-width={resize.renderWidth}
 		style:--sidebar-width-icon={widthIcon}
@@ -399,7 +446,8 @@
 					variant,
 					side,
 					displayState: controller.displayState,
-					edgeRevealed
+					edgeRevealed,
+					flush: pageFlush
 				})}
 			>
 				{@render children?.(api)}

package/dist/components/Sidebar/Sidebar.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { SidebarProps } from './sidebar.props.js';
-declare const Sidebar: import("svelte").Component<SidebarProps, {}, "width" | "ref" | "open" | "displayState">;
+declare const Sidebar: import("svelte").Component<SidebarProps, {}, "view" | "width" | "ref" | "open" | "displayState">;
 type Sidebar = ReturnType<typeof Sidebar>;
 export default Sidebar;

package/dist/components/Sidebar/SidebarMenuItem.svelte

@@ -30,6 +30,8 @@
 		size,
 		activeVariant,
 		density,
+		back = false,
+		ariaLabel,
 		theme
 	}: {
 		item: SidebarMenuEntry;
@@ -39,6 +41,10 @@
 		size: SidebarSize;
 		activeVariant: SidebarActiveVariant;
 		density: SidebarDensity;
+		/** The row a nested view opens on, back to its parent: a leading back arrow, no chevron. */
+		back?: boolean;
+		/** Accessible name when the visible label alone does not say what the row does. */
+		ariaLabel?: string;
 		theme?: SidebarThemeProps;
 	} = $props();
 
@@ -62,7 +68,9 @@
 		api.displayState === 'collapsed' && !api.isMobile && !api.isPeeking
 	);
 	const showTooltip = $derived((tooltips === 'always' || isIconCollapsed) && !api.isMobile);
-	const tooltipContent = $derived(showTooltip ? (item.tooltip ?? item.label) : undefined);
+	const tooltipContent = $derived(
+		showTooltip ? (item.tooltip ?? ariaLabel ?? item.label) : undefined
+	);
 	const hasSubmenu = $derived(!!item.items?.length);
 	// A bare glyph stays bare: the wrapper only appears when the entry asks for a role tint or a
 	// tile, so an untinted row never inherits the ambient `data-color`.
@@ -97,6 +105,7 @@
 			return;
 		}
 		item.onclick?.(event);
+		if (item.view !== undefined && !event.defaultPrevented) api.setView(item.view);
 	}
 </script>
 
@@ -110,7 +119,7 @@
 			<SidebarIcon icon={item.icon} />
 		</span>
 	{:else}
-		<SidebarIcon icon={item.icon} />
+		<SidebarIcon icon={item.icon} class={back ? 'rtl:-scale-x-100' : undefined} />
 	{/if}
 	<span class={classes.menuLabel()}>{item.label}</span>
 {/snippet}
@@ -170,6 +179,8 @@
 			data-active={item.isActive ? 'true' : undefined}
 			data-active-variant={activeVariant}
 			aria-current={item.isActive ? 'page' : undefined}
+			aria-label={ariaLabel}
+			data-sidebar-view-target={item.view}
 			disabled={item.disabled || undefined}
 			class={classes.menuButton({
 				variant: item.variant,
@@ -183,6 +194,12 @@
 			onclick={handleClick}
 		>
 			{@render entryContent()}
+			{#if item.view !== undefined && !back}
+				<SidebarIcon
+					icon={caretRightIcon}
+					class={classes.menuTrailing({ size, className: 'rtl:-scale-x-100' })}
+				/>
+			{/if}
 		</button>
 	{/if}
 {/snippet}

package/dist/components/Sidebar/SidebarMenuItem.svelte.d.ts

@@ -9,6 +9,10 @@ type $$ComponentProps = {
     size: SidebarSize;
     activeVariant: SidebarActiveVariant;
     density: SidebarDensity;
+    /** The row a nested view opens on, back to its parent: a leading back arrow, no chevron. */
+    back?: boolean;
+    /** Accessible name when the visible label alone does not say what the row does. */
+    ariaLabel?: string;
     theme?: SidebarThemeProps;
 };
 declare const SidebarMenuItem: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/Sidebar/SidebarPanel.svelte

@@ -16,8 +16,12 @@
 	import SidebarGroupComponent from './SidebarGroup.svelte';
 	import SidebarIcon from './SidebarIcon.svelte';
 	import SidebarMenuButton from './SidebarMenuButton.svelte';
+	import SidebarMenuItem from './SidebarMenuItem.svelte';
 	import SidebarMenuList from './SidebarMenuList.svelte';
+	import SidebarViewStage from './SidebarViewStage.svelte';
+	import { arrowLeftIcon } from '../Icons/arrowLeft.js';
 	import { useSidebarTheme, type SidebarThemeProps } from './sidebar.theme.js';
+	import { type SidebarSlotValues, type SidebarViewsState } from './sidebar.views.svelte.js';
 
 	let {
 		api,
@@ -36,6 +40,7 @@
 		activeVariant,
 		density,
 		label,
+		views,
 		theme
 	}: {
 		api: SidebarApi;
@@ -55,9 +60,27 @@
 		density: SidebarDensity;
 		/** Accessible name for the body navigation landmark. */
 		label: string;
+		/** Named views; when enabled, each region slides between them instead of rendering the props. */
+		views?: SidebarViewsState;
 		theme?: SidebarThemeProps;
 	} = $props();
 
+	const rootSource = $derived<SidebarSlotValues>({
+		items,
+		content,
+		headerButton,
+		search,
+		headerMenu,
+		header,
+		footerButton,
+		footerMenu,
+		footer
+	});
+	const hasHeader = (source: SidebarSlotValues) =>
+		!!(source.headerButton || source.search || source.headerMenu || source.header);
+	const hasFooter = (source: SidebarSlotValues) =>
+		!!(source.footerButton || source.footerMenu || source.footer);
+
 	const classes = $derived(useSidebarTheme(theme));
 	const t = $derived(useI18n());
 	// A hover peek renders the collapsed panel at full width, so icon-mode behaviour has to
@@ -85,66 +108,87 @@
 	});
 </script>
 
-{#if headerButton || search || headerMenu || header}
-	<div data-slot="sidebar-header" data-sidebar="header" class={classes.header({ density })}>
-		<!--
-			The `header` snippet renders first, so a custom workspace card sits above the built-in
-			search and menu instead of under them. Consumers never need an order override.
-		-->
-		{#if header}
-			{@render header(api)}
-		{/if}
-		{#if headerButton}
-			<SidebarMenuButton
-				{...headerButton}
-				{api}
-				mobile={api.isMobile}
-				defaultAlign="start"
-				{size}
-				{density}
-				{theme}
-			/>
-		{/if}
-		{#if search}
-			<form
-				bind:this={searchRef}
-				data-slot="sidebar-search"
-				class={classes.searchContainer({ size, collapsed })}
-				inert={collapsed ? true : undefined}
-				aria-hidden={collapsed ? 'true' : undefined}
-				onsubmit={(event) => event.preventDefault()}
-			>
-				<input
-					placeholder={search.placeholder}
-					aria-label={search.label ?? t.search}
-					value={search.value}
-					oninput={search.oninput}
-					class={classes.search({ size, density, className: search.class })}
-				/>
-				<SidebarIcon icon={magnifyingGlassIcon} class={classes.searchIcon({ size, density })} />
-			</form>
-		{/if}
-		{#if headerMenu}
-			<SidebarMenuList
-				items={headerMenu}
-				{api}
-				{collapseIcon}
-				{tooltips}
-				{size}
-				{activeVariant}
-				{density}
-				{theme}
-			/>
-		{/if}
-	</div>
-{/if}
+{#snippet headerButtonSlot(headerButton: SidebarMenuButtonItem)}
+	<SidebarMenuButton
+		{...headerButton}
+		{api}
+		mobile={api.isMobile}
+		defaultAlign="start"
+		{size}
+		{density}
+		{theme}
+	/>
+{/snippet}
+
+{#snippet searchSlot(searchBox: SidebarSearch)}
+	<form
+		bind:this={searchRef}
+		data-slot="sidebar-search"
+		class={classes.searchContainer({ size, collapsed })}
+		inert={collapsed ? true : undefined}
+		aria-hidden={collapsed ? 'true' : undefined}
+		onsubmit={(event) => event.preventDefault()}
+	>
+		<input
+			placeholder={searchBox.placeholder}
+			aria-label={searchBox.label ?? t.search}
+			value={searchBox.value}
+			oninput={searchBox.oninput}
+			class={classes.search({ size, density, className: searchBox.class })}
+		/>
+		<SidebarIcon icon={magnifyingGlassIcon} class={classes.searchIcon({ size, density })} />
+	</form>
+{/snippet}
+
+{#snippet menuSlot(items: SidebarMenuEntry[])}
+	<SidebarMenuList
+		{items}
+		{api}
+		{collapseIcon}
+		{tooltips}
+		{size}
+		{activeVariant}
+		{density}
+		{theme}
+	/>
+{/snippet}
+
+{#snippet footerButtonSlot(footerButton: SidebarMenuButtonItem)}
+	<SidebarMenuButton
+		{...footerButton}
+		{api}
+		mobile={api.isMobile}
+		defaultAlign="end"
+		{size}
+		{density}
+		{theme}
+	/>
+{/snippet}
 
-<!-- The activity bar is a second nav landmark, so this one needs its own name to tell them apart. -->
-<nav data-slot="sidebar-nav" data-sidebar="nav" aria-label={label} class={classes.nav({ density })}>
-	{#if content}
-		{@render content(api)}
-	{:else if items}
-		{#each items as group, index (group.label ?? `group-${index}`)}
+{#snippet headerRegion(source: SidebarSlotValues)}
+	<!--
+		The `header` snippet renders first, so a custom workspace card sits above the built-in
+		search and menu instead of under them. Consumers never need an order override.
+	-->
+	{#if source.header}
+		{@render source.header(api)}
+	{/if}
+	{#if source.headerButton}
+		{@render headerButtonSlot(source.headerButton)}
+	{/if}
+	{#if source.search}
+		{@render searchSlot(source.search)}
+	{/if}
+	{#if source.headerMenu}
+		{@render menuSlot(source.headerMenu)}
+	{/if}
+{/snippet}
+
+{#snippet bodyRegion(source: SidebarSlotValues)}
+	{#if source.content}
+		{@render source.content(api)}
+	{:else if source.items}
+		{#each source.items as group, index (group.label ?? `group-${index}`)}
 			{#if group.separator && index > 0}
 				<div
 					data-slot="sidebar-separator"
@@ -164,35 +208,102 @@
 			/>
 		{/each}
 	{/if}
-</nav>
+{/snippet}
 
-{#if footerButton || footerMenu || footer}
-	<div data-slot="sidebar-footer" data-sidebar="footer" class={classes.footer({ density })}>
-		{#if footerButton}
-			<SidebarMenuButton
-				{...footerButton}
-				{api}
-				mobile={api.isMobile}
-				defaultAlign="end"
-				{size}
-				{density}
-				{theme}
-			/>
-		{/if}
-		{#if footerMenu}
-			<SidebarMenuList
-				items={footerMenu}
-				{api}
-				{collapseIcon}
-				{tooltips}
-				{size}
-				{activeVariant}
-				{density}
+{#snippet footerRegion(source: SidebarSlotValues)}
+	{#if source.footerButton}
+		{@render footerButtonSlot(source.footerButton)}
+	{/if}
+	{#if source.footerMenu}
+		{@render menuSlot(source.footerMenu)}
+	{/if}
+	{#if source.footer}
+		{@render source.footer(api)}
+	{/if}
+{/snippet}
+
+{#if views?.enabled}
+	<!--
+		Views with the same header and footer share one panel layer, so only the menu inside slides;
+		a view that changes them slides the whole panel as one page.
+	-->
+	<SidebarViewStage
+		{views}
+		kind="panel"
+		layers={views.layers('panel')}
+		layerClass="flex min-h-0 flex-col"
+		{theme}
+	>
+		{#snippet children(panelLayer)}
+			{@const chrome = views.chrome(panelLayer.view)}
+			{#if hasHeader(chrome)}
+				<div data-slot="sidebar-header" data-sidebar="header" class={classes.header({ density })}>
+					{@render headerRegion(chrome)}
+				</div>
+			{/if}
+			<!-- The activity bar is a second nav landmark, so this one needs its own name to tell them apart. -->
+			<SidebarViewStage
+				{views}
+				kind="body"
+				layers={panelLayer.role
+					? [{ key: panelLayer.view, view: panelLayer.view }]
+					: views.layers('body')}
+				layerClass={classes.nav({ density })}
+				{label}
 				{theme}
-			/>
-		{/if}
-		{#if footer}
-			{@render footer(api)}
-		{/if}
-	</div>
+			>
+				{#snippet children(bodyLayer)}
+					{@const parent = views.parentOf(bodyLayer.view)}
+					{#if parent !== undefined}
+						{@const parentLabel = views.labelOf(parent)}
+						<!-- A nested view opens on a row back to its parent, named after it like a back button. -->
+						<div data-slot="sidebar-group" data-sidebar="group" class={classes.group({ density })}>
+							<ul data-slot="sidebar-menu" data-sidebar="menu" class={classes.menu({ density })}>
+								<SidebarMenuItem
+									item={{ label: parentLabel ?? t.back, icon: arrowLeftIcon, view: parent }}
+									back
+									ariaLabel={parentLabel ? `${t.back}, ${parentLabel}` : undefined}
+									{api}
+									{collapseIcon}
+									{tooltips}
+									{size}
+									{activeVariant}
+									{density}
+									{theme}
+								/>
+							</ul>
+						</div>
+					{/if}
+					{@render bodyRegion(views.body(bodyLayer.view))}
+				{/snippet}
+			</SidebarViewStage>
+			{#if hasFooter(chrome)}
+				<div data-slot="sidebar-footer" data-sidebar="footer" class={classes.footer({ density })}>
+					{@render footerRegion(chrome)}
+				</div>
+			{/if}
+		{/snippet}
+	</SidebarViewStage>
+{:else}
+	{#if hasHeader(rootSource)}
+		<div data-slot="sidebar-header" data-sidebar="header" class={classes.header({ density })}>
+			{@render headerRegion(rootSource)}
+		</div>
+	{/if}
+
+	<!-- The activity bar is a second nav landmark, so this one needs its own name to tell them apart. -->
+	<nav
+		data-slot="sidebar-nav"
+		data-sidebar="nav"
+		aria-label={label}
+		class={classes.nav({ density })}
+	>
+		{@render bodyRegion(rootSource)}
+	</nav>
+
+	{#if hasFooter(rootSource)}
+		<div data-slot="sidebar-footer" data-sidebar="footer" class={classes.footer({ density })}>
+			{@render footerRegion(rootSource)}
+		</div>
+	{/if}
 {/if}

package/dist/components/Sidebar/SidebarPanel.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { DisclosureIndicator } from '../../types/theme.js';
 import type { SidebarActiveVariant, SidebarApi, SidebarGroup, SidebarMenuButtonItem, SidebarMenuEntry, SidebarSearch, SidebarDensity, SidebarSize, SidebarTooltipMode } from './sidebar.props.js';
 import { type SidebarThemeProps } from './sidebar.theme.js';
+import { type SidebarViewsState } from './sidebar.views.svelte.js';
 type $$ComponentProps = {
     api: SidebarApi;
     items?: SidebarGroup[];
@@ -19,6 +20,8 @@ type $$ComponentProps = {
     density: SidebarDensity;
     /** Accessible name for the body navigation landmark. */
     label: string;
+    /** Named views; when enabled, each region slides between them instead of rendering the props. */
+    views?: SidebarViewsState;
     theme?: SidebarThemeProps;
 };
 declare const SidebarPanel: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/Sidebar/SidebarViewStage.svelte

@@ -0,0 +1,103 @@
+<script lang="ts">
+	import { untrack, type Snippet } from 'svelte';
+	import type { Attachment } from 'svelte/attachments';
+	import {
+		sidebarViewTransition,
+		type SidebarViewKind,
+		type SidebarViewLayer,
+		type SidebarViewsState
+	} from './sidebar.views.svelte.js';
+	import { useSidebarMotion, useSidebarTheme, type SidebarThemeProps } from './sidebar.theme.js';
+
+	let {
+		views,
+		kind,
+		layers,
+		layerClass,
+		label,
+		theme,
+		children
+	}: {
+		views: SidebarViewsState;
+		/** `panel` slides the whole panel and owns the swipe; `body` slides the menu inside it. */
+		kind: SidebarViewKind;
+		layers: SidebarViewLayer[];
+		/** Classes each layer wears on top of `viewLayer`. */
+		layerClass?: string;
+		/** Landmark name; the body stage is the nav landmark. */
+		label?: string;
+		theme?: SidebarThemeProps;
+		children: Snippet<[layer: SidebarViewLayer]>;
+	} = $props();
+
+	const classes = $derived(useSidebarTheme(theme));
+	// The `view` motion of the Sidebar motion slot: travel, rest opacity, duration and easing come
+	// from it, so a `<Theme motion>` retune and a reduced-motion preference reach the view slide.
+	const resolveMotion = useSidebarMotion();
+	const motion = $derived(resolveMotion({ part: 'view' }, { motion: theme?.motion }));
+	const duration = $derived(motion.in.duration ?? 0);
+	const travel = $derived(motion.in.x ?? 0);
+	const restOpacity = $derived(motion.in.opacity ?? 0);
+	const isPanel = $derived(kind === 'panel');
+	const swipe = $derived(views.canSwipeBack);
+	const dragging = $derived(views.swipe?.phase === 'drag');
+
+	// A settling swipe (commit or cancel) ends once its layers have eased to rest.
+	$effect(() => {
+		const phase = views.swipe?.phase;
+		if (!isPanel || !phase || phase === 'drag') return;
+		const timer = setTimeout(() => views.settleSwipe(), duration);
+		return () => clearTimeout(timer);
+	});
+
+	// Focus that sat in the view being replaced lands in the new one: on the row that opens the view
+	// just left (a back row after going deeper, the row that opened it after coming back), else on
+	// the first control. Focus anywhere else stays put, so a route change never pulls it here.
+	const arrive: Attachment<HTMLElement> = (node) =>
+		untrack(() => {
+			const stage = node.parentElement;
+			const active = document.activeElement;
+			if (node.dataset.swipe || !stage || !(active instanceof HTMLElement)) return;
+			if (!stage.contains(active) || node.contains(active)) return;
+			const from = views.lastChange.from;
+			const target =
+				(from !== undefined &&
+					node.querySelector<HTMLElement>(`[data-sidebar-view-target="${CSS.escape(from)}"]`)) ||
+				node.querySelector<HTMLElement>(
+					'a[href], button:not([disabled]), input:not([disabled]), [tabindex]:not([tabindex="-1"])'
+				);
+			target?.focus({ preventScroll: true });
+		});
+</script>
+
+<svelte:element
+	this={isPanel ? 'div' : 'nav'}
+	data-slot="sidebar-view-stage"
+	data-sidebar={isPanel ? undefined : 'nav'}
+	data-view-kind={kind}
+	aria-label={label}
+	data-no-swipe={isPanel && views.ownsDrawerSwipe ? '' : undefined}
+	class={classes.viewStage()}
+	{@attach isPanel ? views.swipeAttachment : undefined}
+>
+	{#each layers as layer (layer.key)}
+		{@const swipeStyle = views.swipeStyle(layer.role, travel, restOpacity)}
+		<div
+			data-slot="sidebar-view-layer"
+			data-sidebar="view-layer"
+			data-view={layer.view}
+			data-swipe={layer.role}
+			data-dragging={layer.role && dragging ? 'true' : undefined}
+			inert={layer.role === 'under' && dragging ? true : undefined}
+			class={[layerClass, classes.viewLayer({ swipe })]}
+			style:translate={swipeStyle.translate}
+			style:opacity={swipeStyle.opacity}
+			style:transition-duration={`${duration}ms`}
+			in:sidebarViewTransition={{ phase: 'in', direction: views.lastChange.direction, motion }}
+			out:sidebarViewTransition={{ phase: 'out', direction: views.lastChange.direction, motion }}
+			{@attach arrive}
+		>
+			{@render children(layer)}
+		</div>
+	{/each}
+</svelte:element>