@jupytergis/base 0.15.0 → 0.16.0-alpha.0

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

@@ -0,0 +1,142 @@
+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 currentSegmentIndex = useCurrentSegmentIndex(model);
+    const scrollerRef = useRef(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 bindScrollTrackElement = useCallback((element) => {
+        scrollerRef.current = element;
+        if (!element) {
+            setViewportHeight(0);
+            return;
+        }
+        setViewportHeight(element.clientHeight);
+    }, []);
+    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 = scrollerRef.current;
+        if (!scroller || !enabled) {
+            return;
+        }
+        const update = () => {
+            setViewportHeight(scroller.clientHeight);
+        };
+        return observeElementHeight(scroller, update);
+    }, [enabled, storyRevision, observeElementHeight]);
+    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 value = useMemo(() => ({
+        scrollTrackLayout,
+        bindScrollTrackElement,
+    }), [scrollTrackLayout, bindScrollTrackElement]);
+    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 {};

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

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { buildPendingMeasureIds } from "../utils/listStoryMeasureQueue";
+/**
+ * Queues markdown segments near the active index and measures them one at a time
+ * in a shared off-screen pane (see ListStoryMarkdownMeasurePane).
+ */
+export function useQueuedMarkdownHeightMeasure({ enabled, markdownSegments, currentSegmentIndex, heightsById, onHeight, }) {
+    const [segmentBeingMeasured, setSegmentBeingMeasured] = useState(null);
+    const queueRef = useRef([]);
+    const refillQueue = useCallback(() => {
+        queueRef.current = buildPendingMeasureIds({
+            markdownSegments,
+            currentSegmentIndex,
+            heightsById,
+            measuringSegmentId: segmentBeingMeasured === null || segmentBeingMeasured === void 0 ? void 0 : segmentBeingMeasured.id,
+        });
+    }, [
+        markdownSegments,
+        currentSegmentIndex,
+        heightsById,
+        segmentBeingMeasured === null || segmentBeingMeasured === void 0 ? void 0 : segmentBeingMeasured.id,
+    ]);
+    const reportHeight = useCallback((segmentId, height) => {
+        onHeight(segmentId, height);
+    }, [onHeight]);
+    const completeMeasure = useCallback(() => {
+        setSegmentBeingMeasured(null);
+    }, []);
+    useEffect(() => {
+        if (!enabled) {
+            setSegmentBeingMeasured(null);
+            queueRef.current = [];
+            return;
+        }
+        refillQueue();
+        if (segmentBeingMeasured) {
+            return;
+        }
+        const nextId = queueRef.current.shift();
+        if (!nextId) {
+            return;
+        }
+        const segment = markdownSegments.find(item => item.id === nextId);
+        if (segment) {
+            setSegmentBeingMeasured(segment);
+        }
+    }, [
+        enabled,
+        currentSegmentIndex,
+        markdownSegments,
+        heightsById,
+        segmentBeingMeasured,
+        refillQueue,
+    ]);
+    return { segmentBeingMeasured, reportHeight, completeMeasure };
+}

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

@@ -0,0 +1 @@
+export declare function useStoryImagePreload(imageUrl?: string): boolean;

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

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react';
+export function useStoryImagePreload(imageUrl) {
+    const [imageLoaded, setImageLoaded] = useState(false);
+    useEffect(() => {
+        if (!imageUrl) {
+            setImageLoaded(false);
+            return;
+        }
+        setImageLoaded(false);
+        const img = new Image();
+        img.onload = () => {
+            setImageLoaded(true);
+        };
+        img.onerror = () => {
+            setImageLoaded(false);
+        };
+        img.src = imageUrl;
+        return () => {
+            img.onload = null;
+            img.onerror = null;
+        };
+    }, [imageUrl]);
+    return imageLoaded;
+}

package/lib/{panelview/story-maps → features/story}/hooks/useStoryMap.d.ts

@@ -1,5 +1,5 @@
 import type { IJGISLayer, IJGISStoryMap, IJupyterGISModel } from '@jupytergis/schema';
