@stainless-api/docs 0.1.0-beta.8 → 0.1.0-beta.80

package/plugin/cms/worker.ts

@@ -1,10 +1,11 @@
 import Worker from 'web-worker';
-import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
+import { Languages, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import type * as SDKJSON from '@stainless/sdk-json';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import fs from 'fs/promises';
 import pathutils from 'path';
+import type { VersionUserConfig } from '../loadPluginConfig';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -12,7 +13,81 @@ const __dirname = dirname(__filename);
 const workerPath = resolve(__dirname, '..', 'vendor', 'preview.worker.docs.js');
 
 type OpenAPIDocument = Record<string, any>;
-type ParsedConfig = Record<string, any>;
+export type ParsedConfig = {
+  docs:
+    | {
+        title?: string | undefined;
+        favicon?: string | undefined;
+        logo_icon?: string | undefined;
+        search?:
+          | {
+              algolia?:
+                | {
+                    app_id: string;
+                    index_name: string;
+                    search_key: string;
+                  }
+                | undefined;
+            }
+          | undefined;
+        description?: string | undefined;
+        languages?:
+          | ('node' | 'typescript' | 'python' | 'java' | 'kotlin' | 'go' | 'ruby' | 'terraform' | 'http')[]
+          | undefined;
+        snippets?:
+          | {
+              exclude_languages?: string[] | undefined;
+            }
+          | undefined;
+        show_security?: boolean | undefined;
+        show_readme?: boolean | undefined;
+        base_path?: string | undefined;
+        navigation?:
+          | {
+              menubar?:
+                | {
+                    title: string;
+                    icon?: string;
+                    variant?: string;
+                    href?: string | undefined;
+                    page?: string | undefined;
+                  }[]
+                | undefined;
+              sidebar?:
+                | {
+                    title: string;
+                    icon?: string;
+                    variant?: string;
+                    href?: string | undefined;
+                    page?: string | undefined;
+                  }[]
+                | undefined;
+            }
+          | undefined;
+        pages?: unknown;
+        resources?: unknown[] | undefined;
+      }
+    | undefined;
+  targets: Record<string, { skip?: boolean }>;
+  client_settings: {
+    opts: {
+      [x: string]: {
+        type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+        nullable: boolean;
+        description?: string | undefined;
+        example?: unknown;
+        default?: unknown;
+        read_env?: string | undefined;
+        auth?:
+          | {
+              security_scheme: string;
+              role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+            }
+          | undefined;
+      };
+    };
+  };
+};
 
 function runJob({ type, signal, data }: { type: string; signal?: AbortSignal; data: any }) {
   const stainlessWorker = new Worker(workerPath, {
@@ -22,6 +97,7 @@ function runJob({ type, signal, data }: { type: string; signal?: AbortSignal; da
 
   return new Promise<any>((resolve, reject) => {
     stainlessWorker.addEventListener('error', (e) => {
+      e.preventDefault();
       reject(e);
     });
 
@@ -85,10 +161,12 @@ export async function createSDKJSON({
   oas,
   config,
   languages,
+  version,
 }: {
   oas: OpenAPIDocument;
   config: ParsedConfig;
   languages: DocsLanguage[];
+  version: VersionUserConfig;
 }) {
   const templatePath = resolve(__dirname, '../vendor/templates');
   const readmeLoader = await Promise.all(
@@ -98,7 +176,7 @@ export async function createSDKJSON({
       try {
         const content = await fs.readFile(mdfile);
         return [language, content.toString()];
-      } catch (err) {
+      } catch {
         return [language, null];
       }
     }),
@@ -113,7 +191,7 @@ export async function createSDKJSON({
       config,
       languages,
       transform: false,
-      projectName: '',
+      projectName: version.stainlessProject,
       readmeTemplates,
     },
   });

package/plugin/components/MethodDescription.tsx

@@ -0,0 +1,54 @@
+import { MethodDescriptionProps } from '@stainless-api/docs-ui/components';
+import { useComponents } from '@stainless-api/docs-ui/contexts/use-components';
+import style from '@stainless-api/docs-ui/style';
+import { Button } from '@stainless-api/ui-primitives';
+
+function shouldCollapseDescription(description: string) {
+  const MIN_CHARS = 400;
+  const MIN_LINES = 6;
+
+  const lineCount = description.split('\n').length;
+
+  if (description.length >= MIN_CHARS) return true;
+  if (lineCount >= MIN_LINES) return true;
+
+  // Markdown structure often means longer content
+  if (/#\s/.test(description)) return true; // has headings
+  if (/```/.test(description)) return true; // has code blocks
+  if (/^\s*[-*]\s+/m.test(description)) return true; // has lists
+
+  return false;
+}
+
+export function MethodDescription({ description }: MethodDescriptionProps) {
+  const { Markdown } = useComponents();
+
+  if (description) {
+    // Attempt to determine if we should make the description collapsible initially
+    // or not. If we get this right, there will be no FOUC.
+    const collapsible = shouldCollapseDescription(description);
+
+    return (
+      <div className="stl-method-description">
+        <div
+          className={style.MethodDescription}
+          data-stldocs-property-group="method-description"
+          data-collapsed={collapsible ? 'true' : 'false'}
+        >
+          <Markdown content={description} />
+        </div>
+        <div className="stl-method-description-overflow-wrapper">
+          <Button
+            type="button"
+            data-method-description-toggle
+            size="sm"
+            variant="ghost"
+            hidden={!collapsible}
+          >
+            Show more
+          </Button>
+        </div>
+      </div>
+    );
+  }
+}

package/plugin/components/RequestBuilder/ParamEditor.tsx

@@ -0,0 +1,55 @@
+import { useMemo } from 'react';
+import { Button } from '@stainless-api/ui-primitives';
+import type { Param } from './spec-helpers';
+import { InfoIcon } from 'lucide-react';
+import { Input } from '@stainless-api/docs-ui/components';
+
+function setHighlight(stainlessPath: string, highlighted: boolean) {
+  const ele = document.getElementById(stainlessPath);
+  if (!ele) return;
+  ele.classList.toggle('stldocs-property-highlighted', highlighted);
+  if (highlighted) {
+    if (location.hash) {
+      const prevScroll = document.documentElement.scrollTop;
+      location.hash = '';
+      document.documentElement.scrollTop = prevScroll;
+    }
+    if (document.body.clientWidth >= 1280) {
+      ele.scrollIntoView({
+        behavior: 'smooth',
+      });
+    }
+  }
+}
+
+function htmlToText(html: string) {
+  const template = document.createElement('template');
+  template.innerHTML = html;
+  return template.content.textContent;
+}
+
+export function ParamEditor({ param }: { param: Param }) {
+  const type = useMemo(() => htmlToText(param.type), [param.type]);
+
+  return (
+    <label className="request-builder-param">
+      <Button
+        className="request-builder-param-info-button"
+        variant="ghost"
+        href={`#${encodeURIComponent(param.stainlessPath)}`}
+      >
+        <Button.Icon icon={InfoIcon} size={16} />
+      </Button>
+
+      <span className="request-builder-param-label">{param.key}</span>
+      <span className="request-builder-param-colon">:</span>
+
+      <Input
+        className="request-builder-param-value"
+        onFocus={() => setHighlight(param.stainlessPath, true)}
+        onBlur={() => setHighlight(param.stainlessPath, false)}
+        placeholder={type}
+      />
+    </label>
+  );
+}

package/plugin/components/RequestBuilder/SnippetStainlessIsland.tsx

@@ -0,0 +1,107 @@
+import { useState, useMemo, useEffect, useId, useSyncExternalStore, Activity, Fragment } from 'react';
+import { createPortal } from 'react-dom';
+import { Button } from '@stainless-api/ui-primitives';
+import { PlayIcon, RotateCcw } from 'lucide-react';
+import { SnippetStainlessIslandPropsSchema } from './props';
+import { ParamEditor } from './ParamEditor';
+import './styles.css';
+
+function useRequiredChild<T extends Element = Element>(
+  parent: Element | null,
+  selector: string,
+): React.RefObject<T> {
+  const elementRef = useMemo(() => {
+    const el = parent?.querySelector<T>(selector);
+    return el ? { current: el } : null;
+  }, [parent, selector]);
+  if (!elementRef) throw new Error(`Required child not found: ${selector}`);
+  return elementRef;
+}
+
+function useSetVisibility(elementRef: React.RefObject<HTMLElement>, visible: boolean) {
+  useEffect(() => {
+    elementRef.current.style.display = visible ? '' : 'none';
+  }, [elementRef, visible]);
+}
+
+export default function SnippetStainlessIsland({ parent }: { parent: HTMLElement }) {
+  const [expanded, setExpanded] = useState(false);
+
+  const trigger = useRequiredChild<HTMLButtonElement>(parent, '.try-it-footer .try-it-button');
+  const codeContainer = useRequiredChild<HTMLElement>(parent, '.stldocs-snippet-code');
+  const exampleContainer = useRequiredChild<HTMLElement>(parent, '.stldocs-snippet-multi-response');
+  useSetVisibility(codeContainer, !expanded);
+  useSetVisibility(exampleContainer, !expanded);
+  useSetVisibility(trigger, !expanded);
+  // Attach click handler to trigger
+  useEffect(() => {
+    if (!trigger.current) return;
+    const ac = new AbortController();
+    trigger.current.addEventListener('click', () => setExpanded(true), { signal: ac.signal });
+    return () => ac.abort();
+  });
+
+  const requestBuilderContainer = useRequiredChild<HTMLElement>(parent, '.request-builder-container');
+  const requestBuilderFooter = useRequiredChild<HTMLElement>(parent, '.request-builder-footer');
+  const requestBuilderResponse = useRequiredChild<HTMLElement>(parent, '.request-builder-response');
+  const requestBuilderProps = useRequiredChild<HTMLTemplateElement>(parent, '.request-builder-props').current;
+  const serializedProps = useSyncExternalStore(
+    (cb) => {
+      const mutationObserver = new MutationObserver(() => cb());
+      mutationObserver.observe(requestBuilderProps, { childList: true });
+      return () => mutationObserver.disconnect();
+    },
+    () => requestBuilderProps.content.textContent,
+  );
+  const deserializedProps = SnippetStainlessIslandPropsSchema.parse(JSON.parse(serializedProps));
+  const groupedParams = Map.groupBy(deserializedProps.params, (p) => p.location);
+
+  const formId = `request-builder-form-${useId()}`;
+
+  return (
+    <>
+      {createPortal(
+        <Activity mode={expanded ? 'visible' : 'hidden'}>
+          <form
+            onSubmit={(e) => {
+              alert('TODO: Submit button clicked');
+              e.preventDefault();
+            }}
+            id={formId}
+          >
+            {[...groupedParams.entries()].map(([location, params]) => (
+              <Fragment key={location}>
+                <h4>{location} parameters</h4>
+                {params.map((e) => (
+                  <ParamEditor param={e} key={e.location + e.key} />
+                ))}
+              </Fragment>
+            ))}
+          </form>
+        </Activity>,
+        requestBuilderContainer.current,
+      )}
+
+      {createPortal(
+        <Activity mode={expanded ? 'visible' : 'hidden'}>
+          <Button variant="ghost" border={true} onClick={() => setExpanded(false)}>
+            <Button.Icon icon={RotateCcw} />
+          </Button>
+
+          <Button variant="success" className="send-button" type="submit" form={formId}>
+            <Button.Label>Send</Button.Label>
+            <Button.Icon icon={PlayIcon} />
+          </Button>
+        </Activity>,
+        requestBuilderFooter.current,
+      )}
+
+      {createPortal(
+        <Activity mode={expanded ? 'visible' : 'hidden'}>
+          <div>{/* TODO */}</div>
+        </Activity>,
+        requestBuilderResponse.current,
+      )}
+    </>
+  );
+}

package/plugin/components/RequestBuilder/index.tsx

@@ -0,0 +1,31 @@
+import { ReactNode } from 'react';
+import * as SDKJSON from '@stainless/sdk-json';
+import { useSpec } from '@stainless-api/docs-ui/contexts';
+import { extractParams } from './spec-helpers';
+import type { SnippetStainlessIslandProps } from './props';
+
+/** Load and process the spec on the server side to avoid inflating client bundle */
+export function RequestBuilder({
+  className,
+  children,
+  method,
+}: {
+  className: string;
+  children: ReactNode;
+  method: SDKJSON.Method;
+}) {
+  const spec = useSpec();
+  if (!spec) throw new Error('Spec is required for RequestBuilder');
+  const params = spec && extractParams(spec, method);
+  const [httpMethod, path] = method.endpoint.split(' ') as [string, string];
+
+  return (
+    <stl-island component="SnippetStainlessIsland" className={className}>
+      {/* Pass state down to the client component. TODO: we need a better solution for this */}
+      <template className="request-builder-props">
+        {JSON.stringify({ method: httpMethod, path, params } satisfies SnippetStainlessIslandProps)}
+      </template>
+      {children}
+    </stl-island>
+  );
+}

package/plugin/components/RequestBuilder/props.ts

@@ -0,0 +1,9 @@
+import z from 'zod';
+import { ParamSchema } from './spec-helpers';
+
+export const SnippetStainlessIslandPropsSchema = z.object({
+  method: z.string(),
+  path: z.string(),
+  params: z.array(ParamSchema),
+});
+export type SnippetStainlessIslandProps = z.infer<typeof SnippetStainlessIslandPropsSchema>;

package/plugin/components/RequestBuilder/spec-helpers.ts

@@ -0,0 +1,50 @@
+import type * as SDKJSON from '@stainless/sdk-json';
+import { printer } from '@stainless-api/docs-ui/markdown';
+import z from 'zod';
+
+export const ParamSchema = z.object({
+  stainlessPath: z.string(),
+  location: z.string(),
+  key: z.string(),
+  type: z.string(),
+});
+
+export type Param = z.infer<typeof ParamSchema>;
+
+export function extractParams(spec: SDKJSON.Spec | undefined, method: SDKJSON.Method): Param[] {
+  const httpDecls = spec?.decls?.http;
+  if (!httpDecls) throw new Error('expected http language to be present in SDKJSON');
+  const decl = httpDecls?.[method.stainlessPath];
+  if (decl?.kind !== 'HttpDeclFunction') {
+    throw new Error(
+      'expected HttpDeclFunction at stainlessPath "' + method.stainlessPath + '", got ' + decl?.kind,
+    );
+  }
+  const bodyTypes = Object.keys(decl.bodyParamsChildren ?? {});
+  if (bodyTypes.length > 0 && !bodyTypes.includes('application/json')) {
+    throw new Error('TODO: support non-json body params');
+  }
+  const bodyParams = decl.bodyParamsChildren?.['application/json'];
+  const params = [
+    ...Object.entries(decl.paramsChildren ?? {}).map(([location, children]) => ({ location, children })),
+    ...(bodyParams ? [{ location: 'body', children: bodyParams }] : []),
+  ]
+    .filter((e) => e.children.length)
+    .flatMap(({ location, children }) =>
+      children.map((child) => {
+        const resolved = httpDecls[child];
+        if (resolved?.kind !== 'HttpDeclProperty') {
+          throw new Error(
+            'expected HttpDeclProperty at stainlessPath "' + child + '", got ' + resolved?.kind,
+          );
+        }
+        return {
+          stainlessPath: resolved.stainlessPath,
+          location,
+          key: resolved.key,
+          type: (resolved.optional ? 'optional ' : '') + printer.type('http', resolved.type),
+        };
+      }),
+    );
+  return params;
+}

package/plugin/components/RequestBuilder/styles.css

@@ -0,0 +1,67 @@
+.request-builder-container form {
+  display: grid;
+
+  /* prettier-ignore */
+  grid-template-columns: /*info button*/max-content /*label*/max-content /*colon*/max-content /*input*/1fr;
+  font-family: var(--stl-typography-font);
+  font-size: var(--stl-typography-text-body-sm);
+  color: var(--stl-color-foreground);
+
+  & > * {
+    padding-inline-start: 12px;
+    padding-inline-end: 8px;
+  }
+
+  & > h4 {
+    grid-column: 1 / -1;
+    text-transform: capitalize;
+    font-size: var(--stl-typography-scale-sm);
+    margin-top: 0;
+    margin-bottom: 0.25em;
+    color: var(--stl-color-foreground-muted);
+    padding-top: 0.75rem;
+
+    &:not(:first-child) {
+      border-top: 1px solid var(--stl-color-border);
+    }
+  }
+
+  .request-builder-param {
+    grid-column: 1 / -1;
+    display: grid;
+    grid-template-columns: subgrid;
+    align-items: center;
+    column-gap: 0.5rem;
+    padding-block: 0.35rem;
+
+    .request-builder-param-info-button {
+      color: var(--stl-color-foreground-muted);
+      margin-inline: -4px;
+      padding: 0;
+    }
+    .request-builder-param-label {
+      font-family: var(--stl-typography-font-mono);
+    }
+    .request-builder-param-colon {
+      font-family: var(--stl-typography-font-mono);
+      color: var(--stl-color-foreground-muted);
+    }
+    /* TODO: new input component that is better stylable */
+    .request-builder-param-value {
+      input {
+        margin: 6px 8px;
+        font-size: inherit;
+      }
+    }
+
+    &:has(+ h4),
+    &:last-child {
+      padding-bottom: 0.75rem;
+    }
+  }
+}
+
+.request-builder-footer .stl-ui-button--ghost .stl-ui-button__icon {
+  color: var(--stl-color-foreground);
+  opacity: var(--stl-opacity-level-040);
+}

package/plugin/components/SDKSelect.astro

@@ -1,6 +1,6 @@
 ---
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import { parseRoute } from '@stainless-api/docs-ui/src/routing';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
+import { parseRoute } from '@stainless-api/docs-ui/routing';
 import { cmsClient } from '../cms/client';
 import { BASE_PATH, DEFAULT_LANGUAGE, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
 import { Languages } from '../languages';
@@ -53,100 +53,20 @@ const readmeSlug = language === 'http' ? BASE_PATH : `${BASE_PATH}/${language}`;
   )
 }
 
-<style>
-  @layer starlight.core {
-    label {
-      --sl-label-icon-size: 16px;
-      --sl-caret-size: 1.25rem;
-      --sl-inline-padding: 0.5rem;
-      position: relative;
-      display: flex;
-      align-items: center;
-      gap: 0.25rem;
-      color: var(--sl-color-gray-1);
-    }
-
-    label:hover {
-      color: var(--sl-color-gray-2);
-    }
-
-    .icon {
-      position: absolute;
-      top: 50%;
-      transform: translateY(-50%);
-      pointer-events: none;
-      width: 16px;
-    }
-
-    select {
-      padding-block: 0.3rem;
-      padding-inline: calc(var(--sl-label-icon-size) + var(--sl-inline-padding) + 0.5rem)
-        calc(var(--sl-caret-size) + var(--sl-inline-padding) + 0.25rem);
-      margin-inline: calc(var(--sl-inline-padding) * -1);
-      width: calc(var(--sl-select-width) + var(--sl-inline-padding) * 2);
-      text-overflow: ellipsis;
-      color: inherit;
-      cursor: pointer;
-      appearance: none;
-      font-weight: 600;
-      text-transform: capitalize;
-    }
-
-    select:active {
-      font-weight: inherit;
-      /* font-family: sans-serif;
-      font-weight: 400; */
-    }
-
-    option {
-      background-color: var(--sl-color-bg-nav);
-      color: var(--sl-color-gray-1);
-    }
-
-    @media (min-width: 50rem) {
-      select {
-        font-size: var(--sl-text-sm);
-      }
-    }
-  }
-
-  @layer starlight.components {
-    .label-icon {
-      font-size: var(--sl-label-icon-size);
-      inset-inline-start: 0;
-    }
-
-    .caret {
-      font-size: var(--sl-caret-size);
-      inset-inline-end: 0;
-    }
-  }
-
-  .custom-select-wrapper {
-    --sl-inline-padding: 0.5rem;
-    position: relative;
-    display: inline-block;
-    /* These match the padding on the sidebar menu */
-    padding-left: var(--sl-inline-padding);
-    padding-right: var(--sl-inline-padding);
-
-    .icon.http path {
-      fill: var(--sl-color-text);
-    }
-  }
-</style>
 <script>
   import { navigate } from 'astro:transitions/client';
   import { updateSelectedLanguage } from '../languages';
-  import { initDropdown } from '@stainless-api/docs-ui/src/components/scripts/dropdown';
+  import { initDropdown } from '@stainless-api/docs/components/scripts';
   import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
   import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
 
   document.addEventListener(getPageLoadEvent(), () => {
+    const sdkSelect = document.getElementById('sidebar-sdk-select');
+    if (!sdkSelect) return;
     initDropdown({
-      dropdownId: 'sidebar-sdk-select',
+      root: sdkSelect,
       onSelect: (value) => {
-        const originalLanguage = document.getElementById('sidebar-sdk-select')?.dataset.currentValue;
+        const originalLanguage = sdkSelect.dataset.currentValue;
         navigate(updateSelectedLanguage(BASE_PATH, originalLanguage, value));
       },
     });