@byline/admin 5.1.2 → 5.1.3

package/dist/fields/local-date-time.jsx

@@ -0,0 +1,69 @@
+'use client';
+import { useEffect, useState } from 'react';
+// undefined will use the user's locale
+const dateTimeFormatter = new Intl.DateTimeFormat(undefined, {
+    year: 'numeric',
+    month: 'short', // <- short month text (locale-aware)
+    day: '2-digit',
+    hour: 'numeric',
+    minute: 'numeric',
+});
+const dateFormatter = new Intl.DateTimeFormat(undefined, {
+    year: 'numeric',
+    month: 'short', // <- short month text (locale-aware)
+    day: '2-digit',
+});
+/**
+ * Client-side date/time formatter that displays dates in the user's local timezone.
+ *
+ * This component avoids hydration mismatches by:
+ * 1. Rendering a placeholder on the server/initial render
+ * 2. Updating to the correctly formatted date after hydration
+ *
+ * Use this instead of formatDateTime when you need to display dates
+ * in the user's local timezone rather than UTC.
+ */
+export function LocalDateTime({ value, mode = 'datetime', className, fallback = '—', }) {
+    const [formattedDate, setFormattedDate] = useState(null);
+    useEffect(() => {
+        if (value == null) {
+            setFormattedDate(null);
+            return;
+        }
+        const date = typeof value === 'string' ? Date.parse(value) : value.getTime();
+        if (Number.isNaN(date)) {
+            setFormattedDate('Error');
+            return;
+        }
+        const formatter = mode === 'datetime' ? dateTimeFormatter : dateFormatter;
+        setFormattedDate(formatter.format(date));
+    }, [value, mode]);
+    // Show fallback during SSR and before useEffect runs
+    if (formattedDate === null) {
+        return <span className={className}>{value ? '...' : fallback}</span>;
+    }
+    return <span className={className}>{formattedDate}</span>;
+}
+/**
+ * Formats a date string to the user's local timezone.
+ *
+ * WARNING: Only use this in client components where hydration
+ * mismatches are acceptable or managed. For most cases, prefer
+ * the <LocalDateTime /> component.
+ */
+export function formatLocalDateTime(value) {
+    if (value == null)
+        return '—';
+    const date = typeof value === 'string' ? Date.parse(value) : value.getTime();
+    if (Number.isNaN(date))
+        return 'Error';
+    return dateTimeFormatter.format(date);
+}
+export function formatLocalDate(value) {
+    if (value == null)
+        return '—';
+    const date = typeof value === 'string' ? Date.parse(value) : value.getTime();
+    if (Number.isNaN(date))
+        return 'Error';
+    return dateFormatter.format(date);
+}

package/dist/fields/locale-badge.jsx

@@ -0,0 +1,19 @@
+/**
+ * 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 'clsx';
+import styles from './locale-badge.module.css';
+/**
+ * Small inline badge shown next to the label of a field that has
+ * `localized: true` in its schema definition. Indicates which locale
+ * the editor is currently working in.
+ *
+ * Stable override handle: `.byline-locale-badge`.
+ */
+export const LocaleBadge = ({ locale }) => (<span aria-hidden="true" title={`Localised — editing ${locale.toUpperCase()} content`} className={cx('byline-locale-badge', styles.badge)}>
+    {locale}
+  </span>);

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

