@fuzdev/fuz_app 0.122.0 → 0.123.0

package/dist/ui/CLAUDE.md

@@ -221,7 +221,21 @@ pattern rather than reintroducing prop-drilling.
     to keep narrow mode at `0px`. To change only the wide open offset, target
     `.app-shell.wide-open > .app-shell-content`, also inside that negation.
 - `ColumnLayout.svelte` — fixed `aside` column + fluid `children`
-  column; `column_width = '280px'`.
+  column; `column_width = '280px'`, `aside_label = 'menu'`. Below 64rem of
+  its own width (an `inline-size` container query named `column_layout`;
+  64rem under fuz_css's 62.5% root is fuz_css's `sm` breakpoint, 640px at
+  the default font size) the columns stack and the aside collapses behind a
+  sticky `type="button"` toggle (`menuitem plain` with a `chevron`, text
+  `aside_label`, `aria-expanded`/`aria-controls`); opened, the aside sits in flow above the content (scrolled into view under the toggle when scroll anchoring would leave it above the view), and `afterNavigate` closes it. With a bounded height, the stacked layout
+  scrolls as one column and the toggle sticks to its top; under a parent
+  that grows with its content, the page scrolls and the toggle scrolls away
+  with it. Above the threshold the toggle is `display: none`. The switch is
+  CSS alone, so the server render shows the right form at any width and
+  hydration changes nothing. The
+  `<aside>` takes `aria-label={aside_label}`; consumers wrap links in their
+  own `<nav>`. Hooks: `--column_width`, `--column_toggle_bg` (default
+  `--shade_00`). The container can't size from its content, so a
+  shrink-to-fit placement collapses it to zero width.
 - `MenuLink.svelte` — SvelteKit `<a>` with `selected` derived from
   `page.url.pathname` (fires for exact match + descendant pages).
   Exact matches additionally get `aria-current="page"`. Takes `path`

package/dist/ui/ColumnLayout.svelte

@@ -1,18 +1,52 @@
 <script lang="ts">
 	/**
-	 * Two-column layout — fixed-width `aside` on the left, fluid `children`
+	 * Two-column layout - fixed-width `aside` on the left, fluid `children`
 	 * column on the right. Both columns scroll independently.
 	 *
+	 * Below a threshold of the layout's own width - a container query, not a
+	 * media query, so a nested layout decides for itself - the columns stack:
+	 * the aside collapses behind a toggle button labelled `aside_label`, and
+	 * when opened it sits in flow above the content, pushing it down, until
+	 * the toggle closes it or a navigation does. Opening scrolls the aside
+	 * into view, under the toggle, when it would land above the view.
+	 *
+	 * With a bounded height, the stacked layout scrolls as one column and the
+	 * toggle sticks to its top; under a parent that grows with its content,
+	 * the page scrolls and the toggle scrolls away with it.
+	 *
+	 * The threshold matches fuz_css's `sm` breakpoint. Above it the toggle is
+	 * `display: none`. The switch is CSS alone, so the server render shows the
+	 * right form at any width and hydration changes nothing.
+	 *
+	 * The root is an `inline-size` query container, so its width can't come
+	 * from its content: a layout placed where it would shrink to fit (an
+	 * inline-block, an absolutely positioned or floated box without a width,
+	 * a flex row item that doesn't grow) collapses to zero width. Give it a
+	 * width from its context, as a block or a stretched or growing flex item.
+	 *
+	 * Requires the SvelteKit runtime - it closes the aside from
+	 * `afterNavigate`. Without JS the stacked aside can't be opened, since the
+	 * toggle is client state; above the threshold it's always shown.
+	 *
+	 * Renders a generic `<aside>` named by `aside_label`; wrap navigation
+	 * links in a `<nav>` inside the `aside` snippet.
+	 *
+	 * Styling hooks: `--column_width` (set from `column_width`) and
+	 * `--column_toggle_bg`, the stacked toggle bar's opaque background so
+	 * content scrolls under it unseen (default `--shade_00`, the page ground).
+	 *
 	 * @module
 	 */
 
