@mkbabb/glass-ui 4.0.1 → 4.2.0

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 {};