@leavepulse/ui 0.77.3 → 0.78.1

package/src/components/LpAppShell.vue

@@ -7,13 +7,22 @@ export default { inheritAttrs: false }
 
 <script setup lang="ts">
 /*
- * Full application shell: a fixed-height (h-dvh) flex frame holding the side
- * navigation rail, a top header bar, and a single scrollable main region.
+ * Full application shell: the side navigation rail, a top header bar and the
+ * page, which is what scrolls.
+ *
+ * By default the page is the document: it scrolls the window, and the rail,
+ * the header and the bottom bar are sticky beside and above it. So everything
+ * a browser does with a long page keeps working — a full-page screenshot,
+ * printing, the phone's address bar folding away, pull to refresh, a tap on
+ * the status bar. `scroll="region"` keeps the older frame instead: the shell
+ * is exactly the viewport and the page scrolls inside main (LpScrollArea),
+ * which suits a shell embedded in a page of its own. A `fullBleed` page is
+ * held to the viewport in either.
  *
  * It owns the things every product's cabinet/console layout was re-implementing
  * by hand — and getting subtly wrong:
- *  - the rail is full viewport height and never scrolls with the page (only
- *    `main` scrolls, via LpScrollArea), so the sidebar footer stays pinned;
+ *  - the rail is full viewport height and never scrolls with the page, so the
+ *    sidebar footer stays pinned;
  *  - a responsive burger that drives LpSidebar's mobile drawer;
  *  - a default `isActive` (path prefix-match) and a default page title derived
  *    from the nav items, so the header title and the active pill never drift.
@@ -30,14 +39,33 @@ export default { inheritAttrs: false }
  * #header-title (override the computed title), and the default slot (page body).
  * Overlays that aren't part of the frame (command palette, toaster) live in the
  * host next to <LpAppShell>.
+ *
+ * Every option below is off until asked for, and the shell's markup without
+ * them is what it always was: `headerCollapse`, `backToTop`, `density`,
+ * `pageTransition`, `safeArea`, the #aside region and `adaptiveNav`.
  */
-import { computed, onMounted, ref, useId, watch } from "vue"
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, useId, useSlots, watch } from "vue"
+import { easingToken, durationToken, prefersReducedMotion } from "../composables/easing"
 import { useLabels } from "../composables/useLpConfig"
 import { useScrollMemory } from "../composables/scrollMemory"
+import { nodeWindow, useView, viewWindow } from "../composables/useView"
+import AppShellContextNav from "./AppShellContextNav.vue"
+import {
+  contextNavItems,
+  DENSITY_CLASS,
+  headerCollapsedAfter,
+  NAV_BREAKPOINT_PX,
+  resolveNavMode,
+  type AdaptiveNav,
+  type NavBreakpoint,
+  type NavMode,
+  type ShellDensity,
+} from "./appShell"
 import LpBottomNav from "./LpBottomNav.vue"
 import LpContextSwitcher from "./LpContextSwitcher.vue"
 import LpButton from "./LpButton.vue"
 import LpIcon from "./LpIcon.vue"
+import LpPageScrollbar from "./LpPageScrollbar.vue"
 import LpScrollArea from "./LpScrollArea.vue"
 import LpShift from "./LpShift.vue"
 import LpSidebar from "./LpSidebar.vue"
@@ -46,6 +74,9 @@ import { mergeClass, useMergedAttrs } from "../composables/useMergedClass"
 
 export type { SidebarItem, SidebarSection } from "./sidebar"
 