-	import type { Snippet } from 'svelte';
+	import { tick, type Snippet } from 'svelte';
 	import type { SvelteHTMLElements } from 'svelte/elements';
+	import { afterNavigate } from '$app/navigation';
 
 	const {
 		aside,
 		children,
 		column_width = '280px',
+		aside_label = 'menu',
 		class: class_name = '',
 		...rest
 	}: SvelteHTMLElements['div'] & {
@@ -23,24 +57,85 @@
 		 * @default '280px'
 		 */
 		column_width?: string;
+		/**
+		 * The stacked toggle's text and the aside's accessible name.
+		 * @default 'menu'
+		 */
+		aside_label?: string;
 	} = $props();
+
+	const uid = $props.id();
+	const aside_id = `${uid}-aside`;
+
+	let aside_open = $state(false);
+
+	let toggle_bar_el: HTMLDivElement;
+	let aside_el: HTMLElement;
+
+	const toggle_aside = async (): Promise<void> => {
+		aside_open = !aside_open;
+		await tick();
+		// closed, or closed again before the DOM settled
+		if (!aside_open) return;
+		// the aside goes in above the content, and scroll anchoring keeps the
+		// content where it was, so opening while scrolled - the stacked body,
+		// or the page past a toggle half out of view - leaves the aside above
+		// the view; bring its start back under the toggle, whether the toggle
+		// sticks (bounded) or sits just above it (growing)
+		const bar = toggle_bar_el.getBoundingClientRect();
+		if (aside_el.getBoundingClientRect().top >= Math.max(0, bar.bottom)) return;
+		aside_el.style.scrollMarginTop = `${bar.height}px`;
+		aside_el.scrollIntoView({ block: 'start' });
+	};
+
+	afterNavigate(() => {
+		aside_open = false;
+	});
 </script>
 
 <div class="column-layout {class_name}" style:--column_width={column_width} {...rest}>
-	<aside class="column-fixed unstyled">
-		{@render aside()}
-	</aside>
-	<div class="column-fluid">
-		{@render children()}
+	<div class={['column-layout-body', { 'aside-open': aside_open }]}>
+		<div class="column-toggle-bar" bind:this={toggle_bar_el}>
+			<button
+				type="button"
+				class="column-toggle menuitem plain"
+				aria-expanded={aside_open}
+				aria-controls={aside_id}
+				onclick={toggle_aside}
+			>
+				{aside_label}
+				<span class="chevron" aria-hidden="true"></span>
+			</button>
+		</div>
+		<aside
+			id={aside_id}
+			class="column-fixed unstyled"
+			aria-label={aside_label}
+			bind:this={aside_el}
+		>
+			{@render aside()}
+		</aside>
+		<div class="column-fluid">
+			{@render children()}
+		</div>
 	</div>
 </div>
 
 <style>
 	.column-layout {
+		container: column_layout / inline-size;
+		height: 100%;
+	}
+
+	.column-layout-body {
 		display: flex;
 		height: 100%;
 	}
 
+	.column-toggle-bar {
+		display: none;
+	}
+
 	.column-fixed {
 		width: var(--column_width, 280px);
 		min-width: var(--column_width, 280px);
@@ -54,4 +149,40 @@
 		min-width: 0;
 		overflow: auto;
 	}
+
+	/* fuz_css's `sm` breakpoint is the media query `40rem`, where `rem` is the
+	   initial font size; in a container query `rem` reads the root, which
+	   fuz_css sets to 62.5%, so `64rem` is the same width at any user font
+	   size - keep in sync with `sm` in fuz_css's `modifiers.ts` */
+	@container column_layout (width < 64rem) {
+		.column-layout-body {
+			flex-direction: column;
+			overflow: auto;
+		}
+		.column-toggle-bar {
+			display: block;
+			position: sticky;
+			top: 0;
+			z-index: 1;
+			background-color: var(--column_toggle_bg, var(--shade_00));
+		}
+		/* `flex: none` because the aside scrolls, so it would otherwise shrink
+		   to nothing in the body's fixed height */
+		.column-layout-body > .column-fixed {
+			flex: none;
+			width: auto;
+			min-width: 0;
+			height: auto;
+		}
+		.column-layout-body:not(.aside-open) > .column-fixed {
+			display: none;
+		}
+		.column-fluid {
+			flex: none;
+			height: auto;
+		}
+		.column-layout-body.aside-open > .column-toggle-bar .chevron {
+			rotate: 90deg;
+		}
+	}
 </style>

