@redocly/theme 0.47.0 → 0.48.0

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

@@ -0,0 +1,53 @@
+import React, { PropsWithChildren, useState } from 'react';
+import styled from 'styled-components';
+
+import { useThemeHooks } from '@redocly/theme/core/hooks';
+import { ChevronUpIcon } from '@redocly/theme/icons/ChevronUpIcon/ChevronUpIcon';
+import { ChevronDownIcon } from '@redocly/theme/icons/ChevronDownIcon/ChevronDownIcon';
+
+export function CodePanelPreview({ children }: PropsWithChildren): JSX.Element {
+  const [isOpen, setIsOpen] = useState(false);
+  const { useTranslate } = useThemeHooks();
+  const { translate } = useTranslate();
+
+  return (
+    <CodePanelPreviewWrapper>
+      <PreviewDropdown onClick={() => setIsOpen(!isOpen)}>
+        {translate('codeWalkthrough.preview', 'Preview')}
+        {isOpen ? <ChevronUpIcon /> : <ChevronDownIcon />}
+      </PreviewDropdown>
+      <PreviewContentWrapper isOpen={isOpen}>{children}</PreviewContentWrapper>
+    </CodePanelPreviewWrapper>
+  );
+}
+
+const CodePanelPreviewWrapper = styled.div`
+  width: 100%;
+  padding: var(--spacing-xs) var(--spacing-xs) var(--spacing-xs) var(--spacing-sm);
+  border-bottom: 1px solid var(--border-color-secondary);
+`;
+
+const PreviewDropdown = styled.div`
+  display: flex;
+  align-items: center;
+
+  gap: (--spacing-xxs);
+
+  user-select: none;
+
+  font-size: var(--font-size-base);
+  cursor: pointer;
+`;
+
+const PreviewContentWrapper = styled.div<{ isOpen: boolean }>`
+  display: ${({ isOpen }) => (isOpen ? 'grid' : 'none')};
+  place-items: center;
+
+  margin: auto 0;
+
+  max-height: 50vh;
+  width: 100%;
+  max-width: 100%;
+
+  overflow: auto;
+`;

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

@@ -0,0 +1,31 @@
+import React, { useContext } from 'react';
+import styled from 'styled-components';
+
+import type { CodeWalkthroughFile } from '@redocly/config';
+
+import { CodeWalkthroughControlsStateContext } from '@redocly/theme/core/contexts';
+import { CopyButton } from '@redocly/theme/components/Buttons/CopyButton';
+
+export type CodeToolbarProps = {
+  file: CodeWalkthroughFile;
+};
+
+export function CodePanelToolbar({ file }: CodeToolbarProps): JSX.Element {
+  const { getFileText } = useContext(CodeWalkthroughControlsStateContext);
+
+  const fileContent = getFileText(file);
+
+  return (
+    <CodeToolbarWrapper>
+      <CopyButton data={fileContent} type="compound" variant="secondary" size="medium" />
+    </CodeToolbarWrapper>
+  );
+}
+
+const CodeToolbarWrapper = styled.div`
+  display: flex;
+  position: absolute;
+  bottom: var(--spacing-sm);
+  right: var(--spacing-sm);
+  gap: var(--spacing-xs);
+`;

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

