@specbook/ui 0.0.0-stage → 0.1.0

package/src/fielddoc.ts

@@ -0,0 +1,83 @@
+import { type FieldSection, noteKey } from './panel/fieldnotes-split'
+import {
+  type Defs,
+  describe,
+  type JsonSchema,
+  type KeyPath,
+  kindOf,
+  pathString,
+  propsOf,
+  schemaAt,
+  unwrap,
+} from './schema'
+
+export interface FieldDoc {
+  path: string
+  type: string
+  required: boolean
+  enum?: string[]
+  description?: string
+  /** the project's own note for this field (HTML), shown after the spec's description */
+  note?: string
+  /** what the enclosing object says about itself, shown when the field has no description */
+  parent?: string
+  deprecated?: boolean
+}
+
+/** What the API documents about the field at `path` (relative to `prefix`, e.g. `['data']` for a body). */
+export function fieldDoc(
+  root: JsonSchema | undefined,
+  defs: Defs,
+  path: KeyPath,
+  prefix: KeyPath = [],
+): FieldDoc | undefined {
+  if (!root) return undefined
+  const full = [...prefix, ...path]
+  const schema = full.length === 0 ? root : schemaAt(root, full, defs)
+  if (!schema) return undefined
+  const u = unwrap(schema, defs)
+  // the cursor is on the outermost brace: say what the whole body is, when the spec does
+  if (path.length === 0) {
+    const text = typeof u.description === 'string' ? u.description.trim() : ''
+    if (!text) return undefined
+    return {
+      path: typeof u.title === 'string' && u.title.trim() ? u.title.trim() : 'body',
+      type: kindOf(u),
+      required: false,
+      description: text,
+      deprecated: u.deprecated === true || undefined,
+    }
+  }
+  const key = path[path.length - 1]
+  const parent = schemaAt(root, full.slice(0, -1), defs)
+  const kind = kindOf(u)
+  const item = kind === 'array' ? kindOf(unwrap(u.items, defs)) : undefined
+  return {
+    path: pathString(path),
+    type: item ? `${item}[]` : u.format ? `${kind} · ${u.format}` : kind,
+    required:
+      typeof key === 'string' &&
+      !!parent &&
+      propsOf(parent, defs).some((p) => p.name === key && p.required),
+    enum: Array.isArray(u.enum) ? u.enum.map(String) : undefined,
+    description: describe(u),
+    parent: parent ? describe(unwrap(parent, defs)) : undefined,
+    deprecated: u.deprecated === true || undefined,
+  }
+}
+
+/** `metadata[order]` / `items[0][price]` -> ['metadata', 'order'] / ['items', 0, 'price'] */
+export function keyPath(key: string): KeyPath {
+  return (key.match(/[^[\]]+/g) ?? [key]).map((s) => (/^\d+$/.test(s) ? Number(s) : s))
+}
+
+/** Adds the project's note for `path` in `section` (see `README.md` field sections), when there is one. */
+export function withNote(
+  doc: FieldDoc | undefined,
+  notes: Map<string, string> | undefined,
+  section: FieldSection,
+  path: string,
+): FieldDoc | undefined {
+  const note = doc && notes?.get(noteKey(section, path))
+  return doc && note ? { ...doc, note } : doc
+}

package/src/main.tsx

@@ -0,0 +1,16 @@
+import { render } from 'preact'
+import { App } from './app'
+import { applyTheme } from './theme'
+import 'prism-code-editor/layout.css'
+import 'prism-code-editor/autocomplete.css'
+import 'prism-code-editor/autocomplete-icons.css'
+import './styles/tokens.css'
+import './styles/app.css'
+import './styles/panel.css'
+
+applyTheme()
+render(<App />, document.getElementById('app') as HTMLElement)
+
+if (import.meta.hot) {
+  import.meta.hot.on('specbook:registry-changed', () => location.reload())
+}

package/src/markdown.ts

