@byline/ui 1.6.2 → 1.7.1

package/dist/fields/image/image-field.js

@@ -1,8 +1,10 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useState } from "react";
 import { isPendingStoredFileValue } from "@byline/core";
 import classnames from "classnames";
 import { useFieldError, useFieldValue, useFormContext, useIsDirty } from "../../forms/form-context.js";
 import { ErrorText } from "../../uikit.js";
+import { ImageLightbox } from "../../widgets/image-lightbox/image-lightbox.js";
 import { useFieldChangeHandler } from "../use-field-change-handler.js";
 import image_field_module from "./image-field.module.js";
 import { ImageUploadField } from "./image-upload-field.js";
@@ -21,10 +23,14 @@ const ImageField = ({ field, collectionPath, value, defaultValue, onChange: _onC
         return 'placeholder' === maybe.storageProvider && 'pending' === maybe.storagePath;
     };
     const showUploadWidget = null == incomingValue || isOldPlaceholder(incomingValue);
+    const thumbVariant = incomingValue && !isPendingStoredFileValue(incomingValue) ? incomingValue.variants?.find((v)=>'thumbnail' === v.name) : void 0;
+    const previewUrl = thumbVariant?.storageUrl ?? incomingValue?.storageUrl;
     const handleRemove = ()=>{
         if (isPending) removePendingUpload(fieldPath);
         handleChange(null);
     };
+    const [lightboxOpen, setLightboxOpen] = useState(false);
+    const canOpenLightbox = !isPending && !!incomingValue?.storageUrl;
     return /*#__PURE__*/ jsxs("div", {
         className: `byline-field-image ${field.name}`,
         children: [
@@ -67,11 +73,24 @@ const ImageField = ({ field, collectionPath, value, defaultValue, onChange: _onC
             }) : /*#__PURE__*/ jsxs("div", {
                 className: classnames('byline-field-image-tile', image_field_module.tile),
                 children: [
-                    incomingValue?.storageUrl && /*#__PURE__*/ jsxs("div", {
+                    previewUrl && /*#__PURE__*/ jsxs("div", {
                         className: classnames('byline-field-image-preview-wrap', image_field_module["preview-wrap"]),
                         children: [
-                            /*#__PURE__*/ jsx("img", {
-                                src: incomingValue.storageUrl,
+                            canOpenLightbox ? /*#__PURE__*/ jsx("button", {
+                                type: "button",
+                                onClick: ()=>setLightboxOpen(true),
+                                "aria-label": "Open full-size preview",
+                                className: classnames('byline-field-image-preview-button', image_field_module["preview-button"]),
+                                children: /*#__PURE__*/ jsx("img", {
+                                    src: previewUrl,
+                                    alt: incomingValue.originalFilename ?? incomingValue.filename,
+                                    className: classnames('byline-field-image-preview', image_field_module.preview, 'image/svg+xml' === incomingValue.mimeType && [
+                                        'byline-field-image-preview-svg',
+                                        image_field_module["preview-svg"]
+                                    ])
+                                })
+                            }) : /*#__PURE__*/ jsx("img", {
+                                src: previewUrl,
                                 alt: incomingValue.originalFilename ?? incomingValue.filename,
                                 className: classnames('byline-field-image-preview', image_field_module.preview, 'image/svg+xml' === incomingValue.mimeType && [
                                     'byline-field-image-preview-svg',
@@ -179,7 +198,7 @@ const ImageField = ({ field, collectionPath, value, defaultValue, onChange: _onC
                                                 children: "Thumbnail:"
                                             }),
                                             ' ',
-                                            incomingValue?.thumbnailGenerated ? 'Generated' : 'Pending'
+                                            thumbVariant ? 'Generated' : 'Pending'
                                         ]
                                     })
                                 ]
@@ -191,6 +210,20 @@ const ImageField = ({ field, collectionPath, value, defaultValue, onChange: _onC
             fieldError && /*#__PURE__*/ jsx(ErrorText, {
                 id: `${field.name}-error`,
                 text: fieldError
+            }),
+            canOpenLightbox && incomingValue?.storageUrl && /*#__PURE__*/ jsx(ImageLightbox, {
+                isOpen: lightboxOpen,
+                onDismiss: ()=>setLightboxOpen(false),
+                src: incomingValue.storageUrl,
+                alt: incomingValue.originalFilename ?? incomingValue.filename,
+                downloadFilename: incomingValue.originalFilename ?? incomingValue.filename,
+                title: incomingValue.originalFilename ?? incomingValue.filename,
+                meta: {
+                    width: incomingValue.imageWidth,
+                    height: incomingValue.imageHeight,
+                    fileSize: incomingValue.fileSize,
+                    mimeType: incomingValue.mimeType
+                }
             })
         ]
     });

package/dist/fields/image/image-field.module.js

@@ -8,6 +8,8 @@ const image_field_module = {
     tile: "tile-izbLn0",
     "preview-wrap": "preview-wrap-Cjr0PD",
     previewWrap: "preview-wrap-Cjr0PD",
+    "preview-button": "preview-button-LAsENX",
+    previewButton: "preview-button-LAsENX",
     preview: "preview-DIASGB",
     "preview-svg": "preview-svg-sCwreb",
     previewSvg: "preview-svg-sCwreb",

package/dist/fields/image/image-field_module.css

@@ -51,6 +51,30 @@
   position: relative;
 }
 
+:is(.preview-button-LAsENX, .byline-field-image-preview-button) {
+  appearance: none;
+  cursor: pointer;
+  border-radius: var(--border-radius-sm);
+  background: none;
+  border: none;
+  margin: 0;
+  padding: 0;
+  display: block;
+}
+
+:is(.preview-button-LAsENX:focus-visible, .byline-field-image-preview-button:focus-visible) {
+  outline: 2px solid var(--primary-500);
+  outline-offset: 2px;
+}
+
+:is(.preview-button-LAsENX img, .byline-field-image-preview-button img) {
+  transition: opacity .12s;
+}
+
+:is(.preview-button-LAsENX:hover img, .byline-field-image-preview-button:hover img) {
+  opacity: .85;
+}
+
 :is(.preview-DIASGB, .byline-field-image-preview) {
   border: var(--border-width-thin) var(--border-style-solid) var(--gray-600);
   border-radius: var(--border-radius-sm);

package/dist/uikit.d.ts

@@ -103,6 +103,7 @@ export * from './loaders/spinner.js';
 export * from './widgets/datepicker/datepicker.js';
 export * from './widgets/drawer/drawer.js';
 export * from './widgets/drawer/drawer-context.js';
+export * from './widgets/image-lightbox/image-lightbox.js';
 export * from './widgets/modal/modal.js';
 export * from './widgets/search/search.js';
 export * from './widgets/timeline/timeline.js';

package/dist/uikit.js

@@ -98,6 +98,7 @@ export * from "./loaders/spinner.js";
 export * from "./widgets/datepicker/datepicker.js";
 export * from "./widgets/drawer/drawer.js";
 export * from "./widgets/drawer/drawer-context.js";
+export * from "./widgets/image-lightbox/image-lightbox.js";
 export * from "./widgets/modal/modal.js";
 export * from "./widgets/search/search.js";
 export * from "./widgets/timeline/timeline.js";

package/dist/widgets/image-lightbox/image-lightbox.d.ts

@@ -0,0 +1,25 @@
+export interface ImageLightboxProps {
+    isOpen: boolean;
+    onDismiss: () => void;
+    /** Full-resolution image URL. */
+    src: string;
+    /** Alt text — falls back to filename. */
+    alt?: string;
+    /** Used as the `download` attribute on the download link. */
+    downloadFilename?: string;
+    /** Header label. Defaults to `downloadFilename`. */
+    title?: string;
+    /** Optional metadata row beneath the image. */
+    meta?: {
+        width?: number | null;
+        height?: number | null;
+        fileSize?: number | null;
+        mimeType?: string | null;
+    };
+}
+/**
+ * ImageLightbox — modal preview of a full-resolution image with a download
+ * affordance. Right-click on the image works natively (browser "Save image
+ * as…") because it's a regular `<img src>`.
+ */
+export declare function ImageLightbox({ isOpen, onDismiss, src, alt, downloadFilename, title, meta, }: ImageLightboxProps): import("react").JSX.Element;

package/dist/widgets/image-lightbox/image-lightbox.js

@@ -0,0 +1,94 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import classnames from "classnames";
+import { IconButton } from "../../components/button/icon-button.js";
+import { CloseIcon } from "../../icons/close-icon.js";
+import { DownloadIcon } from "../../icons/download-icon.js";
+import { Modal } from "../modal/modal.js";
+import image_lightbox_module from "./image-lightbox.module.js";
+function formatFileSize(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1048576).toFixed(1)} MB`;
+}
+function triggerDownload(url, filename) {
+    if ("u" < typeof document) return;
+    const a = document.createElement('a');
+    a.href = url;
+    if (filename) a.download = filename;
+    a.target = '_blank';
+    a.rel = 'noreferrer';
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+}
+function ImageLightbox({ isOpen, onDismiss, src, alt, downloadFilename, title, meta }) {
+    const headingText = title ?? downloadFilename ?? 'Image';
+    const altText = alt ?? downloadFilename ?? 'Image preview';
+    return /*#__PURE__*/ jsx(Modal, {
+        isOpen: isOpen,
+        closeOnOverlayClick: true,
+        onDismiss: onDismiss,
+        children: /*#__PURE__*/ jsxs(Modal.Container, {
+            className: classnames('byline-image-lightbox-container', image_lightbox_module.container),
+            children: [
+                /*#__PURE__*/ jsxs(Modal.Header, {
+                    className: classnames('byline-image-lightbox-header', image_lightbox_module.header),
+                    children: [
+                        /*#__PURE__*/ jsxs("div", {
+                            className: classnames('byline-image-lightbox-title-stack', image_lightbox_module["title-stack"]),
+                            children: [
+                                /*#__PURE__*/ jsx("h3", {
+                                    className: classnames('byline-image-lightbox-title', image_lightbox_module.title),
+                                    children: headingText
+                                }),
+                                meta?.width != null && meta?.height != null && /*#__PURE__*/ jsxs("p", {
+                                    className: classnames('byline-image-lightbox-subtitle', image_lightbox_module.subtitle),
+                                    children: [
+                                        meta.width,
+                                        "\xd7",
+                                        meta.height,
+                                        null != meta.fileSize ? ` · ${formatFileSize(meta.fileSize)}` : '',
+                                        meta.mimeType ? ` · ${meta.mimeType}` : ''
+                                    ]
+                                })
+                            ]
+                        }),
+                        /*#__PURE__*/ jsxs("div", {
+                            className: classnames('byline-image-lightbox-actions', image_lightbox_module["header-actions"]),
+                            children: [
+                                /*#__PURE__*/ jsx(IconButton, {
+                                    onClick: ()=>triggerDownload(src, downloadFilename),
+                                    size: "xs",
+                                    "aria-label": "Download original",
+                                    children: /*#__PURE__*/ jsx(DownloadIcon, {
+                                        width: "15px",
+                                        height: "15px"
+                                    })
+                                }),
+                                /*#__PURE__*/ jsx(IconButton, {
+                                    onClick: onDismiss,
+                                    size: "xs",
+                                    "aria-label": "Close preview",
+                                    children: /*#__PURE__*/ jsx(CloseIcon, {
+                                        width: "15px",
+                                        height: "15px"
+                                    })
+                                })
+                            ]
+                        })
+                    ]
+                }),
+                /*#__PURE__*/ jsx(Modal.Content, {
+                    className: classnames('byline-image-lightbox-content', image_lightbox_module.content),
+                    children: /*#__PURE__*/ jsx("img", {
+                        src: src,
+                        alt: altText,
+                        className: classnames('byline-image-lightbox-image', image_lightbox_module.image)
+                    })
+                })
+            ]
+        })
+    });
+}
+export { ImageLightbox };

package/dist/widgets/image-lightbox/image-lightbox.module.js

@@ -0,0 +1,17 @@
+import "./image-lightbox_module.css";
+const image_lightbox_module = {
+    container: "container-E7tMnX",
+    header: "header-soW8da",
+    "title-stack": "title-stack-zc7tfO",
+    titleStack: "title-stack-zc7tfO",
+    title: "title-o7aRVk",
+    subtitle: "subtitle-a_cB7m",
+    "header-actions": "header-actions-Pm2hb3",
+    headerActions: "header-actions-Pm2hb3",
+    content: "content-r1WUuT",
+    image: "image-CFBDM6",
+    meta: "meta-M5aIfQ",
+    "meta-key": "meta-key-ohNmZ4",
+    metaKey: "meta-key-ohNmZ4"
+};
+export default image_lightbox_module;

package/dist/widgets/image-lightbox/image-lightbox_module.css

@@ -0,0 +1,82 @@
+@layer byline-base, byline-utilities, byline-theme;
+
+@layer byline-components {
+  .container-E7tMnX {
+    flex-direction: column;
+    width: auto;
+    max-width: 96vw;
+    max-height: 96vh;
+    display: flex;
+    overflow: hidden;
+  }
+
+  .header-soW8da {
+    justify-content: space-between;
+    align-items: center;
+    gap: var(--gap-3);
+    display: flex;
+  }
+
+  .title-stack-zc7tfO {
+    flex: 1;
+    min-width: 0;
+  }
+
+  .title-o7aRVk {
+    font-size: var(--font-size-md);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    margin: 0;
+    font-weight: 600;
+    overflow: hidden;
+  }
+
+  .subtitle-a_cB7m {
+    font-size: var(--font-size-xs);
+    color: var(--text-color-muted);
+    margin: 0;
+    margin-top: var(--spacing-1);
+  }
+
+  .header-actions-Pm2hb3 {
+    align-items: center;
+    gap: var(--gap-2);
+    flex-shrink: 0;
+    display: flex;
+  }
+
+  .content-r1WUuT {
+    min-height: 0;
+    padding: var(--spacing-8);
+    background: var(--surface-canvas, #0b0b0b);
+    justify-content: center;
+    align-items: center;
+    display: flex;
+    overflow: auto;
+  }
+
+  .image-CFBDM6 {
+    object-fit: contain;
+    -webkit-user-select: none;
+    user-select: none;
+    width: auto;
+    max-width: 100%;
+    height: auto;
+    max-height: calc(96vh - 140px);
+    display: block;
+  }
+
+  .meta-M5aIfQ {
+    gap: var(--gap-3);
+    font-size: var(--font-size-xs);
+    color: var(--text-color-muted);
+    flex-wrap: wrap;
+    display: flex;
+  }
+
+  .meta-key-ohNmZ4 {
+    margin-right: var(--spacing-1);
+    font-weight: 600;
+  }
+}
+

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "1.6.2",
+  "version": "1.7.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -65,9 +65,9 @@
     "react-diff-viewer-continued": "^4.2.2",
     "zod": "^4.4.2",
     "zod-form-data": "^3.0.1",
-    "@byline/core": "1.6.2",
-    "@byline/admin": "1.6.2",
-    "@byline/client": "1.6.2"
+    "@byline/admin": "1.7.1",
+    "@byline/core": "1.7.1",
+    "@byline/client": "1.7.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/fields/image/image-field.module.css

@@ -79,6 +79,34 @@
   position: relative;
 }
 
+.preview-button,
+:global(.byline-field-image-preview-button) {
+  appearance: none;
+  background: none;
+  border: none;
+  padding: 0;
+  margin: 0;
+  display: block;
+  cursor: pointer;
+  border-radius: var(--border-radius-sm);
+}
+
+.preview-button:focus-visible,
+:global(.byline-field-image-preview-button):focus-visible {
+  outline: 2px solid var(--primary-500);
+  outline-offset: 2px;
+}
+
+.preview-button img,
+:global(.byline-field-image-preview-button) img {
+  transition: opacity 120ms ease;
+}
+
+.preview-button:hover img,
+:global(.byline-field-image-preview-button):hover img {
+  opacity: 0.85;
+}
+
 .preview,
 :global(.byline-field-image-preview) {
   max-height: 10rem;

package/src/fields/image/image-field.tsx

@@ -6,6 +6,8 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+import { useState } from 'react'
+
 import {
   type ImageField as FieldType,
   isPendingStoredFileValue,
@@ -15,6 +17,7 @@ import cx from 'classnames'
 
 import { useFieldError, useFieldValue, useFormContext, useIsDirty } from '../../forms/form-context'
 import { ErrorText } from '../../uikit.js'
+import { ImageLightbox } from '../../widgets/image-lightbox/image-lightbox.js'
 import { useFieldChangeHandler } from '../use-field-change-handler'
 import styles from './image-field.module.css'
 import { ImageUploadField } from './image-upload-field'
@@ -68,6 +71,14 @@ export const ImageField = ({
   // Show upload widget only if no value or old placeholder
   const showUploadWidget = incomingValue == null || isOldPlaceholder(incomingValue)
 
+  // Prefer the generated thumbnail variant for the preview tile. SVGs and
+  // other bypass types have no variants — fall back to the original.
+  const thumbVariant =
+    incomingValue && !isPendingStoredFileValue(incomingValue)
+      ? incomingValue.variants?.find((v) => v.name === 'thumbnail')
+      : undefined
+  const previewUrl = thumbVariant?.storageUrl ?? incomingValue?.storageUrl
+
   // Handle remove, including cleanup of pending uploads
   const handleRemove = () => {
     if (isPending) {
@@ -76,6 +87,11 @@ export const ImageField = ({
     handleChange(null)
   }
 
+  // Lightbox state — only enabled for stored (non-pending) images that have a
+  // resolvable original storageUrl.
+  const [lightboxOpen, setLightboxOpen] = useState(false)
+  const canOpenLightbox = !isPending && !!incomingValue?.storageUrl
+
   return (
     <div className={`byline-field-image ${field.name}`}>
       <div className={cx('byline-field-image-header', styles.header)}>
@@ -116,20 +132,42 @@ export const ImageField = ({
       ) : (
         <div className={cx('byline-field-image-tile', styles.tile)}>
           {/* Preview */}
-          {incomingValue?.storageUrl && (
+          {previewUrl && (
             <div className={cx('byline-field-image-preview-wrap', styles['preview-wrap'])}>
-              <img
-                src={incomingValue.storageUrl}
-                alt={incomingValue.originalFilename ?? incomingValue.filename}
-                className={cx(
-                  'byline-field-image-preview',
-                  styles.preview,
-                  incomingValue.mimeType === 'image/svg+xml' && [
-                    'byline-field-image-preview-svg',
-                    styles['preview-svg'],
-                  ]
-                )}
-              />
+              {canOpenLightbox ? (
+                <button
+                  type="button"
+                  onClick={() => setLightboxOpen(true)}
+                  aria-label="Open full-size preview"
+                  className={cx('byline-field-image-preview-button', styles['preview-button'])}
+                >
+                  <img
+                    src={previewUrl}
+                    alt={incomingValue.originalFilename ?? incomingValue.filename}
+                    className={cx(
+                      'byline-field-image-preview',
+                      styles.preview,
+                      incomingValue.mimeType === 'image/svg+xml' && [
+                        'byline-field-image-preview-svg',
+                        styles['preview-svg'],
+                      ]
+                    )}
+                  />
+                </button>
+              ) : (
+                <img
+                  src={previewUrl}
+                  alt={incomingValue.originalFilename ?? incomingValue.filename}
+                  className={cx(
+                    'byline-field-image-preview',
+                    styles.preview,
+                    incomingValue.mimeType === 'image/svg+xml' && [
+                      'byline-field-image-preview-svg',
+                      styles['preview-svg'],
+                    ]
+                  )}
+                />
+              )}
               {/* Pending upload badge */}
               {isPending && (
                 <div className={cx('byline-field-image-pending', styles.pending)}>
@@ -198,7 +236,7 @@ export const ImageField = ({
                   <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
                     Thumbnail:
                   </span>{' '}
-                  {incomingValue?.thumbnailGenerated ? 'Generated' : 'Pending'}
+                  {thumbVariant ? 'Generated' : 'Pending'}
                 </div>
               </>
             )}
@@ -207,6 +245,23 @@ export const ImageField = ({
       )}
 
       {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError} />}
+
+      {canOpenLightbox && incomingValue?.storageUrl && (
+        <ImageLightbox
+          isOpen={lightboxOpen}
+          onDismiss={() => setLightboxOpen(false)}
+          src={incomingValue.storageUrl}
+          alt={incomingValue.originalFilename ?? incomingValue.filename}
+          downloadFilename={incomingValue.originalFilename ?? incomingValue.filename}
+          title={incomingValue.originalFilename ?? incomingValue.filename}
+          meta={{
+            width: incomingValue.imageWidth,
+            height: incomingValue.imageHeight,
+            fileSize: incomingValue.fileSize,
+            mimeType: incomingValue.mimeType,
+          }}
+        />
+      )}
     </div>
   )
 }

package/src/uikit.ts

@@ -111,6 +111,7 @@ export * from './loaders/spinner.js'
 export * from './widgets/datepicker/datepicker.js'
 export * from './widgets/drawer/drawer.js'
 export * from './widgets/drawer/drawer-context.js'
+export * from './widgets/image-lightbox/image-lightbox.js'
 export * from './widgets/modal/modal.js'
 export * from './widgets/search/search.js'
 export * from './widgets/timeline/timeline.js'

package/src/widgets/image-lightbox/image-lightbox.module.css

@@ -0,0 +1,80 @@
+@layer byline-base, byline-utilities, byline-theme, byline-components;
+
+@layer byline-components {
+  .container {
+    width: auto;
+    max-width: 96vw;
+    max-height: 96vh;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+  }
+
+  .header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--gap-3);
+  }
+
+  .title-stack {
+    min-width: 0;
+    flex: 1;
+  }
+
+  .title {
+    font-size: var(--font-size-md);
+    font-weight: 600;
+    margin: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .subtitle {
+    font-size: var(--font-size-xs);
+    color: var(--text-color-muted);
+    margin: 0;
+    margin-top: var(--spacing-1);
+  }
+
+  .header-actions {
+    display: flex;
+    align-items: center;
+    gap: var(--gap-2);
+    flex-shrink: 0;
+  }
+
+  .content {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 0;
+    overflow: auto;
+    padding: var(--spacing-8);
+    background: var(--surface-canvas, #0b0b0b);
+  }
+
+  .image {
+    max-width: 100%;
+    max-height: calc(96vh - 140px);
+    width: auto;
+    height: auto;
+    object-fit: contain;
+    display: block;
+    user-select: none;
+  }
+
+  .meta {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--gap-3);
+    font-size: var(--font-size-xs);
+    color: var(--text-color-muted);
+  }
+
+  .meta-key {
+    font-weight: 600;
+    margin-right: var(--spacing-1);
+  }
+}

package/src/widgets/image-lightbox/image-lightbox.tsx

@@ -0,0 +1,118 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import cx from 'classnames'
+
+import { IconButton } from '../../components/button/icon-button.js'
+import { CloseIcon } from '../../icons/close-icon.js'
+import { DownloadIcon } from '../../icons/download-icon.js'
+import { Modal } from '../modal/modal.js'
+import styles from './image-lightbox.module.css'
+
+export interface ImageLightboxProps {
+  isOpen: boolean
+  onDismiss: () => void
+  /** Full-resolution image URL. */
+  src: string
+  /** Alt text — falls back to filename. */
+  alt?: string
+  /** Used as the `download` attribute on the download link. */
+  downloadFilename?: string
+  /** Header label. Defaults to `downloadFilename`. */
+  title?: string
+  /** Optional metadata row beneath the image. */
+  meta?: {
+    width?: number | null
+    height?: number | null
+    fileSize?: number | null
+    mimeType?: string | null
+  }
+}
+
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/**
+ * Trigger a download via a temporary anchor. Uses the `download` attribute so
+ * same-origin URLs save with the suggested filename; cross-origin URLs that
+ * don't honour the attribute will navigate to the file in a new tab, where
+ * the user can still right-click to save.
+ */
+function triggerDownload(url: string, filename?: string) {
+  if (typeof document === 'undefined') return
+  const a = document.createElement('a')
+  a.href = url
+  if (filename) a.download = filename
+  a.target = '_blank'
+  a.rel = 'noreferrer'
+  document.body.appendChild(a)
+  a.click()
+  document.body.removeChild(a)
+}
+
+/**
+ * ImageLightbox — modal preview of a full-resolution image with a download
+ * affordance. Right-click on the image works natively (browser "Save image
+ * as…") because it's a regular `<img src>`.
+ */
+export function ImageLightbox({
+  isOpen,
+  onDismiss,
+  src,
+  alt,
+  downloadFilename,
+  title,
+  meta,
+}: ImageLightboxProps) {
+  const headingText = title ?? downloadFilename ?? 'Image'
+  const altText = alt ?? downloadFilename ?? 'Image preview'
+
+  return (
+    <Modal isOpen={isOpen} closeOnOverlayClick={true} onDismiss={onDismiss}>
+      <Modal.Container className={cx('byline-image-lightbox-container', styles.container)}>
+        <Modal.Header className={cx('byline-image-lightbox-header', styles.header)}>
+          <div className={cx('byline-image-lightbox-title-stack', styles['title-stack'])}>
+            <h3 className={cx('byline-image-lightbox-title', styles.title)}>{headingText}</h3>
+            {meta?.width != null && meta?.height != null && (
+              <p className={cx('byline-image-lightbox-subtitle', styles.subtitle)}>
+                {meta.width}×{meta.height}
+                {meta.fileSize != null ? ` · ${formatFileSize(meta.fileSize)}` : ''}
+                {meta.mimeType ? ` · ${meta.mimeType}` : ''}
+              </p>
+            )}
+          </div>
+          <div className={cx('byline-image-lightbox-actions', styles['header-actions'])}>
+            <IconButton
+              onClick={() => triggerDownload(src, downloadFilename)}
+              size="xs"
+              aria-label="Download original"
+            >
+              <DownloadIcon width="15px" height="15px" />
+            </IconButton>
+            <IconButton onClick={onDismiss} size="xs" aria-label="Close preview">
+              <CloseIcon width="15px" height="15px" />
+            </IconButton>
+          </div>
+        </Modal.Header>
+
+        <Modal.Content className={cx('byline-image-lightbox-content', styles.content)}>
+          <img
+            src={src}
+            alt={altText}
+            className={cx('byline-image-lightbox-image', styles.image)}
+          />
+        </Modal.Content>
+      </Modal.Container>
+    </Modal>
+  )
+}