@specbook/ui 0.1.0 → 0.3.0

package/src/environment-list.ts

@@ -0,0 +1,16 @@
+import { engine } from './runtime'
+import { environmentNote, environmentRisk, environments, envVarsVersion, version } from './store'
+
+/** Reads the environment list, risks and notes again (after one is made or removed) and tells dependents. */
+export async function refreshEnvironments(): Promise<void> {
+  const v = version.value
+  const [names, risks, notes] = await Promise.all([
+    engine.environments(v),
+    engine.environmentRisks(v),
+    engine.environmentNotes(v),
+  ])
+  environments.value = names
+  environmentRisk.value = risks
+  environmentNote.value = notes
+  envVarsVersion.value += 1
+}

package/src/main.tsx

@@ -1,5 +1,7 @@
+import { loadManifests } from 'virtual:specbook/registry'
 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'
@@ -9,7 +11,18 @@ import './styles/app.css'
 import './styles/panel.css'
 
 applyTheme()
-render(<App />, document.getElementById('app') as HTMLElement)
+// 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(async (handled) => {
+  if (handled) return
+  // a built project starts with its services' lists not loaded: fetch them, then draw the app. The app's own code
+  // is part of this page's static imports, so it loads alongside, not after (an embed fetches only the lists it needs)
+  await loadManifests()
+  render(<App />, document.getElementById('app') as HTMLElement)
+})
 
 if (import.meta.hot) {
   import.meta.hot.on('specbook:registry-changed', () => location.reload())

package/src/nav.ts

@@ -70,7 +70,15 @@ export const paletteOpen = signal(false)
 export const catalogService = signal('')
 export const catalogFilter = signal('')
 
+let navigator: ((r: Route) => void) | undefined
+
+/** A host that is not the app (an embed) takes links itself instead of writing the page's address. */
+export const setNavigator = (fn: ((r: Route) => void) | undefined) => {
+  navigator = fn
+}
+
 export function go(r: Route) {
+  if (navigator) return navigator(r)
   location.hash = hashFor(r)
   route.value = r
 }
@@ -88,13 +96,15 @@ export interface Entry {
   /** the spec requires credentials */
   secured?: boolean
   /** sequences */
+  /** flows and requests */
   tags?: string[]
   /** the flow group heading */
   flowGroup?: string
   description?: string
   /** extra text matched by search, never shown */
   hay: string
-  kind: 'seq' | 'op'
+  /** `req`: a saved request, which opens its operation on that request */
+  kind: 'seq' | 'op' | 'req'
 }
 
 export function search(entries: Entry[], query: string, limit = 40): Entry[] {
@@ -109,6 +119,7 @@ export function search(entries: Entry[], query: string, limit = 40): Entry[] {
     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
+    if (e.kind === 'req') score += 0.4
     scored.push([score, e])
   }
   return scored

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 */
+    }
+  })
+}

package/src/oauth.ts

@@ -0,0 +1,195 @@
+import {
+  authorizeUrl,
+  createPkce,
+  newState,
+  OAuthError,
+  parseCallback,
+  parseTokenResponse,
+  tokenRequestFields,
+} from '@specbook/core'
+import { OAUTH_CHANNEL, type OAuthMessage } from './oauth-callback'
+import { kv, type Store } from './storage'
+
+/**
+ * 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: Store, key: string): Record<string, any> => {
+  try {
+    return JSON.parse(store.getItem(key) ?? '{}')
+  } catch {
+    return {}
+  }
+}
+const writeJson = (store: Store, 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(kv.local, CLIENTS)[authorizationUrl]
+  } catch {
+    return undefined
+  }
+}
+
+export const rememberClientId = (authorizationUrl: string, clientId: string): void => {
+  try {
+    writeJson(kv.local, CLIENTS, {
+      ...readJson(kv.local, 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(kv.session, EXPIRY)
+    if (expiresIn === undefined) delete t[expiryKey(origin, name)]
+    else t[expiryKey(origin, name)] = Date.now() + expiresIn * 1000
+    writeJson(kv.session, EXPIRY, t)
+  } catch {
+    /* no storage */
+  }
+}
+
+export const expiryOf = (origin: string, name: string): number | undefined => {
+  try {
+    return readJson(kv.session, EXPIRY)[expiryKey(origin, name)]
+  } catch {
+    return undefined
+  }
+}

package/src/panel/Body.tsx

