@mkbabb/glass-ui 0.2.0

package/src/components/custom/sidebar/composables/useScrollTracker.ts

@@ -0,0 +1,242 @@
+/**
+ * Tracks which tree node is currently visible via IntersectionObserver,
+ * with a scroll-event fallback for fast scrollbar drags.
+ * Deepest visible node wins.
+ *
+ * Generic over `T extends TreeNode` — pass a custom `getChildren` callback
+ * for tree structures whose children are stored under a different property.
+ */
+import { ref, computed, watch, onMounted, onUnmounted, nextTick, toValue } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+import type { TreeNode, TreeIndexEntry, ScrollTrackerOptions } from "../types";
+
+export function useScrollTracker<T extends TreeNode>(
+    roots: MaybeRefOrGetter<T[]>,
+    index: MaybeRefOrGetter<Map<string, TreeIndexEntry<T>>>,
+    options?: ScrollTrackerOptions & {
+        getChildren?: (node: T) => T[] | undefined;
+        scrollContainer?: Ref<HTMLElement | null>;
+    },
+) {
+    const getChildren =
+        options?.getChildren ?? ((n: T) => n.children as T[] | undefined);
+    const rootMargin = options?.rootMargin ?? "-20% 0px -60% 0px";
+    const threshold = options?.threshold ?? 0;
+
+    const activeId = ref<string | null>(null);
+    const sectionVisibility = new Map<string, boolean>();
+    let observer: IntersectionObserver | null = null;
+    const observedIds = new Set<string>();
+    let locked = false;
+    let mounted = false;
+
+    function lockTracking() {
+        locked = true;
+    }
+    function unlockTracking() {
+        locked = false;
+    }
+
+    const activeRootId = computed(() => {
+        if (!activeId.value) return null;
+        return toValue(index).get(activeId.value)?.parentId ?? null;
+    });
+
+    function findDeepestVisible(list: T[]): string | null {
+        for (const node of list) {
+            const children = getChildren(node);
+            if (children) {
+                const deep = findDeepestVisible(children);
+                if (deep) return deep;
+            }
+            if (sectionVisibility.get(node.id)) return node.id;
+        }
+        return null;
+    }
+
+    function updateActive() {
+        const found = findDeepestVisible(toValue(roots));
+        if (found) activeId.value = found;
+    }
+
+    let cachedIds: string[] | null = null;
+    function collectIds(): string[] {
+        if (cachedIds) return cachedIds;
+        const out: string[] = [];
+        function walk(nodes: T[]) {
+            for (const node of nodes) {
+                out.push(node.id);
+                const children = getChildren(node);
+                if (children) walk(children);
+            }
+        }
+        walk(toValue(roots));
+        cachedIds = out;
+        return out;
+    }
+
+    function invalidateIdCache() {
+        cachedIds = null;
+    }
+
+    let rafId = 0;
+    function onScroll() {
+        if (locked || rafId) return;
+        rafId = requestAnimationFrame(() => {
+            rafId = 0;
+            const container = options?.scrollContainer?.value;
+            const topPct = parseFloat(rootMargin.split(" ")[0]) / 100;
+            const viewportH = container
+                ? container.clientHeight
+                : window.innerHeight;
+            const activeZoneTop = Math.abs(topPct) * viewportH;
+            const containerTop = container
+                ? container.getBoundingClientRect().top
+                : 0;
+
+            const allIds = collectIds();
+            let bestId: string | null = null;
+            let bestDist = Infinity;
+            let closestBelowId: string | null = null;
+            let closestBelowDist = Infinity;
+
+            for (const id of allIds) {
+                const el = document.getElementById(id);
+                if (!el) continue;
+                const rect = el.getBoundingClientRect();
+                const dist = rect.top - containerTop - activeZoneTop;
+                if (dist <= 0 && Math.abs(dist) < bestDist) {
+                    bestDist = Math.abs(dist);
+                    bestId = id;
+                }
+                if (dist > 0 && dist < closestBelowDist) {
+                    closestBelowDist = dist;
+                    closestBelowId = id;
+                }
+            }
+
+            const resolvedId = bestId ?? closestBelowId;
+            if (resolvedId && resolvedId !== activeId.value) {
+                sectionVisibility.clear();
+                sectionVisibility.set(resolvedId, true);
+                activeId.value = resolvedId;
+            }
+        });
+    }
+
+    function observeTree(list: T[]) {
+        for (const node of list) {
+            if (!observedIds.has(node.id)) {
+                const el = document.getElementById(node.id);
+                if (el) {
+                    observer?.observe(el);
+                    observedIds.add(node.id);
+                }
+            }
+            const children = getChildren(node);
+            if (children) observeTree(children);
+        }
+    }
+
+    function setupObserver() {
+        observer?.disconnect();
+        observedIds.clear();
+        sectionVisibility.clear();
+        invalidateIdCache();
+
+        const container = options?.scrollContainer?.value;
+        observer = new IntersectionObserver(
+            (entries) => {
+                if (locked) return;
+                for (const entry of entries) {
+                    sectionVisibility.set(
+                        (entry.target as HTMLElement).id,
+                        entry.isIntersecting,
+                    );
+                }
+                updateActive();
+            },
+            { root: container ?? undefined, rootMargin, threshold },
+        );
+
+        nextTick(() => {
+            observeTree(toValue(roots));
+            const currentRoots = toValue(roots);
+            if (!activeId.value && currentRoots.length > 0) {
+                activeId.value = currentRoots[0].id;
+            }
+        });
+    }
+
+    watch(
+        () => toValue(roots),
+        (newRoots) => {
+            if (!mounted) return;
+            activeId.value = newRoots[0]?.id ?? null;
+            setupObserver();
+        },
+    );
+
+    let scrollTarget: EventTarget | null = null;
+
+    onMounted(() => {
+        mounted = true;
+        setupObserver();
+
+        const container = options?.scrollContainer?.value;
+        scrollTarget = container ?? document;
+        scrollTarget.addEventListener("scroll", onScroll, { passive: true });
+    });
+
+    onUnmounted(() => {
+        mounted = false;
+        observer?.disconnect();
+        if (rafId) cancelAnimationFrame(rafId);
+        scrollTarget?.removeEventListener("scroll", onScroll);
+    });
+
+    function forceRecalculate() {
+        sectionVisibility.clear();
+        if (rafId) cancelAnimationFrame(rafId);
+        rafId = 0;
+
+        const container = options?.scrollContainer?.value;
+        const topPct = parseFloat(rootMargin.split(" ")[0]) / 100;
+        const viewportH = container
+            ? container.clientHeight
+            : window.innerHeight;
+        const activeZoneTop = Math.abs(topPct) * viewportH;
+        const containerTop = container
+            ? container.getBoundingClientRect().top
+            : 0;
+
+        const allIds = collectIds();
+        let bestId: string | null = null;
+        let bestDist = Infinity;
+        let closestBelowId: string | null = null;
+        let closestBelowDist = Infinity;
+
+        for (const id of allIds) {
+            const el = document.getElementById(id);
+            if (!el) continue;
+            const rect = el.getBoundingClientRect();
+            const dist = rect.top - containerTop - activeZoneTop;
+            if (dist <= 0 && Math.abs(dist) < bestDist) {
+                bestDist = Math.abs(dist);
+                bestId = id;
+            }
+            if (dist > 0 && dist < closestBelowDist) {
+                closestBelowDist = dist;
+                closestBelowId = id;
+            }
+        }
+
+        const resolvedId = bestId ?? closestBelowId;
+        if (resolvedId) {
+            sectionVisibility.set(resolvedId, true);
+            activeId.value = resolvedId;
+        }
+    }
+
+    return { activeId, activeRootId, forceRecalculate, lockTracking, unlockTracking };
+}

