@redocly/theme 0.9.15 → 0.11.0

package/src/components/Catalog/CatalogCard.tsx

@@ -0,0 +1,95 @@
+import * as React from 'react';
+import styled from 'styled-components';
+
+import type { CatalogItem } from '@theme/types/portal/src/shared/types/catalog';
+import { Link } from '@portal/Link';
+import { Highlight } from '@theme/ui/Highlight';
+import { Tags } from '@theme/components/Tags';
+
+export function CatalogCard({ item }: { item: CatalogItem }): JSX.Element {
+  return (
+    <Link key={item.docsLink || item.link} to={item.docsLink || item.link}>
+      <StyledCard>
+        <CardTitle>
+          <Highlight>{item.title}</Highlight>
+        </CardTitle>
+        {/* <div>{item.image}</div> */}
+        <CardDescription>
+          <Highlight>{item.description ?? ''}</Highlight>
+        </CardDescription>
+        {item.tags ? <Tags tags={item.tags as string[]} /> : null}
+        <hr />
+        <CardFooter>View documentation</CardFooter>
+      </StyledCard>
+    </Link>
+  );
+}
+
+const StyledCard = styled.div`
+  min-height: 268px;
+  height: 100%;
+  box-shadow: var(--box-shadow);
+
+  display: flex;
+  flex-direction: column;
+
+  color: var(--text-color);
+  background-color: var(--thin-tile-background-color);
+  border-radius: 4px;
+
+  border: 1px solid var(--border-color);
+  box-shadow: 0px 0px 10px 0px rgba(35, 35, 35, 0.05);
+  transition: all 0.2s ease-in-out;
+
+  &:hover {
+    /* box-shadow: 0px 12px 30px 0px rgba(35, 35, 35, 0.2); */
+    box-shadow: 0px 10px 30px 0px rgba(35, 35, 35, 0.1);
+    border: 1px solid var(--border-color);
+    transform: translateY(-2px);
+  }
+
+  border-radius: 8px;
+  width: 100%;
+  padding: 24px 24px 0;
+  display: flex;
+  flex-direction: column;
+  cursor: pointer;
+`;
+
+const CardTitle = styled.h4`
+  line-height: 26px;
+  letter-spacing: 0.8px;
+  font-size: 20px;
+  font-weight: var(--font-weight-bold);
+  margin: 0;
+  margin-bottom: 16px;
+`;
+
+const CardDescription = styled.div`
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  line-height: var(--line-height);
+  letter-spacing: 0px;
+  font-size: 16px;
+  color: var(--text-color-secondary);
+  text-align: inherit;
+  font-weight: 400;
+`;
+
+const CardFooter = styled.div`
+  height: 46px;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  flex-direction: column;
+  font-size: 16px;
+  font-weight: var(--font-weight-bold);
+
+  a:hover & {
+    text-decoration: var(--link-hover-text-decoration);
+    color: var(--link-hover-text-color);
+  }
+`;

package/src/components/Catalog/useCatalog.ts

