@byline/admin 5.1.1 → 5.1.3

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

@@ -0,0 +1,240 @@
+/**
+ * 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, useState } from 'react';
+import { getCollectionAdminConfig } from '@byline/core';
+import { useTranslation } from '@byline/i18n/react';
+import { Button, CheckIcon, LoaderRing, Modal, Search } from '@byline/ui/react';
+import cx from 'clsx';
+import { useBylineFieldServices } from '../field-services-context';
+import { PickerCell, resolveFallbackDisplayField, resolveRowLabel, resolveSelectFields, } from './relation-display';
+import styles from './relation-picker.module.css';
+const PAGE_SIZE = 15;
+export const RelationPicker = ({ targetCollectionPath, targetDefinition, displayField, extraSelectFields, isOpen, multiple = false, excludeIds, onSelect, onSelectMany, onDismiss, }) => {
+    const [query, setQuery] = useState('');
+    const [page, setPage] = useState(1);
+    const { t } = useTranslation('byline-admin');
+    const [selectedDocumentId, setSelectedDocumentId] = useState(null);
+    // Multi-select state. A Map keyed by target id preserves pick order (the
+    // confirmed batch appends in that order) and carries each row's record so
+    // picks survive page/search changes that swap out `documents`.
+    const [selectedMap, setSelectedMap] = useState(() => new Map());
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [documents, setDocuments] = useState([]);
+    const [totalPages, setTotalPages] = useState(1);
+    const [collectionId, setCollectionId] = useState(null);
+    const { getCollectionDocuments } = useBylineFieldServices();
+    const targetAdminConfig = getCollectionAdminConfig(targetCollectionPath);
+    const pickerColumns = targetAdminConfig?.itemView;
+    // Reset local state each time the modal opens so prior queries don't leak.
+    useEffect(() => {
+        if (isOpen) {
+            setQuery('');
+            setPage(1);
+            setSelectedDocumentId(null);
+            setSelectedMap(new Map());
+            setError(null);
+        }
+    }, [isOpen]);
+    // Fetch whenever the modal is open and the query / page changes.
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        let cancelled = false;
+        const selectFields = resolveSelectFields(targetDefinition, displayField, pickerColumns, extraSelectFields);
+        setLoading(true);
+        setError(null);
+        // Item-view sort: the target collection's `itemViewSort` (boot-validated)
+        // orders the picker independently of its list view's `defaultSort`.
+        // Passed as explicit params because the list server fn gives an explicit
+        // `order` top precedence; when absent the server falls back through
+        // `defaultSort` → `created_at desc` (or `order_key asc` for orderable
+        // collections) exactly as before.
+        const itemViewSort = targetAdminConfig?.itemViewSort;
+        getCollectionDocuments({
+            collection: targetCollectionPath,
+            params: {
+                page,
+                page_size: PAGE_SIZE,
+                query: query.length > 0 ? query : undefined,
+                fields: selectFields,
+                ...(itemViewSort != null
+                    ? { order: String(itemViewSort.field), desc: itemViewSort.direction === 'desc' }
+                    : {}),
+            },
+        })
+            .then((response) => {
+            if (cancelled)
+                return;
+            setDocuments(response.docs);
+            setTotalPages(response.meta.totalPages ?? 1);
+            setCollectionId(response.included.collection.id);
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            setError(err instanceof Error ? err.message : t('fields.relation.picker.loadFailed'));
+        })
+            .finally(() => {
+            if (!cancelled)
+                setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        isOpen,
+        targetCollectionPath,
+        query,
+        page,
+        displayField,
+        extraSelectFields,
+        targetDefinition,
+        pickerColumns,
+        getCollectionDocuments,
+        t,
+        targetAdminConfig?.itemViewSort,
+    ]);
+    const resolvedDisplayField = displayField ??
+        targetDefinition?.useAsTitle ??
+        resolveFallbackDisplayField(targetDefinition) ??
+        null;
+    const handleSelect = useCallback(() => {
+        if (!selectedDocumentId || !collectionId || !onSelect)
+            return;
+        const record = documents.find((d) => d?.id === selectedDocumentId);
+        onSelect({
+            targetDocumentId: selectedDocumentId,
+            targetCollectionId: collectionId,
+            record,
+        });
+    }, [selectedDocumentId, collectionId, documents, onSelect]);
+    const handleSelectMany = useCallback(() => {
+        if (selectedMap.size === 0 || !collectionId || !onSelectMany)
+            return;
+        onSelectMany(Array.from(selectedMap, ([targetDocumentId, record]) => ({
+            targetDocumentId,
+            targetCollectionId: collectionId,
+            record,
+        })));
+    }, [selectedMap, collectionId, onSelectMany]);
+    const toggleSelected = useCallback((doc) => {
+        const id = doc.id;
+        setSelectedMap((prev) => {
+            const next = new Map(prev);
+            if (next.has(id)) {
+                next.delete(id);
+            }
+            else {
+                next.set(id, doc);
+            }
+            return next;
+        });
+    }, []);
+    const title = t('fields.relation.selectPickerTitle', {
+        label: targetDefinition?.labels.singular ?? targetCollectionPath,
+    });
+    return (<Modal isOpen={isOpen} onDismiss={onDismiss}>
+      <Modal.Container style={{ maxWidth: '600px', width: '100%' }}>
+        <Modal.Header className={cx('byline-field-relation-picker-header', styles.header)}>
+          <h3 className={cx('byline-field-relation-picker-title', styles.title)}>{title}</h3>
+        </Modal.Header>
+        <Modal.Content>
+          <div className={cx('byline-field-relation-picker-body', styles.body)}>
+            <Search onSearch={(q) => {
+            setPage(1);
+            setQuery(q ?? '');
+        }} onClear={() => {
+            setPage(1);
+            setQuery('');
+        }} inputSize="sm" placeholder={t('fields.relation.picker.searchPlaceholder')}/>
+
+            <div className={cx('byline-field-relation-picker-list', styles.list)}>
+              {loading && documents.length === 0 && (<div className={cx('byline-field-relation-picker-loading', styles.loading)}>
+                  <LoaderRing size={24} color="#888888"/>
+                </div>)}
+              {!loading && error && (<div className={cx('byline-field-relation-picker-error', styles.error)}>
+                  {error}
+                </div>)}
+              {!loading && !error && documents.length === 0 && (<div className={cx('byline-field-relation-picker-empty', styles.empty)}>
+                  {t('fields.relation.picker.empty')}
+                </div>)}
+              {documents.length > 0 && (<ul className={cx('byline-field-relation-picker-rows', styles.rows)}>
+                  {documents.map((doc) => {
+                const id = doc.id;
+                const selected = multiple ? selectedMap.has(id) : selectedDocumentId === id;
+                const excluded = multiple && (excludeIds?.includes(id) ?? false);
+                return (<li key={id}>
+                        <button type="button" disabled={excluded} aria-pressed={multiple ? selected : undefined} title={excluded ? t('fields.relation.picker.alreadyAdded') : undefined} className={cx('byline-field-relation-picker-row-button', styles['row-button'], multiple && [
+                        'byline-field-relation-picker-row-multi',
+                        styles['row-multi'],
+                    ], selected && [
+                        'byline-field-relation-picker-row-selected',
+                        styles['row-selected'],
+                    ], excluded && [
+                        'byline-field-relation-picker-row-added',
+                        styles['row-added'],
+                    ])} onClick={() => {
+                        if (excluded)
+                            return;
+                        if (multiple) {
+                            toggleSelected(doc);
+                        }
+                        else {
+                            setSelectedDocumentId(id);
+                        }
+                    }}>
+                          {multiple && (<span aria-hidden="true" className={cx('byline-field-relation-picker-check', styles.check, (selected || excluded) && [
+                            'byline-field-relation-picker-check-checked',
+                            styles['check-checked'],
+                        ])}>
+                              {(selected || excluded) && <CheckIcon width="12px" height="12px"/>}
+                            </span>)}
+                          {pickerColumns && pickerColumns.length > 0 ? (<div className={cx('byline-field-relation-picker-row-cells', styles['row-cells'])}>
+                              {pickerColumns.map((col) => (<PickerCell key={String(col.fieldName)} column={col} record={doc}/>))}
+                            </div>) : (<div className={cx('byline-field-relation-picker-row-stack', styles['row-stack'])}>
+                              <span className={cx('byline-field-relation-picker-row-label', styles['row-label'])}>
+                                {resolveRowLabel(doc, resolvedDisplayField) || id}
+                              </span>
+                              {typeof doc.path === 'string' && doc.path.length > 0 && (<span className={cx('byline-field-relation-picker-row-path', styles['row-path'])}>
+                                  {doc.path}
+                                </span>)}
+                            </div>)}
+                          {excluded && (<span className={cx('byline-field-relation-picker-added-hint', styles['added-hint'])}>
+                              {t('fields.relation.picker.alreadyAdded')}
+                            </span>)}
+                        </button>
+                      </li>);
+            })}
+                </ul>)}
+            </div>
+
+            {totalPages > 1 && (<div className={cx('byline-field-relation-picker-pager', styles.pager)}>
+                <Button size="xs" variant="outlined" intent="noeffect" type="button" disabled={page <= 1 || loading} onClick={() => setPage((p) => Math.max(1, p - 1))}>
+                  {t('common.pager.previous')}
+                </Button>
+                <span>{t('common.pager.pageOf', { page, total: totalPages })}</span>
+                <Button size="xs" variant="outlined" intent="noeffect" type="button" disabled={page >= totalPages || loading} onClick={() => setPage((p) => Math.min(totalPages, p + 1))}>
+                  {t('common.pager.next')}
+                </Button>
+              </div>)}
+          </div>
+        </Modal.Content>
+        <Modal.Actions>
+          <Button size="sm" intent="noeffect" type="button" onClick={onDismiss} className={cx('byline-field-relation-picker-action', styles.action)}>
+            {t('common.actions.cancel')}
+          </Button>
+          <Button size="sm" className={cx('byline-field-relation-picker-action', styles.action)} intent="primary" type="button" disabled={multiple ? selectedMap.size === 0 : !selectedDocumentId} onClick={multiple ? handleSelectMany : handleSelect}>
+            {multiple
+            ? t('fields.relation.picker.addSelected', { count: selectedMap.size })
+            : t('common.actions.select')}
+          </Button>
+        </Modal.Actions>
+      </Modal.Container>
+    </Modal>);
+};

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

@@ -0,0 +1,45 @@
+/**
+ * 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 { PickerCell, resolveFallbackDisplayField, resolveRowLabel } from './relation-display';
+import styles from './relation-summary.module.css';
+export function RelationSummary({ targetDefinition, targetAdminConfig, displayField, value, cachedRecord, }) {
+    const pickerColumns = targetAdminConfig?.itemView;
+    // Unresolved (deleted target).
+    if (value._resolved === false) {
+        return (<div className={cx('byline-relation-summary-stack', styles.stack)}>
+        <span className={cx('byline-relation-summary-kind', styles.kind)}>
+          {targetDefinition.labels.singular}
+        </span>
+        <span className={cx('byline-relation-summary-value-mono byline-relation-summary-missing', styles['value-mono'], styles.missing)}>
+          (target not found) {value.targetDocumentId}
+        </span>
+      </div>);
+    }
+    // Prefer the populated envelope's document; fall back to the cached
+    // picker record; finally fall back to rendering just the raw ref.
+    const record = (value._resolved === true && !value._cycle && value.document) || cachedRecord || null;
+    if (record && pickerColumns && pickerColumns.length > 0) {
+        return (<div className={cx('byline-relation-summary-row', styles.row)}>
+        {pickerColumns.map((col) => (<PickerCell key={String(col.fieldName)} column={col} record={record}/>))}
+      </div>);
+    }
+    const resolvedDisplayField = displayField ??
+        targetDefinition.useAsTitle ??
+        resolveFallbackDisplayField(targetDefinition) ??
+        null;
+    const label = record ? resolveRowLabel(record, resolvedDisplayField) : null;
+    return (<div className={cx('byline-relation-summary-stack', styles.stack)}>
+      <span className={cx('byline-relation-summary-kind', styles.kind)}>
+        {targetDefinition.labels.singular}
+      </span>
+      {label ? (<span className={cx('byline-relation-summary-value', styles.value)}>{label}</span>) : (<span className={cx('byline-relation-summary-value-mono', styles['value-mono'])}>
+          {value.targetDocumentId}
+        </span>)}
+    </div>);
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 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 { ErrorText, Label, Select } from '@byline/ui/react';
+import cx from 'clsx';
+import { useFieldError, useFieldValue, useIsDirty } from '../../forms/form-context';
+import styles from './select-field.module.css';
+export const SelectField = ({ field, value, defaultValue, onChange, id, path, }) => {
+    const fieldPath = path ?? field.name;
+    const fieldError = useFieldError(fieldPath);
+    const isDirty = useIsDirty(fieldPath);
+    const fieldValue = useFieldValue(fieldPath);
+    const incomingValue = value ?? fieldValue ?? defaultValue ?? '';
+    const htmlId = id ?? fieldPath;
+    return (<div className={`byline-field-select ${field.name}`}>
+      {field.label && (<Label id={htmlId} htmlFor={htmlId} label={field.label} required={!field.optional} className={cx('byline-field-select-label', styles.label)}/>)}
+      <Select size="xs" variant="outlined" id={htmlId} name={field.name} placeholder="Select an option" required={!field.optional} value={incomingValue} ariaLabel={field.label} helpText={field.helpText} items={field.options.map((opt) => ({ value: opt.value, label: opt.label }))} onValueChange={(value) => {
+            if (value != null)
+                onChange?.(value);
+        }} className={cx(isDirty && ['byline-field-select-dirty', styles.dirty])}/>
+      {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError}/>}
+    </div>);
+};

package/dist/fields/sortable-item.jsx

@@ -0,0 +1,54 @@
+/**
+ * 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 { useTranslation } from '@byline/i18n/react';
+import { ChevronDownIcon, GripperVerticalIcon, useSortable } from '@byline/ui/react';
+import cx from 'clsx';
+import { DraggableContextMenu } from './draggable-context-menu';
+import styles from './sortable-item.module.css';
+const ItemFrame = ({ label, children, onAddBelow, onRemove, grip, rootRef, style, dragging = false, rootClassName, }) => {
+    const { t } = useTranslation('byline-admin');
+    const [collapsed, setCollapsed] = useState(false);
+    return (<div ref={rootRef} style={style} className={cx('byline-sortable', styles.root, rootClassName, dragging && ['byline-sortable-dragging', styles.dragging], collapsed && ['byline-sortable-collapsed', styles.collapsed])}>
+      <div className={cx('byline-sortable-header', styles.header, !collapsed && ['byline-sortable-header-expanded', styles['header-expanded']])}>
+        {grip}
+        <div className={cx('byline-sortable-label', styles.label)}>{label}</div>
+        <DraggableContextMenu onAddBelow={onAddBelow} onRemove={onRemove}/>
+        <button type="button" className={cx('byline-sortable-toggle', styles.toggle)} onClick={() => setCollapsed((prev) => !prev)} aria-label={collapsed
+            ? t('fields.sortable.expandAriaLabel')
+            : t('fields.sortable.collapseAriaLabel')}>
+          <ChevronDownIcon className={cx('byline-sortable-toggle-icon', styles['toggle-icon'], collapsed && ['byline-sortable-toggle-icon-rotated', styles['toggle-icon-rotated']])}/>
+        </button>
+      </div>
+      <div className={cx('byline-sortable-content', styles.content, collapsed && ['byline-sortable-content-hidden', styles['content-hidden']])}>
+        {children}
+      </div>
+    </div>);
+};
+export const SortableItem = ({ id, label, children, onAddBelow, onRemove, }) => {
+    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 (<ItemFrame label={label} onAddBelow={onAddBelow} onRemove={onRemove} rootRef={setNodeRef} style={style} dragging={isDragging} grip={<button type="button" className={cx('byline-sortable-grip', styles.grip)} {...attributes} {...listeners}>
+          <GripperVerticalIcon className={cx('byline-sortable-grip-icon', styles['grip-icon'])}/>
+        </button>}>
+      {children}
+    </ItemFrame>);
+};
+export const StaticItem = ({ label, children, onAddBelow, onRemove, }) => (<ItemFrame label={label} onAddBelow={onAddBelow} onRemove={onRemove} rootClassName="byline-sortable-static">
+    {children}
+  </ItemFrame>);

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

@@ -0,0 +1,79 @@
+/**
+ * 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 } from 'react';
+import { Input, Label } from '@byline/ui/react';
+import cx from 'clsx';
+import { useFieldError, useFieldValue } from '../../forms/form-context';
+import { LocaleBadge } from '../locale-badge';
+import styles from './text-field.module.css';
+export const TextField = ({ field, value, defaultValue, onChange, id, path, locale, components, }) => {
+    const fieldPath = path ?? field.name;
+    const fieldError = useFieldError(fieldPath);
+    const fieldValue = useFieldValue(fieldPath);
+    const incomingValue = value ?? fieldValue ?? defaultValue ?? '';
+    const htmlId = id ?? fieldPath;
+    const handleChange = useCallback((value) => {
+        if (onChange) {
+            onChange(value);
+        }
+    }, [onChange]);
+    // 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,
+    };
+    // When a locale is active, render a custom Label+badge and suppress the
+    // Input's own label so the locale indicator appears in the label row.
+    const showBadge = !!locale && !!field.label;
+    // Determine whether the label is handled externally (by a custom slot or
+    // the locale badge row) so Input doesn't render its own.
+    const hasCustomLabel = !!CustomLabel;
+    const suppressInputLabel = showBadge || hasCustomLabel;
+    const suppressInputHelpText = !!CustomHelpText;
+    const labelRowClass = cx('byline-field-text-label-row', styles['label-row']);
+    // ── Label rendering ──────────────────────────────────────────
+    const renderLabel = () => {
+        if (hasCustomLabel) {
+            return (<div className={labelRowClass}>
+          <CustomLabel {...slotBaseProps} label={field.label} required={!field.optional}/>
+          {showBadge && <LocaleBadge locale={locale}/>}
+        </div>);
+        }
+        if (showBadge) {
+            return (<div className={labelRowClass}>
+          <Label id={`${htmlId}-label`} htmlFor={htmlId} label={field.label} required={!field.optional}/>
+          <LocaleBadge locale={locale}/>
+        </div>);
+        }
+        return null;
+    };
+    // ── Field input rendering ────────────────────────────────────
+    const renderInput = () => {
+        if (CustomField) {
+            return (<CustomField {...slotBaseProps} onChange={handleChange} defaultValue={defaultValue} placeholder={field.placeholder}/>);
+        }
+        return (<Input id={htmlId} name={field.name} label={suppressInputLabel ? undefined : field.label} required={!field.optional} helpText={suppressInputHelpText ? undefined : field.helpText} value={incomingValue} onChange={(e) => handleChange(e.target.value)} error={fieldError != null} errorText={fieldError}/>);
+    };
+    return (<div className={`byline-field-text ${field.name}`}>
+      {renderLabel()}
+      {BeforeField && <BeforeField {...slotBaseProps}/>}
+      {renderInput()}
+      {AfterField && <AfterField {...slotBaseProps}/>}
+      {CustomHelpText && <CustomHelpText {...slotBaseProps} helpText={field.helpText}/>}
+    </div>);
+};

package/dist/fields/text-area/text-area-field.jsx

@@ -0,0 +1,79 @@
+/**
+ * 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 } from 'react';
+import { Label, TextArea } from '@byline/ui/react';
+import cx from 'clsx';
+import { useFieldError, useFieldValue } from '../../forms/form-context';
+import { LocaleBadge } from '../locale-badge';
+import styles from './text-area-field.module.css';
+export const TextAreaField = ({ field, value, defaultValue, onChange, id, path, locale, components, }) => {
+    const fieldPath = path ?? field.name;
+    const fieldError = useFieldError(fieldPath);
+    const fieldValue = useFieldValue(fieldPath);
+    const incomingValue = value ?? fieldValue ?? defaultValue ?? '';
+    const htmlId = id ?? fieldPath;
+    const handleChange = useCallback((value) => {
+        if (onChange) {
+            onChange(value);
+        }
+    }, [onChange]);
+    // 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,
+    };
+    // When a locale is active, render a custom Label+badge and suppress the
+    // TextArea's own label so the locale indicator appears in the label row.
+    const showBadge = !!locale && !!field.label;
+    // Determine whether the label is handled externally (by a custom slot or
+    // the locale badge row) so TextArea doesn't render its own.
+    const hasCustomLabel = !!CustomLabel;
+    const suppressInputLabel = showBadge || hasCustomLabel;
+    const suppressInputHelpText = !!CustomHelpText;
+    const labelRowClass = cx('byline-field-text-area-label-row', styles['label-row']);
+    // ── Label rendering ──────────────────────────────────────────
+    const renderLabel = () => {
+        if (hasCustomLabel) {
+            return (<div className={labelRowClass}>
+          <CustomLabel {...slotBaseProps} label={field.label} required={!field.optional}/>
+          {showBadge && <LocaleBadge locale={locale}/>}
+        </div>);
+        }
+        if (showBadge) {
+            return (<div className={labelRowClass}>
+          <Label id={`${htmlId}-label`} htmlFor={htmlId} label={field.label} required={!field.optional}/>
+          <LocaleBadge locale={locale}/>
+        </div>);
+        }
+        return null;
+    };
+    // ── Field input rendering ────────────────────────────────────
+    const renderInput = () => {
+        if (CustomField) {
+            return (<CustomField {...slotBaseProps} onChange={handleChange} defaultValue={defaultValue} placeholder={field.placeholder}/>);
+        }
+        return (<TextArea id={htmlId} name={field.name} label={suppressInputLabel ? undefined : field.label} required={!field.optional} helpText={suppressInputHelpText ? undefined : field.helpText} value={incomingValue} onChange={(e) => handleChange(e.target.value)} error={fieldError != null} errorText={fieldError} rows={4}/>);
+    };
+    return (<div className={`byline-field-text-area ${field.name}`}>
+      {renderLabel()}
+      {BeforeField && <BeforeField {...slotBaseProps}/>}
+      {renderInput()}
+      {AfterField && <AfterField {...slotBaseProps}/>}
+      {CustomHelpText && <CustomHelpText {...slotBaseProps} helpText={field.helpText}/>}
+    </div>);
+};

package/dist/forms/available-locales-reconcile.test.node.js

@@ -0,0 +1,43 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+import { reconcileLocaleState } from './available-locales-reconcile.js';
+/**
+ * The widget's reconciliation is expressed purely as Checkbox intent +
+ * disabled state — no per-row text. `reconcileLocaleState` is the pure heart
+ * of that mapping; the four cells below are the full truth table from
+ * docs/08-internationalization/index.md.
+ */
+describe('reconcileLocaleState', () => {
+    it('ledger-complete + advertised → green, enabled (advertised & complete)', () => {
+        expect(reconcileLocaleState(true, true)).toEqual({ intent: 'success', disabled: false });
+    });
+    it('ledger-complete + not advertised → green, enabled (invitation to advertise)', () => {
+        expect(reconcileLocaleState(false, true)).toEqual({ intent: 'success', disabled: false });
+    });
+    it('not complete + advertised → amber, enabled (advertising an incomplete locale)', () => {
+        // The ⚠ row: surfaced as `warning` and kept enabled so the editor can
+        // uncheck to resolve the over-advertisement.
+        expect(reconcileLocaleState(true, false)).toEqual({ intent: 'warning', disabled: false });
+    });
+    it('not complete + not advertised → gray, disabled (nothing to advertise)', () => {
+        expect(reconcileLocaleState(false, false)).toEqual({ intent: 'noeffect', disabled: true });
+    });
+    it('completeness drives green regardless of advertised state', () => {
+        // The ledger fact wins the colour when complete; only the disabled/amber
+        // distinction depends on the advertised flag.
+        expect(reconcileLocaleState(true, true).intent).toBe('success');
+        expect(reconcileLocaleState(false, true).intent).toBe('success');
+    });
+    it('only the not-complete + not-advertised cell is non-interactive', () => {
+        expect(reconcileLocaleState(true, true).disabled).toBe(false);
+        expect(reconcileLocaleState(false, true).disabled).toBe(false);
+        expect(reconcileLocaleState(true, false).disabled).toBe(false);
+        expect(reconcileLocaleState(false, false).disabled).toBe(true);
+    });
+});

