@moku-labs/web 1.9.0 → 1.11.0

package/dist/browser.d.mts

@@ -1,5 +1,5 @@
 import { EmitFn } from "@moku-labs/core";
-import { ComponentChildren, VNode } from "preact";
+import { ComponentChildren, FunctionComponent, VNode } from "preact";
 import { BundledTheme, ThemeRegistrationAny } from "shiki";
 import { Pluggable, Processor } from "unified";
 
@@ -1734,6 +1734,13 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", Confi
  */
 declare function createComponent(name: string, hooks: ComponentHooks): ComponentDef;
 //#endregion
+//#region src/plugins/spa/lazy-embed.d.ts
+/**
+ * Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+ * The companion of the content pipeline's `::embed` directive.
+ */
+declare const lazyEmbed: ComponentDef;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -1920,7 +1927,7 @@ type DataProvider = {
  */
 declare const dataPlugin: import("@moku-labs/core").PluginInstance<"data", DataConfig, DataState, DataProvider, {}> & Record<never, never>;
 declare namespace types_d_exports {
-  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, MermaidDiagramOptions, State };
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, EmbedFacade, EmbedFacadeProps, EmbedOptions, FileSystemContentOptions, Frontmatter, LoadAllOptions, MermaidDiagramOptions, State };
 }
 /**
  * YAML frontmatter parsed from each article file.
@@ -2064,6 +2071,55 @@ type MermaidDiagramOptions = {
    */
   renderDiagrams?: (sources: readonly string[], mermaidConfig?: Record<string, unknown>) => Promise<readonly string[]>;
 };
+/**
+ * Props handed to an `::embed` facade component (the click-to-activate placeholder
+ * the framework renders to static markup at build time). `width`/`height` are the
+ * parsed pixel dimensions when the directive set them; `attributes` is the full raw
+ * directive attribute bag, so a custom facade can read arbitrary extra options
+ * (e.g. `::embed{… poster="/p.jpg" label="Play"}`).
+ *
+ * @example
+ * ```tsx
+ * const Facade = ({ title, attributes }: EmbedFacadeProps) => (
+ *   <button type="button" class="lazy-embed-button">
+ *     {attributes.poster ? <img src={attributes.poster} alt="" /> : null}
+ *     <span class="lazy-embed-title">{title}</span>
+ *   </button>
+ * );
+ * ```
+ */
+type EmbedFacadeProps = {
+  /** The embed target exactly as written in the directive (the provider resolves it later). */src: string; /** The human-readable embed title (default label + iframe title). */
+  title: string; /** Reserved-box width in pixels, when the directive set `width`/`height`. */
+  width?: number; /** Reserved-box height in pixels, when the directive set `width`/`height`. */
+  height?: number; /** The full raw directive attribute bag (custom options live here). */
+  attributes: Readonly<Record<string, string>>;
+};
+/**
+ * A consumer-supplied facade component: a Preact function component over
+ * {@link EmbedFacadeProps}, rendered (at build time, to static markup) as the
+ * facade's inner content — inside the framework-owned `<figure>` that carries the
+ * island hooks + reserved-box sizing. Defaults to the built-in `EmbedFacadeButton`.
+ */
+type EmbedFacade = FunctionComponent<EmbedFacadeProps>;
+/**
+ * Options for the `::embed` lazy-iframe feature (the `embed` key of
+ * {@link FileSystemContentOptions}). `embed: true` uses the default facade;
+ * `embed: { facade }` swaps in a consumer Preact component for the placeholder.
+ *
+ * @example
+ * ```ts
+ * fileSystemContent({ contentDir: "./content", trustedContent: true, embed: { facade: MyFacade } });
+ * ```
+ */
+type EmbedOptions = {
+  /**
+   * Consumer Preact component rendering the facade's inner content (SSR'd to
+   * static markup at build — no client JS). Receives {@link EmbedFacadeProps}.
+   * Defaults to the built-in `EmbedFacadeButton`.
+   */
+  facade?: EmbedFacade;
+};
 /**
  * Options for the node filesystem provider {@link ContentProvider} `fileSystemContent`.
  * These are the markdown-pipeline + source concerns that used to live on the content
@@ -2098,6 +2154,16 @@ type FileSystemContentOptions = {
    * (plus playwright with an installed browser). Defaults to disabled.
    */
   mermaid?: boolean | MermaidDiagramOptions;
