@specbook/ui 0.0.0-stage → 0.2.0

package/src/extension.ts

@@ -0,0 +1,101 @@
+import {
+  createFetchTransport,
+  requestToWire,
+  type Transport,
+  WIRE_VERSION,
+  type WireCall,
+  type WireReply,
+  wireToResponse,
+} from '@specbook/core'
+
+/**
+ * The page's side of the browser extension. The extension (its own package, not built yet) makes the
+ * outbound call from its service worker with the user's grant, using `handleWireFetch` from core, so the
+ * policy and secret substitution are the ones the dev server and a hosted proxy run.
+ *
+ * A bridge is anything that can carry a `WireCall` to it and bring a `WireReply` back: a content script
+ * relaying `postMessage`, or a test double.
+ */
+export interface ExtensionBridge {
+  /** Protocol version the extension speaks. */
+  version: number
+  send(call: WireCall, signal?: AbortSignal): Promise<WireReply>
+}
+
+declare global {
+  // a content script (or a test) may place its bridge here
+  var __SPECBOOK_EXTENSION__: ExtensionBridge | undefined
+}
+
+const CHANNEL = 'specbook'
+
+/** `postMessage` to a content script that answers on the same window. */
+function windowBridge(version: number): ExtensionBridge {
+  return {
+    version,
+    send(call, signal) {
+      return new Promise<WireReply>((resolve, reject) => {
+        const id = (call as { id?: string }).id
+        const on = (e: MessageEvent) => {
+          const m = e.data as { channel?: string; reply?: WireReply } | undefined
+          if (e.source !== window || m?.channel !== `${CHANNEL}:reply` || !m.reply) return
+          const r = m.reply as { id?: string; type: string }
+          if (id !== undefined && r.id !== id) return
+          cleanup()
+          resolve(m.reply)
+        }
+        const abort = () => {
+          cleanup()
+          window.postMessage({ channel: `${CHANNEL}:call`, call: { v: 1, type: 'abort', id } }, '*')
+          reject(new DOMException('aborted', 'AbortError'))
+        }
+        const cleanup = () => {
+          window.removeEventListener('message', on)
+          signal?.removeEventListener('abort', abort)
+        }
+        window.addEventListener('message', on)
+        signal?.addEventListener('abort', abort)
+        window.postMessage({ channel: `${CHANNEL}:call`, call }, '*')
+      })
+    },
+  }
+}
+
+/** The bridge when an extension is installed and enabled for this page, within a short wait. */
+export async function detectExtension(waitMs = 250): Promise<ExtensionBridge | undefined> {
+  const injected = globalThis.__SPECBOOK_EXTENSION__
+  if (injected) return injected
+  if (typeof window === 'undefined') return undefined
+  const bridge = windowBridge(WIRE_VERSION)
+  const timeout = new Promise<undefined>((r) => setTimeout(() => r(undefined), waitMs))
+  const pong = await Promise.race([
+    bridge.send({ v: 1, type: 'ping' }).catch(() => undefined),
+    timeout,
+  ])
+  return pong?.type === 'pong' ? { ...bridge, version: pong.version } : undefined
+}
+
+let counter = 0
+
+/**
+ * A `Transport` that sends each request to the extension. Built on the ordinary fetch transport with a
+ * `fetch` that carries the request over the bridge, so bodies, query strings and response parsing are
+ * the same as for a direct call.
+ */
+export function extensionTransport(
+  bridge: ExtensionBridge,
+  baseOf: (service: string) => string,
+): Transport {
+  const carry: typeof fetch = async (input, init) => {
+    const req = new Request(input as RequestInfo, init)
+    const id = `c${Date.now().toString(36)}${counter++}`
+    const reply = await bridge.send(
+      { v: 1, type: 'fetch', id, req: await requestToWire(req) },
+      init?.signal ?? undefined,
+    )
+    if (reply.type === 'error') throw new Error(reply.message)
+    if (reply.type !== 'response') throw new Error('unexpected reply from the extension')
+    return wireToResponse(reply.res)
+  }
+  return createFetchTransport({ baseUrl: baseOf, fetch: carry })
+}

package/src/fielddoc.ts