@@ -0,0 +1,280 @@
+import * as React from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+
+import type { Location } from 'react-router-dom';
+
+import type { ResolvedNavItem } from '@theme/types/portal';
+import type {
+  CatalogConfig,
+  FilteredCatalog,
+  ResolvedFilter,
+  CatalogItem,
+  Filter,
+} from '@theme/types/portal/src/shared/types/catalog';
+import { findDeepFirst, toStringIfDefined, withoutHash } from '@theme/utils';
+
+export function useCatalog(items: ResolvedNavItem[], config: CatalogConfig): FilteredCatalog {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const searchParams = useSearchParams(location);
+  const [filtersState, setFiltersState] = React.useState(() =>
+    (config.filters ?? []).map((f) => {
+      return new Set(searchParams.getAll(f.property));
+    }),
+  );
+  const [filterTerm, setFilterTerm] = React.useState(() => searchParams.get('filter') || '');
+
+  const filtersWithOptions = React.useMemo(
+    () => collectFilterOptions(items, config.filters),
+    [items, config.filters],
+  );
+  const normalizedItems = React.useMemo(() => normalizeItems(items, config), [items, config]);
+
+  const toggleOption = React.useCallback((filterIdx, option) => {
+    setFiltersState((prev) => {
+      const newFilterOptions = prev[filterIdx] ? prev[filterIdx] : new Set<string>();
+      if (newFilterOptions.has(option)) {
+        newFilterOptions.delete(option);
+      } else {
+        newFilterOptions.add(option);
+      }
+      return [...prev.slice(0, filterIdx), newFilterOptions, ...prev.slice(filterIdx + 1)];
+    });
+    window.scrollTo(0, 0);
+  }, []);
+
+  const selectOption = React.useCallback(
+    (filterIdx, option) => {
+      setFiltersState((prev) => {
+        const newFilterOptions = new Set<string>(option ? [option] : []);
+        const filter = filtersWithOptions[filterIdx];
+
+        return prev.map((f, idx) =>
+          idx === filterIdx
+            ? newFilterOptions
+            : filtersWithOptions[idx].parentFilter === filter.property
+            ? new Set()
+            : f,
+        );
+      });
+      window.scrollTo(0, 0);
+    },
+    [filtersWithOptions],
+  );
+
+  React.useEffect(() => {
+    filtersState.forEach((filterValues, filterIdx) => {
+      const filter = config.filters?.[filterIdx];
+      if (!filter) return;
+      searchParams.delete(filter.property);
+      filterValues.forEach((value) => {
+        searchParams.append(filter.property, value);
+      });
+    });
+    searchParams;
+    if (filterTerm) {
+      searchParams.set('filter', filterTerm);
+    } else {
+      searchParams.delete('filter');
+    }
+    const newSearch = searchParams.toString();
+    navigate({ search: newSearch });
+  }, [config.filters, searchParams, filtersState, filterTerm, navigate]);
+
+  // filterParents[i] is a Set with indexes of parents of this filter
+  const filterParents = React.useMemo(() => collectFilterParents(config.filters), [config.filters]);
+
+  return React.useMemo(() => {
+    const filters = filtersWithOptions.map((filter, idx) => ({
+      ...filter,
+      toggleOption: (value: string) => toggleOption(idx, value),
+      selectOption: (value: string) => selectOption(idx, value),
+      selectedOptions: filtersState[idx] ?? new Set<string>(),
+      isFilterUsed: (filtersState[idx]?.size ?? 0) > 0, // TODO: rename to isUsed
+    }));
+
+    const filteredItems = filterItems(normalizedItems, filters, filterTerm);
+
+    // add more information to filters state which is known only after filtering items
+    const resolvedFilters = filters.map((filter, idx) => {
+      const parentFilterIdx = filters.findIndex((f) => f.property === filter.parentFilter);
+      const parentUsed = filter.parentFilter
+        ? (filtersState[parentFilterIdx]?.size ?? 0) > 0
+        : true;
+
+      // we filter items with all the other independent filters current state
+      // then we can calculate the options for this filter after other filters are applied
+      // we need it to have correct numbers but also to eliminate options which are not available due to other filters
+      const otherIndependentFilters = filters.filter(
+        (_f, i) => i !== idx && !filterParents[idx]?.has(i),
+      );
+      const filteredWithOtherFilters = filterItems(
+        normalizedItems,
+        otherIndependentFilters,
+        filterTerm,
+      );
+      // collect filter options for this filter, this is probably not optimal but perf is not critical here
+      const adjustedFilterOptions = collectFilterOptions(
+        filteredWithOtherFilters.map((m) => ({ metadata: m })),
+        config.filters,
+      );
+
+      return {
+        ...filter,
+        parentUsed,
+        filteredOptions: adjustedFilterOptions[idx].options,
+      };
+    });
+
+    const groups =
+      config.groupByFirstFilter && filters[0].selectedOptions.size > 0
+        ? groupByFirstFilter(resolvedFilters, filteredItems)
+        : [{ title: 'APIs', items: filteredItems }];
+
+    return { groups, filters: resolvedFilters, setFilterTerm, filterTerm };
+  }, [
+    filtersWithOptions,
+    normalizedItems,
+    filterTerm,
+    config.groupByFirstFilter,
+    config.filters,
+    filtersState,
+    toggleOption,
+    selectOption,
+    filterParents,
+  ]);
+}
+
+function groupByFirstFilter(filters: ResolvedFilter[], filteredItems: CatalogItem[]) {
+  return filters[0].options
+    .map((option) => ({
+      title: option.value,
+      items: filteredItems.filter((item) => {
+        const itemValue = item?.[filters[0].property] || filters[0].missingCategoryName || 'Others';
+        if (Array.isArray(itemValue)) {
+          return itemValue.includes(option.value);
+        }
+        return itemValue === option.value;
+      }),
+    }))
+    .filter((group) => group.items.length > 0);
+}
+
+function useSearchParams(location: Location) {
+  return React.useMemo(() => new URLSearchParams(location.search), [location.search]);
+}
+
+function normalizeItems(items: ResolvedNavItem[], config: CatalogConfig): CatalogItem[] {
+  if (!config.separateVersions) {
+    // keep only default version
+    // idea: save other versions information (may be useful for cards)
+    items = items.filter((item) => item.isDefault === true || item.isDefault === undefined);
+  }
+
+  return items.map((item) => {
+    const metadata = item.metadata || {};
+    const link = item.link || findDeepFirst(item.items || [], (i) => 'link' in i && !!i.link)?.link;
+    const firstSidebarItem = (item as any).sidebar?.[0];
+    return {
+      ...metadata,
+      title: toStringIfDefined(metadata?.title) || item.label || 'Untitled',
+      description: toStringIfDefined(metadata?.description),
+      link: withoutHash(link) ?? '#',
+      docsLink: withoutHash(firstSidebarItem?.link),
+      image: toStringIfDefined(metadata?.image), // TODO: resolve image?
+    } as CatalogItem;
+  });
+}
+
+function collectFilterParents(filtersWithOptions: Filter[] | undefined) {
+  if (!filtersWithOptions) return [];
+  const parents: Set<number>[] = [];
+  // use filter idx as id so we don't need users to provide unique ids
+  for (let i = 0; i < filtersWithOptions.length; i++) {
+    const filter = filtersWithOptions[i];
+    if (filter.parentFilter) {
+      const idx = filtersWithOptions.findIndex((f) => f.property === filter.parentFilter);
+      parents[idx] = parents[idx] || new Set();
+      parents[idx].add(i);
+    }
+  }
+  return parents;
+}
+
+function collectFilterOptions(
+  items: { metadata?: Record<string, unknown> }[],
+  filters: CatalogConfig['filters'],
+) {
+  return (filters ?? []).map((filter) => {
+    const staticOptions = filter.options
+      ? Object.fromEntries(filter.options.map((o) => [o, 0]))
+      : undefined;
+
+    const usedOptions = staticOptions ?? {};
+
+    let othersCount = 0;
+    for (const item of items) {
+      const values = Array.isArray(item.metadata?.[filter.property])
+        ? (item.metadata?.[filter.property] as string[])
+        : [item.metadata?.[filter.property]];
+
+      for (const value of values) {
+        const str = String(value);
+        if (staticOptions) {
+          if (str in staticOptions) {
+            usedOptions[str] = usedOptions[str] + 1;
+          }
+          continue;
+        }
+
+        if (value) {
+          usedOptions[str] = (usedOptions[str] ?? 0) + 1;
+        } else {
+          othersCount++;
+        }
+      }
+    }
+
+    const options = Object.entries(usedOptions)
+      .map(([value, count]) => ({ value, count }))
+      .sort((a, b) => b.value.localeCompare(a.value));
+
+    if (othersCount) {
+      options.push({ value: filter.missingCategoryName || 'Others', count: othersCount });
+    }
+    return { ...filter, options };
+  });
+}
+
+function filterItems(
+  normalizedItems: CatalogItem[],
+  filters: Omit<ResolvedFilter, 'parentUsed' | 'filteredOptions'>[],
+  term: string,
+) {
+  // filter by filters first, and then by search term
+  const filteredByFilters = normalizedItems.filter((item) => {
+    return filters.every((filter) => {
+      if (filter.selectedOptions.size === 0) {
+        return true;
+      }
+      const itemValue = item?.[filter.property] || filter.missingCategoryName || 'Others';
+      if (Array.isArray(itemValue)) {
+        return itemValue.some((value) => filter.selectedOptions.has(value));
+      }
+      return filter.selectedOptions.has(itemValue as string);
+    });
+  });
+
+  if (term) {
+    term = term.toLowerCase();
+    return filteredByFilters.filter((item) => {
+      return Object.values(item).some((value) => {
+        return Array.isArray(value)
+          ? value.some((value) => String(value).toLowerCase().includes(term))
+          : String(value).toLowerCase().includes(term);
+      });
+    });
+  } else {
+    return filteredByFilters;
+  }
+}

