@stainless-api/docs-ui 0.1.0-beta.3 → 0.1.0-beta.30

package/src/languages/typescript.tsx

@@ -1,393 +0,0 @@
-import * as React from 'react';
-import type * as TSAST from '~/lib/json-spec-v2/TSAST';
-import { useDeclaration, useLanguage, useLanguageComponents, useSpec } from '../contexts';
-import { useComponents } from '../contexts/use-components';
-import style from '../style';
-import { PropertyFn } from '.';
-
-const ComplexTypes: Record<string, string> = {
-  TSTypeObject: 'object',
-  TSTypeUnion: 'union',
-  TSTypeInterface: 'interface',
-  TSTypeIntersection: 'intersection',
-  TSTypeArray: 'array',
-};
-
-const constStyle = {
-  string: style.LiteralString,
-  number: style.LiteralNumeric,
-  boolean: style.LiteralBoolean,
-};
-
-type TypeProps = {
-  type: TSAST.TSType;
-};
-
-function Identifier({ name, optional }: { name: string; optional?: boolean }) {
-  return (
-    <>
-      <span className={style.TextIdentifier}>
-        {/^[_a-zA-Z][_a-zA-Z0-9]*$/.test(name) ? name : JSON.stringify(name)}
-      </span>
-      {optional && <span className={style.TextPunctuation}>?</span>}
-    </>
-  );
-}
-
-function TypeParams({ params }: { params?: TSAST.TSTypeParameter[] }) {
-  const Lang = useLanguageComponents();
-  const { Join } = useComponents();
-
-  if (!params?.length) return null;
-
-  const typeParams = params?.map((param, key) =>
-    param.constraint ? (
-      <React.Fragment key={key}>
-        <span className={style.TypeReference}>{param.name}</span>
-        <span className={style.TextKeyword}>extends </span>
-        <Lang.Type type={param.constraint} />
-      </React.Fragment>
-    ) : (
-      <React.Fragment key={key}>param.name</React.Fragment>
-    ),
-  );
-
-  return (
-    <>
-      <span className={style.TypeBracket}>{'<'}</span>
-      <Join items={typeParams} limit={3}>
-        <span className={style.TextOperator}>, </span>
-      </Join>
-      <span className={style.TypeBracket}>{'>'}</span>
-    </>
-  );
-}
-
-function TypePreview({ path }: { path: string }) {
-  const spec = useSpec();
-  const language = useLanguage();
-  const decl = useDeclaration(path);
-  const { Join } = useComponents();
-
-  if (!(decl && 'children' in decl && decl.children.length > 0) || decl['type']?.['kind'] === 'TSTypeUnion')
-    return;
-
-  const items = decl.children.map((prop, key) => (
-    <span key={key} className={style.TypePropertyName}>
-      <span className={style.TextIdentifier}>{spec?.decls?.[language]?.[prop]?.['key']}</span>
-    </span>
-  ));
-
-  return (
-    <span className={style.TypePreview} data-stldocs-type-preview="properties">
-      <span className={style.TypeBrace}>{' {'}</span>
-      <span className={style.TypePreviewContent}>
-        {' '}
-        <Join items={items} limit={3}>
-          <span className={style.TextOperator}>, </span>
-        </Join>{' '}
-      </span>
-      <span className={style.TypeBrace}>{'} '}</span>
-    </span>
-  );
-}
-
-export function TypeName({ type }: TypeProps) {
-  const Lang = useLanguageComponents();
-  return ComplexTypes[type.kind] ?? <Lang.Type type={type} />;
-}
-
-export function Type({ type }: TypeProps) {
-  const Lang = useLanguageComponents();
-  const { Join, SDKReference } = useComponents();
-
-  switch (type.kind) {
-    case 'TSTypeUnknown':
-    case 'TSTypeUndefined':
-    case 'TSTypeNever':
-    case 'TSTypeVoid':
-    case 'TSTypeNull':
-    case 'TSTypeAny':
-    case 'TSTypeBoolean':
-    case 'TSTypeNumber':
-      return (
-        <span className={style.Type}>
-          <span className={style.TypeKeyword}>{type.kind.slice(6).toLowerCase()}</span>
-        </span>
-      );
-
-    case 'TSTypeString':
-      return (
-        <span className={style.Type}>
-          <span className={style.TypeString}>string</span>
-        </span>
-      );
-
-    case 'TSTypeLiteral':
-      return (
-        <span className={style.Type}>
-          <span className={constStyle[typeof type.literal]}>{JSON.stringify(type.literal)}</span>
-        </span>
-      );
-
-    case 'TSTypeArray': {
-      return (
-        <span className={style.Type}>
-          <span className={style.TypeArray}>{'Array<'}</span>
-          <Lang.Type type={type.elementType} />
-          <span className={style.TypeArray}>{'>'}</span>
-        </span>
-      );
-    }
-
-    case 'TSTypeReference': {
-      const name = type.ident.split('.').at(-1);
-      const params = type.typeParameters?.map((param, key) => <Lang.Type key={key} type={param} />);
-
-      return (
-        <span className={style.Type}>
-          <SDKReference stainlessPath={type.$ref}>{name}</SDKReference>
-          {params && params.length > 0 && (
-            <>
-              <span className={style.TypeBracket}>{'<'}</span>
-              <Join items={params} limit={3}>
-                <span className={style.TextOperator}>, </span>
-              </Join>
-              <span className={style.TypeBracket}>{'>'}</span>
-            </>
-          )}
-          <TypePreview path={type.$ref} />
-        </span>
-      );
-    }
-
-    case 'TSTypeIntersection':
-    case 'TSTypeUnion': {
-      const items = type.types.map((t, key) => <Lang.Type key={key} type={t} />);
-
-      const delimiter = type.kind === 'TSTypeUnion' ? '|' : '&';
-
-      return (
-        <span className={style.Type}>
-          <span className={style.TypePreview} data-stldocs-type-preview="union">
-            <span className={style.TypePreviewContent}>
-              <Join items={items} limit={3}>
-                <span className={style.TextOperator}> {delimiter} </span>
-              </Join>
-            </span>
-          </span>
-        </span>
-      );
-    }
-
-    case 'TSTypeObject':
-    case 'TSTypeInterface': {
-      const extend =
-        type.kind === 'TSTypeObject'
-          ? null
-          : type.extends?.map((ref, key) => <Lang.Type key={key} type={ref} />);
-
-      const items = type.members.map((prop, key) => (
-        <React.Fragment key={key}>
-          <span className={style.TypePropertyName}>
-            <Identifier name={prop.ident} optional={prop.optional} />
-          </span>
-          <span className={style.TextPunctuation}>: </span>
-          <Lang.Type type={prop.type} />
-        </React.Fragment>
-      ));
-
-      return (
-        <span className={style.Type}>
-          {extend?.length && (
-            <>
-              <span className={style.TypeKeyword}> extends </span>
-              <Join items={extend} limit={3}>
-                <span className={style.TextOperator}>, </span>
-              </Join>
-            </>
-          )}
-          <span className={style.TypePreview} data-stldocs-type-preview="properties">
-            <span className={style.TypeBrace}>{'{ '}</span>
-            <span className={style.TypePreviewContent}>
-              <Join items={items} limit={3}>
-                <span className={style.TextOperator}>, </span>
-              </Join>
-            </span>
-            <span className={style.TypeBrace}>{'} '}</span>
-          </span>
-        </span>
-      );
-    }
-  }
-}
-
-export type MethodSignatureProps = {
-  decl: TSAST.TSDeclFunction;
-};
-
-export function MethodSignature({ decl }: MethodSignatureProps) {
-  const Lang = useLanguageComponents();
-  const { Join, Tooltip } = useComponents();
-
-  const params = decl.signature.parameters.map((param, i) => (
-    <React.Fragment key={i}>
-      <Tooltip content={<Lang.Type type={param.type} />}>
-        <span className={style.TextIdentifier}>{param.ident}</span>
-      </Tooltip>
-      {param.optional && <span className={style.TextPunctuation}>?</span>}
-    </React.Fragment>
-  ));
-
-  return (
-    <div className={style.MethodSignature}>
-      <span className={style.SignatureTitle}>
-        {decl.signature.async && <span className={style.TextKeyword}>async </span>}
-        <span className={style.SignatureQualified}>
-          <span className={style.TextIdentifier}>{decl.qualified?.slice(0, -decl.ident.length)}</span>
-        </span>
-        <span className={style.SignatureName}>
-          <span className={style.TextIdentifier}>{decl.ident}</span>
-        </span>
-        <span className={style.MethodSignature}>
-          {decl.signature.typeParameters && <TypeParams params={decl.signature.typeParameters} />}
-          <span className={style.SignatureParen}>{'('}</span>
-
-          <span className={style.SignatureParams}>
-            <Join items={params}>
-              <span className={style.TextOperator}>{', '}</span>
-            </Join>
-          </span>
-
-          <span className={style.SignatureParen}>{')'}</span>
-          {decl.signature.returns && (
-            <>
-              <span className={style.TextPunctuation}>: </span>
-              <Lang.Type type={decl.signature.returns} />
-            </>
-          )}
-        </span>
-      </span>
-    </div>
-  );
-}
-
-export type PropertyProps = {
-  decl: TSAST.TSDeclaration;
-  children?: PropertyFn;
-};
-
-export function Property({ decl, children }: PropertyProps) {
-  const Lang = useLanguageComponents();
-
-  if (!decl) return;
-
-  switch (decl.kind) {
-    case 'TSDeclProperty':
-      return children({
-        name: decl.key,
-        typeName: <Lang.TypeName type={decl.type} />,
-        type: decl.type.kind in ComplexTypes && <Lang.Type type={decl.type} />,
-      });
-
-    case 'TSDeclTypeAlias':
-      return children({
-        name: decl.ident,
-        typeName: 'alias',
-        type: <Lang.Type type={decl.type} />,
-      });
-
-    case 'TSDeclReference':
-      return children({ type: <Lang.Type type={decl.type} /> });
-
-    case 'TSDeclInterface':
-      return children({
-        type: (
-          <>
-            <span className={style.TextIdentifier}>{decl.ident}</span>
-            {decl.typeParameters && <TypeParams params={decl.typeParameters} />}
-            {decl.extends?.flatMap((t, key) => (
-              <React.Fragment key={`extends:${key}`}>
-                <span className={style.TextKeyword}> extends </span>
-                <Lang.Type type={t} />
-              </React.Fragment>
-            ))}
-          </>
-        ),
-      });
-  }
-}
-
-export type DeclarationProps = { decl: TSAST.TSDeclaration };
-
-export function Declaration({ decl }: DeclarationProps) {
-  const Lang = useLanguageComponents();
-
-  if (!decl) return;
-
-  switch (decl.kind) {
-    case 'TSDeclProperty':
-      return (
-        <>
-          {decl.declare && <span className={style.TextKeyword}>declare </span>}
-          <span className={style.TypePropertyName}>
-            <Identifier name={decl.key} optional={decl.optional} />
-          </span>
-          <span className={style.TextPunctuation}>: </span>
-          <Lang.Type type={decl.type} />
-        </>
-      );
-
-    case 'TSDeclFunction':
-      return <Lang.MethodSignature decl={decl} />;
-
-    case 'TSDeclTypeAlias':
-      return (
-        <>
-          <Identifier name={decl.ident} />
-          <TypeParams params={decl.typeParameters} />
-          <span className={style.TextOperator}> = </span>
-          <Lang.Type type={decl.type} />
-        </>
-      );
-
-    case 'TSDeclReference':
-      return <Lang.Type type={decl.type} />;
-
-    case 'TSDeclInterface':
-      return (
-        <>
-          <span className={style.TextIdentifier}>{decl.ident}</span>
-          <TypeParams params={decl.typeParameters} />
-          {decl.extends?.map((t, index) => (
-            <React.Fragment key={index}>
-              <span className={style.TextKeyword}> extends </span>
-              <Lang.Type type={t} />
-            </React.Fragment>
-          ))}
-          <TypePreview path={decl.stainlessPath} />
-        </>
-      );
-
-    case 'TSDeclClass':
-      return (
-        <>
-          <span className={style.TextKeyword}>class </span>
-          <span className={style.TextIdentifier}>{decl.ident}</span>
-          <TypeParams params={decl.typeParameters} />
-          {decl.superClass ? (
-            <>
-              <span className={style.TextKeyword}> extends </span>
-              <Lang.Type type={decl.superClass} />
-            </>
-          ) : null}
-          {decl.implements?.map((t, index) => (
-            <React.Fragment key={index}>
-              <span className={style.TextKeyword}> implements </span>
-              <Lang.Type type={t} />
-            </React.Fragment>
-          ))}
-        </>
-      );
-  }
-}

