@redocly/theme 0.70.0-next.9 → 0.70.1

package/src/core/utils/assign-ref.ts

@@ -0,0 +1,9 @@
+import type { Ref } from 'react';
+
+export function assignRef<T>(ref: Ref<T> | undefined, value: T): void {
+  if (typeof ref === 'function') {
+    ref(value);
+  } else if (ref) {
+    ref.current = value;
+  }
+}

package/src/core/utils/attribute-parser.ts

@@ -0,0 +1,11 @@
+export function parseSrcSet(srcSet: string): Map<string, string> {
+  const result = new Map<string, string>();
+  const parts = srcSet.split(', ');
+
+  for (const part of parts) {
+    const [url, theme] = part.split(' ');
+    result.set(theme, url);
+  }
+
+  return result;
+}

package/src/core/utils/build-revision-url.ts

@@ -0,0 +1,16 @@
+export function buildRevisionUrl(
+  basePath: string,
+  revisionDate: string | null | undefined,
+  version?: string | null,
+): string | undefined {
+  if (!revisionDate) {
+    return undefined;
+  }
+
+  const params = new URLSearchParams();
+  params.set('revision', revisionDate);
+  if (version) {
+    params.set('version', version);
+  }
+  return `${basePath}?${params.toString()}`;
+}

package/src/core/utils/change-text-casing.ts

@@ -0,0 +1,25 @@
+type Casing = 'original' | 'lowercase' | 'uppercase' | 'sentence';
+
+export function changeTextCasing(
+  str: string,
+  casing: Casing | ((str: string) => string) = 'original',
+) {
+  if (casing instanceof Function) {
+    return casing(str);
+  }
+
+  if (casing === 'original' || !str) return str;
+
+  if (casing === 'lowercase') {
+    return str.toLowerCase();
+  }
+
+  if (casing === 'uppercase') {
+    return str.toUpperCase();
+  }
+
+  if (casing === 'sentence') {
+    const words = str?.split(/[\s-_]+/);
+    return words.map((word) => word[0].toUpperCase() + word.slice(1).toLowerCase()).join(' ');
+  }
+}

package/src/core/utils/class-names.ts

@@ -0,0 +1,16 @@
+const SPACE_DELIMITER = ' ';
+
+// EasyList/AdGuard ship generic cosmetic rules that hide these exact class tokens on every
+// site; the trailing underscore keeps the class usable without matching the filter lists.
+const ADBLOCK_HIDDEN_CLASS_NAMES = new Set(['product-ad', 'product-ads', 'product-inlist-ad']);
+
+export function getSafeClassName(className: string): string {
+  return ADBLOCK_HIDDEN_CLASS_NAMES.has(className) ? `${className}_` : className;
+}
+
+export function concatClassNames(...args: Array<string | undefined>): string {
+  return args
+    .map((className) => (className ? className.trim() : className))
+    .filter(Boolean)
+    .join(SPACE_DELIMITER);
+}

package/src/core/utils/clipboard-service.ts

@@ -0,0 +1,27 @@
+import copy from 'copy-to-clipboard';
+export class ClipboardService {
+  static copyCustom(text: string): boolean {
+    return copy(text);
+  }
+
+  static selectElement(element: HTMLDivElement | null): void {
+    if (!element) {
+      return;
+    }
+    let range;
+    let selection;
+    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+    if ((document.body as any).createTextRange) {
+      /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+      range = (document.body as any).createTextRange();
+      range.moveToElementText(element);
+      range.select();
+    } else if (document.createRange && window.getSelection) {
+      selection = window.getSelection();
+      range = document.createRange();
+      range.selectNodeContents(element);
+      selection?.removeAllRanges();
+      selection?.addRange(range);
+    }
+  }
+}

package/src/core/utils/color.ts

@@ -0,0 +1,12 @@
+export function stringToHslColor(value: string): string {
+  const s = 30;
+  const l = 80;
+  let hash = 0;
+
+  for (let i = 0; i < value.length; i++) {
+    hash = value.charCodeAt(i) + ((hash << 5) - hash);
+  }
+
+  const h = hash % 360;
+  return `hsl(${h}, ${s}%, ${l}%)`;
+}

package/src/core/utils/consent-settings-link-placement.ts

