blume 1.5.0 → 1.5.2

package/src/components/layout/nav-utils.ts

@@ -1,3 +1,4 @@
+import { isRootTab, isUnderPath } from "../../core/navigation.ts";
 import type { NavNode, NavTab } from "../../core/types.ts";
 
 /** A flat, ordered page reference used for previous/next pagination. */
@@ -71,14 +72,6 @@ export const findBreadcrumbs = (nodes: NavNode[], route: string): Crumb[] => {
   return search(nodes, []) ?? [];
 };
 
-/**
- * Whether `route` is the section root `base` or nested beneath it. Requires a
- * path boundary, so `/api-reference` is not under `/api`. The root `/` spans
- * every route.
- */
-export const isUnderPath = (route: string, base: string): boolean =>
-  base === "/" || route === base || route.startsWith(`${base}/`);
-
 /**
  * The tab whose `path` is the longest prefix of `route`. The root tab (`/`)
  * acts as the fallback when no more specific tab matches.
@@ -99,6 +92,28 @@ export const activeTabForRoute = (
   return match;
 };
 
+/**
+ * The tab to mark as the current one (`aria-current`) for `route`. Same
+ * longest-prefix match as {@link activeTabForRoute}, except inside an archived
+ * version tree: the root tab claims every archived route through its
+ * spans-everything fallback while its link points back at the current docs, so
+ * no tab is genuinely current there.
+ */
+export const currentTabForRoute = (
+  tabs: NavTab[],
+  route: string,
+  root = "/"
+): NavTab | null => {
+  const tab = activeTabForRoute(tabs, route);
+  // The root tab sitting away from the tree root means the tree is a version
+  // snapshot in a different path space — the tab matched as a fallback, not
+  // because it owns the route.
+  if (tab && isRootTab(tab, root) && tab.path !== root) {
+    return null;
+  }
+  return tab;
+};
+
 /**
  * The children of the group whose path is `base`, searched at any depth — so a
  * content tree wrapped in a top-level container group still resolves to the
@@ -144,7 +159,7 @@ const withoutTabSections = (
 ): NavNode[] => {
   const tabPaths = new Set<string>();
   for (const tab of tabs) {
-    if (tab.path !== root) {
+    if (!isRootTab(tab, root)) {
       tabPaths.add(tab.path);
     }
   }
@@ -181,11 +196,15 @@ const withoutTabSections = (
  * the root tab), the tab-owned groups are hidden so the root sidebar shows
  * only pages that don't belong to a tab.
  *
- * `root` is the tree root in the tabs' own path space (`Navigation.root`) —
- * tab paths arrive localized and based, so under i18n or a `basePath` the root
- * tab is `/en` or `/docs`, not `/`. Comparing against `/` would misread it as
- * a section tab: a root-level `(group)` folder's path is exactly that prefix,
- * so the sidebar collapsed to that one group (or blanked entirely).
+ * `root` is the tree root (`Navigation.root`), localized and based like tab
+ * paths — under i18n or a `basePath` the root tab sits at `/en` or `/docs`,
+ * not `/`, and a bare-`/` comparison would misread it as a section tab (a
+ * root-level `(group)` folder's path is exactly that prefix, so the sidebar
+ * collapsed to that one group or blanked entirely). In an archived version
+ * tree the root is versionized (`/v1.0`) while tab paths stay in current-docs
+ * space, so root-tab checks use {@link isRootTab} containment, not equality:
+ * the root tab owns no group in a snapshot, and misreading it as a section
+ * tab blanked the archived sidebar.
  *
  * When a matched tab owns no sidebar group — a standalone page like the
  * generated changelog timeline (`/changelog`), or a tab whose source produced
@@ -201,7 +220,7 @@ export const sidebarForRoute = (
   root = "/"
 ): NavNode[] => {
   const tab = activeTabForRoute(tabs, route);
-  if (tab && tab.path !== root) {
+  if (tab && !isRootTab(tab, root)) {
     return sectionChildren(sidebar, tab.path) ?? [];
   }
   const scoped = withoutTabSections(sidebar, tabs, root);

package/src/components/layout/search/orama.ts

@@ -11,8 +11,9 @@ import type { IndexedDocument, SearchFn } from "./types.ts";
  * available in both dev and the production build. A generous match pool is
  * pulled so the section pills can count across the whole result set before the
  * active filter and display limit are applied. `locale` is the site's
- * `i18n.defaultLocale`, baked into the generated client so unspaced scripts
- * (Japanese, Chinese, Korean, Thai) get a word-segmenting tokenizer.
+ * `i18n.defaultLocale`, baked into the generated client so non-Latin scripts
+ * (Japanese and Chinese, but equally Cyrillic, Greek, Hebrew, Devanagari…)
+ * get a word-segmenting tokenizer.
  */
 export const createSearch = async (opts: {
   indexUrl: string;

package/src/components/openapi/AsyncApiOperation.astro

@@ -18,6 +18,9 @@ import {
 } from "./async.ts";
 import type { MessageSample } from "./async-snippets.ts";
 import { asyncSampleLanguages } from "./async-snippets.ts";
+import { buildMessage, defaultMessageValues } from "./message.ts";
+import { messageModel } from "./message-model.ts";
+import MessageComposer from "./MessageComposer.astro";
 import Authorization from "./Authorization.astro";
 import Bindings from "./Bindings.astro";
 import { exampleValue, type SchemaLike, toJson } from "./helpers.ts";
@@ -86,13 +89,21 @@ const messagePanels = await Promise.all(
   })
 );
 
