@specbook/ui 0.0.0-stage → 0.2.0

package/src/components/Catalog.tsx

@@ -0,0 +1,324 @@
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
+import { brand } from '../branding'
+import { catalogFilter, catalogService, type Entry, go, route, search } from '../nav'
+import { Lock } from '../panel/icons'
+import { ModeHint } from './ModeHint'
+import { PoweredBy } from './PoweredBy'
+
+export interface ServiceInfo {
+  id: string
+  title?: string
+  version?: string
+  ops: number
+}
+
+/** Groups with more operations than this start collapsed unless something is being searched. */
+const OPEN_LIMIT = 60
+
+const DEFAULT_FLOW_GROUP = 'Default'
+
+function isActive(e: Entry): boolean {
+  const r = route.value
+  return (
+    (e.route.kind === 'op' && r.kind === 'op' && e.route.key === r.key) ||
+    (e.route.kind === 'seq' && r.kind === 'seq' && e.route.id === r.id)
+  )
+}
+
+function OpRow({ e }: { e: Entry }) {
+  return (
+    <button
+      type="button"
+      class={`op-row ${isActive(e) ? 'active' : ''}`}
+      onClick={() => go(e.route)}
+      title={e.path ? `${e.title}\n${e.path}` : e.title}
+    >
+      <span class={`method ${e.method}`}>{e.method}</span>
+      <span class="op-title">
+        {e.title}
+        {e.secured && (
+          <span class="op-lock" title="Needs credentials">
+            <Lock />
+          </span>
+        )}
+      </span>
+      <span class="op-path">{e.path}</span>
+    </button>
+  )
+}
+
+/** Shared by the list and the overview: which entries the current pill and filter select. */
+function useCatalog(entries: Entry[], services: ServiceInfo[]) {
+  const q = catalogFilter.value.trim()
+  const single = services.length <= 1
+  const svc = single ? (services[0]?.id ?? '') : catalogService.value
+  const ops = useMemo(() => entries.filter((e) => e.kind === 'op'), [entries])
+  const flows = useMemo(() => entries.filter((e) => e.kind === 'seq'), [entries])
+  const shownOps = useMemo(() => {
+    const scoped = svc ? ops.filter((e) => e.service === svc) : ops
+    return q ? search(scoped, q, 500) : scoped
+  }, [ops, svc, q])
+  const shownFlows = useMemo(() => {
+    const scoped = svc && !single ? flows.filter((e) => e.tags?.includes(svc)) : flows
+    return q ? search(scoped, q, 100) : scoped
+  }, [flows, svc, q, single])
+  return { q, single, svc, shownOps, shownFlows }
+}
+
+/** The left column: pills, filter and grouped rows. It never changes width, so opening the panel moves nothing. */
+export function CatalogList({ entries, services }: { entries: Entry[]; services: ServiceInfo[] }) {
+  const filter = useRef<HTMLInputElement>(null)
+  const list = useRef<HTMLDivElement>(null)
+  // what the user chose per group; groups they haven't touched follow the default
+  const [chosen, setChosen] = useState<Map<string, boolean>>(new Map())
+  const { q, single, svc, shownOps, shownFlows } = useCatalog(entries, services)
+
+  useEffect(() => {
+    const key = (e: KeyboardEvent) => {
+      const el = e.target as HTMLElement
+      if (e.key === '/' && !/^(INPUT|TEXTAREA|SELECT)$/.test(el.tagName)) {
+        e.preventDefault()
+        filter.current?.focus()
+      }
+    }
+    addEventListener('keydown', key)
+    return () => removeEventListener('keydown', key)
+  }, [])
+
+  // arrow keys walk the rows; going up from the first one returns to the filter
+  useEffect(() => {
+    const el = list.current
+    if (!el) return
+    const move = (e: KeyboardEvent) => {
+      if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return
+      const rows = [...el.querySelectorAll<HTMLElement>('.op-row, .flow-row')]
+      const at = rows.indexOf(document.activeElement as HTMLElement)
+      if (at < 0) return
+      const next = e.key === 'ArrowDown' ? at + 1 : at - 1
+      e.preventDefault()
+      if (next >= 0 && next < rows.length) rows[next]?.focus()
+      else if (next < 0) filter.current?.focus()
+    }
+    el.addEventListener('keydown', move)
+    return () => el.removeEventListener('keydown', move)
+  }, [])
+
+  const groups = useMemo(() => {
+    const m = new Map<string, Entry[]>()
+    for (const e of shownOps) {
+      const tag = e.tag ?? 'default'
+      const name = svc || single ? tag : `${e.service} · ${tag}`
+      m.set(name, [...(m.get(name) ?? []), e])
+    }
+    return [...m.entries()].sort(([a], [b]) => a.localeCompare(b))
+  }, [shownOps, svc, single])
+
+  // "Default" first, then the rest alphabetically
+  const flowGroups = useMemo(() => {
+    const m = new Map<string, Entry[]>()
+    for (const e of shownFlows) {
+      const name = e.flowGroup?.trim() || DEFAULT_FLOW_GROUP
+      m.set(name, [...(m.get(name) ?? []), e])
+    }
+    const rank = (n: string) => (n === DEFAULT_FLOW_GROUP ? 0 : 1)
+    return [...m.entries()].sort(([a], [b]) => rank(a) - rank(b) || a.localeCompare(b))
+  }, [shownFlows])
+
+  const crowded = shownOps.length > OPEN_LIMIT && !q
+  const isOpen = (name: string, rows: Entry[]) =>
+    chosen.get(name) ?? (!crowded || rows.some(isActive))
+  const toggle = (name: string, rows: Entry[]) => {
+    const n = new Map(chosen)
+    n.set(name, !isOpen(name, rows))
+    setChosen(n)
+  }
+
+  return (
+    <div class="catalog" ref={list}>
+      <div class="cat-top">
+        {!single && (
+          <div class="pills" role="tablist" aria-label="APIs">
+            <button
+              type="button"
+              role="tab"
+              aria-selected={svc === ''}
+              class={`pill ${svc === '' ? 'on' : ''}`}
+              onClick={() => (catalogService.value = '')}
+            >
+              All
+            </button>
+            {services.map((s) => (
+              <button
+                type="button"
+                role="tab"
+                aria-selected={svc === s.id}
+                class={`pill ${svc === s.id ? 'on' : ''}`}
+                onClick={() => (catalogService.value = s.id)}
+              >
+                {s.id} <span class="count">{s.ops}</span>
+              </button>
+            ))}
+          </div>
+        )}
+        <div class="cat-filter-wrap">
+          <input
+            ref={filter}
+            type="text"
+            class="cat-filter"
+            placeholder={svc ? `Filter ${svc}` : 'Filter operations and flows'}
+            aria-label="Filter"
+            value={catalogFilter.value}
+            onInput={(e) => (catalogFilter.value = (e.target as HTMLInputElement).value)}
+            onKeyDown={(e) => {
+              if (e.key === 'ArrowDown') {
+                e.preventDefault()
+                list.current?.querySelector<HTMLElement>('.op-row, .flow-row')?.focus()
+              }
+              if (e.key === 'Escape') catalogFilter.value = ''
+            }}
+          />
+          <kbd class="cat-hint" title="Focus the filter">
+            /
+          </kbd>
+        </div>
+      </div>
+
+      {flowGroups.length > 0 && (
+        <section class="flows" aria-label="Flows">
+          <div class="flows-title">
+            <span class="method flow">FLOW</span>
+            <span class="muted small">Multi-step sequences you can run end to end</span>
+            <span class="count">{shownFlows.length}</span>
+          </div>
+          {flowGroups.map(([name, rows]) => {
+            const key = `flows:${name}`
+            const solo = flowGroups.length === 1
+            const expanded = solo || (chosen.get(key) ?? true)
+            return (
+              <div class="flow-group" key={key}>
+                {!solo && (
+                  <button
+                    type="button"
+                    class="group-head flow-head"
+                    aria-expanded={expanded}
+                    onClick={() => {
+                      const n = new Map(chosen)
+                      n.set(key, !expanded)
+                      setChosen(n)
+                    }}
+                  >
+                    <span class="caret">{expanded ? '▾' : '▸'}</span> {name}{' '}
+                    <span class="count">{rows.length}</span>
+                  </button>
+                )}
+                {expanded &&
+                  rows.map((e) => (
+                    <button
+                      type="button"
+                      class={`op-row flow-row ${isActive(e) ? 'active' : ''}`}
+                      onClick={() => go(e.route)}
+                    >
+                      <span class="flow-play" aria-hidden="true">
+                        ▶
+                      </span>
+                      <span class="op-title">{e.title}</span>
+                    </button>
+                  ))}
+              </div>
+            )
+          })}
+        </section>
+      )}
+
+      {groups.map(([name, rows]) => {
+        const expanded = isOpen(name, rows)
+        return (
+          <div class="op-group" key={name}>
+            <button
+              type="button"
+              class="group-head"
+              aria-expanded={expanded}
+              onClick={() => toggle(name, rows)}
+            >
+              <span class="caret">{expanded ? '▾' : '▸'}</span> {name}{' '}
+              <span class="count">{rows.length}</span>
+            </button>
+            {expanded && rows.map((e) => <OpRow e={e} />)}
+          </div>
+        )
+      })}
+      {groups.length === 0 && flowGroups.length === 0 && (
+        <p class="muted cat-empty">
+          {q ? `Nothing matches “${q}”.` : 'No operations.'}{' '}
+          {q && (
+            <button type="button" class="link" onClick={() => (catalogFilter.value = '')}>
+              Clear the filter
+            </button>
+          )}
+        </p>
+      )}
+    </div>
+  )
+}
+
+/** The stage when nothing is open: the API's identity, since the list is the content. */
+export function Overview({ services }: { services: ServiceInfo[] }) {
+  const b = brand.value
+  // wait for the project's branding: showing the fallback first and swapping it makes the page jump
+  if (!b.ready) return <div class="overview" aria-busy="true" />
+  const total = services.reduce((n, s) => n + s.ops, 0)
+  const single = services.length === 1 ? services[0] : undefined
+  const title =
+    b.title ??
+    b.name ??
+    (single
+      ? (single.title ?? single.id)
+      : `${services.length} APIs · ${total.toLocaleString()} operations`)
+  const meta = single
+    ? `${single.ops} ${single.ops === 1 ? 'operation' : 'operations'}${single.version ? ` · v${single.version}` : ''}`
+    : b.name || b.title
+      ? `${services.length} APIs · ${total.toLocaleString()} operations`
+      : undefined
+  return (
+    <div class="overview">
+      {b.logo && (
+        <img
+          class="overview-logo"
+          src={b.logo}
+          alt=""
+          style={
+            b.logoBackground
+              ? { background: b.logoBackground, padding: '10px 16px', borderRadius: '10px' }
+              : undefined
+          }
+        />
+      )}
+      {b.title && b.name && <p class="overview-name">{b.name}</p>}
+      <h1>{title}</h1>
+      {b.tagline && <p class="tagline">{b.tagline}</p>}
+      {meta && <p class="muted">{meta}</p>}
+      <p class="overview-hint">Choose an operation or flow on the left to read it and try it.</p>
+      <ModeHint />
+      <button
+        type="button"
+        class="btn primary overview-browse"
+        onClick={() => go({ kind: 'browse' })}
+      >
+        Browse operations and flows
+      </button>
+      {b.links.length > 0 && (
+        <p class="overview-links">
+          {b.links.map((l) => (
+            <a href={l.href} target="_blank" rel="noreferrer">
+              {l.label}
+            </a>
+          ))}
+        </p>
+      )}
+      <p class="muted overview-keys">
+        <kbd>⌘</kbd> <kbd>K</kbd> jumps anywhere · <kbd>/</kbd> filters the list
+      </p>
+      <PoweredBy />
+    </div>
+  )
+}

