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

package/src/routing.ts

@@ -1,238 +0,0 @@
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-
-export const Languages = [
-  'http',
-  'node',
-  'python',
-  'go',
-  'typescript',
-  'terraform',
-  'ruby',
-  'java',
-  'kotlin',
-] as const;
-
-export const SupportedLanguageSyntaxes = [
-  'http',
-  'javascript',
-  'python',
-  'go',
-  'typescript',
-  'terraform',
-  'ruby',
-  'java',
-  'kotlin',
-];
-
-export type DocsLanguage = (typeof Languages)[number];
-
-export const LanguageNames: Record<DocsLanguage, string> = {
-  http: 'HTTP',
-  node: 'TypeScript',
-  typescript: 'TypeScript',
-  python: 'Python',
-  go: 'Go',
-  ruby: 'Ruby',
-  java: 'Java',
-  kotlin: 'Kotlin',
-  terraform: 'Terraform',
-};
-
-export function getLanguageSnippet(language: DocsLanguage) {
-  return language === 'http' ? ('http.curl' as const) : (`${language}.default` as const);
-}
-
-export function isSupportedLanguage(language: string): language is DocsLanguage {
-  return Languages.includes(language as DocsLanguage);
-}
-
-const DefaultLanguage = 'http';
-
-const StainlessPathPattern =
-  /(\(resource\) (?<resource>[^\s]+))( > (\(method\) (?<method>[^\s]+)|\(model\) (?<model>[^\s]+))?)?/;
-
-export type ParsedStainlessPath = ReturnType<typeof parseStainlessPath>;
-
-export function parseStainlessPath(stainlessPath: string) {
-  const match = stainlessPath.match(StainlessPathPattern);
-
-  if (!match) return null;
-
-  return {
-    resource: match.groups.resource.split('.'),
-    method: match.groups.method ?? null,
-    model: match.groups.model ?? null,
-    routable: match.groups.model ? match[1] : match[0],
-  };
-}
-
-export function trimStainlessPath(stainlessPath: string) {
-  return stainlessPath.replace(/ > \([^\s]+\)$/, '');
-}
-
-export function getResource(stainlessPath: string) {
-  const parsed = parseStainlessPath(stainlessPath);
-  return parsed?.resource[0];
-}
-
-export function parseRoute(
-  basePath: string,
-  route: string,
-): { stainlessPath: string; language: DocsLanguage } {
-  if (!route.startsWith(basePath)) return { stainlessPath: '', language: DefaultLanguage };
-
-  if (basePath && route.startsWith(basePath)) route = route.slice(basePath.length);
-
-  let stainlessPath = '';
-  let elements = route.slice(1).split('/');
-  let language: DocsLanguage = DefaultLanguage;
-
-  if (elements[0] && Languages.includes(elements[0] as DocsLanguage)) {
-    language = elements[0] as DocsLanguage;
-    elements = elements.slice(1);
-  }
-
-  while (elements.length > 0) {
-    const element = elements.shift();
-    switch (element) {
-      case 'resources':
-        stainlessPath += `(resource) ${elements.shift()}`;
-        break;
-
-      case 'subresources':
-        stainlessPath += `.${elements.shift()}`;
-        break;
-
-      case 'methods':
-        stainlessPath += ` > (method) ${elements.shift()}`;
-        break;
-    }
-  }
-
-  return { stainlessPath, language };
-}
-
-export function generateRoute(basePath: string, language: string, stainlessPath: string) {
-  const parsedPath = parseStainlessPath(stainlessPath);
-  if (!parsedPath) return null;
-
-  const path = [basePath.endsWith('/') ? basePath.slice(0, -1) : basePath];
-  if (language && language !== DefaultLanguage) path.push(language);
-
-  const resources = parsedPath.resource.flatMap((name, index) => [
-    index > 0 ? 'subresources' : 'resources',
-    name,
-  ]);
-
-  // Ensure model links always go to top-level resource page
-  const resourcePath = parsedPath.model ? resources.slice(0, 2) : resources;
-  path.push(...resourcePath);
-
-  if (parsedPath.method) path.push('methods', parsedPath.method);
-
-  return stainlessPath.length > parsedPath.routable.length
-    ? `${path.join('/')}#${encodeURIComponent(stainlessPath)}`
-    : path.join('/');
-}
-
-export type SpecTreeEntry = {
-  data: SDKJSON.Method | SDKJSON.Resource | SDKJSON.Model;
-  path: string[];
-};
-
-function* walkResource(
-  resource: SDKJSON.Resource,
-  path: string[],
-  includeModels?: boolean,
-): Generator<SpecTreeEntry> {
-  yield { data: resource, path };
-
-  for (const data of Object.values(resource.methods)) {
-    yield { data, path: [...path, 'methods', data.name] };
-  }
-
-  if (includeModels)
-    for (const data of Object.values(resource.models)) {
-      yield { data, path: [...path, 'models', data.name] };
-    }
-
-  for (const data of Object.values(resource.subresources ?? {})) {
-    yield* walkResource(data, [...path, 'subresources', data.name]);
-  }
-}
-
-export function* walkTree(spec: SDKJSON.Spec, includeModels?: boolean) {
-  for (const data of Object.values(spec.resources)) {
-    yield* walkResource(data, ['resources', data.name], includeModels);
-  }
-}
-
-export type RouteEntry = {
-  title: string;
-  kind: SpecTreeEntry['data']['kind'];
-  language: DocsLanguage;
-  stainlessPath: string;
-  slug: string;
-};
-
-export function generateRouteList({
-  spec,
-  languages,
-  excludeLanguages = [],
-}: {
-  spec: SDKJSON.Spec;
-  languages?: DocsLanguage[];
-  excludeLanguages?: DocsLanguage[];
-}): RouteEntry[] {
-  const entries = Array.from(walkTree(spec));
-  const langs = languages ?? spec.docs?.languages ?? ['http'];
-
-  return langs
-    .filter((lang) => Languages.includes(lang) && lang !== 'terraform')
-    .filter((lang) => !excludeLanguages?.includes(lang))
-    .flatMap((language) =>
-      entries.map(({ path, data: { title, kind, stainlessPath } }) => ({
-        title,
-        kind,
-        language,
-        stainlessPath,
-        slug: (language === 'http' ? path : [language, ...path]).join('/'),
-      })),
-    );
-}
-
-type ResourceOrMethod = SDKJSON.Resource | SDKJSON.Method;
-
-export function findNavigationPath(items: ResourceOrMethod[], target: string) {
-  for (const item of Object.values(items)) {
-    if (item.stainlessPath === target) return [item.stainlessPath];
-    if (item.kind === 'http_method') continue;
-
-    const path = findNavigationPath(
-      [...Object.values(item.methods ?? {}), ...Object.values(item.subresources ?? {})],
-      target,
-    );
-
-    if (path) return [item.stainlessPath, ...path];
-  }
-}
-
-export function expandToElement(el: HTMLElement) {
-  while (el) {
-    if (el.tagName === 'DETAILS') el['open'] = true;
-    el = el.parentElement;
-  }
-}
-
-export function scrollToPath(stainlessPath: string) {
-  const el = document.getElementById(stainlessPath);
-  if (el) {
-    expandToElement(el);
-    el.scrollIntoView({ behavior: 'smooth' });
-  }
-}
-
-export function updateHistory(basePath: string, language: DocsLanguage, stainlessPath: string) {
-  const path = generateRoute(basePath, language, stainlessPath);
-  window.history.pushState({ stainlessPath, language }, '', path);
-}