package/dist/ui/ColumnLayout.svelte.d.ts

@@ -1,10 +1,42 @@
 /**
-     * Two-column layout — fixed-width `aside` on the left, fluid `children`
+     * Two-column layout - fixed-width `aside` on the left, fluid `children`
      * column on the right. Both columns scroll independently.
      *
+     * Below a threshold of the layout's own width - a container query, not a
+     * media query, so a nested layout decides for itself - the columns stack:
+     * the aside collapses behind a toggle button labelled `aside_label`, and
+     * when opened it sits in flow above the content, pushing it down, until
+     * the toggle closes it or a navigation does. Opening scrolls the aside
+     * into view, under the toggle, when it would land above the view.
+     *
+     * With a bounded height, the stacked layout scrolls as one column and the
+     * toggle sticks to its top; under a parent that grows with its content,
+     * the page scrolls and the toggle scrolls away with it.
+     *
+     * The threshold matches fuz_css's `sm` breakpoint. Above it the toggle is
+     * `display: none`. The switch is CSS alone, so the server render shows the
+     * right form at any width and hydration changes nothing.
+     *
+     * The root is an `inline-size` query container, so its width can't come
+     * from its content: a layout placed where it would shrink to fit (an
+     * inline-block, an absolutely positioned or floated box without a width,
+     * a flex row item that doesn't grow) collapses to zero width. Give it a
+     * width from its context, as a block or a stretched or growing flex item.
+     *
+     * Requires the SvelteKit runtime - it closes the aside from
+     * `afterNavigate`. Without JS the stacked aside can't be opened, since the
+     * toggle is client state; above the threshold it's always shown.
+     *
+     * Renders a generic `<aside>` named by `aside_label`; wrap navigation
+     * links in a `<nav>` inside the `aside` snippet.
+     *
+     * Styling hooks: `--column_width` (set from `column_width`) and
+     * `--column_toggle_bg`, the stacked toggle bar's opaque background so
+     * content scrolls under it unseen (default `--shade_00`, the page ground).
+     *
      * @module
      */
-import type { Snippet } from 'svelte';
+import { type Snippet } from 'svelte';
 import type { SvelteHTMLElements } from 'svelte/elements';
 type $$ComponentProps = SvelteHTMLElements['div'] & {
     aside: Snippet;
@@ -14,6 +46,11 @@ type $$ComponentProps = SvelteHTMLElements['div'] & {
      * @default '280px'
      */
     column_width?: string;
+    /**
+     * The stacked toggle's text and the aside's accessible name.
+     * @default 'menu'
+     */
+    aside_label?: string;
 };
 declare const ColumnLayout: import("svelte").Component<$$ComponentProps, {}, "">;
 type ColumnLayout = ReturnType<typeof ColumnLayout>;

package/dist/ui/ColumnLayout.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ColumnLayout.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/ColumnLayout.svelte"],"names":[],"mappings":"AAGA;;;;;OAKI;AACJ,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,KAAK,gBAAgB,GAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AA6BH,QAAA,MAAM,YAAY,sDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"ColumnLayout.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/ColumnLayout.svelte"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCI;AACJ,OAAO,EAAQ,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,KAAK,gBAAgB,GAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG;IACpD,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAmEH,QAAA,MAAM,YAAY,sDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.122.0",
+  "version": "0.123.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",
@@ -80,7 +80,7 @@
     "@fuzdev/blake3-wasm": "^0.2.0",
     "@fuzdev/fuz_code": "^0.50.0",
     "@fuzdev/fuz_css": "^0.65.0",
-    "@fuzdev/fuz_ui": "^0.209.0",
+    "@fuzdev/fuz_ui": "^0.210.0",
     "@fuzdev/fuz_util": "^0.71.0",
     "@fuzdev/gro": "^0.213.0",
     "@fuzdev/mdz": "^0.3.0",