@specbook/ui 0.0.0-stage → 0.1.0

package/src/viewer/main.tsx

@@ -0,0 +1,285 @@
+import { render } from 'preact'
+import { useEffect, useRef, useState } from 'preact/hooks'
+import { applyTheme } from '../theme'
+import { type OpenFailure, SpecWorker } from './client'
+import { mountOpened } from './mount'
+import { Opening } from './Opening'
+import type { OpenResult, Source } from './protocol'
+import { recentSpecs, rememberSpec } from './recent'
+import { rawGithub, softEncode } from './share'
+import { loadUpload, saveUpload } from './uploads'
+import 'prism-code-editor/layout.css'
+import 'prism-code-editor/autocomplete.css'
+import 'prism-code-editor/autocomplete-icons.css'
+import '../styles/tokens.css'
+import '../styles/app.css'
+import '../styles/panel.css'
+import './viewer.css'
+
+const EXAMPLES: { label: string; url: string }[] = [
+  { label: 'Petstore', url: 'https://petstore3.swagger.io/api/v3/openapi.json' },
+  { label: 'httpbin (live requests work)', url: 'https://httpbin.org/spec.json' },
+  {
+    label: 'Stripe (form-encoded requests)',
+    url: 'https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json',
+  },
+  {
+    label: 'OpenAI',
+    url: 'https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml',
+  },
+  {
+    label: 'GitHub (large)',
+    url: 'https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json',
+  },
+]
+
+// a stored light or dark choice applies before anything is drawn, as the app itself would
+applyTheme()
+
+const root = document.getElementById('app') as HTMLElement
+const params = new URLSearchParams(location.search)
+// a link that names its document goes straight to opening it: show the app's shape, not the picker
+const autostart = params.has('spec') || params.has('upload')
+
+const specUrl = (u: string) => `${location.origin}${location.pathname}?spec=${softEncode(u)}`
+
+type Phase =
+  | { kind: 'idle' }
+  | { kind: 'loading'; what: string; progress?: string }
+  | { kind: 'error'; message: string; code?: OpenFailure['code'] }
+  | { kind: 'base'; open: OpenResult; apply(base: string | undefined): void }
+
+function Picker({ initial }: { initial: Phase }) {
+  const [phase, setPhase] = useState<Phase>(initial)
+  const [url, setUrl] = useState(params.get('spec') ?? '')
+  const [text, setText] = useState('')
+  const [over, setOver] = useState(false)
+  const worker = useRef<SpecWorker | undefined>(undefined)
+
+  const start = async (source: Source, label: string, remember?: string) => {
+    worker.current ??= new SpecWorker()
+    setPhase({ kind: 'loading', what: label })
+    const { promise } = worker.current.open(source, (progress) =>
+      setPhase({ kind: 'loading', what: label, progress }),
+    )
+    try {
+      const result = await promise
+      const finish = async (baseUrl?: string) => {
+        if (remember) rememberSpec(remember)
+        // the app renders over this one: clearing first would leave a blank page while its code loads
+        await mountOpened({ result, worker: worker.current as SpecWorker, source, baseUrl })
+      }
+      if (result.needsBaseUrl)
+        setPhase({ kind: 'base', open: result, apply: (b) => void finish(b) })
+      else await finish()
+    } catch (e) {
+      const f = e as OpenFailure
+      setPhase({ kind: 'error', message: f.message, code: f.code })
+    }
+  }
+
+  const openUrl = (u: string) => {
+    const clean = rawGithub(u.trim())
+    if (!clean) return
+    if (!/^https?:\/\//i.test(clean))
+      return setPhase({
+        kind: 'error',
+        message: 'Enter an address starting with http:// or https://',
+      })
+    history.replaceState(null, '', specUrl(clean))
+    void start({ kind: 'url', url: clean }, clean, clean)
+  }
+
+  const openText = async (name: string, body: string) => {
+    const id = await saveUpload(name, body)
+    if (id) history.replaceState(null, '', `${location.pathname}?upload=${id}`)
+    void start({ kind: 'text', text: body, name }, name)
+  }
+
+  useEffect(() => {
+    const s = params.get('spec')
+    const up = params.get('upload')
+    if (s) openUrl(s)
+    else if (up)
+      void loadUpload(up).then((u) =>
+        u
+          ? start({ kind: 'text', text: u.text, name: u.name }, u.name)
+          : setPhase({
+              kind: 'error',
+              message: 'That uploaded document is no longer stored in this browser.',
+            }),
+      )
+  }, [])
+
+  const busy = phase.kind === 'loading'
+  if (autostart && (phase.kind === 'idle' || phase.kind === 'loading'))
+    return (
+      <Opening
+        what={params.get('spec') ?? 'your uploaded document'}
+        progress={phase.kind === 'loading' ? phase.progress : undefined}
+      />
+    )
+  return (
+    <main class="vw">
+      <div class="vw-card">
+        <h1>Specbook</h1>
+        <p>
+          Open any OpenAPI or Swagger document. It is read in your browser; nothing is uploaded.
+        </p>
+
+        <form
+          onSubmit={(e) => {
+            e.preventDefault()
+            openUrl(url)
+          }}
+        >
+          <input
+            type="url"
+            placeholder="https://example.com/openapi.json"
+            aria-label="Address of an OpenAPI or Swagger document"
+            value={url}
+            onInput={(e) => setUrl((e.target as HTMLInputElement).value)}
+            disabled={busy}
+          />
+          <button type="submit" class="btn primary" disabled={busy}>
+            Open
+          </button>
+        </form>
+
+        {phase.kind === 'loading' && (
+          <p class="vw-progress" role="status">
+            {phase.progress ?? 'Opening…'}
+          </p>
+        )}
+
+        {phase.kind === 'error' && (
+          <div class="vw-error" role="alert">
+            {phase.message}
+            {phase.code === 'cors' && (
+              <> Paste the document below or drop the file instead; it works the same.</>
+            )}
+          </div>
+        )}
+
+        {phase.kind === 'base' && <BasePrompt onApply={phase.apply} title={phase.open.title} />}
+
+        <section
+          class={`vw-drop ${over ? 'over' : ''}`}
+          aria-label="Drop a document here"
+          onDragOver={(e) => {
+            e.preventDefault()
+            setOver(true)
+          }}
+          onDragLeave={() => setOver(false)}
+          onDrop={async (e) => {
+            e.preventDefault()
+            setOver(false)
+            const f = e.dataTransfer?.files?.[0]
+            if (f) await openText(f.name, await f.text())
+          }}
+        >
+          Drop a file here, or{' '}
+          <label class="link">
+            choose one
+            <input
+              type="file"
+              accept=".json,.yaml,.yml,application/json"
+              hidden
+              onChange={async (e) => {
+                const f = (e.target as HTMLInputElement).files?.[0]
+                if (f) await openText(f.name, await f.text())
+              }}
+            />
+          </label>
+        </section>
+
+        <details>
+          <summary>Paste the document</summary>
+          <p />
+          <textarea
+            aria-label="OpenAPI or Swagger document text"
+            placeholder="{ &quot;openapi&quot;: &quot;3.0.0&quot;, … }"
+            value={text}
+            onInput={(e) => setText((e.target as HTMLTextAreaElement).value)}
+          />
+          <p />
+          <button
+            type="button"
+            class="btn primary"
+            disabled={busy || text.trim() === ''}
+            onClick={() => void openText('pasted document', text)}
+          >
+            Open pasted document
+          </button>
+        </details>
+
+        <section>
+          <p>Try one</p>
+          <ul>
+            {EXAMPLES.map((x) => (
+              <li>
+                <button type="button" class="link" onClick={() => openUrl(x.url)}>
+                  {x.label}
+                </button>
+              </li>
+            ))}
+          </ul>
+        </section>
+
+        {recentSpecs().length > 0 && (
+          <section>
+            <p>Recent</p>
+            <ul>
+              {recentSpecs().map((u) => (
+                <li>
+                  <button type="button" class="link" title={u} onClick={() => openUrl(u)}>
+                    {u}
+                  </button>
+                </li>
+              ))}
+            </ul>
+          </section>
+        )}
+      </div>
+    </main>
+  )
+}
+
+function BasePrompt({
+  onApply,
+  title,
+}: {
+  onApply(base: string | undefined): void
+  title: string
+}) {
+  const [base, setBase] = useState('')
+  return (
+    <form
+      class="vw-base"
+      onSubmit={(e) => {
+        e.preventDefault()
+        if (/^https?:\/\//i.test(base.trim())) onApply(base.trim().replace(/\/$/, ''))
+      }}
+    >
+      <p>
+        This document gives its server as a relative address. Enter where the API is to make live
+        calls, or continue with mock data only.
+      </p>
+      <input
+        type="url"
+        placeholder="https://api.example.com"
+        aria-label={`Base URL for ${title}`}
+        value={base}
+        onInput={(e) => setBase((e.target as HTMLInputElement).value)}
+      />
+      <button type="submit" class="btn primary">
+        Use this base URL
+      </button>
+      <button type="button" class="link" onClick={() => onApply(undefined)}>
+        Continue with mock data
+      </button>
+    </form>
+  )
+}
+
+render(<Picker initial={{ kind: 'idle' }} />, root)

package/src/viewer/mount.ts

@@ -0,0 +1,52 @@
+import type { SpecWorker } from './client'
+import type { OpenResult, Source } from './protocol'
+import type { ViewerGlobal } from './registry'
+
+/**
+ * Hands an opened spec to the app and starts it. The app reads the registry module when it loads, so the
+ * global is set first. `shareable` is false for a page that is not the viewer's own (an embed), where a
+ * link back to `?spec=` would point at a page that does not read it.
+ */
+export async function mountOpened(o: {
+  result: OpenResult
+  worker: SpecWorker
+  source: Source
+  baseUrl?: string
+  shareable?: boolean
+  setTitle?: boolean
+}): Promise<void> {
+  const { worker: w } = o
+  const g: ViewerGlobal = {
+    open: o.result,
+    baseUrl: o.baseUrl,
+    source:
+      o.shareable === false
+        ? undefined
+        : o.source.kind === 'url'
+          ? { kind: 'url', url: o.source.url }
+          : { kind: 'text' },
+    bundle: (id) => w.bundle(id) as Promise<Record<string, any>>,
+    definitions: () => w.definitions() as Promise<Record<string, any>>,
+  }
+  globalThis.__SPECBOOK_VIEWER__ = g
+  if (o.setTitle !== false) document.title = `${o.result.title} · Specbook`
+  await import('../main')
+  warmFaker()
+}
+
+/**
+ * Mock responses are generated with the spec, so the first mock request needs no faker. Faker (a
+ * sizeable chunk) is only used by "Dynamic" examples and `{{faker.*}}` values, so it is fetched when the
+ * page has been idle for a moment instead of up front: by the time someone picks Dynamic it is cached.
+ */
+function warmFaker() {
+  if ((navigator as Navigator & { connection?: { saveData?: boolean } }).connection?.saveData)
+    return
+  const idle: (f: () => void) => void =
+    (window as unknown as { requestIdleCallback?: (f: () => void) => void }).requestIdleCallback ??
+    ((f) => setTimeout(f, 1500))
+  idle(() => {
+    // the registry's loader is the same import the run would make
+    void import('./registry').then((r) => r.loadFaker()).catch(() => {})
+  })
+}

package/src/viewer/protocol.ts

@@ -0,0 +1,51 @@
+import type { AuthProfileLike } from './registry-data'
+
+/** Where a spec comes from. */
+export type Source = { kind: 'url'; url: string } | { kind: 'text'; text: string; name?: string }
+
+export interface Timings {
+  /** fetching the document (url sources) */
+  fetch?: number
+  parse: number
+  generate: number
+  total: number
+}
+
+export interface OpenResult {
+  /** slug of the API title: the service key the UI uses */
+  service: string
+  title: string
+  /** the manifest's operation list, as the UI's registry wants it */
+  manifest: Record<string, unknown>
+  /** per operation, what `defineOperation` needs */
+  metas: Record<string, Record<string, unknown>>
+  /** operation id -> the example names offered (spec ones and generated) */
+  exampleNames: Record<string, string[]>
+  auth: Record<string, AuthProfileLike>
+  secrets: Record<string, Record<string, never>>
+  defaultProfile?: string
+  /** absolute API address, from `servers` (resolved against the spec URL) or `host` */
+  baseUrl?: string
+  /** a relative `servers` entry the person has to give a base URL for */
+  needsBaseUrl: boolean
+  warnings: string[]
+  timings: Timings
+  /** bytes of the document, and of the shared definitions */
+  bytes: { spec: number; definitions: number }
+}
+
+export type Request =
+  | { id: number; type: 'open'; source: Source }
+  | { id: number; type: 'bundle'; opId: string }
+  | { id: number; type: 'definitions' }
+  | { id: number; type: 'cancel' }
+
+export type Response =
+  | { id: number; ok: true; result: OpenResult | string | null }
+  | {
+      id: number
+      ok: false
+      error: string
+      code?: 'cors' | 'http' | 'too-large' | 'timeout' | 'parse'
+    }
+  | { id: number; progress: string }

package/src/viewer/recent.ts

@@ -0,0 +1,22 @@
+const KEY = 'specbook:recent-specs'
+const MAX = 10
+
+export function recentSpecs(): string[] {
+  try {
+    const v = JSON.parse(localStorage.getItem(KEY) ?? '[]')
+    return Array.isArray(v) ? v.filter((x) => typeof x === 'string').slice(0, MAX) : []
+  } catch {
+    return []
+  }
+}
+
+export function rememberSpec(url: string) {
+  try {
+    localStorage.setItem(
+      KEY,
+      JSON.stringify([url, ...recentSpecs().filter((u) => u !== url)].slice(0, MAX)),
+    )
+  } catch {
+    /* private mode: nothing to remember with */
+  }
+}

package/src/viewer/registry-data.ts

@@ -0,0 +1,4 @@
+export interface AuthProfileLike {
+  title: string
+  apply: { headers?: Record<string, string>; query?: Record<string, string> }
+}

package/src/viewer/registry.ts

@@ -0,0 +1,154 @@
+/**
+ * The registry the UI reads (`virtual:specbook/registry`) for a spec opened at run time. The shell opens
+ * the document in a worker and puts the result on `globalThis.__SPECBOOK_VIEWER__` before the app is
+ * imported; this module turns that into the same named exports the dev server and the static build give.
+ */
+import { defineOperation, type OpMeta } from '@specbook/core'
+import type { OpenResult } from './protocol'
+
+export interface ViewerGlobal {
+  open: OpenResult
+  bundle(opId: string): Promise<Record<string, any>>
+  definitions(): Promise<Record<string, any>>
+  /** the base URL the person gave, when the document has none of its own */
+  baseUrl?: string
+  /** where the document came from, which decides whether a link to this view can be shared */
+  source?: import('./share').ViewerSource
+}
+
+declare global {
+  // set by the shell
+  var __SPECBOOK_VIEWER__: ViewerGlobal | undefined
+}
+
+const v = globalThis.__SPECBOOK_VIEWER__
+if (!v) throw new Error('The viewer registry was imported before a spec was opened')
+
+const { open } = v
+const service = open.service
+const keyOf = (id: string) => `${service}/${id}`
+const ids = Object.keys(open.metas)
+
+export const mode = 'static' as const
+export const project = { root: '', outDir: '', requestsDir: 'requests' }
+export const manifests = { [service]: open.manifest }
+export const requests: never[] = []
+export const sequences: never[] = []
+export const sequenceMeta = {}
+export const unresolvedSequences: string[] = []
+export const brandingAssets = {}
+export const environmentVars = {}
+export const docs: never[] = []
+
+/** Per operation bundles are fetched from the worker once and kept. */
+const bundles = new Map<string, Promise<Record<string, any>>>()
+const bundle = (key: string) => {
+  const id = key.slice(service.length + 1)
+  const have = bundles.get(key)
+  if (have) return have
+  const fresh: Promise<Record<string, any>> = v.bundle(id).catch(() => ({}))
+  bundles.set(key, fresh)
+  return fresh
+}
+
+/** A lookup that answers only for `service/Operation` keys. */
+const byKey = <T>(make: (key: string) => T) =>
+  new Proxy({} as Record<string, T>, {
+    get: (_, k) =>
+      typeof k === 'string' &&
+      k.startsWith(`${service}/`) &&
+      ids.includes(k.slice(service.length + 1))
+        ? make(k)
+        : undefined,
+    has: (_, k) =>
+      typeof k === 'string' &&
+      k.startsWith(`${service}/`) &&
+      ids.includes(k.slice(service.length + 1)),
+    ownKeys: () => ids.map(keyOf),
+    getOwnPropertyDescriptor: () => ({ enumerable: true, configurable: true }),
+  })
+
+const part = (pick: (b: Record<string, any>) => unknown) =>
+  byKey((key) => () => bundle(key).then((b) => ({ default: pick(b) })))
+
+export const schemas = part((b) => b.schema)
+export const responseSchemas = part((b) => b.responses)
+export const operationDocs = part((b) => b.docs)
+
+export const definitions = {
+  [service]: () => v.definitions().then((d) => ({ default: d })),
+}
+
+/** Mock responses are keyed `service/Operation.<status|default>`. */
+export const examples = new Proxy({} as Record<string, () => Promise<{ default: unknown }>>, {
+  get: (_, k) => {
+    if (typeof k !== 'string' || !k.includes('.')) return undefined
+    const at = k.lastIndexOf('.')
+    const key = k.slice(0, at)
+    if (!ids.includes(key.slice(service.length + 1))) return undefined
+    return () => bundle(key).then((b) => ({ default: b.mock?.[k.slice(at + 1)] }))
+  },
+})
+
+export const requestExamples = byKey((key) =>
+  (open.exampleNames[key.slice(service.length + 1)] ?? []).map((name) => ({
+    name,
+    source: 'generated' as const,
+    dir: `${key}@generated`,
+    load: () => bundle(key).then((b) => ({ default: b.examples?.[name] })),
+  })),
+)
+
+/** Upload fields are filled with a small sample file, served from memory. */
+let sample: string | undefined
+export const assets = new Proxy({} as Record<string, () => Promise<string>>, {
+  get: (_, k) =>
+    typeof k === 'string' && k.endsWith('/sample.txt')
+      ? () => {
+          sample ??= URL.createObjectURL(
+            new Blob(['specbook sample file\n'], { type: 'text/plain' }),
+          )
+          return Promise.resolve(sample)
+        }
+      : undefined,
+})
+
+export const operations = Object.fromEntries(
+  ids.map((id) => [
+    keyOf(id),
+    async () => ({ [id]: defineOperation(open.metas[id] as unknown as OpMeta) }),
+  ]),
+) as Record<string, () => Promise<Record<string, any>>>
+
+/**
+ * Faker, English only: a locale is its own chunk in a project build, but a viewer opening a stranger's
+ * spec has no reason to ship the others. Loaded only when a run uses `{{faker.*}}`.
+ */
+export const loadFaker = () =>
+  import('./faker-en').then((m) => ({
+    Faker: m.Faker,
+    // a run asks for its locale and `base`, the fallback every locale chain ends in
+    locales: {
+      en: () => Promise.resolve(m.en),
+      base: () => Promise.resolve(m.base),
+    },
+  }))
+
+const baseUrl = v.baseUrl ?? open.baseUrl
+export const loadConfig = () =>
+  Promise.resolve({
+    default: {
+      project: service,
+      secrets: open.secrets,
+      auth: open.auth,
+      // one locale, so the header offers no locale choice
+      faker: { default: 'en', locales: { en: ['en', 'base'] } },
+      services: {
+        [service]: {
+          spec: '',
+          baseUrl: baseUrl ? { live: baseUrl } : {},
+          ...(open.defaultProfile ? { auth: open.defaultProfile } : {}),
+        },
+      },
+    },
+  })