@specbook/ui 0.0.0-stage → 0.1.0

package/src/components/Fields.tsx

@@ -0,0 +1,220 @@
+import type { JSX } from 'preact'
+
+/** Normalised field description, built from either a Control or a described input control. */
+export interface FieldSpec {
+  kind: string
+  /** a friendlier name than the parameter key, and a sentence about it */
+  label?: string
+  description?: string
+  default?: unknown
+  options?: { label: string; value: unknown }[]
+  shape?: Record<string, FieldSpec>
+  item?: FieldSpec
+  min?: number
+  max?: number
+}
+
+export function specFromControl(ctl: any): FieldSpec {
+  const o = ctl.opts ?? {}
+  const meta = {
+    ...(typeof o.label === 'string' ? { label: o.label as string } : {}),
+    ...(typeof o.description === 'string' ? { description: o.description as string } : {}),
+  }
+  return { ...baseSpec(ctl, o), ...meta }
+}
+
+function baseSpec(ctl: any, o: any): FieldSpec {
+  switch (ctl.kind) {
+    case 'select':
+    case 'multiselect': {
+      const value = (x: unknown) => (typeof o.value === 'function' ? o.value(x) : x)
+      const label = (x: unknown) => (typeof o.label === 'function' ? o.label(x) : String(value(x)))
+      return {
+        kind: ctl.kind,
+        options: (o.options as unknown[]).map((x) => ({ label: label(x), value: value(x) })),
+      }
+    }
+    case 'object':
+      return {
+        kind: 'object',
+        shape: Object.fromEntries(
+          Object.entries(o.shape as Record<string, any>).map(([k, v]) => [k, specFromControl(v)]),
+        ),
+      }
+    case 'array':
+      return {
+        kind: 'array',
+        item: specFromControl(o.item),
+        default: o.default,
+        min: o.min,
+        max: o.max,
+      }
+    default:
+      return { kind: ctl.kind, default: o.default, min: o.min, max: o.max }
+  }
+}
+
+export function defaultFor(spec: FieldSpec): unknown {
+  switch (spec.kind) {
+    case 'select':
+      return spec.options?.[0]?.value
+    case 'multiselect':
+      return []
+    case 'object':
+      return Object.fromEntries(
+        Object.entries(spec.shape ?? {}).map(([k, s]) => [k, defaultFor(s)]),
+      )
+    case 'array':
+      return spec.default ?? []
+    case 'boolean':
+      return spec.default ?? false
+    case 'number':
+      return spec.default ?? 0
+    default:
+      return spec.default ?? ''
+  }
+}
+
+interface FieldProps {
+  name: string
+  spec: FieldSpec
+  value: unknown
+  onChange: (v: unknown) => void
+}
+
+const same = (a: unknown, b: unknown) => a === b || JSON.stringify(a) === JSON.stringify(b)
+
+export function Field({ name, spec, value, onChange }: FieldProps): JSX.Element {
+  const wrap = (body: JSX.Element) => (
+    <div class="field">
+      <span class="label">{name}</span>
+      {body}
+    </div>
+  )
+  switch (spec.kind) {
+    case 'number':
+      return wrap(
+        <input
+          type="number"
+          value={Number(value ?? 0)}
+          min={spec.min}
+          max={spec.max}
+          onInput={(e) => onChange(Number((e.target as HTMLInputElement).value))}
+        />,
+      )
+    case 'boolean':
+      return wrap(
+        <input
+          type="checkbox"
+          checked={Boolean(value)}
+          onChange={(e) => onChange((e.target as HTMLInputElement).checked)}
+        />,
+      )
+    case 'date':
+      return wrap(
+        <input
+          type="date"
+          value={String(value ?? '')}
+          onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+        />,
+      )
+    case 'select': {
+      const idx = Math.max(
+        0,
+        (spec.options ?? []).findIndex((o) => same(o.value, value)),
+      )
+      return wrap(
+        <select
+          value={idx}
+          onChange={(e) =>
+            onChange(spec.options?.[Number((e.target as HTMLSelectElement).value)]?.value)
+          }
+        >
+          {(spec.options ?? []).map((o, i) => (
+            <option value={i}>{o.label}</option>
+          ))}
+        </select>,
+      )
+    }
+    case 'multiselect': {
+      const current = (value as unknown[]) ?? []
+      return wrap(
+        <div>
+          {(spec.options ?? []).map((o) => (
+            <label class="row">
+              <input
+                type="checkbox"
+                checked={current.some((c) => same(c, o.value))}
+                onChange={(e) =>
+                  onChange(
+                    (e.target as HTMLInputElement).checked
+                      ? [...current, o.value]
+                      : current.filter((c) => !same(c, o.value)),
+                  )
+                }
+              />
+              {o.label}
+            </label>
+          ))}
+        </div>,
+      )
+    }
+    case 'object': {
+      const obj = (value ?? {}) as Record<string, unknown>
+      return wrap(
+        <div class="nested">
+          {Object.entries(spec.shape ?? {}).map(([k, s]) => (
+            <Field
+              name={k}
+              spec={s}
+              value={obj[k]}
+              onChange={(v) => onChange({ ...obj, [k]: v })}
+            />
+          ))}
+        </div>,
+      )
+    }
+    case 'array': {
+      const list = (value as unknown[]) ?? []
+      const item = spec.item as FieldSpec
+      return wrap(
+        <div class="nested">
+          {list.map((v, i) => (
+            <div class="row">
+              <Field
+                name={`#${i + 1}`}
+                spec={item}
+                value={v}
+                onChange={(nv) => onChange(list.map((x, j) => (j === i ? nv : x)))}
+              />
+              <button
+                type="button"
+                class="btn"
+                disabled={spec.min !== undefined && list.length <= spec.min}
+                onClick={() => onChange(list.filter((_, j) => j !== i))}
+              >
+                Remove
+              </button>
+            </div>
+          ))}
+          <button
+            type="button"
+            class="btn"
+            disabled={spec.max !== undefined && list.length >= spec.max}
+            onClick={() => onChange([...list, defaultFor(item)])}
+          >
+            Add
+          </button>
+        </div>,
+      )
+    }
+    default:
+      return wrap(
+        <input
+          type="text"
+          value={String(value ?? '')}
+          onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+        />,
+      )
+  }
+}