package/src/components/CodeBlock/index.ts

@@ -0,0 +1 @@
+export * from '@theme/components/CodeBlock/CodeBlock';

package/src/components/CodeSample/CodeSample.tsx

@@ -0,0 +1,236 @@
+import React, { useState } from 'react';
+import styled, { css } from 'styled-components';
+
+import { ClipboardService } from '@theme/utils/ClipboardService';
+import { useThemeConfig } from '@theme/hooks/useThemeConfig';
+import { ReportDialog, useReportDialog } from '@theme/components/Feedback';
+
+export type CodeSampleProps = {
+  language: string;
+  highlighted: string;
+  rawContent: string;
+  'data-source'?: string;
+  'data-hash'?: string;
+};
+
+export function CodeSample({
+  rawContent,
+  highlighted,
+  language,
+  'data-source': dataSource,
+  'data-hash': dataHash,
+}: CodeSampleProps): JSX.Element {
+  const langClassName = language ? `language-${language}` : '';
+  const { codeSnippet: { copy = {}, report = {} } = {} } = useThemeConfig();
+
+  const [isCopied, setIsCopied] = useState(false);
+  const { isReportDialogShown, isReportButtonShown, reportButtonProps, reportDialogProps } =
+    useReportDialog(report);
+
+  const copyCode = (code: string) => {
+    ClipboardService.copyCustom(code);
+    setIsCopied(true);
+    setTimeout(() => setIsCopied(false), copy.toasterDuration || 1500);
+  };
+
+  return (
+    <Wrapper
+      className="code-sample"
+      data-component-name="Markdown/CodeSample/CodeSample"
+      data-source={dataSource}
+      data-hash={dataHash}
+    >
+      <CodeSampleButtonContainer>
+        {!copy.hide && (
+          <>
+            {!isCopied && (
+              <Button
+                onClick={() => copyCode(rawContent)}
+                title={copy.tooltipText || 'Copy to clipboard'}
+              >
+                {copy.buttonText || 'Copy'}
+              </Button>
+            )}
+            {isCopied && <DoneIndicator>{copy.toasterText || 'Copied!'}</DoneIndicator>}
+          </>
+        )}
+
+        {isReportButtonShown && <Button {...reportButtonProps}>Report</Button>}
+
+        {isReportDialogShown && <ReportDialog {...reportDialogProps} location={rawContent} />}
+      </CodeSampleButtonContainer>
+      <pre className={langClassName}>
+        <code className={langClassName} dangerouslySetInnerHTML={{ __html: highlighted }} />
+      </pre>
+    </Wrapper>
+  );
+}
+
+const CodeSampleButtonContainer = styled.div`
+  display: flex;
+  position: absolute;
+  top: 12px;
+  right: 5px;
+`;
+
+const Button = styled.div`
+  padding: var(--code-block-controls-padding);
+  border-radius: var(--code-block-controls-border-radius);
+  font-size: var(--code-block-controls-font-size);
+  font-family: var(--code-block-controls-font-family);
+  &:hover {
+    cursor: pointer;
+  }
+
+  @media print {
+    display: none;
+  }
+`;
+
+const DoneIndicator = styled.div`
+  padding: var(--code-block-controls-padding);
+  border-radius: var(--code-block-controls-border-radius);
+  font-size: var(--code-block-controls-font-size);
+  font-family: var(--code-block-controls-font-family);
+  cursor: default;
+`;
+
+const darkStyleTokens = css`
+  .token.comment,
+  .token.prolog,
+  .token.doctype,
+  .token.cdata {
+    color: hsl(30, 20%, 50%);
+  }
+  .token.property,
+  .token.tag,
+  .token.number,
+  .token.constant,
+  .token.symbol {
+    color: #62bff9;
+  }
+  .token.boolean {
+    color: firebrick;
+  }
+  .token.selector,
+  .token.attr-name,
+  .token.string,
+  .token.char,
+  .token.builtin,
+  .token.inserted {
+    color: #a0fbaa;
+    & + a,
+    & + a:visited {
+      color: #4ed2ba;
+      text-decoration: underline;
+    }
+  }
+  .token.operator,
+  .token.entity,
+  .token.url,
+  .token.variable {
+    color: hsl(40, 90%, 60%);
+  }
+  .token.atrule,
+  .token.attr-value,
+  .token.keyword {
+    color: hsl(350, 40%, 70%);
+  }
+  .token.regex,
+  .token.important {
+    color: #e90;
+  }
+  .token.deleted {
+    color: red;
+  }
+`;
+
+const Wrapper = styled.div`
+  overflow: auto;
+  border-radius: 4px;
+  position: relative;
+
+  ${Button},
+  ${DoneIndicator} {
+    color: var(--code-block-controls-text-color);
+    background-color: var(--code-block-controls-background-color);
+    opacity: var(--code-block-controls-opacity);
+  }
+  ${Button}:hover {
+    color: var(--code-block-controls-hover-text-color);
+    background-color: var(--code-block-controls-hover-background-color);
+    opacity: var(--code-block-controls-active-opacity);
+  }
+
+  pre {
+    white-space: var(--code-wrap);
+    color: white;
+    padding: 12px 14px 15px 14px;
+    overflow-x: auto;
+    line-height: normal;
+    border-radius: var(--code-block-border-radius);
+    font-family: var(--code-font-family);
+    background-color: var(--code-block-background-color);
+
+    print-color-adjust: exact;
+    -webkit-print-color-adjust: exact;
+
+    code {
+      background-color: transparent;
+      border: 0;
+      padding: 0;
+      color: var(--code-block-text-color);
+      &:before,
+      &:after {
+        content: none;
+      }
+    }
+  }
+  pre[class*='language-'] {
+    padding: 1em;
+    margin: 0.5em 0;
+    overflow: auto;
+    border: 0;
+    border-radius: var(--border-radius);
+  }
+  code[class='language-text'] {
+    line-height: 1.2em;
+    display: inline-flex;
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+  }
+  code[class*='language-'],
+  pre[class*='language-'] {
+    text-align: left;
+    white-space: pre;
+    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;
+    .token.important,
+    .token.bold {
+      font-weight: bold;
+    }
+    .token.italic {
+      font-style: italic;
+    }
+    .token.entity {
+      cursor: help;
+    }
+    .token.punctuation {
+      opacity: 0.7;
+    }
+    .namespace {
+      opacity: 0.7;
+    }
+
+    ${darkStyleTokens};
+  }
+`;