package/src/markdown/index.ts

@@ -1,107 +0,0 @@
-import Markdoc from '@markdoc/markdoc';
-import * as md from './md';
-import { EnvironmentType, getDecl, getSnippet, stripMarkup } from './utils';
-import * as printer from '../search/printer';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import type { Node } from '@markdoc/markdoc';
-
-export function declaration(env: EnvironmentType, decl: SDKJSON.DeclarationNode) {
-  const content = printer.declaration(env.language, decl);
-  return md.paragraph(md.code(stripMarkup(content)));
-}
-
-function renderChildren(env: EnvironmentType, children: SDKJSON.ID[], nesting: string[] = []) {
-  return md.list(...children.map((child) => renderDecl(env, child, nesting)));
-}
-
-function renderDecl(env: EnvironmentType, path: string, nesting: string[] = []) {
-  const decl = getDecl(env, path);
-  const item = md.item(declaration(env, decl));
-
-  const hasChildren = 'children' in decl && decl.children.length > 0;
-  const showModelProps = !decl['modelPath'] || env.options.includeModelProperties;
-
-  if ('docstring' in decl && decl.docstring) item.children.push(...md.parse(decl.docstring));
-  if (hasChildren && showModelProps && !nesting.includes(path))
-    item.push(renderChildren(env, decl.children, [...nesting, path]));
-
-  return item;
-}
-
-function renderMethod(env: EnvironmentType, method: SDKJSON.Method) {
-  const decl = getDecl(env, method.stainlessPath);
-
-  if (!decl)
-    return [
-      md.paragraph(
-        md.text('The method '),
-        md.code(method.name),
-        md.text(' is not available in this language.'),
-      ),
-    ];
-
-  const signature = printer.methodSignature(env.language, decl);
-  const [httpMethod, endpoint] = method.endpoint.split(' ');
-
-  const output = [
-    md.heading(2, method.title),
-    env.language === 'http' ? null : md.paragraph(md.code(stripMarkup(signature))),
-    md.paragraph(md.strong(md.text(httpMethod)), md.text(' '), md.code(endpoint)),
-  ];
-
-  if (method.description) output.push(...md.parse(method.description));
-
-  if ('paramsChildren' in decl && Array.isArray(decl.paramsChildren) && decl.paramsChildren.length > 0)
-    output.push(md.heading(3, 'Parameters'), renderChildren(env, decl.paramsChildren));
-
-  if ('responseChildren' in decl && decl.responseChildren.length > 0)
-    output.push(md.heading(3, 'Returns'), renderChildren(env, decl.responseChildren));
-
-  const snippet = getSnippet(env, method.stainlessPath);
-  if (snippet) output.push(md.heading(3, 'Example'), md.fence(env.language, snippet));
-
-  return output;
-}
-
-function renderModel(env: EnvironmentType, model: SDKJSON.Model) {
-  return [md.heading(3, model.title), md.list(renderDecl(env, `${model.stainlessPath} > (schema)`))];
-}
-
-function renderResource(env: EnvironmentType, resource: SDKJSON.Resource) {
-  const methods = Object.values(resource.methods)
-    .filter((method) => getDecl(env, method.stainlessPath))
-    .flatMap((method) => renderMethod(env, method));
-
-  const models = Object.values(resource.models)
-    .filter((model) => getDecl(env, `${model.stainlessPath} > (schema)`))
-    .flatMap((model) => renderModel(env, model));
-
-  const doc: Node[] = [md.heading(1, resource.title), ...methods];
-
-  if (models.length > 0) doc.push(md.heading(2, 'Domain Types'), ...models);
-
-  if (!env.options.renderNestedResources) return doc;
-
-  const children = Object.values(resource.subresources).map((resource) => renderResource(env, resource));
-  return [...doc, ...children];
-}
-
-export function render(env: EnvironmentType, node: SDKJSON.Resource | SDKJSON.Method | SDKJSON.Model) {
-  switch (node.kind) {
-    case 'resource':
-      return renderResource(env, node);
-    case 'http_method':
-      return renderMethod(env, node);
-    case 'model':
-      return renderModel(env, node);
-  }
-}
-
-export function renderMarkdown(
-  env: EnvironmentType,
-  node: SDKJSON.Resource | SDKJSON.Method | SDKJSON.Model,
-) {
-  const content = render(env, node);
-  const doc = new Markdoc.Ast.Node('document', {}, content);
-  return Markdoc.format(doc);
-}

