@byline/ui 0.9.3

package/src/fields/field-helpers.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 '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,255 @@
+/**
+ * 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,
+} 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
+}
+
+export const FieldRenderer = ({
+  field,
+  defaultValue,
+  basePath,
+  disableSorting,
+  hideLabel,
+  collectionPath,
+  contentLocale,
+  components,
+}: 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': {
+        const RichTextEditor = 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 'file':
+        return (
+          <FileField
+            field={hideLabel ? { ...field, label: undefined } : field}
+            defaultValue={defaultValue}
+            onChange={handleChange}
+            path={path}
+          />
+        )
+      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/file/file-field.module.css

@@ -0,0 +1,88 @@
+/**
+ * FileField — placeholder file widget showing stored file metadata.
+ *
+ * Override handles:
+ *   .byline-field-file              — wrapper div
+ *   .byline-field-file-dirty        — dirty-state border on the wrapper
+ *   .byline-field-file-header       — label/help row
+ *   .byline-field-file-label        — primary label text
+ *   .byline-field-file-help         — secondary help text
+ *   .byline-field-file-action       — action button (e.g. "Upload (coming soon)")
+ *   .byline-field-file-empty        — empty-state hint text
+ *   .byline-field-file-meta         — metadata list
+ *   .byline-field-file-meta-key     — metadata field-name span
+ */
+
+.dirty,
+:global(.byline-field-file-dirty) {
+  padding: var(--spacing-12);
+  border: var(--border-width-thin) var(--border-style-solid) var(--blue-300);
+  border-radius: var(--border-radius-md);
+}
+
+.header,
+:global(.byline-field-file-header) {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  margin-bottom: 0.25rem;
+}
+
+.label,
+:global(.byline-field-file-label) {
+  color: var(--gray-100);
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-medium);
+}
+
+.help,
+:global(.byline-field-file-help) {
+  margin-top: 0.125rem;
+  color: var(--gray-400);
+  font-size: var(--font-size-xs);
+}
+
+.action,
+:global(.byline-field-file-action) {
+  background: none;
+  border: none;
+  padding: 0;
+  color: var(--blue-300);
+  font-size: var(--font-size-xs);
+  cursor: pointer;
+}
+
+.action:hover,
+:global(.byline-field-file-action):hover {
+  color: var(--blue-200);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.action:disabled,
+:global(.byline-field-file-action):disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.empty,
+:global(.byline-field-file-empty) {
+  color: var(--gray-500);
+  font-size: var(--font-size-xs);
+  font-style: italic;
+}
+
+.meta,
+:global(.byline-field-file-meta) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+  margin-top: 0.25rem;
+  color: var(--gray-200);
+  font-size: var(--font-size-xs);
+}
+
+.meta-key,
+:global(.byline-field-file-meta-key) {
+  font-weight: var(--font-weight-semibold);
+}

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

@@ -0,0 +1,107 @@
+/**
+ * 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 { FileField as FieldType, StoredFileValue } from '@byline/core'
+import { ErrorText } from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import { useFieldError, useFieldValue, useIsDirty } from '../../forms/form-context'
+import styles from './file-field.module.css'
+
+interface FileFieldProps {
+  field: FieldType
+  // Stored value is currently a plain object with file metadata
+  // coming from the seed data / storage layer.
+  value?: StoredFileValue | null
+  defaultValue?: StoredFileValue | null
+  onChange?: (value: StoredFileValue | null) => void
+  path?: string
+}
+
+export const FileField = ({
+  field,
+  value,
+  defaultValue,
+  onChange: _onChange,
+  path,
+}: FileFieldProps) => {
+  const fieldPath = path ?? field.name
+  const fieldError = useFieldError(fieldPath)
+  const isDirty = useIsDirty(fieldPath)
+  const fieldValue = useFieldValue<StoredFileValue | null | undefined>(fieldPath)
+  const incomingValue = value ?? fieldValue ?? defaultValue ?? null
+
+  const isPlaceholderStoredFileValue = (v: unknown): boolean => {
+    if (!v || typeof v !== 'object') return false
+    const maybe = v as Partial<StoredFileValue>
+    return maybe.storageProvider === 'placeholder' && maybe.storagePath === 'pending'
+  }
+
+  const effectiveValue: StoredFileValue | null = isPlaceholderStoredFileValue(incomingValue)
+    ? null
+    : incomingValue
+
+  return (
+    <div
+      className={cx(
+        'byline-field-file',
+        field.name,
+        isDirty && ['byline-field-file-dirty', styles.dirty]
+      )}
+    >
+      <div className={cx('byline-field-file-header', styles.header)}>
+        <div>
+          <div className={cx('byline-field-file-label', styles.label)}>
+            {field.label ?? field.name}
+            {field.optional ? '' : ' *'}
+          </div>
+          {field.helpText && (
+            <div className={cx('byline-field-file-help', styles.help)}>{field.helpText}</div>
+          )}
+        </div>
+        {/* Placeholder action area for future upload UI */}
+        <button type="button" className={cx('byline-field-file-action', styles.action)} disabled>
+          Upload (coming soon)
+        </button>
+      </div>
+
+      {effectiveValue == null ? (
+        <div className={cx('byline-field-file-empty', styles.empty)}>No file selected</div>
+      ) : (
+        <div className={cx('byline-field-file-meta', styles.meta)}>
+          <div>
+            <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>Filename:</span>{' '}
+            {effectiveValue.filename}
+          </div>
+          <div>
+            <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>Original:</span>{' '}
+            {effectiveValue.originalFilename}
+          </div>
+          <div>
+            <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>Type:</span>{' '}
+            {effectiveValue.mimeType}
+          </div>
+          <div>
+            <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>Size:</span>{' '}
+            {effectiveValue.fileSize}
+          </div>
+          <div>
+            <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>Storage:</span>{' '}
+            {effectiveValue.storageProvider}
+          </div>
+          <div>
+            <span className={cx('byline-field-file-meta-key', styles['meta-key'])}>Path:</span>{' '}
+            {effectiveValue.storagePath}
+          </div>
+        </div>
+      )}
+
+      {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError} />}
+    </div>
+  )
+}

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

