@stoplight/elements-core 9.0.11 → 9.0.12-beta-0.1

package/src/hoc/withMosaicProvider.tsx

@@ -0,0 +1,28 @@
+import { Provider as MosaicProvider, useMosaicContext } from '@stoplight/mosaic';
+import React from 'react';
+
+import { getDisplayName } from './utils';
+
+export function withMosaicProvider<P>(WrappedComponent: React.ComponentType<P>): React.FC<P> {
+  const WithMosaicProvider = (props: P) => {
+    try {
+      // if already have mosaic context in tree, use it rather than creating a new provider
+      const mosaicContext = useMosaicContext();
+      if (mosaicContext?.providerId) {
+        return <WrappedComponent {...props} />;
+      }
+    } catch {
+      // no mosaic context yet in the tree (if `useMosaicContext` throws)
+    }
+
+    return (
+      <MosaicProvider style={{ height: '100%' }}>
+        <WrappedComponent {...props} />
+      </MosaicProvider>
+    );
+  };
+
+  WithMosaicProvider.displayName = `WithMosaicProvider(${getDisplayName(WrappedComponent)})`;
+
+  return WithMosaicProvider;
+}

package/src/hoc/withQueryClientProvider.spec.tsx

@@ -0,0 +1,38 @@
+import { render } from '@testing-library/react';
+import React from 'react';
+import { QueryClient, QueryClientProvider, useQueryClient } from 'react-query';
+
+import { withQueryClientProvider } from './withQueryClientProvider';
+
+describe('withQueryClientProvider()', () => {
+  it('should re-use react-query context if already present in tree, rather than creating a new provider', () => {
+    const queryClientFromParent = new QueryClient();
+    let queryClientFromProvider: QueryClient | undefined;
+
+    const Page = withQueryClientProvider(() => {
+      queryClientFromProvider = useQueryClient();
+      return null;
+    });
+
+    render(
+      <QueryClientProvider client={queryClientFromParent}>
+        <Page />
+      </QueryClientProvider>,
+    );
+
+    expect(queryClientFromProvider).toBe(queryClientFromParent);
+  });
+
+  it('should create new react-query context if not already present in tree', () => {
+    let queryClientFromProvider: QueryClient | undefined;
+
+    const Page = withQueryClientProvider(() => {
+      queryClientFromProvider = useQueryClient();
+      return null;
+    });
+
+    render(<Page />);
+
+    expect(queryClientFromProvider).toBeInstanceOf(QueryClient);
+  });
+});

package/src/hoc/withQueryClientProvider.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { QueryClient, QueryClientProvider, useQueryClient } from 'react-query';
+
+import { getDisplayName } from './utils';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: false,
+      staleTime: 5 * 60 * 1000,
+    },
+  },
+});
+
+export function withQueryClientProvider<P>(WrappedComponent: React.ComponentType<P>): React.FC<P> {
+  const WithQueryClientProvider = (props: P) => {
+    try {
+      // if already have query client in tree, use it rather than creating a new provider
+      useQueryClient();
+      return <WrappedComponent {...props} />;
+    } catch {
+      // no query client yet in the tree (if `useQueryClient` throws)
+    }
+
+    return (
+      <QueryClientProvider client={queryClient}>
+        <WrappedComponent {...props} />
+      </QueryClientProvider>
+    );
+  };
+
+  WithQueryClientProvider.displayName = `WithQueryClientProvider(${getDisplayName(WrappedComponent)})`;
+
+  return WithQueryClientProvider;
+}

package/src/hoc/withRouter.tsx