package/src/markdown/md.ts

@@ -1,45 +0,0 @@
-import Markdoc from '@markdoc/markdoc';
-import type { Node } from '@markdoc/markdoc';
-
-export function heading(level: number, children: string | Node[]) {
-  const content = inline(...(typeof children === 'string' ? [text(children)] : children));
-
-  return new Markdoc.Ast.Node('heading', { level }, [content]);
-}
-
-export function text(content: string) {
-  return new Markdoc.Ast.Node('text', { content });
-}
-
-export function code(content: string) {
-  return new Markdoc.Ast.Node('code', { content });
-}
-
-export function paragraph(...children: Node[]) {
-  const inline = new Markdoc.Ast.Node('inline', {}, children);
-  return new Markdoc.Ast.Node('paragraph', {}, [inline]);
-}
-
-export function list(...children: Node[]) {
-  return new Markdoc.Ast.Node('list', { ordered: false }, children);
-}
-
-export function item(...children: Node[]) {
-  return new Markdoc.Ast.Node('item', {}, children);
-}
-
-export function strong(...children: Node[]) {
-  return new Markdoc.Ast.Node('strong', {}, children);
-}
-
-export function inline(...children: Node[]) {
-  return new Markdoc.Ast.Node('inline', {}, children);
-}
-
-export function fence(language: string, content: string) {
-  return new Markdoc.Ast.Node('fence', { language, content });
-}
-
-export function parse(content: string) {
-  return Markdoc.parse(content).children;
-}

