@specbook/ui 0.2.0 → 0.3.0

package/src/custom-environments.ts

@@ -0,0 +1,63 @@
+/**
+ * Environments a person makes in the browser, for pages with no project files to write them to (a built
+ * site, the hosted viewer). A variable here is not a secret, so it lives in `localStorage`, kept per spec; a
+ * document opened from a file has no stable address and keeps them for the tab only.
+ */
+import { kv } from './storage'
+
+const KEY = 'specbook.environments.v1'
+
+export interface BrowserEnvironment {
+  /** the environment it was copied from; absent for a built-in environment this browser overrides */
+  from?: string
+  vars: Record<string, string>
+}
+
+export interface EnvironmentStore {
+  all(): Record<string, BrowserEnvironment>
+  save(name: string, env: BrowserEnvironment): void
+  remove(name: string): void
+}
+
+type Table = Record<string, Record<string, BrowserEnvironment>>
+
+const memory: Record<'local' | 'session', Table> = { local: {}, session: {} }
+
+const storageOf = (kind: 'local' | 'session') => (kind === 'local' ? kv.local : kv.session)
+
+function read(kind: 'local' | 'session'): Table {
+  try {
+    const raw = storageOf(kind).getItem(KEY)
+    return raw ? (JSON.parse(raw) as Table) : memory[kind]
+  } catch {
+    return memory[kind]
+  }
+}
+
+function write(kind: 'local' | 'session', table: Table) {
+  memory[kind] = table
+  try {
+    storageOf(kind).setItem(KEY, JSON.stringify(table))
+  } catch {
+    /* private mode or blocked storage: the in-memory copy still serves this page */
+  }
+}
+
+/** The store for one spec (`scope`: its address); `session` keeps it for this tab only. */
+export function createEnvironmentStore(
+  scope: string,
+  kind: 'local' | 'session' = 'local',
+): EnvironmentStore {
+  return {
+    all: () => read(kind)[scope] ?? {},
+    save(name, env) {
+      const t = read(kind)
+      write(kind, { ...t, [scope]: { ...t[scope], [name]: env } })
+    },
+    remove(name) {
+      const t = read(kind)
+      const { [name]: _gone, ...rest } = t[scope] ?? {}
+      write(kind, { ...t, [scope]: rest })
+    },
+  }
+}

package/src/embed/panel.tsx

@@ -1,115 +1,357 @@
 import { render } from 'preact'
 import { useEffect, useState } from 'preact/hooks'
+import { brandCss } from '../branding'
 import type { SequenceInfo, Variant } from '../engine'
+import { setNavigator } from '../nav'
 import { Host } from '../panel/Host'
+import { Panel } from '../panel/Panel'
 import { engine, registry } from '../runtime'
-import { env, environmentNote, environmentRisk, environments, version } from '../store'
+import { useMemoryStorage } from '../storage'
+import {
+  env,
+  environmentNote,
+  environmentRisk,
+  environments,
+  features,
+  locale,
+  version,
+} from '../store'
 import { panelSheets } from './styles'
+import type { Target } from './target'
+import { followTheme, setMode } from './theme'
 
-export interface Target {
-  service?: string
-  operation?: string
-  sequence?: string
-  example?: string
-  /** open on the Docs tab instead of Try */
-  tab?: 'docs' | 'try'
-}
+// A page that embeds the panel owns its storage and its address: what a visitor types stays in memory, nothing is
+// written to the page's `localStorage`, and a link inside the panel opens inside it. There is no dialog for creating an
+// environment or for settings here, so the controls that lead to them are not offered.
+useMemoryStorage()
+features.value = { createEnvironment: false, environmentSettings: false }
+
+export type { Target } from './target'
 
 interface Loaded {
   variants: Record<string, Variant[]>
 }
 
