@specbook/ui 0.0.0-stage → 0.1.0

package/src/panel/Host.tsx

@@ -0,0 +1,100 @@
+import type { SequenceInfo, Variant } from '../engine'
+import type { PanelTab } from '../nav'
+import { OperationDocs } from './OperationDocs'
+import { Panel } from './Panel'
+import { type OpInfo, RequestPanel } from './RequestPanel'
+import { SequenceDocs } from './SequenceDocs'
+import { SequencePanel } from './SequencePanel'
+
+type Props = {
+  onClose: () => void
+  /** dims the page and traps focus; the standalone site docks the panel beside its list instead */
+  modal?: boolean
+  tab?: PanelTab
+  /** switch tab, optionally opening a named example */
+  onNavigate: (to: { tab: PanelTab; example?: string }) => void
+  onPrev?: () => void
+  onNext?: () => void
+} & (
+  | { kind: 'op'; service: string; op: OpInfo; variants: Variant[]; example: string }
+  | { kind: 'seq'; info: SequenceInfo }
+)
+
+/** Lazy entry for everything the side panel needs, so the catalog carries no editor code. */
+export function Host(p: Props) {
+  const tab = p.tab ?? 'try'
+  const tabs = (
+    <div class="rq-tabs panel-tabs" role="tablist">
+      {(
+        [
+          ['try', p.kind === 'seq' ? 'Run' : 'Try'],
+          ['docs', 'Docs'],
+        ] as const
+      ).map(([id, label]) => (
+        <button
+          type="button"
+          role="tab"
+          aria-selected={tab === id}
+          class={`rq-tab ${tab === id ? 'on' : ''}`}
+          onClick={() => p.onNavigate({ tab: id })}
+        >
+          {label}
+        </button>
+      ))}
+    </div>
+  )
+
+  if (p.kind === 'seq')
+    return (
+      <Panel
+        title={p.info.seq.meta.title}
+        subtitle="Sequence"
+        flush
+        modal={p.modal}
+        onPrev={p.onPrev}
+        onNext={p.onNext}
+        onClose={p.onClose}
+      >
+        <div class="panel-split">
+          {tabs}
+          <div class={`panel-main ${tab === 'docs' ? 'scroll' : ''}`}>
+            {tab === 'docs' ? <SequenceDocs info={p.info} /> : <SequencePanel info={p.info} />}
+          </div>
+        </div>
+      </Panel>
+    )
+  return (
+    <Panel
+      title={p.op.summary?.replace(/\.$/, '') || p.op.path}
+      subtitle={`${p.op.method} ${p.op.path}`}
+      flush
+      modal={p.modal}
+      onPrev={p.onPrev}
+      onNext={p.onNext}
+      onClose={p.onClose}
+    >
+      <div class="panel-split">
+        {tabs}
+        <div class={`panel-main ${tab === 'docs' ? 'scroll' : ''}`}>
+          {tab === 'docs' ? (
+            <OperationDocs
+              key={`${p.service}/${p.op.id}`}
+              service={p.service}
+              op={p.op}
+              variants={p.variants}
+              onTry={(example) => p.onNavigate({ tab: 'try', example })}
+            />
+          ) : (
+            <RequestPanel
+              key={`${p.service}/${p.op.id}`}
+              service={p.service}
+              op={p.op}
+              variants={p.variants}
+              initial={p.example}
+            />
+          )}
+        </div>
+      </div>
+    </Panel>
+  )
+}

package/src/panel/OperationDocs.tsx

