@redocly/theme 0.55.0-next.2 → 0.55.0-next.3

package/lib/components/Marker/Marker.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { MarkerArea } from '../../core/types';
+type MarkerProps = {
+    marker: MarkerArea;
+    registerMarker: (element: HTMLElement) => void;
+    removeMarker: (element: HTMLElement) => void;
+    dataAttribures?: Record<string, string | boolean | number>;
+};
+export declare const Marker: React.ForwardRefExoticComponent<MarkerProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/lib/components/Marker/Marker.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Marker = void 0;
+const react_1 = __importStar(require("react"));
+const styled_components_1 = __importDefault(require("styled-components"));
+exports.Marker = (0, react_1.forwardRef)(({ marker, dataAttribures, registerMarker, removeMarker }, forwardedRef) => {
+    const internalRef = (0, react_1.useRef)(null);
+    // Reference should be available before paint
+    (0, react_1.useLayoutEffect)(() => {
+        if (!forwardedRef)
+            return;
+        if (typeof forwardedRef === 'function') {
+            forwardedRef(internalRef.current);
+        }
+        else {
+            forwardedRef.current = internalRef.current;
+        }
+    }, [forwardedRef]);
+    (0, react_1.useEffect)(() => {
+        const currentElement = internalRef.current;
+        if (!currentElement)
+            return;
+        registerMarker(currentElement);
+        return () => removeMarker(currentElement);
+    }, [registerMarker, removeMarker, marker]);
+    return (react_1.default.createElement(StyledMarker, Object.assign({ "data-component-name": "Marker/Marker", ref: internalRef, marker: marker }, (dataAttribures !== null && dataAttribures !== void 0 ? dataAttribures : {}))));
+});
+const StyledMarker = styled_components_1.default.div `
+  position: absolute;
+  z-index: -1;
+  top: ${({ marker }) => marker.offset}px;
+  height: ${({ marker }) => marker.height}px;
+  width: 100%;
+  left: 0;
+`;
+//# sourceMappingURL=Marker.js.map

package/lib/core/contexts/CodeWalkthrough/CodeWalkthroughStepsContext.d.ts

@@ -1,2 +1,2 @@
-import type { WalkthroughStepsState } from '../../../core/hooks';
+import type { WalkthroughStepsState } from '../../../core/types';
 export declare const CodeWalkthroughStepsContext: import("react").Context<WalkthroughStepsState>;

package/lib/core/contexts/CodeWalkthrough/CodeWalkthroughStepsContext.js

@@ -3,9 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodeWalkthroughStepsContext = void 0;
 const react_1 = require("react");
 exports.CodeWalkthroughStepsContext = (0, react_1.createContext)({
+    markers: {},
     activeStep: null,
     setActiveStep: () => { },
-    register: () => { },
-    unregister: () => { },
+    registerStep: () => { },
+    registerMarker: () => { },
+    removeMarker: () => { },
+    removeStep: () => { },
 });
 //# sourceMappingURL=CodeWalkthroughStepsContext.js.map

package/lib/core/hooks/code-walkthrough/use-code-walkthrough-steps.d.ts

@@ -1,15 +1,23 @@
 import type { CodeWalkthroughStepAttr } from '@redocly/config';
-type ActiveStep = string | null;
+import type { WalkthroughStepsState } from '../../../core/types';
 type CodeWalkthroughStep = CodeWalkthroughStepAttr & {
     compRef?: HTMLElement;
+    markerRef?: HTMLElement;
 };
