@specbook/ui 0.0.0-stage → 0.2.0

package/src/oauth.ts

@@ -0,0 +1,194 @@
+import {
+  authorizeUrl,
+  createPkce,
+  newState,
+  OAuthError,
+  parseCallback,
+  parseTokenResponse,
+  tokenRequestFields,
+} from '@specbook/core'
+import { OAUTH_CHANNEL, type OAuthMessage } from './oauth-callback'
+
+/**
+ * Page side of "Sign in": opens the provider in a popup, waits for the return leg
+ * (`oauth-callback.ts`), exchanges the code and hands back the access token. The verifier and the `state`
+ * live in this closure only: not in the URL, not in storage, not in a log.
+ */
+
+/**
+ * The address a provider sends the person back to, and the one to register with it.
+ *
+ * The hosted site declares a stable, unversioned callback page (a `<meta>` its assembly adds to the viewer's
+ * `index.html`), so what people register does not change with the viewer's channel (`/v1/`, `/v2/`).
+ * Anywhere else (a self-hosted copy, an embed on a host page, the dev server) it is the page's own address.
+ */
+export const redirectUri = (): string => {
+  const declared = document
+    .querySelector<HTMLMetaElement>('meta[name="specbook-oauth-callback"]')
+    ?.content.trim()
+  if (declared) {
+    try {
+      return new URL(declared, location.origin).href
+    } catch {
+      /* not an address: fall back to the page's own */
+    }
+  }
+  return `${location.origin}${location.pathname}`
+}
+
+export interface SignInInput {
+  authorizationUrl: string
+  clientId: string
+  scopes: string[]
+  /** posts the form to the token endpoint and returns the parsed response body */
+  exchange(fields: Record<string, string>, signal?: AbortSignal): Promise<unknown>
+  signal?: AbortSignal
+  /** how long to wait for the person to finish (default five minutes) */
+  timeoutMs?: number
+}
+
+/**
+ * Call this straight from a click: the popup has to open before anything is awaited or the browser
+ * blocks it.
+ */
+export async function signIn(
+  i: SignInInput,
+): Promise<{ accessToken: string; expiresIn?: number; scope?: string }> {
+  // opened blank and pointed at the provider once the challenge exists, which keeps Safari's
+  // user-activation rule happy
+  const popup = window.open('', OAUTH_CHANNEL, 'popup,width=520,height=720')
+  if (!popup)
+    throw new OAuthError(
+      'The browser blocked the sign-in window. Allow pop-ups for this page and try again.',
+    )
+
+  const channel = new BroadcastChannel(OAUTH_CHANNEL)
+  let onWindowMessage: ((e: MessageEvent<OAuthMessage>) => void) | undefined
+  try {
+    const { verifier, challenge } = await createPkce()
+    const state = newState()
+    const redirect = redirectUri()
+
+    const returned = new Promise<OAuthMessage & { type: 'callback' }>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new OAuthError('Sign-in timed out. Try again.')),
+        i.timeoutMs ?? 5 * 60_000,
+      )
+      const stop = () => clearTimeout(timer)
+      i.signal?.addEventListener('abort', () => {
+        stop()
+        reject(new OAuthError('Sign-in was cancelled.'))
+      })
+      // the return arrives over the channel or from the popup as its opener; both carry the same message,
+      // and the one that arrives second is a repeat of the first
+      const take = (m: OAuthMessage | undefined, ack: (a: OAuthMessage) => void) => {
+        if (m?.type !== 'callback' || m.state !== state) return
+        stop()
+        ack({ type: 'ack', state })
+        resolve(m)
+      }
+      channel.onmessage = (e: MessageEvent<OAuthMessage>) =>
+        take(e.data, (a) => channel.postMessage(a))
+      onWindowMessage = (e: MessageEvent<OAuthMessage>) => {
+        // only this origin's own callback page: another site cannot hand us a code
+        if (e.origin !== location.origin) return
+        take(e.data, (a) => (e.source as Window | null)?.postMessage(a, location.origin))
+      }
+      addEventListener('message', onWindowMessage)
+    })
+
+    popup.location.href = authorizeUrl({
+      authorizationUrl: i.authorizationUrl,
+      clientId: i.clientId,
+      redirectUri: redirect,
+      scopes: i.scopes,
+      state,
+      challenge,
+    })
+
+    const back = await returned
+    const { code } = parseCallback(
+      {
+        state: back.state,
+        ...(back.code ? { code: back.code } : {}),
+        ...(back.error ? { error: back.error } : {}),
+        ...(back.description ? { error_description: back.description } : {}),
+      },
+      state,
+    )
+    const body = await i.exchange(
+      tokenRequestFields({ code, verifier, clientId: i.clientId, redirectUri: redirect }),
+      i.signal,
+    )
+    return parseTokenResponse(body)
+  } finally {
+    channel.close()
+    if (onWindowMessage) removeEventListener('message', onWindowMessage)
+    try {
+      popup.close()
+    } catch {
+      /* a severed popup cannot be closed from here; the callback page closes itself */
+    }
+  }
+}
+
+// ---- small per-browser conveniences: a client id is public, and an expiry note is not a secret ----
+
+const CLIENTS = 'specbook.oauth.clients.v1'
+const EXPIRY = 'specbook.oauth.expiry.v1'
+
+const readJson = (store: Storage, key: string): Record<string, any> => {
+  try {
+    return JSON.parse(store.getItem(key) ?? '{}')
+  } catch {
+    return {}
+  }
+}
+const writeJson = (store: Storage, key: string, value: unknown) => {
+  try {
+    store.setItem(key, JSON.stringify(value))
+  } catch {
+    /* blocked or full: the page still works without it */
+  }
+}
+
+export const recallClientId = (authorizationUrl: string): string | undefined => {
+  try {
+    return readJson(localStorage, CLIENTS)[authorizationUrl]
+  } catch {
+    return undefined
+  }
+}
+
+export const rememberClientId = (authorizationUrl: string, clientId: string): void => {
+  try {
+    writeJson(localStorage, CLIENTS, {
+      ...readJson(localStorage, CLIENTS),
+      [authorizationUrl]: clientId,
+    })
+  } catch {
+    /* no storage */
+  }
+}
+
+const expiryKey = (origin: string, name: string) => `${origin}\n${name}`
+
+/** Remembered for this tab only, to say "expires in 59 min"; the token itself stays in the secret store. */
+export const noteExpiry = (origin: string, name: string, expiresIn: number | undefined): void => {
+  try {
+    const t = readJson(sessionStorage, EXPIRY)
+    if (expiresIn === undefined) delete t[expiryKey(origin, name)]
+    else t[expiryKey(origin, name)] = Date.now() + expiresIn * 1000
+    writeJson(sessionStorage, EXPIRY, t)
+  } catch {
+    /* no storage */
+  }
+}
+
+export const expiryOf = (origin: string, name: string): number | undefined => {
+  try {
+    return readJson(sessionStorage, EXPIRY)[expiryKey(origin, name)]
+  } catch {
+    return undefined
+  }
+}

