@mkbabb/glass-ui 0.2.0

package/src/composables/useWatercolorBlob.ts

@@ -0,0 +1,136 @@
+import { ref, onUnmounted, watch, type Ref } from "vue";
+import { mulberry32, hashString, randomRadii, radiiToCSS } from "./prng";
+
+export interface UseWatercolorBlobOptions {
+    /** Enable rAF animation loop */
+    animate?: boolean;
+    /** Base cycle duration in ms (default 4000) */
+    cycleDuration?: number;
+    /** Border-radius range [lo, hi] as percentages (default [20, 80]) */
+    range?: [number, number];
+    /** Extra seed string mixed into the hash for unique shapes */
+    seed?: string;
+}
+
+/**
+ * Per-vertex animation state — each of the 8 border-radius values
+ * animates independently with its own timing, producing organic motion.
+ */
+interface VertexState {
+    from: number;
+    to: number;
+    startTime: number;
+    duration: number;
+}
+
+export function useWatercolorBlob(
+    color: Ref<string> | (() => string),
+    options: UseWatercolorBlobOptions = {},
+) {
+    const {
+        animate = false,
+        cycleDuration = 4000,
+        range = [20, 80],
+        seed = "",
+    } = options;
+
+    const borderRadius = ref("");
+    const hoverBorderRadius = ref("");
+
+    const getColor = typeof color === "function" ? color : () => color.value;
+
+    // Deterministic initial shape from color string + optional seed
+    const rng = mulberry32(hashString(getColor() + seed));
+    const initial = randomRadii(rng, range[0], range[1]);
+    borderRadius.value = radiiToCSS(initial);
+
+    // Generate a second deterministic shape for hover state
+    const hoverShape = randomRadii(rng, range[0], range[1]);
+    hoverBorderRadius.value = radiiToCSS(hoverShape);
+
+    // No-op nudge for non-animated blobs
+    let nudge = () => {};
+
+    // Re-seed when color changes (non-animated mode)
+    if (!animate) {
+        if (typeof color !== "function") {
+            watch(color, (c) => {
+                const r = mulberry32(hashString(c + seed));
+                borderRadius.value = radiiToCSS(randomRadii(r, range[0], range[1]));
+                hoverBorderRadius.value = radiiToCSS(randomRadii(r, range[0], range[1]));
+            });
+        }
+        return { borderRadius, hoverBorderRadius, nudge };
+    }
+
+    // --- Per-vertex independent animation ---
+
+    const [lo, hi] = range;
+    const current = [...initial];
+
+    // Each vertex gets its own timing with wide variance
+    const vertices: VertexState[] = [];
+    for (let i = 0; i < 8; i++) {
+        const durationMul = 0.5 + rng() * 1.3;
+        const phaseOffset = rng();
+        vertices.push({
+            from: initial[i],
+            to: lo + rng() * (hi - lo),
+            startTime: -phaseOffset * cycleDuration * durationMul,
+            duration: cycleDuration * durationMul,
+        });
+    }
+
+    let rafId: number | null = null;
+    let lastNow = 0;
+
+    function tick(now: number) {
+        lastNow = now;
+        for (let i = 0; i < 8; i++) {
+            const v = vertices[i];
+            let t = (now - v.startTime) / v.duration;
+
+            if (t >= 1) {
+                v.from = v.to;
+                v.to = lo + rng() * (hi - lo);
+                v.duration = cycleDuration * (0.5 + rng() * 1.3);
+                v.startTime = now;
+                t = 0;
+            }
+
+            // Sinusoidal ease — smoother and more organic than quadratic
+            const ease = 0.5 - 0.5 * Math.cos(Math.PI * t);
+            current[i] = v.from + ease * (v.to - v.from);
+        }
+
+        borderRadius.value = radiiToCSS(current);
+        rafId = requestAnimationFrame(tick);
+    }
+
+    /**
+     * Nudge: immediately retarget all vertices to new random positions
+     * with short durations, creating a visible "jiggle" effect.
+     */
+    nudge = () => {
+        const now = lastNow || performance.now();
+        for (let i = 0; i < 8; i++) {
+            const v = vertices[i];
+            v.from = current[i];
+            v.to = lo + rng() * (hi - lo);
+            // Fast transition (25-50% of normal cycle)
+            v.duration = cycleDuration * (0.25 + rng() * 0.25);
+            v.startTime = now;
+        }
+    };
+
+    rafId = requestAnimationFrame(tick);
+
+    onUnmounted(() => {
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+            rafId = null;
+        }
+    });
+
+    return { borderRadius, hoverBorderRadius, nudge };
+}

