@leavepulse/ui 0.72.8 → 0.73.0

package/dist/chunks/{LpAppShell-CPCG0I-c.js → LpAppShell-rr5kqiK3.js}

@@ -1,5 +1,6 @@
 import { defineComponent, computed, useModel, ref, useId, onMounted, watch, openBlock, createElementBlock, mergeProps, unref, createElementVNode, withModifiers, toDisplayString, createVNode, createSlots, withCtx, renderSlot, normalizeProps, guardReactiveProps, normalizeClass, withDirectives, vShow, createBlock, Teleport, createCommentVNode, mergeModels } from "vue";
 import { useLabels } from "../composables/useLpConfig.js";
+import { useScrollMemory } from "../composables/scrollMemory.js";
 import { _ as _sfc_main$6 } from "./LpBottomNav-CbNQQPuL.js";
 import { _ as _sfc_main$2 } from "./LpButton-CFb44IjC.js";
 import { _ as _sfc_main$3 } from "./LpIcon--5WSb3jJ.js";
@@ -22,6 +23,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     autoCollapseAfter: {},
     modelValue: {},
     path: {},
+    hash: {},
     isActive: {},
     title: {},
     mobileBreakpoint: { default: "lg" },
@@ -88,9 +90,13 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       () => props.path,
       () => {
         if (drawerOpen.value) drawerOpen.value = false;
-        scrollArea.value?.viewportEl?.scrollTo({ top: 0, left: 0, behavior: "instant" });
       }
     );
+    useScrollMemory(
+      () => bleeding.value ? null : scrollArea.value?.viewportEl,
+      () => props.path,
+      () => props.hash
+    );
     function onSelect(item) {
       emit("select", item);
     }

package/dist/chunks/{LpTableOfContents-CraicEs4.js → LpTableOfContents-BN5zvpnx.js}

@@ -1,7 +1,7 @@
 import { defineComponent, computed, ref, useId, onMounted, watch, onBeforeUnmount, openBlock, createElementBlock, createElementVNode, toDisplayString, Fragment, renderList, normalizeStyle, normalizeClass, createBlock, unref, createCommentVNode, createTextVNode } from "vue";
 import { Motion } from "motion-v";
 import { useLabels } from "../composables/useLpConfig.js";
-import { scrollParent, atScrollEnd } from "../composables/scroll.js";
+import { scrollParent, scrollToElement, scrollMarginTop, atScrollEnd } from "../composables/scroll.js";
 import { usePillTransition } from "../composables/usePillTransition.js";
 const _hoisted_1 = ["aria-label"];
 const _hoisted_2 = { class: "mb-2.5 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted" };
@@ -103,7 +103,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       ev.preventDefault();
       activeId.value = id;
       suppressSpyUntilScrollEnds(el);
-      el.scrollIntoView({ behavior: "smooth", block: "start" });
+      scrollToElement(el, { block: "start", behavior: "smooth", margin: scrollMarginTop(el) });
       history.replaceState(history.state, "", `#${id}`);
     }
     onMounted(setup);

package/dist/components/LpAppShell.vue.d.ts

@@ -16,8 +16,18 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
      * The current route path. Enables the built-in prefix-match active test and
      * the derived page title without the host wiring its own `isActive`. Pass
      * `route.path`. Ignored when a custom `isActive` is provided.
+     *
+     * A new path also places the page in the shell's scroll region: back and
+     * forward return to where it was left, a `hash` lands on that anchor
+     * (honouring its `scroll-margin-top`), anything else starts at the top.
      */
     path?: string;
+    /**
+     * The current route hash (`route.hash`). With `path` it lands a page on
+     * its anchor; a new hash on the same path glides there, after a dialog
+     * that started the jump has closed.
+     */
+    hash?: string;
     /**
      * Custom active test (router-driven nav). Overrides `path`/`modelValue`.
      */
@@ -97,8 +107,18 @@ declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
      * The current route path. Enables the built-in prefix-match active test and
      * the derived page title without the host wiring its own `isActive`. Pass
      * `route.path`. Ignored when a custom `isActive` is provided.
+     *
+     * A new path also places the page in the shell's scroll region: back and
+     * forward return to where it was left, a `hash` lands on that anchor
+     * (honouring its `scroll-margin-top`), anything else starts at the top.
      */
     path?: string;