-import { CSSProperties, RefObject } from 'react';
+import { RefObject } from 'react';
 /** Entry for a layer affected by layer override
  * remove if we added a layer or restore if we modified an existing layer.
  **/
@@ -13,12 +13,8 @@ export interface IUseStoryMapParams {
     removeLayer?: (id: string) => void;
     addLayer?: (id: string, layer: IJGISLayer, index: number) => Promise<void>;
     isSpecta: boolean;
-    /** Panel root element for applying specta presentation CSS variables. */
-    panelRef?: RefObject<HTMLDivElement | null>;
 }
-/** Inline style for specta presentation (bg and text color from story). */
-export declare function getSpectaPresentationStyle(story: IJGISStoryMap | null): CSSProperties;
-export declare function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLayer, panelRef, isSpecta, }: IUseStoryMapParams): {
+export declare function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLayer, isSpecta, }: IUseStoryMapParams): {
     storyData: IJGISStoryMap | null;
     storySegments: IJGISLayer[];
     currentIndex: number;
@@ -36,5 +32,4 @@ export declare function useStoryMap({ model, overrideLayerEntriesRef, removeLaye
     } | undefined;
     layerName: string;
     currentStorySegmentId: string | undefined;
-    zoomToCurrentLayer: () => void;
 };

package/lib/{panelview/story-maps → features/story}/hooks/useStoryMap.js

@@ -1,22 +1,8 @@
 import { UUID } from '@lumino/coreutils';
-import { useCallback, useEffect, useMemo, useState, } from 'react';
-/** Inline style for specta presentation (bg and text color from story). */
-export function getSpectaPresentationStyle(story) {
-    const bgColor = story === null || story === void 0 ? void 0 : story.presentationBgColor;
-    const textColor = story === null || story === void 0 ? void 0 : story.presentationTextColor;
-    const style = {};
-    if (bgColor) {
-        style['--jgis-specta-bg-color'] = bgColor;
-        style.backgroundColor = bgColor;
-    }
-    if (textColor) {
-        style['--jgis-specta-text-color'] = textColor;
-        style.color = textColor;
-    }
-    return style;
-}
-export function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLayer, panelRef, isSpecta, }) {
-    var _a;
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { STORY_TYPE } from "../../../types";
+export function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLayer, isSpecta, }) {
+    var _a, _b;
     const [currentIndex, setCurrentIndex] = useState(() => { var _a; return (_a = model.getCurrentSegmentIndex()) !== null && _a !== void 0 ? _a : 0; });
     const [storyData, setStoryData] = useState(() => { var _a; return (_a = model.getSelectedStory().story) !== null && _a !== void 0 ? _a : null; });
     const storySegments = useMemo(() => {
@@ -33,7 +19,9 @@ export function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLa
     const activeSlide = useMemo(() => currentStorySegment === null || currentStorySegment === void 0 ? void 0 : currentStorySegment.parameters, [currentStorySegment]);
     const layerName = useMemo(() => { var _a; return (_a = currentStorySegment === null || currentStorySegment === void 0 ? void 0 : currentStorySegment.name) !== null && _a !== void 0 ? _a : ''; }, [currentStorySegment]);
     const currentStorySegmentId = useMemo(() => storySegmentIds === null || storySegmentIds === void 0 ? void 0 : storySegmentIds[currentIndex], [storySegmentIds, currentIndex]);
-    const showGradient = (_a = storyData === null || storyData === void 0 ? void 0 : storyData.showGradient) !== null && _a !== void 0 ? _a : true;
+    const currentSegmentContentMode = (_a = activeSlide === null || activeSlide === void 0 ? void 0 : activeSlide.content) === null || _a === void 0 ? void 0 : _a.contentMode;
+    const showGradient = (_b = storyData === null || storyData === void 0 ? void 0 : storyData.showGradient) !== null && _b !== void 0 ? _b : true;
+    const isGuidedStory = (storyData === null || storyData === void 0 ? void 0 : storyData.storyType) === STORY_TYPE.guided;
     const hasPrev = currentIndex > 0;
     const hasNext = currentIndex < segmentCount - 1;
     const clearOverrideLayers = useCallback(() => {
@@ -54,11 +42,6 @@ export function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLa
         });
         entries.length = 0;
     }, [model, overrideLayerEntriesRef, removeLayer]);
-    const zoomToCurrentLayer = useCallback(() => {
-        if (currentStorySegmentId) {
-            model.centerOnPosition(currentStorySegmentId);
-        }
-    }, [model, currentStorySegmentId]);
     const setIndex = useCallback((index) => {
         model.setCurrentSegmentIndex(index);
     }, [model]);
@@ -196,44 +179,38 @@ export function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLa
         };
     }, []);
     useEffect(() => {
-        if (currentStorySegmentId) {
-            zoomToCurrentLayer();
+        if (!currentStorySegmentId) {
+            return;
         }
-    }, [currentStorySegmentId, zoomToCurrentLayer]);
+        if (currentSegmentContentMode === 'markdown') {
+            return;
+        }
+        model.centerOnPosition(currentStorySegmentId);
+    }, [model, currentStorySegmentId, currentSegmentContentMode]);
     // Set selected layer and apply symbology when segment changes; remove previous segment's override layers first.
     useEffect(() => {
         if (!(storyData === null || storyData === void 0 ? void 0 : storyData.storySegments) || currentIndex < 0) {
             return;
         }
         clearOverrideLayers();
-        setSelectedLayerByIndex(currentIndex);
+        if (isGuidedStory) {
+            setSelectedLayerByIndex(currentIndex);
+        }
         overrideSymbology(currentIndex);
     }, [
         storyData,
         currentIndex,
+        isGuidedStory,
         setSelectedLayerByIndex,
         clearOverrideLayers,
         overrideSymbology,
     ]);
     // Set selected layer on initial render and when story data changes
     useEffect(() => {
-        if ((storyData === null || storyData === void 0 ? void 0 : storyData.storySegments) && currentIndex >= 0) {
+        if (isGuidedStory && (storyData === null || storyData === void 0 ? void 0 : storyData.storySegments) && currentIndex >= 0) {
             setSelectedLayerByIndex(currentIndex);
         }
-    }, [storyData, currentIndex, setSelectedLayerByIndex]);
-    // Apply story presentation colors (specta) to panel root
-    useEffect(() => {
-        if (!isSpecta || !(panelRef === null || panelRef === void 0 ? void 0 : panelRef.current)) {
-            return;
-        }
-        const container = panelRef.current;
-        const style = getSpectaPresentationStyle(storyData);
-        Object.entries(style).forEach(([key, value]) => {
-            if (value !== null) {
-                container.style.setProperty(key, String(value));
-            }
-        });
-    }, [storyData, isSpecta, panelRef]);
+    }, [storyData, currentIndex, isGuidedStory, setSelectedLayerByIndex]);
     return {
         storyData,
         storySegments,
@@ -250,6 +227,5 @@ export function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLa
         activeSlide,
         layerName,
         currentStorySegmentId,
-        zoomToCurrentLayer,
     };
 }

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