-export type WalkthroughStepsState = {
-    activeStep: ActiveStep;
-    setActiveStep: (stepId: ActiveStep) => void;
-    register: (element: HTMLElement) => void;
-    unregister: (element: HTMLElement) => void;
-    lockObserver?: React.RefObject<boolean>;
-    filtersElementRef?: React.RefObject<HTMLDivElement | null>;
+type Params = {
+    steps: CodeWalkthroughStep[];
+    enableDeepLink: boolean;
+    root: React.RefObject<HTMLDivElement | null>;
 };
-export declare function useCodeWalkthroughSteps(steps: CodeWalkthroughStep[], enableDeepLink: boolean): WalkthroughStepsState;
+export declare function useCodeWalkthroughSteps({ steps, enableDeepLink, root, }: Params): WalkthroughStepsState;
+type StepsGroup = {
+    freeSpace: number;
+    usedSpace: number;
+    offset: number;
+    steps: {
+        offset: number;
+        height: number;
+    }[];
+};
+export declare function getGroupMarkers(group: StepsGroup): number[];
 export {};

package/lib/core/hooks/code-walkthrough/use-code-walkthrough-steps.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useCodeWalkthroughSteps = useCodeWalkthroughSteps;
+exports.getGroupMarkers = getGroupMarkers;
 const react_1 = require("react");
 const react_router_dom_1 = require("react-router-dom");
 const utils_1 = require("../../../core/utils");
 const constants_1 = require("../../../core/constants");
-function useCodeWalkthroughSteps(steps, enableDeepLink) {
+function useCodeWalkthroughSteps({ steps, enableDeepLink, root, }) {
     const location = (0, react_router_dom_1.useLocation)();
     const navigate = (0, react_router_dom_1.useNavigate)();
     const searchParams = (0, react_1.useMemo)(() => new URLSearchParams(location.search), [location.search]);
@@ -15,56 +16,122 @@ function useCodeWalkthroughSteps(steps, enableDeepLink) {
     // Track observed elements in case new observer needs to be created
     const observedElementsRef = (0, react_1.useRef)(new Set());
     const [activeStep, setActiveStep] = (0, react_1.useState)(enableDeepLink ? searchParams.get(constants_1.ACTIVE_STEP_QUERY_PARAM) : null);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    const _steps = (0, react_1.useMemo)(() => steps, [JSON.stringify(steps)]);
-    const register = (0, react_1.useCallback)((element) => {
-        // for some reason, the observer is not ready immediately
-        setTimeout(() => {
-            if (observerRef.current) {
-                const stepKey = Number(element.dataset.stepKey);
-                if (Number.isInteger(stepKey) && stepKey >= 0 && _steps[stepKey]) {
-                    _steps[stepKey].compRef = element;
-                }
-                observerRef.current.observe(element);
-                observedElementsRef.current.add(element);
+    const stepsMap = (0, react_1.useMemo)(() => {
+        const map = new Map();
+        steps.forEach((step, index) => {
+            map.set(step.id, Object.assign(Object.assign({}, step), { index }));
+        });
+        return map;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [JSON.stringify(steps)]);
+    const options = (0, react_1.useMemo)(() => {
+        var _a, _b;
+        if (!(0, utils_1.isBrowser)()) {
+            return null;
+        }
+        const filtersElementHeight = ((_a = filtersElementRef.current) === null || _a === void 0 ? void 0 : _a.clientHeight) || 0;
+        const navbarHeight = ((_b = document.querySelector('nav')) === null || _b === void 0 ? void 0 : _b.getBoundingClientRect().height) || 0;
+        return {
+            filtersElementHeight,
+            navbarHeight,
+        };
+    }, []);
+    const [visibleSteps, setVisibleSteps] = (0, react_1.useState)([]);
+    const [markers, setMarkers] = (0, react_1.useState)({});
+    (0, react_1.useEffect)(() => {
+        var _a, _b, _c, _d, _e;
+        if (!root.current || !visibleSteps.length || !options) {
+            return;
+        }
+        const markersMinTopOffset = options.filtersElementHeight + options.navbarHeight;
+        const rootHeight = (_b = (_a = root.current) === null || _a === void 0 ? void 0 : _a.clientHeight) !== null && _b !== void 0 ? _b : 0;
+        const lastStepOffset = (_e = (_d = (_c = visibleSteps[visibleSteps.length - 1]) === null || _c === void 0 ? void 0 : _c.compRef) === null || _d === void 0 ? void 0 : _d.offsetTop) !== null && _e !== void 0 ? _e : 0;
+        const deficit = Math.max(lastStepOffset - (rootHeight - window.innerHeight), 0);
+        const groups = getGroups(visibleSteps);
+        let markers = groups.flatMap((group) => getGroupMarkers(group));
+        if (deficit) {
+            const startOffset = markersMinTopOffset;
+            const endOffset = Math.max(rootHeight - window.innerHeight, 0);
+            markers = distributeMarkers({
+                endOffset,
+                markers,
+                startOffset: markersMinTopOffset < endOffset ? startOffset : 0,
+            });
+        }
+        setMarkers(markers.reduce((acc, marker, index) => {
+            var _a;
+            const step = visibleSteps[index];
+            acc[step.id] = {
+                offset: marker,
+                height: markers[index + 1] || !step.compRef
+                    ? ((_a = markers[index + 1]) !== null && _a !== void 0 ? _a : rootHeight) - marker
+                    : step.compRef.clientHeight,
+            };
+            return acc;
+        }, {}));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [visibleSteps, root.current, options]);
+    const registerMarker = (0, react_1.useCallback)((stepId, element) => {
+        if (observerRef.current) {
+            const step = stepsMap.get(stepId);
+            if (step) {
+                step.markerRef = element;
             }
-        }, 10);
-    }, [_steps]);
-    const unregister = (0, react_1.useCallback)((element) => {
+            observerRef.current.observe(element);
+            observedElementsRef.current.add(element);
+        }
+    }, [stepsMap]);
+    const removeMarker = (0, react_1.useCallback)((stepId, element) => {
         if (observerRef.current) {
-            const stepKey = Number(element.dataset.stepKey);
-            if (Number.isInteger(stepKey) && stepKey >= 0 && _steps[stepKey]) {
-                _steps[stepKey].compRef = undefined;
+            const step = stepsMap.get(stepId);
+            if (step) {
+                step.markerRef = undefined;
             }
             observerRef.current.unobserve(element);
             observedElementsRef.current.delete(element);
         }
-    }, [_steps]);
+    }, [stepsMap]);
+    const registerStep = (0, react_1.useCallback)((stepId, element) => {
+        const step = stepsMap.get(stepId);
+        if (!step) {
+            return;
+        }
+        step.compRef = element;
+        setVisibleSteps((prevSteps) => (0, utils_1.insertAt)(prevSteps, step.index, step));
+    }, [stepsMap]);
+    const removeStep = (0, react_1.useCallback)((stepId) => {
+        const step = stepsMap.get(stepId);
+        if (!step) {
+            return;
+        }
+        step.compRef = undefined;
+        setVisibleSteps((prevSteps) => (0, utils_1.removeElement)(prevSteps, step));
+        setActiveStep((prevStep) => (prevStep === stepId ? null : prevStep));
+    }, [stepsMap]);
     const observerCallback = (0, react_1.useCallback)((entries) => {
         var _a, _b, _c;
-        if (lockObserver.current) {
+        if (lockObserver.current || !visibleSteps.length) {
             return;
         }
-        const renderedSteps = _steps.filter((step) => Boolean(step.compRef));
-        if (renderedSteps.length < 2) {
-            setActiveStep(((_a = renderedSteps[0]) === null || _a === void 0 ? void 0 : _a.id) || null);
+        if (visibleSteps.length < 2) {
+            setActiveStep(((_a = visibleSteps[0]) === null || _a === void 0 ? void 0 : _a.id) || null);
             return;
         }
         for (const entry of entries) {
-            const stepKey = Number((_c = (_b = entry.target) === null || _b === void 0 ? void 0 : _b.dataset) === null || _c === void 0 ? void 0 : _c.stepKey);
-            if (!Number.isInteger(stepKey) || stepKey < 0) {
+            const stepId = (_c = (_b = entry.target) === null || _b === void 0 ? void 0 : _b.dataset) === null || _c === void 0 ? void 0 : _c.stepId;
+            if (!stepId) {
                 continue;
             }
             const { intersectionRatio, boundingClientRect, rootBounds, isIntersecting } = entry;
-            const step = _steps[stepKey];
-            const stepIndex = renderedSteps.findIndex((renderedStep) => renderedStep.stepKey === step.stepKey);
-            const { next } = (0, utils_1.getAdjacentValues)(renderedSteps, stepIndex);
+            const step = stepsMap.get(stepId);
+            if (!step) {
+                continue;
+            }
+            const stepIndex = visibleSteps.findIndex((renderedStep) => renderedStep.id === stepId);
+            const { next } = (0, utils_1.getAdjacentValues)(visibleSteps, stepIndex);
             const intersectionAtTop = (rootBounds === null || rootBounds === void 0 ? void 0 : rootBounds.bottom) !== undefined && boundingClientRect.top < rootBounds.top;
             const stepGoesIn = isIntersecting;
-            if (intersectionRatio > 0.8 &&
-                intersectionRatio < 1 &&
-                intersectionAtTop &&
-                activeStep === null) {
+            if (intersectionRatio > 0.8 && intersectionRatio < 1 && intersectionAtTop) {
                 setActiveStep(step.id);
                 break;
             }
@@ -76,28 +143,37 @@ function useCodeWalkthroughSteps(steps, enableDeepLink) {
                 else if (next) {
                     newStep = next.id;
                 }
-                if (newStep !== activeStep) {
-                    setActiveStep(newStep);
-                }
+                setActiveStep((prevStep) => newStep || prevStep);
                 break;
             }
         }
-    }, [_steps, activeStep]);
+    }, [stepsMap, visibleSteps]);
     (0, react_1.useEffect)(() => {
-        var _a, _b, _c;
-        const filtersElementHeight = ((_a = filtersElementRef.current) === null || _a === void 0 ? void 0 : _a.clientHeight) || 0;
-        const navbarHeight = ((_b = document.querySelector('nav')) === null || _b === void 0 ? void 0 : _b.clientHeight) || 0;
+        var _a;
+        if (!options) {
+            return;
+        }
         const newObserver = new IntersectionObserver(observerCallback, {
-            threshold: [0.8, 0.85, 0.9, 0.95],
-            rootMargin: `-${filtersElementHeight + navbarHeight}px 0px 0px 0px`,
+            threshold: [0.3, 0.8, 0.9, 0.95],
+            rootMargin: `-${options.filtersElementHeight + options.navbarHeight}px 0px 0px 0px`,
         });
-        for (const observedElement of observedElementsRef.current) {
+        for (const observedElement of observedElementsRef.current.values()) {
             newObserver.observe(observedElement);
         }
-        // Unobserve all from the old observer
-        (_c = observerRef.current) === null || _c === void 0 ? void 0 : _c.disconnect();
+        (_a = observerRef.current) === null || _a === void 0 ? void 0 : _a.disconnect();
         observerRef.current = newObserver;
-    }, [observerCallback]);
+    }, [observerCallback, markers, options]);
+    (0, react_1.useEffect)(() => {
+        var _a, _b, _c;
+        if (!options) {
+            return;
+        }
+        const rootTopOffset = (_b = (_a = root.current) === null || _a === void 0 ? void 0 : _a.offsetTop) !== null && _b !== void 0 ? _b : 0;
+        if (!activeStep && rootTopOffset <= options.navbarHeight) {
+            setActiveStep(((_c = visibleSteps[0]) === null || _c === void 0 ? void 0 : _c.id) || null);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [activeStep, root.current, options, visibleSteps]);
     /**
      * Update the URL search params with the current state of the filters and inputs
      */
@@ -118,6 +194,125 @@ function useCodeWalkthroughSteps(steps, enableDeepLink) {
         navigate({ search: newSearch }, { replace: true });
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [activeStep]);
-    return { register, unregister, lockObserver, filtersElementRef, activeStep, setActiveStep };
+    return {
+        registerStep,
+        removeStep,
+        markers,
+        registerMarker,
+        removeMarker,
+        lockObserver,
+        filtersElementRef,
+        activeStep,
+        setActiveStep,
+    };
+}
+/**
+ * This function analyzes the offset and height of each step to determine
+ * when a new group should be created. A new group is started when there is a free space
+ * between the two steps, treating it as the content of the next group header.
+ *
+ * @param steps - An array of `CodeWalkthroughStep` objects
+ *
+ * @returns An array of `StepsGroup` objects, each containing the offset from the top of the relative
+ *          block, the free space at the top of the group, the total space used by the steps within the group
+ *          and the steps themselves with relative offset and height.
+ */
+function getGroups(steps) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+    if (!steps.length) {
+        return [];
+    }
+    const firstStepOffset = (_c = (_b = (_a = steps[0]) === null || _a === void 0 ? void 0 : _a.compRef) === null || _b === void 0 ? void 0 : _b.offsetTop) !== null && _c !== void 0 ? _c : 0;
+    const firstStepHeight = (_f = (_e = (_d = steps[0]) === null || _d === void 0 ? void 0 : _d.compRef) === null || _e === void 0 ? void 0 : _e.clientHeight) !== null && _f !== void 0 ? _f : 0;
+    const secondStepOffset = (_j = (_h = (_g = steps[1]) === null || _g === void 0 ? void 0 : _g.compRef) === null || _h === void 0 ? void 0 : _h.offsetTop) !== null && _j !== void 0 ? _j : 0;
+    const margin = Math.max(secondStepOffset - firstStepOffset - firstStepHeight, 0);
+    let groupIndex = 0;
+    const groups = [
+        {
+            offset: 0,
+            freeSpace: firstStepOffset,
+            usedSpace: 0,
+            steps: [],
+        },
+    ];
+    for (let i = 0; i < steps.length; i++) {
+        let currentGroup = groups[groupIndex];
+        const step = steps[i];
+        const stepHeight = (_l = (_k = step.compRef) === null || _k === void 0 ? void 0 : _k.clientHeight) !== null && _l !== void 0 ? _l : 0;
+        const stepOffset = (_o = (_m = step.compRef) === null || _m === void 0 ? void 0 : _m.offsetTop) !== null && _o !== void 0 ? _o : 0;
+        const prevStepOffset = currentGroup.freeSpace + currentGroup.usedSpace;
+        if (prevStepOffset !== Math.max(stepOffset - currentGroup.offset, 0)) {
+            const offset = currentGroup.offset + currentGroup.freeSpace + currentGroup.usedSpace;
+            groupIndex++;
+            groups[groupIndex] = {
+                offset,
+                freeSpace: Math.max(stepOffset - offset, 0),
+                usedSpace: 0,
+                steps: [],
+            };
+            currentGroup = groups[groupIndex];
+        }
+        currentGroup.steps.push({
+            offset: stepOffset - currentGroup.offset,
+            height: stepHeight,
+            ref: step.compRef,
+        });
+        currentGroup.usedSpace += stepHeight + margin;
+    }
+    return groups;
+}
+function getGroupMarkers(group) {
+    if (!group.steps.length) {
+        return [];
+    }
+    if (group.steps.length === 1) {
+        return [group.offset + group.steps[0].offset - group.freeSpace];
+    }
+    const availableFreeSpace = group.freeSpace > 0.3 * window.innerHeight ? 0.3 * window.innerHeight : group.freeSpace;
+    const unusedFreeSpace = group.freeSpace - availableFreeSpace;
+    const lastStepOffset = group.steps[group.steps.length - 1].offset;
+    // distribute group free space between steps
+    return distributeMarkers({
+        startOffset: 0,
+        endOffset: lastStepOffset - unusedFreeSpace,
+        markers: group.steps.map((step) => step.offset),
+        additionalSteps: [(marker) => group.offset + unusedFreeSpace + marker],
+    });
+}
+/**
+ * Distribute markers preserving the relationship throughout the available space
+ * @param startOffset - the starting point of the available space
+ * @param endOffset - the end point of the available space
+ * @param markers - the markers to distribute
+ * @param additionalSteps - additional steps to apply to the markers
+ *
+ * @returns array of markers positions
+ */
+function distributeMarkers({ endOffset, markers, startOffset, additionalSteps = [], }) {
+    return markers.map((marker) => {
+        const normalizedOffset = getNormalizedNumber({
+            min: markers[0],
+            max: markers[markers.length - 1],
+            value: marker,
+        });
+        const availableSpace = endOffset - startOffset;
+        let result = startOffset + normalizedOffset * availableSpace;
+        for (const additionalStep of additionalSteps) {
+            result = additionalStep(result);
+        }
+        return result;
+    });
+}
+/**
+ * Normalize a number between a min and max value
+ * @param min - the minimum value of the distribution
+ * @param max - the maximum value of the distribution
+ * @param value - the value to normalize
+ *
+ * @returns normalized number between 0 and 1
+ */
+function getNormalizedNumber(options) {
+    const { min, max, value } = options;
+    return (value - min) / (max - min);
 }
 //# sourceMappingURL=use-code-walkthrough-steps.js.map

package/lib/core/hooks/code-walkthrough/use-code-walkthrough.d.ts

@@ -1,9 +1,16 @@
 import type { CodeWalkthroughFile, CodeWalkthroughStepAttr, CodeWalkthroughAttr } from '@redocly/config';
-import { type WalkthroughControlsState, type WalkthroughStepsState } from '../../../core/hooks';
+import type { WalkthroughStepsState } from '../../../core/types';
+import { type WalkthroughControlsState } from '../../../core/hooks';
 export type WalkthroughState = {
     stepsState: WalkthroughStepsState;
     controlsState: WalkthroughControlsState;
     downloadAssociatedFiles: CodeWalkthroughFile[];
     files: CodeWalkthroughFile[];
 };
-export declare function useCodeWalkthrough(steps: CodeWalkthroughStepAttr[], attributes: Omit<CodeWalkthroughAttr, 'steps' | 'preview'>): WalkthroughState;
+type Params = {
+    steps: CodeWalkthroughStepAttr[];
+    attributes: Omit<CodeWalkthroughAttr, 'steps' | 'preview'>;
+    root: React.RefObject<HTMLDivElement | null>;
+};
+export declare function useCodeWalkthrough({ steps, attributes, root }: Params): WalkthroughState;
+export {};

package/lib/core/hooks/code-walkthrough/use-code-walkthrough.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useCodeWalkthrough = useCodeWalkthrough;
 const hooks_1 = require("../../../core/hooks");
-function useCodeWalkthrough(steps, attributes) {
+function useCodeWalkthrough({ steps, attributes, root }) {
     const { filters, filesets, inputs, toggles, __idx } = attributes;
     /*
       We only enable deep linking for the first CodeWalkthrough,
@@ -11,7 +11,7 @@ function useCodeWalkthrough(steps, attributes) {
       collisions/conflicts in the URL.
     */
     const enableDeepLink = __idx === 1;
-    const stepsState = (0, hooks_1.useCodeWalkthroughSteps)(steps, enableDeepLink);
+    const stepsState = (0, hooks_1.useCodeWalkthroughSteps)({ steps, enableDeepLink, root });
     const controlsState = (0, hooks_1.useCodeWalkthroughControls)(filters, inputs, toggles, enableDeepLink);
     const files = filesets
         .filter((fileset) => controlsState.areConditionsMet(fileset))

package/lib/core/hooks/index.d.ts

@@ -36,5 +36,5 @@ export * from '../../core/hooks/code-walkthrough/use-renderable-files';
 export * from '../../core/hooks/use-element-size';
 export * from '../../core/hooks/use-time-ago';
 export * from '../../core/hooks/use-input-key-commands';
-export * from '../../core/hooks/use-page-active-version';
+export * from '../../core/hooks/use-active-page-version';
 export * from '../../core/hooks/use-page-versions';

package/lib/core/hooks/index.js

@@ -52,6 +52,6 @@ __exportStar(require("../../core/hooks/code-walkthrough/use-renderable-files"),
 __exportStar(require("../../core/hooks/use-element-size"), exports);
 __exportStar(require("../../core/hooks/use-time-ago"), exports);
 __exportStar(require("../../core/hooks/use-input-key-commands"), exports);
-__exportStar(require("../../core/hooks/use-page-active-version"), exports);
+__exportStar(require("../../core/hooks/use-active-page-version"), exports);
 __exportStar(require("../../core/hooks/use-page-versions"), exports);
 //# sourceMappingURL=index.js.map

package/lib/core/hooks/use-active-page-version.d.ts

@@ -0,0 +1 @@
+export declare function useActivePageVersion(): string | undefined;

package/lib/core/hooks/{use-page-active-version.js → use-active-page-version.js}

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.usePageActiveVersion = usePageActiveVersion;
+exports.useActivePageVersion = useActivePageVersion;
 const hooks_1 = require("../../core/hooks");
-function usePageActiveVersion() {
+function useActivePageVersion() {
     const { usePageVersions } = (0, hooks_1.useThemeHooks)();
     const { versions } = usePageVersions();
     const activeVersion = versions.find((version) => version.active);
     return activeVersion === null || activeVersion === void 0 ? void 0 : activeVersion.version;
 }
-//# sourceMappingURL=use-page-active-version.js.map
+//# sourceMappingURL=use-active-page-version.js.map

package/lib/core/types/code-walkthrough.d.ts

@@ -0,0 +1,13 @@
+import type { MarkerArea } from '../../core/types';
+export type ActiveStep = string | null;
+export type WalkthroughStepsState = {
+    activeStep: ActiveStep;
+    setActiveStep: (stepId: ActiveStep) => void;
+    markers: Record<string, MarkerArea>;
+    registerMarker: (stepId: string, element: HTMLElement) => void;
+    removeMarker: (stepId: string, element: HTMLElement) => void;
+    registerStep: (stepId: string, element: HTMLElement) => void;
+    removeStep: (stepId: string) => void;
+    lockObserver?: React.RefObject<boolean>;
+    filtersElementRef?: React.RefObject<HTMLDivElement | null>;
+};

package/lib/core/types/code-walkthrough.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=code-walkthrough.js.map

package/lib/core/types/index.d.ts

@@ -13,3 +13,5 @@ export * from '../../core/types/user-menu';
 export * from '../../core/types/user-claims';
 export * from '../../core/types/common';
 export * from '../../core/types/open-api-server';
+export * from '../../core/types/marker';
+export * from '../../core/types/code-walkthrough';

package/lib/core/types/index.js

@@ -29,4 +29,6 @@ __exportStar(require("../../core/types/user-menu"), exports);
 __exportStar(require("../../core/types/user-claims"), exports);
 __exportStar(require("../../core/types/common"), exports);
 __exportStar(require("../../core/types/open-api-server"), exports);
+__exportStar(require("../../core/types/marker"), exports);
+__exportStar(require("../../core/types/code-walkthrough"), exports);
 //# sourceMappingURL=index.js.map

package/lib/core/types/marker.d.ts

@@ -0,0 +1,4 @@
+export type MarkerArea = {
+    offset: number;
+    height: number;
+};

package/lib/core/types/marker.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=marker.js.map

package/lib/core/utils/js-utils.d.ts

@@ -36,3 +36,21 @@ export declare function getAdjacentValues<T>(array: T[], index: number): {
     prev: T | null;
     next: T | null;
 };
+/**
+ * Inserts an element at a given index in an array. Returns a new array with the element inserted.
+ *
+ * @example
+ * const array = [10, 20, 30, 40];
+ * insertAt(array, 2, 25);
+ * // returns: [10, 20, 25, 30, 40]
+ */
+export declare function insertAt<T>(array: T[], index: number, newElement: T): T[];
+/**
+ * Removes an element from an array. Returns a new array with the element removed.
+ *
+ * @example
+ * const array = [10, 20, 30, 40];
+ * removeElement(array, 20);
+ * // returns: [10, 30, 40]
+ */
+export declare function removeElement<T>(array: T[], item: T): T[];