@specbook/ui 0.3.0 → 0.5.0

package/dist-viewer/index.html

@@ -7,10 +7,10 @@
     <title>Specbook</title>
     <link rel="icon" href="./favicon.svg" type="image/svg+xml" />
     <link rel="apple-touch-icon" href="./apple-touch-icon.png" />
-    <script type="module" crossorigin src="./assets/index-BBlFcQUE.js"></script>
-    <link rel="modulepreload" crossorigin href="./assets/panel-9eYU7Gz6.js">
-    <link rel="modulepreload" crossorigin href="./assets/mount-DfwluJy4.js">
-    <link rel="stylesheet" crossorigin href="./assets/panel-hNOojwiM.css">
+    <script type="module" crossorigin src="./assets/index-BcHcUWbc.js"></script>
+    <link rel="modulepreload" crossorigin href="./assets/panel-nV09I7Wr.js">
+    <link rel="modulepreload" crossorigin href="./assets/mount-D3holu10.js">
+    <link rel="stylesheet" crossorigin href="./assets/panel-l1xvY4kI.css">
     <link rel="stylesheet" crossorigin href="./assets/index-Ds6DZpGP.css">
   </head>
   <body>

package/dist-viewer/specbook.js

@@ -1 +1 @@
-import{a as e,r as t,t as n}from"./assets/mount-DfwluJy4.js";function r(){let e=document.getElementById(`specbook-config`);if(e?.textContent)try{return JSON.parse(e.textContent)}catch{}let t=document.querySelector(`script[src$="specbook.js"][data-spec]`);return{spec:t?.dataset.spec,baseUrl:t?.dataset.baseUrl}}function i(e){let t=e?document.querySelector(e):document.getElementById(`app`);if(t)return t;let n=document.createElement(`div`);return n.id=`app`,document.body.append(n),n}var a=(e,t,n=!1)=>{e.textContent=t,e.style.cssText=`font:16px system-ui,sans-serif;padding:24px;color:${n?`#b42318`:`#5b6270`}`};async function o(){if(await e({stripWhenUnclaimed:!1}))return;let o=r(),s=i(o.target);if(!o.spec)return a(s,`Specbook: no spec was given (set "spec" in #specbook-config).`,!0);let c;try{c=new URL(o.spec,location.href).toString()}catch{return a(s,`Specbook: "${o.spec}" is not a valid address.`,!0)}a(s,`Loading the API…`);let l=new t;try{let e=await l.open({kind:`url`,url:c}).promise;s.textContent=``,s.removeAttribute(`style`),await n({result:e,worker:l,source:{kind:`url`,url:c},baseUrl:o.baseUrl,shareable:!1,setTitle:!1})}catch(e){a(s,`Specbook: ${e instanceof Error?e.message:String(e)}`,!0)}}o();
+import{a as e,r as t,t as n}from"./assets/mount-D3holu10.js";function r(){let e=document.getElementById(`specbook-config`);if(e?.textContent)try{return JSON.parse(e.textContent)}catch{}let t=document.querySelector(`script[src$="specbook.js"][data-spec]`);return{spec:t?.dataset.spec,baseUrl:t?.dataset.baseUrl,defaultEnv:t?.dataset.defaultEnv}}function i(e){let t=e?document.querySelector(e):document.getElementById(`app`);if(t)return t;let n=document.createElement(`div`);return n.id=`app`,document.body.append(n),n}var a=(e,t,n=!1)=>{e.textContent=t,e.style.cssText=`font:16px system-ui,sans-serif;padding:24px;color:${n?`#b42318`:`#5b6270`}`};async function o(){if(await e({stripWhenUnclaimed:!1}))return;let o=r(),s=i(o.target);if(!o.spec)return a(s,`Specbook: no spec was given (set "spec" in #specbook-config).`,!0);let c;try{c=new URL(o.spec,location.href).toString()}catch{return a(s,`Specbook: "${o.spec}" is not a valid address.`,!0)}a(s,`Loading the API…`);let l=new t;try{let e=await l.open({kind:`url`,url:c}).promise;s.textContent=``,s.removeAttribute(`style`),await n({result:e,worker:l,source:{kind:`url`,url:c},baseUrl:o.baseUrl,defaultEnv:typeof o.defaultEnv==`string`?o.defaultEnv:void 0,shareable:!1,setTitle:!1})}catch(e){a(s,`Specbook: ${e instanceof Error?e.message:String(e)}`,!0)}}o();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/ui",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The Specbook docs app, spec viewer and embeddable specbook.js.",
   "keywords": [
     "specbook",
@@ -29,14 +29,14 @@
   },
   "dependencies": {
     "@preact/signals": "2.11.3",
-    "@specbook/codegen": "0.3.0",
-    "@specbook/core": "0.3.0",
+    "@specbook/codegen": "0.5.0",
+    "@specbook/core": "0.5.0",
     "preact": "11.0.1",
     "prism-code-editor": "^5.4.0"
   },
   "devDependencies": {
     "@faker-js/faker": "9.3.0",
-    "@specbook/vite": "0.3.0",
+    "@specbook/vite": "0.5.0",
     "@vitest/browser-playwright": "5.0.3",
     "playwright": "1.64.0",
     "typescript": "7.0.2",

package/src/app.tsx

@@ -19,6 +19,7 @@ import {
   environmentNote,
   environmentRisk,
   environments,
+  fakerInUse,
   locale,
   newEnvironmentOpen,
   seed,
@@ -108,6 +109,8 @@ export function App() {
       .finally(loadRest)
     engine.environments(version.value).then((e) => {
       environments.value = e
+      const first = globalThis.__SPECBOOK_VIEWER__?.defaultEnv
+      if (first && e.includes(first)) env.value = first
     })
     engine.environmentRisks(version.value).then((r) => {
       environmentRisk.value = r
@@ -289,12 +292,17 @@ export function App() {
           {registry.loadFaker && (
             <span
               class="row muted"
-              title="Generated values such as {{faker.person.fullName}}: new on every run, or fixed so the same number always gives the same data"
+              title={
+                fakerInUse.value
+                  ? 'Generated values such as {{faker.person.fullName}}: new on every run, or fixed so the same number always gives the same data. `specbook test --seed` reproduces a run.'
+                  : 'Applies when the open request or flow uses {{faker.*}}'
+              }
             >
               <label class="row">
-                Synthetic data
+                Generated values
                 <select
-                  aria-label="Synthetic data"
+                  aria-label="Generated values"
+                  disabled={!fakerInUse.value}
                   value={seed.value === undefined ? 'random' : 'fixed'}
                   onChange={(e) => {
                     const fixed = (e.target as HTMLSelectElement).value === 'fixed'
@@ -311,6 +319,7 @@ export function App() {
                   class="seed-input"
                   aria-label="Seed number"
                   title="The same number gives the same data every run"
+                  disabled={!fakerInUse.value}
                   value={seed.value}
                   onInput={(e) => {
                     const n = (e.target as HTMLInputElement).valueAsNumber

package/src/branding.ts

@@ -87,7 +87,8 @@ export function applyBranding(
   }
   style.textContent = cfg ? brandCss(cfg) : ''
   const name = resolved.name ?? fallbackName
-  document.title = resolved.title ? `${name} · ${resolved.title}` : name
+  if (globalThis.__SPECBOOK_VIEWER__?.setTitle !== false)
+    document.title = resolved.title ? `${name} · ${resolved.title}` : name
   if (resolved.favicon || resolved.logo) {
     let link = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
     if (!link) {

package/src/engine.ts

@@ -26,6 +26,7 @@ import {
   runSequence,
   type Sequence,
   type SpecbookConfig,
+  setFaker,
   type Transport,
   usesFaker,
   withMock,
@@ -75,6 +76,8 @@ export interface Registry {
   loadConfig: (v: number) => Promise<{ default: any }>
   /** Project's @faker-js/faker (ESM), when installed. */
   loadFaker?: ((v: number) => Promise<Record<string, any>>) | null
+  /** Said when a run uses `{{faker.*}}` and there is no faker (the hosted viewer ships none). */
+  fakerUnavailable?: string
   mode?: 'dev' | 'static'
   /** variables from `.specbook/environments/<env>.env`, baked in at build time */
   environmentVars?: Record<string, Record<string, string>>
@@ -138,6 +141,20 @@ const text = (v: unknown) =>
   v !== null && typeof v === 'object' ? JSON.stringify(v) : String(v ?? '')
 
 export function createEngine(reg: Registry, opts: EngineOptions = {}) {
+  // no faker to load: a `{{faker.*}}` ends the run with the registry's message, not "install @faker-js/faker"
+  if (!reg.loadFaker && reg.fakerUnavailable) {
+    const message = reg.fakerUnavailable
+    setFaker(
+      new Proxy(
+        {},
+        {
+          get() {
+            throw new Error(message)
+          },
+        },
+      ),
+    )
+  }
   const mockLoader = {
     statuses: (service: string, opId: string) =>
       reg.manifests[service]?.operations.find((o) => o.id === opId)?.statuses ?? [],

package/src/panel/OperationDocs.tsx

@@ -60,7 +60,7 @@ function SavedRequestNote({ variant, html }: { variant: Variant; html?: string }
   return (
     <section class="saved-note-doc">
       <h2>
-        Saved request <code>{variant.name}</code>
+        Request <code>{variant.name}</code>
       </h2>
       <div class="doc-custom" dangerouslySetInnerHTML={{ __html: html }} />
     </section>

package/src/panel/RequestPanel.tsx

@@ -1,4 +1,10 @@
-import { collectPlaceholders, type Encoding, type Example, type RunResult } from '@specbook/core'
+import {
+  collectPlaceholders,
+  type Encoding,
+  type Example,
+  type RunResult,
+  rootName,
+} from '@specbook/core'
 import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
 import { EnvBadge } from '../components/EnvBadge'
 import type { Variant } from '../engine'
@@ -7,7 +13,16 @@ import { engine, isStatic, registry, saveFile } from '../runtime'
 import { type Defs, type JsonSchema, propsOf, unwrap } from '../schema'
 import { statusClass, statusName } from '../status'
 import { kv } from '../storage'
-import { env, envSettingsOpen, envVarsVersion, features, locale, seed, version } from '../store'
+import {
+  env,
+  envSettingsOpen,
+  envVarsVersion,
+  fakerInUse,
+  features,
+  locale,
+  seed,
+  version,
+} from '../store'
 import { announcement, describeRun } from './announce'
 import { Body } from './Body'
 import { DraftCodeSample } from './CodeSample'
@@ -235,13 +250,36 @@ export function RequestPanel({ service, op, variants, initial, autoRun }: Props)
         .filter(
           (n) => !n.startsWith('faker.') && !n.startsWith('secrets.') && !n.startsWith('session.'),
         )
-        .map((n) => n.split('.')[0] as string)
+        .map(rootName)
         .filter((n, i, a) => a.indexOf(n) === i)
     } catch {
       return []
     }
   }, [draft, encoding])
 
+  // the header's Generated values control applies while this request can use faker: a `{{faker.*}}` in what is
+  // typed, or an `init`/`data` function in a saved request
+  const usesFakerNow = useMemo(() => {
+    const input = saved?.def.input
+    if (Object.values(input?.init ?? {}).some((v) => typeof v === 'function')) return true
+    if (typeof input?.data === 'function') return true
+    if (!draft) return false
+    try {
+      const parts = requestParts(draft, encoding)
+      return [
+        ...collectPlaceholders([parts.path, parts.query, parts.headers, parts.data, vars]),
+      ].some((n) => n.startsWith('faker.'))
+    } catch {
+      return false
+    }
+  }, [saved, draft, encoding, vars])
+  useEffect(() => {
+    fakerInUse.value = usesFakerNow
+    return () => {
+      fakerInUse.value = false
+    }
+  }, [usesFakerNow])
+
   // placeholders nothing supplies: not in config or the environment's files. They stay listed while
   // you type, so the field you are filling does not disappear under you.
   // a saved request brings the values of its own `init`: they are what a run uses, so nothing is missing
@@ -435,7 +473,7 @@ export function RequestPanel({ service, op, variants, initial, autoRun }: Props)
                   </option>
                 ))}
                 {variants.map((v) => (
-                  <option value={`saved:${v.file}`}>{v.name} · saved request</option>
+                  <option value={`saved:${v.file}`}>{v.name} · request</option>
                 ))}
               </select>
             </label>
@@ -520,7 +558,9 @@ export function RequestPanel({ service, op, variants, initial, autoRun }: Props)
 
         {saved && (
           <p class="muted lock">
-            A saved request: its own values, checks and mock hook apply, and it is read-only here.
+            A request from your project: it runs with its own values and checks. Edit its file to
+            change it.
+            {env.value === 'mock' && saved.def.mockHook ? ' Its mock hook shapes the answer.' : ''}
           </p>
         )}
 

package/src/panel/SequencePanel.tsx

@@ -4,7 +4,7 @@ import { EnvBadge } from '../components/EnvBadge'
 import { defaultFor, type FieldSpec, specFromControl } from '../components/Fields'
 import type { SequenceInfo } from '../engine'
 import { engine } from '../runtime'
-import { env, locale, seed, version } from '../store'
+import { env, fakerInUse, locale, seed, version } from '../store'
 import { announcement, describeRun } from './announce'
 import { Failure } from './Checks'
 import { ControlsGrid } from './ControlsGrid'
@@ -80,6 +80,13 @@ export function SequencePanel({
   // a flow with inputs can run on their defaults alone, as `specbook test` does
   const hasInputs = Object.keys(specs).length > 0 || seq.nodes.some((n) => n.kind === 'input')
 
+  useEffect(() => {
+    fakerInUse.value = hasGenerated
+    return () => {
+      fakerInUse.value = false
+    }
+  }, [hasGenerated])
+
   /** Every input at its default; a generated one needs faker, which is made ready first. */
   const freshInputs = async () => {
     if (hasGenerated)

package/src/store.ts

@@ -10,6 +10,8 @@ export const environmentRisk = signal<Record<string, 'production' | 'sandbox'>>(
 export const environmentNote = signal<Record<string, string>>({})
 export const locale = signal<string | undefined>(undefined)
 export const seed = signal<number | undefined>(undefined)
+/** Whether the request or flow that is open can use generated values; the header's control is enabled while it is. */
+export const fakerInUse = signal(false)
 /** Bumped when an environment's variables change, so what is derived from them (addresses, origins) is redone. */
 export const envVarsVersion = signal(0)
 /** Whether Environment settings is open; set from elsewhere to point a person at it. */

package/src/styles/app.css

@@ -684,6 +684,19 @@
       text-overflow: ellipsis;
       white-space: nowrap;
     }
+    /* room for it: a name of ordinary length stays whole and the search field gives way instead, while a
+       longer one still ends in an ellipsis. Narrower than this only the logo is left. */
+    @media (min-width: 360px) {
+      .brand {
+        flex: 0 0 auto;
+      }
+      .brand-name {
+        max-width: 9ch;
+      }
+      .header .palette-btn {
+        min-width: 64px;
+      }
+    }
     .palette-btn {
       flex: 1;
       min-width: 0;
@@ -736,7 +749,7 @@
       width: 56%;
       min-width: 0;
     }
-    /* Synthetic data is a row inside a row (its label and, once fixed, a seed field): the inner one fills it */
+    /* Generated values is a row inside a row (its label and, once fixed, a seed field): the inner one fills it */
     .header-controls .row > .row {
       flex: 1 1 100%;
     }

package/src/styles/panel.css

@@ -1971,12 +1971,10 @@
     .panel-head .spacer {
       display: none;
     }
-    .panel-head label.row > .muted {
+    /* the Environment badge in the panel is the one switch on a phone: a bare, unlabeled copy here only confuses */
+    .panel-head label.row {
       display: none;
     }
-    .panel-head select {
-      max-width: 34%;
-    }
     .stepper {
       gap: 0;
     }

package/src/viewer/embed.ts

@@ -7,7 +7,8 @@
  *   <script type="module" src="https://ui.specbook.dev/v1/specbook.js"></script>
  *
  * 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.
+ * `baseUrl` gives the API address when the document has none, `target` names another container, and
+ * `defaultEnv` (`"live"` or the name of a server) picks the environment shown first instead of `mock`.
  */
 import { handleOAuthCallback } from '../oauth-callback'
 import { SpecWorker } from './client'
@@ -17,6 +18,7 @@ interface EmbedConfig {
   spec?: string
   baseUrl?: string
   target?: string
+  defaultEnv?: string
 }
 
 function readConfig(): EmbedConfig {
@@ -29,7 +31,11 @@ function readConfig(): EmbedConfig {
     }
   }
   const script = document.querySelector<HTMLScriptElement>('script[src$="specbook.js"][data-spec]')
-  return { spec: script?.dataset.spec, baseUrl: script?.dataset.baseUrl }
+  return {
+    spec: script?.dataset.spec,
+    baseUrl: script?.dataset.baseUrl,
+    defaultEnv: script?.dataset.defaultEnv,
+  }
 }
 
 function container(sel?: string): HTMLElement {
@@ -72,6 +78,7 @@ async function start() {
       worker,
       source: { kind: 'url', url },
       baseUrl: cfg.baseUrl,
+      defaultEnv: typeof cfg.defaultEnv === 'string' ? cfg.defaultEnv : undefined,
       shareable: false,
       setTitle: false,
     })

package/src/viewer/mount.ts

@@ -12,6 +12,7 @@ export async function mountOpened(o: {
   worker: SpecWorker
   source: Source
   baseUrl?: string
+  defaultEnv?: string
   shareable?: boolean
   setTitle?: boolean
 }): Promise<void> {
@@ -19,6 +20,8 @@ export async function mountOpened(o: {
   const g: ViewerGlobal = {
     open: o.result,
     baseUrl: o.baseUrl,
+    defaultEnv: o.defaultEnv,
+    setTitle: o.setTitle,
     source:
       o.shareable === false
         ? undefined
@@ -31,22 +34,4 @@ export async function mountOpened(o: {
   globalThis.__SPECBOOK_VIEWER__ = g
   if (o.setTitle !== false) document.title = `${o.result.title} · Specbook`
   await import('../main')
-  warmFaker()
-}
-
-/**
- * Mock responses are generated with the spec, so the first mock request needs no faker. Faker (a
- * sizeable chunk) is only used by "Dynamic" examples and `{{faker.*}}` values, so it is fetched when the
- * page has been idle for a moment instead of up front: by the time someone picks Dynamic it is cached.
- */
-function warmFaker() {
-  if ((navigator as Navigator & { connection?: { saveData?: boolean } }).connection?.saveData)
-    return
-  const idle: (f: () => void) => void =
-    (window as unknown as { requestIdleCallback?: (f: () => void) => void }).requestIdleCallback ??
-    ((f) => setTimeout(f, 1500))
-  idle(() => {
-    // the registry's loader is the same import the run would make
-    void import('./registry').then((r) => r.loadFaker()).catch(() => {})
-  })
 }

package/src/viewer/registry.ts

@@ -12,6 +12,10 @@ export interface ViewerGlobal {
   definitions(): Promise<Record<string, any>>
   /** the base URL the person gave, when the document has none of its own */
   baseUrl?: string
+  /** the environment to show first, when it is one the document offers (otherwise `mock`) */
+  defaultEnv?: string
+  /** false on a page that is not the viewer's own (an embed), where the host's title stays */
+  setTitle?: boolean
   /** where the document came from, which decides whether a link to this view can be shared */
   source?: import('./share').ViewerSource
 }
@@ -124,18 +128,12 @@ export const operations = Object.fromEntries(
 ) as Record<string, () => Promise<Record<string, any>>>
 
 /**
- * Faker, English only: a locale is its own chunk in a project build, but a viewer opening a stranger's
- * spec has no reason to ship the others. Loaded only when a run uses `{{faker.*}}`.
+ * The hosted viewer and the embed ship no faker: a spec's mock and example values come from the generator, and a
+ * `{{faker.*}}` someone types is refused with this message instead of being sent as it is.
  */
-export const loadFaker = () =>
-  import('./faker-en').then((m) => ({
-    Faker: m.Faker,
-    // a run asks for its locale and `base`, the fallback every locale chain ends in
-    locales: {
-      en: () => Promise.resolve(m.en),
-      base: () => Promise.resolve(m.base),
-    },
-  }))
+export const loadFaker = null
+export const fakerUnavailable =
+  'Generated values ({{faker.…}}) work in a Specbook project, not in the hosted viewer. Type a value instead.'
 
 // `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.
@@ -185,8 +183,6 @@ export const loadConfig = () =>
       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: '',