@stainless-api/docs-ui 0.1.0-beta.7 → 0.1.0-beta.71

package/src/languages/go.tsx

@@ -1,281 +0,0 @@
-import * as React from 'react';
-import type * as AST from '~/lib/json-spec-v2/GoAST';
-
-import { useComponents } from '../contexts/use-components';
-import { useLanguageComponents } from '../contexts';
-import style from '../style';
-import { PropertyFn } from '.';
-
-const ComplexTypes: Record<string, string> = {
-  GoTypeMap: 'map',
-  GoTypeArray: 'array',
-};
-
-const Keywords = {
-  GoTypeAny: 'any',
-  GoTypeUnknown: 'unknown',
-  GoTypeInt: 'int64',
-  GoTypeFloat: 'float64',
-  GoTypeBool: 'bool',
-  GoTypeError: 'error',
-};
-
-function isField(type: AST.GoType) {
-  return type.kind === 'GoTypeReference' && type.typeName === 'param.Field';
-}
-
-export type TypeProps = {
-  type: AST.GoType;
-};
-
-export function TypeName({ type }: TypeProps) {
-  const Lang = useLanguageComponents();
-  return isField(type) ? 'field' : (ComplexTypes[type.kind] ?? <Lang.Type type={type} />);
-}
-
-export function Type({ type }: TypeProps) {
-  const Lang = useLanguageComponents();
-  const { Join, SDKReference } = useComponents();
-
-  switch (type.kind) {
-    case 'GoTypeReference': {
-      const params = type.typeParameters?.map((param, key) => <Lang.Type key={key} type={param} />);
-
-      return (
-        <span className={style.Type}>
-          <SDKReference stainlessPath={type.$ref}>{type.typeName}</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>
-            </>
-          ) : null}
-        </span>
-      );
-    }
-
-    case 'GoTypeAny':
-    case 'GoTypeUnknown':
-    case 'GoTypeInt':
-    case 'GoTypeFloat':
-    case 'GoTypeBool':
-    case 'GoTypeError':
-      return (
-        <span className={style.Type}>
-          <span className={style.TypeKeyword}>{Keywords[type.kind]}</span>
-        </span>
-      );
-
-    case 'GoTypeString':
-      return (
-        <span className={style.Type}>
-          <span className={style.TypeString}>string</span>
-        </span>
-      );
-
-    case 'GoTypeArray':
-      return (
-        <span className={style.Type}>
-          <span className={style.TextOperator}>[]</span>
-          <Lang.Type type={type.elementType} />
-        </span>
-      );
-
-    case 'GoTypeStruct':
-      return (
-        <span className={style.Type}>
-          <span className={style.TypeKeyword}>{'struct{…}'}</span>
-        </span>
-      );
-
-    case 'GoTypeInterface':
-      return (
-        <span className={style.Type}>
-          <span className={style.TypeKeyword}>{'interface{…}'}</span>
-        </span>
-      );
-
-    case 'GoTypeMap':
-      return (
-        <span className={style.Type}>
-          <span className={style.TypeKeyword}>map</span>
-          <span className={style.TypeBracket}>[</span>
-          <Lang.Type type={type.indexType} />
-          <span className={style.TextPunctuation}>,</span> <Lang.Type type={type.itemType} />
-          <span className={style.TypeBracket}>]</span>
-        </span>
-      );
-
-    case 'GoTypePointer':
-      return (
-        <span className={style.Type}>
-          <span className={style.TextOperator}>*</span>
-          <Lang.Type type={type.inner} />
-        </span>
-      );
-  }
-}
-
-export type MethodSignatureProps = {
-  decl: AST.GoDeclFunction;
-};
-
-export function MethodSignature({ decl }: MethodSignatureProps) {
-  const Lang = useLanguageComponents();
-  const { Join } = useComponents();
-
-  const params = decl.parameters.map((param, i) => (
-    <React.Fragment key={i}>
-      <span className={style.TextIdentifier}>{param.ident}</span>
-      {param.optional && <span className={style.TextPunctuation}>?</span>}
-    </React.Fragment>
-  ));
-
-  const returns = decl.returnType.map((t, key) => <Lang.Type key={key} type={t} />);
-
-  return (
-    <div className={style.MethodSignature}>
-      <span className={style.SignatureTitle}>
-        {decl.async && <span className={style.TextKeyword}>async </span>}
-        {decl.qualified && (
-          <span className={style.SignatureQualified}>
-            <span className={style.TextIdentifier}>{decl.qualified?.slice(0, -decl.ident.length)}</span>
-          </span>
-        )}
-        {decl.kind === 'GoDeclFunction' && (
-          <span className={style.SignatureName}>
-            <span className={style.TextIdentifier}>{decl.ident}</span>
-          </span>
-        )}
-        <span className={style.MethodSignature}>
-          <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.returnType.length === 1 ? (
-            returns
-          ) : (
-            <>
-              <span className={style.SignatureParen}>{'('}</span>
-              <Join items={returns}>
-                <span className={style.TextOperator}>, </span>
-              </Join>
-              <span className={style.SignatureParen}>{')'}</span>
-            </>
-          )}
-        </span>
-      </span>
-    </div>
-  );
-}
-
-export type PropertyProps = {
-  decl: AST.GoDeclaration;
-  children?: PropertyFn;
-};
-
-export function Property({ decl, children }: PropertyProps) {
-  const Docs = useComponents();
-  const Lang = useLanguageComponents();
-
-  if (!decl) return null;
-
-  switch (decl.kind) {
-    case 'GoDeclProperty':
-      return children({
-        name: decl.ident,
-        typeName: <Lang.TypeName type={decl.type} />,
-        badges: decl.optional && <Docs.Badge id="optional" />,
-        type: (isField(decl.type) || decl.type.kind in ComplexTypes) && <Lang.Type type={decl.type} />,
-      });
-
-    case 'GoDeclConst':
-      return children({
-        name: decl.ident,
-        typeName: 'const',
-        type: <Lang.Type type={decl.type} />,
-      });
-
-    case 'GoDeclReference':
-      return children({ type: <Lang.Type type={decl.type} /> });
-
-    case 'GoDeclType':
-    case 'GoDeclTypeAlias': {
-      const typeName =
-        decl.type.kind === 'GoTypeStruct'
-          ? 'struct'
-          : decl.type.kind === 'GoTypeInterface'
-            ? 'interface'
-            : decl.kind === 'GoDeclTypeAlias'
-              ? 'alias'
-              : 'type';
-
-      return children({
-        name: decl.ident,
-        typeName,
-        type: ['GoTypeStruct', 'GoTypeInterface'].includes(decl.type.kind) || <Lang.Type type={decl.type} />,
-      });
-    }
-  }
-}
-
-export type DeclarationProps = { decl: AST.GoDeclaration };
-
-export function Declaration({ decl }: DeclarationProps) {
-  const Lang = useLanguageComponents();
-
-  if (!decl) return;
-
-  switch (decl.kind) {
-    case 'GoDeclType':
-      return (
-        <>
-          <span className={style.TextKeyword}>type </span>
-          <span className={style.TextIdentifier}>{decl.ident} </span>
-          <Lang.Type type={decl.type} />
-        </>
-      );
-
-    case 'GoDeclTypeAlias':
-      return (
-        <>
-          <span className={style.TextKeyword}>type </span>
-          <span className={style.TextIdentifier}>{decl.ident} </span>
-          <span className={style.TextOperator}>= </span>
-          <Lang.Type type={decl.type} />
-        </>
-      );
-
-    case 'GoDeclProperty':
-      return (
-        <>
-          <span className={style.TypePropertyName}>
-            <span className={style.TextIdentifier}>{decl.ident} </span>
-          </span>
-          <Lang.Type type={decl.type} />
-        </>
-      );
-
-    case 'GoDeclReference':
-      return <Lang.Type type={decl.type} />;
-
-    case 'GoDeclConst':
-      return (
-        <>
-          <span className={style.TextKeyword}>const </span>
-          <span className={style.TextIdentifier}>{decl.ident} </span>
-          <Lang.Type type={decl.type} />
-          <span className={style.TextOperator}> = </span>
-          {JSON.stringify(decl.value)}
-        </>
-      );
-  }
-}