package/src/search/form.tsx

@@ -1,127 +0,0 @@
-import * as React from 'react';
-import { Search as SearchIcon, X as XIcon } from 'lucide-react';
-import { QueryKinds, QueryKindsType, ResultData } from './types';
-import { GuideResult, QueryKindDisplay, SearchResult } from './results';
-import { guideSearch } from './providers/pagefind';
-import { useLanguage, useSearch, useSearchContext } from '../contexts';
-import { useComponents } from '../contexts/use-components';
-
-import style from '../style';
-
-export function SearchForm() {
-  const Docs = useComponents();
-  const search = useSearch();
-  const language = useLanguage();
-  const { onSelect, pageFind } = useSearchContext();
-
-  const [results, setResults] = React.useState<ResultData>(null);
-  const [filterKind, setFilterKind] = React.useState<QueryKindsType>('all');
-  const [searchQuery, setSearchQuery] = React.useState<string>('');
-  const inputRef = React.useRef<HTMLInputElement>(null);
-
-  async function performSearch() {
-    const guideLimit = filterKind === 'guide' ? 25 : 5;
-    const kind = ['all', 'guide'].includes(filterKind) ? undefined : filterKind;
-
-    const [guideResults, apiResults] = await Promise.all([
-      pageFind ? guideSearch(pageFind, searchQuery, guideLimit) : [],
-      search({ query: searchQuery, kind, language }),
-    ]);
-
-    setResults({
-      items: filterKind === 'guide' ? guideResults : [...guideResults, ...apiResults.hits],
-      counts: {
-        ...apiResults.facets?.['kind'],
-        guide: guideResults.length,
-        all: apiResults.nbHits,
-      },
-    });
-  }
-
-  function clearInput() {
-    setSearchQuery('');
-    inputRef?.current?.focus();
-  }
-
-  React.useEffect(() => void performSearch(), [searchQuery, filterKind, language]);
-
-  return (
-    <div className={style.SearchForm}>
-      <Docs.Input
-        ref={inputRef}
-        autoFocus
-        onChange={(ev) => setSearchQuery(ev.target.value)}
-        left={<SearchIcon size={16} className={style.Icon} />}
-        right={
-          searchQuery && (
-            <XIcon cursor="pointer" onClick={() => clearInput()} size={16} className={style.Icon} />
-          )
-        }
-        value={searchQuery}
-        placeholder="Search"
-      />
-
-      <SearchFilter
-        results={results}
-        filterKind={filterKind}
-        onChange={(filterKind) => setFilterKind(filterKind)}
-      />
-
-      <Docs.ListView
-        items={results?.items ?? []}
-        itemDelegate={(item) =>
-          'kind' in item ? <SearchResult result={item} /> : <GuideResult result={item} />
-        }
-        onSelectListItem={(item) => onSelect?.(item['data']?.['url'] ?? item['stainlessPath'])}
-      />
-    </div>
-  );
-}
-
-export type SearchFilterProps = {
-  results: ResultData;
-  filterKind: QueryKindsType;
-  onChange: (filterKind?: QueryKindsType) => void;
-};
-
-export function SearchFilter({ results, filterKind, onChange }: SearchFilterProps) {
-  const Docs = useComponents();
-  const { pageFind } = useSearchContext();
-  const toggles = pageFind ? QueryKinds : QueryKinds.slice(0, -1);
-
-  return (
-    <div className={style.SearchFilter}>
-      {toggles.map((kind, index) => (
-        <Docs.ToggleButton key={index} selected={filterKind === kind} onClick={() => onChange?.(kind)}>
-          {React.createElement(QueryKindDisplay[kind].icon, {
-            size: 16,
-            className: style.Icon,
-          })}
-          {QueryKindDisplay[kind].name}
-          <span className={style.SearchFilterCount}>{results?.counts?.[kind] ?? 0}</span>
-        </Docs.ToggleButton>
-      ))}
-    </div>
-  );
-}
-
-export type SearchModalProps = {
-  id?: string;
-  open?: boolean;
-};
-
-export function SearchModal({ id, open: isOpen }: SearchModalProps) {
-  const [open, setOpen] = React.useState<boolean>(isOpen);
-
-  return (
-    <div
-      id={id}
-      onToggle={(ev) => setOpen(ev.newState === 'open')}
-      className={style.SearchModal}
-      popover="auto"
-      data-stldocs-modal-open={open}
-    >
-      {open && <SearchForm />}
-    </div>
-  );
-}

