@byline/admin 2.5.2 → 2.6.0

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,61 @@
+/**
+ * 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, Label, Select } from '@byline/ui/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 ?? ''
+  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} />
+      )}
+      <Select<string>
+        size="sm"
+        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/src/fields/sortable-item.module.css

@@ -0,0 +1,167 @@
+/**
+ * SortableItem — drag-card wrapping array/blocks list rows.
+ *
+ * Override handles:
+ *   .byline-sortable                  — root card
+ *   .byline-sortable-dragging         — added while the item is mid-drag
+ *   .byline-sortable-collapsed        — added when content is collapsed
+ *   .byline-sortable-header           — top row (gripper + label + actions)
+ *   .byline-sortable-header-collapsed — added to header when collapsed
+ *   .byline-sortable-grip             — drag handle button
+ *   .byline-sortable-grip-icon        — drag handle icon
+ *   .byline-sortable-label            — header label text
+ *   .byline-sortable-toggle           — collapse/expand button
+ *   .byline-sortable-toggle-icon      — chevron icon (rotates when collapsed)
+ *   .byline-sortable-content          — body container (children)
+ *   .byline-sortable-content-hidden   — collapsed body state
+ */
+
+.root,
+:global(.byline-sortable) {
+  padding: var(--spacing-16);
+  padding-top: var(--spacing-8);
+  border: var(--border-width-thin) dashed var(--gray-600);
+  border-radius: var(--border-radius-md);
+  background-color: oklch(from var(--canvas-50) l c h / 0.5);
+  box-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+}
+
+.dragging,
+:global(.byline-sortable-dragging) {
+  background-color: oklch(from var(--canvas-50) l c h / 0.8);
+  box-shadow:
+    0 4px 6px -1px rgb(0 0 0 / 0.1),
+    0 2px 4px -2px rgb(0 0 0 / 0.1);
+}
+
+.collapsed,
+:global(.byline-sortable-collapsed) {
+  padding-top: var(--spacing-8);
+  padding-bottom: var(--spacing-8);
+}
+
+.header,
+:global(.byline-sortable-header) {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-8);
+  margin-bottom: 0;
+  margin-left: -0.75rem;
+}
+
+.header-expanded,
+:global(.byline-sortable-header-expanded) {
+  margin-bottom: var(--spacing-8);
+}
+
+.grip,
+:global(.byline-sortable-grip) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.25rem;
+  border: none;
+  background: none;
+  border-radius: var(--border-radius-sm);
+  color: var(--gray-400);
+  cursor: grab;
+}
+
+.grip:hover,
+:global(.byline-sortable-grip):hover {
+  background-color: var(--gray-100);
+}
+
+.grip:active,
+:global(.byline-sortable-grip):active {
+  cursor: grabbing;
+}
+
+.grip-icon,
+:global(.byline-sortable-grip-icon) {
+  width: 1rem;
+  height: 1rem;
+  color: var(--primary-500);
+}
+
+.label,
+:global(.byline-sortable-label) {
+  flex: 1;
+  min-width: 0;
+  font-size: 1rem;
+  font-weight: var(--font-weight-medium);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.toggle,
+:global(.byline-sortable-toggle) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.25rem;
+  border: none;
+  background: none;
+  border-radius: var(--border-radius-sm);
+  color: var(--gray-400);
+  cursor: pointer;
+}
+
+.toggle:hover,
+:global(.byline-sortable-toggle):hover {
+  background-color: var(--gray-800);
+}
+
+.toggle-icon,
+:global(.byline-sortable-toggle-icon) {
+  width: 1rem;
+  height: 1rem;
+  transition: transform 150ms ease;
+}
+
+.toggle-icon-rotated,
+:global(.byline-sortable-toggle-icon-rotated) {
+  transform: rotate(180deg);
+}
+
+.content,
+:global(.byline-sortable-content) {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-16);
+  transition: all 200ms ease;
+  opacity: 1;
+}
+
+.content-hidden,
+:global(.byline-sortable-content-hidden) {
+  max-height: 0;
+  opacity: 0;
+  z-index: -10;
+}
+
+/* ─── Dark theme variants ───────────────────────────────────── */
+
+:is([data-theme="dark"], :global(.dark)) {
+  .root,
+  :global(.byline-sortable) {
+    background-color: var(--canvas-800);
+  }
+
+  .dragging,
+  :global(.byline-sortable-dragging) {
+    background-color: oklch(from var(--canvas-700) l c h / 0.3);
+  }
+
+  .grip:hover,
+  :global(.byline-sortable-grip):hover {
+    background-color: var(--gray-800);
+  }
+
+  .grip-icon,
+  :global(.byline-sortable-grip-icon) {
+    color: var(--primary-200);
+  }
+}

