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

package/src/components/Docs/Model/Model.tsx

@@ -0,0 +1,192 @@
+import { JsonSchemaViewer } from '@stoplight/json-schema-viewer';
+import { Box, CopyButton, Flex, Heading, HStack, NodeAnnotation, Panel, Select, Text, VStack } from '@stoplight/mosaic';
+import { CodeViewer } from '@stoplight/mosaic-code-viewer';
+import { withErrorBoundary } from '@stoplight/react-error-boundary';
+import cn from 'classnames';
+import { JSONSchema7 } from 'json-schema';
+import * as React from 'react';
+
+import { useResolvedObject, useSchemaInlineRefResolver } from '../../../context/InlineRefResolver';
+import { useOptionsCtx } from '../../../context/Options';
+import { useIsCompact } from '../../../hooks/useIsCompact';
+import { exceedsSize, generateExamplesFromJsonSchema } from '../../../utils/exampleGeneration/exampleGeneration';
+import { getOriginalObject } from '../../../utils/ref-resolving/resolvedObject';
+import { LoadMore } from '../../LoadMore';
+import { MarkdownViewer } from '../../MarkdownViewer';
+import { DocsComponentProps } from '..';
+import { DeprecatedBadge, InternalBadge } from '../HttpOperation/Badges';
+import LazySchemaTreePreviewer from '../HttpOperation/LazySchemaTreePreviewer';
+import { ExportButton } from '../HttpService/ExportButton';
+import { NodeVendorExtensions } from '../NodeVendorExtensions';
+import { TwoColumnLayout } from '../TwoColumnLayout';
+
+export type ModelProps = DocsComponentProps<JSONSchema7>;
+
+const ModelComponent: React.FC<ModelProps> = ({
+  data: unresolvedData,
+  className,
+  nodeTitle,
+  layoutOptions,
+  exportProps,
+  disableProps,
+}) => {
+  const [resolveRef, maxRefDepth] = useSchemaInlineRefResolver();
+  const data = useResolvedObject(unresolvedData) as JSONSchema7;
+  const { nodeHasChanged, renderExtensionAddon } = useOptionsCtx();
+
+  const { ref: layoutRef, isCompact } = useIsCompact(layoutOptions);
+
+  const nodeId = (data?.['x-stoplight' as keyof JSONSchema7] as { [key: string]: any })?.id;
+  const title = data.title ?? nodeTitle;
+  const isDeprecated = !!data['deprecated' as keyof JSONSchema7];
+  const isInternal = !!data['x-internal' as keyof JSONSchema7];
+
+  const shouldDisplayHeader =
+    !layoutOptions?.noHeading && (title !== undefined || (exportProps && !layoutOptions?.hideExport));
+
+  const titleChanged = nodeHasChanged?.({ nodeId, attr: ['title', 'internal'] });
+  const header = (shouldDisplayHeader || isInternal || isDeprecated) && (
+    <Flex justifyContent="between" alignItems="center">
+      <Box pos="relative">
+        <HStack spacing={5}>
+          {title && (
+            <Heading size={1} fontWeight="semibold">
+              {title}
+            </Heading>
+          )}
+
+          <HStack spacing={2}>
+            {isDeprecated && <DeprecatedBadge />}
+            {isInternal && <InternalBadge />}
+          </HStack>
+        </HStack>
+
+        <NodeAnnotation change={titleChanged} />
+      </Box>
+      {exportProps && !layoutOptions?.hideExport && !isCompact && <ExportButton {...exportProps} />}
+    </Flex>
+  );
+
+  const modelExamples = !layoutOptions?.hideModelExamples && <ModelExamples data={data} isCollapsible={isCompact} />;
+
+  const descriptionChanged = nodeHasChanged?.({ nodeId, attr: 'description' });
+
+  const getMaskProperties = (): Array<{ path: string; required?: boolean }> => {
+    const disablePropsConfig = disableProps?.models;
+    const absolutePathsToHide: Array<{ path: string; required?: boolean }> = [];
+    if (disableProps?.models) {
+      disablePropsConfig.forEach((configEntry: any) => {
+        const { location, paths, isComplex } = configEntry;
+        if (paths.length === 0 && !isComplex) {
+          absolutePathsToHide.push({ path: location });
+        } else {
+          paths.forEach((item: any) => {
+            const fullPath = location === '#' ? item?.path : `${location}/${item.path}`;
+            let object: any = { path: fullPath };
+            if (item.hasOwnProperty('required')) {
+              object = { ...object, required: item?.required };
+            }
+            absolutePathsToHide.push(object);
+          });
+        }
+      });
+    }
+    return absolutePathsToHide;
+  };
+  const shouldUseLazySchema =
+    disableProps && disableProps?.models
+      ? disableProps.models.some((entry: { isComplex: boolean }) => entry.isComplex === true)
+      : false;
+
+  const description = (
+    <VStack spacing={10}>
+      {data.description && data.type === 'object' && (
+        <Box pos="relative">
+          <MarkdownViewer role="textbox" markdown={data.description} />
+          <NodeAnnotation change={descriptionChanged} />
+        </Box>
+      )}
+
+      <NodeVendorExtensions data={data} />
+
+      {!disableProps?.hideModelTryIt && isCompact && modelExamples}
+      {data && shouldUseLazySchema ? (
+        <LazySchemaTreePreviewer schema={data} hideData={getMaskProperties()} complexData={disableProps?.models} />
+      ) : (
+        <JsonSchemaViewer
+          resolveRef={resolveRef}
+          maxRefDepth={maxRefDepth}
+          schema={getOriginalObject(data)}
+          nodeHasChanged={nodeHasChanged}
+          renderExtensionAddon={renderExtensionAddon}
+          skipTopLevelDescription
+        />
+      )}
+    </VStack>
+  );
+
+  return (
+    <TwoColumnLayout
+      ref={layoutRef}
+      className={cn('Model', className)}
+      header={header}
+      left={description}
+      right={!disableProps?.hideModelTryIt && !isCompact && modelExamples}
+    />
+  );
+};
+
+const ModelExamples = React.memo(({ data, isCollapsible = false }: { data: JSONSchema7; isCollapsible?: boolean }) => {
+  const [chosenExampleIndex, setChosenExampleIndex] = React.useState(0);
+  const [show, setShow] = React.useState<boolean>(false);
+  const [loading, setLoading] = React.useState<boolean>(false);
+
+  const examples = React.useMemo(() => generateExamplesFromJsonSchema(data), [data]);
+
+  const selectedExample = examples[chosenExampleIndex]?.data;
+
+  const handleLoadMorePress = React.useCallback(() => {
+    setLoading(true);
+    setTimeout(() => setShow(true), 50);
+  }, []);
+
+  const examplesSelect = examples.length > 1 && (
+    <Select
+      aria-label="Example"
+      value={String(chosenExampleIndex)}
+      options={examples.map(({ label }, index) => ({ value: index, label }))}
+      onChange={value => setChosenExampleIndex(parseInt(String(value), 10))}
+      size="sm"
+      triggerTextPrefix="Example: "
+    />
+  );
+
+  return (
+    <Panel rounded isCollapsible={isCollapsible} defaultIsOpen={!isCollapsible}>
+      <Panel.Titlebar rightComponent={selectedExample ? <CopyButton size="sm" copyValue={selectedExample} /> : null}>
+        {examplesSelect || (
+          <Text color="body" role="heading">
+            Example
+          </Text>
+        )}
+      </Panel.Titlebar>
+
+      <Panel.Content p={0}>
+        {show || !exceedsSize(selectedExample) ? (
+          <CodeViewer
+            aria-label={selectedExample}
+            noCopyButton
+            maxHeight="500px"
+            language="json"
+            value={selectedExample}
+            showLineNumbers
+          />
+        ) : (
+          <LoadMore loading={loading} onClick={handleLoadMorePress} />
+        )}
+      </Panel.Content>
+    </Panel>
+  );
+});
+
+export const Model = withErrorBoundary<ModelProps>(ModelComponent, { recoverableProps: ['data'] });