+    /**
+     * The current route hash (`route.hash`). With `path` it lands a page on
+     * its anchor; a new hash on the same path glides there, after a dialog
+     * that started the jump has closed.
+     */
+    hash?: string;
     /**
      * Custom active test (router-driven nav). Overrides `path`/`modelValue`.
      */

package/dist/components/LpAppShell.vue.js

@@ -1,4 +1,4 @@
-import { _ as _sfc_main } from "../chunks/LpAppShell-CPCG0I-c.js";
+import { _ as _sfc_main } from "../chunks/LpAppShell-rr5kqiK3.js";
 export {
   _sfc_main as default
 };

package/dist/components/LpTableOfContents.vue.js

@@ -1,4 +1,4 @@
-import { _ as _sfc_main } from "../chunks/LpTableOfContents-CraicEs4.js";
+import { _ as _sfc_main } from "../chunks/LpTableOfContents-BN5zvpnx.js";
 export {
   _sfc_main as default
 };

package/dist/composables/scroll.d.ts

@@ -19,4 +19,6 @@ export interface ScrollToElementOptions {
     margin?: number;
 }
 /** Scroll the nearest scroller, and only it, so that `el` is in view. */
+/** The element's own `scroll-margin-top`, the gap it asks to keep above it when scrolled to. */
+export declare function scrollMarginTop(el: Element): number;
 export declare function scrollToElement(el: Element | null | undefined, { block, behavior, margin }?: ScrollToElementOptions): void;

package/dist/composables/scroll.js

@@ -15,6 +15,9 @@ function atScrollEnd(el, slack = 2) {
   if (!box) return true;
   return box.scrollTop + box.clientHeight >= box.scrollHeight - slack;
 }
