blume 1.0.4 → 1.1.1

package/src/components/content/Tabs.astro

@@ -4,6 +4,20 @@ interface Props {
   defaultTabIndex?: number;
   dropdown?: boolean;
   hash?: boolean | "false" | "true";
+  /**
+   * Render borderless — a tab strip on a full-width rule with the content
+   * flowing beneath as prose — instead of the default bordered box. Reads as
+   * page-level navigation rather than an isolated widget; pair with `param` for
+   * shareable, multiple-per-page tabs.
+   */
+  inline?: boolean;
+  /**
+   * Sync the active tab to this URL query-param key instead of the hash. Each
+   * group owns its own param, so several `Tabs` can share a page and every
+   * selection is deep-linkable (`?install=windows`). Give each group a unique
+   * `param`; it takes precedence over `hash`.
+   */
+  param?: string;
   sync?: boolean;
 }
 
@@ -12,34 +26,53 @@ const {
   defaultTabIndex = 0,
   dropdown = false,
   hash = true,
+  inline = false,
+  param,
   sync = true,
 } = Astro.props;
 
 // MDX string attributes (`hash="false"` from generated markup) must read as
 // their boolean meaning — the string "false" is truthy.
 const hashEnabled = String(hash) !== "false";
+// The dropdown (select) affordance belongs to the boxed layout; inline always
+// renders a tab strip.
+const useDropdown = dropdown && !inline;
 ---
 
 <blume-tabs
-  class="not-prose my-6 block overflow-hidden rounded-blume border border-border bg-background"
+  class:list={[
+    "my-6 block",
+    inline
+      ? ""
+      : "not-prose overflow-hidden rounded-blume border border-border bg-background",
+  ]}
   data-border-bottom={borderBottom ? "true" : "false"}
   data-default-tab-index={defaultTabIndex}
-  data-dropdown={dropdown ? "true" : "false"}
+  data-dropdown={useDropdown ? "true" : "false"}
   data-hash={hashEnabled ? "true" : "false"}
+  data-param={param}
   data-sync={sync ? "true" : "false"}
 >
-  <div class:list={[dropdown ? "" : "overflow-x-auto"]}>
+  <div
+    class:list={[
+      inline ? "not-prose" : "",
+      useDropdown ? "" : "overflow-x-auto",
+    ]}
+  >
     <div
       class:list={[
-        dropdown || borderBottom ? "border-border border-b" : "",
-        dropdown ? "p-3" : "flex gap-4 px-3",
+        useDropdown || borderBottom ? "border-border border-b" : "",
+        useDropdown ? "p-3" : inline ? "flex gap-4" : "flex gap-4 px-3",
       ]}
       data-blume-tablist
-      role={dropdown ? undefined : "tablist"}
+      role={useDropdown ? undefined : "tablist"}
     >
     </div>
   </div>
-  <div data-blume-tab-content>
+  <div
+    class:list={[inline ? "pt-4 [&>[data-blume-tab-panel]]:p-0!" : ""]}
+    data-blume-tab-content
+  >
     <slot />
   </div>
 </blume-tabs>
