@wildo-ai/saas-website 1.1.1

package/src/astro/blog-post-bridge.tsx

@@ -0,0 +1,404 @@
+import type { ComponentType, FunctionComponent, ReactNode } from 'react';
+
+import type { FrontendProvidersBlock } from '@wildo-ai/saas-models/public-runtime';
+import type { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import {
+  WebsiteRuntimeContextProvider,
+  type WebsiteRuntimeContextValue,
+} from '../core/contexts/WebsiteRuntimeContext';
+import { createFrontendWebsiteProviderRegistry } from '../core/external-providers/frontend-provider-registry.website';
+import { BlogPost, BLOG_POST_PAGE_REF } from '../mdx/BlogPost';
+import type { WebsiteMdxComponentsMap } from '../mdx/website-mdx-provider';
+import type { WebsiteDesignTokens } from '../schemas/design-tokens/website-design-tokens.shared.schemas';
+import type { WebsiteLabelKey } from '../schemas/label-keys/website-label-key.schemas';
+import type { WebsiteNavigationConfig } from '../schemas/manifests/website-root-config.shared.schemas';
+import type { LabelPack } from '../schemas/validators/label-pack.validator';
+
+/**
+ * @wildo_source:part:start saas.website.blog.bridge facet:layer:astro facet:family:website
+ *
+ * `createWebsiteBlogPostBridgeIsland(deps)` — factory that returns the
+ * React island a consumer's per-locale `*.bridge.tsx` module exports for
+ * mounting blog post pages. **Sibling** of `createWebsitePageBridgeIsland`
+ * but adapted to the dynamic-routing constraint of the marketing-blog
+ * adapter (Phase 7, D-6 = Option A).
+ *
+ * # Why blog posts cannot reuse the page bridge factory
+ *
+ * Three structural differences between marketing pages and blog posts
+ * forced this dedicated factory shape:
+ *
+ *   1. **Per-slug body resolution.** A marketing page (`landing`,
+ *      `pricing`, etc.) has ONE `PageComponent` known at bridge-module
+ *      load time — the page bridge closes over it. A blog post's body
+ *      is the compiled MDX module, which varies per slug. Closing the
+ *      MDX body inside the factory at module load time would force one
+ *      bridge file per post (defeats Q16=B "one MDX file per post").
+ *      Instead, the factory closes over a `slugToMdxBody: Record<string,
+ *      ComponentType>` map — typically built from
+ *      `import.meta.glob('./content/blog/<locale>/*.mdx', { eager: true })`
+ *      on the consumer side — and the island accepts the active `slug`
+ *      as a primitive (JSON-serializable) prop.
+ *
+ *   2. **Layout already wrapped by `<BlogPost>`.** The page bridge wraps
+ *      its `PageComponent` in `<WebsitePageLayout pageRef={…}>`. The
+ *      `<BlogPost>` renderer ALREADY wraps its tree in
+ *      `<WebsitePageLayout pageRef={BLOG_POST_PAGE_REF}>` (the framework
+ *      reserves the page ref for the entire blog surface — see
+ *      `BLOG_POST_PAGE_REF` JSDoc in `BlogPost.tsx`). Reusing the page
+ *      bridge would double-wrap the layout. This factory instead
+ *      provides the runtime context and yields directly to `<BlogPost>`,
+ *      which owns the layout boundary itself.
+ *
+ *   3. **Astro's React-children context-propagation gap.** Astro
+ *      renders React component children INDEPENDENTLY of the parent
+ *      component when the boundary is `.astro` ↔ `.tsx`, even on the
+ *      server side. This means
+ *      `<BlogPost client:load><Content /></BlogPost>` written in an
+ *      `.astro` file would NOT propagate the `<WebsiteMdxProvider>`
+ *      context to the React components embedded inside `<Content />`
+ *      (the embedded `<CTASection />` would render WITHOUT the engine's
+ *      MDX provider scope; the `mdxComponents` map would be ignored).
+ *      Confirmed via the Astro docs, `@astrojs/react` integration
+ *      readme, and the documented "Bridging two JSX runtimes" gotcha.
+ *
+ *      The fix: the entire blog post tree (BlogPost + MDX body +
+ *      embedded section components) lives inside ONE React island. The
+ *      MDX module is imported as a React component via Astro's
+ *      `import.meta.glob`, and the bridge renders it as JSX children
+ *      of `<BlogPost>` from INSIDE the island — no `.astro` ↔ `.tsx`
+ *      boundary is crossed during the body render.
+ *
+ * # Why hydration is required (vs. pure SSR)
+ *
+ * The `WebsiteRuntimeContextProvider` + `<BlogPost>` tree could in
+ * theory render on the server only (no `client:*` directive). But:
+ *
+ *   - Embedded sections (`<CTASection />`) typically have their own
+ *     interactivity (analytics handlers, A/B variant flippers, etc.)
+ *     that need React event listeners to attach client-side.
+ *   - The framework's `useWebsiteLabel(...)` hook chain assumes a live
+ *     React render tree — a pure-SSR tree would freeze label resolution
+ *     at build time, but any future client-driven label override (e.g.
+ *     a debug-mode label inspector) would silently break.
+ *
+ * The factory therefore returns an island that the consumer's `.astro`
+ * mounts with `client:load` (or `client:idle` for posts known to be
+ * non-interactive). The hydration cost is bounded by the per-locale MDX
+ * glob — see "Bundle scaling cliff" below.
+ *
+ * # Bundle scaling cliff (deferred trade-off)
+ *
+ * `import.meta.glob({ eager: true })` materializes EVERY post's
+ * compiled JS into the per-locale React-island bundle (~5–20 KB per
+ * post depending on length and embedded section count). For the
+ * Phase 7 dogfood (≤10 posts) this is fine and matches the documented
+ * Astro+MDX pattern. Past ~50 posts this becomes a real budget concern.
+ * The factory's API is forward-compatible with `{ eager: false }`
+ * (lazy loaders): swap the consumer's glob to lazy mode and the
+ * `slugToMdxBody[slug]` lookup returns a `() => Promise<{ default:
+ * ComponentType }>`; wrap in `React.lazy()` + `<Suspense>` and the
+ * factory call site stays unchanged. The migration is a consumer-side
+ * change, not an engine API break.
+ *
+ * # Authoring pattern
+ *
+ * **Per-locale bridge file** (consumer side, ONE per locale):
+ *
+ * ```tsx
+ * // examples/<app>/website/src/pages-impl/blog-post-en.bridge.tsx
+ * import type { ComponentType } from 'react';
+ *
+ * import { createWebsiteBlogPostBridgeIsland }
+ *   from '@wildo-ai/saas-website/mdx';
+ * import { BLOG_POST_MDX_COMPONENTS }
+ *   from './blog-post.mdx-components';
+ * import { WEBSITE_ROOT_CONFIG } from '../website-root.config';
+ *
+ * // Static analyzable glob — Vite resolves at build time. The glob
+ * // pattern MUST be a single string literal (no concatenation, no
+ * // variable interpolation); Vite parses it AST-side. The `as` cast
+ * // narrows the unknown record to the per-MDX-file shape Astro's mdx
+ * // integration emits (default export = the compiled React component).
+ * const rawModules = import.meta.glob('./content/blog/en/*.mdx', {
+ *   eager: true,
+ * }) as Record<string, { default: ComponentType }>;
+ *
+ * const slugToMdxBody: Record<string, ComponentType> = {};
+ * for (const [path, mod] of Object.entries(rawModules)) {
+ *   // './content/blog/en/why-context.mdx' -> 'why-context'
+ *   const slug = path.split('/').pop()!.replace(/\.mdx$/, '');
+ *   slugToMdxBody[slug] = mod.default;
+ * }
+ *
+ * export const BlogPostEnBridgeIsland =
+ *   createWebsiteBlogPostBridgeIsland({
+ *     slugToMdxBody,
+ *     navigation: WEBSITE_ROOT_CONFIG.navigation,
+ *     mdxComponents: BLOG_POST_MDX_COMPONENTS,
+ *   });
+ * ```
+ *
+ * **Per-locale `[slug].astro` shell** (consumer side):
+ *
+ * ```astro
+ * ---
+ * import { getCollection } from 'astro:content';
+ * import {
+ *   loadWebsitePageRuntime,
+ *   renderBlogPostHeadHtml,
+ *   renderWebsiteDesignTokensCss,
+ * } from '@wildo-ai/saas-website/astro';
+ * import { parseBlogPostFrontmatter } from '@wildo-ai/saas-website/mdx';
+ * import { BlogPostEnBridgeIsland } from '@/pages-impl/blog-post-en.bridge';
+ * import { BLOG_POST_PAGE_MANIFEST } from '@/pages-impl/blog-post.page';
+ * import { WEBSITE_SITE_CONTEXT } from '@/website-site-context';
+ *
+ * export async function getStaticPaths() {
+ *   const posts = await getCollection('blog');
+ *   const defaultLocale = WEBSITE_SITE_CONTEXT.websiteConfig.defaultLocale;
+ *   return posts
+ *     .filter((p) => p.data.locale === defaultLocale)
+ *     .map((p) => ({ params: { slug: p.data.slug }, props: { entry: p } }));
+ * }
+ * const { entry } = Astro.props;
+ *
+ * const runtime = loadWebsitePageRuntime({
+ *   manifest: BLOG_POST_PAGE_MANIFEST,
+ *   siteContext: WEBSITE_SITE_CONTEXT,
+ *   labelPacksDir: './src/i18n',
+ *   astroLocale: Astro.currentLocale,
+ * });
+ * const frontmatter = parseBlogPostFrontmatter(entry.data, { source: entry.id });
+ * const headHtml = renderBlogPostHeadHtml({
+ *   siteContext: WEBSITE_SITE_CONTEXT,
+ *   locale: runtime.locale,
+ *   routePath: `/blog/${frontmatter.slug}`,
+ *   frontmatter,
+ * });
+ * const designTokensCss = renderWebsiteDesignTokensCss(
+ *   WEBSITE_SITE_CONTEXT.rootConfig.designTokens,
+ * );
+ * ---
+ * <!doctype html>
+ * <html lang={runtime.locale}>
+ *   <head>
+ *     <meta charset="UTF-8" />
+ *     <meta name="viewport" content="width=device-width,initial-scale=1.0" />
+ *     <Fragment set:html={headHtml} />
+ *     <style set:html={designTokensCss}></style>
+ *   </head>
+ *   <body>
+ *     <BlogPostEnBridgeIsland
+ *       client:load
+ *       slug={frontmatter.slug}
+ *       rawFrontmatter={entry.data}
+ *       source={entry.id}
+ *       locale={runtime.locale}
+ *       defaultLocale={runtime.defaultLocale}
+ *       labelPack={runtime.labelPack}
+ *       designTokens={WEBSITE_SITE_CONTEXT.rootConfig.designTokens}
+ *       skipToMainContentLabelKey={
+ *         WEBSITE_SITE_CONTEXT.rootConfig.skipToMainContentLabelKey
+ *       }
+ *     />
+ *   </body>
+ * </html>
+ * ```
+ *
+ * # Boundary
+ *
+ * Strictly client-bundle-safe (re-exported from `mdx.ts` — NOT from
+ * `astro-island.ts`, because this module hard-imports the MDX adapter
+ * whose `@mdx-js/react` peer is optional; walked by the
+ * bundle-isolation test). MUST stay clear of `node:*` and SSR-tier
+ * specifiers.
+ */
+
+/**
+ * Module-load-time dependencies — closed over inside the returned
+ * island. NEVER cross the hydration boundary as serialized props.
+ */
+export interface CreateWebsiteBlogPostBridgeIslandDeps {
+  /**
+   * Per-slug map of compiled MDX bodies (each entry is a React
+   * component — the `.default` export of the MDX module). Typically
+   * built from `import.meta.glob('./content/blog/<locale>/*.mdx',
+   * { eager: true })` with the path-key normalized to the slug. Closed
+   * over at module-load time so the entire MDX body graph for the
+   * locale lands inside ONE React island bundle (D-6 Option A) — this
+   * is the structural fix for Astro's React-children context-propagation
+   * gap (see file preamble).
+   *
+   * The map is read by `slugToMdxBody[props.slug]` at island render
+   * time. A missing slug throws a clear framework-owned error (rather than
+   * rendering an empty body silently); the consumer's `getStaticPaths`
+   * is responsible for not emitting routes for slugs absent from the
+   * map.
+   *
+   * **Why `ComponentType<any>` and not a stricter generic**: matches
+   * the upstream `@mdx-js/react` convention (`MDXContent` from
+   * `mdx/types` is parameterized over an open `MDXProps` shape). MDX
+   * compilation hands the body a compiler-managed props object that
+   * the type system cannot narrow at the framework boundary; using
+   * `<any>` here keeps the consumer's
+   * `import.meta.glob(...) as Record<string, { default: ComponentType }>`
+   * cast assignable without an additional wrap/unwrap. Same posture
+   * as `WebsiteMdxComponentsMap` (intentional symmetry).
+   */
+  slugToMdxBody: Readonly<Record<string, ComponentType<any>>>;
+  /**
+   * Site-wide navigation slot bindings (header / footer components).
+   * Closed over here for the same reason as the page bridge: both
+   * fields are `ComponentType` refs that cannot survive Astro's
+   * serialization boundary.
+   */
+  navigation: WebsiteNavigationConfig;
+  /**
+   * MDX-tag → React-component map forwarded into `<BlogPost>` and
+   * scoped via `<WebsiteMdxProvider>`. Typically a small object
+   * literal exporting the consumer-authored business sections that
+   * blog posts can embed (`<CTASection />`, etc.). Closed over here
+   * (rather than passed as an island prop) because the values are
+   * `ComponentType` refs.
+   */
+  mdxComponents?: WebsiteMdxComponentsMap;
+}
+
+/**
+ * Hydration-boundary props — what the consumer's `.astro` page passes
+ * to `<BlogPostEnBridgeIsland client:load ...{primitiveProps}/>`.
+ * Every field is JSON-serializable.
+ */
+export interface WebsiteBlogPostBridgeIslandProps {
+  /**
+   * Slug of the post being rendered. Used by the island to look up
+   * the matching MDX body in `deps.slugToMdxBody`. Carried as a plain
+   * string (not the branded `BlogPostSlug`) because Astro's
+   * serialization boundary unwraps brands.
+   */
+  slug: string;
+  /**
+   * Raw frontmatter object Astro hands the page from `entry.data`.
+   * Forwarded straight to `<BlogPost>` for strict Zod-4 validation.
+   * The bridge does NOT re-validate (single validation surface, owned
+   * by the renderer).
+   */
+  rawFrontmatter: unknown;
+  /**
+   * Diagnostic source identifier echoed into validation errors —
+   * typically `entry.id` from Astro's content collection. Optional
+   * but recommended for actionable error messages.
+   */
+  source?: string;
+  /** The locale Astro resolved (with default-locale fallback). */
+  locale: AvailableLanguage;
+  /**
+   * The site's default locale. Required for `WebsiteInternalLink`
+   * locale-prefix logic (mirrors the page bridge's `defaultLocale`
+   * island prop).
+   */
+  defaultLocale: AvailableLanguage;
+  /** Already-loaded + already-shape-validated label pack. */
+  labelPack: LabelPack;
+  /** Design-token bundle from `WebsiteRootConfig.designTokens`. */
+  designTokens: WebsiteDesignTokens;
+  /**
+   * Fully-composed label key the framework reads to render the
+   * "Skip to main content" affordance. Mirrors
+   * `WebsiteRootConfig.skipToMainContentLabelKey`. Carried as a
+   * primitive island prop for the same reason as the page bridge.
+   */
+  skipToMainContentLabelKey: WebsiteLabelKey;
+  /** Optional website-facing public providers materialized at build time. */
+  frontendProviders?: FrontendProvidersBlock;
+}
+
+const EMPTY_MDX_COMPONENTS: WebsiteMdxComponentsMap = Object.freeze({});
+
+/**
+ * Returns a FUNCTION component, not the wider `ComponentType` union. The island IS a function
+ * component — Astro hydrates nothing else here — and the union is not callable, so declaring it
+ * cost callers the ability to invoke the island directly (which the bridge suites do, to observe
+ * the synchronous throw for an unregistered slug without routing it through React's reconciler
+ * error path). `FunctionComponent` is assignable to `ComponentType`, so no consumer narrows.
+ */
+export function createWebsiteBlogPostBridgeIsland(
+  deps: CreateWebsiteBlogPostBridgeIslandDeps,
+): FunctionComponent<WebsiteBlogPostBridgeIslandProps> {
+  const {
+    slugToMdxBody,
+    navigation,
+    mdxComponents = EMPTY_MDX_COMPONENTS,
+  } = deps;
+
+  function WebsiteBlogPostBridgeIsland({
+    slug,
+    rawFrontmatter,
+    source,
+    locale,
+    defaultLocale,
+    labelPack,
+    designTokens,
+    skipToMainContentLabelKey,
+    frontendProviders,
+  }: WebsiteBlogPostBridgeIslandProps): ReactNode {
+    const MdxBody = slugToMdxBody[slug];
+    if (MdxBody === undefined) {
+      /**
+       * Loud failure — the consumer's `getStaticPaths` is supposed to
+       * only emit routes for slugs present in the MDX glob. A missing
+       * lookup means the glob and the collection are out of sync; the
+       * operator needs an actionable error string with the offending
+       * slug + the keys that ARE present (truncated to keep the build
+       * log readable).
+       */
+      const knownKeys = Object.keys(slugToMdxBody);
+      const known =
+        knownKeys.length <= 5
+          ? knownKeys.join(', ')
+          : `${knownKeys.slice(0, 5).join(', ')}, … (${knownKeys.length} total)`;
+      throw new Error(
+        `[blog-post-bridge] No MDX body registered for slug="${slug}". ` +
+          `The bridge factory's slugToMdxBody map only knows: ${known}. ` +
+          `Verify the consumer's import.meta.glob('...content/blog/<locale>/*.mdx') ` +
+          `pattern matches the source file naming.`,
+      );
+    }
+
+    const runtimeValue: WebsiteRuntimeContextValue = {
+      locale,
+      defaultLocale,
+      labelPack,
+      designTokens,
+      navigation,
+      skipToMainContentLabelKey,
+      frontendProviderRegistry: createFrontendWebsiteProviderRegistry(frontendProviders),
+    };
+    return (
+      <WebsiteRuntimeContextProvider value={runtimeValue}>
+        <BlogPost
+          rawFrontmatter={rawFrontmatter}
+          source={source}
+          mdxComponents={mdxComponents}
+        >
+          <MdxBody />
+        </BlogPost>
+      </WebsiteRuntimeContextProvider>
+    );
+  }
+  WebsiteBlogPostBridgeIsland.displayName = 'WebsiteBlogPostBridgeIsland';
+
+  return WebsiteBlogPostBridgeIsland;
+}
+
+/**
+ * Re-export of the framework-reserved blog-post page ref. Consumers
+ * authoring `BLOG_POST_PAGE_MANIFEST` need this constant to satisfy
+ * the manifest's `ref` field; re-exporting it from the bridge module
+ * means the consumer's per-locale bridge file can grab both symbols
+ * from the one `@wildo-ai/saas-website/mdx` import it already has.
+ */
+export { BLOG_POST_PAGE_REF };
+/** @wildo_source:part:end saas.website.blog.bridge */