@redocly/theme 0.47.0 → 0.48.0

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

@@ -0,0 +1,6 @@
+import type { CodeWalkthroughFile } from '@redocly/config';
+export declare function useCodePanel(files: CodeWalkthroughFile[]): {
+    readonly activeFile: CodeWalkthroughFile;
+    readonly handleTabSwitch: (name: string) => void;
+    readonly highlightedCode: string;
+};

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

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCodePanel = useCodePanel;
+const react_1 = require("react");
+const contexts_1 = require("../../../core/contexts");
+const hooks_1 = require("../../../core/hooks");
+const ACTIVE_FILE_MOCK = {
+    content: [],
+    path: '',
+    basename: '',
+    metadata: {},
+    language: '',
+};
+function useCodePanel(files) {
+    const { activeStep } = (0, react_1.useContext)(contexts_1.CodeWalkthroughStepsContext);
+    const { areConditionsMet, populateInputsWithValue } = (0, react_1.useContext)(contexts_1.CodeWalkthroughControlsStateContext);
+    const { useCodeHighlight } = (0, hooks_1.useThemeHooks)();
+    const { highlight } = useCodeHighlight();
+    const findFileIndexByName = (0, react_1.useCallback)((name) => {
+        return files.findIndex((file) => file.path === name);
+    }, [files]);
+    const findFileIndexByStepId = (0, react_1.useCallback)((id) => files.findIndex((file) => file.metadata.steps.includes(id)), [files]);
+    const activeStepFileIndex = activeStep ? findFileIndexByStepId(activeStep) : 0;
+    const initialActiveFileIndex = activeStepFileIndex !== -1 ? activeStepFileIndex : 0;
+    const [activeFileIndex, setActiveFileIndex] = (0, react_1.useState)(initialActiveFileIndex);
+    (0, react_1.useEffect)(() => {
+        setActiveFileIndex(initialActiveFileIndex);
+    }, [initialActiveFileIndex, activeStep, files]);
+    const handleTabSwitch = (0, react_1.useCallback)((name) => {
+        const index = findFileIndexByName(name);
+        if (index !== -1) {
+            setActiveFileIndex(index);
+        }
+    }, [findFileIndexByName]);
+    const activeFile = files[activeFileIndex] ||
+        // Fallback to default. Needed when switching from language with more files to a language with less files
+        files[initialActiveFileIndex] ||
+        // Final fallback for dev mode when no files were added yet
+        ACTIVE_FILE_MOCK;
+    const highlightedCode = (0, react_1.useMemo)(() => {
+        const { highlightedLines, code, isWholeFileSelected } = getRenderableCode(activeFile, activeStep, areConditionsMet, populateInputsWithValue);
+        return highlight(code, activeFile.language, {
+            withLineNumbers: true,
+            // Shiki transformerMetaHighlight meta to highlight lines
+            // If the whole file is selected for a step, do not apply highlighting
+            highlight: isWholeFileSelected ? '' : `{${Array.from(highlightedLines).join(',')}}`,
+            customTransformer: {
+                // Add greyed-out class to lines that are not highlighted
+                line(hast, number) {
+                    if (!highlightedLines.has(number)) {
+                        this.addClassToHast(hast, 'greyed-out');
+                    }
+                },
+            },
+        });
+    }, [activeFile, activeStep, highlight, areConditionsMet, populateInputsWithValue]);
+    return { activeFile, handleTabSwitch, highlightedCode };
+}
+function getRenderableCode(activeFile, activeStep, areConditionsMet, populateInputsWithValue) {
+    const codeLines = activeFile.content.flatMap((node) => getCodeLinesFromNode(node, activeStep, areConditionsMet, populateInputsWithValue));
+    const codeLinesContent = [];
+    const highlightedLines = new Set();
+    codeLines.forEach(({ lineContent, highlighted }, idx) => {
+        codeLinesContent.push(lineContent);
+        if (highlighted) {
+            highlightedLines.add(idx + 1);
+        }
+    });
+    return {
+        highlightedLines,
+        code: codeLinesContent.join('\n'),
+        isWholeFileSelected: highlightedLines.size === codeLinesContent.length,
+    };
+}
+/**
+ * Convert code node to code line objects with content to render and their highlighted status
+ */
+function getCodeLinesFromNode(node, activeStep, areConditionsMet, populateInputsWithValue, parentHighlighted = false) {
+    if (typeof node === 'string') {
+        const replacedNode = populateInputsWithValue(node);
+        return [{ lineContent: replacedNode, highlighted: parentHighlighted }];
+    }
+    else {
+        const shouldRenderChunk = areConditionsMet(node.condition);
+        const isHighlighted = activeStep != null &&
+            node.condition.steps.length > 0 &&
+            node.condition.steps.includes(activeStep);
+        return shouldRenderChunk
+            ? node.children.flatMap((child) => getCodeLinesFromNode(child, activeStep, areConditionsMet, populateInputsWithValue, isHighlighted))
+            : [];
+    }
+}
+//# sourceMappingURL=use-code-panel.js.map

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

