@specbook/ui 0.0.0-stage → 0.2.0

package/src/styles/tokens.css

@@ -0,0 +1,122 @@
+/* Semantic tokens (public theming API). Components use only these. */
+@layer reset, tokens, base, components, brand;
+
+@layer tokens {
+  :root,
+  :host {
+    color-scheme: light;
+    --sb-bg: #f8fafc;
+    --sb-surface: #ffffff;
+    --sb-surface-raised: #f1f5f9;
+    --sb-border: #e2e8f0;
+    --sb-text: #0f172a;
+    --sb-text-muted: #64748b;
+    --sb-accent: #2563eb;
+    --sb-accent-hover: #1d4ed8;
+    --sb-text-on-accent: #ffffff;
+    --sb-focus-ring: #93c5fd;
+    --sb-info: #0369a1;
+    --sb-success: #15803d;
+    --sb-success-subtle: #dcfce7;
+    --sb-danger: #b91c1c;
+    --sb-text-on-danger: #ffffff;
+    --sb-danger-subtle: #fee2e2;
+    --sb-warning: #b45309;
+    --sb-warning-subtle: #fef3c7;
+    --sb-method-get: #0369a1;
+    --sb-method-post: #15803d;
+    --sb-method-put: #b45309;
+    --sb-method-patch: #7c3aed;
+    --sb-method-delete: #b91c1c;
+    --sb-code-bg: #f8fafc;
+    --sb-code-line: #e8eefc;
+    --sb-code-key: #0369a1;
+    --sb-code-string: #15803d;
+    --sb-code-number: #b45309;
+    --sb-code-literal: #7c3aed;
+    --sb-code-keyword: #2563eb;
+    --sb-code-comment: #64748b;
+    --sb-code-punct: #475569;
+    --sb-font-sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    --sb-font-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+    --sb-radius-control: 6px;
+    --sb-radius-card: 10px;
+    --sb-space-1: 4px;
+    --sb-space-2: 8px;
+    --sb-space-3: 12px;
+    --sb-space-4: 16px;
+    --sb-space-6: 24px;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]),
+    :host(:not([data-theme="light"])) {
+      color-scheme: dark;
+      --sb-bg: #0b1020;
+      --sb-surface: #111827;
+      --sb-surface-raised: #1e293b;
+      --sb-border: #243049;
+      --sb-text: #e5e7eb;
+      --sb-text-muted: #94a3b8;
+      --sb-accent: #3b82f6;
+      --sb-accent-hover: #60a5fa;
+      --sb-text-on-accent: #0b1020;
+      --sb-focus-ring: #1d4ed8;
+      --sb-success: #4ade80;
+      --sb-success-subtle: #052e16;
+      --sb-danger: #f87171;
+      --sb-text-on-danger: #0b1020;
+      --sb-danger-subtle: #450a0a;
+      --sb-warning: #fbbf24;
+      --sb-warning-subtle: #422006;
+      --sb-method-get: #38bdf8;
+      --sb-method-post: #4ade80;
+      --sb-method-put: #fbbf24;
+      --sb-method-patch: #a78bfa;
+      --sb-method-delete: #f87171;
+      --sb-code-bg: #0f172a;
+      --sb-code-line: #1e2a4a;
+      --sb-code-key: #38bdf8;
+      --sb-code-string: #4ade80;
+      --sb-code-number: #fbbf24;
+      --sb-code-literal: #a78bfa;
+      --sb-code-keyword: #60a5fa;
+      --sb-code-comment: #94a3b8;
+      --sb-code-punct: #94a3b8;
+    }
+  }
+  :root[data-theme="dark"],
+  :host([data-theme="dark"]) {
+    color-scheme: dark;
+    --sb-bg: #0b1020;
+    --sb-surface: #111827;
+    --sb-surface-raised: #1e293b;
+    --sb-border: #243049;
+    --sb-text: #e5e7eb;
+    --sb-text-muted: #94a3b8;
+    --sb-accent: #3b82f6;
+    --sb-accent-hover: #60a5fa;
+    --sb-text-on-accent: #0b1020;
+    --sb-focus-ring: #1d4ed8;
+    --sb-success: #4ade80;
+    --sb-success-subtle: #052e16;
+    --sb-danger: #f87171;
+    --sb-text-on-danger: #0b1020;
+    --sb-danger-subtle: #450a0a;
+    --sb-warning: #fbbf24;
+    --sb-warning-subtle: #422006;
+    --sb-method-get: #38bdf8;
+    --sb-method-post: #4ade80;
+    --sb-method-put: #fbbf24;
+    --sb-method-patch: #a78bfa;
+    --sb-method-delete: #f87171;
+    --sb-code-bg: #0f172a;
+    --sb-code-line: #1e2a4a;
+    --sb-code-key: #38bdf8;
+    --sb-code-string: #4ade80;
+    --sb-code-number: #fbbf24;
+    --sb-code-literal: #a78bfa;
+    --sb-code-keyword: #60a5fa;
+    --sb-code-comment: #94a3b8;
+    --sb-code-punct: #94a3b8;
+  }
+}

