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

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

@@ -2,28 +2,31 @@ import { useCallback, useEffect, useRef, useState, useMemo } from 'react';
 import { useLocation, useNavigate } from 'react-router-dom';
 
 import type { CodeWalkthroughStepAttr } from '@redocly/config';
+import type { ActiveStep, MarkerArea, WalkthroughStepsState } from '@redocly/theme/core/types';
 
-import { getAdjacentValues } from '@redocly/theme/core/utils';
+import { getAdjacentValues, insertAt, isBrowser, removeElement } from '@redocly/theme/core/utils';
 import { ACTIVE_STEP_QUERY_PARAM } from '@redocly/theme/core/constants';
 
-type ActiveStep = string | null;
 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 StepWithIndex = CodeWalkthroughStep & {
+  index: number;
 };
 
-export function useCodeWalkthroughSteps(
-  steps: CodeWalkthroughStep[],
-  enableDeepLink: boolean,
-): WalkthroughStepsState {
+type Params = {
+  steps: CodeWalkthroughStep[];
+  enableDeepLink: boolean;
+  root: React.RefObject<HTMLDivElement | null>;
+};
+
+export function useCodeWalkthroughSteps({
+  steps,
+  enableDeepLink,
+  root,
+}: Params): WalkthroughStepsState {
   const location = useLocation();
   const navigate = useNavigate();
   const searchParams = useMemo(() => new URLSearchParams(location.search), [location.search]);
@@ -38,80 +41,169 @@ export function useCodeWalkthroughSteps(
     enableDeepLink ? searchParams.get(ACTIVE_STEP_QUERY_PARAM) : null,
   );
 
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  const _steps = useMemo(() => steps, [JSON.stringify(steps)]);
-
-  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]) {
-            _steps[stepKey].compRef = element;
-          }
+  const stepsMap = useMemo(() => {
+    const map = new Map<string, StepWithIndex>();
+    steps.forEach((step, index) => {
+      map.set(step.id, { ...step, index });
+    });
+
+    return map;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(steps)]);
+
+  const options = useMemo(() => {
+    if (!isBrowser()) {
+      return null;
+    }
+
+    const filtersElementHeight = filtersElementRef.current?.clientHeight || 0;
+    const navbarHeight = document.querySelector('nav')?.getBoundingClientRect().height || 0;
+
+    return {
+      filtersElementHeight,
+      navbarHeight,
+    };
+  }, []);
+
+  const [visibleSteps, setVisibleSteps] = useState<StepWithIndex[]>([]);
+
+  const [markers, setMarkers] = useState<Record<string, MarkerArea>>({});
+
+  useEffect(() => {
+    if (!root.current || !visibleSteps.length || !options) {
+      return;
+    }
+
+    const markersMinTopOffset = options.filtersElementHeight + options.navbarHeight;
+
+    const rootHeight = root.current?.clientHeight ?? 0;
+    const lastStepOffset = visibleSteps[visibleSteps.length - 1]?.compRef?.offsetTop ?? 0;
+    const deficit = Math.max(lastStepOffset - (rootHeight - window.innerHeight), 0);
+
+    const groups = getGroups(visibleSteps);
+    let markers: number[] = groups.flatMap((group) => getGroupMarkers(group));
+
+    if (deficit) {
+      const startOffset = markersMinTopOffset;
+      const endOffset = Math.max(rootHeight - window.innerHeight, 0);
 
-          observerRef.current.observe(element);
-          observedElementsRef.current.add(element);
+      markers = distributeMarkers({
+        endOffset,
+        markers,
+        startOffset: markersMinTopOffset < endOffset ? startOffset : 0,
+      });
+    }
+
+    setMarkers(
+      markers.reduce(
+        (acc, marker, index) => {
+          const step = visibleSteps[index];
+          acc[step.id] = {
+            offset: marker,
+            height:
+              markers[index + 1] || !step.compRef
+                ? (markers[index + 1] ?? rootHeight) - marker
+                : step.compRef.clientHeight,
+          };
+          return acc;
+        },
+        {} as Record<string, MarkerArea>,
+      ),
+    );
+
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [visibleSteps, root.current, options]);
+
+  const registerMarker = useCallback(
+    (stepId: string, element: HTMLElement) => {
+      if (observerRef.current) {
+        const step = stepsMap.get(stepId);
+        if (step) {
+          step.markerRef = element;
         }
-      }, 10);
+
+        observerRef.current.observe(element);
+        observedElementsRef.current.add(element);
+      }
     },