package/src/components/Docs/Model/index.ts

@@ -0,0 +1 @@
+export * from './Model';

package/src/components/Docs/NodeVendorExtensions.tsx

@@ -0,0 +1,55 @@
+import { INode } from '@stoplight/types';
+import type { JSONSchema7 } from 'json-schema';
+import { isEmpty, memoize, pickBy } from 'lodash';
+import * as React from 'react';
+
+import { useOptionsCtx } from '../../context/Options';
+import { getOriginalObject } from '../../utils/ref-resolving/resolvedObject';
+
+export type NodeVendorExtensionsProps = {
+  /**
+   * The input data for the component to display.
+   */
+  data: INode | JSONSchema7;
+};
+
+/**
+ * @private
+ * Resolves the vendor extensions from the given object,
+ * covers the case where the given data is not a INode which has already parsed
+ * the vendor extensions into the `extensions` property.
+ *
+ * @param data The object to extract the vendor extensions from.
+ */
+const getVendorExtensions = memoize((data: INode) => pickBy(data, (_val, key) => key.startsWith('x-')));
+
+/**
+ * @private
+ * Renders the vendor extensions for a content node
+ */
+export const NodeVendorExtensions = React.memo<NodeVendorExtensionsProps>(({ data }) => {
+  const { renderExtensionAddon } = useOptionsCtx();
+
+  if (!renderExtensionAddon) {
+    return null;
+  }
+
+  const originalObject = getOriginalObject(data) as INode;
+  const vendorExtensions = originalObject.extensions ? originalObject.extensions : getVendorExtensions(originalObject);
+
+  if (isEmpty(vendorExtensions)) {
+    return null;
+  }
+
+  return (
+    <>
+      {renderExtensionAddon({
+        // Use nestingLevel -1 to represent the root node of the document
+        nestingLevel: -1,
+        schemaNode: originalObject as any,
+        vendorExtensions,
+      })}
+    </>
+  );
+});
+NodeVendorExtensions.displayName = 'NodeVendorExtensions';