package/dist/forms/available-locales-widget.jsx

@@ -0,0 +1,63 @@
+'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 { useCallback, useMemo } from 'react';
+import { useTranslation } from '@byline/i18n/react';
+import { Checkbox, Label } from '@byline/ui/react';
+import cx from 'clsx';
+import { reconcileLocaleState } from './available-locales-reconcile';
+import styles from './available-locales-widget.module.css';
+import { useFormContext, useSystemAvailableLocales } from './form-context';
+export { reconcileLocaleState } from './available-locales-reconcile';
+/**
+ * System-managed `availableLocales` widget — the editorial "advertise these
+ * content locales" control. Renders one checkbox per content locale in the
+ * sidebar, directly below the path widget. The checked state reflects the
+ * stored advertised set (`useSystemAvailableLocales`); each row's intent
+ * reconciles that against the structural ledger fact (`availableVersionLocales`)
+ * via {@link reconcileLocaleState}. Opt-in: nothing is advertised until the
+ * editor checks a (green) locale.
+ *
+ * Stable override handles: `.byline-form-available-locales`,
+ * `.byline-form-available-locales-list`.
+ */
+export const AvailableLocalesWidget = ({ disabled: mutationsBlocked = false, contentLocales, availableVersionLocales, }) => {
+    const { t } = useTranslation('byline-admin');
+    const { setSystemAvailableLocales } = useFormContext();
+    const advertised = useSystemAvailableLocales();
+    const advertisedSet = useMemo(() => new Set(advertised), [advertised]);
+    const ledgerSet = useMemo(() => new Set(availableVersionLocales), [availableVersionLocales]);
+    const toggle = useCallback((code, checked) => {
+        if (mutationsBlocked)
+            return;
+        const next = new Set(advertised);
+        if (checked) {
+            next.add(code);
+        }
+        else {
+            next.delete(code);
+        }
+        setSystemAvailableLocales([...next]);
+    }, [mutationsBlocked, advertised, setSystemAvailableLocales]);
+    if (contentLocales.length === 0) {
+        return null;
+    }
+    return (<div className={cx('byline-form-available-locales', styles.container)}>
+      <Label id="available-locales" htmlFor="available-locales-group" label={t('availableLocalesWidget.label')}/>
+      <div id="available-locales-group" className={cx('byline-form-available-locales-list', styles.list)} role="group" aria-labelledby="label-for-available-locales" aria-describedby="available-locales-description">
+        {contentLocales.map(({ code, label }) => {
+            const checked = advertisedSet.has(code);
+            const { intent, disabled } = reconcileLocaleState(checked, ledgerSet.has(code));
+            return (<Checkbox key={code} id={`available-locale-${code}`} name={`__availableLocale_${code}__`} label={label} intent={intent} checked={checked} disabled={mutationsBlocked || disabled} onCheckedChange={(value) => toggle(code, value === true)}/>);
+        })}
+      </div>
+      <span id="available-locales-description" className={cx('byline-form-available-locales-sr-only', styles['sr-only'])}>
+        {t('availableLocalesWidget.srDescription')}
+      </span>
+    </div>);
+};