@@ -0,0 +1,133 @@
+const esc = (s: string) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+/** Inline markup on already-escaped text: `code`, **bold**, *italic*, and http(s)/mailto links. */
+function inline(text: string): string {
+  const codes: string[] = []
+  let s = text.replace(/`([^`]+)`/g, (_m, c: string) => {
+    codes.push(`<code>${c}</code>`)
+    return `\uE000${codes.length - 1}\uE000`
+  })
+  s = s
+    .replace(
+      /\[([^\]]+)\]\(((?:https?:\/\/|mailto:)[^)\s]+)\)/g,
+      (_m, label: string, href: string) => {
+        return `<a href="${href}" target="_blank" rel="noreferrer">${label}</a>`
+      },
+    )
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/(^|[\s(])\*([^*\s][^*]*)\*(?=[\s).,;:!?]|$)/g, '$1<em>$2</em>')
+    .replace(/(^|[\s(])_([^_\s][^_]*)_(?=[\s).,;:!?]|$)/g, '$1<em>$2</em>')
+  return s.replace(/\uE000(\d+)\uE000/g, (_m, i: string) => codes[Number(i)] ?? '')
+}
+
+/**
+ * A small, safe markdown subset for descriptions: paragraphs, headings, bullet and numbered lists, fenced
+ * code, and inline code, bold, italics and links. Everything is HTML-escaped first, and only http(s) and
+ * mailto links are linked, so descriptions from a spec or a sequence can be rendered without trusting them.
+ */
+export function markdownToHtml(src: string | undefined): string {
+  if (!src) return ''
+  const lines = src.replace(/\r\n?/g, '\n').split('\n')
+  const out: string[] = []
+  let para: string[] = []
+  let list: { tag: 'ul' | 'ol'; items: string[] } | undefined
+
+  const flushPara = () => {
+    if (para.length) out.push(`<p>${inline(esc(para.join(' ')))}</p>`)
+    para = []
+  }
+  const flushList = () => {
+    if (list)
+      out.push(
+        `<${list.tag}>${list.items.map((i) => `<li>${inline(esc(i))}</li>`).join('')}</${list.tag}>`,
+      )
+    list = undefined
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] as string
+    if (/^```/.test(line)) {
+      flushPara()
+      flushList()
+      const code: string[] = []
+      i++
+      while (i < lines.length && !/^```/.test(lines[i] as string)) code.push(lines[i++] as string)
+      out.push(`<pre><code>${esc(code.join('\n'))}</code></pre>`)
+      continue
+    }
+    const heading = /^(#{1,4})\s+(.*)$/.exec(line)
+    if (heading) {
+      flushPara()
+      flushList()
+      const level = Math.min(4, (heading[1] as string).length + 1)
+      out.push(`<h${level}>${inline(esc(heading[2] as string))}</h${level}>`)
+      continue
+    }
+    const quote = /^>\s?(.*)$/.exec(line)
+    if (quote) {
+      flushPara()
+      flushList()
+      const text: string[] = [quote[1] as string]
+      while (i + 1 < lines.length && /^>\s?/.test(lines[i + 1] as string))
+        text.push((lines[++i] as string).replace(/^>\s?/, ''))
+      out.push(`<blockquote>${inline(esc(text.join(' ')))}</blockquote>`)
+      continue
+    }
+    const bullet = /^\s*[-*+]\s+(.*)$/.exec(line)
+    const numbered = /^\s*\d+[.)]\s+(.*)$/.exec(line)
+    if (bullet || numbered) {
+      flushPara()
+      const tag = bullet ? 'ul' : 'ol'
+      if (list && list.tag !== tag) flushList()
+      list ??= { tag, items: [] }
+      list.items.push((bullet ?? numbered)?.[1] as string)
+      continue
+    }
+    if (line.trim() === '') {
+      flushPara()
+      flushList()
+      continue
+    }
+    flushList()
+    para.push(line.trim())
+  }
+  flushPara()
+  flushList()
+  return out.join('')
+}
+
+/** Markdown reduced to readable plain text: links keep their label, markers and fences disappear. */
+export function plainText(src: string | undefined): string {
+  if (!src) return ''
+  return src
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/^#{1,6}\s+/gm, '')
+    .replace(/^\s*(?:[-*+]|\d+[.)])\s+/gm, '')
+    .replace(/^>\s?/gm, '')
+    .replace(/[`*]|(^|\s)_|_(?=\s|$)/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+export function firstParagraph(src: string | undefined): string {
+  if (!src) return ''
+  return (src.trim().split(/\n\s*\n/)[0] ?? '').replace(/\s*\n\s*/g, ' ').trim()
+}
+
+/** Inline markup only (code, bold, italics, links) in already-safe HTML, for a single line or cell. */
+export function inlineMarkdown(src: string | undefined): string {
+  return src ? inline(esc(src)) : ''
+}
+
+/**
+ * A one-paragraph summary for table cells: inline markdown when it is short, plain text with an ellipsis
+ * when it is long (cutting markdown mid-link would break it).
+ */
+export function inlineSummary(src: string | undefined, max = 300): string {
+  const para = firstParagraph(src)
+  if (!para) return ''
+  const text = plainText(para)
+  return text.length > max ? esc(`${text.slice(0, max - 1).trimEnd()}…`) : inlineMarkdown(para)
+}

package/src/nav.ts

@@ -0,0 +1,118 @@
+import { signal } from '@preact/signals'
+
+export type PanelTab = 'docs' | 'try'
+
+/**
+ * The page is always the catalog; an operation or sequence route opens the side panel on top of it.
+ * `play` is the example to open ('' = the first), `tab` picks Docs or Try (default Try).
+ */
+export type Route =
+  | { kind: 'home' }
+  /** the catalog itself, without the overview: what a phone shows after its splash screen */
+  | { kind: 'browse' }
+  | { kind: 'op'; key: string; play?: string; tab?: PanelTab }
+  | { kind: 'seq'; id: string; play?: string; tab?: PanelTab }
+
+/**
+ * A project with one API needs no service in its links: `#/op/FindPetsByStatus`, not
+ * `#/op/swagger-petstore-openapi-3-0/FindPetsByStatus`. The app names that service once it knows the
+ * registry; a longer link (an older one, or one from a project with several APIs) still opens.
+ */
+let defaultService: string | undefined
+
+export function setDefaultService(name: string | undefined) {
+  defaultService = name
+  if (typeof location !== 'undefined') route.value = parseHash(location.hash)
+}
+
+const keyOut = (key: string) =>
+  defaultService && key.startsWith(`${defaultService}/`)
+    ? key.slice(defaultService.length + 1)
+    : key
+const keyIn = (key: string) =>
+  defaultService && !key.includes('/') ? `${defaultService}/${key}` : key
+/** Slashes read fine in a fragment, so only what would be ambiguous is escaped. */
+const soft = (s: string) => encodeURIComponent(s).replace(/%2F/gi, '/')
+
+export function parseHash(hash: string): Route {
+  const [path = '', query = ''] = hash.split('?')
+  const q = new URLSearchParams(query)
+  const play = q.get('play') ?? undefined
+  const t = q.get('tab')
+  const tab = t === 'docs' || t === 'try' ? t : undefined
+  const op = /^#\/op\/(.+)$/.exec(path)
+  if (op) return { kind: 'op', key: keyIn(decodeURIComponent(op[1] as string)), play, tab }
+  const seq = /^#\/seq\/(.+)$/.exec(path)
+  if (seq) return { kind: 'seq', id: decodeURIComponent(seq[1] as string), play, tab }
+  if (path === '#/browse') return { kind: 'browse' }
+  return { kind: 'home' }
+}
+
+export function hashFor(r: Route): string {
+  if (r.kind === 'home') return '#/'
+  if (r.kind === 'browse') return '#/browse'
+  const base = r.kind === 'op' ? `#/op/${soft(keyOut(r.key))}` : `#/seq/${encodeURIComponent(r.id)}`
+  const q = new URLSearchParams()
+  if (r.play !== undefined) q.set('play', r.play)
+  if (r.tab) q.set('tab', r.tab)
+  const s = q.toString()
+  return s ? `${base}?${s}` : base
+}
+
+/** A phone's home is its splash screen, so closing a panel lands on the list rather than back on it. */
+export const isPhone = () =>
+  typeof matchMedia === 'function' && matchMedia('(max-width: 820px)').matches
+export const pageOf = (_r: Route): Route => (isPhone() ? { kind: 'browse' } : { kind: 'home' })
+
+export const route = signal<Route>(parseHash(typeof location === 'undefined' ? '' : location.hash))
+export const paletteOpen = signal(false)
+/** The catalog's service pill ('' = overview) and filter text. */
+export const catalogService = signal('')
+export const catalogFilter = signal('')
+
+export function go(r: Route) {
+  location.hash = hashFor(r)
+  route.value = r
+}
+
+export interface Entry {
+  route: Route
+  title: string
+  /** group label shown muted, e.g. "pet" */
+  group: string
+  service?: string
+  tag?: string
+  /** operations */
+  method?: string
+  path?: string
+  /** the spec requires credentials */
+  secured?: boolean
+  /** sequences */
+  tags?: string[]
+  /** the flow group heading */
+  flowGroup?: string
+  description?: string
+  /** extra text matched by search, never shown */
+  hay: string
+  kind: 'seq' | 'op'
+}
+
+export function search(entries: Entry[], query: string, limit = 40): Entry[] {
+  const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean)
+  if (terms.length === 0) return entries.slice(0, limit)
+  const scored: [number, Entry][] = []
+  for (const e of entries) {
+    const title = e.title.toLowerCase()
+    const hay = `${title} ${e.group.toLowerCase()} ${e.hay.toLowerCase()}`
+    if (!terms.every((t) => hay.includes(t))) continue
+    // prefer title matches and sequences
+    let score = 0
+    for (const t of terms) score += title.startsWith(t) ? 3 : title.includes(t) ? 2 : 1
+    if (e.kind === 'seq') score += 0.5
+    scored.push([score, e])
+  }
+  return scored
+    .sort((a, b) => b[0] - a[0])
+    .slice(0, limit)
+    .map(([, e]) => e)
+}

