@jupytergis/base 0.15.0 → 0.16.0-alpha.1

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,7 @@
-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 +18,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 +41,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]);
@@ -94,7 +76,7 @@ export function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLa
             return;
         }
         layerOverrides.forEach(override => {
-            var _a, _b, _c, _d;
+            var _a, _b, _c;
             const { color, opacity, sourceProperties, symbologyState, targetLayer: targetLayerId, visible, } = override;
             if (!targetLayerId) {
                 return;
@@ -135,20 +117,6 @@ export function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLa
                         model.triggerLayerUpdate(sourceId, source);
                     }
                 }
-                if ((symbologyState === null || symbologyState === void 0 ? void 0 : symbologyState.renderType) === 'Heatmap') {
-                    targetLayer.type = 'HeatmapLayer';
-                    if (addLayer) {
-                        const newId = UUID.uuid4();
-                        addLayer(newId, targetLayer, 100);
-                        (_d = overrideLayerEntriesRef.current) === null || _d === void 0 ? void 0 : _d.push({
-                            layerId: newId,
-                            action: 'remove',
-                        });
-                    }
-                }
-                else {
-                    model.triggerLayerUpdate(targetLayerId, targetLayer);
-                }
             }
         });
     }, [addLayer, model, storySegments, overrideLayerEntriesRef]);
@@ -196,44 +164,38 @@ export function useStoryMap({ model, overrideLayerEntriesRef, removeLayer, addLa
         };
     }, []);
     useEffect(() => {
-        if (currentStorySegmentId) {
-            zoomToCurrentLayer();
+        if (!currentStorySegmentId) {
+            return;
+        }
+        if (currentSegmentContentMode === 'markdown') {
+            return;
         }
-    }, [currentStorySegmentId, zoomToCurrentLayer]);
+        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 +212,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]);
+}

package/lib/features/story/types/types.d.ts

@@ -0,0 +1,43 @@
+import type { IStorySegmentLayer } from '@jupytergis/schema';
+export type StorySegmentDisplayMode = 'map' | 'markdown';
+/** Active handoff between two segments while scrolling the virtual track. */
+export interface IListStorySegmentTransition {
+    /** 0–1 across the handoff span (outgoing segment + gap + incoming segment). */
+    progress: number;
+    fromIndex: number;
+    toIndex: number;
+    fromMode: StorySegmentDisplayMode;
+    toMode: StorySegmentDisplayMode;
+}
+export interface IStorySegmentViewItem {
+    id: string;
+    index: number;
+    layerName: string;
+    activeSlide: IStorySegmentLayer['parameters'] | undefined;
+}
+export interface IListStoryTitleBarContentProps {
+    segmentItems: IStorySegmentViewItem[];
+    currentIndex: number;
+    onSegmentClick: (index: number) => void;
+}
+export interface IListStoryMarkdownSegment {
+    id: string;
+    index: number;
+    markdown: string;
+}
+export interface IListStoryScrollTrackSegment {
+    id: string;
+    index: number;
+    contentMode: StorySegmentDisplayMode;
+    height: number;
+    measured: boolean;
+    /** Inclusive start in scroller content coordinates. */
+    start: number;
+    /** Exclusive end in scroller content coordinates. */
+    end: number;
+}
+export interface IListStoryScrollTrackLayout {
+    segments: IListStoryScrollTrackSegment[];
+    /** Sum of segment heights and handoff gaps (virtual track height). */
+    scrollTrackHeight: number;
+}

package/lib/features/story/types/types.js

@@ -0,0 +1 @@
+export {};

package/lib/features/story/utils/computeListStoryScrollState.d.ts

@@ -0,0 +1,14 @@
+import type { IListStorySegmentTransition, IListStoryScrollTrackSegment } from "../types/types";
+export interface IListStoryScrollState {
+    activeIndex: number;
+    segmentTransition: IListStorySegmentTransition | null;
+}
+interface IComputeListStoryScrollInput {
+    scrollTop: number;
+    viewportHeight: number;
+    segments: IListStoryScrollTrackSegment[];
+}
+/** Same-segment scroll (from and to pane share content; to pane is the stack tail). */
+export declare function isIntraSegmentScroll(transition: IListStorySegmentTransition | null): boolean;
+export declare function computeListStoryScrollState({ scrollTop, viewportHeight, segments, }: IComputeListStoryScrollInput): IListStoryScrollState | null;
+export {};

package/lib/features/story/utils/computeListStoryScrollState.js

