@byline/ui 0.9.3

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

@@ -0,0 +1,325 @@
+/**
+ * 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 { Button, LoaderRing, Modal, Search } from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import { useBylineFieldServices } from '../../services/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 [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 : 'Failed to load documents')
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [
+    isOpen,
+    targetCollectionPath,
+    query,
+    page,
+    displayField,
+    targetDefinition,
+    pickerColumns,
+    getCollectionDocuments,
+  ])
+
+  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 = targetDefinition
+    ? `Select ${targetDefinition.labels.singular}`
+    : `Select ${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="Search"
+            />
+
+            <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)}>
+                  No documents found
+                </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))}
+                >
+                  Previous
+                </Button>
+                <span>
+                  Page {page} of {totalPages}
+                </span>
+                <Button
+                  size="xs"
+                  variant="outlined"
+                  intent="noeffect"
+                  type="button"
+                  disabled={page >= totalPages || loading}
+                  onClick={() => setPage((p) => Math.min(totalPages, p + 1))}
+                >
+                  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)}
+          >
+            Cancel
+          </Button>
+          <Button
+            size="sm"
+            className={cx('byline-field-relation-picker-action', styles.action)}
+            intent="primary"
+            type="button"
+            disabled={!selectedDocumentId}
+            onClick={handleSelect}
+          >
+            Select
+          </Button>
+        </Modal.Actions>
+      </Modal.Container>
+    </Modal>
+  )
+}

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

@@ -0,0 +1,55 @@
+/**
+ * RelationSummary — selected-value tile for the relation field widget.
+ *
+ * Override handles:
+ *   .byline-relation-summary               — root container
+ *   .byline-relation-summary-stack         — vertical layout used for label + value
+ *   .byline-relation-summary-row           — horizontal layout used for picker columns
+ *   .byline-relation-summary-kind          — small "type" label above the value
+ *   .byline-relation-summary-value         — primary value text
+ *   .byline-relation-summary-value-mono    — monospace fallback (raw uuid / not-found)
+ *   .byline-relation-summary-missing       — added to the value when target is unresolved
+ */
+
+.stack,
+:global(.byline-relation-summary-stack) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+  min-width: 0;
+}
+
+.row,
+:global(.byline-relation-summary-row) {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  min-width: 0;
+}
+
+.kind,
+:global(.byline-relation-summary-kind) {
+  color: var(--gray-500);
+}
+
+.value,
+:global(.byline-relation-summary-value) {
+  color: var(--gray-100);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.value-mono,
+:global(.byline-relation-summary-value-mono) {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.missing,
+:global(.byline-relation-summary-missing) {
+  font-size: var(--font-size-xs);
+  color: var(--red-400);
+}

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

@@ -0,0 +1,123 @@
+/**
+ * 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 { CollectionAdminConfig, CollectionDefinition } from '@byline/core'
+import cx from 'classnames'
+
+import { PickerCell, resolveFallbackDisplayField, resolveRowLabel } from './relation-display'
+import styles from './relation-summary.module.css'
+
+// ---------------------------------------------------------------------------
+// RelationSummary — selected-value tile for the relation field widget.
+//
+// Rendering priority (mirrors RelationPicker so the tile and picker rows
+// look identical):
+//   1. target `CollectionAdminConfig.picker` columns (full fidelity, with
+//      formatters — e.g. MediaThumbnail + title)
+//   2. explicit `displayField` prop (from source schema's RelationField)
+//   3. `CollectionDefinition.useAsTitle`
+//   4. first declared text field on the target
+//   5. target UUID (only when nothing else is available — "resolved but
+//      naked" or unpopulated)
+//
+// Value source priority:
+//   1. `populated.document` — a `PopulatedRelationValue` attached by the
+//      server-side populate pass on first page load.
+//   2. `cachedRecord` — the raw document the picker just handed us after
+//      a fresh pick (no server round trip needed).
+//   3. neither — we have only the stored ref; fall through to UUID.
+// ---------------------------------------------------------------------------
+
+interface RelationSummaryProps {
+  targetDefinition: CollectionDefinition
+  targetAdminConfig: CollectionAdminConfig | null
+  displayField?: string
+  /** The raw relation value from the form. May be a plain ref or a populated envelope. */
+  value: {
+    targetDocumentId: string
+    targetCollectionId: string
+    _resolved?: boolean
+    _cycle?: boolean
+    document?: Record<string, any>
+  }
+  /**
+   * A document record cached client-side from a recent picker selection.
+   * Used when `value` is a plain ref (post-pick state) but we still want
+   * the tile to render real display data without a refetch. Caller is
+   * responsible for clearing/replacing this when the value's
+   * `targetDocumentId` changes.
+   */
+  cachedRecord?: Record<string, any> | null
+}
+
+export function RelationSummary({
+  targetDefinition,
+  targetAdminConfig,
+  displayField,
+  value,
+  cachedRecord,
+}: RelationSummaryProps) {
+  const pickerColumns = targetAdminConfig?.picker
+
+  // 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: Record<string, any> | null =
+    (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/src/fields/select/select-field.module.css

@@ -0,0 +1,13 @@
+/**
+ * SelectField — dropdown form widget.
+ *
+ * Override handles:
+ *   .byline-field-select         — the wrapper div
+ *   .byline-field-select-dirty   — added to the inner select when the
+ *                                  field has unsaved local changes
+ */
+
+.dirty,
+:global(.byline-field-select-dirty) {
+  border-color: var(--blue-300);
+}

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

@@ -0,0 +1,56 @@
+/**
+ * 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 { SelectField as FieldType } from '@byline/core'
+import { ErrorText, Select } from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import { useFieldError, useFieldValue, useIsDirty } from '../../forms/form-context'
+import styles from './select-field.module.css'
+
+export const SelectField = ({
+  field,
+  value,
+  defaultValue,
+  onChange,
+  id,
+  path,
+}: {
+  field: FieldType
+  value?: string
+  defaultValue?: string
+  onChange?: (value: string) => void
+  id?: string
+  path?: string
+}) => {
+  const fieldPath = path ?? field.name
+  const fieldError = useFieldError(fieldPath)
+  const isDirty = useIsDirty(fieldPath)
+  const fieldValue = useFieldValue<string | undefined>(fieldPath)
+  const incomingValue = value ?? fieldValue ?? defaultValue ?? ''
+
+  return (
+    <div className={`byline-field-select ${field.name}`}>
+      <Select<string>
+        size="xs"
+        id={id ?? fieldPath}
+        name={field.name}
+        placeholder="Select an option"
+        required={!field.optional}
+        value={incomingValue}
+        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>
+  )
+}