package/src/panel/Body.tsx

@@ -0,0 +1,182 @@
+import { type Encoding, fromFormRows, toFormRows } from '@specbook/core'
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
+import { type FieldDoc as Doc, fieldDoc, keyPath, withNote } from '../fielddoc'
+import { type Defs, type JsonSchema, linePaths, pathString } from '../schema'
+import { BodyEditor } from './BodyEditor'
+import { jsonCompletions } from './completions'
+import { type Draft, type FieldRow, gridMode } from './draft'
+import { FieldDoc } from './FieldDoc'
+import { type Graphql, joinGraphql, splitGraphql } from './graphql'
+import { ParamGrid } from './ParamGrid'
+
+interface Props {
+  encoding: Encoding
+  draft: Draft
+  onChange: (d: Draft) => void
+  /** request schema (`{ path, query, headers, data }`) and shared definitions */
+  schema?: JsonSchema
+  defs?: Defs
+  /** dotted body paths that are uploads */
+  files?: string[]
+  /** the project's own notes for body fields, by `data.<path>` */
+  notes?: Map<string, string>
+}
+
+/** Keeps the typed texts locally, so invalid variables JSON isn't rewritten while the user is typing. */
+function GraphqlBody({ draft, onChange }: { draft: Draft; onChange: (d: Draft) => void }) {
+  const [g, setG] = useState(() => splitGraphql(draft.body) as Graphql)
+  const emitted = useRef(draft.body)
+  useEffect(() => {
+    if (draft.body === emitted.current) return
+    const next = splitGraphql(draft.body)
+    if (next) setG(next)
+    emitted.current = draft.body
+  }, [draft.body])
+
+  const set = (part: Partial<Graphql>) => {
+    const next = { ...g, ...part }
+    setG(next)
+    emitted.current = joinGraphql(next)
+    onChange({ ...draft, body: emitted.current })
+  }
+  return (
+    <section class="body" aria-label="Body">
+      <div class="section-head">
+        <h3>Query</h3>
+        <span class="chip">graphql</span>
+      </div>
+      <BodyEditor
+        label="GraphQL query"
+        language="graphql"
+        value={g.query}
+        onChange={(query) => set({ query })}
+      />
+      <div class="section-head">
+        <h3>Variables</h3>
+        <span class="chip">json</span>
+      </div>
+      <BodyEditor
+        label="GraphQL variables"
+        language="json"
+        value={g.variables}
+        onChange={(variables) => set({ variables })}
+      />
+    </section>
+  )
+}
+
+const language = (e: Encoding) => (e === 'graphql' ? 'graphql' : e === 'text' ? 'text' : 'json')
+
+export function Body({ encoding, draft, onChange, schema, defs, files = [], notes }: Props) {
+  const [line, setLine] = useState(0)
+  const paths = useMemo(() => linePaths(draft.body), [draft.body])
+  const documented = encoding === 'json' || encoding === 'form'
+  const doc: Doc | undefined = useMemo(() => {
+    const p = paths[line]
+    return p && documented
+      ? withNote(fieldDoc(schema, defs, p, ['data']), notes, 'data', pathString(p))
+      : undefined
+  }, [paths, line, schema, defs, documented, notes])
+  const complete = useMemo(
+    () =>
+      documented && schema
+        ? (text: string, pos: number) => jsonCompletions(schema, defs, ['data'], text, pos)
+        : undefined,
+    [schema, defs, documented],
+  )
+
+  /** Form bodies convert between the nested JSON and the bracket-key rows when the view is switched. */
+  const switchView = (view: 'json' | 'grid') => {
+    if (view === (draft.formView ?? 'grid')) return
+    if (view === 'grid') {
+      try {
+        onChange({ ...draft, formView: 'grid', fields: toFormRows(JSON.parse(draft.body || '{}')) })
+      } catch {
+        onChange({ ...draft, formView: 'grid' })
+      }
+    } else {
+      onChange({
+        ...draft,
+        formView: 'json',
+        body: JSON.stringify(fromFormRows(draft.fields.filter((r) => !r.file)), null, 2),
+      })
+    }
+  }
+  const viewToggle =
+    encoding === 'form' ? (
+      <fieldset class="seg" aria-label="Body view">
+        {(['json', 'grid'] as const).map((v) => (
+          <button
+            type="button"
+            class={`seg-btn ${(draft.formView ?? 'grid') === v ? 'on' : ''}`}
+            aria-pressed={(draft.formView ?? 'grid') === v}
+            onClick={() => switchView(v)}
+          >
+            {v === 'json' ? 'JSON' : 'Grid'}
+          </button>
+        ))}
+      </fieldset>
+    ) : null
+
+  if (gridMode(draft, encoding) || encoding === 'binary') {
+    const isFile = (k: string) => encoding === 'binary' || files.includes(k.replace(/\[\d+\]/g, ''))
+    const set = (fields: FieldRow[]) => onChange({ ...draft, fields })
+    const fileKeys = (draft.fields.length ? draft.fields.map((r) => r.key) : []).filter(isFile)
+    return (
+      <>
+        {viewToggle && (
+          <div class="section-head">
+            <h3>Body</h3>
+            <span class="chip">{encoding}</span>
+            <span class="spacer" />
+            {viewToggle}
+          </div>
+        )}
+        <ParamGrid
+          title={encoding === 'binary' ? 'File' : 'Body'}
+          bare={!!viewToggle}
+          rows={draft.fields}
+          onChange={set}
+          documented={[...new Set(fileKeys)].map((name) => ({ name, file: true }))}
+          docFor={(k) => withNote(fieldDoc(schema, defs, keyPath(k), ['data']), notes, 'data', k)}
+        />
+      </>
+    )
+  }
+
+  const format = () => {
+    try {
+      onChange({ ...draft, body: JSON.stringify(JSON.parse(draft.body), null, 2) })
+    } catch {
+      /* the invalid-JSON message is shown by the panel */
+    }
+  }
+
+  if (encoding === 'graphql' && splitGraphql(draft.body))
+    return <GraphqlBody draft={draft} onChange={onChange} />
+
+  return (
+    <section class="body" aria-label="Body">
+      <div class="section-head">
+        <h3>Body</h3>
+        <span class="chip">{encoding}</span>
+        <span class="spacer" />
+        {encoding !== 'text' && (
+          <button type="button" class="link" onClick={format}>
+            Format
+          </button>
+        )}
+        {viewToggle}
+      </div>
+      <BodyEditor
+        label="Request body"
+        language={language(encoding === 'form' ? 'json' : encoding)}
+        value={draft.body}
+        onChange={(body) => onChange({ ...draft, body })}
+        onLine={setLine}
+        complete={complete}
+      />
+      {documented && <FieldDoc doc={doc} />}
+    </section>
+  )
+}

