@specbook/ui 0.2.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;
@@ -970,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;
@@ -1462,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;
@@ -1578,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);
@@ -1651,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;
@@ -1805,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;

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

@@ -25,6 +25,12 @@ 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` */

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,28 +137,61 @@ export const loadFaker = () =>
     },
   }))
 
-// `live` is the document's first server, or the address the person typed for it; the rest keep their own names
+// `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 baseUrl: Record<string, string> = {
-  ...(live ? { live } : {}),
-  ...Object.fromEntries(open.servers.filter((s) => s.name !== 'live').map((s) => [s.name, s.url])),
-}
-const described = Object.fromEntries(
-  open.servers.filter((s) => s.description).map((s) => [s.name, { description: s.description }]),
+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(described).length ? { environments: described } : {}),
+      ...(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,
+          // 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

@@ -113,8 +113,14 @@ async function open(id: number, source: Source, signal: AbortSignal): Promise<Op
     ]),
   )
   const sourceUrl = source.kind === 'url' ? source.url : undefined
-  const { auth, secrets, defaultProfile } = authFromSpec(doc, sourceUrl)
   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,
@@ -125,6 +131,8 @@ async function open(id: number, source: Source, signal: AbortSignal): Promise<Op
     auth,
     secrets,
     defaultProfile,
+    authVars,
+    authEnvironmentVars,
     baseUrl,
     servers,
     needsBaseUrl,

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<