@redocly/theme 0.5.0 → 0.6.0

package/src/config.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+const LogoConfig = z
+  .object({
+    image: z.string().optional(),
+    altText: z.string().optional(),
+    link: z.string().optional(),
+    favicon: z.string().optional(),
+  })
+  .strict();
+
+const HideConfig = z.object({
+  hide: z.boolean().optional(),
+});
+
+export const ThemeConfig = z
+  .object({
+    imports: z.array(z.string()).default([]).optional(),
+
+    logo: LogoConfig.optional(),
+    navbar: HideConfig.strict().optional(),
+    footer: HideConfig.strict().optional(),
+    sidebar: HideConfig.strict().optional(),
+    navbarItems: z.any().optional(), // todo: think about validation here
+    footerItems: z.any().optional(), // todo: think about validation here
+
+    scripts: z
+      .array(z.union([z.string(), z.record(z.union([z.boolean(), z.string()]))]))
+      .optional(),
+    postBodyScripts: z
+      .array(z.union([z.string(), z.record(z.union([z.boolean(), z.string()]))]))
+      .optional(),
+    styles: z.array(z.union([z.string(), z.record(z.union([z.boolean(), z.string()]))])).optional(),
+
+    search: z
+      .object({
+        placement: z.string().default('navbar').optional(),
+      })
+      .extend(HideConfig.shape)
+      .strict()
+      .default({})
+      .optional(),
+
+    colorMode: z
+      .object({
+        disableDetect: z.boolean().optional(),
+        default: z.string().optional(),
+        modes: z.array(z.string()).default(['light', 'dark']).optional(),
+      })
+      .extend(HideConfig.shape)
+      .strict()
+      .optional()
+      .default({}),
+    navigation: z
+      .object({
+        nextPageLink: z
+          .object({ label: z.string().default('Next to {label}') })
+          .extend(HideConfig.shape)
+          .optional()
+          .default({}),
+        prevPageLink: z
+          .object({ label: z.string().default('Back to {label}') })
+          .extend(HideConfig.shape)
+          .optional()
+          .default({}),
+      })
+      .strict()
+      .optional()
+      .default({}),
+    markdown: z
+      .object({
+        frontmatterKeysToResolve: z.array(z.string()).default(['image', 'links']).optional(),
+        lastUpdatedBlock: z
+          .object({
+            format: z.enum(['timeago', 'iso', 'long', 'short']).default('timeago').optional(),
+            locale: z.string().default('en-US').optional(),
+          })
+          .extend(HideConfig.shape)
+          .default({})
+          .optional(),
+        toc: z
+          .object({
+            header: z.string().default('On this page').optional(),
+            maxDepth: z.number().default(3).optional(),
+          })
+          .extend(HideConfig.shape)
+          .optional()
+          .default({}),
+        editPage: z
+          .object({
+            baseUrl: z.string().optional(),
+            icon: z.string().optional(),
+            text: z.string().optional().default('Edit this page'),
+          })
+          .extend(HideConfig.shape)
+          .default({})
+          .optional(),
+        copyCodeSnippet: z
+          .object({
+            buttonText: z.string().default('Copy').optional(),
+            tooltipText: z.string().default('Copy to clipboard').optional(),
+            toasterText: z.string().default('Copied').optional(),
+            toasterDuration: z.number().default(1500).optional(),
+          })
+          .extend(HideConfig.shape)
+          .optional()
+          .default({}),
+      })
+      .strict()
+      .default({})
+      .optional(),
+    openapi: z.object({}).passthrough().optional(),
+    graphql: z.object({}).passthrough().optional(),
+  })
+  .passthrough()
+  .default({});
+
+export type ThemeConfig = z.infer<typeof ThemeConfig>;
+export type ThemeUIConfig = Omit<
+  ThemeConfig,
+  'navbarItems' | 'footerItems' | 'styles' | 'scripts' | 'postBodyScripts'
+> & {
+  navbarItems?: any; // TODO
+  footerItems?: any; // TODO
+  auth?: {
+    // used by portal dev login emulator
+    idpIds?: string[];
+    devLogin?: boolean;
+  };
+};

package/src/globalStyle.ts

@@ -182,7 +182,7 @@ const headingsTypography = css`
   --heading-anchor-color: var(--color-primary-500); // @presenter Color
   --heading-anchor-icon: none;
 
-  // TODO: implement a theme setting for heading-anchor-location: left right
+  // TODO: implement a theme config for heading-anchor-location: left right
 
   /**
   * @tokens Heading level 1
@@ -316,7 +316,6 @@ const buttons = css`
   --button-active-background-color: var(--color-emphasis-600); // @presenter Color
   --button-active-border-color: var(--color-emphasis-600); // @presenter Color
 