@@ -0,0 +1,93 @@
+/**
+ * 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 { useEffect, useState } from 'react';
+import { normalizeNumericValue } from '@byline/core';
+import { Input } from '@byline/ui/react';
+import { useFieldError, useFieldValue } from '../../forms/form-context';
+const COMPLETE_NUMERIC_RE = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+export const NumericalField = ({ field, value, defaultValue, onChange, id, path, components, }) => {
+    const fieldPath = path ?? field.name;
+    const fieldError = useFieldError(fieldPath);
+    const fieldValue = useFieldValue(fieldPath);
+    const incomingValue = value !== undefined ? value : fieldValue !== undefined ? fieldValue : (defaultValue ?? null);
+    const htmlId = id ?? fieldPath;
+    const canonicalDisplay = incomingValue == null ? '' : String(incomingValue);
+    const [displayValue, setDisplayValue] = useState(canonicalDisplay);
+    const [isEditing, setIsEditing] = useState(false);
+    useEffect(() => {
+        if (!isEditing)
+            setDisplayValue(canonicalDisplay);
+    }, [canonicalDisplay, isEditing]);
+    const canonicalize = (nextValue) => {
+        if (nextValue == null || (typeof nextValue === 'string' && nextValue.trim() === ''))
+            return null;
+        if (field.type === 'counter')
+            return undefined;
+        if (typeof nextValue === 'string' && !COMPLETE_NUMERIC_RE.test(nextValue.trim())) {
+            return undefined;
+        }
+        try {
+            return normalizeNumericValue(field.type, nextValue, fieldPath);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const commit = (nextValue) => {
+        const canonical = canonicalize(nextValue);
+        if (canonical !== undefined)
+            onChange?.(canonical);
+        return canonical;
+    };
+    // Custom component slots (from admin config)
+    const slots = components;
+    const CustomLabel = slots?.Label;
+    const CustomHelpText = slots?.HelpText;
+    const CustomField = slots?.Field;
+    const BeforeField = slots?.beforeField;
+    const AfterField = slots?.afterField;
+    // Shared props available to every slot component
+    const slotBaseProps = {
+        field: field,
+        path: fieldPath,
+        value: incomingValue,
+        error: fieldError,
+        id: htmlId,
+    };
+    const hasCustomLabel = !!CustomLabel;
+    const suppressInputLabel = hasCustomLabel;
+    const suppressInputHelpText = !!CustomHelpText;
+    // ── Label rendering ──────────────────────────────────────────
+    const renderLabel = () => {
+        if (hasCustomLabel) {
+            return <CustomLabel {...slotBaseProps} label={field.label} required={!field.optional}/>;
+        }
+        return null;
+    };
+    // ── Field input rendering ────────────────────────────────────
+    const renderInput = () => {
+        if (CustomField) {
+            return (<CustomField {...slotBaseProps} onChange={(nextValue) => commit(nextValue)} defaultValue={defaultValue} placeholder={field.placeholder}/>);
+        }
+        return (<Input type="text" inputMode={field.type === 'integer' || field.type === 'counter' ? 'numeric' : 'decimal'} step={field.type === 'integer' || field.type === 'counter' ? 1 : 'any'} id={htmlId} name={field.name} label={suppressInputLabel ? undefined : field.label} required={!field.optional} readOnly={field.readOnly} helpText={suppressInputHelpText ? undefined : field.helpText} value={displayValue} onFocus={() => setIsEditing(true)} onChange={(e) => {
+                setDisplayValue(e.target.value);
+                commit(e.target.value);
+            }} onBlur={() => {
+                setIsEditing(false);
+                const canonical = commit(displayValue);
+                setDisplayValue(canonical === undefined ? canonicalDisplay : (canonical?.toString() ?? ''));
+            }} error={fieldError != null} errorText={fieldError}/>);
+    };
+    return (<div className={`byline-field-${field.type} ${field.name}`}>
+      {renderLabel()}
+      {BeforeField && <BeforeField {...slotBaseProps}/>}
+      {renderInput()}
+      {AfterField && <AfterField {...slotBaseProps}/>}
+      {CustomHelpText && <CustomHelpText {...slotBaseProps} helpText={field.helpText}/>}
+    </div>);
+};

package/dist/fields/relation/relation-column-formatter.jsx

@@ -0,0 +1,74 @@
+/**
+ * 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 { getCollectionDefinition } from '@byline/core';
+import { resolveFallbackDisplayField, resolveRowLabel } from './relation-display';
+/** Max titles shown for a hasMany cell before collapsing to "+N more". */
+const MAX_SHOWN = 3;
+function labelFor(env, displayField) {
+    // Unresolved (deleted / out-of-scope target) or not populated → no title.
+    if (env == null || env._resolved === false || env.document == null)
+        return null;
+    return resolveRowLabel(env.document, displayField);
+}
+/**
+ * Pure text projection of a relation cell: the target's title for a single
+ * relation, or "A, B, +N more" for `hasMany`. Unresolved targets are skipped;
+ * an all-empty cell yields `null` (the formatter renders a muted dash).
+ *
+ * `displayField` is the resolved chain
+ * (`field.displayField` → target `useAsTitle` → first text field).
+ */
+export function formatRelationCellText(field, value, displayField) {
+    const envelopes = field.hasMany
+        ? Array.isArray(value)
+            ? value
+            : []
+        : value
+            ? [value]
+            : [];
+    const labels = envelopes
+        .map((env) => labelFor(env, displayField))
+        .filter((l) => l != null && l.length > 0);
+    if (labels.length === 0)
+        return null;
+    if (!field.hasMany)
+        return labels[0] ?? null;
+    const shown = labels.slice(0, MAX_SHOWN);
+    const extra = labels.length - shown.length;
+    return extra > 0 ? `${shown.join(', ')}, +${extra} more` : shown.join(', ');
+}
+/**
+ * The built-in `{ component }` column formatter for a `relation` field. Resolves
+ * the target collection's `useAsTitle` at render time and renders the cell text.
+ */
+export function relationColumnFormatter(field) {
+    return {
+        component: ({ value }) => {
+            const targetDef = getCollectionDefinition(field.targetCollection);
+            const displayField = field.displayField ?? targetDef?.useAsTitle ?? resolveFallbackDisplayField(targetDef);
+            const text = formatRelationCellText(field, value, displayField);
+            return text != null ? (<span className="byline-relation-column">{text}</span>) : (<span className="byline-relation-column-empty muted">—</span>);
+        },
+    };
+}
+/**
+ * Return a copy of `columns` with {@link relationColumnFormatter} applied to any
+ * `relation`-typed column that doesn't already declare its own formatter, so
+ * relation cells render target titles by default. Other columns are untouched.
+ */
+export function applyRelationColumnFormatters(columns, definition) {
+    return columns.map((col) => {
+        if (col.formatter)
+            return col;
+        const field = definition.fields.find((f) => f.name === String(col.fieldName));
+        if (field?.type === 'relation') {
+            return { ...col, formatter: relationColumnFormatter(field) };
+        }
+        return col;
+    });
+}