package/src/fields/sortable-item.tsx

@@ -0,0 +1,106 @@
+/**
+ * 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 ReactNode, useState } from 'react'
+
+import { useTranslation } from '@byline/i18n/react'
+import { ChevronDownIcon, GripperVerticalIcon, useSortable } from '@byline/ui/react'
+import cx from 'classnames'
+
+import { DraggableContextMenu } from './draggable-context-menu'
+import styles from './sortable-item.module.css'
+
+export const SortableItem = ({
+  id,
+  label,
+  children,
+  onAddBelow,
+  onRemove,
+}: {
+  id: string
+  label: ReactNode
+  children: ReactNode
+  onAddBelow?: () => void
+  onRemove?: () => void
+}) => {
+  const { t } = useTranslation('byline-admin')
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id,
+    transition: {
+      duration: 250,
+      easing: 'cubic-bezier(0, 0.2, 0.2, 1)',
+    },
+  })
+
+  const [collapsed, setCollapsed] = useState(false)
+
+  const style = {
+    transform: transform ? `translate3d(${transform.x}px, ${transform.y}px, 0)` : undefined,
+    transition,
+    zIndex: isDragging ? 10 : 'auto',
+  }
+
+  return (
+    <div
+      ref={setNodeRef}
+      style={style}
+      className={cx(
+        'byline-sortable',
+        styles.root,
+        isDragging && ['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']]
+        )}
+      >
+        <button
+          type="button"
+          className={cx('byline-sortable-grip', styles.grip)}
+          {...attributes}
+          {...listeners}
+        >
+          <GripperVerticalIcon className={cx('byline-sortable-grip-icon', styles['grip-icon'])} />
+        </button>
+        <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>
+  )
+}

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

@@ -0,0 +1,13 @@
+/**
+ * TextField — single-line text input wrapper.
+ *
+ * Override handles:
+ *   .byline-field-text             — the wrapper div
+ *   .byline-field-text-label-row   — the label + locale-badge row
+ */
+
+.label-row,
+:global(.byline-field-text-label-row) {
+  display: flex;
+  align-items: center;
+}

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

@@ -0,0 +1,146 @@
+/**
+ * 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 type { Field, FieldComponentSlots, TextField as FieldType } from '@byline/core'
+import { Input, Label } from '@byline/ui/react'
+import cx from 'classnames'
+
+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,
+}: {
+  field: FieldType
+  value?: string
+  defaultValue?: string
+  onChange?: (value: string) => void
+  id?: string
+  path?: string
+  /** When provided, renders a LocaleBadge next to the field label. */
+  locale?: string
+  /** Optional UI component slot overrides from the admin config. */
+  components?: FieldComponentSlots
+}) => {
+  const fieldPath = path ?? field.name
+  const fieldError = useFieldError(fieldPath)
+  const fieldValue = useFieldValue<string | undefined>(fieldPath)
+  const incomingValue = value ?? fieldValue ?? defaultValue ?? ''
+  const htmlId = id ?? fieldPath
+
+  const handleChange = useCallback(
+    (value: string) => {
+      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 as 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/src/fields/text-area/text-area-field.module.css

@@ -0,0 +1,13 @@
+/**
+ * TextAreaField — multi-line text input wrapper.
+ *
+ * Override handles:
+ *   .byline-field-text-area             — the wrapper div
+ *   .byline-field-text-area-label-row   — the label + locale-badge row
+ */
+
+.label-row,
+:global(.byline-field-text-area-label-row) {
+  display: flex;
+  align-items: center;
+}