@moku-labs/web 1.11.0 → 1.12.1

package/dist/browser.d.mts

@@ -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, 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.
@@ -2120,6 +2120,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
@@ -2164,6 +2224,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

package/dist/browser.mjs

@@ -3738,6 +3738,17 @@ async function performNavigation(pathname, handlers, signal) {
 	}
 }
 /**
+* Whether the user has asked the platform to minimise motion.
+*
+* @returns `true` when `(prefers-reduced-motion: reduce)` currently matches; `false` when
+*   it does not, or when `matchMedia` is absent (guards SSR/test environments).
+* @example
+* const behavior: ScrollBehavior = prefersReducedMotion() ? "instant" : "smooth";
+*/
+function prefersReducedMotion() {
+	return typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+/**
 * Run a DOM-mutating swap, optionally wrapped in the View Transitions API when
 * enabled and supported (instant swap otherwise — never throws).
 *
@@ -3758,7 +3769,7 @@ async function performNavigation(pathname, handlers, signal) {
 * runSwap(() => current.replaceWith(next), true, () => scrollTo({ top: 0, behavior: "instant" }));
 */
 function runSwap(doSwap, viewTransitions, beforeCapture) {
-	const reduced = typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
+	const reduced = prefersReducedMotion();
 	const docWithVt = document;
 	const canUseViewTransitions = viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function";
 	beforeCapture?.();
@@ -3856,7 +3867,7 @@ function attachHistoryFallback(handlers, navigate = (pathname, _scrollToTop, sig
 		if (pathWithSearch(url) === pathWithSearch(location)) {
 			window.scrollTo({
 				top: 0,
-				behavior: "smooth"
+				behavior: prefersReducedMotion() ? "instant" : "smooth"
 			});
 			return;
 		}
@@ -3910,7 +3921,7 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname, _scroll
 			navEvent.intercept({ handler: () => {
 				window.scrollTo({
 					top: 0,
-					behavior: "smooth"
+					behavior: prefersReducedMotion() ? "instant" : "smooth"
 				});
 				return Promise.resolve();
 			} });
@@ -4087,26 +4098,30 @@ function createSpaKernel(state, config, emit, deps) {
 	let pendingScrollToTop = true;
 	/**
 	* Apply the in-flight navigation's scroll intent — the swap's `beforeCapture` hook.
-	* For a forward nav it scrolls to top BEFORE the snapshot is captured, so the old and
-	* new states share scrollY=0 (no delta → the sticky header never un-pins) and there is
-	* no pre-fetch scroll pause. Traverse (back/forward) sets `pendingScrollToTop = false`
-	* and restores its saved position after the swap instead.
+	* For a forward nav it scrolls to top BEFORE the swap (and, with view transitions on,
+	* before the "old" snapshot is captured), so the old and new states share scrollY=0:
+	* no delta for a transition to animate → a `position: sticky` header never un-pins.
+	* Traverse (back/forward) sets `pendingScrollToTop = false` and restores its saved
+	* position after the swap instead.
 	*
-	* Scroll behaviour: `"instant"` ONLY when view transitions are enabled — that is what
-	* keeps scrollY=0 in the captured snapshot (a `scroll-behavior: smooth` would otherwise
-	* animate the reset and re-create the delta → sticky-header flicker). With view
-	* transitions OFF there is no snapshot to protect, so it honours the page's
-	* `scroll-behavior` (`"auto"` = use the CSS value, e.g. a smooth scroll-to-top on nav).
+	* The reset is ALWAYS `"instant"`, never the CSS-driven `"auto"`. It runs synchronously
+	* immediately before the swap, and the swap mutates document height (the outgoing page is
+	* usually taller than the incoming one). A smooth scroll — from `behavior: "smooth"` or a
+	* page `scroll-behavior: smooth` that `"auto"` would inherit — is still animating when that
+	* height change lands; the browser clamps scrollY to the new, smaller maximum and cancels
+	* the in-flight animation there (worst on WebKit), stranding the page near the OLD position
+	* instead of the top. Instant lands scrollY=0 before the swap, every time. (A smooth
+	* scroll-to-top on the SAME page is unaffected — the router's same-page handler animates
+	* it, where there is no swap to race.)
 	*
 	* @example
 	* runSwap(renderAndMount, viewTransitions, applyPendingScroll);
 	*/
 	const applyPendingScroll = () => {
 		if (!pendingScrollToTop) return;
-		const behavior = resolved.viewTransitions ? "instant" : "auto";
 		window.scrollTo({
 			top: 0,
-			behavior
+			behavior: "instant"
 		});
 	};
 	/**