@redocly/theme 0.47.0 → 0.48.0

package/src/core/hooks/code-walkthrough/use-code-panel.ts

@@ -0,0 +1,164 @@
+import { useContext, useCallback, useEffect, useState, useMemo } from 'react';
+
+import type {
+  CodeWalkthroughFile,
+  CodeWalkthroughNode,
+  CodeWalkthroughConditionsObject,
+} from '@redocly/config';
+
+import {
+  CodeWalkthroughControlsStateContext,
+  CodeWalkthroughStepsContext,
+} from '@redocly/theme/core/contexts';
+import { useThemeHooks } from '@redocly/theme/core/hooks';
+
+const ACTIVE_FILE_MOCK = {
+  content: [],
+  path: '',
+  basename: '',
+  metadata: {},
+  language: '',
+};
+
+export function useCodePanel(files: CodeWalkthroughFile[]) {
+  const { activeStep } = useContext(CodeWalkthroughStepsContext);
+
+  const { areConditionsMet, populateInputsWithValue } = useContext(
+    CodeWalkthroughControlsStateContext,
+  );
+
+  const { useCodeHighlight } = useThemeHooks();
+  const { highlight } = useCodeHighlight();
+
+  const findFileIndexByName = useCallback(
+    (name: string) => {
+      return files.findIndex((file) => file.path === name);
+    },
+    [files],
+  );
+
+  const findFileIndexByStepId = useCallback(
+    (id: string) => files.findIndex((file) => file.metadata.steps.includes(id)),
+    [files],
+  );
+
+  const activeStepFileIndex = activeStep ? findFileIndexByStepId(activeStep) : 0;
+  const initialActiveFileIndex = activeStepFileIndex !== -1 ? activeStepFileIndex : 0;
+
+  const [activeFileIndex, setActiveFileIndex] = useState(initialActiveFileIndex);
+
+  useEffect(() => {
+    setActiveFileIndex(initialActiveFileIndex);
+  }, [initialActiveFileIndex, activeStep, files]);
+
+  const handleTabSwitch = useCallback(
+    (name: string) => {
+      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 = 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 } as const;
+}
+
+function getRenderableCode(
+  activeFile: CodeWalkthroughFile,
+  activeStep: string | null,
+  areConditionsMet: (conditions: CodeWalkthroughConditionsObject) => boolean,
+  populateInputsWithValue: (node: string) => string,
+): {
+  highlightedLines: Set<number>;
+  code: string;
+  isWholeFileSelected: boolean;
+} {
+  const codeLines = activeFile.content.flatMap((node) =>
+    getCodeLinesFromNode(node, activeStep, areConditionsMet, populateInputsWithValue),
+  );
+
+  const codeLinesContent: string[] = [];
+  const highlightedLines = new Set<number>();
+
+  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: CodeWalkthroughNode,
+  activeStep: string | null,
+  areConditionsMet: (conditions: CodeWalkthroughConditionsObject) => boolean,
+  populateInputsWithValue: (node: string) => string,
+  parentHighlighted: boolean = false,
+): { lineContent: string; highlighted: boolean }[] {
+  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,
+          ),
+        )
+      : [];
+  }
+}

package/src/core/hooks/code-walkthrough/use-code-walkthrough-controls.ts