@@ -0,0 +1,43 @@
+/**
+ * GroupField — fixed-order group of child fields.
+ *
+ * Override handles:
+ *   .byline-field-group           — outer wrapper
+ *   .byline-field-group-header    — label/help text block
+ *   .byline-field-group-title     — title heading
+ *   .byline-field-group-required  — required asterisk
+ *   .byline-field-group-help      — help text below title
+ *   .byline-field-group-body      — vertical stack of children
+ */
+
+.header,
+:global(.byline-field-group-header) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+  margin-bottom: var(--spacing-8);
+}
+
+.title,
+:global(.byline-field-group-title) {
+  font-size: 1rem;
+  font-weight: var(--font-weight-medium);
+}
+
+.required,
+:global(.byline-field-group-required) {
+  color: var(--red-500);
+}
+
+.help,
+:global(.byline-field-group-help) {
+  color: var(--gray-500);
+  font-size: var(--font-size-xs);
+}
+
+.body,
+:global(.byline-field-group-body) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-8);
+}

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

@@ -0,0 +1,84 @@
+/**
+ * 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 { useMemo } from 'react'
+
+import type { Field, GroupField as GroupFieldType } from '@byline/core'
+import { ErrorText } from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import { placeholderForField } from '../../fields/field-helpers'
+import { FieldRenderer } from '../../fields/field-renderer'
+import { useFieldError } from '../../forms/form-context'
+import styles from './group-field.module.css'
+
+// ---------------------------------------------------------------------------
+// GroupField — renders a fixed-order group of child fields wrapped in a
+// single div. No drag-and-drop. No add/remove.
+// The outer div carries the field type ('group') and field name as classes
+// so consumers can target individual groups via CSS.
+//
+// Stable override handles: `.byline-field-group`, `.byline-field-group-header`,
+// `.byline-field-group-title`, `.byline-field-group-help`,
+// `.byline-field-group-body`.
+// ---------------------------------------------------------------------------
+
+interface GroupFieldProps {
+  field: GroupFieldType
+  defaultValue: any
+  path: string
+}
+
+export const GroupField = ({ field, defaultValue, path }: GroupFieldProps) => {
+  const fieldError = useFieldError(field.name)
+  // Default value for a group field is a plain object: { rating: 5, comment: '...' }
+  // Normalize to a plain object if not already one.
+  const groupData = useMemo(() => {
+    if (defaultValue && typeof defaultValue === 'object' && !Array.isArray(defaultValue)) {
+      return defaultValue
+    }
+    // Fallback: build a placeholder object from child field definitions
+    const placeholder: Record<string, any> = {}
+    for (const childField of field.fields as Field[]) {
+      placeholder[childField.name] = placeholderForField(childField)
+    }
+    return placeholder
+  }, [defaultValue, field.fields])
+
+  return (
+    <div className={`byline-field-group ${field.name}`}>
+      {field.label && (
+        <div className={cx('byline-field-group-header', styles.header)}>
+          <h3 className={cx('byline-field-group-title', styles.title)}>
+            {field.label}{' '}
+            {!field.optional && (
+              <span className={cx('byline-field-group-required', styles.required)}>*</span>
+            )}
+          </h3>
+          {field.helpText && (
+            <p className={cx('byline-field-group-help', styles.help)}>{field.helpText}</p>
+          )}
+        </div>
+      )}
+      <div className={cx('byline-field-group-body', styles.body)}>
+        {(field.fields as Field[]).map((innerField) => {
+          return (
+            <FieldRenderer
+              key={innerField.name}
+              field={innerField}
+              defaultValue={groupData[innerField.name]}
+              basePath={path}
+              disableSorting={true}
+            />
+          )
+        })}
+      </div>
+      {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError} />}
+    </div>
+  )
+}