@@ -20,10 +20,20 @@ interface Props {
   files?: string[]
   /** the project's own notes for body fields, by `data.<path>` */
   notes?: Map<string, string>
+  /** shown, not edited */
+  readOnly?: boolean
 }
 
 /** 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 }) {
+function GraphqlBody({
+  draft,
+  onChange,
+  readOnly,
+}: {
+  draft: Draft
+  onChange: (d: Draft) => void
+  readOnly?: boolean
+}) {
   const [g, setG] = useState(() => splitGraphql(draft.body) as Graphql)
   const emitted = useRef(draft.body)
   useEffect(() => {
@@ -46,6 +56,7 @@ function GraphqlBody({ draft, onChange }: { draft: Draft; onChange: (d: Draft) =
         <span class="chip">graphql</span>
       </div>
       <BodyEditor
+        readOnly={readOnly}
         label="GraphQL query"
         language="graphql"
         value={g.query}
@@ -56,6 +67,7 @@ function GraphqlBody({ draft, onChange }: { draft: Draft; onChange: (d: Draft) =
         <span class="chip">json</span>
       </div>
       <BodyEditor
+        readOnly={readOnly}
         label="GraphQL variables"
         language="json"
         value={g.variables}
@@ -67,7 +79,16 @@ function GraphqlBody({ draft, onChange }: { draft: Draft; onChange: (d: Draft) =
 
 const language = (e: Encoding) => (e === 'graphql' ? 'graphql' : e === 'text' ? 'text' : 'json')
 
-export function Body({ encoding, draft, onChange, schema, defs, files = [], notes }: Props) {
+export function Body({
+  encoding,
+  draft,
+  onChange,
+  schema,
+  defs,
+  files = [],
+  notes,
+  readOnly,
+}: Props) {
   const [line, setLine] = useState(0)
   const paths = useMemo(() => linePaths(draft.body), [draft.body])
   const documented = encoding === 'json' || encoding === 'form'
@@ -136,6 +157,7 @@ export function Body({ encoding, draft, onChange, schema, defs, files = [], note
           title={encoding === 'binary' ? 'File' : 'Body'}
           bare={!!viewToggle}
           rows={draft.fields}
+          readOnly={readOnly}
           onChange={set}
           documented={[...new Set(fileKeys)].map((name) => ({ name, file: true }))}
           docFor={(k) => withNote(fieldDoc(schema, defs, keyPath(k), ['data']), notes, 'data', k)}
@@ -153,7 +175,7 @@ export function Body({ encoding, draft, onChange, schema, defs, files = [], note
   }
 
   if (encoding === 'graphql' && splitGraphql(draft.body))
-    return <GraphqlBody draft={draft} onChange={onChange} />
+    return <GraphqlBody draft={draft} onChange={onChange} readOnly={readOnly} />
 
   return (
     <section class="body" aria-label="Body">
@@ -161,7 +183,7 @@ export function Body({ encoding, draft, onChange, schema, defs, files = [], note
         <h3>Body</h3>
         <span class="chip">{encoding}</span>
         <span class="spacer" />
-        {encoding !== 'text' && (
+        {encoding !== 'text' && !readOnly && (
           <button type="button" class="link" onClick={format}>
             Format
           </button>
@@ -169,6 +191,7 @@ export function Body({ encoding, draft, onChange, schema, defs, files = [], note
         {viewToggle}
       </div>
       <BodyEditor
+        readOnly={readOnly}
         label="Request body"
         language={language(encoding === 'form' ? 'json' : encoding)}
         value={draft.body}

package/src/panel/Checks.tsx

@@ -0,0 +1,79 @@
+import { type AssertionResult, type DiffLine, diffAssertion } from '@specbook/core'
+import { registry } from '../runtime'
+
+/** The project file an assertion failed in, as `file:line`, when its stack names one of the project's requests or flows. */
+export function whereOf(a: AssertionResult): string | undefined {
+  const loc = a.location
+  if (!loc) return undefined
+  const files = [...registry.requests, ...registry.sequences].map((e) => e.file)
+  // the stack names a file by its address in the page; the longest project path it ends with is the file
+  const hit = files.filter((f) => loc.file.includes(f)).sort((a, b) => b.length - a.length)[0]
+  return hit ? `${hit}:${loc.line}` : undefined
+}
+
+const GUTTER = { expected: '−', received: '+', same: ' ', skip: ' ' } as const
+const SPOKEN = { expected: 'expected', received: 'received', same: '', skip: '' } as const
+
+function Diff({ lines }: { lines: DiffLine[] }) {
+  return (
+    // biome-ignore lint/a11y/noNoninteractiveTabindex: a block that scrolls sideways must be reachable by keyboard
+    <section class="diff" tabIndex={0} aria-label="Expected and received values">
+      {lines.map((l) => (
+        <div class={`diff-line diff-${l.kind}`}>
+          <span class="diff-gutter" aria-hidden="true">
+            {GUTTER[l.kind]}
+          </span>
+          {SPOKEN[l.kind] && <span class="visually-hidden">{SPOKEN[l.kind]}: </span>}
+          <span class="diff-text">{l.text}</span>
+        </div>
+      ))}
+    </section>
+  )
+}
+
+/** One failed assertion: what it checks, what was expected and received as a colored diff, and where it is. */
+export function Failure({ a }: { a: AssertionResult }) {
+  const lines = diffAssertion(a)
+  const where = whereOf(a)
+  return (
+    <fieldset class="check-fail">
+      <legend class="visually-hidden">Failed check: {a.label}</legend>
+      <div class="check-head">
+        <span class="check-mark" aria-hidden="true">
+          ✗
+        </span>
+        <strong>{a.label}</strong>
+        <span class="chip">{a.operator}</span>
+      </div>
+      {lines.length > 0 && (
+        <>
+          <div class="diff-legend" aria-hidden="true">
+            <span class="diff-key diff-expected">− Expected</span>
+            <span class="diff-key diff-received">+ Received</span>
+          </div>
+          <Diff lines={lines} />
+        </>
+      )}
+      {where && <div class="check-where">at {where}</div>}
+    </fieldset>
+  )
+}
+
+/** The checks of a step: passing ones in a line, failing ones as cards with their diff. */
+export function Checks({ assertions }: { assertions: AssertionResult[] }) {
+  return (
+    <ul class="checks">
+      {assertions.map((a) =>
+        a.pass ? (
+          <li class="ok">
+            <span class="tick">✓</span> {a.label}
+          </li>
+        ) : (
+          <li class="bad">
+            <Failure a={a} />
+          </li>
+        ),
+      )}
+    </ul>
+  )
+}