@@ -0,0 +1,71 @@
+import { DefaultComponentMapping } from '@stoplight/markdown-viewer';
+import * as React from 'react';
+import { Route, Routes, useInRouterContext } from 'react-router-dom';
+
+import { LinkHeading } from '../components/LinkHeading';
+import { MarkdownComponentsProvider } from '../components/MarkdownViewer/CustomComponents/Provider';
+import { ReactRouterMarkdownLink } from '../components/MarkdownViewer/CustomComponents/ReactRouterLink';
+import { ScrollToHashElement } from '../components/MarkdownViewer/CustomComponents/ScrollToHashElement';
+import { RouterTypeContext } from '../context/RouterType';
+import { useRouter } from '../hooks/useRouter';
+import { RoutingProps } from '../types';
+import { getDisplayName } from './utils';
+
+const components: Partial<DefaultComponentMapping> = {
+  a: ReactRouterMarkdownLink,
+  h2: ({ color, ...props }) => <LinkHeading size={2} {...props} />,
+  h3: ({ color, ...props }) => <LinkHeading size={3} {...props} />,
+  h4: ({ color, ...props }) => <LinkHeading size={4} {...props} />,
+};
+
+const InternalRoutes = ({ children }: { children: React.ReactNode }): JSX.Element => {
+  return (
+    <Routes>
+      <Route
+        path="/*"
+        element={
+          <MarkdownComponentsProvider value={components}>
+            <ScrollToHashElement />
+            {children}
+          </MarkdownComponentsProvider>
+        }
+      />
+    </Routes>
+  );
+};
+
+export function withRouter<P extends RoutingProps>(
+  WrappedComponent: React.ComponentType<P & { outerRouter?: boolean }>,
+): React.FC<P> {
+  const WithRouter = (props: P) => {
+    const outerRouter = useInRouterContext();
+    const basePath = props.basePath ?? '/';
+    const staticRouterPath = props.staticRouterPath ?? '';
+    const routerType = props.router ?? 'history';
+    const { Router, routerProps } = useRouter(routerType, basePath, staticRouterPath);
+
+    if (!outerRouter) {
+      return (
+        <RouterTypeContext.Provider value={routerType}>
+          <Router {...routerProps} key={basePath}>
+            <InternalRoutes>
+              <WrappedComponent {...props} outerRouter={false} />
+            </InternalRoutes>
+          </Router>
+        </RouterTypeContext.Provider>
+      );
+    }
+
+    return (
+      <RouterTypeContext.Provider value={routerType}>
+        <InternalRoutes>
+          <WrappedComponent {...props} outerRouter />
+        </InternalRoutes>
+      </RouterTypeContext.Provider>
+    );
+  };
+
+  WithRouter.displayName = `WithRouter(${getDisplayName(WrappedComponent)})`;
+
+  return WithRouter;
+}

package/src/hooks/useBundleRefsIntoDocument.ts

@@ -0,0 +1,60 @@
+import $RefParser from '@stoplight/json-schema-ref-parser';
+import { isObject } from 'lodash';
+import * as React from 'react';
+
+/**
+ * @param type branch node snapshot type
+ * @param data branch node snapshot data
+ */
+
+interface Options {
+  baseUrl?: string;
+}
+
+/**
+ * Fetches and bundles external $refs into an OAS document. Internal $refs are not resolved.
+ */
+export function useBundleRefsIntoDocument(document: unknown, options?: Options) {
+  const [bundledData, setBundledData] = React.useState(document);
+
+  const baseUrl = options?.baseUrl;
+
+  React.useEffect(() => {
+    if (!isObject(document)) {
+      setBundledData(document);
+      return;
+    }
+
+    let isMounted = true;
+    doBundle(document, baseUrl)
+      .then(res => {
+        if (isMounted) {
+          setBundledData({ ...res }); // this hmm....library mutates document so a shallow copy is required to force a rerender in all cases
+        }
+      })
+      .catch(reason => {
+        if (typeof reason === 'object' && reason !== null && 'files' in reason) {
+          if (isMounted) {
+            setBundledData({ ...reason.files.schema });
+          }
+        } else {
+          console.warn(`Could bundle: ${reason?.message ?? 'Unknown error'}`);
+        }
+      });
+
+    return () => {
+      isMounted = false;
+    };
+  }, [document, baseUrl]);
+
+  return bundledData;
+}
+
+const commonBundleOptions = { continueOnError: true };
+const doBundle = (data: object, baseUrl?: string) => {
+  if (!baseUrl) {
+    return $RefParser.bundle(data, commonBundleOptions);
+  } else {
+    return $RefParser.bundle(baseUrl, data, commonBundleOptions);
+  }
+};