package/src/components/custom/sidebar/composables/useSidebarFollow.ts

@@ -0,0 +1,247 @@
+/**
+ * Damped scroll-following for sidebar navigation.
+ * Keeps the active item in view without hijacking manual scrolling.
+ *
+ * - Deadzone: no scroll if active item is already visible
+ * - Manual override: stops auto-scrolling when user scrolls the sidebar
+ * - Damped animation: smooth approach via requestAnimationFrame
+ */
+import { nextTick, onMounted, onUnmounted, watch } from "vue";
+import type { Ref } from "vue";
+
+export interface SidebarFollowOptions {
+    /** The sidebar nav element to auto-scroll. */
+    sidebarEl: Ref<HTMLElement | null>;
+    /** Currently active section ID. */
+    activeId: Ref<string | null>;
+    /** Currently active root section ID. */
+    activeRootId?: Ref<string | null>;
+    /** External scroll source (page container) to listen to. */
+    scrollSource?: Ref<HTMLElement | null>;
+    /** Damping factor (0-1, default 0.22). Lower = slower approach. */
+    damping?: number;
+}
+
+export function useSidebarFollow(options: SidebarFollowOptions) {
+    const damping = options.damping ?? 0.22;
+    let followRaf = 0;
+    let syncRaf = 0;
+    let currentScrollSource: HTMLElement | null = null;
+    let currentSidebar: HTMLElement | null = null;
+    let targetScrollTop: number | null = null;
+    let manualOverride = false;
+    let programmaticScrollDepth = 0;
+
+    function suspendForManualInteraction() {
+        manualOverride = true;
+        targetScrollTop = null;
+        if (followRaf) {
+            cancelAnimationFrame(followRaf);
+            followRaf = 0;
+        }
+        if (syncRaf) {
+            cancelAnimationFrame(syncRaf);
+            syncRaf = 0;
+        }
+    }
+
+    function escapeSelector(value: string): string {
+        if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+            return CSS.escape(value);
+        }
+        return value.replace(/["\\]/g, "\\$&");
+    }
+
+    function getActiveElement(): HTMLElement | null {
+        const nav = options.sidebarEl.value;
+        const id = options.activeId.value ?? options.activeRootId?.value ?? null;
+        if (!nav || !id) return null;
+        return nav.querySelector(
+            `[data-toc-id="${escapeSelector(id)}"]`,
+        ) as HTMLElement | null;
+    }
+
+    function resolveTarget(nav: HTMLElement, activeEl: HTMLElement): number {
+        const navHeight = nav.clientHeight;
+        const elementCenter = activeEl.offsetTop + activeEl.offsetHeight / 2;
+        const maxScrollTop = Math.max(0, nav.scrollHeight - navHeight);
+        const deadzone = navHeight * 0.18;
+        const currentCenter = nav.scrollTop + navHeight / 2;
+        if (Math.abs(elementCenter - currentCenter) <= deadzone) {
+            return nav.scrollTop;
+        }
+        return Math.max(0, Math.min(maxScrollTop, elementCenter - navHeight / 2));
+    }
+
+    function withProgrammaticScroll(fn: () => void) {
+        programmaticScrollDepth += 1;
+        try {
+            fn();
+        } finally {
+            requestAnimationFrame(() => {
+                programmaticScrollDepth = Math.max(0, programmaticScrollDepth - 1);
+            });
+        }
+    }
+
+    function follow() {
+        followRaf = 0;
+        if (manualOverride) return;
+        const nav = options.sidebarEl.value;
+        const target = targetScrollTop;
+        if (!nav || target == null) return;
+
+        const delta = target - nav.scrollTop;
+        if (Math.abs(delta) < 1) {
+            withProgrammaticScroll(() => {
+                nav.scrollTop = target;
+            });
+            targetScrollTop = null;
+            return;
+        }
+
+        withProgrammaticScroll(() => {
+            nav.scrollTop += delta * damping;
+        });
+        followRaf = requestAnimationFrame(follow);
+    }
+
+    function queue(immediate = false) {
+        if (!immediate && manualOverride) return;
+        const nav = options.sidebarEl.value;
+        const activeEl = getActiveElement();
+        if (!nav || !activeEl) return;
+
+        targetScrollTop = resolveTarget(nav, activeEl);
+
+        if (immediate) {
+            if (followRaf) {
+                cancelAnimationFrame(followRaf);
+                followRaf = 0;
+            }
+            withProgrammaticScroll(() => {
+                nav.scrollTop = targetScrollTop!;
+            });
+            targetScrollTop = null;
+            return;
+        }
+
+        if (!followRaf) {
+            followRaf = requestAnimationFrame(follow);
+        }
+    }
+
+    function scheduleFromScroll() {
+        if (manualOverride) {
+            manualOverride = false;
+            targetScrollTop = null;
+        }
+        if (syncRaf) return;
+        syncRaf = requestAnimationFrame(() => {
+            syncRaf = 0;
+            queue();
+        });
+    }
+
+    function handleSidebarWheel() {
+        suspendForManualInteraction();
+    }
+
+    function handleSidebarTouch() {
+        suspendForManualInteraction();
+    }
+
+    function handleSidebarPointer(event: PointerEvent) {
+        const target = event.target as HTMLElement | null;
+        if (target?.closest("[data-toc-id], .sidebar-top-btn")) return;
+        suspendForManualInteraction();
+    }
+
+    function handleSidebarKeydown(event: KeyboardEvent) {
+        if (
+            event.key === "ArrowUp" ||
+            event.key === "ArrowDown" ||
+            event.key === "PageUp" ||
+            event.key === "PageDown" ||
+            event.key === "Home" ||
+            event.key === "End" ||
+            event.key === " "
+        ) {
+            suspendForManualInteraction();
+        }
+    }
+
+    function handleSidebarScroll() {
+        if (programmaticScrollDepth > 0) return;
+        suspendForManualInteraction();
+    }
+
+    function bindSidebar(nav: HTMLElement | null) {
+        if (currentSidebar === nav) return;
+        currentSidebar?.removeEventListener("wheel", handleSidebarWheel);
+        currentSidebar?.removeEventListener("scroll", handleSidebarScroll);
+        currentSidebar?.removeEventListener("touchstart", handleSidebarTouch);
+        currentSidebar?.removeEventListener("pointerdown", handleSidebarPointer as EventListener);
+        currentSidebar?.removeEventListener("keydown", handleSidebarKeydown);
+        currentSidebar = nav;
+        currentSidebar?.addEventListener("wheel", handleSidebarWheel, { passive: true });
+        currentSidebar?.addEventListener("scroll", handleSidebarScroll, { passive: true });
+        currentSidebar?.addEventListener("touchstart", handleSidebarTouch, { passive: true });
+        currentSidebar?.addEventListener("pointerdown", handleSidebarPointer as EventListener, { passive: true });
+        currentSidebar?.addEventListener("keydown", handleSidebarKeydown);
+    }
+
+    function bindScrollSource(source: HTMLElement | null) {
+        if (currentScrollSource === source) return;
+        currentScrollSource?.removeEventListener("scroll", scheduleFromScroll);
+        currentScrollSource = source;
+        currentScrollSource?.addEventListener("scroll", scheduleFromScroll, {
+            passive: true,
+        });
+    }
+
+    onMounted(() => {
+        bindScrollSource(options.scrollSource?.value ?? null);
+        bindSidebar(options.sidebarEl.value ?? null);
+        nextTick(() => queue(true));
+        window.addEventListener("resize", scheduleFromScroll);
+    });
+
+    watch(
+        [options.activeId, options.activeRootId ?? { value: null }],
+        () => {
+            nextTick(() => queue());
+        },
+        { flush: "post" },
+    );
+
+    watch(
+        options.sidebarEl,
+        (sidebar) => {
+            bindSidebar(sidebar);
+        },
+        { immediate: true },
+    );
+
+    watch(
+        () => options.scrollSource?.value ?? null,
+        (source) => {
+            bindScrollSource(source);
+        },
+        { immediate: true },
+    );
+
+    onUnmounted(() => {
+        if (followRaf) cancelAnimationFrame(followRaf);
+        if (syncRaf) cancelAnimationFrame(syncRaf);
+        currentScrollSource?.removeEventListener("scroll", scheduleFromScroll);
+        currentSidebar?.removeEventListener("wheel", handleSidebarWheel);
+        currentSidebar?.removeEventListener("scroll", handleSidebarScroll);
+        currentSidebar?.removeEventListener("touchstart", handleSidebarTouch);
+        currentSidebar?.removeEventListener("pointerdown", handleSidebarPointer as EventListener);
+        currentSidebar?.removeEventListener("keydown", handleSidebarKeydown);
+        window.removeEventListener("resize", scheduleFromScroll);
+    });
+
+    return { queueSidebarFollow: queue };
+}

package/src/components/custom/sidebar/composables/useSidebarState.ts

@@ -0,0 +1,72 @@
+/**
+ * Manages sidebar section expand/collapse state with user overrides.
+ * Combines tree indexing, scroll tracking, and manual toggle tracking
+ * into a unified SidebarState.
+ */
+import { reactive, computed } from "vue";
+import type { Ref } from "vue";
+import type { SidebarSection, SidebarState } from "../types";
+import { useTreeIndex } from "./useTreeIndex";
+
+export interface UseSidebarStateOptions {
+    sections: SidebarSection[];
+    activeId: Ref<string | null>;
+    activeRootId: Ref<string | null>;
+    scrollTo: (id: string) => void;
+    scrollToTop: () => void;
+}
+
+export function useSidebarState(options: UseSidebarStateOptions): SidebarState {
+    const {
+        index: treeIndex,
+        isActive: checkActive,
+        isInActiveChain: checkChain,
+    } = useTreeIndex(options.sections);
+
+    // Tracks user overrides for section expand/collapse state
+    const userExpanded = reactive(new Set<string>());
+    const userCollapsed = reactive(new Set<string>());
+
+    function isExpanded(sectionId: string): boolean {
+        if (userCollapsed.has(sectionId)) return false;
+        if (userExpanded.has(sectionId)) return true;
+        return options.activeRootId.value === sectionId;
+    }
+
+    function toggleSection(sectionId: string) {
+        if (isExpanded(sectionId)) {
+            userExpanded.delete(sectionId);
+            userCollapsed.add(sectionId);
+        } else {
+            userCollapsed.delete(sectionId);
+            userExpanded.add(sectionId);
+        }
+    }
+
+    function navigateTo(id: string) {
+        options.scrollTo(id);
+    }
+
+    function isActive(id: string): boolean {
+        return checkActive(id, options.activeId.value);
+    }
+
+    function isInActiveChain(id: string): boolean {
+        return checkChain(id, options.activeId.value);
+    }
+
+    const activeRootId = computed(() => options.activeRootId.value);
+
+    return {
+        sections: options.sections,
+        activeId: options.activeId,
+        activeRootId,
+        treeIndex,
+        isExpanded,
+        toggleSection,
+        navigateTo,
+        scrollToTop: options.scrollToTop,
+        isActive,
+        isInActiveChain,
+    };
+}