package/src/theme.ts

@@ -0,0 +1,37 @@
+import { signal } from '@preact/signals'
+
+export type Theme = 'auto' | 'light' | 'dark'
+
+const KEY = 'specbook:theme'
+
+function load(): Theme {
+  try {
+    const t = localStorage.getItem(KEY)
+    return t === 'light' || t === 'dark' ? t : 'auto'
+  } catch {
+    return 'auto'
+  }
+}
+
+/** `auto` follows the operating system; the tokens react to `data-theme` on the root element. */
+export const theme = signal<Theme>(load())
+
+export function applyTheme(t: Theme = theme.value) {
+  if (typeof document === 'undefined') return
+  if (t === 'auto') delete document.documentElement.dataset.theme
+  else document.documentElement.dataset.theme = t
+}
+
+const NEXT: Record<Theme, Theme> = { auto: 'light', light: 'dark', dark: 'auto' }
+
+export function cycleTheme() {
+  const next = NEXT[theme.value]
+  theme.value = next
+  try {
+    if (next === 'auto') localStorage.removeItem(KEY)
+    else localStorage.setItem(KEY, next)
+  } catch {
+    /* optional */
+  }
+  applyTheme(next)
+}

package/src/viewer/Opening.tsx

@@ -0,0 +1,43 @@
+import markUrl from '../assets/mark.svg'
+
+const ROWS = [78, 92, 64, 84, 70, 88, 60, 80, 72, 90, 66, 76]
+// the header's controls on a wide screen, by width: two labelled selects, then three icon buttons
+const PILLS = [93, 118, 81, 72, 46, 46, 32]
+
+/**
+ * What a link to `?spec=` shows while the document downloads: the app's own header and two columns, so
+ * the real UI replaces it in place instead of a centred card giving way to a different layout. It reuses
+ * the shell's structural classes for the geometry and none of the ones tests and scripts look for.
+ */
+export function Opening({ what, progress }: { what: string; progress?: string }) {
+  return (
+    <div class="app sk" role="status" aria-live="polite" aria-busy="true">
+      <header class="header">
+        <span class="sk-brand">
+          <img src={markUrl} alt="" width="24" height="24" />
+          Specbook
+        </span>
+        <span class="sk-search" aria-hidden="true" />
+        <span class="spacer" />
+        {PILLS.map((w) => (
+          <span class="sk-pill" style={{ width: `${w}px` }} aria-hidden="true" />
+        ))}
+        <span class="sk-menu" aria-hidden="true" />
+      </header>
+      <div class="layout" data-view="splash">
+        <nav class="list-col" aria-hidden="true">
+          <span class="sk-filter" />
+          {ROWS.map((w) => (
+            <span class="sk-row" style={{ width: `${w}%` }} />
+          ))}
+        </nav>
+        <main class="stage">
+          <p class="sk-status">{progress ?? 'Opening…'}</p>
+          <p class="sk-what" title={what}>
+            {what}
+          </p>
+        </main>
+      </div>
+    </div>
+  )
+}

package/src/viewer/bundles.ts

