API Docs Primitives

Copy"exports": {
  "./auto-anchor": "./dist/auto-anchor/index.js",
  "./auto-anchor/client": "./dist/auto-anchor/client.js",
  "./codegen": "./dist/codegen.js",
  "./components/accordion": "./dist/components/accordion.js",
  "./components/dialog": "./dist/components/dialog.js",
  "./components/input": "./dist/components/input.js",
  "./components/playground/inputs": "./dist/components/playground/inputs.js",
  "./components/playground/schema": "./dist/components/playground/schema.js",
  "./components/schema": "./dist/components/schema/index.js",
  "./components/schema/client": "./dist/components/schema/client.js",
  "./components/select": "./dist/components/select.js",
  "./components/select-tab": "./dist/components/select-tab.js",
  "./components/spinner": "./dist/components/spinner.js",
  "./i18n": "./dist/i18n.js",
  "./schema": "./dist/schema/index.js",
  "./schema/bundle": "./dist/schema/bundle.js",
  "./schema/dereference": "./dist/schema/dereference.js",
  "./schema/merge": "./dist/schema/merge.js",
  "./schema/ref": "./dist/schema/ref.js",
  "./schema/resolve-ref": "./dist/schema/resolve-ref.js",
  "./schema/sample": "./dist/schema/sample.js",
  "./schema/to-string": "./dist/schema/to-string.js",
  "./utils/id-to-title": "./dist/utils/id-to-title.js",
  "./utils/url": "./dist/utils/url.js",
  "./package.json": "./package.json",
  "./css/*": "./css/*"
},

Copyimport type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 
type ReferenceObject = { $ref: string };
 
export type NoReference<T> = T extends (infer I)[]
  ? NoReference<I>[]
  : T extends ReferenceObject
    ? Exclude<T, ReferenceObject>
    : T extends object
      ? {
          [K in keyof T]: NoReference<T[K]>;
        }
      : T;
 
export type NoReferenceSwallow<T> = T extends ReferenceObject ? Exclude<T, ReferenceObject> : T;
 
export type ParsedSchema =
  | (JSONSchema & {
      'x-playground-lazy'?: boolean;
      discriminator?: {
        propertyName?: string;
        mapping?: Record<string, string>;
      };
    })
  | boolean;

Copyexport type SchemaResolver = (schema: ParsedSchema) => {
  /** shallowly dereferenced schema */
  dereferenced: ParsedSchema;
  /** the ref value (if dereferenced) */
  $ref?: string;
};

Copyexport { bundle } from '@apidevtools/json-schema-ref-parser';

Copyexport interface CodeUsageGeneratorRegistry<Data = unknown, Context = unknown> {
  add: (id: string, generator: CodeUsageGenerator<Data, Context>) => void;
  get: (id: string) => CodeUsageGenerator<Data, Context> | undefined;
  addInline: (generator: InlineCodeUsageGenerator<Data, Context>) => void;
  /**
   * @returns if the generator is removed
   */
  remove: (id: string) => boolean;
  map: () => Map<string, CodeUsageGenerator<Data, Context>>;
}
 
/**
 * Generate code example for given programming language
 */
export interface CodeUsageGenerator<Data = unknown, Context = unknown> {
  generate: (data: Data, context: Context) => string;
  lang: string;
  label?: string;
}
 
/**
 * Generate code example for given programming language
 */
export interface InlineCodeUsageGenerator<Data = unknown, Context = unknown> {
  id?: string;
  lang: string;
  label?: string;
  /**
   * either:
   * - code
   * - a function imported from a file with "use client" directive
   * - false (disabled)
   */
  source?: string | CodeUsageGeneratorFn<Data, Context> | false;
}
 