@@ -0,0 +1,181 @@
+import { useEffect, useState } from 'preact/hooks'
+import type { Variant } from '../engine'
+import { markdownToHtml } from '../markdown'
+import { registry } from '../runtime'
+import type { Defs, JsonSchema } from '../schema'
+import { unwrap } from '../schema'
+import { statusClass, statusName } from '../status'
+import { FieldTable } from './FieldTable'
+import { useOperationNotes } from './fieldnotes'
+
+export interface DocOp {
+  id: string
+  method: string
+  path: string
+  summary?: string
+  tags: string[]
+  statuses: number[]
+}
+
+interface LongDocs {
+  description?: string
+  examples: { name: string; title: string; source: string }[]
+}
+
+const SECTIONS = [
+  ['path', 'Path'],
+  ['query', 'Query'],
+  ['headers', 'Headers'],
+] as const
+
+/** Everything the page shows below its header, fetched together so the page is laid out once. */
+interface Loaded {
+  long?: LongDocs
+  req?: JsonSchema
+  defs?: Defs
+  /** a saved request's own markdown (`<name>.req.md` beside its `.req.ts`), by file */
+  saved: Record<string, string>
+}
+
+const soft = <T,>(p: Promise<T> | undefined): Promise<T | undefined> =>
+  (p ?? Promise.resolve(undefined)).catch(() => undefined)
+
+function loadAll(key: string, service: string, files: string[]): Promise<Loaded> {
+  return Promise.all([
+    soft(registry.operationDocs[key]?.().then((m: { default: LongDocs }) => m.default)),
+    soft(registry.schemas[key]?.().then((m: { default: JsonSchema }) => m.default)),
+    soft(registry.definitions[service]?.().then((m: { default: Defs }) => m.default)),
+    Promise.all(files.map((f) => soft(registry.docs.find((d) => d.requestFile === f)?.load()))),
+  ]).then(([long, req, defs, notes]) => ({
+    long,
+    req,
+    defs,
+    saved: Object.fromEntries(files.flatMap((f, i) => (notes[i] ? [[f, notes[i] as string]] : []))),
+  }))
+}
+
+/** A saved request's own markdown (`<name>.req.md` beside its `.req.ts`), when it has one. */
+function SavedRequestNote({ variant, html }: { variant: Variant; html?: string }) {
+  if (!html) return null
+  return (
+    <section class="saved-note-doc">
+      <h2>
+        Saved request <code>{variant.name}</code>
+      </h2>
+      <div class="doc-custom" dangerouslySetInnerHTML={{ __html: html }} />
+    </section>
+  )
+}
+
+export function OperationDocs({
+  service,
+  op,
+  variants = [],
+  onTry,
+}: {
+  service: string
+  op: DocOp
+  variants?: Variant[]
+  /** open the Try tab, optionally on a named example */
+  onTry: (example?: string) => void
+}) {
+  const key = `${service}/${op.id}`
+  const [loaded, setLoaded] = useState<Loaded>()
+  const files = variants.map((v) => v.file)
+  const fileKey = files.join('\n')
+
+  useEffect(() => {
+    let live = true
+    setLoaded(undefined)
+    loadAll(key, service, fileKey ? fileKey.split('\n') : []).then((l) => live && setLoaded(l))
+    return () => {
+      live = false
+    }
+  }, [key, service, fileKey])
+
+  const page = useOperationNotes(key)
+  // the header is there at once; everything below it appears together once it has all arrived
+  const ready = !!loaded && page.loaded
+  const { long, req, defs } = loaded ?? { saved: {} }
+  const root = req ? unwrap(req, defs) : undefined
+  const section = (name: string) => root?.properties?.[name] as JsonSchema | undefined
+  const body = section('data')
+
+  return (
+    <article class="doc" data-op={key}>
+      <div class="doc-intro">
+        <span class={`method ${op.method}`}>{op.method}</span> <code>{op.path}</code>
+        <span class="spacer" />
+        <button type="button" class="btn primary" onClick={() => onTry()}>
+          Try it
+        </button>
+      </div>
+
+      {ready && (
+        <>
+          {/* the spec's own text first; the project's page follows it, or stands in for it with `replace: true` */}
+          {!(page.found && page.replace) && long?.description && (
+            <div
+              class="doc-custom"
+              dangerouslySetInnerHTML={{ __html: markdownToHtml(long.description) }}
+            />
+          )}
+          {page.intro && (
+            <div
+              class={`doc-custom ${page.replace ? '' : 'doc-project'}`}
+              dangerouslySetInnerHTML={{ __html: page.intro }}
+            />
+          )}
+
+          {variants.map((v) => (
+            <SavedRequestNote key={v.file} variant={v} html={loaded?.saved[v.file]} />
+          ))}
+
+          {SECTIONS.map(([k, title]) =>
+            section(k) ? (
+              <section>
+                <h2>{title} parameters</h2>
+                <FieldTable schema={section(k)} defs={defs} section={k} notes={page.notes} />
+              </section>
+            ) : null,
+          )}
+
+          {body && (
+            <section>
+              <h2>Request body</h2>
+              <FieldTable schema={body} defs={defs} section="data" notes={page.notes} />
+            </section>
+          )}
+
+          {op.statuses.length > 0 && (
+            <section>
+              <h2>Responses</h2>
+              <ul class="statuses">
+                {op.statuses.map((s) => (
+                  <li>
+                    <span class={`state-badge ${statusClass(s)}`}>{s}</span> {statusName(s)}
+                  </li>
+                ))}
+              </ul>
+            </section>
+          )}
+
+          {(long?.examples.length ?? 0) > 1 && (
+            <section>
+              <h2>Examples</h2>
+              <ul class="examples">
+                {long?.examples.map((e) => (
+                  <li>
+                    <button type="button" class="link" onClick={() => onTry(e.name)}>
+                      ▶ {e.title}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          )}
+        </>
+      )}
+    </article>
+  )
+}

package/src/panel/Panel.tsx

@@ -0,0 +1,193 @@
+import type { ComponentChildren } from 'preact'
+import { useEffect, useRef } from 'preact/hooks'
+import { env, environments } from '../store'
+
+interface Props {
+  title: string
+  subtitle?: string
+  /** the body fills the panel and manages its own scrolling */
+  flush?: boolean
+  /** dims the page and traps focus (embeds); the standalone site leaves its list usable beside the panel */
+  modal?: boolean
+  onPrev?: () => void
+  onNext?: () => void
+  onClose: () => void
+  children: ComponentChildren
+}
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/** The three-quarter sheet from the right where requests and sequences run. */
+export function Panel({
+  title,
+  subtitle,
+  flush,
+  modal = true,
+  onPrev,
+  onNext,
+  onClose,
+  children,
+}: Props) {
+  const aside = useRef<HTMLElement>(null)
+
+  useEffect(() => {
+    const root = aside.current?.getRootNode() as Document | ShadowRoot
+    const before = root?.activeElement as HTMLElement | null
+    if (modal) aside.current?.focus()
+    return () => before?.focus?.()
+  }, [modal])
+
+  // The keyboard hides the lower half of a phone's screen and iOS does not reliably scroll a field in
+  // a fixed panel above it. While a text field is focused its scroller gets room under the content,
+  // and the field is placed near the top of the panel, which the keyboard never covers.
+  useEffect(() => {
+    const el = aside.current
+    if (!el || typeof matchMedia === 'undefined') return
+    const phone = matchMedia('(max-width: 820px)')
+    const FIELD = 'input:not([type="checkbox"]):not([type="radio"]):not([type="file"]), textarea'
+    let padded: { box: HTMLElement; was: string } | undefined
+    let timers: number[] = []
+    const scroller = (from: HTMLElement) => {
+      for (let n = from.parentElement; n && n !== el; n = n.parentElement) {
+        const y = getComputedStyle(n).overflowY
+        if (y === 'auto' || y === 'scroll') return n
+      }
+      return null
+    }
+    const place = (field: HTMLElement) => {
+      const box = scroller(field)
+      if (!box) return
+      // measured against what is visible: iOS pans its visual viewport under the keyboard
+      const vv = typeof visualViewport === 'undefined' ? undefined : visualViewport
+      const top = vv?.offsetTop ?? 0
+      const height = vv?.height ?? innerHeight
+      const at = field.getBoundingClientRect().top
+      const want = top + height * 0.2
+      if (at > top + height * 0.4 || at < top) box.scrollTop += at - want
+    }
+    const focusin = (e: Event) => {
+      const field = e.target as HTMLElement
+      if (!phone.matches || !field.matches?.(FIELD)) return
+      const box = scroller(field)
+      if (box && padded?.box !== box) {
+        if (padded) padded.box.style.paddingBottom = padded.was
+        padded = { box, was: box.style.paddingBottom }
+        box.style.paddingBottom = '70vh'
+      }
+      // the keyboard animates in; place the field as it opens and again once it has settled
+      for (const t of timers) clearTimeout(t)
+      timers = [0, 150, 400, 800].map((ms) => window.setTimeout(() => place(field), ms))
+    }
+    const focusout = () => {
+      timers.push(
+        window.setTimeout(() => {
+          const at = (el.getRootNode() as Document | ShadowRoot).activeElement
+          if (at?.matches?.(FIELD) || !padded) return
+          padded.box.style.paddingBottom = padded.was
+          padded = undefined
+        }, 200),
+      )
+    }
+    el.addEventListener('focusin', focusin)
+    el.addEventListener('focusout', focusout)
+    return () => {
+      el.removeEventListener('focusin', focusin)
+      el.removeEventListener('focusout', focusout)
+      for (const t of timers) clearTimeout(t)
+      if (padded) padded.box.style.paddingBottom = padded.was
+    }
+  }, [])
+
+  useEffect(() => {
+    const key = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+      if (e.key !== 'Tab' || !modal || !aside.current) return
+      const items = [...aside.current.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(
+        (el) => el.offsetParent !== null,
+      )
+      const first = items[0]
+      const last = items[items.length - 1]
+      const root = aside.current.getRootNode() as Document | ShadowRoot
+      const at = root.activeElement
+      if (!first || !last) return
+      if (e.shiftKey && (at === first || at === aside.current)) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && at === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    addEventListener('keydown', key)
+    return () => removeEventListener('keydown', key)
+  }, [onClose, modal])
+
+  // a dialog when it dims the page (embeds), a complementary region when docked beside the list
+  const attrs = {
+    class: `panel ${modal ? '' : 'docked'}`,
+    part: 'panel',
+    'aria-label': title,
+    'aria-modal': modal ? true : undefined,
+    role: (modal ? 'dialog' : 'complementary') as 'dialog',
+    tabIndex: -1,
+  }
+
+  return (
+    <>
+      {modal && (
+        <button type="button" class="panel-backdrop" aria-label="Close" onClick={onClose} />
+      )}
+      <section {...attrs} ref={aside}>
+        <header class="panel-head" part="header">
+          <div class="panel-title">
+            <h2>{title}</h2>
+            {subtitle && <div class="muted small">{subtitle}</div>}
+          </div>
+          <span class="spacer" />
+          {modal && environments.value.length > 1 && (
+            <label class="row">
+              <span class="muted">Environment</span>
+              <select
+                value={env.value}
+                onChange={(e) => (env.value = (e.target as HTMLSelectElement).value)}
+              >
+                {environments.value.map((e) => (
+                  <option value={e}>{e}</option>
+                ))}
+              </select>
+            </label>
+          )}
+          {(onPrev || onNext) && (
+            <span class="stepper">
+              <button
+                type="button"
+                class="icon"
+                title="Previous"
+                aria-label="Previous"
+                disabled={!onPrev}
+                onClick={onPrev}
+              >
+                ↑
+              </button>
+              <button
+                type="button"
+                class="icon"
+                title="Next"
+                aria-label="Next"
+                disabled={!onNext}
+                onClick={onNext}
+              >
+                ↓
+              </button>
+            </span>
+          )}
+          <button type="button" class="icon" aria-label="Close panel" onClick={onClose}>
+            ×
+          </button>
+        </header>
+        <div class={`panel-body ${flush ? 'flush' : ''}`}>{children}</div>
+      </section>
+    </>
+  )
+}