@redocly/theme 0.48.0 → 0.48.2

package/src/core/utils/find-closest-common-directory.ts

@@ -0,0 +1,51 @@
+/**
+ * Splits a file path into its directory components, removing the file name.
+ * @param path - The full file path.
+ * @returns An array of directories.
+ */
+function splitPath(path: string): string[] {
+  const parts = path.split('/').filter(Boolean);
+  parts.pop();
+  return parts;
+}
+
+/**
+ * Finds the longest common prefix between two paths.
+ * @param path1 - The first path as an array of directories.
+ * @param path2 - The second path as an array of directories.
+ * @returns An array representing the common prefix.
+ */
+function findCommonPrefix(path1: string[], path2: string[]): string[] {
+  const common: string[] = [];
+  for (let i = 0; i < Math.min(path1.length, path2.length); i++) {
+    if (path1[i] === path2[i]) {
+      common.push(path1[i]);
+    } else {
+      break;
+    }
+  }
+  return common;
+}
+
+/**
+ * Finds the closest common directory for a set of file paths.
+ * @param paths - An array of absolute file paths.
+ * @returns The closest common directory as a string.
+ */
+export function findClosestCommonDirectory(paths: string[]): string {
+  if (paths.length === 0) {
+    return '/';
+  }
+
+  const splitPaths = paths.map(splitPath);
+  let commonPrefix = splitPaths[0];
+
+  for (let i = 1; i < splitPaths.length; i++) {
+    commonPrefix = findCommonPrefix(commonPrefix, splitPaths[i]);
+    if (commonPrefix.length === 0) {
+      return '/';
+    }
+  }
+
+  return '/' + commonPrefix.join('/');
+}

package/src/core/utils/get-code-walkthrough-file-text.ts