package/src/hooks/useFirstRender.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+
+export function useFirstRender() {
+  const ref = React.useRef(true);
+  const firstRender = ref.current;
+  ref.current = false;
+  return firstRender;
+}

package/src/hooks/useIsCompact.ts

@@ -0,0 +1,26 @@
+import { Breakpoints, useBreakpoints } from '@stoplight/mosaic';
+import { Ref } from 'react';
+
+import { DocsProps } from '../components/Docs';
+
+const getBreakpoints = (compact?: number | boolean): Breakpoints | undefined => {
+  if (!compact) return undefined;
+
+  if (typeof compact === 'number') {
+    return [
+      ['compact', compact],
+      ['regular', Infinity],
+    ];
+  }
+
+  return [['compact', Infinity]];
+};
+
+/**
+ * Given layoutOptions, determines if the component is in compact mode
+ */
+export function useIsCompact(layoutOptions: DocsProps['layoutOptions']) {
+  const { ref, breakpoint } = useBreakpoints(getBreakpoints(layoutOptions?.compact));
+
+  return { ref: ref as Ref<HTMLDivElement>, isCompact: breakpoint === 'compact' };
+}

package/src/hooks/useParsedData.ts

@@ -0,0 +1,99 @@
+import { NodeType } from '@stoplight/types';
+import { parse as parseYaml } from '@stoplight/yaml';
+import * as React from 'react';
+
+import { ParsedNode } from '../types';
+import { isHttpOperation, isHttpService, isHttpWebhookOperation, isJSONSchema, isSMDASTRoot } from '../utils/guards';
+
+export function useParsedData(nodeType: NodeType, data: unknown): ParsedNode | undefined {
+  return React.useMemo(() => parserMap[nodeType]?.(data), [nodeType, data]);
+}
+
+type Parser = (rawData: unknown) => ParsedNode | undefined;
+
+const parserMap: Record<NodeType, Parser> = {
+  [NodeType.Article]: parseArticleData,
+  [NodeType.HttpOperation]: parseHttpOperation,
+  [NodeType.HttpWebhook]: parseHttpWebhookOperation,
+  [NodeType.HttpService]: parseHttpService,
+  [NodeType.Model]: parseModel,
+  [NodeType.HttpServer]: parseUnknown,
+  [NodeType.Generic]: parseUnknown,
+  [NodeType.TableOfContents]: parseUnknown,
+  [NodeType.SpectralRuleset]: parseUnknown,
+  [NodeType.Styleguide]: parseUnknown,
+  [NodeType.Image]: parseUnknown,
+  [NodeType.HttpCallback]: parseUnknown,
+  [NodeType.StoplightOverride]: parseUnknown,
+  [NodeType.StoplightResolutions]: parseUnknown,
+  [NodeType.Unknown]: parseUnknown,
+};
+
+function parseArticleData(rawData: unknown): ParsedNode | undefined {
+  if (typeof rawData === 'string' || isSMDASTRoot(rawData)) {
+    return {
+      type: NodeType.Article,
+      data: rawData,
+    };
+  }
+
+  return undefined;
+}
+
+function parseHttpOperation(rawData: unknown): ParsedNode | undefined {
+  const data = tryParseYamlOrObject(rawData);
+  if (isHttpOperation(data)) {
+    return {
+      type: NodeType.HttpOperation,
+      data: data,
+    };
+  }
+  return undefined;
+}
+
+function parseHttpWebhookOperation(rawData: unknown): ParsedNode | undefined {
+  const data = tryParseYamlOrObject(rawData);
+  if (isHttpWebhookOperation(data)) {
+    return {
+      type: NodeType.HttpWebhook,
+      data: data,
+    };
+  }
+  return undefined;
+}
+
+function parseHttpService(rawData: unknown): ParsedNode | undefined {
+  const data = tryParseYamlOrObject(rawData);
+  if (isHttpService(data)) {
+    return {
+      type: NodeType.HttpService,
+      data: data,
+    };
+  }
+  return undefined;
+}
+
+function parseModel(rawData: unknown): ParsedNode | undefined {
+  const data = tryParseYamlOrObject(rawData);
+  if (isJSONSchema(data)) {
+    return {
+      type: NodeType.Model,
+      data: data,
+    };
+  }
+  return undefined;
+}
+
+function tryParseYamlOrObject(yamlOrObject: unknown): object | undefined {
+  if (typeof yamlOrObject === 'object' && yamlOrObject !== null) return yamlOrObject;
+  if (typeof yamlOrObject === 'string') {
+    try {
+      return parseYaml(yamlOrObject);
+    } catch (e) {}
+  }
+  return undefined;
+}
+
+function parseUnknown() {
+  return undefined;
+}

