@specbook/ui 0.0.0-stage → 0.2.0

package/src/panel/OAuthSignIn.tsx

@@ -0,0 +1,163 @@
+import { isDiscovery, type OAuthSettings } from '@specbook/core'
+import { useEffect, useRef, useState } from 'preact/hooks'
+import { noteExpiry, recallClientId, redirectUri, rememberClientId, signIn } from '../oauth'
+import { engine } from '../runtime'
+import { secretStore } from '../secrets'
+import { env, version } from '../store'
+
+type Status = { kind: 'idle' } | { kind: 'busy' } | { kind: 'error'; message: string }
+
+interface Endpoints {
+  authorizationUrl: string
+  scopes: Record<string, string>
+}
+
+/**
+ * "Sign in" for a scheme with an authorization code flow, or an OpenID Connect provider. The token lands
+ * in the same tab-scoped store, bound to the API's origin, that a pasted value would, so everything
+ * downstream is unchanged. A failure or a cancel only reports itself: the paste field next to this stays
+ * usable.
+ */
+export function OAuthSignIn({
+  service,
+  profile,
+  origin,
+  secret,
+  oauth,
+  onSignedIn,
+}: {
+  service: string
+  profile: string
+  origin: string
+  /** the secret the profile's `apply` reads; the token is stored under it */
+  secret: string
+  oauth: OAuthSettings
+  onSignedIn(): void
+}) {
+  // one provider, one remembered client id: keyed by the address that identifies the provider
+  const providerKey = isDiscovery(oauth) ? oauth.openIdConnectUrl : oauth.authorizationUrl
+  const [clientId, setClientId] = useState(
+    () => oauth.clientId ?? recallClientId(providerKey) ?? '',
+  )
+  const [endpoints, setEndpoints] = useState<Endpoints | undefined>(undefined)
+  const [picked, setPicked] = useState<string[]>([])
+  const [status, setStatus] = useState<Status>({ kind: 'idle' })
+  const abort = useRef<AbortController | undefined>(undefined)
+  const busy = status.kind === 'busy'
+  const [attempt, setAttempt] = useState(0)
+
+  // The provider's endpoints are settled before a click: the popup has to open from the click itself,
+  // and an OpenID Connect provider has to be asked where it is first.
+  useEffect(() => {
+    let on = true
+    setEndpoints(undefined)
+    setStatus((s) => (s.kind === 'busy' ? s : { kind: 'idle' }))
+    engine
+      .oauthEndpoints({ env: env.value, version: version.value, profile })
+      .then((found) => {
+        if (!on) return
+        setEndpoints(found)
+        // OpenID Connect asks for `openid` alone until more is ticked; a plain OAuth scheme lists what
+        // its operations need, so those are all ticked
+        setPicked(isDiscovery(oauth) ? ['openid'] : Object.keys(found.scopes))
+      })
+      .catch((e: unknown) => {
+        if (on) setStatus({ kind: 'error', message: e instanceof Error ? e.message : String(e) })
+      })
+    return () => {
+      on = false
+    }
+  }, [profile, env.value, version.value, attempt])
+
+  const scopeNames = Object.keys(endpoints?.scopes ?? {})
+
+  // called from the click itself: the popup must open before anything is awaited
+  const start = () => {
+    if (!endpoints) return setAttempt((n) => n + 1)
+    const id = clientId.trim()
+    if (!id)
+      return setStatus({ kind: 'error', message: 'Enter the client id registered for this page.' })
+    const ctl = new AbortController()
+    abort.current = ctl
+    setStatus({ kind: 'busy' })
+    rememberClientId(providerKey, id)
+    signIn({
+      authorizationUrl: endpoints.authorizationUrl,
+      clientId: id,
+      scopes: picked,
+      signal: ctl.signal,
+      exchange: (fields, signal) =>
+        engine.oauthExchange({ env: env.value, version: version.value, profile, fields, signal }),
+    })
+      .then((token) => {
+        secretStore.set(origin, secret, token.accessToken)
+        noteExpiry(origin, secret, token.expiresIn)
+        setStatus({ kind: 'idle' })
+        onSignedIn()
+      })
+      .catch((e: unknown) =>
+        setStatus({ kind: 'error', message: e instanceof Error ? e.message : String(e) }),
+      )
+  }
+
+  const failedLookup = !endpoints && status.kind === 'error'
+  // the idle line (the address to register) is the only one a phone can do without
+  const hint = !busy && status.kind !== 'error' && !!endpoints
+  return (
+    <span class="needs-var oauth-signin">
+      <input
+        type="text"
+        autocomplete="off"
+        aria-label={`Client id for ${service}`}
+        placeholder="client id"
+        value={clientId}
+        disabled={busy}
+        onInput={(e) => setClientId((e.target as HTMLInputElement).value)}
+      />
+      {busy ? (
+        <button type="button" class="link" onClick={() => abort.current?.abort()}>
+          Cancel
+        </button>
+      ) : (
+        <button type="button" class="btn" disabled={!endpoints && !failedLookup} onClick={start}>
+          {failedLookup ? 'Try again' : 'Sign in'}
+        </button>
+      )}
+      {scopeNames.length > 0 && (
+        <details>
+          <summary class="muted small">
+            Scopes ({picked.length} of {scopeNames.length})
+          </summary>
+          {scopeNames.map((s) => (
+            <label class="small" title={endpoints?.scopes[s] || undefined}>
+              <input
+                type="checkbox"
+                checked={picked.includes(s)}
+                disabled={busy}
+                onChange={(e) =>
+                  setPicked((p) =>
+                    (e.target as HTMLInputElement).checked ? [...p, s] : p.filter((x) => x !== s),
+                  )
+                }
+              />{' '}
+              <code>{s}</code>
+            </label>
+          ))}
+        </details>
+      )}
+      <span
+        class={`muted small oauth-status ${hint ? 'oauth-hint' : ''}`}
+        role="status"
+        aria-live="polite"
+      >
+        {busy
+          ? 'Waiting for the sign-in window…'
+          : status.kind === 'error'
+            ? status.message
+            : !endpoints
+              ? 'Looking up the provider…'
+              : `Register this redirect URI with the provider: ${redirectUri()}`}
+      </span>
+    </span>
+  )
+}