-    [_steps],
+    [stepsMap],
   );
 
-  const unregister = useCallback(
-    (element: HTMLElement) => {
+  const removeMarker = useCallback(
+    (stepId: string, element: HTMLElement) => {
       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 = useCallback(
+    (stepId: string, element: HTMLElement) => {
+      const step = stepsMap.get(stepId);
+      if (!step) {
+        return;
+      }
+
+      step.compRef = element;
+      setVisibleSteps((prevSteps) => insertAt(prevSteps, step.index, step));
+    },
+    [stepsMap],
+  );
+
+  const removeStep = useCallback(
+    (stepId: string) => {
+      const step = stepsMap.get(stepId);
+      if (!step) {
+        return;
+      }
+
+      step.compRef = undefined;
+      setVisibleSteps((prevSteps) => removeElement(prevSteps, step));
+      setActiveStep((prevStep) => (prevStep === stepId ? null : prevStep));
+    },
+    [stepsMap],
   );
 
   const observerCallback = useCallback(
     (entries: IntersectionObserverEntry[]) => {
-      if (lockObserver.current) {
+      if (lockObserver.current || !visibleSteps.length) {
         return;
       }
 
-      const renderedSteps = _steps.filter((step) => Boolean(step.compRef));
-
-      if (renderedSteps.length < 2) {
-        setActiveStep(renderedSteps[0]?.id || null);
+      if (visibleSteps.length < 2) {
+        setActiveStep(visibleSteps[0]?.id || null);
         return;
       }
 
       for (const entry of entries) {
-        const stepKey = Number((entry.target as HTMLElement)?.dataset?.stepKey);
+        const stepId = (entry.target as HTMLElement)?.dataset?.stepId;
 
-        if (!Number.isInteger(stepKey) || stepKey < 0) {
+        if (!stepId) {
           continue;
         }
 
         const { intersectionRatio, boundingClientRect, rootBounds, isIntersecting } = entry;
-        const step = _steps[stepKey];
+        const step = stepsMap.get(stepId);
 
-        const stepIndex = renderedSteps.findIndex(
-          (renderedStep) => renderedStep.stepKey === step.stepKey,
-        );
-        const { next } = getAdjacentValues(renderedSteps, stepIndex);
+        if (!step) {
+          continue;
+        }
+
+        const stepIndex = visibleSteps.findIndex((renderedStep) => renderedStep.id === stepId);
+        const { next } = getAdjacentValues(visibleSteps, stepIndex);
 
         const intersectionAtTop =
           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;
         }
@@ -125,32 +217,45 @@ export function useCodeWalkthroughSteps(
             newStep = next.id;
           }
 
-          if (newStep !== activeStep) {
-            setActiveStep(newStep);
-          }
+          setActiveStep((prevStep) => newStep || prevStep);
 
           break;
         }
       }
     },
-    [_steps, activeStep],
+    [stepsMap, visibleSteps],
   );
+
   useEffect(() => {
-    const filtersElementHeight = filtersElementRef.current?.clientHeight || 0;
-    const navbarHeight = document.querySelector('nav')?.clientHeight || 0;
+    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
     observerRef.current?.disconnect();
     observerRef.current = newObserver;
-  }, [observerCallback]);
+  }, [observerCallback, markers, options]);
+
+  useEffect(() => {
+    if (!options) {
+      return;
+    }
+
+    const rootTopOffset = root.current?.offsetTop ?? 0;
+    if (!activeStep && rootTopOffset <= options.navbarHeight) {
+      setActiveStep(visibleSteps[0]?.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
@@ -176,5 +281,161 @@ export function useCodeWalkthroughSteps(
     // 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,
+  };
+}
+
+type StepsGroup = {
+  freeSpace: number;
+  usedSpace: number;
+  offset: number;
+  steps: { offset: number; height: number }[];
+};
+/**
+ * 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: CodeWalkthroughStep[]): StepsGroup[] {
+  if (!steps.length) {
+    return [];
+  }
+
+  const firstStepOffset = steps[0]?.compRef?.offsetTop ?? 0;
+  const firstStepHeight = steps[0]?.compRef?.clientHeight ?? 0;
+  const secondStepOffset = steps[1]?.compRef?.offsetTop ?? 0;
+  const margin = Math.max(secondStepOffset - firstStepOffset - firstStepHeight, 0);
+
+  let groupIndex = 0;
+  const groups: StepsGroup[] = [
+    {
+      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 = step.compRef?.clientHeight ?? 0;
+    const stepOffset = step.compRef?.offsetTop ?? 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,
+    } as any);
+    currentGroup.usedSpace += stepHeight + margin;
+  }
+
+  return groups;
+}
+
+export function getGroupMarkers(group: StepsGroup) {
+  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 = [],
+}: {
+  startOffset: number;
+  endOffset: number;
+  markers: number[];
+  additionalSteps?: ((marker: number) => number)[];
+}) {
+  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: { min: number; max: number; value: number }) {
+  const { min, max, value } = options;
+
+  return (value - min) / (max - min);
 }

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

@@ -3,12 +3,12 @@ import type {
   CodeWalkthroughStepAttr,
   CodeWalkthroughAttr,
 } from '@redocly/config';
+import type { WalkthroughStepsState } from '@redocly/theme/core/types';
 
 import {
   useCodeWalkthroughSteps,
   useCodeWalkthroughControls,
   type WalkthroughControlsState,
-  type WalkthroughStepsState,
 } from '@redocly/theme/core/hooks';
 
 export type WalkthroughState = {
@@ -18,10 +18,13 @@ export type WalkthroughState = {
   files: CodeWalkthroughFile[];
 };
 
-export 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 function useCodeWalkthrough({ steps, attributes, root }: Params): WalkthroughState {
   const { filters, filesets, inputs, toggles, __idx } = attributes;
   /* 
     We only enable deep linking for the first CodeWalkthrough, 
@@ -31,7 +34,7 @@ export function useCodeWalkthrough(
   */
   const enableDeepLink = __idx === 1;
 
-  const stepsState = useCodeWalkthroughSteps(steps, enableDeepLink);
+  const stepsState = useCodeWalkthroughSteps({ steps, enableDeepLink, root });
   const controlsState = useCodeWalkthroughControls(filters, inputs, toggles, enableDeepLink);
 
   const files: CodeWalkthroughFile[] = filesets

package/src/core/hooks/index.ts

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

package/src/core/hooks/{use-page-active-version.ts → use-active-page-version.ts}

@@ -1,6 +1,6 @@
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 
-export function usePageActiveVersion(): string | undefined {
+export function useActivePageVersion(): string | undefined {
   const { usePageVersions } = useThemeHooks();
   const { versions } = usePageVersions();
   const activeVersion = versions.find((version) => version.active);

package/src/core/types/code-walkthrough.ts

@@ -0,0 +1,15 @@
+import type { MarkerArea } from '@redocly/theme/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/src/core/types/index.ts

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

package/src/core/types/marker.ts

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

package/src/core/utils/js-utils.ts

@@ -71,3 +71,34 @@ export function getAdjacentValues<T>(
 
   return { prev: prevValue, next: nextValue };
 }
+
+/**
+ * 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 function insertAt<T>(array: T[], index: number, newElement: T): T[] {
+  const result = array.concat();
+  result.splice(index, 0, newElement);
+  return result;
+}
+
+/**
+ * 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 function removeElement<T>(array: T[], item: T): T[] {
+  const index = array.indexOf(item);
+  if (index === -1) return array;
+
+  const result = array.slice();
+  result.splice(index, 1);
+  return result;
+}

package/src/index.ts

@@ -23,6 +23,7 @@ export * from '@redocly/theme/components/Tooltip/Tooltip';
 export * from '@redocly/theme/components/Tags/HttpTag';
 export * from '@redocly/theme/components/Tags/CounterTag';
 export * from '@redocly/theme/components/VersionPicker/VersionPicker';
+export * from '@redocly/theme/components/Marker/Marker';
 /* Buttons */
 export * from '@redocly/theme/components/Buttons/CopyButton';
 export * from '@redocly/theme/components/Buttons/EditPageButton';