@mkbabb/glass-ui 4.0.0 → 4.1.0

package/dist/composables/motion/useScrollTrigger.d.ts

@@ -0,0 +1,67 @@
+import { type MaybeRefOrGetter, type Ref } from "vue";
+/**
+ * A declared trigger-point on the scroll source: a pixel offset, a 0..1 progress
+ * fraction (resolved against the source's scrollable extent), or a named element
+ * whose top crosses the source.
+ */
+export interface TriggerPoint {
+    /**
+     * A pixel offset on the scroll source, OR a 0..1 progress fraction (resolved
+     * against the source's scrollable extent), OR a named element whose top crosses
+     * the source.
+     */
+    at: number | {
+        fraction: number;
+    } | {
+        element: MaybeRefOrGetter<HTMLElement | null>;
+    };
+    /** Fire on which crossing direction. Default "both". */
+    direction?: "down" | "up" | "both";
+    /** Stable id for the event payload + de-dup. */
+    id?: string;
+}
+export interface UseScrollTriggerOptions {
+    triggers?: TriggerPoint[];
+    /**
+     * The flip-delta debounce (px) before a DIRECTION flip commits — the anti-thrash,
+     * mirroring the dock's HOVER_INTENT_MS=60ms hysteresis. Default 8 (the RN
+     * reference).
+     */
+    flipDeltaPx?: number;
+    /** Resolve the continuous `progress` ref against the source (0..1). Default true. */
+    trackProgress?: boolean;
+    /** Honor `prefers-reduced-motion: reduce` (snap `progress` to discrete endpoints). Default true. */
+    respectReducedMotion?: boolean;
+    /** Crossed a trigger in the committed direction (fires ONCE per crossing). */
+    onCross?: (id: string, dir: "down" | "up", scrollPos: number) => void;
+    /** Crossed a trigger scrolling INTO its region (past it, in `down`). */
+    onEnter?: (id: string) => void;
+    /** Crossed OUT of a trigger's region (back before it, in `up`). */
+    onLeave?: (id: string) => void;
+}
+export interface UseScrollTriggerReturn {
+    /** Continuous 0..1 scroll progress off the SAME rAF read (native-timeline-gated). */
+    progress: Ref<number>;
+    /** Current scroll direction (committed past flipDeltaPx). */
+    direction: Ref<"down" | "up" | null>;
+    /** Current scroll velocity (px/s, framerate-independent — Δpos / Δt). */
+    velocity: Ref<number>;
+    /** Force a re-read + re-evaluate every trigger (post-resize/layout). */
+    recalculate: () => void;
+}
+/**
+ * The ONE scroll reader. Composes `createScrollReader` (the shared rAF-coalesced
+ * core); resolves triggers to px; emits direction/velocity/crossing; native-timeline-
+ * gated continuous ramp.
+ *
+ * @example
+ * ```ts
+ * const { progress, direction, velocity } = useScrollTrigger(() => window, {
+ *   triggers: [{ at: 120, id: "shrink", direction: "down" }],
+ *   onCross(id, dir, pos) {  // fires once when crossing 120px scrolling down
+ *     if (id === "shrink" && dir === "down") collapseChrome()
+ *   },
+ * })
+ * ```
+ */
+export declare function useScrollTrigger(scrollSource: MaybeRefOrGetter<HTMLElement | Window | null>, opts?: UseScrollTriggerOptions): UseScrollTriggerReturn;

package/dist/composables/motion/useSpringPress.d.ts

@@ -1,14 +1,14 @@
 import { type UseSpringOptions, type SpringRef } from "./useSpring";
 export interface UseSpringPressOptions extends UseSpringOptions {
     /**
-     * Spring `response`. Default 0.25s (iOS tap-press canonical; faster
-     * than the default `useSpring` 0.5s to keep press feedback under the
-     * 100ms perception threshold).
+     * Spring `response`. Default `0.15s` — the `press` SPRING_PRESETS row (the
+     * Apple `interactiveSpring`): the sub-100ms iOS tap-press window, faster than
+     * the generic `useSpring` 0.5s so the feedback lands under the 100ms threshold.
      */
     response?: number;
     /**
-     * Spring `dampingFraction`. Default 0.7 (overshoots ~5% — feels
-     * springy but doesn't ring).
+     * Spring `dampingFraction`. Default `0.86` — the `press` row's ζ: a tiny
+     * sub-perceptual rebound (springy/alive) that does NOT ring.
      */
     dampingFraction?: number;
 }

package/dist/composables/motion/useStaggerReveal.d.ts

@@ -25,4 +25,28 @@ export declare function useStaggerReveal(options?: StaggerRevealConfig): {
     register: (el: HTMLElement | null, index?: number) => void;
     revealed: Record<number, boolean>;
 };
+/**
+ * The `[data-scroll-reveal-once]` latch — BC.W-MOTION-PRESETS.
+ *
+ * The `scroll-driven.css` `[data-scroll-reveal]` recipe rides a native `view()`
+ * timeline that RE-FIRES its entrance every time a child re-enters the entry range
+ * — wrong for a virtualized/teleporting list (a row scrolls out + back and re-plays
+ * the fade-lift). A `view()` timeline cannot latch "play once" (the CSS limit), so
+ * the `[data-scroll-reveal-once]` opt-in plays the entrance ONCE: this directive
+ * adds `data-revealed=""` to each child on its FIRST cross and `unobserve`s it (the
+ * SAME `once: true` discipline `useStaggerReveal` runs above — `if (once)
+ * observer?.unobserve(el)`); the CSS plays the one-shot `gl-reveal-once` keyframe
+ * keyed off `[data-revealed]`, NOT the live `view()` range. NO second observer
+ * engine — the same `IntersectionObserver` the composable speaks for the `once`
+ * case, packaged as a Vue directive a consumer binds on the scroller.
+ *
+ * On an engine without `IntersectionObserver` (SSR/old) it reveals immediately so
+ * the terminal state is correct (the CSS animation simply never plays). Under PRM
+ * the scroll-driven.css `@media` outer gate drops the entrance and the row paints
+ * in-place (a flourish — the reveal carve, not a legibility cue).
+ */
+export declare const vScrollRevealOnce: {
+    mounted(scroller: HTMLElement): void;
+    unmounted(scroller: HTMLElement): void;
+};
 export {};

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

@@ -4,4 +4,7 @@ export type { SidebarFollowOptions } from "./useSidebarFollow";
 export { useSidebarState } from "./useSidebarState";
 export type { UseSidebarStateOptions, GenericSidebarState } from "./useSidebarState";
 export { useTreeIndex, buildTreeIndex, isActive, isInActiveChain } from "./useTreeIndex";
-export type { TreeNode, TreeIndexEntry, SidebarSection, SidebarIndexEntry, SidebarState, ScrollTrackerOptions, } from "./types";
+export { useScrollTo } from "./useScrollTo";
+export { useClickDelegate } from "./useClickDelegate";
+export { useLazyLoader } from "./useLazyLoader";
+export type { TreeNode, TreeIndexEntry, SidebarSection, SidebarIndexEntry, SidebarState, ScrollTrackerOptions, ScrollToOptions, ClickDelegateOptions, LazyLoaderOptions, } from "./types";

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

package/dist/concentric.d.ts

@@ -0,0 +1 @@
+export * from "./components/custom/concentric";