@specbook/ui 0.1.0 → 0.3.0

package/src/styles/embed.css

@@ -0,0 +1,116 @@
+/*
+ * How the panel sits on someone else's page. Unlayered on purpose: it must beat the app's layered rules (the full-screen
+ * phone sheet, the sheet from the right) which this presentation replaces.
+ */
+
+/* the browser's top layer when it has one (so no host z-index can cover the panel), else a very high fixed box */
+.sb-top {
+  position: fixed;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  max-width: none;
+  max-height: none;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  overflow: visible;
+  background: transparent;
+  color: inherit;
+}
+.sb-top.sb-fallback {
+  z-index: 2147483000;
+}
+.sb-top[hidden] {
+  display: none;
+}
+
+.panel-backdrop {
+  backdrop-filter: blur(2px);
+}
+
+/* desktop: a centered dialog */
+.panel.popover {
+  position: fixed;
+  inset: 0;
+  margin: auto;
+  width: min(880px, calc(100vw - 48px));
+  min-width: 0;
+  height: min(86vh, 780px);
+  overflow: hidden;
+  border: 1px solid var(--sb-border);
+  border-radius: 14px;
+  box-shadow:
+    0 24px 64px color-mix(in srgb, black 35%, transparent),
+    0 2px 8px color-mix(in srgb, black 20%, transparent);
+  animation: sb-popover-in 180ms cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+@keyframes sb-popover-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px) scale(0.985);
+  }
+}
+@keyframes sb-sheet-in {
+  from {
+    opacity: 0;
+    transform: translateY(24px);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .panel.popover {
+    animation: none;
+  }
+}
+
+/* phone: a sheet from the bottom, with a handle, clear of the notch and the home bar */
+@media (max-width: 820px) {
+  .panel.popover {
+    inset: auto 0 0 0;
+    margin: 0;
+    width: 100%;
+    height: min(92dvh, calc(100dvh - env(safe-area-inset-top, 0px) - 12px));
+    border-width: 1px 0 0;
+    border-radius: 16px 16px 0 0;
+    padding-bottom: env(safe-area-inset-bottom, 0px);
+    animation-name: sb-sheet-in;
+  }
+  .panel.popover::before {
+    content: "";
+    flex: none;
+    width: 36px;
+    height: 4px;
+    margin: 8px auto 0;
+    border-radius: 2px;
+    background: var(--sb-border);
+  }
+}
+
+/* a finger, not a pointer: the controls of the header are comfortable targets */
+@media (pointer: coarse) {
+  .panel.popover .panel-head .icon {
+    min-width: 44px;
+    min-height: 44px;
+  }
+}
+
+.embed-problem {
+  margin: var(--sb-space-4);
+  color: var(--sb-text);
+}
+
+/* what the page's attributes asked for that could not be done, over the foot of the panel */
+.embed-banner {
+  position: fixed;
+  left: 50%;
+  bottom: 12px;
+  transform: translateX(-50%);
+  z-index: 22;
+  max-width: min(640px, calc(100vw - 24px));
+  padding: 6px 12px;
+  border: 1px solid var(--sb-border);
+  border-radius: 8px;
+  background: var(--sb-surface-raised, var(--sb-surface));
+  color: var(--sb-text);
+  font-size: 13px;
+}

package/src/styles/panel.css

@@ -377,6 +377,46 @@
     gap: var(--sb-space-2);
     padding: 8px;
   }