package/src/components/EnvBadge.tsx

@@ -0,0 +1,48 @@
+import { env, environmentNote, environmentRisk, environments } from '../store'
+
+/**
+ * The environment a request will run in, and a way to change it. On a phone the header with the
+ * selector is behind a menu or under a panel, so the chip appears in the header and in each panel: it
+ * is a real control (a transparent native select over the label), so a tap opens the platform picker.
+ * Anything but `mock` is flagged, and production more strongly: an environment the config marks
+ * `risk: 'production'`, or by default one whose name contains "prod".
+ */
+export function EnvBadge() {
+  const name = env.value
+  const names = environments.value.includes(name)
+    ? environments.value
+    : [name, ...environments.value]
+  const risk = environmentRisk.value[name]
+  const kind =
+    name === 'mock'
+      ? 'mock'
+      : risk === 'production' || (risk !== 'sandbox' && /prod/i.test(name))
+        ? 'prod'
+        : 'live'
+  const switchable = names.length > 1
+  return (
+    <span
+      class={`env-badge ${kind} ${switchable ? 'switch' : ''}`}
+      title={
+        name === 'mock'
+          ? 'Environment: mock (no network)'
+          : `Environment: ${name}. Requests go to the real API.`
+      }
+    >
+      <span class="env-name">{name}</span>
+      {switchable && (
+        <select
+          aria-label="Environment"
+          value={name}
+          onChange={(e) => (env.value = (e.target as HTMLSelectElement).value)}
+        >
+          {names.map((n) => (
+            <option value={n} title={environmentNote.value[n]}>
+              {n}
+            </option>
+          ))}
+        </select>
+      )}
+    </span>
+  )
+}