package/src/composables/virtual/index.ts

@@ -0,0 +1,22 @@
+export {
+    useVirtualSectionWindow,
+    type VirtualSectionWindowOptions,
+} from "./useVirtualSectionWindow";
+
+export {
+    useWindowedStore,
+    type WindowedStore,
+    type UseWindowedStoreOptions,
+} from "./useWindowedStore";
+
+export {
+    buildSectionLayout,
+    findSectionOffset,
+    resolveActiveSection,
+    resolveSectionWindow,
+    type FlatSection,
+    type ForcedSectionWindowRange,
+    type SectionLayout,
+    type SectionLayoutEntry,
+    type SectionWindowRange,
+} from "./virtualSectionLayout";

package/src/composables/virtual/useVirtualSectionWindow.ts

@@ -0,0 +1,338 @@
+import {
+    computed,
+    onMounted,
+    onUnmounted,
+    ref,
+    shallowRef,
+    toValue,
+    watch,
+    type MaybeRefOrGetter,
+    type Ref,
+} from "vue";
+import type { FlatSection } from "./virtualSectionLayout";
+import {
+    buildSectionLayout,
+    findSectionOffset,
+    resolveActiveSection,
+    resolveSectionWindow,
+    type ForcedSectionWindowRange,
+    type SectionLayout,
+    type SectionWindowRange,
+} from "./virtualSectionLayout";
+
+export interface VirtualSectionWindowOptions<T extends FlatSection = FlatSection> {
+    /** The flat list of section items to virtualize. */
+    items: MaybeRefOrGetter<readonly T[]>;
+    /**
+     * The element whose scroll position drives the window.
+     * `null` = use `window` / document scroll.
+     */
+    scrollContainer: Ref<HTMLElement | null>;
+    /**
+     * The wrapper element around the virtualized content.
+     * When provided, scroll offset is computed relative to this element's
+     * position in the page, so content above it (headers, images, etc.)
+     * is correctly excluded from the layout calculation.
+     */
+    contentEl?: Ref<HTMLElement | null>;
+    /** Overscan before the viewport in pixels. Default: viewport height. */
+    overscanBeforePx?: number;
+    /** Overscan after the viewport in pixels. Default: 2x viewport height. */
+    overscanAfterPx?: number;
+    /** Number of items to warm before a target when using `ensureTargetWindow`. Default: 2. */
+    warmTargetBefore?: number;
+    /** Number of items to warm after a target when using `ensureTargetWindow`. Default: 3. */
+    warmTargetAfter?: number;
+}
+
+/** Session-level height cache shared across all instances. */
+const SESSION_HEIGHT_CACHE = new Map<string, number>();
+
+/**
+ * Scroll-based virtual windowing composable for section lists.
+ *
+ * Renders only the items visible in (or near) the scroll viewport,
+ * using spacer divs to maintain correct scroll height. Supports:
+ *
+ * - Measured heights: call `measureSection(id, el)` from a template ref
+ *   to replace estimated heights with real DOM measurements.
+ * - Warm targeting: call `ensureTargetWindow(id)` to force an item into
+ *   the render window before scrolling to it.
+ * - Active tracking: `activeId` / `activeRootId` report which section
+ *   is currently at the 20% viewport mark.
+ * - Content offset: provide `contentEl` to correctly handle non-virtualized
+ *   content (headers, banners) above the virtual list.
+ */
+export function useVirtualSectionWindow<T extends FlatSection>(
+    options: VirtualSectionWindowOptions<T>,
+) {
+    const items = computed(() => Array.from(toValue(options.items)));
+    const measuredHeights = new Map<string, number>();
+    const itemIndex = new Map<string, number>();
+    const layout = shallowRef<SectionLayout<T>>({
+        entries: [],
+        totalHeight: 0,
+    });
+    const range = ref<SectionWindowRange>({
+        startIndex: 0,
+        endIndex: -1,
+        topSpacerPx: 0,
+        bottomSpacerPx: 0,
+    });
+    const activeItem = ref<T | null>(null);
+    const warmRange = ref<ForcedSectionWindowRange | null>(null);
+
+    const elementMap = new Map<string, HTMLElement>();
+    let scrollRaf = 0;
+    let recalcRaf = 0;
+    let warmTimer = 0;
+    let containerResizeObserver: ResizeObserver | null = null;
+
+    function getViewportHeight(): number {
+        return Math.max(
+            1,
+            options.scrollContainer.value?.clientHeight ?? window.innerHeight ?? 900,
+        );
+    }
+
+    /**
+     * Compute how far the user has scrolled into the virtualized content.
+     * When `contentEl` is provided, we measure relative to the content
+     * wrapper's position — so headers/images above it are excluded.
+     */
+    function getContentScrollTop(): number {
+        const contentEl = options.contentEl?.value;
+        if (contentEl) {
+            // Negative rect.top = user has scrolled past the content's top edge
+            return Math.max(0, -contentEl.getBoundingClientRect().top);
+        }
+        const container = options.scrollContainer.value;
+        return container
+            ? container.scrollTop
+            : (document.documentElement.scrollTop || document.body.scrollTop || 0);
+    }
+
+    function getHeight(item: T): number {
+        return (
+            measuredHeights.get(item.id) ??
+            SESSION_HEIGHT_CACHE.get(item.id) ??
+            item.estimatedHeight
+        );
+    }
+
+    function rebuildLayout() {
+        layout.value = buildSectionLayout(items.value, getHeight);
+    }
+
+    function computeWindowState() {
+        const viewportHeight = getViewportHeight();
+        const overscanBeforePx = options.overscanBeforePx ?? viewportHeight;
+        const overscanAfterPx = options.overscanAfterPx ?? viewportHeight * 2;
+        const normalizedScrollTop = getContentScrollTop();
+
+        range.value = resolveSectionWindow(
+            layout.value,
+            normalizedScrollTop,
+            viewportHeight,
+            overscanBeforePx,
+            overscanAfterPx,
+            warmRange.value,
+        );
+        activeItem.value = resolveActiveSection(
+            layout.value,
+            normalizedScrollTop + viewportHeight * 0.2,
+        );
+    }
+
+    /** Force a full layout rebuild and window recomputation. */
+    function recalculate() {
+        rebuildLayout();
+        computeWindowState();
+    }
+
+    function scheduleRecalculate() {
+        if (recalcRaf) return;
+        recalcRaf = requestAnimationFrame(() => {
+            recalcRaf = 0;
+            recalculate();
+        });
+    }
+
+    function scheduleWarmRangeRelease() {
+        if (warmTimer) window.clearTimeout(warmTimer);
+        warmTimer = window.setTimeout(() => {
+            warmRange.value = null;
+            scheduleRecalculate();
+        }, 320);
+    }
+
+    function syncMeasuredHeight(id: string, height: number) {
+        const normalized = Math.max(1, Math.round(height));
+        if (measuredHeights.get(id) === normalized) return;
+        measuredHeights.set(id, normalized);
+        SESSION_HEIGHT_CACHE.set(id, normalized);
+        scheduleRecalculate();
+    }
+
+    function disconnectSection(id: string) {
+        elementMap.delete(id);
+    }
+
+    /**
+     * Register (or update) a section's DOM element for height measurement.
+     * Call from a template ref callback: `:ref="(el) => measureSection(item.id, el)"`.
+     * Pass `null` to disconnect.
+     */
+    function measureSection(id: string, el: HTMLElement | null) {
+        if (!el) {
+            disconnectSection(id);
+            return;
+        }
+
+        const current = elementMap.get(id);
+        if (current === el) {
+            syncMeasuredHeight(id, el.offsetHeight);
+            return;
+        }
+
+        disconnectSection(id);
+        elementMap.set(id, el);
+        requestAnimationFrame(() => {
+            const target = elementMap.get(id);
+            if (target) syncMeasuredHeight(id, target.offsetHeight);
+        });
+    }
+
+    /**
+     * Force an item into the render window so it can be scrolled to.
+     * The warm range auto-releases after 320ms.
+     */
+    function ensureTargetWindow(id: string) {
+        const index = itemIndex.get(id);
+        if (index == null) return;
+        const warmBefore = options.warmTargetBefore ?? 2;
+        const warmAfter = options.warmTargetAfter ?? 3;
+        warmRange.value = {
+            startIndex: Math.max(0, index - warmBefore),
+            endIndex: Math.min(items.value.length - 1, index + warmAfter),
+        };
+        scheduleWarmRangeRelease();
+        recalculate();
+    }
+
+    /** Get the pixel offset of a section by id, or `null` if not found. */
+    function getOffsetFor(id: string): number | null {
+        return findSectionOffset(layout.value, id);
+    }
+
+    function attachContainerObserver(container: HTMLElement | null) {
+        containerResizeObserver?.disconnect();
+        containerResizeObserver = null;
+        if (!container || typeof ResizeObserver === "undefined") return;
+        containerResizeObserver = new ResizeObserver(() => {
+            scheduleRecalculate();
+        });
+        containerResizeObserver.observe(container);
+    }
+
+    function handleScroll() {
+        if (scrollRaf) return;
+        scrollRaf = requestAnimationFrame(() => {
+            scrollRaf = 0;
+            computeWindowState();
+        });
+    }
+
+    let currentContainer: EventTarget | null = null;
+    function bindContainer(container: HTMLElement | null) {
+        const scrollTarget: EventTarget = container ?? window;
+        if (currentContainer === scrollTarget) return;
+        if (currentContainer) {
+            currentContainer.removeEventListener("scroll", handleScroll);
+        }
+        currentContainer = scrollTarget;
+        currentContainer.addEventListener("scroll", handleScroll, { passive: true });
+        attachContainerObserver(container);
+        scheduleRecalculate();
+    }
+
+    watch(
+        items,
+        (nextItems) => {
+            itemIndex.clear();
+            for (const item of nextItems) {
+                itemIndex.set(item.id, item.index);
+                const cached = SESSION_HEIGHT_CACHE.get(item.id);
+                if (cached != null) measuredHeights.set(item.id, cached);
+            }
+            for (const id of [...measuredHeights.keys()]) {
+                if (!itemIndex.has(id)) measuredHeights.delete(id);
+            }
+            recalculate();
+        },
+        { immediate: true },
+    );
+
+    watch(
+        options.scrollContainer,
+        (container) => bindContainer(container),
+        { immediate: true },
+    );
+
+    // Also observe the content element for resize (e.g. images loading above)
+    let contentResizeObserver: ResizeObserver | null = null;
+    if (options.contentEl) {
+        watch(
+            options.contentEl,
+            (el) => {
+                contentResizeObserver?.disconnect();
+                contentResizeObserver = null;
+                if (el && typeof ResizeObserver !== "undefined") {
+                    contentResizeObserver = new ResizeObserver(() => scheduleRecalculate());
+                    contentResizeObserver.observe(el);
+                }
+            },
+            { immediate: true },
+        );
+    }
+
+    onMounted(() => {
+        // Ensure initial calculation after DOM is ready
+        scheduleRecalculate();
+    });
+
+    onUnmounted(() => {
+        if (scrollRaf) cancelAnimationFrame(scrollRaf);
+        if (recalcRaf) cancelAnimationFrame(recalcRaf);
+        if (warmTimer) window.clearTimeout(warmTimer);
+        if (currentContainer) {
+            currentContainer.removeEventListener("scroll", handleScroll);
+        }
+        containerResizeObserver?.disconnect();
+        contentResizeObserver?.disconnect();
+        elementMap.clear();
+    });
+
+    /** The subset of items currently in the render window. */
+    const visibleItems = computed(() => {
+        if (range.value.endIndex < range.value.startIndex) return [] as T[];
+        return items.value.slice(range.value.startIndex, range.value.endIndex + 1);
+    });
+
+    /** The `id` of the currently active (at 20% viewport) section. */
+    const activeId = computed(() => activeItem.value?.id ?? null);
+    /** The `rootId` of the currently active section. */
+    const activeRootId = computed(() => activeItem.value?.rootId ?? null);
+
+    return {
+        visibleItems,
+        topSpacerPx: computed(() => range.value.topSpacerPx),
+        bottomSpacerPx: computed(() => range.value.bottomSpacerPx),
+        measureSection,
+        ensureTargetWindow,
+        getOffsetFor,
+        activeId,
+        activeRootId,
+        recalculate,
+    };
+}