+  .panel-error {
+    margin: var(--sb-space-4);
+    padding: var(--sb-space-4);
+    border: 1px solid var(--sb-border);
+    border-left: 3px solid var(--sb-danger, #dc2626);
+    border-radius: var(--sb-radius-card);
+    background: var(--sb-surface);
+  }
+  .panel-error pre {
+    margin: var(--sb-space-2) 0 var(--sb-space-3);
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+    font: 12px var(--sb-font-mono);
+    color: var(--sb-text-muted);
+  }
+  button.flows-title {
+    width: 100%;
+    border: 0;
+    background: none;
+    color: inherit;
+    font: inherit;
+    text-align: left;
+    cursor: pointer;
+  }
+  @media (pointer: coarse) {
+    button.flows-title {
+      min-height: 44px;
+    }
+  }
+  button.flows-title:hover {
+    background: var(--sb-surface-raised);
+  }
+  button.flows-title:focus-visible {
+    outline: 2px solid var(--sb-focus-ring);
+    outline-offset: -2px;
+  }
+  .flows-title .caret {
+    width: 1em;
+    color: var(--sb-text-muted);
+  }
   .flows-title .count {
     margin-left: auto;
     font-size: 12px;
@@ -390,6 +430,20 @@
   .flows .op-row:last-child {
     border-bottom: 0;
   }
+  /* saved requests: the same block as flows, in the neutral border colour, so flows stay the one accent */
+  .flows.requests {
+    border-color: var(--sb-border);
+    border-left-color: var(--sb-text-muted);
+    background: var(--sb-surface-raised);
+  }
+  .method.req {
+    color: var(--sb-text-muted);
+  }
+  .req-tag {
+    margin-left: 6px;
+    font-size: 11px;
+    font-weight: 500;
+  }
   .flow-play {
     font-size: 10px;
     text-align: center;
@@ -715,13 +769,53 @@
   }
   .needs-var {
     display: inline-flex;
+    flex-wrap: wrap;
     align-items: center;
     gap: 6px;
+    min-width: 0;
+    max-width: 100%;
   }
   .needs-var input {
     width: 130px;
     min-width: 0;
   }
+  /* the pasted value looks like the client id field beside it */
+  .needs-var input[type="password"] {
+    padding: 5px 8px;
+    border: 1px solid var(--sb-border);
+    border-radius: var(--sb-radius-control);
+    background: var(--sb-surface);
+  }
+  /* Sign in: its own row inside the credential, so the client id, the button, the scopes and the status
+     wrap under each other on a narrow screen instead of running off the edge */
+  .oauth-signin {
+    flex: 1 1 100%;
+  }
+  .oauth-signin input[type="text"] {
+    flex: 1 1 140px;
+    width: auto;
+    max-width: 360px;
+  }
+  .oauth-signin details {
+    flex: 1 1 100%;
+    min-width: 0;
+  }
+  .oauth-signin input[type="checkbox"] {
+    flex: 0 0 auto;
+    width: auto;
+  }
+  .oauth-signin details label {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    min-height: 28px;
+    overflow-wrap: anywhere;
+  }
+  .oauth-status {
+    flex: 1 1 100%;
+    min-width: 0;
+    overflow-wrap: anywhere;
+  }
   .rq-meta {
     display: flex;
     align-items: center;
@@ -930,6 +1024,99 @@
     border: 0;
   }
 
+  /* ---- a failed check: what was expected, what came back, as a colored diff */
+  .visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+  .checks .bad {
+    margin-top: var(--sb-space-2);
+    color: inherit;
+  }
+  .check-fail {
+    display: grid;
+    gap: var(--sb-space-2);
+    margin: 0;
+    min-width: 0;
+    padding: var(--sb-space-3);
+    border: 1px solid color-mix(in srgb, var(--sb-danger) 35%, var(--sb-border));
+    border-left: 3px solid var(--sb-danger);
+    border-radius: var(--sb-radius-control);
+    background: color-mix(in srgb, var(--sb-danger) 5%, var(--sb-surface));
+  }
+  .check-head {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--sb-space-2);
+    color: var(--sb-danger);
+  }
+  .check-head strong {
+    min-width: 0;
+    overflow-wrap: anywhere;
+  }
+  .diff-legend {
+    display: flex;
+    gap: var(--sb-space-3);
+    font-size: 12px;
+    font-weight: 600;
+  }
+  .diff-key.diff-expected,
+  .diff-line.diff-expected {
+    color: var(--sb-success);
+  }
+  .diff-key.diff-received,
+  .diff-line.diff-received {
+    color: var(--sb-danger);
+  }
+  .diff {
+    margin: 0;
+    padding: var(--sb-space-2) 0;
+    white-space: pre;
+    max-height: 18em;
+    overflow: auto;
+    border-radius: var(--sb-radius-control);
+    background: var(--sb-surface);
+    border: 1px solid var(--sb-border);
+    font: 12.5px / 1.5 var(--sb-font-mono);
+  }
+  .diff-line {
+    display: flex;
+    min-width: max-content;
+    padding: 0 var(--sb-space-3) 0 0;
+  }
+  .diff-line.diff-expected {
+    background: var(--sb-success-subtle);
+  }
+  .diff-line.diff-received {
+    background: var(--sb-danger-subtle);
+  }
+  .diff-line.diff-same {
+    color: var(--sb-text-muted);
+  }
+  .diff-line.diff-skip {
+    color: var(--sb-text-muted);
+    font-style: italic;
+  }
+  .diff-gutter {
+    flex: none;
+    width: 2em;
+    text-align: center;
+    user-select: none;
+  }
+  .diff-text {
+    white-space: pre;
+  }
+  .check-where {
+    font: 12px var(--sb-font-mono);
+    color: var(--sb-text-muted);
+    overflow-wrap: anywhere;
+  }
+
   /* ---- shared small controls */
   .link {
     background: none;
@@ -1422,6 +1609,66 @@
       width: 60%;
     }
   }
