@byline/admin 2.5.2 → 2.6.1

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;
+}

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

@@ -0,0 +1,147 @@
+/**
+ * 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, TextAreaField as FieldType } from '@byline/core'
+import { Label, TextArea } from '@byline/ui/react'
+import cx from 'classnames'
+
+import { useFieldError, useFieldValue } from '../../forms/form-context'
+import { LocaleBadge } from '../locale-badge'
+import styles from './text-area-field.module.css'
+
+export const TextAreaField = ({
+  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
+  // TextArea'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 TextArea doesn't render its own.
+  const hasCustomLabel = !!CustomLabel
+  const suppressInputLabel = showBadge || hasCustomLabel
+  const suppressInputHelpText = !!CustomHelpText
+
+  const labelRowClass = cx('byline-field-text-area-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 (
+      <TextArea
+        id={htmlId}
+        name={field.name}
+        label={suppressInputLabel ? undefined : field.label}
+        required={!field.optional}
+        helpText={suppressInputHelpText ? undefined : field.helpText}
+        value={incomingValue}
+        onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => handleChange(e.target.value)}
+        error={fieldError != null}
+        errorText={fieldError}
+        rows={4}
+      />
+    )
+  }
+
+  return (
+    <div className={`byline-field-text-area ${field.name}`}>
+      {renderLabel()}
+      {BeforeField && <BeforeField {...slotBaseProps} />}
+      {renderInput()}
+      {AfterField && <AfterField {...slotBaseProps} />}
+      {CustomHelpText && <CustomHelpText {...slotBaseProps} helpText={field.helpText} />}
+    </div>
+  )
+}

package/src/fields/use-field-change-handler.ts

@@ -0,0 +1,112 @@
+/**
+ * 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, FieldBeforeChangeResult, FieldHookContext } from '@byline/core'
+import { normalizeHooks } from '@byline/core'
+
+import { useFormContext } from '../forms/form-context'
+
+/**
+ * Returns a change handler for the given field that runs through the
+ * field-hook pipeline before committing the value:
+ *
+ *   1. `clearFieldError(path)`
+ *   2. `field.hooks.beforeValidate(ctx)` — advisory: may set an error on
+ *      the field but the value is **always** committed (user can keep typing)
+ *   3. `field.hooks.beforeChange(ctx)` — may return `{ value }` to replace
+ *      or `{ error }` to block the change entirely
+ *   4. `setFieldValue(path, finalValue)`
+ *
+ * When the field has no hooks the function is a zero-overhead pass-through
+ * to `setFieldValue` (no promises, no extra allocations).
+ */
+export function useFieldChangeHandler(field: Field, path: string) {
+  const { setFieldValue, getFieldValue, getFieldValues, setFieldError, clearFieldError } =
+    useFormContext()
+
+  return useCallback(
+    (value: any) => {
+      const hooks = field.hooks
+
+      // ── fast path: no hooks defined ────────────────────────────
+      const validateFns = normalizeHooks(hooks?.beforeValidate)
+      const changeFns = normalizeHooks(hooks?.beforeChange)
+
+      if (validateFns.length === 0 && changeFns.length === 0) {
+        setFieldValue(path, value)
+        return
+      }
+
+      // ── slow path: run async hook pipeline ─────────────────────
+      const previousValue = getFieldValue(path)
+      const ctx: FieldHookContext = {
+        value,
+        previousValue,
+        data: getFieldValues(),
+        path,
+        field,
+        operation: 'change',
+      }
+
+      clearFieldError(path)
+
+      // When there are only advisory beforeValidate hooks (no beforeChange that can
+      // block or transform the value), commit synchronously so that controlled inputs
+      // (e.g. <input value={...}>) receive the updated value before React's next
+      // render. Deferring even one microtask tick (via await) causes React to
+      // reconcile the stale value prop against the DOM and reset cursor position.
+      if (changeFns.length === 0) {
+        setFieldValue(path, value)
+      }
+
+      void (async () => {
+        try {
+          // 1. beforeValidate (advisory — value is always committed)
+          let advisoryError: string | undefined
+          for (const fn of validateFns) {
+            const result = (await fn(ctx)) as FieldBeforeChangeResult | undefined
+            if (result?.error) {
+              advisoryError = result.error
+            }
+            if (result?.value !== undefined) {
+              ctx.value = result.value
+            }
+          }
+
+          // 2. beforeChange
+          for (const fn of changeFns) {
+            const result = (await fn(ctx)) as FieldBeforeChangeResult | undefined
+            if (result?.error) {
+              setFieldError(path, result.error)
+              return // block the change
+            }
+            if (result?.value !== undefined) {
+              ctx.value = result.value
+            }
+          }
+
+          // 3. commit the (possibly transformed) value and surface any advisory error.
+          // If there were no beforeChange hooks we already committed synchronously above;
+          // this call is a no-op if the value hasn't been altered by a hook.
+          setFieldValue(path, ctx.value)
+          if (advisoryError) {
+            setFieldError(path, advisoryError)
+          }
+        } catch (err) {
+          // Surface unexpected hook errors as field errors rather than crashing
+          const message = err instanceof Error ? err.message : 'Unexpected hook error'
+          setFieldError(path, message)
+        }
+      })()
+    },
+    // field reference is stable per render cycle; path is derived from props
+    [field, path, setFieldValue, getFieldValue, getFieldValues, setFieldError, clearFieldError]
+  )
+}