package/src/search/index.tsx

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

package/src/search/indexer.ts

@@ -1,246 +0,0 @@
-import { generateRoute, Languages, parseStainlessPath, walkTree } from '../routing';
-import * as printer from './printer';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import type { IndexEntry } from './types';
-import { renderMarkdown } from '../markdown';
-
-// function sanitizeTerraformType(key: string, value: any) {
-//   return typeof value === "number" && !Number.isSafeInteger(value)
-//     ? value.toString()
-//     : value;
-// }
-
-export function getResourceNames(resourceIds: string[], topResources?: Record<string, SDKJSON.Resource>) {
-  let element: SDKJSON.Resource | undefined = undefined;
-  let resources: Record<string, SDKJSON.Resource> | undefined = topResources;
-  const resourceName = [];
-  for (const resource of resourceIds) {
-    element = resources?.[resource];
-    if (!element) break;
-    resourceName.push(element.title);
-    resources = element?.subresources;
-  }
-
-  return resourceName;
-}
-
-function chunkByLines(content: string, maxSize: number = 60000) {
-  if (Buffer.byteLength(content, 'utf8') < maxSize) return [content];
-
-  const lines = content.split('\n');
-  const chunks = [];
-
-  let currentChunk = [];
-  let currentSize = 0;
-
-  for (const line of lines) {
-    const lineSize = Buffer.byteLength(line + '\n', 'utf8');
-    if (currentSize + lineSize > maxSize) {
-      chunks.push(currentChunk.join('\n'));
-      currentChunk = [];
-      currentSize = 0;
-    }
-
-    currentChunk.push(line);
-    currentSize += lineSize;
-  }
-
-  if (currentChunk.length > 0) chunks.push(currentChunk.join('\n'));
-  return chunks;
-}
-
-export function* generateChatIndex(spec: SDKJSON.Spec) {
-  for (const [language, readme] of Object.entries(spec.readme)) {
-    const chunks = chunkByLines(readme);
-
-    for (const chunk of chunks) {
-      yield {
-        language,
-        title: 'Overview',
-        content: chunk,
-        url: `docs://BASE_PATH/${language}`,
-      };
-    }
-  }
-
-  for (const { data } of walkTree(spec)) {
-    if (data.kind !== 'http_method') continue;
-    const { title, name, stainlessPath, httpMethod, summary, description } = data;
-    const endpoint = data.endpoint.slice(httpMethod.length).trim();
-
-    for (const language of Languages) {
-      const decl = spec.decls[language]?.[stainlessPath];
-      if (!decl) continue;
-
-      const env = {
-        spec,
-        language,
-        options: {
-          includeModelProperties: true,
-        },
-      };
-
-      const content = renderMarkdown(env, data);
-      const chunks = chunkByLines(content);
-
-      for (const chunk of chunks) {
-        yield {
-          language,
-          title,
-          name,
-          endpoint,
-          httpMethod,
-          summary,
-          description,
-          stainlessPath,
-          qualified: decl['qualified'],
-          ident: decl['ident'],
-          content: chunk,
-          url: generateRoute('docs://BASE_PATH', language, stainlessPath),
-        };
-      }
-    }
-  }
-}
-
-export function* generateIndex(
-  spec: SDKJSON.Spec,
-  renderMarkdownFn?: (string?) => string | null,
-  includeTypes?: boolean,
-): Generator<IndexEntry> {
-  const parentCrumbs: Record<string, string[]> = {};
-  for (const { data } of walkTree(spec, true)) {
-    const { kind, name, title, stainlessPath } = data;
-    const common = { name, title, stainlessPath };
-
-    const parsedPath = parseStainlessPath(stainlessPath);
-    const crumbs = getResourceNames(parsedPath.resource, spec.resources);
-
-    switch (kind) {
-      case 'resource':
-        for (const language of Languages) {
-          if (!data[language]) continue;
-
-          parentCrumbs[stainlessPath] = crumbs;
-          const { Name, QualifiedName } = data[language]!;
-
-          yield {
-            kind,
-            crumbs,
-            language,
-            Name,
-            QualifiedName,
-            priority: 0,
-            ...common,
-          };
-        }
-
-        break;
-
-      case 'http_method': {
-        const { summary, endpoint, httpMethod } = data;
-        for (const language of Languages) {
-          const found = spec.decls[language]?.[stainlessPath];
-          if (!found) continue;
-
-          parentCrumbs[stainlessPath] = [...crumbs, title];
-          const qualified = found['qualified'];
-          const ident = qualified?.split('.')?.at(-1);
-
-          yield {
-            kind,
-            crumbs: [...crumbs, title],
-            ident,
-            qualified,
-            language,
-            description: renderMarkdownFn?.(data.description) ?? data.description,
-            endpoint: endpoint.slice(httpMethod.length).trim(),
-            httpMethod,
-            summary,
-            priority: 0,
-            ...common,
-          };
-        }
-
-        break;
-      }
-
-      case 'model':
-        for (const language of Languages) {
-          if (!spec.decls[language]) continue;
-
-          parentCrumbs[stainlessPath] = [...crumbs, title];
-          const schema = spec.decls[language]?.[`${stainlessPath} > (schema)`];
-          const children =
-            schema?.['children']
-              ?.map((childPath) => {
-                const child = spec.decls?.[language]?.[childPath];
-                return (
-                  child?.['ident'] ??
-                  child?.['name'] ??
-                  child?.['key'] ??
-                  child?.['type']?.['literal']?.['value'] ??
-                  child?.['type']?.['literal'] ??
-                  child?.['type']?.['value']
-                );
-              })
-              ?.filter((child) => child) ?? [];
-
-          yield {
-            kind,
-            crumbs: [...crumbs, title],
-            children,
-            language,
-            priority: 2,
-            ident: schema?.['ident'],
-            ...common,
-          };
-        }
-    }
-  }
-
-  for (const language of Languages) {
-    const decls = spec.decls?.[language];
-    if (!decls) continue;
-
-    for (const decl of Object.values<SDKJSON.LanguageDeclNodes[SDKJSON.SpecLanguage]>(decls)) {
-      switch (decl.kind) {
-        // case "TerraformDeclAttribute":
-        case 'JavaDeclProperty':
-        case 'GoDeclProperty':
-        case 'PythonDeclProperty':
-        case 'RubyDeclProperty':
-        case 'HttpDeclProperty':
-        case 'TSDeclProperty':
-          {
-            const parsedPath = parseStainlessPath(decl.stainlessPath);
-            const type = includeTypes === false ? undefined : printer.typeName(language, decl.type);
-            const name = decl['ident'] ?? decl['name'] ?? decl['key'];
-
-            const parent = parentCrumbs[parsedPath.routable];
-            // Filter out properties of non-routable response types
-            if (parent === undefined) continue;
-
-            const matches = decl.stainlessPath.matchAll(/\((property|params|param)\) ([^\s]+)/g);
-
-            const props = Array.from(matches)
-              .map((p) => p[2])
-              .filter((p) => p !== undefined);
-
-            yield {
-              kind: 'property',
-              name,
-              stainlessPath: decl.stainlessPath,
-              crumbs: [...parent, ...props],
-              docstring: renderMarkdownFn?.(decl.docstring) ?? decl.docstring,
-              type,
-              language,
-              priority: 3,
-            };
-          }
-
-          break;
-      }
-    }
-  }
-}