@@ -0,0 +1,22 @@
+import type { CodeWalkthroughFile, CodeWalkthroughFilter, InputsMarkdocAttr, TogglesMarkdocAttr, CodeWalkthroughFilterItem, ControlState, ControlTypeValue, ControlType, CodeWalkthroughConditionsObject } from '@redocly/config';
+export type getState<T extends ControlType> = (id: string) => Omit<ControlState<T>, 'type'> | null;
+export type changeState<T extends ControlType> = (id: string, value: ControlTypeValue<T>) => void;
+export type ActiveFilter = {
+    id: string;
+    label?: string;
+    items: CodeWalkthroughFilterItem[];
+};
+export type WalkthroughControlsState = {
+    activeFilters: ActiveFilter[];
+    getToggleState: getState<'toggle'>;
+    changeToggleState: changeState<'toggle'>;
+    getInputState: getState<'input'>;
+    changeInputState: changeState<'input'>;
+    getFilterState: getState<'filter'>;
+    changeFilterState: changeState<'filter'>;
+    areConditionsMet: (conditions: CodeWalkthroughConditionsObject) => boolean;
+    handleDownloadCode: (files: CodeWalkthroughFile[]) => Promise<void>;
+    getFileText: (file: CodeWalkthroughFile) => string;
+    populateInputsWithValue: (node: string) => string;
+};
+export declare function useCodeWalkthroughControls(filters: Record<string, CodeWalkthroughFilter>, inputs: InputsMarkdocAttr, toggles: TogglesMarkdocAttr): WalkthroughControlsState;

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

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCodeWalkthroughControls = useCodeWalkthroughControls;
+const react_1 = require("react");
+const react_router_dom_1 = require("react-router-dom");
+const utils_1 = require("../../../core/utils");
+const defaultControlsValues = {
+    input: '',
+    toggle: false,
+    filter: '',
+};
+function useCodeWalkthroughControls(filters, inputs, toggles) {
+    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]);
+    const [togglesState, setTogglesState] = (0, react_1.useState)(() => {
+        const initialState = {};
+        for (const [id, toggle] of Object.entries(toggles)) {
+            initialState[id] = Object.assign(Object.assign({}, toggle), { render: true, type: 'toggle', value: searchParams.get(id) === 'true' });
+        }
+        return initialState;
+    });
+    const changeToggleState = (toggleId, checked) => {
+        setTogglesState((prev) => {
+            const toggle = prev[toggleId];
+            if (toggle) {
+                return Object.assign(Object.assign({}, prev), { [toggleId]: Object.assign(Object.assign({}, toggle), { value: checked }) });
+            }
+            else {
+                return prev;
+            }
+        });
+    };
+    const getToggleState = (toggleId) => {
+        const toggleState = togglesState[toggleId];
+        if (toggleState) {
+            return {
+                render: toggleState.render,
+                value: toggleState.value,
+            };
+        }
+        else {
+            return null;
+        }
+    };
+    const [inputsState, setInputsState] = (0, react_1.useState)(() => {
+        const initialState = {};
+        for (const [id, input] of Object.entries(inputs)) {
+            initialState[id] = Object.assign(Object.assign({}, input), { render: true, type: 'input', value: searchParams.get(id) || input.value });
+        }
+        return initialState;
+    });
+    const changeInputState = (inputId, value) => {
+        setInputsState((prev) => {
+            const input = prev[inputId];
+            if (input) {
+                return Object.assign(Object.assign({}, prev), { [inputId]: Object.assign(Object.assign({}, input), { value }) });
+            }
+            else {
+                return prev;
+            }
+        });
+    };
+    const getInputState = (inputId) => {
+        const inputState = inputsState[inputId];
+        if (inputState) {
+            return {
+                render: inputState.render,
+                value: inputState.value,
+            };
+        }
+        else {
+            return null;
+        }
+    };
+    const [filtersState, setFiltersState] = (0, react_1.useState)(() => {
+        var _a, _b;
+        const initialState = {};
+        for (const [id, filter] of Object.entries(filters)) {
+            initialState[id] = Object.assign(Object.assign({}, filter), { render: true, type: 'filter', value: searchParams.get(id) || ((_b = (_a = filter === null || filter === void 0 ? void 0 : filter.items) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.value) || '' });
+        }
+        return initialState;
+    });
+    const changeFilterState = (filterId, value) => {
+        setFiltersState((prev) => {
+            const filter = prev[filterId];
+            if (filter) {
+                return Object.assign(Object.assign({}, prev), { [filterId]: Object.assign(Object.assign({}, filter), { value }) });
+            }
+            else {
+                return prev;
+            }
+        });
+    };
+    const getFilterState = (filterId) => {
+        const filterState = filtersState[filterId];
+        if (filterState) {
+            return {
+                render: filterState.render,
+                value: filterState.value,
+            };
+        }
+        else {
+            return null;
+        }
+    };
+    const state = Object.assign(Object.assign(Object.assign({}, filtersState), togglesState), inputsState);
+    const walkthroughContext = (0, react_1.useMemo)(() => {
+        const areConditionsMet = (conditions) => (0, utils_1.matchCodeWalkthroughConditions)(conditions, state);
+        for (const [id, element] of Object.entries(state)) {
+            if (element && !areConditionsMet(element)) {
+                state[id].render = false;
+                state[id].value = defaultControlsValues[element.type];
+            }
+        }
+        const activeFilters = [];
+        for (const [id, filter] of Object.entries(filters)) {
+            if (!filtersState[id].render) {
+                continue;
+            }
+            // code-walk-todo: need to check if we have a default fallback
+            const items = Array.isArray(filter === null || filter === void 0 ? void 0 : filter.items) ? filter.items : [];
+            const activeItems = items.filter((item) => areConditionsMet(item));
+            if (activeItems.length === 0) {
+                filtersState[id].render = false;
+                filtersState[id].value = defaultControlsValues['filter'];
+                continue;
+            }
+            const currentValue = filtersState[id].value;
+            if (currentValue) {
+                const isValueInActiveItems = activeItems.findIndex(({ value }) => value === currentValue) !== -1;
+                filtersState[id].value = isValueInActiveItems ? currentValue : activeItems[0].value;
+            }
+            else {
+                filtersState[id].value = activeItems[0].value;
+            }
+            activeFilters.push({
+                id,
+                label: filter.label,
+                items: activeItems,
+            });
+        }
+        const handleDownloadCode = (files) => (0, utils_1.downloadCodeWalkthrough)(files, state, inputsState);
+        const getFileText = (file) => (0, utils_1.getCodeWalkthroughFileText)(file, state, inputsState);
+        const populateInputsWithValue = (node) => (0, utils_1.replaceInputsWithValue)(node, inputsState);
+        return {
+            activeFilters,
+            areConditionsMet,
+            handleDownloadCode,
+            getFileText,
+            populateInputsWithValue,
+        };
+        // Ignore state in dependency array as it's simply a combination of toggles, filters and inputs.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [filters, filtersState, togglesState, inputsState]);
+    /**
+     * Update the URL search params with the current state of the filters and inputs
+     */
+    (0, react_1.useEffect)(() => {
+        const newSearchParams = new URLSearchParams(Array.from(searchParams.entries()));
+        for (const [id, { value }] of Object.entries(state)) {
+            if (value) {
+                newSearchParams.set(id, value.toString());
+            }
+            else {
+                newSearchParams.delete(id);
+            }
+        }
+        const newSearch = newSearchParams.toString();
+        if (newSearch === location.search.substring(1))
+            return;
+        navigate({ search: newSearch });
+        // Ignore searchParams in dependency array to avoid infinite re-renders
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [filters, filtersState, togglesState, inputsState, navigate, location, state]);
+    return Object.assign({ getInputState,
+        changeInputState,
+        getToggleState,
+        changeToggleState,
+        getFilterState,
+        changeFilterState }, walkthroughContext);
+}
+//# sourceMappingURL=use-code-walkthrough-controls.js.map

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

@@ -0,0 +1,16 @@
+import type { CodeWalkthroughStepAttr } from '@redocly/config';
+type ActiveStep = string | null;
+type CodeWalkthroughStep = CodeWalkthroughStepAttr & {
+    active?: boolean;
+    compRef?: HTMLElement;
+};
+export type WalkthroughStepsState = {
+    activeStep: ActiveStep;
+    setActiveStep: (stepId: ActiveStep) => void;
+    register: (element: HTMLElement) => void;
+    unregister: (element: HTMLElement) => void;
+    lockObserver?: React.MutableRefObject<boolean>;
+    filtersElementRef?: React.RefObject<HTMLDivElement>;
+};
+export declare function useCodeWalkthroughSteps(steps: CodeWalkthroughStep[]): WalkthroughStepsState;
+export {};

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

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCodeWalkthroughSteps = useCodeWalkthroughSteps;
+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) {
+    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]);
+    const observerRef = (0, react_1.useRef)(null);
+    const filtersElementRef = (0, react_1.useRef)(null);
+    const lockObserver = (0, react_1.useRef)(false);
+    // 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)(searchParams.get(constants_1.ACTIVE_STEP_QUERY_PARAM));
+    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].compRef = element;
+                }
+                observerRef.current.observe(element);
+                observedElementsRef.current.add(element);
+            }
+        }, 10);
+    }, [steps]);
+    const unregister = (0, react_1.useCallback)((element) => {
+        if (observerRef.current) {
+            const stepKey = Number(element.dataset.stepKey);
+            if (Number.isInteger(stepKey) && stepKey >= 0) {
+                steps[stepKey].compRef = undefined;
+            }
+            observerRef.current.unobserve(element);
+            observedElementsRef.current.delete(element);
+        }
+    }, [steps]);
+    const observerCallback = (0, react_1.useCallback)((entries) => {
+        var _a, _b, _c;
+        if (lockObserver.current) {
+            return;
+        }
+        const stepsEntries = [];
+        for (const entry of entries) {
+            const { target } = entry;
+            const stepKey = Number((_a = target === null || target === void 0 ? void 0 : target.dataset) === null || _a === void 0 ? void 0 : _a.stepKey);
+            const stepActive = ((_b = target === null || target === void 0 ? void 0 : target.dataset) === null || _b === void 0 ? void 0 : _b.stepActive) === 'true';
+            if (!Number.isInteger(stepKey) || stepKey < 0) {
+                continue;
+            }
+            const step = steps[stepKey];
+            step.active = stepActive;
+            stepsEntries.push(entry);
+        }
+        for (const stepEntry of stepsEntries) {
+            const { target, intersectionRatio, boundingClientRect, rootBounds, isIntersecting } = stepEntry;
+            const stepKey = Number((_c = target === null || target === void 0 ? void 0 : target.dataset) === null || _c === void 0 ? void 0 : _c.stepKey);
+            const step = steps[stepKey];
+            const renderedSteps = steps.filter((step) => Boolean(step.compRef));
+            const stepIndex = renderedSteps.findIndex((renderedStep) => renderedStep.stepKey === step.stepKey);
+            const { next } = (0, utils_1.getAdjacentValues)(renderedSteps, stepIndex);
+            const intersectionAtTop = (rootBounds === null || rootBounds === void 0 ? void 0 : rootBounds.bottom) !== undefined && boundingClientRect.top < rootBounds.top;
+            const stepGoesIn = isIntersecting;
+            if (intersectionRatio < 1 && intersectionRatio !== 0 && intersectionAtTop) {
+                let newStep = null;
+                if (stepGoesIn) {
+                    newStep = step.id;
+                }
+                else if (next) {
+                    newStep = next.id;
+                }
+                if (newStep !== activeStep) {
+                    setActiveStep(newStep);
+                }
+                break;
+            }
+        }
+    }, [steps, activeStep]);
+    (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;
+        const newObserver = new IntersectionObserver(observerCallback, {
+            threshold: [0.8],
+            rootMargin: `-${filtersElementHeight + navbarHeight}px 0px 0px 0px`,
+        });
+        for (const observedElement of observedElementsRef.current) {
+            newObserver.observe(observedElement);
+        }
+        // Unobserve all from the old observer
+        (_c = observerRef.current) === null || _c === void 0 ? void 0 : _c.disconnect();
+        observerRef.current = newObserver;
+    }, [observerCallback]);
+    /**
+     * Update the URL search params with the current state of the filters and inputs
+     */
+    (0, react_1.useEffect)(() => {
+        const newSearchParams = new URLSearchParams(Array.from(searchParams.entries()));
+        if (activeStep) {
+            newSearchParams.set(constants_1.ACTIVE_STEP_QUERY_PARAM, activeStep);
+        }
+        else {
+            newSearchParams.delete(constants_1.ACTIVE_STEP_QUERY_PARAM);
+        }
+        const newSearch = newSearchParams.toString();
+        if (newSearch === location.search.substring(1))
+            return;
+        navigate({ search: newSearch });
+        // Ignore searchParams in dependency array to avoid infinite re-renders
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [activeStep, navigate, location]);
+    return { register, unregister, lockObserver, filtersElementRef, activeStep, setActiveStep };
+}
+//# sourceMappingURL=use-code-walkthrough-steps.js.map

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

