@specbook/ui 0.0.0-stage → 0.1.0

package/src/viewer/share.ts

@@ -0,0 +1,134 @@
+/**
+ * Whether the page in front of someone can be shared as a link, and the links to do it with. A link is
+ * only offered when everyone who opens it would get the same result: the document came from a public
+ * address (a spec fetched by the browser from our origin, so it allows our origin for everyone), and
+ * the address carries no credential.
+ */
+
+export type ViewerSource = { kind: 'url'; url: string } | { kind: 'text'; name?: string }
+
+const SECRETISH =
+  /^(token|access_token|id_token|refresh_token|key|api[-_]?key|apikey|secret|client_secret|password|passwd|pwd|auth|authorization|signature|sig|jwt|session|sid|code|x-amz-.*|x-goog-.*)$/i
+
+const PRIVATE_HOST = /\.(local|internal|lan|home|corp|intranet|localhost)$/i
+
+function privateAddress(host: string): boolean {
+  const h = host.replace(/^\[|\]$/g, '').toLowerCase()
+  if (h === 'localhost' || PRIVATE_HOST.test(h)) return true
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h)
+  if (v4) {
+    const [a, b] = [Number(v4[1]), Number(v4[2])]
+    return (
+      a === 0 ||
+      a === 10 ||
+      a === 127 ||
+      (a === 169 && b === 254) ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168) ||
+      (a === 100 && b >= 64 && b <= 127)
+    )
+  }
+  return h === '::1' || /^f[cd]/.test(h) || /^fe[89ab]/.test(h)
+}
+
+/**
+ * A spec address in a link: the colon and slashes of a URL are legal in a query string and stay as they
+ * are, so the link reads as `?spec=https://host/openapi.json`; `&`, `#` and `%` are still escaped.
+ */
+export const softEncode = (s: string) =>
+  encodeURIComponent(s).replace(/%3A/gi, ':').replace(/%2F/gi, '/')
+
+/**
+ * The address of a file as GitHub serves it to programs. A file page (`github.com/o/r/blob/<ref>/<path>`) and
+ * its "Raw" link (`github.com/o/r/raw/<ref>/<path>`, which redirects without CORS headers) are HTML or a
+ * redirect; the document itself is at `raw.githubusercontent.com/o/r/<ref>/<path>`. Anything else is
+ * returned unchanged. The landing page keeps a copy of this (`landing/landing.js`, plain script).
+ */
+export function rawGithub(address: string): string {
+  let u: URL
+  try {
+    u = new URL(address)
+  } catch {
+    return address
+  }
+  if (u.protocol !== 'https:' || !/^(www\.)?github\.com$/i.test(u.hostname)) return address
+  const m = /^\/([^/]+)\/([^/]+)\/(?:blob|raw)\/(.+)$/.exec(u.pathname)
+  return m ? `https://raw.githubusercontent.com/${m[1]}/${m[2]}/${m[3]}` : address
+}
+
+export type Shareable = { ok: true; spec: string } | { ok: false; reason: string }
+
+export function shareable(source: ViewerSource | undefined): Shareable {
+  if (!source || source.kind === 'text')
+    return {
+      ok: false,
+      reason:
+        'This document was pasted or opened from a file, so there is no address to link to. Put the file somewhere public (a GitHub raw link or a Gist works) and open that address to get a link.',
+    }
+  let u: URL
+  try {
+    u = new URL(source.url)
+  } catch {
+    return { ok: false, reason: 'The document address is not a valid link.' }
+  }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:')
+    return { ok: false, reason: 'Only http and https addresses can be linked.' }
+  if (privateAddress(u.hostname))
+    return {
+      ok: false,
+      reason:
+        'That address is only reachable from your own machine or network, so a link would not work for anyone else.',
+    }
+  if (u.username || u.password)
+    return { ok: false, reason: 'The address contains a login, which a link would publish.' }
+  for (const k of u.searchParams.keys())
+    if (SECRETISH.test(k))
+      return {
+        ok: false,
+        reason: `The address has a "${k}" parameter that looks like a credential, which a link would publish.`,
+      }
+  return { ok: true, spec: u.toString() }
+}
+
+export interface ShareLinks {
+  link: string
+  title: string
+  targets: { id: string; label: string; href: string }[]
+}
+
+/** `location` is the viewer's own (origin, path and the hash of the operation being looked at). */
+export function shareLinks(
+  where: { origin: string; pathname: string; hash: string },
+  spec: string,
+  apiTitle: string,
+): ShareLinks {
+  const link = `${where.origin}${where.pathname}?spec=${softEncode(spec)}${where.hash}`
+  const title = `Exploring ${apiTitle} in Specbook`
+  const q = (o: Record<string, string>) => new URLSearchParams(o).toString()
+  return {
+    link,
+    title,
+    targets: [
+      {
+        id: 'x',
+        label: 'X',
+        href: `https://twitter.com/intent/tweet?${q({ text: title, url: link })}`,
+      },
+      {
+        id: 'reddit',
+        label: 'Reddit',
+        href: `https://www.reddit.com/submit?${q({ url: link, title })}`,
+      },
+      {
+        id: 'hn',
+        label: 'Hacker News',
+        href: `https://news.ycombinator.com/submitlink?${q({ u: link, t: title })}`,
+      },
+      {
+        id: 'linkedin',
+        label: 'LinkedIn',
+        href: `https://www.linkedin.com/sharing/share-offsite/?${q({ url: link })}`,
+      },
+    ],
+  }
+}