@@ -0,0 +1,74 @@
+import type { GeneratedFile } from '@specbook/codegen/browser'
+
+/** Raw JSON text of what one operation's page needs, assembled without parsing it. */
+export interface OpParts {
+  schema?: string
+  responses?: string
+  docs?: string
+  examples: Record<string, string>
+  mock: Record<string, string>
+}
+
+export interface Parts {
+  ops: Map<string, OpParts>
+  definitions: string
+  manifest: string
+}
+
+const trim = (s: string) => s.trimEnd()
+
+/**
+ * Sorts a data-only `generate` run into the same per-operation bundles the static build writes
+ * (`{ schema, responses, docs?, examples, mock }`), keeping each piece as the JSON text it already is.
+ */
+export function sortFiles(files: GeneratedFile[]): Parts {
+  const ops = new Map<string, OpParts>()
+  const at = (id: string) => {
+    const have = ops.get(id)
+    if (have) return have
+    const fresh: OpParts = { examples: {}, mock: {} }
+    ops.set(id, fresh)
+    return fresh
+  }
+  let definitions = '{}'
+  let manifest = '{}'
+  for (const f of files) {
+    const parts = f.path.split('/')
+    if (f.path === 'schemas/definitions.schema.json') definitions = trim(f.content)
+    else if (f.path === 'manifest.json') manifest = f.content
+    else if (parts[0] === 'schemas' && parts[1]?.endsWith('.request.schema.json'))
+      at(parts[1].replace(/\.request\.schema\.json$/, '')).schema = trim(f.content)
+    else if (parts[0] === 'schemas' && parts[1]?.endsWith('.responses.schema.json'))
+      at(parts[1].replace(/\.responses\.schema\.json$/, '')).responses = trim(f.content)
+    else if (parts[0] === 'docs' && parts[1]?.endsWith('.json')) {
+      // nothing worth a file or a request: no text, and no examples beyond the generated pair
+      const d = JSON.parse(f.content) as { description?: string; examples?: unknown[] }
+      if (d.description || (d.examples?.length ?? 0) > 2)
+        at(parts[1].replace(/\.json$/, '')).docs = trim(f.content)
+    } else if (parts[0] === 'examples' && parts.length === 3) {
+      const [, id, file] = parts as [string, string, string]
+      if (file.endsWith('.example.json'))
+        at(id).examples[file.replace(/\.example\.json$/, '')] = trim(f.content)
+      else if (file.endsWith('.response.json'))
+        at(id).mock[file.replace(/\.response\.json$/, '')] = trim(f.content)
+    }
+  }
+  return { ops, definitions, manifest }
+}
+
+const obj = (entries: Record<string, string>) =>
+  `{${Object.entries(entries)
+    .map(([k, v]) => `${JSON.stringify(k)}:${v}`)
+    .join(',')}}`
+
+/** The JSON text of one operation's bundle. */
+export function bundleJson(p: OpParts | undefined): string {
+  if (!p) return '{}'
+  const out: string[] = []
+  if (p.schema) out.push(`"schema":${p.schema}`)
+  if (p.responses) out.push(`"responses":${p.responses}`)
+  if (p.docs) out.push(`"docs":${p.docs}`)
+  if (Object.keys(p.examples).length) out.push(`"examples":${obj(p.examples)}`)
+  if (Object.keys(p.mock).length) out.push(`"mock":${obj(p.mock)}`)
+  return `{${out.join(',')}}`
+}

package/src/viewer/client.ts

@@ -0,0 +1,54 @@
+import type { OpenResult, Request, Response, Source } from './protocol'
+import { startWorker } from './worker-factory'
+
+type Call = Request extends infer R ? (R extends { id: number } ? Omit<R, 'id'> : never) : never
+
+export type OpenFailure = Error & { code?: 'cors' | 'http' | 'too-large' | 'timeout' | 'parse' }
+
+/** The main thread's handle on the spec worker: one request at a time per id, with progress. */
+export class SpecWorker {
+  private worker: Worker
+  private next = 1
+  private pending = new Map<
+    number,
+    { resolve(v: unknown): void; reject(e: Error): void; onProgress?: (m: string) => void }
+  >()
+
+  constructor() {
+    this.worker = startWorker()
+    this.worker.addEventListener('message', (e: MessageEvent<Response>) => {
+      const m = e.data
+      const p = this.pending.get(m.id)
+      if (!p) return
+      if ('progress' in m) return p.onProgress?.(m.progress)
+      this.pending.delete(m.id)
+      if (m.ok) p.resolve(m.result)
+      else p.reject(Object.assign(new Error(m.error), { code: m.code }) as OpenFailure)
+    })
+  }
+
+  private call<T>(req: Call, onProgress?: (m: string) => void) {
+    const id = this.next++
+    return {
+      id,
+      promise: new Promise<T>((resolve, reject) => {
+        this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, onProgress })
+        this.worker.postMessage({ ...req, id } as Request)
+      }),
+    }
+  }
+
+  open(source: Source, onProgress?: (m: string) => void) {
+    const { id, promise } = this.call<OpenResult>({ type: 'open', source }, onProgress)
+    return { promise, cancel: () => this.worker.postMessage({ type: 'cancel', id } as Request) }
+  }
+
+  async bundle(opId: string): Promise<unknown> {
+    const json = await this.call<string>({ type: 'bundle', opId }).promise
+    return JSON.parse(json)
+  }
+
+  async definitions(): Promise<unknown> {
+    return JSON.parse(await this.call<string>({ type: 'definitions' }).promise)
+  }
+}