+  /**
+   * Lazy iframe embeds: rewrite `::embed{src="…" title="…"}` leaf directives
+   * into static click-to-activate facades (no iframe — and none of the target's
+   * network/JS cost — until the reader clicks). Pair with the `lazyEmbed` SPA
+   * island, which swaps the facade for the real `<iframe loading="lazy">`.
+   * `true` enables with the default facade; an object passes {@link EmbedOptions}
+   * (e.g. a consumer `facade` Preact component). Requires `trustedContent: true`
+   * (the facade is raw HTML the sanitize pass would strip). Defaults to disabled.
+   */
+  embed?: boolean | EmbedOptions;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -2400,4 +2466,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$5, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Content, types_d_exports$1 as Data, types_d_exports$2 as Env, types_d_exports$3 as Head, types_d_exports$4 as Log, types_d_exports$5 as Router, types_d_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Content, types_d_exports$1 as Data, types_d_exports$2 as Env, types_d_exports$3 as Head, types_d_exports$4 as Log, types_d_exports$5 as Router, types_d_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/browser.mjs

@@ -4428,6 +4428,89 @@ function disposeSpa() {
 	}
 }
 //#endregion
+//#region src/plugins/spa/lazy-embed.ts
+/**
+* @file `lazyEmbed` island — activates the static embed facades emitted by the
+* content pipeline's `::embed` directive (pipeline/embed.ts). Mounts on every
+* `[data-component="lazy-embed"]` figure; a click on the facade's button swaps
+* it for the real `<iframe loading="lazy">`. Until that click the embedded
+* document costs the page nothing — no request, no third-party JS, no
+* scroll-jacking. Register it in `pluginConfigs.spa.components`; all visual
+* chrome (`.lazy-embed*` classes) is consumer CSS.
+*/
+/** CSS class on the injected `<iframe>` (consumer CSS sizes it). */
+const EMBED_FRAME_CLASS = "lazy-embed-frame";
+/**
+* Swap a facade `<figure>`'s content for its real `<iframe>`. The iframe
+* carries `loading="lazy"` plus fullscreen permission, and the figure gains
+* `data-embed-active` so consumer CSS can restyle the activated state.
+*
+* @param figure - The facade element carrying `data-embed-src`/`data-embed-title`.
+* @example
+* ```ts
+* activateEmbed(figure);
+* ```
+*/
+function activateEmbed(figure) {
+	const src = figure.dataset.embedSrc;
+	if (!src) return;
+	const iframe = document.createElement("iframe");
+	iframe.src = src;
+	iframe.title = figure.dataset.embedTitle ?? "";
+	iframe.className = EMBED_FRAME_CLASS;
+	iframe.setAttribute("loading", "lazy");
+	iframe.allow = "fullscreen; autoplay; gamepad";
+	iframe.allowFullscreen = true;
+	figure.replaceChildren(iframe);
+	figure.dataset.embedActive = "";
+}
+/**
+* Shared click handler (module-level so mount/unmount detach the same
+* reference): any click on the not-yet-active facade activates the embed. It
+* fires on the whole facade — not a specific button class — so a consumer's
+* custom facade markup (see content `embed.facade`) works without re-wiring;
+* the default facade's `<button>` keeps it keyboard-accessible. Once active
+* (`data-embed-active`), clicks fall through to the live iframe.
+*
+* @param event - The click event from the facade figure.
+* @example
+* ```ts
+* element.addEventListener("click", onFacadeClick);
+* ```
+*/
+function onFacadeClick(event) {
+	const figure = event.currentTarget;
+	if (!(figure instanceof HTMLElement)) return;
+	if (figure.dataset.embedActive !== void 0) return;
+	activateEmbed(figure);
+}
+/**
+* Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+* The companion of the content pipeline's `::embed` directive.
+*/
+const lazyEmbed = createComponent("lazy-embed", {
+	/**
+	* Bind the activation click handler when a facade mounts.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onMount(ctx);
+	*/
+	onMount(ctx) {
+		ctx.el.addEventListener("click", onFacadeClick);
+	},
+	/**
+	* Remove the activation click handler when the facade is destroyed.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onDestroy(ctx);
+	*/
+	onDestroy(ctx) {
+		ctx.el.removeEventListener("click", onFacadeClick);
+	}
+});
+//#endregion
 //#region src/plugins/spa/index.ts
 /**
 * @file spa — Complex Plugin (WIRING ONLY, ≤30 lines). All logic lives in the
@@ -5115,4 +5198,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Env, types_exports$3 as Head, types_exports$4 as Log, types_exports$5 as Router, types_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Env, types_exports$3 as Head, types_exports$4 as Log, types_exports$5 as Router, types_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };