@specbook/ui 0.0.0-stage → 0.2.0

package/src/panel/graphql.ts

@@ -0,0 +1,31 @@
+export interface Graphql {
+  query: string
+  variables: string
+  rest: Record<string, unknown>
+}
+
+/** A GraphQL body is `{ query, variables?, operationName? }`; split it so each part gets its own editor. */
+export function splitGraphql(body: string): Graphql | undefined {
+  try {
+    const { query, variables, ...rest } = JSON.parse(body)
+    if (typeof query !== 'string') return undefined
+    return {
+      query,
+      variables: variables === undefined ? '' : JSON.stringify(variables, null, 2),
+      rest,
+    }
+  } catch {
+    return undefined
+  }
+}
+
+export function joinGraphql(g: Graphql): string {
+  let variables: unknown
+  try {
+    variables = g.variables.trim() ? JSON.parse(g.variables) : undefined
+  } catch {
+    // keep what was typed so the body stays editable; the panel reports invalid JSON
+    variables = g.variables
+  }
+  return JSON.stringify({ query: g.query, variables, ...g.rest }, null, 2)
+}

package/src/panel/icons.tsx

@@ -0,0 +1,85 @@
+/** A paper plane pointing right, the usual "send" mark. SVG because Unicode has no paper-plane emoji. */
+export function PaperPlane({ size = 16 }: { size?: number }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      width={size}
+      height={size}
+      fill="none"
+      stroke="currentColor"
+      stroke-width="1.8"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M3 3l19 9-19 9 3.5-9z" />
+      <path d="M6.5 12H14" />
+    </svg>
+  )
+}
+
+/** A padlock: the operation needs credentials. */
+export function Lock({ size = 12 }: { size?: number }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      width={size}
+      height={size}
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="4" y="11" width="16" height="10" rx="2" />
+      <path d="M8 11V7a4 4 0 0 1 8 0v4" />
+    </svg>
+  )
+}
+
+/** The share mark of Apple's platforms and most browsers: an arrow rising out of a tray. */
+export function ShareIcon({ size = 16 }: { size?: number }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      width={size}
+      height={size}
+      fill="none"
+      stroke="currentColor"
+      stroke-width="1.8"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M12 15V3" />
+      <path d="M7.5 7.5 12 3l4.5 4.5" />
+      <path d="M5 11H4.5A1.5 1.5 0 0 0 3 12.5v7A1.5 1.5 0 0 0 4.5 21h15a1.5 1.5 0 0 0 1.5-1.5v-7a1.5 1.5 0 0 0-1.5-1.5H19" />
+    </svg>
+  )
+}
+
+export function GitHubMark({ size = 16 }: { size?: number }) {
+  return (
+    <svg viewBox="0 0 16 16" width={size} height={size} fill="currentColor" aria-hidden="true">
+      <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82a7.6 7.6 0 0 1 4 0c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z" />
+    </svg>
+  )
+}
+
+export function StarIcon({ size = 14 }: { size?: number }) {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      width={size}
+      height={size}
+      fill="none"
+      stroke="currentColor"
+      stroke-width="1.8"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path d="m12 3 2.7 5.6 6.1.9-4.4 4.3 1 6.1L12 17l-5.4 2.9 1-6.1-4.4-4.3 6.1-.9z" />
+    </svg>
+  )
+}

package/src/panel/jsonCursor.ts

