@jupytergis/base 0.15.0 → 0.16.0-alpha.1

package/lib/features/story/components/SpectaDesktopView.js

@@ -0,0 +1,67 @@
+import React, { useImperativeHandle, useLayoutEffect, useMemo, } from 'react';
+import { ListStoryVirtualScrollTrack } from "./ListStoryVirtualScrollTrack";
+import { SpectaSingleModeContent } from "./SpectaSingleModeContent";
+import { useListStoryScrollTrackContext } from "../context/ListStoryScrollTrackContext";
+import { useListStoryScroll } from "../hooks/useListStoryScroll";
+import { useStoryScrollState } from "../hooks/useStoryScrollState";
+import { getSpectaPresentationCssVars } from "../utils/spectaPresentation";
+import { buildStorySegmentViewItems } from "../utils/storySegmentViewItems";
+import { STORY_TYPE } from "../../../types";
+import SpectaPresentationProgressBar from "../../../workspace/statusbar/SpectaPresentationProgressBar";
+export function SpectaDesktopView({ model, isSpecta, containerRef, storyViewerPanelRef, segmentContainerRef, storyData, currentIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, showGradient, setIndex, onSegmentTransitionChange, }) {
+    const isVerticalScrollView = (storyData === null || storyData === void 0 ? void 0 : storyData.storyType) === STORY_TYPE.verticalScroll;
+    const viewMode = isVerticalScrollView
+        ? 'verticalScroll'
+        : 'single';
+    const sentinelsEnabled = !isVerticalScrollView;
+    const { scrollContainerRef, topSentinelRef, bottomSentinelRef, getAtTop, getAtBottom, } = useStoryScrollState({ currentIndex, sentinelsEnabled });
+    const segmentViewItems = useMemo(() => buildStorySegmentViewItems(model, storyData), [model, storyData]);
+    const spectaPresentationStyle = useMemo(() => getSpectaPresentationCssVars(storyData), [
+        storyData === null || storyData === void 0 ? void 0 : storyData.storyType,
+        storyData === null || storyData === void 0 ? void 0 : storyData.presentationBgColor,
+        storyData === null || storyData === void 0 ? void 0 : storyData.presentationTextColor,
+    ]);
+    const segmentTransitionSyncEnabled = Boolean(onSegmentTransitionChange) && isVerticalScrollView;
+    const { scrollTrackLayout, bindScrollTrackElement } = useListStoryScrollTrackContext();
+    useLayoutEffect(() => {
+        if (!isVerticalScrollView) {
+            bindScrollTrackElement(null);
+            return;
+        }
+        bindScrollTrackElement(scrollContainerRef.current);
+        return () => {
+            bindScrollTrackElement(null);
+        };
+    }, [isVerticalScrollView, bindScrollTrackElement, scrollContainerRef]);
+    useListStoryScroll({
+        enabled: segmentTransitionSyncEnabled,
+        scrollContainerRef,
+        storyData,
+        scrollTrackLayout,
+        items: segmentViewItems,
+        currentIndex,
+        setIndex,
+        onSegmentTransitionChange,
+    });
+    const renderModeContent = {
+        single: () => (React.createElement(SpectaSingleModeContent, { isSpecta: isSpecta, segmentContainerRef: segmentContainerRef, storyData: storyData, currentIndex: currentIndex, activeSlide: activeSlide, layerName: layerName, handlePrev: handlePrev, handleNext: handleNext, hasPrev: hasPrev, hasNext: hasNext, topSentinelRef: topSentinelRef, bottomSentinelRef: bottomSentinelRef })),
+        verticalScroll: () => (React.createElement(ListStoryVirtualScrollTrack, { scrollTrackLayout: scrollTrackLayout })),
+    };
+    useImperativeHandle(storyViewerPanelRef, () => ({
+        handlePrev,
+        handleNext,
+        spectaMode: isSpecta,
+        hasPrev,
+        hasNext,
+        getAtTop,
+        getAtBottom,
+        getScrollContainer: () => scrollContainerRef.current,
+    }), [handlePrev, handleNext, isSpecta, hasPrev, hasNext, getAtTop, getAtBottom]);
+    return (React.createElement(React.Fragment, null,
+        React.createElement("div", { className: "jgis-specta-right-panel-container-mod jgis-right-panel-container", style: showGradient ? undefined : { width: '25%', borderRadius: 0 } },
+            React.createElement("div", { ref: containerRef, className: "jgis-specta-story-panel-container", style: spectaPresentationStyle },
+                React.createElement("div", { ref: scrollContainerRef, className: `jgis-story-viewer-panel-specta-mod ${isVerticalScrollView
+                        ? 'jgis-story-viewer-panel-specta-mod-vertical-scroll'
+                        : ''}`, id: "jgis-story-segment-panel", style: showGradient ? undefined : { width: 'unset' } }, renderModeContent[viewMode]()))),
+        !isVerticalScrollView && React.createElement(SpectaPresentationProgressBar, { model: model })));
+}

