@moku-labs/web 1.10.0 → 1.12.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";
 
@@ -1927,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, GalleryComponent, GalleryOptions, GalleryProps, GallerySlide, GalleryTransformOptions, LoadAllOptions, MermaidDiagramOptions, State };
 }
 /**
  * YAML frontmatter parsed from each article file.
@@ -2071,6 +2071,115 @@ 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;
+};
+/** One resolved gallery slide handed to a {@link GalleryComponent}. */
+type GallerySlide = {
+  /** Shared absolute image URL (`/<slug>/<dir>/<file>`), identical from every locale page. */src: string; /** Per-slide alt text (the directive `caption` with a ` · N` index suffix, or just `N`). */
+  alt: string;
+};
+/**
+ * Props handed to a `::gallery` component (the swipeable image set the framework
+ * renders to static markup at build time). The framework resolves the directive's
+ * `src` folder to the sorted, URL-rewritten {@link GallerySlide} list; `caption` is
+ * the directive's `caption` attribute; `attributes` is the full raw directive
+ * attribute bag, so a custom component can read arbitrary extra options
+ * (e.g. `::gallery{… layout="dots"}`).
+ *
+ * @example
+ * ```tsx
+ * const Gallery = ({ slides, caption }: GalleryProps) => (
+ *   <div class="gallery-track">
+ *     {slides.map(s => <img src={s.src} alt={s.alt} />)}
+ *   </div>
+ * );
+ * ```
+ */
+type GalleryProps = {
+  /** The resolved slides, in folder order. */slides: readonly GallerySlide[]; /** The directive's `caption` attribute (empty string when unset). */
+  caption: string; /** The full raw directive attribute bag (custom options live here). */
+  attributes: Readonly<Record<string, string>>;
+};
+/**
+ * A consumer-supplied gallery component: a Preact function component over
+ * {@link GalleryProps}, rendered (at build time, to static markup) as the inner
+ * content — inside the framework-owned `<div data-component="gallery">` that carries
+ * the island hook. Defaults to the built-in `GalleryTrack`.
+ */
+type GalleryComponent = FunctionComponent<GalleryProps>;
+/**
+ * Options for the `::gallery` feature (the `gallery` key of
+ * {@link FileSystemContentOptions}). `gallery: true` uses the default component;
+ * `gallery: { component }` swaps in a consumer Preact component.
+ *
+ * @example
+ * ```ts
+ * fileSystemContent({ contentDir: "./content", trustedContent: true, gallery: { component: MyGallery } });
+ * ```
+ */
+type GalleryOptions = {
+  /**
+   * Consumer Preact component rendering the gallery's inner content (SSR'd to
+   * static markup at build). Receives {@link GalleryProps}. Defaults to the
+   * built-in `GalleryTrack`.
+   */
+  component?: GalleryComponent;
+};
+/**
+ * Resolved gallery transform inputs — {@link GalleryOptions} plus the provider's
+ * `contentDir` (needed to read the directive's `src` folder from disk). Assembled
+ * by the pipeline wiring; not part of the public config surface.
+ */
+type GalleryTransformOptions = GalleryOptions & {
+  /** The provider's content directory (folder reads resolve against it). */contentDir: string;
+};
 /**
  * Options for the node filesystem provider {@link ContentProvider} `fileSystemContent`.
  * These are the markdown-pipeline + source concerns that used to live on the content
@@ -2110,10 +2219,22 @@ type FileSystemContentOptions = {
    * 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">`.
-   * Requires `trustedContent: true` (the facade is raw HTML the sanitize pass
-   * would strip). Defaults to disabled.
-   */
-  embed?: boolean;
+   * `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;
+  /**
+   * Folder galleries: rewrite `::gallery{src="./images/dir/" caption="…"}` leaf
+   * directives into a swipeable image set. The framework reads the co-located
+   * `src` folder, sorts its images, rewrites each to its shared `/<slug>/…` URL,
+   * and renders them through a consumer Preact component (pair it with a gallery
+   * SPA island for swipe/keyboard/lightbox). `true` enables with the default
+   * component; an object passes {@link GalleryOptions} (e.g. a consumer
+   * `component`). Requires `trustedContent: true` (the markup is raw HTML the
+   * sanitize pass would strip). Defaults to disabled.
+   */
+  gallery?: boolean | GalleryOptions;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and

package/dist/browser.mjs

@@ -4466,7 +4466,11 @@ function activateEmbed(figure) {
 }
 /**
 * Shared click handler (module-level so mount/unmount detach the same
-* reference): a click on the facade's button activates the embed.
+* 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
@@ -4475,9 +4479,10 @@ function activateEmbed(figure) {
 * ```
 */
 function onFacadeClick(event) {
-	if (!event.target.closest("button.lazy-embed-button")) return;
 	const figure = event.currentTarget;
-	if (figure instanceof HTMLElement) activateEmbed(figure);
+	if (!(figure instanceof HTMLElement)) return;
+	if (figure.dataset.embedActive !== void 0) return;
+	activateEmbed(figure);
 }
 /**
 * Lazy-embed island: facade button click → real `<iframe loading="lazy">`.