package/src/components/EnvironmentMenu.tsx

@@ -0,0 +1,262 @@
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import { engine, isStatic } from '../runtime'
+import { env, version } from '../store'
+
+type Source = 'session' | 'process' | 'environment' | 'shared' | undefined
+type Scope = 'environment' | 'session' | 'shared'
+
+interface SecretRow {
+  name: string
+  key: string
+  source: Source
+}
+interface EnvState {
+  vars: Record<string, string>
+  secrets: SecretRow[]
+  warnings: string[]
+}
+
+const SOURCE_LABEL: Record<NonNullable<Source>, string> = {
+  session: 'this session',
+  process: 'environment variable',
+  environment: 'environment file',
+  shared: 'shared file',
+}
+
+async function post(path: string, body: object) {
+  const r = await fetch(path, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  if (!r.ok) throw new Error(((await r.json()) as { error?: string }).error ?? 'save failed')
+}
+
+/**
+ * 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.
+ */
+export function EnvironmentMenu() {
+  const [state, setState] = useState<EnvState>()
+  const [labels, setLabels] = useState<Record<string, string>>({})
+  const [open, setOpen] = useState(false)
+  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
+
+  const refresh = () =>
+    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])
+
+  useEffect(() => {
+    engine.config(version.value).then((cfg) => {
+      const out: Record<string, string> = {}
+      for (const [profile, p] of Object.entries(cfg.auth ?? {}))
+        for (const m of JSON.stringify(p.apply).matchAll(/secrets\.([\w$-]+)/g))
+          out[m[1] as string] = p.title ?? profile
+      setLabels(out)
+    })
+  }, [])
+
+  const missing = useMemo(
+    () => (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 (!hasAnything) return null
+
+  const run = async (fn: () => Promise<void>) => {
+    setError(undefined)
+    try {
+      await fn()
+      await refresh()
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e))
+    }
+  }
+  const saveSecret = (secret: string, value: string) =>
+    run(async () => {
+      await post('/__specbook/secret', {
+        name: secret,
+        value,
+        scope,
+        env: scope === 'shared' ? undefined : name,
+      })
+      setDraft((d) => ({ ...d, [secret]: '' }))
+    })
+  const saveVar = (varName: string, value: string | null) =>
+    run(() => post('/__specbook/var', { env: name, name: varName, value }))
+
+  return (
+    <div class="envmenu">
+      <button
+        type="button"
+        class="btn envmenu-btn"
+        aria-expanded={open}
+        title={`Variables and credentials for ${name}`}
+        onClick={() => setOpen(!open)}
+      >
+        <span aria-hidden="true">⚙︎</span> Environment settings
+        {missing > 0 && <span class="badge-missing">{missing}</span>}
+      </button>
+
+      {open && (
+        <div class="envmenu-pop" role="dialog" aria-label={`Settings for ${name}`}>
+          <header class="envmenu-head">
+            <strong>{name}</strong>
+            <span class="muted small">
+              {name === 'mock' ? 'mocks need no credentials' : 'values apply to this environment'}
+            </span>
+            <span class="spacer" />
+            <button type="button" class="icon" aria-label="Close" onClick={() => setOpen(false)}>
+              ×
+            </button>
+          </header>
+
+          {state.warnings.map((w) => (
+            <p class="envmenu-warn">{w}</p>
+          ))}
+          {error && <p class="envmenu-warn">{error}</p>}
+
+          <section>
+            <h3>Variables</h3>
+            <p class="muted small">
+              Shared with the team in <code>.specbook/environments/{name}.env</code>.
+            </p>
+            {Object.entries(state.vars).map(([k, v]) => (
+              <div class="envrow">
+                <code>{k}</code>
+                <input
+                  aria-label={`Value of ${k}`}
+                  value={draft[`var:${k}`] ?? v}
+                  onInput={(e) =>
+                    setDraft({ ...draft, [`var:${k}`]: (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>
+              </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>
+        </div>
+      )}
+    </div>
+  )
+}