@specbook/ui 0.2.0 → 0.3.0

package/src/oauth.ts

@@ -8,6 +8,7 @@ import {
   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
@@ -137,14 +138,14 @@ export async function signIn(
 const CLIENTS = 'specbook.oauth.clients.v1'
 const EXPIRY = 'specbook.oauth.expiry.v1'
 
-const readJson = (store: Storage, key: string): Record<string, any> => {
+const readJson = (store: Store, key: string): Record<string, any> => {
   try {
     return JSON.parse(store.getItem(key) ?? '{}')
   } catch {
     return {}
   }
 }
-const writeJson = (store: Storage, key: string, value: unknown) => {
+const writeJson = (store: Store, key: string, value: unknown) => {
   try {
     store.setItem(key, JSON.stringify(value))
   } catch {
@@ -154,7 +155,7 @@ const writeJson = (store: Storage, key: string, value: unknown) => {
 
 export const recallClientId = (authorizationUrl: string): string | undefined => {
   try {
-    return readJson(localStorage, CLIENTS)[authorizationUrl]
+    return readJson(kv.local, CLIENTS)[authorizationUrl]
   } catch {
     return undefined
   }
@@ -162,8 +163,8 @@ export const recallClientId = (authorizationUrl: string): string | undefined =>
 
 export const rememberClientId = (authorizationUrl: string, clientId: string): void => {
   try {
-    writeJson(localStorage, CLIENTS, {
-      ...readJson(localStorage, CLIENTS),
+    writeJson(kv.local, CLIENTS, {
+      ...readJson(kv.local, CLIENTS),
       [authorizationUrl]: clientId,
     })
   } catch {
@@ -176,10 +177,10 @@ 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)
+    const t = readJson(kv.session, EXPIRY)
     if (expiresIn === undefined) delete t[expiryKey(origin, name)]
     else t[expiryKey(origin, name)] = Date.now() + expiresIn * 1000
-    writeJson(sessionStorage, EXPIRY, t)
+    writeJson(kv.session, EXPIRY, t)
   } catch {
     /* no storage */
   }
@@ -187,7 +188,7 @@ export const noteExpiry = (origin: string, name: string, expiresIn: number | und
 
 export const expiryOf = (origin: string, name: string): number | undefined => {
   try {
-    return readJson(sessionStorage, EXPIRY)[expiryKey(origin, name)]
+    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 { env, 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,19 +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 ?? {}
-      // 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 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, env.value])
+  }, [service, profile, env.value, envVarsVersion.value])
 
   const built = useMemo<{ text?: string; error?: string }>(() => {
     try {
@@ -76,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 */
     }

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

@@ -3,7 +3,7 @@ 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'
+import { env, envVarsVersion, version } from '../store'
 
 type Status = { kind: 'idle' } | { kind: 'busy' } | { kind: 'error'; message: string }
 
@@ -39,6 +39,10 @@ export function OAuthSignIn({
   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' })
@@ -67,7 +71,7 @@ export function OAuthSignIn({
     return () => {
       on = false
     }
-  }, [profile, env.value, version.value, attempt])
+  }, [profile, env.value, version.value, attempt, envVarsVersion.value])
 
   const scopeNames = Object.keys(endpoints?.scopes ?? {})