package/src/search/mcp.ts

@@ -1,61 +0,0 @@
-import { renderMarkdown } from '../markdown';
-import { DocsLanguage, parseStainlessPath } from '../routing';
-import { getResourceFromSpec } from '../utils';
-import { buildIndex, search } from './providers/fuse';
-import type { IndexEntry } from './types';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-
-export function consolidate(results: IndexEntry[]) {
-  const resources = new Set<string>();
-  const methods = new Set<string>();
-
-  for (const entry of results) {
-    const parsed = parseStainlessPath(entry.stainlessPath);
-    if (parsed.method) methods.add(parsed.routable);
-    else resources.add(parsed.routable);
-  }
-
-  const filtered = Array.from(methods).filter((path) => !resources.has(path.split(' >').at(0)));
-  return [...resources, ...filtered];
-}
-
-export function render(
-  spec: SDKJSON.Spec,
-  language: DocsLanguage,
-  items: IndexEntry[],
-  includeModelProperties: boolean,
-) {
-  const env = {
-    spec,
-    language,
-    options: {
-      renderNestedResources: false,
-      includeModelProperties,
-    },
-  };
-
-  const paths = consolidate(items);
-  const output = paths.map((entry) => {
-    const parsed = parseStainlessPath(entry);
-    const resource = getResourceFromSpec(parsed.resource, spec);
-    const target = parsed.method ? resource.methods[parsed.method] : resource;
-    const content = renderMarkdown(env, target);
-    return [entry, content];
-  });
-
-  return Object.fromEntries(output);
-}
-
-export function searchAndRender(
-  spec: SDKJSON.Spec,
-  language: DocsLanguage,
-  query: string,
-  limit?: number,
-  includeModelProperties: boolean = false,
-) {
-  const idx = buildIndex(spec, language);
-  const results = search(idx, query, limit).map(({ item }) => item);
-  return render(spec, language, results, includeModelProperties);
-}
-
-export { buildIndex };