@@ -0,0 +1,83 @@
+import { type FieldSection, noteKey } from './panel/fieldnotes-split'
+import {
+  type Defs,
+  describe,
+  type JsonSchema,
+  type KeyPath,
+  kindOf,
+  pathString,
+  propsOf,
+  schemaAt,
+  unwrap,
+} from './schema'
+
+export interface FieldDoc {
+  path: string
+  type: string
+  required: boolean
+  enum?: string[]
+  description?: string
+  /** the project's own note for this field (HTML), shown after the spec's description */
+  note?: string
+  /** what the enclosing object says about itself, shown when the field has no description */
+  parent?: string
+  deprecated?: boolean
+}
+
+/** What the API documents about the field at `path` (relative to `prefix`, e.g. `['data']` for a body). */
+export function fieldDoc(
+  root: JsonSchema | undefined,
+  defs: Defs,
+  path: KeyPath,
+  prefix: KeyPath = [],
+): FieldDoc | undefined {
+  if (!root) return undefined
+  const full = [...prefix, ...path]
+  const schema = full.length === 0 ? root : schemaAt(root, full, defs)
+  if (!schema) return undefined
+  const u = unwrap(schema, defs)
+  // the cursor is on the outermost brace: say what the whole body is, when the spec does
+  if (path.length === 0) {
+    const text = typeof u.description === 'string' ? u.description.trim() : ''
+    if (!text) return undefined
+    return {
+      path: typeof u.title === 'string' && u.title.trim() ? u.title.trim() : 'body',
+      type: kindOf(u),
+      required: false,
+      description: text,
+      deprecated: u.deprecated === true || undefined,
+    }
+  }
+  const key = path[path.length - 1]
+  const parent = schemaAt(root, full.slice(0, -1), defs)
+  const kind = kindOf(u)
+  const item = kind === 'array' ? kindOf(unwrap(u.items, defs)) : undefined
+  return {
+    path: pathString(path),
+    type: item ? `${item}[]` : u.format ? `${kind} · ${u.format}` : kind,
+    required:
+      typeof key === 'string' &&
+      !!parent &&
+      propsOf(parent, defs).some((p) => p.name === key && p.required),
+    enum: Array.isArray(u.enum) ? u.enum.map(String) : undefined,
+    description: describe(u),
+    parent: parent ? describe(unwrap(parent, defs)) : undefined,
+    deprecated: u.deprecated === true || undefined,
+  }
+}
+
+/** `metadata[order]` / `items[0][price]` -> ['metadata', 'order'] / ['items', 0, 'price'] */
+export function keyPath(key: string): KeyPath {
+  return (key.match(/[^[\]]+/g) ?? [key]).map((s) => (/^\d+$/.test(s) ? Number(s) : s))
+}
+
+/** Adds the project's note for `path` in `section` (see `README.md` field sections), when there is one. */
+export function withNote(
+  doc: FieldDoc | undefined,
+  notes: Map<string, string> | undefined,
+  section: FieldSection,
+  path: string,
+): FieldDoc | undefined {
+  const note = doc && notes?.get(noteKey(section, path))
+  return doc && note ? { ...doc, note } : doc
+}

package/src/main.tsx

@@ -0,0 +1,24 @@
+import { render } from 'preact'
+import { App } from './app'
+import { handleOAuthCallback } from './oauth-callback'
+import { applyTheme } from './theme'
+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'
+
+applyTheme()
+// A sign-in's return leg is handed to the tab that started it; this page then has nothing to draw. Under the
+// viewer shell or an embed (which import this) that was settled before they got here, and running it again
+// would strip a host page's own `?code=&state=` that the embed deliberately left alone.
+const underShell =
+  (globalThis as { __SPECBOOK_VIEWER__?: unknown }).__SPECBOOK_VIEWER__ !== undefined
+void (underShell ? Promise.resolve(false) : handleOAuthCallback()).then((handled) => {
+  if (!handled) render(<App />, document.getElementById('app') as HTMLElement)
+})
+
+if (import.meta.hot) {
+  import.meta.hot.on('specbook:registry-changed', () => location.reload())
+}

package/src/markdown.ts