package/src/panel/Body.tsx

@@ -0,0 +1,182 @@
+import { type Encoding, fromFormRows, toFormRows } from '@specbook/core'
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
+import { type FieldDoc as Doc, fieldDoc, keyPath, withNote } from '../fielddoc'
+import { type Defs, type JsonSchema, linePaths, pathString } from '../schema'
+import { BodyEditor } from './BodyEditor'
+import { jsonCompletions } from './completions'
+import { type Draft, type FieldRow, gridMode } from './draft'
+import { FieldDoc } from './FieldDoc'
+import { type Graphql, joinGraphql, splitGraphql } from './graphql'
+import { ParamGrid } from './ParamGrid'
+
+interface Props {
+  encoding: Encoding
+  draft: Draft
+  onChange: (d: Draft) => void
+  /** request schema (`{ path, query, headers, data }`) and shared definitions */
+  schema?: JsonSchema
+  defs?: Defs
+  /** dotted body paths that are uploads */
+  files?: string[]
+  /** the project's own notes for body fields, by `data.<path>` */
+  notes?: Map<string, string>
+}
+
+/** Keeps the typed texts locally, so invalid variables JSON isn't rewritten while the user is typing. */
+function GraphqlBody({ draft, onChange }: { draft: Draft; onChange: (d: Draft) => void }) {
+  const [g, setG] = useState(() => splitGraphql(draft.body) as Graphql)
+  const emitted = useRef(draft.body)
+  useEffect(() => {
+    if (draft.body === emitted.current) return
+    const next = splitGraphql(draft.body)
+    if (next) setG(next)
+    emitted.current = draft.body
+  }, [draft.body])
+
+  const set = (part: Partial<Graphql>) => {
+    const next = { ...g, ...part }
+    setG(next)
+    emitted.current = joinGraphql(next)
+    onChange({ ...draft, body: emitted.current })
+  }
+  return (
+    <section class="body" aria-label="Body">
+      <div class="section-head">
+        <h3>Query</h3>
+        <span class="chip">graphql</span>
+      </div>
+      <BodyEditor
+        label="GraphQL query"
+        language="graphql"
+        value={g.query}
+        onChange={(query) => set({ query })}
+      />
+      <div class="section-head">
+        <h3>Variables</h3>
+        <span class="chip">json</span>
+      </div>
+      <BodyEditor
+        label="GraphQL variables"
+        language="json"
+        value={g.variables}
+        onChange={(variables) => set({ variables })}
+      />
+    </section>
+  )
+}
+
+const language = (e: Encoding) => (e === 'graphql' ? 'graphql' : e === 'text' ? 'text' : 'json')
+
+export function Body({ encoding, draft, onChange, schema, defs, files = [], notes }: Props) {
+  const [line, setLine] = useState(0)
+  const paths = useMemo(() => linePaths(draft.body), [draft.body])
+  const documented = encoding === 'json' || encoding === 'form'
+  const doc: Doc | undefined = useMemo(() => {
+    const p = paths[line]
+    return p && documented
+      ? withNote(fieldDoc(schema, defs, p, ['data']), notes, 'data', pathString(p))
+      : undefined
+  }, [paths, line, schema, defs, documented, notes])
+  const complete = useMemo(
+    () =>
+      documented && schema
+        ? (text: string, pos: number) => jsonCompletions(schema, defs, ['data'], text, pos)
+        : undefined,
+    [schema, defs, documented],
+  )
+
+  /** Form bodies convert between the nested JSON and the bracket-key rows when the view is switched. */
+  const switchView = (view: 'json' | 'grid') => {
+    if (view === (draft.formView ?? 'grid')) return
+    if (view === 'grid') {
+      try {
+        onChange({ ...draft, formView: 'grid', fields: toFormRows(JSON.parse(draft.body || '{}')) })
+      } catch {
+        onChange({ ...draft, formView: 'grid' })
+      }
+    } else {
+      onChange({
+        ...draft,
+        formView: 'json',
+        body: JSON.stringify(fromFormRows(draft.fields.filter((r) => !r.file)), null, 2),
+      })
+    }
+  }
+  const viewToggle =
+    encoding === 'form' ? (
+      <fieldset class="seg" aria-label="Body view">
+        {(['json', 'grid'] as const).map((v) => (
+          <button
+            type="button"
+            class={`seg-btn ${(draft.formView ?? 'grid') === v ? 'on' : ''}`}
+            aria-pressed={(draft.formView ?? 'grid') === v}
+            onClick={() => switchView(v)}
+          >
+            {v === 'json' ? 'JSON' : 'Grid'}
+          </button>
+        ))}
+      </fieldset>
+    ) : null
+
+  if (gridMode(draft, encoding) || encoding === 'binary') {
+    const isFile = (k: string) => encoding === 'binary' || files.includes(k.replace(/\[\d+\]/g, ''))
+    const set = (fields: FieldRow[]) => onChange({ ...draft, fields })
+    const fileKeys = (draft.fields.length ? draft.fields.map((r) => r.key) : []).filter(isFile)
+    return (
+      <>
+        {viewToggle && (
+          <div class="section-head">
+            <h3>Body</h3>
+            <span class="chip">{encoding}</span>
+            <span class="spacer" />
+            {viewToggle}
+          </div>
+        )}
+        <ParamGrid
+          title={encoding === 'binary' ? 'File' : 'Body'}
+          bare={!!viewToggle}
+          rows={draft.fields}
+          onChange={set}
+          documented={[...new Set(fileKeys)].map((name) => ({ name, file: true }))}
+          docFor={(k) => withNote(fieldDoc(schema, defs, keyPath(k), ['data']), notes, 'data', k)}
+        />
+      </>
+    )
+  }
+
+  const format = () => {
+    try {
+      onChange({ ...draft, body: JSON.stringify(JSON.parse(draft.body), null, 2) })
+    } catch {
+      /* the invalid-JSON message is shown by the panel */
+    }
+  }
+
+  if (encoding === 'graphql' && splitGraphql(draft.body))
+    return <GraphqlBody draft={draft} onChange={onChange} />
+
+  return (
+    <section class="body" aria-label="Body">
+      <div class="section-head">
+        <h3>Body</h3>
+        <span class="chip">{encoding}</span>
+        <span class="spacer" />
+        {encoding !== 'text' && (
+          <button type="button" class="link" onClick={format}>
+            Format
+          </button>
+        )}
+        {viewToggle}
+      </div>
+      <BodyEditor
+        label="Request body"
+        language={language(encoding === 'form' ? 'json' : encoding)}
+        value={draft.body}
+        onChange={(body) => onChange({ ...draft, body })}
+        onLine={setLine}
+        complete={complete}
+      />
+      {documented && <FieldDoc doc={doc} />}
+    </section>
+  )
+}