package/dist/fields/relation/relation-display.jsx

@@ -0,0 +1,118 @@
+/**
+ * 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 'clsx';
+import styles from './relation-display.module.css';
+// ---------------------------------------------------------------------------
+// Shared render helpers used by both the relation picker modal rows and
+// the relation-summary tile on the edit form. Kept in lock-step so a row
+// rendered in the picker looks identical to the selected tile.
+// ---------------------------------------------------------------------------
+/**
+ * Render a single row cell from a `ColumnDefinition`, reading the value
+ * from the document's `fields` (with a fallback to top-level metadata like
+ * `status`, `updated_at`, `path`). Honours both formatter shapes — plain
+ * function → its return value, `{ component }` → the component is rendered.
+ */
+export function PickerCell({ column, record, }) {
+    const name = String(column.fieldName);
+    const value = record?.fields?.[name] ?? record?.[name];
+    let content;
+    if (column.formatter) {
+        if (typeof column.formatter === 'function') {
+            content = column.formatter(value, record);
+        }
+        else {
+            const Comp = column.formatter.component;
+            content = <Comp value={value} record={record}/>;
+        }
+    }
+    else if (value == null) {
+        content = null;
+    }
+    else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        content = String(value);
+    }
+    else {
+        content = null;
+    }
+    return (<div className={cx('byline-relation-cell', styles.cell, column.align === 'center' && ['byline-relation-cell-center', styles['cell-center']], column.align === 'right' && ['byline-relation-cell-right', styles['cell-right']], column.className)}>
+      {content}
+    </div>);
+}
+/** First top-level `text` field name on a collection, or null. */
+export function resolveFallbackDisplayField(def) {
+    if (!def)
+        return null;
+    const textField = def.fields.find((f) => f.type === 'text');
+    return textField?.name ?? null;
+}
+/** Resolve the row's primary label text from the document. */
+export function resolveRowLabel(doc, displayField) {
+    if (!doc)
+        return null;
+    if (displayField) {
+        const v = doc.fields?.[displayField];
+        if (typeof v === 'string' && v.length > 0)
+            return v;
+    }
+    if (typeof doc.fields?.title === 'string' && doc.fields.title.length > 0) {
+        return doc.fields.title;
+    }
+    if (typeof doc.path === 'string' && doc.path.length > 0)
+        return doc.path;
+    return null;
+}
+/**
+ * Build the `fields` projection for the picker listing. Unions:
+ *   - caller-supplied `displayField`
+ *   - target schema's `useAsTitle` (always included, even when not visible)
+ *   - every `fieldName` declared in the admin config's `picker` columns
+ *   - `title` (metadata fallback for rows with no explicit picker columns)
+ *
+ * Note that the document `path` is top-level metadata on every list response
+ * — it is always returned by `getCollectionDocuments` regardless of the
+ * `fields` projection. Callers that need `{ title, path }` for downstream
+ * normalisation (e.g. the rich-text link plugin) can rely on:
+ *   - `record.fields[def.useAsTitle]` for the title
+ *   - `record.path` for the path
+ *
+ * Returns `undefined` when no target definition is available, leaving the
+ * listing endpoint to decide its own default projection.
+ */
+export function resolveSelectFields(def, displayField, pickerColumns, extraFields) {
+    if (!def)
+        return undefined;
+    const out = new Set();
+    if (displayField)
+        out.add(displayField);
+    if (def.useAsTitle)
+        out.add(def.useAsTitle);
+    const fallback = resolveFallbackDisplayField(def);
+    if (fallback)
+        out.add(fallback);
+    if (pickerColumns) {
+        for (const col of pickerColumns) {
+            const name = String(col.fieldName);
+            if (def.fields.some((f) => f.name === name))
+                out.add(name);
+        }
+    }
+    // Extra non-display fields a consumer needs on `record.fields` (e.g. the
+    // inline-image modal seeding alt-text). Loaded but not rendered as columns.
+    if (extraFields) {
+        for (const name of extraFields) {
+            if (def.fields.some((f) => f.name === name))
+                out.add(name);
+        }
+    }
+    if (def.fields.some((f) => f.name === 'title'))
+        out.add('title');
+    if (out.size === 0)
+        return undefined;
+    return Array.from(out);
+}

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

@@ -0,0 +1,108 @@
+/**
+ * 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 { getCollectionAdminConfig, getCollectionDefinition, isSingleton } from '@byline/core';
+import { useTranslation } from '@byline/i18n/react';
+import { Button, CloseIcon, EditIcon, ErrorText, HelpText, IconButton, Label, } from '@byline/ui/react';
+import cx from 'clsx';
+import { useFieldError, useFieldValue } from '../../forms/form-context';
+import styles from './relation-field.module.css';
+import { RelationPicker } from './relation-picker';
+import { RelationSummary } from './relation-summary';
+export const RelationField = ({ field, value, defaultValue, onChange, id, path, }) => {
+    const fieldPath = path ?? field.name;
+    const htmlId = id ?? fieldPath;
+    const fieldError = useFieldError(fieldPath);
+    const fieldValue = useFieldValue(fieldPath);
+    const incomingValue = fieldValue !== undefined
+        ? (fieldValue ?? null)
+        : (value ??
+            defaultValue ??
+            null);
+    // Resolve the target collection definition + admin config. The admin
+    // config drives the picker-column rendering inside RelationSummary so
+    // the selected tile matches the picker row exactly. Missing target →
+    // render an inline error and disable the picker.
+    const targetDefinition = getCollectionDefinition(field.targetCollection);
+    const targetDef = targetDefinition != null && !isSingleton(targetDefinition) ? targetDefinition : null;
+    const targetAdminConfig = getCollectionAdminConfig(field.targetCollection);
+    const { t } = useTranslation('byline-admin');
+    const [pickerOpen, setPickerOpen] = useState(false);
+    // Cached target document from the most recent picker selection. Lets the
+    // tile render real display data (name, thumbnail) immediately after a
+    // pick without a round trip. Cleared via the `targetDocumentId`
+    // comparison in the render path.
+    const [pickedRecord, setPickedRecord] = useState(null);
+    const handleSelect = (selection) => {
+        setPickerOpen(false);
+        if (selection.record) {
+            setPickedRecord({ id: selection.targetDocumentId, record: selection.record });
+        }
+        else {
+            setPickedRecord(null);
+        }
+        onChange?.({
+            targetDocumentId: selection.targetDocumentId,
+            targetCollectionId: selection.targetCollectionId,
+        });
+    };
+    const handleRemove = () => {
+        setPickedRecord(null);
+        onChange?.(null);
+    };
+    // Only carry the cached picker record through to the summary when it
+    // still matches the current value — guards against a stale cache after
+    // an external value change (e.g. patch rollback).
+    const cachedRecord = pickedRecord && incomingValue && pickedRecord.id === incomingValue.targetDocumentId
+        ? pickedRecord.record
+        : null;
+    const isUnknown = targetDef == null;
+    return (<div className={`byline-field-relation ${field.name}`}>
+      <div className={cx('byline-field-relation-header', styles.header)}>
+        <Label id={`${htmlId}-label`} htmlFor={htmlId} label={field.label ?? field.name} required={!field.optional}/>
+      </div>
+      {isUnknown ? (<div className={cx('byline-field-relation-error-tile', styles['error-tile'])}>
+          <span>
+            {t('fields.relation.unknownError', {
+                name: field.name,
+                target: field.targetCollection,
+            })}
+          </span>
+          <span className={cx('byline-field-relation-error-text', styles['error-text'])}>
+            {t('fields.relation.unknownHint')}
+          </span>
+        </div>) : (
+        // Rounded frame below the label wrapping the interactive body
+        // (selected tile or select button) — see `.frame` in the CSS module.
+        <div className={cx('byline-field-relation-frame', styles.frame)}>
+          {incomingValue ? (<div className={cx('byline-field-relation-tile', styles.tile)}>
+              <RelationSummary targetDefinition={targetDef} targetAdminConfig={targetAdminConfig} displayField={field.displayField} value={incomingValue} cachedRecord={cachedRecord}/>
+              <div className={cx('byline-field-relation-actions', styles.actions)}>
+                <IconButton id={htmlId} type="button" intent="noeffect" size="xs" aria-label={t('fields.relation.changeAriaLabel', {
+                    label: targetDef.labels.singular,
+                })} onClick={() => setPickerOpen(true)}>
+                  <EditIcon width="15px" height="15px"/>
+                </IconButton>
+                <IconButton type="button" intent="noeffect" size="xs" aria-label={t('fields.relation.removeAriaLabel', {
+                    label: targetDef.labels.singular,
+                })} onClick={handleRemove}>
+                  <CloseIcon width="15px" height="15px"/>
+                </IconButton>
+              </div>
+            </div>) : (<Button id={htmlId} size="xs" variant="outlined" intent="noeffect" type="button" onClick={() => setPickerOpen(true)}>
+              {t('fields.relation.selectButton', { label: targetDef.labels.singular })}
+            </Button>)}
+        </div>)}
+
+      {field.helpText != null && <HelpText text={field.helpText}/>}
+
+      {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError}/>}
+
+      {!isUnknown && (<RelationPicker targetCollectionPath={field.targetCollection} targetDefinition={targetDef} displayField={field.displayField} isOpen={pickerOpen} onSelect={handleSelect} onDismiss={() => setPickerOpen(false)}/>)}
+    </div>);
+};

package/dist/fields/relation/relation-many-field.jsx

@@ -0,0 +1,142 @@
+/**
+ * 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 { getCollectionAdminConfig, getCollectionDefinition, isSingleton } from '@byline/core';
+import { useTranslation } from '@byline/i18n/react';
+import { Button, CloseIcon, DraggableSortable, ErrorText, GripperVerticalIcon, HelpText, IconButton, Label, moveItem, PlusIcon, useSortable, } from '@byline/ui/react';
+import cx from 'clsx';
+import { useFieldError, useFieldValue, useFormContext } from '../../forms/form-context';
+import styles from './relation-field.module.css';
+import { RelationPicker } from './relation-picker';
+import { RelationSummary } from './relation-summary';
+const RelationManyTile = ({ id, children, onRemove, removeAriaLabel }) => {
+    const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+        id,
+        transition: { duration: 250, easing: 'cubic-bezier(0, 0.2, 0.2, 1)' },
+    });
+    const style = {
+        transform: transform ? `translate3d(${transform.x}px, ${transform.y}px, 0)` : undefined,
+        transition,
+        zIndex: isDragging ? 10 : 'auto',
+    };
+    return (<div ref={setNodeRef} style={style} className={cx('byline-field-relation-many-tile', styles['many-tile'], isDragging && ['byline-field-relation-many-tile-dragging', styles['many-tile-dragging']])}>
+      <button type="button" className={cx('byline-field-relation-many-grip', styles['many-grip'])} {...attributes} {...listeners}>
+        <GripperVerticalIcon />
+      </button>
+      <div className={cx('byline-field-relation-many-body', styles['many-body'])}>{children}</div>
+      <IconButton type="button" size="xs" intent="noeffect" aria-label={removeAriaLabel} className={cx('byline-field-relation-many-remove', styles['many-remove'])} onClick={onRemove}>
+        <CloseIcon width="14px" height="14px"/>
+      </IconButton>
+    </div>);
+};
+export const RelationManyField = ({ field, defaultValue, id, path }) => {
+    const fieldPath = path ?? field.name;
+    const htmlId = id ?? fieldPath;
+    const { t } = useTranslation('byline-admin');
+    const fieldError = useFieldError(fieldPath);
+    const { getFieldValue, setFieldValue } = useFormContext();
+    const targetDefinition = getCollectionDefinition(field.targetCollection);
+    const targetDef = targetDefinition != null && !isSingleton(targetDefinition) ? targetDefinition : null;
+    const targetAdminConfig = getCollectionAdminConfig(field.targetCollection);
+    const isUnknown = targetDef == null;
+    const targetLabel = targetDef?.labels.singular ?? field.targetCollection;
+    const [pickerOpen, setPickerOpen] = useState(false);
+    // Records handed back by the picker, keyed by target id — lets a freshly
+    // added tile render real display data (title / thumbnail) without a refetch.
+    const [pickedRecords, setPickedRecords] = useState({});
+    // Subscribe to the live array so reorders / adds / removes re-render.
+    const liveValue = useFieldValue(fieldPath);
+    const items = Array.isArray(liveValue)
+        ? liveValue
+        : Array.isArray(defaultValue)
+            ? defaultValue
+            : [];
+    const currentArray = () => {
+        const v = getFieldValue(fieldPath);
+        if (Array.isArray(v))
+            return v;
+        return Array.isArray(defaultValue) ? defaultValue : [];
+    };
+    const handleAddMany = (selections) => {
+        setPickerOpen(false);
+        const current = currentArray();
+        // Dedup the batch against the current array — a target may appear at most
+        // once. The picker already disables already-added rows, so this is a
+        // belt-and-braces guard for stale state (e.g. a concurrent remove).
+        const existing = new Set(current.map((v) => v.targetDocumentId));
+        const additions = selections.filter((s) => !existing.has(s.targetDocumentId));
+        if (additions.length === 0)
+            return;
+        const records = additions.filter((s) => s.record != null);
+        if (records.length > 0) {
+            setPickedRecords((prev) => {
+                const next = { ...prev };
+                for (const s of records)
+                    next[s.targetDocumentId] = s.record;
+                return next;
+            });
+        }
+        setFieldValue(fieldPath, [
+            ...current,
+            ...additions.map((s) => ({
+                targetDocumentId: s.targetDocumentId,
+                targetCollectionId: s.targetCollectionId,
+            })),
+        ]);
+    };
+    const handleRemove = (targetDocumentId) => {
+        setFieldValue(fieldPath, currentArray().filter((v) => v.targetDocumentId !== targetDocumentId));
+    };
+    const handleDragEnd = ({ moveFromIndex, moveToIndex, }) => {
+        if (moveFromIndex === moveToIndex)
+            return;
+        setFieldValue(fieldPath, moveItem(currentArray(), moveFromIndex, moveToIndex));
+    };
+    return (<div className={`byline-field-relation ${field.name}`}>
+      <div className={cx('byline-field-relation-header', styles.header)}>
+        <Label id={`${htmlId}-label`} htmlFor={htmlId} label={field.label ?? field.name} required={!field.optional}/>
+      </div>
+      {isUnknown ? (<div className={cx('byline-field-relation-error-tile', styles['error-tile'])}>
+          <span>
+            {t('fields.relation.unknownError', {
+                name: field.name,
+                target: field.targetCollection,
+            })}
+          </span>
+          <span className={cx('byline-field-relation-error-text', styles['error-text'])}>
+            {t('fields.relation.unknownHint')}
+          </span>
+        </div>) : (<>
+          {/* Rounded frame below the label wrapping the interactive
+                body (tile list and add button) — see `.frame` in the CSS
+                module. */}
+          <div className={cx('byline-field-relation-frame', styles.frame)}>
+            {items.length === 0 ? (<p className={cx('byline-field-relation-many-empty', styles['many-empty'])}>
+                {t('fields.relation.manyEmpty', { label: targetDef.labels.plural })}
+              </p>) : (<DraggableSortable ids={items.map((v) => v.targetDocumentId)} onDragEnd={handleDragEnd} className={cx('byline-field-relation-many', styles.many)}>
+                {items.map((value) => (<RelationManyTile key={value.targetDocumentId} id={value.targetDocumentId} onRemove={() => handleRemove(value.targetDocumentId)} removeAriaLabel={t('fields.relation.removeAriaLabel', { label: targetLabel })}>
+                    <RelationSummary targetDefinition={targetDef} targetAdminConfig={targetAdminConfig} displayField={field.displayField} value={value} cachedRecord={pickedRecords[value.targetDocumentId] ?? null}/>
+                  </RelationManyTile>))}
+              </DraggableSortable>)}
+
+            <div className={cx('byline-field-relation-many-add', styles['many-add'])}>
+              <Button id={htmlId} size="xs" variant="outlined" intent="noeffect" type="button" onClick={() => setPickerOpen(true)}>
+                <PlusIcon width="14px" height="14px"/>
+                {t('fields.relation.addButton', { label: targetLabel })}
+              </Button>
+            </div>
+          </div>
+
+          {field.helpText != null && <HelpText text={field.helpText}/>}
+
+          {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError}/>}
+
+          <RelationPicker multiple targetCollectionPath={field.targetCollection} targetDefinition={targetDef} displayField={field.displayField} isOpen={pickerOpen} excludeIds={items.map((v) => v.targetDocumentId)} onSelectMany={handleAddMany} onDismiss={() => setPickerOpen(false)}/>
+        </>)}
+    </div>);
+};