package/src/viewer/site.ts

@@ -0,0 +1,3 @@
+/** The project's repository, in one place. */
+export const REPO = 'specbook-dev/specbook'
+export const REPO_URL = `https://github.com/${REPO}`

package/src/viewer/uploads.ts

@@ -0,0 +1,53 @@
+/**
+ * Pasted and dropped documents, kept in this browser so a reload reopens them. They are never shared
+ * (a link cannot carry them) and only the last few are kept.
+ */
+const DB = 'specbook-viewer'
+const STORE = 'uploads'
+const KEEP = 5
+
+interface Row {
+  id: string
+  name: string
+  text: string
+  at: number
+}
+
+function db(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const r = indexedDB.open(DB, 1)
+    r.onupgradeneeded = () => r.result.createObjectStore(STORE, { keyPath: 'id' })
+    r.onsuccess = () => resolve(r.result)
+    r.onerror = () => reject(r.error)
+  })
+}
+
+const done = <T>(r: IDBRequest<T>) =>
+  new Promise<T>((resolve, reject) => {
+    r.onsuccess = () => resolve(r.result)
+    r.onerror = () => reject(r.error)
+  })
+
+export async function saveUpload(name: string, text: string): Promise<string | undefined> {
+  try {
+    const d = await db()
+    const id = Math.random().toString(36).slice(2, 10)
+    const s = d.transaction(STORE, 'readwrite').objectStore(STORE)
+    await done(s.put({ id, name, text, at: Date.now() } satisfies Row))
+    const all = (await done(s.getAll())) as Row[]
+    for (const old of all.sort((a, b) => b.at - a.at).slice(KEEP)) s.delete(old.id)
+    return id
+  } catch {
+    return undefined
+  }
+}
+
+export async function loadUpload(id: string): Promise<{ name: string; text: string } | undefined> {
+  try {
+    const d = await db()
+    const row = (await done(d.transaction(STORE).objectStore(STORE).get(id))) as Row | undefined
+    return row ? { name: row.name, text: row.text } : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/viewer/viewer.css

@@ -0,0 +1,184 @@
+.vw {
+  min-height: 100dvh;
+  display: grid;
+  place-items: center;
+  padding: 24px 16px;
+  background: var(--sb-bg);
+  color: var(--sb-text);
+  font-family: var(--sb-font-sans);
+}
+.vw-card {
+  width: min(640px, 100%);
+  display: grid;
+  gap: 16px;
+}
+.vw h1 {
+  margin: 0;
+  font-size: 28px;
+  letter-spacing: -0.01em;
+}
+.vw p {
+  margin: 0;
+  color: var(--sb-text-muted);
+}
+.vw form {
+  display: flex;
+  gap: 8px;
+}
+.vw input[type="url"],
+.vw input[type="text"],
+.vw textarea {
+  flex: 1;
+  min-width: 0;
+  font: inherit;
+  font-size: 16px;
+  padding: 10px 12px;
+  color: var(--sb-text);
+  background: var(--sb-surface);
+  border: 1px solid var(--sb-border);
+  border-radius: var(--sb-radius-control);
+}
+.vw textarea {
+  width: 100%;
+  min-height: 120px;
+  font-family: var(--sb-font-mono);
+  font-size: 13px;
+}
+.vw .vw-drop {
+  border: 1px dashed var(--sb-border);
+  border-radius: var(--sb-radius-control);
+  padding: 14px;
+  text-align: center;
+  color: var(--sb-text-muted);
+}
+.vw .vw-drop.over {
+  border-color: var(--sb-accent);
+  color: var(--sb-text);
+}
+.vw .vw-error {
+  color: var(--sb-danger);
+  background: var(--sb-danger-subtle);
+  border-radius: var(--sb-radius-control);
+  padding: 10px 12px;
+}
+.vw .vw-warn {
+  color: var(--sb-warning);
+}
+.vw ul {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: grid;
+  gap: 4px;
+}
+.vw li button.link {
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.vw .vw-progress {
+  color: var(--sb-text-muted);
+}
+@media (max-width: 480px) {
+  .vw form {
+    flex-direction: column;
+  }
+}
+
+/* the opening screen: the app's header and columns, with placeholders where its content will be */
+.sk .sk-brand {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 15px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  color: var(--sb-text);
+  /* the real brand is a button, and carries its padding */
+  padding: 1px 6px;
+}
+.sk .sk-search {
+  min-width: min(360px, 40vw);
+  height: 34px;
+  border: 1px solid var(--sb-border);
+  border-radius: var(--sb-radius-control);
+  background: var(--sb-bg);
+}
+.sk .sk-pill {
+  height: 32px;
+  border-radius: var(--sb-radius-control);
+  background: var(--sb-surface-raised);
+}
+.sk .sk-menu {
+  display: none;
+  width: 36px;
+  height: 36px;
+  border-radius: var(--sb-radius-control);
+  background: var(--sb-surface-raised);
+}
+.sk .sk-filter {
+  display: block;
+  height: 34px;
+  border: 1px solid var(--sb-border);
+  border-radius: var(--sb-radius-control);
+  background: var(--sb-bg);
+}
+.sk .stage {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+}
+.sk .sk-row {
+  display: block;
+  height: 34px;
+  margin: 12px 0 0;
+  border-radius: var(--sb-radius-control);
+  background: linear-gradient(
+    90deg,
+    var(--sb-surface-raised) 0%,
+    var(--sb-bg) 50%,
+    var(--sb-surface-raised) 100%
+  );
+  background-size: 200% 100%;
+  animation: sk-shimmer 1.4s linear infinite;
+}
+.sk .sk-status {
+  margin: 0;
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--sb-text);
+}
+.sk .sk-what {
+  margin: 6px 0 0;
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--sb-text-muted);
+}
+@keyframes sk-shimmer {
+  to {
+    background-position: -200% 0;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .sk .sk-row {
+    animation: none;
+  }
+}
+@media (max-width: 900px) {
+  .sk .sk-search {
+    flex: 1;
+    min-width: 0;
+  }
+  .sk .sk-pill,
+  .sk .spacer {
+    display: none;
+  }
+  .sk .sk-menu {
+    display: block;
+  }
+}

package/src/viewer/worker-factory.ts

@@ -0,0 +1,14 @@
+import workerUrl from './worker.ts?worker&url'
+
+/**
+ * The spec worker. A browser will not start a `Worker` from another origin's URL, and the embed script
+ * is exactly that when a page loads it from the CDN, so a cross-origin worker is started from a blob
+ * that imports it (the module's own CORS headers make that allowed). A host page whose CSP forbids blob
+ * workers cannot use this path; it serves the viewer's files itself instead.
+ */
+export function startWorker(): Worker {
+  const url = new URL(workerUrl, import.meta.url)
+  if (url.origin === location.origin) return new Worker(url, { type: 'module' })
+  const blob = new Blob([`import ${JSON.stringify(url.href)}`], { type: 'text/javascript' })
+  return new Worker(URL.createObjectURL(blob), { type: 'module' })
+}

package/src/viewer/worker.ts

@@ -0,0 +1,171 @@
+/// <reference lib="webworker" />
+import { generateData, type OperationMeta, openSpec } from '@specbook/codegen/browser'
+import { authFromSpec, liveBaseUrl } from '@specbook/core'
+import { bundleJson, type Parts, sortFiles } from './bundles'
+import type { OpenResult, Request, Response, Source } from './protocol'
+
+const MAX_BYTES = 25 * 1024 * 1024
+const TIMEOUT_MS = 30_000
+
+const post = (r: Response) => (self as unknown as Worker).postMessage(r)
+
+let parts: Parts | undefined
+const aborts = new Map<number, AbortController>()
+
+class Failure extends Error {
+  constructor(
+    message: string,
+    readonly code?: 'cors' | 'http' | 'too-large' | 'timeout' | 'parse',
+  ) {
+    super(message)
+  }
+}
+
+const slug = (s: string) =>
+  s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'api'
+
+/** The document's bytes, read as a stream so a cap applies before it is all in memory. */
+async function download(url: string, signal: AbortSignal): Promise<string> {
+  let res: globalThis.Response
+  try {
+    res = await fetch(url, { signal, redirect: 'follow', credentials: 'omit' })
+  } catch {
+    if (signal.aborted) throw new Failure('The server took too long to answer.', 'timeout')
+    throw new Failure(
+      'The browser could not read that address. The server may not allow requests from other sites (CORS), or the address is not reachable from here.',
+      'cors',
+    )
+  }
+  if (!res.ok) throw new Failure(`The server answered ${res.status} for that address.`, 'http')
+  const declared = Number(res.headers.get('content-length') ?? 0)
+  if (declared > MAX_BYTES) throw new Failure('That document is larger than 25 MB.', 'too-large')
+  const reader = res.body?.getReader()
+  if (!reader) return res.text()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.length
+    if (size > MAX_BYTES) {
+      await reader.cancel()
+      throw new Failure('That document is larger than 25 MB.', 'too-large')
+    }
+    chunks.push(value)
+  }
+  const all = new Uint8Array(size)
+  let o = 0
+  for (const c of chunks) {
+    all.set(c, o)
+    o += c.length
+  }
+  return new TextDecoder().decode(all)
+}
+
+async function open(id: number, source: Source, signal: AbortSignal): Promise<OpenResult> {
+  const t0 = performance.now()
+  let text: string
+  let fetched: number | undefined
+  let name: string | undefined
+  if (source.kind === 'url') {
+    post({ id, progress: 'Fetching the document…' })
+    const t = performance.now()
+    text = await download(source.url, signal)
+    fetched = performance.now() - t
+    name = source.url
+  } else {
+    text = source.text
+    name = source.name
+  }
+  post({ id, progress: 'Reading the document…' })
+  const tParse = performance.now()
+  let opened: Awaited<ReturnType<typeof openSpec>>
+  try {
+    opened = await openSpec(text)
+  } catch (e) {
+    throw new Failure(e instanceof Error ? e.message : String(e), 'parse')
+  }
+  const parse = performance.now() - tParse
+  const { doc, warnings } = opened
+
+  post({ id, progress: 'Preparing operations…' })
+  const title = (doc.info?.title as string | undefined) ?? 'API'
+  const service = slug(title)
+  const tGen = performance.now()
+  const generated = generateData(doc, { service })
+  const generate = performance.now() - tGen
+
+  parts = sortFiles(generated.files)
+  const manifest = JSON.parse(parts.manifest) as Record<string, any>
+  const slim = {
+    ...manifest,
+    operations: manifest.operations.map(
+      ({ description: _d, examples: _e, file: _f, ...o }: Record<string, unknown>) => o,
+    ),
+  }
+  const exampleNames = Object.fromEntries(
+    manifest.operations.map((o: any) => [
+      o.id,
+      (o.examples as { name: string }[]).map((e) => e.name),
+    ]),
+  )
+  const { auth, secrets, defaultProfile } = authFromSpec(doc)
+  const sourceUrl = source.kind === 'url' ? source.url : undefined
+  const baseUrl = liveBaseUrl(doc, sourceUrl ?? name ?? '')
+  const relativeServer =
+    typeof doc.servers?.[0]?.url === 'string' && !/^https?:\/\//i.test(doc.servers[0].url)
+  return {
+    service,
+    title,
+    manifest: slim,
+    metas: generated.metas as unknown as Record<string, Record<string, unknown>>,
+    exampleNames,
+    auth,
+    secrets,
+    defaultProfile,
+    baseUrl,
+    needsBaseUrl: !baseUrl && relativeServer,
+    warnings,
+    timings: {
+      ...(fetched !== undefined ? { fetch: Math.round(fetched) } : {}),
+      parse: Math.round(parse),
+      generate: Math.round(generate),
+      total: Math.round(performance.now() - t0),
+    },
+    bytes: { spec: text.length, definitions: parts.definitions.length },
+  }
+}
+
+self.addEventListener('message', async (e: MessageEvent<Request>) => {
+  const m = e.data
+  try {
+    if (m.type === 'cancel') {
+      aborts.get(m.id)?.abort()
+      return
+    }
+    if (m.type === 'bundle') {
+      return post({ id: m.id, ok: true, result: bundleJson(parts?.ops.get(m.opId)) })
+    }
+    if (m.type === 'definitions') {
+      return post({ id: m.id, ok: true, result: parts?.definitions ?? '{}' })
+    }
+    const ctl = new AbortController()
+    aborts.set(m.id, ctl)
+    const timer = setTimeout(() => ctl.abort(), TIMEOUT_MS)
+    try {
+      const result = await open(m.id, m.source, ctl.signal)
+      post({ id: m.id, ok: true, result })
+    } finally {
+      clearTimeout(timer)
+      aborts.delete(m.id)
+    }
+  } catch (err) {
+    if (err instanceof Failure) post({ id: m.id, ok: false, error: err.message, code: err.code })
+    else post({ id: m.id, ok: false, error: err instanceof Error ? err.message : String(err) })
+  }
+})
+
+export type { OperationMeta }

package/src/virtual.d.ts

@@ -0,0 +1,104 @@
+declare module 'virtual:specbook/registry' {
+  interface Entry {
+    file: string
+    load: (version: number) => Promise<Record<string, any>>
+    /** static builds only */
+    source?: () => Promise<string>
+  }
+  export const mode: 'dev' | 'static'
+  export const project: { root: string; outDir: string; requestsDir: string }
+  export const manifests: Record<
+    string,
+    {
+      service: string
+      title?: string
+      version?: string
+      /** from the spec's `info.x-logo` */
+      logo?: { url: string; altText?: string; backgroundColor?: string }
+      tags: string[]
+      operations: {
+        id: string
+        method: string
+        path: string
+        summary?: string
+        tags: string[]
+        statuses: number[]
+        /** the spec requires credentials */
+        secured?: boolean
+      }[]
+    }
+  >
+  export const requests: Entry[]
+  export const sequences: Entry[]
+  /** Sequence headers read from the `*.seq.ts` text (no import), keyed by id. */
+  export const sequenceMeta: Record<
+    string,
+    {
+      id: string
+      title: string
+      description?: string
+      tags?: string[]
+      group?: string
+      file: string
+    }
+  >
+  /** Sequence files whose header is not plain literals; these are imported to be listed. */
+  export const unresolvedSequences: string[]
+  /** `.specbook/branding/logo.*` and `favicon.*`, resolved to URLs on demand. */
+  export const brandingAssets: Partial<Record<'logo' | 'favicon', () => Promise<string>>>
+  /** Non-secret variables from `.specbook/environments/<env>.env`, by environment. */
+  export const environmentVars: Record<string, Record<string, string>>
+  /** Long description and example titles per `service/OperationId`, loaded when its page opens. */
+  export const operationDocs: Record<
+    string,
+    () => Promise<{
+      default: { description?: string; examples: { name: string; title: string; source: string }[] }
+    }>
+  >
+  export const operations: Record<string, (version: number) => Promise<Record<string, any>>>
+  /** JSON Schema of the request object ({ path, query, headers, data }) per `service/OperationId` */
+  export const schemas: Record<string, () => Promise<{ default: Record<string, any> }>>
+  /** JSON Schema per response status, per `service/OperationId`: { "200": schema, ... } */
+  export const responseSchemas: Record<string, () => Promise<{ default: Record<string, any> }>>
+  /** Shared component definitions per service */
+  export const definitions: Record<string, () => Promise<{ default: Record<string, any> }>>
+  export const examples: Record<string, (version: number) => Promise<{ default: unknown }>>
+  /** Request examples per `service/OperationId`; project files override generated ones of the same name. */
+  export const requestExamples: Record<
+    string,
+    {
+      name: string
+      source: 'generated' | 'project'
+      dir: string
+      load: (version: number) => Promise<{ default: unknown }>
+    }[]
+  >
+  /** Non-JSON files an example uploads, keyed `<dir>/<file>`; resolves to a URL. */
+  export const assets: Record<string, () => Promise<string>>
+  /** Markdown pages (compiled at build time) tied to an operation or sequence. */
+  export const docs: {
+    file: string
+    operation?: string
+    sequence?: string
+    /** the `.seq.ts` this page sits beside */
+    sequenceFile?: string
+    /** the `.req.ts` this page sits beside */
+    requestFile?: string
+    /** the page replaces the operation's spec description */
+    replace?: boolean
+    title?: string
+    load: () => Promise<string>
+  }[]
+  export const loadFaker: ((version: number) => Promise<Record<string, any>>) | null
+  export const loadConfig: (version: number) => Promise<{ default: any }>
+}
+
+declare module 'virtual:specbook/types' {
+  const types: { libs: Record<string, string>; sources: Record<string, string> }
+  export default types
+}
+
+declare module 'virtual:specbook/faker' {
+  const mod: Record<string, any>
+  export = mod
+}