zone5 1.3.2 → 1.5.0

package/README.md

@@ -90,6 +90,64 @@ widths = [400, 800, 1200, 1600, 2400]
 <Zone5 images={[image1, image2]} />
 ```
 
+### Layout Modes
+
+Zone5 supports three layout modes:
+
+#### Justified Mode (Default)
+
+Row-based layout (like Flickr/Google Photos). Each row fills the full width while preserving aspect ratios. Panoramic images (aspect ratio > 3) automatically get their own row.
+
+```svelte
+<Zone5 images={images} mode="justified" />
+
+<!-- With custom row height and gap -->
+<Zone5
+  images={images}
+  mode="justified"
+  targetRowHeight={250}
+  gap={12}
+/>
+```
+
+#### Wall Mode
+
+Fixed-height grid layout. Images are cropped to fill their containers.
+
+```svelte
+<Zone5 images={images} mode="wall" />
+```
+
+#### Waterfall Mode
+
+Column-based masonry layout. Images are distributed across columns and maintain their aspect ratios.
+
+```svelte
+<Zone5 images={images} mode="waterfall" />
+
+<!-- With custom column breakpoints -->
+<Zone5
+  images={images}
+  mode="waterfall"
+  columnBreakpoints={{ 640: 2, 1024: 4 }}
+/>
+```
+
+### Setting Mode in Markdown
+
+Use the `zone5mode` frontmatter property:
+
+```markdown
+---
+zone5mode: justified
+---
+
+![Photo 1](./photo1.jpg?z5)
+![Photo 2](./photo2.jpg?z5)
+```
+
+Valid values: `wall`, `waterfall`, `justified`
+
 ### Using in Markdown/MDX
 
 Add the remark plugin to your `svelte.config.js`:

package/dist/cli/index.js

@@ -8198,7 +8198,15 @@ async function vh(t, i, a, n) {
   }
 }
 async function wh(t, i) {
-  const n = `# Photo Gallery
+  const n = `---
+# Zone5 Gallery Configuration
+# https://cwygoda.github.io/zone5/docs/reference/remark-plugin-api#frontmatter-options
+
+# Gallery layout mode: "justified" (default) | "wall" | "waterfall"
+# zone5mode: justified
+---
+
+# Photo Gallery
 
 ${i.map(({ relativePath: s }) => {
     const l = Rt(s);

package/dist/components/Zone5.svelte

@@ -5,21 +5,32 @@
 	import Zone5Single from './Zone5Single.svelte';
 	import Zone5Wall from './Zone5Wall.svelte';
 	import Zone5Waterfall from './Zone5Waterfall.svelte';
-	import { DEFAULT_COLUMN_BREAKPOINTS } from './constants';
+	import Zone5Justified from './Zone5Justified.svelte';
+	import {
+		DEFAULT_COLUMN_BREAKPOINTS,
+		DEFAULT_TARGET_ROW_HEIGHT,
+		DEFAULT_GAP,
+	} from './constants';
 	import type { ImageData } from './types';
 
 	interface Props {
-		columnBreakpoints?: { [key: number]: number };
 		images: ImageData[];
-		mode?: 'wall' | 'waterfall';
+		mode?: 'wall' | 'waterfall' | 'justified';
 		nocaption?: boolean;
+		// Waterfall mode options
+		columnBreakpoints?: { [key: number]: number };
+		// Justified mode options
+		targetRowHeight?: number;
+		gap?: number;
 	}
 
 	let {
-		columnBreakpoints = DEFAULT_COLUMN_BREAKPOINTS,
 		images,
-		mode = 'wall',
+		mode = 'justified',
 		nocaption = false,
+		columnBreakpoints = DEFAULT_COLUMN_BREAKPOINTS,
+		targetRowHeight = DEFAULT_TARGET_ROW_HEIGHT,
+		gap = DEFAULT_GAP,
 	}: Props = $props();
 
 	const imageStore = useImageRegistry();
@@ -71,4 +82,11 @@
 		{images}
 		onImageClick={imageStore ? handleImageClick : undefined}
 	/>
+{:else if mode === 'justified'}
+	<Zone5Justified
+		{images}
+		{targetRowHeight}
+		{gap}
+		onImageClick={imageStore ? handleImageClick : undefined}
+	/>
 {/if}

package/dist/components/Zone5.svelte.d.ts

@@ -1,11 +1,13 @@
 import type { ImageData } from './types';
 interface Props {
+    images: ImageData[];
+    mode?: 'wall' | 'waterfall' | 'justified';
+    nocaption?: boolean;
     columnBreakpoints?: {
         [key: number]: number;
     };
-    images: ImageData[];
-    mode?: 'wall' | 'waterfall';
-    nocaption?: boolean;
+    targetRowHeight?: number;
+    gap?: number;
 }
 declare const Zone5: import("svelte").Component<Props, {}, "">;
 type Zone5 = ReturnType<typeof Zone5>;

package/dist/components/Zone5Justified.svelte

@@ -0,0 +1,128 @@
+<script lang="ts">
+	import Img from './Zone5Img.svelte';
+	import { DEFAULT_TARGET_ROW_HEIGHT, DEFAULT_GAP, PANORAMA_THRESHOLD } from './constants';
+	import type { ImageData } from './types';
+
+	interface Props {
+		images: ImageData[];
+		onImageClick?: (index: number) => void;
+		targetRowHeight?: number;
+		gap?: number;
+	}
+
+	let {
+		images,
+		onImageClick,
+		targetRowHeight = DEFAULT_TARGET_ROW_HEIGHT,
+		gap = DEFAULT_GAP,
+	}: Props = $props();
+
+	let containerWidth = $state(0);
+
+	interface JustifiedRow {
+		images: { image: ImageData; idx: number }[];
+		height: number;
+	}
+
+	/**
+	 * Calculate the row height that makes all images fit the container width exactly.
+	 * Formula: h = (containerWidth - totalGaps) / sum(aspectRatios)
+	 */
+	function calculateRowHeight(
+		row: { image: ImageData; idx: number }[],
+		width: number,
+		gapSize: number,
+	): number {
+		const aspectRatioSum = row.reduce((sum, item) => sum + item.image.properties.aspectRatio, 0);
+		const totalGapWidth = (row.length - 1) * gapSize;
+		const availableWidth = width - totalGapWidth;
+		return availableWidth / aspectRatioSum;
+	}
+
+	/**
+	 * Calculate justified rows using a greedy algorithm.
+	 * Images are added to rows until the row height drops to or below the target height.
+	 */
+	let rows = $derived.by((): JustifiedRow[] => {
+		if (images.length === 0) {
+			return [];
+		}
+
+		// Use containerWidth if available, otherwise fall back to a default for SSR/testing
+		const effectiveWidth = containerWidth > 0 ? containerWidth : 1200;
+
+		const result: JustifiedRow[] = [];
+		let currentRow: { image: ImageData; idx: number }[] = [];
+
+		for (let i = 0; i < images.length; i++) {
+			const image = images[i];
+			const aspectRatio = image.properties.aspectRatio;
+
+			// Handle panoramas: if we have images in the current row, finalize it first
+			if (aspectRatio > PANORAMA_THRESHOLD && currentRow.length > 0) {
+				result.push({
+					images: [...currentRow],
+					height: calculateRowHeight(currentRow, effectiveWidth, gap),
+				});
+				currentRow = [];
+			}
+
+			currentRow.push({ image, idx: i });
+
+			// Panorama gets its own row with height capped at target
+			if (aspectRatio > PANORAMA_THRESHOLD) {
+				const panoramaHeight = Math.min(effectiveWidth / aspectRatio, targetRowHeight);
+				result.push({
+					images: [...currentRow],
+					height: panoramaHeight,
+				});
+				currentRow = [];
+				continue;
+			}
+
+			const rowHeight = calculateRowHeight(currentRow, effectiveWidth, gap);
+
+			// If row height is at or below target, finalize this row
+			if (rowHeight <= targetRowHeight) {
+				result.push({
+					images: [...currentRow],
+					height: rowHeight,
+				});
+				currentRow = [];
+			}
+		}
+
+		// Handle last row: left-align by capping height at target
+		if (currentRow.length > 0) {
+			const calculatedHeight = calculateRowHeight(currentRow, effectiveWidth, gap);
+			result.push({
+				images: currentRow,
+				height: Math.min(calculatedHeight, targetRowHeight),
+			});
+		}
+
+		return result;
+	});
+</script>
+
+<div
+	class="zone5-justified flex flex-col"
+	bind:clientWidth={containerWidth}
+	role="list"
+	style:gap="{gap}px"
+>
+	{#each rows as row, rowIdx (rowIdx)}
+		<div class="zone5-justified-row flex" style:height="{row.height}px" style:gap="{gap}px">
+			{#each row.images as { image, idx } (idx)}
+				<div
+					class="zone5-justified-item shrink-0"
+					role="listitem"
+					style:width="{row.height * image.properties.aspectRatio}px"
+					style:height="{row.height}px"
+				>
+					<Img {image} cover class="w-full h-full" onclick={onImageClick ? () => onImageClick(idx) : undefined} />
+				</div>
+			{/each}
+		</div>
+	{/each}
+</div>

package/dist/components/Zone5Justified.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { ImageData } from './types';
+interface Props {
+    images: ImageData[];
+    onImageClick?: (index: number) => void;
+    targetRowHeight?: number;
+    gap?: number;
+}
+declare const Zone5Justified: import("svelte").Component<Props, {}, "">;
+type Zone5Justified = ReturnType<typeof Zone5Justified>;
+export default Zone5Justified;

package/dist/components/constants.d.ts

@@ -7,6 +7,19 @@ export declare const DEFAULT_COLUMN_BREAKPOINTS: {
     readonly 768: 3;
     readonly 1024: 4;
 };
+/**
+ * Default target row height for justified mode in pixels.
+ */
+export declare const DEFAULT_TARGET_ROW_HEIGHT = 300;
+/**
+ * Default gap between images in justified mode in pixels.
+ */
+export declare const DEFAULT_GAP = 8;
+/**
+ * Aspect ratio threshold for panoramic images.
+ * Images with aspect ratio greater than this get their own row in justified mode.
+ */
+export declare const PANORAMA_THRESHOLD = 3;
 /**
  * Height for single image in wall mode (Tailwind class)
  */

package/dist/components/constants.js

@@ -7,6 +7,19 @@ export const DEFAULT_COLUMN_BREAKPOINTS = {
     768: 3, // md: 3 columns
     1024: 4, // lg: 4 columns
 };
+/**
+ * Default target row height for justified mode in pixels.
+ */
+export const DEFAULT_TARGET_ROW_HEIGHT = 300;
+/**
+ * Default gap between images in justified mode in pixels.
+ */
+export const DEFAULT_GAP = 8;
+/**
+ * Aspect ratio threshold for panoramic images.
+ * Images with aspect ratio greater than this get their own row in justified mode.
+ */
+export const PANORAMA_THRESHOLD = 3.0;
 /**
  * Height for single image in wall mode (Tailwind class)
  */

package/dist/config.d.ts

@@ -18,6 +18,31 @@ declare const ConfigSchema: z.ZodObject<{
         resize_gamma: z.ZodOptional<z.ZodNumber>;
         variants: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
     }, z.core.$strip>>>;
+    gallery: z.ZodPrefault<z.ZodPipe<z.ZodPrefault<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            wall: "wall";
+            waterfall: "waterfall";
+            justified: "justified";
+        }>>;
+        columnBreakpoints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        targetRowHeight: z.ZodOptional<z.ZodNumber>;
+        gap: z.ZodOptional<z.ZodNumber>;
+        panoramaThreshold: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>, z.ZodTransform<{
+        columnBreakpoints: {
+            [k: string]: number;
+        } | undefined;
+        mode?: "wall" | "waterfall" | "justified" | undefined;
+        targetRowHeight?: number | undefined;
+        gap?: number | undefined;
+        panoramaThreshold?: number | undefined;
+    }, {
+        mode?: "wall" | "waterfall" | "justified" | undefined;
+        columnBreakpoints?: Record<string, number> | undefined;
+        targetRowHeight?: number | undefined;
+        gap?: number | undefined;
+        panoramaThreshold?: number | undefined;
+    }>>>;
 }, z.core.$strip>;
 export type ConfigType = z.infer<typeof ConfigSchema>;
 export declare const walkUntilFound: (path: string) => Promise<string | undefined>;
@@ -32,6 +57,15 @@ export declare const load: (configDir?: string | undefined) => Promise<{
         variants: number[];
         resize_gamma?: number | undefined;
     };
+    gallery: {
+        columnBreakpoints: {
+            [k: string]: number;
+        } | undefined;
+        mode?: "wall" | "waterfall" | "justified" | undefined;
+        targetRowHeight?: number | undefined;
+        gap?: number | undefined;
+        panoramaThreshold?: number | undefined;
+    };
 } | {
     src: string;
     base: {
@@ -44,6 +78,15 @@ export declare const load: (configDir?: string | undefined) => Promise<{
         variants: number[];
         resize_gamma?: number | undefined;
     };
+    gallery: {
+        columnBreakpoints: {
+            [k: string]: number;
+        } | undefined;
+        mode?: "wall" | "waterfall" | "justified" | undefined;
+        targetRowHeight?: number | undefined;
+        gap?: number | undefined;
+        panoramaThreshold?: number | undefined;
+    };
 }>;
 export declare const toToml: (config: ConfigType & {
     src?: string;

package/dist/config.js

@@ -5,6 +5,7 @@ import { stringify } from 'smol-toml';
 import { z } from 'zod';
 import { loadConfig } from 'zod-config';
 import { tomlAdapter } from 'zod-config/toml-adapter';
+import { GalleryConfigSchema } from './gallery/config.js';
 import { ProcessorConfigSchema } from './processor/config.js';
 const BaseConfigSchema = z.object({
     root: z.string().default(cwd()),
@@ -14,6 +15,7 @@ const BaseConfigSchema = z.object({
 const ConfigSchema = z.object({
     base: BaseConfigSchema.prefault({}),
     processor: ProcessorConfigSchema.prefault({}),
+    gallery: GalleryConfigSchema.prefault({}),
 });
 export const walkUntilFound = async (path) => {
     try {

package/dist/gallery/config.d.ts

@@ -0,0 +1,32 @@
+import z from 'zod';
+/**
+ * Schema for gallery configuration in .zone5.toml
+ *
+ * These values override the component defaults.
+ */
+export declare const GalleryConfigSchema: z.ZodPipe<z.ZodPrefault<z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+        wall: "wall";
+        waterfall: "waterfall";
+        justified: "justified";
+    }>>;
+    columnBreakpoints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    targetRowHeight: z.ZodOptional<z.ZodNumber>;
+    gap: z.ZodOptional<z.ZodNumber>;
+    panoramaThreshold: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>, z.ZodTransform<{
+    columnBreakpoints: {
+        [k: string]: number;
+    } | undefined;
+    mode?: "wall" | "waterfall" | "justified" | undefined;
+    targetRowHeight?: number | undefined;
+    gap?: number | undefined;
+    panoramaThreshold?: number | undefined;
+}, {
+    mode?: "wall" | "waterfall" | "justified" | undefined;
+    columnBreakpoints?: Record<string, number> | undefined;
+    targetRowHeight?: number | undefined;
+    gap?: number | undefined;
+    panoramaThreshold?: number | undefined;
+}>>;
+export type GalleryConfig = z.output<typeof GalleryConfigSchema>;

package/dist/gallery/config.js

@@ -0,0 +1,27 @@
+import z from 'zod';
+/**
+ * Schema for gallery configuration in .zone5.toml
+ *
+ * These values override the component defaults.
+ */
+export const GalleryConfigSchema = z
+    .object({
+    /** Default gallery layout mode */
+    mode: z.enum(['wall', 'waterfall', 'justified']).optional(),
+    /** Viewport width to column count mapping for waterfall mode */
+    columnBreakpoints: z.record(z.string(), z.number().int().positive()).optional(),
+    /** Target row height in pixels for justified mode */
+    targetRowHeight: z.number().int().positive().optional(),
+    /** Gap between images in pixels for justified mode */
+    gap: z.number().int().nonnegative().optional(),
+    /** Aspect ratio threshold for panoramic images in justified mode */
+    panoramaThreshold: z.number().positive().optional(),
+})
+    .prefault({})
+    .transform((data) => ({
+    ...data,
+    // Convert string keys to numbers for columnBreakpoints
+    columnBreakpoints: data.columnBreakpoints
+        ? Object.fromEntries(Object.entries(data.columnBreakpoints).map(([k, v]) => [parseInt(k, 10), v]))
+        : undefined,
+}));

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { load } from './config.js';
 export type { BaseConfigType, ConfigType } from './config.js';
+export type { GalleryConfig } from './gallery/config.js';
 export { default, default as processor } from './processor/index.js';
 export type * from './processor/index.js';
 export type * from './components/types.js';

package/dist/remark.d.ts

@@ -1,5 +1,15 @@
 import type { Plugin } from 'unified';
+import type { GalleryConfig } from './gallery/config.js';
+/**
+ * Options for the remarkZ5Images plugin
+ */
+export interface RemarkZ5ImagesOptions {
+    /** Gallery configuration from .zone5.toml */
+    gallery?: GalleryConfig;
+}
 /**
  * Remark plugin to process Zone5 images
+ *
+ * @param options - Plugin options including gallery config from .zone5.toml
  */
-export declare const remarkZ5Images: Plugin;
+export declare const remarkZ5Images: Plugin<[RemarkZ5ImagesOptions?]>;

package/dist/remark.js

@@ -25,10 +25,56 @@ function buildImagesExpression(imageData) {
     const imageExpressions = imageData.map((img) => `{...${img.key}, properties: {...${img.key}.properties, alt: ${JSON.stringify(img.alt)}, title: ${JSON.stringify(img.title)}}}`);
     return '[' + imageExpressions.join(',') + ']';
 }
+/**
+ * Create a string property node
+ */
+function createStringProperty(name, value) {
+    return {
+        type: 'svelteProperty',
+        name,
+        shorthand: 'none',
+        value: [{ type: 'text', value }],
+        modifiers: [],
+    };
+}
+/**
+ * Create a numeric property node (as expression)
+ */
+function createNumberProperty(name, value) {
+    return {
+        type: 'svelteProperty',
+        name,
+        shorthand: 'none',
+        value: [
+            {
+                type: 'svelteDynamicContent',
+                expression: { type: 'svelteExpression', value: String(value) },
+            },
+        ],
+        modifiers: [],
+    };
+}
+/**
+ * Create an object property node (as expression)
+ */
+function createObjectProperty(name, value) {
+    return {
+        type: 'svelteProperty',
+        name,
+        shorthand: 'none',
+        value: [
+            {
+                type: 'svelteDynamicContent',
+                expression: { type: 'svelteExpression', value: JSON.stringify(value) },
+            },
+        ],
+        modifiers: [],
+    };
+}
 /**
  * Create a Zone5 Svelte component node
  */
-function createZone5Component(imageData, mode) {
+function createZone5Component(imageData, options) {
     const properties = [
         {
             type: 'svelteProperty',
@@ -46,19 +92,17 @@ function createZone5Component(imageData, mode) {
             modifiers: [],
         },
     ];
-    if (mode) {
-        properties.push({
-            type: 'svelteProperty',
-            name: 'mode',
-            shorthand: 'none',
-            value: [
-                {
-                    type: 'text',
-                    value: mode,
-                },
-            ],
-            modifiers: [],
-        });
+    if (options.mode) {
+        properties.push(createStringProperty('mode', options.mode));
+    }
+    if (options.columnBreakpoints) {
+        properties.push(createObjectProperty('columnBreakpoints', options.columnBreakpoints));
+    }
+    if (options.targetRowHeight !== undefined) {
+        properties.push(createNumberProperty('targetRowHeight', options.targetRowHeight));
+    }
+    if (options.gap !== undefined) {
+        properties.push(createNumberProperty('gap', options.gap));
     }
     return {
         type: 'svelteComponent',
@@ -174,14 +218,26 @@ function createScriptElement(importMap) {
 }
 /**
  * Remark plugin to process Zone5 images
+ *
+ * @param options - Plugin options including gallery config from .zone5.toml
  */
-export const remarkZ5Images = () => {
+export const remarkZ5Images = (options = {}) => {
+    const galleryConfig = (options.gallery ?? {});
     return (tree, file) => {
         const rootTree = tree;
         const importMap = {};
         const existingKeys = new Set();
+        // Get frontmatter values (these override config)
         const fm = file.data.fm;
-        const zone5mode = fm?.zone5mode;
+        const frontmatterMode = fm?.zone5mode;
+        // Merge config with frontmatter (frontmatter takes precedence)
+        const resolvedOptions = {
+            mode: frontmatterMode ?? galleryConfig.mode,
+            columnBreakpoints: galleryConfig.columnBreakpoints,
+            targetRowHeight: galleryConfig.targetRowHeight,
+            gap: galleryConfig.gap,
+            panoramaThreshold: galleryConfig.panoramaThreshold,
+        };
         // First, collect all Z5 images for the import map
         visit(rootTree, 'image', (node) => {
             if (isZ5Image(node)) {
@@ -199,7 +255,7 @@ export const remarkZ5Images = () => {
                     const paragraph = child;
                     const z5Images = paragraph.children.filter((ch) => isZ5Image(ch));
                     const imageData = collectImageData(z5Images, existingKeys);
-                    const svelteComponent = createZone5Component(imageData, zone5mode);
+                    const svelteComponent = createZone5Component(imageData, resolvedOptions);
                     // Replace the multi-image paragraph with the svelte component
                     node.children.splice(i, 1, svelteComponent);
                 }
@@ -214,7 +270,7 @@ export const remarkZ5Images = () => {
                     .map((index) => getImageFromParagraph(node.children[index]))
                     .filter((img) => img !== null);
                 const imageData = collectImageData(imageNodes, existingKeys);
-                const svelteComponent = createZone5Component(imageData, zone5mode);
+                const svelteComponent = createZone5Component(imageData, resolvedOptions);
                 // Calculate how many nodes to remove (including newlines)
                 const startIndex = group[0];
                 const endIndex = group[group.length - 1];
@@ -234,7 +290,7 @@ export const remarkZ5Images = () => {
                 if (isZ5ImageParagraph(child) && child.type === 'paragraph') {
                     const imageNode = child.children[0];
                     const imageData = collectImageData([imageNode], existingKeys);
-                    const svelteComponent = createZone5Component(imageData, zone5mode);
+                    const svelteComponent = createZone5Component(imageData, resolvedOptions);
                     // Replace the single image paragraph with the svelte component
                     node.children.splice(i, 1, svelteComponent);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "zone5",
-	"version": "1.3.2",
+	"version": "1.5.0",
 	"repository": {
 		"url": "https://github.com/cwygoda/zone5"
 	},