@specbook/ui 0.2.0 → 0.4.0

package/src/panel/SecretsBar.tsx

@@ -1,10 +1,9 @@
-import type { AuthProfile, OAuthSettings } from '@specbook/core'
+import { absoluteBase, type OAuthSettings } from '@specbook/core'
 import { useEffect, useState } from 'preact/hooks'
 import { expiryOf, noteExpiry } from '../oauth'
-import { absoluteBase } from '../routing'
 import { engine } from '../runtime'
 import { originOf, SECRET_PLACEHOLDER, secretStore } from '../secrets'
-import { env, version } from '../store'
+import { env, envVarsVersion, version } from '../store'
 import { OAuthSignIn } from './OAuthSignIn'
 
 interface Need {
@@ -60,15 +59,17 @@ export function SecretsBar({
     }
     let on = true
     if (!supplied) engine.managedSecrets(env.value).then((m) => on && setManaged(m))
-    engine.config(version.value).then((cfg) => {
-      if (!on) return
+    engine.config(version.value).then(async (cfg) => {
       const out: Need[] = []
+      const where = await engine.addressesIn(cfg, env.value)
       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]
+        // the address this environment's variables give; one that cannot be worked out has no origin
+        const base = where.baseUrl(service)
         const origin = originOf(base ? absoluteBase(base, globalThis.location?.href) : undefined)
         if (!profile || !origin) continue
+        const oauth = s.auth ? where.oauth(s.auth) : undefined
         const names = [
           ...new Set(
             [...JSON.stringify(profile.apply).matchAll(SECRET_PLACEHOLDER)].map(
@@ -83,15 +84,15 @@ export function SecretsBar({
             title: profile.title ?? s.auth ?? '',
             names,
             profile: s.auth as string,
-            oauth: (profile as AuthProfile).oauth,
+            oauth,
           })
       }
-      setNeeds(out)
+      if (on) setNeeds(out)
     })
     return () => {
       on = false
     }
-  }, [live, env.value, wanted, version.value])
+  }, [live, env.value, wanted, version.value, envVarsVersion.value])
 
   if (!live || needs.length === 0) return null
   const have = (n: Need, name: string) =>

package/src/panel/SequenceDocs.tsx

@@ -2,6 +2,7 @@ import { useMemo } from 'preact/hooks'
 import { defaultFor, type FieldSpec, specFromControl } from '../components/Fields'
 import type { SequenceInfo } from '../engine'
 import { go } from '../nav'
+import { show } from './short'
 import { useSequenceNotes } from './stepnotes'
 
 const KIND: Record<string, string> = {
@@ -11,7 +12,7 @@ const KIND: Record<string, string> = {
   check: 'check',
 }
 
-const show = (v: unknown) => (typeof v === 'string' ? v : JSON.stringify(v))
+const showValue = (v: unknown) => (typeof v === 'string' ? v : show(v))
 
 /**
  * What a sequence does, as documentation: its description (markdown), an optional markdown page from
@@ -21,9 +22,9 @@ export function SequenceDocs({ info }: { info: SequenceInfo }) {
   const { seq } = info
   const { intro, notes } = useSequenceNotes(info)
 
-  const params = useMemo(
+  const inputs = useMemo(
     () =>
-      Object.entries((seq.meta.params ?? {}) as Record<string, unknown>).map(([name, c]) => {
+      Object.entries((seq.meta.inputs ?? {}) as Record<string, unknown>).map(([name, c]) => {
         const spec: FieldSpec = specFromControl(c)
         return { name, spec, initial: defaultFor(spec) }
       }),
@@ -42,7 +43,7 @@ export function SequenceDocs({ info }: { info: SequenceInfo }) {
 
       {intro && <div class="doc-custom" dangerouslySetInnerHTML={{ __html: intro }} />}
 
-      {params.length > 0 && (
+      {inputs.length > 0 && (
         <section>
           <h2>Controls</h2>
           <table class="fields">
@@ -55,7 +56,7 @@ export function SequenceDocs({ info }: { info: SequenceInfo }) {
               </tr>
             </thead>
             <tbody>
-              {params.map((p) => (
+              {inputs.map((p) => (
                 <tr>
                   <td>
                     <code>{p.name}</code>
@@ -64,7 +65,7 @@ export function SequenceDocs({ info }: { info: SequenceInfo }) {
                     <span class="chip">{p.spec.kind}</span>
                   </td>
                   <td>
-                    <code>{show(p.initial)}</code>
+                    <code>{showValue(p.initial)}</code>
                   </td>
                   <td>{p.spec.description}</td>
                 </tr>

package/src/panel/SequencePanel.tsx

@@ -1,13 +1,16 @@
 import type { RunResult, StepResult } from '@specbook/core'
-import { useEffect, useMemo, useState } from 'preact/hooks'
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
 import { EnvBadge } from '../components/EnvBadge'
 import { defaultFor, type FieldSpec, specFromControl } from '../components/Fields'
 import type { SequenceInfo } from '../engine'
 import { engine } from '../runtime'
 import { env, locale, seed, version } from '../store'
+import { announcement, describeRun } from './announce'
+import { Failure } from './Checks'
 import { ControlsGrid } from './ControlsGrid'
 import { SecretsBar } from './SecretsBar'
 import { StepExchange } from './StepExchange'
+import { short, show } from './short'
 import { useSequenceNotes } from './stepnotes'
 
 /** `Check items #2` belongs to the step `Check items`. */
@@ -24,18 +27,24 @@ const ICON = {
   paused: '⏸',
   pending: '',
 }
-const short = (v: unknown) => {
-  const s = typeof v === 'string' ? v : JSON.stringify(v)
-  return s.length > 28 ? `${s.slice(0, 27)}…` : s
-}
 
 /** |timeline|request|: the journey on the left, the selected step's exchange on the right. */
-export function SequencePanel({ info }: { info: SequenceInfo }) {
+export function SequencePanel({
+  info,
+  preset,
+  autoRun,
+}: {
+  info: SequenceInfo
+  /** input values to start from instead of the defaults (an embed's data-specbook-inputs) */
+  preset?: Record<string, unknown>
+  /** run on the defaults as soon as the flow is ready */
+  autoRun?: boolean
+}) {
   const { seq } = info
   const specs = useMemo(
     () =>
       Object.fromEntries(
-        Object.entries((seq.meta.params ?? {}) as Record<string, unknown>).map(([k, c]) => [
+        Object.entries((seq.meta.inputs ?? {}) as Record<string, unknown>).map(([k, c]) => [
           k,
           specFromControl(c),
         ]),
@@ -52,7 +61,7 @@ export function SequencePanel({ info }: { info: SequenceInfo }) {
     }
     return [...names]
   }, [seq])
-  const [params, setParams] = useState<Record<string, unknown>>({})
+  const [inputs, setInputs] = useState<Record<string, unknown>>({})
   const [result, setResult] = useState<RunResult>()
   const [live, setLive] = useState<Live>({})
   const [running, setRunning] = useState(false)
@@ -67,11 +76,41 @@ export function SequencePanel({ info }: { info: SequenceInfo }) {
   const [sheet, setSheet] = useState(false)
   const [error, setError] = useState<string>()
 
+  const hasGenerated = Object.values(specs).some((s) => s.generate)
+  // a flow with inputs can run on their defaults alone, as `specbook test` does
+  const hasInputs = Object.keys(specs).length > 0 || seq.nodes.some((n) => n.kind === 'input')
+
+  /** Every input at its default; a generated one needs faker, which is made ready first. */
+  const freshInputs = async () => {
+    if (hasGenerated)
+      await engine.fakerReady(version.value, locale.value, seed.value).catch(() => {})
+    return Object.fromEntries(Object.entries(specs).map(([k, v]) => [k, defaultFor(v)]))
+  }
+
   useEffect(() => {
-    setParams(Object.fromEntries(Object.entries(specs).map(([k, v]) => [k, defaultFor(v)])))
+    let current = true
+    const start = (v: Record<string, unknown>) => ({ ...v, ...(preset ?? {}) })
+    setInputs(start(Object.fromEntries(Object.entries(specs).map(([k, v]) => [k, defaultFor(v)]))))
+    // generated values need faker: fill them in as soon as it is ready
+    if (hasGenerated)
+      void freshInputs().then((v) => {
+        if (!current) return
+        setInputs(start(v))
+        if (autoRun) void run({ inputs: start(v), headless: true })
+      })
+    else if (autoRun)
+      void run({
+        inputs: start(
+          Object.fromEntries(Object.entries(specs).map(([k, v]) => [k, defaultFor(v)])),
+        ),
+        headless: true,
+      })
     setResult(undefined)
     setLive({})
     setPause(undefined)
+    return () => {
+      current = false
+    }
   }, [info.file])
 
   const planned = seq.nodes.map((n) => n.name)
@@ -80,7 +119,20 @@ export function SequencePanel({ info }: { info: SequenceInfo }) {
     : planned.map((n) => ({ name: n }))
   const current = rows[picked]?.step
 
-  const run = async () => {
+  /** ends the run that is going: what is out is stopped, and nothing after it starts */
+  const stopper = useRef<AbortController | undefined>(undefined)
+  const [stopped, setStopped] = useState(false)
+  const stop = () => {
+    setStopped(true)
+    stopper.current?.abort()
+    // a run waiting for a choice is released, and then finds it is stopped
+    pause?.resolve(choice)
+  }
+
+  const run = async (options: { inputs?: Record<string, unknown>; headless?: boolean } = {}) => {
+    const ctl = new AbortController()
+    stopper.current = ctl
+    setStopped(false)
     setRunning(true)
     setResult(undefined)
     setError(undefined)
@@ -91,32 +143,42 @@ export function SequencePanel({ info }: { info: SequenceInfo }) {
       const r = await engine.run(seq, {
         env: env.value,
         version: version.value,
-        params,
+        inputs: options.inputs ?? inputs,
         locale: locale.value,
         seed: seed.value,
+        signal: ctl.signal,
         onEvent: (e) => {
           if (e.type === 'step:start') setLive((l) => ({ ...l, [e.name]: 'running' }))
           if (e.type === 'step:end') setLive((l) => ({ ...l, [e.name]: e.status }))
         },
-        onInput: ({ name, controls }) =>
-          new Promise((resolve) => {
-            const c = controls as Record<string, FieldSpec>
-            setLive((l) => ({ ...l, [name]: 'paused' }))
-            setChoice(Object.fromEntries(Object.entries(c).map(([k, v]) => [k, defaultFor(v)])))
-            setPause({
-              name,
-              controls: c,
-              resolve: (values) => {
-                setPause(undefined)
-                resolve(values)
-              },
-            })
-          }),
+        onInput: options.headless
+          ? undefined
+          : ({ name, controls }) =>
+              new Promise((resolve) => {
+                const c = controls as Record<string, FieldSpec>
+                setLive((l) => ({ ...l, [name]: 'paused' }))
+                setChoice(Object.fromEntries(Object.entries(c).map(([k, v]) => [k, defaultFor(v)])))
+                setPause({
+                  name,
+                  controls: c,
+                  resolve: (values) => {
+                    setPause(undefined)
+                    resolve(values)
+                  },
+                })
+              }),
       })
       setResult(r)
+      announcement.value = describeRun(r)
+      // a run that did not pass shows its first failing step, not its first step
+      const bad = r.steps
+        .filter((s) => s.kind !== 'auth')
+        .findIndex((s) => s.status === 'fail' || s.status === 'error')
+      if (bad >= 0) setPicked(bad)
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e))
     } finally {
+      stopper.current = undefined
       setRunning(false)
       setPause(undefined)
     }
@@ -128,17 +190,43 @@ export function SequencePanel({ info }: { info: SequenceInfo }) {
     <div class={`sequence-panel ${sheet && current ? 'sheet-open' : ''}`} data-seq={seq.meta.id}>
       <div class="seq-left">
         <SecretsBar services={serviceNames} />
-        <ControlsGrid title="Controls" specs={specs} values={params} onChange={setParams} />
+        <ControlsGrid title="Inputs" specs={specs} values={inputs} onChange={setInputs} />
         <div class="seq-run">
-          <button type="button" class="btn primary" disabled={running} onClick={run}>
+          <button type="button" class="btn primary" disabled={running} onClick={() => run()}>
             {running ? 'Running…' : '▶ Run'}
           </button>
+          {running && (
+            <button type="button" class="btn" onClick={stop}>
+              Stop
+            </button>
+          )}
+          {hasInputs && (
+            <button
+              type="button"
+              class="btn"
+              disabled={running}
+              title="Skip every question and use each input's default, as specbook test does"
+              onClick={async () => {
+                const fresh = await freshInputs()
+                setInputs(fresh)
+                await run({ inputs: fresh, headless: true })
+              }}
+            >
+              Run with defaults
+            </button>
+          )}
           <EnvBadge />
           {result && (
             <span class={`badge ${overall}`}>
               {ICON[overall as 'pass']}{' '}
-              {overall === 'pass' ? 'Passed' : overall === 'fail' ? 'Failed' : 'Error'} ·{' '}
-              {result.totals.passed}/{result.totals.steps} steps · {result.durationMs}ms
+              {overall === 'pass'
+                ? 'Passed'
+                : stopped
+                  ? 'Stopped'
+                  : overall === 'fail'
+                    ? 'Failed'
+                    : 'Error'}{' '}
+              · {result.totals.passed}/{result.totals.steps} steps · {result.durationMs}ms
             </span>
           )}
         </div>
@@ -187,16 +275,20 @@ export function SequencePanel({ info }: { info: SequenceInfo }) {
                     ))}
                   {step &&
                     Object.entries(step.captured).map(([k, v]) => (
-                      <span class="cap make" title={JSON.stringify(v)}>
+                      <span class="cap make" title={show(v)}>
                         → {k} <b>{short(v)}</b>
                       </span>
                     ))}
                   {step?.error && <div class="error-text">{step.error}</div>}
                   {failed.map((a) => (
-                    <div class="error-text">✗ {a.label}</div>
+                    <Failure a={a} />
                   ))}
                   {status === 'skipped' && (
-                    <div class="muted">Skipped: an earlier step did not pass.</div>
+                    <div class="muted">
+                      {stopped
+                        ? 'Skipped: you stopped the run.'
+                        : 'Skipped: an earlier step did not pass.'}
+                    </div>
                   )}
                   {pause && live[row.name] === 'paused' && (
                     <div class="pause">

package/src/panel/announce.ts

@@ -0,0 +1,17 @@
+import { signal } from '@preact/signals'
+import type { RunResult } from '@specbook/core'
+
+/** What a screen reader is told when a run finishes: the panel renders it in a polite live region. */
+export const announcement = signal('')
+
+/** One sentence for a finished run: a request by its response, a flow by how many steps passed. */
+export function describeRun(r: RunResult): string {
+  if (r.kind === 'request') {
+    const s = r.steps.find((x) => x.response) ?? r.steps[0]
+    if (!s?.response) return r.status === 'error' ? 'The request could not be sent.' : 'Done.'
+    const checks = s.assertions.filter((a) => !a.pass).length
+    return `${s.response.status}, ${r.durationMs} milliseconds${checks ? `, ${checks} check${checks === 1 ? '' : 's'} failed` : ''}.`
+  }
+  const word = r.status === 'pass' ? 'passed' : r.status === 'fail' ? 'failed' : 'could not run'
+  return `Flow ${word}, ${r.totals.passed} of ${r.totals.steps} steps passed.`
+}

package/src/panel/icons.tsx

@@ -83,3 +83,12 @@ export function StarIcon({ size = 14 }: { size?: number }) {
     </svg>
   )
 }
+
+/** A filled square, the usual "stop" mark. */
+export function StopSquare({ size = 16 }: { size?: number }) {
+  return (
+    <svg viewBox="0 0 24 24" width={size} height={size} fill="currentColor" aria-hidden="true">
+      <rect x="6" y="6" width="12" height="12" rx="2" />
+    </svg>
+  )
+}

package/src/panel/short.ts

@@ -0,0 +1,24 @@
+/**
+ * A value as text, whatever it is. A run hands the page whatever the project's code and the API produced, and JSON cannot
+ * write all of it: `undefined` and functions come back as nothing, a circular object or a BigInt throws. A line that cannot
+ * be drawn must not stop the panel, so this never throws and never returns nothing.
+ */
+export function show(v: unknown, space?: number): string {
+  try {
+    const s = JSON.stringify(v, null, space)
+    if (s !== undefined) return s
+  } catch {
+    /* circular, or something JSON has no form for: name it instead */
+  }
+  try {
+    return String(v)
+  } catch {
+    return Object.prototype.toString.call(v)
+  }
+}
+
+/** A value for a line of text: its text, cut at 28 characters. */
+export function short(v: unknown): string {
+  const s = typeof v === 'string' ? v : show(v)
+  return s.length > 28 ? `${s.slice(0, 27)}…` : s
+}

package/src/routing.ts

@@ -29,15 +29,6 @@ export function routeFor(o: {
   return 'direct'
 }
 
-/** A config `baseUrl` may be relative (`/api/v1`): it is resolved against the page. */
-export function absoluteBase(baseUrl: string, pageHref?: string): string {
-  try {
-    return new URL(baseUrl, pageHref).toString()
-  } catch {
-    return baseUrl
-  }
-}
-
 const names = (req: PreparedRequest): string[] => {
   const out = new Set<string>()
   const scan = (v: unknown) => {

package/src/runtime.ts

@@ -1,4 +1,5 @@
 import * as reg from 'virtual:specbook/registry'
+import { createEnvironmentStore } from './custom-environments'
 import { createEngine, pickRunnable } from './engine'
 import { detectExtension, type ExtensionBridge } from './extension'
 import { version } from './store'
@@ -14,10 +15,27 @@ const extension = async () => {
   return bridge
 }
 
-export const engine = createEngine(reg as never, { extension })
+/**
+ * A page with no project files keeps the environments a person makes in the browser: per spec in the
+ * hosted viewer (its registry says where), per page for a built site. An embed has none.
+ */
+const storeAt = (reg as { environmentStore?: { scope: string; session: boolean } | null })
+  .environmentStore
+const environmentStore =
+  reg.mode === 'static' && storeAt !== null
+    ? createEnvironmentStore(
+        storeAt?.scope ?? `${globalThis.location?.origin}${globalThis.location?.pathname}`,
+        storeAt?.session ? 'session' : 'local',
+      )
+    : undefined
+
+export const engine = createEngine(reg as never, { extension, environmentStore })
 
 export const isStatic = reg.mode === 'static'
 
+/** A build that publishes only the requests and flows the project uses (`specbook build --minimal`). */
+export const isMinimal = !!(reg as { minimal?: boolean }).minimal
+
 /** Dev only: writes a project file through the plugin, then busts import caches. */
 export async function saveFile(path: string, content: string): Promise<void> {
   const r = await fetch('/__specbook/save', {

package/src/secrets.ts

@@ -6,6 +6,8 @@
  * closes) with an in-memory fallback; another backend (an encrypted store, say) can sit behind the same
  * interface. Requests carry `{{secrets.NAME}}` placeholders until the transport sends them.
  */
+import { kv } from './storage'
+
 const KEY = 'specbook.secrets.v1'
 
 type Table = Record<string, Record<string, string>>
@@ -20,7 +22,7 @@ let memory: Table = {}
 
 const read = (): Table => {
   try {
-    const raw = sessionStorage.getItem(KEY)
+    const raw = kv.session.getItem(KEY)
     return raw ? (JSON.parse(raw) as Table) : memory
   } catch {
     return memory
@@ -30,7 +32,7 @@ const read = (): Table => {
 const write = (t: Table) => {
   memory = t
   try {
-    sessionStorage.setItem(KEY, JSON.stringify(t))
+    kv.session.setItem(KEY, JSON.stringify(t))
   } catch {
     /* private mode or blocked storage: the in-memory copy still serves this page */
   }

package/src/storage.ts

@@ -0,0 +1,58 @@
+// Where the UI keeps what a person typed. In the app and the viewer it is the browser's storage, kept as before. In an embed
+// it is memory: a docs page shares its origin's `localStorage` with its own code, and a visitor's drafts and credentials
+// must not land there, or be read from there.
+
+export type Store = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>
+
+function memory(): Store {
+  const m = new Map<string, string>()
+  return {
+    getItem: (k) => m.get(k) ?? null,
+    setItem: (k, v) => void m.set(k, String(v)),
+    removeItem: (k) => void m.delete(k),
+  }
+}
+
+/** Reading the global can itself throw (blocked site data), so it is done when asked and a failure falls back to memory. */
+function browser(which: 'localStorage' | 'sessionStorage'): Store {
+  try {
+    const s = globalThis[which]
+    if (s) return s
+  } catch {
+    /* blocked */
+  }
+  return memory()
+}
+
+let local: Store | undefined
+let session: Store | undefined
+let isolated = false
+
+export const kv = {
+  get local(): Store {
+    if (!isolated) return browser('localStorage')
+    if (!local) local = memory()
+    return local
+  },
+  get session(): Store {
+    if (!isolated) return browser('sessionStorage')
+    if (!session) session = memory()
+    return session
+  },
+}
+
+/** From here on nothing is read from or written to the page's own storage. */
+export function useMemoryStorage(): void {
+  isolated = true
+  local = undefined
+  session = undefined
+}
+
+/** Back to the browser's storage (for tests). */
+export function useBrowserStorage(): void {
+  isolated = false
+  local = undefined
+  session = undefined
+}
+
+export const storageIsolated = () => isolated

package/src/store.ts

@@ -10,3 +10,11 @@ export const environmentRisk = signal<Record<string, 'production' | 'sandbox'>>(
 export const environmentNote = signal<Record<string, string>>({})
 export const locale = signal<string | undefined>(undefined)
 export const seed = signal<number | undefined>(undefined)
+/** Bumped when an environment's variables change, so what is derived from them (addresses, origins) is redone. */
+export const envVarsVersion = signal(0)
+/** Whether Environment settings is open; set from elsewhere to point a person at it. */
+export const envSettingsOpen = signal(false)
+/** The New environment dialog. */
+export const newEnvironmentOpen = signal(false)
+/** What the shell around the panels offers. An embed has no dialog for creating an environment or for settings. */
+export const features = signal({ createEnvironment: true, environmentSettings: true })