@@ -0,0 +1,79 @@
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}
+/** Same-segment scroll (from and to pane share content; to pane is the stack tail). */
+export function isIntraSegmentScroll(transition) {
+    return transition !== null && transition.fromIndex === transition.toIndex;
+}
+function findSegmentAtScrollTop(scrollTop, segments) {
+    if (scrollTop < segments[0].start) {
+        return segments[0];
+    }
+    for (const segment of segments) {
+        if (scrollTop >= segment.start && scrollTop < segment.end) {
+            return segment;
+        }
+    }
+    return segments[segments.length - 1];
+}
+function buildIntraSegmentScrollState(segment, scrollTop) {
+    const span = segment.end - segment.start;
+    const progress = span > 0 ? clamp01((scrollTop - segment.start) / span) : 0;
+    return {
+        activeIndex: segment.index,
+        segmentTransition: {
+            progress,
+            fromIndex: segment.index,
+            toIndex: segment.index,
+            fromMode: segment.contentMode,
+            toMode: segment.contentMode,
+        },
+    };
+}
+function computePairTransition(scrollTop, fromSegment, toSegment) {
+    if (scrollTop < fromSegment.start || scrollTop >= toSegment.end) {
+        return null;
+    }
+    const handoffEndScrollTop = toSegment.start;
+    const handoffSpan = handoffEndScrollTop - fromSegment.start;
+    if (handoffSpan <= 0) {
+        return null;
+    }
+    if (scrollTop >= handoffEndScrollTop) {
+        return null;
+    }
+    const progress = clamp01((scrollTop - fromSegment.start) / handoffSpan);
+    return {
+        progress,
+        activeIndex: progress >= 0.5 ? toSegment.index : fromSegment.index,
+    };
+}
+function buildSegmentTransitionPayload(fromSegment, toSegment, progress) {
+    return {
+        progress,
+        fromIndex: fromSegment.index,
+        toIndex: toSegment.index,
+        fromMode: fromSegment.contentMode,
+        toMode: toSegment.contentMode,
+    };
+}
+export function computeListStoryScrollState({ scrollTop, viewportHeight, segments, }) {
+    if (!segments.length) {
+        return null;
+    }
+    if (segments.length > 1) {
+        for (let i = 0; i < segments.length - 1; i++) {
+            const fromSegment = segments[i];
+            const toSegment = segments[i + 1];
+            const pairTransition = computePairTransition(scrollTop, fromSegment, toSegment);
+            if (!pairTransition) {
+                continue;
+            }
+            return {
+                activeIndex: pairTransition.activeIndex,
+                segmentTransition: buildSegmentTransitionPayload(fromSegment, toSegment, pairTransition.progress),
+            };
+        }
+    }
+    return buildIntraSegmentScrollState(findSegmentAtScrollTop(scrollTop, segments), scrollTop);
+}

package/lib/features/story/utils/listStoryMeasureQueue.d.ts

@@ -0,0 +1,11 @@
+import type { IListStoryMarkdownSegment } from "../types/types";
+export declare const LIST_STORY_MEASURE_LOOKAHEAD = 2;
+interface IBuildPendingMeasureIdsParams {
+    markdownSegments: IListStoryMarkdownSegment[];
+    currentSegmentIndex: number;
+    heightsById: Readonly<Record<string, number>>;
+    measuringSegmentId: string | undefined;
+}
+/** Markdown segment ids near the active index that still need measurement. */
+export declare function buildPendingMeasureIds({ markdownSegments, currentSegmentIndex, heightsById, measuringSegmentId, }: IBuildPendingMeasureIdsParams): string[];
+export {};

package/lib/features/story/utils/listStoryMeasureQueue.js

@@ -0,0 +1,14 @@
+export const LIST_STORY_MEASURE_LOOKAHEAD = 2;
+/** Markdown segment ids near the active index that still need measurement. */
+export function buildPendingMeasureIds({ markdownSegments, currentSegmentIndex, heightsById, measuringSegmentId, }) {
+    const pending = markdownSegments
+        .filter(segment => Math.abs(segment.index - currentSegmentIndex) <=
+        LIST_STORY_MEASURE_LOOKAHEAD && heightsById[segment.id] === undefined)
+        .sort((a, b) => Math.abs(a.index - currentSegmentIndex) -
+        Math.abs(b.index - currentSegmentIndex))
+        .map(segment => segment.id);
+    if (!measuringSegmentId) {
+        return pending;
+    }
+    return pending.filter(id => id !== measuringSegmentId);
+}

package/lib/features/story/utils/listStoryScrollTrack.d.ts