@@ -0,0 +1,115 @@
+import type { KeyPath } from '../schema'
+
+export interface JsonCursor {
+  /** `key`: completing a property name of the object at `path`. `value`: completing the value at `path`. */
+  mode: 'key' | 'value'
+  path: KeyPath
+  /** the range a completion replaces: a whole string (quotes included) or the word being typed */
+  from: number
+  to: number
+  inString: boolean
+  /** what was typed so far inside the string or word */
+  prefix: string
+  /** key mode: properties the object already has */
+  existing: Set<string>
+  /** key mode in a string: a `:` already follows, so only the key is replaced */
+  hasColon: boolean
+}
+
+type Frame =
+  | { t: 'o'; key?: string; expectKey: boolean; keys: Set<string> }
+  | { t: 'a'; index: number }
+
+const WORD = /[\w$.+-]/
+
+/**
+ * Where the cursor is in a (possibly unfinished) JSON document: which object or value, whether a key
+ * or a value is being written, and what is already there. Tolerates broken JSON, since the user is
+ * mid-edit. Returns undefined at the document root or where nothing can be completed.
+ */
+export function jsonCursor(text: string, pos: number): JsonCursor | undefined {
+  const stack: Frame[] = []
+  const top = () => stack[stack.length - 1]
+  let i = 0
+  while (i < pos) {
+    const c = text[i]
+    if (c === '"') {
+      let j = i + 1
+      let value = ''
+      while (j < text.length && text[j] !== '"' && text[j] !== '\n') {
+        if (text[j] === '\\') {
+          value += text[j + 1] ?? ''
+          j += 2
+        } else value += text[j++]
+      }
+      const closed = text[j] === '"'
+      const t = top()
+      if (pos <= j || (!closed && pos <= text.length && j >= pos)) {
+        // the cursor is inside this string
+        const isKey = t?.t === 'o' && t.expectKey
+        const to = closed ? j + 1 : pos
+        let after = to
+        while (/\s/.test(text[after] ?? '')) after++
+        return finish({
+          mode: isKey ? 'key' : 'value',
+          from: i,
+          to,
+          inString: true,
+          prefix: text.slice(i + 1, pos),
+          hasColon: text[after] === ':',
+        })
+      }
+      if (t?.t === 'o' && t.expectKey) {
+        t.key = value
+        t.keys.add(value)
+        t.expectKey = false
+      }
+      i = j + 1
+      continue
+    }
+    if (c === '{') stack.push({ t: 'o', expectKey: true, keys: new Set() })
+    else if (c === '[') stack.push({ t: 'a', index: 0 })
+    else if (c === '}' || c === ']') stack.pop()
+    else if (c === ',') {
+      const t = top()
+      if (t?.t === 'o') {
+        t.expectKey = true
+        t.key = undefined
+      } else if (t?.t === 'a') t.index++
+    }
+    i++
+  }
+
+  // not inside a string: the word being typed, if any
+  let from = pos
+  while (from > 0 && WORD.test(text[from - 1] ?? '')) from--
+  let to = pos
+  while (to < text.length && WORD.test(text[to] ?? '')) to++
+  const t = top()
+  return finish({
+    mode: t?.t === 'o' && t.expectKey ? 'key' : 'value',
+    from,
+    to,
+    inString: false,
+    prefix: text.slice(from, pos),
+    hasColon: false,
+  })
+
+  function finish(
+    c: Pick<JsonCursor, 'mode' | 'from' | 'to' | 'inString' | 'prefix' | 'hasColon'>,
+  ) {
+    if (stack.length === 0) return undefined
+    const path: KeyPath = []
+    for (let k = 0; k < stack.length; k++) {
+      const f = stack[k] as Frame
+      const last = k === stack.length - 1
+      if (f.t === 'o') {
+        if (last && c.mode === 'key') break
+        if (f.key === undefined) return undefined
+        path.push(f.key)
+      } else path.push(f.index)
+    }
+    const f = top()
+    return { ...c, path, existing: f?.t === 'o' ? f.keys : new Set<string>() }
+  }
+}

package/src/panel/stepnotes-split.ts

@@ -0,0 +1,38 @@
+export interface SequenceNotes {
+  /** the page without the sections that belong to steps */
+  intro: string
+  /** step name -> HTML of the section headed by that name */
+  notes: Map<string, string>
+}
+
+/** The text of a heading, without tags or entities. */
+const plain = (h: string) =>
+  h
+    .replace(/<[^>]+>/g, '')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+
+const norm = (s: string) => s.replace(/\s+/g, ' ').trim().toLowerCase()
+
+/**
+ * A `## Heading` that names a step becomes that step's note (everything up to the next `##`).
+ * Anything else stays in the intro, so ordinary headings keep working.
+ */
+export function splitStepNotes(html: string, stepNames: string[]): SequenceNotes {
+  const notes = new Map<string, string>()
+  if (!html || stepNames.length === 0) return { intro: html, notes }
+  const wanted = new Map(stepNames.map((n) => [norm(n), n]))
+  const intro: string[] = []
+  // the page is rendered markdown, so every `##` is an <h2> at the top level
+  for (const chunk of html.split(/(?=<h2[ >])/)) {
+    const m = /^<h2[^>]*>([\s\S]*?)<\/h2>/.exec(chunk)
+    const name = m ? wanted.get(norm(plain(m[1] as string))) : undefined
+    if (m && name !== undefined) {
+      if (!notes.has(name)) notes.set(name, chunk.slice(m[0].length))
+    } else intro.push(chunk)
+  }
+  return { intro: intro.join(''), notes }
+}

package/src/panel/stepnotes.ts

@@ -0,0 +1,58 @@
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import type { SequenceInfo } from '../engine'
+import { markdownToHtml } from '../markdown'
+import { registry } from '../runtime'
+
+export { type SequenceNotes, splitStepNotes } from './stepnotes-split'
+
+import { type SequenceNotes, splitStepNotes } from './stepnotes-split'
+
+/** The sequence's markdown page (or its description) split into an intro and per-step notes. */
+export function useSequenceNotes(info: SequenceInfo): SequenceNotes & { loaded: boolean } {
+  const { seq } = info
+  const [html, setHtml] = useState<string>()
+  const [loaded, setLoaded] = useState(false)
+  useEffect(() => {
+    let live = true
+    setHtml(undefined)
+    setLoaded(false)
+    const page = registry.docs.find(
+      (d) => d.sequence === seq.meta.id || d.sequenceFile === info.file,
+    )
+    if (!page) {
+      setLoaded(true)
+      return
+    }
+    page
+      .load()
+      .then((h: string) => live && setHtml(h))
+      .finally(() => live && setLoaded(true))
+    return () => {
+      live = false
+    }
+  }, [seq.meta.id, info.file])
+
+  const names = useMemo(() => seq.nodes.map((n) => n.name), [seq])
+  return useMemo(() => {
+    const source = html ?? markdownToHtml(seq.meta.description)
+    return { ...splitStepNotes(source, names), loaded }
+  }, [html, names, seq, loaded])
+}
+
+/** The markdown beside a saved request (`<name>.req.md`), rendered. */
+export function useRequestNote(file: string | undefined): string | undefined {
+  const [html, setHtml] = useState<string>()
+  useEffect(() => {
+    let live = true
+    setHtml(undefined)
+    if (file)
+      registry.docs
+        .find((d) => d.requestFile === file)
+        ?.load()
+        .then((h: string) => live && setHtml(h))
+    return () => {
+      live = false
+    }
+  }, [file])
+  return html
+}

package/src/routing.ts

