@specbook/ui 0.0.0-stage → 0.1.0

package/src/panel/RequestView.tsx

@@ -0,0 +1,108 @@
+import type { RenderedRequest } from '@specbook/core'
+import { useMemo, useState } from 'preact/hooks'
+import { fieldDoc, withNote } from '../fielddoc'
+import { type Defs, type JsonSchema, linePaths, pathString } from '../schema'
+import { BodyEditor } from './BodyEditor'
+import { FieldDoc } from './FieldDoc'
+
+const pretty = (v: unknown) => (typeof v === 'string' ? v : JSON.stringify(v, null, 2))
+
+/** Repeated keys for arrays, as the transport sends them. */
+export function queryString(query: Record<string, string | string[]>) {
+  const p = new URLSearchParams()
+  for (const [k, v] of Object.entries(query))
+    for (const x of Array.isArray(v) ? v : [v]) p.append(k, x)
+  const s = p.toString()
+  return s ? `?${s}` : ''
+}
+
+/** What the spec says about the fields: the request schema (`{ path, query, headers, data }`). */
+export interface RequestDocs {
+  schema?: JsonSchema
+  defs?: Defs
+  notes?: Map<string, string>
+}
+
+/** The body as sent, with the documentation of the field the cursor is on below it. */
+function SentBody({ body, docs }: { body: unknown; docs?: RequestDocs }) {
+  const [line, setLine] = useState(0)
+  const text = pretty(body)
+  const documented = !!docs?.schema && typeof body === 'object' && body !== null
+  const paths = useMemo(() => (documented ? linePaths(text) : []), [documented, text])
+  const doc = useMemo(() => {
+    const p = paths[line]
+    return p && docs
+      ? withNote(fieldDoc(docs.schema, docs.defs, p, ['data']), docs.notes, 'data', pathString(p))
+      : undefined
+  }, [paths, line, docs])
+  return (
+    <>
+      <BodyEditor
+        label="Body as sent"
+        value={text}
+        readOnly
+        language={typeof body === 'string' ? 'text' : 'json'}
+        onLine={setLine}
+      />
+      {documented && <FieldDoc doc={doc} />}
+    </>
+  )
+}
+
+/** The request exactly as it went out: method, URL, headers and body after placeholders were filled. */
+export function RequestView({
+  request,
+  hideBar,
+  docs,
+}: {
+  request?: RenderedRequest
+  /** the surrounding view already shows the method and URL */
+  hideBar?: boolean
+  /** when given, a field's description is shown as the cursor moves through the body */
+  docs?: RequestDocs
+}) {
+  if (!request)
+    return (
+      <div class="rs-empty">
+        <strong>Nothing sent yet</strong>
+        <span class="muted">The request, with every value filled in, appears here after Send.</span>
+      </div>
+    )
+  const headers = Object.entries(request.headers)
+  return (
+    <div class="sent-view">
+      {!hideBar && (
+        <div class="rq-bar">
+          <span class={`method ${request.method}`}>{request.method}</span>
+          <div class="rq-url" title={request.url}>
+            <code>
+              {request.url}
+              {queryString(request.query)}
+            </code>
+          </div>
+        </div>
+      )}
+      <h3>Headers</h3>
+      {headers.length === 0 ? (
+        <p class="muted">No headers.</p>
+      ) : (
+        <table class="headers">
+          <tbody>
+            {headers.map(([k, v]) => (
+              <tr>
+                <th>{k}</th>
+                <td>{v}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+      {request.body !== undefined && (
+        <>
+          <h3>Body</h3>
+          <SentBody body={request.body} docs={docs} />
+        </>
+      )}
+    </div>
+  )
+}

package/src/panel/ResponseView.tsx

@@ -0,0 +1,182 @@
+import type { StepResult } from '@specbook/core'
+import { useMemo, useState } from 'preact/hooks'
+import { fieldDoc } from '../fielddoc'
+import { type Defs, type JsonSchema, linePaths, validate } from '../schema'
+import { statusClass, statusName } from '../status'
+import { BodyEditor } from './BodyEditor'
+import { FieldDoc } from './FieldDoc'
+import { PaperPlane } from './icons'
+import { queryString } from './RequestView'
+
+interface Props {
+  step?: StepResult
+  error?: string
+  schemas?: Record<string, JsonSchema>
+  defs?: Defs
+  /** the request is shown elsewhere */
+  hideRequest?: boolean
+}
+
+const pretty = (v: unknown) => JSON.stringify(v, null, 2)
+const size = (n: number) => (n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KB`)
+
+export function ResponseView({ step, error, schemas, defs, hideRequest }: Props) {
+  const [tab, setTab] = useState<'body' | 'headers' | 'checks'>('body')
+  const [line, setLine] = useState(0)
+  const response = step?.response
+  const schema = response ? (schemas?.[String(response.status)] ?? schemas?.default) : undefined
+  const issues = useMemo(
+    () => (response && schema ? validate(response.body, schema, defs, { reportExtra: true }) : []),
+    [response, schema, defs],
+  )
+  const text =
+    response === undefined || response.body === undefined || response.body === ''
+      ? ''
+      : typeof response.body === 'string'
+        ? response.body
+        : pretty(response.body)
+  const paths = useMemo(() => linePaths(text), [text])
+  const doc = useMemo(() => {
+    const p = paths[line]
+    return p ? fieldDoc(schema, defs, p) : undefined
+  }, [paths, line, schema, defs])
+  const checks = step?.assertions ?? []
+  const failed = checks.filter((a) => !a.pass).length
+  const headers = Object.entries(response?.headers ?? {})
+  const empty = !response && !error && !step?.error
+
+  return (
+    <section class="response" aria-label="Response">
+      <div class="rs-head">
+        {response && (
+          <>
+            <span class={`state-badge ${statusClass(response.status)}`}>
+              {response.status} {statusName(response.status)}
+            </span>
+            <span class="rs-stat">{response.durationMs} ms</span>
+            <span class="rs-stat">{size(new Blob([text]).size)}</span>
+          </>
+        )}
+        <span class="spacer" />
+        {response && (
+          <span class={`conf ${schema ? (issues.length ? 'warn' : 'ok') : 'none'}`}>
+            {schema
+              ? issues.length
+                ? `⚠ ${issues.length} difference${issues.length > 1 ? 's' : ''} from spec`
+                : '✓ Matches spec'
+              : 'No schema for this response'}
+          </span>
+        )}
+      </div>
+
+      {step?.request && !hideRequest && (
+        <p class="sent">
+          <span class={`method ${step.request.method}`}>{step.request.method}</span>{' '}
+          <code>
+            {step.request.url}
+            {queryString(step.request.query)}
+          </code>
+        </p>
+      )}
+      {error && <p class="error-text">{error}</p>}
+      {step?.error && <p class="error-text">{step.error}</p>}
+      {empty && (
+        <div class="rs-empty">
+          <strong>No response yet</strong>
+          <span class="muted">
+            Press{' '}
+            <kbd class="icon-key">
+              <PaperPlane size={12} />
+            </kbd>{' '}
+            or <kbd>⌘</kbd> <kbd>↵</kbd>
+          </span>
+        </div>
+      )}
+
+      {response && (
+        <>
+          <div class="rq-tabs" role="tablist">
+            {(
+              [
+                ['body', 'Body', 0],
+                ['headers', 'Headers', headers.length],
+                ['checks', 'Checks', checks.length],
+              ] as const
+            ).map(([id, label, n]) => (
+              <button
+                type="button"
+                role="tab"
+                aria-selected={tab === id}
+                class={`rq-tab ${tab === id ? 'on' : ''}`}
+                onClick={() => setTab(id)}
+              >
+                {label}
+                {n > 0 && (
+                  <span class={`count ${id === 'checks' && failed ? 'bad' : ''}`}>{n}</span>
+                )}
+              </button>
+            ))}
+          </div>
+          <div class="rs-pane">
+            <div hidden={tab !== 'body'}>
+              {text === '' ? (
+                <p class="muted">No content.</p>
+              ) : (
+                <BodyEditor
+                  label="Response body"
+                  value={text}
+                  readOnly
+                  language={typeof response.body === 'string' ? 'text' : 'json'}
+                  onLine={setLine}
+                />
+              )}
+              {text !== '' && <FieldDoc doc={doc} />}
+              {issues.length > 0 && (
+                <details class="issues">
+                  <summary>What differs</summary>
+                  <ul>
+                    {issues.map((i) => (
+                      <li>
+                        <code>{i.path || '(root)'}</code> {i.message}
+                      </li>
+                    ))}
+                  </ul>
+                </details>
+              )}
+            </div>
+            <div hidden={tab !== 'headers'}>
+              <table class="headers">
+                <tbody>
+                  {headers.map(([k, v]) => (
+                    <tr>
+                      <th>{k}</th>
+                      <td>{v}</td>
+                    </tr>
+                  ))}
+                  {headers.length === 0 && (
+                    <tr>
+                      <td class="muted">No headers recorded</td>
+                    </tr>
+                  )}
+                </tbody>
+              </table>
+            </div>
+            <div hidden={tab !== 'checks'}>
+              {checks.length === 0 ? (
+                <p class="muted">This request has no checks.</p>
+              ) : (
+                <ul class="checks">
+                  {checks.map((a) => (
+                    <li class={a.pass ? 'ok' : 'bad'}>
+                      {a.pass ? '✓' : '✗'} {a.label}
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </div>
+          </div>
+        </>
+      )}
+    </section>
+  )
+}

package/src/panel/SecretsBar.tsx

@@ -0,0 +1,156 @@
+import { useEffect, useState } from 'preact/hooks'
+import { absoluteBase } from '../routing'
+import { engine } from '../runtime'
+import { originOf, SECRET_PLACEHOLDER, secretStore } from '../secrets'
+import { env, version } from '../store'
+
+interface Need {
+  service: string
+  origin: string
+  title: string
+  names: string[]
+}
+
+const SOURCE: Record<string, string> = {
+  session: 'this session',
+  process: 'environment variable',
+  environment: 'environment file',
+  shared: 'shared file',
+}
+
+/**
+ * Credentials, asked for where they are needed: the request or flow about to run. A value typed here
+ * goes into the request, bound to the API's own origin, and stays in this tab. Where the dev server
+ * already has one (an environment variable or a secrets file) it is listed as available and only needs
+ * a value here to override it; a name nothing supplies is what the bar asks for.
+ */
+export function SecretsBar({
+  services,
+  enabled = true,
+  supplied,
+}: {
+  services?: string[]
+  /** false hides the bar (the caller has its own way to ask) */
+  enabled?: boolean
+  /** names the executor already holds, by source; read from the engine unless given */
+  supplied?: Record<string, string>
+}) {
+  const [needs, setNeeds] = useState<Need[]>([])
+  const [asked, setManaged] = useState<Record<string, string>>({})
+  const managed = supplied ?? asked
+  const [, bump] = useState(0)
+  // once nothing is missing the prompt folds to one small chip; a tap opens it again
+  const [open, setOpen] = useState(false)
+  const live = enabled && env.value !== 'mock'
+  const wanted = services?.join('\n') ?? '*'
+
+  useEffect(() => {
+    if (!live) {
+      setNeeds([])
+      return
+    }
+    let on = true
+    if (!supplied) engine.managedSecrets(env.value).then((m) => on && setManaged(m))
+    engine.config(version.value).then((cfg) => {
+      if (!on) return
+      const out: Need[] = []
+      for (const [service, s] of Object.entries(cfg.services ?? {})) {
+        if (services && !services.includes(service)) continue
+        const profile = s.auth ? cfg.auth?.[s.auth] : undefined
+        const base = s.baseUrl?.[env.value]
+        const origin = originOf(base ? absoluteBase(base, globalThis.location?.href) : undefined)
+        if (!profile || !origin) continue
+        const names = [
+          ...new Set(
+            [...JSON.stringify(profile.apply).matchAll(SECRET_PLACEHOLDER)].map(
+              (m) => m[1] as string,
+            ),
+          ),
+        ]
+        if (names.length) out.push({ service, origin, title: profile.title ?? s.auth ?? '', names })
+      }
+      setNeeds(out)
+    })
+    return () => {
+      on = false
+    }
+  }, [live, env.value, wanted, version.value])
+
+  if (!live || needs.length === 0) return null
+  const have = (n: Need, name: string) =>
+    secretStore.get(n.origin, name) !== undefined || managed[name] !== undefined
+  const missing = needs.some((n) => n.names.some((x) => !have(n, x)))
+  if (!missing && !open)
+    return (
+      <div class="secrets-folded">
+        <button
+          type="button"
+          class="secrets-chip"
+          aria-expanded="false"
+          title="Credentials are available. Tap to change or clear the ones set in this tab."
+          onClick={() => setOpen(true)}
+        >
+          <span aria-hidden="true">🔑</span> {needs.map((n) => n.title || n.service).join(' · ')} ✓
+        </button>
+      </div>
+    )
+  return (
+    <fieldset class={`needs-vars ${missing ? '' : 'ok'}`} aria-label="Credentials for this request">
+      {needs.map((n) => (
+        <>
+          <span class="muted" title={`Sent from this browser to ${n.origin}`}>
+            {n.service} · {n.title}
+          </span>
+          {n.names.map((name) => {
+            const has = secretStore.get(n.origin, name) !== undefined
+            const from = managed[name]
+            return (
+              <span class="needs-var">
+                <code>{name}</code>
+                {has ? (
+                  <>
+                    <span class="muted">✓ set</span>
+                    <button
+                      type="button"
+                      class="link"
+                      onClick={() => {
+                        secretStore.remove(n.origin, name)
+                        bump((x) => x + 1)
+                      }}
+                    >
+                      Clear
+                    </button>
+                  </>
+                ) : (
+                  <>
+                    {from && <span class="muted">from {SOURCE[from] ?? from}</span>}
+                    <input
+                      type="password"
+                      autocomplete="off"
+                      aria-label={`${name} for ${n.service}`}
+                      placeholder={from ? 'use another value' : 'paste value'}
+                      onChange={(e) => {
+                        const v = (e.target as HTMLInputElement).value
+                        if (v === '') return
+                        secretStore.set(n.origin, name, v)
+                        bump((x) => x + 1)
+                      }}
+                    />
+                  </>
+                )}
+              </span>
+            )
+          })}
+        </>
+      ))}
+      <span class="muted small secrets-note">
+        Kept in this tab only; sent from your browser to the API.
+      </span>
+      {!missing && (
+        <button type="button" class="link" onClick={() => setOpen(false)}>
+          Hide
+        </button>
+      )}
+    </fieldset>
+  )
+}

package/src/panel/SequenceDocs.tsx

@@ -0,0 +1,132 @@
+import { useMemo } from 'preact/hooks'
+import { defaultFor, type FieldSpec, specFromControl } from '../components/Fields'
+import type { SequenceInfo } from '../engine'
+import { go } from '../nav'
+import { useSequenceNotes } from './stepnotes'
+
+const KIND: Record<string, string> = {
+  step: 'request',
+  each: 'for each item',
+  input: 'you choose',
+  check: 'check',
+}
+
+const show = (v: unknown) => (typeof v === 'string' ? v : JSON.stringify(v))
+
+/**
+ * What a sequence does, as documentation: its description (markdown), an optional markdown page from
+ * `docs/*.md` with `sequence: <id>` frontmatter, the controls it takes and the operation behind each step.
+ */
+export function SequenceDocs({ info }: { info: SequenceInfo }) {
+  const { seq } = info
+  const { intro, notes } = useSequenceNotes(info)
+
+  const params = useMemo(
+    () =>
+      Object.entries((seq.meta.params ?? {}) as Record<string, unknown>).map(([name, c]) => {
+        const spec: FieldSpec = specFromControl(c)
+        return { name, spec, initial: defaultFor(spec) }
+      }),
+    [seq],
+  )
+
+  return (
+    <article class="doc" data-seq={seq.meta.id}>
+      {(seq.meta.tags?.length ?? 0) > 0 && (
+        <p class="doc-tags">
+          {seq.meta.tags?.map((t) => (
+            <span class="chip">{t}</span>
+          ))}
+        </p>
+      )}
+
+      {intro && <div class="doc-custom" dangerouslySetInnerHTML={{ __html: intro }} />}
+
+      {params.length > 0 && (
+        <section>
+          <h2>Controls</h2>
+          <table class="fields">
+            <thead>
+              <tr>
+                <th>Name</th>
+                <th>Type</th>
+                <th>Default</th>
+                <th>Description</th>
+              </tr>
+            </thead>
+            <tbody>
+              {params.map((p) => (
+                <tr>
+                  <td>
+                    <code>{p.name}</code>
+                  </td>
+                  <td>
+                    <span class="chip">{p.spec.kind}</span>
+                  </td>
+                  <td>
+                    <code>{show(p.initial)}</code>
+                  </td>
+                  <td>{p.spec.description}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </section>
+      )}
+
+      <section>
+        <h2>Steps</h2>
+        <table class="fields">
+          <thead>
+            <tr>
+              <th>#</th>
+              <th>Step</th>
+              <th>What it does</th>
+            </tr>
+          </thead>
+          <tbody>
+            {seq.nodes.map((n, i) => {
+              const def = n.kind === 'step' && typeof n.def !== 'function' ? n.def : undefined
+              const op = def?.op
+              const note = notes.get(n.name)
+              return (
+                <>
+                  <tr class={note ? 'has-note' : ''}>
+                    <td>{i + 1}</td>
+                    <td>{n.name}</td>
+                    <td>
+                      {op ? (
+                        <button
+                          type="button"
+                          class="link"
+                          title="Open this operation"
+                          onClick={() => go({ kind: 'op', key: `${op.service}/${op.id}` })}
+                        >
+                          <span class={`method ${op.method}`}>{op.method}</span>{' '}
+                          <code>{op.path}</code>
+                        </button>
+                      ) : (
+                        <span class="muted">{KIND[n.kind] ?? n.kind}</span>
+                      )}
+                    </td>
+                  </tr>
+                  {note && (
+                    <tr class="step-note-row">
+                      <td />
+                      <td colSpan={2}>
+                        <div
+                          class="doc-custom step-note"
+                          dangerouslySetInnerHTML={{ __html: note }}
+                        />
+                      </td>
+                    </tr>
+                  )}
+                </>
+              )
+            })}
+          </tbody>
+        </table>
+      </section>
+    </article>
+  )
+}