blume 0.2.0 → 0.3.0

package/src/components/index.ts

@@ -2,9 +2,8 @@
  * Public component contracts.
  *
  * Prop types for built-in components are exported here so users can type their
- * overrides (`import type { CalloutProps } from "blume/components"`). Concrete
- * component types are added as components land; the override descriptor types
- * below are stable today.
+ * overrides (`import type { CalloutProps } from "blume/components"`), alongside
+ * the override descriptor types.
  */
 export type {
   ComponentOverride,
@@ -12,3 +11,4 @@ export type {
   IslandDescriptor,
 } from "../core/define-components.ts";
 export type { HydrationMode } from "../core/schema.ts";
+export type * from "./props.ts";

package/src/components/islands/ask-ai.tsx

@@ -25,6 +25,19 @@ const nextId = (): number => {
   return idCounter;
 };
 
+// The endpoint and page path both honor the deployment `base` so grounding works
+// under a non-root base path (the server matches base-less document routes).
+const ASK_ENDPOINT = `${import.meta.env.BASE_URL}api/ask`.replace("//", "/");
+
+/** The current route with the deployment base stripped, for page-context lookup. */
+const currentPath = (): string => {
+  const base = import.meta.env.BASE_URL;
+  const path = window.location.pathname;
+  return base.length > 1 && path.startsWith(base)
+    ? `/${path.slice(base.length)}`
+    : path;
+};
+
 const BUTTON_CLASS =
   "inline-flex h-9 cursor-pointer items-center gap-2 rounded-blume border border-border bg-muted px-2.5 text-muted-foreground text-sm hover:border-accent disabled:opacity-50";
 
@@ -72,9 +85,10 @@ const AskAI = ({ strings }: { strings?: UIStrings["ask"] }) => {
     setBusy(true);
 
     try {
-      const response = await fetch("/api/ask", {
+      const response = await fetch(ASK_ENDPOINT, {
         body: JSON.stringify({
           messages: history.map((m) => ({ content: m.content, role: m.role })),
+          page: { path: currentPath() },
         }),
         headers: { "content-type": "application/json" },
         method: "POST",

package/src/components/islands/hooks.ts

@@ -0,0 +1,188 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { BlumeClientData } from "../../core/data.ts";
+import type { SearchFn, SearchResult } from "../layout/search/types.ts";
+
+/**
+ * React hooks for Blume islands.
+ *
+ * Islands hydrate independently (there's no shared React root spanning them), so
+ * project data can't come through context. Instead the layout serializes a small
+ * snapshot into a `<script type="application/json" id="blume-client-data">` tag,
+ * and {@link useBlume}/{@link usePage} read it after mount. {@link useSearch} and
+ * {@link useAskAI} wrap the generated search client and the Ask AI endpoint.
+ *
+ * Import them from `blume/hooks`:
+ *
+ * ```tsx
+ * import { useBlume, usePage } from "blume/hooks";
+ * ```
+ */
+
+export type { BlumeClientData } from "../../core/data.ts";
+
+let cachedData: BlumeClientData | null = null;
+
+/** Read + parse the injected snapshot (memoized); null on the server. */
+const readClientData = (): BlumeClientData | null => {
+  if (cachedData) {
+    return cachedData;
+  }
+  if (typeof document === "undefined") {
+    return null;
+  }
+  const element = document.querySelector("#blume-client-data");
+  if (!element?.textContent) {
+    return null;
+  }
+  try {
+    cachedData = JSON.parse(element.textContent) as BlumeClientData;
+    return cachedData;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Read the injected snapshot after mount. `null` on the server and on the first
+ * client render (so hydration matches), then the data once mounted.
+ */
+const useClientData = (): BlumeClientData | null => {
+  const [data, setData] = useState<BlumeClientData | null>(null);
+  useEffect(() => setData(readClientData()), []);
+  return data;
+};
+
+/** Site config + navigation for the current page, or `null` before mount. */
+export const useBlume = (): Pick<
+  BlumeClientData,
+  "config" | "navigation"
+> | null => {
+  const data = useClientData();
+  return data ? { config: data.config, navigation: data.navigation } : null;
+};
+
+/** The current page's route + title, or `null` before mount. */
+export const usePage = (): BlumeClientData["page"] | null =>
+  useClientData()?.page ?? null;
+
+/** State + actions returned by {@link useSearch}. */
+export interface UseSearch {
+  loading: boolean;
+  results: SearchResult | null;
+  search: (
+    query: string,
+    options?: { locale?: string; section?: string }
+  ) => Promise<SearchResult>;
+}
+
+/**
+ * Query the site's configured search provider. The provider client is created
+ * lazily on the first search, so islands that never search ship no extra weight.
+ */
+export const useSearch = (): UseSearch => {
+  const [results, setResults] = useState<SearchResult | null>(null);
+  const [loading, setLoading] = useState(false);
+  const searchFn = useRef<SearchFn | null>(null);
+
+  const search = useCallback<UseSearch["search"]>(async (query, options) => {
+    if (!searchFn.current) {
+      const { createSearch } = await import("blume:search-client");
+      searchFn.current = await createSearch();
+    }
+    setLoading(true);
+    try {
+      const result = await searchFn.current(query, options);
+      setResults(result);
+      return result;
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  return { loading, results, search };
+};
+
+/** A single Ask AI chat message. */
+export interface AskMessage {
+  content: string;
+  role: "assistant" | "user";
+}
+
+/** State + actions returned by {@link useAskAI}. */
+export interface UseAskAI {
+  ask: (question: string) => Promise<void>;
+  loading: boolean;
+  messages: AskMessage[];
+  reset: () => void;
+}
+
+const ASK_ENDPOINT = `${import.meta.env.BASE_URL}api/ask`.replace("//", "/");
+
+/** The current route with the deployment base stripped, for page grounding. */
+const currentPath = (): string => {
+  const base = import.meta.env.BASE_URL;
+  const path = window.location.pathname;
+  return base.length > 1 && path.startsWith(base)
+    ? `/${path.slice(base.length)}`
+    : path;
+};
+
+/**
+ * Stream answers from the Ask AI endpoint. Mirrors the built-in Ask AI island so
+ * a custom chat UI shares the same grounded, page-aware backend.
+ */
+export const useAskAI = (): UseAskAI => {
+  const [messages, setMessages] = useState<AskMessage[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  const ask = useCallback<UseAskAI["ask"]>(
+    async (question) => {
+      const trimmed = question.trim();
+      if (!trimmed || loading) {
+        return;
+      }
+      const history: AskMessage[] = [
+        ...messages,
+        { content: trimmed, role: "user" },
+      ];
+      const assistant: AskMessage = { content: "", role: "assistant" };
+      setMessages([...history, assistant]);
+      setLoading(true);
+      try {
+        const response = await fetch(ASK_ENDPOINT, {
+          body: JSON.stringify({
+            messages: history,
+            page: { path: currentPath() },
+          }),
+          headers: { "content-type": "application/json" },
+          method: "POST",
+        });
+        const reader = response.body?.getReader();
+        const decoder = new TextDecoder();
+        if (reader) {
+          let done = false;
+          while (!done) {
+            // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
+            const chunk = await reader.read();
+            ({ done } = chunk);
+            if (chunk.value) {
+              assistant.content += decoder.decode(chunk.value);
+              setMessages((current) => [
+                ...current.slice(0, -1),
+                { ...assistant },
+              ]);
+            }
+          }
+        }
+      } finally {
+        setLoading(false);
+      }
+    },
+    [loading, messages]
+  );
+
+  const reset = useCallback(() => setMessages([]), []);
+
+  return { ask, loading, messages, reset };
+};

package/src/components/layout/Empty.astro

@@ -0,0 +1,6 @@
+---
+// A no-op layout slot: renders nothing regardless of props. Used as the built-in
+// fallback for the content-injection slots (Footer, PageHeader, PageFooter) that
+// have no default, so an unconfigured slot renders empty while `resolveSlot`
+// still returns a valid component and the generated pages stay type-safe.
+---

package/src/components/layout/Header.astro

@@ -1,9 +1,13 @@
 ---
+import type { ComponentOverride } from "../../core/define-components.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
 import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
 import LanguageSwitcher from "./LanguageSwitcher.astro";
+import Logo from "./Logo.astro";
+import NavSelector from "./NavSelector.astro";
+import { resolveSlot } from "./overrides.ts";
 import Search from "./Search.astro";
 
 interface Props {
@@ -27,6 +31,12 @@ interface Props {
   localeSwitch?: LocaleSwitchOption[];
   /** Active locale for per-language search filtering. */
   searchLocale?: string;
+  /**
+   * Layout-slot overrides forwarded from the root layout. The header honors
+   * `Logo` and `Search` here so those pieces can be replaced without swapping
+   * the whole header.
+   */
+  layout?: Record<string, ComponentOverride>;
 }
 
 const {
@@ -41,15 +51,11 @@ const {
   switcherStrings,
   localeSwitch,
   searchLocale,
+  layout = {},
 } = Astro.props;
 
-// The logo is resolved upstream: an inline `svg` (so a currentColor mark
-// follows the theme) or image URL(s) for an <img>.
-const logoSvg = logo?.svg;
-const logoLight = logo?.light;
-const logoDark = logo?.dark ?? logo?.light;
-const logoAlt = logo?.alt ?? "";
-const brandHref = logo?.href ?? "/";
+const LogoSlot = resolveSlot(layout.Logo, Logo);
+const SearchSlot = resolveSlot(layout.Search, Search);
 
 const iconButton =
   "inline-flex size-9 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground";
@@ -80,37 +86,16 @@ const clickScript = `document.addEventListener("click",(e)=>{const t=e.target.cl
       </button>
     )
   }
-  <a
-    class="inline-flex items-center gap-2 font-semibold text-base text-foreground"
-    href={brandHref}
-  >
-    {
-      logoSvg && (
-        <span
-          aria-hidden="true"
-          class="inline-flex h-5 items-center [&>svg]:h-5 [&>svg]:w-auto"
-          set:html={logoSvg}
-        />
-      )
-    }
-    {
-      !logoSvg &&
-        logoLight &&
-        (logoLight === logoDark ? (
-          <img alt={logoAlt} class="h-5 w-auto" src={logoLight} />
-        ) : (
-          <>
-            <img alt={logoAlt} class="h-5 w-auto dark:hidden" src={logoLight} />
-            <img
-              alt={logoAlt}
-              class="hidden h-5 w-auto dark:block"
-              src={logoDark}
-            />
-          </>
-        ))
-    }
-    {site.title}
-  </a>
+  <LogoSlot logo={logo} site={site} />
+  {
+    navigation.selectors.length > 0 && (
+      <div class="flex items-center gap-1.5">
+        {navigation.selectors.map((selector) => (
+          <NavSelector route={route} selector={selector} />
+        ))}
+      </div>
+    )
+  }
   {
     navigation.tabs.length > 0 && (
       <nav aria-label="Sections" class="hidden gap-1 md:flex">
@@ -144,7 +129,7 @@ const clickScript = `document.addEventListener("click",(e)=>{const t=e.target.cl
   }
   {
     searchEnabled && (
-      <Search
+      <SearchSlot
         askEnabled={askEnabled}
         locale={searchLocale}
         navigation={navigation}

package/src/components/layout/Logo.astro

@@ -0,0 +1,50 @@
+---
+// The site brand: the logo mark (inline SVG so a `currentColor` mark follows the
+// theme, or light/dark `<img>` variants) followed by the site title, wrapped in
+// a link to the brand href. Extracted from the header so it can be replaced on
+// its own through the `Logo` layout slot (`defineComponents({ layout: { Logo } })`).
+import type { BlumeLogo } from "../../core/data.ts";
+
+interface Props {
+  site: { title: string };
+  logo?: BlumeLogo | null;
+}
+
+const { site, logo } = Astro.props;
+
+// The logo is resolved upstream: an inline `svg` (so a currentColor mark follows
+// the theme) or image URL(s) for an <img>.
+const logoSvg = logo?.svg;
+const logoLight = logo?.light;
+const logoDark = logo?.dark ?? logo?.light;
+const logoAlt = logo?.alt ?? "";
+const brandHref = logo?.href ?? "/";
+---
+
+<a
+  class="inline-flex items-center gap-2 font-semibold text-base text-foreground"
+  href={brandHref}
+>
+  {
+    logoSvg && (
+      <span
+        aria-hidden="true"
+        class="inline-flex h-5 items-center [&>svg]:h-5 [&>svg]:w-auto"
+        set:html={logoSvg}
+      />
+    )
+  }
+  {
+    !logoSvg &&
+      logoLight &&
+      (logoLight === logoDark ? (
+        <img alt={logoAlt} class="h-5 w-auto" src={logoLight} />
+      ) : (
+        <>
+          <img alt={logoAlt} class="h-5 w-auto dark:hidden" src={logoLight} />
+          <img alt={logoAlt} class="hidden h-5 w-auto dark:block" src={logoDark} />
+        </>
+      ))
+  }
+  {site.title}
+</a>

package/src/components/layout/NavSelector.astro

@@ -0,0 +1,75 @@
+---
+// A top-level navigation selector (Mintlify-style): a dropdown that switches
+// between partitions of the site — a product, a version, or any grouped set of
+// destinations (`navigation.selectors` in the config). Zero-JS, built on
+// <details>/<summary> like the language switcher.
+import type { NavSelector } from "../../core/types.ts";
+import Icon from "../Icon.astro";
+
+interface Props {
+  selector: NavSelector;
+  route: string;
+}
+
+const { selector, route } = Astro.props;
+
+// The active item is the deepest path that prefixes the current route, falling
+// back to the first item so the summary always shows something meaningful.
+const active =
+  selector.items.find((item) => item.path === route) ??
+  selector.items
+    .filter((item) => route.startsWith(item.path))
+    .toSorted((a, b) => b.path.length - a.path.length)[0] ??
+  selector.items[0];
+
+const iconButton =
+  "inline-flex h-9 cursor-pointer items-center gap-1.5 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground";
+const menuRowClass =
+  "flex w-full items-start gap-2.5 rounded-md px-2 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=true]:text-foreground";
+---
+
+{
+  selector.items.length > 0 && (
+    <details class="group relative">
+      <summary
+        aria-label={selector.label}
+        class={`${iconButton} list-none [&::-webkit-details-marker]:hidden`}
+      >
+        {active?.icon && <Icon name={active.icon} size={16} />}
+        <span class="max-sm:hidden">{active?.label ?? selector.label}</span>
+        <Icon
+          class="transition-transform group-open:rotate-180"
+          name="chevron-down"
+          size={14}
+        />
+      </summary>
+      <div class="absolute start-0 z-50 mt-2 min-w-56 rounded-blume border border-border bg-background p-1 shadow-xl">
+        {selector.items.map((item) => (
+          <a
+            aria-current={item.path === active?.path ? "true" : undefined}
+            class={menuRowClass}
+            href={item.path}
+          >
+            {item.icon && <Icon class="mt-0.5" name={item.icon} size={16} />}
+            <span class="flex-1">
+              <span class="flex items-center gap-2">
+                {item.label}
+                {item.tag && (
+                  <span class="rounded-full bg-muted px-1.5 py-0.5 text-[0.65rem] text-muted-foreground">
+                    {item.tag}
+                  </span>
+                )}
+              </span>
+              {item.description && (
+                <span class="mt-0.5 block text-muted-foreground text-xs">
+                  {item.description}
+                </span>
+              )}
+            </span>
+            {item.path === active?.path && <Icon name="check" size={14} />}
+          </a>
+        ))}
+      </div>
+    </details>
+  )
+}

package/src/components/layout/PageLayout.astro

@@ -17,6 +17,7 @@
 //   </PageLayout>
 import type {
   BlumeBanner,
+  BlumeClientData,
   BlumeDataConfig,
   BlumeFavicon,
   BlumeLogo,
@@ -69,6 +70,12 @@ interface Props {
   ui?: UIStrings;
   /** Language-switcher entries for the header. */
   localeSwitch?: LocaleSwitchOption[];
+  /**
+   * Snapshot for React island hooks (`blume/hooks`). Pass it when a custom page
+   * hosts islands that read `useBlume()`/`usePage()`:
+   * `clientData={{ config: data.config, navigation: data.navigation, page: { route: "/", title } }}`.
+   */
+  clientData?: BlumeClientData | null;
 }
 
 const {
@@ -93,8 +100,13 @@ const {
   dir = "ltr",
   ui,
   localeSwitch,
+  clientData,
 } = Astro.props;
 
+const clientDataJson = clientData
+  ? JSON.stringify(clientData).replaceAll("<", "\\u003c")
+  : null;
+
 const strings = ui ?? EN_UI;
 // Filter search to the active language only when the site is multi-locale.
 const searchLocale =
@@ -110,8 +122,17 @@ const route = page?.route ?? "/";
 const ogSlug = route === "/" ? "index" : route.slice(1);
 const resolvedCanonical =
   canonical ?? (siteUrl ? `${siteUrl}${route === "/" ? "" : route}` : null);
-const resolvedOgImage =
-  ogImage ?? (ogEnabled && siteUrl ? `${siteUrl}/og/${ogSlug}.png` : null);
+// An explicit `ogImage` wins. A root-relative path (e.g. an image dropped in
+// `public/`) is resolved against the site URL so crawlers get an absolute
+// `og:image`; an already-absolute URL passes through untouched. Otherwise fall
+// back to the generated OG card for this route.
+const absolutizeOgImage = (value: string): string =>
+  value.startsWith("/") && siteUrl ? `${siteUrl}${value}` : value;
+const resolvedOgImage = ogImage
+  ? absolutizeOgImage(ogImage)
+  : ogEnabled && siteUrl
+    ? `${siteUrl}/og/${ogSlug}.png`
+    : null;
 
 const initialThemeScript = themeInitScript(themeMode);
 const bannerScript = banner?.dismissible
@@ -169,5 +190,20 @@ const bannerScript = banner?.dismissible
     </Header>
     <main id="blume-content"><slot /></main>
     <slot name="footer" />
+    {
+      clientDataJson && (
+        <script
+          id="blume-client-data"
+          is:inline
+          set:html={clientDataJson}
+          type="application/json"
+        />
+      )
+    }
+    <script>
+      // Dev-only: friendly hint after a React island hydration mismatch;
+      // tree-shaken out of production builds.
+      import "./hydration-hint.ts";
+    </script>
   </body>
 </html>