@byline/admin 2.5.1 → 2.6.0

package/src/fields/local-date-time.tsx

@@ -0,0 +1,88 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+// undefined will use the user's locale
+const dateTimeFormatter = new Intl.DateTimeFormat(undefined, {
+  year: 'numeric',
+  month: 'short', // <- short month text (locale-aware)
+  day: '2-digit',
+  hour: 'numeric',
+  minute: 'numeric',
+})
+
+const dateFormatter = new Intl.DateTimeFormat(undefined, {
+  year: 'numeric',
+  month: 'short', // <- short month text (locale-aware)
+  day: '2-digit',
+})
+
+interface LocalDateTimeProps {
+  value: string | Date | null | undefined
+  mode?: 'datetime' | 'date'
+  className?: string
+  fallback?: string
+}
+
+/**
+ * Client-side date/time formatter that displays dates in the user's local timezone.
+ *
+ * This component avoids hydration mismatches by:
+ * 1. Rendering a placeholder on the server/initial render
+ * 2. Updating to the correctly formatted date after hydration
+ *
+ * Use this instead of formatDateTime when you need to display dates
+ * in the user's local timezone rather than UTC.
+ */
+export function LocalDateTime({
+  value,
+  mode = 'datetime',
+  className,
+  fallback = '—',
+}: LocalDateTimeProps): React.JSX.Element {
+  const [formattedDate, setFormattedDate] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (value == null) {
+      setFormattedDate(null)
+      return
+    }
+
+    const date = typeof value === 'string' ? Date.parse(value) : value.getTime()
+    if (Number.isNaN(date)) {
+      setFormattedDate('Error')
+      return
+    }
+
+    const formatter = mode === 'datetime' ? dateTimeFormatter : dateFormatter
+    setFormattedDate(formatter.format(date))
+  }, [value, mode])
+
+  // Show fallback during SSR and before useEffect runs
+  if (formattedDate === null) {
+    return <span className={className}>{value ? '...' : fallback}</span>
+  }
+
+  return <span className={className}>{formattedDate}</span>
+}
+
+/**
+ * Formats a date string to the user's local timezone.
+ *
+ * WARNING: Only use this in client components where hydration
+ * mismatches are acceptable or managed. For most cases, prefer
+ * the <LocalDateTime /> component.
+ */
+export function formatLocalDateTime(value: string | Date | null | undefined): string {
+  if (value == null) return '—'
+  const date = typeof value === 'string' ? Date.parse(value) : value.getTime()
+  if (Number.isNaN(date)) return 'Error'
+  return dateTimeFormatter.format(date)
+}
+
+export function formatLocalDate(value: string | Date | null | undefined): string {
+  if (value == null) return '—'
+  const date = typeof value === 'string' ? Date.parse(value) : value.getTime()
+  if (Number.isNaN(date)) return 'Error'
+  return dateFormatter.format(date)
+}

package/src/fields/locale-badge.module.css

@@ -0,0 +1,37 @@
+/**
+ * LocaleBadge — small inline badge shown next to a localised field label.
+ *
+ * Override handle: `.byline-locale-badge`
+ */
+
+.badge,
+:global(.byline-locale-badge) {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.125rem;
+  margin-left: 0.375rem;
+  padding: 0.125rem 0.375rem;
+  border: var(--border-width-thin) var(--border-style-solid) var(--yellow-400);
+  border-radius: var(--border-radius-sm);
+  background-color: var(--yellow-100);
+  color: var(--yellow-800);
+  font-size: 0.6rem;
+  font-weight: var(--font-weight-semibold);
+  line-height: 1;
+  letter-spacing: var(--letter-spacing-wide);
+  text-transform: uppercase;
+  pointer-events: none;
+  user-select: none;
+  vertical-align: middle;
+}
+
+/* ─── Dark theme variants ───────────────────────────────────── */
+
+:is([data-theme="dark"], :global(.dark)) {
+  .badge,
+  :global(.byline-locale-badge) {
+    border-color: var(--yellow-700);
+    background-color: oklch(from var(--yellow-900) l c h / 0.4);
+    color: var(--yellow-400);
+  }
+}

package/src/fields/locale-badge.tsx

@@ -0,0 +1,32 @@
+/**
+ * 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 'classnames'
+
+import styles from './locale-badge.module.css'
+
+export interface LocaleBadgeProps {
+  locale: string
+}
+
+/**
+ * Small inline badge shown next to the label of a field that has
+ * `localized: true` in its schema definition. Indicates which locale
+ * the editor is currently working in.
+ *
+ * Stable override handle: `.byline-locale-badge`.
+ */
+export const LocaleBadge = ({ locale }: LocaleBadgeProps) => (
+  <span
+    aria-hidden="true"
+    title={`Localised — editing ${locale.toUpperCase()} content`}
+    className={cx('byline-locale-badge', styles.badge)}
+  >
+    {locale}
+  </span>
+)

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

