@moku-labs/web 1.11.0 → 1.12.0

package/dist/index.d.cts

@@ -2671,7 +2671,7 @@ type Api$1 = {
  */
 declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
 declare namespace types_d_exports$2 {
-  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, EmbedFacade, EmbedFacadeProps, EmbedOptions, 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.
@@ -2864,6 +2864,66 @@ type EmbedOptions = {
    */
   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
@@ -2908,6 +2968,17 @@ type FileSystemContentOptions = {
    * (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
@@ -3667,6 +3738,26 @@ declare function fileSystemContent(options: FileSystemContentOptions): ContentPr
  */
 declare function EmbedFacadeButton(props: EmbedFacadeProps): VNode;
 //#endregion
+//#region src/plugins/content/pipeline/gallery-default.d.ts
+/**
+ * Default `::gallery` inner content: a single track holding every slide `<img>`
+ * in folder order. A companion gallery island (consumer-provided) can enhance
+ * the track with swipe/keyboard/lightbox; with no island and no CSS it is still
+ * a plain horizontally-scrollable image strip. Provided as the default and as a
+ * composable building block for custom galleries.
+ *
+ * @param props - The gallery props (the resolved `slides`).
+ * @returns The gallery inner-content VNode.
+ * @example
+ * ```tsx
+ * // Compose the default inside a richer custom gallery:
+ * const MyGallery = (p: GalleryProps) => (
+ *   <figure><GalleryTrack {...p} /><figcaption>{p.caption}</figcaption></figure>
+ * );
+ * ```
+ */
+declare function GalleryTrack(props: GalleryProps): VNode;
+//#endregion
 //#region src/index.d.ts
 /**
  * Create and initialize a `@moku-labs/web` application — the Layer-3 entry point.
@@ -3773,4 +3864,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, 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 Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, types_d_exports$5 as Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/index.d.mts

@@ -2671,7 +2671,7 @@ type Api$1 = {
  */
 declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
 declare namespace types_d_exports$2 {
-  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, EmbedFacade, EmbedFacadeProps, EmbedOptions, 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.
@@ -2864,6 +2864,66 @@ type EmbedOptions = {
    */
   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
@@ -2908,6 +2968,17 @@ type FileSystemContentOptions = {
    * (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
@@ -3667,6 +3738,26 @@ declare function fileSystemContent(options: FileSystemContentOptions): ContentPr
  */
 declare function EmbedFacadeButton(props: EmbedFacadeProps): VNode;
 //#endregion
+//#region src/plugins/content/pipeline/gallery-default.d.ts
+/**
+ * Default `::gallery` inner content: a single track holding every slide `<img>`
+ * in folder order. A companion gallery island (consumer-provided) can enhance
+ * the track with swipe/keyboard/lightbox; with no island and no CSS it is still
+ * a plain horizontally-scrollable image strip. Provided as the default and as a
+ * composable building block for custom galleries.
+ *
+ * @param props - The gallery props (the resolved `slides`).
+ * @returns The gallery inner-content VNode.
+ * @example
+ * ```tsx
+ * // Compose the default inside a richer custom gallery:
+ * const MyGallery = (p: GalleryProps) => (
+ *   <figure><GalleryTrack {...p} /><figcaption>{p.caption}</figcaption></figure>
+ * );
+ * ```
+ */
+declare function GalleryTrack(props: GalleryProps): VNode;
+//#endregion
 //#region src/index.d.ts
 /**
  * Create and initialize a `@moku-labs/web` application — the Layer-3 entry point.
@@ -3773,4 +3864,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, 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 Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, types_d_exports$5 as Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };