@byline/admin 5.2.0 → 6.0.0

package/dist/fields/file/file-field.jsx

@@ -0,0 +1,176 @@
+/**
+ * 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 { isPendingStoredFileValue, } from '@byline/core';
+import { useTranslation } from '@byline/i18n/react';
+import { CloseIcon, DocumentIcon, DownloadIcon, ErrorText, HelpText, IconButton, Label, LoaderRing, VideoIcon, } from '@byline/ui/react';
+import cx from 'clsx';
+import { useFieldError, useFieldValue, useFormContext, useIsDirty, useIsFieldUploading, } from '../../forms/form-context';
+import { useFieldChangeHandler } from '../use-field-change-handler';
+import styles from './file-field.module.css';
+import { FileUploadField } from './file-upload-field';
+/**
+ * Trigger a download via a temporary anchor. Mirrors the helper in
+ * `image-lightbox.tsx`: same-origin URLs respect the `download` attribute and
+ * save with the suggested filename; cross-origin URLs without CORS headers
+ * fall through to navigation in a new tab, where the user can right-click
+ * Save As.
+ */
+function triggerDownload(url, filename) {
+    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);
+}
+export const FileField = ({ field, value, defaultValue, onChange: _onChange, path, }) => {
+    const fieldPath = path ?? field.name;
+    const { t } = useTranslation('byline-admin');
+    const fieldError = useFieldError(fieldPath);
+    const isDirty = useIsDirty(fieldPath);
+    const fieldValue = useFieldValue(fieldPath);
+    const isUploading = useIsFieldUploading(fieldPath);
+    // `collectionPath` comes from form context rather than a prop: it is
+    // constant for the form, and prop-drilling it meant any container that
+    // forgot to forward it silently rendered this widget read-only.
+    const { removePendingUpload, documentId, collectionPath } = useFormContext();
+    const handleChange = useFieldChangeHandler(field, fieldPath);
+    // Mirror the image-field rule: once the field has been touched, the form
+    // value is authoritative (even when null, so a click-to-remove sticks);
+    // otherwise fall back to props.
+    const incomingValue = isDirty
+        ? (fieldValue ?? null)
+        : (value ?? fieldValue ?? defaultValue ?? null);
+    const isPending = isPendingStoredFileValue(incomingValue);
+    // Legacy placeholder shape — kept for backwards compatibility with older
+    // seed data, matching the image-field check.
+    const isOldPlaceholder = (v) => {
+        if (!v || typeof v !== 'object')
+            return false;
+        const maybe = v;
+        return maybe.storageProvider === 'placeholder' && maybe.storagePath === 'pending';
+    };
+    const showUploadWidget = incomingValue == null || isOldPlaceholder(incomingValue);
+    // `upload.requireSavedDocument` gate: until the document is persisted,
+    // render a "save first" notice in place of the upload zone. Server-side
+    // upload hooks that depend on save-time state (counters, document id)
+    // rely on this; existing stored values still render normally below.
+    const uploadGated = field.upload?.requireSavedDocument === true && documentId == null;
+    const handleRemove = () => {
+        if (isPending) {
+            removePendingUpload(fieldPath);
+        }
+        handleChange(null);
+    };
+    // MIME-driven glyph dispatch. Until a dedicated VideoField primitive lands,
+    // the FileField is the canonical home for video uploads — the schema's
+    // `upload.allowedMimeTypes` decides what gets in, and we swap the glyph
+    // here based on the resolved MIME so the tile reads as "video" rather
+    // than "generic document".
+    const isVideo = incomingValue?.mimeType?.startsWith('video/') === true;
+    const FileGlyph = isVideo ? VideoIcon : DocumentIcon;
+    const htmlId = fieldPath;
+    return (<div className={`byline-field-file ${field.name}`}>
+      <div className={cx('byline-field-file-header', styles.header)}>
+        <Label id={htmlId} htmlFor={htmlId} label={field.label ?? field.name} required={!field.optional}/>
+      </div>
+
+      {showUploadWidget ? (uploadGated ? (<div className={cx('byline-field-file-empty', styles.empty)} role="note" data-testid="upload-require-saved-document">
+            {t('fields.upload.requireSavedDocument')}
+          </div>) : collectionPath ? (<FileUploadField field={field} collectionPath={collectionPath} fieldPath={fieldPath} onUploaded={(uploaded) => {
+                handleChange(uploaded);
+            }}/>) : (<div className={cx('byline-field-file-empty', styles.empty)}>
+            {t('fields.file.empty')}
+          </div>)) : (<div className={cx('byline-field-file-tile', styles.tile)}>
+          {isUploading && (<div className={cx('byline-field-file-uploading', styles.uploading)} aria-live="polite" aria-busy="true">
+              <LoaderRing />
+            </div>)}
+          {collectionPath && (<div className={cx('byline-field-file-actions', styles.actions)}>
+              {!isPending && incomingValue?.storageUrl && (<IconButton type="button" intent="noeffect" onClick={() => triggerDownload(incomingValue.storageUrl, incomingValue.originalFilename ?? incomingValue.filename)} size="xs" disabled={isUploading} aria-label={t('fields.file.downloadAriaLabel')}>
+                  <DownloadIcon width="15px" height="15px"/>
+                </IconButton>)}
+              <IconButton type="button" intent="noeffect" onClick={handleRemove} size="xs" disabled={isUploading} aria-label={t('fields.file.removeAriaLabel')}>
+                <CloseIcon width="15px" height="15px"/>
+              </IconButton>
+            </div>)}
+          {/* Document icon + (optional) pending badge — mirrors the
+                image-field's preview-wrap so the file tile has the same
+                visual hierarchy: glyph on the left, metadata on the right.
+                When the file is stored (non-pending and resolvable storageUrl),
+                the wrap is rendered as an anchor that opens the asset in a new
+                tab — browser-native viewer dispatch (PDFs render inline,
+                non-renderable types fall through to download). */}
+          {!isPending && incomingValue?.storageUrl ? (<a href={incomingValue.storageUrl} target="_blank" rel="noreferrer" aria-label={t('fields.file.openInNewTabAriaLabel', {
+                    filename: incomingValue.originalFilename ?? incomingValue.filename,
+                })} className={cx('byline-field-file-icon-wrap', styles['icon-wrap'])}>
+              <FileGlyph width="48px" height="48px" className={cx('byline-field-file-icon', styles.icon)}/>
+            </a>) : (<div className={cx('byline-field-file-icon-wrap', styles['icon-wrap'])}>
+              <FileGlyph width="48px" height="48px" className={cx('byline-field-file-icon', styles.icon)}/>
+              {isPending && (<div className={cx('byline-field-file-pending', styles.pending)}>
+                  {t('fields.fileMeta.pendingUpload')}
+                </div>)}
+            </div>)}
+          <div className={cx('byline-field-file-meta', styles.meta)}>
+            <div>
+              <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>
+                {t('fields.fileMeta.filename')}
+              </span>{' '}
+              {incomingValue?.filename}
+            </div>
+            <div>
+              <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>
+                {t('fields.fileMeta.original')}
+              </span>{' '}
+              {incomingValue?.originalFilename}
+            </div>
+            <div>
+              <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>
+                {t('fields.fileMeta.type')}
+              </span>{' '}
+              {incomingValue?.mimeType}
+            </div>
+            <div>
+              <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>
+                {t('fields.fileMeta.size')}
+              </span>{' '}
+              {incomingValue?.fileSize}
+            </div>
+            {isPending ? (<div>
+                <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>
+                  {t('fields.fileMeta.status')}
+                </span>{' '}
+                <span className={cx('byline-field-file-meta-pending', styles['meta-pending'])}>
+                  {t('fields.fileMeta.willUploadOnSave')}
+                </span>
+              </div>) : (<>
+                <div>
+                  <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>
+                    {t('fields.fileMeta.storage')}
+                  </span>{' '}
+                  {incomingValue?.storageProvider}
+                </div>
+                <div>
+                  <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>
+                    {t('fields.fileMeta.path')}
+                  </span>{' '}
+                  {incomingValue?.storagePath}
+                </div>
+              </>)}
+          </div>
+        </div>)}
+
+      {field.helpText && <HelpText text={field.helpText}/>}
+
+      {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError}/>}
+    </div>);
+};

package/dist/fields/file/file-upload-field.jsx

@@ -0,0 +1,89 @@
+/**
+ * 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 { useCallback, useRef, useState } from 'react';
+import { createPendingStoredFileValue, } from '@byline/core';
+import { useTranslation } from '@byline/i18n/react';
+import cx from 'clsx';
+import { useFormContext } from '../../forms/form-context';
+import styles from './file-upload-field.module.css';
+export const FileUploadField = ({ field: _field, collectionPath, fieldPath, onUploaded, accept, }) => {
+    const inputRef = useRef(null);
+    const { t } = useTranslation('byline-admin');
+    const [status, setStatus] = useState('idle');
+    const [errorMessage, setErrorMessage] = useState(null);
+    const [isDragOver, setIsDragOver] = useState(false);
+    const { addPendingUpload } = useFormContext();
+    const handleFileSelected = useCallback((file) => {
+        setStatus('processing');
+        setErrorMessage(null);
+        // Blob URL is created so the form orchestrator can revoke it on cleanup
+        // alongside image-field uploads; it isn't surfaced in the UI here.
+        const previewUrl = URL.createObjectURL(file);
+        const pendingValue = createPendingStoredFileValue(file, previewUrl);
+        if (!addPendingUpload(fieldPath, {
+            file,
+            previewUrl,
+            collectionPath,
+        })) {
+            return;
+        }
+        setStatus('idle');
+        onUploaded(pendingValue);
+    }, [collectionPath, fieldPath, addPendingUpload, onUploaded]);
+    const handleFileChange = useCallback((e) => {
+        const file = e.target.files?.[0];
+        if (file)
+            handleFileSelected(file);
+        // Reset so re-selecting the same file fires the event again.
+        e.target.value = '';
+    }, [handleFileSelected]);
+    const handleBrowseClick = useCallback(() => {
+        inputRef.current?.click();
+    }, []);
+    const handleDragOver = useCallback((e) => {
+        e.preventDefault();
+        setIsDragOver(true);
+    }, []);
+    const handleDragLeave = useCallback((e) => {
+        e.preventDefault();
+        setIsDragOver(false);
+    }, []);
+    const handleDrop = useCallback((e) => {
+        e.preventDefault();
+        setIsDragOver(false);
+        const file = e.dataTransfer.files?.[0];
+        if (file)
+            handleFileSelected(file);
+    }, [handleFileSelected]);
+    const isProcessing = status === 'processing';
+    return (<div className={cx('byline-field-file-upload', styles.root)}>
+      <input ref={inputRef} type="file" accept={accept} className={cx('byline-field-file-upload-input', styles.input)} onChange={handleFileChange} disabled={isProcessing} aria-hidden="true" tabIndex={-1}/>
+
+      <div role="button" tabIndex={0} aria-label={t('fields.file.upload.zoneAriaLabel')} onDragOver={handleDragOver} onDragLeave={handleDragLeave} onDrop={handleDrop} onClick={handleBrowseClick} onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                handleBrowseClick();
+            }
+        }} className={cx('byline-field-file-upload-zone', styles.zone, isDragOver &&
+            !isProcessing && ['byline-field-file-upload-zone-active', styles['zone-active']], isProcessing && ['byline-field-file-upload-zone-busy', styles['zone-busy']])}>
+        <svg xmlns="http://www.w3.org/2000/svg" className={cx('byline-field-file-upload-icon', styles.icon)} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5} aria-hidden="true">
+          <path strokeLinecap="round" strokeLinejoin="round" d="M3 16.5v2.25A2.25 2.25 0 005.25 21h13.5A2.25 2.25 0 0021 18.75V16.5m-13.5-9L12 3m0 0l4.5 4.5M12 3v13.5"/>
+        </svg>
+        <span className={cx('byline-field-file-upload-label', styles.label)}>
+          {t('fields.file.upload.label')}{' '}
+          <span className={cx('byline-field-file-upload-action', styles.action)}>
+            {t('fields.file.upload.browse')}
+          </span>
+        </span>
+      </div>
+
+      {status === 'error' && errorMessage && (<p className={cx('byline-field-file-upload-error', styles.error)} role="alert">
+          {errorMessage}
+        </p>)}
+    </div>);
+};

package/dist/fields/group/group-field.jsx

@@ -0,0 +1,46 @@
+/**
+ * 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 { useMemo } from 'react';
+import { ErrorText } from '@byline/ui/react';
+import cx from 'clsx';
+import { sliceFieldAdmin } from '../../fields/field-admin';
+import { placeholderForField } from '../../fields/field-helpers';
+import { FieldRenderer } from '../../fields/field-renderer';
+import { useFieldError } from '../../forms/form-context';
+import styles from './group-field.module.css';
+export const GroupField = ({ field, defaultValue, path, disableSorting = true, contentLocale, fieldAdmin, }) => {
+    const fieldError = useFieldError(field.name);
+    // Default value for a group field is a plain object: { rating: 5, comment: '...' }
+    // Normalize to a plain object if not already one.
+    const groupData = useMemo(() => {
+        if (defaultValue && typeof defaultValue === 'object' && !Array.isArray(defaultValue)) {
+            return defaultValue;
+        }
+        // Fallback: build a placeholder object from child field definitions
+        const placeholder = {};
+        for (const childField of field.fields) {
+            placeholder[childField.name] = placeholderForField(childField);
+        }
+        return placeholder;
+    }, [defaultValue, field.fields]);
+    return (<div className={`byline-field-group ${field.name}`}>
+      {field.label && (<div className={cx('byline-field-group-header', styles.header)}>
+          <h3 className={cx('byline-field-group-title', styles.title)}>
+            {field.label}{' '}
+            {!field.optional && (<span className={cx('byline-field-group-required', styles.required)}>*</span>)}
+          </h3>
+          {field.helpText && (<p className={cx('byline-field-group-help', styles.help)}>{field.helpText}</p>)}
+        </div>)}
+      <div className={cx('byline-field-group-body', styles.body)}>
+        {field.fields.map((innerField) => {
+            return (<FieldRenderer key={innerField.name} field={innerField} defaultValue={groupData[innerField.name]} basePath={path} disableSorting={disableSorting} contentLocale={contentLocale} components={fieldAdmin?.[innerField.name]?.components} editor={fieldAdmin?.[innerField.name]?.editor} fieldAdmin={sliceFieldAdmin(fieldAdmin, innerField.name)}/>);
+        })}
+      </div>
+      {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError}/>}
+    </div>);
+};

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

@@ -0,0 +1,183 @@
+/**
+ * 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 { useState } from 'react';
+import { isPendingStoredFileValue, } from '@byline/core';
+import { useTranslation } from '@byline/i18n/react';
+import { CloseIcon, ErrorText, HelpText, IconButton, ImageLightbox, Label, LoaderRing, } from '@byline/ui/react';
+import cx from 'clsx';
+import { useFieldError, useFieldValue, useFormContext, useIsDirty, useIsFieldUploading, } from '../../forms/form-context';
+import { useFieldChangeHandler } from '../use-field-change-handler';
+import styles from './image-field.module.css';
+import { ImageUploadField } from './image-upload-field';
+export const ImageField = ({ field, value, defaultValue, onChange: _onChange, path, }) => {
+    const fieldPath = path ?? field.name;
+    const fieldError = useFieldError(fieldPath);
+    const isDirty = useIsDirty(fieldPath);
+    const fieldValue = useFieldValue(fieldPath);
+    const isUploading = useIsFieldUploading(fieldPath);
+    // `collectionPath` comes from form context rather than a prop: it is
+    // constant for the form, and prop-drilling it meant any container that
+    // forgot to forward it silently rendered this widget read-only.
+    const { removePendingUpload, documentId, collectionPath } = useFormContext();
+    const { t } = useTranslation('byline-admin');
+    // Re-use the standard field change handler so patches are emitted correctly.
+    const handleChange = useFieldChangeHandler(field, fieldPath);
+    // When the field has been explicitly set (dirty), use the field value from
+    // form state — even if it's null (user clicked Remove). Only fall back to
+    // the prop / defaultValue when the field hasn't been touched yet.
+    const incomingValue = isDirty
+        ? (fieldValue ?? null)
+        : (value ?? fieldValue ?? defaultValue ?? null);
+    // Check if this is a pending upload (selected but not yet uploaded)
+    const isPending = isPendingStoredFileValue(incomingValue);
+    // Old placeholder check for backwards compatibility
+    const isOldPlaceholder = (v) => {
+        if (!v || typeof v !== 'object')
+            return false;
+        const maybe = v;
+        return maybe.storageProvider === 'placeholder' && maybe.storagePath === 'pending';
+    };
+    // Show upload widget only if no value or old placeholder
+    const showUploadWidget = incomingValue == null || isOldPlaceholder(incomingValue);
+    // `upload.requireSavedDocument` gate: until the document is persisted,
+    // render a "save first" notice in place of the upload zone. Server-side
+    // upload hooks that depend on save-time state (counters, document id)
+    // rely on this; existing stored values still render normally below.
+    const uploadGated = field.upload?.requireSavedDocument === true && documentId == null;
+    // 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) {
+            removePendingUpload(fieldPath);
+        }
+        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;
+    const htmlId = fieldPath;
+    return (<div className={`byline-field-image ${field.name}`}>
+      <div className={cx('byline-field-image-header', styles.header)}>
+        <Label id={htmlId} htmlFor={htmlId} label={field.label ?? field.name} required={!field.optional}/>
+      </div>
+
+      {showUploadWidget ? (uploadGated ? (<div className={cx('byline-field-image-empty', styles.empty)} role="note" data-testid="upload-require-saved-document">
+            {t('fields.upload.requireSavedDocument')}
+          </div>) : collectionPath ? (<ImageUploadField field={field} collectionPath={collectionPath} fieldPath={fieldPath} onUploaded={(uploaded) => {
+                handleChange(uploaded);
+            }}/>) : (<div className={cx('byline-field-image-empty', styles.empty)}>
+            {t('fields.image.empty')}
+          </div>)) : (<div className={cx('byline-field-image-tile', styles.tile)}>
+          {isUploading && (<div className={cx('byline-field-image-uploading', styles.uploading)} aria-live="polite" aria-busy="true">
+              <LoaderRing />
+            </div>)}
+          {/* Remove button — shown when an image is set (including pending) */}
+          {collectionPath && (<div className={cx('byline-field-image-remove', styles.remove)}>
+              <IconButton type="button" intent="noeffect" onClick={handleRemove} size="xs" disabled={isUploading} aria-label={t('fields.image.removeAriaLabel')}>
+                <CloseIcon width="15px" height="15px"/>
+              </IconButton>
+            </div>)}
+          {/* Preview */}
+          {previewUrl && (<div className={cx('byline-field-image-preview-wrap', styles['preview-wrap'])}>
+              {canOpenLightbox ? (<button type="button" onClick={() => setLightboxOpen(true)} aria-label={t('fields.image.openLightboxAriaLabel')} 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)}>
+                  {t('fields.fileMeta.pendingUpload')}
+                </div>)}
+            </div>)}
+          {/* Metadata */}
+          <div className={cx('byline-field-image-meta', styles.meta)}>
+            <div>
+              <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
+                {t('fields.fileMeta.filename')}
+              </span>{' '}
+              {incomingValue?.filename}
+            </div>
+            <div>
+              <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
+                {t('fields.fileMeta.original')}
+              </span>{' '}
+              {incomingValue?.originalFilename}
+            </div>
+            <div>
+              <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
+                {t('fields.fileMeta.type')}
+              </span>{' '}
+              {incomingValue?.mimeType}
+            </div>
+            <div>
+              <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
+                {t('fields.fileMeta.size')}
+              </span>{' '}
+              {incomingValue?.fileSize}
+            </div>
+            {isPending ? (<div>
+                <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
+                  {t('fields.fileMeta.status')}
+                </span>{' '}
+                <span className={cx('byline-field-image-meta-pending', styles['meta-pending'])}>
+                  {t('fields.fileMeta.willUploadOnSave')}
+                </span>
+              </div>) : (<>
+                <div>
+                  <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
+                    {t('fields.fileMeta.storage')}
+                  </span>{' '}
+                  {incomingValue?.storageProvider}
+                </div>
+                {incomingValue?.imageWidth != null && (<div>
+                    <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
+                      {t('fields.imageMeta.dimensions')}
+                    </span>{' '}
+                    {incomingValue.imageWidth}
+                    {incomingValue.imageHeight != null ? `×${incomingValue.imageHeight}` : ''}
+                  </div>)}
+                {incomingValue?.imageFormat != null && (<div>
+                    <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
+                      {t('fields.imageMeta.format')}
+                    </span>{' '}
+                    {incomingValue.imageFormat}
+                  </div>)}
+                <div>
+                  <span className={cx('byline-field-image-meta-key', styles['meta-key'])}>
+                    {t('fields.imageMeta.thumbnail')}
+                  </span>{' '}
+                  {thumbVariant
+                    ? t('fields.imageMeta.thumbnailGenerated')
+                    : t('fields.imageMeta.thumbnailPending')}
+                </div>
+              </>)}
+          </div>
+        </div>)}
+
+      {field.helpText && <HelpText text={field.helpText}/>}
+
+      {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/dist/fields/image/image-upload-field.jsx

@@ -0,0 +1,157 @@
+/**
+ * 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 { useCallback, useEffect, useRef, useState } from 'react';
+import { createPendingStoredFileValue, } from '@byline/core';
+import { useTranslation } from '@byline/i18n/react';
+import cx from 'clsx';
+import { useFormContext } from '../../forms/form-context';
+import styles from './image-upload-field.module.css';
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+export const ImageUploadField = ({ field: _field, collectionPath, fieldPath, onUploaded, accept = 'image/*', }) => {
+    const inputRef = useRef(null);
+    const mountedRef = useRef(true);
+    const [status, setStatus] = useState('idle');
+    const [errorMessage, setErrorMessage] = useState(null);
+    const [isDragOver, setIsDragOver] = useState(false);
+    const { addPendingUpload } = useFormContext();
+    const { t } = useTranslation('byline-admin');
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    // -------------------------------------------------------------------------
+    // Core file selection logic (deferred upload)
+    // -------------------------------------------------------------------------
+    const handleFileSelected = useCallback((file) => {
+        setStatus('processing');
+        setErrorMessage(null);
+        // Basic client-side validation
+        if (!file.type.startsWith('image/')) {
+            setStatus('error');
+            setErrorMessage(t('fields.image.upload.errors.notAnImage'));
+            return;
+        }
+        // Create a blob URL for immediate preview
+        const previewUrl = URL.createObjectURL(file);
+        // Extract image dimensions for the pending value
+        const img = new Image();
+        img.onload = () => {
+            if (!mountedRef.current) {
+                URL.revokeObjectURL(previewUrl);
+                return;
+            }
+            // SVGs without explicit width/height attrs (viewBox-only) report naturalWidth/Height = 0.
+            // Skip dimensions when zero so they are stored as null (scalable, no fixed size).
+            const w = img.naturalWidth;
+            const h = img.naturalHeight;
+            const dimensions = w > 0 && h > 0 ? { width: w, height: h } : undefined;
+            // Create the pending stored file value
+            const pendingValue = createPendingStoredFileValue(file, previewUrl, dimensions);
+            // Register the pending upload in form context
+            if (!addPendingUpload(fieldPath, {
+                file,
+                previewUrl,
+                collectionPath,
+            })) {
+                return;
+            }
+            setStatus('idle');
+            onUploaded(pendingValue);
+        };
+        img.onerror = () => {
+            URL.revokeObjectURL(previewUrl);
+            if (!mountedRef.current)
+                return;
+            setStatus('error');
+            setErrorMessage(t('fields.image.upload.errors.cannotRead'));
+        };
+        img.src = previewUrl;
+    }, [collectionPath, fieldPath, addPendingUpload, onUploaded, t]);
+    // -------------------------------------------------------------------------
+    // File input
+    // -------------------------------------------------------------------------
+    const handleFileChange = useCallback((e) => {
+        const file = e.target.files?.[0];
+        if (file)
+            handleFileSelected(file);
+        // Reset so re-selecting the same file fires the event again.
+        e.target.value = '';
+    }, [handleFileSelected]);
+    const handleBrowseClick = useCallback(() => {
+        inputRef.current?.click();
+    }, []);
+    // -------------------------------------------------------------------------
+    // Drag and drop
+    // -------------------------------------------------------------------------
+    const handleDragOver = useCallback((e) => {
+        e.preventDefault();
+        setIsDragOver(true);
+    }, []);
+    const handleDragLeave = useCallback((e) => {
+        e.preventDefault();
+        setIsDragOver(false);
+    }, []);
+    const handleDrop = useCallback((e) => {
+        e.preventDefault();
+        setIsDragOver(false);
+        const file = e.dataTransfer.files?.[0];
+        if (file)
+            handleFileSelected(file);
+    }, [handleFileSelected]);
+    // -------------------------------------------------------------------------
+    // Render
+    // -------------------------------------------------------------------------
+    const isProcessing = status === 'processing';
+    return (<div className={cx('byline-field-image-upload', styles.root)}>
+      {/* Hidden native file input */}
+      <input ref={inputRef} type="file" accept={accept} className={cx('byline-field-image-upload-input', styles.input)} onChange={handleFileChange} disabled={isProcessing} aria-hidden="true" tabIndex={-1}/>
+
+      {/* Drop zone */}
+      <div role="button" tabIndex={0} aria-label={t('fields.image.upload.zoneAriaLabel')} onDragOver={handleDragOver} onDragLeave={handleDragLeave} onDrop={handleDrop} onClick={handleBrowseClick} onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                handleBrowseClick();
+            }
+        }} className={cx('byline-field-image-upload-zone', styles.zone, isDragOver &&
+            !isProcessing && ['byline-field-image-upload-zone-active', styles['zone-active']], isProcessing && ['byline-field-image-upload-zone-busy', styles['zone-busy']])}>
+        {isProcessing ? (<>
+            {/* Spinner */}
+            <svg className={cx('byline-field-image-upload-spinner', styles.spinner)} xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" aria-hidden="true">
+              <circle style={{ opacity: 0.25 }} cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"/>
+              <path style={{ opacity: 0.75 }} fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"/>
+            </svg>
+            <span className={cx('byline-field-image-upload-label', styles.label)}>
+              {t('fields.image.upload.processing')}
+            </span>
+          </>) : (<>
+            {/* Upload icon */}
+            <svg xmlns="http://www.w3.org/2000/svg" className={cx('byline-field-image-upload-icon', styles.icon)} fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5} aria-hidden="true">
+              <path strokeLinecap="round" strokeLinejoin="round" d="M3 16.5v2.25A2.25 2.25 0 005.25 21h13.5A2.25 2.25 0 0021 18.75V16.5m-13.5-9L12 3m0 0l4.5 4.5M12 3v13.5"/>
+            </svg>
+            <span className={cx('byline-field-image-upload-label', styles.label)}>
+              {t('fields.image.upload.label')}{' '}
+              <span className={cx('byline-field-image-upload-action', styles.action)}>
+                {t('fields.image.upload.browse')}
+              </span>
+            </span>
+            <span className={cx('byline-field-image-upload-hint', styles.hint)}>
+              {t('fields.image.upload.hint')}
+            </span>
+          </>)}
+      </div>
+
+      {/* Error message */}
+      {status === 'error' && errorMessage && (<p className={cx('byline-field-image-upload-error', styles.error)} role="alert">
+          {errorMessage}
+        </p>)}
+    </div>);
+};