package/src/markdown/utils.ts

@@ -1,49 +0,0 @@
-import { Parser } from 'htmlparser2';
-import type { DocsLanguage } from '../routing';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import type { TransformRequestSnippetFn } from '../components/sdk';
-
-export type EnvironmentType = {
-  spec: SDKJSON.Spec;
-  language: DocsLanguage;
-  transforms?: {
-    transformRequestSnippet?: TransformRequestSnippetFn;
-  };
-  options: {
-    renderNestedResources?: boolean;
-    includeModelProperties?: boolean;
-  };
-};
-
-export function getDecl(env: EnvironmentType, path: string) {
-  const decl = env.spec?.decls?.[env.language]?.[path];
-
-  if (decl?.kind?.endsWith('Reference')) {
-    const refId = decl['type']['$ref'];
-    if (refId === path) return decl;
-    if (refId) return getDecl(env, refId);
-  }
-
-  return decl;
-}
-
-export function getSnippet(env: EnvironmentType, path: string) {
-  let snippet = env.spec?.snippets?.[`${env.language}.default`]?.[path];
-  if (typeof snippet === 'string' && env.transforms?.transformRequestSnippet) {
-    snippet = env.transforms.transformRequestSnippet({ snippet, language: env.language });
-  }
-  return snippet;
-}
-
-export function stripMarkup(content: string) {
-  let output = '';
-
-  const parser = new Parser({
-    ontext(content) {
-      output += content;
-    },
-  });
-
-  parser.parseComplete(content);
-  return output;
-}