@@ -0,0 +1,302 @@
+import { useState, useEffect, useMemo } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+
+import type {
+  CodeWalkthroughFile,
+  CodeWalkthroughFilter,
+  InputsMarkdocAttr,
+  TogglesMarkdocAttr,
+  CodeWalkthroughControls,
+  TogglesState,
+  InputsState,
+  FiltersState,
+  CodeWalkthroughFilterItem,
+  ControlState,
+  ControlTypeValue,
+  ControlType,
+  CodeWalkthroughConditionsObject,
+} from '@redocly/config';
+
+import {
+  downloadCodeWalkthrough,
+  matchCodeWalkthroughConditions,
+  getCodeWalkthroughFileText,
+  replaceInputsWithValue,
+} from '@redocly/theme/core/utils';
+
+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[];
+  /* Toggle State Controls */
+  getToggleState: getState<'toggle'>;
+  changeToggleState: changeState<'toggle'>;
+  /* Input State Controls */
+  getInputState: getState<'input'>;
+  changeInputState: changeState<'input'>;
+  /* Filter State Controls */
+  getFilterState: getState<'filter'>;
+  changeFilterState: changeState<'filter'>;
+  /* Utility */
+  areConditionsMet: (conditions: CodeWalkthroughConditionsObject) => boolean;
+  handleDownloadCode: (files: CodeWalkthroughFile[]) => Promise<void>;
+  getFileText: (file: CodeWalkthroughFile) => string;
+  populateInputsWithValue: (node: string) => string;
+};
+
+const defaultControlsValues: CodeWalkthroughControls = {
+  input: '',
+  toggle: false,
+  filter: '',
+};
+
+export function useCodeWalkthroughControls(
+  filters: Record<string, CodeWalkthroughFilter>,
+  inputs: InputsMarkdocAttr,
+  toggles: TogglesMarkdocAttr,
+): WalkthroughControlsState {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const searchParams = useMemo(() => new URLSearchParams(location.search), [location.search]);
+
+  const [togglesState, setTogglesState] = useState(() => {
+    const initialState: TogglesState = {};
+    for (const [id, toggle] of Object.entries(toggles)) {
+      initialState[id] = {
+        ...toggle,
+        render: true,
+        type: 'toggle',
+        value: searchParams.get(id) === 'true',
+      };
+    }
+    return initialState;
+  });
+
+  const changeToggleState = (toggleId: string, checked: boolean) => {
+    setTogglesState((prev) => {
+      const toggle = prev[toggleId];
+      if (toggle) {
+        return {
+          ...prev,
+          [toggleId]: {
+            ...toggle,
+            value: checked,
+          },
+        };
+      } else {
+        return prev;
+      }
+    });
+  };
+
+  const getToggleState = (toggleId: string) => {
+    const toggleState = togglesState[toggleId];
+
+    if (toggleState) {
+      return {
+        render: toggleState.render,
+        value: toggleState.value,
+      };
+    } else {
+      return null;
+    }
+  };
+
+  const [inputsState, setInputsState] = useState(() => {
+    const initialState: InputsState = {};
+
+    for (const [id, input] of Object.entries(inputs)) {
+      initialState[id] = {
+        ...input,
+        render: true,
+        type: 'input',
+        value: searchParams.get(id) || input.value,
+      };
+    }
+    return initialState;
+  });
+
+  const changeInputState = (inputId: string, value: string) => {
+    setInputsState((prev) => {
+      const input = prev[inputId];
+      if (input) {
+        return {
+          ...prev,
+          [inputId]: {
+            ...input,
+            value,
+          },
+        };
+      } else {
+        return prev;
+      }
+    });
+  };
+
+  const getInputState = (inputId: string) => {
+    const inputState = inputsState[inputId];
+
+    if (inputState) {
+      return {
+        render: inputState.render,
+        value: inputState.value,
+      };
+    } else {
+      return null;
+    }
+  };
+
+  const [filtersState, setFiltersState] = useState(() => {
+    const initialState: FiltersState = {};
+
+    for (const [id, filter] of Object.entries(filters)) {
+      initialState[id] = {
+        ...filter,
+        render: true,
+        type: 'filter',
+        value: searchParams.get(id) || filter?.items?.[0]?.value || '',
+      };
+    }
+
+    return initialState;
+  });
+
+  const changeFilterState = (filterId: string, value: string) => {
+    setFiltersState((prev) => {
+      const filter = prev[filterId];
+      if (filter) {
+        return {
+          ...prev,
+          [filterId]: {
+            ...filter,
+            value,
+          },
+        };
+      } else {
+        return prev;
+      }
+    });
+  };
+
+  const getFilterState = (filterId: string) => {
+    const filterState = filtersState[filterId];
+
+    if (filterState) {
+      return {
+        render: filterState.render,
+        value: filterState.value,
+      };
+    } else {
+      return null;
+    }
+  };
+
+  const state = {
+    ...filtersState,
+    ...togglesState,
+    ...inputsState,
+  };
+
+  const walkthroughContext = useMemo(() => {
+    const areConditionsMet = (conditions: CodeWalkthroughConditionsObject) =>
+      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?.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: CodeWalkthroughFile[]) =>
+      downloadCodeWalkthrough(files, state, inputsState);
+
+    const getFileText = (file: CodeWalkthroughFile) =>
+      getCodeWalkthroughFileText(file, state, inputsState);
+
+    const populateInputsWithValue = (node: string) => 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
+   */
+  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 {
+    getInputState,
+    changeInputState,
+
+    getToggleState,
+    changeToggleState,
+
+    getFilterState,
+    changeFilterState,
+
+    ...walkthroughContext,
+  };
+}

package/src/core/hooks/code-walkthrough/use-code-walkthrough-steps.ts

@@ -0,0 +1,165 @@
+import { useCallback, useEffect, useRef, useState, useMemo } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+
+import type { CodeWalkthroughStepAttr } from '@redocly/config';
+
+import { getAdjacentValues } from '@redocly/theme/core/utils';
+import { ACTIVE_STEP_QUERY_PARAM } from '@redocly/theme/core/constants';
+
+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 function useCodeWalkthroughSteps(steps: CodeWalkthroughStep[]): WalkthroughStepsState {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const searchParams = useMemo(() => new URLSearchParams(location.search), [location.search]);
+
+  const observerRef = useRef<IntersectionObserver | null>(null);
+  const filtersElementRef = useRef<HTMLDivElement>(null);
+  const lockObserver = useRef<boolean>(false);
+  // Track observed elements in case new observer needs to be created
+  const observedElementsRef = useRef(new Set<HTMLElement>());
+
+  const [activeStep, setActiveStep] = useState<ActiveStep>(
+    searchParams.get(ACTIVE_STEP_QUERY_PARAM),
+  );
+
+  const register = useCallback(
+    (element: HTMLElement) => {
+      // 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 = useCallback(
+    (element: HTMLElement) => {
+      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 = useCallback(
+    (entries: IntersectionObserverEntry[]) => {
+      if (lockObserver.current) {
+        return;
+      }
+
+      const stepsEntries = [];
+      for (const entry of entries) {
+        const { target } = entry;
+        const stepKey = Number((target as HTMLElement)?.dataset?.stepKey);
+        const stepActive = (target as HTMLElement)?.dataset?.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((target as HTMLElement)?.dataset?.stepKey);
+        const step = steps[stepKey];
+
+        const renderedSteps = steps.filter((step) => Boolean(step.compRef));
+        const stepIndex = renderedSteps.findIndex(
+          (renderedStep) => renderedStep.stepKey === step.stepKey,
+        );
+        const { next } = getAdjacentValues(renderedSteps, stepIndex);
+
+        const intersectionAtTop =
+          rootBounds?.bottom !== undefined && boundingClientRect.top < rootBounds.top;
+        const stepGoesIn = isIntersecting;
+
+        if (intersectionRatio < 1 && intersectionRatio !== 0 && intersectionAtTop) {
+          let newStep: string | null = null;
+
+          if (stepGoesIn) {
+            newStep = step.id;
+          } else if (next) {
+            newStep = next.id;
+          }
+
+          if (newStep !== activeStep) {
+            setActiveStep(newStep);
+          }
+
+          break;
+        }
+      }
+    },
+    [steps, activeStep],
+  );
+  useEffect(() => {
+    const filtersElementHeight = filtersElementRef.current?.clientHeight || 0;
+    const navbarHeight = document.querySelector('nav')?.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
+    observerRef.current?.disconnect();
+    observerRef.current = newObserver;
+  }, [observerCallback]);
+
+  /**
+   * Update the URL search params with the current state of the filters and inputs
+   */
+  useEffect(() => {
+    const newSearchParams = new URLSearchParams(Array.from(searchParams.entries()));
+
+    if (activeStep) {
+      newSearchParams.set(ACTIVE_STEP_QUERY_PARAM, activeStep);
+    } else {
+      newSearchParams.delete(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 };
+}

package/src/core/hooks/code-walkthrough/use-code-walkthrough.ts

@@ -0,0 +1,51 @@
+import type {
+  CodeWalkthroughFileset,
+  CodeWalkthroughFile,
+  CodeWalkthroughStepAttr,
+  CodeWalkthroughFilter,
+  InputsMarkdocAttr,
+  TogglesMarkdocAttr,
+} from '@redocly/config';
+
+import {
+  useCodeWalkthroughSteps,
+  useCodeWalkthroughControls,
+  type WalkthroughControlsState,
+  type WalkthroughStepsState,
+} from '@redocly/theme/core/hooks';
+
+export type WalkthroughState = {
+  stepsState: WalkthroughStepsState;
+  controlsState: WalkthroughControlsState;
+  downloadAssociatedFiles: CodeWalkthroughFile[];
+  files: CodeWalkthroughFile[];
+};
+
+export function useCodeWalkthrough(
+  steps: CodeWalkthroughStepAttr[],
+  attributes: {
+    filters: Record<string, CodeWalkthroughFilter>;
+    filesets: CodeWalkthroughFileset[];
+    inputs: InputsMarkdocAttr;
+    toggles: TogglesMarkdocAttr;
+  },
+): WalkthroughState {
+  const { filters, filesets, inputs, toggles } = attributes;
+  const stepsState = useCodeWalkthroughSteps(steps);
+  const controlsState = useCodeWalkthroughControls(filters, inputs, toggles);
+
+  const files: CodeWalkthroughFile[] = filesets
+    .filter((fileset) => controlsState.areConditionsMet(fileset))
+    .flatMap((fileset) => fileset.files || []);
+
+  const downloadAssociatedFiles: CodeWalkthroughFile[] = filesets
+    .filter((fileset) => controlsState.areConditionsMet(fileset))
+    .flatMap((fileset) => fileset.downloadAssociatedFiles || []);
+
+  return {
+    stepsState,
+    controlsState,
+    downloadAssociatedFiles,
+    files,
+  };
+}

package/src/core/hooks/index.ts

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