@@ -114,7 +147,7 @@ const hashEnabled = String(hash) !== "false";
         if (this.#syncEnabled()) {
           document.addEventListener(SYNC_EVENT, this.#sync);
         }
-        window.addEventListener("hashchange", this.#hashChange);
+        this.#addUrlListener();
         return;
       }
       this.dataset.blumeTabsReady = "true";
@@ -173,12 +206,13 @@ const hashEnabled = String(hash) !== "false";
       if (this.#syncEnabled()) {
         document.addEventListener(SYNC_EVENT, this.#sync);
       }
-      window.addEventListener("hashchange", this.#hashChange);
+      this.#addUrlListener();
     }
 
     disconnectedCallback() {
       document.removeEventListener(SYNC_EVENT, this.#sync);
-      window.removeEventListener("hashchange", this.#hashChange);
+      window.removeEventListener("hashchange", this.#urlChange);
+      window.removeEventListener("popstate", this.#urlChange);
     }
 
     activate(index: number, sync: boolean, updateHash: boolean) {
@@ -201,8 +235,18 @@ const hashEnabled = String(hash) !== "false";
         this.#select.value = String(index);
       }
       const id = panelId(activePanel);
-      if (updateHash && id && this.#hashEnabled()) {
-        history.replaceState(null, "", `#${encodeURIComponent(id)}`);
+      if (updateHash && id) {
+        const param = this.#paramName();
+        if (param) {
+          // Query-param mode: write only this group's key, so several groups on
+          // one page each deep-link independently. replaceState (not push) keeps
+          // the shareable URL current without stacking a history entry per click.
+          const url = new URL(window.location.href);
+          url.searchParams.set(param, id);
+          history.replaceState(history.state, "", url);
+        } else if (this.#hashEnabled()) {
+          history.replaceState(null, "", `#${encodeURIComponent(id)}`);
+        }
       }
       if (sync && this.#syncEnabled()) {
         document.dispatchEvent(
@@ -239,8 +283,29 @@ const hashEnabled = String(hash) !== "false";
       return true;
     }
 
+    #activateByParam() {
+      const param = this.#paramName();
+      if (!param) {
+        return false;
+      }
+      const value = new URL(window.location.href).searchParams.get(param);
+      if (!value) {
+        return false;
+      }
+      const index = this.#panels.findIndex((panel) => panelId(panel) === value);
+      if (index === -1) {
+        return false;
+      }
+
+      this.activate(index, false, false);
+      return true;
+    }
+
     #initialIndex() {
-      if (this.#activateByHash()) {
+      const activated = this.#paramName()
+        ? this.#activateByParam()
+        : this.#activateByHash();
+      if (activated) {
         return this.#panels.findIndex((panel) => !panel.classList.contains("hidden"));
       }
       return boundedIndex(
@@ -278,6 +343,20 @@ const hashEnabled = String(hash) !== "false";
       return this.dataset.hash !== "false";
     }
 
+    #paramName() {
+      return this.dataset.param || null;
+    }
+
+    // Query-param changes don't fire `hashchange`; they surface through history
+    // navigation (`popstate`). Listen to whichever channel this group syncs on.
+    #addUrlListener() {
+      if (this.#paramName()) {
+        window.addEventListener("popstate", this.#urlChange);
+      } else {
+        window.addEventListener("hashchange", this.#urlChange);
+      }
+    }
+
     #sync = (event: Event) => {
       const title = (event as CustomEvent<{ title?: string }>).detail?.title;
       if (title) {
@@ -285,8 +364,12 @@ const hashEnabled = String(hash) !== "false";
       }
     };
 
-    #hashChange = () => {
-      this.#activateByHash();
+    #urlChange = () => {
+      if (this.#paramName()) {
+        this.#activateByParam();
+      } else {
+        this.#activateByHash();
+      }
     };
   }
 

package/src/components/layout/Breadcrumbs.astro

@@ -31,7 +31,7 @@ const eyebrowCrumb = crumbs.length > 1 ? crumbs[crumbs.length - 2] : null;
       aria-label={n.breadcrumb}
       class:list={[
         "mb-2 text-muted-foreground text-sm",
-        wide ? "max-w-none" : "mx-auto max-w-[42rem]",
+        wide ? "max-w-none" : "mx-auto max-w-content",
       ]}
     >
       {eyebrowCrumb.route ? (

package/src/components/layout/Header.astro

@@ -182,6 +182,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
         askEnabled={askEnabled}
         locale={searchLocale}
         navigation={navigation}
+        popularPages={data.config.search.popular}
         strings={searchStrings}
       />
     )

package/src/components/layout/PageFeedback.astro

@@ -20,7 +20,7 @@ const buttonClass =
 
 <section
   aria-label={f.question}
-  class="mx-auto mt-12 flex max-w-[42rem] items-center justify-between gap-4 border-border border-t pt-6"
+  class="mx-auto mt-12 flex max-w-content items-center justify-between gap-4 border-border border-t pt-6"
   data-blume-page-feedback
 >
   <p class="text-muted-foreground text-sm">{f.question}</p>

package/src/components/layout/PageLayout.astro

@@ -186,7 +186,11 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     <title>{pageTitle}</title>
     <Favicon appleIcon={appleIcon} favicon={favicon} />
     <Fonts cssVars={fontCssVars ?? []} />
-    {resolvedCanonical && <link href={resolvedCanonical} rel="canonical" />}
+    {/* Google warns against pairing a canonical with noindex — the canonical
+        says "index that URL", the robots meta says "distrust this page". */}
+    {resolvedCanonical && !noindex && (
+      <link href={resolvedCanonical} rel="canonical" />
+    )}
     {noindex && <meta content="noindex" name="robots" />}
     {description && <meta content={description} name="description" />}
     <meta content="website" property="og:type" />

package/src/components/layout/Pagination.astro

@@ -26,7 +26,7 @@ const s = { ...EN_UI.page, ...strings };
   (prev || next) && (
     <nav
       aria-label={s.pagination}
-      class="mx-auto mt-12 flex max-w-[42rem] justify-between gap-4 border-border border-t pt-6 max-md:flex-col"
+      class="mx-auto mt-12 flex max-w-content justify-between gap-4 border-border border-t pt-6 max-md:flex-col"
     >
       {prev ? (
         <a

package/src/components/layout/RootLayout.astro

@@ -261,7 +261,7 @@ if (isBare) {
 } else if (isApiOperation) {
   gridClass = "lg:grid-cols-[17.5rem_minmax(0,1fr)]";
 }
-let articleClass = "prose mx-auto max-w-[42rem]";
+let articleClass = "prose mx-auto max-w-content";
 if (isBare) {
   articleClass = "prose mx-auto max-w-[54rem]";
 } else if (isApiOperation) {
@@ -345,7 +345,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     <title>{pageTitle}</title>
     <Favicon favicon={favicon} appleIcon={appleIcon} />
     <Fonts cssVars={fontCssVars ?? []} />
-    {canonical && <link rel="canonical" href={canonical} />}
+    {/* Google warns against pairing a canonical with noindex — the canonical
+        says "index that URL", the robots meta says "distrust this page". */}
+    {canonical && !noindex && <link rel="canonical" href={canonical} />}
     {
       localeAlternates?.map((alt) => (
         <link href={alt.href} hreflang={alt.hreflang} rel="alternate" />
@@ -592,7 +594,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
                 route={page.route}
               />
               {formattedLastModified && (
-                <p class="mx-auto mt-10 max-w-[42rem] text-muted-foreground text-sm">
+                <p class="mx-auto mt-10 max-w-content text-muted-foreground text-sm">
                   {strings.page.lastUpdated} {formattedLastModified}
                 </p>
               )}

package/src/components/layout/Search.astro

@@ -2,6 +2,7 @@
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
+import { resolveIcon } from "../../theme/icons.ts";
 import Icon from "../Icon.astro";
 import { flattenPages } from "./nav-utils.ts";
 
@@ -13,19 +14,43 @@ import { flattenPages } from "./nav-utils.ts";
 interface Props {
   askEnabled?: boolean;
   navigation?: Navigation;
+  /** Curated empty-state pages; falls back to the first sidebar pages when empty or omitted. */
+  popularPages?: { icon?: string; label: string; route: string }[];
   strings?: UIStrings["search"];
   /** Active locale to filter results to; omitted disables locale filtering. */
   locale?: string;
 }
 
-const { askEnabled = false, navigation, strings, locale } = Astro.props;
+const { askEnabled = false, navigation, popularPages, strings, locale } =
+  Astro.props;
 // Merge over the English baseline per key (rather than `strings ?? …`) so a
 // partial — or empty `{}` — strings object still resolves every label to a
 // default, matching the pattern PageActions uses for its own dictionary.
 const s = { ...EN_UI.search, ...strings };
 
-// Pages shown in the empty state, before the user has typed anything.
-const popular = navigation ? flattenPages(navigation.sidebar).slice(0, 6) : [];
+// Icons resolve to inline SVG here (`theme/icons.ts` is a server-only module —
+// far too large to ship to the browser), so the island gets ready-to-render
+// markup rather than a name it can't resolve. Same approach as AskAI.astro.
+// A name outside the set falls through to the island's own file glyph.
+const iconSvg = (name: string | undefined): string | undefined => {
+  const resolved = name ? resolveIcon(name) : null;
+  return resolved
+    ? `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="${resolved.viewBox}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${resolved.body}</svg>`
+    : undefined;
+};
+
+// Pages shown in the empty state, before the user has typed anything. Only
+// curated entries carry an icon; sidebar-derived rows keep the file glyph.
+const popular =
+  popularPages && popularPages.length > 0
+    ? popularPages.map((page) => ({
+        icon: iconSvg(page.icon),
+        label: page.label,
+        route: page.route,
+      }))
+    : navigation
+      ? flattenPages(navigation.sidebar).slice(0, 6)
+      : [];
 
 const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 ---
@@ -166,6 +191,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
     }
 
     interface PopularPage {
+      /** Pre-resolved inline SVG from the server; absent falls back to `file`. */
+      icon?: string;
       label: string;
       route: string;
     }
@@ -501,7 +528,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         if (this.popular.length > 0) {
           const group = this.addGroup(this.popularMsg);
           for (const page of this.popular) {
-            const item = this.createLinkRow(page.route, page.label);
+            const item = this.createLinkRow(page.route, page.label, page.icon);
             group.appendChild(item.el);
             this.selectables.push(item);
           }
@@ -590,13 +617,15 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         return item;
       }
 
-      createLinkRow(url: string, label: string): Selectable {
+      createLinkRow(url: string, label: string, icon?: string): Selectable {
         const el = document.createElement("a");
         const href = prefixBase(import.meta.env.BASE_URL, url);
         el.href = href;
         el.className = ROW_CLASS;
+        // `icon` is server-resolved markup from the bundled icon set, not
+        // author HTML — the label still goes through `escapeHtml`.
         el.innerHTML = `
-          <span class="mt-0.5 shrink-0 text-muted-foreground">${svg("file")}</span>
+          <span class="mt-0.5 shrink-0 text-muted-foreground">${icon ?? svg("file")}</span>
           <span class="flex-1">
             <span class="block truncate font-normal text-foreground text-sm">${escapeHtml(label)}</span>
           </span>`;

package/src/components/layout/TableOfContents.astro

@@ -19,7 +19,7 @@ const { headings, title, variant } = Astro.props;
 
 {
   headings.length > 0 && variant === "mobile" && (
-    <details class="group mx-auto mb-6 max-w-[42rem] rounded-blume border border-border xl:hidden">
+    <details class="group mx-auto mb-6 max-w-content rounded-blume border border-border xl:hidden">
       <summary class="flex cursor-pointer list-none items-center justify-between gap-2 px-4 py-3 font-medium text-foreground text-sm [&::-webkit-details-marker]:hidden">
         <span>{title}</span>
         <Icon

package/src/components/openapi/Authorization.astro

@@ -0,0 +1,80 @@
+---
+import {
+  type OperationSecurity,
+  schemeCarrier,
+  schemeLabel,
+} from "./security.ts";
+
+interface Props {
+  security: OperationSecurity;
+}
+
+const { security } = Astro.props;
+---
+
+{
+  security.alternatives.length > 0 && (
+    <section class="mt-6">
+      <div
+        aria-level="2"
+        class="mb-2 font-semibold text-foreground text-sm"
+        role="heading"
+      >
+        Authorization
+      </div>
+      {security.optional && (
+        <p class="mb-2 text-muted-foreground text-sm">
+          Optional — this operation also accepts unauthenticated requests.
+        </p>
+      )}
+      {security.alternatives.map((alternative, index) => (
+        <>
+          {index > 0 && (
+            <div class="my-2 font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide">
+              or
+            </div>
+          )}
+          <div class="not-prose rounded-blume border border-border px-4">
+            {alternative.map((resolved) => {
+              const carrier = schemeCarrier(resolved);
+              return (
+                <div class="border-border border-t py-3 first:border-t-0">
+                  <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+                    <code class="font-mono text-foreground text-sm">
+                      {carrier?.name ?? resolved.key}
+                    </code>
+                    <span class="text-muted-foreground text-xs">
+                      {schemeLabel(resolved)}
+                      {carrier ? ` · ${carrier.in}` : ""}
+                    </span>
+                    {!security.optional && (
+                      <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
+                        required
+                      </span>
+                    )}
+                  </div>
+                  {resolved.scheme?.description && (
+                    <div
+                      class="mt-1 text-muted-foreground text-sm"
+                      set:text={resolved.scheme.description}
+                    />
+                  )}
+                  {resolved.scopes.length > 0 && (
+                    <div class="mt-1 flex flex-wrap items-center gap-1 text-xs">
+                      <span class="text-muted-foreground">Scopes:</span>
+                      {resolved.scopes.map((scope) => (
+                        <code class="rounded bg-muted px-1 py-0.5 text-foreground">
+                          {scope}
+                        </code>
+                      ))}
+                    </div>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        </>
+      ))}
+    </section>
+  )
+}

package/src/components/openapi/Operation.astro

@@ -6,7 +6,15 @@ import {
   resolveComponentRef,
   type SchemaLike,
 } from "./helpers.ts";
+import {
+  effectiveSecurity,
+  resolveSecurity,
+  sampleAuth,
+  type SecurityRequirementLike,
+  type SecuritySchemeLike,
+} from "./security.ts";
 import { buildRequestSample, sampleLanguages } from "./snippets.ts";
+import Authorization from "./Authorization.astro";
 import MethodBadge from "./MethodBadge.astro";
 import ParametersTable from "./ParametersTable.astro";
 import RequestBody from "./RequestBody.astro";
@@ -43,6 +51,7 @@ interface FullOperation {
   parameters?: ParameterLike[];
   requestBody?: RequestBodyLike;
   responses?: Record<string, ResponseLike>;
+  security?: SecurityRequirementLike[];
 }
 
 const { source, id } = Astro.props;
@@ -59,7 +68,9 @@ const doc = (spec?.document ?? {}) as {
     parameters?: Record<string, ParameterLike>;
     requestBodies?: Record<string, RequestBodyLike>;
     responses?: Record<string, ResponseLike>;
+    securitySchemes?: Record<string, SecuritySchemeLike>;
   };
+  security?: SecurityRequirementLike[];
   servers?: { url?: string }[];
 };
 const pathItem = ref ? doc.paths?.[ref.path] : undefined;
@@ -84,6 +95,11 @@ const responses = Object.fromEntries(
   ])
 );
 
+const security = resolveSecurity(
+  effectiveSecurity(operation?.security, doc.security),
+  doc.components?.securitySchemes
+);
+
 const sample =
   ref && operation
     ? buildRequestSample(
@@ -91,7 +107,8 @@ const sample =
         ref.method,
         ref.path,
         doc.servers ?? [],
-        schemas
+        schemas,
+        sampleAuth(security)
       )
     : null;
 const languages = sampleLanguages(spec?.codeSamples ?? []);
@@ -115,6 +132,7 @@ const languages = sampleLanguages(spec?.codeSamples ?? []);
       </div>
       <div class="grid grid-cols-1 items-start gap-x-10 gap-y-8 xl:grid-cols-[minmax(0,1fr)_minmax(0,28rem)]">
         <div>
+          <Authorization security={security} />
           <ParametersTable parameters={params} schemas={schemas} />
           {requestBody && (
             <RequestBody

package/src/components/openapi/ParametersTable.astro

@@ -39,7 +39,7 @@ const groups = SECTIONS.map((section) => ({
   groups.map((group) => (
     <section class="mt-6">
       <div
-        aria-level="3"
+        aria-level="2"
         class="mb-2 font-semibold text-foreground text-sm"
         role="heading"
       >