package/src/languages/http.tsx

@@ -1,321 +0,0 @@
-import type * as AST from '~/lib/json-spec-v2/HttpAST';
-import { useDeclaration, useLanguage, useLanguageComponents, useSpec } from '../contexts';
-import { useComponents } from '../contexts/use-components';
-import style from '../style';
-import React from 'react';
-import { PropertyFn } from '.';
-import { PropertyToggle } from '../components';
-
-const ComplexTypes: Partial<Record<AST.HttpType['kind'], string>> = {
-  HttpTypeUnion: 'union',
-  HttpTypeIntersection: 'intersection',
-};
-
-const constStyle = {
-  string: style.LiteralString,
-  number: style.LiteralNumeric,
-  boolean: style.LiteralBoolean,
-};
-
-type TypeProps = {
-  type: AST.HttpType;
-};
-
-function Identifier({ name }: { name: string }) {
-  return (
-    <>
-      <span className={style.TextIdentifier}>
-        {/^[_a-zA-Z][_a-zA-Z0-9]*$/.test(name) ? name : JSON.stringify(name)}
-      </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'] === 'HttpTypeUnion')
-    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();
-
-  if (type.kind === 'HttpTypeArray') return <>array of {<Lang.TypeName type={type.elementType} />}</>;
-
-  if (type.kind === 'HttpTypeUnion' && type.types.every((t) => t.kind === 'HttpTypeLiteral')) return 'enum';
-
-  if (type.kind === 'HttpTypeReference' && type.ident.split('.').at(-1) === 'Record') return 'map';
-
-  return ComplexTypes[type.kind] ?? <Lang.Type type={type} />;
-}
-
-export function Type({ type }: TypeProps) {
-  const Lang = useLanguageComponents();
-  const { Join, SDKReference } = useComponents();
-
-  switch (type.kind) {
-    case 'HttpTypeUnknown':
-    case 'HttpTypeUndefined':
-    case 'HttpTypeNull':
-    case 'HttpTypeBoolean':
-    case 'HttpTypeNumber':
-      return (
-        <span className={style.Type}>
-          <span className={style.TypePlain}>{type.kind.slice(8).toLowerCase()}</span>
-        </span>
-      );
-
-    case 'HttpTypeString':
-      return (
-        <span className={style.Type}>
-          <span className={style.TypePlain}>string</span>
-        </span>
-      );
-
-    case 'HttpTypeLiteral':
-      return (
-        <span className={style.Type}>
-          <span className={constStyle[typeof type.literal]}>{JSON.stringify(type.literal)}</span>
-        </span>
-      );
-
-    case 'HttpTypeArray': {
-      return (
-        <span className={style.Type}>
-          <span className={style.TypeArray}>{'array of '}</span>
-          <Lang.Type type={type.elementType} />
-        </span>
-      );
-    }
-
-    case 'HttpTypeIntersection':
-    case 'HttpTypeUnion': {
-      const items = type.types.map((t, key) => <Lang.Type key={key} type={t} />);
-
-      const delimiter = type.kind === 'HttpTypeUnion' ? 'or' : 'and';
-
-      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 'HttpTypeReference': {
-      const name = type.ident.split('.').at(-1);
-      const params = type.typeParameters?.map((param, key) => <Lang.Type key={key} type={param} />);
-
-      // TODO: come up with an unambiguous way to identify these on the sdkjson side
-      // This is sketchy because it's possible for a user-defined type to be named "Record"
-      if (
-        name === 'Record' &&
-        type.typeParameters?.length === 2 &&
-        type.typeParameters?.at(0).kind === 'HttpTypeString'
-      )
-        return (
-          <>
-            <span className={style.TypeArray}>map</span>[{params?.[1]}]
-          </>
-        );
-
-      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 'HttpTypeObject':
-      const items = type.members.map(({ ident }) => (
-        <span className={style.TypePropertyName}>
-          <Identifier name={ident} />
-        </span>
-      ));
-
-      return (
-        <span className={style.Type}>
-          <span className={style.TypePlain}>object</span>
-          <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: AST.HttpDeclFunction;
-};
-
-export function MethodSignature({ decl }: MethodSignatureProps) {
-  return null;
-}
-
-export function MethodInfo({ decl, children }: MethodSignatureProps & { children: React.ReactNode }) {
-  const Docs = useComponents();
-
-  const params = Object.entries(decl.paramsChildren)
-    .filter(([_, value]) => value.length)
-    .map(([location, value]) => (
-      <React.Fragment key={location}>
-        <div className={style.MethodParameters} data-stldocs-property-group={location.at(0)}>
-          <h5>
-            {location.at(0).toUpperCase()}
-            {location.slice(1)} Parameters
-            <PropertyToggle target={location.at(0)} />
-          </h5>
-          <Docs.SDKChildren paths={value} />
-        </div>
-      </React.Fragment>
-    ));
-
-  if (decl.bodyParamsChildren?.['application/json']?.length > 0)
-    params.push(
-      <div className={style.MethodInfoSection}>
-        <h5>
-          Body Parameters
-          <PropertyToggle target="body" />
-        </h5>
-        <div className={style.MethodParameters} data-stldocs-property-group="body">
-          <Docs.SDKChildren paths={decl.bodyParamsChildren?.['application/json']} />
-        </div>
-      </div>,
-    );
-
-  return (
-    <div className={style.MethodInfo}>
-      {children && <div className={style.MethodContent}>{children}</div>}
-      {params.length > 0 && params}
-      {decl.responseChildren.length > 0 && (
-        <div className={style.MethodInfoSection}>
-          <h5>
-            Returns
-            <PropertyToggle target="returns" />
-          </h5>
-          <div className={style.MethodReturns} data-stldocs-property-group="returns">
-            <Docs.SDKChildren paths={decl.responseChildren} />
-          </div>
-        </div>
-      )}
-    </div>
-  );
-}
-
-function renderVariantInfo(type: AST.HttpType) {
-  if (
-    type.kind === 'HttpTypeUnion' &&
-    type.types.every((t) => t.kind === 'HttpTypeObject' || t.kind === 'HttpTypeReference')
-  )
-    return <>One of the following {type.types.length} object variants:</>;
-}
-
-export type PropertyProps = {
-  decl: AST.HttpDeclaration;
-  children?: PropertyFn;
-};
-
-export function Property({ decl, children }: PropertyProps) {
-  const Lang = useLanguageComponents();
-
-  if (!decl) return;
-
-  switch (decl.kind) {
-    case 'HttpDeclProperty': {
-      const variants = renderVariantInfo(decl.type);
-
-      return children({
-        name: decl.key,
-        typeName: <Lang.TypeName type={decl.type} />,
-        type: decl.type.kind in ComplexTypes && !variants && <Lang.Type type={decl.type} />,
-      });
-    }
-
-    case 'HttpDeclTypeAlias':
-      return children({
-        name: decl.ident,
-        typeName: <Lang.TypeName type={decl.type} />,
-      });
-
-    case 'HttpDeclReference':
-      return children({ type: <Lang.Type type={decl.type} /> });
-  }
-}
-
-export type DeclarationProps = { decl: AST.HttpDeclaration };
-
-export function Declaration({ decl }: DeclarationProps) {
-  const Lang = useLanguageComponents();
-
-  if (!decl) return;
-
-  switch (decl.kind) {
-    case 'HttpDeclProperty':
-      return (
-        <>
-          <span className={style.TypePropertyName}>
-            <Identifier name={decl.key} />
-          </span>
-          <span className={style.TextPunctuation}>: </span>
-          {decl.optional && <span className={style.TextPunctuation}>optional </span>}
-          <Lang.Type type={decl.type} />
-        </>
-      );
-
-    case 'HttpDeclTypeAlias':
-      return (
-        <>
-          <Identifier name={decl.ident} />
-          <span className={style.TextOperator}> = </span>
-          <Lang.Type type={decl.type} />
-        </>
-      );
-
-    case 'HttpDeclReference':
-      return <Lang.Type type={decl.type} />;
-  }
-}

package/src/languages/index.ts

@@ -1,26 +0,0 @@
-import { type ReactNode } from 'react';
-import type { DeclarationNode, Type } from '~/lib/json-spec-v2/types';
-
-import * as typescript from './typescript';
-import * as java from './java';
-import { PropertyProps } from '../components';
-
-export * as go from './go';
-export * as python from './python';
-export * as ruby from './ruby';
-export * as http from './http';
-
-export { typescript, java };
-export const node = typescript;
-export const kotlin = java;
-
-export type PropertyFn = (params: PropertyProps) => ReactNode;
-
-export interface LanguageComponentDefinition {
-  Declaration(props: { decl: DeclarationNode });
-  Property(props: { decl: DeclarationNode; children: PropertyFn });
-  TypeName(props: { type: Type; optional?: boolean });
-  Type(props: { type: Type; optional?: boolean });
-  MethodSignature(props: { decl: DeclarationNode });
-  MethodInfo?(props: { decl: DeclarationNode; children?: ReactNode });
-}