datocms-plugin-media-layouts 0.1.0 → 0.1.1

package/README.md

@@ -9,10 +9,12 @@ A DatoCMS plugin that extends JSON fields to allow editors to select assets with
 - **Self-contained data**: Stores URL, filename, and all metadata directly in JSON—no additional API calls needed
 - **Three operational modes**: Single asset, multiple assets (gallery), or predefined layout slots
 - **Aspect ratio control**: 9 presets plus custom ratios for precise cropping
-- **Width presets**: Original (max) plus 320px mobile to 4K resolution
+- **Width presets**: Original (max) plus 320px mobile to 4K resolution, with named custom presets and custom widths
 - **Focal point support**: Preserves focal point data from DatoCMS media library
 - **Metadata editing**: Edit alt text, title, and focal point directly from the field
-- **Layout mode**: Define grid-based slot configurations with required fields
+- **Per-asset options**: Optional CSS class and lazy loading toggle per image
+- **Layout builder**: Grid or masonry layouts with drag-and-drop placement, slot spans, and auto-sizing from aspect ratio
+- **Layout metadata**: Optional layout aspect ratio + width for overall composition sizing
 - **Automatic height calculation**: Heights computed from width and aspect ratio for easy imgix integration
 
 ## Installation
@@ -34,6 +36,7 @@ Configure default values that apply to all fields using this plugin:
 |---------|-------------|---------|
 | Default Aspect Ratio | Applied to new assets when no field override exists | 16:9 |
 | Default Width | Applied to new assets when no field override exists | 1920px |
+| Width Presets | Named width options shown in all width selectors | (none) |
 
 ### Field Configuration
 
@@ -49,13 +52,26 @@ Select multiple images, each with independent layout settings. Stores an array o
 
 #### Layout Mode (Predefined Slots)
 
-Define a grid with named slots that editors fill with assets. Each slot has:
+Define a layout with named slots that editors fill with assets. Choose a style:
+
+- **Grid**: Explicit rows/columns (1–4 columns, 1–6 rows), slots placed in cells
+- **Masonry**: Column-based layout with variable heights and ordered slots
+
+Each slot has:
 - **Label**: Descriptive name (e.g., "Hero Image", "Sidebar Thumbnail")
-- **Aspect Ratio**: Fixed ratio for this slot
-- **Width**: Fixed output width for this slot (including Original)
+- **Aspect Ratio**: Fixed ratio for this slot (including Custom)
+- **Width**: Fixed output width for this slot (including Custom)
 - **Required**: Whether the slot must be filled
 
-Grid supports 1-4 columns and 1-6 rows.
+Layout builder enhancements:
+- **Drag-and-drop placement**: Move or swap slots directly in the preview
+- **Slot spans** (grid): Slots can span multiple rows/columns
+- **Auto size from aspect ratio** (grid): Let spans be calculated based on the slot ratio
+- **Column span** (masonry): Control the width of a masonry tile
+
+Optional layout metadata:
+- **Layout aspect ratio**: Auto, preset, or custom ratio for the overall composition
+- **Layout width**: Auto, preset, or custom width for the overall composition (used to compute layout dimensions)
 
 ### Field Overrides
 
@@ -63,6 +79,12 @@ For single/multiple modes, you can optionally override global defaults:
 - Toggle "Override default aspect ratio" to set a field-specific ratio
 - Toggle "Override default width" to set a field-specific width
 
+### Per-Asset Options
+
+You can optionally enable extra per-image fields:
+- **CSS class**: Text input to pass a custom class name
+- **Lazy loading**: Boolean toggle for lazy loading preference
+
 ## Aspect Ratio Options
 
 | Value | Label | Use Case |
@@ -92,6 +114,17 @@ For single/multiple modes, you can optionally override global defaults:
 | 2560px | 2K | High-resolution displays |
 | 3840px | 4K | Ultra HD displays |
 
+Custom widths are supported: select "Custom..." and enter any pixel value
+between 1 and 10000. Heights are still calculated automatically.
+
+You can also add named custom presets in the plugin configuration (label + width),
+which appear alongside the built-in options to guide editors with context-specific
+sizes.
+
+Custom presets are available in all width selectors (global defaults, field overrides,
+asset/slot width pickers, and layout width). Layout width excludes the "Original"
+option and supports Auto + Custom values.
+
 ## Data Model
 
 The plugin stores all asset data directly in the JSON field, including the URL. No additional API calls are needed to render images.
@@ -107,6 +140,8 @@ The plugin stores all asset data directly in the JSON field, including the URL.
   "size": 245000,
   "alt": "A beautiful sunset",
   "title": "Sunset at the beach",
+  "cssClass": "hero-image",
+  "lazyLoading": true,
   "focalPoint": { "x": 0.5, "y": 0.3 },
   "aspectRatio": "16:9",
   "width": 1920,
@@ -128,6 +163,8 @@ The plugin stores all asset data directly in the JSON field, including the URL.
     "size": 180000,
     "alt": "First image",
     "title": null,
+    "cssClass": "",
+    "lazyLoading": false,
     "focalPoint": null,
     "aspectRatio": "1:1",
     "width": 640,