@@ -1,11 +1,11 @@
-import type { CodeWalkthroughFile, CodeWalkthroughNode, InputsState } from '@redocly/config';
+import type { CodeWalkthroughFile, CodeWalkthroughNode } from '@redocly/config';
 
 import { matchCodeWalkthroughConditions, replaceInputsWithValue } from '@redocly/theme/core/utils';
 
 export function getCodeWalkthroughFileText(
   file: CodeWalkthroughFile,
   state: Record<string, { value: string | boolean }>,
-  inputsState: InputsState,
+  inputsState: Record<string, { value: string }>,
 ) {
   const contentChunks: string[] =
     file?.content.flatMap((node) => getChunkText(node, state, inputsState)) ?? [];
@@ -16,7 +16,7 @@ export function getCodeWalkthroughFileText(
 function getChunkText(
   node: CodeWalkthroughNode,
   state: Record<string, { value: string | boolean }>,
-  inputsState: InputsState,
+  inputsState: Record<string, { value: string }>,
 ): string[] {
   if (typeof node === 'string') {
     const replacedNode = replaceInputsWithValue(node, inputsState);

package/src/core/utils/get-file-icon.ts

@@ -10,6 +10,9 @@ import { DocumentHtmlIcon } from '@redocly/theme/icons/DocumentHtmlIcon/Document
 import { DocumentReactIcon } from '@redocly/theme/icons/DocumentReactIcon/DocumentReactIcon';
 import { DocumentMarkdownIcon } from '@redocly/theme/icons/DocumentMarkdownIcon/DocumentMarkdownIcon';
 import { DocumentGraphqlIcon } from '@redocly/theme/icons/DocumentGraphqlIcon/DocumentGraphqlIcon';
+import { DocumentPythonIcon } from '@redocly/theme/icons/DocumentPythonIcon/DocumentPythonIcon';
+import { DocumentShellIcon } from '@redocly/theme/icons/DocumentShellIcon/DocumentShellIcon';
+import { DocumentJavaIcon } from '@redocly/theme/icons/DocumentJavaIcon/DocumentJavaIcon';
 
 const fileIconMap: Record<string, React.FunctionComponent<IconProps>> = {
   yaml: DocumentYamlIcon,
@@ -28,6 +31,10 @@ const fileIconMap: Record<string, React.FunctionComponent<IconProps>> = {
 
   graphql: DocumentGraphqlIcon,
   gql: DocumentGraphqlIcon,
+
+  py: DocumentPythonIcon,
+  sh: DocumentShellIcon,
+  java: DocumentJavaIcon,
 };
 
 export function getFileIconByExt(ext: string) {

package/src/core/utils/index.ts

@@ -30,3 +30,4 @@ export * from '@redocly/theme/core/utils/download-code-walkthrough';
 export * from '@redocly/theme/core/utils/get-file-icon';
 export * from '@redocly/theme/core/utils/match-code-walkthrough-conditions';
 export * from '@redocly/theme/core/utils/replace-inputs-with-value';
+export * from '@redocly/theme/core/utils/find-closest-common-directory';

package/src/core/utils/replace-inputs-with-value.ts

@@ -1,11 +1,14 @@
-const inputRegex = /(?:\/\*|<!--|#|\/\/)\s*@redocly-input\s*\{"id":\s*"(.*?)"\}\s*(?:\*\/|-->)?/g;
+export function replaceInputsWithValue(node: string, inputs: Record<string, { value?: string }>) {
+  const validKeys = Object.entries(inputs)
+    .filter(([_, input]) => input.value)
+    .map(([key]) => key)
+    .join('|');
 
-export function replaceInputsWithValue(node: string, inputs: Record<string, { value: string }>) {
-  return node.replace(inputRegex, (match, inputKey) => {
-    if (Object.prototype.hasOwnProperty.call(inputs, inputKey)) {
-      return inputs[inputKey]?.value;
-    } else {
-      return match;
-    }
-  });
+  if (!validKeys) {
+    return node;
+  }
+
+  const inputRegex = new RegExp(`\\{\\{\\s*(${validKeys})\\s*\\}\\}`, 'g');
+
+  return node.replace(inputRegex, (_, inputKey) => inputs[inputKey]?.value as string);
 }

package/src/icons/DocumentJavaIcon/DocumentJavaIcon.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { IconProps } from '@redocly/theme/icons/types';
+
+import { getCssColorVariable } from '@redocly/theme/core/utils';
+
+const Icon = (props: IconProps) => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M2 13H14V14H2V13ZM14 2H3.5C3.36739 2 3.24021 2.05268 3.14645 2.14645C3.05268 2.24021 3 2.36739 3 2.5V9C3 9.53043 3.21071 10.0391 3.58579 10.4142C3.96086 10.7893 4.46957 11 5 11H10C10.5304 11 11.0391 10.7893 11.4142 10.4142C11.7893 10.0391 12 9.53043 12 9V7H14C14.2652 7 14.5196 6.89464 14.7071 6.70711C14.8946 6.51957 15 6.26522 15 6V3C15 2.73478 14.8946 2.48043 14.7071 2.29289C14.5196 2.10536 14.2652 2 14 2ZM14 6H12V3H14V6Z"
+      fill="#3B3C45"
+    />
+  </svg>
+);
+
+export const DocumentJavaIcon = styled(Icon).attrs(() => ({
+  'data-component-name': 'icons/DocumentJavaIcon/DocumentJavaIcon',
+}))<IconProps>`
+  path {
+    fill: ${({ color }) => getCssColorVariable(color)};
+  }
+
+  height: ${({ size }) => size || '16px'};
+  width: ${({ size }) => size || '16px'};
+`;

package/src/icons/DocumentJavaIcon/index.ts

@@ -0,0 +1 @@
+export { DocumentJavaIcon } from '@redocly/theme/icons/DocumentJavaIcon/DocumentJavaIcon';

package/src/icons/DocumentPythonIcon/DocumentPythonIcon.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { IconProps } from '@redocly/theme/icons/types';
+
+import { getCssColorVariable } from '@redocly/theme/core/utils';
+
+const Icon = (props: IconProps) => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M6.57325 1.33301C6.06757 1.33301 5.5826 1.53389 5.22504 1.89146C4.86747 2.24903 4.66659 2.734 4.66659 3.23967V4.35967H7.52659C7.78659 4.35967 7.99992 4.73967 7.99992 4.99967H3.23992C2.73424 4.99967 2.24927 5.20055 1.8917 5.55812C1.53413 5.91569 1.33325 6.40066 1.33325 6.90634V9.42701C1.33325 9.93269 1.53413 10.4177 1.8917 10.7752C2.24927 11.1328 2.73424 11.3337 3.23992 11.3337H4.02659V9.54701C4.02571 9.29694 4.07421 9.04915 4.1693 8.81786C4.26439 8.58657 4.4042 8.37633 4.58072 8.19919C4.75724 8.02206 4.96699 7.88151 5.19794 7.78561C5.4289 7.6897 5.67651 7.64034 5.92659 7.64034H9.42659C10.4799 7.64034 11.3333 6.79301 11.3333 5.73967V3.23967C11.3333 2.734 11.1324 2.24903 10.7748 1.89146C10.4172 1.53389 9.93227 1.33301 9.42659 1.33301H6.57325ZM6.09325 2.40634C6.35992 2.40634 6.57325 2.48634 6.57325 2.87967C6.57325 3.27301 6.35992 3.47367 6.09325 3.47367C5.83325 3.47367 5.61992 3.27367 5.61992 2.88034C5.61992 2.48701 5.83325 2.40634 6.09325 2.40634Z"
+      fill="#3B3C45"
+    />
+    <path
+      d="M11.9727 4.66699V6.45366C11.9735 6.70367 11.925 6.95139 11.8298 7.1826C11.7347 7.41381 11.5949 7.62397 11.4184 7.80104C11.2419 7.97811 11.0321 8.1186 10.8012 8.21446C10.5703 8.31032 10.3228 8.35966 10.0727 8.35966H6.57341C6.32334 8.35878 6.07556 8.40728 5.84427 8.50237C5.61298 8.59746 5.40274 8.73727 5.2256 8.91379C5.04846 9.09031 4.90791 9.30006 4.81201 9.53102C4.71611 9.76197 4.66675 10.0096 4.66675 10.2597V12.7597C4.66675 13.2653 4.86763 13.7503 5.2252 14.1079C5.58277 14.4654 6.06774 14.6663 6.57341 14.6663H9.42675C9.93231 14.6663 10.4172 14.4655 10.7747 14.1081C11.1323 13.7507 11.3332 13.2659 11.3334 12.7603V11.6403H8.47275C8.21275 11.6403 8.00008 11.2603 8.00008 11.0003H12.7601C13.2658 11.0003 13.7507 10.7994 14.1083 10.4419C14.4659 10.0843 14.6667 9.59934 14.6667 9.09366V6.57366C14.6667 6.06798 14.4659 5.58301 14.1083 5.22544C13.7507 4.86787 13.2658 4.66699 12.7601 4.66699H11.9727ZM5.54675 7.67566L5.54408 7.67833L5.56941 7.67566H5.54675ZM9.90675 12.5263C10.1667 12.5263 10.3801 12.7263 10.3801 13.1197C10.3801 13.1818 10.3678 13.2434 10.3441 13.3008C10.3203 13.3582 10.2854 13.4104 10.2414 13.4544C10.1975 13.4983 10.1453 13.5332 10.0879 13.557C10.0305 13.5807 9.96891 13.593 9.90675 13.593C9.64008 13.593 9.42675 13.513 9.42675 13.1197C9.42675 12.7263 9.64008 12.5263 9.90675 12.5263Z"
+      fill="#3B3C45"
+    />
+  </svg>
+);
+
+export const DocumentPythonIcon = styled(Icon).attrs(() => ({
+  'data-component-name': 'icons/DocumentPythonIcon/DocumentPythonIcon',
+}))<IconProps>`
+  path {
+    fill: ${({ color }) => getCssColorVariable(color)};
+  }
+
+  height: ${({ size }) => size || '16px'};
+  width: ${({ size }) => size || '16px'};
+`;

package/src/icons/DocumentPythonIcon/index.ts

@@ -0,0 +1 @@
+export { DocumentPythonIcon } from '@redocly/theme/icons/DocumentPythonIcon/DocumentPythonIcon';

package/src/icons/DocumentShellIcon/DocumentShellIcon.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import styled from 'styled-components';
+
+import type { IconProps } from '@redocly/theme/icons/types';
+
+import { getCssColorVariable } from '@redocly/theme/core/utils';
+
+const Icon = (props: IconProps) => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    {...props}
+  >
+    <path
+      d="M14.5351 2.99992H3.83862C3.6752 3.00407 3.51738 3.06029 3.38814 3.16039C3.25891 3.26049 3.16501 3.39924 3.12012 3.55642L1.02012 12.4434C0.998149 12.5106 0.993246 12.5822 1.00585 12.6518C1.01845 12.7213 1.04817 12.7867 1.09232 12.8419C1.13646 12.8971 1.19365 12.9404 1.25874 12.968C1.32382 12.9956 1.39474 13.0066 1.46512 12.9999H12.1616C12.3249 12.9957 12.4827 12.9394 12.6118 12.8393C12.7409 12.7392 12.8348 12.6005 12.8796 12.4434L14.9801 3.55592C15.002 3.48876 15.0068 3.41722 14.9942 3.34773C14.9815 3.27825 14.9518 3.213 14.9076 3.15785C14.8635 3.10271 14.8064 3.05941 14.7413 3.03184C14.6763 3.00427 14.6054 2.9933 14.5351 2.99992ZM4.31312 11.8984C4.16872 11.9865 3.99731 12.0194 3.83057 11.9909C3.66383 11.9624 3.51306 11.8745 3.40612 11.7434L3.40262 11.7389C3.35483 11.6781 3.32075 11.6076 3.30269 11.5324C3.28463 11.4572 3.28302 11.3789 3.29797 11.303C3.31292 11.2271 3.34409 11.1554 3.38933 11.0926C3.43457 11.0298 3.49283 10.9776 3.56012 10.9394L8.36012 7.90892L5.30912 4.98292L5.30412 4.97792C5.24784 4.92482 5.20377 4.86011 5.17497 4.78829C5.14616 4.71647 5.13332 4.63924 5.13731 4.56196C5.14131 4.48469 5.16205 4.4092 5.1981 4.34073C5.23416 4.27226 5.28466 4.21244 5.34612 4.16542L5.36462 4.15042C5.49395 4.04749 5.65594 3.9944 5.82112 4.00082C5.98629 4.00725 6.14367 4.07275 6.26462 4.18542L9.88112 7.66392C9.96402 7.76867 10.006 7.90001 9.99912 8.03342C9.99485 8.11013 9.97427 8.18504 9.93875 8.25316C9.90323 8.32127 9.85358 8.38102 9.79312 8.42842C9.75612 8.44842 9.72012 8.48792 4.31762 11.8959L4.31312 11.8984ZM12.0001 11.4699C11.9905 11.6194 11.9221 11.7589 11.81 11.8582C11.6979 11.9575 11.5511 12.0084 11.4016 11.9999H8.58462C8.51096 12.0071 8.43662 11.9987 8.36638 11.9754C8.29614 11.9521 8.23156 11.9144 8.17677 11.8646C8.12199 11.8149 8.07822 11.7542 8.04828 11.6865C8.01834 11.6188 8.00289 11.5457 8.00293 11.4716C8.00296 11.3976 8.01848 11.3245 8.04848 11.2568C8.07849 11.1892 8.12231 11.1285 8.17714 11.0788C8.23197 11.0291 8.2966 10.9915 8.36686 10.9682C8.43712 10.945 8.51147 10.9367 8.58512 10.9439H11.4016C11.5503 10.9353 11.6965 10.9855 11.8085 11.0837C11.9205 11.182 11.9893 11.3203 12.0001 11.4689V11.4699Z"
+      fill="#3B3C45"
+    />
+  </svg>
+);
+
+export const DocumentShellIcon = styled(Icon).attrs(() => ({
+  'data-component-name': 'icons/DocumentShellIcon/DocumentShellIcon',
+}))<IconProps>`
+  path {
+    fill: ${({ color }) => getCssColorVariable(color)};
+  }
+
+  height: ${({ size }) => size || '16px'};
+  width: ${({ size }) => size || '16px'};
+`;

package/src/icons/DocumentShellIcon/index.ts

@@ -0,0 +1 @@
+export { DocumentShellIcon } from '@redocly/theme/icons/DocumentShellIcon/DocumentShellIcon';

package/src/icons/__tests__/IconTestUtils.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+export function testIconComponent(IconComponent: React.ComponentType<any>, componentName: string) {
+  const dataName = `icons/${componentName}/${componentName}`;
+
+  return {
+    rendersCorrectlyWithDefaultProps: () => {
+      const { container } = render(<IconComponent />);
+      const svgElement = container.querySelector('svg');
+      expect(svgElement).toBeInTheDocument();
+      expect(container.firstChild).toHaveStyle('height: 16px; width: 16px;');
+    },
+
+    appliesCustomSizeAndColor: () => {
+      const { container } = render(<IconComponent size="24px" color="--color-primary" />);
+
+      const svgElement = container.querySelector('svg');
+      expect(svgElement).toBeInTheDocument();
+      expect(container.firstChild).toHaveStyle('height: 24px; width: 24px;');
+      const pathElement = container.querySelector('path');
+      expect(pathElement).toHaveStyle('fill: var(--color-primary);');
+    },
+
+    hasCorrectDataComponentName: () => {
+      const { container } = render(<IconComponent />);
+      expect(container.firstChild).toHaveAttribute('data-component-name', dataName);
+    },
+  };
+}

package/src/layouts/CodeWalkthroughLayout.tsx

@@ -1,6 +1,8 @@
 import React from 'react';
 import styled from 'styled-components';
 
+import { breakpoints } from '@redocly/theme/core';
+
 export type CodeWalkthroughLayoutProps = React.PropsWithChildren<{
   className?: string;
 }>;
@@ -66,8 +68,10 @@ const ContentWrapper = styled.section`
 
     /* Full-width styling for all .code-walkthroughs */
     .code-walkthrough {
-      max-width: none;
       width: 100%;
+      max-width: ${breakpoints.max};
+      margin-left: auto;
+      margin-right: auto;
     }
 
     &:first-child > h1:first-child {

package/src/markdoc/components/CodeWalkthrough/CodeContainer.tsx

@@ -21,9 +21,33 @@ export function CodeContainer({
     // useEffect executed before DOM is updated due to re-render called before "painting" phase.
     setTimeout(() => {
       if (compRef.current) {
-        const element = compRef.current.querySelector('span.line.highlighted');
-        if (element) {
-          element.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'start' });
+        const highlightedLines = Array.from(
+          compRef.current.querySelectorAll('span.line.highlighted'),
+        );
+        const { bottom: panelBottom, top: panelTop } = compRef.current.getBoundingClientRect();
+
+        const linesBelow: Element[] = [];
+        const linesAbove: Element[] = [];
+        for (const highlightedLine of highlightedLines) {
+          const { bottom: lineBottom, top: lineTop } = highlightedLine.getBoundingClientRect();
+          const below = lineBottom > panelBottom;
+          const above = lineTop < panelTop;
+
+          if (below) {
+            linesBelow.push(highlightedLine);
+          } else if (above) {
+            linesAbove.push(highlightedLine);
+          }
+        }
+
+        if ((linesBelow.length && linesAbove.length) || linesAbove.length) {
+          linesAbove[0].scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'start' });
+        } else if (linesBelow.length) {
+          linesBelow[linesBelow.length - 1].scrollIntoView({
+            behavior: 'smooth',
+            block: 'nearest',
+            inline: 'start',
+          });
         }
       }
     }, 200);
@@ -31,6 +55,7 @@ export function CodeContainer({
 
   return (
     <CodeContainerWrapper
+      data-component-name="Markdoc/CodeWalkthrough/CodeContainer"
       ref={compRef}
       hideCodeColors={!isHovered}
       onMouseEnter={() => setIsHovered(true)}

package/src/markdoc/components/CodeWalkthrough/CodeFilters.tsx

@@ -3,11 +3,12 @@ import styled from 'styled-components';
 
 import type { CodeWalkthroughFilter } from '@redocly/config';
 
-import { Tag } from '@redocly/theme/components/Tag/Tag';
+import { Tag, ContentWrapper as TagContentWrapper } from '@redocly/theme/components/Tag/Tag';
 
+export type GetFilterState = (groupId: string) => { value: string; render: boolean } | null;
 export type CodeFilterProps = {
   filters: CodeWalkthroughFilter[];
-  getFilterState: (groupId: string) => { value: string; render: boolean } | null;
+  getFilterState: GetFilterState;
   handleFilterSelect: (groupId: string, id: string) => void;
   filtersElementRef?: React.RefObject<HTMLDivElement>;
 };
@@ -23,7 +24,10 @@ export function CodeFilters({
   }
 
   return (
-    <FilterWrapper ref={filtersElementRef}>
+    <FilterWrapper
+      ref={filtersElementRef}
+      data-component-name="Markdoc/CodeWalkthrough/CodeFilters"
+    >
       {filters.map(({ label, items, id }) => {
         return (
           <Filter key={id}>
@@ -50,8 +54,9 @@ export function CodeFilters({
 
 const Filter = styled.div`
   display: flex;
-  align-items: center;
+  align-items: flex-start;
   gap: var(--spacing-xs);
+  max-width: 100%;
 `;
 
 const FilterName = styled.div`
@@ -74,14 +79,26 @@ const FilterWrapper = styled.div`
   top: calc(var(--navbar-height));
   background-color: var(--bg-color);
   z-index: 1;
+  max-width: var(--md-content-max-width);
 `;
 
 const ButtonsWrapper = styled.div`
   display: flex;
+  min-width: 0;
+  flex-wrap: wrap;
 `;
 
 const TagButton = styled(Tag)`
   cursor: pointer;
   padding: 0px var(--spacing-xs);
   margin-right: var(--spacing-xs);
+  max-width: 100%;
+  margin-bottom: var(--spacing-xs);
+
+  ${TagContentWrapper} {
+    display: inline-block;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    overflow: hidden;
+  }
 `;

package/src/markdoc/components/CodeWalkthrough/CodePanel.tsx

@@ -25,7 +25,7 @@ export function CodePanel({
   const { handleDownloadCode } = useContext(CodeWalkthroughControlsStateContext);
 
   return (
-    <CodePanelWrapper>
+    <CodePanelWrapper data-component-name="Markdoc/CodeWalkthrough/CodePanel">
       {preview ? (
         <CodePanelPreview>
           {preview.map((element, idx) => (

package/src/markdoc/components/CodeWalkthrough/CodePanelHeader.tsx

@@ -1,10 +1,9 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
 import styled, { css } from 'styled-components';
 
 import type { CodeWalkthroughFile } from '@redocly/config';
 
-import { useThemeHooks } from '@redocly/theme/core/hooks';
-import { getFileIconByExt } from '@redocly/theme/core/utils';
+import { useThemeHooks, useRenderableFiles, type RenderableFile } from '@redocly/theme/core/hooks';
 import { OverflowMenuVerticalIcon } from '@redocly/theme/icons/OverflowMenuVerticalIcon/OverflowMenuVerticalIcon';
 import { Dropdown } from '@redocly/theme/components/Dropdown/Dropdown';
 import { DropdownMenu } from '@redocly/theme/components/Dropdown/DropdownMenu';
@@ -25,32 +24,45 @@ export function CodePanelHeader({
   activeTabName,
   onDownloadCode,
 }: CodePanelHeaderProps): JSX.Element {
+  const renderableFiles = useRenderableFiles(files);
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
   const tabRefs = useRef<HTMLButtonElement[]>([]);
   const tabsWrapperRef = useRef<HTMLDivElement>(null);
-  const [hiddenFiles, setHiddenFiles] = useState<CodeWalkthroughFile[]>([]);
+  const [hiddenFiles, setHiddenFiles] = useState<RenderableFile[]>([]);
 
   useEffect(() => {
     const activeTab = tabRefs.current.find((tab) => tab?.dataset.name === activeTabName);
-    if (activeTab) {
-      activeTab.scrollIntoView({ block: 'nearest', inline: 'center' });
+    const tabsWrapper = tabsWrapperRef.current;
+
+    if (activeTab && tabsWrapper) {
+      const { left: wrapperLeft, right: wrapperRight } = tabsWrapper.getBoundingClientRect();
+      const { left: tabLeft, right: tabRight } = activeTab.getBoundingClientRect();
+      const tabHidden = tabLeft < wrapperLeft || tabRight > wrapperRight;
+
+      if (tabHidden) {
+        activeTab.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+      }
     }
-  }, [activeTabName]);
 
-  useEffect(() => {
     const calculateHiddenFiles = () => {
       if (!tabsWrapperRef.current) return;
       const { left: wrapperLeft, right: wrapperRight } =
         tabsWrapperRef.current.getBoundingClientRect();
 
-      const hidden = files.filter((_, i) => {
+      const hidden: RenderableFile[] = [];
+
+      for (let i = 0; i < renderableFiles.length; i++) {
         const tab = tabRefs.current[i];
-        if (!tab) return false;
+        if (!tab) continue;
+
         const { left: tabLeft, right: tabRight } = tab.getBoundingClientRect();
+        const visible = tabLeft > wrapperLeft && tabRight < wrapperRight;
 
-        return tabLeft < wrapperLeft || tabRight > wrapperRight;
-      });
+        if (!visible) {
+          hidden.push(renderableFiles[i]);
+        }
+      }
 
       setHiddenFiles(hidden);
     };
@@ -58,32 +70,29 @@ export function CodePanelHeader({
     calculateHiddenFiles();
     window.addEventListener('resize', calculateHiddenFiles);
     return () => window.removeEventListener('resize', calculateHiddenFiles);
-  }, [files]);
-
-  const getFileTypeIcon = useCallback((basename: string) => {
-    const extension = basename.split('.').pop()?.toLowerCase() || '';
-    return getFileIconByExt(extension);
-  }, []);
+  }, [activeTabName, files, renderableFiles]);
 
   return (
     <CodePanelHeaderWrapper data-component-name="Markdoc/CodeWalkthrough/CodePanelHeader">
       <TabsWrapper ref={tabsWrapperRef}>
         <Tabs>
-          {files.map(({ path, basename }, i) => {
-            const FileIcon = getFileTypeIcon(basename);
-            return (
-              <Tab
-                ref={(el: HTMLButtonElement) => (tabRefs.current[i] = el)}
-                data-name={path}
-                active={path === activeTabName}
-                key={i}
-                onClick={() => handleTabSwitch(path)}
-              >
-                <FileIcon />
-                {basename}
-              </Tab>
-            );
-          })}
+          {renderableFiles.map(
+            ({ path, basename, FileIcon, parentFolder, isNameDuplicate, inRootDir }, i) => {
+              return (
+                <Tab
+                  ref={(el: HTMLButtonElement) => (tabRefs.current[i] = el)}
+                  data-name={path}
+                  active={path === activeTabName}
+                  key={i}
+                  onClick={() => handleTabSwitch(path)}
+                >
+                  <FileIcon />
+                  {basename}
+                  {isNameDuplicate && !inRootDir ? <Dirname>{parentFolder}</Dirname> : null}
+                </Tab>
+              );
+            },
+          )}
         </Tabs>
         <Gradient />
       </TabsWrapper>
@@ -92,18 +101,21 @@ export function CodePanelHeader({
         {hiddenFiles.length ? (
           <Dropdown trigger={<StyledOverflowMenuVerticalIcon size="14px" />} alignment="end">
             <StyledDropdownMenu>
-              {hiddenFiles.map(({ path, basename }, i) => {
-                const FileIcon = getFileTypeIcon(basename);
-                return (
-                  <DropdownMenuItem
-                    active={path === activeTabName}
-                    key={i}
-                    onAction={() => handleTabSwitch(path)}
-                    prefix={<FileIcon />}
-                    content={basename}
-                  />
-                );
-              })}
+              {hiddenFiles.map(
+                ({ path, basename, FileIcon, isNameDuplicate, inRootDir, parentFolder }, i) => {
+                  return (
+                    <DropdownMenuItem
+                      active={path === activeTabName}
+                      key={i}
+                      onAction={() => handleTabSwitch(path)}
+                      prefix={<FileIcon />}
+                      content={
+                        isNameDuplicate && !inRootDir ? `${parentFolder}/${basename}` : basename
+                      }
+                    />
+                  );
+                },
+              )}
             </StyledDropdownMenu>
           </Dropdown>
         ) : null}
@@ -141,7 +153,7 @@ const Gradient = styled.div`
 
 const Tabs = styled.div`
   display: flex;
-  overflow-x: auto;
+  overflow-x: hidden;
   padding-right: var(--spacing-base);
 
   &::-webkit-scrollbar {
@@ -149,6 +161,11 @@ const Tabs = styled.div`
   }
 `;
 
+const Dirname = styled.span`
+  font-size: var(--font-size-sm);
+  color: var(--text-color-description);
+`;
+
 const ActionBar = styled.div`
   display: flex;
 `;
@@ -164,7 +181,7 @@ const Tab = styled.button<{ active: boolean }>`
   gap: var(--spacing-xs);
   color: var(--text-color-secondary);
   white-space: nowrap;
-
+  scroll-margin-right: var(--spacing-base);
   ${({ active }) =>
     active
       ? css`

package/src/markdoc/components/CodeWalkthrough/CodePanelPreview.tsx

@@ -11,7 +11,7 @@ export function CodePanelPreview({ children }: PropsWithChildren): JSX.Element {
   const { translate } = useTranslate();
 
   return (
-    <CodePanelPreviewWrapper>
+    <CodePanelPreviewWrapper data-component-name="Markdoc/CodeWalkthrough/CodePanelPreview">
       <PreviewDropdown onClick={() => setIsOpen(!isOpen)}>
         {translate('codeWalkthrough.preview', 'Preview')}
         {isOpen ? <ChevronUpIcon /> : <ChevronDownIcon />}

package/src/markdoc/components/CodeWalkthrough/CodePanelToolbar.tsx

@@ -16,7 +16,7 @@ export function CodePanelToolbar({ file }: CodeToolbarProps): JSX.Element {
   const fileContent = getFileText(file);
 
   return (
-    <CodeToolbarWrapper>
+    <CodeToolbarWrapper data-component-name="Markdoc/CodeWalkthrough/CodePanelToolbar">
       <CopyButton data={fileContent} type="compound" variant="secondary" size="medium" />
     </CodeToolbarWrapper>
   );

package/src/markdoc/components/CodeWalkthrough/CodeStep.tsx

@@ -70,7 +70,7 @@ export function CodeStep({
 
     const filtersElementHeight = filtersElementRef?.current?.clientHeight || 0;
     const navbarHeight = document.querySelector('nav')?.clientHeight || 0;
-    setScrollMarginTop(filtersElementHeight + navbarHeight);
+    setScrollMarginTop(filtersElementHeight + navbarHeight + 10);
 
     return () => {
       if (currentCompRef) {
@@ -80,11 +80,15 @@ export function CodeStep({
   }, [activeStep, register, unregister, filtersElementRef]);
 
   if (!areConditionsMet({ when, unless })) {
+    if (isActive) {
+      setActiveStep(null);
+    }
     return null;
   }
 
   return (
     <StepWrapper
+      data-component-name="Markdoc/CodeWalkthrough/CodeStep"
       ref={compRef}
       isActive={isActive}
       scrollMarginTop={scrollMarginTop}