package/src/components/GitHubStar.tsx

@@ -0,0 +1,22 @@
+import { GitHubMark } from '../panel/icons'
+import { REPO_URL } from '../viewer/site'
+
+/**
+ * A way to the repository. Only in the viewer (a project's own published site has its own header and is
+ * not ours to put links in).
+ */
+export function GitHubStar() {
+  if (!globalThis.__SPECBOOK_VIEWER__?.source) return null
+  return (
+    <a
+      class="btn gh-star"
+      href={REPO_URL}
+      target="_blank"
+      rel="noopener"
+      title="Specbook's source is on GitHub"
+    >
+      <GitHubMark />
+      <span class="gh-label">GitHub</span>
+    </a>
+  )
+}

package/src/components/ListResizer.tsx

@@ -0,0 +1,70 @@
+import { signal } from '@preact/signals'
+
+const KEY = 'specbook:list-width'
+export const MIN = 280
+const maxWidth = () => Math.round(innerWidth * 0.55)
+
+function load(): number | undefined {
+  try {
+    const n = Number(localStorage.getItem(KEY))
+    return n >= MIN ? n : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** The list column's width in px; undefined = the stylesheet's responsive default. */
+export const listWidth = signal<number | undefined>(load())
+
+function set(w: number | undefined) {
+  listWidth.value = w === undefined ? undefined : Math.round(Math.max(MIN, Math.min(maxWidth(), w)))
+  try {
+    if (listWidth.value === undefined) localStorage.removeItem(KEY)
+    else localStorage.setItem(KEY, String(listWidth.value))
+  } catch {
+    /* optional */
+  }
+}
+
+/** A draggable (and keyboard-operable) edge on the list column; double-click restores the default. */
+export function ListResizer() {
+  const drag = (e: PointerEvent) => {
+    e.preventDefault()
+    document.body.classList.add('resizing')
+    const move = (m: PointerEvent) => set(m.clientX)
+    const up = () => {
+      document.body.classList.remove('resizing')
+      removeEventListener('pointermove', move)
+      removeEventListener('pointerup', up)
+    }
+    addEventListener('pointermove', move)
+    addEventListener('pointerup', up)
+  }
+  const current = () =>
+    listWidth.value ?? document.querySelector<HTMLElement>('.list-col')?.offsetWidth ?? 360
+
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: a draggable splitter has no native element
+    <div
+      class="list-resizer"
+      role="separator"
+      aria-orientation="vertical"
+      aria-label="Resize the list"
+      aria-valuenow={listWidth.value}
+      aria-valuemin={MIN}
+      tabIndex={0}
+      title="Drag to resize · double-click to reset"
+      onPointerDown={drag}
+      onDblClick={() => set(undefined)}
+      onKeyDown={(e) => {
+        if (e.key === 'ArrowLeft') {
+          e.preventDefault()
+          set(current() - 24)
+        } else if (e.key === 'ArrowRight') {
+          e.preventDefault()
+          set(current() + 24)
+        }
+      }}
+    />
+  )
+}

package/src/components/ModeHint.tsx

@@ -0,0 +1,17 @@
+import { environments } from '../store'
+
+/**
+ * In the viewer a document opens on mock data. Say so, and where the real API is, once, on the stage:
+ * someone who has pasted a link and sees a response should not wonder whether it came from the server.
+ */
+export function ModeHint() {
+  if (!globalThis.__SPECBOOK_VIEWER__) return null
+  const live = environments.value.some((e) => e !== 'mock')
+  return (
+    <p class="muted overview-mode">
+      {live
+        ? 'Requests start on mock data. Switch Environment to live to call the real API.'
+        : 'Requests run on generated mock data: this document does not say where the API lives.'}
+    </p>
+  )
+}

package/src/components/Palette.tsx

@@ -0,0 +1,85 @@
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
+import { type Entry, go, paletteOpen, search } from '../nav'
+
+export function Palette({ entries }: { entries: Entry[] }) {
+  const [q, setQ] = useState('')
+  const [sel, setSel] = useState(0)
+  const input = useRef<HTMLInputElement>(null)
+  const open = paletteOpen.value
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
+        e.preventDefault()
+        paletteOpen.value = !paletteOpen.value
+      } else if (e.key === 'Escape') paletteOpen.value = false
+    }
+    addEventListener('keydown', onKey)
+    return () => removeEventListener('keydown', onKey)
+  }, [])
+
+  useEffect(() => {
+    if (open) {
+      setQ('')
+      setSel(0)
+      setTimeout(() => input.current?.focus(), 0)
+    }
+  }, [open])
+
+  const results = useMemo(() => search(entries, q, 30), [entries, q])
+  if (!open) return null
+
+  const choose = (e: Entry | undefined) => {
+    if (!e) return
+    paletteOpen.value = false
+    go(e.route)
+  }
+
+  return (
+    <div class="palette-backdrop">
+      <button
+        type="button"
+        class="palette-dismiss"
+        aria-label="Close"
+        onClick={() => (paletteOpen.value = false)}
+      />
+      <div class="palette" role="dialog" aria-label="Jump to">
+        <input
+          ref={input}
+          type="text"
+          placeholder="Jump to a sequence or operation…"
+          value={q}
+          onInput={(e) => {
+            setQ((e.target as HTMLInputElement).value)
+            setSel(0)
+          }}
+          onKeyDown={(e) => {
+            if (e.key === 'ArrowDown') {
+              e.preventDefault()
+              setSel(Math.min(results.length - 1, sel + 1))
+            } else if (e.key === 'ArrowUp') {
+              e.preventDefault()
+              setSel(Math.max(0, sel - 1))
+            } else if (e.key === 'Enter') choose(results[sel])
+          }}
+        />
+        <ul>
+          {results.map((e, i) => (
+            <li>
+              <button
+                type="button"
+                class={i === sel ? 'sel' : ''}
+                onMouseEnter={() => setSel(i)}
+                onClick={() => choose(e)}
+              >
+                <span class="p-title">{e.title}</span>
+                <span class="muted">{e.kind === 'seq' ? 'Sequence' : e.group}</span>
+              </button>
+            </li>
+          ))}
+          {results.length === 0 && <li class="muted pad">Nothing matches “{q}”</li>}
+        </ul>
+      </div>
+    </div>
+  )
+}