package/src/components/Docs/Sections.tsx

@@ -0,0 +1,54 @@
+import { Box, Flex, HeadingProps, Panel, PanelProps } from '@stoplight/mosaic';
+import * as React from 'react';
+
+import { slugify } from '../../utils/string';
+import { LinkHeading } from '../LinkHeading';
+
+export interface ISectionTitle {
+  title: string;
+  id?: string;
+  size?: HeadingProps['size'];
+  isCompact?: boolean;
+}
+
+export const SectionTitle: React.FC<ISectionTitle> = ({ title, id, size = 2, isCompact = false, children }) => {
+  return (
+    <Flex w="full">
+      <Box py={1} pr={6} as={LinkHeading} size={size} aria-label={title} id={id || slugify(title)}>
+        {title}
+      </Box>
+      <Flex alignSelf={'center'} py={1} flexGrow style={{ minWidth: 0 }} justify={isCompact ? 'end' : undefined}>
+        {children}
+      </Flex>
+    </Flex>
+  );
+};
+
+export const SectionSubtitle: React.FC<ISectionTitle> = props => {
+  return <SectionTitle {...props} size={3} />;
+};
+
+type SubSectionPanelProps = {
+  title: React.ReactNode;
+  hasContent?: boolean;
+  rightComponent?: React.ReactNode;
+};
+
+export const SubSectionPanel: React.FC<SubSectionPanelProps & Pick<PanelProps, 'defaultIsOpen' | 'onChange'>> = ({
+  title,
+  children,
+  hasContent,
+  rightComponent,
+  defaultIsOpen = true,
+  onChange,
+}) => {
+  return (
+    <Panel isCollapsible={hasContent} defaultIsOpen={defaultIsOpen} onChange={onChange} appearance="outlined">
+      <Panel.Titlebar fontWeight="medium" rightComponent={rightComponent}>
+        <div role="heading">{title}</div>
+      </Panel.Titlebar>
+
+      {hasContent !== false && <Panel.Content>{children}</Panel.Content>}
+    </Panel>
+  );
+};

package/src/components/Docs/Security/PanelContent.tsx

@@ -0,0 +1,38 @@
+import { MarkdownViewer } from '@stoplight/markdown-viewer';
+import { Box, NodeAnnotation } from '@stoplight/mosaic';
+import { HttpSecurityScheme } from '@stoplight/types';
+import * as React from 'react';
+
+import { useOptionsCtx } from '../../../context/Options';
+import { getReadableSecurityName, shouldIncludeKey } from '../../../utils/oas/security';
+import { getDefaultDescription } from '../../../utils/securitySchemes';
+
+export const PanelContent: React.FC<{ schemes: HttpSecurityScheme[] }> = ({ schemes }) => {
+  const { nodeHasChanged } = useOptionsCtx();
+
+  if (!schemes || !schemes.length) {
+    return null;
+  }
+
+  const collection = schemes.length > 1;
+
+  return (
+    <Box>
+      {schemes.map(scheme => (
+        <Box key={scheme.key} p={2} m={2} border>
+          {collection && (
+            <MarkdownViewer
+              style={{ fontWeight: 'bold', fontSize: 12, marginBottom: 10 }}
+              markdown={getReadableSecurityName(scheme, shouldIncludeKey(schemes, scheme.type))}
+            />
+          )}
+          <MarkdownViewer
+            style={{ fontSize: 12 }}
+            markdown={`${scheme.description ?? ''}\n\n` + getDefaultDescription(scheme)}
+          />
+          <NodeAnnotation change={nodeHasChanged?.({ nodeId: scheme.id })} />
+        </Box>
+      ))}
+    </Box>
+  );
+};