+function scrollMarginTop(el) {
+  return Number.parseFloat(getComputedStyle(el).scrollMarginTop) || 0;
+}
 function scrollToElement(el, { block = "nearest", behavior = "auto", margin = 0 } = {}) {
   if (!el) return;
   const doc = el.ownerDocument;
@@ -33,6 +36,7 @@ function scrollToElement(el, { block = "nearest", behavior = "auto", margin = 0
 }
 export {
   atScrollEnd,
+  scrollMarginTop,
   scrollParent,
   scrollToElement
 };

package/dist/composables/scrollMemory.d.ts

@@ -0,0 +1 @@
+export declare function useScrollMemory(viewport: () => HTMLElement | null | undefined, path: () => string | undefined, hash: () => string | undefined): void;

package/dist/composables/scrollMemory.js

@@ -0,0 +1,111 @@
+import { watch, nextTick, onMounted, onBeforeUnmount } from "vue";
+import { scrollMarginTop } from "./scroll.js";
+const SETTLE_MS = 1500;
+const DIALOG_WAIT_MS = 2e3;
+const SETTLE_STOP = ["wheel", "touchstart", "keydown", "pointerdown"];
+const positions = /* @__PURE__ */ new Map();
+function addressKey() {
+  return `${location.pathname}${location.search}`;
+}
+function useScrollMemory(viewport, path, hash) {
+  if (typeof window === "undefined") return;
+  let current = addressKey();
+  let shown = path();
+  let travelled = false;
+  let stopHold;
+  let pending = 0;
+  const onPop = () => {
+    travelled = true;
+  };
+  window.addEventListener("popstate", onPop);
+  function anchor(value) {
+    if (!value || value === "#") return null;
+    const id = decodeURIComponent(value.replace(/^#/, ""));
+    return document.getElementById(id);
+  }
+  function reach(value, behavior) {
+    const view = viewport();
+    const target = anchor(value);
+    if (!view || !target || !view.contains(target)) return false;
+    const top = target.getBoundingClientRect().top - view.getBoundingClientRect().top + view.scrollTop - scrollMarginTop(target);
+    view.scrollTo({ top: Math.max(0, top), behavior });
+    return true;
+  }
+  function hold(land) {
+    stopHold?.();
+    const view = viewport();
+    const content = view?.firstElementChild;
+    land();
+    if (!content) return;
+    const watcher = new ResizeObserver(land);
+    const timer = window.setTimeout(() => stop(), SETTLE_MS);
+    const stop = () => {
+      watcher.disconnect();
+      window.clearTimeout(timer);
+      for (const name of SETTLE_STOP) window.removeEventListener(name, stop, true);
+      if (stopHold === stop) stopHold = void 0;
+    };
+    for (const name of SETTLE_STOP) window.addEventListener(name, stop, { capture: true, passive: true });
+    watcher.observe(content);
+    stopHold = stop;
+  }
+  function arrive() {
+    const back = travelled;
+    travelled = false;
+    current = addressKey();
+    shown = path();
+    const view = viewport();
+    if (!view) return;
+    const saved = positions.get(current);
+    if (back && saved !== void 0) {
+      hold(() => view.scrollTo({ top: saved, behavior: "instant" }));
+      return;
+    }
+    if (hash()) {
+      hold(() => {
+        if (!reach(hash(), "instant")) view.scrollTo({ top: 0, behavior: "instant" });
+      });
+      return;
+    }
+    stopHold?.();
+    view.scrollTo({ top: 0, left: 0, behavior: "instant" });
+  }
+  function afterDialogs(run) {
+    const since = performance.now();
+    const mine = ++pending;
+    const tick = () => {
+      if (mine !== pending) return;
+      const locked = document.querySelector('[role="dialog"]') || getComputedStyle(document.body).overflow === "hidden";
+      if (locked && performance.now() - since < DIALOG_WAIT_MS) requestAnimationFrame(tick);
+      else run();
+    };
+    requestAnimationFrame(tick);
+  }
+  watch(
+    path,
+    () => {
+      const view = viewport();
+      if (view) positions.set(current, view.scrollTop);
+      void nextTick(() => requestAnimationFrame(arrive));
+    },
+    { flush: "pre" }
+  );
+  watch(hash, (next, previous) => {
+    if (next === previous) return;
+    if (path() !== shown) return;
+    afterDialogs(() => {
+      travelled = false;
+      if (!reach(next, "smooth")) viewport()?.scrollTo({ top: 0, behavior: "smooth" });
+    });
+  });
+  onMounted(() => {
+    if (hash()) requestAnimationFrame(() => hold(() => void reach(hash(), "instant")));
+  });
+  onBeforeUnmount(() => {
+    stopHold?.();
+    window.removeEventListener("popstate", onPop);
+  });
+}
+export {
+  useScrollMemory
+};

package/dist/index.js

@@ -4,7 +4,7 @@ import { _ as _3 } from "./chunks/LpMapPicker-DRGgh89B.js";
 import { OSM_TILES, createNominatimProvider, emptyAddress, formatAddress, project, tileUrl, unproject } from "./components/address.js";
 import { _ as _4 } from "./chunks/LpActionBar-BP1ld7-S.js";
 import { _ as _5 } from "./chunks/LpAlert-n5XPAZfv.js";
-import { _ as _6 } from "./chunks/LpAppShell-CPCG0I-c.js";
+import { _ as _6 } from "./chunks/LpAppShell-rr5kqiK3.js";
 import { _ as _7 } from "./chunks/LpAutocomplete-DOu7FN5P.js";
 import { _ as _8 } from "./chunks/LpAvatar-Cg6Az3wz.js";
 import { _ as _9 } from "./chunks/LpBadge-wUYLN4U9.js";
@@ -99,7 +99,7 @@ import { _ as _71 } from "./chunks/LpSwitch-BnXd1llc.js";
 import { default as default12 } from "./components/LpTable.vue.js";
 import { compareValues } from "./components/tableSort.js";
 import { resolveRowMenu } from "./components/tableRowMenu.js";
-import { _ as _72 } from "./chunks/LpTableOfContents-CraicEs4.js";
+import { _ as _72 } from "./chunks/LpTableOfContents-BN5zvpnx.js";
 import { default as default13 } from "./components/LpTabs.vue.js";
 import { _ as _73 } from "./chunks/LpBottomNav-CbNQQPuL.js";
 import { _ as _74 } from "./chunks/LpTagsInput-C-mDG648.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leavepulse/ui",
-  "version": "0.72.8",
+  "version": "0.73.0",
   "type": "module",
   "description": "LeavePulse token-driven Vue component kit.",
   "repository": {

package/src/components/LpAppShell.vue

@@ -33,6 +33,7 @@ export default { inheritAttrs: false }
  */
 import { computed, onMounted, ref, useId, watch } from "vue"
 import { useLabels } from "../composables/useLpConfig"
+import { useScrollMemory } from "../composables/scrollMemory"
 import LpBottomNav from "./LpBottomNav.vue"
 import LpButton from "./LpButton.vue"
 import LpIcon from "./LpIcon.vue"
@@ -59,8 +60,18 @@ const props = withDefaults(
      * The current route path. Enables the built-in prefix-match active test and
      * the derived page title without the host wiring its own `isActive`. Pass
      * `route.path`. Ignored when a custom `isActive` is provided.
+     *
+     * A new path also places the page in the shell's scroll region: back and
+     * forward return to where it was left, a `hash` lands on that anchor
+     * (honouring its `scroll-margin-top`), anything else starts at the top.
      */
     path?: string
+    /**
+     * The current route hash (`route.hash`). With `path` it lands a page on
+     * its anchor; a new hash on the same path glides there, after a dialog
+     * that started the jump has closed.
+     */
+    hash?: string
     /**
      * Custom active test (router-driven nav). Overrides `path`/`modelValue`.
      */
@@ -177,7 +188,8 @@ const text = useLabels(
 /*
  * The page scrolls inside the shell's own region, not the window, so the
  * router's scroll behaviour never reaches it: without this a route change from
- * a scrolled page landed mid-way down the next one.
+ * a scrolled page landed mid-way down the next one, and back never returned.
+ * A full-bleed page owns its scrolling, so the shell leaves it alone.
  */
 const scrollArea = ref<{ viewportEl: HTMLElement | null } | null>(null)
 const bleedId = `lp-shell-bleed-${useId()}`
@@ -195,9 +207,13 @@ watch(
   () => props.path,
   () => {
     if (drawerOpen.value) drawerOpen.value = false
-    scrollArea.value?.viewportEl?.scrollTo({ top: 0, left: 0, behavior: "instant" })
   },
 )
+useScrollMemory(
+  () => (bleeding.value ? null : scrollArea.value?.viewportEl),
+  () => props.path,
+  () => props.hash,
+)
 
 function onSelect(item: SidebarItem) {
   emit("select", item)

package/src/components/LpTableOfContents.vue

@@ -12,7 +12,7 @@
 import { Motion } from "motion-v"
 import { computed, onBeforeUnmount, onMounted, ref, useId, watch } from "vue"
 import { useLabels } from "../composables/useLpConfig"
-import { atScrollEnd, scrollParent } from "../composables/scroll"
+import { atScrollEnd, scrollMarginTop, scrollParent, scrollToElement } from "../composables/scroll"
 import { usePillTransition } from "../composables/usePillTransition"
 
 export interface TocLink {
@@ -170,7 +170,9 @@ function onClick(id: string, ev: MouseEvent) {
   ev.preventDefault()
   activeId.value = id // mark immediately so the bar jumps to the clicked item
   suppressSpyUntilScrollEnds(el)
-  el.scrollIntoView({ behavior: "smooth", block: "start" })
+  // Only the nearest scrolling box moves: scrollIntoView also shifted every
+  // overflow-hidden ancestor, the shell itself among them.
+  scrollToElement(el, { block: "start", behavior: "smooth", margin: scrollMarginTop(el) })
   // Keep the router's own state: replacing it with null broke scroll
   // restoration and back/forward bookkeeping in vue-router apps.
   history.replaceState(history.state, "", `#${id}`)

package/src/composables/scroll.ts

@@ -46,6 +46,11 @@ export interface ScrollToElementOptions {
 }
 
 /** Scroll the nearest scroller, and only it, so that `el` is in view. */
+/** The element's own `scroll-margin-top`, the gap it asks to keep above it when scrolled to. */
+export function scrollMarginTop(el: Element): number {
+  return Number.parseFloat(getComputedStyle(el).scrollMarginTop) || 0
+}
+
 export function scrollToElement(
   el: Element | null | undefined,
   { block = "nearest", behavior = "auto", margin = 0 }: ScrollToElementOptions = {},

package/src/composables/scrollMemory.ts

@@ -0,0 +1,145 @@
+import { nextTick, onBeforeUnmount, onMounted, watch } from "vue"
+import { scrollMarginTop } from "./scroll"
+
+/*
+ * Where a page lands when the shell's own scroll region changes page. The
+ * region is not the window, so a router's scrollBehavior never reaches it, and
+ * the shell has to answer the questions a browser answers for a plain site:
+ *
+ *  - back and forward return to where the page was left;
+ *  - an address with a hash lands on that anchor, and stays on it while the
+ *    page is still growing (a lazily loaded body, images), until the reader
+ *    scrolls or a moment has passed;
+ *  - a new hash on the same page glides there, once a dialog that started the
+ *    jump (a palette, a menu) has let go of the page;
+ *  - anything else starts at the top.
+ *
+ * The router is not needed: what changed is read from the shell's `path` and
+ * `hash` props, history position from `popstate`, and positions are keyed by
+ * the address the browser shows.
+ */
+
+const SETTLE_MS = 1500
+const DIALOG_WAIT_MS = 2000
+const SETTLE_STOP = ["wheel", "touchstart", "keydown", "pointerdown"] as const
+
+const positions = new Map<string, number>()
+
+function addressKey(): string {
+  return `${location.pathname}${location.search}`
+}
+
+export function useScrollMemory(
+  viewport: () => HTMLElement | null | undefined,
+  path: () => string | undefined,
+  hash: () => string | undefined,
+): void {
+  if (typeof window === "undefined") return
+  let current = addressKey()
+  let shown = path()
+  let travelled = false
+  let stopHold: (() => void) | undefined
+  let pending = 0
+
+  const onPop = () => {
+    travelled = true
+  }
+  window.addEventListener("popstate", onPop)
+
+  function anchor(value: string | undefined): HTMLElement | null {
+    if (!value || value === "#") return null
+    const id = decodeURIComponent(value.replace(/^#/, ""))
+    return document.getElementById(id)
+  }
+
+  function reach(value: string | undefined, behavior: ScrollBehavior): boolean {
+    const view = viewport()
+    const target = anchor(value)
+    if (!view || !target || !view.contains(target)) return false
+    const top = target.getBoundingClientRect().top - view.getBoundingClientRect().top + view.scrollTop - scrollMarginTop(target)
+    view.scrollTo({ top: Math.max(0, top), behavior })
+    return true
+  }
+
+  // Re-applies a landing while the page below it keeps changing size.
+  function hold(land: () => void) {
+    stopHold?.()
+    const view = viewport()
+    const content = view?.firstElementChild
+    land()
+    if (!content) return
+    const watcher = new ResizeObserver(land)
+    const timer = window.setTimeout(() => stop(), SETTLE_MS)
+    const stop = () => {
+      watcher.disconnect()
+      window.clearTimeout(timer)
+      for (const name of SETTLE_STOP) window.removeEventListener(name, stop, true)
+      if (stopHold === stop) stopHold = undefined
+    }
+    for (const name of SETTLE_STOP) window.addEventListener(name, stop, { capture: true, passive: true })
+    watcher.observe(content)
+    stopHold = stop
+  }
+
+  function arrive() {
+    const back = travelled
+    travelled = false
+    current = addressKey()
+    shown = path()
+    const view = viewport()
+    if (!view) return
+    const saved = positions.get(current)
+    if (back && saved !== undefined) {
+      hold(() => view.scrollTo({ top: saved, behavior: "instant" }))
+      return
+    }
+    if (hash()) {
+      hold(() => {
+        if (!reach(hash(), "instant")) view.scrollTo({ top: 0, behavior: "instant" })
+      })
+      return
+    }
+    stopHold?.()
+    view.scrollTo({ top: 0, left: 0, behavior: "instant" })
+  }
+
+  function afterDialogs(run: () => void) {
+    const since = performance.now()
+    const mine = ++pending
+    const tick = () => {
+      if (mine !== pending) return
+      const locked = document.querySelector('[role="dialog"]') || getComputedStyle(document.body).overflow === "hidden"
+      if (locked && performance.now() - since < DIALOG_WAIT_MS) requestAnimationFrame(tick)
+      else run()
+    }
+    requestAnimationFrame(tick)
+  }
+
+  watch(
+    path,
+    () => {
+      const view = viewport()
+      if (view) positions.set(current, view.scrollTop)
+      void nextTick(() => requestAnimationFrame(arrive))
+    },
+    { flush: "pre" },
+  )
+
+  watch(hash, (next, previous) => {
+    if (next === previous) return
+    if (path() !== shown) return
+    afterDialogs(() => {
+      travelled = false
+      if (!reach(next, "smooth")) viewport()?.scrollTo({ top: 0, behavior: "smooth" })
+    })
+  })
+
+  onMounted(() => {
+    if (hash()) requestAnimationFrame(() => hold(() => void reach(hash(), "instant")))
+  })
+
+  onBeforeUnmount(() => {
+    stopHold?.()
+    window.removeEventListener("popstate", onPop)
+  })
+}