package/src/components/PoweredBy.tsx

@@ -0,0 +1,15 @@
+import { badgeHref, showBadge } from '../badge'
+import { brand } from '../branding'
+import { isStatic } from '../runtime'
+
+export function PoweredBy() {
+  const host = globalThis.location?.hostname ?? ''
+  if (!showBadge({ host, published: isStatic, badge: brand.value.badge })) return null
+  return (
+    <p class="powered-by">
+      <a href={badgeHref(host)} target="_blank" rel="noopener">
+        Powered by Specbook
+      </a>
+    </p>
+  )
+}

package/src/components/ShareMenu.tsx

@@ -0,0 +1,94 @@
+import { useState } from 'preact/hooks'
+import { route } from '../nav'
+import { ShareIcon } from '../panel/icons'
+import { shareable, shareLinks } from '../viewer/share'
+
+/**
+ * Share, for the hosted viewer only (a project's own site has no viewer global). The menu says why when a
+ * link would not work for others, rather than offering one that fails for whoever opens it.
+ */
+export function ShareMenu() {
+  const v = globalThis.__SPECBOOK_VIEWER__
+  const [open, setOpen] = useState(false)
+  const [copied, setCopied] = useState(false)
+  if (!v?.source) return null
+  void route.value // re-render when the operation changes, so the link follows it
+
+  const can = shareable(v.source)
+  const links = can.ok
+    ? shareLinks(
+        { origin: location.origin, pathname: location.pathname, hash: location.hash },
+        can.spec,
+        v.open.title,
+      )
+    : undefined
+
+  const copy = async () => {
+    if (!links) return
+    try {
+      await navigator.clipboard.writeText(links.link)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1500)
+    } catch {
+      /* the link is shown in the menu to copy by hand */
+    }
+  }
+
+  return (
+    <div class="share">
+      <button
+        type="button"
+        class="btn"
+        aria-expanded={open}
+        aria-haspopup="true"
+        aria-label="Share"
+        onClick={() => setOpen(!open)}
+      >
+        <ShareIcon />
+        <span class="share-label">Share</span>
+      </button>
+      {open && (
+        <div class="share-pop" role="menu">
+          {links ? (
+            <>
+              <input
+                class="share-link"
+                readOnly
+                value={links.link}
+                aria-label="Link to this view"
+                onFocus={(e) => (e.target as HTMLInputElement).select()}
+              />
+              <div class="share-actions">
+                <button type="button" class="btn primary" onClick={copy}>
+                  {copied ? 'Copied' : 'Copy link'}
+                </button>
+                {typeof navigator.share === 'function' && (
+                  <button
+                    type="button"
+                    class="btn"
+                    onClick={() =>
+                      void navigator.share({ title: links.title, url: links.link }).catch(() => {})
+                    }
+                  >
+                    Share…
+                  </button>
+                )}
+              </div>
+              <ul class="share-targets">
+                {links.targets.map((t) => (
+                  <li>
+                    <a href={t.href} target="_blank" rel="noopener noreferrer">
+                      {t.label}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </>
+          ) : (
+            <p class="muted">{can.ok ? '' : can.reason}</p>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/ThemeToggle.tsx

@@ -0,0 +1,52 @@
+import { cycleTheme, type Theme, theme } from '../theme'
+
+const LABEL: Record<Theme, string> = {
+  auto: 'Theme: follows your system. Click for light.',
+  light: 'Theme: light. Click for dark.',
+  dark: 'Theme: dark. Click to follow your system.',
+}
+
+const Icon = ({ mode }: { mode: Theme }) => (
+  <svg
+    viewBox="0 0 24 24"
+    width="16"
+    height="16"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.8"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    {mode === 'light' && (
+      <>
+        <circle cx="12" cy="12" r="4" />
+        <path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" />
+      </>
+    )}
+    {mode === 'dark' && <path d="M20 14.5A8.5 8.5 0 0 1 9.5 4 8.5 8.5 0 1 0 20 14.5z" />}
+    {mode === 'auto' && (
+      <>
+        <circle cx="12" cy="12" r="8.5" />
+        <path d="M12 3.5v17a8.5 8.5 0 0 0 0-17z" fill="currentColor" stroke="none" />
+      </>
+    )}
+  </svg>
+)
+
+/** Light / dark / follow the system, remembered in this browser. */
+export function ThemeToggle() {
+  const t = theme.value
+  return (
+    <button
+      type="button"
+      class="icon theme-toggle"
+      title={LABEL[t]}
+      aria-label={LABEL[t]}
+      data-theme-mode={t}
+      onClick={cycleTheme}
+    >
+      <Icon mode={t} />
+    </button>
+  )
+}

package/src/embed/panel.tsx

@@ -0,0 +1,114 @@
+import { render } from 'preact'
+import { useEffect, useState } from 'preact/hooks'
+import type { SequenceInfo, Variant } from '../engine'
+import { Host } from '../panel/Host'
+import { engine, registry } from '../runtime'
+import { env, environmentRisk, environments, version } from '../store'
+import { panelSheets } from './styles'
+
+export interface Target {
+  service?: string
+  operation?: string
+  sequence?: string
+  example?: string
+  /** open on the Docs tab instead of Try */
+  tab?: 'docs' | 'try'
+}
+
+interface Loaded {
+  variants: Record<string, Variant[]>
+}
+
+let loaded: Promise<Loaded> | undefined
+const load = () =>
+  (loaded ??= (async () => {
+    environments.value = await engine.environments(version.value)
+    environmentRisk.value = await engine.environmentRisks(version.value)
+    env.value = environments.value.includes('mock') ? 'mock' : (environments.value[0] ?? 'mock')
+    return { variants: await engine.loadVariants(registry.requests, version.value) }
+  })())
+
+/** Headers are read from the file text, so only the requested module (or the odd unresolved ones) is imported. */
+async function loadSequence(id: string) {
+  const file = registry.sequenceMeta[id]?.file
+  const wanted = (f: string) => (file ? f === file : registry.unresolvedSequences.includes(f))
+  const entries = registry.sequences.filter((e) => wanted(e.file))
+  const list = await engine.loadSequences(entries, version.value)
+  return list.find((s) => s.seq.meta.id === id)
+}
+
+function findOperation(t: Target) {
+  const services = Object.values(registry.manifests)
+  const scope = t.service ? services.filter((m) => m.service === t.service) : services
+  for (const m of scope) {
+    const op = m.operations.find((o) => o.id === t.operation)
+    if (op) return { service: m.service, op }
+  }
+  return undefined
+}
+
+function Embedded({ target, onClose }: { target: Target; onClose: () => void }) {
+  const [data, setData] = useState<Loaded>()
+  const [seq, setSeq] = useState<SequenceInfo>()
+  const [view, setView] = useState<{ tab: 'docs' | 'try'; example: string }>({
+    tab: target.tab ?? 'try',
+    example: target.example ?? '',
+  })
+  const navigate = (to: { tab: 'docs' | 'try'; example?: string }) =>
+    setView({ tab: to.tab, example: to.example ?? view.example })
+  useEffect(() => {
+    load().then(setData)
+    if (target.sequence) loadSequence(target.sequence).then(setSeq)
+  }, [])
+  if (target.sequence)
+    return seq ? (
+      <Host kind="seq" info={seq} tab={view.tab} onNavigate={navigate} onClose={onClose} />
+    ) : null
+  if (!data) return null
+  const found = findOperation(target)
+  if (!found) return null
+  return (
+    <Host
+      kind="op"
+      service={found.service}
+      op={found.op}
+      variants={data.variants[`${found.service}/${found.op.id}`] ?? []}
+      example={view.example}
+      tab={view.tab}
+      onNavigate={navigate}
+      onClose={onClose}
+    />
+  )
+}
+
+class SpecbookPanel extends HTMLElement {
+  private mount!: HTMLElement
+
+  connectedCallback() {
+    if (this.shadowRoot) return
+    const root = this.attachShadow({ mode: 'open' })
+    root.adoptedStyleSheets = panelSheets()
+    this.mount = document.createElement('div')
+    this.mount.className = 'sb-root'
+    root.append(this.mount)
+  }
+
+  show(target: Target | undefined) {
+    render(
+      target ? <Embedded target={target} onClose={() => this.show(undefined)} /> : null,
+      this.mount,
+    )
+  }
+}
+
+customElements.define('specbook-panel', SpecbookPanel)
+
+/** One panel serves every Play button on the page. */
+export function show(target: Target) {
+  let panel = document.querySelector<SpecbookPanel>('specbook-panel')
+  if (!panel) {
+    panel = document.createElement('specbook-panel') as SpecbookPanel
+    document.body.append(panel)
+  }
+  panel.show(target)
+}