@redocly/theme 0.0.0-react18-20231120182601

package/src/components/Catalog/CatalogCard.tsx

@@ -0,0 +1,171 @@
+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 { Tag } from '@theme/components/Tag';
+import { PointingArrowIcon } from '@theme/icons';
+import { telemetry } from '@portal/telemetry';
+import { slug, capitalize } from '@theme/utils';
+import { getLevelColor } from '@theme/components/Scorecard/Card';
+
+export function CatalogCard({ item }: { item: CatalogItem }): JSX.Element {
+  const hasTags = item.scorecardLevel || item.tags?.length;
+  return (
+    <Link key={item.docsLink || item.link} to={item.docsLink || item.link}>
+      <StyledCard onClick={() => telemetry.send('catalog_item_clicked', {})}>
+        <CardTitle>
+          <Highlight>{item.title}</Highlight>
+        </CardTitle>
+        <CardContent>
+          <CardDescription>
+            <Highlight>{item.description ?? ''}</Highlight>
+          </CardDescription>
+          <CardFooter>
+            {hasTags && (
+              <CardTags>
+                {((item.tags as string[]) || []).map((tag, index) => (
+                  <CardTag key={tag + index} color={slug(tag)}>
+                    <Highlight>{capitalize(tag)}</Highlight>
+                  </CardTag>
+                ))}
+                {(item.scorecardLevel && (
+                  <StatusDot
+                    color={getLevelColor(
+                      item.scorecardLevelIdx || -1,
+                      Object.keys(item.scorecardLevels || {}).length,
+                    )}
+                  >
+                    <Highlight>{item.scorecardLevel}</Highlight>
+                  </StatusDot>
+                )) ||
+                  null}
+              </CardTags>
+            )}
+            <SelectButton>
+              <PointingArrowIcon />
+            </SelectButton>
+          </CardFooter>
+        </CardContent>
+      </StyledCard>
+    </Link>
+  );
+}
+
+const SelectButton = styled.div`
+  border: 1px solid var(--catalog-card-button-border-color);
+  border-radius: 100%;
+  min-width: var(--catalog-card-button-width);
+  width: var(--catalog-card-button-width);
+  height: var(--catalog-card-button-height);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: all 0.2s ease-in-out;
+
+  svg {
+    fill: var(--catalog-card-icon-color);
+  }
+`;
+
+const StyledCard = styled.div.attrs({ 'data-cy': 'Catalog/CatalogCard' })`
+  min-height: var(--catalog-card-min-height);
+  height: 100%;
+  color: var(--catalog-card-text-color);
+  font-size: var(--catalog-card-font-size);
+  font-weight: var(--catalog-card-font-weight);
+  background-color: var(--catalog-card-background-color);
+  border: var(--catalog-card-border-width) var(--catalog-card-border-style) var(--catalog-card-border-color);
+  transition: all 0.2s ease-in-out;
+  border-radius: var(--catalog-card-border-radius);
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+
+  &:hover {
+    border-color: var(--catalog-card-hover-border-color);
+
+    ${SelectButton} {
+      transform: rotate(-45deg);
+      border-color: var(--catalog-card-hover-border-color);
+      background: var(--catalog-card-button-hover-background);
+
+      svg {
+        fill: var(--catalog-card-icon-hover-color);
+      }
+    }
+`;
+
+const CardTitle = styled.h4`
+  color: var(--catalog-card-title-color);
+  min-height: var(--catalog-card-title-min-height);
+  font-size: var(--catalog-card-title-font-size);
+  font-weight: var(--catalog-card-title-font-weight);
+  margin: 0;
+  padding: var(--catalog-card-title-padding-vertical) var(--catalog-card-title-padding-horizontal);
+`;
+
+const CardDescription = styled.div`
+  display: -webkit-box;
+  -webkit-line-clamp: var(--catalog-card-description-line-clamp);
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  margin-bottom: var(--catalog-card-description-margin-bottom);
+`;
+
+const CardContent = styled.div`
+  background-color: var(--catalog-card-content-background-color);
+  border-radius: var(--catalog-card-content-border-radius);
+  padding: var(--catalog-card-content-padding);
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+`;
+
+const CardFooter = styled.div`
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+`;
+
+const CardTags = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--spacing-xxs);
+  min-height: var(--spacing-xl);
+`;
+
+const CardTag = styled(Tag)`
+  display: block;
+  text-transform: inherit;
+  margin: 0;
+`;
+
+const StatusDot = styled.div<{ color: string }>`
+  font-size: var(--font-size-base);
+  font-style: normal;
+  font-weight: 400;
+  line-height: 22px;
+  display: flex;
+  align-items: center;
+  &:not(:only-child) {
+    margin-left: 4px;
+  }
+
+  ${({ color }) =>
+    color &&
+    `
+  &::before {
+    content: '';
+    display: inline-block;
+    width: 10px;
+    height: 10px;
+    border-radius: 50%;
+    background-color: ${color};
+    margin-right: 8px;
+  }`};
+`;

package/src/components/Catalog/index.ts

@@ -0,0 +1,4 @@
+export * from '@theme/components/Catalog/Catalog';
+export * from '@theme/components/Catalog/CatalogCard';
+export * from '@theme/components/Catalog/useCatalog';
+export * from '@theme/components/Catalog/styledVariables';

package/src/components/Catalog/styledVariables.ts

@@ -0,0 +1,94 @@
+import { css } from 'styled-components';
+
+export const catalog = css`
+  /* === Catalog === */
+  /**
+    * @tokens Catalog page
+    */
+  --catalog-page-padding-vertical: var(--spacing-lg);
+  --catalog-page-padding-horizontal: var(--spacing-xl);
+  --catalog-page-padding: var(--catalog-page-padding-vertical) var(--catalog-page-padding-horizontal);
+
+  --mobile-catalog-filter-padding-vertical: var(--spacing-sm);
+  --mobile-catalog-filter-padding-horizontal: var(--spacing-base);
+
+  --catalog-heading-margin: 0 0 var(--spacing-xl) 0;
+
+  /**
+    * @tokens Catalog page title
+    */
+  --catalog-title-text-color: var(--text-primary);
+  --catalog-title-font-weight: var(--font-weight-bold);
+  --catalog-title-font-size: var(--font-size-heading-3);
+  --catalog-title-margin: 0 0 var(--spacing-sm) 0;
+
+  /**
+    * @tokens Catalog page description
+    */
+  --catalog-description-text-color: var(--text-secondary);
+  --catalog-description-font-weight: var(--font-weight-regular);
+  --catalog-description-font-size: var(--font-size-base);
+  --catalog-description-margin: 0 0 var(--spacing-sm) 0;
+
+  /**
+    * @tokens Catalog page separator
+    */
+  --catalog-separator-color: var(--text-secondary);
+  --catalog-separator-font-size: var(--font-size-base);
+  --catalog-separator-font-weight: var(--font-weight-regular);
+  --catalog-separator-border-color: var(--border-secondary);
+  --catalog-separator-margin: 0 0 var(--spacing-base) 0;
+  --catalog-separator-padding: var(--spacing-xxs) 0 0 0;
+  --catalog-separator-label-margin: 0 var(--spacing-xs);
+  --catalog-separator-count-height: var(--control-height-xs);
+  --catalog-separator-count-padding: 0 var(--spacing-xxs);
+  --catalog-separator-count-border-radius: var(--border-radius-xlg);
+  --catalog-separator-count-border-color: var(--border-primary);
+  --catalog-separator-count-background: var(--bg-overlay);
+
+  /**
+    * @tokens Catalog card
+    */
+  --catalog-card-min-height: 214px;
+  --catalog-card-text-color: var(--text-secondary);
+  --catalog-card-font-size: var(--font-size-base);
+  --catalog-card-font-weight: var(--font-weight-regular);
+  --catalog-card-background-color: var(--bg-raised);
+  --catalog-card-border-color: var(--border-secondary);
+  --catalog-card-border-width: var(--border-width);
+  --catalog-card-border-style: var(--border-style);
+  --catalog-card-hover-border-color: var(--border-primary);
+  --catalog-card-border-radius: var(--border-radius-lg);
+
+  /**
+    * @tokens Catalog card button
+    */
+  --catalog-card-icon-color: var(--text-secondary);
+  --catalog-card-icon-hover-color: var(--text-primary);
+  --catalog-card-button-hover-background: var(--bg-overlay);
+  --catalog-card-button-height: var(--spacing-xl);
+  --catalog-card-button-width: var(--spacing-xl);
+  --catalog-card-button-border-color: var(--border-secondary);
+  --catalog-cards-group-margin: 0 0 var(--spacing-base) 0;
+
+  /**
+    * @tokens Catalog card title
+    */
+  --catalog-card-title-color: var(--text-primary);
+  --catalog-card-title-min-height: calc(var(--spacing-unit) * 18);
+  --catalog-card-title-font-size: var(--font-size-lg);
+  --catalog-card-title-font-weight: var(--font-weight-bold);
+  --catalog-card-title-padding-vertical: var(--spacing-sm);
+  --catalog-card-title-padding-horizontal: var(--spacing-base);
+
+  /**
+    * @tokens Catalog card description
+    */
+  --catalog-card-description-line-clamp: 3;
+  --catalog-card-description-margin-bottom: var(--spacing-base);
+  --catalog-card-content-background-color: var(--bg-base);
+  --catalog-card-content-border-radius: var(--border-radius-lg);
+  --catalog-card-content-padding: var(--spacing-base);
+  
+  // @tokens End
+`;

package/src/components/Catalog/useCatalog.ts

@@ -0,0 +1,373 @@
+import * as React from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+
+import type { Location } from 'react-router-dom';
+
+import { telemetry } from '@portal/telemetry';
+import { usePageData } from '@portal/hooks/usePageData';
+import type { ResolvedNavItem } from '@theme/types/portal';
+import type {
+  CatalogItem,
+  FilteredCatalog,
+  ResolvedFilter,
+} from '@theme/types/portal/src/shared/types/catalog';
+import { findDeepFirst, toStringIfDefined, withoutHash } from '@theme/utils';
+import type { CatalogConfig, CatalogFilterConfig } from '@theme/config';
+
+export function useCatalog(items: ResolvedNavItem[], config: CatalogConfig): FilteredCatalog {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const pageData = usePageData();
+  const searchParams = useSearchParams(location);
+  const [filtersState, setFiltersState] = React.useState(() =>
+    (config.filters ?? []).map((f) => {
+      if (f.type === 'date-range') {
+        const [from, to] = searchParams.get(f.property)?.split('--') ?? [];
+        if (!from && !to) return {};
+        return { from, to };
+      }
+      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 customFields = pageData?.props?.customFields;
+  const normalizedItems = React.useMemo(
+    () => normalizeItems(items, config, customFields || ({} as any)),
+    [items, config, customFields],
+  );
+
+  const toggleOption = React.useCallback((filterIdx: number, option: any) => {
+    setFiltersState((prev) => {
+      const newFilterOptions = prev[filterIdx] ? prev[filterIdx] : new Set<string>();
+      if (!(newFilterOptions instanceof Set)) return prev;
+      if (newFilterOptions.has(option)) {
+        newFilterOptions.delete(option);
+      } else {
+        newFilterOptions.add(option);
+      }
+      return [...prev.slice(0, filterIdx), newFilterOptions, ...prev.slice(filterIdx + 1)];
+    });
+    telemetry.send('catalog_filter_changed', { type: 'toggle' });
+    window.scrollTo(0, 0);
+  }, []);
+
+  const selectOption = React.useCallback(
+    (filterIdx: number, option: any) => {
+      setFiltersState((prev) => {
+        const newFilterOptions =
+          prev[filterIdx] instanceof Set
+            ? new Set<string>(option ? [option] : [])
+            : {
+                from: option?.from,
+                to: option?.to,
+              };
+        const filter = filtersWithOptions[filterIdx];
+
+        return prev.map((f, idx) =>
+          idx === filterIdx
+            ? newFilterOptions
+            : filtersWithOptions[idx].parentFilter === filter.property
+            ? new Set()
+            : f,
+        );
+      });
+      telemetry.send('catalog_filter_changed', { type: 'select' });
+      window.scrollTo(0, 0);
+    },
+    [filtersWithOptions],
+  );
+
+  React.useEffect(() => {
+    filtersState.forEach((filterValues, filterIdx) => {
+      const filter = config.filters?.[filterIdx];
+      if (!filter) return;
+      searchParams.delete(filter.property);
+      if (filterValues instanceof Set) {
+        filterValues.forEach((value) => {
+          searchParams.append(filter.property, value);
+        });
+      } else if (filterValues.from || filterValues.to) {
+        searchParams.append(
+          filter.property,
+          `${filterValues.from || ''}--${filterValues.to || ''}`,
+        );
+        return;
+      }
+    });
+
+    if (filterTerm) {
+      searchParams.set('filter', filterTerm);
+    } else {
+      searchParams.delete('filter');
+    }
+    const newSearch = searchParams.toString();
+    if (newSearch === location.search.substring(1)) return;
+    navigate({ search: newSearch });
+  }, [config.filters, searchParams, filtersState, filterTerm, navigate, location]);
+
+  // 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] as any)?.size ?? 0) > 0 || !!(filtersState[idx] as any)?.from,
+    }));
+
+    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] as any)?.size ?? 0) > 0 ||
+          !!(filtersState[parentFilterIdx] as any).from
+        : 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
+      ? groupByFirstFilter(resolvedFilters, filteredItems)
+      : [{ title: 'APIs', items: filteredItems }];
+
+    return {
+      groups,
+      filters: resolvedFilters,
+      setFilterTerm: (newTerm) => {
+        setFilterTerm(newTerm);
+
+        telemetry.send('catalog_filter_changed', { type: 'term' });
+      },
+      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,
+  customFields: Record<string, Record<string, unknown>>,
+): CatalogItem[] {
+  // because of RBAC some versions can be missing so we need to pick up other default version
+  const hasDeafultVersion: Record<string, boolean> = {};
+  for (const item of items) {
+    if (item.versionFolderId && item.isDefault) {
+      hasDeafultVersion[item.versionFolderId] = true;
+    }
+  }
+
+  if (!config.separateVersions) {
+    // keep only default version
+    // idea: save other versions information (may be useful for cards)
+    items = items.filter((item) => {
+      if (!item.versionFolderId) return true;
+      if (!hasDeafultVersion[item.versionFolderId]) {
+        // we already picked the default version so let's ignore next versions
+        hasDeafultVersion[item.versionFolderId] = true;
+        return true;
+      }
+      return item.isDefault;
+    });
+  }
+
+  return items.map((item) => {
+    const metadata = item.metadata || {};
+    const apiCustomFields = customFields[item.fsPath || ''] || {};
+    const link = item.link || findDeepFirst(item.items || [], (i) => 'link' in i && !!i.link)?.link;
+    const firstSidebarItem = (item as any).sidebar?.[0];
+    return {
+      ...metadata,
+      ...apiCustomFields,
+      publishedAt: metadata.publishedAt || metadata.createdAt,
+      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: CatalogFilterConfig[] | 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 = mapFilterValues(String(value), filter.valuesMapping) as string;
+        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 }));
+
+    if (!staticOptions) {
+      options.sort((a, b) => b.value.localeCompare(a.value));
+    }
+
+    if (othersCount) {
+      options.push({
+        value: filter.missingCategoryNameTranslationKey || 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 && !(filter.selectedOptions instanceof Set)) {
+        try {
+          const date = new Date(item[filter.property] as string).toISOString().split('T')[0];
+          return (
+            date >= (filter.selectedOptions.from ?? '') &&
+            date <= (filter.selectedOptions.to ?? 'Z')
+          );
+        } catch (e) {
+          return true;
+        }
+      }
+
+      if (filter.selectedOptions.size === 0) {
+        return true;
+      }
+
+      const itemValue = mapFilterValues(
+        item?.[filter.property] || filter.missingCategoryName || 'Others',
+        filter.valuesMapping,
+      );
+
+      if (Array.isArray(itemValue)) {
+        return itemValue.some((value) => (filter.selectedOptions as Set<any>).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;
+  }
+}
+
+function mapFilterValues(value: unknown | unknown[], mapping?: Record<string, string>) {
+  if (!mapping) return value;
+  return Array.isArray(value)
+    ? value.map((v) => mapping[String(v)] || v)
+    : mapping[String(value)] || value;
+}