package/src/hooks/useParsedValue.ts

@@ -0,0 +1,19 @@
+import { parse } from '@stoplight/yaml';
+import * as React from 'react';
+
+export function useParsedValue(value: unknown) {
+  return React.useMemo(() => {
+    let parsedValue = value;
+
+    if (typeof value === 'string') {
+      try {
+        // Parse YAML to object
+        parsedValue = parse(value);
+      } catch (error) {
+        // noop
+      }
+    }
+
+    return parsedValue;
+  }, [value]);
+}

package/src/hooks/useResponsiveLayout.tsx

@@ -0,0 +1,51 @@
+import * as React from 'react';
+
+type ElementsNode = 'docs';
+
+const ElementsBreakpoints: Record<ElementsNode, number> = {
+  docs: 700,
+};
+
+export enum ScreenType {
+  Phone = 415,
+  Tablet = 750,
+  Resized_Browser = 980,
+  Normal_Browser = 1_000_000,
+}
+
+const getScreenType = () => {
+  if (window?.innerWidth <= ScreenType.Phone) {
+    return ScreenType.Phone;
+  } else if (window?.innerWidth <= ScreenType.Tablet) {
+    return ScreenType.Tablet;
+  } else if (window?.innerWidth <= ScreenType.Resized_Browser) {
+    return ScreenType.Resized_Browser;
+  }
+  return ScreenType.Normal_Browser;
+};
+
+export const useResponsiveLayout = () => {
+  const [screenType, setScreenType] = React.useState<ScreenType | undefined>();
+
+  const getElementsBreakpoint = (node: ElementsNode) => {
+    return ElementsBreakpoints[node];
+  };
+
+  React.useLayoutEffect(() => {
+    function handleResize() {
+      setScreenType(getScreenType());
+    }
+    window?.addEventListener('resize', handleResize);
+    handleResize();
+    return () => window?.removeEventListener('resize', handleResize);
+  }, []);
+
+  // isResponsiveLayoutEnabled can be applied to generally trigger responsive layout behavior
+  const isResponsiveLayoutEnabled = screenType !== ScreenType.Normal_Browser;
+
+  return {
+    isResponsiveLayoutEnabled,
+    screenType,
+    getElementsBreakpoint,
+  };
+};

package/src/hooks/useRouter.tsx

@@ -0,0 +1,31 @@
+import { Dictionary } from '@stoplight/types';
+import * as React from 'react';
+import { BrowserRouter, HashRouter, MemoryRouter } from 'react-router-dom';
+import { StaticRouter } from 'react-router-dom/server.js';
+
+import { RouterType } from '../types';
+
+const RouterComponent: Dictionary<React.ComponentType, RouterType> = {
+  history: BrowserRouter,
+  memory: MemoryRouter,
+  hash: HashRouter,
+  static: StaticRouter as any,
+};
+
+interface RouterProps {
+  basename?: string;
+  location?: string;
+}
+
+export const useRouter = (router: RouterType, basePath: string, staticRouterPath?: string) => {
+  const Router = RouterComponent[router];
+  const routerProps: RouterProps = {
+    ...(router !== 'memory' && { basename: basePath }),
+    ...(router === 'static' && { location: staticRouterPath }),
+  };
+
+  return {
+    Router,
+    routerProps,
+  };
+};

package/src/hooks/useUniqueId.ts

@@ -0,0 +1,4 @@
+import { nanoid } from 'nanoid';
+import * as React from 'react';
+
+export const useUniqueId = (prefix: string = 'id_') => React.useRef(`${prefix}${nanoid(8)}`).current;

package/src/index.ts

@@ -0,0 +1,48 @@
+export { Docs, DocsProps, ExtensionAddonRenderer, ExtensionRowProps, ParsedDocs } from './components/Docs';
+export { DeprecatedBadge } from './components/Docs/HttpOperation/Badges';
+export { ExportButton, ExportButtonProps } from './components/Docs/HttpService/ExportButton';
+export { ResponsiveSidebarLayout } from './components/Layout/ResponsiveSidebarLayout';
+export { SidebarLayout } from './components/Layout/SidebarLayout';
+export { LinkHeading } from './components/LinkHeading';
+export { Logo } from './components/Logo';
+export { DefaultSMDComponents } from './components/MarkdownViewer/CustomComponents/CodeComponent';
+export {
+  CustomComponentMapping,
+  MarkdownComponentsProvider,
+} from './components/MarkdownViewer/CustomComponents/Provider';
+export { ReactRouterMarkdownLink } from './components/MarkdownViewer/CustomComponents/ReactRouterLink';
+export { ScrollToHashElement } from './components/MarkdownViewer/CustomComponents/ScrollToHashElement';
+export { NonIdealState } from './components/NonIdealState';
+export { PoweredByLink } from './components/PoweredByLink';
+export { TableOfContents } from './components/TableOfContents';
+export {
+  CustomLinkComponent,
+  TableOfContentsGroup,
+  TableOfContentsItem,
+  TableOfContentsNode,
+  TableOfContentsNodeGroup,
+} from './components/TableOfContents/types';
+export { findFirstNode } from './components/TableOfContents/utils';
+export { TryIt, TryItProps, TryItWithRequestSamples, TryItWithRequestSamplesProps } from './components/TryIt';
+export { HttpMethodColors, NodeTypeColors, NodeTypeIconDefs, NodeTypePrettyName } from './constants';
+export { MockingProvider } from './containers/MockingProvider';
+export { InlineRefResolverProvider } from './context/InlineRefResolver';
+export { ElementsOptionsProvider } from './context/Options';
+export { PersistenceContextProvider, withPersistenceBoundary } from './context/Persistence';
+export { RouterTypeContext } from './context/RouterType';
+export { withMosaicProvider } from './hoc/withMosaicProvider';
+export { withQueryClientProvider } from './hoc/withQueryClientProvider';
+export { withRouter } from './hoc/withRouter';
+export { useBundleRefsIntoDocument } from './hooks/useBundleRefsIntoDocument';
+export { useParsedData } from './hooks/useParsedData';
+export { useParsedValue } from './hooks/useParsedValue';
+export { useResponsiveLayout } from './hooks/useResponsiveLayout';
+export { useRouter } from './hooks/useRouter';
+export { Styled, withStyles } from './styled';
+export { Divider, Group, ITableOfContentsTree, Item, ParsedNode, RoutingProps, TableOfContentItem } from './types';
+export { isHttpOperation, isHttpService, isHttpWebhookOperation } from './utils/guards';
+export { resolveUrl } from './utils/http-spec/IServer';
+export { ReferenceResolver } from './utils/ref-resolving/ReferenceResolver';
+export { createResolvedObject } from './utils/ref-resolving/resolvedObject';
+export { resolveRelativeLink, slugify } from './utils/string';
+export { createElementClass } from './web-components/createElementClass';

package/src/styled.tsx

@@ -0,0 +1,22 @@
+import { Box } from '@stoplight/mosaic';
+import * as React from 'react';
+
+import { getDisplayName } from './hoc/utils';
+
+export const Styled = ({ children }: { children: React.ReactNode }) => {
+  return (
+    <Box className="sl-elements sl-antialiased" fontFamily="ui" fontSize="base" color="body" h="full">
+      {children}
+    </Box>
+  );
+};
+
+export function withStyles<T>(Component: React.ComponentType<T>): React.FC<T> {
+  const Inner: React.FC<T> = props => (
+    <Styled>
+      <Component {...props} />
+    </Styled>
+  );
+  Inner.displayName = `withStyles(${getDisplayName(Component)})`;
+  return Inner;
+}

package/src/styles.css

@@ -0,0 +1,4 @@
+@import '@stoplight/mosaic/styles.css';
+@import '@stoplight/mosaic/themes/default.css';
+
+@import 'core.css';