@@ -0,0 +1,21 @@
+import { RefObject } from 'react';
+/**
+ * Specta story column scroll container + optional sentinel tracking.
+ * - `scrollContainerRef`: list + single attach here (`#jgis-story-segment-panel`).
+ * - With `sentinelsEnabled: false` (list mode), only the ref is used.
+ * - `getAtTop` / `getAtBottom`: guided/unguided wheel edges (single mode).
+ */
+interface IUseStoryScrollStateParams {
+    currentIndex: number;
+    /** When false, only exposes scrollContainerRef (list story virtual track). */
+    sentinelsEnabled?: boolean;
+}
+interface IUseStoryScrollStateResult {
+    scrollContainerRef: RefObject<HTMLDivElement>;
+    topSentinelRef: RefObject<HTMLDivElement>;
+    bottomSentinelRef: RefObject<HTMLDivElement>;
+    getAtTop: () => boolean;
+    getAtBottom: () => boolean;
+}
+export declare function useStoryScrollState({ currentIndex, sentinelsEnabled, }: IUseStoryScrollStateParams): IUseStoryScrollStateResult;
+export {};

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

@@ -0,0 +1,39 @@
+import { useEffect, useRef } from 'react';
+export function useStoryScrollState({ currentIndex, sentinelsEnabled = true, }) {
+    const scrollContainerRef = useRef(null);
+    const topSentinelRef = useRef(null);
+    const bottomSentinelRef = useRef(null);
+    const atTopRef = useRef(false);
+    const atBottomRef = useRef(false);
+    useEffect(() => {
+        if (!sentinelsEnabled) {
+            return;
+        }
+        const root = scrollContainerRef.current;
+        const topEl = topSentinelRef.current;
+        const bottomEl = bottomSentinelRef.current;
+        if (!root || !topEl || !bottomEl) {
+            return;
+        }
+        const observer = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.target === topEl) {
+                    atTopRef.current = entry.isIntersecting;
+                }
+                else if (entry.target === bottomEl) {
+                    atBottomRef.current = entry.isIntersecting;
+                }
+            }
+        }, { root, threshold: 0, rootMargin: '0px' });
+        observer.observe(topEl);
+        observer.observe(bottomEl);
+        return () => observer.disconnect();
+    }, [currentIndex, sentinelsEnabled]);
+    return {
+        scrollContainerRef,
+        topSentinelRef,
+        bottomSentinelRef,
+        getAtTop: () => atTopRef.current,
+        getAtBottom: () => atBottomRef.current,
+    };
+}

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