@@ -0,0 +1,114 @@
+/**
+ * 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 {
+  CounterField,
+  DecimalField,
+  Field,
+  FieldComponentSlots,
+  FloatField,
+  IntegerField,
+} from '@byline/core'
+import { Input } from '@byline/ui/react'
+
+import { useFieldError, useFieldValue } from '../../forms/form-context'
+
+export const NumericalField = ({
+  field,
+  value,
+  defaultValue,
+  onChange,
+  id,
+  path,
+  components,
+}: {
+  field: IntegerField | FloatField | DecimalField | CounterField
+  value?: string | number | null
+  defaultValue?: string | number | null
+  onChange?: (value: string) => void
+  id?: string
+  path?: 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 | number | undefined>(fieldPath)
+  const incomingValue = value ?? fieldValue ?? defaultValue ?? ''
+  const htmlId = id ?? fieldPath
+  const displayValue =
+    incomingValue === undefined || incomingValue === null ? '' : String(incomingValue)
+
+  // 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,
+  }
+
+  const hasCustomLabel = !!CustomLabel
+  const suppressInputLabel = hasCustomLabel
+  const suppressInputHelpText = !!CustomHelpText
+
+  // ── Label rendering ──────────────────────────────────────────
+  const renderLabel = () => {
+    if (hasCustomLabel) {
+      return <CustomLabel {...slotBaseProps} label={field.label} required={!field.optional} />
+    }
+    return null
+  }
+
+  // ── Field input rendering ────────────────────────────────────
+  const renderInput = () => {
+    if (CustomField) {
+      return (
+        <CustomField
+          {...slotBaseProps}
+          onChange={(v: any) => onChange?.(v)}
+          defaultValue={defaultValue}
+          placeholder={field.placeholder}
+        />
+      )
+    }
+    return (
+      <Input
+        type="number"
+        id={htmlId}
+        name={field.name}
+        label={suppressInputLabel ? undefined : field.label}
+        required={!field.optional}
+        readOnly={field.readOnly}
+        helpText={suppressInputHelpText ? undefined : field.helpText}
+        value={displayValue}
+        onChange={(e) => onChange?.(e.target.value)}
+        error={fieldError != null}
+        errorText={fieldError}
+      />
+    )
+  }
+
+  return (
+    <div className={`byline-field-${field.type} ${field.name}`}>
+      {renderLabel()}
+      {BeforeField && <BeforeField {...slotBaseProps} />}
+      {renderInput()}
+      {AfterField && <AfterField {...slotBaseProps} />}
+      {CustomHelpText && <CustomHelpText {...slotBaseProps} helpText={field.helpText} />}
+    </div>
+  )
+}

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

@@ -0,0 +1,36 @@
+/**
+ * RelationDisplay — shared cell renderer for relation picker rows and the
+ * relation-summary selected-value tile.
+ *
+ * Override handles:
+ *   .byline-relation-cell           — single column cell
+ *   .byline-relation-cell-center    — cell with align: center
+ *   .byline-relation-cell-right     — cell with align: right
+ */
+
+.cell,
+:global(.byline-relation-cell) {
+  min-width: 0;
+  color: var(--gray-700);
+  font-size: var(--font-size-sm);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.cell-center,
+:global(.byline-relation-cell-center) {
+  text-align: center;
+}
+
+.cell-right,
+:global(.byline-relation-cell-right) {
+  text-align: right;
+}
+
+:is([data-theme="dark"], :global(.dark)) {
+  .cell,
+  :global(.byline-relation-cell) {
+    color: var(--gray-100);
+  }
+}

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 row
+ *   .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 + actions container
+ *   .byline-field-relation-actions       — top-right icon-button group (edit + remove)
+ *   .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;
+}
+
+.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: flex-start;
+  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);
+}
+
+.actions,
+:global(.byline-field-relation-actions) {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-4);
+  flex-shrink: 0;
+}
+
+:global(.byline-field-relation-actions .byline-button) {
+  color: var(--gray-900);
+}
+
+:global(.dark .byline-field-relation-actions .byline-button),
+:global([data-theme="dark"] .byline-field-relation-actions .byline-button) {
+  color: var(--gray-200);
+}
+
+.mono,
+:global(.byline-field-relation-mono) {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}