@byline/admin 2.5.1 → 2.6.0

package/src/fields/draggable-context-menu.tsx

@@ -0,0 +1,87 @@
+'use client'
+
+/**
+ * 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 { useTranslation } from '@byline/i18n/react'
+import {
+  DeleteIcon,
+  Dropdown as DropdownMenu,
+  EllipsisIcon,
+  IconButton,
+  PlusIcon,
+} from '@byline/ui/react'
+import cx from 'classnames'
+
+import styles from './draggable-context-menu.module.css'
+
+interface DraggableContextMenuProps {
+  onAddBelow?: () => void
+  onRemove?: () => void
+}
+
+export function DraggableContextMenu({
+  onAddBelow,
+  onRemove,
+}: DraggableContextMenuProps): React.JSX.Element {
+  const { t } = useTranslation('byline-admin')
+  const itemClass = cx('byline-draggable-menu-item', styles.item)
+  const rowClass = cx('byline-draggable-menu-row', styles.row)
+  const iconSlotClass = cx('byline-draggable-menu-icon-slot', styles['icon-slot'])
+  const labelClass = cx('byline-draggable-menu-label', styles.label)
+
+  return (
+    <DropdownMenu.Root modal={false}>
+      <DropdownMenu.Trigger render={<IconButton variant="text" size="sm" />}>
+        <EllipsisIcon width="16px" height="16px" />
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Portal>
+        <DropdownMenu.Content
+          align="end"
+          sideOffset={0}
+          className={cx('byline-draggable-menu', styles.menu)}
+        >
+          <DropdownMenu.Item className={itemClass} onClick={onAddBelow}>
+            <div className={rowClass}>
+              <span className={iconSlotClass}>
+                <PlusIcon width="18px" height="18px" />
+              </span>
+              <span className={labelClass}>{t('fields.draggableMenu.addBelow')}</span>
+            </div>
+          </DropdownMenu.Item>
+          <DropdownMenu.Separator
+            className={cx('byline-draggable-menu-separator', styles.separator)}
+          />
+          <DropdownMenu.Item className={itemClass} onClick={onRemove}>
+            <div className={rowClass}>
+              <div className={rowClass}>
+                <span className={iconSlotClass}>
+                  <DeleteIcon
+                    width="18px"
+                    height="18px"
+                    svgClassName={cx('byline-draggable-menu-delete-icon', styles['delete-icon'])}
+                  />
+                </span>
+                <span
+                  className={cx(
+                    'byline-draggable-menu-label byline-draggable-menu-label-danger',
+                    styles.label,
+                    styles['label-danger']
+                  )}
+                >
+                  {t('fields.draggableMenu.remove')}
+                </span>
+              </div>
+            </div>
+          </DropdownMenu.Item>
+        </DropdownMenu.Content>
+      </DropdownMenu.Portal>
+    </DropdownMenu.Root>
+  )
+}

package/src/fields/field-helpers.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 { Field } from '@byline/core'
+import { resolveFieldDefaultValue } from '@byline/core'
+
+export const placeholderStoredFileValue = {
+  fileId: crypto.randomUUID(),
+  filename: 'placeholder',
+  originalFilename: 'placeholder',
+  mimeType: 'application/octet-stream',
+  fileSize: 0,
+  storageProvider: 'placeholder',
+  storagePath: 'pending',
+  storageUrl: null,
+  fileHash: null,
+  imageWidth: null,
+  imageHeight: null,
+  imageFormat: null,
+  processingStatus: 'pending',
+  thumbnailGenerated: false,
+}
+
+export const placeholderForField = (f: Field): any => {
+  switch (f.type) {
+    case 'text':
+    case 'textArea':
+      return ''
+    case 'checkbox':
+      return false
+    case 'integer':
+      return 0
+    case 'counter':
+      // Allocator-assigned in the lifecycle layer; absent at form-init time.
+      return undefined
+    case 'richText':
+    case 'datetime':
+      return undefined
+    case 'select':
+      return ''
+    case 'file':
+    case 'image':
+      return placeholderStoredFileValue
+    default:
+      return null
+  }
+}
+
+export const defaultScalarForField = async (
+  f: Field,
+  getFieldValues: () => Record<string, any>
+): Promise<any> => {
+  const schemaDefault = await resolveFieldDefaultValue(f, {
+    data: getFieldValues(),
+    now: () => new Date(),
+    uuid: () => crypto.randomUUID(),
+  })
+
+  if (schemaDefault !== undefined) {
+    return schemaDefault
+  }
+
+  return placeholderForField(f)
+}

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

@@ -0,0 +1,22 @@
+/**
+ * FieldRenderer — main field-type switch wrapper.
+ *
+ * Override handles:
+ *   .byline-field-localized-wrap   — wrapper added when a non-self-badging
+ *                                    field needs an absolutely-positioned
+ *                                    locale badge in the corner
+ *   .byline-field-localized-badge  — the absolutely-positioned badge slot
+ */
+
+.localized-wrap,
+:global(.byline-field-localized-wrap) {
+  position: relative;
+}
+
+.localized-badge,
+:global(.byline-field-localized-badge) {
+  position: absolute;
+  top: 0;
+  right: 0;
+  line-height: 1;
+}