package/src/composables/virtual/useWindowedStore.ts

@@ -0,0 +1,86 @@
+import { ref, shallowRef, type Ref, type ShallowRef } from "vue";
+
+export interface UseWindowedStoreOptions {
+    /** Maximum items to keep in memory. Default: 200. */
+    maxResident?: number;
+}
+
+export interface WindowedStore<T> {
+    /** Currently loaded items (a sliding window of the full list). */
+    items: ShallowRef<T[]>;
+    /** Logical offset of `items[0]` in the full list. */
+    windowStart: Ref<number>;
+    /** Generation counter -- increments on each reset. Used to reject stale appends. */
+    generation: Ref<number>;
+    /** Append or replace items. `replace=true` resets window; `replace=false` appends with eviction from front. */
+    set(newItems: T[], replace?: boolean): void;
+    /** Prepend items before the current window. Evicts from the end if over `maxResident`. */
+    prepend(newItems: T[], newWindowStart: number): void;
+    /** Clear all items and reset window. */
+    clear(): void;
+    /**
+     * Append items only if the generation matches (i.e., no reset happened since the fetch started).
+     * Returns `true` if the append was accepted, `false` if rejected (stale).
+     */
+    appendIfCurrent(newItems: T[], expectedGeneration: number): boolean;
+}
+
+/**
+ * Sliding-window store primitive for paginated / infinite-scroll data.
+ *
+ * Supports both forward (append) and backward (prepend) loading.
+ * When items exceed `maxResident`, trims from the opposite end.
+ *
+ * Uses a generation counter to reject stale appends after a backward reset,
+ * preventing race conditions between concurrent page fetches.
+ */
+export function useWindowedStore<T>(
+    options?: UseWindowedStoreOptions,
+): WindowedStore<T> {
+    const maxResident = options?.maxResident ?? 200;
+    const items = shallowRef<T[]>([]);
+    const windowStart = ref(0);
+    const generation = ref(0);
+
+    function set(newItems: T[], replace = true) {
+        if (replace) {
+            items.value = [...newItems];
+            windowStart.value = 0;
+            generation.value++;
+        } else {
+            const merged = [...items.value, ...newItems];
+            if (merged.length > maxResident) {
+                const trimCount = merged.length - maxResident;
+                items.value = merged.slice(trimCount);
+                windowStart.value += trimCount;
+            } else {
+                items.value = merged;
+            }
+        }
+    }
+
+    function appendIfCurrent(newItems: T[], expectedGeneration: number): boolean {
+        if (generation.value !== expectedGeneration) return false;
+        set(newItems, false);
+        return true;
+    }
+
+    function prepend(newItems: T[], newWindowStart: number) {
+        const merged = [...newItems, ...items.value];
+        windowStart.value = newWindowStart;
+        generation.value++;
+        if (merged.length > maxResident) {
+            items.value = merged.slice(0, maxResident);
+        } else {
+            items.value = merged;
+        }
+    }
+
+    function clear() {
+        items.value = [];
+        windowStart.value = 0;
+        generation.value++;
+    }
+
+    return { items, windowStart, generation, set, prepend, appendIfCurrent, clear };
+}