package/src/panel/BodyEditor.tsx

@@ -0,0 +1,92 @@
+import { createEditor, type PrismEditor } from 'prism-code-editor'
+import { autoComplete, fuzzyFilter, registerCompletions } from 'prism-code-editor/autocomplete'
+import { defaultKeymap, editHistory, editorCommands } from 'prism-code-editor/commands'
+import { cursorPosition } from 'prism-code-editor/cursor'
+import 'prism-code-editor/languages/json'
+import 'prism-code-editor/languages/graphql'
+import 'prism-code-editor/prism/languages/json'
+import 'prism-code-editor/prism/languages/graphql'
+import { useEffect, useRef } from 'preact/hooks'
+import type { Completions } from './completions'
+
+/** Per-editor completion providers; one global source dispatches to the editor it was asked about. */
+const providers = new WeakMap<PrismEditor, (text: string, pos: number) => Completions | undefined>()
+
+registerCompletions(['json'], {
+  sources: [
+    (ctx, editor) => {
+      const found = providers.get(editor)?.(editor.value, ctx.pos)
+      if (!found) return null
+      return {
+        from: found.from,
+        to: found.to,
+        options: found.options.map((o) => ({
+          ...o,
+          renderDocs: o.doc ? () => [o.doc as string] : undefined,
+        })),
+      }
+    },
+  ],
+})
+
+interface Props {
+  value: string
+  language?: 'json' | 'graphql' | 'text'
+  readOnly?: boolean
+  label: string
+  onChange?: (value: string) => void
+  /** 0-based line the cursor is on */
+  onLine?: (line: number) => void
+  /** schema-driven suggestions for keys and values (JSON bodies only) */
+  complete?: (text: string, pos: number) => Completions | undefined
+}
+
+export function BodyEditor({
+  value,
+  language = 'json',
+  readOnly,
+  label,
+  onChange,
+  onLine,
+  complete,
+}: Props) {
+  const host = useRef<HTMLDivElement>(null)
+  const editor = useRef<PrismEditor | undefined>(undefined)
+  const on = useRef({ onChange, onLine })
+  on.current = { onChange, onLine }
+  const completer = useRef(complete)
+  completer.current = complete
+
+  useEffect(() => {
+    const e = createEditor(
+      host.current,
+      {
+        value,
+        language,
+        readOnly,
+        lineNumbers: false,
+        wordWrap: true,
+        onUpdate: (v) => on.current.onChange?.(v),
+        onSelectionChange: (_s, _v, ed) => on.current.onLine?.(ed.activeLine - 1),
+      },
+      editorCommands(defaultKeymap),
+      editHistory(),
+      ...(complete ? [cursorPosition(), autoComplete({ filter: fuzzyFilter })] : []),
+    )
+    if (complete) providers.set(e, (text, pos) => completer.current?.(text, pos))
+    e.textarea.setAttribute('aria-label', label)
+    editor.current = e
+    return () => e.remove()
+  }, [])
+
+  useEffect(() => {
+    const e = editor.current
+    if (e && e.value !== value) e.setOptions({ value })
+  }, [value])
+
+  useEffect(() => {
+    editor.current?.setOptions({ readOnly, language })
+  }, [readOnly, language])
+
+  return <div class="body-editor" part="editor" ref={host} />
+}

