@redocly/theme 0.48.0 → 0.48.2

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

@@ -7,14 +7,9 @@ import type {
   InputsMarkdocAttr,
   TogglesMarkdocAttr,
   CodeWalkthroughControls,
-  TogglesState,
-  InputsState,
-  FiltersState,
   CodeWalkthroughFilterItem,
-  ControlState,
-  ControlTypeValue,
-  ControlType,
   CodeWalkthroughConditionsObject,
+  CodeWalkthroughControlsState,
 } from '@redocly/config';
 
 import {
@@ -24,8 +19,6 @@ import {
   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;
@@ -34,15 +27,8 @@ export type ActiveFilter = {
 
 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'>;
+  getControlState: (id: string) => { value: string | boolean; render: boolean } | null;
+  changeControlState: (id: string, value: string | boolean) => void;
   /* Utility */
   areConditionsMet: (conditions: CodeWalkthroughConditionsObject) => boolean;
   handleDownloadCode: (files: CodeWalkthroughFile[]) => Promise<void>;
@@ -60,163 +46,126 @@ export function useCodeWalkthroughControls(
   filters: Record<string, CodeWalkthroughFilter>,
   inputs: InputsMarkdocAttr,
   toggles: TogglesMarkdocAttr,
+  enableDeepLink: boolean,
 ): WalkthroughControlsState {
   const location = useLocation();
   const navigate = useNavigate();
   const searchParams = useMemo(() => new URLSearchParams(location.search), [location.search]);
 
-  const [togglesState, setTogglesState] = useState(() => {
-    const initialState: TogglesState = {};
+  const [controlsState, setControlsState] = useState(() => {
+    const initialState: CodeWalkthroughControlsState = {};
+
     for (const [id, toggle] of Object.entries(toggles)) {
       initialState[id] = {
         ...toggle,
         render: true,
         type: 'toggle',
-        value: searchParams.get(id) === 'true',
+        value: enableDeepLink ? searchParams.get(id) === 'true' : false,
       };
     }
-    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,
+        value: enableDeepLink ? (searchParams.get(id) ?? input.value) : 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)) {
+      const defaultValue = filter?.items?.[0]?.value || '';
       initialState[id] = {
         ...filter,
         render: true,
         type: 'filter',
-        value: searchParams.get(id) || filter?.items?.[0]?.value || '',
+        value: enableDeepLink ? (searchParams.get(id) ?? defaultValue) : defaultValue,
       };
     }
 
     return initialState;
   });
 
-  const changeFilterState = (filterId: string, value: string) => {
-    setFiltersState((prev) => {
-      const filter = prev[filterId];
-      if (filter) {
-        return {
-          ...prev,
-          [filterId]: {
-            ...filter,
-            value,
-          },
-        };
-      } else {
+  const changeControlState = (id: string, value: string | boolean) => {
+    setControlsState((prev) => {
+      const control = prev[id];
+      if (!control) {
+        console.error(`Control with id "${id}" not found.`);
         return prev;
       }
+
+      switch (control.type) {
+        case 'input':
+          if (typeof value !== 'string') {
+            console.error(
+              `Invalid value type for input "${id}". Input control type requires a string value.`,
+            );
+            return prev;
+          }
+          break;
+
+        case 'toggle':
+          if (typeof value !== 'boolean') {
+            console.error(
+              `Invalid value type for toggle "${id}". Toggle control type requires a boolean value.`,
+            );
+            return prev;
+          }
+          break;
+
+        case 'filter':
+          if (typeof value !== 'string') {
+            console.error(
+              `Invalid value type for filter "${id}". Filter control type requires a string value.`,
+            );
+            return prev;
+          }
+          break;
+
+        default:
+          console.error(
+            `Invalid control type "${(control as { type: string })?.type}" for control "${id}". Allowed types are "toggle", "input", or "filter".`,
+          );
+          return prev;
+      }
+
+      return {
+        ...prev,
+        [id]: {
+          ...control,
+          value,
+        },
+      } as CodeWalkthroughControlsState;
     });
   };
 
-  const getFilterState = (filterId: string) => {
-    const filterState = filtersState[filterId];
+  const getControlState = (id: string) => {
+    const controlState = controlsState[id];
 
-    if (filterState) {
+    if (controlState) {
       return {
-        render: filterState.render,
-        value: filterState.value,
+        render: controlState.render,
+        value: controlState.value,
       };
     } else {
       return null;
     }
   };
 
-  const state = {
-    ...filtersState,
-    ...togglesState,
-    ...inputsState,
-  };
-
   const walkthroughContext = useMemo(() => {
     const areConditionsMet = (conditions: CodeWalkthroughConditionsObject) =>
-      matchCodeWalkthroughConditions(conditions, state);
+      matchCodeWalkthroughConditions(conditions, controlsState);
 
-    for (const [id, element] of Object.entries(state)) {
-      if (element && !areConditionsMet(element)) {
-        state[id].render = false;
-        state[id].value = defaultControlsValues[element.type];
+    for (const [id, control] of Object.entries(controlsState)) {
+      if (control && !areConditionsMet(control)) {
+        controlsState[id].render = false;
+        controlsState[id].value = defaultControlsValues[control.type];
       }
     }
 
     const activeFilters = [];
     for (const [id, filter] of Object.entries(filters)) {
-      if (!filtersState[id].render) {
+      if (!controlsState[id].render) {
         continue;
       }
 
@@ -226,18 +175,18 @@ export function useCodeWalkthroughControls(
       const activeItems = items.filter((item) => areConditionsMet(item));
 
       if (activeItems.length === 0) {
-        filtersState[id].render = false;
-        filtersState[id].value = defaultControlsValues['filter'];
+        controlsState[id].render = false;
+        controlsState[id].value = defaultControlsValues['filter'];
         continue;
       }
 
-      const currentValue = filtersState[id].value;
+      const currentValue = controlsState[id].value;
       if (currentValue) {
         const isValueInActiveItems =
           activeItems.findIndex(({ value }) => value === currentValue) !== -1;
-        filtersState[id].value = isValueInActiveItems ? currentValue : activeItems[0].value;
+        controlsState[id].value = isValueInActiveItems ? currentValue : activeItems[0].value;
       } else {
-        filtersState[id].value = activeItems[0].value;
+        controlsState[id].value = activeItems[0].value;
       }
 
       activeFilters.push({
@@ -247,11 +196,15 @@ export function useCodeWalkthroughControls(
       });
     }
 
+    const inputsState = Object.fromEntries(
+      Object.entries(controlsState).filter(([_, controlState]) => controlState.type === 'input'),
+    ) as Record<string, { value: string }>;
+
     const handleDownloadCode = (files: CodeWalkthroughFile[]) =>
-      downloadCodeWalkthrough(files, state, inputsState);
+      downloadCodeWalkthrough(files, controlsState, inputsState);
 
     const getFileText = (file: CodeWalkthroughFile) =>
-      getCodeWalkthroughFileText(file, state, inputsState);
+      getCodeWalkthroughFileText(file, controlsState, inputsState);
 
     const populateInputsWithValue = (node: string) => replaceInputsWithValue(node, inputsState);
 
@@ -262,17 +215,19 @@ export function useCodeWalkthroughControls(
       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]);
+  }, [filters, controlsState]);
 
   /**
    * Update the URL search params with the current state of the filters and inputs
    */
   useEffect(() => {
+    if (!enableDeepLink) {
+      return;
+    }
+
     const newSearchParams = new URLSearchParams(Array.from(searchParams.entries()));
 
-    for (const [id, { value }] of Object.entries(state)) {
+    for (const [id, { value }] of Object.entries(controlsState)) {
       if (value) {
         newSearchParams.set(id, value.toString());
       } else {
@@ -285,18 +240,11 @@ export function useCodeWalkthroughControls(
     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]);
+  }, [filters, controlsState, navigate, location]);
 
   return {
-    getInputState,
-    changeInputState,
-
-    getToggleState,
-    changeToggleState,
-
-    getFilterState,
-    changeFilterState,
-
+    changeControlState,
+    getControlState,
     ...walkthroughContext,
   };
 }

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

@@ -8,9 +8,9 @@ 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;
@@ -20,7 +20,10 @@ export type WalkthroughStepsState = {
   filtersElementRef?: React.RefObject<HTMLDivElement>;
 };
 
-export function useCodeWalkthroughSteps(steps: CodeWalkthroughStep[]): WalkthroughStepsState {
+export function useCodeWalkthroughSteps(
+  steps: CodeWalkthroughStep[],
+  enableDeepLink: boolean,
+): WalkthroughStepsState {
   const location = useLocation();
   const navigate = useNavigate();
   const searchParams = useMemo(() => new URLSearchParams(location.search), [location.search]);
@@ -32,7 +35,7 @@ export function useCodeWalkthroughSteps(steps: CodeWalkthroughStep[]): Walkthrou
   const observedElementsRef = useRef(new Set<HTMLElement>());
 
   const [activeStep, setActiveStep] = useState<ActiveStep>(
-    searchParams.get(ACTIVE_STEP_QUERY_PARAM),
+    enableDeepLink ? searchParams.get(ACTIVE_STEP_QUERY_PARAM) : null,
   );
 
   const register = useCallback(
@@ -74,28 +77,23 @@ export function useCodeWalkthroughSteps(steps: CodeWalkthroughStep[]): Walkthrou
         return;
       }
 
-      const stepsEntries = [];
+      const renderedSteps = steps.filter((step) => Boolean(step.compRef));
+
+      if (renderedSteps.length < 2) {
+        setActiveStep(renderedSteps[0]?.id || null);
+        return;
+      }
+
       for (const entry of entries) {
-        const { target } = entry;
-        const stepKey = Number((target as HTMLElement)?.dataset?.stepKey);
-        const stepActive = (target as HTMLElement)?.dataset?.stepActive === 'true';
+        const stepKey = Number((entry.target as HTMLElement)?.dataset?.stepKey);
 
         if (!Number.isInteger(stepKey) || stepKey < 0) {
           continue;
         }
 
+        const { intersectionRatio, boundingClientRect, rootBounds, isIntersecting } = entry;
         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,
         );
@@ -105,6 +103,16 @@ export function useCodeWalkthroughSteps(steps: CodeWalkthroughStep[]): Walkthrou
           rootBounds?.bottom !== undefined && boundingClientRect.top < rootBounds.top;
         const stepGoesIn = isIntersecting;
 
+        if (
+          intersectionRatio > 0.8 &&
+          intersectionRatio < 1 &&
+          intersectionAtTop &&
+          activeStep === null
+        ) {
+          setActiveStep(step.id);
+          break;
+        }
+
         if (intersectionRatio < 1 && intersectionRatio !== 0 && intersectionAtTop) {
           let newStep: string | null = null;
 
@@ -128,7 +136,7 @@ export function useCodeWalkthroughSteps(steps: CodeWalkthroughStep[]): Walkthrou
     const filtersElementHeight = filtersElementRef.current?.clientHeight || 0;
     const navbarHeight = document.querySelector('nav')?.clientHeight || 0;
     const newObserver = new IntersectionObserver(observerCallback, {
-      threshold: [0.8],
+      threshold: [0.8, 0.85, 0.9, 0.95],
       rootMargin: `-${filtersElementHeight + navbarHeight}px 0px 0px 0px`,
     });
 
@@ -145,6 +153,10 @@ export function useCodeWalkthroughSteps(steps: CodeWalkthroughStep[]): Walkthrou
    * Update the URL search params with the current state of the filters and inputs
    */
   useEffect(() => {
+    if (!enableDeepLink) {
+      return;
+    }
+
     const newSearchParams = new URLSearchParams(Array.from(searchParams.entries()));
 
     if (activeStep) {

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

@@ -1,10 +1,7 @@
 import type {
-  CodeWalkthroughFileset,
   CodeWalkthroughFile,
   CodeWalkthroughStepAttr,
-  CodeWalkthroughFilter,
-  InputsMarkdocAttr,
-  TogglesMarkdocAttr,
+  CodeWalkthroughAttr,
 } from '@redocly/config';
 
 import {
@@ -23,16 +20,19 @@ export type WalkthroughState = {
 
 export function useCodeWalkthrough(
   steps: CodeWalkthroughStepAttr[],
-  attributes: {
-    filters: Record<string, CodeWalkthroughFilter>;
-    filesets: CodeWalkthroughFileset[];
-    inputs: InputsMarkdocAttr;
-    toggles: TogglesMarkdocAttr;
-  },
+  attributes: Omit<CodeWalkthroughAttr, 'steps' | 'preview'>,
 ): WalkthroughState {
-  const { filters, filesets, inputs, toggles } = attributes;
-  const stepsState = useCodeWalkthroughSteps(steps);
-  const controlsState = useCodeWalkthroughControls(filters, inputs, toggles);
+  const { filters, filesets, inputs, toggles, __idx } = attributes;
+  /* 
+    We only enable deep linking for the first CodeWalkthrough, 
+    because we don't expect more than one on the same page. 
+    Any subsequent walkthroughs have it disabled to avoid 
+    collisions/conflicts in the URL.
+  */
+  const enableDeepLink = __idx === 1;
+
+  const stepsState = useCodeWalkthroughSteps(steps, enableDeepLink);
+  const controlsState = useCodeWalkthroughControls(filters, inputs, toggles, enableDeepLink);
 
   const files: CodeWalkthroughFile[] = filesets
     .filter((fileset) => controlsState.areConditionsMet(fileset))

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

@@ -0,0 +1,51 @@
+import { useMemo } from 'react';
+
+import type { CodeWalkthroughFile } from '@redocly/config';
+import type { IconProps } from '@redocly/theme/icons/types';
+
+import {
+  getFileIconByExt,
+  removeLeadingSlash,
+  findClosestCommonDirectory,
+} from '@redocly/theme/core/utils';
+
+export type RenderableFile = CodeWalkthroughFile & {
+  FileIcon: React.FunctionComponent<IconProps>;
+  parentFolder: string;
+  isNameDuplicate: boolean;
+  inRootDir: boolean;
+};
+
+export function useRenderableFiles(files: CodeWalkthroughFile[]): RenderableFile[] {
+  return useMemo(
+    function () {
+      const filePaths = files.map(({ path }) => path);
+      const rootDir = findClosestCommonDirectory(filePaths);
+
+      const renderableFiles = files.map((file) => {
+        const FileIcon = getFileTypeIcon(file.basename);
+        const parentFolder = file.path.split('/').slice(-2, -1)[0];
+        const isNameDuplicate = files.some(
+          (_file) => file.basename === _file.basename && file.path !== _file.path,
+        );
+        const inRootDir = file.path === `${removeLeadingSlash(rootDir)}/${file.basename}`;
+
+        return {
+          ...file,
+          FileIcon,
+          inRootDir,
+          parentFolder,
+          isNameDuplicate,
+        };
+      });
+
+      return renderableFiles;
+    },
+    [files],
+  );
+}
+
+function getFileTypeIcon(basename: string) {
+  const extension = basename.split('.').pop()?.toLowerCase() || '';
+  return getFileIconByExt(extension);
+}

package/src/core/hooks/index.ts

@@ -32,3 +32,4 @@ 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';
+export * from '@redocly/theme/core/hooks/code-walkthrough/use-renderable-files';

package/src/core/styles/global.ts

@@ -1019,6 +1019,24 @@ const error = css`
   --detailed-error-message-width: 100%;
   --detailed-error-message-font-size: var(--font-size-base);
   --detailed-error-message-font-family: var(--code-block-controls-font-family);
+    
+  --compilation-error-description-padding: 0 0 var(--spacing-base);
+  --compilation-error-codeframe-margin: var(--spacing-xs) 0 0 0;
+  --compilation-error-codeframe-padding: var(--spacing-xs);
+  --compilation-error-block-padding: var(--spacing-base);
+  --compilation-error-block-margin: var(--spacing-xl) 0;
+  --compilation-error-title-font-size: var(--font-size-xl);
+  --compilation-error-header-font-size: var(--font-size-lg);
+  --compilation-error-text-font-size: var(--font-size-base);
+  --compilation-error-header-padding: var(--spacing-sm);
+  --compilation-error-container-margin: var(--spacing-xxl) auto;
+  --compilation-error-container-padding: var(--spacing-lg);
+  --compilation-error-page-max-width: 800px;
+  --compilation-error-font-family: var(--font-family-base);  
+  --compilation-error-fix-instruction-margin: var(--spacing-sm) 0 0 0;
+  --compilation-error-highlighted-text-padding: 0 var(--spacing-xxs);
+  --compilation-error-divider-margin: var(--spacing-base) 0;
+  --compilation-error-file-header-margin: 0 0 var(--spacing-xs) 0;
 `;
 
 const modal = css`

package/src/core/types/l10n.ts

@@ -85,8 +85,9 @@ export type TranslationKey =
   | 'search.filter.field.reset'
   | 'search.ai.thinkingText'
   | 'search.ai.resourcesFound'
-  | 'search.aiButton'
+  | 'search.ai.button'
   | 'search.ai.label'
+  | 'search.ai.disclaimer'
   | 'toc.header'
   | 'footer.copyrightText'
   | 'page.homeButton'
@@ -196,6 +197,7 @@ export type TranslationKey =
   | 'openapi.expandAll'
   | 'openapi.collapseAll'
   | 'openapi.noResponseExample'
+  | 'openapi.noResponseContent'
   | 'openapi.noRequestPayload'
   | 'openapi.hidePattern'
   | 'openapi.showPattern'

package/src/core/utils/download-code-walkthrough.ts

@@ -1,9 +1,13 @@
 import { saveAs } from 'file-saver';
 import JSZip from 'jszip';
 
-import type { CodeWalkthroughFile, InputsState } from '@redocly/config';
+import type { CodeWalkthroughFile } from '@redocly/config';
 
-import { getCodeWalkthroughFileText } from '@redocly/theme/core/utils';
+import {
+  findClosestCommonDirectory,
+  getCodeWalkthroughFileText,
+  removeLeadingSlash,
+} from '@redocly/theme/core/utils';
 
 // https://github.com/Stuk/jszip/issues/196#issuecomment-69503828
 JSZip.support.nodebuffer = false;
@@ -11,13 +15,21 @@ JSZip.support.nodebuffer = false;
 export async function downloadCodeWalkthrough(
   files: CodeWalkthroughFile[],
   state: Record<string, { value: string | boolean }>,
-  inputsState: InputsState,
+  inputsState: Record<string, { value: string }>,
 ) {
   const zip = new JSZip();
 
+  const filePaths = files.map(({ path }) => path);
+  const commonClosestDirectory = findClosestCommonDirectory(filePaths);
+
   for (const file of files) {
     const fileContent = getCodeWalkthroughFileText(file, state, inputsState);
-    zip.file(file.basename, fileContent);
+    if (commonClosestDirectory === '/') {
+      zip.file(file.path, fileContent);
+    } else {
+      const filePath = file.path.replace(removeLeadingSlash(`${commonClosestDirectory}/`), '');
+      zip.file(filePath, fileContent);
+    }
   }
 
   const zipContent = await zip.generateAsync({ type: 'blob' });