@redocly/theme 0.45.11 → 0.46.0

package/lib/markdoc/components/Cards/CardIcon.js

@@ -7,8 +7,8 @@ exports.CardIcon = CardIcon;
 const react_1 = __importDefault(require("react"));
 const styled_components_1 = __importDefault(require("styled-components"));
 const InlineSvg_1 = require("../../../markdoc/components/InlineSvg/InlineSvg");
-function CardIcon({ variant, src, rawContent }) {
-    return (react_1.default.createElement(CardIconWrapper, { "$variant": variant }, rawContent ? react_1.default.createElement(CardSvg, { fileRawContent: rawContent }) : react_1.default.createElement(CardImg, { src: src })));
+function CardIcon({ variant, src, rawContent, position }) {
+    return (react_1.default.createElement(CardIconWrapper, { "$variant": variant, "$position": position }, rawContent ? react_1.default.createElement(CardSvg, { fileRawContent: rawContent }) : react_1.default.createElement(CardImg, { src: src })));
 }
 const CardImg = styled_components_1.default.img `
   width: var(--card-icon-width);
@@ -29,7 +29,7 @@ const CardSvg = (0, styled_components_1.default)(InlineSvg_1.InlineSvg) `
 `;
 const CardIconWrapper = styled_components_1.default.div `
   display: flex;
-  align-items: center;
+  align-self: ${({ $position }) => ($position ? $position : 'auto')};
   justify-content: center;
   min-width: var(--card-icon-width);
   min-height: var(--card-icon-height);

package/lib/markdoc/tags/card.js

@@ -28,6 +28,11 @@ exports.card = {
                 matches: ['start', 'end'],
                 default: 'start',
             },
+            iconPosition: {
+                type: String,
+                matches: ['auto', 'start', 'center', 'end'],
+                default: 'auto',
+            },
             layout: {
                 type: String,
                 matches: ['horizontal', 'combined', 'vertical'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/theme",
-  "version": "0.45.11",
+  "version": "0.46.0",
   "description": "Shared UI components lib",
   "keywords": [
     "theme",
@@ -27,7 +27,6 @@
   "peerDependencies": {
     "@markdoc/markdoc": "0.4.0",
     "lodash.throttle": "^4.1.1",
-    "prismjs": "^1.28.0",
     "react": "^17.0.0 || ^18.0.0",
     "react-dom": "^17.0.0 || ^18.0.0",
     "react-router-dom": "^6.21.1",
@@ -44,7 +43,6 @@
     "@types/jest-when": "3.5.5",
     "@types/lodash.throttle": "4.1.9",
     "@types/node": "18.19.3",
-    "@types/prismjs": "1.26.4",
     "@types/react": "18.3.9",
     "@types/react-dom": "18.2.25",
     "@types/styled-components": "5.1.34",

package/src/components/CodeBlock/CodeBlock.tsx

@@ -4,8 +4,8 @@ import styled from 'styled-components';
 import type { CodeBlockControlsProps } from '@redocly/theme/components/CodeBlock/CodeBlockControls';
 import type { ReportDialogProps } from '@redocly/theme/components/Feedback/ReportDialog';
 
-import { highlight, addLineNumbers } from '@redocly/theme/core/utils';
-import { useModalScrollLock, useReportDialog } from '@redocly/theme/core/hooks';
+import { addLineNumbers } from '@redocly/theme/core/utils';
+import { useModalScrollLock, useReportDialog, useThemeHooks } from '@redocly/theme/core/hooks';
 import { ReportDialog } from '@redocly/theme/components/Feedback/ReportDialog';
 import { CodeBlockContainer } from '@redocly/theme/components/CodeBlock/CodeBlockContainer';
 import { CodeBlockControls } from '@redocly/theme/components/CodeBlock/CodeBlockControls';
@@ -26,6 +26,7 @@ export type CodeBlockProps = {
   codeBlockMaxHeight?: string;
   hideCodeColors?: boolean;
   wrapContents?: boolean;
+  [key: string]: unknown;
 };
 
 type UnstableExternalCodeSample = {
@@ -64,12 +65,25 @@ export function CodeBlock({
   hideCodeColors,
   wrapContents = false,
   children,
+  ...rest
 }: React.PropsWithChildren<CodeBlockProps>): JSX.Element {
   const [sourceCode, setSourceCode] = useState<string>(
     (source || externalSource?.sample?.get?.(externalSource)) ?? '',
   );
+  const { useCodeHighlight } = useThemeHooks();
+  const { highlight } = useCodeHighlight() || {};
 
-  const highlightedCode = highlightedHtml || (children ? null : highlight(sourceCode, lang));
+  const highlightedCode = highlightedHtml
+    ? withLineNumbers
+      ? addLineNumbers(highlightedHtml, startLineNumber)
+      : highlightedHtml
+    : children
+      ? null
+      : highlight?.(sourceCode, lang, {
+          withLineNumbers,
+          startLineNumber,
+          highlight: rest['data-highlight'] as string | undefined,
+        });
 
   // The same initial value should be returned for ssr and frontend to avoid issues
   // Because we don't have session storage in ssr and can't get the security details there
@@ -102,13 +116,11 @@ export function CodeBlock({
         />
         <CodeBlockContainer
           ref={codeBlockRef}
-          className={withLineNumbers ? 'line-numbers' : ''}
+          withLineNumbers={withLineNumbers}
           dangerouslySetInnerHTML={
             highlightedCode
               ? {
-                  __html: withLineNumbers
-                    ? addLineNumbers(highlightedCode, startLineNumber)
-                    : highlightedCode,
+                  __html: highlightedCode,
                 }
               : undefined
           }
@@ -142,4 +154,6 @@ const CodeBlockWrapper = styled.div`
   border-radius: var(--border-radius);
   background-color: var(--code-block-bg-color);
   margin: 0 0 var(--spacing-sm);
+
+  --md-pre-margin: 0;
 `;

package/src/components/CodeBlock/CodeBlockContainer.tsx

@@ -9,6 +9,7 @@ export type CodeBlockContainerProps = PropsWithChildren<{
   wrapContents?: boolean;
   ref?: (instance: HTMLPreElement | null) => void;
   className?: string;
+  withLineNumbers?: boolean;
   dangerouslySetInnerHTML?: {
     __html: string;
   };
@@ -42,95 +43,269 @@ const CodeBlockContainerComponent = styled.pre<CodeBlockContainerProps>`
       font-family: var(--code-block-font-family);
     }
   }
-  /**
-  * Based on prism-dark.css
-  */
-  code[class*='language-'],
-  pre[class*='language-'] {
-    text-shadow: 0 -0.1em 0.2em black;
-    text-align: left;
-    word-spacing: normal;
-    word-break: normal;
-    word-wrap: normal;
-    line-height: 1.5;
-
-    -moz-tab-size: 4;
-    -o-tab-size: 4;
-    tab-size: 4;
-
-    -webkit-hyphens: none;
-    -moz-hyphens: none;
-    -ms-hyphens: none;
-    hyphens: none;
-  }
 
-  @media print {
-    code[class*='language-'],
-    pre[class*='language-'] {
-      text-shadow: none;
+  .highlighted {
+    background: var(--layer-color-hover);
+    margin-left: calc(var(--spacing-sm) * -1);
+    padding-left: var(--spacing-sm);
+    width: calc(100% + var(--spacing-sm));
+    display: inline-block;
+
+    &.error {
+      background: var(--color-raspberry-2);
+    }
+
+    &.warning {
+      background: var(--color-carrot-2);
     }
   }
 
-  /* Code blocks */
+  [data-line-number] {
+    &::before {
+      content: attr(data-line-number);
+      display: inline-block;
+      min-width: 2em;
+      padding-right: 0.8em;
+      text-align: right;
+      pointer-events: none;
+      user-select: none;
+    }
+  }
 
-  pre[class*='language-'] {
-    padding: 1em;
-    margin: 0.5em 0;
-    overflow: auto;
+  .has-diff {
+    > .line {
+      &::before {
+        content: attr(data-line-number) '  ';
+        display: inline-block;
+        padding-right: 0.4em;
+        text-align: right;
+        pointer-events: none;
+        user-select: none;
+      }
+      &[data-line-number]::before {
+        min-width: 3em;
+      }
+    }
   }
 
-  .token.punctuation {
-    opacity: 1;
+  .diff {
+    margin-left: calc(var(--spacing-sm) * -1);
+    padding-left: var(--spacing-sm);
+    width: calc(100% + var(--spacing-sm));
+    display: inline-block;
+
+    &.add {
+      background: var(--color-grass-2);
+      &:before {
+        content: attr(data-line-number) ' +';
+        color: var(--color-grass-7);
+      }
+    }
+    &.remove {
+      background: var(--color-raspberry-2);
+
+      &:before {
+        content: attr(data-line-number) ' -';
+        color: var(--color-raspberry-7);
+      }
+    }
   }
 
-  .namespace {
-    opacity: 0.7;
+  .highlighted-word {
+    background: var(--color-carrot-2);
+    border: 1px solid var(--color-carrot-5);
+    border-radius: 4px;
   }
 
-  .token.selector,
-  .token.attr-name,
-  .token.string,
-  .token.char,
-  .token.builtin,
-  .token.inserted {
-    & + a,
-    & + a:visited {
-      color: var(--code-block-tokens-link-color);
-      text-decoration: underline;
+  .has-focused {
+    .line {
+      margin-left: calc(var(--spacing-sm) * -1);
+      padding-left: var(--spacing-sm);
+      width: calc(100% + var(--spacing-sm));
+      display: inline-block;
+
+      opacity: 0.7;
+      filter: blur(0.095rem);
+      transition:
+        filter 0.35s,
+        opacity 0.35s;
+      &.focused {
+        opacity: 1;
+        filter: blur(0);
+      }
+    }
+
+    &:hover {
+      .line {
+        opacity: 1;
+        filter: blur(0);
+      }
     }
   }
 
-  .token.property.string {
-    color: var(--code-block-tokens-property-string-color);
+  /*
+  * Tree view styles
+   */
+
+  .shiki {
+    &.theme {
+      display: inline-block;
+      width: 100%;
+
+      &.tree-view-root {
+        display: flex;
+        flex-direction: column;
+      }
+    }
   }
 
-  .token.important,
-  .token.bold {
-    font-weight: bold;
+  . .line {
+    display: inline-block;
   }
 
-  .token.italic {
-    font-style: italic;
+  .tree-view-line {
+    display: flex;
   }
 
-  .token.entity {
-    cursor: help;
+  .tree-view-branch {
+    color: var(--code-block-tree-view-lines-color);
   }
 
-  .code-line {
-    &:before {
-      content: attr(data-line-number);
-      display: inline-block;
-      min-width: 2em;
-      padding-right: 0.8em;
-      text-align: right;
-      pointer-events: none;
-      user-select: none;
+  .tree-view-file {
+    display: inline-flex;
+    &::before {
+      content: '\\ea01';
+      margin-left: 0.3rem;
+      margin-right: 0.5rem;
+      font-family: 'TreeViewIcons';
     }
-  }
 
-  .highlighted {
-    background: var(--tag-basic-bg-color);
+    &.no-file {
+      &::before {
+        content: '';
+        margin-right: 0;
+      }
+    }
+
+    &.ext-folder {
+      &::before {
+        content: '\\ea02';
+      }
+    }
+
+    &.ext-img,
+    &.ext-png,
+    &.ext-jpg,
+    &.ext-jpeg,
+    &.ext-gif,
+    &.ext-svg {
+      &::before {
+        content: '\\ea03';
+      }
+    }
+
+    &.ext-mp2,
+    &.ext-mp3,
+    &.ext-wav,
+    &.ext-ogg,
+    &.ext-flac {
+      &::before {
+        content: '\\ea04';
+      }
+    }
+
+    &.ext-mp4,
+    &.ext-mkv,
+    &.ext-avi,
+    &.ext-mov,
+    &.ext-wmv,
+    &.ext-flv {
+      &::before {
+        content: '\\ea05';
+      }
+    }
+
+    &.ext-txt,
+    &.ext-text,
+    &.ext-md,
+    &.ext-markdown {
+      &::before {
+        content: '\\ea06';
+      }
+    }
+
+    &.ext-js,
+    &.ext-ts,
+    &.ext-jsx,
+    &.ext-tsx,
+    &.ext-json,
+    &.ext-yaml,
+    &.ext-yml,
+    &.ext-xml,
+    &.ext-html,
+    &.ext-css,
+    &.ext-scss,
+    &.ext-less,
+    &.ext-sass,
+    &.ext-java,
+    &.ext-c,
+    &.ext-cpp,
+    &.ext-cs,
+    &.ext-php,
+    &.ext-py,
+    &.ext-rb,
+    &.ext-go,
+    &.ext-swift,
+    &.ext-sql,
+    &.ext-perl,
+    &.ext-lua,
+    &.ext-scala,
+    &.ext-sh {
+      &::before {
+        content: '\\ea07';
+      }
+    }
+
+    &.ext-zip,
+    &.ext-rar,
+    &.ext-tar,
+    &.ext-gz,
+    &.ext-iso {
+      &::before {
+        content: '\\ea08';
+      }
+    }
+
+    &.ext-pdf,
+    &.ext-PDF {
+      &::before {
+        content: '\\ea09';
+      }
+    }
+
+    &.ext-excel,
+    &.ext-xls,
+    &.ext-xlsx {
+      &::before {
+        content: '\\ea0a';
+      }
+    }
+
+    &.ext-powerpoint,
+    &.ext-ppt,
+    &.ext-pptx {
+      &::before {
+        content: '\\ea0b';
+      }
+    }
+
+    &.ext-doc,
+    &.ext-docx,
+    &.ext-rtf {
+      &::before {
+        content: '\\ea0c';
+      }
+    }
   }
 
   ${generateCodeBlockTokens()}
@@ -138,9 +313,9 @@ const CodeBlockContainerComponent = styled.pre<CodeBlockContainerProps>`
   ${({ hideCodeColors }) =>
     hideCodeColors &&
     css`
-      .code-line:not(.highlighted),
-      .code-line:not(.highlighted) > span,
-      .code-line:not(.highlighted) > span > span {
+      .line-number:not(.highlighted),
+      .line-number:not(.highlighted) > span,
+      .line-number:not(.highlighted) > span > span {
         color: grey;
       }
     `}

package/src/components/CodeBlock/variables.ts

@@ -1,6 +1,30 @@
 import { css } from 'styled-components';
 
 export const code = css`
+  /**
+    * Tree view icons font
+    */
+  @font-face {
+    font-family: 'TreeViewIcons';
+    /**
+    * Use the following escape sequences to refer to a specific icon:
+    *
+    * - \\ea01 file
+    * - \\ea02 folder
+    * - \\ea03 image
+    * - \\ea04 audio
+    * - \\ea05 video
+    * - \\ea06 text
+    * - \\ea07 code
+    * - \\ea08 archive
+    * - \\ea09 pdf
+    * - \\ea0a excel
+    * - \\ea0b powerpoint
+    * - \\ea0c word
+    */
+    src: url('data:application/font-woff;base64,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') format('woff');
+  }
+  
   /**
     * @tokens Code base styles
     */
@@ -83,10 +107,29 @@ export const code = css`
   --code-block-tokens-atrule-color: var(--code-block-tokens-keyword-color); // @presenter Color
   --code-block-tokens-attr-value-color: var(--code-block-tokens-keyword-color); // @presenter Color
   --code-block-tokens-regex-color: var(--color-carrot-7); // @presenter Color
+  --code-block-tokens-regex-char-escape-color: var(--color-grass-8); // @presenter Color
   --code-block-tokens-important-color: var(--code-block-tokens-regex-color); // @presenter Color
   --code-block-tokens-deleted-color: var(--color-red-7); // @presenter Color
   --code-block-tokens-class-name-color: var(--color-carrot-7); // @presenter Color
   --code-block-tokens-function-color: var(--color-carrot-7); // @presenter Color
+  --code-block-tokens-invalid-color: var(--color-orange-8); // @presenter Color
+  --code-block-tokens-message-error-color: var(--code-block-tokens-invalid-color); // @presenter Color
+  --code-block-tokens-unmatched-color: var(--code-block-tokens-invalid-color); // @presenter Color
+  --code-block-tokens-markup-bg-color: var(--color-grass-1); // @presenter Color
+  --code-block-tokens-markup-foreground-color: var(--color-grass-8); // @presenter Color
+  --code-block-tokens-markup-changed-color: var(--color-carrot-1); // @presenter Color
+  --code-block-tokens-markup-deleted-color: var(--color-magenta-1); // @presenter Color
+  --code-block-tokens-markup-quote-color: var(--color-grass-8); // @presenter Color
+  --code-block-tokens-markup-ignored-color: var(--color-blue-1); // @presenter Color
+  --code-block-tokens-warm-bg-color: var(--color-warm-grey-2); // @presenter Color
+  --code-block-tokens-warm-foreground-color: var(--color-warm-grey-8); // @presenter Color
+  --code-block-tokens-meta-diff-range-color: var(--color-purple-8); // @presenter Color
+
+  /**
+    * @tokens Code Block tree view
+   */
+  --code-block-tree-view-icon-font-family: 'TreeViewIcons'; // @presenter FontFamily
+  --code-block-tree-view-lines-color: var(--border-color-primary); // @presenter Color
 
   // @tokens End
 `;

package/src/components/Link/Link.tsx

@@ -19,7 +19,7 @@ export type LinkProps = {
 export function Link(props: React.PropsWithChildren<LinkProps>): JSX.Element {
   const context = useContext(ThemeDataContext);
 
-  if (context) {
+  if (context?.components) {
     const { LinkComponent } = context.components;
     return <LinkComponent {...props} />;
   } else {

package/src/core/hooks/use-theme-config.ts

@@ -10,7 +10,7 @@ export function useThemeConfig<T extends Record<string, unknown>>(
 ): T & NonNullable<UiAccessibleConfig> {
   const context = useContext(ThemeDataContext);
 
-  if (!context) {
+  if (!context?.config) {
     return {} as T;
   }
   const { config, hooks } = context;

package/src/core/hooks/use-theme-hooks.ts

@@ -12,6 +12,7 @@ const fallbacks = {
   useSubmitFeedback: () => ({ submitFeedback: () => {} }),
   useTelemetry: () => ({ telemetry: () => {} }),
   useBreadcrumbs: () => [],
+  useCodeHighlight: () => ({ highlight: (rawContent: string) => rawContent }),
 };
 
 export const useThemeHooks = () => {

package/src/core/types/hooks.ts

@@ -110,6 +110,17 @@ export type ThemeHooks = {
   useTelemetry: () => { send(action: TelemetryEvent, data: unknown): void };
   useUserTeams: () => string[];
   usePageProps: <T extends Record<string, unknown>>() => PageProps & T;
+  useCodeHighlight: () => {
+    highlight: (
+      code: string,
+      language?: string | undefined,
+      highlightOptions?: {
+        withLineNumbers?: boolean;
+        startLineNumber?: number;
+        highlight?: string;
+      },
+    ) => string;
+  };
 };
 
 export type L10nConfig = {

package/src/core/utils/add-line-numbers.ts

@@ -0,0 +1,16 @@
+const NEW_LINE_EXP = /\n(?!$)/g;
+
+/**
+ * @param highlightedCode - A string with new line breaks; the line numbers will be added before each line.
+ * @param start - The number to start the line numbering from; default is 1
+ * @returns A string with line numbers added before each line
+ */
+export function addLineNumbers(highlightedCode: string, start = 1): string {
+  const codeLines = highlightedCode.split(NEW_LINE_EXP);
+
+  return codeLines
+    .map((line, i) => {
+      return `<span class='line' data-line-number='${start + i}'>${line}</span>`;
+    })
+    .join('\n');
+}

package/src/core/utils/index.ts

@@ -1,6 +1,6 @@
 export * from '@redocly/theme/core/utils/clipboard-service';
 export * from '@redocly/theme/core/utils/css-variables';
-export * from '@redocly/theme/core/utils/highlight';
+export * from '@redocly/theme/core/utils/add-line-numbers';
 export * from '@redocly/theme/core/utils/media-css';
 export * from '@redocly/theme/core/utils/theme-helpers';
 export * from '@redocly/theme/core/utils/class-names';

package/src/markdoc/components/Cards/Card.tsx

@@ -12,6 +12,7 @@ export type CardProps = React.PropsWithChildren<{
   icon?: string;
   iconRawContent?: string;
   imagePosition?: 'start' | 'end';
+  iconPosition?: 'auto' | 'start' | 'center' | 'end';
   lineClamp?: number;
   layout?: 'horizontal' | 'vertical' | 'combined';
   variant?: 'filled' | 'outlined' | 'elevated' | 'ghost';
@@ -26,6 +27,7 @@ export function Card({
   icon,
   iconRawContent,
   imagePosition = 'start',
+  iconPosition = 'auto',
   layout = 'vertical',
   variant = 'filled',
   lineClamp,
@@ -59,7 +61,14 @@ export function Card({
           $textAlign={textAlign}
           $hasImage={image !== undefined}
         >
-          {icon && <CardIcon variant={iconVariant} src={icon} rawContent={iconRawContent} />}
+          {icon && (
+            <CardIcon
+              variant={iconVariant}
+              src={icon}
+              rawContent={iconRawContent}
+              position={iconPosition}
+            />
+          )}
           <ContentWrapper>
             <Title id={cardTitleId} $isCardLink={!!to} $justifyContent={justifyContent}>
               {title}

package/src/markdoc/components/Cards/CardIcon.tsx

@@ -7,11 +7,12 @@ export type CardIconProps = {
   variant?: string;
   src: string;
   rawContent?: string;
+  position?: 'auto' | 'start' | 'center' | 'end';
 };
 
-export function CardIcon({ variant, src, rawContent }: CardIconProps) {
+export function CardIcon({ variant, src, rawContent, position }: CardIconProps) {
   return (
-    <CardIconWrapper $variant={variant}>
+    <CardIconWrapper $variant={variant} $position={position}>
       {rawContent ? <CardSvg fileRawContent={rawContent} /> : <CardImg src={src} />}
     </CardIconWrapper>
   );
@@ -36,9 +37,9 @@ const CardSvg = styled(InlineSvg)`
   }
 `;
 
-const CardIconWrapper = styled.div<{ $variant?: string }>`
+const CardIconWrapper = styled.div<{ $variant?: string; $position?: string }>`
   display: flex;
-  align-items: center;
+  align-self: ${({ $position }) => ($position ? $position : 'auto')};
   justify-content: center;
   min-width: var(--card-icon-width);
   min-height: var(--card-icon-height);