@specbook/ui 0.1.0 → 0.3.0

package/src/panel/Combo.tsx

@@ -9,40 +9,71 @@ interface Props {
   /** forwarded so the grid can move between rows with Enter and the arrow keys */
   onKeyDown?: (e: KeyboardEvent) => void
   cell?: string
+  /** shown, not edited: no list, no typing */
+  readOnly?: boolean
 }
 
 /** A text input with the spec's allowed values as a dropdown; any other value can still be typed. */
-export function Combo({ value, options, onChange, label, placeholder, onKeyDown, cell }: Props) {
+export function Combo({
+  value,
+  options,
+  onChange,
+  label,
+  placeholder,
+  onKeyDown,
+  cell,
+  readOnly,
+}: Props) {
   const [open, setOpen] = useState(false)
   const [at, setAt] = useState(-1)
   const [pos, setPos] = useState<Record<string, string>>()
   const box = useRef<HTMLDivElement>(null)
 
-  /** The list is `fixed` so the grid's rounded, clipped table and the scrolling pane can't cut it off. */
+  /**
+   * The list is `fixed` so the grid's rounded, clipped table and the scrolling pane can't cut it off. A
+   * `fixed` box is placed against the viewport unless an ancestor contains it (a `container-type` does), so
+   * a probe filling the inset-0 box says where its coordinates really start.
+   */
   const place = () => {
-    const r = box.current?.getBoundingClientRect()
-    if (!r) return
+    const el = box.current
+    const r = el?.getBoundingClientRect()
+    if (!el || !r) return
+    const probe = document.createElement('div')
+    probe.style.cssText = 'position:fixed;inset:0;visibility:hidden;pointer-events:none'
+    el.append(probe)
+    const cb = probe.getBoundingClientRect()
+    probe.remove()
     const below = innerHeight - r.bottom - 8
     const flip = below < 160 && r.top > below
     // strings with units: Preact 11 sets style properties as given
     setPos({
-      left: `${r.left}px`,
+      left: `${r.left - cb.left}px`,
       width: `${Math.max(r.width, 160)}px`,
       maxHeight: `${Math.min(240, (flip ? r.top : below) - 4)}px`,
-      ...(flip ? { bottom: `${innerHeight - r.top + 2}px` } : { top: `${r.bottom + 2}px` }),
+      ...(flip ? { bottom: `${cb.bottom - r.top + 2}px` } : { top: `${r.bottom + 2 - cb.top}px` }),
     })
   }
 
   useEffect(() => {
-    if (!open) return
+    if (!open) {
+      // the next opening starts unplaced, not where it last was
+      setPos(undefined)
+      return
+    }
     place()
-    const close = (e: Event) => {
-      if (!(e.target instanceof Node && box.current?.contains(e.target))) setOpen(false)
+    // the list follows its field when something scrolls (a phone moves the field clear of its keyboard),
+    // and goes once the field is out of sight
+    const follow = (e: Event) => {
+      if (e.target instanceof Node && box.current?.contains(e.target)) return
+      const r = box.current?.getBoundingClientRect()
+      if (!r || r.bottom < 0 || r.top > innerHeight) setOpen(false)
+      else place()
     }
-    addEventListener('scroll', close, true)
+    const close = () => setOpen(false)
+    addEventListener('scroll', follow, true)
     addEventListener('resize', close)
     return () => {
-      removeEventListener('scroll', close, true)
+      removeEventListener('scroll', follow, true)
       removeEventListener('resize', close)
     }
   }, [open])
@@ -73,7 +104,8 @@ export function Combo({ value, options, onChange, label, placeholder, onKeyDown,
         aria-expanded={open}
         role="combobox"
         autocomplete="off"
-        onFocus={() => setOpen(true)}
+        readOnly={readOnly}
+        onFocus={() => !readOnly && setOpen(true)}
         onInput={(e) => onChange((e.target as HTMLInputElement).value)}
         onKeyDown={(e) => {
           if (open && e.key === 'ArrowDown') {
@@ -99,12 +131,19 @@ export function Combo({ value, options, onChange, label, placeholder, onKeyDown,
         class="combo-toggle"
         tabIndex={-1}
         aria-label={`Show ${label} options`}
+        disabled={readOnly}
         onClick={() => setOpen(!open)}
       >
         ▾
       </button>
       {open && (
-        <div class="combo-list" role="listbox" style={pos}>
+        // until it is placed it waits out of sight at the corner: in the flow of the table it would grow
+        // the scrolling pane for a moment, and the pane jumps to the bottom
+        <div
+          class="combo-list"
+          role="listbox"
+          style={pos ?? { top: '0px', left: '0px', visibility: 'hidden' }}
+        >
           {options.map((o, i) => (
             <button
               type="button"

package/src/panel/ControlsGrid.tsx

@@ -1,5 +1,5 @@
 import { useState } from 'preact/hooks'
-import { defaultFor, type FieldSpec } from '../components/Fields'
+import { defaultFor, type FieldSpec, generateFor } from '../components/Fields'
 import { Combo } from './Combo'
 
 interface Props {
@@ -135,16 +135,48 @@ function ValueCell({
   }
 }
 
+/** A die: the control that makes another generated value. */
+function Die() {
+  return (
+    <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false">
+      <rect x="1.5" y="1.5" width="13" height="13" rx="3" fill="none" stroke="currentColor" />
+      <circle cx="5.2" cy="5.2" r="1.1" fill="currentColor" />
+      <circle cx="10.8" cy="10.8" r="1.1" fill="currentColor" />
+      <circle cx="8" cy="8" r="1.1" fill="currentColor" />
+    </svg>
+  )
+}
+
 /**
- * A sequence's controls (params, or the choices of an input step) as the same spreadsheet the request
+ * A flow's controls (inputs, or the choices of an input step) as the same spreadsheet the request
  * parameters use: name, value, description.
  */
 export function ControlsGrid({ title, specs, values, onChange }: Props) {
   const names = Object.keys(specs)
   if (names.length === 0) return null
+  const generated = names.filter((n) => specs[n]?.generate)
   return (
     <section class="grid controls-grid" aria-label={title}>
-      <h3>{title}</h3>
+      <h3 class="controls-head">
+        <span>{title}</span>
+        {generated.length > 1 && (
+          <button
+            type="button"
+            class="btn small gen-all"
+            title="Make a new value for every generated input"
+            onClick={() =>
+              onChange({
+                ...values,
+                ...Object.fromEntries(
+                  generated.map((n) => [n, generateFor(specs[n] as FieldSpec)]),
+                ),
+              })
+            }
+          >
+            <Die /> Generate all
+          </button>
+        )}
+      </h3>
       <table>
         <colgroup>
           <col class="c-key" />
@@ -169,12 +201,25 @@ export function ControlsGrid({ title, specs, values, onChange }: Props) {
                   </span>
                 </td>
                 <td class="g-val">
-                  <ValueCell
-                    name={name}
-                    spec={spec}
-                    value={values[name]}
-                    onChange={(v) => onChange({ ...values, [name]: v })}
-                  />
+                  <div class={spec.generate ? 'cell-gen' : undefined}>
+                    <ValueCell
+                      name={name}
+                      spec={spec}
+                      value={values[name]}
+                      onChange={(v) => onChange({ ...values, [name]: v })}
+                    />
+                    {spec.generate && (
+                      <button
+                        type="button"
+                        class="gen"
+                        aria-label={`Generate ${spec.label ?? name}`}
+                        title="Make another value"
+                        onClick={() => onChange({ ...values, [name]: generateFor(spec) })}
+                      >
+                        <Die />
+                      </button>
+                    )}
+                  </div>
                 </td>
                 <td class="g-doc" title={spec.description}>
                   <span class="chip">{hint(spec)}</span> {spec.description}

package/src/panel/ErrorBoundary.tsx

@@ -0,0 +1,36 @@
+import { Component, type ComponentChildren } from 'preact'
+
+interface Props {
+  children: ComponentChildren
+}
+
+/**
+ * What is drawn in a panel comes from a run, and a run is whatever the API answered and whatever the project's code did with
+ * it. If drawing that fails anyway, the panel says so in words and offers the run again, instead of stopping where it was
+ * with nothing to click: a render that throws leaves the part of the page under it dead.
+ */
+export class ErrorBoundary extends Component<Props, { error?: Error }> {
+  state: { error?: Error } = {}
+
+  componentDidCatch(error: unknown) {
+    console.error('specbook: a panel could not be drawn', error)
+    this.setState({ error: error instanceof Error ? error : new Error(String(error)) })
+  }
+
+  render() {
+    const { error } = this.state
+    if (!error) return this.props.children
+    return (
+      <div class="panel-error" role="alert">
+        <p>
+          <strong>This could not be shown.</strong> The run finished, but what it returned could not
+          be drawn.
+        </p>
+        <pre>{error.message}</pre>
+        <button type="button" class="btn" onClick={() => this.setState({ error: undefined })}>
+          Try drawing it again
+        </button>
+      </div>
+    )
+  }
+}

package/src/panel/Host.tsx

@@ -11,6 +11,11 @@ type Props = {
   /** dims the page and traps focus; the standalone site docks the panel beside its list instead */
   modal?: boolean
   tab?: PanelTab
+  /** `popover`: a centered dialog (a sheet from the bottom on a phone); `side`: the app's sheet from the right */
+  variant?: 'side' | 'popover'
+  /** an embed's preset flow inputs, and whether to run as soon as it is ready */
+  preset?: Record<string, unknown>
+  autoRun?: boolean
   /** switch tab, optionally opening a named example */
   onNavigate: (to: { tab: PanelTab; example?: string }) => void
   onPrev?: () => void
@@ -51,6 +56,7 @@ export function Host(p: Props) {
         subtitle="Sequence"
         flush
         modal={p.modal}
+        variant={p.variant}
         onPrev={p.onPrev}
         onNext={p.onNext}
         onClose={p.onClose}
@@ -58,7 +64,11 @@ export function Host(p: Props) {
         <div class="panel-split">
           {tabs}
           <div class={`panel-main ${tab === 'docs' ? 'scroll' : ''}`}>
-            {tab === 'docs' ? <SequenceDocs info={p.info} /> : <SequencePanel info={p.info} />}
+            {tab === 'docs' ? (
+              <SequenceDocs info={p.info} />
+            ) : (
+              <SequencePanel info={p.info} preset={p.preset} autoRun={p.autoRun} />
+            )}
           </div>
         </div>
       </Panel>
@@ -69,6 +79,7 @@ export function Host(p: Props) {
       subtitle={`${p.op.method} ${p.op.path}`}
       flush
       modal={p.modal}
+      variant={p.variant}
       onPrev={p.onPrev}
       onNext={p.onNext}
       onClose={p.onClose}
@@ -86,11 +97,12 @@ export function Host(p: Props) {
             />
           ) : (
             <RequestPanel
-              key={`${p.service}/${p.op.id}`}
+              key={`${p.service}/${p.op.id}${p.example.startsWith('saved:') ? `@${p.example}` : ''}`}
               service={p.service}
               op={p.op}
               variants={p.variants}
               initial={p.example}
+              autoRun={p.autoRun}
             />
           )}
         </div>

package/src/panel/OAuthSignIn.tsx

@@ -0,0 +1,167 @@
+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, envVarsVersion, 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) ?? '',
+  )
+  // another environment may sign in somewhere else, with its own client
+  useEffect(() => {
+    setClientId(oauth.clientId ?? recallClientId(providerKey) ?? '')
+  }, [providerKey, oauth.clientId])
+  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, envVarsVersion.value])
+
+  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/Panel.tsx

@@ -1,6 +1,10 @@
 import type { ComponentChildren } from 'preact'
-import { useEffect, useRef } from 'preact/hooks'
-import { env, environments } from '../store'
+import { useEffect, useLayoutEffect, useMemo, useRef } from 'preact/hooks'
+import { env, environmentNote, environments } from '../store'
+import { announcement } from './announce'
+import { ErrorBoundary } from './ErrorBoundary'
+
+let panelIds = 0
 
 interface Props {
   title: string
@@ -9,6 +13,8 @@ interface Props {
   flush?: boolean
   /** dims the page and traps focus (embeds); the standalone site leaves its list usable beside the panel */
   modal?: boolean
+  /** `popover`: a centered dialog on a desktop and a bottom sheet on a phone; `side` is the app's sheet from the right */
+  variant?: 'side' | 'popover'
   onPrev?: () => void
   onNext?: () => void
   onClose: () => void
@@ -24,12 +30,22 @@ export function Panel({
   subtitle,
   flush,
   modal = true,
+  variant = 'side',
   onPrev,
   onNext,
   onClose,
   children,
 }: Props) {
   const aside = useRef<HTMLElement>(null)
+  const titleId = useMemo(() => `sb-panel-title-${++panelIds}`, [])
+
+  // what was announced for one run is not read out again when the next panel opens
+  useEffect(
+    () => () => {
+      announcement.value = ''
+    },
+    [],
+  )
 
   useEffect(() => {
     const root = aside.current?.getRootNode() as Document | ShadowRoot
@@ -63,14 +79,23 @@ export function Panel({
       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
+      // a dropdown field needs its list visible too, and picking from it needs no keyboard: it is moved
+      // only when it is down where the keyboard would be, and not as far
+      const dropdown = field.getAttribute('role') === 'combobox'
+      const want = top + height * (dropdown ? 0.3 : 0.2)
+      if (at > top + height * (dropdown ? 0.55 : 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) {
+      // a dropdown field high enough on the screen is not moved, so it needs no room below (which would
+      // only show a scrollbar)
+      const vv = typeof visualViewport === 'undefined' ? undefined : visualViewport
+      const low =
+        field.getBoundingClientRect().top >
+        (vv?.offsetTop ?? 0) + (vv?.height ?? innerHeight) * 0.55
+      if (box && padded?.box !== box && (field.getAttribute('role') !== 'combobox' || low)) {
         if (padded) padded.box.style.paddingBottom = padded.was
         padded = { box, was: box.style.paddingBottom }
         box.style.paddingBottom = '70vh'
@@ -99,7 +124,9 @@ export function Panel({
     }
   }, [])
 
-  useEffect(() => {
+  // 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
@@ -119,15 +146,18 @@ export function Panel({
         first.focus()
       }
     }
-    addEventListener('keydown', key)
-    return () => removeEventListener('keydown', key)
+    // a dialog over someone else's page listens on itself (focus is trapped in it), not on the window; the app's
+    // docked panel keeps its window-wide Escape
+    const target: EventTarget = modal && aside.current ? aside.current : window
+    target.addEventListener('keydown', key as EventListener)
+    return () => target.removeEventListener('keydown', key as EventListener)
   }, [onClose, modal])
 
   // a dialog when it dims the page (embeds), a complementary region when docked beside the list
   const attrs = {
-    class: `panel ${modal ? '' : 'docked'}`,
+    class: `panel ${modal ? '' : 'docked'} ${variant === 'popover' ? 'popover' : ''}`,
     part: 'panel',
-    'aria-label': title,
+    'aria-labelledby': titleId,
     'aria-modal': modal ? true : undefined,
     role: (modal ? 'dialog' : 'complementary') as 'dialog',
     tabIndex: -1,
@@ -141,7 +171,7 @@ export function Panel({
       <section {...attrs} ref={aside}>
         <header class="panel-head" part="header">
           <div class="panel-title">
-            <h2>{title}</h2>
+            <h2 id={titleId}>{title}</h2>
             {subtitle && <div class="muted small">{subtitle}</div>}
           </div>
           <span class="spacer" />
@@ -153,7 +183,9 @@ export function Panel({
                 onChange={(e) => (env.value = (e.target as HTMLSelectElement).value)}
               >
                 {environments.value.map((e) => (
-                  <option value={e}>{e}</option>
+                  <option value={e} title={environmentNote.value[e]}>
+                    {e}
+                  </option>
                 ))}
               </select>
             </label>
@@ -186,7 +218,12 @@ export function Panel({
             ×
           </button>
         </header>
-        <div class={`panel-body ${flush ? 'flush' : ''}`}>{children}</div>
+        <div class={`panel-body ${flush ? 'flush' : ''}`}>
+          <ErrorBoundary>{children}</ErrorBoundary>
+        </div>
+        <div class="visually-hidden" role="status" aria-live="polite" aria-atomic="true">
+          {announcement.value}
+        </div>
       </section>
     </>
   )