-  /* TODO more styles for disabled state ??? */
   --button-disabled-color: var(--button-color); // @presenter Color
   --button-disabled-background-color: var(--color-emphasis-200); // @presenter Color
 
@@ -495,8 +494,8 @@ const sidebar = css`
   --sidebar-item-group-active-text-color: var(--sidebar-item-active-color);
   --sidebar-item-group-active-background-color: var(--sidebar-item-active-background-color);
 
-  // we need a theme setting for chevron-location: left (default), right-compact, right, none
-  // we need another theme setting for chevron-style: up-down, down-up, right-down, down-right
+  // we need a theme config for chevron-location: left (default), right-compact, right, none
+  // we need another theme config for chevron-style: up-down, down-up, right-down, down-right
 
   --sidebar-group-item-chevron-size: var(--sidebar-spacing-unit);
   --sidebar-group-item-chevron-color: var(--sidebar-item-text-color);
@@ -556,7 +555,6 @@ const admonition = css`
   --admonition-padding-vertical: calc(var(--spacing-unit) * 4);
   --admonition-icon-size: 25px;
 
-  // TODO this is should be changed to --border-radius-lg
   /**
   * @tokens Admonition border
   */

package/src/hooks/index.ts

@@ -1,3 +1,4 @@
+export * from '@theme/hooks/useThemeConfig';
 export * from '@theme/hooks/useControl';
 export * from '@theme/hooks/useMount';
 export * from '@theme/hooks/useUnmount';

package/src/hooks/useActiveHeading.ts

@@ -11,7 +11,9 @@ export function useActiveHeading(
   contentElement: HTMLDivElement | null,
   displayedHeaders: Array<string | undefined>,
 ): UseActiveHeadingReturnType {
-  const [heading, setHeading] = useState<string | undefined>(undefined);
+  const [heading, setHeading] = useState<string | undefined>(
+    displayedHeaders.length > 1 ? displayedHeaders[0] : undefined,
+  );
   const [headingElements, setHeadingElements] = useState<HTMLElement[]>([]);
   const headingElementsRef = useRef<HeadingEntry>({});
 

package/src/hooks/useActiveSectionId.ts

@@ -46,7 +46,7 @@ export function useActiveSectionId(
     }, 0);
 
     return () => {
-      window.removeEventListener('scroll', scrollListener); // TODO: add throttle
+      window.removeEventListener('scroll', scrollListener);
     };
   }, [location, navbarHeight, scrollListener]);
 

package/src/hooks/useThemeConfig.ts

@@ -0,0 +1 @@
+export { useThemeConfig } from '@portal/hooks';

package/src/icons/ColorModeIcon/ColorModeIcon.tsx