@@ -0,0 +1,14 @@
+import type { CodeWalkthroughFileset, CodeWalkthroughFile, CodeWalkthroughStepAttr, CodeWalkthroughFilter, InputsMarkdocAttr, TogglesMarkdocAttr } from '@redocly/config';
+import { type WalkthroughControlsState, type WalkthroughStepsState } from '../../../core/hooks';
+export type WalkthroughState = {
+    stepsState: WalkthroughStepsState;
+    controlsState: WalkthroughControlsState;
+    downloadAssociatedFiles: CodeWalkthroughFile[];
+    files: CodeWalkthroughFile[];
+};
+export declare function useCodeWalkthrough(steps: CodeWalkthroughStepAttr[], attributes: {
+    filters: Record<string, CodeWalkthroughFilter>;
+    filesets: CodeWalkthroughFileset[];
+    inputs: InputsMarkdocAttr;
+    toggles: TogglesMarkdocAttr;
+}): WalkthroughState;

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

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCodeWalkthrough = useCodeWalkthrough;
+const hooks_1 = require("../../../core/hooks");
+function useCodeWalkthrough(steps, attributes) {
+    const { filters, filesets, inputs, toggles } = attributes;
+    const stepsState = (0, hooks_1.useCodeWalkthroughSteps)(steps);
+    const controlsState = (0, hooks_1.useCodeWalkthroughControls)(filters, inputs, toggles);
+    const files = filesets
+        .filter((fileset) => controlsState.areConditionsMet(fileset))
+        .flatMap((fileset) => fileset.files || []);
+    const downloadAssociatedFiles = filesets
+        .filter((fileset) => controlsState.areConditionsMet(fileset))
+        .flatMap((fileset) => fileset.downloadAssociatedFiles || []);
+    return {
+        stepsState,
+        controlsState,
+        downloadAssociatedFiles,
+        files,
+    };
+}
+//# sourceMappingURL=use-code-walkthrough.js.map

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