+/* Past this much scrolled the way back up is worth a button. */
+const BACK_TO_TOP_AFTER_PX = 600
+
 const props = withDefaults(
   defineProps<{
     /** Flat items, or sections for grouped nav. Forwarded to LpSidebar. */
@@ -91,10 +122,26 @@ const props = withDefaults(
      * (for a canvas / map / graph that fills the viewport and pans internally).
      */
     fullBleed?: boolean
+    /**
+     * What scrolls. `"document"` (the default): the window, with the rail,
+     * header and bottom bar sticky; a page that filled main with `h-full`
+     * grows with its content now, so a page meant to fill the screen asks for
+     * `min-h-[calc(100dvh-4rem)]` or `fullBleed`. `"region"`: the shell is
+     * the viewport and the page scrolls inside main. Read once: changing it
+     * remounts the page.
+     */
+    scroll?: "document" | "region"
+    /**
+     * While the document scrolls, draw the kit's overlay bar for it
+     * (LpPageScrollbar) under the header and above the bottom bar, in place of
+     * the browser's, which takes width from the page. `false` keeps the
+     * browser's. Where the browser's bars float anyway (phones) it draws none.
+     */
+    pageScrollbar?: boolean
     /** Loading skeleton for the nav. */
     loading?: boolean
     /** Text overrides: the burger's name and the skip link. */
-    labels?: Partial<{ openMenu: string; skipToContent: string }>
+    labels?: Partial<{ openMenu: string; skipToContent: string; backToTop: string; aside: string; contextNav: string }>
     /** Icon-only rail (v-model:compact). Forwarded to LpSidebar. */
     compact?: boolean
     /** The person sizes the rail and folds it to icons. Forwarded to LpSidebar. */
@@ -123,14 +170,51 @@ const props = withDefaults(
     /**
      * On phones, the main pages along the bottom instead of the burger, with
      * "More" for the rest (it opens the drawer). `true` takes the first four
-     * pages, a number that many, a list of ids those pages.
+     * pages, a number that many, a list of ids those pages. Top-level pages
+     * only: an id from `children` is ignored, and such a page stays behind "More".
      */
     bottomNav?: boolean | number | string[]
+    /**
+     * The header leaves as the page scrolls down and returns on the way up,
+     * giving a small screen its height back. A keyboard user tabbing into it
+     * brings it back too. A full-bleed page owns its scrolling, so the header
+     * stays there.
+     */
+    headerCollapse?: boolean
+    /** A button back to the top of a long page; a number sets how far down it appears, in px. */
+    backToTop?: boolean | number
+    /** How tight the page sits in main. Unset keeps the shell's own padding. */
+    density?: ShellDensity
+    /**
+     * A new `path` fades the page and the header's title and actions in as one,
+     * on the same clock, so actions arriving by teleport do not land apart from
+     * their page. Nothing is remounted. Skipped under reduced motion.
+     */
+    pageTransition?: boolean
+    /**
+     * Keep the header and the page's end clear of a notch and a home bar
+     * (`viewport-fit=cover`). The bottom bar always does.
+     */
+    safeArea?: boolean
+    /** Tailwind breakpoint below which the #aside region is hidden. Defaults to `mobileBreakpoint`. */
+    asideBreakpoint?: NavBreakpoint
+    /** Classes for the #aside region, its width above all. */
+    asideClass?: string
+    /**
+     * One model for the navigation across widths; see `NavMode`. Below
+     * `mobileBreakpoint` it is `bottomNav` or the drawer, as ever; this adds the
+     * fold to icons in between and the row of sub-pages where the rail is gone.
+     * A `compact` the app controls wins, and a person folding the rail by hand
+     * holds until the width crosses into another mode.
+     */
+    adaptiveNav?: AdaptiveNav
   }>(),
   {
     mobileBreakpoint: "lg",
     divider: true,
     contentClass: "mx-auto w-full max-w-6xl",
+    scroll: "document",
+    pageScrollbar: true,
     // Unset, not false: an absent boolean would hand the sidebar "expanded"
     // and override the state it remembers.
     compact: undefined,
@@ -144,6 +228,8 @@ const emit = defineEmits<{
   (e: "update:compact", value: boolean): void
   (e: "update:pinned", ids: string[]): void
   (e: "update:context", id: string): void
+  /** The navigation the width settled on, with `adaptiveNav` or without. */
+  (e: "nav-mode", mode: NavMode): void
 }>()
 
 const switching = computed(() => (props.contexts?.length ?? 0) > 1)
@@ -153,11 +239,16 @@ const flatItems = computed<SidebarItem[]>(() =>
   (props.sections ? props.sections.flatMap((s) => s.items) : (props.items ?? [])).flatMap((i) => [i, ...(i.children ?? [])]),
 )
 
+// Compared in one spelling, so "/billing/" and "//billing" are "/billing".
+const SLASH_RUN = /\/{2,}/g
+const TRAILING_SLASH = /(?<=.)\/$/
+const cleanPath = computed(() => props.path?.replace(SLASH_RUN, "/").replace(TRAILING_SLASH, ""))
+
 // Default active test: exact match for "/", prefix match (on a segment
 // boundary) otherwise — so "/billing" doesn't light up on "/billing-x".
 function matchesPath(item: SidebarItem): boolean {
-  if (item.id === "/") return props.path === "/"
-  return props.path === item.id || props.path!.startsWith(`${item.id}/`)
+  if (item.id === "/") return cleanPath.value === "/"
+  return cleanPath.value === item.id || cleanPath.value!.startsWith(`${item.id}/`)
 }
 
 // Only the LONGEST match lights up. A parent whose id prefixes its children —
@@ -193,7 +284,7 @@ const pageTitle = computed(() => {
 const drawerOpen = defineModel<boolean>("open", { default: false })
 const text = useLabels(
   "appShell",
-  { openMenu: "Open menu", skipToContent: "Skip to content" },
+  { openMenu: "Open menu", skipToContent: "Skip to content", backToTop: "Back to top", aside: "Details", contextNav: "In this section" },
   () => props.labels,
 )
 
@@ -204,27 +295,230 @@ const text = useLabels(
  * A full-bleed page owns its scrolling, so the shell leaves it alone.
  */
 const scrollArea = ref<{ viewportEl: HTMLElement | null } | null>(null)
+const asideArea = ref<{ viewportEl: HTMLElement | null } | null>(null)
+const pageEl = ref<HTMLElement | null>(null)
 const bleedId = `lp-shell-bleed-${useId()}`
 const mounted = ref(false)
 onMounted(() => (mounted.value = true))
 const bleeding = computed(() => props.fullBleed && mounted.value)
+const documentScroll = props.scroll !== "region"
+// The window scrolls the page; a full-bleed page holds the shell to the viewport.
+const windowScrolls = computed(() => documentScroll && !props.fullBleed)
 const mainId = `lp-main-${useId()}`
 
 // Focus instead of following the hash, which a router would treat as a navigation.
+const mainEl = ref<HTMLElement | null>(null)
 function skipToMain() {
-  document.getElementById(mainId)?.focus()
+  mainEl.value?.focus()
 }
 
 watch(
   () => props.path,
   () => {
     if (drawerOpen.value) drawerOpen.value = false
+    headerCollapsed.value = false
   },
 )
+function pageScroller(): HTMLElement | null | undefined {
+  if (bleeding.value) return null
+  if (!documentScroll) return scrollArea.value?.viewportEl
+  return (pageEl.value?.ownerDocument.scrollingElement as HTMLElement | null | undefined) ?? null
+}
 useScrollMemory(
-  () => (bleeding.value ? null : scrollArea.value?.viewportEl),
+  pageScroller,
   () => props.path,
   () => props.hash,
+  "",
+  // The sticky header covers the top of the window; a region starts below it.
+  () => (documentScroll && !bleeding.value ? (headerEl.value?.offsetHeight ?? 0) : 0),
+)
+// The side region keeps its own place on the same address.
+useScrollMemory(
+  () => asideArea.value?.viewportEl,
+  () => props.path,
+  () => undefined,
+  "aside:",
+)
+
+const headerCollapsed = ref(false)
+const scrolledFar = ref(false)
+const backToTopAfter = computed(() => (typeof props.backToTop === "number" ? props.backToTop : BACK_TO_TOP_AFTER_PX))
+let lastTop = 0
+
+function onScrolled(top: number, max: number) {
+  if (!props.headerCollapse && !props.backToTop) return
+  if (props.headerCollapse) headerCollapsed.value = headerCollapsedAfter(headerCollapsed.value, lastTop, top, max)
+  scrolledFar.value = top > backToTopAfter.value
+  lastTop = top
+}
+function onMainScroll(event: Event) {
+  const view = event.target as HTMLElement
+  onScrolled(view.scrollTop, view.scrollHeight - view.clientHeight)
+}
+function onWindowScroll() {
+  const view = pageScroller()
+  if (view) onScrolled(view.scrollTop, view.scrollHeight - view.clientHeight)
+}
+
+const headerHidden = computed(() => headerCollapsed.value && !bleeding.value)
+const HEADER_HEIGHT = "4rem"
+const headerHeight = computed(() => (props.safeArea ? `calc(${HEADER_HEIGHT} + env(safe-area-inset-top))` : HEADER_HEIGHT))
+
+/*
+ * A full-bleed page shrinks the document to the viewport, which loses the
+ * place; it is taken back on the way out, unless the page changed in between.
+ *
+ * No scroll-padding-top on the document for the sticky header: with it the
+ * browser counts the header as covered by itself, and a control in it taking
+ * focus scrolled the page (by 350 px, measured). Anchors get the header's
+ * height from scroll memory instead.
+ */
+let bleedTop: number | undefined
+watch(
+  () => props.path,
+  () => (bleedTop = undefined),
+)
+watch(bleeding, (bleed) => {
+  if (!documentScroll) return
+  const view = pageEl.value?.ownerDocument.scrollingElement
+  if (!view) return
+  if (bleed) bleedTop = view.scrollTop
+  else if (bleedTop !== undefined) {
+    const top = bleedTop
+    bleedTop = undefined
+    void nextTick(() => view.scrollTo({ top, behavior: "instant" }))
+  }
+})
+// The bottom bar's height, for the page's scrollbar to stop above it (0 where it is hidden).
+const bottomBarEl = ref<{ $el: HTMLElement } | null>(null)
+const bottomBarHeight = ref(0)
+let bottomBarSize: ResizeObserver | undefined
+onMounted(() => {
+  const el = bottomBarEl.value?.$el
+  if (!el || el.nodeType !== 1) return
+  bottomBarSize = new (nodeWindow(el).ResizeObserver)(() => (bottomBarHeight.value = el.offsetHeight))
+  bottomBarSize.observe(el)
+})
+onBeforeUnmount(() => bottomBarSize?.disconnect())
+
+let releaseDocument: (() => void) | undefined
+onMounted(() => {
+  if (!documentScroll || !pageEl.value) return
+  const win = nodeWindow(pageEl.value)
+  win.addEventListener("scroll", onWindowScroll, { passive: true })
+  releaseDocument = () => win.removeEventListener("scroll", onWindowScroll)
+})
+onBeforeUnmount(() => releaseDocument?.())
+
+function scrollToTop() {
+  const view = pageScroller()
+  if (!view) return
+  view.scrollTo({ top: 0, behavior: prefersReducedMotion(nodeWindow(view)) ? "instant" : "smooth" })
+  // The button is about to leave, and focus must not leave with it.
+  mainEl.value?.focus()
+}
+
+const headerClass = computed(() =>
+  mergeClass(
+    "relative flex h-16 shrink-0 items-center gap-3 border-b border-line bg-surface px-4 md:px-6",
+    windowScrolls.value && `${STICKY} top-0`,
+    props.headerCollapse &&
+      (windowScrolls.value ? "transition-transform" : "transition-[margin-top]") + " duration-[var(--duration-medium)] ease-[var(--ease-settle)]",
+    props.safeArea &&
+      "h-[calc(4rem+env(safe-area-inset-top))] pt-[env(safe-area-inset-top)] pl-[max(1rem,env(safe-area-inset-left))] pr-[max(1rem,env(safe-area-inset-right))] md:pl-[max(1.5rem,env(safe-area-inset-left))] md:pr-[max(1.5rem,env(safe-area-inset-right))]",
+  ),
+)
+const pageClass = computed(() =>
+  mergeClass(
+    DENSITY_CLASS[props.density ?? "comfortable"],
+    props.contentClass,
+    props.safeArea && !props.bottomNav && "pb-[calc(1.5rem+env(safe-area-inset-bottom))]",
+  ),
+)
+
+// Fades on one clock, read from the page's own tokens. Post flush: a teleported
+// action arrives with the render that brought the page.
+const headerEl = ref<HTMLElement | null>(null)
+const bleedEl = ref<HTMLElement | null>(null)
+watch(
+  () => props.path,
+  () => {
+    const content = bleeding.value ? bleedEl.value : documentScroll ? pageEl.value : scrollArea.value?.viewportEl
+    if (!props.pageTransition || !content || prefersReducedMotion(nodeWindow(content))) return
+    const timing = { duration: durationToken("duration-medium", undefined, content), easing: easingToken("ease-settle", undefined, content) }
+    // Title and actions; the burger is the frame, not the page.
+    const header = headerEl.value?.querySelectorAll(":scope > :not(button)") ?? []
+    for (const el of [content, ...header]) el.animate({ opacity: [0, 1] }, timing)
+  },
+  { flush: "post" },
+)
+
+const slots = useSlots()
+const hasAside = computed(() => !!slots.aside)
+const ASIDE_VISIBLE: Record<NavBreakpoint, string> = {
+  sm: "hidden sm:flex",
+  md: "hidden md:flex",
+  lg: "hidden lg:flex",
+  xl: "hidden xl:flex",
+  "2xl": "hidden 2xl:flex",
+}
+const asideClasses = computed(() =>
+  mergeClass(
+    "min-h-0 w-80 flex-col border-l border-line bg-surface",
+    windowScrolls.value &&
+      "sticky top-(--lp-shell-top) h-[calc(100dvh-var(--lp-shell-top))] self-start transition-[top,height] duration-[var(--duration-medium)] ease-[var(--ease-settle)]",
+    ASIDE_VISIBLE[props.asideBreakpoint ?? props.mobileBreakpoint],
+    props.asideClass,
+  ),
+)
+
+/*
+ * The aside takes a grid column rather than a wrapper around main: a wrapper
+ * that comes and goes with the slot would remount the page. Header, the
+ * sub-page row and the bottom bar span both columns.
+ */
+const columnClass = computed(() => (hasAside.value ? "grid min-w-0 flex-1 grid-cols-[minmax(0,1fr)_auto]" : "flex min-w-0 flex-1 flex-col"))
+const columnStyle = computed(() => ({
+  ...(hasAside.value ? { gridTemplateRows: `auto ${contextVisible.value ? "auto " : ""}minmax(0,1fr) auto` } : {}),
+  ...(windowScrolls.value ? { "--lp-shell-top": shellTop.value } : {}),
+}))
+const spanClass = computed(() => (hasAside.value ? "col-span-2" : undefined))
+
+// One width rather than a media query per breakpoint: those report one by one,
+// so a jump across two passed through a mode the window was never in.
+const view = useView()
+const width = ref(0)
+const measureWidth = () => (width.value = viewWindow(view.value).innerWidth)
+onMounted(() => {
+  measureWidth()
+  viewWindow(view.value).addEventListener("resize", measureWidth)
+})
+onBeforeUnmount(() => viewWindow(view.value).removeEventListener("resize", measureWidth))
+
+// Before mount there is no width: a server render is the plain rail.
+const navMode = computed<NavMode>(() =>
+  mounted.value
+    ? resolveNavMode((breakpoint) => width.value >= NAV_BREAKPOINT_PX[breakpoint], {
+        mobileBreakpoint: props.mobileBreakpoint,
+        bottomNav: !!props.bottomNav,
+        compactBelow: props.adaptiveNav?.compactBelow,
+      })
+    : "rail",
+)
+watch(navMode, (mode) => emit("nav-mode", mode))
+
+// What a person chose by hand, for as long as the width stays in this mode.
+const handCompact = ref<boolean | undefined>()
+watch(navMode, () => (handCompact.value = undefined))
+const railCompact = computed(() => props.compact ?? handCompact.value ?? (navMode.value === "compact" ? true : undefined))
+function onCompact(value: boolean) {
+  if (props.adaptiveNav) handCompact.value = value
+  emit("update:compact", value)
+}
+
+const contextItems = computed(() => (props.adaptiveNav?.contextNav ? contextNavItems(topItems.value, activeTest.value) : []))
+const contextVisible = computed(
+  () => (navMode.value === "bottom" || navMode.value === "drawer") && (contextItems.value.length > 0 || (!!slots["context-nav"] && !!props.adaptiveNav?.contextNav)),
 )
 
 function onSelect(item: SidebarItem) {
@@ -260,11 +554,33 @@ function onBottom(item: SidebarItem) {
 
 // Expose the burger trigger so a host can omit its own header entirely.
 const _openDrawer = () => (drawerOpen.value = true)
-defineExpose({ openDrawer: _openDrawer })
+defineExpose({ openDrawer: _openDrawer, navMode })
+
+// In region mode the shell claims the full viewport height, which is wrong when it is embedded in a page that already has a header of its own.
+// The document mode clips sideways with `clip`, not `hidden`: a hidden overflow would make the root the sticky children's scroller.
+const { class: rootClass, attrs: rest } = useMergedAttrs(() =>
+  windowScrolls.value ? "flex min-h-dvh overflow-x-clip bg-surface text-ink" : "flex h-dvh overflow-hidden bg-surface text-ink",
+)
 
-// The shell claims the full viewport height, which is wrong when it is embedded in a page that already has a header of its own.
-const { class: rootClass, attrs: rest } = useMergedAttrs(
-  "flex h-dvh overflow-hidden bg-surface text-ink",
+/*
+ * What stays in view while the window scrolls the page. The header sits on
+ * top; the row of sub-pages and the aside sit under it, following it out
+ * when it collapses (--lp-shell-top is how much of the header is showing).
+ */
+const STICKY = "sticky z-(--z-sticky)"
+const railClass = computed(() => (windowScrolls.value ? "sticky top-0 flex h-dvh shrink-0 self-start" : "contents"))
+const shellTop = computed(() => (headerHidden.value ? "0px" : headerHeight.value))
+const BACK_TO_TOP_ABOVE_BAR: Record<NavBreakpoint, string> = {
+  sm: "bottom-[calc(4.5rem+env(safe-area-inset-bottom))] sm:bottom-[calc(1rem+env(safe-area-inset-bottom))]",
+  md: "bottom-[calc(4.5rem+env(safe-area-inset-bottom))] md:bottom-[calc(1rem+env(safe-area-inset-bottom))]",
+  lg: "bottom-[calc(4.5rem+env(safe-area-inset-bottom))] lg:bottom-[calc(1rem+env(safe-area-inset-bottom))]",
+  xl: "bottom-[calc(4.5rem+env(safe-area-inset-bottom))] xl:bottom-[calc(1rem+env(safe-area-inset-bottom))]",
+  "2xl": "bottom-[calc(4.5rem+env(safe-area-inset-bottom))] 2xl:bottom-[calc(1rem+env(safe-area-inset-bottom))]",
+}
+const backToTopClass = computed(() =>
+  windowScrolls.value
+    ? ["fixed right-6 z-(--z-sticky)", props.bottomNav ? BACK_TO_TOP_ABOVE_BAR[props.mobileBreakpoint] : "bottom-[calc(1rem+env(safe-area-inset-bottom))]"]
+    : "absolute bottom-[calc(1rem+env(safe-area-inset-bottom))] right-6",
 )
 </script>
 
@@ -279,6 +595,10 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
     >
       {{ text.skipToContent }}
     </a>
+    <!-- The rail's own box: a viewport-tall sticky column while the window
+         scrolls the page, and no box at all (contents) in the region frame,
+         where the rail is the frame's full height already. -->
+    <div :class="railClass">
     <LpSidebar
       :model-value="modelValue"
       :items="items"
@@ -292,7 +612,7 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
       :loading="loading"
       :collapsed="collapsed"
       :auto-collapse-after="autoCollapseAfter"
-      :compact="compact"
+      :compact="railCompact"
       :resizable="resizable"
       :pinnable="pinnable"
       :pinned="pinned"
@@ -303,7 +623,7 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
       :hints="hints"
       class="shrink-0"
       @update:model-value="onModel"
-      @update:compact="(v) => emit('update:compact', v)"
+      @update:compact="onCompact"
       @update:pinned="(v) => emit('update:pinned', v)"
       @update:open="(v) => (drawerOpen = v)"
       @update:collapsed="(v) => emit('update:collapsed', v)"
@@ -334,9 +654,10 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
         <slot name="sidebar-item" v-bind="slotProps" />
       </template>
     </LpSidebar>
+    </div>
 
     <!-- Main column: header + the single scroll region. -->
-    <div class="flex min-w-0 flex-1 flex-col">
+    <div :class="columnClass" :style="columnStyle">
       <!-- `relative` so a consumer can centre something — section tabs, a
            search box — against the WHOLE bar. Centring it inside the title
            block instead makes its position depend on how wide the actions are,
@@ -344,7 +665,10 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
            59 px off centre with two actions and 77 px with three, which reads
            as the navigation drifting rather than the page changing. -->
       <header
-        class="relative flex h-16 shrink-0 items-center gap-3 border-b border-line bg-surface px-4 md:px-6"
+        ref="headerEl"
+        :class="[headerClass, spanClass]"
+        :style="headerHidden ? (windowScrolls ? { transform: 'translateY(-100%)' } : { marginTop: `calc(-1 * ${headerHeight})` }) : undefined"
+        @focusin="headerCollapsed = false"
       >
         <LpButton
           :class="burgerClass"
@@ -398,26 +722,63 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
            tab going from a full-bleed page to a padded one cut instead of
            playing its transition, and lost the page's state. Until mount the
            page stays in the scroll region, which is what a server render has. -->
-      <main :id="mainId" tabindex="-1" class="flex min-h-0 flex-1 flex-col outline-none">
-        <div v-show="bleeding" :id="bleedId" class="min-h-0 flex-1 overflow-hidden" />
+      <template v-if="contextVisible">
+        <slot name="context-nav" :items="contextItems" :mode="navMode">
+          <AppShellContextNav
+            :class="[spanClass, windowScrolls && `${STICKY} top-(--lp-shell-top) transition-[top] duration-[var(--duration-medium)] ease-[var(--ease-settle)]`]"
+            :items="contextItems"
+            :is-active="activeTest"
+            :label="text.contextNav"
+            @select="onBottom"
+          />
+        </slot>
+      </template>
+      <main ref="mainEl" :id="mainId" tabindex="-1" :data-lp-density="density" :class="['flex min-h-0 flex-1 flex-col outline-none', backToTop && 'relative']">
+        <div ref="bleedEl" v-show="bleeding" :id="bleedId" class="min-h-0 flex-1 overflow-hidden" />
+        <div v-if="documentScroll" v-show="!bleeding" ref="pageEl" :class="['flex-1', pageClass]">
+          <Teleport :to="`#${bleedId}`" :disabled="!bleeding" defer>
+            <slot />
+          </Teleport>
+        </div>
         <LpScrollArea
+          v-else
           v-show="!bleeding"
           ref="scrollArea"
           class="min-h-0 flex-1"
-          :content-class="mergeClass('px-4 py-6 md:px-6', contentClass)"
+          :content-class="pageClass"
+          @scroll="onMainScroll"
         >
           <Teleport :to="`#${bleedId}`" :disabled="!bleeding" defer>
             <slot />
           </Teleport>
         </LpScrollArea>
+        <LpButton
+          v-if="backToTop && scrolledFar && !bleeding"
+          :class="backToTopClass"
+          variant="outline"
+          size="sm"
+          square
+          :aria-label="text.backToTop"
+          @click="scrollToTop"
+        >
+          <LpIcon name="lucide:arrow-up" :size="16" />
+        </LpButton>
       </main>
+      <aside v-if="hasAside" :aria-label="text.aside" :class="asideClasses">
+        <LpScrollArea ref="asideArea" class="min-h-0 flex-1" content-class="p-4">
+          <slot name="aside" />
+        </LpScrollArea>
+      </aside>
+      <LpPageScrollbar v-if="windowScrolls && pageScrollbar" top="var(--lp-shell-top)" :bottom="`${bottomBarHeight}px`" />
       <LpBottomNav
         v-if="bottomNav"
-        :class="burgerHidden[mobileBreakpoint]"
+        ref="bottomBarEl"
+        :class="[burgerHidden[mobileBreakpoint], spanClass, windowScrolls && `${STICKY} bottom-0`]"
         :items="bottomItems"
         :is-active="activeTest"
         more
         :more-active="moreActive"
+        :more-expanded="drawerOpen"
         @select="onBottom"
         @more="drawerOpen = true"
       />

package/src/components/LpAutocomplete.vue

@@ -10,6 +10,8 @@ export type AutocompleteLabels = {
 </script>
 
 <script setup lang="ts">
+import IconCloseButton from "./IconCloseButton.vue"
+import { CONTROL_SIZE } from "./controlSize"
 import { usePaletteControl, type PaletteControlOptions } from "../composables/usePaletteCommands"
 /*
  * Free-text autocomplete — a text field that suggests as you type but never
@@ -33,11 +35,11 @@ import {
   ComboboxRoot,
   ComboboxViewport,
 } from "reka-ui"
-import { computed, nextTick, ref, useAttrs, useId, watch } from "vue"
-import { useFieldControl } from "../composables/useField"
+import { computed, nextTick, ref, useId, watch } from "vue"
+import { useAttrsField, mergeDescribedBy } from "../composables/useField"
 import { useInputFilter } from "../composables/useInputFilter"
 import { useLabels } from "../composables/useLpConfig"
-import { CLOSE_ICON, OPTION_ITEM, optionStagger, POPOVER_PANEL } from "./dropdown"
+import { CLOSE_ICON, OPTION_ITEM, optionStagger, COMBOBOX_PANEL, POPOVER_PANEL } from "./dropdown"
 import LpIcon from "./LpIcon.vue"
 import OptionContent from "./OptionContent.vue"
 import type { LpOptionBase, OptionSelection } from "./options"
@@ -115,18 +117,12 @@ const text = computed<string>({
 
 // class/style lay out the whole control; every other attr (name, autocomplete,
 // @blur, @keydown…) belongs to the text <input>.
-const attrs = useAttrs()
 const inputAttrs = computed(() => {
   const { class: _c, style: _s, ...rest } = attrs
   return rest
 })
 
-const field = useFieldControl(() => ({
-  wrapped: false,
-  id: typeof attrs.id === "string" ? attrs.id : undefined,
-  invalid: props.invalid || isInvalid(props.modelValue),
-  disabled: props.disabled,
-}))
+const { attrs, field } = useAttrsField(() => ({ invalid: props.invalid || isInvalid(props.modelValue), disabled: props.disabled }))
 const isInvalidState = computed(() => field.value.invalid)
 const labels = useLabels<AutocompleteLabels>(
   "autocomplete",
@@ -179,7 +175,7 @@ watch(
 // reader is told who it is through a description.
 const selectedId = useId()
 const describedBy = computed(() =>
-  [field.value.describedBy, showSelected.value ? selectedId : undefined].filter(Boolean).join(" ") || undefined,
+  mergeDescribedBy(attrs["aria-describedby"], field.value.describedBy, showSelected.value ? selectedId : undefined),
 )
 
 // Threshold met AND something to show → the list is allowed to open.
@@ -210,11 +206,7 @@ function onOpenChange(next: boolean) {
 
 const hasValue = computed(() => (props.modelValue ?? "").length > 0)
 
-const anchorSize = {
-  sm: "h-(--size-control-sm) text-xs",
-  md: "h-(--size-control-md) text-sm",
-  lg: "h-(--size-control-lg) text-sm",
-}
+const anchorSize = CONTROL_SIZE
 
 function onInput(event: Event) {
   filterInput(event)
@@ -373,20 +365,13 @@ usePaletteControl({ disabled: () => field.value.disabled, invalid: () => field.v
           </span>
         </Transition>
       </div>
-      <button
+      <IconCloseButton
         v-if="clearable && hasValue && !field.disabled"
-        type="button"
-        class="group flex shrink-0 items-center text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink"
-        :aria-label="labels.clear"
+        inline
+        :label="labels.clear"
         @pointerdown.prevent
         @click="clear"
-      >
-        <LpIcon
-          name="lucide:x"
-          :size="16"
-          :class="CLOSE_ICON"
-        />
-      </button>
+      />
     </ComboboxAnchor>
 
     <!-- A press on the list keeps focus in the field. Otherwise the field
@@ -397,9 +382,7 @@ usePaletteControl({ disabled: () => field.value.disabled, invalid: () => field.v
       <ComboboxContent
         @interact-outside="guardOutside"
         @escape-key-down="guardOutside"
-        :collision-padding="8"
-        position="popper"
-        :side-offset="6"
+        v-bind="COMBOBOX_PANEL"
         :class="[POPOVER_PANEL, 'z-(--z-popover) max-h-72 w-(--reka-combobox-trigger-width) overflow-hidden']"
         @open-auto-focus.prevent
         @mousedown.prevent