@jupytergis/base 0.14.1 → 0.16.0-alpha.0

package/lib/{stacBrowser → features/stac-browser}/hooks/useStacFilterExtension.js

@@ -10,13 +10,15 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 import { endOfToday, startOfToday } from 'date-fns';
-import { useCallback, useEffect, useState } from 'react';
-import useIsFirstRender from "../../shared/hooks/useIsFirstRender";
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { useStacResultsContext } from "../context/StacResultsContext";
 import { useStacSearch } from "./useStacSearch";
-import { GlobalStateDbManager } from "../../store";
-import { fetchWithProxies } from "../../tools";
+import useIsFirstRender from "../../../shared/hooks/useIsFirstRender";
+import { GlobalStateDbManager } from "../../../shared/store";
+import { fetchWithProxies } from "../../../tools";
 const STAC_FILTER_EXTENSION_STATE_KEY = 'jupytergis:stac-filter-extension-state';
+const STAC_COLLECTIONS_CACHE_STATE_KEY = 'jupytergis:stac-collections-cache';
+const STAC_QUERYABLES_CACHE_STATE_KEY = 'jupytergis:stac-queryables-cache';
 /**
  * Hook for searching STAC catalogs that support the Filter Extension (CQL2-JSON).
  * Fetches collections and queryables, and builds filter queries using the STAC Filter Extension.
@@ -25,7 +27,7 @@ export function useStacFilterExtension({ model, baseUrl, limit = 12, }) {
     const isFirstRender = useIsFirstRender();
     const { registerBuildQuery, executeQuery } = useStacResultsContext();
     // Get temporal/spatial filters from useStacSearch
-    const { startTime, endTime, setStartTime, setEndTime, currentBBox, useWorldBBox, setUseWorldBBox, } = useStacSearch({
+    const { startTime, endTime, setStartTime, setEndTime, currentBBox, useWorldBBox, setUseWorldBBox, hasLoadedInitialSearchState, } = useStacSearch({
         model,
     });
     const [queryableFields, setQueryableFields] = useState();
@@ -33,30 +35,132 @@ export function useStacFilterExtension({ model, baseUrl, limit = 12, }) {
     const [selectedCollection, setSelectedCollection] = useState('');
     const [selectedQueryables, setSelectedQueryables] = useState({});
     const [filterOperator, setFilterOperator] = useState('and');
+    const hasLoadedInitialFilterStateRef = useRef(false);
+    const hasLoadedInitialQueryablesRef = useRef(false);
+    /** Last auto-search request; skips duplicate consecutive fetches (React churn). */
+    const lastAutoQueryKeyRef = useRef(null);
     const stateDb = GlobalStateDbManager.getInstance().getStateDb();
+    const getCollectionsCacheKey = useCallback(() => `${STAC_COLLECTIONS_CACHE_STATE_KEY}:${baseUrl}`, [baseUrl]);
+    const getQueryablesCacheKey = useCallback(() => `${STAC_QUERYABLES_CACHE_STATE_KEY}:${baseUrl}:${selectedCollection}`, [baseUrl, selectedCollection]);
+    const updateSelectedQueryables = useCallback((qKey, filter) => {
+        setSelectedQueryables(prev => {
+            // If filter is null, remove the key entirely
+            if (filter === null) {
+                const _a = prev, _b = qKey, _ = _a[_b], rest = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+                return rest;
+            }
+            // If inputValue is undefined but filter exists, keep it (user might be
+            // entering value). Only remove if explicitly set to null.
+            return Object.assign(Object.assign({}, prev), { [qKey]: filter });
+        });
+    }, []);
+    const handleSelectedCollectionChange = useCallback((nextSelectedCollection) => {
+        if (selectedCollection !== '' &&
+            nextSelectedCollection !== '' &&
+            selectedCollection !== nextSelectedCollection) {
+            setSelectedQueryables({});
+            setQueryableFields(undefined);
+            setFilterOperator('and');
+        }
+        setSelectedCollection(nextSelectedCollection);
+    }, [selectedCollection]);
+    const buildQuery = useCallback(() => {
+        const st = startTime
+            ? startTime.toISOString()
+            : startOfToday().toISOString();
+        const et = endTime ? endTime.toISOString() : endOfToday().toISOString();
+        // Build filter object from selectedQueryables
+        const filterConditions = Object.entries(selectedQueryables)
+            .filter(([, filter]) => filter.inputValue !== undefined)
+            .map(([property, filter]) => {
+            var _a, _b;
+            // Check if this property is a datetime type
+            const queryableField = queryableFields === null || queryableFields === void 0 ? void 0 : queryableFields.find(([key]) => key === property);
+            const isDateTime = queryableField &&
+                ((_a = queryableField[1]) === null || _a === void 0 ? void 0 : _a.type) === 'string' &&
+                ((_b = queryableField[1]) === null || _b === void 0 ? void 0 : _b.format) === 'date-time';
+            // For datetime values, wrap in timestamp object; otherwise use value directly
+            const value = isDateTime
+                ? { timestamp: filter.inputValue }
+                : filter.inputValue;
+            const condition = {
+                op: filter.operator,
+                args: [{ property }, value],
+            };
+            return condition;
+        });
+        const body = {
+            bbox: currentBBox,
+            collections: [selectedCollection],
+            datetime: `${st}/${et}`,
+            limit,
+            'filter-lang': 'cql2-json',
+        };
+        // Only add filter if there are any conditions
+        if (filterConditions.length > 0) {
+            body.filter = {
+                op: filterOperator,
+                args: filterConditions,
+            };
+        }
+        return body;
+    }, [
+        startTime,
+        endTime,
+        currentBBox,
+        selectedCollection,
+        limit,
+        selectedQueryables,
+        filterOperator,
+        queryableFields,
+    ]);
+    // Register buildQuery with context
+    useEffect(() => {
+        registerBuildQuery(() => buildQuery());
+    }, [registerBuildQuery, buildQuery, baseUrl]);
+    const handleSubmit = useCallback(async () => {
+        if (!model) {
+            return;
+        }
+        // Build query body and execute query
+        const queryBody = buildQuery();
+        const searchUrl = baseUrl.endsWith('/')
+            ? `${baseUrl}search`
+            : `${baseUrl}/search`;
+        lastAutoQueryKeyRef.current = JSON.stringify({
+            searchUrl,
+            queryBody,
+        });
+        await executeQuery(queryBody, searchUrl);
+    }, [model, buildQuery, baseUrl]);
     // On mount, load saved filter state from StateDB (if present)
     useEffect(() => {
         async function loadFilterExtensionStateFromDb() {
-            const savedFilterState = (await (stateDb === null || stateDb === void 0 ? void 0 : stateDb.fetch(STAC_FILTER_EXTENSION_STATE_KEY)));
-            if (savedFilterState) {
-                if (savedFilterState.selectedCollection) {
-                    setSelectedCollection(savedFilterState.selectedCollection);
-                }
-                if (savedFilterState.queryableFilters) {
-                    // Convert null back to undefined for inputValue
-                    const restoredFilters = {};
-                    Object.entries(savedFilterState.queryableFilters).forEach(([key, filter]) => {
-                        restoredFilters[key] = {
-                            operator: filter.operator,
-                            inputValue: filter.inputValue === null ? undefined : filter.inputValue,
-                        };
-                    });
-                    setSelectedQueryables(restoredFilters);
-                }
-                if (savedFilterState.filterOperator) {
-                    setFilterOperator(savedFilterState.filterOperator);
+            hasLoadedInitialFilterStateRef.current = false;
+            try {
+                const savedFilterState = (await (stateDb === null || stateDb === void 0 ? void 0 : stateDb.fetch(STAC_FILTER_EXTENSION_STATE_KEY)));
+                if (savedFilterState) {
+                    if (savedFilterState.selectedCollection) {
+                        handleSelectedCollectionChange(savedFilterState.selectedCollection);
+                    }
+                    if (savedFilterState.queryableFilters) {
+                        const restoredFilters = {};
+                        Object.entries(savedFilterState.queryableFilters).forEach(([key, filter]) => {
+                            restoredFilters[key] = {
+                                operator: filter.operator,
+                                inputValue: filter.inputValue === null ? undefined : filter.inputValue,
+                            };
+                        });
+                        setSelectedQueryables(restoredFilters);
+                    }
+                    if (savedFilterState.filterOperator) {
+                        setFilterOperator(savedFilterState.filterOperator);
+                    }
                 }
             }
+            finally {
+                hasLoadedInitialFilterStateRef.current = true;
+            }
         }
         loadFilterExtensionStateFromDb();
     }, [stateDb]);
@@ -84,6 +188,8 @@ export function useStacFilterExtension({ model, baseUrl, limit = 12, }) {
     }, [selectedCollection, selectedQueryables, filterOperator, stateDb]);
     // Reset all state when URL changes
     useEffect(() => {
+        lastAutoQueryKeyRef.current = null;
+        hasLoadedInitialQueryablesRef.current = false;
         setQueryableFields(undefined);
         setCollections([]);
         setSelectedCollection('');
@@ -96,14 +202,37 @@ export function useStacFilterExtension({ model, baseUrl, limit = 12, }) {
             return;
         }
         const fetchCollections = async () => {
+            var _a;
             if (!baseUrl) {
                 return;
             }
+            const cachedCollections = (await (stateDb === null || stateDb === void 0 ? void 0 : stateDb.fetch(getCollectionsCacheKey())));
+            if (cachedCollections && cachedCollections.length > 0) {
+                setCollections(cachedCollections);
+                if (hasLoadedInitialQueryablesRef.current &&
+                    selectedCollection === '') {
+                    handleSelectedCollectionChange(cachedCollections[0].id);
+                }
+                return;
+            }
             const collectionsUrl = baseUrl.endsWith('/')
                 ? `${baseUrl}collections`
                 : `${baseUrl}/collections`;
-            const data = await fetchWithProxies(collectionsUrl, model, async (response) => await response.json(), undefined);
-            const collections = data.collections
+            const allCollections = [];
+            let nextUrl = collectionsUrl;
+            while (nextUrl) {
+                const page = await fetchWithProxies(nextUrl, model, async (response) => await response.json(), undefined);
+                if (!page) {
+                    break;
+                }
+                allCollections.push(...page.collections);
+                const currentPageUrl = nextUrl;
+                const nextLinkHref = (_a = page.links.find(link => link.rel === 'next')) === null || _a === void 0 ? void 0 : _a.href;
+                nextUrl = nextLinkHref
+                    ? new URL(nextLinkHref, currentPageUrl).toString()
+                    : null;
+            }
+            const collections = allCollections
                 .map((collection) => {
                 var _a;
                 return ({
@@ -118,13 +247,23 @@ export function useStacFilterExtension({ model, baseUrl, limit = 12, }) {
                 return titleA.localeCompare(titleB);
             });
             setCollections(collections);
+            await (stateDb === null || stateDb === void 0 ? void 0 : stateDb.save(getCollectionsCacheKey(), collections));
             // Set first collection as default if one isn't loaded
-            if (collections.length > 0 && !(selectedCollection === '')) {
-                setSelectedCollection(collections[0].id);
+            if (hasLoadedInitialQueryablesRef.current &&
+                collections.length > 0 &&
+                !(selectedCollection === '')) {
+                handleSelectedCollectionChange(collections[0].id);
             }
         };
         fetchCollections();
-    }, [model, baseUrl]);
+    }, [
+        model,
+        baseUrl,
+        stateDb,
+        selectedCollection,
+        getCollectionsCacheKey,
+        handleSelectedCollectionChange,
+    ]);
     // for queryables
     // ! TODO - support multiple collection selections
     useEffect(() => {
@@ -132,102 +271,46 @@ export function useStacFilterExtension({ model, baseUrl, limit = 12, }) {
             return;
         }
         const fetchQueryables = async () => {
-            if (!baseUrl) {
+            if (!baseUrl || selectedCollection === '') {
+                return;
+            }
+            hasLoadedInitialQueryablesRef.current = false;
+            const cachedQueryables = (await (stateDb === null || stateDb === void 0 ? void 0 : stateDb.fetch(getQueryablesCacheKey())));
+            if (cachedQueryables !== undefined) {
+                setQueryableFields(Object.entries(cachedQueryables));
+                hasLoadedInitialQueryablesRef.current = true;
                 return;
             }
             const queryablesUrl = baseUrl.endsWith('/')
-                ? `${baseUrl}queryables`
-                : `${baseUrl}/queryables`;
+                ? `${baseUrl}collections/${encodeURIComponent(selectedCollection)}/queryables`
+                : `${baseUrl}/collections/${encodeURIComponent(selectedCollection)}/queryables`;
             const data = await fetchWithProxies(queryablesUrl, model, async (response) => await response.json(), undefined);
-            setQueryableFields(Object.entries(data.properties));
+            const queryableProperties = data.properties;
+            setQueryableFields(Object.entries(queryableProperties));
+            await (stateDb === null || stateDb === void 0 ? void 0 : stateDb.save(getQueryablesCacheKey(), queryableProperties));
+            hasLoadedInitialQueryablesRef.current = true;
         };
         fetchQueryables();
-    }, [model, baseUrl]);
-    const updateSelectedQueryables = useCallback((qKey, filter) => {
-        setSelectedQueryables(prev => {
-            // If filter is null, remove the key entirely
-            if (filter === null) {
-                const _a = prev, _b = qKey, _ = _a[_b], rest = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
-                return rest;
-            }
-            // If inputValue is undefined but filter exists, keep it (user might be entering value)
-            // Only remove if explicitly set to null
-            return Object.assign(Object.assign({}, prev), { [qKey]: filter });
-        });
-    }, []);
-    const buildQuery = useCallback(() => {
-        const st = startTime
-            ? startTime.toISOString()
-            : startOfToday().toISOString();
-        const et = endTime ? endTime.toISOString() : endOfToday().toISOString();
-        // Build filter object from selectedQueryables
-        const filterConditions = Object.entries(selectedQueryables)
-            .filter(([, filter]) => filter.inputValue !== undefined)
-            .map(([property, filter]) => {
-            var _a, _b;
-            // Check if this property is a datetime type
-            const queryableField = queryableFields === null || queryableFields === void 0 ? void 0 : queryableFields.find(([key]) => key === property);
-            const isDateTime = queryableField &&
-                ((_a = queryableField[1]) === null || _a === void 0 ? void 0 : _a.type) === 'string' &&
-                ((_b = queryableField[1]) === null || _b === void 0 ? void 0 : _b.format) === 'date-time';
-            // For datetime values, wrap in timestamp object; otherwise use value directly
-            const value = isDateTime
-                ? { timestamp: filter.inputValue }
-                : filter.inputValue;
-            const condition = {
-                op: filter.operator,
-                args: [{ property }, value],
-            };
-            return condition;
-        });
-        const body = {
-            bbox: currentBBox,
-            collections: [selectedCollection],
-            datetime: `${st}/${et}`,
-            limit,
-            'filter-lang': 'cql2-json',
-        };
-        // Only add filter if there are any conditions
-        if (filterConditions.length > 0) {
-            body.filter = {
-                op: filterOperator,
-                args: filterConditions,
-            };
-        }
-        return body;
-    }, [
-        startTime,
-        endTime,
-        currentBBox,
-        selectedCollection,
-        limit,
-        selectedQueryables,
-        filterOperator,
-        queryableFields,
-    ]);
-    // Register buildQuery with context
-    useEffect(() => {
-        registerBuildQuery(() => buildQuery());
-    }, [registerBuildQuery, buildQuery, baseUrl]);
-    const handleSubmit = useCallback(async () => {
-        if (!model) {
-            return;
-        }
-        // Build query body and execute query
-        const queryBody = buildQuery();
-        const searchUrl = baseUrl.endsWith('/')
-            ? `${baseUrl}search`
-            : `${baseUrl}/search`;
-        await executeQuery(queryBody, searchUrl);
-    }, [model, executeQuery, buildQuery, baseUrl]);
+    }, [model, baseUrl, selectedCollection, stateDb, getQueryablesCacheKey]);
     // Handle search when filters change
     useEffect(() => {
-        if (model && !isFirstRender && selectedCollection !== '') {
+        const hasLoadedInitialFilterState = hasLoadedInitialFilterStateRef.current &&
+            hasLoadedInitialQueryablesRef.current;
+        if (model &&
+            !isFirstRender &&
+            selectedCollection !== '' &&
+            hasLoadedInitialFilterState &&
+            hasLoadedInitialSearchState) {
             const queryBody = buildQuery();
             const searchUrl = baseUrl.endsWith('/')
                 ? `${baseUrl}search`
                 : `${baseUrl}/search`;
-            executeQuery(queryBody, searchUrl);
+            const autoQueryKey = JSON.stringify({ searchUrl, queryBody });
+            if (lastAutoQueryKeyRef.current === autoQueryKey) {
+                return;
+            }
+            lastAutoQueryKeyRef.current = autoQueryKey;
+            void executeQuery(queryBody, searchUrl);
         }
     }, [
         model,
@@ -235,18 +318,19 @@ export function useStacFilterExtension({ model, baseUrl, limit = 12, }) {
         selectedCollection,
         selectedQueryables,
         filterOperator,
+        queryableFields,
         startTime,
         endTime,
         currentBBox,
         buildQuery,
-        executeQuery,
         baseUrl,
+        hasLoadedInitialSearchState,
     ]);
     return {
         queryableFields,
         collections,
         selectedCollection,
-        setSelectedCollection,
+        setSelectedCollection: handleSelectedCollectionChange,
         handleSubmit,
         startTime,
         endTime,

package/lib/{stacBrowser → features/stac-browser}/hooks/useStacSearch.d.ts

@@ -11,6 +11,7 @@ interface IUseStacSearchReturn {
     setCurrentBBox: (bbox: [number, number, number, number]) => void;
     useWorldBBox: boolean;
     setUseWorldBBox: (val: boolean) => void;
+    hasLoadedInitialSearchState: boolean;
 }
 /**
  * Base hook for managing STAC search - handles temporal/spatial filters

package/lib/{stacBrowser → features/stac-browser}/hooks/useStacSearch.js

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { GlobalStateDbManager } from "../../store";
+import { GlobalStateDbManager } from "../../../shared/store";
 const STAC_SEARCH_STATE_KEY = 'jupytergis:stac-search-state';
 /**
  * Base hook for managing STAC search - handles temporal/spatial filters
@@ -9,22 +9,29 @@ export function useStacSearch({ model, }) {
     const [endTime, setEndTime] = useState(undefined);
     const [currentBBox, setCurrentBBox] = useState([-180, -90, 180, 90]);
     const [useWorldBBox, setUseWorldBBox] = useState(false);
+    const [hasLoadedInitialSearchState, setHasLoadedInitialSearchState] = useState(false);
     const stateDb = GlobalStateDbManager.getInstance().getStateDb();
     // Load saved state from StateDB on mount
     useEffect(() => {
         async function loadStacSearchStateFromDb() {
-            const savedState = (await (stateDb === null || stateDb === void 0 ? void 0 : stateDb.fetch(STAC_SEARCH_STATE_KEY)));
-            if (savedState) {
-                if (savedState.startTime) {
-                    setStartTime(new Date(savedState.startTime));
-                }
-                if (savedState.endTime) {
-                    setEndTime(new Date(savedState.endTime));
-                }
-                if (savedState.useWorldBBox !== undefined) {
-                    setUseWorldBBox(savedState.useWorldBBox);
+            setHasLoadedInitialSearchState(false);
+            try {
+                const savedState = (await (stateDb === null || stateDb === void 0 ? void 0 : stateDb.fetch(STAC_SEARCH_STATE_KEY)));
+                if (savedState) {
+                    if (savedState.startTime) {
+                        setStartTime(new Date(savedState.startTime));
+                    }
+                    if (savedState.endTime) {
+                        setEndTime(new Date(savedState.endTime));
+                    }
+                    if (savedState.useWorldBBox !== undefined) {
+                        setUseWorldBBox(savedState.useWorldBBox);
+                    }
                 }
             }
+            finally {
+                setHasLoadedInitialSearchState(true);
+            }
         }
         loadStacSearchStateFromDb();
     }, [stateDb]);
@@ -63,5 +70,6 @@ export function useStacSearch({ model, }) {
         setCurrentBBox,
         useWorldBBox,
         setUseWorldBBox,
+        hasLoadedInitialSearchState,
     };
 }

package/lib/features/stac-browser/types/types.js

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

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

@@ -1,6 +1,7 @@
 import { IJGISLayer, IJupyterGISModel } from '@jupytergis/schema';
 import React, { RefObject } from 'react';
 import type { IStoryViewerPanelHandle } from './StoryViewerPanel';
+import type { IListStorySegmentTransition } from './types/types';
 interface ISpectaPanelProps {
     model: IJupyterGISModel;
     isSpecta: boolean;
@@ -10,6 +11,8 @@ interface ISpectaPanelProps {
     storyViewerPanelRef: RefObject<IStoryViewerPanelHandle>;
     addLayer?: (id: string, layer: IJGISLayer, index: number) => Promise<void>;
     removeLayer?: (id: string) => void;
+    /** List stories: segment handoff state for the map stage overlay. */
+    onSegmentTransitionChange?: (payload: IListStorySegmentTransition | null) => void;
 }
-export declare function SpectaPanel({ model, isSpecta, isMobile, onSegmentTransitionEnd, containerRef, storyViewerPanelRef, addLayer, removeLayer, }: ISpectaPanelProps): React.JSX.Element;
+export declare function SpectaPanel({ model, isSpecta, isMobile, onSegmentTransitionEnd, containerRef, storyViewerPanelRef, addLayer, removeLayer, onSegmentTransitionChange, }: ISpectaPanelProps): React.JSX.Element;
 export {};

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

@@ -2,7 +2,7 @@ import React, { useEffect, useRef } from 'react';
 import { SpectaDesktopView } from './components/SpectaDesktopView';
 import { SpectaMobileView } from './components/SpectaMobileView';
 import { useStoryMap } from './hooks/useStoryMap';
-export function SpectaPanel({ model, isSpecta, isMobile, onSegmentTransitionEnd, containerRef, storyViewerPanelRef, addLayer, removeLayer, }) {
+export function SpectaPanel({ model, isSpecta, isMobile, onSegmentTransitionEnd, containerRef, storyViewerPanelRef, addLayer, removeLayer, onSegmentTransitionChange, }) {
     const overrideLayerEntriesRef = useRef([]);
     const segmentContainerRef = useRef(null);
     const { storyData, currentIndex, setIndex, handlePrev, handleNext, hasPrev, hasNext, activeSlide, layerName, showGradient, } = useStoryMap({
@@ -10,7 +10,6 @@ export function SpectaPanel({ model, isSpecta, isMobile, onSegmentTransitionEnd,
         overrideLayerEntriesRef,
         removeLayer,
         addLayer,
-        panelRef: isMobile ? undefined : containerRef,
         isSpecta,
     });
     // Notify when segment transition animation ends
@@ -29,7 +28,7 @@ export function SpectaPanel({ model, isSpecta, isMobile, onSegmentTransitionEnd,
         return () => el.removeEventListener('animationend', handleAnimationEnd);
     }, [currentIndex, onSegmentTransitionEnd]);
     if (isMobile) {
-        return (React.createElement(SpectaMobileView, { model: model, segmentContainerRef: segmentContainerRef, storyData: storyData, currentIndex: currentIndex, activeSlide: activeSlide, layerName: layerName, handlePrev: handlePrev, handleNext: handleNext, hasPrev: hasPrev, hasNext: hasNext, setIndex: setIndex }));
+        return (React.createElement(SpectaMobileView, { segmentContainerRef: segmentContainerRef, storyData: storyData, currentIndex: currentIndex, activeSlide: activeSlide, layerName: layerName, handlePrev: handlePrev, handleNext: handleNext, hasPrev: hasPrev, hasNext: hasNext }));
     }
-    return (React.createElement(SpectaDesktopView, { model: model, isSpecta: isSpecta, containerRef: containerRef, storyViewerPanelRef: storyViewerPanelRef, segmentContainerRef: segmentContainerRef, storyData: storyData, currentIndex: currentIndex, activeSlide: activeSlide, layerName: layerName, handlePrev: handlePrev, handleNext: handleNext, hasPrev: hasPrev, hasNext: hasNext, showGradient: showGradient, setIndex: setIndex }));
+    return (React.createElement(SpectaDesktopView, { model: model, isSpecta: isSpecta, containerRef: containerRef, storyViewerPanelRef: storyViewerPanelRef, segmentContainerRef: segmentContainerRef, storyData: storyData, currentIndex: currentIndex, activeSlide: activeSlide, layerName: layerName, handlePrev: handlePrev, handleNext: handleNext, hasPrev: hasPrev, hasNext: hasNext, showGradient: showGradient, setIndex: setIndex, onSegmentTransitionChange: onSegmentTransitionChange }));
 }

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

@@ -3,8 +3,8 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import jgisSchema from '@jupytergis/schema/lib/schema/project/jgis.json';
 import React, { useMemo } from 'react';
 import { CommandIDs } from "../../constants";
-import { StoryEditorPropertiesForm } from "../../formbuilder/objectform/StoryEditorForm";
 import { Button } from "../../shared/components/Button";
+import { StoryEditorPropertiesForm } from "../../shared/formbuilder/objectform/StoryEditorForm";
 import { deepCopy } from "../../tools";
 const storyMapSchema = deepCopy(jgisSchema.definitions.jGISStoryMap);
 const AddStorySegmentButton = ({ model, commands }) => (React.createElement("div", { style: { display: 'flex', justifyContent: 'center' } },

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

@@ -1,8 +1,13 @@
-import { IJGISStoryMap, IJupyterGISModel, IStorySegmentLayer } from '@jupytergis/schema';
+import { IJGISStoryMap, IStorySegmentLayer } from '@jupytergis/schema';
 import React, { RefObject } from 'react';
+export interface IStoryViewerPanelSegmentNav {
+    handlePrev: () => void;
+    handleNext: () => void;
+    hasPrev: boolean;
+    hasNext: boolean;
+}
 /** Props: story state and callbacks come from useStoryMap in parent (SpectaPanel or SpectaMobileView). */
 interface IStoryViewerPanelProps {
-    model: IJupyterGISModel;
     isSpecta: boolean;
     isMobile?: boolean;
     /** Ref for the segment container (SpectaPanel uses it for animationend). */
@@ -11,11 +16,10 @@ interface IStoryViewerPanelProps {
     currentIndex: number;
     activeSlide: IStorySegmentLayer['parameters'] | undefined;
     layerName: string;
-    handlePrev: () => void;
-    handleNext: () => void;
-    hasPrev: boolean;
-    hasNext: boolean;
-    setIndex: (index: number) => void;
+    /** Omit for list-story overlay; required when segment nav is shown. */
+    segmentNav?: IStoryViewerPanelSegmentNav;
+    /** Disable fade animation for list stories. */
+    disableSegmentAnimation?: boolean;
 }
 export interface IStoryViewerPanelHandle {
     handlePrev: () => void;
@@ -40,8 +44,5 @@ export type StoryNavPlacement = 'below-title' | 'over-image' | 'subtitle-specta'
  * Story viewer (presentational). Receives story state and callbacks from parent.
  * Desktop scroll/sentinel/imperative handle live in SpectaDesktopView.
  */
-declare function StoryViewerPanel({ model, isSpecta, isMobile, segmentContainerRef, storyData, currentIndex, activeSlide, layerName, handlePrev, handleNext, hasPrev, hasNext, setIndex, }: IStoryViewerPanelProps): React.JSX.Element;
-declare namespace StoryViewerPanel {
-    var displayName: string;
-}
+declare function StoryViewerPanel({ isSpecta, isMobile, segmentContainerRef, storyData, currentIndex, activeSlide, layerName, segmentNav, disableSegmentAnimation, }: IStoryViewerPanelProps): React.JSX.Element;
 export default StoryViewerPanel;

package/lib/features/story/StoryViewerPanel.js

@@ -0,0 +1,64 @@
+import React from 'react';
+import { STORY_TYPE } from "../../types";
+import StoryContentSection from './components/StoryContentSection';
+import StoryImageSection from './components/StoryImageSection';
+import StoryNavBar from './components/StoryNavBar';
+import StorySubtitleSection from './components/StorySubtitleSection';
+import StoryTitleSection from './components/StoryTitleSection';
+import { useStoryImagePreload } from './hooks/useStoryImagePreload';
+/**
+ * Returns which section should render the nav bar, or null if nav should be hidden.
+ */
+function getStoryNavPlacement(isSpecta, hasImage, storyType, isMobile) {
+    if (storyType === STORY_TYPE.verticalScroll) {
+        return null;
+    }
+    if (storyType === STORY_TYPE.unguided) {
+        return isSpecta && !isMobile ? 'subtitle-specta' : null;
+    }
+    if (storyType === STORY_TYPE.guided) {
+        if (isSpecta) {
+            return isMobile ? null : 'subtitle-specta';
+        }
+        return hasImage ? 'over-image' : 'below-title';
+    }
+    return null;
+}
+/**
+ * Story viewer (presentational). Receives story state and callbacks from parent.
+ * Desktop scroll/sentinel/imperative handle live in SpectaDesktopView.
+ */
+function StoryViewerPanel({ isSpecta, isMobile = false, segmentContainerRef, storyData, currentIndex, activeSlide, layerName, segmentNav, disableSegmentAnimation = false, }) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    const imageLoaded = useStoryImagePreload((_a = activeSlide === null || activeSlide === void 0 ? void 0 : activeSlide.content) === null || _a === void 0 ? void 0 : _a.image);
+    if (!storyData || ((_b = storyData === null || storyData === void 0 ? void 0 : storyData.storySegments) === null || _b === void 0 ? void 0 : _b.length) === 0) {
+        return (React.createElement("div", { style: { padding: '1rem' } },
+            React.createElement("p", null, "No Segments available. Add one using the Add Layer menu.")));
+    }
+    const hasImage = !!(((_c = activeSlide === null || activeSlide === void 0 ? void 0 : activeSlide.content) === null || _c === void 0 ? void 0 : _c.image) && imageLoaded);
+    const storyType = (_d = storyData.storyType) !== null && _d !== void 0 ? _d : STORY_TYPE.guided;
+    const navPlacement = getStoryNavPlacement(isSpecta, hasImage, storyType, isMobile);
+    const navSlot = navPlacement !== null && segmentNav ? (React.createElement(StoryNavBar, { placement: navPlacement, onPrev: segmentNav.handlePrev, onNext: segmentNav.handleNext, hasPrev: segmentNav.hasPrev, hasNext: segmentNav.hasNext })) : null;
+    const transitionTime = (_f = (_e = activeSlide === null || activeSlide === void 0 ? void 0 : activeSlide.transition) === null || _e === void 0 ? void 0 : _e.time) !== null && _f !== void 0 ? _f : 0.3;
+    const segmentAnimationEnabled = !disableSegmentAnimation;
+    const segmentContainerKey = segmentAnimationEnabled
+        ? currentIndex
+        : undefined;
+    const segmentContainerClassName = segmentAnimationEnabled
+        ? 'jgis-story-segment-container'
+        : 'jgis-story-segment-container jgis-story-segment-container--no-segment-animation';
+    const segmentContainerStyle = segmentAnimationEnabled
+        ? { animationDuration: `${transitionTime}s` }
+        : undefined;
+    return (React.createElement("div", { className: storyData.storyType !== STORY_TYPE.verticalScroll
+            ? 'jgis-story-viewer-panel'
+            : '' },
+        React.createElement("div", { ref: segmentContainerRef, key: segmentContainerKey, className: segmentContainerClassName, style: segmentContainerStyle },
+            React.createElement("div", { id: "jgis-story-segment-header" },
+                React.createElement("h1", { className: "jgis-story-viewer-title" }, layerName !== null && layerName !== void 0 ? layerName : `Slide ${currentIndex + 1}`),
+                ((_g = activeSlide === null || activeSlide === void 0 ? void 0 : activeSlide.content) === null || _g === void 0 ? void 0 : _g.image) && imageLoaded ? (React.createElement(StoryImageSection, { imageUrl: activeSlide.content.image, imageLoaded: imageLoaded, layerName: layerName !== null && layerName !== void 0 ? layerName : '', slideNumber: currentIndex, navSlot: navPlacement === 'over-image' ? navSlot : null })) : (React.createElement(StoryTitleSection, { title: (_h = storyData.title) !== null && _h !== void 0 ? _h : '', navSlot: navPlacement === 'below-title' ? navSlot : null })),
+                React.createElement(StorySubtitleSection, { title: (_k = (_j = activeSlide === null || activeSlide === void 0 ? void 0 : activeSlide.content) === null || _j === void 0 ? void 0 : _j.title) !== null && _k !== void 0 ? _k : '', navSlot: navPlacement === 'subtitle-specta' ? navSlot : null })),
+            React.createElement("div", { id: "jgis-story-segment-content" },
+                React.createElement(StoryContentSection, { markdown: (_m = (_l = activeSlide === null || activeSlide === void 0 ? void 0 : activeSlide.content) === null || _l === void 0 ? void 0 : _l.markdown) !== null && _m !== void 0 ? _m : '' })))));
+}
+export default StoryViewerPanel;

package/lib/features/story/__tests__/fixtures/listStoryTestItems.d.ts

@@ -0,0 +1,9 @@
+import { IListStoryScrollTrackSegment, IStorySegmentViewItem } from '../../types/types';
+export declare function storyItem(id: string, index: number, contentMode: 'map' | 'markdown', markdown?: string): IStorySegmentViewItem;
+export interface IListStoryScrollTrackFixtureOptions {
+    items: IStorySegmentViewItem[];
+    viewportHeight: number;
+    mapViewportHeight?: number;
+    heightsById?: Readonly<Record<string, number>>;
+}
+export declare function layoutSegments(options: IListStoryScrollTrackFixtureOptions): IListStoryScrollTrackSegment[];