@@ -0,0 +1,120 @@
+import {
+  MissingSecretsError,
+  type PreparedRequest,
+  secretNames,
+  substituteText,
+  type Transport,
+} from '@specbook/core'
+import { originOf, SECRET_PLACEHOLDER, type SecretStore } from './secrets'
+
+/** Who makes the outbound call for a service. */
+export type Route = 'direct' | 'proxy' | 'extension'
+
+/**
+ * Per service and per request:
+ * - a configured proxy (the dev server, or a hosted portal's same-origin route) takes every call;
+ * - otherwise a same-origin API is called straight from the page (no extension, cookies just work);
+ * - otherwise the extension, when it is installed and enabled, bypasses CORS;
+ * - otherwise a direct call, which may be blocked by CORS and says so.
+ */
+export function routeFor(o: {
+  proxy: boolean
+  extension: boolean
+  baseUrl: string
+  pageOrigin?: string
+}): Route {
+  if (o.proxy) return 'proxy'
+  if (o.pageOrigin && originOf(o.baseUrl) === o.pageOrigin) return 'direct'
+  if (o.extension) return 'extension'
+  return 'direct'
+}
+
+/** A config `baseUrl` may be relative (`/api/v1`): it is resolved against the page. */
+export function absoluteBase(baseUrl: string, pageHref?: string): string {
+  try {
+    return new URL(baseUrl, pageHref).toString()
+  } catch {
+    return baseUrl
+  }
+}
+
+const names = (req: PreparedRequest): string[] => {
+  const out = new Set<string>()
+  const scan = (v: unknown) => {
+    if (typeof v === 'string') for (const n of secretNames(new TextEncoder().encode(v))) out.add(n)
+    else if (Array.isArray(v)) v.forEach(scan)
+    else if (v && typeof v === 'object' && Object.getPrototypeOf(v) === Object.prototype)
+      Object.values(v).forEach(scan)
+  }
+  scan(req.headers)
+  scan(req.query)
+  scan(req.body)
+  return [...out]
+}
+
+/**
+ * Puts the values the person typed into a request, bound to the API's origin. A name with no value is
+ * left as a placeholder for whoever executes the call (the dev server falls back to its environment
+ * files, the extension to its own store); a direct call has no one to fall back on, so it stops there.
+ */
+export function withPageSecrets(
+  inner: Transport,
+  o: {
+    store: SecretStore
+    originFor(service: string): string | undefined
+    unresolved: 'keep' | 'fail'
+  },
+): Transport {
+  return (req, signal) => {
+    const asked = names(req)
+    if (asked.length === 0) return inner(req, signal)
+    const origin = o.originFor(req.service)
+    const values = new Map<string, string>()
+    const missing: string[] = []
+    for (const n of asked) {
+      const v = origin ? o.store.get(origin, n) : undefined
+      if (v === undefined) missing.push(n)
+      else values.set(n, v)
+    }
+    if (missing.length && o.unresolved === 'fail') throw new MissingSecretsError(missing)
+    const walk = (v: unknown): unknown =>
+      typeof v === 'string'
+        ? substituteText(v, values)
+        : Array.isArray(v)
+          ? v.map(walk)
+          : v && typeof v === 'object' && Object.getPrototypeOf(v) === Object.prototype
+            ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]))
+            : v
+    return inner(
+      {
+        ...req,
+        headers: walk(req.headers) as typeof req.headers,
+        query: walk(req.query) as typeof req.query,
+        body: walk(req.body),
+      },
+      signal,
+    )
+  }
+}
+
+export function routingTransport(o: {
+  direct: Transport
+  proxy?: Transport
+  extension?: Transport
+  baseOf(service: string): string
+  pageOrigin?: string
+}): Transport {
+  return (req, signal) => {
+    const route = routeFor({
+      proxy: !!o.proxy,
+      extension: !!o.extension,
+      baseUrl: o.baseOf(req.service),
+      pageOrigin: o.pageOrigin,
+    })
+    const send = route === 'proxy' ? o.proxy : route === 'extension' ? o.extension : o.direct
+    return (send ?? o.direct)(req, signal)
+  }
+}
+
+/** Re-exported for the credentials prompt. */
+export { SECRET_PLACEHOLDER }

package/src/runtime.ts

@@ -0,0 +1,32 @@
+import * as reg from 'virtual:specbook/registry'
+import { createEngine, pickRunnable } from './engine'
+import { detectExtension, type ExtensionBridge } from './extension'
+import { version } from './store'
+
+export const registry = reg
+
+// looking for the extension costs a short wait when it is absent, so a run does not repeat it
+let found: { at: number; bridge: ExtensionBridge | undefined } | undefined
+const extension = async () => {
+  if (found && Date.now() - found.at < 30_000) return found.bridge
+  const bridge = await detectExtension()
+  found = { at: Date.now(), bridge }
+  return bridge
+}
+
+export const engine = createEngine(reg as never, { extension })
+
+export const isStatic = reg.mode === 'static'
+
+/** Dev only: writes a project file through the plugin, then busts import caches. */
+export async function saveFile(path: string, content: string): Promise<void> {
+  const r = await fetch('/__specbook/save', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ path, content }),
+  })
+  if (!r.ok) throw new Error(((await r.json()) as { error?: string }).error ?? 'save failed')
+  version.value = Date.now()
+}
+
+export { pickRunnable }