@byline/ui 0.9.3

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

@@ -0,0 +1,130 @@
+/**
+ * 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 type { CollectionDefinition, ColumnDefinition } from '@byline/core'
+import cx from 'classnames'
+
+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,
+}: {
+  column: ColumnDefinition
+  record: Record<string, any>
+}) {
+  const name = String(column.fieldName)
+  const value = record?.fields?.[name] ?? record?.[name]
+
+  let content: any
+  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: CollectionDefinition | null | undefined
+): string | null {
+  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: Record<string, any> | null | undefined,
+  displayField: string | null
+): string | null {
+  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 as string
+  }
+  if (typeof doc.path === 'string' && doc.path.length > 0) return doc.path as string
+  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: CollectionDefinition | null | undefined,
+  displayField: string | undefined,
+  pickerColumns: ColumnDefinition[] | undefined
+): string[] | undefined {
+  if (!def) return undefined
+  const out = new Set<string>()
+  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)
+    }
+  }
+  if (def.fields.some((f) => f.name === 'title')) out.add('title')
+  if (out.size === 0) return undefined
+  return Array.from(out)
+}

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

@@ -0,0 +1,83 @@
+/**
+ * RelationField — widget for `type: 'relation'` fields.
+ *
+ * Override handles:
+ *   .byline-field-relation               — outer wrapper
+ *   .byline-field-relation-header        — label + remove-button row
+ *   .byline-field-relation-remove        — text-link remove button
+ *   .byline-field-relation-help          — help text below the label
+ *   .byline-field-relation-error-tile    — wrapper shown when target collection is unknown
+ *   .byline-field-relation-error-text    — secondary error message below the title
+ *   .byline-field-relation-tile          — bordered selected-value + change-button container
+ *   .byline-field-relation-mono          — monospace `<code>` for field/collection names
+ */
+
+.header,
+:global(.byline-field-relation-header) {
+  display: flex;
+  align-items: baseline;
+  gap: var(--spacing-8);
+  margin-bottom: 0.25rem;
+}
+
+.remove,
+:global(.byline-field-relation-remove) {
+  background: none;
+  border: none;
+  padding: 0;
+  color: var(--red-500);
+  font-size: var(--font-size-xs);
+  cursor: pointer;
+}
+
+.remove:hover,
+:global(.byline-field-relation-remove):hover {
+  color: var(--red-400);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.help,
+:global(.byline-field-relation-help) {
+  margin-bottom: 0.25rem;
+  color: var(--gray-400);
+  font-size: var(--font-size-xs);
+}
+
+.error-tile,
+:global(.byline-field-relation-error-tile) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  margin-top: 0.25rem;
+  padding: var(--spacing-8);
+  border: var(--border-width-thin) var(--border-style-solid) var(--red-700);
+  background-color: oklch(from var(--red-900) l c h / 0.2);
+  border-radius: var(--border-radius-md);
+  color: var(--red-200);
+  font-size: var(--font-size-xs);
+}
+
+.error-text,
+:global(.byline-field-relation-error-text) {
+  color: oklch(from var(--red-400) l c h / 0.8);
+}
+
+.tile,
+:global(.byline-field-relation-tile) {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-8);
+  margin-top: 0.25rem;
+  padding: var(--spacing-8);
+  border: var(--border-width-thin) var(--border-style-solid) var(--primary-500);
+  border-radius: var(--border-radius-md);
+  color: var(--gray-200);
+  font-size: var(--font-size-xs);
+}
+
+.mono,
+:global(.byline-field-relation-mono) {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}

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

@@ -0,0 +1,202 @@
+/**
+ * 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 { Button, ErrorText, Label } from '@infonomic/uikit/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 [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
+  const monoClass = cx('byline-field-relation-mono', styles.mono)
+
+  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}
+        />
+        {incomingValue && !isUnknown && (
+          <button
+            type="button"
+            className={cx('byline-field-relation-remove', styles.remove)}
+            onClick={handleRemove}
+          >
+            Remove
+          </button>
+        )}
+      </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>
+            Relation field <code className={monoClass}>{field.name}</code> targets unknown
+            collection <code className={monoClass}>{field.targetCollection}</code>.
+          </span>
+          <span className={cx('byline-field-relation-error-text', styles['error-text'])}>
+            Register the collection in your Byline config or correct the target path.
+          </span>
+        </div>
+      ) : incomingValue ? (
+        <div className={cx('byline-field-relation-tile', styles.tile)}>
+          <RelationSummary
+            targetDefinition={targetDef}
+            targetAdminConfig={targetAdminConfig}
+            displayField={field.displayField}
+            value={incomingValue}
+            cachedRecord={cachedRecord}
+          />
+          <Button
+            id={htmlId}
+            size="xs"
+            variant="outlined"
+            intent="noeffect"
+            type="button"
+            onClick={() => setPickerOpen(true)}
+          >
+            Change
+          </Button>
+        </div>
+      ) : (
+        <Button
+          id={htmlId}
+          size="xs"
+          variant="outlined"
+          intent="noeffect"
+          type="button"
+          onClick={() => setPickerOpen(true)}
+        >
+          Select {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);
+  }
+}