@@ -0,0 +1,149 @@
+import React, { useContext, useRef, type PropsWithChildren, useEffect, useState } from 'react';
+import styled from 'styled-components';
+
+import type { WithConditions } from '@redocly/config';
+
+import {
+  CodeWalkthroughControlsStateContext,
+  CodeWalkthroughStepsContext,
+} from '@redocly/theme/core/contexts';
+
+export type CodeStepProps = WithConditions<{
+  id: string;
+  stepKey: number;
+  heading?: string;
+}>;
+
+export function CodeStep({
+  id,
+  heading,
+  stepKey,
+  when,
+  unless,
+  children,
+}: PropsWithChildren<CodeStepProps>) {
+  const compRef = useRef<HTMLDivElement | null>(null);
+  const { areConditionsMet } = useContext(CodeWalkthroughControlsStateContext);
+  const { activeStep, setActiveStep, register, unregister, lockObserver, filtersElementRef } =
+    useContext(CodeWalkthroughStepsContext);
+  const isActive = activeStep === id;
+
+  const [scrollMarginTop, setScrollMarginTop] = useState(0);
+
+  const handleActivateStep = () => {
+    if (lockObserver) {
+      lockObserver.current = true;
+
+      if (compRef.current) {
+        compRef.current.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      }
+
+      setActiveStep(id);
+      setTimeout(() => {
+        lockObserver.current = false;
+      }, 1000);
+    }
+  };
+
+  useEffect(() => {
+    // If the step is active during first render, scroll to it
+    // This is to ensure that the step is visible when the page is loaded
+    if (isActive) {
+      handleActivateStep();
+    }
+
+    // Ignore dependency array because we only need to run this once
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    const currentCompRef = compRef.current;
+    if (currentCompRef) {
+      currentCompRef
+        .querySelectorAll<HTMLElement>('a, button, input, textarea, select, [tabindex]')
+        .forEach((el) => {
+          el.setAttribute('tabindex', '-1');
+        });
+
+      register(currentCompRef);
+    }
+
+    const filtersElementHeight = filtersElementRef?.current?.clientHeight || 0;
+    const navbarHeight = document.querySelector('nav')?.clientHeight || 0;
+    setScrollMarginTop(filtersElementHeight + navbarHeight);
+
+    return () => {
+      if (currentCompRef) {
+        unregister(currentCompRef);
+      }
+    };
+  }, [activeStep, register, unregister, filtersElementRef]);
+
+  if (!areConditionsMet({ when, unless })) {
+    return null;
+  }
+
+  return (
+    <StepWrapper
+      ref={compRef}
+      isActive={isActive}
+      scrollMarginTop={scrollMarginTop}
+      data-step-key={stepKey}
+      data-step-active={isActive}
+      onClick={handleActivateStep}
+      onFocus={handleActivateStep}
+      tabIndex={0}
+    >
+      <StepContent isActive={isActive}>
+        {heading ? <StepHeading>{heading}</StepHeading> : null}
+        {children}
+      </StepContent>
+    </StepWrapper>
+  );
+}
+
+const StepContent = styled.div<{ isActive: boolean }>`
+  margin: var(--spacing-xs) 0px var(--spacing-xs) calc(var(--spacing-unit) * 3.5);
+  padding: var(--spacing-md) var(--spacing-lg);
+  background: ${({ isActive }) => (isActive ? 'var(--layer-color)' : 'none')};
+  border-radius: var(--border-radius);
+
+  &:hover {
+    background-color: ${({ isActive }) =>
+      isActive ? 'var(--code-step-bg-active-hover)' : 'var(--code-step-bg-hover)'};
+  }
+`;
+
+const StepHeading = styled.p`
+  font-weight: var(--font-weight-semibold);
+`;
+
+export const StepWrapper = styled.div<{ isActive: boolean; scrollMarginTop: number }>`
+  position: relative;
+  scroll-margin-top: ${({ scrollMarginTop }) => scrollMarginTop}px;
+
+  &::before {
+    content: '';
+    position: absolute;
+    width: 6px;
+    height: 100%;
+    background-color: ${({ isActive }) =>
+      isActive ? 'var(--code-step-vertical-line-bg-active)' : 'none'};
+    border-radius: var(--border-radius-lg);
+  }
+  &:hover::before {
+    background-color: ${({ isActive }) =>
+      isActive
+        ? 'var(--code-step-vertical-line-bg-active)'
+        : 'var(--code-step-vertical-line-bg-hover)'};
+  }
+
+  &:hover::before {
+    width: ${({ isActive }) => (isActive ? '8px' : '6px')};
+  }
+
+  &:hover ${StepContent} {
+    background-color: ${({ isActive }) =>
+      isActive ? 'var(--code-step-bg-active-hover)' : 'var(--code-step-bg-hover)'};
+  }
+`;

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

