@specbook/ui 0.2.0 → 0.3.0

package/src/components/EnvironmentMenu.tsx

@@ -1,6 +1,8 @@
 import { useEffect, useMemo, useState } from 'preact/hooks'
+import type { EnvironmentView, VariableRow } from '../engine'
+import { refreshEnvironments } from '../environment-list'
 import { engine, isStatic } from '../runtime'
-import { env, version } from '../store'
+import { env, envSettingsOpen, envVarsVersion, version } from '../store'
 
 type Source = 'session' | 'process' | 'environment' | 'shared' | undefined
 type Scope = 'environment' | 'session' | 'shared'
@@ -23,6 +25,13 @@ const SOURCE_LABEL: Record<NonNullable<Source>, string> = {
   shared: 'shared file',
 }
 
+const VARIABLE_LABEL: Record<VariableRow['source'], string> = {
+  default: 'default',
+  config: 'config',
+  file: 'file',
+  browser: 'this browser',
+}
+
 async function post(path: string, body: object) {
   const r = await fetch(path, {
     method: 'POST',
@@ -32,32 +41,59 @@ async function post(path: string, body: object) {
   if (!r.ok) throw new Error(((await r.json()) as { error?: string }).error ?? 'save failed')
 }
 
+/** What a variable is for in this environment: the calls and sign-ins that read it. */
+function usesOf(row: VariableRow, view: EnvironmentView): string[] {
+  const u = view.uses[row.name]
+  if (!u) return []
+  const out: string[] = []
+  for (const service of u.services) {
+    const a = view.addresses.find((x) => x.service === service)
+    out.push(a?.url ? `${service} calls go to ${a.url}` : `${service} calls use this address`)
+  }
+  for (const p of u.profiles) out.push(`${p.profile} sign-in reads this (${p.field})`)
+  return out
+}
+
 /**
- * Header control for what the selected environment needs: its variables (`<env>.env`, committed) and
- * secrets (`<env>.secrets.env`, gitignored, or this session only). The badge counts secrets still missing.
+ * Header control for what the selected environment needs: its variables (defaults from the config, and
+ * the environment's own in `<env>.env`, committed, or in this browser) and secrets (`<env>.secrets.env`,
+ * gitignored, or this session only). The badge counts secrets still missing.
  */
 export function EnvironmentMenu() {
   const [state, setState] = useState<EnvState>()
+  const [view, setView] = useState<EnvironmentView>()
   const [labels, setLabels] = useState<Record<string, string>>({})
-  const [open, setOpen] = useState(false)
+  const open = envSettingsOpen.value
+  const setOpen = (o: boolean) => (envSettingsOpen.value = o)
   const [scope, setScope] = useState<Scope>('environment')
   const [draft, setDraft] = useState<Record<string, string>>({})
   const [newVar, setNewVar] = useState({ name: '', value: '' })
   const [error, setError] = useState<string>()
   const name = env.value
 
+  // the dev server's view of secrets (and committed-secret warnings); a static page has no files
   const refresh = () =>
-    fetch(`/__specbook/environment?env=${encodeURIComponent(name)}`)
-      .then((r) => r.json() as Promise<EnvState>)
-      .then(setState, () => setState(undefined))
+    isStatic
+      ? Promise.resolve()
+      : fetch(`/__specbook/environment?env=${encodeURIComponent(name)}`)
+          .then((r) => r.json() as Promise<EnvState>)
+          .then(setState, () => setState(undefined))
 
   useEffect(() => {
-    if (isStatic) return
     refresh()
     setScope(name === 'mock' ? 'session' : 'environment')
     setDraft({})
   }, [name])
 
+  // the variables as the settings show them: defaults and overrides, and where each address goes
+  useEffect(() => {
+    let on = true
+    engine.environmentView(name, version.value).then((v) => on && setView(v))
+    return () => {
+      on = false
+    }
+  }, [name, version.value, envVarsVersion.value])
+
   useEffect(() => {
     engine.config(version.value).then((cfg) => {
       const out: Record<string, string> = {}
@@ -72,9 +108,10 @@ export function EnvironmentMenu() {
     () => (name === 'mock' ? 0 : (state?.secrets.filter((s) => !s.source).length ?? 0)),
     [state, name],
   )
-  if (isStatic || !state) return null
-  const hasAnything =
-    state.secrets.length > 0 || Object.keys(state.vars).length > 0 || name !== 'mock'
+  if (!view) return null
+  if (!isStatic && !state) return null
+  const secrets = state?.secrets ?? []
+  const hasAnything = secrets.length > 0 || view.rows.length > 0 || name !== 'mock'
   if (!hasAnything) return null
 
   const run = async (fn: () => Promise<void>) => {
@@ -96,8 +133,27 @@ export function EnvironmentMenu() {
       })
       setDraft((d) => ({ ...d, [secret]: '' }))
     })
+  // a variable change moves addresses and sign-in origins: what is derived from them is redone
   const saveVar = (varName: string, value: string | null) =>
-    run(() => post('/__specbook/var', { env: name, name: varName, value }))
+    run(async () => {
+      await engine.setVariable(name, varName, value === '' ? null : value)
+      envVarsVersion.value += 1
+    })
+  const removeEnvironment = () =>
+    run(async () => {
+      engine.deleteEnvironment(name)
+      env.value = 'mock'
+      await refreshEnvironments()
+    })
+
+  const warnings = [
+    ...(state?.warnings ?? []),
+    ...(name === 'mock' ? [] : view.addresses.filter((a) => a.error).map((a) => a.error as string)),
+  ]
+  const ordered = [...view.rows].sort(
+    (a, b) =>
+      Number(!!view.uses[b.name]) - Number(!!view.uses[a.name]) || a.name.localeCompare(b.name),
+  )
 
   return (
     <div class="envmenu">
@@ -106,9 +162,12 @@ export function EnvironmentMenu() {
         class="btn envmenu-btn"
         aria-expanded={open}
         title={`Variables and credentials for ${name}`}
+        aria-label={
+          missing > 0 ? `Environment settings, ${missing} missing` : 'Environment settings'
+        }
         onClick={() => setOpen(!open)}
       >
-        <span aria-hidden="true">⚙︎</span> Environment settings
+        <span aria-hidden="true">⚙︎</span> <span class="envmenu-label">Environment settings</span>
         {missing > 0 && <span class="badge-missing">{missing}</span>}
       </button>
 
@@ -125,7 +184,7 @@ export function EnvironmentMenu() {
             </button>
           </header>
 
-          {state.warnings.map((w) => (
+          {warnings.map((w) => (
             <p class="envmenu-warn">{w}</p>
           ))}
           {error && <p class="envmenu-warn">{error}</p>}
@@ -133,128 +192,179 @@ export function EnvironmentMenu() {
           <section>
             <h3>Variables</h3>
             <p class="muted small">
-              Shared with the team in <code>.specbook/environments/{name}.env</code>.
+              {isStatic ? (
+                'Kept in this browser; the defaults come from the spec or site.'
+              ) : (
+                <>
+                  Shared with the team in <code>.specbook/environments/{name}.env</code>. Defaults
+                  come from specbook.config.ts.
+                </>
+              )}
             </p>
-            {Object.entries(state.vars).map(([k, v]) => (
-              <div class="envrow">
-                <code>{k}</code>
+            {ordered.map((row) => {
+              const own = row.source === 'file' || row.source === 'browser'
+              const key = `var:${row.name}`
+              return (
+                <div key={row.name}>
+                  <div class="envrow">
+                    <code>{row.name}</code>
+                    <input
+                      aria-label={`Value of ${row.name}`}
+                      value={draft[key] ?? row.value}
+                      disabled={!row.editable}
+                      onInput={(e) =>
+                        setDraft({ ...draft, [key]: (e.target as HTMLInputElement).value })
+                      }
+                      onBlur={() => {
+                        const next = draft[key]
+                        if (next !== undefined && next !== row.value) saveVar(row.name, next)
+                      }}
+                      onKeyDown={(e) => e.key === 'Enter' && (e.target as HTMLInputElement).blur()}
+                    />
+                    <span class={`src ${own ? 'set' : 'inherited'}`}>
+                      {VARIABLE_LABEL[row.source]}
+                    </span>
+                    {own && row.editable && (
+                      <button
+                        type="button"
+                        class="icon"
+                        aria-label={
+                          row.fallback !== undefined ? `Reset ${row.name}` : `Remove ${row.name}`
+                        }
+                        title={
+                          row.fallback !== undefined
+                            ? `Back to ${row.fallback}`
+                            : 'Remove this variable'
+                        }
+                        onClick={() => saveVar(row.name, null)}
+                      >
+                        ×
+                      </button>
+                    )}
+                  </div>
+                  {usesOf(row, view).map((line) => (
+                    <p class="muted small envuse">{line}</p>
+                  ))}
+                </div>
+              )
+            })}
+            {name !== 'mock' &&
+              view.addresses
+                .filter(
+                  (a) =>
+                    a.url && !Object.values(view.uses).some((u) => u.services.includes(a.service)),
+                )
+                .map((a) => (
+                  <p class="muted small envuse">
+                    {a.service} calls go to {a.url}
+                  </p>
+                ))}
+            {name !== 'mock' && (
+              <form
+                class="envrow"
+                onSubmit={(e) => {
+                  e.preventDefault()
+                  if (!newVar.name) return
+                  saveVar(newVar.name, newVar.value).then(() => setNewVar({ name: '', value: '' }))
+                }}
+              >
+                <input
+                  placeholder="name"
+                  aria-label="New variable name"
+                  value={newVar.name}
+                  onInput={(e) =>
+                    setNewVar({ ...newVar, name: (e.target as HTMLInputElement).value })
+                  }
+                />
                 <input
-                  aria-label={`Value of ${k}`}
-                  value={draft[`var:${k}`] ?? v}
+                  placeholder="value"
+                  aria-label="New variable value"
+                  value={newVar.value}
                   onInput={(e) =>
-                    setDraft({ ...draft, [`var:${k}`]: (e.target as HTMLInputElement).value })
+                    setNewVar({ ...newVar, value: (e.target as HTMLInputElement).value })
                   }
-                  onBlur={() => {
-                    const next = draft[`var:${k}`]
-                    if (next !== undefined && next !== v) saveVar(k, next)
-                  }}
-                  onKeyDown={(e) => e.key === 'Enter' && (e.target as HTMLInputElement).blur()}
                 />
-                <button
-                  type="button"
-                  class="icon"
-                  aria-label={`Remove ${k}`}
-                  onClick={() => saveVar(k, null)}
-                >
-                  ×
+                <button type="submit" class="btn" disabled={!newVar.name}>
+                  Add
+                </button>
+              </form>
+            )}
+            {view.removable && (
+              <p>
+                <button type="button" class="link" onClick={removeEnvironment}>
+                  Delete environment
                 </button>
-              </div>
-            ))}
-            <form
-              class="envrow"
-              onSubmit={(e) => {
-                e.preventDefault()
-                if (!newVar.name) return
-                saveVar(newVar.name, newVar.value).then(() => setNewVar({ name: '', value: '' }))
-              }}
-            >
-              <input
-                placeholder="name"
-                aria-label="New variable name"
-                value={newVar.name}
-                onInput={(e) =>
-                  setNewVar({ ...newVar, name: (e.target as HTMLInputElement).value })
-                }
-              />
-              <input
-                placeholder="value"
-                aria-label="New variable value"
-                value={newVar.value}
-                onInput={(e) =>
-                  setNewVar({ ...newVar, value: (e.target as HTMLInputElement).value })
-                }
-              />
-              <button type="submit" class="btn" disabled={!newVar.name}>
-                Add
-              </button>
-            </form>
-          </section>
-
-          <section>
-            <h3>Secrets</h3>
-            {state.secrets.length === 0 ? (
-              <p class="muted small">
-                None declared. Add <code>secrets: {'{ NAME: {} }'}</code> to the config.
               </p>
-            ) : (
-              <>
-                <label class="envrow scope">
-                  <span class="muted small">Save to</span>
-                  <select
-                    aria-label="Where to save secrets"
-                    value={scope}
-                    onChange={(e) => setScope((e.target as HTMLSelectElement).value as Scope)}
-                  >
-                    <option value="environment">{name}.secrets.env (remembered here)</option>
-                    <option value="session">this session only</option>
-                    <option value="shared">all environments (secrets.local.env)</option>
-                  </select>
-                </label>
-                {state.secrets.map((s) => (
-                  <form
-                    class="secretrow"
-                    onSubmit={(e) => {
-                      e.preventDefault()
-                      saveSecret(s.name, draft[s.name] ?? '')
-                    }}
-                  >
-                    <div class="secretrow-head">
-                      <span>{labels[s.name] ?? s.name}</span>
-                      <code class="muted small">{s.key}</code>
-                      <span class={`src ${s.source ? 'set' : 'missing'}`}>
-                        {s.source ? SOURCE_LABEL[s.source] : 'missing'}
-                      </span>
-                    </div>
-                    <div class="envrow">
-                      <input
-                        type="password"
-                        autocomplete="off"
-                        aria-label={`Value of ${s.name}`}
-                        placeholder={s.source ? '•••••• (type to replace)' : 'paste a value'}
-                        value={draft[s.name] ?? ''}
-                        onInput={(e) =>
-                          setDraft({ ...draft, [s.name]: (e.target as HTMLInputElement).value })
-                        }
-                      />
-                      <button type="submit" class="btn" disabled={!draft[s.name]}>
-                        Save
-                      </button>
-                      {s.source && s.source !== 'process' && (
-                        <button
-                          type="button"
-                          class="link"
-                          onClick={() => saveSecret(s.name, '')}
-                          title="Remove the value from the selected place"
-                        >
-                          Clear
-                        </button>
-                      )}
-                    </div>
-                  </form>
-                ))}
-              </>
             )}
           </section>
+
+          {!isStatic && (
+            <section>
+              <h3>Secrets</h3>
+              {secrets.length === 0 ? (
+                <p class="muted small">
+                  None declared. Add <code>secrets: {'{ NAME: {} }'}</code> to the config.
+                </p>
+              ) : (
+                <>
+                  <label class="envrow scope">
+                    <span class="muted small">Save to</span>
+                    <select
+                      aria-label="Where to save secrets"
+                      value={scope}
+                      onChange={(e) => setScope((e.target as HTMLSelectElement).value as Scope)}
+                    >
+                      <option value="environment">{name}.secrets.env (remembered here)</option>
+                      <option value="session">this session only</option>
+                      <option value="shared">all environments (secrets.local.env)</option>
+                    </select>
+                  </label>
+                  {secrets.map((s) => (
+                    <form
+                      class="secretrow"
+                      onSubmit={(e) => {
+                        e.preventDefault()
+                        saveSecret(s.name, draft[s.name] ?? '')
+                      }}
+                    >
+                      <div class="secretrow-head">
+                        <span>{labels[s.name] ?? s.name}</span>
+                        <code class="muted small">{s.key}</code>
+                        <span class={`src ${s.source ? 'set' : 'missing'}`}>
+                          {s.source ? SOURCE_LABEL[s.source] : 'missing'}
+                        </span>
+                      </div>
+                      <div class="envrow">
+                        <input
+                          type="password"
+                          autocomplete="off"
+                          aria-label={`Value of ${s.name}`}
+                          placeholder={s.source ? '•••••• (type to replace)' : 'paste a value'}
+                          value={draft[s.name] ?? ''}
+                          onInput={(e) =>
+                            setDraft({ ...draft, [s.name]: (e.target as HTMLInputElement).value })
+                          }
+                        />
+                        <button type="submit" class="btn" disabled={!draft[s.name]}>
+                          Save
+                        </button>
+                        {s.source && s.source !== 'process' && (
+                          <button
+                            type="button"
+                            class="link"
+                            onClick={() => saveSecret(s.name, '')}
+                            title="Remove the value from the selected place"
+                          >
+                            Clear
+                          </button>
+                        )}
+                      </div>
+                    </form>
+                  ))}
+                </>
+              )}
+            </section>
+          )}
         </div>
       )}
     </div>

package/src/components/Fields.tsx

@@ -7,6 +7,8 @@ export interface FieldSpec {
   label?: string
   description?: string
   default?: unknown
+  /** makes a fresh starting value (a faker value): the control offers to generate another */
+  generate?: () => unknown
   options?: { label: string; value: unknown }[]
   shape?: Record<string, FieldSpec>
   item?: FieldSpec
@@ -50,11 +52,26 @@ function baseSpec(ctl: any, o: any): FieldSpec {
         max: o.max,
       }
     default:
-      return { kind: ctl.kind, default: o.default, min: o.min, max: o.max }
+      return typeof o.default === 'function'
+        ? { kind: ctl.kind, generate: o.default as () => unknown, min: o.min, max: o.max }
+        : { kind: ctl.kind, default: o.default, min: o.min, max: o.max }
   }
 }
 
+/** A fresh generated value for a field, or its plain default when it has no generator or the generator cannot run. */
+export function generateFor(spec: FieldSpec): unknown {
+  if (spec.generate) {
+    try {
+      return spec.generate()
+    } catch {
+      /* faker is not ready: fall through to the plain default */
+    }
+  }
+  return defaultFor({ ...spec, generate: undefined })
+}
+
 export function defaultFor(spec: FieldSpec): unknown {
+  if (spec.generate) return generateFor(spec)
   switch (spec.kind) {
     case 'select':
       return spec.options?.[0]?.value

package/src/components/NewEnvironmentDialog.tsx

@@ -0,0 +1,118 @@
+import { useEffect, useRef, useState } from 'preact/hooks'
+import { refreshEnvironments } from '../environment-list'
+import { engine } from '../runtime'
+import { env, environments, envSettingsOpen, newEnvironmentOpen, version } from '../store'
+
+const NAME = /^[A-Za-z0-9_-]+$/
+
+/**
+ * Makes an environment as a copy of another one's variables: its own address, its own sign-in provider, the
+ * same secrets as nothing (those are asked for again). In a project it becomes `.specbook/environments/<name>.env`;
+ * on a page without files it is kept in this browser.
+ */
+export function NewEnvironmentDialog() {
+  return newEnvironmentOpen.value ? <Dialog /> : null
+}
+
+// mounted only while open, so each opening starts fresh: empty name, a copy of what is being looked at
+function Dialog() {
+  const [name, setName] = useState('')
+  const [from, setFrom] = useState(() =>
+    // unless that is mock (nothing of its own to copy)
+    env.value === 'mock' ? (environments.value.find((e) => e !== 'mock') ?? 'mock') : env.value,
+  )
+  const [error, setError] = useState<string>()
+  const [busy, setBusy] = useState(false)
+  const input = useRef<HTMLInputElement>(null)
+
+  useEffect(() => {
+    input.current?.focus()
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') newEnvironmentOpen.value = false
+    }
+    addEventListener('keydown', onKey)
+    return () => removeEventListener('keydown', onKey)
+  }, [])
+
+  const close = () => (newEnvironmentOpen.value = false)
+  const taken = environments.value.includes(name)
+  const problem =
+    name === ''
+      ? undefined
+      : !NAME.test(name)
+        ? 'Use letters, digits, "-" and "_"'
+        : name === 'mock' || taken
+          ? `"${name}" already exists`
+          : undefined
+
+  const create = async () => {
+    setBusy(true)
+    setError(undefined)
+    try {
+      await engine.createEnvironment(name, from, version.value)
+      await refreshEnvironments()
+      env.value = name
+      newEnvironmentOpen.value = false
+      envSettingsOpen.value = true
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div class="palette-backdrop newenv-backdrop">
+      <button type="button" class="palette-dismiss" aria-label="Close" onClick={close} />
+      <div class="palette newenv" role="dialog" aria-label="New environment">
+        <form
+          onSubmit={(e) => {
+            e.preventDefault()
+            if (name && !problem && !busy) create()
+          }}
+        >
+          <h2>New environment</h2>
+          <label>
+            <span class="muted small">Name</span>
+            <input
+              ref={input}
+              type="text"
+              aria-label="Environment name"
+              placeholder="staging"
+              value={name}
+              onInput={(e) => setName((e.target as HTMLInputElement).value.trim())}
+            />
+          </label>
+          <label>
+            <span class="muted small">Duplicate of</span>
+            <select
+              aria-label="Duplicate of"
+              value={from}
+              onChange={(e) => setFrom((e.target as HTMLSelectElement).value)}
+            >
+              {environments.value
+                .filter((e) => e !== 'mock')
+                .map((e) => (
+                  <option value={e}>{e}</option>
+                ))}
+            </select>
+          </label>
+          <p class="muted small">
+            It starts with {from}'s variables. Change its address in Variables; secrets are asked
+            for again.
+          </p>
+          {(problem || error) && <p class="envmenu-warn">{problem ?? error}</p>}
+          <div class="envrow">
+            <span class="spacer" />
+            <button type="button" class="btn" onClick={close}>
+              Cancel
+            </button>
+            <button type="submit" class="btn primary" disabled={!name || !!problem || busy}>
+              Create
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  )
+}

package/src/components/Palette.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
 import { type Entry, go, paletteOpen, search } from '../nav'
+import { isMinimal } from '../runtime'
 
 export function Palette({ entries }: { entries: Entry[] }) {
   const [q, setQ] = useState('')
@@ -47,7 +48,9 @@ export function Palette({ entries }: { entries: Entry[] }) {
         <input
           ref={input}
           type="text"
-          placeholder="Jump to a sequence or operation…"
+          placeholder={
+            isMinimal ? 'Jump to a flow or request…' : 'Jump to a sequence, request or operation…'
+          }
           value={q}
           onInput={(e) => {
             setQ((e.target as HTMLInputElement).value)
@@ -73,7 +76,9 @@ export function Palette({ entries }: { entries: Entry[] }) {
                 onClick={() => choose(e)}
               >
                 <span class="p-title">{e.title}</span>
-                <span class="muted">{e.kind === 'seq' ? 'Sequence' : e.group}</span>
+                <span class="muted">
+                  {e.kind === 'seq' ? 'Sequence' : e.kind === 'req' ? 'Request' : e.group}
+                </span>
               </button>
             </li>
           ))}