@specbook/ui 0.0.0-stage → 0.1.0

package/src/panel/CodeSample.tsx

@@ -0,0 +1,237 @@
+import {
+  type AuthProfile,
+  type Encoding,
+  type RenderedRequest,
+  render,
+  type SnippetInput,
+  type SnippetLang,
+  snippetLangs,
+  toSnippet,
+} from '@specbook/core'
+import type { ComponentChildren } from 'preact'
+import { useCallback, useEffect, useMemo, useState } from 'preact/hooks'
+import { engine } from '../runtime'
+import { version } from '../store'
+import { type Draft, requestParts } from './draft'
+
+const LANG_KEY = 'specbook:code-lang'
+
+function savedLang(): SnippetLang {
+  try {
+    const v = localStorage.getItem(LANG_KEY)
+    if (v === 'curl' || v === 'fetch') return v
+  } catch {
+    /* optional */
+  }
+  return 'curl'
+}
+
+type Applied = { headers?: Record<string, string>; query?: Record<string, string> } | undefined
+
+interface Props {
+  service: string
+  /** auth profile to apply: its name, `service` for the service's default, or nothing */
+  profile?: string
+  /** shown as a hint under the sample */
+  secured?: boolean
+  /** builds the request; keep it stable (useCallback) so values from faker do not change per render */
+  make: (base: string, applied: Applied) => SnippetInput
+  /** the request as it actually went out, offered as a third view once there is one */
+  sent?: ComponentChildren
+}
+
+/** cURL / Node fetch tabs with a copy button, for a request described by `make`. */
+export function CodeSample({ service, profile, secured, make, sent }: Props) {
+  const [view, setView] = useState<SnippetLang | 'sent'>(savedLang)
+  const lang: SnippetLang = view === 'sent' ? 'curl' : view
+  const [copied, setCopied] = useState(false)
+  const [base, setBase] = useState<string>()
+  const [applied, setApplied] = useState<Applied>()
+
+  useEffect(() => {
+    let live = true
+    engine.config(version.value).then((c) => {
+      if (!live) return
+      const svc = c.services?.[service]
+      const urls = svc?.baseUrl ?? {}
+      setBase(urls.live ?? Object.values(urls)[0])
+      const name = profile === 'service' ? svc?.auth : profile
+      setApplied(name ? (c.auth?.[name] as AuthProfile | undefined)?.apply : undefined)
+    })
+    return () => {
+      live = false
+    }
+  }, [service, profile])
+
+  const built = useMemo<{ text?: string; error?: string }>(() => {
+    try {
+      return { text: toSnippet(lang, make(base ?? 'https://api.example.com', applied)) }
+    } catch (e) {
+      return { error: e instanceof Error ? e.message : String(e) }
+    }
+  }, [make, lang, base, applied])
+
+  const pick = (l: SnippetLang | 'sent') => {
+    setView(l)
+    if (l === 'sent') return
+    try {
+      localStorage.setItem(LANG_KEY, l)
+    } catch {
+      /* optional */
+    }
+  }
+
+  const copy = async () => {
+    if (!built.text) return
+    try {
+      await navigator.clipboard.writeText(built.text)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1500)
+    } catch {
+      /* clipboard blocked: the text is selectable */
+    }
+  }
+
+  return (
+    <div class="code-sample">
+      <div class="code-head">
+        <fieldset class="seg" aria-label="Code sample">
+          {snippetLangs.map((l) => (
+            <button
+              type="button"
+              aria-pressed={view === l.id}
+              class={`seg-btn ${view === l.id ? 'on' : ''}`}
+              onClick={() => pick(l.id)}
+            >
+              {l.label}
+            </button>
+          ))}
+          {sent !== undefined && (
+            <button
+              type="button"
+              aria-pressed={view === 'sent'}
+              class={`seg-btn ${view === 'sent' ? 'on' : ''}`}
+              onClick={() => pick('sent')}
+            >
+              Sent
+            </button>
+          )}
+        </fieldset>
+        <span class="spacer" />
+        {view !== 'sent' && (
+          <button type="button" class="btn small" onClick={copy} disabled={!built.text}>
+            {copied ? 'Copied' : 'Copy'}
+          </button>
+        )}
+      </div>
+      {view === 'sent' ? (
+        sent
+      ) : built.error ? (
+        <p class="muted">{built.error}</p>
+      ) : (
+        <pre class="code-block" part="code">
+          <code>{built.text}</code>
+        </pre>
+      )}
+      {view !== 'sent' && secured && (
+        <p class="muted small">Secrets are read from environment variables; set them first.</p>
+      )}
+    </div>
+  )
+}
+
+interface DraftProps {
+  service: string
+  method: string
+  /** the operation's path template, e.g. /pets/{petId} */
+  path: string
+  draft: Draft
+  encoding: Encoding
+  vars: Record<string, string>
+  secured?: boolean
+  sent?: ComponentChildren
+}
+
+/** The sample for the request as currently edited in the panel. */
+export function DraftCodeSample({
+  service,
+  method,
+  path,
+  draft,
+  encoding,
+  vars,
+  secured,
+  sent,
+}: DraftProps) {
+  const make = useCallback(
+    (base: string, applied: Applied): SnippetInput => {
+      const parts = requestParts(draft, encoding)
+      const raw = {
+        path: parts.path ?? {},
+        query: parts.query ?? {},
+        headers: parts.headers ?? {},
+        data: parts.data,
+      }
+      let r = raw
+      try {
+        r = render(raw, vars)
+      } catch {
+        /* a variable is still unset: show the placeholders as they are */
+      }
+      const url = path.replace(/\{([^}]+)\}/g, (m, n: string) => {
+        const v = (r.path as Record<string, unknown>)[n]
+        return v === undefined || v === '' ? m : encodeURIComponent(String(v))
+      })
+      return {
+        method,
+        url: `${base.replace(/\/+$/, '')}${url}`,
+        query: { ...(applied?.query ?? {}), ...(r.query as Record<string, string | string[]>) },
+        headers: { ...(applied?.headers ?? {}), ...(r.headers as Record<string, string>) },
+        body: r.data,
+        encoding,
+      }
+    },
+    [draft, encoding, vars, method, path],
+  )
+  return (
+    <CodeSample
+      service={service}
+      profile={secured ? 'service' : undefined}
+      secured={secured}
+      make={make}
+      sent={sent}
+    />
+  )
+}
+
+/** The sample for a request a sequence step recorded (placeholders for secrets and session values kept). */
+export function StepCodeSample({
+  request,
+  encoding,
+  sent,
+}: {
+  request: RenderedRequest
+  encoding: Encoding
+  sent?: ComponentChildren
+}) {
+  const make = useCallback(
+    (base: string, applied: Applied): SnippetInput => ({
+      method: request.method,
+      url: `${base.replace(/\/+$/, '')}${request.url}`,
+      query: { ...(applied?.query ?? {}), ...request.query },
+      headers: { ...(applied?.headers ?? {}), ...request.headers },
+      body: request.body,
+      encoding,
+    }),
+    [request, encoding],
+  )
+  return (
+    <CodeSample
+      service={request.service}
+      profile={request.profile}
+      secured={!!request.profile}
+      make={make}
+      sent={sent}
+    />
+  )
+}