@@ -0,0 +1,63 @@
+import React, { useContext } from 'react';
+import styled from 'styled-components';
+
+import { CodeWalkthroughControlsStateContext } from '@redocly/theme/core/contexts';
+import { StepWrapper } from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeStep';
+import { Switch } from '@redocly/theme/components/Switch/Switch';
+
+export type CodeToggleProps = React.PropsWithChildren<{
+  id: string;
+  label: string;
+  description?: React.ReactNode[];
+}>;
+
+export function CodeToggle(props: CodeToggleProps) {
+  const { id, label, description, children } = props;
+  const { getToggleState, changeToggleState } = useContext(CodeWalkthroughControlsStateContext);
+
+  const toggleState = getToggleState(id);
+
+  if (!(toggleState && toggleState.render)) {
+    return null;
+  }
+  const checked = toggleState.value;
+
+  return (
+    <ToggleWrapper>
+      <ToggleContentWrapper>
+        <ToggleSubtitle>
+          <Switch value={checked} onChange={(newValue) => changeToggleState(id, newValue)} />
+          <div>{label}</div>
+        </ToggleSubtitle>
+        {description ? (
+          <div>
+            {description.map((paragraph, idx) => (
+              <React.Fragment key={idx}>{paragraph}</React.Fragment>
+            ))}
+          </div>
+        ) : null}
+      </ToggleContentWrapper>
+      {checked ? children : null}
+    </ToggleWrapper>
+  );
+}
+
+export const ToggleWrapper = styled.div`
+  ${StepWrapper} {
+    margin-left: 0;
+  }
+`;
+
+export const ToggleSubtitle = styled.div`
+  display: flex;
+  gap: var(--spacing-sm);
+  align-items: center;
+  font-weight: var(--font-weight-bold);
+`;
+
+const ToggleContentWrapper = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-xs);
+  padding: var(--spacing-xs) 0;
+`;

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

@@ -0,0 +1,111 @@
+import React, { useState, type PropsWithChildren } from 'react';
+import styled from 'styled-components';
+
+import type { CodeWalkthroughAttr } from '@redocly/config';
+
+import {
+  CodeWalkthroughStepsContext,
+  CodeWalkthroughControlsStateContext,
+} from '@redocly/theme/core/contexts';
+import { CodePanel } from '@redocly/theme/markdoc/components/CodeWalkthrough/CodePanel';
+import { useCodeWalkthrough } from '@redocly/theme/core/hooks';
+import { CodeFilters } from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeFilters';
+import { StepWrapper } from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeStep';
+
+export type CodeWalkthroughProps = PropsWithChildren<CodeWalkthroughAttr>;
+
+export function CodeWalkthrough({ children, steps, preview, ...attributes }: CodeWalkthroughProps) {
+  // Steps are being modified causing the observer to be recreated in the useCodeWalkthrough hook
+  // This is a workaround to prevent the observer from being recreated
+  const [initialSteps] = useState([...steps]);
+  const { controlsState, stepsState, files, downloadAssociatedFiles } = useCodeWalkthrough(
+    initialSteps,
+    attributes,
+  );
+  const { activeFilters, getFilterState, changeFilterState } = controlsState;
+  const { filtersElementRef } = stepsState;
+
+  return (
+    <CodeWalkthroughStepsContext.Provider value={stepsState}>
+      <CodeWalkthroughControlsStateContext.Provider value={controlsState}>
+        <CodeWalkthroughWrapper className="code-walkthrough">
+          <DocsPanel>
+            <CodeFilters
+              filters={activeFilters}
+              getFilterState={getFilterState}
+              handleFilterSelect={changeFilterState}
+              filtersElementRef={filtersElementRef}
+            />
+            <ContentWrapper>{children}</ContentWrapper>
+          </DocsPanel>
+
+          <CodePanel
+            files={files}
+            downloadAssociatedFiles={downloadAssociatedFiles}
+            preview={preview}
+          />
+        </CodeWalkthroughWrapper>
+      </CodeWalkthroughControlsStateContext.Provider>
+    </CodeWalkthroughStepsContext.Provider>
+  );
+}
+
+const CodeWalkthroughWrapper = styled.div`
+  display: grid;
+  grid-template-columns: 4fr 6fr;
+
+  padding-right: var(--spacing-xl);
+
+  border-top: 1px solid var(--border-color-secondary);
+  border-bottom: 1px solid var(--border-color-secondary);
+
+  &:first-child {
+    border-top: none;
+  }
+
+  &:last-child {
+    border-bottom: none;
+  }
+`;
+
+const DocsPanel = styled.div`
+  display: flex;
+  flex-direction: column;
+
+  min-height: 0;
+  min-height: calc(100vh - var(--navbar-height));
+
+  padding-right: var(--spacing-xs);
+  padding-bottom: calc(var(--spacing-xs) + var(--spacing-xl));
+  gap: var(--spacing-xl);
+`;
+
+const ContentWrapper = styled.div`
+  flex-grow: 1;
+
+  min-height: 0;
+  max-width: var(--md-content-max-width);
+
+  & > *:not(${StepWrapper}) {
+    padding-left: var(--spacing-xl);
+  }
+  overflow-y: scroll;
+
+  /* Hide scrollbar for Chrome, Safari and Opera */
+  &::-webkit-scrollbar {
+    display: none;
+  }
+  /* Hide scrollbar for IE, Edge and Firefox */
+  -ms-overflow-style: none; /* IE and Edge */
+  scrollbar-width: none; /* Firefox */
+
+  &:first-child {
+    padding-top: var(--spacing-sm);
+  }
+
+  &:not(:first-child) {
+    & > *:first-child {
+      margin-top: 0;
+    }
+  }
+`;

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

@@ -0,0 +1,101 @@
+import React, { useContext, useState, useCallback } from 'react';
+import styled from 'styled-components';
+import debounce from 'lodash.debounce';
+
+import { CodeWalkthroughControlsStateContext } from '@redocly/theme/core/contexts';
+
+export type InputProps = {
+  id: string;
+  label?: string;
+  placeholder?: string;
+  value?: string;
+};
+
+const DEBOUNCE_TIME = 500;
+
+export function Input(props: InputProps) {
+  const { id, label, placeholder } = props;
+  const { getInputState, changeInputState } = useContext(CodeWalkthroughControlsStateContext);
+
+  const inputState = getInputState(id);
+
+  const [value, setValue] = useState(inputState?.value || '');
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const debouncedSave = useCallback(
+    debounce((id: string, value: string) => {
+      changeInputState(id, value);
+    }, DEBOUNCE_TIME),
+    [],
+  );
+
+  if (!inputState?.render) {
+    return null;
+  }
+
+  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const inputValue = event.target.value;
+
+    setValue(inputValue);
+    debouncedSave(id, inputValue);
+  };
+
+  return (
+    <InputWrapper>
+      {label && <Label>{label}</Label>}
+      <StyledInput
+        id={id}
+        value={value}
+        onChange={handleChange}
+        aria-label={label}
+        placeholder={placeholder}
+      />
+    </InputWrapper>
+  );
+}
+
+const InputWrapper = styled.div`
+  display: flex;
+  flex-direction: column;
+  margin: var(--md-paragraph-margin);
+`;
+
+const Label = styled.p`
+  color: var(--text-color-secondary);
+  font-size: var(--font-size-base);
+  line-height: var(--line-height-base);
+  font-family: var(--font-family-base);
+  font-weight: var(--font-weight-medium);
+`;
+
+const StyledInput = styled.input`
+  border: 1px solid var(--border-color-primary);
+  width: 224px;
+  outline: none;
+  padding: var(--input-padding) var(--spacing-sm);
+  border-radius: var(--input-border-radius);
+  background-color: var(--input-bg-color);
+  color: var(--text-color-secondary);
+  font-family: var(--font-family-base);
+  font-size: var(--font-size-base);
+  line-height: var(--input-line-height);
+
+  &::placeholder {
+    opacity: 1;
+    color: var(--input-content-placeholder-color);
+  }
+
+  &:hover {
+    color: var(--text-color-primary);
+    border: 1px solid var(--border-color-primary);
+  }
+
+  &:focus {
+    color: var(--text-color-primary);
+    border: 1px solid var(--border-color-primary);
+  }
+
+  &:-webkit-autofill {
+    background-color: var(--input-bg-color);
+  }
+`;

package/src/markdoc/components/CodeWalkthrough/variables.ts

@@ -0,0 +1,16 @@
+import { css } from 'styled-components';
+
+export const codeWalkthrough = css`
+--code-step-vertical-line-bg-active: var(--color-blue-6);
+--code-step-vertical-line-bg-hover: var(--color-hover-base);
+
+--code-step-bg-active: var(--layer-color);
+--code-step-bg-hover: var(--color-hover-base);
+--code-step-bg-active-hover: var(--layer-color-hover);
+
+--code-panel-bg-color: var(--layer-color);
+--code-panel-line-numbering-color: var(--text-color-disabled);
+--code-panel-header-height: var(--spacing-lg);
+--code-panel-border-color: var(--border-color-secondary);
+--code-panel-border-radius: var(--border-radius);
+`;

package/src/markdoc/components/default.ts

@@ -12,3 +12,8 @@ export * from '@redocly/theme/markdoc/components/Cards/Card';
 export * from '@redocly/theme/markdoc/components/Cards/CardIcon';
 export * from '@redocly/theme/markdoc/components/Cards/CardImage';
 export * from '@redocly/theme/markdoc/components/Image/Image';
+export * from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeWalkthrough';
+export * from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeStep';
+export * from '@redocly/theme/markdoc/components/CodeWalkthrough/Input';
+export * from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeToggle';
+export * from '@redocly/theme/markdoc/components/CodeWalkthrough/CodeContainer';

package/src/markdoc/default.ts

@@ -19,6 +19,10 @@ import { inlineSvg } from '@redocly/theme/markdoc/tags/inline-svg';
 import { cards } from '@redocly/theme/markdoc/tags/cards';
 import { card } from '@redocly/theme/markdoc/tags/card';
 import { img } from '@redocly/theme/markdoc/tags/img';
+import { codeWalkthrough } from '@redocly/theme/markdoc/tags/code-walkthrough';
+import { codeStep } from '@redocly/theme/markdoc/tags/code-step';
+import { input } from '@redocly/theme/markdoc/tags/input';
+import { toggle } from '@redocly/theme/markdoc/tags/code-toggle';
 
 export const tags = {
   [admonition.tagName]: admonition.schema,
@@ -33,4 +37,8 @@ export const tags = {
   [cards.tagName]: cards.schema,
   [card.tagName]: card.schema,
   [img.tagName]: img.schema,
+  [codeWalkthrough.tagName]: codeWalkthrough.schema,
+  [codeStep.tagName]: codeStep.schema,
+  [toggle.tagName]: toggle.schema,
+  [input.tagName]: input.schema,
 };

package/src/markdoc/tags/code-step.ts

@@ -0,0 +1,27 @@
+import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
+
+export const codeStep: MarkdocSchemaWrapper = {
+  tagName: 'step',
+  schema: {
+    attributes: {
+      id: {
+        type: String,
+        required: true,
+      },
+      heading: {
+        type: String,
+      },
+      when: {
+        type: Object,
+      },
+      unless: {
+        type: Object,
+      },
+      stepKey: {
+        type: Number, // internal
+      },
+    },
+
+    render: 'CodeStep',
+  },
+};

package/src/markdoc/tags/code-toggle.ts

@@ -0,0 +1,37 @@
+import markdoc from '@markdoc/markdoc';
+
+import type { MarkdocSchemaWrapper } from '@redocly/theme/markdoc/tags/types';
+
+export const toggle: MarkdocSchemaWrapper = {
+  tagName: 'toggle',
+  schema: {
+    attributes: {
+      id: {
+        type: String,
+        required: true,
+      },
+      label: {
+        type: String,
+        required: true,
+      },
+      unless: {
+        type: Object,
+        required: false,
+      },
+      when: {
+        type: Object,
+        required: false,
+      },
+    },
+    slots: {
+      description: { required: false, render: true },
+    },
+    transform: (node, config) => {
+      const attributes = node.transformAttributes(config);
+      const children = node.transformChildren(config);
+
+      return new markdoc.Tag('CodeToggle', attributes, children);
+    },
+    render: 'CodeToggle',
+  },
+};