@@ -0,0 +1,18 @@
+import type { ConsentConfig, RedoclyConfig } from '@redocly/config';
+
+export type SettingsLinkPlacement = 'footer' | 'none';
+
+export function resolveSettingsLinkPlacement(
+  consent: ConsentConfig | undefined,
+  footer: RedoclyConfig['footer'] | undefined,
+): SettingsLinkPlacement {
+  const choice = consent?.settingsLink ?? 'auto';
+  if (choice !== 'auto') {
+    return choice;
+  }
+  const footerShown =
+    Boolean(footer) &&
+    !footer?.hide &&
+    (Boolean(footer?.copyrightText) || (Array.isArray(footer?.items) && footer.items.length > 0));
+  return footerShown ? 'footer' : 'none';
+}

package/src/core/utils/content-segments.ts

@@ -0,0 +1,119 @@
+import type { ToolCall, ContentSegment, GroupedContentSegment } from '../types/search';
+
+const SENTENCE_END_MARKS = '.!?:;';
+const CLOSING_MARKS = `"')]*_\``;
+const CODE_FENCE = /^[ \t]*(```|~~~)/gm;
+
+/**
+ * Splits an answer at its tool calls. A call made in the middle of a sentence or a code block is
+ * placed at the end of that paragraph, so the sentence reads as one piece.
+ */
+export function splitContentByToolCalls(
+  content: string | undefined,
+  toolCalls: ToolCall[] | undefined,
+): ContentSegment[] {
+  if (!toolCalls || toolCalls.length === 0) {
+    return [{ type: 'text', text: content || '' }];
+  }
+
+  const text = content ?? '';
+  const fences = Array.from(text.matchAll(CODE_FENCE), (match) => match.index);
+  const segments: ContentSegment[] = [];
+  let lastPos = 0;
+
+  for (const toolCall of toolCalls) {
+    const position = Math.max(lastPos, getBlockBoundary(text, toolCall.position, fences));
+    if (position > lastPos) {
+      segments.push({ type: 'text', text: text.substring(lastPos, position) });
+    }
+    segments.push({ type: 'tool', toolCall });
+    lastPos = position;
+  }
+
+  if (lastPos < text.length) {
+    segments.push({ type: 'text', text: text.substring(lastPos) });
+  }
+
+  return segments;
+}
+
+function getBlockBoundary(content: string, position: number, fences: number[]): number {
+  if (position <= 0 || position >= content.length) {
+    return position;
+  }
+  const isInsideCodeFence = (index: number) => {
+    let count = 0;
+    while (count < fences.length && fences[count] < index) count++;
+    return count % 2 === 1;
+  };
+  if (!isInsideCodeFence(position) && endsBlockOrSentence(content, position)) {
+    return position;
+  }
+  for (
+    let boundary = content.indexOf('\n\n', position);
+    boundary !== -1;
+    boundary = content.indexOf('\n\n', boundary + 2)
+  ) {
+    if (!isInsideCodeFence(boundary)) {
+      return boundary;
+    }
+  }
+  return content.length;
+}
+
+function endsBlockOrSentence(content: string, position: number): boolean {
+  let index = position - 1;
+  while (index >= 0 && /\s/.test(content[index])) {
+    if (content[index] === '\n') return true;
+    index--;
+  }
+  while (index >= 0 && CLOSING_MARKS.includes(content[index])) index--;
+  return index >= 0 && SENTENCE_END_MARKS.includes(content[index]);
+}
+
+/**
+ * Groups consecutive tool calls and drops text that is only whitespace. While the answer is
+ * generated, an answer with nothing to show yet is one empty active group (the thinking status),
+ * and the last group is active until text that is not whitespace follows it.
+ */
+export function groupToolCallSegments(
+  segments: ContentSegment[],
+  isGenerating?: boolean,
+): GroupedContentSegment[] {
+  const grouped: GroupedContentSegment[] = [];
+  let text = '';
+
+  for (const segment of segments) {
+    if (segment.type === 'text') {
+      text += segment.text;
+      if (segment.text.trim()) {
+        grouped.push(segment);
+      }
+      continue;
+    }
+    const previous = grouped.at(-1);
+    if (previous?.type === 'tools') {
+      previous.toolCalls.push(segment.toolCall);
+    } else {
+      grouped.push({ type: 'tools', toolCalls: [segment.toolCall], isActive: false });
+    }
+  }
+
+  if (!isGenerating) {
+    return grouped;
+  }
+  const last = grouped.at(-1);
+  if (last?.type === 'tools') {
+    last.isActive = !text.slice(last.toolCalls.at(-1)?.position ?? 0).trim();
+  } else if (grouped.length === 0) {
+    return [{ type: 'tools', toolCalls: [], isActive: true }];
+  }
+  return grouped;
+}
+
+export function hasToolCallsAndText(segments: ContentSegment[]): boolean {
+  return (
+    segments.some((segment) => segment.type === 'tool') &&
+    segments.some((segment) => segment.type === 'text' && segment.text.trim().length > 0)
+  );
+}

package/src/core/utils/css-variables.ts

@@ -0,0 +1,4 @@
+export const getCssColorVariable = (
+  color: string | undefined,
+  defaultValue = 'currentColor',
+): string => (color?.startsWith('--') ? `var(${color})` : color || defaultValue);

package/src/core/utils/custom-catalog-options-casing.ts

@@ -0,0 +1,29 @@
+/**
+ * Converts a string to title case for catalog option labels.
+ * Splits on whitespace, hyphens, and underscores; capitalizes each word.
+ * The first word is rendered as "API" when it is "api" (case-insensitive).
+ *
+ * @param str - The raw string to format (e.g. from config or entity data).
+ * @returns The formatted label with words capitalized and joined by spaces.
+ *
+ * @example
+ * customCatalogOptionsCasing('api_spec')           // 'API Spec'
+ * customCatalogOptionsCasing('my-custom-option')  // 'My Custom Option'
+ * customCatalogOptionsCasing('user name')         // 'User Name'
+ * customCatalogOptionsCasing('  api   version  ') // 'API Version'
+ */
+export function customCatalogOptionsCasing(str: string): string {
+  const trimmedStr = str.trim();
+  if (!trimmedStr) return trimmedStr;
+
+  const words = trimmedStr.split(/[\s-_]+/);
+
+  return words
+    .map((word, index) => {
+      if (index === 0 && word.toLowerCase() === 'api') {
+        return 'API';
+      }
+      return word[0].toUpperCase() + word.slice(1);
+    })
+    .join(' ');
+}

package/src/core/utils/date.ts

@@ -0,0 +1,33 @@
+/**
+ * Formats a date string to localized short date format (e.g., "Dec 12, 2025")
+ * @param dateString - ISO date string or null
+ * @param locale - Locale string (e.g., "en-US")
+ * @returns Formatted date string or empty string if dateString is null
+ */
+export function toLocalizedShortDate(dateString: string | null, locale: string): string {
+  if (!dateString) return '';
+  const date = new Date(dateString);
+  return date.toLocaleDateString(locale, {
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  });
+}
+
+/**
+ * Formats a date string to localized short date-time format (e.g., "Dec 12, 3:45 PM")
+ * @param dateString - ISO date string or null
+ * @param locale - Locale string (e.g., "en-US")
+ * @returns Formatted date-time string or empty string if dateString is null
+ */
+export function toLocalizedShortDateTime(dateString: string | null, locale: string): string {
+  if (!dateString) return '';
+  const date = new Date(dateString);
+  return date.toLocaleString(locale, {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true,
+  });
+}

package/src/core/utils/details.ts

@@ -0,0 +1,47 @@
+export function extendDetailsBehaviour() {
+  enhanceDetails();
+  openDetailsFromHash();
+  window.addEventListener('hashchange', openDetailsFromHash);
+
+  return () => {
+    window.removeEventListener('hashchange', openDetailsFromHash);
+  };
+}
+
+function openDetailsAndScroll(detailsElement: Element) {
+  detailsElement.setAttribute('open', '');
+  setTimeout(() => {
+    detailsElement.scrollIntoView({
+      block: 'center',
+      behavior: 'smooth',
+    });
+  }, 0);
+}
+
+function enhanceDetails() {
+  const existingIds: string[] = [];
+  Array.from(document.getElementsByTagName('details')).forEach((detailsElement, index) => {
+    if (detailsElement.id) {
+      return;
+    }
+
+    const generatedId =
+      detailsElement.querySelector('summary')?.textContent?.replace(/\s+/g, '-').toLowerCase() ||
+      `details-${index}`;
+
+    detailsElement.id = existingIds.includes(generatedId) ? `${generatedId}-${index}` : generatedId;
+
+    existingIds.push(detailsElement.id);
+  });
+}
+
+function openDetailsFromHash() {
+  const hash = window.location.hash;
+  if (!hash) return;
+
+  const detailsElement = document.getElementById(hash.substring(1));
+
+  if (detailsElement?.tagName === 'DETAILS') {
+    openDetailsAndScroll(detailsElement);
+  }
+}

package/src/core/utils/dom.ts

@@ -0,0 +1 @@
+export const IS_BROWSER = typeof window !== 'undefined' && 'HTMLElement' in window;

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

@@ -0,0 +1,36 @@
+import { saveAs } from 'file-saver';
+
+import type { CodeWalkthroughFile } from '@redocly/theme/core/types';
+
+import { removeLeadingSlash } from './urls';
+import { findClosestCommonDirectory } from './find-closest-common-directory';
+import { getCodeWalkthroughFileText } from './get-code-walkthrough-file-text';
+
+export async function downloadCodeWalkthrough(
+  files: CodeWalkthroughFile[],
+  state: Record<string, { value: string | boolean }>,
+  inputsState: Record<string, { value: string }>,
+) {
+  const JSZip = (await import('jszip')).default;
+
+  // https://github.com/Stuk/jszip/issues/196#issuecomment-69503828
+  JSZip.support.nodebuffer = false;
+
+  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);
+    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' });
+  saveAs(zipContent, 'sample-code.zip');
+}

package/src/core/utils/dropdown.ts

@@ -0,0 +1,14 @@
+import type { DropdownAlignment } from '../types/dropdown';
+
+export function fitDropdownAlignment(
+  anchor: DOMRect,
+  menuWidth: number,
+  alignment: DropdownAlignment = 'start',
+): DropdownAlignment {
+  const fits: Record<DropdownAlignment, boolean> = {
+    start: anchor.left + menuWidth <= window.innerWidth,
+    end: anchor.right - menuWidth >= 0,
+  };
+  const other: DropdownAlignment = alignment === 'end' ? 'start' : 'end';
+  return fits[alignment] || !fits[other] ? alignment : other;
+}

package/src/core/utils/enhanced-smoothstep.ts

@@ -0,0 +1,14 @@
+/**
+ * Enhanced smoothstep function for smooth interpolation with configurable threshold.
+ * Used in active heading detection to create virtual positions for better scroll behavior.
+ */
+export function enhancedSmoothstep(input: number, threshold: number = 0.4): number {
+  if (input <= threshold) {
+    return 0;
+  }
+
+  const normalizedValue = Math.min(Math.max((input - threshold) / (1 - threshold), 0), 1);
+  return (
+    3 * normalizedValue * normalizedValue - 2 * normalizedValue * normalizedValue * normalizedValue
+  );
+}

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/format-date-without-timezone.ts

@@ -0,0 +1,9 @@
+export function formatDateWithoutTimeZone(date?: Date | null) {
+  if (!date) return date;
+
+  return `${date.getFullYear()}-${padZero(date.getMonth() + 1)}-${padZero(date.getDate())}`;
+}
+
+function padZero(num: number) {
+  return num < 10 ? '0' + num : num;
+}

package/src/core/utils/frontmatter-translate.ts

@@ -0,0 +1,9 @@
+/**
+ * Utility function for use in React frontmatter
+ * This function creates a string that will be processed by the frontmatter loader
+ * to convert it into a translation key object
+ */
+export const frontmatterTranslate = (key: string, defaultValue: string): string => {
+  const escapedDefaultValue = defaultValue.replace(/'/g, "\\'");
+  return `frontmatterTranslate('${key}', '${escapedDefaultValue}')`;
+};

package/src/core/utils/get-ai-prompt-link.ts

@@ -0,0 +1,30 @@
+import type { AiPromptTarget } from '../types/prompt';
+
+type AiPromptEndpoint = { baseUrl: string; queryParam: string };
+
+const AI_PROMPT_ENDPOINTS: Record<AiPromptTarget, AiPromptEndpoint> = {
+  chatgpt: { baseUrl: 'https://chat.openai.com', queryParam: 'q' },
+  claude: { baseUrl: 'https://claude.ai/new', queryParam: 'q' },
+  // Encoding: https://cursor.com/docs/integrations/deeplinks
+  cursor: { baseUrl: 'https://cursor.com/link/prompt', queryParam: 'text' },
+};
+
+/**
+ * Builds a link that opens an AI tool with the prompt prefilled.
+ *
+ * @param target - The AI tool to open.
+ * @param prompt - The plain-text prompt to prefill.
+ * @returns The absolute URL with the encoded prompt in the query string.
+ *
+ * @example
+ * ```ts
+ * getAiPromptLink('claude', 'Summarize this page');
+ * // 'https://claude.ai/new?q=Summarize+this+page'
+ * ```
+ */
+export function getAiPromptLink(target: AiPromptTarget, prompt: string): string {
+  const { baseUrl, queryParam } = AI_PROMPT_ENDPOINTS[target];
+  const url = new URL(baseUrl);
+  url.searchParams.set(queryParam, prompt);
+  return url.toString();
+}

package/src/core/utils/get-auto-dismiss-duration.ts

@@ -0,0 +1,20 @@
+import type { ToastType } from '../types/toast';
+
+const SIMPLE_TOAST_DURATION_MS = 2500;
+const DETAILED_TOAST_DURATION_MS = 4000;
+
+export function getAutoDismissDuration(
+  hasDetails: boolean,
+  type: ToastType,
+  duration?: number,
+): number | null {
+  if (duration !== undefined) {
+    return duration;
+  }
+
+  if (type === 'loading') {
+    return null;
+  }
+
+  return hasDetails ? DETAILED_TOAST_DURATION_MS : SIMPLE_TOAST_DURATION_MS;
+}

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

@@ -0,0 +1,33 @@
+import type { CodeWalkthroughFile, CodeWalkthroughNode } from '@redocly/theme/core/types';
+
+import { matchCodeWalkthroughConditions } from './match-code-walkthrough-conditions';
+import { replaceInputsWithValue } from './replace-inputs-with-value';
+
+export function getCodeWalkthroughFileText(
+  file: CodeWalkthroughFile,
+  state: Record<string, { value: string | boolean }>,
+  inputsState: Record<string, { value: string }>,
+) {
+  const contentChunks: string[] =
+    file?.content.flatMap((node) => getChunkText(node, state, inputsState)) ?? [];
+
+  return contentChunks.join('\n');
+}
+
+function getChunkText(
+  node: CodeWalkthroughNode,
+  state: Record<string, { value: string | boolean }>,
+  inputsState: Record<string, { value: string }>,
+): string[] {
+  if (typeof node === 'string') {
+    const replacedNode = replaceInputsWithValue(node, inputsState);
+
+    return [replacedNode];
+  } else {
+    if (!matchCodeWalkthroughConditions(node.condition || {}, state)) {
+      return [];
+    }
+
+    return node.children.flatMap((child) => getChunkText(child, state, inputsState));
+  }
+}

package/src/core/utils/get-navbar-element.ts

@@ -0,0 +1,10 @@
+export function getNavbarElement(): HTMLElement | null {
+  const navElements = (typeof document !== 'undefined' && document.querySelectorAll('nav')) || [];
+  // there can be multiple nav elements (e.g. mobile and non-mobile), let's use the first one with non-zero height
+  for (let i = 0; i < navElements.length; i++) {
+    if (navElements[i].getBoundingClientRect().height > 1) {
+      return navElements[i];
+    }
+  }
+  return navElements[0] || null;
+}

package/src/core/utils/get-operation-color.ts

@@ -0,0 +1,18 @@
+type OperationColorProps = {
+  deprecated?: boolean;
+  isAdditionalOperation?: boolean;
+  httpVerb: string;
+};
+
+export function getOperationColor({
+  deprecated,
+  isAdditionalOperation,
+  httpVerb,
+}: OperationColorProps): string {
+  if (deprecated) {
+    return 'http-deprecated';
+  } else if (isAdditionalOperation) {
+    return 'http-additional-operation';
+  }
+  return httpVerb;
+}

package/src/core/utils/get-scorecard-color-variable.ts

@@ -0,0 +1,18 @@
+export const getScorecardColorVariable = (
+  levelIndex: number,
+  scorecardLevelsLength: number,
+): string => {
+  let colorLevels = scorecardLevelsLength;
+
+  if (colorLevels > 5) {
+    colorLevels = 5;
+  }
+
+  if (colorLevels < 2) {
+    colorLevels = 2;
+  }
+
+  return `--scorecard-level-color-${colorLevels}-${
+    levelIndex + 1 > colorLevels ? colorLevels : levelIndex + 1
+  }`;
+};