export function createCodeUsageGeneratorRegistry<Data, Context>(
  inherit?: CodeUsageGeneratorRegistry<Data, Context>,
): CodeUsageGeneratorRegistry<Data, Context> {

Copyexport function dereferenceBundledDocument(bundled: Document): DereferencedDocument {
  const dereferenceMap = new Map<object, string>();
 
  return {
    bundled,
    dereferenced: dereferenceSync(bundled as JSONSchema, {
      setOriginalRef(schema, ref) {
        dereferenceMap.set(schema as object, ref);
      },
    }) as NoReference<Document>,
    getRawRef(obj: object) {
      return dereferenceMap.get(obj);
    },
  };
}

Copyexport interface DereferencedDocument {
  /**
   * dereferenced document
   */
  dereferenced: NoReference<Document>;
 
  /**
   * Get raw $ref from dereferenced object
   */
  getRawRef: (obj: object) => string | undefined;
 
  bundled: Document;
}

Copyexport function dereferenceBundledDocument(bundled: AsyncAPIObject): DereferencedDocument {
  const dereferenceMap = new Map<object, string>();
 
  return {
    bundled,
    dereferenced: dereferenceSync(bundled as JSONSchema, {
      setOriginalRef(schema, ref) {
        dereferenceMap.set(schema as object, ref);
      },
    }) as NoReference<AsyncAPIObject>,
    getRawRef(obj: object) {
      return dereferenceMap.get(obj);
    },
  };
}

Copyexport interface DereferencedDocument {
  /**
   * dereferenced document
   */
  dereferenced: NoReference<AsyncAPIObject>;
 
  /**
   * Get raw $ref from dereferenced object
   */
  getRawRef: (obj: object) => string | undefined;
 
  bundled: AsyncAPIObject;
}

Copyexport { bundle } from '@apidevtools/json-schema-ref-parser';

Copyfunction inferType(schema: SchemaDoc): string | null {
  if (schema.type !== undefined) {
    const t = schema.type;
    return Array.isArray(t) ? (t.length === 0 ? null : String(t[0])) : String(t);
  }
 
  const keywordTypes: Record<string, string> = {
    multipleOf: 'number',
    maximum: 'number',
    exclusiveMaximum: 'number',
    minimum: 'number',
    exclusiveMinimum: 'number',
    maxLength: 'string',
    minLength: 'string',
    pattern: 'string',
    items: 'array',
    maxItems: 'array',
    minItems: 'array',
    uniqueItems: 'array',
    additionalItems: 'array',
    maxProperties: 'object',
    minProperties: 'object',
    required: 'object',
    additionalProperties: 'object',
    properties: 'object',
    patternProperties: 'object',
    dependencies: 'object',
  };
 
  for (const [kw, ty] of Object.entries(keywordTypes)) {
    if (schema[kw] !== undefined) return ty;
  }
  return null;
}

Copyexport function getExampleRequests({
  path,
  method,
  ctx,
  operation,
  pathItem,
}: {
  path: string;
  pathItem: NoReference<PathItemObject>;
  method: HttpMethods;
  operation: NoReference<OperationObject>;
  ctx: RenderContext;
}): ExampleRequestItem[] {
  const requestBody = operation.requestBody;
  const media = requestBody?.content ? getPreferredType(requestBody.content) : null;
  const bodyOfType = media ? requestBody!.content![media] : null;
  const parameters = [...(operation.parameters ?? []), ...(pathItem.parameters ?? [])];
 
  if (bodyOfType?.examples) {
    const result: ExampleRequestItem[] = [];
 
    for (const [key, value] of Object.entries(bodyOfType.examples)) {
      const data = getRequestData({
        path,
        body: operation.requestBody,
        parameters,
        sampleKey: key,
        method,
      });
 
      result.push({
        id: key,
        name: value.summary || key,
        description: value.description,
        data,
        encoded: encodeRequestData(data, ctx.mediaAdapters, parameters),
      });
    }
 
    if (result.length > 0) return result;
  }
 
  const data = getRequestData({ path, body: operation.requestBody, method, parameters });
  return [
    {
      id: '_default',
      name: 'Default',
      description:
        typeof bodyOfType?.schema === 'object' ? bodyOfType.schema.description : undefined,
      data,
      encoded: encodeRequestData(data, ctx.mediaAdapters, parameters),
    },
  ];
}

Copyfunction getRequestData({
  method,
  path,
  parameters,
  sampleKey,
  body,
}: {
  path: string;
  sampleKey?: string;
  method: HttpMethods;
  parameters: NoReference<ParameterObject>[];
  body?: NoReference<RequestBodyObject>;
}): RawRequestData {
  const result: RawRequestData = {
    path: {},
    cookie: {},
    header: {},
    query: {},
    method: method,
  };
 
  for (const param of parameters) {
    let value = pickExample(param as never);
 
    if (value === undefined && param.required) {
      if (param.schema) {
        value = sample(param.schema as object);
      } else if (param.content) {
        const type = getPreferredType(param.content);
        const content = type ? param.content[type] : undefined;
        if (!content || !content.schema)
          throw new Error(
            `Cannot find "${param.name}" parameter info for media type "${type}" in ${path} ${method}`,
          );
 
        value = sample(content.schema as object);
      }
    }
 
    switch (param.in) {
      case 'cookie':
        result.cookie[param.name!] = value;
        break;
      case 'header':
        result.header[param.name!] = value;
        break;
      case 'query':
        result.query[param.name!] = value;
        break;
      default:
        result.path[param.name!] = value;
    }
  }
 
  if (body?.content) {
    const type = getPreferredType(body.content);
    if (!type) throw new Error(`Cannot find body schema for ${path} ${method}: missing media type`);
    result.bodyMediaType = type as RawRequestData['bodyMediaType'];
    const bodyOfType = body.content[type];
 
    if (bodyOfType.examples && sampleKey) {
      result.body = bodyOfType.examples[sampleKey].value;
    } else if (bodyOfType.example) {
      result.body = bodyOfType.example;
    } else {
      result.body = sample((bodyOfType?.schema ?? {}) as object, {
        skipReadOnly: method !== 'get',
        skipWriteOnly: method === 'get',
        skipNonRequired: true,
      });
    }
  }
 
  return result;
}

Copyexport enum FormatFlags {
  None = 0,
  UseAlias = 1 << 0,
}
 
export function schemaToString(
  value: ParsedSchema,
  resolver?: SchemaResolver,
  flags: FormatFlags = FormatFlags.None,
): string {

Copyif (schema.type === 'array')
  return `array<${schema.items ? run(schema.items, flags | FormatFlags.UseAlias) : 'unknown'}>`;
 

Copyif (schema.oneOf && schema.anyOf) {
  return `(${union(schema.oneOf, ' | ', flags)}) & (${union(schema.anyOf, ' | ', flags)})`;
}

Copyexport interface SchemaUIGeneratedData {
  $root: string;
  refs: Record<string, SchemaData>;
}
 
export function Schema({
  client,
  root,
  readOnly,
  writeOnly,
  resolver,
  showExample,
  renderMarkdown,
}: SchemaUIOptions) {
  const translations = useTranslations().translations;
  const generated = useMemo(() => {
    return generateSchemaUI({
      root,
      resolver,
      readOnly,
      writeOnly,
      showExample,
      renderMarkdown,
      translations,
    });
  }, [root, readOnly, writeOnly, resolver, showExample, renderMarkdown, translations]);
 
  return <SchemaUI {...client} generated={generated} />;
}
 
export function generateSchemaUI({
  root,
  resolver,
  renderMarkdown,
  readOnly = false,
  writeOnly = false,
  showExample = false,
  translations = {},
}: Omit<SchemaUIOptions, 'client'> & {
  translations?: Partial<Record<string, string>>;
}): SchemaUIGeneratedData {

Copyif (schema.type === 'object') {
  const out: SchemaData = {
    type: 'object',
    props: [],
    ...base(schema),
  };
  refs[id] = out;
 
  const { properties = {}, patternProperties, additionalProperties } = schema;
  const props = Object.entries(properties);
  if (patternProperties) props.push(...Object.entries(patternProperties));
 
  for (const [key, prop] of props) {
    if (!prop || !isVisible(prop)) continue;
    const $type = getSchemaId(prop);
    scanRefs($type, prop);
    out.props.push({
      $type,
      name: key,
      required: schema.required?.includes(key) ?? false,
    });
  }
 
  if (additionalProperties && isVisible(additionalProperties)) {
    const $type = getSchemaId(additionalProperties);
    scanRefs($type, additionalProperties);
 
    out.props.push({
      $type,
      name: '[key: string]',
      required: false,
    });
  }
  return;

Copyimport { slug } from 'github-slugger';
 
/** slugify segments, append `\0` to keep segment as-is */
export function anchorSegments(...segs: string[]): string {
  const mapped: string[] = [];
  for (const seg of segs) {
    if (seg.startsWith('\0')) {
      mapped.push(seg.slice(1));
    } else if (seg.length > 0) {
      mapped.push(slug(seg));
    }
  }
  return mapped.join('.');
}

Copyinterface PathItemType {
  name: string;
  $ref: string;
  scrollTop?: number;
  /** property name of highlighted field, only applicable for objects */
  highlighted?: string;
  tabValues?: string[];
  /** popover state, only applicable for root */
  closed?: boolean;
}
 
interface StateContextType {
  rootId: string;
  /** the first tiem will always be the root item */
  path: PathItemType[];
  setPath: (path: PathItemType[]) => void;
  generated: SchemaUIGeneratedData;
  renderTypeInfoTrigger: (props: {
    pathName: string;
    $ref: string;
    children: ReactNode;
  }) => ReactNode;
}

Copyexport function formatBindingScalar(value: unknown): string {
  if (value === null || value === undefined) return '';
  if (typeof value === 'boolean') return value ? 'Yes' : 'No';
  if (typeof value === 'number') return String(value);
  if (typeof value === 'string') return value;
  if (Array.isArray(value)) {
    return value.map((item) => formatBindingScalar(item)).join(', ');
  }
 
  return JSON.stringify(value);
}
 
export function hasBindingFields(
  binding: Record<string, unknown>,
  ignore: string[] = ['bindingVersion'],
): boolean {
  return Object.keys(binding).some(
    (key) => !ignore.includes(key) && !key.startsWith('x-') && binding[key] !== undefined,
  );
}
 
export function joinBindingSummary(
  ...parts: (string | undefined | null | false)[]
): string | undefined {
  const filtered = parts.filter((part): part is string => Boolean(part));
  return filtered.length > 0 ? filtered.join(' · ') : undefined;
}