package/src/panel/CodeSample.tsx

@@ -0,0 +1,238 @@
+import {
+  type AuthProfile,
+  type Encoding,
+  type RenderedRequest,
+  render,
+  type SnippetInput,
+  type SnippetLang,
+  snippetLangs,
+  toSnippet,
+} from '@specbook/core'
+import type { ComponentChildren } from 'preact'
+import { useCallback, useEffect, useMemo, useState } from 'preact/hooks'
+import { engine } from '../runtime'
+import { env, version } from '../store'
+import { type Draft, requestParts } from './draft'
+
+const LANG_KEY = 'specbook:code-lang'
+
+function savedLang(): SnippetLang {
+  try {
+    const v = localStorage.getItem(LANG_KEY)
+    if (v === 'curl' || v === 'fetch') return v
+  } catch {
+    /* optional */
+  }
+  return 'curl'
+}
+
+type Applied = { headers?: Record<string, string>; query?: Record<string, string> } | undefined
+
+interface Props {
+  service: string
+  /** auth profile to apply: its name, `service` for the service's default, or nothing */
+  profile?: string
+  /** shown as a hint under the sample */
+  secured?: boolean
+  /** builds the request; keep it stable (useCallback) so values from faker do not change per render */
+  make: (base: string, applied: Applied) => SnippetInput
+  /** the request as it actually went out, offered as a third view once there is one */
+  sent?: ComponentChildren
+}
+
+/** cURL / Node fetch tabs with a copy button, for a request described by `make`. */
+export function CodeSample({ service, profile, secured, make, sent }: Props) {
+  const [view, setView] = useState<SnippetLang | 'sent'>(savedLang)
+  const lang: SnippetLang = view === 'sent' ? 'curl' : view
+  const [copied, setCopied] = useState(false)
+  const [base, setBase] = useState<string>()
+  const [applied, setApplied] = useState<Applied>()
+
+  useEffect(() => {
+    let live = true
+    engine.config(version.value).then((c) => {
+      if (!live) return
+      const svc = c.services?.[service]
+      const urls = svc?.baseUrl ?? {}
+      // the environment being used, so a sample for the sandbox points at the sandbox
+      setBase(urls[env.value] ?? urls.live ?? Object.values(urls)[0])
+      const name = profile === 'service' ? svc?.auth : profile
+      setApplied(name ? (c.auth?.[name] as AuthProfile | undefined)?.apply : undefined)
+    })
+    return () => {
+      live = false
+    }
+  }, [service, profile, env.value])
+
+  const built = useMemo<{ text?: string; error?: string }>(() => {
+    try {
+      return { text: toSnippet(lang, make(base ?? 'https://api.example.com', applied)) }
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) }
+    }
+  }, [make, lang, base, applied])
+
+  const pick = (l: SnippetLang | 'sent') => {
+    setView(l)
+    if (l === 'sent') return
+    try {
+      localStorage.setItem(LANG_KEY, l)
+    } catch {
+      /* optional */
+    }
+  }
+
+  const copy = async () => {
+    if (!built.text) return
+    try {
+      await navigator.clipboard.writeText(built.text)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1500)
+    } catch {
+      /* clipboard blocked: the text is selectable */
+    }
+  }
+
+  return (
+    <div class="code-sample">
+      <div class="code-head">
+        <fieldset class="seg" aria-label="Code sample">
+          {snippetLangs.map((l) => (
+            <button
+              type="button"
+              aria-pressed={view === l.id}
+              class={`seg-btn ${view === l.id ? 'on' : ''}`}
+              onClick={() => pick(l.id)}
+            >
+              {l.label}
+            </button>
+          ))}
+          {sent !== undefined && (
+            <button
+              type="button"
+              aria-pressed={view === 'sent'}
+              class={`seg-btn ${view === 'sent' ? 'on' : ''}`}
+              onClick={() => pick('sent')}
+            >
+              Sent
+            </button>
+          )}
+        </fieldset>
+        <span class="spacer" />
+        {view !== 'sent' && (
+          <button type="button" class="btn small" onClick={copy} disabled={!built.text}>
+            {copied ? 'Copied' : 'Copy'}
+          </button>
+        )}
+      </div>
+      {view === 'sent' ? (
+        sent
+      ) : built.error ? (
+        <p class="muted">{built.error}</p>
+      ) : (
+        <pre class="code-block" part="code">
+          <code>{built.text}</code>
+        </pre>
+      )}
+      {view !== 'sent' && secured && (
+        <p class="muted small">Secrets are read from environment variables; set them first.</p>
+      )}
+    </div>
+  )
+}
+
+interface DraftProps {
+  service: string
+  method: string
+  /** the operation's path template, e.g. /pets/{petId} */
+  path: string
+  draft: Draft
+  encoding: Encoding
+  vars: Record<string, string>
+  secured?: boolean
+  sent?: ComponentChildren
+}
+
+/** The sample for the request as currently edited in the panel. */
+export function DraftCodeSample({
+  service,
+  method,
+  path,
+  draft,
+  encoding,
+  vars,
+  secured,
+  sent,
+}: DraftProps) {
+  const make = useCallback(
+    (base: string, applied: Applied): SnippetInput => {
+      const parts = requestParts(draft, encoding)
+      const raw = {
+        path: parts.path ?? {},
+        query: parts.query ?? {},
+        headers: parts.headers ?? {},
+        data: parts.data,
+      }
+      let r = raw
+      try {
+        r = render(raw, vars)
+      } catch {
+        /* a variable is still unset: show the placeholders as they are */
+      }
+      const url = path.replace(/\{([^}]+)\}/g, (m, n: string) => {
+        const v = (r.path as Record<string, unknown>)[n]
+        return v === undefined || v === '' ? m : encodeURIComponent(String(v))
+      })
+      return {
+        method,
+        url: `${base.replace(/\/+$/, '')}${url}`,
+        query: { ...(applied?.query ?? {}), ...(r.query as Record<string, string | string[]>) },
+        headers: { ...(applied?.headers ?? {}), ...(r.headers as Record<string, string>) },
+        body: r.data,
+        encoding,
+      }
+    },
+    [draft, encoding, vars, method, path],
+  )
+  return (
+    <CodeSample
+      service={service}
+      profile={secured ? 'service' : undefined}
+      secured={secured}
+      make={make}
+      sent={sent}
+    />
+  )
+}
+
+/** The sample for a request a sequence step recorded (placeholders for secrets and session values kept). */
+export function StepCodeSample({
+  request,
+  encoding,
+  sent,
+}: {
+  request: RenderedRequest
+  encoding: Encoding
+  sent?: ComponentChildren
+}) {
+  const make = useCallback(
+    (base: string, applied: Applied): SnippetInput => ({
+      method: request.method,
+      url: `${base.replace(/\/+$/, '')}${request.url}`,
+      query: { ...(applied?.query ?? {}), ...request.query },
+      headers: { ...(applied?.headers ?? {}), ...request.headers },
+      body: request.body,
+      encoding,
+    }),
+    [request, encoding],
+  )
+  return (
+    <CodeSample
+      service={request.service}
+      profile={request.profile}
+      secured={!!request.profile}
+      make={make}
+      sent={sent}
+    />
+  )
+}