package/src/panel/CodeSample.tsx

@@ -11,14 +11,15 @@ import {
 import type { ComponentChildren } from 'preact'
 import { useCallback, useEffect, useMemo, useState } from 'preact/hooks'
 import { engine } from '../runtime'
-import { version } from '../store'
+import { kv } from '../storage'
+import { env, envVarsVersion, 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)
+    const v = kv.local.getItem(LANG_KEY)
     if (v === 'curl' || v === 'fetch') return v
   } catch {
     /* optional */
@@ -50,18 +51,25 @@ export function CodeSample({ service, profile, secured, make, sent }: Props) {
 
   useEffect(() => {
     let live = true
-    engine.config(version.value).then((c) => {
-      if (!live) return
+    engine.config(version.value).then(async (c) => {
       const svc = c.services?.[service]
-      const urls = svc?.baseUrl ?? {}
-      setBase(urls.live ?? Object.values(urls)[0])
+      const addressIn = (e: string) =>
+        engine.baseUrlOf(service, e, version.value).catch(() => undefined)
+      // the environment being used, so a sample for the sandbox points at the sandbox; mock, or an
+      // environment with no address, uses `live`, else the first address the service lists
+      let address = env.value === 'mock' ? undefined : await addressIn(env.value)
+      address ??= await addressIn('live')
+      if (!address && svc && typeof svc.baseUrl === 'object')
+        address = Object.values(svc.baseUrl)[0]
+      if (!live) return
+      setBase(address)
       const name = profile === 'service' ? svc?.auth : profile
       setApplied(name ? (c.auth?.[name] as AuthProfile | undefined)?.apply : undefined)
     })
     return () => {
       live = false
     }
-  }, [service, profile])
+  }, [service, profile, env.value, envVarsVersion.value])
 
   const built = useMemo<{ text?: string; error?: string }>(() => {
     try {
@@ -75,7 +83,7 @@ export function CodeSample({ service, profile, secured, make, sent }: Props) {
     setView(l)
     if (l === 'sent') return
     try {
-      localStorage.setItem(LANG_KEY, l)
+      kv.local.setItem(LANG_KEY, l)
     } catch {
       /* optional */
     }