@@ -0,0 +1,133 @@
+const esc = (s: string) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+/** Inline markup on already-escaped text: `code`, **bold**, *italic*, and http(s)/mailto links. */
+function inline(text: string): string {
+  const codes: string[] = []
+  let s = text.replace(/`([^`]+)`/g, (_m, c: string) => {
+    codes.push(`<code>${c}</code>`)
+    return `\uE000${codes.length - 1}\uE000`
+  })
+  s = s
+    .replace(
+      /\[([^\]]+)\]\(((?:https?:\/\/|mailto:)[^)\s]+)\)/g,
+      (_m, label: string, href: string) => {
+        return `<a href="${href}" target="_blank" rel="noreferrer">${label}</a>`
+      },
+    )
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/(^|[\s(])\*([^*\s][^*]*)\*(?=[\s).,;:!?]|$)/g, '$1<em>$2</em>')
+    .replace(/(^|[\s(])_([^_\s][^_]*)_(?=[\s).,;:!?]|$)/g, '$1<em>$2</em>')
+  return s.replace(/\uE000(\d+)\uE000/g, (_m, i: string) => codes[Number(i)] ?? '')
+}
+
+/**
+ * A small, safe markdown subset for descriptions: paragraphs, headings, bullet and numbered lists, fenced
+ * code, and inline code, bold, italics and links. Everything is HTML-escaped first, and only http(s) and
+ * mailto links are linked, so descriptions from a spec or a sequence can be rendered without trusting them.
+ */
+export function markdownToHtml(src: string | undefined): string {
+  if (!src) return ''
+  const lines = src.replace(/\r\n?/g, '\n').split('\n')
+  const out: string[] = []
+  let para: string[] = []
+  let list: { tag: 'ul' | 'ol'; items: string[] } | undefined
+
+  const flushPara = () => {
+    if (para.length) out.push(`<p>${inline(esc(para.join(' ')))}</p>`)
+    para = []
+  }
+  const flushList = () => {
+    if (list)
+      out.push(
+        `<${list.tag}>${list.items.map((i) => `<li>${inline(esc(i))}</li>`).join('')}</${list.tag}>`,
+      )
+    list = undefined
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] as string
+    if (/^```/.test(line)) {
+      flushPara()
+      flushList()
+      const code: string[] = []
+      i++
+      while (i < lines.length && !/^```/.test(lines[i] as string)) code.push(lines[i++] as string)
+      out.push(`<pre><code>${esc(code.join('\n'))}</code></pre>`)
+      continue
+    }
+    const heading = /^(#{1,4})\s+(.*)$/.exec(line)
+    if (heading) {
+      flushPara()
+      flushList()
+      const level = Math.min(4, (heading[1] as string).length + 1)
+      out.push(`<h${level}>${inline(esc(heading[2] as string))}</h${level}>`)
+      continue
+    }
+    const quote = /^>\s?(.*)$/.exec(line)
+    if (quote) {
+      flushPara()
+      flushList()
+      const text: string[] = [quote[1] as string]
+      while (i + 1 < lines.length && /^>\s?/.test(lines[i + 1] as string))
+        text.push((lines[++i] as string).replace(/^>\s?/, ''))
+      out.push(`<blockquote>${inline(esc(text.join(' ')))}</blockquote>`)
+      continue
+    }
+    const bullet = /^\s*[-*+]\s+(.*)$/.exec(line)
+    const numbered = /^\s*\d+[.)]\s+(.*)$/.exec(line)
+    if (bullet || numbered) {
+      flushPara()
+      const tag = bullet ? 'ul' : 'ol'
+      if (list && list.tag !== tag) flushList()
+      list ??= { tag, items: [] }
+      list.items.push((bullet ?? numbered)?.[1] as string)
+      continue
+    }
+    if (line.trim() === '') {
+      flushPara()
+      flushList()
+      continue
+    }
+    flushList()
+    para.push(line.trim())
+  }
+  flushPara()
+  flushList()
+  return out.join('')
+}
+
+/** Markdown reduced to readable plain text: links keep their label, markers and fences disappear. */
+export function plainText(src: string | undefined): string {
+  if (!src) return ''
+  return src
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/^#{1,6}\s+/gm, '')
+    .replace(/^\s*(?:[-*+]|\d+[.)])\s+/gm, '')
+    .replace(/^>\s?/gm, '')
+    .replace(/[`*]|(^|\s)_|_(?=\s|$)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+export function firstParagraph(src: string | undefined): string {
+  if (!src) return ''
+  return (src.trim().split(/\n\s*\n/)[0] ?? '').replace(/\s*\n\s*/g, ' ').trim()
+}
+
+/** Inline markup only (code, bold, italics, links) in already-safe HTML, for a single line or cell. */
+export function inlineMarkdown(src: string | undefined): string {
+  return src ? inline(esc(src)) : ''
+}
+
+/**
+ * A one-paragraph summary for table cells: inline markdown when it is short, plain text with an ellipsis
+ * when it is long (cutting markdown mid-link would break it).
+ */
+export function inlineSummary(src: string | undefined, max = 300): string {
+  const para = firstParagraph(src)
+  if (!para) return ''
+  const text = plainText(para)
+  return text.length > max ? esc(`${text.slice(0, max - 1).trimEnd()}…`) : inlineMarkdown(para)
+}

package/src/nav.ts

@@ -0,0 +1,118 @@
+import { signal } from '@preact/signals'
+
+export type PanelTab = 'docs' | 'try'
+
+/**
+ * The page is always the catalog; an operation or sequence route opens the side panel on top of it.
+ * `play` is the example to open ('' = the first), `tab` picks Docs or Try (default Try).
+ */
+export type Route =
+  | { kind: 'home' }
+  /** the catalog itself, without the overview: what a phone shows after its splash screen */
+  | { kind: 'browse' }
+  | { kind: 'op'; key: string; play?: string; tab?: PanelTab }
+  | { kind: 'seq'; id: string; play?: string; tab?: PanelTab }
+
+/**
+ * A project with one API needs no service in its links: `#/op/FindPetsByStatus`, not
+ * `#/op/swagger-petstore-openapi-3-0/FindPetsByStatus`. The app names that service once it knows the
+ * registry; a longer link (an older one, or one from a project with several APIs) still opens.
+ */
+let defaultService: string | undefined
+
+export function setDefaultService(name: string | undefined) {
+  defaultService = name
+  if (typeof location !== 'undefined') route.value = parseHash(location.hash)
+}
+
+const keyOut = (key: string) =>
+  defaultService && key.startsWith(`${defaultService}/`)
+    ? key.slice(defaultService.length + 1)
+    : key
+const keyIn = (key: string) =>
+  defaultService && !key.includes('/') ? `${defaultService}/${key}` : key
+/** Slashes read fine in a fragment, so only what would be ambiguous is escaped. */
+const soft = (s: string) => encodeURIComponent(s).replace(/%2F/gi, '/')
+
+export function parseHash(hash: string): Route {
+  const [path = '', query = ''] = hash.split('?')
+  const q = new URLSearchParams(query)
+  const play = q.get('play') ?? undefined
+  const t = q.get('tab')
+  const tab = t === 'docs' || t === 'try' ? t : undefined
+  const op = /^#\/op\/(.+)$/.exec(path)
+  if (op) return { kind: 'op', key: keyIn(decodeURIComponent(op[1] as string)), play, tab }
+  const seq = /^#\/seq\/(.+)$/.exec(path)
+  if (seq) return { kind: 'seq', id: decodeURIComponent(seq[1] as string), play, tab }
+  if (path === '#/browse') return { kind: 'browse' }
+  return { kind: 'home' }
+}
+
+export function hashFor(r: Route): string {
+  if (r.kind === 'home') return '#/'
+  if (r.kind === 'browse') return '#/browse'
+  const base = r.kind === 'op' ? `#/op/${soft(keyOut(r.key))}` : `#/seq/${encodeURIComponent(r.id)}`
+  const q = new URLSearchParams()
+  if (r.play !== undefined) q.set('play', r.play)
+  if (r.tab) q.set('tab', r.tab)
+  const s = q.toString()
+  return s ? `${base}?${s}` : base
+}
+
+/** A phone's home is its splash screen, so closing a panel lands on the list rather than back on it. */
+export const isPhone = () =>
+  typeof matchMedia === 'function' && matchMedia('(max-width: 820px)').matches
+export const pageOf = (_r: Route): Route => (isPhone() ? { kind: 'browse' } : { kind: 'home' })
+
+export const route = signal<Route>(parseHash(typeof location === 'undefined' ? '' : location.hash))
+export const paletteOpen = signal(false)
+/** The catalog's service pill ('' = overview) and filter text. */
+export const catalogService = signal('')
+export const catalogFilter = signal('')
+
+export function go(r: Route) {
+  location.hash = hashFor(r)
+  route.value = r
+}
+
+export interface Entry {
+  route: Route
+  title: string
+  /** group label shown muted, e.g. "pet" */
+  group: string
+  service?: string
+  tag?: string
+  /** operations */
+  method?: string
+  path?: string
+  /** the spec requires credentials */
+  secured?: boolean
+  /** sequences */
+  tags?: string[]
+  /** the flow group heading */
+  flowGroup?: string
+  description?: string
+  /** extra text matched by search, never shown */
+  hay: string
+  kind: 'seq' | 'op'
+}
+
+export function search(entries: Entry[], query: string, limit = 40): Entry[] {
+  const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean)
+  if (terms.length === 0) return entries.slice(0, limit)
+  const scored: [number, Entry][] = []
+  for (const e of entries) {
+    const title = e.title.toLowerCase()
+    const hay = `${title} ${e.group.toLowerCase()} ${e.hay.toLowerCase()}`
+    if (!terms.every((t) => hay.includes(t))) continue
+    // prefer title matches and sequences
+    let score = 0
+    for (const t of terms) score += title.startsWith(t) ? 3 : title.includes(t) ? 2 : 1
+    if (e.kind === 'seq') score += 0.5
+    scored.push([score, e])
+  }
+  return scored
+    .sort((a, b) => b[0] - a[0])
+    .slice(0, limit)
+    .map(([, e]) => e)
+}

