@byline/admin 2.5.2 → 2.6.0

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

@@ -0,0 +1,211 @@
+/**
+ * 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 type {
+  CollectionAdminConfig,
+  CollectionDefinition,
+  RelationField as FieldType,
+  RelatedDocumentValue,
+} from '@byline/core'
+import { getCollectionAdminConfig, getCollectionDefinition } from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
+import { Button, CloseIcon, EditIcon, ErrorText, IconButton, Label } from '@byline/ui/react'
+import cx from 'classnames'
+
+import { useFieldError, useFieldValue } from '../../forms/form-context'
+import styles from './relation-field.module.css'
+import { RelationPicker } from './relation-picker'
+import { RelationSummary } from './relation-summary'
+
+// The raw form value for a relation field is `RelatedDocumentValue`, but
+// when the edit loader runs server-side populate the value arrives as a
+// `PopulatedRelationValue` (same base shape, plus `_resolved` / `document`
+// discriminator keys). We accept both here and let `RelationSummary`
+// narrow internally.
+type IncomingRelationValue = RelatedDocumentValue & {
+  _resolved?: boolean
+  _cycle?: boolean
+  document?: Record<string, any>
+}
+
+// ---------------------------------------------------------------------------
+// RelationField — widget for `type: 'relation'` fields
+// ---------------------------------------------------------------------------
+
+interface RelationFieldProps {
+  field: FieldType
+  value?: RelatedDocumentValue | null
+  defaultValue?: RelatedDocumentValue | null
+  onChange?: (value: RelatedDocumentValue | null) => void
+  id?: string
+  path?: string
+}
+
+export const RelationField = ({
+  field,
+  value,
+  defaultValue,
+  onChange,
+  id,
+  path,
+}: RelationFieldProps) => {
+  const fieldPath = path ?? field.name
+  const htmlId = id ?? fieldPath
+  const fieldError = useFieldError(fieldPath)
+  const fieldValue = useFieldValue<IncomingRelationValue | null | undefined>(fieldPath)
+
+  const incomingValue: IncomingRelationValue | null =
+    fieldValue !== undefined
+      ? ((fieldValue as IncomingRelationValue | null) ?? null)
+      : ((value as IncomingRelationValue | null) ??
+        (defaultValue as IncomingRelationValue | null) ??
+        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 targetDef: CollectionDefinition | null = getCollectionDefinition(field.targetCollection)
+  const targetAdminConfig: CollectionAdminConfig | null = 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<{
+    id: string
+    record: Record<string, any>
+  } | null>(null)
+
+  const handleSelect = (selection: {
+    targetDocumentId: string
+    targetCollectionId: string
+    record?: Record<string, any>
+  }) => {
+    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>
+      {field.helpText && (
+        <div className={cx('byline-field-relation-help', styles.help)}>{field.helpText}</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>
+      ) : 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>
+      )}
+
+      {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/src/fields/relation/relation-picker.module.css

@@ -0,0 +1,168 @@
+/**
+ * RelationPicker — modal listing for selecting a target document.
+ *
+ * Override handles:
+ *   .byline-field-relation-picker             — picker chrome wrapper
+ *   .byline-field-relation-picker-header      — modal header (title)
+ *   .byline-field-relation-picker-title       — title text
+ *   .byline-field-relation-picker-body        — vertical stack of search + list + pager
+ *   .byline-field-relation-picker-list        — scrollable list container
+ *   .byline-field-relation-picker-loading     — centered spinner row
+ *   .byline-field-relation-picker-error       — error message row
+ *   .byline-field-relation-picker-empty       — "no results" message row
+ *   .byline-field-relation-picker-rows        — <ul> of rows
+ *   .byline-field-relation-picker-row-button  — clickable row button
+ *   .byline-field-relation-picker-row-selected — added when row is selected
+ *   .byline-field-relation-picker-row-cells   — picker-columns layout inside a row
+ *   .byline-field-relation-picker-row-stack   — fallback label/path stack
+ *   .byline-field-relation-picker-row-label   — fallback row label text
+ *   .byline-field-relation-picker-row-path    — fallback row secondary path
+ *   .byline-field-relation-picker-pager       — pager row at the bottom
+ *   .byline-field-relation-picker-action      — Cancel / Select buttons
+ */
+
+.header,
+:global(.byline-field-relation-picker-header) {
+  padding-top: 1rem;
+  margin-bottom: var(--spacing-8);
+}
+
+.title,
+:global(.byline-field-relation-picker-title) {
+  margin: 0 0 var(--spacing-8) 0;
+  font-size: var(--font-size-xl);
+}
+
+.body,
+:global(.byline-field-relation-picker-body) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.list,
+:global(.byline-field-relation-picker-list) {
+  min-height: 320px;
+  max-height: 420px;
+  overflow-y: auto;
+  border: var(--border-width-thin) var(--border-style-solid) var(--gray-700);
+  border-radius: var(--border-radius-md);
+}
+
+.loading,
+:global(.byline-field-relation-picker-loading) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 2.5rem 0;
+}
+
+.error,
+:global(.byline-field-relation-picker-error) {
+  padding: 2.5rem 1rem;
+  color: var(--red-500);
+  font-size: var(--font-size-sm);
+  text-align: center;
+}
+
+.empty,
+:global(.byline-field-relation-picker-empty) {
+  padding: 2.5rem 1rem;
+  color: var(--gray-400);
+  font-size: var(--font-size-sm);
+  text-align: center;
+}
+
+.rows,
+:global(.byline-field-relation-picker-rows) {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.rows > li + li,
+:global(.byline-field-relation-picker-rows) > li + li {
+  border-top: var(--border-width-thin) var(--border-style-solid) var(--gray-700);
+}
+
+.row-button,
+:global(.byline-field-relation-picker-row-button) {
+  width: 100%;
+  padding: var(--spacing-8) 0.75rem;
+  border: none;
+  background: none;
+  text-align: left;
+  color: inherit;
+  cursor: pointer;
+  transition: background-color 150ms ease;
+}
+
+.row-button:hover,
+:global(.byline-field-relation-picker-row-button):hover {
+  background-color: var(--gray-25);
+}
+
+.row-selected,
+:global(.byline-field-relation-picker-row-selected) {
+  background-color: oklch(from var(--primary-200) l c h / 0.3);
+  border-left: 2px solid var(--primary-200);
+}
+
+.row-cells,
+:global(.byline-field-relation-picker-row-cells) {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.row-stack,
+:global(.byline-field-relation-picker-row-stack) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+}
+
+.row-label,
+:global(.byline-field-relation-picker-row-label) {
+  color: var(--gray-100);
+  font-size: var(--font-size-sm);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.row-path,
+:global(.byline-field-relation-picker-row-path) {
+  color: var(--gray-500);
+  font-size: var(--font-size-xs);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.pager,
+:global(.byline-field-relation-picker-pager) {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  color: var(--gray-400);
+  font-size: var(--font-size-xs);
+}
+
+.action,
+:global(.byline-field-relation-picker-action) {
+  min-width: 70px;
+}
+
+:is([data-theme="dark"], :global(.dark)) {
+  .row-button:hover,
+  :global(.byline-field-relation-picker-row-button):hover {
+    background-color: var(--gray-900);
+  }
+
+  .row-selected,
+  :global(.byline-field-relation-picker-row-selected) {
+    background-color: oklch(from var(--primary-900) l c h / 0.3);
+    border-left: 2px solid var(--primary-400);
+  }
+}

package/src/fields/relation/relation-picker.tsx

@@ -0,0 +1,326 @@
+/**
+ * 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 type { CollectionAdminConfig, CollectionDefinition } from '@byline/core'
+import { getCollectionAdminConfig } from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
+import { Button, LoaderRing, Modal, Search } from '@byline/ui/react'
+import cx from 'classnames'
+
+import { useBylineFieldServices } from '../field-services-context'
+import {
+  PickerCell,
+  resolveFallbackDisplayField,
+  resolveRowLabel,
+  resolveSelectFields,
+} from './relation-display'
+import styles from './relation-picker.module.css'
+
+// ---------------------------------------------------------------------------
+// RelationPicker — modal listing for selecting a target document
+// ---------------------------------------------------------------------------
+
+/**
+ * Row rendering strategy, in priority order:
+ *   1. `CollectionAdminConfig.picker` — a ColumnDefinition[] from the target
+ *      admin config. Each row renders the declared columns side-by-side,
+ *      reusing any column formatters (thumbnail, date, etc).
+ *   2. Explicit `displayField` prop on this component (forwarded from
+ *      `RelationField.displayField`).
+ *   3. `CollectionDefinition.useAsTitle` on the target.
+ *   4. First top-level `text` field on the target.
+ *
+ * Paths 2–4 render a single-line label (primary) + `path` (secondary).
+ */
+interface RelationPickerProps {
+  /** The target collection path (e.g. `'media'`). */
+  targetCollectionPath: string
+  /** The target collection definition (used for labels + displayField fallback). */
+  targetDefinition?: CollectionDefinition | null
+  /** Explicit display field to render as row label. */
+  displayField?: string
+  /** Modal open/close state. */
+  isOpen: boolean
+  /**
+   * Called with the picked selection when the user confirms.
+   *
+   * `record` is the raw document the picker row rendered — the caller can
+   * use it to show the selected value in its own tile without a refetch.
+   * The fields available on `record` are whatever `resolveSelectFields`
+   * asked the listing endpoint for (picker columns + `useAsTitle` +
+   * `displayField`), so any display surface downstream of the picker that
+   * also renders from those same columns will find the data it needs.
+   */
+  onSelect: (selection: {
+    targetDocumentId: string
+    targetCollectionId: string
+    record?: Record<string, any>
+  }) => void
+  /** Called when the user dismisses the modal. */
+  onDismiss: () => void
+}
+
+const PAGE_SIZE = 15
+
+export const RelationPicker = ({
+  targetCollectionPath,
+  targetDefinition,
+  displayField,
+  isOpen,
+  onSelect,
+  onDismiss,
+}: RelationPickerProps) => {
+  const [query, setQuery] = useState<string>('')
+  const [page, setPage] = useState<number>(1)
+  const { t } = useTranslation('byline-admin')
+  const [selectedDocumentId, setSelectedDocumentId] = useState<string | null>(null)
+  const [loading, setLoading] = useState<boolean>(false)
+  const [error, setError] = useState<string | null>(null)
+  const [documents, setDocuments] = useState<any[]>([])
+  const [totalPages, setTotalPages] = useState<number>(1)
+  const [collectionId, setCollectionId] = useState<string | null>(null)
+
+  const { getCollectionDocuments } = useBylineFieldServices()
+
+  const targetAdminConfig: CollectionAdminConfig | null =
+    getCollectionAdminConfig(targetCollectionPath)
+  const pickerColumns = targetAdminConfig?.picker
+
+  // Reset local state each time the modal opens so prior queries don't leak.
+  useEffect(() => {
+    if (isOpen) {
+      setQuery('')
+      setPage(1)
+      setSelectedDocumentId(null)
+      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)
+
+    setLoading(true)
+    setError(null)
+    getCollectionDocuments({
+      collection: targetCollectionPath,
+      params: {
+        page,
+        page_size: PAGE_SIZE,
+        query: query.length > 0 ? query : undefined,
+        fields: selectFields,
+      },
+    })
+      .then((response: any) => {
+        if (cancelled) return
+        setDocuments(response.docs)
+        setTotalPages(response.meta.totalPages ?? 1)
+        setCollectionId(response.included.collection.id as string)
+      })
+      .catch((err: any) => {
+        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,
+    targetDefinition,
+    pickerColumns,
+    getCollectionDocuments,
+    t,
+  ])
+
+  const resolvedDisplayField =
+    displayField ??
+    targetDefinition?.useAsTitle ??
+    resolveFallbackDisplayField(targetDefinition) ??
+    null
+
+  const handleSelect = useCallback(() => {
+    if (!selectedDocumentId || !collectionId) return
+    const record = documents.find((d) => d?.id === selectedDocumentId)
+    onSelect({
+      targetDocumentId: selectedDocumentId,
+      targetCollectionId: collectionId,
+      record,
+    })
+  }, [selectedDocumentId, collectionId, documents, onSelect])
+
+  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 as string
+                    const selected = selectedDocumentId === id
+                    return (
+                      <li key={id}>
+                        <button
+                          type="button"
+                          className={cx(
+                            'byline-field-relation-picker-row-button',
+                            styles['row-button'],
+                            selected && [
+                              'byline-field-relation-picker-row-selected',
+                              styles['row-selected'],
+                            ]
+                          )}
+                          onClick={() => setSelectedDocumentId(id)}
+                        >
+                          {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>
+                          )}
+                        </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={!selectedDocumentId}
+            onClick={handleSelect}
+          >
+            {t('common.actions.select')}
+          </Button>
+        </Modal.Actions>
+      </Modal.Container>
+    </Modal>
+  )
+}