blume 0.2.0 → 0.3.0

package/src/components/layout/RootLayout.astro

@@ -1,6 +1,7 @@
 ---
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import type { BlumeClientData } from "../../core/data.ts";
 import type {
   Heading,
   LocaleSwitchOption,
@@ -12,6 +13,7 @@ import { buildStructuredData } from "../../seo/jsonld.ts";
 import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
 import Breadcrumbs from "./Breadcrumbs.astro";
+import Empty from "./Empty.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
@@ -108,9 +110,20 @@ interface Props {
   /**
    * User layout-slot overrides from `components.ts` (`defineComponents`). Each
    * key replaces the matching built-in; unknown keys are ignored. Wired slots:
-   * `Header`, `Sidebar`, `Breadcrumbs`, `TableOfContents`, `Pagination`.
+   * `Header`, `Logo`, `Search`, `Sidebar`, `MobileNav`, `Breadcrumbs`,
+   * `TableOfContents`, `Pagination`, `Feedback`, plus the content-injection slots
+   * `PageHeader`, `PageFooter`, and `Footer` (which have no built-in and render
+   * only when overridden). `Layout` (replacing this whole component) is wired in
+   * the generated page templates, not here.
    */
   layout?: Record<string, ComponentOverride>;
+  /**
+   * Snapshot serialized for React island hooks (`blume/hooks`). Rendered into a
+   * JSON `<script>` when present; omitted for zero-JS pages that need no islands.
+   */
+  clientData?: BlumeClientData | null;
+  /** Table-of-contents settings (`toc` config): visibility + heading range. */
+  toc?: { enabled: boolean; maxLevel: number; minLevel: number };
 }
 
 const {
@@ -152,21 +165,44 @@ const {
   xDefault,
   localeSwitch,
   layout = {},
+  clientData,
+  toc = { enabled: true, maxLevel: 3, minLevel: 2 },
 } = Astro.props;
 
+// Serialized once for island hooks; `<` escaped so content can't break the tag.
+const clientDataJson = clientData
+  ? JSON.stringify(clientData).replaceAll("<", "\\u003c")
+  : null;
+
 // Layout-slot overrides: render the user's component when configured, else the
 // built-in. Each override receives the same props as the component it replaces.
+// `Logo` and `Search` are resolved inside the header (forwarded via `layout`).
 const HeaderSlot = resolveSlot(layout.Header, Header);
 const SidebarSlot = resolveSlot(layout.Sidebar, NavTree);
 const BreadcrumbsSlot = resolveSlot(layout.Breadcrumbs, Breadcrumbs);
 const TableOfContentsSlot = resolveSlot(layout.TableOfContents, TableOfContents);
 const PaginationSlot = resolveSlot(layout.Pagination, Pagination);
+// The mobile drawer reuses the sidebar unless a distinct `MobileNav` is given.
+const MobileNavSlot = layout.MobileNav
+  ? resolveSlot(layout.MobileNav, NavTree)
+  : null;
+// Content-injection slots with no built-in: the `Empty` fallback renders nothing
+// when unconfigured, so these are safe to render unconditionally.
+const FooterSlot = resolveSlot(layout.Footer, Empty);
+const PageHeaderSlot = resolveSlot(layout.PageHeader, Empty);
+const PageFooterSlot = resolveSlot(layout.PageFooter, Empty);
+// The "Was this page helpful?" rating (rendered only when `feedback` is on).
+const FeedbackSlot = resolveSlot(layout.Feedback, PageFeedback);
 
 const strings = ui ?? EN_UI;
 // Filter search to the active language only when the site is multi-locale.
 const searchLocale =
   localeSwitch && localeSwitch.length > 1 ? locale : undefined;
-const tocHeadings = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+// TOC entries: the configured heading range, or none when the TOC is disabled
+// (an empty list makes TableOfContents render nothing).
+const tocHeadings = toc.enabled
+  ? headings.filter((h) => h.depth >= toc.minLevel && h.depth <= toc.maxLevel)
+  : [];
 const pageTitle = page.title ? `${page.title} - ${site.title}` : site.title;
 const description = page.description ?? site.description;
 
@@ -282,6 +318,7 @@ const bannerScript = banner?.dismissible
     <Banner banner={banner} />
     <HeaderSlot
       askEnabled={askEnabled}
+      layout={layout}
       localeSwitch={localeSwitch}
       logo={logo}
       navigation={navigation}
@@ -300,7 +337,20 @@ const bannerScript = banner?.dismissible
         class="fixed top-16 start-0 z-[35] h-[calc(100dvh-4rem)] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:z-auto lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4"
       >
         <nav>
-          <SidebarSlot currentRoute={page.route} items={sidebar} />
+          {
+            MobileNavSlot ? (
+              <>
+                <div class="lg:hidden">
+                  <MobileNavSlot currentRoute={page.route} items={sidebar} />
+                </div>
+                <div class="hidden lg:block">
+                  <SidebarSlot currentRoute={page.route} items={sidebar} />
+                </div>
+              </>
+            ) : (
+              <SidebarSlot currentRoute={page.route} items={sidebar} />
+            )
+          }
         </nav>
       </aside>
       <main class="min-w-0 px-6 pt-6 pb-10 lg:px-8 xl:px-10" id="blume-content">
@@ -310,9 +360,11 @@ const bannerScript = banner?.dismissible
           title={strings.toc.title}
           variant="mobile"
         />
+        <PageHeaderSlot headings={tocHeadings} page={page} route={page.route} />
         <article class="prose mx-auto max-w-[42rem]" dir={contentDir}>
           <slot />
         </article>
+        <PageFooterSlot headings={tocHeadings} page={page} route={page.route} />
         {
           formattedLastModified && (
             <p class="mx-auto mt-10 max-w-[42rem] text-muted-foreground text-sm">
@@ -320,7 +372,7 @@ const bannerScript = banner?.dismissible
             </p>
           )
         }
-        {feedback && <PageFeedback strings={strings.feedback} />}
+        {feedback && <FeedbackSlot strings={strings.feedback} />}
         <PaginationSlot next={next} prev={prev} strings={strings.page} />
       </main>
       <aside
@@ -344,6 +396,17 @@ const bannerScript = banner?.dismissible
         />
       </aside>
     </div>
+    <FooterSlot navigation={navigation} site={site} ui={strings} />
+    {
+      clientDataJson && (
+        <script
+          id="blume-client-data"
+          is:inline
+          set:html={clientDataJson}
+          type="application/json"
+        />
+      )
+    }
     <button
       aria-label="Close navigation"
       class="fixed inset-0 z-[30] hidden cursor-pointer border-0 bg-black/40 [:where([data-blume-nav-open])_&]:block lg:hidden"
@@ -358,6 +421,9 @@ const bannerScript = banner?.dismissible
       // Registers the <blume-toc> custom element: scrollspy for the table of
       // contents, highlighting the section currently in view as you scroll.
       import "./toc-element.ts";
+      // Dev-only: adds a friendly hint after a React island hydration mismatch.
+      // Tree-shaken out of production builds.
+      import "./hydration-hint.ts";
 
       const svg = (name: string) =>
         `<svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${icons[name]}</svg>`;

package/src/components/layout/hydration-hint.ts

@@ -0,0 +1,30 @@
+// Dev-only: when React reports a hydration mismatch for an island, follow it
+// with a friendly Blume hint pointing at the islands guide. Guarded by
+// `import.meta.env.DEV`, so the whole block is tree-shaken out of production
+// builds (the module ships no runtime code there).
+
+const HINT =
+  "[blume] A hydration mismatch was detected in an island. Make sure props passed from `.astro`/MDX are serializable and the component renders the same output on the server and client (avoid `Date.now()`, `Math.random()`, `window` at render time). See https://useblume.dev/docs/content/islands";
+
+const PATTERNS = [
+  /hydrat/iu,
+  /did not match/iu,
+  /server-rendered html/iu,
+  /server rendered html/iu,
+];
+
+if (import.meta.env.DEV && typeof window !== "undefined") {
+  const original = console.error.bind(console);
+  let shown = false;
+  console.error = (...args: unknown[]) => {
+    original(...args);
+    if (shown) {
+      return;
+    }
+    const text = args.map(String).join(" ");
+    if (PATTERNS.some((pattern) => pattern.test(text))) {
+      shown = true;
+      original(HINT);
+    }
+  };
+}

package/src/components/layout/overrides.ts

@@ -4,10 +4,12 @@ import type { ComponentOverride } from "../../core/define-components.ts";
  * Resolve a layout-slot override to the component Astro should render, falling
  * back to Blume's built-in when no usable override is configured.
  *
- * An override may be a bare component reference or an `IslandDescriptor`
- * (`{ component, client }`); only the component is used here. String-path
- * overrides can't be imported at render time, so they fall back to the built-in
- * for now (imported components are the recommended, type-safe form).
+ * By the time values reach here, the generated `components.ts` has already turned
+ * path strings and hydrated (`client:*`) overrides into imported components /
+ * wrappers, so the runtime map holds real components. This handles the remaining
+ * cases: a bare component reference, an `IslandDescriptor` (`{ component }`,
+ * unwrapped to its component), and — as a safety net for overrides that couldn't
+ * be resolved at build time — a leftover string, which falls back to the built-in.
  */
 export const resolveSlot = <T>(
   override: ComponentOverride | undefined,

package/src/components/props.ts

@@ -0,0 +1,68 @@
+// Public prop types for Blume's built-in components, so users can type their
+// overrides and wrappers: `import type { CalloutProps } from "blume/components"`.
+//
+// Each type is derived straight from the component with Astro's `ComponentProps`,
+// so it can never drift from the real props. `typeof import(...)` keeps these
+// type-only (no runtime import); the file-level disable is because that syntax is
+// the only way to reference an `.astro` component's type without a value import.
+// oxlint-disable typescript/consistent-type-imports
+import type { ComponentProps } from "astro/types";
+
+export type AccordionProps = ComponentProps<
+  typeof import("./content/Accordion.astro").default
+>;
+export type AccordionItemProps = ComponentProps<
+  typeof import("./content/AccordionItem.astro").default
+>;
+export type BadgeProps = ComponentProps<
+  typeof import("./content/Badge.astro").default
+>;
+export type CalloutProps = ComponentProps<
+  typeof import("./content/Callout.astro").default
+>;
+export type CardProps = ComponentProps<
+  typeof import("./content/Card.astro").default
+>;
+export type CardGroupProps = ComponentProps<
+  typeof import("./content/CardGroup.astro").default
+>;
+export type CodeGroupProps = ComponentProps<
+  typeof import("./content/CodeGroup.astro").default
+>;
+export type ColumnProps = ComponentProps<
+  typeof import("./content/Column.astro").default
+>;
+export type ColumnsProps = ComponentProps<
+  typeof import("./content/Columns.astro").default
+>;
+export type ExpandableProps = ComponentProps<
+  typeof import("./content/Expandable.astro").default
+>;
+export type FrameProps = ComponentProps<
+  typeof import("./content/Frame.astro").default
+>;
+export type PanelProps = ComponentProps<
+  typeof import("./content/Panel.astro").default
+>;
+export type PromptProps = ComponentProps<
+  typeof import("./content/Prompt.astro").default
+>;
+export type StepProps = ComponentProps<
+  typeof import("./content/Step.astro").default
+>;
+export type StepsProps = ComponentProps<
+  typeof import("./content/Steps.astro").default
+>;
+export type TabProps = ComponentProps<
+  typeof import("./content/Tab.astro").default
+>;
+export type TabsProps = ComponentProps<
+  typeof import("./content/Tabs.astro").default
+>;
+export type TileProps = ComponentProps<
+  typeof import("./content/Tile.astro").default
+>;
+export type TooltipProps = ComponentProps<
+  typeof import("./content/Tooltip.astro").default
+>;
+export type IconProps = ComponentProps<typeof import("./Icon.astro").default>;

package/src/core/builtin-tags.ts

@@ -0,0 +1,39 @@
+/**
+ * The MDX component tags Blume ships (the keys of the catch-all's component map,
+ * plus composed sub-parts like `Color.Item`/`Tree.File`). Used by the
+ * missing-component diagnostic to tell an unknown `<Tag>` from a built-in. Keep
+ * in sync with the component map in `astro/templates.ts`.
+ */
+export const BUILTIN_MDX_TAGS = new Set<string>([
+  "Accordion",
+  "AccordionItem",
+  "AutoTypeTable",
+  "Badge",
+  "Callout",
+  "Card",
+  "CardGroup",
+  "CodeBlock",
+  "CodeGroup",
+  "Color",
+  "Column",
+  "Columns",
+  "Component",
+  "Diff",
+  "Expandable",
+  "FileTree",
+  "Frame",
+  "GithubInfo",
+  "Icon",
+  "Math",
+  "Panel",
+  "Prompt",
+  "Step",
+  "Steps",
+  "Tab",
+  "Tabs",
+  "Tile",
+  "Tooltip",
+  "Tree",
+  "TypeTable",
+  "Visibility",
+]);

package/src/core/component-diagnostics.ts

@@ -0,0 +1,44 @@
+import { BUILTIN_MDX_TAGS } from "./builtin-tags.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+
+/** `CardGroup` → `card-group`, matching registry item names. */
+const toKebab = (tag: string): string =>
+  tag
+    .replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>-$<upper>")
+    .toLowerCase();
+
+/**
+ * Warn when an `.mdx` page uses a `<Component>` tag that resolves to nothing —
+ * a built-in, an island, or a `components.ts` override — so a typo surfaces as a
+ * friendly diagnostic (with a `blume add` hint where one exists) instead of a raw
+ * MDX "X is not defined" build error. `extraTags` are the project's own known
+ * components (islands + overrides); `registryNames` gates the install hint.
+ */
+export const validateUsedComponents = (
+  pages: PageRecord[],
+  extraTags: Set<string>,
+  registryNames: Set<string>
+): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = [];
+  const seen = new Set<string>();
+  for (const page of pages) {
+    for (const tag of page.componentsUsed ?? []) {
+      if (BUILTIN_MDX_TAGS.has(tag) || extraTags.has(tag) || seen.has(tag)) {
+        continue;
+      }
+      seen.add(tag);
+      const name = toKebab(tag);
+      const suggestion = registryNames.has(name)
+        ? `Run \`blume add ${name}\` to install it, or register <${tag}> in components.ts (mdx).`
+        : `Register <${tag}> in components.ts (mdx), or add an islands/${tag}.tsx component.`;
+      diagnostics.push({
+        code: "BLUME_UNKNOWN_COMPONENT",
+        file: page.sourcePath ?? page.id,
+        message: `<${tag}> is used in ${page.route} but isn't a known component.`,
+        severity: "warning",
+        suggestion,
+      });
+    }
+  }
+  return diagnostics;
+};