@@ -28,3 +28,7 @@ export * from '../../core/hooks/search/use-search-dialog';
 export * from '../../core/hooks/search/use-search-filter';
 export * from '../../core/hooks/use-controlled-state';
 export * from '../../core/hooks/use-codeblock-tabs-controls';
+export * from '../../core/hooks/code-walkthrough/use-code-walkthrough';
+export * from '../../core/hooks/code-walkthrough/use-code-walkthrough-steps';
+export * from '../../core/hooks/code-walkthrough/use-code-walkthrough-controls';
+export * from '../../core/hooks/code-walkthrough/use-code-panel';

package/lib/core/hooks/index.js

@@ -44,4 +44,8 @@ __exportStar(require("../../core/hooks/search/use-search-dialog"), exports);
 __exportStar(require("../../core/hooks/search/use-search-filter"), exports);
 __exportStar(require("../../core/hooks/use-controlled-state"), exports);
 __exportStar(require("../../core/hooks/use-codeblock-tabs-controls"), exports);
+__exportStar(require("../../core/hooks/code-walkthrough/use-code-walkthrough"), exports);
+__exportStar(require("../../core/hooks/code-walkthrough/use-code-walkthrough-steps"), exports);
+__exportStar(require("../../core/hooks/code-walkthrough/use-code-walkthrough-controls"), exports);
+__exportStar(require("../../core/hooks/code-walkthrough/use-code-panel"), exports);
 //# sourceMappingURL=index.js.map

