@specbook/ui 0.1.0 → 0.3.0

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

@@ -6,5 +6,15 @@ export const env = signal('mock')
 export const environments = signal<string[]>(['mock'])
 /** Environments the config marks `production` or `sandbox`; others are judged by their name. */
 export const environmentRisk = signal<Record<string, 'production' | 'sandbox'>>({})
+/** What the config says each environment is, for the tooltip of its entry in a picker. */
+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 })

package/src/styles/app.css

@@ -146,6 +146,8 @@
   .list-col {
     min-height: 0;
     overflow: auto;
+    /* folding a group changes how tall the list is: keep the scrollbar's space, so the list does not widen and narrow */
+    scrollbar-gutter: stable;
     /* scrolling to the end of the list must not drag the whole page along */
     overscroll-behavior: contain;
     padding: var(--sb-space-3);
@@ -287,6 +289,37 @@
     font-size: 15px;
     outline: none;
   }
+  /* New environment: a small form in the palette's frame, above a docked panel and the settings popover */
+  .newenv-backdrop {
+    z-index: 60;
+  }
+  .newenv {
+    /* the palette stretches to fill its height; a short form should not */
+    align-self: flex-start;
+  }
+  .newenv form {
+    display: flex;
+    flex-direction: column;
+    gap: var(--sb-space-2);
+    padding: var(--sb-space-4);
+  }
+  .newenv h2 {
+    margin: 0;
+    font-size: 15px;
+  }
+  .newenv label {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+  .newenv input,
+  .newenv select {
+    border: 1px solid var(--sb-border);
+    border-radius: var(--sb-radius-control);
+    padding: 8px 10px;
+    /* 16px, so iOS does not zoom the page when a field is focused */
+    font-size: 16px;
+  }
   .palette ul {
     list-style: none;
     margin: 0;
@@ -427,7 +460,11 @@
     padding: var(--sb-space-3) 0 0;
     border-top: 1px solid var(--sb-border);
   }
+  /* the tick says it passed; the sentence is muted, so a list of checks reads calmly and a failure stands out */
   .checks .ok {
+    color: var(--sb-text-muted);
+  }
+  .checks .ok .tick {
     color: var(--sb-success);
   }
   .checks .bad {
@@ -657,7 +694,7 @@
       white-space: nowrap;
     }
     .palette-btn kbd,
-    .header .spacer {
+    .header > .spacer {
       display: none;
     }
     .header .menu-btn {
@@ -693,12 +730,37 @@
       justify-content: space-between;
       flex-wrap: nowrap;
     }
-    .header-controls select {
-      min-width: 140px;
+    /* every labelled control in the menu: the label to the left, the control the same width on the right */
+    .header-controls .row > select {
+      flex: 0 0 56%;
+      width: 56%;
+      min-width: 0;
+    }
+    /* Synthetic data is a row inside a row (its label and, once fixed, a seed field): the inner one fills it */
+    .header-controls .row > .row {
+      flex: 1 1 100%;
+    }
+    .header-controls .row.muted {
+      flex-wrap: wrap;
+    }
+    .header-controls .seed-input {
+      flex: 0 0 56%;
+      margin-left: auto;
+    }
+    .header-controls .envmenu,
+    .header-controls .envmenu-btn {
+      width: 100%;
+    }
+    .header-controls .envmenu-btn {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      gap: var(--sb-space-2);
     }
     /* in the menu there is room for the words, and each link is a full row */
     .header-controls .gh-label,
-    .header-controls .share-label {
+    .header-controls .share-label,
+    .header-controls .envmenu-label {
       display: inline;
     }
     .header-controls .gh-star,
@@ -800,10 +862,11 @@
     min-width: 120px;
     max-width: 360px;
   }
-  /* GitHub and Share keep their icons and lose their words where the header is tight */
+  /* GitHub, Share and Environment settings keep their icons and lose their words where the header is tight */
   @media (max-width: 1360px) {
     .gh-label,
-    .share-label {
+    .share-label,
+    .envmenu-label {
       display: none;
     }
   }