package/src/panel/Combo.tsx

@@ -0,0 +1,124 @@
+import { useEffect, useRef, useState } from 'preact/hooks'
+
+interface Props {
+  value: string
+  options: string[]
+  onChange: (value: string) => void
+  label: string
+  placeholder?: string
+  /** forwarded so the grid can move between rows with Enter and the arrow keys */
+  onKeyDown?: (e: KeyboardEvent) => void
+  cell?: string
+}
+
+/** A text input with the spec's allowed values as a dropdown; any other value can still be typed. */
+export function Combo({ value, options, onChange, label, placeholder, onKeyDown, cell }: Props) {
+  const [open, setOpen] = useState(false)
+  const [at, setAt] = useState(-1)
+  const [pos, setPos] = useState<Record<string, string>>()
+  const box = useRef<HTMLDivElement>(null)
+
+  /** The list is `fixed` so the grid's rounded, clipped table and the scrolling pane can't cut it off. */
+  const place = () => {
+    const r = box.current?.getBoundingClientRect()
+    if (!r) return
+    const below = innerHeight - r.bottom - 8
+    const flip = below < 160 && r.top > below
+    // strings with units: Preact 11 sets style properties as given
+    setPos({
+      left: `${r.left}px`,
+      width: `${Math.max(r.width, 160)}px`,
+      maxHeight: `${Math.min(240, (flip ? r.top : below) - 4)}px`,
+      ...(flip ? { bottom: `${innerHeight - r.top + 2}px` } : { top: `${r.bottom + 2}px` }),
+    })
+  }
+
+  useEffect(() => {
+    if (!open) return
+    place()
+    const close = (e: Event) => {
+      if (!(e.target instanceof Node && box.current?.contains(e.target))) setOpen(false)
+    }
+    addEventListener('scroll', close, true)
+    addEventListener('resize', close)
+    return () => {
+      removeEventListener('scroll', close, true)
+      removeEventListener('resize', close)
+    }
+  }, [open])
+
+  useEffect(() => {
+    if (!open) return
+    const away = (e: MouseEvent) => {
+      if (!e.composedPath().includes(box.current as Node)) setOpen(false)
+    }
+    document.addEventListener('mousedown', away, true)
+    return () => document.removeEventListener('mousedown', away, true)
+  }, [open])
+
+  const pick = (v: string) => {
+    onChange(v)
+    setOpen(false)
+    setAt(-1)
+  }
+
+  return (
+    <div class="combo" ref={box}>
+      <input
+        class="cell"
+        data-cell={cell}
+        value={value}
+        placeholder={placeholder}
+        aria-label={label}
+        aria-expanded={open}
+        role="combobox"
+        autocomplete="off"
+        onFocus={() => setOpen(true)}
+        onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+        onKeyDown={(e) => {
+          if (open && e.key === 'ArrowDown') {
+            e.preventDefault()
+            setAt((at + 1) % options.length)
+          } else if (open && e.key === 'ArrowUp') {
+            e.preventDefault()
+            setAt((at - 1 + options.length) % options.length)
+          } else if (open && e.key === 'Enter' && at >= 0) {
+            e.preventDefault()
+            pick(options[at] as string)
+          } else if (e.key === 'Escape' && open) {
+            e.stopPropagation()
+            setOpen(false)
+          } else {
+            if (e.key === 'Enter' || e.key === 'Tab') setOpen(false)
+            onKeyDown?.(e)
+          }
+        }}
+      />
+      <button
+        type="button"
+        class="combo-toggle"
+        tabIndex={-1}
+        aria-label={`Show ${label} options`}
+        onClick={() => setOpen(!open)}
+      >
+        ▾
+      </button>
+      {open && (
+        <div class="combo-list" role="listbox" style={pos}>
+          {options.map((o, i) => (
+            <button
+              type="button"
+              role="option"
+              aria-selected={o === value}
+              class={`${o === value ? 'on' : ''} ${i === at ? 'at' : ''}`}
+              onMouseDown={(e) => e.preventDefault()}
+              onClick={() => pick(o)}
+            >
+              {o}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/panel/ControlsGrid.tsx

@@ -0,0 +1,189 @@
+import { useState } from 'preact/hooks'
+import { defaultFor, type FieldSpec } from '../components/Fields'
+import { Combo } from './Combo'
+
+interface Props {
+  title: string
+  specs: Record<string, FieldSpec>
+  values: Record<string, unknown>
+  onChange: (values: Record<string, unknown>) => void
+}
+
+const same = (a: unknown, b: unknown) => a === b || JSON.stringify(a) === JSON.stringify(b)
+
+function hint(spec: FieldSpec): string {
+  const bits: string[] = [spec.kind]
+  if (spec.min !== undefined || spec.max !== undefined)
+    bits.push(`${spec.min ?? ''}–${spec.max ?? ''}`)
+  return bits.join(' · ')
+}
+
+/** One editable cell, by control kind. Nested objects and arrays are edited as JSON. */
+function ValueCell({
+  name,
+  spec,
+  value,
+  onChange,
+}: {
+  name: string
+  spec: FieldSpec
+  value: unknown
+  onChange: (v: unknown) => void
+}) {
+  const [raw, setRaw] = useState<string>()
+  switch (spec.kind) {
+    case 'number':
+      return (
+        <input
+          class="cell"
+          type="number"
+          aria-label={name}
+          value={String(value ?? '')}
+          min={spec.min}
+          max={spec.max}
+          onInput={(e) => {
+            const v = (e.target as HTMLInputElement).value
+            onChange(v === '' ? undefined : Number(v))
+          }}
+        />
+      )
+    case 'boolean':
+      return (
+        <Combo
+          label={name}
+          value={String(Boolean(value))}
+          options={['true', 'false']}
+          onChange={(v) => (v === 'true' || v === 'false' ? onChange(v === 'true') : undefined)}
+        />
+      )
+    case 'date':
+      return (
+        <input
+          class="cell"
+          type="date"
+          aria-label={name}
+          value={String(value ?? '')}
+          onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+        />
+      )
+    case 'select': {
+      const options = spec.options ?? []
+      const current = options.find((o) => same(o.value, value))
+      return (
+        <Combo
+          label={name}
+          value={current?.label ?? String(value ?? '')}
+          options={options.map((o) => o.label)}
+          onChange={(label) => {
+            const hit = options.find((o) => o.label === label)
+            if (hit) onChange(hit.value)
+          }}
+        />
+      )
+    }
+    case 'multiselect': {
+      const chosen = (value as unknown[]) ?? []
+      return (
+        <div class="multi-cell">
+          {(spec.options ?? []).map((o) => (
+            <label>
+              <input
+                type="checkbox"
+                checked={chosen.some((c) => same(c, o.value))}
+                onChange={(e) =>
+                  onChange(
+                    (e.target as HTMLInputElement).checked
+                      ? [...chosen, o.value]
+                      : chosen.filter((c) => !same(c, o.value)),
+                  )
+                }
+              />
+              {o.label}
+            </label>
+          ))}
+        </div>
+      )
+    }
+    case 'object':
+    case 'array':
+      return (
+        <input
+          class="cell mono"
+          aria-label={name}
+          value={raw ?? JSON.stringify(value ?? defaultFor(spec))}
+          onInput={(e) => {
+            const text = (e.target as HTMLInputElement).value
+            setRaw(text)
+            try {
+              onChange(JSON.parse(text))
+            } catch {
+              /* keep typing; the last valid value stays */
+            }
+          }}
+          onBlur={() => setRaw(undefined)}
+        />
+      )
+    default:
+      return (
+        <input
+          class="cell"
+          aria-label={name}
+          value={String(value ?? '')}
+          onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+        />
+      )
+  }
+}
+
+/**
+ * A sequence's controls (params, or the choices of an input step) as the same spreadsheet the request
+ * parameters use: name, value, description.
+ */
+export function ControlsGrid({ title, specs, values, onChange }: Props) {
+  const names = Object.keys(specs)
+  if (names.length === 0) return null
+  return (
+    <section class="grid controls-grid" aria-label={title}>
+      <h3>{title}</h3>
+      <table>
+        <colgroup>
+          <col class="c-key" />
+          <col class="c-val" />
+          <col />
+        </colgroup>
+        <thead>
+          <tr>
+            <th class="g-key">Name</th>
+            <th class="g-val">Value</th>
+            <th class="g-doc">Description</th>
+          </tr>
+        </thead>
+        <tbody>
+          {names.map((name) => {
+            const spec = specs[name] as FieldSpec
+            return (
+              <tr key={name}>
+                <td class="g-key">
+                  <span class="key">
+                    <code>{spec.label ?? name}</code>
+                  </span>
+                </td>
+                <td class="g-val">
+                  <ValueCell
+                    name={name}
+                    spec={spec}
+                    value={values[name]}
+                    onChange={(v) => onChange({ ...values, [name]: v })}
+                  />
+                </td>
+                <td class="g-doc" title={spec.description}>
+                  <span class="chip">{hint(spec)}</span> {spec.description}
+                </td>
+              </tr>
+            )
+          })}
+        </tbody>
+      </table>
+    </section>
+  )
+}

package/src/panel/FieldDoc.tsx

@@ -0,0 +1,42 @@
+import type { FieldDoc as Doc } from '../fielddoc'
+import { markdownToHtml } from '../markdown'
+
+/** The documentation for the field the cursor is on, shown below the editor instead of beside each line. */
+export function FieldDoc({ doc, hint }: { doc?: Doc; hint?: string }) {
+  if (!doc)
+    return (
+      <div class="field-doc empty" part="field-doc" aria-live="polite">
+        {hint ?? 'Put the cursor on a field to see what the API says about it.'}
+      </div>
+    )
+  return (
+    <div class="field-doc" part="field-doc" aria-live="polite">
+      <div class="field-doc-head">
+        <code>{doc.path}</code>
+        <span class="chip">{doc.type}</span>
+        {doc.required && <span class="chip req">required</span>}
+        {doc.deprecated && <span class="chip warn">deprecated</span>}
+      </div>
+      {doc.description ? (
+        <div
+          class="field-doc-text"
+          dangerouslySetInnerHTML={{ __html: markdownToHtml(doc.description) }}
+        />
+      ) : doc.note ? null : (
+        <p class="muted">
+          The spec has no description for this field.
+          {doc.parent && <> It is part of: {doc.parent}</>}
+        </p>
+      )}
+      {doc.note && <div class="field-note" dangerouslySetInnerHTML={{ __html: doc.note }} />}
+      {doc.enum && (
+        <p class="field-doc-enum">
+          {doc.enum.slice(0, 12).map((v) => (
+            <code>{v}</code>
+          ))}
+          {doc.enum.length > 12 && <span class="muted">+{doc.enum.length - 12} more</span>}
+        </p>
+      )}
+    </div>
+  )
+}

package/src/panel/FieldTable.tsx

@@ -0,0 +1,113 @@
+import { inlineSummary } from '../markdown'
+import { type Defs, describe, type JsonSchema, kindOf, propsOf, unwrap } from '../schema'
+import { type FieldSection, noteKey } from './fieldnotes-split'
+
+interface Row {
+  name: string
+  depth: number
+  type: string
+  required: boolean
+  description?: string
+  enum?: string[]
+}
+
+const MAX_ROWS = 60
+
+function typeOf(u: JsonSchema, defs: Defs): string {
+  const kind = kindOf(u)
+  if (kind === 'array') return `${kindOf(unwrap(u.items, defs))}[]`
+  return u.format ? `${kind} · ${u.format}` : kind
+}
+
+export function flatten(schema: JsonSchema | undefined, defs: Defs, depth = 0, prefix = ''): Row[] {
+  if (!schema || depth > 2) return []
+  const rows: Row[] = []
+  for (const p of propsOf(schema, defs)) {
+    const u = unwrap(p.schema, defs)
+    const name = prefix ? `${prefix}.${p.name}` : p.name
+    rows.push({
+      name,
+      depth,
+      type: typeOf(u, defs),
+      required: p.required,
+      description: describe(u),
+      enum: Array.isArray(u.enum) && u.enum.length <= 10 ? u.enum.map(String) : undefined,
+    })
+    const nested = kindOf(u) === 'array' ? unwrap(u.items, defs) : u
+    if (kindOf(nested) === 'object') rows.push(...flatten(nested, defs, depth + 1, name))
+  }
+  return rows
+}
+
+export function FieldTable({
+  schema,
+  defs,
+  section = 'data',
+  notes,
+}: {
+  schema?: JsonSchema
+  defs: Defs
+  /** where these fields sit in the request, for looking up the project's notes */
+  section?: FieldSection
+  notes?: Map<string, string>
+}) {
+  const rows = flatten(schema, defs)
+  if (rows.length === 0) return null
+  return (
+    <table class="fields">
+      <thead>
+        <tr>
+          <th>Field</th>
+          <th>Type</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        {rows.slice(0, MAX_ROWS).map((r) => (
+          <tr>
+            <td style={{ paddingLeft: `${r.depth * 16 + 8}px` }}>
+              <code>{r.name.split('.').pop()}</code>
+              {r.required && (
+                <span class="req" title="required">
+                  *
+                </span>
+              )}
+            </td>
+            <td>
+              <span class="chip">{r.type}</span>
+            </td>
+            <td>
+              <span
+                class="doc-inline wrap"
+                dangerouslySetInnerHTML={{ __html: inlineSummary(r.description, 220) }}
+              />
+              {notes?.get(noteKey(section, r.name)) && (
+                <div
+                  class="field-note"
+                  dangerouslySetInnerHTML={{
+                    __html: notes.get(noteKey(section, r.name)) as string,
+                  }}
+                />
+              )}
+              {r.enum && (
+                <span class="field-doc-enum">
+                  {' '}
+                  {r.enum.map((v) => (
+                    <code>{v}</code>
+                  ))}
+                </span>
+              )}
+            </td>
+          </tr>
+        ))}
+        {rows.length > MAX_ROWS && (
+          <tr>
+            <td colSpan={3} class="muted">
+              +{rows.length - MAX_ROWS} more fields in the spec
+            </td>
+          </tr>
+        )}
+      </tbody>
+    </table>
+  )
+}