package/src/panel/BodyEditor.tsx

@@ -0,0 +1,92 @@
+import { createEditor, type PrismEditor } from 'prism-code-editor'
+import { autoComplete, fuzzyFilter, registerCompletions } from 'prism-code-editor/autocomplete'
+import { defaultKeymap, editHistory, editorCommands } from 'prism-code-editor/commands'
+import { cursorPosition } from 'prism-code-editor/cursor'
+import 'prism-code-editor/languages/json'
+import 'prism-code-editor/languages/graphql'
+import 'prism-code-editor/prism/languages/json'
+import 'prism-code-editor/prism/languages/graphql'
+import { useEffect, useRef } from 'preact/hooks'
+import type { Completions } from './completions'
+
+/** Per-editor completion providers; one global source dispatches to the editor it was asked about. */
+const providers = new WeakMap<PrismEditor, (text: string, pos: number) => Completions | undefined>()
+
+registerCompletions(['json'], {
+  sources: [
+    (ctx, editor) => {
+      const found = providers.get(editor)?.(editor.value, ctx.pos)
+      if (!found) return null
+      return {
+        from: found.from,
+        to: found.to,
+        options: found.options.map((o) => ({
+          ...o,
+          renderDocs: o.doc ? () => [o.doc as string] : undefined,
+        })),
+      }
+    },
+  ],
+})
+
+interface Props {
+  value: string
+  language?: 'json' | 'graphql' | 'text'
+  readOnly?: boolean
+  label: string
+  onChange?: (value: string) => void
+  /** 0-based line the cursor is on */
+  onLine?: (line: number) => void
+  /** schema-driven suggestions for keys and values (JSON bodies only) */
+  complete?: (text: string, pos: number) => Completions | undefined
+}
+
+export function BodyEditor({
+  value,
+  language = 'json',
+  readOnly,
+  label,
+  onChange,
+  onLine,
+  complete,
+}: Props) {
+  const host = useRef<HTMLDivElement>(null)
+  const editor = useRef<PrismEditor | undefined>(undefined)
+  const on = useRef({ onChange, onLine })
+  on.current = { onChange, onLine }
+  const completer = useRef(complete)
+  completer.current = complete
+
+  useEffect(() => {
+    const e = createEditor(
+      host.current,
+      {
+        value,
+        language,
+        readOnly,
+        lineNumbers: false,
+        wordWrap: true,
+        onUpdate: (v) => on.current.onChange?.(v),
+        onSelectionChange: (_s, _v, ed) => on.current.onLine?.(ed.activeLine - 1),
+      },
+      editorCommands(defaultKeymap),
+      editHistory(),
+      ...(complete ? [cursorPosition(), autoComplete({ filter: fuzzyFilter })] : []),
+    )
+    if (complete) providers.set(e, (text, pos) => completer.current?.(text, pos))
+    e.textarea.setAttribute('aria-label', label)
+    editor.current = e
+    return () => e.remove()
+  }, [])
+
+  useEffect(() => {
+    const e = editor.current
+    if (e && e.value !== value) e.setOptions({ value })
+  }, [value])
+
+  useEffect(() => {
+    editor.current?.setOptions({ readOnly, language })
+  }, [readOnly, language])
+
+  return <div class="body-editor" part="editor" ref={host} />
+}