package/src/panel/OperationDocs.tsx

@@ -0,0 +1,181 @@
+import { useEffect, useState } from 'preact/hooks'
+import type { Variant } from '../engine'
+import { markdownToHtml } from '../markdown'
+import { registry } from '../runtime'
+import type { Defs, JsonSchema } from '../schema'
+import { unwrap } from '../schema'
+import { statusClass, statusName } from '../status'
+import { FieldTable } from './FieldTable'
+import { useOperationNotes } from './fieldnotes'
+
+export interface DocOp {
+  id: string
+  method: string
+  path: string
+  summary?: string
+  tags: string[]
+  statuses: number[]
+}
+
+interface LongDocs {
+  description?: string
+  examples: { name: string; title: string; source: string }[]
+}
+
+const SECTIONS = [
+  ['path', 'Path'],
+  ['query', 'Query'],
+  ['headers', 'Headers'],
+] as const
+
+/** Everything the page shows below its header, fetched together so the page is laid out once. */
+interface Loaded {
+  long?: LongDocs
+  req?: JsonSchema
+  defs?: Defs
+  /** a saved request's own markdown (`<name>.req.md` beside its `.req.ts`), by file */
+  saved: Record<string, string>
+}
+
+const soft = <T,>(p: Promise<T> | undefined): Promise<T | undefined> =>
+  (p ?? Promise.resolve(undefined)).catch(() => undefined)
+
+function loadAll(key: string, service: string, files: string[]): Promise<Loaded> {
+  return Promise.all([
+    soft(registry.operationDocs[key]?.().then((m: { default: LongDocs }) => m.default)),
+    soft(registry.schemas[key]?.().then((m: { default: JsonSchema }) => m.default)),
+    soft(registry.definitions[service]?.().then((m: { default: Defs }) => m.default)),
+    Promise.all(files.map((f) => soft(registry.docs.find((d) => d.requestFile === f)?.load()))),
+  ]).then(([long, req, defs, notes]) => ({
+    long,
+    req,
+    defs,
+    saved: Object.fromEntries(files.flatMap((f, i) => (notes[i] ? [[f, notes[i] as string]] : []))),
+  }))
+}
+
+/** A saved request's own markdown (`<name>.req.md` beside its `.req.ts`), when it has one. */
+function SavedRequestNote({ variant, html }: { variant: Variant; html?: string }) {
+  if (!html) return null
+  return (
+    <section class="saved-note-doc">
+      <h2>
+        Saved request <code>{variant.name}</code>
+      </h2>
+      <div class="doc-custom" dangerouslySetInnerHTML={{ __html: html }} />
+    </section>
+  )
+}
+
+export function OperationDocs({
+  service,
+  op,
+  variants = [],
+  onTry,
+}: {
+  service: string
+  op: DocOp
+  variants?: Variant[]
+  /** open the Try tab, optionally on a named example */
+  onTry: (example?: string) => void
+}) {
+  const key = `${service}/${op.id}`
+  const [loaded, setLoaded] = useState<Loaded>()
+  const files = variants.map((v) => v.file)
+  const fileKey = files.join('\n')
+
+  useEffect(() => {
+    let live = true
+    setLoaded(undefined)
+    loadAll(key, service, fileKey ? fileKey.split('\n') : []).then((l) => live && setLoaded(l))
+    return () => {
+      live = false
+    }
+  }, [key, service, fileKey])
+
+  const page = useOperationNotes(key)
+  // the header is there at once; everything below it appears together once it has all arrived
+  const ready = !!loaded && page.loaded
+  const { long, req, defs } = loaded ?? { saved: {} }
+  const root = req ? unwrap(req, defs) : undefined
+  const section = (name: string) => root?.properties?.[name] as JsonSchema | undefined
+  const body = section('data')
+
+  return (
+    <article class="doc" data-op={key}>
+      <div class="doc-intro">
+        <span class={`method ${op.method}`}>{op.method}</span> <code>{op.path}</code>
+        <span class="spacer" />
+        <button type="button" class="btn primary" onClick={() => onTry()}>
+          Try it
+        </button>
+      </div>
+
+      {ready && (
+        <>
+          {/* the spec's own text first; the project's page follows it, or stands in for it with `replace: true` */}
+          {!(page.found && page.replace) && long?.description && (
+            <div
+              class="doc-custom"
+              dangerouslySetInnerHTML={{ __html: markdownToHtml(long.description) }}
+            />
+          )}
+          {page.intro && (
+            <div
+              class={`doc-custom ${page.replace ? '' : 'doc-project'}`}
+              dangerouslySetInnerHTML={{ __html: page.intro }}
+            />
+          )}
+
+          {variants.map((v) => (
+            <SavedRequestNote key={v.file} variant={v} html={loaded?.saved[v.file]} />
+          ))}
+
+          {SECTIONS.map(([k, title]) =>
+            section(k) ? (
+              <section>
+                <h2>{title} parameters</h2>
+                <FieldTable schema={section(k)} defs={defs} section={k} notes={page.notes} />
+              </section>
+            ) : null,
+          )}
+
+          {body && (
+            <section>
+              <h2>Request body</h2>
+              <FieldTable schema={body} defs={defs} section="data" notes={page.notes} />
+            </section>
+          )}
+
+          {op.statuses.length > 0 && (
+            <section>
+              <h2>Responses</h2>
+              <ul class="statuses">
+                {op.statuses.map((s) => (
+                  <li>
+                    <span class={`state-badge ${statusClass(s)}`}>{s}</span> {statusName(s)}
+                  </li>
+                ))}
+              </ul>
+            </section>
+          )}
+
+          {(long?.examples.length ?? 0) > 1 && (
+            <section>
+              <h2>Examples</h2>
+              <ul class="examples">
+                {long?.examples.map((e) => (
+                  <li>
+                    <button type="button" class="link" onClick={() => onTry(e.name)}>
+                      ▶ {e.title}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          )}
+        </>
+      )}
+    </article>
+  )
+}

package/src/panel/Panel.tsx

@@ -0,0 +1,197 @@
+import type { ComponentChildren } from 'preact'
+import { useEffect, useLayoutEffect, useRef } from 'preact/hooks'
+import { env, environmentNote, environments } from '../store'
+
+interface Props {
+  title: string
+  subtitle?: string
+  /** the body fills the panel and manages its own scrolling */
+  flush?: boolean
+  /** dims the page and traps focus (embeds); the standalone site leaves its list usable beside the panel */
+  modal?: boolean
+  onPrev?: () => void
+  onNext?: () => void
+  onClose: () => void
+  children: ComponentChildren
+}
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/** The three-quarter sheet from the right where requests and sequences run. */
+export function Panel({
+  title,
+  subtitle,
+  flush,
+  modal = true,
+  onPrev,
+  onNext,
+  onClose,
+  children,
+}: Props) {
+  const aside = useRef<HTMLElement>(null)
+
+  useEffect(() => {
+    const root = aside.current?.getRootNode() as Document | ShadowRoot
+    const before = root?.activeElement as HTMLElement | null
+    if (modal) aside.current?.focus()
+    return () => before?.focus?.()
+  }, [modal])
+
+  // The keyboard hides the lower half of a phone's screen and iOS does not reliably scroll a field in
+  // a fixed panel above it. While a text field is focused its scroller gets room under the content,
+  // and the field is placed near the top of the panel, which the keyboard never covers.
+  useEffect(() => {
+    const el = aside.current
+    if (!el || typeof matchMedia === 'undefined') return
+    const phone = matchMedia('(max-width: 820px)')
+    const FIELD = 'input:not([type="checkbox"]):not([type="radio"]):not([type="file"]), textarea'
+    let padded: { box: HTMLElement; was: string } | undefined
+    let timers: number[] = []
+    const scroller = (from: HTMLElement) => {
+      for (let n = from.parentElement; n && n !== el; n = n.parentElement) {
+        const y = getComputedStyle(n).overflowY
+        if (y === 'auto' || y === 'scroll') return n
+      }
+      return null
+    }
+    const place = (field: HTMLElement) => {
+      const box = scroller(field)
+      if (!box) return
+      // measured against what is visible: iOS pans its visual viewport under the keyboard
+      const vv = typeof visualViewport === 'undefined' ? undefined : visualViewport
+      const top = vv?.offsetTop ?? 0
+      const height = vv?.height ?? innerHeight
+      const at = field.getBoundingClientRect().top
+      const want = top + height * 0.2
+      if (at > top + height * 0.4 || at < top) box.scrollTop += at - want
+    }
+    const focusin = (e: Event) => {
+      const field = e.target as HTMLElement
+      if (!phone.matches || !field.matches?.(FIELD)) return
+      const box = scroller(field)
+      if (box && padded?.box !== box) {
+        if (padded) padded.box.style.paddingBottom = padded.was
+        padded = { box, was: box.style.paddingBottom }
+        box.style.paddingBottom = '70vh'
+      }
+      // the keyboard animates in; place the field as it opens and again once it has settled
+      for (const t of timers) clearTimeout(t)
+      timers = [0, 150, 400, 800].map((ms) => window.setTimeout(() => place(field), ms))
+    }
+    const focusout = () => {
+      timers.push(
+        window.setTimeout(() => {
+          const at = (el.getRootNode() as Document | ShadowRoot).activeElement
+          if (at?.matches?.(FIELD) || !padded) return
+          padded.box.style.paddingBottom = padded.was
+          padded = undefined
+        }, 200),
+      )
+    }
+    el.addEventListener('focusin', focusin)
+    el.addEventListener('focusout', focusout)
+    return () => {
+      el.removeEventListener('focusin', focusin)
+      el.removeEventListener('focusout', focusout)
+      for (const t of timers) clearTimeout(t)
+      if (padded) padded.box.style.paddingBottom = padded.was
+    }
+  }, [])
+
+  // A layout effect, so the keys work from the moment the panel is on screen: an effect waits for the next
+  // frame, and a key pressed (or sent by a test, or a host page) before it was ignored
+  useLayoutEffect(() => {
+    const key = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+      if (e.key !== 'Tab' || !modal || !aside.current) return
+      const items = [...aside.current.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(
+        (el) => el.offsetParent !== null,
+      )
+      const first = items[0]
+      const last = items[items.length - 1]
+      const root = aside.current.getRootNode() as Document | ShadowRoot
+      const at = root.activeElement
+      if (!first || !last) return
+      if (e.shiftKey && (at === first || at === aside.current)) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && at === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    addEventListener('keydown', key)
+    return () => removeEventListener('keydown', key)
+  }, [onClose, modal])
+
+  // a dialog when it dims the page (embeds), a complementary region when docked beside the list
+  const attrs = {
+    class: `panel ${modal ? '' : 'docked'}`,
+    part: 'panel',
+    'aria-label': title,
+    'aria-modal': modal ? true : undefined,
+    role: (modal ? 'dialog' : 'complementary') as 'dialog',
+    tabIndex: -1,
+  }
+
+  return (
+    <>
+      {modal && (
+        <button type="button" class="panel-backdrop" aria-label="Close" onClick={onClose} />
+      )}
+      <section {...attrs} ref={aside}>
+        <header class="panel-head" part="header">
+          <div class="panel-title">
+            <h2>{title}</h2>
+            {subtitle && <div class="muted small">{subtitle}</div>}
+          </div>
+          <span class="spacer" />
+          {modal && environments.value.length > 1 && (
+            <label class="row">
+              <span class="muted">Environment</span>
+              <select
+                value={env.value}
+                onChange={(e) => (env.value = (e.target as HTMLSelectElement).value)}
+              >
+                {environments.value.map((e) => (
+                  <option value={e} title={environmentNote.value[e]}>
+                    {e}
+                  </option>
+                ))}
+              </select>
+            </label>
+          )}
+          {(onPrev || onNext) && (
+            <span class="stepper">
+              <button
+                type="button"
+                class="icon"
+                title="Previous"
+                aria-label="Previous"
+                disabled={!onPrev}
+                onClick={onPrev}
+              >
+                ↑
+              </button>
+              <button
+                type="button"
+                class="icon"
+                title="Next"
+                aria-label="Next"
+                disabled={!onNext}
+                onClick={onNext}
+              >
+                ↓
+              </button>
+            </span>
+          )}
+          <button type="button" class="icon" aria-label="Close panel" onClick={onClose}>
+            ×
+          </button>
+        </header>
+        <div class={`panel-body ${flush ? 'flush' : ''}`}>{children}</div>
+      </section>
+    </>
+  )
+}