package/src/viewer/embed.ts

@@ -0,0 +1,83 @@
+/**
+ * `specbook.js`: a page that already serves an API's spec (a framework's docs route) loads this to get the
+ * viewer, on its own origin, with no CORS and with the visitor's cookies.
+ *
+ *   <div id="app"></div>
+ *   <script type="application/json" id="specbook-config">{"spec": "/v3/api-docs"}</script>
+ *   <script type="module" src="https://ui.specbook.dev/v1/specbook.js"></script>
+ *
+ * The script takes the page over (it owns the document, as `/docs` does). `spec` may be relative.
+ * `baseUrl` gives the API address when the document has none, `target` names another container.
+ */
+import { handleOAuthCallback } from '../oauth-callback'
+import { SpecWorker } from './client'
+import { mountOpened } from './mount'
+
+interface EmbedConfig {
+  spec?: string
+  baseUrl?: string
+  target?: string
+}
+
+function readConfig(): EmbedConfig {
+  const el = document.getElementById('specbook-config')
+  if (el?.textContent) {
+    try {
+      return JSON.parse(el.textContent) as EmbedConfig
+    } catch {
+      /* fall through to the script's own attributes */
+    }
+  }
+  const script = document.querySelector<HTMLScriptElement>('script[src$="specbook.js"][data-spec]')
+  return { spec: script?.dataset.spec, baseUrl: script?.dataset.baseUrl }
+}
+
+function container(sel?: string): HTMLElement {
+  const found = sel ? document.querySelector<HTMLElement>(sel) : document.getElementById('app')
+  if (found) return found
+  const made = document.createElement('div')
+  made.id = 'app'
+  document.body.append(made)
+  return made
+}
+
+const say = (el: HTMLElement, text: string, error = false) => {
+  el.textContent = text
+  el.style.cssText = `font:16px system-ui,sans-serif;padding:24px;color:${error ? '#b42318' : '#5b6270'}`
+}
+
+async function start() {
+  // A sign-in's popup comes back to this page, so the viewer is what has to hand the code on. The address
+  // is left alone unless a viewer tab claims it: the page is the host's, and its `?code=&state=` may be
+  // the host application's own sign-in.
+  if (await handleOAuthCallback({ stripWhenUnclaimed: false })) return
+  const cfg = readConfig()
+  const target = container(cfg.target)
+  if (!cfg.spec)
+    return say(target, 'Specbook: no spec was given (set "spec" in #specbook-config).', true)
+  let url: string
+  try {
+    url = new URL(cfg.spec, location.href).toString()
+  } catch {
+    return say(target, `Specbook: "${cfg.spec}" is not a valid address.`, true)
+  }
+  say(target, 'Loading the API…')
+  const worker = new SpecWorker()
+  try {
+    const result = await worker.open({ kind: 'url', url }).promise
+    target.textContent = ''
+    target.removeAttribute('style')
+    await mountOpened({
+      result,
+      worker,
+      source: { kind: 'url', url },
+      baseUrl: cfg.baseUrl,
+      shareable: false,
+      setTitle: false,
+    })
+  } catch (e) {
+    say(target, `Specbook: ${e instanceof Error ? e.message : String(e)}`, true)
+  }
+}
+
+void start()

package/src/viewer/faker-en.ts

@@ -0,0 +1,3 @@
+// English only: the other locales are not named here, so the bundler leaves them out. (The size is the
+// English data itself, which is most of faker; the locale list in the header is hidden for one locale.)
+export { base, en, Faker } from '@faker-js/faker'