+  .controls-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--sb-space-2);
+  }
+  .controls-head .gen-all {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    text-transform: none;
+    letter-spacing: 0;
+    font-size: 12px;
+    padding: 4px 10px;
+  }
+  /* a value with a generator: the cell and the button that makes another, never wider than the column */
+  .cell-gen {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    min-width: 0;
+  }
+  .cell-gen > :first-child {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+  .cell-gen .cell {
+    width: 100%;
+    min-width: 0;
+  }
+  .gen {
+    flex: none;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 28px;
+    height: 28px;
+    margin-right: 4px;
+    padding: 0;
+    color: var(--sb-text-muted);
+    background: transparent;
+    border: 1px solid var(--sb-border);
+    border-radius: var(--sb-radius-control);
+    cursor: pointer;
+  }
+  .gen:hover,
+  .gen:focus-visible {
+    color: var(--sb-accent);
+    border-color: var(--sb-accent);
+  }
+  /* a finger, not a pointer: the button is a comfortable target */
+  @media (pointer: coarse) {
+    .gen {
+      width: 44px;
+      height: 44px;
+    }
+    .controls-head .gen-all {
+      min-height: 44px;
+    }
+  }
   .multi-cell {
     display: flex;
     flex-wrap: wrap;
@@ -1538,6 +1785,8 @@
     max-height: min(70vh, 640px);
     overflow: auto;
     display: grid;
+    /* one column that cannot outgrow the popover: Safari sizes an auto track to its widest field */
+    grid-template-columns: minmax(0, 1fr);
     gap: var(--sb-space-3);
     padding: var(--sb-space-3) var(--sb-space-4);
     background: var(--sb-surface);
@@ -1611,6 +1860,23 @@
     background: var(--sb-danger-subtle);
     color: var(--sb-danger);
   }
+  /* a variable's value, where it comes from */
+  .envrow .src {
+    flex: none;
+    padding: 0 8px;
+    border-radius: 999px;
+    font-size: 11px;
+    font-weight: 600;
+  }
+  .src.inherited {
+    background: var(--sb-surface-raised);
+    color: var(--sb-text-muted);
+  }
+  .envuse {
+    margin: -2px 0 var(--sb-space-2);
+    padding-left: 2px;
+    overflow-wrap: anywhere;
+  }
   .op-lock {
     display: inline-block;
     margin-left: 6px;
@@ -1765,6 +2031,13 @@
     .envrow {
       flex-wrap: wrap;
     }
+    /* a variable: its name above, then the value (an address needs the room) beside its source */
+    .envrow code {
+      flex: 1 0 100%;
+    }
+    .envrow input {
+      flex: 1 1 0;
+    }
     .envrow input,
     .envrow select {
       min-width: 0;
@@ -1787,8 +2060,10 @@
       flex-wrap: wrap;
       padding-inline: var(--sb-space-3);
     }
-    /* the credentials note is in the chip's tooltip; not worth a line of a phone screen */
-    .secrets-note {
+    /* the credentials note is in the chip's tooltip; not worth a line of a phone screen. The redirect
+       address to register is a desktop job too; a problem or a wait is still shown */
+    .secrets-note,
+    .oauth-hint {
       display: none;
     }
     .secrets-folded,

package/src/viewer/embed.ts

@@ -9,6 +9,7 @@
  * The script takes the page over (it owns the document, as `/docs` does). `spec` may be relative.
  * `baseUrl` gives the API address when the document has none, `target` names another container.
  */
+import { handleOAuthCallback } from '../oauth-callback'
 import { SpecWorker } from './client'
 import { mountOpened } from './mount'
 
@@ -46,6 +47,10 @@ const say = (el: HTMLElement, text: string, error = false) => {
 }
 
 async function start() {
+  // A sign-in's popup comes back to this page, so the viewer is what has to hand the code on. The address
+  // is left alone unless a viewer tab claims it: the page is the host's, and its `?code=&state=` may be
+  // the host application's own sign-in.
+  if (await handleOAuthCallback({ stripWhenUnclaimed: false })) return
   const cfg = readConfig()
   const target = container(cfg.target)
   if (!cfg.spec)

package/src/viewer/main.tsx

@@ -1,5 +1,6 @@
 import { render } from 'preact'
 import { useEffect, useRef, useState } from 'preact/hooks'
+import { handleOAuthCallback } from '../oauth-callback'
 import { applyTheme } from '../theme'
 import { type OpenFailure, SpecWorker } from './client'
 import { mountOpened } from './mount'
@@ -282,4 +283,7 @@ function BasePrompt({
   )
 }
 
-render(<Picker initial={{ kind: 'idle' }} />, root)
+// a sign-in's return leg lands on this page too: hand it to the tab that started it, draw nothing here
+void handleOAuthCallback().then((handled) => {
+  if (!handled) render(<Picker initial={{ kind: 'idle' }} />, root)
+})

package/src/viewer/manifests.ts

@@ -0,0 +1,2 @@
+// The viewer's registry has its one manifest from the start; there is nothing to fill in.
+export {}

package/src/viewer/protocol.ts

@@ -1,3 +1,4 @@
+import type { ServerEntry } from '@specbook/core'
 import type { AuthProfileLike } from './registry-data'
 
 /** Where a spec comes from. */
@@ -24,8 +25,16 @@ export interface OpenResult {
   auth: Record<string, AuthProfileLike>
   secrets: Record<string, Record<string, never>>
   defaultProfile?: string
+  /**
+   * Sign-in addresses the document gives relative to its servers, as variables: the values for `live`,
+   * and per other environment. The profiles in `auth` read them as `{{name}}`.
+   */
+  authVars: Record<string, string>
+  authEnvironmentVars: Record<string, Record<string, string>>
   /** absolute API address, from `servers` (resolved against the spec URL) or `host` */
   baseUrl?: string
+  /** every usable server the document lists, as environments; the first is `live` */
+  servers: ServerEntry[]
   /** a relative `servers` entry the person has to give a base URL for */
   needsBaseUrl: boolean
   warnings: string[]

package/src/viewer/registry-data.ts

@@ -1,4 +1,8 @@
+import type { OAuthSettings } from '@specbook/core'
+
 export interface AuthProfileLike {
   title: string
   apply: { headers?: Record<string, string>; query?: Record<string, string> }
+  /** the scheme's authorization code flow, when it has one the page can sign in to */
+  oauth?: OAuthSettings
 }

package/src/viewer/registry.ts

@@ -3,7 +3,7 @@
  * the document in a worker and puts the result on `globalThis.__SPECBOOK_VIEWER__` before the app is
  * imported; this module turns that into the same named exports the dev server and the static build give.
  */
-import { defineOperation, type OpMeta } from '@specbook/core'
+import { defineOperation, environmentsFromServers, type OpMeta } from '@specbook/core'
 import type { OpenResult } from './protocol'
 
 export interface ViewerGlobal {
@@ -32,7 +32,10 @@ const ids = Object.keys(open.metas)
 export const mode = 'static' as const
 export const project = { root: '', outDir: '', requestsDir: 'requests' }
 export const manifests = { [service]: open.manifest }
+export const loadManifests = async (_services?: string[]) => {}
 export const requests: never[] = []
+export const requestMeta = {}
+export const unresolvedRequests: string[] = []
 export const sequences: never[] = []
 export const sequenceMeta = {}
 export const unresolvedSequences: string[] = []
@@ -134,19 +137,61 @@ export const loadFaker = () =>
     },
   }))
 
-const baseUrl = v.baseUrl ?? open.baseUrl
+// `live` is the document's first server, or the address the person typed for it; the rest keep their own
+// names. Each address is the variable `baseUrl` in its environment, so a copy of one can point elsewhere.
+const live = v.baseUrl ?? open.baseUrl
+const liveServer = open.servers.find((s) => s.name === 'live')
+const addresses = environmentsFromServers(
+  [
+    ...(live ? [{ name: 'live', url: live, description: liveServer?.description }] : []),
+    ...open.servers.filter((s) => s.name !== 'live'),
+  ],
+  'baseUrl',
+)
+// a sign-in address the document gave relative to its server needs the address the person typed
+const absolute = (value: string) => {
+  if (/^https?:\/\//i.test(value) || !v.baseUrl) return value
+  try {
+    return new URL(value, `${v.baseUrl.replace(/\/+$/, '')}/`).toString()
+  } catch {
+    return value
+  }
+}
+const vars = {
+  ...addresses.vars,
+  ...Object.fromEntries(Object.entries(open.authVars).map(([k, x]) => [k, absolute(x)])),
+}
+const environmentSettings: Record<string, { description?: string; vars?: Record<string, string> }> =
+  {
+    ...addresses.environments,
+  }
+for (const [name, evars] of Object.entries(open.authEnvironmentVars))
+  environmentSettings[name] = {
+    ...environmentSettings[name],
+    vars: { ...environmentSettings[name]?.vars, ...evars },
+  }
+/** Where environments made in this browser are kept: per spec address, or for the tab for an upload. */
+export const environmentStore: { scope: string; session: boolean } | null = v.source
+  ? {
+      scope: v.source.kind === 'url' ? v.source.url : `upload:${service}`,
+      session: v.source.kind !== 'url',
+    }
+  : null
 export const loadConfig = () =>
   Promise.resolve({
     default: {
       project: service,
       secrets: open.secrets,
       auth: open.auth,
+      ...(Object.keys(vars).length ? { vars } : {}),
+      ...(Object.keys(environmentSettings).length ? { environments: environmentSettings } : {}),
       // one locale, so the header offers no locale choice
       faker: { default: 'en', locales: { en: ['en', 'base'] } },
       services: {
         [service]: {
           spec: '',
-          baseUrl: baseUrl ? { live: baseUrl } : {},
+          // a document that gives no address at all has no live environment either
+          baseUrl: live || open.servers.length ? addresses.baseUrl : {},
           ...(open.defaultProfile ? { auth: open.defaultProfile } : {}),
         },
       },

package/src/viewer/worker.ts

@@ -1,6 +1,6 @@
 /// <reference lib="webworker" />
 import { generateData, type OperationMeta, openSpec } from '@specbook/codegen/browser'
-import { authFromSpec, liveBaseUrl } from '@specbook/core'
+import { authFromSpec, MAX_SERVERS, openApiServers } from '@specbook/core'
 import { bundleJson, type Parts, sortFiles } from './bundles'
 import type { OpenResult, Request, Response, Source } from './protocol'
 
@@ -112,11 +112,16 @@ async function open(id: number, source: Source, signal: AbortSignal): Promise<Op
       (o.examples as { name: string }[]).map((e) => e.name),
     ]),
   )
-  const { auth, secrets, defaultProfile } = authFromSpec(doc)
   const sourceUrl = source.kind === 'url' ? source.url : undefined
-  const baseUrl = liveBaseUrl(doc, sourceUrl ?? name ?? '')
-  const relativeServer =
-    typeof doc.servers?.[0]?.url === 'string' && !/^https?:\/\//i.test(doc.servers[0].url)
+  const { servers, needsBaseUrl, omitted } = openApiServers(doc, sourceUrl ?? name ?? '')
+  const {
+    auth,
+    secrets,
+    defaultProfile,
+    vars: authVars,
+    environmentVars: authEnvironmentVars,
+  } = authFromSpec(doc, sourceUrl, servers)
+  const baseUrl = servers.find((s) => s.name === 'live')?.url
   return {
     service,
     title,
@@ -126,9 +131,17 @@ async function open(id: number, source: Source, signal: AbortSignal): Promise<Op
     auth,
     secrets,
     defaultProfile,
+    authVars,
+    authEnvironmentVars,
     baseUrl,
-    needsBaseUrl: !baseUrl && relativeServer,
-    warnings,
+    servers,
+    needsBaseUrl,
+    warnings: omitted
+      ? [
+          ...warnings,
+          `This document lists ${servers.length + omitted} servers. The first ${MAX_SERVERS} are offered as environments.`,
+        ]
+      : warnings,
     timings: {
       ...(fetched !== undefined ? { fetch: Math.round(fetched) } : {}),
       parse: Math.round(parse),

package/src/virtual.d.ts

@@ -6,6 +6,8 @@ declare module 'virtual:specbook/registry' {
     source?: () => Promise<string>
   }
   export const mode: 'dev' | 'static'
+  /** A build that publishes only the operations the project's requests and flows use. */
+  export const minimal: boolean | undefined
   export const project: { root: string; outDir: string; requestsDir: string }
   export const manifests: Record<
     string,
@@ -28,7 +30,13 @@ declare module 'virtual:specbook/registry' {
       }[]
     }
   >
+  /** Fetches the manifests of the named services (all when none are named) into `manifests`. A build starts with it empty. */
+  export const loadManifests: (services?: string[]) => Promise<void>
   export const requests: Entry[]
+  /** Which `service/Operation` each request file is for, read from its text (no import), by project-relative file. */
+  export const requestMeta: Record<string, string>
+  /** Request files whose text does not say; these are imported to be listed. */
+  export const unresolvedRequests: string[]
   export const sequences: Entry[]
   /** Sequence headers read from the `*.seq.ts` text (no import), keyed by id. */
   export const sequenceMeta: Record<