package/lib/features/story/components/SpectaMobileListModeContent.d.ts

@@ -0,0 +1,13 @@
+import { IJGISStoryMap, IJupyterGISModel } from '@jupytergis/schema';
+import type { IListStorySegmentTransition } from "../types/types";
+export interface ISpectaMobileListModeContentProps {
+    model: IJupyterGISModel;
+    storyData: IJGISStoryMap | null;
+    currentIndex: number;
+    setIndex: (index: number) => void;
+    onSegmentTransitionChange?: (payload: IListStorySegmentTransition | null) => void;
+}
+/**
+ * Mobile list story: full-viewport touch scroll on the virtual track drives
+ */
+export declare function SpectaMobileListModeContent({ model, storyData, currentIndex, setIndex, onSegmentTransitionChange, }: ISpectaMobileListModeContentProps): JSX.Element;

package/lib/features/story/components/SpectaMobileListModeContent.js

@@ -0,0 +1,36 @@
+import React, { useLayoutEffect, useMemo, useRef } from 'react';
+import { ListStoryVirtualScrollTrack } from "./ListStoryVirtualScrollTrack";
+import { useListStoryScrollTrackContext } from "../context/ListStoryScrollTrackContext";
+import { useListStoryScroll } from "../hooks/useListStoryScroll";
+import { getSpectaPresentationStyle } from "../utils/spectaPresentation";
+import { buildStorySegmentViewItems } from "../utils/storySegmentViewItems";
+import { STORY_TYPE } from "../../../types";
+/**
+ * Mobile list story: full-viewport touch scroll on the virtual track drives
+ */
+export function SpectaMobileListModeContent({ model, storyData, currentIndex, setIndex, onSegmentTransitionChange, }) {
+    const scrollContainerRef = useRef(null);
+    const { scrollTrackLayout, bindScrollTrackElement } = useListStoryScrollTrackContext();
+    const segmentViewItems = useMemo(() => buildStorySegmentViewItems(model, storyData), [model, storyData]);
+    const presentationStyle = getSpectaPresentationStyle(storyData);
+    const segmentTransitionSyncEnabled = Boolean(onSegmentTransitionChange) &&
+        (storyData === null || storyData === void 0 ? void 0 : storyData.storyType) === STORY_TYPE.verticalScroll;
+    useLayoutEffect(() => {
+        bindScrollTrackElement(scrollContainerRef.current);
+        return () => {
+            bindScrollTrackElement(null);
+        };
+    }, [bindScrollTrackElement]);
+    useListStoryScroll({
+        enabled: segmentTransitionSyncEnabled,
+        scrollContainerRef,
+        storyData,
+        scrollTrackLayout,
+        items: segmentViewItems,
+        currentIndex,
+        setIndex,
+        onSegmentTransitionChange,
+    });
+    return (React.createElement("div", { ref: scrollContainerRef, id: "jgis-story-segment-panel", className: "jgis-story-viewer-panel-specta-mod-vertical-scroll jgis-story-mobile-list-scroll", style: presentationStyle },
+        React.createElement(ListStoryVirtualScrollTrack, { scrollTrackLayout: scrollTrackLayout })));
+}

package/lib/features/story/components/SpectaMobileSingleModeContent.d.ts

@@ -0,0 +1,14 @@
+import { IJGISStoryMap, IStorySegmentLayer } from '@jupytergis/schema';
+import { RefObject } from 'react';
+export interface ISpectaMobileSingleModeContentProps {
+    segmentContainerRef: RefObject<HTMLDivElement>;
+    storyData: IJGISStoryMap | null;
+    currentIndex: number;
+    activeSlide: IStorySegmentLayer['parameters'] | undefined;
+    layerName: string;
+    handlePrev: () => void;
+    handleNext: () => void;
+    hasPrev: boolean;
+    hasNext: boolean;
+}
+export declare function SpectaMobileSingleModeContent({ segmentContainerRef, storyData, currentIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, }: ISpectaMobileSingleModeContentProps): JSX.Element;