package/src/fields/field-renderer.tsx

@@ -0,0 +1,288 @@
+/**
+ * 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 {
+  ArrayField as ArrayFieldType,
+  BlocksField as BlocksFieldType,
+  Field,
+  FieldComponentSlots,
+  GroupField as GroupFieldType,
+  RichTextEditorComponent,
+} from '@byline/core'
+import { getClientConfig } from '@byline/core'
+import cx from 'classnames'
+
+import { ArrayField } from './array/array-field'
+import { BlocksField } from './blocks/blocks-field'
+import { CheckboxField } from './checkbox/checkbox-field'
+import { DateTimeField } from './datetime/datetime-field'
+import styles from './field-renderer.module.css'
+import { FileField } from './file/file-field'
+import { GroupField } from './group/group-field'
+import { ImageField } from './image/image-field'
+import { LocaleBadge } from './locale-badge'
+import { NumericalField } from './numerical/numerical-field'
+import { RelationField } from './relation/relation-field'
+import { SelectField } from './select/select-field'
+import { TextField } from './text/text-field'
+import { TextAreaField } from './text-area/text-area-field'
+import { useFieldChangeHandler } from './use-field-change-handler'
+
+// ---------------------------------------------------------------------------
+// FieldRenderer — the main field type switch. Delegates to the appropriate
+// field widget based on `field.type`.
+// ---------------------------------------------------------------------------
+
+interface FieldRendererProps {
+  field: Field
+  defaultValue?: any
+  basePath?: string
+  disableSorting?: boolean
+  hideLabel?: boolean
+  /** Collection path (e.g. `'media'`) forwarded to upload-capable fields. */
+  collectionPath?: string
+  /**
+   * The active content locale (e.g. `'en'`, `'fr'`). When provided and
+   * `field.localized === true`, a small locale badge is shown so the editor
+   * knows they are working on a localised field in the current language.
+   */
+  contentLocale?: string
+  /**
+   * Optional UI component slot overrides from the admin config.
+   * Forwarded to value-field widgets that support custom slots.
+   */
+  components?: FieldComponentSlots
+  /**
+   * Per-field rich-text editor component override from the admin config.
+   * Takes precedence over the globally registered
+   * `ClientConfig.fields.richText.editor` for this single field.
+   * Ignored when `field.type !== 'richText'`.
+   */
+  editor?: RichTextEditorComponent
+}
+
+export const FieldRenderer = ({
+  field,
+  defaultValue,
+  basePath,
+  disableSorting,
+  hideLabel,
+  collectionPath,
+  contentLocale,
+  components,
+  editor,
+}: FieldRendererProps) => {
+  const path = basePath ? `${basePath}.${field.name}` : field.name
+  const htmlId = path.replace(/[[\].]/g, '-')
+
+  const handleChange = useFieldChangeHandler(field, path)
+
+  // When a locale is active and the field is localised, inject a badge into
+  // the field label so the editor knows they are editing locale-specific content.
+  const isLocalised = (field as any).localized === true
+
+  const badge =
+    isLocalised && contentLocale && !hideLabel ? <LocaleBadge locale={contentLocale} /> : null
+
+  /**
+   * Render the underlying field widget. If the field is localised, we wrap it
+   * so we can append the locale badge after the label.
+   */
+  const renderField = () => {
+    switch (field.type) {
+      case 'text':
+        return (
+          <TextField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            id={htmlId}
+            locale={isLocalised ? contentLocale : undefined}
+            components={components}
+          />
+        )
+      case 'textArea':
+        return (
+          <TextAreaField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            id={htmlId}
+            locale={isLocalised ? contentLocale : undefined}
+            components={components}
+          />
+        )
+      case 'checkbox':
+        return (
+          <CheckboxField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            id={htmlId}
+          />
+        )
+      case 'select':
+        return (
+          <SelectField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            id={htmlId}
+          />
+        )
+      case 'richText': {
+        // Admin-side per-field override takes precedence over the globally
+        // registered editor (`ClientConfig.fields.richText.editor`). The
+        // override travels via `FieldAdminConfig.fields.<name>.editor` —
+        // see admin-types — so React component references stay out of the
+        // schema graph that's loaded by the server bootstrap.
+        const RichTextEditor = editor ?? getClientConfig().fields?.richText?.editor
+        if (!RichTextEditor) {
+          throw new Error(
+            'No richText editor registered. Install @byline/richtext-lexical and set ' +
+              '`fields.richText.editor` in your admin config.'
+          )
+        }
+        return (
+          <RichTextEditor
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            instanceKey={htmlId}
+            locale={isLocalised ? contentLocale : undefined}
+          />
+        )
+      }
+      case 'datetime':
+        return (
+          <DateTimeField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            id={htmlId}
+          />
+        )
+      case 'integer':
+        return (
+          <NumericalField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            id={htmlId}
+            components={components}
+          />
+        )
+      case 'counter':
+        // Counter values are allocator-assigned; force readOnly at the
+        // renderer level so the widget is always non-editable regardless
+        // of whether the developer set `field.readOnly` explicitly.
+        return (
+          <NumericalField
+            field={
+              hideLabel
+                ? { ...field, label: undefined, readOnly: true }
+                : { ...field, readOnly: true }
+            }
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            id={htmlId}
+            components={components}
+          />
+        )
+      case 'file':
+        return (
+          <FileField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            collectionPath={collectionPath}
+          />
+        )
+      case 'image':
+        return (
+          <ImageField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            collectionPath={collectionPath}
+          />
+        )
+      case 'relation':
+        return (
+          <RelationField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+            id={htmlId}
+          />
+        )
+      case 'group':
+        // Render a group field as a fixed-order inline field group.
+        return (
+          <GroupField
+            field={
+              hideLabel
+                ? ({ ...field, label: undefined } as unknown as GroupFieldType)
+                : (field as unknown as GroupFieldType)
+            }
+            defaultValue={defaultValue}
+            path={path}
+          />
+        )
+      case 'blocks':
+        if (!field.blocks) return null
+        return (
+          <BlocksField
+            field={field as unknown as BlocksFieldType}
+            defaultValue={defaultValue}
+            path={path}
+          />
+        )
+      case 'array':
+        if (!field.fields) return null
+        return (
+          <ArrayField
+            field={field as unknown as ArrayFieldType}
+            defaultValue={defaultValue}
+            path={path}
+            disableSorting={disableSorting}
+          />
+        )
+      default:
+        return null
+    }
+  }
+
+  // text and textArea render the badge inside their own Label row;
+  // the outer wrapper is only needed for other field types.
+  const selfBadge = field.type === 'text' || field.type === 'textArea' || field.type === 'richText'
+
+  if (badge && !selfBadge) {
+    return (
+      <div className={cx('byline-field-localized-wrap', styles['localized-wrap'])}>
+        {renderField()}
+        <span className={cx('byline-field-localized-badge', styles['localized-badge'])}>
+          {badge}
+        </span>
+      </div>
+    )
+  }
+
+  return renderField()
+}

