@stainless-api/playgrounds 0.0.1-beta.0

package/src/codemirror/react.tsx

@@ -0,0 +1,615 @@
+import { useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type Ref } from 'react';
+import { Braces, ChevronsUpDownIcon, CopyIcon, KeyRound, Play, Square } from 'lucide-react';
+import type { EditorView } from '@codemirror/view';
+import type * as lsp from 'vscode-languageserver-protocol';
+import type { Diagnostic } from '@codemirror/lint';
+import type { EditorState, Extension, Text, Transaction } from '@codemirror/state';
+import type { Transport } from '@codemirror/lsp-client';
+import type { PlaygroundLanguage } from '../create.tsx';
+import style from '@stainless-api/docs-ui/style';
+import { LogsContext } from '../logs-context.ts';
+import { Logs, type Logger, type Part, type StatePart } from '../Logs.tsx';
+import type { Completion } from '@codemirror/autocomplete';
+import { Button, Dropdown } from '@stainless-api/ui-primitives';
+import { PlaygroundIcon } from '../icon.tsx';
+import { initDropdown } from '@stainless-api/ui-primitives/scripts';
+// @ts-expect-error TODO: make independent from stl-starlight
+import { navigate } from 'astro:transitions/client';
+// @ts-expect-error TODO: make independent from stl-starlight
+import { updateSelectedLanguage } from 'virtual:stl-playground/unstable-update-language';
+// @ts-expect-error TODO: make independent from stl-starlight
+import { BASE_PATH } from 'virtual:stl-starlight-virtual-module';
+import authData from 'virtual:stl-playground/auth.json';
+import { Panel } from '../Panel.tsx';
+import { PlaygroundPanelWrapper } from '../PlaygroundPanelWrapper.tsx';
+import { MaskedInput } from '@stainless-api/docs-ui/components/MaskedInput';
+import useStorage from '../use-storage.ts';
+
+let codeMirrorPromise: Promise<typeof import('./deps.ts')>;
+function loadCodeMirror(): Promise<typeof import('./deps.ts')> {
+  return codeMirrorPromise || (codeMirrorPromise = import('./deps.ts'));
+}
+
+function fromPosition(doc: Text, pos: lsp.Position): number {
+  const line = doc.line(pos.line + 1);
+  return line.from + pos.character;
+}
+
+function hydrateDetail(completion: Completion): Completion & { sortText?: string } {
+  if (completion.detail?.startsWith('\0{')) {
+    const extra = JSON.parse(completion.detail.slice(1));
+    completion.detail = undefined;
+    Object.assign(completion, extra);
+  }
+  return completion;
+}
+
+async function initCodeMirror({
+  signal,
+  container,
+  extensions,
+  fileName,
+  doc,
+  transport,
+}: {
+  signal: AbortSignal;
+  container: HTMLDivElement;
+  transport?: Transport;
+  fileName: string;
+  extensions: Extension[];
+  doc: string;
+}): Promise<{ editor: EditorView; fixGutters(): void }> {
+  const {
+    view: {
+      ViewUpdate,
+      EditorView,
+      keymap,
+      highlightSpecialChars,
+      drawSelection,
+      dropCursor,
+      rectangularSelection,
+      crosshairCursor,
+      lineNumbers,
+    },
+    language: { indentOnInput, bracketMatching, foldGutter, indentUnit },
+    commands: { history },
+    search: { highlightSelectionMatches },
+    autocomplete: { autocompletion, closeBrackets },
+    lint: { setDiagnostics },
+    state: { EditorState, Compartment },
+    lsp: { LSPClient, languageServerSupport },
+    vscodeKeymap,
+    createLSPClient,
+    shikiHighlighter,
+  } = await loadCodeMirror();
+
+  if (signal.aborted) throw new Error('unmounted');
+
+  if (transport) {
+    const client = await createLSPClient(
+      LSPClient,
+      {
+        rootUri: 'file:///play/',
+        onDiagnostics: (lspDiagnostics) => {
+          const diagnostics = lspDiagnostics.map((lsp): Diagnostic => {
+            return {
+              from: fromPosition(editor.state.doc, lsp.range.start),
+              to: fromPosition(editor.state.doc, lsp.range.end),
+              message: lsp.message,
+              severity:
+                lsp.severity === 4
+                  ? 'hint'
+                  : lsp.severity === 3
+                    ? 'info'
+                    : lsp.severity === 2
+                      ? 'warning'
+                      : 'error',
+            };
+          });
+          editor.dispatch(setDiagnostics(editor.state, diagnostics));
+        },
+      },
+      transport,
+    );
+    signal.addEventListener('abort', () => client.disconnect());
+    extensions.push(languageServerSupport(client, 'file:///play/' + fileName));
+  }
+
+  const editorTheme = new Compartment();
+  const getTheme = (): Extension[] => {
+    const isDark = document.documentElement.dataset.theme === 'dark';
+    return [EditorView.theme({}, { dark: isDark })];
+  };
+  const editor = new EditorView({
+    doc,
+    parent: container,
+    extensions: [
+      lineNumbers(),
+      foldGutter(),
+      highlightSpecialChars(),
+      history(),
+      drawSelection(),
+      dropCursor(),
+      EditorState.allowMultipleSelections.of(true),
+      indentOnInput(),
+      bracketMatching(),
+      closeBrackets(),
+      autocompletion({
+        compareCompletions(a, b) {
+          return (hydrateDetail(a).sortText ?? a.label).localeCompare(hydrateDetail(b).sortText ?? b.label);
+        },
+        optionClass(completion) {
+          hydrateDetail(completion);
+          return '';
+        },
+      }),
+      rectangularSelection(),
+      crosshairCursor(),
+      highlightSelectionMatches(),
+      keymap.of(vscodeKeymap),
+      shikiHighlighter,
+      editorTheme.of(getTheme()),
+      indentUnit.of(fileName.endsWith('.py') ? '    ' : '  '),
+      ...extensions,
+    ],
+  });
+  const observer = new MutationObserver(() => {
+    editor.dispatch({
+      effects: editorTheme.reconfigure(getTheme()),
+    });
+  });
+  observer.observe(document.documentElement, {
+    attributeFilter: ['data-theme'],
+  });
+  signal.addEventListener('abort', () => {
+    editor.destroy();
+    observer.disconnect();
+  });
+  return {
+    editor,
+    fixGutters() {
+      const update = (
+        ViewUpdate as unknown as {
+          create(view: EditorView, state: EditorState, _: []): Transaction & { flags: number };
+        }
+      ).create(editor, editor.state, []);
+      update.flags = update.flags | 4; /* UpdateFlag.Viewport */
+      editor.dispatch(update);
+    },
+  };
+}
+
+type State =
+  | { state: 'loading' }
+  | { state: 'error'; error: unknown }
+  | {
+      state: 'ready';
+      view: EditorView;
+      fixGutters(): void;
+      run: (signal: AbortSignal) => Promise<void>;
+      format(): Promise<void>;
+      setEnv(vars: Record<string, string>): Promise<void>;
+    };
+
+export interface Language {
+  transport?: Transport;
+  fileName: string;
+  extensions: Extension[];
+  doc: string;
+  setLogger: (s: Logger) => void;
+  freeLogHandle(handle: string): void;
+  expandLogHandle(handle: string): Promise<Part[]>;
+  run: (code: string, signal: AbortSignal) => Promise<void>;
+  format: (code: string) => Promise<string | undefined>;
+  setEnv(vars: Record<string, string>): Promise<void>;
+}
+
+const useCodeMirror = (
+  initLanguage: (arg: { signal: AbortSignal }) => Promise<Language>,
+): {
+  containerRef: Ref<HTMLDivElement>;
+} & State => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [state, setState] = useState<State>({ state: 'loading' });
+  const logsSignal = useContext(LogsContext)!;
+  useEffect(() => {
+    const controller = new AbortController();
+    let run: Language['run'];
+    let format: Language['format'];
+    let setEnv: Language['setEnv'];
+    (async () => {
+      const {
+        transport,
+        fileName,
+        extensions,
+        doc,
+        run: run_,
+        format: format_,
+        setEnv: setEnv_,
+        setLogger,
+        freeLogHandle,
+        expandLogHandle,
+      } = await initLanguage({
+        signal: controller.signal,
+      });
+      setEnv = setEnv_;
+      run = run_;
+      format = format_;
+      if (controller.signal.aborted) throw new Error('unmounted');
+      setLogger((log) => {
+        if (log.type === 'clear') {
+          logsSignal.value = [];
+        } else {
+          const mapPart = (part: Part): StatePart => ({
+            css: part.css,
+            value: typeof part.value === 'string' ? part.value : part.value.map(mapPart),
+            handle:
+              part.expandHandle === undefined
+                ? undefined
+                : {
+                    async expand() {
+                      const e = await expandLogHandle(part.expandHandle!);
+                      return e.map(mapPart);
+                    },
+                    free() {
+                      freeLogHandle(part.expandHandle!);
+                    },
+                    id: part.id,
+                  },
+            lowPriority: part.lowPriority,
+          });
+          logsSignal.value = [
+            ...logsSignal.value,
+            { type: log.type, parts: log.parts.map((e) => (typeof e === 'string' ? e : mapPart(e))) },
+          ];
+        }
+      });
+      return await initCodeMirror({
+        extensions,
+        transport,
+        fileName,
+        container: containerRef.current!,
+        signal: controller.signal,
+        doc,
+      });
+    })().then(
+      ({ editor: view, fixGutters }) => {
+        setState({
+          state: 'ready',
+          view,
+          fixGutters,
+          run(signal) {
+            return run(view.state.doc.toString(), signal);
+          },
+          setEnv,
+          async format() {
+            const newDoc = await format(view.state.doc.toString());
+            if (newDoc !== undefined) {
+              view.dispatch({
+                changes: {
+                  from: 0,
+                  to: view.state.doc.length,
+                  insert: newDoc,
+                },
+              });
+            }
+          },
+        });
+      },
+      (error) => {
+        if (!controller.signal.aborted) {
+          console.error(error);
+          setState({ state: 'error', error });
+        }
+      },
+    );
+    return () => {
+      controller.abort();
+    };
+  }, []);
+  return { containerRef, ...state };
+};
+
+const circleAlertIcon = `<circle cx="12" cy="12" r="10"/><line x1="12" x2="12" y1="8" y2="12"/><line x1="12" x2="12.01" y1="16" y2="16"/>`;
+const checkIcon = `<path d="M20 6 9 17l-5-5"/>`;
+function DOMNode({ node }: { node: Node }) {
+  const wrap = useRef<HTMLDivElement>(null);
+
+  useLayoutEffect(() => {
+    wrap.current!.replaceChildren(node);
+  }, [node]);
+
+  return <div style={{ display: 'contents' }} ref={wrap} />;
+}
+function prefixIds(root: Element | DocumentFragment, idPrefix: string) {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, null);
+
+  let node;
+  while ((node = walker.nextNode() as Element | null)) {
+    if (node.id) {
+      node.id = idPrefix + node.id;
+    }
+    if (node.hasAttribute('aria-labelledby')) {
+      node.setAttribute('aria-labelledby', idPrefix + node.getAttribute('aria-labelledby'));
+    }
+    for (const attr of node.getAttributeNames()) {
+      node.setAttribute(attr, node.getAttribute(attr)!.replaceAll('url(#', 'url(#' + idPrefix));
+    }
+
+    if (node instanceof HTMLTemplateElement && node.content) {
+      prefixIds(node.content, idPrefix);
+    }
+  }
+}
+export const Editor = ({
+  lang,
+  doc,
+  container,
+  onLoad,
+  unmount,
+}: {
+  lang: PlaygroundLanguage;
+  doc: string;
+  container: HTMLElement;
+  onLoad: (onShow: () => void) => void;
+  unmount: () => void;
+}) => {
+  const titleNode = useMemo(
+    () => container.querySelector('.stldocs-snippet-request-title-method')!.cloneNode(true),
+    [container],
+  );
+  const idPrefix = useId();
+  const menuNode = useMemo(() => {
+    const clone = container
+      .querySelector('.stldocs-snippet-request-title-content')!
+      .cloneNode(true) as HTMLElement;
+    prefixIds(clone, idPrefix);
+    initDropdown({
+      root: clone.querySelector('#' + idPrefix + 'stldocs-snippet-select')!,
+      onSelect: (value) => {
+        const originalLanguage = document.getElementById(idPrefix + 'stldocs-snippet-select')?.dataset
+          .currentValue;
+        const path: string = updateSelectedLanguage(BASE_PATH, originalLanguage, value);
+        navigate(path.replace(/(\?.+)?($|#)/, (_, str, end) => (str ? str + '&play' : '?play') + end));
+      },
+    });
+    return clone;
+  }, [container]);
+  const editor = useCodeMirror(async ({ signal }) => {
+    let _never: never;
+    void _never!;
+    switch (lang) {
+      case 'python': {
+        const { createPyright } = await import('./python');
+        if (signal.aborted) throw new Error('unmounted');
+        return await createPyright(signal, doc);
+      }
+      case 'typescript': {
+        const { createTypescript } = await import('./typescript');
+        if (signal.aborted) throw new Error('unmounted');
+        return await createTypescript(signal, doc);
+      }
+      case 'http': {
+        const { createCurl } = await import('./curl');
+        if (signal.aborted) throw new Error('unmounted');
+        return await createCurl(signal, doc);
+      }
+      default:
+        throw (_never = lang);
+    }
+  });
+  const logs = useContext(LogsContext);
+  useEffect(() => {
+    if (editor.state !== 'loading') {
+      onLoad(editor.state === 'ready' ? () => editor.fixGutters() : () => {});
+    }
+  }, [editor.state]);
+  const [controller, setController] = useState<AbortController | null>(null);
+  return (
+    <div className="stldocs-snippet stl-snippet-non-collapsible stldocs-snippet-playground">
+      <div className="stldocs-snippet-request">
+        <div className="stldocs-snippet-request-title">
+          <DOMNode node={titleNode} />
+          <DOMNode node={menuNode} />
+          <Button
+            variant="outline"
+            onClick={async (e) => {
+              if (editor.state !== 'ready') return;
+              const copyButton = e.currentTarget;
+              if (copyButton.dataset.__stldocsCopyTimeout) return;
+              const iconElement = copyButton.querySelector('.stldocs-icon') as SVGElement;
+              const originalIcon = iconElement.innerHTML;
+              try {
+                await navigator.clipboard.writeText(editor.view.state.doc.toString());
+                iconElement.innerHTML = checkIcon;
+              } catch {
+                iconElement.innerHTML = circleAlertIcon;
+              }
+              copyButton.dataset.__stldocsCopyTimeout =
+                setTimeout(() => {
+                  copyButton.dataset.__stldocsCopyTimeout = '';
+                  iconElement.innerHTML = originalIcon;
+                }, 1000) + '';
+            }}
+            title={'Copy Code'}
+          >
+            <CopyIcon size={16} className={style.Icon} />
+          </Button>
+          <Button
+            variant="accent-muted"
+            border
+            title="Back to snippet"
+            onClick={() => {
+              unmount();
+            }}
+          >
+            <PlaygroundIcon />
+          </Button>
+        </div>
+        <div className="playground-editor-wrap">
+          {editor.state === 'error' && (
+            <pre className="playground-editor-load-error">Failed to load editor:{'\n' + editor.error}</pre>
+          )}
+          <div
+            className="playground-editor-container"
+            ref={editor.containerRef}
+            hidden={editor.state !== 'ready'}
+          />
+        </div>
+        <div className="playground-footer">
+          {lang !== 'http' && (
+            <Button
+              variant="outline"
+              onClick={async (e) => {
+                if (editor.state !== 'ready') return;
+                const button = e.currentTarget;
+                if (button.dataset.__stldocsFormatTimeout) return;
+                if (button.getAttribute('aria-disabled') === 'true') return;
+                const iconElement = button.querySelector('.stldocs-icon') as SVGElement;
+                const originalIcon = iconElement.innerHTML;
+                // use aria-disabled, not disabled, to avoid losing focus
+                button.setAttribute('aria-disabled', 'true');
+                button.setAttribute('aria-label', 'Formatting...');
+                button.classList.add('stl-ui-button--loading');
+                try {
+                  await editor.format();
+                  iconElement.innerHTML = checkIcon;
+                } catch {
+                  iconElement.innerHTML = circleAlertIcon;
+                }
+                button.dataset.__stldocsFormatTimeout =
+                  setTimeout(() => {
+                    button.dataset.__stldocsFormatTimeout = '';
+                    iconElement.innerHTML = originalIcon;
+                  }, 1000) + '';
+                button.removeAttribute('aria-disabled');
+                button.removeAttribute('aria-label');
+                button.classList.remove('stl-ui-button--loading');
+              }}
+              title={'Format Code'}
+              aria-label={'Format Code'}
+            >
+              <Braces size={16} className={style.Icon} />
+            </Button>
+          )}
+          <span className="playground-spacer" />
+          <Button
+            variant="accent"
+            onClick={async () => {
+              if (controller) {
+                controller.abort();
+                return;
+              }
+              if (editor.state !== 'ready') return;
+              try {
+                const controller = new AbortController();
+                setController(controller);
+                await editor.run(controller.signal);
+              } catch (e) {
+                logs!.value = [...logs!.value, { type: 'error', parts: ['Uncaught ' + e] }];
+              } finally {
+                setController(null);
+              }
+            }}
+            style={{ minWidth: '6em' }}
+          >
+            {controller ? (
+              <>
+                Stop <Square size={16} className={style.Icon} style={{ marginLeft: '0.5em' }} />
+              </>
+            ) : (
+              <>
+                Run <Play size={16} className={style.Icon} style={{ marginLeft: '0.5em' }} />
+              </>
+            )}
+          </Button>
+        </div>
+      </div>
+      <PlaygroundPanelWrapper>
+        <Auth setEnv={editor.state === 'ready' ? editor.setEnv : undefined} />
+        <Logs />
+      </PlaygroundPanelWrapper>
+    </div>
+  );
+};
+
+function Auth(props: { setEnv?: (vars: Record<string, string>) => Promise<void> }) {
+  const [env, setEnv] = useStorage<Record<string, string>>(sessionStorage, 'stl-playground-env', {});
+  const id = useId();
+  const [selected, setSelected] = useState(authData![0]!.name);
+  const current = authData!.find((e) => e.name === selected)!;
+  useEffect(() => {
+    props.setEnv?.(env);
+  }, [props.setEnv, env, current]);
+  return (
+    <Panel title="Authentication" icon={KeyRound}>
+      <div className="playground-auth-panel playground-panel-content">
+        {authData!.length > 1 && (
+          <>
+            <label htmlFor={id + '-trigger'}>Method</label>
+            <div>
+              <Dropdown
+                id={id}
+                data-current-value={selected}
+                className={''}
+                ref={(root) => {
+                  initDropdown({
+                    root,
+                    onSelect(value) {
+                      setSelected(value);
+                    },
+                  });
+                }}
+              >
+                <Dropdown.Trigger
+                  className="dropdown-toggle"
+                  type="button"
+                  id={id + '-trigger'}
+                  aria-expanded="false"
+                >
+                  <Dropdown.TriggerSelectedItem>
+                    <span>{current.title}</span>
+                  </Dropdown.TriggerSelectedItem>
+                  <Dropdown.TriggerIcon>
+                    <ChevronsUpDownIcon size={16} />
+                  </Dropdown.TriggerIcon>
+                </Dropdown.Trigger>
+                <Dropdown.Menu aria-labelledby={id + '-trigger'}>
+                  {authData!.map((item) => (
+                    <Dropdown.MenuItem key={item.name} value={item.name} isSelected={item.name === selected}>
+                      <div>{item.title}</div>
+                    </Dropdown.MenuItem>
+                  ))}
+                </Dropdown.Menu>
+              </Dropdown>
+            </div>
+          </>
+        )}
+        {...current.opts
+          .filter((e) => e.read_env)
+          .map((e, i) => {
+            return (
+              <>
+                {(i !== 0 || authData!.length > 1) && <hr />}
+                <label htmlFor={id + '-var-' + i}>
+                  <code>{e.read_env} =</code>
+                </label>
+                <MaskedInput
+                  type="text"
+                  key={e.name}
+                  defaultValue={env[e.read_env!]}
+                  onInput={(evt) => {
+                    const input = (evt.target as HTMLElement).closest('input') as HTMLInputElement;
+                    setEnv({
+                      ...env,
+                      [e.read_env!]: input.value,
+                    });
+                  }}
+                />
+              </>
+            );
+          })}
+      </div>
+    </Panel>
+  );
+}

package/src/codemirror/sanitize-html.ts

@@ -0,0 +1,12 @@
+import DOMPurify from 'dompurify';
+
+export function sanitizeHTML(html: string) {
+  const dom = DOMPurify.sanitize(html, {
+    RETURN_DOM: true,
+  }) as HTMLBodyElement;
+  for (const link of dom.querySelectorAll('a, area')) {
+    link.setAttribute('target', '_blank');
+    link.setAttribute('rel', 'noopener');
+  }
+  return dom.innerHTML;
+}

package/src/codemirror/shiki.ts

@@ -0,0 +1,65 @@
+import { language } from '@codemirror/language';
+import { Prec, RangeSetBuilder } from '@codemirror/state';
+import {
+  Decoration,
+  type DecorationSet,
+  type EditorView,
+  ViewPlugin,
+  type ViewUpdate,
+} from '@codemirror/view';
+import { SupportedLanguageSyntaxes } from '@stainless-api/docs-ui/routing';
+import { createHighlighter } from 'shiki';
+// @ts-expect-error TODO: make independent from stl-starlight
+import { HIGHLIGHT_THEMES } from 'virtual:stl-starlight-virtual-module';
+export const highlighter = await createHighlighter({
+  themes: [HIGHLIGHT_THEMES?.dark ?? 'github-dark', HIGHLIGHT_THEMES?.light ?? 'github-light'],
+  langs: SupportedLanguageSyntaxes,
+});
+const span = document.createElement('span');
+class TreeHighlighter {
+  decorations: DecorationSet;
+
+  constructor(view: EditorView) {
+    this.decorations = this.buildDeco(view);
+  }
+
+  update(update: ViewUpdate) {
+    if (update.docChanged) {
+      this.decorations = this.buildDeco(update.view);
+    }
+  }
+
+  buildDeco(view: EditorView) {
+    const builder = new RangeSetBuilder<Decoration>();
+    const { tokens } = highlighter.codeToTokens(view.state.doc.toString(), {
+      themes: {
+        dark: HIGHLIGHT_THEMES?.dark ?? 'github-dark',
+        light: HIGHLIGHT_THEMES?.light ?? 'github-light',
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      lang: view.state.facet(language)!.name as any,
+    });
+    for (const token of tokens.flat()) {
+      span.style.cssText = '';
+      for (const k in token.htmlStyle) {
+        span.style.setProperty(k, token.htmlStyle[k]!);
+      }
+      builder.add(
+        token.offset,
+        token.offset + token.content.length,
+        Decoration.mark({
+          attributes: {
+            style: span.style.cssText,
+          },
+        }),
+      );
+    }
+    return builder.finish();
+  }
+}
+
+export const shikiHighlighter = Prec.high(
+  ViewPlugin.fromClass(TreeHighlighter, {
+    decorations: (v) => v.decorations,
+  }),
+);

package/src/codemirror/typescript/cdn-typescript.d.ts

@@ -0,0 +1 @@
+export { default } from 'typescript';

package/src/codemirror/typescript/cdn-typescript.js

@@ -0,0 +1 @@
+export default (importScripts('https://cdn.jsdelivr.net/npm/typescript@5.9.3/lib/typescript.js'), ts);