package/lib/{panelview/story-maps/components/SpectaMobileView.js → features/story/components/SpectaMobileSingleModeContent.js}

@@ -1,8 +1,8 @@
 import React, { useEffect, useState } from 'react';
+import StoryViewerPanel from "../StoryViewerPanel";
+import { getSpectaPresentationStyle } from "../utils/spectaPresentation";
 import { Button } from "../../../shared/components/Button";
 import { Drawer, DrawerContent, DrawerTrigger, } from "../../../shared/components/Drawer";
-import StoryViewerPanel from '../StoryViewerPanel';
-import { getSpectaPresentationStyle } from '../hooks/useStoryMap';
 const MAIN_ID = 'jp-main-content-panel';
 const SEGMENT_PANEL_ID = 'jgis-story-segment-panel';
 const SEGMENT_HEADER_ID = 'jgis-story-segment-header';
@@ -29,7 +29,7 @@ function getFirstSnapFromSegmentHeader(mainEl, segmentPanelEl, segmentHeaderEl)
     const clamped = Math.max(SNAP_FIRST_MIN, Math.min(SNAP_FIRST_MAX, fraction));
     return clamped;
 }
-export function SpectaMobileView({ model, segmentContainerRef, storyData, currentIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, setIndex, }) {
+export function SpectaMobileSingleModeContent({ segmentContainerRef, storyData, currentIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, }) {
     const [container, setContainer] = useState(null);
     const [snapPoints, setSnapPoints] = useState([
         SNAP_FIRST_DEFAULT,
@@ -37,7 +37,6 @@ export function SpectaMobileView({ model, segmentContainerRef, storyData, curren
     ]);
     const [snap, setSnap] = useState(snapPoints[0]);
     const presentationStyle = getSpectaPresentationStyle(storyData);
-    // Keep active snap in sync with snapPoints so Vaul's --snap-point-height stays defined.
     useEffect(() => {
         const isInSnapPoints = snapPoints.some(p => p === snap ||
             (typeof p === 'number' &&
@@ -47,7 +46,6 @@ export function SpectaMobileView({ model, segmentContainerRef, storyData, curren
             setSnap(snapPoints[0]);
         }
     }, [snapPoints, snap]);
-    // Observe #jgis-story-segment-panel (and re-attach when drawer reopens).
     useEffect(() => {
         const mainEl = document.getElementById(MAIN_ID);
         setContainer(mainEl);
@@ -96,5 +94,5 @@ export function SpectaMobileView({ model, segmentContainerRef, storyData, curren
                 React.createElement(Button, null, "Open Story Panel")),
             React.createElement(DrawerContent, { style: presentationStyle },
                 React.createElement("div", { id: SEGMENT_PANEL_ID, className: "jgis-story-viewer-panel" },
-                    React.createElement(StoryViewerPanel, { model: model, isSpecta: true, isMobile: true, segmentContainerRef: segmentContainerRef, storyData: storyData, currentIndex: currentIndex, activeSlide: activeSlide, layerName: layerName, handlePrev: handlePrev, handleNext: handleNext, hasPrev: hasPrev, hasNext: hasNext, setIndex: setIndex }))))));
+                    React.createElement(StoryViewerPanel, { isSpecta: true, isMobile: true, segmentContainerRef: segmentContainerRef, storyData: storyData, currentIndex: currentIndex, activeSlide: activeSlide, layerName: layerName, segmentNav: { handlePrev, handleNext, hasPrev, hasNext } }))))));
 }

package/lib/{panelview/story-maps → features/story}/components/SpectaMobileView.d.ts

@@ -1,17 +1,19 @@
 import { IJGISStoryMap, IJupyterGISModel, IStorySegmentLayer } from '@jupytergis/schema';
-import React, { RefObject } from 'react';
+import { RefObject } from 'react';
+import type { IListStorySegmentTransition } from "../types/types";
 interface ISpectaMobileViewProps {
     model: IJupyterGISModel;
     segmentContainerRef: RefObject<HTMLDivElement>;
     storyData: IJGISStoryMap | null;
     currentIndex: number;
+    setIndex: (index: number) => void;
     activeSlide: IStorySegmentLayer['parameters'] | undefined;
     layerName: string;
     handlePrev: () => void;
     handleNext: () => void;
     hasPrev: boolean;
     hasNext: boolean;
-    setIndex: (index: number) => void;
+    onSegmentTransitionChange?: (payload: IListStorySegmentTransition | null) => void;
 }
-export declare function SpectaMobileView({ model, segmentContainerRef, storyData, currentIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, setIndex, }: ISpectaMobileViewProps): React.JSX.Element;
+export declare function SpectaMobileView({ model, segmentContainerRef, storyData, currentIndex, setIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, onSegmentTransitionChange, }: ISpectaMobileViewProps): JSX.Element;
 export {};

package/lib/features/story/components/SpectaMobileView.js

@@ -0,0 +1,12 @@
+import React from 'react';
+import { SpectaMobileListModeContent } from "./SpectaMobileListModeContent";
+import { SpectaMobileSingleModeContent } from "./SpectaMobileSingleModeContent";
+import { STORY_TYPE } from "../../../types";
+export function SpectaMobileView({ model, segmentContainerRef, storyData, currentIndex, setIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, onSegmentTransitionChange, }) {
+    const viewMode = (storyData === null || storyData === void 0 ? void 0 : storyData.storyType) === STORY_TYPE.verticalScroll ? 'list' : 'single';
+    const renderModeContent = {
+        single: () => (React.createElement(SpectaMobileSingleModeContent, { segmentContainerRef: segmentContainerRef, storyData: storyData, currentIndex: currentIndex, activeSlide: activeSlide, layerName: layerName, handlePrev: handlePrev, handleNext: handleNext, hasPrev: hasPrev, hasNext: hasNext })),
+        list: () => (React.createElement(SpectaMobileListModeContent, { model: model, storyData: storyData, currentIndex: currentIndex, setIndex: setIndex, onSegmentTransitionChange: onSegmentTransitionChange })),
+    };
+    return renderModeContent[viewMode]();
+}

package/lib/features/story/components/SpectaSingleModeContent.d.ts

@@ -0,0 +1,18 @@
+import { IJGISStoryMap, IStorySegmentLayer } from '@jupytergis/schema';
+import { RefObject } from 'react';
+interface ISpectaSingleModeContentProps {
+    isSpecta: boolean;
+    segmentContainerRef: RefObject<HTMLDivElement>;
+    storyData: IJGISStoryMap | null;
+    currentIndex: number;
+    activeSlide: IStorySegmentLayer['parameters'] | undefined;
+    layerName: string;
+    handlePrev: () => void;
+    handleNext: () => void;
+    hasPrev: boolean;
+    hasNext: boolean;
+    topSentinelRef: RefObject<HTMLDivElement>;
+    bottomSentinelRef: RefObject<HTMLDivElement>;
+}
+export declare function SpectaSingleModeContent({ isSpecta, segmentContainerRef, storyData, currentIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, topSentinelRef, bottomSentinelRef, }: ISpectaSingleModeContentProps): JSX.Element;
+export {};

package/lib/features/story/components/SpectaSingleModeContent.js

@@ -0,0 +1,8 @@
+import React from 'react';
+import StoryViewerPanel from "../StoryViewerPanel";
+export function SpectaSingleModeContent({ isSpecta, segmentContainerRef, storyData, currentIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, topSentinelRef, bottomSentinelRef, }) {
+    return (React.createElement(React.Fragment, null,
+        React.createElement("div", { ref: topSentinelRef, "aria-hidden": true, "data-story-scroll-sentinel": "top", style: { height: 1, minHeight: 1, pointerEvents: 'none' } }),
+        React.createElement(StoryViewerPanel, { isSpecta: isSpecta, segmentContainerRef: segmentContainerRef, storyData: storyData, currentIndex: currentIndex, activeSlide: activeSlide, layerName: layerName, segmentNav: { handlePrev, handleNext, hasPrev, hasNext } }),
+        React.createElement("div", { ref: bottomSentinelRef, "aria-hidden": true, "data-story-scroll-sentinel": "bottom", style: { height: 1, minHeight: 1, pointerEvents: 'none' } })));
+}

package/lib/features/story/context/ListStoryScrollTrackContext.d.ts

@@ -0,0 +1,19 @@
+import type { IJupyterGISModel } from '@jupytergis/schema';
+import React from 'react';
+import type { IListStoryScrollTrackLayout } from "../types/types";
+interface IListStoryScrollTrackContextValue {
+    scrollTrackLayout: IListStoryScrollTrackLayout | null;
+    scrollTop: number;
+    bindScrollTrackElement: (element: HTMLDivElement | null) => void;
+    scrollToSegmentIndex: (index: number, options?: {
+        behavior?: ScrollBehavior;
+    }) => void;
+}
+interface IListStoryScrollTrackProviderProps {
+    model: IJupyterGISModel;
+    enabled: boolean;
+    children: React.ReactNode;
+}
+export declare function ListStoryScrollTrackProvider({ model, enabled, children, }: IListStoryScrollTrackProviderProps): JSX.Element;
+export declare function useListStoryScrollTrackContext(): IListStoryScrollTrackContextValue;
+export {};

package/lib/features/story/context/ListStoryScrollTrackContext.js

@@ -0,0 +1,186 @@
+import React, { createContext, useCallback, useContext, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { ListStoryMarkdownMeasurePane } from "../components/ListStoryMarkdownMeasurePane";
+import { useCurrentSegmentIndex } from "../hooks/useCurrentSegmentIndex";
+import { useQueuedMarkdownHeightMeasure } from "../hooks/useQueuedMarkdownHeightMeasure";
+import { buildListStoryScrollTrack } from "../utils/listStoryScrollTrack";
+import { buildStorySegmentViewItems, getListStoryMarkdownSegmentsFromItems, } from "../utils/storySegmentViewItems";
+const ListStoryScrollTrackContext = createContext(null);
+export function ListStoryScrollTrackProvider({ model, enabled, children, }) {
+    const [storyRevision, setStoryRevision] = useState(0);
+    const [heightsById, setHeightsById] = useState({});
+    const [viewportHeight, setViewportHeight] = useState(0);
+    const [mapViewportHeight, setMapViewportHeight] = useState(0);
+    const [scrollTop, setScrollTop] = useState(0);
+    const currentSegmentIndex = useCurrentSegmentIndex(model);
+    const scrollerRef = useRef(null);
+    const [scrollTrackElement, setScrollTrackElement] = useState(null);
+    useLayoutEffect(() => {
+        const bump = () => {
+            setStoryRevision(value => value + 1);
+            setHeightsById({});
+        };
+        model.sharedModel.storyMapsChanged.connect(bump);
+        model.sharedModel.layersChanged.connect(bump);
+        return () => {
+            model.sharedModel.storyMapsChanged.disconnect(bump);
+            model.sharedModel.layersChanged.disconnect(bump);
+        };
+    }, [model]);
+    const storyData = useMemo(() => {
+        var _a;
+        return (_a = model.getSelectedStory().story) !== null && _a !== void 0 ? _a : null;
+    }, [model, storyRevision]);
+    const items = useMemo(() => buildStorySegmentViewItems(model, storyData), [model, storyData]);
+    const markdownSegments = useMemo(() => getListStoryMarkdownSegmentsFromItems(items), [items]);
+    const mapViewportHeightOption = mapViewportHeight > 0 ? mapViewportHeight : undefined;
+    const buildScrollTrackLayout = useCallback((nextHeightsById) => buildListStoryScrollTrack({
+        items,
+        viewportHeight,
+        mapViewportHeight: mapViewportHeightOption,
+        heightsById: nextHeightsById,
+    }), [items, viewportHeight, mapViewportHeightOption]);
+    const syncScrollerMetrics = useCallback((scroller) => {
+        setViewportHeight(scroller.clientHeight);
+        setScrollTop(scroller.scrollTop);
+    }, []);
+    const bindScrollTrackElement = useCallback((element) => {
+        scrollerRef.current = element;
+        setScrollTrackElement(element);
+        if (!element) {
+            setViewportHeight(0);
+            setScrollTop(0);
+            return;
+        }
+        syncScrollerMetrics(element);
+    }, [syncScrollerMetrics]);
+    const observeElementHeight = useCallback((element, update, options) => {
+        if (options === null || options === void 0 ? void 0 : options.callImmediately) {
+            update();
+        }
+        const ro = new ResizeObserver(update);
+        ro.observe(element);
+        return () => {
+            ro.disconnect();
+        };
+    }, []);
+    useLayoutEffect(() => {
+        const scroller = scrollTrackElement;
+        if (!scroller || !enabled) {
+            return;
+        }
+        const update = () => {
+            syncScrollerMetrics(scroller);
+        };
+        return observeElementHeight(scroller, update);
+    }, [enabled, scrollTrackElement, observeElementHeight, syncScrollerMetrics]);
+    useLayoutEffect(() => {
+        const scroller = scrollTrackElement;
+        if (!scroller || !enabled) {
+            return;
+        }
+        const onScroll = () => {
+            setScrollTop(scroller.scrollTop);
+            setViewportHeight(scroller.clientHeight);
+        };
+        scroller.addEventListener('scroll', onScroll, { passive: true });
+        onScroll();
+        return () => {
+            scroller.removeEventListener('scroll', onScroll);
+        };
+    }, [enabled, scrollTrackElement]);
+    useLayoutEffect(() => {
+        if (!enabled) {
+            setMapViewportHeight(0);
+            return;
+        }
+        const container = document.querySelector('.jGIS-Mainview-Container');
+        if (!(container instanceof HTMLElement)) {
+            setMapViewportHeight(0);
+            return;
+        }
+        const update = () => {
+            setMapViewportHeight(container.clientHeight);
+        };
+        return observeElementHeight(container, update, { callImmediately: true });
+    }, [enabled, storyRevision, observeElementHeight]);
+    const handleMeasuredHeight = useCallback((segmentId, height) => {
+        const measuredHeightPx = Math.ceil(height);
+        setHeightsById(prev => {
+            if (prev[segmentId] === measuredHeightPx) {
+                return prev;
+            }
+            const scroller = scrollerRef.current;
+            const oldLayout = enabled && viewportHeight > 0
+                ? buildListStoryScrollTrack({
+                    items,
+                    viewportHeight,
+                    mapViewportHeight: mapViewportHeight || undefined,
+                    heightsById: prev,
+                })
+                : null;
+            const next = Object.assign(Object.assign({}, prev), { [segmentId]: measuredHeightPx });
+            if (scroller && oldLayout) {
+                const oldSegment = oldLayout.segments.find(s => s.id === segmentId);
+                if (oldSegment && !oldSegment.measured) {
+                    const scrollCompensation = measuredHeightPx - oldSegment.height;
+                    if (scrollCompensation !== 0 &&
+                        scroller.scrollTop > oldSegment.start) {
+                        requestAnimationFrame(() => {
+                            scroller.scrollTop += scrollCompensation;
+                        });
+                    }
+                }
+            }
+            return next;
+        });
+    }, [enabled, items, mapViewportHeight, viewportHeight]);
+    const { segmentBeingMeasured, reportHeight, completeMeasure } = useQueuedMarkdownHeightMeasure({
+        enabled: enabled && viewportHeight > 0,
+        markdownSegments,
+        currentSegmentIndex,
+        heightsById,
+        onHeight: handleMeasuredHeight,
+    });
+    const scrollTrackLayout = useMemo(() => {
+        if (!enabled || !items.length || viewportHeight <= 0) {
+            return null;
+        }
+        return buildScrollTrackLayout(heightsById);
+    }, [enabled, items, viewportHeight, heightsById, buildScrollTrackLayout]);
+    const scrollToSegmentIndex = useCallback((index, options) => {
+        var _a;
+        const safeIndex = Math.max(0, index);
+        const scroller = scrollerRef.current;
+        const segment = scrollTrackLayout === null || scrollTrackLayout === void 0 ? void 0 : scrollTrackLayout.segments.find(s => s.index === safeIndex);
+        if (scroller && segment !== undefined) {
+            scroller.scrollTo({
+                top: segment.start,
+                behavior: (_a = options === null || options === void 0 ? void 0 : options.behavior) !== null && _a !== void 0 ? _a : 'smooth',
+            });
+            return;
+        }
+        model.setCurrentSegmentIndex(safeIndex);
+    }, [model, scrollTrackLayout]);
+    const value = useMemo(() => ({
+        scrollTrackLayout,
+        scrollTop,
+        bindScrollTrackElement,
+        scrollToSegmentIndex,
+    }), [
+        scrollTrackLayout,
+        scrollTop,
+        bindScrollTrackElement,
+        scrollToSegmentIndex,
+    ]);
+    return (React.createElement(ListStoryScrollTrackContext.Provider, { value: value },
+        children,
+        enabled && segmentBeingMeasured ? (React.createElement("div", { className: "jgis-story-markdown-measure-host", "aria-hidden": true },
+            React.createElement(ListStoryMarkdownMeasurePane, { key: segmentBeingMeasured.id, segmentId: segmentBeingMeasured.id, markdown: segmentBeingMeasured.markdown, onHeight: reportHeight, onMeasureComplete: completeMeasure }))) : null));
+}
+export function useListStoryScrollTrackContext() {
+    const value = useContext(ListStoryScrollTrackContext);
+    if (!value) {
+        throw new Error('useListStoryScrollTrackContext must be used within ListStoryScrollTrackProvider');
+    }
+    return value;
+}

package/lib/features/story/hooks/useCurrentSegmentIndex.d.ts

@@ -0,0 +1,3 @@
+import type { IJupyterGISModel } from '@jupytergis/schema';
+/** Subscribes to model's current story segment index for a single source of truth */
+export declare function useCurrentSegmentIndex(model: IJupyterGISModel): number;

package/lib/features/story/hooks/useCurrentSegmentIndex.js

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react';
+/** Subscribes to model's current story segment index for a single source of truth */
+export function useCurrentSegmentIndex(model) {
+    const [currentIndex, setCurrentIndex] = useState(() => { var _a; return (_a = model.getCurrentSegmentIndex()) !== null && _a !== void 0 ? _a : 0; });
+    useEffect(() => {
+        var _a;
+        const handler = (_sender, index) => {
+            setCurrentIndex(Math.max(0, index !== null && index !== void 0 ? index : 0));
+        };
+        model.currentSegmentIndexChanged.connect(handler);
+        setCurrentIndex((_a = model.getCurrentSegmentIndex()) !== null && _a !== void 0 ? _a : 0);
+        return () => {
+            model.currentSegmentIndexChanged.disconnect(handler);
+        };
+    }, [model]);
+    return currentIndex;
+}

package/lib/features/story/hooks/useListStoryScroll.d.ts

@@ -0,0 +1,15 @@
+import type { IJGISStoryMap } from '@jupytergis/schema';
+import { RefObject } from 'react';
+import type { IListStoryScrollTrackLayout, IStorySegmentViewItem, IListStorySegmentTransition } from "../types/types";
+interface IUseListStoryScrollParams {
+    enabled: boolean;
+    scrollContainerRef: RefObject<HTMLDivElement | null>;
+    storyData: IJGISStoryMap | null;
+    scrollTrackLayout: IListStoryScrollTrackLayout | null;
+    items: IStorySegmentViewItem[];
+    currentIndex: number;
+    setIndex: (index: number) => void;
+    onSegmentTransitionChange?: (payload: IListStorySegmentTransition | null) => void;
+}
+export declare function useListStoryScroll({ enabled, scrollContainerRef, storyData, scrollTrackLayout, items, currentIndex, setIndex, onSegmentTransitionChange, }: IUseListStoryScrollParams): void;
+export {};

package/lib/features/story/hooks/useListStoryScroll.js

@@ -0,0 +1,107 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { computeListStoryScrollState, } from "../utils/computeListStoryScrollState";
+function isSameSegmentTransition(prev, next) {
+    if (!prev || !next) {
+        return false;
+    }
+    return (next.progress === prev.progress &&
+        next.fromIndex === prev.fromIndex &&
+        next.toIndex === prev.toIndex &&
+        next.fromMode === prev.fromMode &&
+        next.toMode === prev.toMode);
+}
+export function useListStoryScroll({ enabled, scrollContainerRef, storyData, scrollTrackLayout, items, currentIndex, setIndex, onSegmentTransitionChange, }) {
+    const onSegmentTransitionChangeRef = useRef(onSegmentTransitionChange);
+    onSegmentTransitionChangeRef.current = onSegmentTransitionChange;
+    const setIndexRef = useRef(setIndex);
+    setIndexRef.current = setIndex;
+    const storyDataRef = useRef(storyData);
+    storyDataRef.current = storyData;
+    const scrollTrackLayoutRef = useRef(scrollTrackLayout);
+    scrollTrackLayoutRef.current = scrollTrackLayout;
+    const currentIndexRef = useRef(currentIndex);
+    currentIndexRef.current = currentIndex;
+    const latchedRef = useRef({
+        activeIndex: currentIndex,
+        segmentTransition: null,
+    });
+    const rafIdRef = useRef(null);
+    const clearSegmentTransition = useCallback(() => {
+        var _a;
+        latchedRef.current = {
+            activeIndex: currentIndexRef.current,
+            segmentTransition: null,
+        };
+        (_a = onSegmentTransitionChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onSegmentTransitionChangeRef, null);
+    }, []);
+    const emitState = useCallback((next) => {
+        var _a;
+        const prev = latchedRef.current;
+        latchedRef.current = next;
+        if (next.activeIndex !== currentIndexRef.current) {
+            setIndexRef.current(next.activeIndex);
+        }
+        const segmentTransition = next.segmentTransition;
+        const prevTransition = prev.segmentTransition;
+        if (isSameSegmentTransition(prevTransition, segmentTransition)) {
+            return;
+        }
+        (_a = onSegmentTransitionChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onSegmentTransitionChangeRef, segmentTransition);
+    }, []);
+    const computeAndEmit = useCallback(() => {
+        const scroller = scrollContainerRef.current;
+        const layout = scrollTrackLayoutRef.current;
+        const currentStoryData = storyDataRef.current;
+        if (!enabled || !scroller || !currentStoryData || !layout) {
+            clearSegmentTransition();
+            return;
+        }
+        const next = computeListStoryScrollState({
+            scrollTop: scroller.scrollTop,
+            viewportHeight: scroller.clientHeight,
+            segments: layout.segments,
+        });
+        if (!next) {
+            return;
+        }
+        emitState(next);
+    }, [enabled, scrollContainerRef, emitState, clearSegmentTransition]);
+    const scheduleCompute = useCallback(() => {
+        if (rafIdRef.current !== null) {
+            return;
+        }
+        rafIdRef.current = window.requestAnimationFrame(() => {
+            rafIdRef.current = null;
+            computeAndEmit();
+        });
+    }, [computeAndEmit]);
+    useEffect(() => {
+        latchedRef.current = {
+            activeIndex: currentIndex,
+            segmentTransition: latchedRef.current.segmentTransition,
+        };
+    }, [currentIndex]);
+    useEffect(() => {
+        scheduleCompute();
+    }, [items, storyData, scrollTrackLayout, scheduleCompute]);
+    useEffect(() => {
+        if (!enabled) {
+            clearSegmentTransition();
+            return;
+        }
+        const scroller = scrollContainerRef.current;
+        if (!scroller) {
+            clearSegmentTransition();
+            return;
+        }
+        scroller.addEventListener('scroll', scheduleCompute, { passive: true });
+        scheduleCompute();
+        return () => {
+            scroller.removeEventListener('scroll', scheduleCompute);
+            if (rafIdRef.current !== null) {
+                window.cancelAnimationFrame(rafIdRef.current);
+                rafIdRef.current = null;
+            }
+        };
+    }, [enabled, scrollContainerRef, scheduleCompute, clearSegmentTransition]);
+}

package/lib/features/story/hooks/useQueuedMarkdownHeightMeasure.d.ts

@@ -0,0 +1,19 @@
+import type { IListStoryMarkdownSegment } from "../types/types";
+interface IUseQueuedMarkdownHeightMeasureParams {
+    enabled: boolean;
+    markdownSegments: IListStoryMarkdownSegment[];
+    currentSegmentIndex: number;
+    heightsById: Readonly<Record<string, number>>;
+    onHeight: (segmentId: string, height: number) => void;
+}
+interface IQueuedMarkdownHeightMeasureState {
+    segmentBeingMeasured: IListStoryMarkdownSegment | null;
+    reportHeight: (segmentId: string, height: number) => void;
+    completeMeasure: () => void;
+}
+/**
+ * Queues markdown segments near the active index and measures them one at a time
+ * in a shared off-screen pane (see ListStoryMarkdownMeasurePane).
+ */
+export declare function useQueuedMarkdownHeightMeasure({ enabled, markdownSegments, currentSegmentIndex, heightsById, onHeight, }: IUseQueuedMarkdownHeightMeasureParams): IQueuedMarkdownHeightMeasureState;
+export {};