package/lib/core/hooks/search/use-search-filter.d.ts

@@ -1,9 +1,9 @@
 import type { SearchFilterItem } from '../../../core/types';
 export declare function useSearchFilter(filter: SearchFilterItem[], setFilter: React.Dispatch<React.SetStateAction<SearchFilterItem[]>>): {
     onFacetReset: (field: string) => void;
-    onTopFacetsReset: () => void;
-    onFilterChange: (field: string, value: string | string[] | undefined, isTop?: boolean) => void;
+    onFilterChange: (field: string, value: string | string[] | undefined, isQuickFilter?: boolean) => void;
     onFilterReset: () => void;
     onFilterToggle: () => void;
+    onQuickFilterReset: () => void;
     isFilterOpen: boolean;
 };

package/lib/core/hooks/search/use-search-filter.js

@@ -7,7 +7,7 @@ function useSearchFilter(filter, setFilter) {
     const onFilterToggle = (0, react_1.useCallback)(() => {
         setIsFilterOpen(!isFilterOpen);
     }, [isFilterOpen]);
-    const onFilterChange = (field, value, isTop) => {
+    const onFilterChange = (field, value, isQuickFilter) => {
         const values = value ? (Array.isArray(value) ? value : [value]) : [];
         const _filter = [...filter];
         const fieldIndex = _filter.findIndex((filter) => filter.field === field);
@@ -18,16 +18,16 @@ function useSearchFilter(filter, setFilter) {
         else {
             if (!values.length)
                 return;
-            _filter.push({ field, values, isTop });
+            _filter.push({ field, values, isQuickFilter });
         }
         setFilter(_filter.filter((item) => item.values.length));
     };
     const onFilterReset = () => {
         setFilter([]);
     };
-    const onTopFacetsReset = () => {
+    const onQuickFilterReset = () => {
         const _filter = [...filter];
-        setFilter(_filter.filter((item) => !item.isTop));
+        setFilter(_filter.filter((item) => !item.isQuickFilter));
     };
     const onFacetReset = (field) => {
         const _filter = [...filter];
@@ -39,10 +39,10 @@ function useSearchFilter(filter, setFilter) {
     };
     return {
         onFacetReset,
-        onTopFacetsReset,
         onFilterChange,
         onFilterReset,
         onFilterToggle,
+        onQuickFilterReset,
         isFilterOpen,
     };
 }

package/lib/core/styles/global.js

@@ -38,6 +38,7 @@ const variables_32 = require("../../components/VersionPicker/variables");
 const variables_33 = require("../../components/DatePicker/variables");
 const variables_34 = require("../../components/Switch/variables");
 const variables_35 = require("../../markdoc/components/Cards/variables");
+const variables_36 = require("../../markdoc/components/CodeWalkthrough/variables");
 const themeColors = (0, styled_components_1.css) `
   /* === Palette === */
   /**
@@ -1152,6 +1153,7 @@ exports.styles = (0, styled_components_1.css) `
     ${variables_35.cards}
     ${variables_8.catalog}
     ${variables_21.code}
+    ${variables_36.codeWalkthrough}
     ${docsDropdown}
     ${variables_12.dropdown}
     ${error}

package/lib/core/templates/Markdown.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import type { UiAccessibleConfig } from '../../config';
 import type { MdHeading } from '../../core/types';
-type MarkdownTemplateProps = {
+export type MarkdownTemplateProps = {
     pageProps: {
         frontmatter?: UiAccessibleConfig;
         headings?: (MdHeading | null)[];
@@ -9,7 +9,13 @@ type MarkdownTemplateProps = {
             to: string;
         };
         lastModified?: string | null;
+        metadata: {
+            markdoc: {
+                tagList: string[];
+                [key: string]: unknown;
+            };
+            [key: string]: unknown;
+        };
     };
 };
 export default function ({ pageProps, children }: React.PropsWithChildren<MarkdownTemplateProps>): React.JSX.Element;
-export {};

package/lib/core/templates/Markdown.js

@@ -32,6 +32,7 @@ const Markdown_1 = require("../../components/Markdown/Markdown");
 const TableOfContent_1 = require("../../components/TableOfContent/TableOfContent");
 const Feedback_1 = require("../../components/Feedback/Feedback");
 const utils_1 = require("../../core/utils");
+const CodeWalkthroughLayout_1 = require("../../layouts/CodeWalkthroughLayout");
 function default_1({ pageProps, children }) {
     var _a;
     const [wrapperElement, setWrapperElement] = React.useState(null);
@@ -63,7 +64,9 @@ function default_1({ pageProps, children }) {
     if (utils_1.IS_BROWSER) {
         (0, utils_1.onDocumentReady)(utils_1.extendDetailsBehaviour);
     }
-    return (React.createElement(DocumentationLayout_1.DocumentationLayout, Object.assign({}, documentationLayoutProps),
-        React.createElement(Markdown_1.Markdown, { ref: wrapperRefCb }, children)));
+    const document = React.createElement(Markdown_1.Markdown, { ref: wrapperRefCb }, children);
+    const tagList = pageProps.metadata.markdoc.tagList;
+    const withCodeWalkthrough = Boolean(Array.isArray(tagList) && tagList.includes('code-walkthrough'));
+    return withCodeWalkthrough ? (React.createElement(CodeWalkthroughLayout_1.CodeWalkthroughLayout, null, document)) : (React.createElement(DocumentationLayout_1.DocumentationLayout, Object.assign({}, documentationLayoutProps), document));
 }
 //# sourceMappingURL=Markdown.js.map

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

@@ -1,4 +1,5 @@
 import type { PageProps, ResolvedNavItemWithLink, Version } from '@redocly/config';
+import type { ShikiTransformer } from '@shikijs/types';
 import type { Callback, TFunction as TFunc } from 'i18next';
 import type { To, Location, NavigateFunction } from 'react-router-dom';
 import type { CatalogConfig, ProductUiConfig } from '../../config';
@@ -53,6 +54,7 @@ export type ThemeHooks = {
         items: Record<string, SearchItemData[] | null>;
         isSearchLoading: boolean;
         facets: SearchFacet[];
+        groupField: string;
         setLoadMore: React.Dispatch<React.SetStateAction<{
             groupKey: string;
             offset: number;
@@ -103,6 +105,7 @@ export type ThemeHooks = {
             withLineNumbers?: boolean;
             startLineNumber?: number;
             highlight?: string;
+            customTransformer?: ShikiTransformer;
         }) => string;
     };
     useLoadAndNavigate: () => (options: {