package/src/oauth-callback.ts

@@ -0,0 +1,87 @@
+/**
+ * The return leg of a sign-in. The identity provider redirects the popup to a page with `?code=&state=`
+ * (or `?error=`). Run first on boot: when the tab that started the sign-in is waiting for this `state`
+ * it takes the result and this popup closes without drawing the app.
+ *
+ * Two ways to reach the waiting tab, because each survives what the other does not:
+ * - a same-origin `BroadcastChannel`: providers that send `Cross-Origin-Opener-Policy` sever
+ *   `window.opener`, but a channel still connects the two pages;
+ * - `window.opener.postMessage`: a viewer inside an iframe on another site has partitioned storage, so its
+ *   channel never hears a top-level popup, but its window is still the popup's opener.
+ *
+ * A stray visit to a URL that merely looks like a callback is told nobody is waiting and carries on as a
+ * normal page load. The hosted site's own callback page (`landing/oauth/callback/callback.js`) does the same
+ * in plain JS; keep the two in step.
+ */
+export const OAUTH_CHANNEL = 'specbook-oauth'
+
+export type OAuthMessage =
+  | { type: 'callback'; state: string; code?: string; error?: string; description?: string }
+  | { type: 'ack'; state: string }
+
+/** How long a callback page waits to be told that someone is waiting for it. */
+const ACK_WAIT_MS = 1500
+
+export interface CallbackOptions {
+  /**
+   * Remove `?code=&state=` from the address even when no tab claims it (default). An embedded viewer sets
+   * this to false: the page belongs to someone else, and its query may be their own application's sign-in.
+   */
+  stripWhenUnclaimed?: boolean
+}
+
+/** true when this page load was a sign-in's return and has been handed over: do not boot the app. */
+export function handleOAuthCallback(options: CallbackOptions = {}): Promise<boolean> {
+  const strip = options.stripWhenUnclaimed ?? true
+  const here = globalThis.location
+  if (!here || (typeof BroadcastChannel === 'undefined' && !globalThis.opener))
+    return Promise.resolve(false)
+  const q = new URLSearchParams(here.search)
+  const state = q.get('state')
+  if (!state || !(q.has('code') || q.has('error'))) return Promise.resolve(false)
+
+  const message: OAuthMessage = {
+    type: 'callback',
+    state,
+    ...(q.get('code') ? { code: q.get('code') as string } : {}),
+    ...(q.get('error') ? { error: q.get('error') as string } : {}),
+    ...(q.get('error_description') ? { description: q.get('error_description') as string } : {}),
+  }
+  // the code and state are single-use and do not belong in history or a copied address
+  const clean = () => history.replaceState(null, '', here.pathname + here.hash)
+  if (strip) clean()
+
+  return new Promise((resolve) => {
+    const channel =
+      typeof BroadcastChannel === 'undefined' ? null : new BroadcastChannel(OAUTH_CHANNEL)
+    let finished = false
+    const finish = (handled: boolean) => {
+      if (finished) return
+      finished = true
+      clearTimeout(timer)
+      channel?.close()
+      removeEventListener('message', onMessage)
+      resolve(handled)
+    }
+    const claimed = () => {
+      if (finished) return
+      clean()
+      finish(true)
+      document.body.textContent = 'Signed in. You can close this window.'
+      window.close()
+    }
+    const isAck = (d: OAuthMessage | undefined) => d?.type === 'ack' && d.state === state
+    const onMessage = (e: MessageEvent<OAuthMessage>) => {
+      if (e.origin === here.origin && isAck(e.data)) claimed()
+    }
+    const timer = setTimeout(() => finish(false), ACK_WAIT_MS)
+    if (channel) channel.onmessage = (e: MessageEvent<OAuthMessage>) => isAck(e.data) && claimed()
+    addEventListener('message', onMessage)
+    channel?.postMessage(message)
+    try {
+      window.opener?.postMessage(message, here.origin)
+    } catch {
+      /* the opener is cross-origin or gone: the channel is the only way */
+    }
+  })
+}