-const sample: MessageSample | null = ref
-  ? {
+// One derived model feeds the static default sample, the composer form, and
+// (client-side) the live samples + WebSocket frame — they can never drift.
+const model = ref
+  ? messageModel({
       action: ref.method === "send" ? "send" : "receive",
       address: ref.path,
-      payload: messages.length > 0 ? exampleOf(messages[0].message) : undefined,
-      server: servers[0],
-    }
+      messages,
+      parameters,
+      protocol,
+      schemas,
+      servers,
+    })
+  : null;
+const sample: MessageSample | null = model
+  ? buildMessage(model, defaultMessageValues(model))
   : null;
 const languages = asyncSampleLanguages(spec?.codeSamples ?? [], protocol);
 const samplePanels = sample
@@ -104,6 +115,7 @@ const samplePanels = sample
         }),
         key: language.id,
         label: language.label,
+        lang: language.id,
       }))
     )
   : [];
@@ -223,8 +235,11 @@ const channelBindings = bindingGroups(channel?.bindings);
             title="Channel bindings"
           />
         </div>
-        {(samplePanels.length > 0 || messagePanels.length > 0) && (
-          <div class="xl:sticky xl:top-24 xl:self-start">
+        {(spec.playground.enabled ||
+          samplePanels.length > 0 ||
+          messagePanels.length > 0) && (
+          <div class="xl:sticky xl:top-24 xl:self-start" data-operation-panel>
+            {spec.playground.enabled && model && <MessageComposer model={model} />}
             <div class="not-prose flex flex-col gap-6">
               <PanelTabs copy heading="Example" panels={samplePanels} />
               <PanelTabs heading="Message" panels={messagePanels} />

package/src/components/openapi/MessageComposer.astro

@@ -0,0 +1,238 @@
+---
+import { randomUUID } from "node:crypto";
+
+import type { MessageModel } from "./message.ts";
+
+/**
+ * The interactive "Try it" panel for one event operation. Server-rendered as a
+ * native collapsed `<details>` with plain labelled controls — keyboard
+ * operable with zero JS — and the client module loads only when the reader
+ * first opens it (loader script at the foot of this file). The message model
+ * rides along as JSON so the lazy chunk needs no data fetch.
+ *
+ * Composing and copying a sample works on every protocol; a live connection is
+ * offered only where a browser can actually make one (WebSocket bindings), and
+ * the panel says so plainly rather than presenting a dead button.
+ */
+
+interface Props {
+  model: MessageModel;
+}
+
+const { model } = Astro.props;
+
+// `</script>`-proof embedding: `<` only ever occurs inside JSON strings, where
+// the \u escape is equivalent, so a spec description can never close the model
+// script early and inject markup.
+const modelJson = JSON.stringify(model).replaceAll("<", "\\u003c");
+
+// Unique per rendered composer (a page can hold several), so the textarea's
+// aria-describedby can point at ITS error container and no other.
+const payloadErrorsId = `blume-payload-errors-${randomUUID()}`;
+
+const LABEL_ROW =
+  "mb-1 flex flex-wrap items-baseline gap-x-1.5 font-medium text-foreground text-xs";
+const FIELD =
+  "w-full rounded border border-border bg-background px-2 py-1.5 font-mono text-foreground text-xs";
+const HINT = "mt-1 block text-muted-foreground text-xs";
+const GROUP = "flex flex-col gap-3";
+const GROUP_HEADING =
+  "font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide";
+const BUTTON =
+  "cursor-pointer rounded-blume bg-accent px-4 py-2 font-medium text-accent-foreground text-sm transition hover:bg-accent/90 disabled:cursor-not-allowed disabled:opacity-50";
+const BUTTON_QUIET =
+  "cursor-pointer rounded-blume border border-border px-4 py-2 font-medium text-foreground text-sm transition hover:bg-muted disabled:cursor-not-allowed disabled:opacity-50";
+---
+
+<blume-message-composer class="mb-6 block">
+  <script
+    data-composer-model
+    is:inline
+    set:html={modelJson}
+    type="application/json"
+  />
+  <details
+    class="not-prose rounded-blume border border-border bg-background"
+    data-composer
+  >
+    <summary class="cursor-pointer px-4 py-3 font-semibold text-foreground text-sm">
+      Try it
+    </summary>
+    <div class="flex flex-col gap-5 border-border border-t px-4 py-4">
+      <div class={GROUP}>
+        <div class={GROUP_HEADING}>Server</div>
+        {
+          model.servers.length > 0 && (
+            <label class="block">
+              <span class={LABEL_ROW}>Server</span>
+              <select class={FIELD} data-server>
+                {model.servers.map((option, index) => (
+                  <option value={String(index)}>{option.label}</option>
+                ))}
+              </select>
+            </label>
+          )
+        }
+        <label class="block">
+          <span class={LABEL_ROW}>Custom server URL</span>
+          <input
+            class={FIELD}
+            data-server-custom
+            placeholder="wss://events.example.com"
+            type="text"
+          />
+          <span class={HINT}>
+            Overrides the selected server; the channel address is appended.
+          </span>
+        </label>
+      </div>
+      {
+        model.params.length > 0 && (
+          <div class={GROUP}>
+            <div class={GROUP_HEADING}>Channel parameters</div>
+            {model.params.map((param) => (
+              <label class="block">
+                <span class={LABEL_ROW}>
+                  <code class="font-mono">{param.name}</code>
+                  <span class="text-red-600 dark:text-red-400" title="required">
+                    *
+                  </span>
+                </span>
+                {param.enum ? (
+                  <select
+                    class={FIELD}
+                    data-param={param.name}
+                    title={param.description}
+                  >
+                    {param.enum.map((value) => (
+                      <option selected={value === param.value} value={value}>
+                        {value}
+                      </option>
+                    ))}
+                  </select>
+                ) : (
+                  <input
+                    class={FIELD}
+                    data-param={param.name}
+                    placeholder="string"
+                    title={param.description}
+                    type="text"
+                    value={param.value}
+                  />
+                )}
+                {param.description && (
+                  <span class={HINT} set:text={param.description} />
+                )}
+              </label>
+            ))}
+          </div>
+        )
+      }
+      <div class={GROUP}>
+        <div class={GROUP_HEADING}>
+          Payload
+          {
+            model.payload.contentType && (
+              <span class="ml-1.5 font-mono normal-case">
+                {model.payload.contentType}
+              </span>
+            )
+          }
+        </div>
+        <label class="block">
+          <span class={LABEL_ROW}>Message payload</span>
+          <textarea
+            aria-describedby={payloadErrorsId}
+            class={FIELD}
+            data-payload
+            rows="8"
+            spellcheck="false">{model.payload.example}</textarea
+          >
+        </label>
+        <div
+          aria-live="polite"
+          class="mt-1 flex flex-col gap-0.5 empty:hidden"
+          data-payload-errors
+          id={payloadErrorsId}
+        />
+      </div>
+      {
+        model.connectable ? (
+          <div class={GROUP}>
+            <div class={GROUP_HEADING}>Connection</div>
+            <div class="flex flex-wrap items-center gap-2">
+              <button class={BUTTON} data-connect type="button">
+                Connect
+              </button>
+              <button class={BUTTON_QUIET} data-disconnect disabled type="button">
+                Disconnect
+              </button>
+              {/* AsyncAPI 3 states the action from the API's side: a
+                  `receive` operation is the one a reader publishes to, while a
+                  `send` operation only streams frames at them. */}
+              {model.action === "receive" && (
+                <button class={BUTTON} data-send disabled type="button">
+                  Send
+                </button>
+              )}
+            </div>
+            <div
+              aria-live="polite"
+              class="text-muted-foreground text-xs"
+              data-status
+            >
+              {model.action === "send"
+                ? "Not connected. Connect to stream messages as they arrive."
+                : "Not connected."}
+            </div>
+            <div
+              aria-live="polite"
+              class="flex flex-col gap-1 empty:hidden"
+              data-log
+            />
+          </div>
+        ) : (
+          <p class="text-muted-foreground text-xs">
+            {model.protocol
+              ? `Live sending isn't possible for ${model.protocol} from a browser tab — copy the sample above and run it against your broker.`
+              : "Live sending needs a WebSocket binding — copy the sample above and run it against your broker."}
+          </p>
+        )
+      }
+    </div>
+  </details>
+</blume-message-composer>
+
+<script>
+  // Hydration waits for intent: a collapsed <details> can only fire its first
+  // `toggle` by opening, so the one-shot listener imports the client module —
+  // a separate chunk readers who never compose a message never download — and
+  // wires the form. The custom element lives here, not in the client module,
+  // so that module stays import-safe under the test runner.
+  class BlumeMessageComposer extends HTMLElement {
+    connectedCallback() {
+      const details = this.querySelector<HTMLDetailsElement>(
+        "details[data-composer]"
+      );
+      if (!details) {
+        return;
+      }
+      const init = async () => {
+        const { initComposer } = await import("./message-composer.ts");
+        initComposer(this);
+      };
+      // A re-attached element (bfcache restore, DOM moves) can arrive with the
+      // panel already open — its first toggle has fired, so a listener alone
+      // would leave a visible form dead.
+      if (details.open) {
+        void init();
+        return;
+      }
+      details.addEventListener("toggle", init, { once: true });
+    }
+  }
+
+  if (!customElements.get("blume-message-composer")) {
+    customElements.define("blume-message-composer", BlumeMessageComposer);
+  }
+</script>

package/src/components/openapi/Operation.astro

@@ -6,18 +6,20 @@ import {
   resolveComponentRef,
   type SchemaLike,
 } from "./helpers.ts";
+import { operationModel } from "./operation-model.ts";
+import { buildRequest, defaultValues } from "./request.ts";
 import {
   effectiveSecurity,
   resolveSecurity,
-  sampleAuth,
   type SecurityRequirementLike,
   type SecuritySchemeLike,
 } from "./security.ts";
-import { buildRequestSample, sampleLanguages } from "./snippets.ts";
+import { sampleLanguages } from "./snippets.ts";
 import AsyncApiOperation from "./AsyncApiOperation.astro";
 import Authorization from "./Authorization.astro";
 import MethodBadge from "./MethodBadge.astro";
 import ParametersTable from "./ParametersTable.astro";
+import Playground from "./Playground.astro";
 import RequestBody from "./RequestBody.astro";
 import RequestPanel from "./RequestPanel.astro";
 import Responses from "./Responses.astro";
@@ -104,17 +106,21 @@ const security = resolveSecurity(
   doc.components?.securitySchemes
 );
 
-const sample =
+// One derived model feeds the static default sample, the playground form,
+// and (client-side) the live samples + fetch — they can never drift apart.
+const model =
   ref && operation
-    ? buildRequestSample(
-        { parameters: params, requestBody },
-        ref.method,
-        ref.path,
-        doc.servers ?? [],
+    ? operationModel({
+        method: ref.method,
+        parameters: params,
+        path: ref.path,
+        requestBody,
         schemas,
-        sampleAuth(security)
-      )
+        security,
+        servers: doc.servers ?? [],
+      })
     : null;
+const sample = model ? buildRequest(model, defaultValues(model)) : null;
 const languages = sampleLanguages(spec?.codeSamples ?? []);
 ---
 {
@@ -154,8 +160,16 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
             />
           )}
         </div>
-        {sample && (
-          <div class="xl:sticky xl:top-24 xl:self-start">
+        {sample && model && (
+          <div class="xl:sticky xl:top-24 xl:self-start" data-operation-panel>
+            {spec.playground.enabled && (
+              <Playground
+                model={model}
+                operation={id}
+                proxy={spec.playground.proxy}
+                slug={spec.slug}
+              />
+            )}
             <RequestPanel
               languages={languages}
               responses={responses}

package/src/components/openapi/PanelTabs.astro

@@ -13,6 +13,12 @@ interface Panel {
   html?: string | null;
   /** Plain-text fallback when there is nothing to highlight. */
   text?: string;
+  /**
+   * Code-sample language id for a request-sample panel. Tags the panel with
+   * `data-sample-lang` so the playground client can re-render it live; panels
+   * that aren't samples leave it off.
+   */
+  lang?: string;
 }
 
 interface Props {
@@ -88,6 +94,7 @@ const TAB_CLASS =
             aria-labelledby={idFor("tab", panel.key)}
             class:list={[index === 0 ? "" : "hidden"]}
             data-panel={panel.key}
+            data-sample-lang={panel.lang}
             id={idFor("panel", panel.key)}
             role="tabpanel"
           >