@@ -0,0 +1,17 @@
+import type { IStorySegmentLayer } from '@jupytergis/schema';
+import type { IListStoryScrollTrackLayout, StorySegmentDisplayMode, IStorySegmentViewItem } from "../types/types";
+interface IBuildListStoryScrollTrackInput {
+    items: IStorySegmentViewItem[];
+    /** Story column scroller height (markdown estimates, scroll padding). */
+    viewportHeight: number;
+    /** Map stage height (`.jGIS-Mainview-Container`); defaults to viewportHeight. */
+    mapViewportHeight?: number;
+    heightsById?: Readonly<Record<string, number>>;
+}
+export declare function estimateMarkdownHeight(markdown: string, viewportHeight: number): number;
+export declare function estimateMapSegmentHeight(viewportHeight: number): number;
+export declare function getScrollTrackSegmentHeight(layout: IListStoryScrollTrackLayout | null, index: number): number | undefined;
+/** Builds cumulative segment ranges for the virtual list story scroll track. */
+export declare function buildListStoryScrollTrack({ items, viewportHeight, mapViewportHeight, heightsById, }: IBuildListStoryScrollTrackInput): IListStoryScrollTrackLayout | null;
+export declare function getSegmentDisplayMode(activeSlide: IStorySegmentLayer['parameters'] | undefined): StorySegmentDisplayMode;
+export {};

package/lib/features/story/utils/listStoryScrollTrack.js

@@ -0,0 +1,72 @@
+const MARKDOWN_LINE_HEIGHT_PX = 28;
+const MARKDOWN_CONTENT_PADDING_PX = 32;
+const MIN_MARKDOWN_VIEWPORT_RATIO = 0.5;
+export function estimateMarkdownHeight(markdown, viewportHeight) {
+    const lineCount = Math.max(1, markdown.split('\n').length);
+    const estimatedFromLines = lineCount * MARKDOWN_LINE_HEIGHT_PX + MARKDOWN_CONTENT_PADDING_PX;
+    const minHeight = viewportHeight * MIN_MARKDOWN_VIEWPORT_RATIO;
+    return Math.max(minHeight, estimatedFromLines);
+}
+export function estimateMapSegmentHeight(viewportHeight) {
+    return viewportHeight;
+}
+export function getScrollTrackSegmentHeight(layout, index) {
+    var _a;
+    return (_a = layout === null || layout === void 0 ? void 0 : layout.segments.find(segment => segment.index === index)) === null || _a === void 0 ? void 0 : _a.height;
+}
+function segmentHeightForItem(item, viewportHeight, mapViewportHeight, heightsById) {
+    var _a, _b, _c;
+    const mode = getSegmentDisplayMode(item.activeSlide);
+    if (mode === 'map') {
+        return {
+            height: estimateMapSegmentHeight(mapViewportHeight),
+            measured: mapViewportHeight > 0,
+        };
+    }
+    const measured = heightsById[item.id];
+    if (measured !== undefined && measured > 0) {
+        return { height: measured, measured: true };
+    }
+    const markdown = (_c = (_b = (_a = item.activeSlide) === null || _a === void 0 ? void 0 : _a.content) === null || _b === void 0 ? void 0 : _b.markdown) !== null && _c !== void 0 ? _c : '';
+    return {
+        height: estimateMarkdownHeight(typeof markdown === 'string' ? markdown : '', viewportHeight),
+        measured: false,
+    };
+}
+/** Builds cumulative segment ranges for the virtual list story scroll track. */
+export function buildListStoryScrollTrack({ items, viewportHeight, mapViewportHeight, heightsById = {}, }) {
+    if (!items.length || viewportHeight <= 0) {
+        return null;
+    }
+    const mapHeight = mapViewportHeight !== null && mapViewportHeight !== void 0 ? mapViewportHeight : viewportHeight;
+    const heights = items.map(item => segmentHeightForItem(item, viewportHeight, mapHeight, heightsById));
+    const handoffGap = mapHeight;
+    let offset = 0;
+    const segments = items.map((item, i) => {
+        const start = offset;
+        const height = heights[i].height;
+        const gapAfter = i < items.length - 1 ? handoffGap : 0;
+        const end = start + height + gapAfter;
+        offset = end;
+        return {
+            id: item.id,
+            index: item.index,
+            contentMode: getSegmentDisplayMode(item.activeSlide),
+            height,
+            measured: heights[i].measured,
+            start,
+            end,
+        };
+    });
+    return {
+        segments,
+        scrollTrackHeight: offset,
+    };
+}
+export function getSegmentDisplayMode(activeSlide) {
+    var _a;
+    if (((_a = activeSlide === null || activeSlide === void 0 ? void 0 : activeSlide.content) === null || _a === void 0 ? void 0 : _a.contentMode) === 'markdown') {
+        return 'markdown';
+    }
+    return 'map';
+}

package/lib/features/story/utils/spectaPresentation.d.ts

@@ -0,0 +1,9 @@
+import type { IJGISStoryMap } from '@jupytergis/schema';
+import type { CSSProperties } from 'react';
+/** CSS variables (+ optional text color) for specta theming */
+export declare function getSpectaPresentationCssVars(story: IJGISStoryMap | null): CSSProperties;
+/**
+ * Full inline style for solid surfaces (e.g. mobile drawer).
+ * Do not use on `.jgis-specta-story-panel-container` — it overrides the gradient.
+ */
+export declare function getSpectaPresentationStyle(story: IJGISStoryMap | null): CSSProperties;