@@ -143,6 +180,8 @@ The plugin stores all asset data directly in the JSON field, including the URL.
     "size": 320000,
     "alt": "Second image",
     "title": null,
+    "cssClass": "gallery-item",
+    "lazyLoading": true,
     "focalPoint": { "x": 0.3, "y": 0.5 },
     "aspectRatio": "4:3",
     "width": 1024,
@@ -156,40 +195,79 @@ The plugin stores all asset data directly in the JSON field, including the URL.
 ### Layout Mode
 
 ```json
-[
-  {
-    "slotId": "hero",
-    "uploadId": "abc123",
-    "url": "https://www.datocms-assets.com/12345/hero.jpg",
-    "filename": "hero.jpg",
-    "format": "jpg",
-    "size": 450000,
-    "alt": "Hero banner",
-    "title": null,
-    "focalPoint": { "x": 0.5, "y": 0.5 },
-    "aspectRatio": "21:9",
-    "width": 1920,
-    "height": 823,
-    "originalWidth": 4000,
-    "originalHeight": 2000
+{
+  "layout": {
+    "columns": 2,
+    "rows": 2,
+    "layoutStyle": "grid",
+    "layoutAspectRatio": "16:9",
+    "layoutWidth": 1920,
+    "slots": [
+      {
+        "id": "hero",
+        "label": "Hero",
+        "aspectRatio": "21:9",
+        "width": 1920,
+        "row": 0,
+        "col": 0,
+        "rowSpan": 1,
+        "colSpan": 2,
+        "autoSpan": false,
+        "required": true
+      },
+      {
+        "id": "sidebar",
+        "label": "Sidebar",
+        "aspectRatio": "1:1",
+        "width": 320,
+        "row": 1,
+        "col": 1,
+        "rowSpan": 1,
+        "colSpan": 1,
+        "autoSpan": false,
+        "required": false
+      }
+    ]
   },
-  {
-    "slotId": "sidebar",
-    "uploadId": "def456",
-    "url": "https://www.datocms-assets.com/12345/sidebar.jpg",
-    "filename": "sidebar.jpg",
-    "format": "jpg",
-    "size": 85000,
-    "alt": "Sidebar image",
-    "title": null,
-    "focalPoint": null,
-    "aspectRatio": "1:1",
-    "width": 320,
-    "height": 320,
-    "originalWidth": 800,
-    "originalHeight": 800
-  }
-]
+  "assignments": [
+    {
+      "slotId": "hero",
+      "uploadId": "abc123",
+      "url": "https://www.datocms-assets.com/12345/hero.jpg",
+      "filename": "hero.jpg",
+      "format": "jpg",
+      "size": 450000,
+      "alt": "Hero banner",
+      "title": null,
+      "cssClass": "hero-image",
+      "lazyLoading": true,
+      "focalPoint": { "x": 0.5, "y": 0.5 },
+      "aspectRatio": "21:9",
+      "width": 1920,
+      "height": 823,
+      "originalWidth": 4000,
+      "originalHeight": 2000
+    },
+    {
+      "slotId": "sidebar",
+      "uploadId": "def456",
+      "url": "https://www.datocms-assets.com/12345/sidebar.jpg",
+      "filename": "sidebar.jpg",
+      "format": "jpg",
+      "size": 85000,
+      "alt": "Sidebar image",
+      "title": null,
+      "cssClass": "",
+      "lazyLoading": false,
+      "focalPoint": null,
+      "aspectRatio": "1:1",
+      "width": 320,
+      "height": 320,
+      "originalWidth": 800,
+      "originalHeight": 800
+    }
+  ]
+}
 ```
 
 ### TypeScript Types
@@ -203,6 +281,8 @@ type MediaLayoutItem = {
   size: number;
   alt: string | null;
   title: string | null;
+  cssClass?: string;
+  lazyLoading?: boolean;
   focalPoint: { x: number; y: number } | null;
   aspectRatio: string;
   customAspectRatio?: string; // When aspectRatio is "custom"
@@ -212,6 +292,30 @@ type MediaLayoutItem = {
   originalHeight: number | null;
 };
 
+type LayoutSlot = {
+  id: string;
+  label: string;
+  aspectRatio: string;
+  customAspectRatio?: string; // When aspectRatio is "custom"
+  width: number | 'original';
+  row: number;
+  col: number;
+  rowSpan?: number;
+  colSpan?: number;
+  autoSpan?: boolean;
+  required: boolean;
+};
+
+type LayoutConfig = {
+  slots: LayoutSlot[];
+  columns: number;
+  rows: number;
+  layoutStyle?: 'grid' | 'masonry';
+  layoutAspectRatio?: string;
+  layoutCustomAspectRatio?: string;
+  layoutWidth?: number;
+};
+
 // Single mode value
 type SingleFieldValue = MediaLayoutItem | null;
 
@@ -220,7 +324,10 @@ type MultipleFieldValue = MediaLayoutItem[];
 
 // Layout mode value
 type SlotAssignment = MediaLayoutItem & { slotId: string };
-type LayoutFieldValue = SlotAssignment[];
+type LayoutFieldValue = {
+  layout: LayoutConfig;
+  assignments: SlotAssignment[];
+};
 ```
 
 ## Usage with imgix