package/src/components/Docs/Security/index.ts

@@ -0,0 +1 @@
+export * from './PanelContent';

package/src/components/Docs/Skeleton.tsx

@@ -0,0 +1,12 @@
+import cn from 'classnames';
+import * as React from 'react';
+
+export const DocsSkeleton = ({ className, padding = '12' }: { className?: string; padding?: string }) => {
+  return (
+    <div className={cn('PageSkeleton', className, `sl-p-${padding}`, 'sl-flex sl-flex-col sl-h-full')}>
+      <div className={cn('DocsSkeleton sl-h-12 sl-w-1/5')} />
+      <div className={cn('DocsSkeleton sl-h-12 sl-my-6')} />
+      <div className={cn('DocsSkeleton sl-flex-1 sl-my-6')} />
+    </div>
+  );
+};

package/src/components/Docs/TwoColumnLayout.tsx

@@ -0,0 +1,27 @@
+import { Box, Flex, VStack } from '@stoplight/mosaic';
+import React from 'react';
+
+export interface TwoColumnLayoutProps {
+  header: React.ReactNode;
+  right: React.ReactNode;
+  left: React.ReactNode;
+  className?: string;
+}
+
+export const TwoColumnLayout = React.forwardRef<HTMLDivElement, TwoColumnLayoutProps>(
+  ({ header, right, left, className }, ref) => (
+    <VStack ref={ref} w="full" className={className} spacing={8}>
+      {header}
+      <Flex>
+        <Box data-testid="two-column-left" w={0} flex={1}>
+          {left}
+        </Box>
+        {right && (
+          <Box data-testid="two-column-right" ml={16} pos="relative" w="2/5" style={{ maxWidth: 500 }}>
+            {right}
+          </Box>
+        )}
+      </Flex>
+    </VStack>
+  ),
+);

package/src/components/Docs/index.ts

@@ -0,0 +1 @@
+export * from './Docs';

package/src/components/Docs/story-helper.ts

@@ -0,0 +1,46 @@
+import type { ErrorBoundaryProps } from '@stoplight/react-error-boundary';
+import type { Meta, StoryFn } from '@storybook/react';
+import * as React from 'react';
+
+import { ExtensionAddonRenderer } from './Docs';
+import { wrapOptionsContext } from './story-renderer-helper';
+
+type DocsProps = { data: any; renderExtensionAddon?: ExtensionAddonRenderer } & ErrorBoundaryProps;
+
+type storyOptions = DocsProps & { layoutOptions?: object };
+
+interface HelperReturn<P extends DocsProps> {
+  meta: Meta<DocsProps>;
+  createStory(name: string, input: storyOptions): StoryFn<P>;
+  createHoistedStory(input: storyOptions): StoryFn<P>;
+}
+
+export const createStoriesForDocsComponent = (
+  Component: React.ComponentType<DocsProps>,
+  title?: string,
+): HelperReturn<DocsProps> => {
+  const createStory = (name: string, input: storyOptions) => {
+    const story: StoryFn<DocsProps> = (args: any) => {
+      const component = React.createElement(Component, args);
+      return wrapOptionsContext(component);
+    };
+    story.args = input;
+    story.storyName = name;
+    return story;
+  };
+  return {
+    meta: {
+      title: `Internal/Docs/${title || Component.displayName}`,
+      component: Component,
+      argTypes: <HelperReturn<DocsProps>['meta']['argTypes']>{
+        data: {
+          control: { type: 'object' },
+        },
+        FallbackComponent: { table: { disable: true } },
+        recoverableProps: { table: { disable: true } },
+      },
+    },
+    createStory: createStory,
+    createHoistedStory: input => createStory(title ?? Component.displayName ?? Component.name ?? '_unknown_', input),
+  };
+};

package/src/components/Docs/story-renderer-helper.tsx