-let loaded: Promise<Loaded> | undefined
-const load = () =>
-  (loaded ??= (async () => {
+/** The environments, locale and accent: shared by everything a page opens, so asked for once. */
+let shared: Promise<void> | undefined
+const loadShared = () =>
+  (shared ??= (async () => {
     environments.value = await engine.environments(version.value)
     environmentRisk.value = await engine.environmentRisks(version.value)
     environmentNote.value = await engine.environmentNotes(version.value)
     env.value = environments.value.includes('mock') ? 'mock' : (environments.value[0] ?? 'mock')
-    return { variants: await engine.loadVariants(registry.requests, version.value) }
+    // the project's faker locale and accent, as the app applies them
+    const cfg = await engine.config(version.value).catch(() => undefined)
+    if (cfg?.faker?.default) locale.value = cfg.faker.default
+    if (cfg?.branding) applyBranding(cfg.branding)
   })())
 
+/**
+ * One request: only the request files that are for its operation are imported (the registry says which from their text),
+ * and only its service's list of operations is fetched, not every request and every service of the project.
+ */
+async function loadRequest(t: Target): Promise<Loaded & { service?: string; operation?: string }> {
+  const wanted = (file: string, key?: string) =>
+    t.request
+      ? file === t.request
+      : registry.requestMeta[file] === key || registry.unresolvedRequests.includes(file)
+  let key: string | undefined
+  if (!t.request) {
+    // a bare operation id names no service: the lists of all services say which has it
+    if (!t.service) await registry.loadManifests()
+    const service =
+      t.service ??
+      Object.values(registry.manifests).find((m) => m.operations.some((o) => o.id === t.operation))
+        ?.service
+    key = service && t.operation ? `${service}/${t.operation}` : undefined
+    if (!key) return { variants: {} }
+  }
+  const entries = registry.requests.filter((e) => wanted(e.file, key))
+  const variants = await engine.loadVariants(entries, version.value)
+  if (t.request) {
+    const hit = Object.keys(variants)[0]
+    if (!hit) return { variants }
+    key = hit
+  }
+  const at = (key as string).indexOf('/')
+  const service = (key as string).slice(0, at)
+  await registry.loadManifests([service])
+  return { variants, service, operation: (key as string).slice(at + 1) }
+}
+
 /** Headers are read from the file text, so only the requested module (or the odd unresolved ones) is imported. */
 async function loadSequence(id: string) {
   const file = registry.sequenceMeta[id]?.file
   const wanted = (f: string) => (file ? f === file : registry.unresolvedSequences.includes(f))
   const entries = registry.sequences.filter((e) => wanted(e.file))
   const list = await engine.loadSequences(entries, version.value)
-  return list.find((s) => s.seq.meta.id === id)
+  const found = list.find((s) => s.seq.meta.id === id)
+  if (found) {
+    // the services its steps call; a step built by a function is only known when it runs, so any such step asks for all
+    const names = new Set<string>()
+    let all = false
+    for (const n of found.seq.nodes) {
+      if (n.kind === 'step' && typeof n.def !== 'function') names.add(n.def.op.service)
+      else if (n.kind === 'step' || n.kind === 'each') all = true
+    }
+    await registry.loadManifests(all ? undefined : [...names])
+  }
+  return found
+}
+
+function findOperation(t: Target, data: Loaded & { service?: string; operation?: string }) {
+  if (!data.service || !data.operation) return undefined
+  const op = registry.manifests[data.service]?.operations.find((o) => o.id === data.operation)
+  if (!op) return undefined
+  return {
+    service: data.service,
+    op,
+    example: t.request ? `saved:${t.request}` : (t.example ?? ''),
+  }
 }
 
-function findOperation(t: Target) {
-  const services = Object.values(registry.manifests)
-  const scope = t.service ? services.filter((m) => m.service === t.service) : services
-  for (const m of scope) {
-    const op = m.operations.find((o) => o.id === t.operation)
-    if (op) return { service: m.service, op }
+const isProduction = (name: string) =>
+  environmentRisk.value[name] === 'production' ||
+  (environmentRisk.value[name] !== 'sandbox' && /prod/i.test(name))
+
+/** Applies the element's environment: unknown names fall back with a note, and auto-run is refused for production. */
+function chooseEnvironment(t: Target): string | undefined {
+  if (!t.env) return undefined
+  if (!environments.value.includes(t.env)) {
+    return `Environment "${t.env}" does not exist here (${environments.value.join(', ')}); using "${env.value}".`
   }
+  env.value = t.env
   return undefined
 }
 
+function Problem({ title, text, onClose }: { title: string; text: string; onClose: () => void }) {
+  return (
+    <Panel title={title} modal variant="popover" onClose={onClose}>
+      <p class="embed-problem" role="alert">
+        {text}
+      </p>
+    </Panel>
+  )
+}
+
 function Embedded({ target, onClose }: { target: Target; onClose: () => void }) {
-  const [data, setData] = useState<Loaded>()
+  const [data, setData] = useState<Loaded & { service?: string; operation?: string }>()
   const [seq, setSeq] = useState<SequenceInfo>()
+  const [seqMissing, setSeqMissing] = useState(false)
+  const [note, setNote] = useState<string>()
   const [view, setView] = useState<{ tab: 'docs' | 'try'; example: string }>({
     tab: target.tab ?? 'try',
     example: target.example ?? '',
   })
   const navigate = (to: { tab: 'docs' | 'try'; example?: string }) =>
     setView({ tab: to.tab, example: to.example ?? view.example })
+
   useEffect(() => {
-    load().then(setData)
-    if (target.sequence) loadSequence(target.sequence).then(setSeq)
+    // one navigation inside the panel at a time: a link in the docs opens that operation or flow here
+    setNavigator((r) => {
+      if (r.kind === 'op') show({ service: r.key.split('/')[0], operation: r.key.split('/')[1] })
+      else if (r.kind === 'seq') show({ sequence: r.id })
+    })
+    return () => setNavigator(undefined)
   }, [])
-  if (target.sequence)
-    return seq ? (
-      <Host kind="seq" info={seq} tab={view.tab} onNavigate={navigate} onClose={onClose} />
+
+  useEffect(() => {
+    loadShared().then(async () => {
+      setNote(chooseEnvironment(target))
+      if (target.sequence) {
+        const s = await loadSequence(target.sequence)
+        if (s) setSeq(s)
+        else setSeqMissing(true)
+        setData({ variants: {} })
+      } else setData(await loadRequest(target))
+    })
+  }, [])
+
+  const wantsAutoRun = !!target.autoRun && !isProduction(env.value)
+  const autoRunRefused = !!target.autoRun && isProduction(env.value)
+  const banner = [target.problem, note, autoRunRefused ? 'Auto-run is off for production.' : '']
+    .filter(Boolean)
+    .join(' ')
+
+  if (target.sequence) {
+    if (seqMissing)
+      return (
+        <Problem
+          title="Flow not found"
+          text={`This build has no flow "${target.sequence}".`}
+          onClose={onClose}
+        />
+      )
+    return seq && data ? (
+      <>
+        <Host
+          kind="seq"
+          info={seq}
+          variant="popover"
+          tab={view.tab}
+          preset={target.inputs}
+          autoRun={wantsAutoRun}
+          onNavigate={navigate}
+          onClose={onClose}
+        />
+        {banner && <Banner text={banner} />}
+      </>
     ) : null
+  }
   if (!data) return null
-  const found = findOperation(target)
-  if (!found) return null
+  const found = findOperation(target, data)
+  if (!found)
+    return (
+      <Problem
+        title="Request not found"
+        text={`This build has no request "${target.request ?? [target.service, target.operation].filter(Boolean).join('/')}".`}
+        onClose={onClose}
+      />
+    )
+  return (
+    <>
+      <Host
+        kind="op"
+        service={found.service}
+        op={found.op}
+        variants={data.variants[`${found.service}/${found.op.id}`] ?? []}
+        example={view.example || found.example}
+        variant="popover"
+        tab={view.tab}
+        autoRun={wantsAutoRun}
+        onNavigate={navigate}
+        onClose={onClose}
+      />
+      {banner && <Banner text={banner} />}
+    </>
+  )
+}
+
+/** A line over the panel for what the page's attributes asked that could not be done. */
+function Banner({ text }: { text: string }) {
   return (
-    <Host
-      kind="op"
-      service={found.service}
-      op={found.op}
-      variants={data.variants[`${found.service}/${found.op.id}`] ?? []}
-      example={view.example}
-      tab={view.tab}
-      onNavigate={navigate}
-      onClose={onClose}
-    />
+    <div class="embed-banner" role="status">
+      {text}
+    </div>
   )
 }
 
+let brandSheet: CSSStyleSheet | undefined
+function applyBranding(b: Parameters<typeof brandCss>[0]) {
+  const css = brandCss(b, 'host')
+  if (!css) return
+  brandSheet = new CSSStyleSheet()
+  brandSheet.replaceSync(css)
+  const panel = document.querySelector<SpecbookPanel>('specbook-panel')
+  panel?.adopt(brandSheet)
+}
+
+/** The active element through any number of shadow roots, which is where focus goes back to. */
+function deepActive(): HTMLElement | null {
+  let el = document.activeElement as HTMLElement | null
+  while (el?.shadowRoot?.activeElement) el = el.shadowRoot.activeElement as HTMLElement
+  return el
+}
+
 class SpecbookPanel extends HTMLElement {
   private mount!: HTMLElement
+  private top!: HTMLElement
+  private opener: HTMLElement | null = null
+  private trigger: HTMLElement | undefined
+  private native = false
 
   connectedCallback() {
     if (this.shadowRoot) return
     const root = this.attachShadow({ mode: 'open' })
     root.adoptedStyleSheets = panelSheets()
+    this.top = document.createElement('div')
+    this.top.className = 'sb-top'
+    this.native = typeof this.top.showPopover === 'function'
+    if (this.native) this.top.setAttribute('popover', 'manual')
+    else this.top.className += ' sb-fallback'
+    this.top.hidden = !this.native
     this.mount = document.createElement('div')
     this.mount.className = 'sb-root'
-    root.append(this.mount)
+    this.top.append(this.mount)
+    root.append(this.top)
+    if (brandSheet) this.adopt(brandSheet)
+  }
+
+  adopt(sheet: CSSStyleSheet) {
+    const root = this.shadowRoot
+    if (root && !root.adoptedStyleSheets.includes(sheet))
+      root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet]
   }
 
-  show(target: Target | undefined) {
+  show(target: Target | undefined, trigger?: HTMLElement) {
+    if (!target) return this.close()
+    if (trigger) {
+      this.trigger = trigger
+      this.opener = deepActive()
+      setExpanded(trigger, true)
+      trigger.dispatchEvent(
+        new CustomEvent('specbook:open', { bubbles: true, composed: true, detail: target }),
+      )
+    }
+    if (this.isConnected) {
+      if (this.followed) setMode(this, target.theme)
+      else {
+        followTheme(this, target.theme)
+        this.followed = true
+      }
+    }
+    if (this.native) {
+      if (!this.top.matches(':popover-open')) this.top.showPopover()
+    } else this.top.hidden = false
     render(
-      target ? <Embedded target={target} onClose={() => this.show(undefined)} /> : null,
+      <Embedded key={JSON.stringify(target)} target={target} onClose={() => this.close()} />,
       this.mount,
     )
   }
+
+  private followed = false
+
+  close() {
+    render(null, this.mount)
+    if (this.native) {
+      if (this.top.matches(':popover-open')) this.top.hidePopover()
+    } else this.top.hidden = true
+    const trigger = this.trigger
+    this.trigger = undefined
+    if (trigger) {
+      setExpanded(trigger, false)
+      trigger.dispatchEvent(new CustomEvent('specbook:close', { bubbles: true, composed: true }))
+    }
+    // back to where the person was, which is the button that opened the panel
+    const opener = this.opener
+    this.opener = null
+    // a programmatic open leaves focus on the page's body, so the trigger itself is where it goes back to
+    const back =
+      opener && opener !== document.body
+        ? opener
+        : (trigger?.shadowRoot?.querySelector('button') ?? trigger)
+    if (back?.isConnected) back.focus()
+  }
+}
+
+/** The button that opens the panel says whether it is open. */
+function setExpanded(trigger: HTMLElement, open: boolean) {
+  const button = trigger.shadowRoot?.querySelector('button') ?? trigger
+  button.setAttribute('aria-expanded', String(open))
 }
 
 customElements.define('specbook-panel', SpecbookPanel)
 
-/** One panel serves every Play button on the page. */
-export function show(target: Target) {
+/** One panel serves every trigger on the page. */
+export function show(target: Target, trigger?: HTMLElement) {
   let panel = document.querySelector<SpecbookPanel>('specbook-panel')
   if (!panel) {
     panel = document.createElement('specbook-panel') as SpecbookPanel
     document.body.append(panel)
   }
-  panel.show(target)
+  panel.show(target, trigger)
+}
+
+export function close() {
+  document.querySelector<SpecbookPanel>('specbook-panel')?.close()
 }

package/src/embed/styles.ts

@@ -2,6 +2,7 @@ import complete from 'prism-code-editor/autocomplete.css?inline'
 import completeIcons from 'prism-code-editor/autocomplete-icons.css?inline'
 import layout from 'prism-code-editor/layout.css?inline'
 import app from '../styles/app.css?inline'
+import embed from '../styles/embed.css?inline'
 import panel from '../styles/panel.css?inline'
 import tokens from '../styles/tokens.css?inline'
 
@@ -21,6 +22,7 @@ export const panelSheets = () => [
   sheet(app),
   sheet(panel),
   sheet(root),
+  sheet(embed),
 ]
 
 /** Inline `color`/`font` on the host would be beaten by host-page rules, so the root element sets them. */

package/src/embed/target.ts

@@ -0,0 +1,82 @@
+// What a page's data attributes ask the play panel to open. Pure, so it is tested in node.
+
+export type EmbedTheme = 'host' | 'auto' | 'light' | 'dark'
+
+export interface Target {
+  /** `petstore` of `petstore/GetPetById`; empty when the build has one service and the attribute gave a bare id */
+  service?: string
+  operation?: string
+  /** a saved request, by its project file (`requests/petstore/find-pets.req.ts`) */
+  request?: string
+  sequence?: string
+  example?: string
+  /** open on the Docs tab instead of Try */
+  tab?: 'docs' | 'try'
+  /** preset flow inputs, merged over each input's default */
+  inputs?: Record<string, unknown>
+  /** why `inputs` was not used */
+  problem?: string
+  env?: string
+  autoRun?: boolean
+  theme?: EmbedTheme
+}
+
+/** The attributes the panel reads, all namespaced so a host page's own `data-theme` or `data-env` cannot collide. */
+export const TRIGGER_SELECTOR = '[data-specbook-try],[data-specbook-flow]'
+
+const THEMES = new Set<string>(['host', 'auto', 'light', 'dark'])
+
+type Attrs = Pick<Element, 'getAttribute' | 'hasAttribute' | 'closest'>
+
+const attr = (el: Attrs, name: string) =>
+  el.getAttribute(`data-specbook-${name}`)?.trim() || undefined
+
+/** The nearest ancestor (or the element itself) that sets an attribute, for page-wide defaults like the environment. */
+function inherited(el: Attrs, name: string): string | undefined {
+  return attr(el.closest(`[data-specbook-${name}]`) ?? el, name)
+}
+
+/**
+ * Reads one trigger. `data-specbook-try="petstore/GetPetById"` (or a bare `GetPetById`, or a saved request's file)
+ * opens a request and `data-specbook-flow="adopt-pet"` a flow; a flow wins when both are given.
+ */
+export function parseTarget(el: Attrs): Target | undefined {
+  const tryValue = attr(el, 'try')
+  const flow = attr(el, 'flow')
+  if (!tryValue && !flow) return undefined
+
+  const target: Target = {
+    example: attr(el, 'example'),
+    tab: attr(el, 'tab') === 'docs' ? 'docs' : undefined,
+    env: inherited(el, 'env'),
+    autoRun: el.hasAttribute('data-specbook-auto-run'),
+  }
+  const theme = inherited(el, 'theme')
+  if (theme && THEMES.has(theme)) target.theme = theme as EmbedTheme
+
+  if (flow) target.sequence = flow
+  else if (tryValue) {
+    if (/\.req\.ts$/.test(tryValue)) target.request = tryValue
+    else {
+      const slash = tryValue.indexOf('/')
+      if (slash < 0) target.operation = tryValue
+      else {
+        target.service = tryValue.slice(0, slash)
+        target.operation = tryValue.slice(slash + 1)
+      }
+    }
+  }
+
+  const inputs = attr(el, 'inputs')
+  if (inputs) {
+    try {
+      const parsed: unknown = JSON.parse(inputs)
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+        target.inputs = parsed as Record<string, unknown>
+      else target.problem = 'data-specbook-inputs must be a JSON object, such as {"quantity":2}.'
+    } catch {
+      target.problem = `data-specbook-inputs is not valid JSON: ${inputs}`
+    }
+  }
+  return target
+}

package/src/embed/theme.ts

@@ -0,0 +1,75 @@
+// Which colors the panel and the Play buttons wear: the host page's, unless the author says otherwise. Tokens react to a
+// `data-theme` attribute on the host element itself, which is all a shadow root can see.
+
+import type { EmbedTheme } from './target'
+
+export type Scheme = 'light' | 'dark' | undefined
+
+export interface PageTheme {
+  /** `data-theme` on the root element (Starlight, many docs themes) */
+  attr?: string | null
+  /** the root element's classes (`dark`, `light`: Tailwind and others) */
+  classes?: string
+  /** the computed `color-scheme` of the root element */
+  colorScheme?: string
+}
+
+/** `undefined` is "auto": follow the operating system. Pure, so it is tested in node. */
+export function pageScheme(p: PageTheme): Scheme {
+  if (p.attr === 'light' || p.attr === 'dark') return p.attr
+  const classes = (p.classes ?? '').split(/\s+/)
+  if (classes.includes('dark')) return 'dark'
+  if (classes.includes('light')) return 'light'
+  const cs = (p.colorScheme ?? '').trim()
+  if (cs === 'dark' || cs === 'light') return cs
+  return undefined
+}
+
+/** What an element asking for `mode` should wear, given the page. */
+export function schemeFor(mode: EmbedTheme | undefined, page: PageTheme): Scheme {
+  if (mode === 'light' || mode === 'dark') return mode
+  if (mode === 'auto') return undefined
+  return pageScheme(page)
+}
+
+const readPage = (): PageTheme => {
+  const root = document.documentElement
+  return {
+    attr: root.getAttribute('data-theme'),
+    classes: root.className,
+    colorScheme: getComputedStyle(root).colorScheme,
+  }
+}
+
+const themed = new Map<HTMLElement, EmbedTheme | undefined>()
+let watching = false
+
+const apply = (el: HTMLElement, mode: EmbedTheme | undefined) => {
+  const s = schemeFor(mode, readPage())
+  if (s) el.setAttribute('data-theme', s)
+  else el.removeAttribute('data-theme')
+}
+
+/** Keeps `el` in step with the page: set now, and again when the page changes its theme. */
+export function followTheme(el: HTMLElement, mode: EmbedTheme | undefined): void {
+  themed.set(el, mode)
+  apply(el, mode)
+  if (watching || typeof MutationObserver === 'undefined') return
+  watching = true
+  const refresh = () => {
+    for (const [e, m] of themed) {
+      if (e.isConnected) apply(e, m)
+      else themed.delete(e)
+    }
+  }
+  new MutationObserver(refresh).observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ['data-theme', 'class', 'style'],
+  })
+}
+
+/** A new mode for an element already followed (a different Play button opens the one panel). */
+export function setMode(el: HTMLElement, mode: EmbedTheme | undefined): void {
+  if (themed.has(el)) themed.set(el, mode)
+  apply(el, mode)
+}