@@ -0,0 +1,8 @@
+import { IJGISStoryMap, IJupyterGISModel } from '@jupytergis/schema';
+interface IUseStorySegmentSyncParams {
+    model: IJupyterGISModel;
+    storyData: IJGISStoryMap | null;
+    setIndex: (index: number) => void;
+}
+export declare function useStorySegmentSync({ model, storyData, setIndex, }: IUseStorySegmentSyncParams): void;
+export {};

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

@@ -0,0 +1,51 @@
+import { useEffect } from 'react';
+import { STORY_TYPE } from "../../../types";
+function getSingleSelectedLayerId(selected) {
+    if (!selected) {
+        return null;
+    }
+    const selectedLayerIds = Object.keys(selected);
+    if (selectedLayerIds.length !== 1) {
+        return null;
+    }
+    return selectedLayerIds[0];
+}
+function getStorySegmentIndexFromLayerId(storyData, selectedLayerId) {
+    var _a;
+    const index = (_a = storyData.storySegments) === null || _a === void 0 ? void 0 : _a.indexOf(selectedLayerId);
+    if (index === undefined || index === -1) {
+        return null;
+    }
+    return index;
+}
+// This hook just syncs the active segment with the currently selected segment
+// Only for unguided mode
+export function useStorySegmentSync({ model, storyData, setIndex, }) {
+    useEffect(() => {
+        const handleSelectedStorySegmentChanged = () => {
+            var _a, _b;
+            if (!storyData || storyData.storyType !== STORY_TYPE.unguided) {
+                return;
+            }
+            const selected = (_b = (_a = model.localState) === null || _a === void 0 ? void 0 : _a.selected) === null || _b === void 0 ? void 0 : _b.value;
+            const selectedLayerId = getSingleSelectedLayerId(selected);
+            if (!selectedLayerId) {
+                return;
+            }
+            const selectedLayer = model.getLayer(selectedLayerId);
+            if (!selectedLayer || selectedLayer.type !== 'StorySegmentLayer') {
+                return;
+            }
+            const index = getStorySegmentIndexFromLayerId(storyData, selectedLayerId);
+            if (index === null) {
+                return;
+            }
+            setIndex(index);
+        };
+        model.selectedChanged.connect(handleSelectedStorySegmentChanged);
+        handleSelectedStorySegmentChanged();
+        return () => {
+            model.selectedChanged.disconnect(handleSelectedStorySegmentChanged);
+        };
+    }, [model, storyData, setIndex]);
+}