@@ -0,0 +1,56 @@
+import { isPlainObject } from '@stoplight/json';
+import { isRegularNode } from '@stoplight/json-schema-tree';
+import { MarkdownViewer } from '@stoplight/markdown-viewer';
+import { Box } from '@stoplight/mosaic';
+import * as React from 'react';
+
+import { ElementsOptionsProvider } from '../../context/Options';
+import { ExtensionAddonRenderer, ExtensionRowProps } from './Docs';
+
+/**
+ * Renders the known x-enum-Description vendor extension
+ * @returns React.ReactElement
+ */
+// eslint-disable-next-line storybook/prefer-pascal-case
+export const renderExtensionRenderer: ExtensionAddonRenderer = (props: ExtensionRowProps) => {
+  const { nestingLevel, schemaNode, vendorExtensions } = props;
+  const { 'x-enum-descriptions': enumDescriptions = {} } = vendorExtensions;
+
+  // If the nesting level is 0, we are at the root of the schema and should not render anything
+  if (nestingLevel === 0) {
+    return null;
+  }
+
+  // This implementation of the extension renderer only supports the `x-enum-descriptions`-extension
+  if ('x-enum-descriptions' in vendorExtensions && isRegularNode(schemaNode) && isPlainObject(enumDescriptions)) {
+    let value = `| Enum value | Description |\n|---|---|\n`;
+
+    for (const enumValue of schemaNode.enum ?? []) {
+      const description = enumDescriptions[String(enumValue)];
+      value += `| ${enumValue} | ${description} |\n`;
+    }
+
+    return (
+      <Box mb={2}>
+        <Box
+          mt={2}
+          as={MarkdownViewer}
+          markdown={value}
+          style={{
+            fontSize: 12,
+          }}
+        />
+      </Box>
+    );
+  }
+
+  return null;
+};
+
+/**
+ * @private
+ * Helper function to wrap the options context for the Docs subcomponents
+ */
+export const wrapOptionsContext = (story: any) => {
+  return <ElementsOptionsProvider renderExtensionAddon={renderExtensionRenderer}>{story}</ElementsOptionsProvider>;
+};

package/src/components/Layout/MobileTopNav.tsx

@@ -0,0 +1,78 @@
+import { faBars, faX } from '@fortawesome/free-solid-svg-icons';
+import { Box, Button, Drawer, Flex, Icon } from '@stoplight/mosaic';
+import * as React from 'react';
+
+import { LogoProps } from '../../types';
+import type { TableOfContentsItem } from '../TableOfContents';
+import { Sidebar } from './ResponsiveSidebarLayout';
+
+export const MobileTopNav = ({
+  name,
+  logo,
+  tree,
+  pathname,
+  onTocClick,
+}: {
+  name: string;
+  logo?: string | LogoProps;
+  tree: TableOfContentsItem[];
+  pathname: string;
+  onTocClick(): void;
+}): JSX.Element => {
+  const [isSidebarOpen, setIsSidebarOpen] = React.useState<boolean>(false);
+
+  const handleTocClick = () => {
+    onTocClick();
+    setIsSidebarOpen(false);
+  };
+  return (
+    <Flex className="TopNav--mosaic" alignItems="center" h="3xl" pl={4} pr={4} bg="canvas" borderB pos="fixed" w="full">
+      <Flex data-test="mobile-top-nav" w="full" alignItems="center" justifyContent="between">
+        <Button data-test="show-left-sidebar-btn" onPress={() => setIsSidebarOpen(true)} appearance="minimal">
+          <Icon size="lg" icon={faBars} />
+        </Button>
+        <NavHeading heading={name} />
+      </Flex>
+
+      <Drawer isOpen={isSidebarOpen} position="left" onClose={() => setIsSidebarOpen(false)} w="5/6">
+        <Flex justifyContent="end">
+          <Button
+            className="sl-mr-4 sl-mt-2"
+            onPress={() => setIsSidebarOpen(false)}
+            appearance="minimal"
+            justifySelf="end"
+          >
+            <Icon size="lg" icon={faX} />
+          </Button>
+        </Flex>
+        <Box tabIndex={-1}>
+          <Sidebar
+            name={name}
+            logo={logo}
+            tree={tree}
+            pathname={pathname}
+            onTocClick={handleTocClick}
+            isInResponsiveMode={true}
+          />
+        </Box>
+      </Drawer>
+    </Flex>
+  );
+};
+
+const NavHeading = ({ heading }: { heading?: string }): JSX.Element => (
+  <Flex flex={1} data-test="mobile-project-top-nav" style={{ minWidth: 0 }}>
+    <Box
+      fontSize="xl"
+      fontWeight="semibold"
+      whitespace="nowrap"
+      textOverflow="overflow-ellipsis"
+      overflowX="hidden"
+      overflowY="hidden"
+      w="full"
+      textAlign="center"
+    >
+      {heading}
+    </Box>
+  </Flex>
+);