package/src/components/CodeSample/index.ts

@@ -0,0 +1 @@
+export * from '@theme/components/CodeSample/CodeSample';

package/src/components/ColorModeSwitcher/index.ts

@@ -0,0 +1 @@
+export * from '@theme/components/ColorModeSwitcher/ColorModeSwitcher';

package/src/components/CopyButton/CopyButton.tsx

@@ -0,0 +1,31 @@
+import React, { useState } from 'react';
+import copy from 'copy-to-clipboard';
+import { Button } from '@theme';
+
+export interface CopyButtonProps {
+  text: string;
+  dataTestId?: string;
+}
+
+export const CopyButton = ({ text, dataTestId = 'copy-button' }: CopyButtonProps): JSX.Element => {
+  const [title, setTitle] = useState('Copy');
+
+  async function write() {
+    await copy(text);
+
+    setTitle('Copied!');
+
+    setTimeout(() => setTitle('Copy'), 1500);
+  }
+
+  return (
+    <Button
+      color="secondary"
+      onClick={write}
+      data-cy={dataTestId}
+      data-component-name="CopyButton/CopyButton"
+    >
+      {title}
+    </Button>
+  );
+};

package/src/components/CopyButton/CopyButtonWrapper.tsx

@@ -0,0 +1,55 @@
+import React, { memo } from 'react';
+
+import { SamplesControlButton } from '@theme/components/SamplesPanelControls';
+import { Tooltip } from '@theme/components/Tooltip';
+import { useControl } from '@theme/hooks';
+import { ClipboardService } from '@theme/utils';
+import type { TooltipProps } from '@theme/components/Tooltip';
+
+export interface CopyButtonWrapperProps {
+  data: unknown;
+  children: (props: {
+    renderCopyButton: (placement?: TooltipProps['placement']) => JSX.Element;
+  }) => JSX.Element;
+  onCopyClick?: () => void;
+  dataTestId?: string;
+}
+
+function CopyButtonWrapperComponent({
+  data,
+  children,
+  onCopyClick,
+  dataTestId = 'copy-button',
+}: CopyButtonWrapperProps): JSX.Element {
+  const tooltip = useControl();
+
+  const showTooltip = (): void => {
+    tooltip.handleOpen();
+
+    setTimeout(() => {
+      tooltip.handleClose();
+    }, 1500);
+  };
+
+  const copy = (): void => {
+    const content = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+    ClipboardService.copyCustom(content);
+    showTooltip();
+
+    onCopyClick?.();
+  };
+
+  const renderCopyButton = (placement: TooltipProps['placement'] = 'top'): JSX.Element => {
+    return (
+      <Tooltip className="copy-button" tip="Copied" isOpen={tooltip.isOpened} placement={placement}>
+        <SamplesControlButton onClick={copy} data-cy={dataTestId}>
+          Copy
+        </SamplesControlButton>
+      </Tooltip>
+    );
+  };
+
+  return children({ renderCopyButton });
+}
+
+export const CopyButtonWrapper = memo<CopyButtonWrapperProps>(CopyButtonWrapperComponent);

package/src/components/CopyButton/index.ts

@@ -0,0 +1,2 @@
+export * from '@theme/components/CopyButton/CopyButtonWrapper';
+export * from '@theme/components/CopyButton/CopyButton';