package/src/fields/field-services-context.tsx

@@ -0,0 +1,35 @@
+/**
+ * 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 { createContext, type ReactNode, useContext } from 'react'
+
+import type { BylineFieldServices } from './field-services-types'
+
+const FieldServicesContext = createContext<BylineFieldServices | null>(null)
+
+interface BylineFieldServicesProviderProps {
+  services: BylineFieldServices
+  children: ReactNode
+}
+
+export const BylineFieldServicesProvider = ({
+  services,
+  children,
+}: BylineFieldServicesProviderProps) => (
+  <FieldServicesContext.Provider value={services}>{children}</FieldServicesContext.Provider>
+)
+
+export const useBylineFieldServices = (): BylineFieldServices => {
+  const ctx = useContext(FieldServicesContext)
+  if (!ctx) {
+    throw new Error(
+      '@byline/ui: BylineFieldServicesProvider missing. Wrap your admin tree with <BylineFieldServicesProvider services={…} />.'
+    )
+  }
+  return ctx
+}

package/src/fields/field-services-types.ts

@@ -0,0 +1,68 @@
+/**
+ * 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
+ */
+
+/**
+ * Framework-neutral function contracts that field/form components in
+ * `@byline/ui` need from the host application. The host wires concrete
+ * implementations via `BylineFieldServicesProvider` — typically thin
+ * adapters around TanStack Start server functions, Next.js server
+ * actions, or any other RPC-style transport.
+ */
+
+import type { StoredFileValue } from '@byline/core'
+
+export interface CollectionListParams {
+  page?: number
+  page_size?: number
+  order?: string
+  desc?: boolean
+  query?: string
+  locale?: string
+  status?: string
+  fields?: string[]
+}
+
+export interface CollectionListDoc {
+  id: string
+  path?: string
+  [field: string]: unknown
+}
+
+export interface CollectionListResponse {
+  docs: CollectionListDoc[]
+  meta: { totalPages?: number; [k: string]: unknown }
+  included: { collection: { id: string; [k: string]: unknown } }
+}
+
+export type GetCollectionDocumentsFn = (input: {
+  collection: string
+  params: CollectionListParams
+}) => Promise<CollectionListResponse>
+
+export interface UploadedFileResult {
+  documentId?: string
+  documentVersionId?: string
+  /**
+   * The persisted file value, including the `variants` array with
+   * `storagePath`, `storageUrl`, `width`, `height`, and `format` for each
+   * generated derivative. Single source of truth — the legacy top-level
+   * `variants: { name, url }[]` is gone.
+   */
+  storedFile: StoredFileValue
+}
+
+export type UploadFieldFn = (
+  collection: string,
+  formData: FormData,
+  createDocument?: boolean
+) => Promise<UploadedFileResult>
+
+export interface BylineFieldServices {
+  getCollectionDocuments: GetCollectionDocumentsFn
+  uploadField: UploadFieldFn
+}