@byline/admin 2.5.1 → 2.6.0

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]
+  )
+}

package/src/forms/document-actions.module.css

@@ -0,0 +1,160 @@
+/**
+ * DocumentActions — overflow menu (Unpublish / Delete) on the form chrome.
+ *
+ * Override handles:
+ *   .byline-form-actions-icon         — the rotated ellipsis trigger icon
+ *   .byline-form-actions-menu         — dropdown content panel
+ *   .byline-form-actions-item         — a row inside the dropdown
+ *   .byline-form-actions-item-icon    — fixed-width icon column
+ *   .byline-form-actions-item-text    — label column
+ *   .byline-form-actions-delete       — destructive label colour
+ *   .byline-form-actions-modal-head   — modal header layout
+ *   .byline-form-actions-modal-title  — modal heading text
+ *   .byline-form-actions-sr-only      — visually-hidden autofocus shim
+ */
+
+.icon,
+:global(.byline-form-actions-icon) {
+  transform: rotate(90deg);
+  color: var(--primary-500);
+}
+
+.menu,
+:global(.byline-form-actions-menu) {
+  min-width: 140px;
+}
+
+.item,
+:global(.byline-form-actions-item) {
+  display: flex;
+  align-items: center;
+  margin-left: var(--spacing-8);
+}
+
+.item-icon,
+:global(.byline-form-actions-item-icon) {
+  display: inline-block;
+  width: 28px;
+}
+
+.item-text,
+:global(.byline-form-actions-item-text) {
+  display: inline-block;
+  width: 100%;
+  flex: 1;
+  font-size: var(--font-size-sm);
+  text-align: left;
+}
+
+.delete,
+:global(.byline-form-actions-delete) {
+  flex: 1;
+  width: 100%;
+  border: none;
+  background: none;
+  padding: 0;
+  color: var(--red-600);
+  line-height: 1;
+  text-align: left;
+  cursor: pointer;
+}
+
+.modal-head,
+:global(.byline-form-actions-modal-head) {
+  padding-top: 1rem;
+  margin-bottom: var(--spacing-8);
+}
+
+.modal-title,
+:global(.byline-form-actions-modal-title) {
+  margin: 0 0 var(--spacing-8) 0;
+  font-size: var(--font-size-2xl);
+}
+
+.sr-only,
+:global(.byline-form-actions-sr-only) {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.list,
+:global(.byline-form-actions-list) {
+  margin: var(--spacing-8) 0;
+  padding-left: 1.25rem;
+  font-size: var(--font-size-sm);
+}
+
+.preview,
+:global(.byline-form-actions-preview) {
+  margin-top: var(--spacing-16);
+  padding: var(--spacing-8) var(--spacing-12);
+  background: var(--surface-2, rgba(0, 0, 0, 0.03));
+  border: 1px solid var(--border-subtle, rgba(0, 0, 0, 0.08));
+  border-radius: var(--radius-md, 4px);
+  font-size: var(--font-size-sm);
+}
+
+.preview-label,
+:global(.byline-form-actions-preview-label) {
+  font-weight: 500;
+  margin-bottom: var(--spacing-4);
+  opacity: 0.75;
+}
+
+.preview-row,
+:global(.byline-form-actions-preview-row) {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-8);
+  flex-wrap: wrap;
+}
+
+.preview-before,
+:global(.byline-form-actions-preview-before) {
+  font-family: var(--font-mono, monospace);
+  opacity: 0.7;
+}
+
+.preview-arrow,
+:global(.byline-form-actions-preview-arrow) {
+  opacity: 0.5;
+}
+
+.preview-after,
+:global(.byline-form-actions-preview-after) {
+  font-family: var(--font-mono, monospace);
+  font-weight: 500;
+}
+
+.copy-row,
+:global(.byline-form-actions-copy-row) {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+.copy-label,
+:global(.byline-form-actions-copy-label) {
+  /* Layout-only handle; spacing is set inline alongside the field. */
+}
+
+.copy-source,
+:global(.byline-form-actions-copy-source) {
+  font-family: var(--font-mono, monospace);
+}
+
+/* ─── Dark theme variants ───────────────────────────────────── */
+
+:is([data-theme="dark"], :global(.dark)) {
+  .delete,
+  :global(.byline-form-actions-delete) {
+    color: var(--red-400);
+  }
+}