@specbook/ui 0.0.0-stage → 0.2.0

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>
+  )
+}

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>
+  )
+}