@@ -11,7 +11,7 @@ function Icon({ mode, className }: ColorModeIconProps) {
     case 'dark':
       return (
         <svg
-          className={className}
+          className={className + ' dark'}
           data-testid="dark"
           viewBox="0 0 16 16"
           xmlns="http://www.w3.org/2000/svg"
@@ -23,7 +23,7 @@ function Icon({ mode, className }: ColorModeIconProps) {
       return (
         <svg
           data-testid="light"
-          className={className}
+          className={className + ' light'}
           viewBox="0 0 16 16"
           xmlns="http://www.w3.org/2000/svg"
         >
@@ -34,7 +34,7 @@ function Icon({ mode, className }: ColorModeIconProps) {
       return (
         <svg
           data-testid="custom"
-          className={className}
+          className={className + (mode ? ' ' + mode : '')}
           viewBox="0 0 16 16"
           xmlns="http://www.w3.org/2000/svg"
         >

package/src/index.ts

@@ -17,3 +17,6 @@ export * from './OperationBadge';
 export * from './TableOfContent';
 export * from './Profile';
 export * from './ColorModeSwitcher';
+export * from './Sidebar';
+export * from './types/config';
+export * from './config';

package/src/mocks/Link.tsx

@@ -3,7 +3,14 @@ import React from 'react';
 // TODO: use real typings here
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
 export function Link(props: any): JSX.Element {
-  const { active: _, httpVerb: _1, hasActiveSubItem: _2, ...filteredProps } = props;
+  const {
+    active: _,
+    httpVerb: _1,
+    hasActiveSubItem: _2,
+    routeSlug: _3,
+    external: _4,
+    ...filteredProps
+  } = props;
   // We omit "active" property to avoid "Warning: Received `false` for a non-boolean attribute `active`."
   return <a href={filteredProps.to} {...filteredProps} />;
 }

package/src/mocks/hooks/index.ts

@@ -1,7 +1,4 @@
-interface RawTheme {
-  name: string;
-  settings?: any;
-}
+import type { ThemeUIConfig } from '@theme/config';
 
 interface PageLink {
   label: string;
@@ -9,18 +6,34 @@ interface PageLink {
   type: 'link';
 }
 
-export function useThemeSettings(_: string): RawTheme['settings'] {
+export function useThemeConfig<T extends Record<string, unknown>>(): T & ThemeUIConfig {
   return {
-    toc: { header: { label: 'header' }, hide: false },
+    search: { hide: false, placement: 'navbar' },
+    markdown: {
+      toc: { maxDepth: 3, header: 'Table of contents', hide: false },
+      lastUpdatedBlock: { hide: false, format: 'timeago', locale: 'en-US' },
+      copyCodeSnippet: {
+        hide: false,
+        buttonText: 'Copy',
+        tooltipText: 'Copy to clipboard',
+        toasterText: 'Copied',
+        toasterDuration: 1500,
+      },
+      editPage: {
+        baseUrl: '',
+        text: 'Edit this page',
+      },
+      frontmatterKeysToResolve: ['image', 'links'],
+    },
     navigation: {
-      nextPageLink: { label: 'next page theme settings label' },
-      prevPageLink: { label: 'prev page theme settings label' },
+      nextPageLink: { label: 'next page theme config label' },
+      prevPageLink: { label: 'prev page theme config label' },
     },
     colorMode: {
       modes: ['light', 'dark'],
       default: 'light',
     },
-  };
+  } as ThemeUIConfig as T & ThemeUIConfig;
 }
 
 export function useSidebarSiblingsData(): { nextPage: PageLink | null; prevPage: PageLink | null } {

package/src/mocks/types.ts

@@ -1,14 +1,5 @@
 export type ActiveItem<T> = T;
 export type SearchDocument = any;
 export type OperationParameter = any;
-export interface RawTheme {
-  name: string;
-  settings: {
-    lastUpdatedBlock?: {
-      hide?: boolean;
-      format?: 'timeago' | 'iso' | 'short' | 'long';
-      locale?: string;
-    };
-    [k: string]: any; // TODO: add missing settings
-  };
-}
+
+// TODO: get rid of these types

package/src/mocks/utils.ts

@@ -3,7 +3,7 @@ export function withPathPrefix(link: string): string {
 }
 
 export function timeAgo(lastModified: string | Date): string {
-  // should return format(lastModified) in new-hope
+  // should return format(lastModified) in portal
   const d = new Date(lastModified);
   return `${d.getDate()}-${d.getMonth() + 1}-${d.getFullYear()}`;
 }

package/src/types/config.ts

@@ -0,0 +1,5 @@
+export type DefaultThemeUIConfig = {
+  lastUpdatedBlock?: {
+    hide?: boolean;
+  };
+};

package/src/types/portal/src/shared/constants.d.ts

@@ -1,6 +1,5 @@
 export declare const RUNTIME_RESOURCES_DIR = 'runtime';
 export declare const REDOC_OVERVIEW_ITEM_ID = 'overview';
-export declare const PORTAL_CUSTOM_THEMES_FOLDER = '@theme';
 export declare const DEFAULT_THEME_NAME = '@redocly/theme';
 export declare const CUSTOM_MARKDOC_OPTIONS_PATH = 'markdoc';
 export declare const CUSTOM_MARKDOC_TAGS_PATH = 'tags';

package/src/utils/args-typecheck.ts

@@ -5,5 +5,5 @@ export function isEmptyArray(items: any): boolean {
 
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
 export function isPrimitive(arg: any): boolean {
-  return ['string', 'boolean', 'number'].includes(typeof arg);
+  return ['string', 'boolean', 'number', 'undefined'].includes(typeof arg);
 }

package/lib/hooks/useDefaultThemeSettings.d.ts

@@ -1,2 +0,0 @@
-import type { RawTheme } from '../mocks/types';
-export declare function useDefaultThemeSettings(): RawTheme['settings'];

package/lib/hooks/useDefaultThemeSettings.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.useDefaultThemeSettings = void 0;
-const hooks_1 = require("../mocks/hooks");
-const constants_1 = require("../mocks/constants");
-function useDefaultThemeSettings() {
-    return (0, hooks_1.useThemeSettings)(constants_1.DEFAULT_THEME_NAME);
-}
-exports.useDefaultThemeSettings = useDefaultThemeSettings;
-//# sourceMappingURL=useDefaultThemeSettings.js.map

package/src/hooks/useDefaultThemeSettings.ts

@@ -1,7 +0,0 @@
-import { useThemeSettings } from '@portal/hooks';
-import { DEFAULT_THEME_NAME } from '@portal/constants';
-import type { RawTheme } from '@portal/types';
-
-export function useDefaultThemeSettings(): RawTheme['settings'] {
-  return useThemeSettings(DEFAULT_THEME_NAME);
-}