@mkbabb/glass-ui 4.0.1 → 4.1.0

package/dist/composables/sidebar/types.d.ts

@@ -4,9 +4,13 @@ export interface TreeNode {
     id: string;
     children?: TreeNode[];
 }
-/** Generic flat index entry for a tree node. */
-export interface TreeIndexEntry<T extends TreeNode = TreeNode> {
-    node: T;
+/**
+ * The flat-hierarchy fields shared by every flattened tree row. Both the
+ * sidebar's `TreeIndexEntry` and the virtual-windowing `FlatSection`
+ * (`composables/virtual`) extend this — the four fields are declared ONCE,
+ * not redeclared independently (BC.W-VIRTUAL-WINDOW type-reconcile).
+ */
+export interface SectionHierarchy {
     depth: number;
     /** ID of the root-level ancestor (self.id when depth === 0). */
     rootId: string;
@@ -15,6 +19,10 @@ export interface TreeIndexEntry<T extends TreeNode = TreeNode> {
     /** Index within root-level nodes. */
     rootIndex: number;
 }
+/** Generic flat index entry for a tree node. */
+export interface TreeIndexEntry<T extends TreeNode = TreeNode> extends SectionHierarchy {
+    node: T;
+}
 /** A section in the sidebar tree. */
 export interface SidebarSection extends TreeNode {
     title: string;
@@ -29,6 +37,63 @@ export interface ScrollTrackerOptions {
     rootMargin?: string;
     threshold?: number;
 }
+/**
+ * Options for `useScrollTo` — the rAF-retry scroll-to-id + treeIndex-aware
+ * partial-load (the ToC-click → virtual-window warm bridge).
+ *
+ * GENERIC-count-sourced: `totalCount`/`visibleCount` are plain params, NEVER a
+ * consumer type. When a `treeIndex` is passed, `ensureTargetLoaded` loads only
+ * up to the target section's `rootIndex + 2` (the partial-load) instead of
+ * force-loading everything.
+ */
+export interface ScrollToOptions {
+    /** The scroll container element to scroll within. */
+    scrollContainer: Ref<HTMLElement | null>;
+    /** Total number of items/sections (the generic count ceiling). */
+    totalCount: number;
+    /** The progressively-rendered count this leaf writes the partial-load into. */
+    visibleCount: Ref<number>;
+    /** Pixel offset from the container top. Default: 16 */
+    scrollOffset?: number;
+    /** Max rAF retry attempts before bailing. Default: 60 */
+    maxAttempts?: number;
+    /**
+     * Tree index for resolving a target id to its root section index. When
+     * provided, `scrollTo` loads only up to the target's root section + buffer
+     * (`rootIndex + 2`) instead of all content. Shares the same `TreeIndexEntry`
+     * the windowing `FlatSection` hierarchy fields reconcile with.
+     */
+    treeIndex?: Map<string, TreeIndexEntry>;
+}
+/**
+ * Options for `useClickDelegate` — the ONE delegated `[data-scroll-target]`
+ * click→scroll handler for an entire ToC (not N per-link listeners).
+ */
+export interface ClickDelegateOptions {
+    /** Container element to attach the single delegated listener to. */
+    container: Ref<HTMLElement | null>;
+    /** CSS selector for clickable elements. Default: "[data-scroll-target]" */
+    selector?: string;
+    /** Attribute to read the target id from. Default: "data-scroll-target" */
+    attribute?: string;
+    /** Maps the attribute value to a scroll-target id. Return null to skip. */
+    resolve: (value: string) => string | null;
+    /** Called with the resolved id (typically `useScrollTo`'s `scrollTo`). */
+    scrollTo: (id: string) => void;
+}
+/**
+ * Options for `useLazyLoader` — the progressive batch-render count. Distinct
+ * from `useInfiniteScroll` (which fires a data-fetch `onLoadMore` trigger):
+ * the lazy-loader grows a RENDER-MOUNT count over an already-loaded list.
+ */
+export interface LazyLoaderOptions {
+    /** Sections rendered per batch. Default: 2 */
+    batchSize?: number;
+    /** IntersectionObserver rootMargin for the bottom sentinel. Default: "0px 0px 600px 0px" */
+    rootMargin?: string;
+    /** Scroll container for the fast-drag scroll fallback. Falls back to document. */
+    scrollContainer?: Ref<HTMLElement | null>;
+}
 /** Reactive state returned by `useSidebarState`. */
 export interface SidebarState {
     sections: SidebarSection[];

package/dist/composables/sidebar/useClickDelegate.d.ts

@@ -0,0 +1,4 @@
+import type { ClickDelegateOptions } from "./types";
+export declare function useClickDelegate(options: ClickDelegateOptions): {
+    handleClick: (e: MouseEvent) => void;
+};

package/dist/composables/sidebar/useLazyLoader.d.ts

@@ -0,0 +1,5 @@
+import type { LazyLoaderOptions } from "./types";
+export declare function useLazyLoader(totalCount: number, options?: LazyLoaderOptions): {
+    visibleCount: import("vue").Ref<number, number>;
+    loadSentinel: import("vue").Ref<HTMLElement | null, HTMLElement | null>;
+};

package/dist/composables/sidebar/useScrollTo.d.ts

@@ -0,0 +1,5 @@
+import type { ScrollToOptions } from "./types";
+export declare function useScrollTo(options: ScrollToOptions): {
+    scrollTo: (id: string) => void;
+    cancel: () => void;
+};

package/dist/composables/virtual/index.d.ts

@@ -0,0 +1,4 @@
+export { useVirtualSectionWindow, clearSessionHeightCache, } from "./useVirtualSectionWindow";
+export { useWindowedStore } from "./useWindowedStore";
+export { buildSectionLayout, findSectionOffset, resolveActiveSection, resolveSectionWindow, } from "./virtualSectionLayout";
+export type { FlatSection, SectionLayout, SectionWindowRange, ForcedSectionWindowRange, } from "./virtualSectionLayout";

package/dist/composables/virtual/useVirtualSectionWindow.d.ts

@@ -0,0 +1,72 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+import type { FlatSection } from "./virtualSectionLayout";
+/**
+ * Lineage: a glass-ui primitive at v0.9.4, retired at v1.0 (MIGRATION.md §3.2),
+ * carried on as a verbatim transposed copy in the words app, and HOME again at
+ * BC (the live words consumer + the dock-search results list overturn the
+ * no-consumer retirement verdict). Byte-faithful to the proven words copy save
+ * the recorded refinements: the container/content ResizeObservers route through
+ * the house `useResizeObserver` leaf (cleanup discipline) instead of raw
+ * `new ResizeObserver`, and `findSectionOffset` is the binary-search variant.
+ */
+interface VirtualWindowConfig<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;
+}
+/**
+ * Evict every cached measured section height. The documented escape for a
+ * consumer that wants to drop the module-global `SESSION_HEIGHT_CACHE` (a
+ * font-size change, a layout reflow that invalidates prior measurements).
+ */
+export declare function clearSessionHeightCache(): void;
+/**
+ * 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 (auto-releases after 320ms).
+ * - Active tracking: `activeId` / `activeRootId` report which section
+ *   is currently at the 20% viewport mark. NOTE — this is the windowing-LOCAL
+ *   render-active reader; a ToC/sidebar consumer reads `useScrollTracker`'s
+ *   `activeId` (the deepest-visible reader) for the binding highlight. The two
+ *   serve distinct concerns and are deliberately NOT one function
+ *   (BC.W-VIRTUAL-WINDOW active-section reconcile).
+ * - Content offset: provide `contentEl` to correctly handle non-virtualized
+ *   content (headers, banners) above the virtual list.
+ */
+export declare function useVirtualSectionWindow<T extends FlatSection>(options: VirtualWindowConfig<T>): {
+    visibleItems: import("vue").ComputedRef<T[]>;
+    topSpacerPx: import("vue").ComputedRef<number>;
+    bottomSpacerPx: import("vue").ComputedRef<number>;
+    measureSection: (id: string, el: HTMLElement | null) => void;
+    ensureTargetWindow: (id: string) => void;
+    getOffsetFor: (id: string) => number | null;
+    activeId: import("vue").ComputedRef<any>;
+    activeRootId: import("vue").ComputedRef<any>;
+    recalculate: () => void;
+};
+export {};

package/dist/composables/virtual/useWindowedStore.d.ts

@@ -0,0 +1,43 @@
+import { type Ref, type ShallowRef } from "vue";
+/**
+ * Lineage: a glass-ui primitive at v0.9.4, retired at v1.0 (MIGRATION.md §3.3),
+ * carried on as a verbatim transposed copy in the words app, and HOME again at
+ * BC (the words wordlist store is the live consumer the no-consumer retirement
+ * verdict missed). Byte-faithful to the proven words copy — the
+ * generation-counter stale-append rejection is the load-bearing concurrency
+ * primitive, preserved verbatim.
+ */
+interface ResidentWindowConfig {
+    /** Maximum items to keep in memory. Default: 200. */
+    maxResident?: number;
+}
+interface ResidentWindowState<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 declare function useWindowedStore<T>(options?: ResidentWindowConfig): ResidentWindowState<T>;
+export {};

package/dist/composables/virtual/virtualSectionLayout.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Pure layout computation functions for virtual section scrolling.
+ *
+ * These are stateless — they take data in, return layout info out.
+ * No Vue reactivity, no DOM access.
+ *
+ * Lineage: this engine was a glass-ui primitive at v0.9.4, retired at v1.0
+ * (MIGRATION.md §3.4 — "0 production consumers, demo-only"), and lived on as
+ * a verbatim transposed copy in the words app. The retirement is REVERSED at
+ * BC: the live words consumer + the dock-search results list overturn the
+ * no-consumer verdict, so the windowing engine comes HOME. Byte-faithful to
+ * the proven words copy except the one functional refinement recorded below
+ * (`findSectionOffset` binary search) and the shared-hierarchy type-reconcile.
+ */
+import type { SectionHierarchy } from "../sidebar/types";
+/**
+ * A flattened section item with hierarchy metadata for virtual scrolling.
+ *
+ * The four hierarchy fields (`depth`/`rootId`/`parentId`/`rootIndex`) come
+ * from the shared `SectionHierarchy` base (`composables/sidebar/types`) — the
+ * same fields the sidebar's `TreeIndexEntry` carries, declared ONCE. The
+ * producer (`flattenPaperSections` in latex-paper, the dock-search result
+ * flattener) builds these in the consumer; glass-ui owns only the contract.
+ */
+export interface FlatSection extends SectionHierarchy {
+    id: string;
+    index: number;
+    estimatedHeight: number;
+}
+/** A single entry in a computed section layout with resolved position. */
+interface VirtualLayoutEntry<T extends FlatSection = FlatSection> {
+    item: T;
+    height: number;
+    top: number;
+    bottom: number;
+}
+/** Complete layout for a list of sections — entries plus total height. */
+export interface SectionLayout<T extends FlatSection = FlatSection> {
+    entries: VirtualLayoutEntry<T>[];
+    totalHeight: number;
+    /**
+     * Entry slots sorted ascending by `item.id`, so `findSectionOffset` can
+     * binary-search an arbitrary string id in O(log n) (the words copy
+     * linear-scanned `entries` — `virtualSectionLayout.ts:244-252`). Built
+     * once in `buildSectionLayout`; the `top` is read straight off the matched
+     * entry, so the offset answer is byte-identical to the linear scan.
+     */
+    byId: VirtualLayoutEntry<T>[];
+}
+/** The visible window range with spacer sizes for virtual scrolling. */
+export interface SectionWindowRange {
+    startIndex: number;
+    endIndex: number;
+    topSpacerPx: number;
+    bottomSpacerPx: number;
+}
+/** A forced index range that must be included in the visible window. */
+export interface ForcedSectionWindowRange {
+    startIndex: number;
+    endIndex: number;
+}
+/**
+ * Build a layout from a flat list of sections using a height resolver.
+ *
+ * Each entry gets an absolute `top` and `bottom` offset in pixels,
+ * computed sequentially from index 0. Heights are rounded and clamped >= 1.
+ */
+export declare function buildSectionLayout<T extends FlatSection>(items: readonly T[], getHeight: (item: T) => number): SectionLayout<T>;
+/**
+ * Resolve which section indices are visible given scroll state.
+ *
+ * Uses binary search for O(log n) lookup. Overscan extends the window
+ * before and after the viewport. An optional `forcedRange` guarantees
+ * certain indices are always included (used for warm-up targeting).
+ */
+export declare function resolveSectionWindow<T extends FlatSection>(layout: SectionLayout<T>, scrollTopPx: number, viewportHeightPx: number, overscanBeforePx: number, overscanAfterPx: number, forcedRange?: ForcedSectionWindowRange | null): SectionWindowRange;
+/**
+ * Find the section that is "active" at a given scroll offset.
+ *
+ * Returns the last section whose top edge is at or before `activeOffsetPx`.
+ *
+ * NOTE — this is the windowing-LOCAL render-active reader (the section at the
+ * 20%-viewport mark, used to label the current render window). It is NOT the
+ * ToC's binding active-section reader: a sidebar/ToC consumer reads
+ * `useScrollTracker.activeId` (the deepest-visible reader) for the highlight.
+ * The two serve distinct concerns and are deliberately NOT one function
+ * (BC.W-VIRTUAL-WINDOW active-section reconcile).
+ */
+export declare function resolveActiveSection<T extends FlatSection>(layout: SectionLayout<T>, activeOffsetPx: number): T | null;
+/**
+ * Find the pixel offset of a section by its `id`.
+ * Returns `null` if the section is not in the layout.
+ *
+ * REFINEMENT (BC.W-VIRTUAL-WINDOW): the words copy linear-scans `entries`
+ * matching on `id` (O(n), `virtualSectionLayout.ts:244-252`). Here we binary
+ * search `layout.byId` — the entries sorted ascending by `item.id` in
+ * `buildSectionLayout` — which is a total order over the string ids, so the
+ * search is correct + O(log n). The `top` is read straight off the matched
+ * entry, so the answer is byte-identical to the linear scan (the fixture pins
+ * this over a 1000-item layout).
+ */
+export declare function findSectionOffset<T extends FlatSection>(layout: SectionLayout<T>, id: string): number | null;
+export {};