@byline/admin 3.16.0 → 3.17.0

package/dist/fields/array/array-field.d.ts

@@ -6,11 +6,18 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { ArrayField as ArrayFieldType } from '@byline/core';
-export declare const ArrayField: ({ field, defaultValue, path, disableSorting, contentLocale, }: {
+export declare const ArrayField: ({ field, defaultValue, path, disableSorting, collectionPath, contentLocale, }: {
     field: ArrayFieldType;
     defaultValue: any;
     path: string;
     disableSorting?: boolean;
+    /**
+     * Collection path forwarded to upload-capable fields (`file` / `image`)
+     * nested inside an array item, which need it to reach the `/upload`
+     * endpoint. Without it those fields fall back to their empty placeholder
+     * and never render an upload widget.
+     */
+    collectionPath?: string;
     /**
      * Active content locale, forwarded to each array item's fields so
      * localized widgets nested inside an array (e.g. a `localized` richText)

package/dist/fields/array/array-field.js

@@ -8,7 +8,7 @@ import { FieldRenderer } from "../field-renderer.js";
 import { SortableItem } from "../sortable-item.js";
 import { useFormContext } from "../../forms/form-context.js";
 import array_field_module from "./array-field.module.js";
-const ArrayField = ({ field, defaultValue, path, disableSorting = false, contentLocale })=>{
+const ArrayField = ({ field, defaultValue, path, disableSorting = false, collectionPath, contentLocale })=>{
     const { appendPatch, getFieldValue, getFieldValues, setFieldStore } = useFormContext();
     const { t } = useTranslation('byline-admin');
     const [items, setItems] = useState([]);
@@ -118,6 +118,7 @@ const ArrayField = ({ field, defaultValue, path, disableSorting = false, content
                                 defaultValue: groupData[innerField.name],
                                 basePath: `${arrayElementPath}.${childField.name}`,
                                 disableSorting: true,
+                                collectionPath: collectionPath,
                                 contentLocale: contentLocale
                             }, innerField.name))
                     ]
@@ -128,6 +129,7 @@ const ArrayField = ({ field, defaultValue, path, disableSorting = false, content
                 defaultValue: initial,
                 basePath: arrayElementPath,
                 disableSorting: true,
+                collectionPath: collectionPath,
                 contentLocale: contentLocale
             }, childField.name);
         });

package/dist/fields/field-renderer.d.ts

@@ -33,5 +33,5 @@ interface FieldRendererProps {
      */
     editor?: RichTextEditorComponent;
 }
-export declare const FieldRenderer: ({ field, defaultValue, basePath, disableSorting, hideLabel, collectionPath, contentLocale, components, editor, }: FieldRendererProps) => import("react").JSX.Element | null;
+export declare const FieldRenderer: ({ field, defaultValue: initialDefault, basePath, disableSorting, hideLabel, collectionPath, contentLocale, components, editor, }: FieldRendererProps) => import("react").JSX.Element | null;
 export {};

package/dist/fields/field-renderer.js

@@ -1,6 +1,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { getClientConfig } from "@byline/core";
 import classnames from "classnames";
+import { useFormContext } from "../forms/form-context.js";
 import { ArrayField } from "./array/array-field.js";
 import { BlocksField } from "./blocks/blocks-field.js";
 import { CheckboxField } from "./checkbox/checkbox-field.js";
@@ -17,14 +18,20 @@ import { SelectField } from "./select/select-field.js";
 import { TextField } from "./text/text-field.js";
 import { TextAreaField } from "./text-area/text-area-field.js";
 import { useFieldChangeHandler } from "./use-field-change-handler.js";
-const FieldRenderer = ({ field, defaultValue, basePath, disableSorting, hideLabel, collectionPath, contentLocale, components, editor })=>{
+import { useFieldCondition } from "./use-field-condition.js";
+const FieldRenderer = ({ field, defaultValue: initialDefault, basePath, disableSorting, hideLabel, collectionPath, contentLocale, components, editor })=>{
     const path = basePath ? `${basePath}.${field.name}` : field.name;
     const htmlId = path.replace(/[[\].]/g, '-');
     const handleChange = useFieldChangeHandler(field, path);
+    const { getFieldValue } = useFormContext();
+    const visible = useFieldCondition(field, basePath);
+    const storedValue = field.condition ? getFieldValue(path) : void 0;
+    const defaultValue = void 0 !== storedValue ? storedValue : initialDefault;
     const isLocalised = true === field.localized;
     const badge = isLocalised && contentLocale && !hideLabel ? /*#__PURE__*/ jsx(LocaleBadge, {
         locale: contentLocale
     }) : null;
+    if (!visible) return null;
     const renderField = ()=>{
         switch(field.type){
             case 'text':
@@ -180,6 +187,7 @@ const FieldRenderer = ({ field, defaultValue, basePath, disableSorting, hideLabe
                     } : field,
                     defaultValue: defaultValue,
                     path: path,
+                    collectionPath: collectionPath,
                     contentLocale: contentLocale
                 });
             case 'blocks':
@@ -197,6 +205,7 @@ const FieldRenderer = ({ field, defaultValue, basePath, disableSorting, hideLabe
                     defaultValue: defaultValue,
                     path: path,
                     disableSorting: disableSorting,
+                    collectionPath: collectionPath,
                     contentLocale: contentLocale
                 });
             default:

package/dist/fields/group/group-field.d.ts

@@ -10,6 +10,12 @@ interface GroupFieldProps {
     field: GroupFieldType;
     defaultValue: any;
     path: string;
+    /**
+     * Collection path forwarded to upload-capable child fields (`file` / `image`),
+     * which need it to reach the `/upload` endpoint. Without it those fields fall
+     * back to their empty placeholder and never render an upload widget.
+     */
+    collectionPath?: string;
     /**
      * Active content locale, forwarded to child fields so localized widgets
      * nested inside the group (e.g. a `localized` richText) can render their
@@ -17,5 +23,5 @@ interface GroupFieldProps {
      */
     contentLocale?: string;
 }
-export declare const GroupField: ({ field, defaultValue, path, contentLocale }: GroupFieldProps) => import("react").JSX.Element;
+export declare const GroupField: ({ field, defaultValue, path, collectionPath, contentLocale, }: GroupFieldProps) => import("react").JSX.Element;
 export {};

package/dist/fields/group/group-field.js

@@ -6,7 +6,7 @@ import { placeholderForField } from "../field-helpers.js";
 import { FieldRenderer } from "../field-renderer.js";
 import { useFieldError } from "../../forms/form-context.js";
 import group_field_module from "./group-field.module.js";
-const GroupField = ({ field, defaultValue, path, contentLocale })=>{
+const GroupField = ({ field, defaultValue, path, collectionPath, contentLocale })=>{
     const fieldError = useFieldError(field.name);
     const groupData = useMemo(()=>{
         if (defaultValue && 'object' == typeof defaultValue && !Array.isArray(defaultValue)) return defaultValue;
@@ -47,6 +47,7 @@ const GroupField = ({ field, defaultValue, path, contentLocale })=>{
                         defaultValue: groupData[innerField.name],
                         basePath: path,
                         disableSorting: true,
+                        collectionPath: collectionPath,
                         contentLocale: contentLocale
                     }, innerField.name))
             }),

package/dist/fields/use-field-change-handler.js

@@ -15,7 +15,8 @@ function useFieldChangeHandler(field, path) {
             data: getFieldValues(),
             path,
             field,
-            operation: 'change'
+            operation: 'change',
+            setFieldValue
         };
         clearFieldError(path);
         if (0 === changeFns.length) setFieldValue(path, value);

package/dist/fields/use-field-condition.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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';
+/**
+ * Evaluate a field's visibility `condition` against live form data.
+ *
+ * Subscribes to the form's meta listeners — fired on every field commit, the
+ * same loop `TabDefinition.condition` rides — and recomputes the predicate.
+ * The consumer only re-renders when the boolean actually flips, so a stable
+ * condition costs one function call per form edit, no reconciliation.
+ *
+ * `basePath` is the field's sibling scope: the enclosing group / array item
+ * (e.g. `files[0].filesGroup` for `files[0].filesGroup.thumbnailPage`).
+ * Root-level fields pass no basePath and receive the full form data as their
+ * sibling scope, mirroring `FieldCondition`'s contract.
+ *
+ * Fields without a condition are always visible and no subscription is made.
+ */
+export declare const useFieldCondition: (field: Field, basePath?: string) => boolean;

package/dist/fields/use-field-condition.js

@@ -0,0 +1,28 @@
+import { useCallback, useEffect, useState } from "react";
+import { useFormContext } from "../forms/form-context.js";
+import { get } from "../forms/nested-path.js";
+const useFieldCondition = (field, basePath)=>{
+    const { getFieldValues, subscribeMeta } = useFormContext();
+    const evaluate = useCallback(()=>{
+        if (!field.condition) return true;
+        const data = getFieldValues();
+        const siblingData = basePath ? get(data, basePath) ?? {} : data;
+        return Boolean(field.condition(data, siblingData));
+    }, [
+        field,
+        basePath,
+        getFieldValues
+    ]);
+    const [visible, setVisible] = useState(evaluate);
+    useEffect(()=>{
+        if (!field.condition) return;
+        setVisible(evaluate());
+        return subscribeMeta(()=>setVisible(evaluate()));
+    }, [
+        field.condition,
+        subscribeMeta,
+        evaluate
+    ]);
+    return visible;
+};
+export { useFieldCondition };

package/dist/forms/form-context.js

@@ -144,10 +144,6 @@ const FormProvider = ({ children, initialData = {} })=>{
         ];
         dirtyFields.current.add('__patch__');
         notifyMetaListeners();
-        if ('production' !== process.env.NODE_ENV) console.debug('FormContext.appendPatch', {
-            patch,
-            dirtyCount: dirtyFields.current.size
-        });
     }, [
         notifyMetaListeners
     ]);
@@ -248,6 +244,7 @@ const FormProvider = ({ children, initialData = {} })=>{
         const formErrors = [];
         const data = getFieldValues();
         for (const field of fields){
+            if (field.condition && !field.condition(data, data)) continue;
             const value = getFieldValue(field.name);
             if (!field.optional && (null == value || '' === value)) formErrors.push({
                 field: field.name,
@@ -331,6 +328,7 @@ const FormProvider = ({ children, initialData = {} })=>{
         for (const field of fields){
             const fns = normalizeHooks(field.hooks?.beforeValidate);
             if (0 === fns.length) continue;
+            if (field.condition && !field.condition(data, data)) continue;
             const path = field.name;
             const value = getFieldValue(path);
             const ctx = {
@@ -339,7 +337,8 @@ const FormProvider = ({ children, initialData = {} })=>{
                 data,
                 path,
                 field,
-                operation: 'submit'
+                operation: 'submit',
+                setFieldValue
             };
             try {
                 for (const fn of fns){

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -155,10 +155,10 @@
     "react-diff-viewer-continued": "^4.2.2",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.16.0",
-    "@byline/ui": "3.16.0",
-    "@byline/core": "3.16.0",
-    "@byline/i18n": "3.16.0"
+    "@byline/auth": "3.17.0",
+    "@byline/i18n": "3.17.0",
+    "@byline/core": "3.17.0",
+    "@byline/ui": "3.17.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

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

@@ -29,12 +29,20 @@ export const ArrayField = ({
   defaultValue,
   path,
   disableSorting = false,
+  collectionPath,
   contentLocale,
 }: {
   field: ArrayFieldType
   defaultValue: any
   path: string
   disableSorting?: boolean
+  /**
+   * Collection path forwarded to upload-capable fields (`file` / `image`)
+   * nested inside an array item, which need it to reach the `/upload`
+   * endpoint. Without it those fields fall back to their empty placeholder
+   * and never render an upload widget.
+   */
+  collectionPath?: string
   /**
    * Active content locale, forwarded to each array item's fields so
    * localized widgets nested inside an array (e.g. a `localized` richText)
@@ -205,6 +213,7 @@ export const ArrayField = ({
                 defaultValue={groupData[innerField.name]}
                 basePath={`${arrayElementPath}.${childField.name}`}
                 disableSorting={true}
+                collectionPath={collectionPath}
                 contentLocale={contentLocale}
               />
             ))}
@@ -219,6 +228,7 @@ export const ArrayField = ({
           defaultValue={initial}
           basePath={arrayElementPath}
           disableSorting={true}
+          collectionPath={collectionPath}
           contentLocale={contentLocale}
         />
       )

package/src/fields/field-renderer.tsx

@@ -17,6 +17,7 @@ import type {
 import { getClientConfig } from '@byline/core'
 import cx from 'classnames'
 
+import { useFormContext } from '../forms/form-context'
 import { ArrayField } from './array/array-field'
 import { BlocksField } from './blocks/blocks-field'
 import { CheckboxField } from './checkbox/checkbox-field'
@@ -33,6 +34,7 @@ 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'
+import { useFieldCondition } from './use-field-condition'
 
 // ---------------------------------------------------------------------------
 // FieldRenderer — the main field type switch. Delegates to the appropriate
@@ -69,7 +71,7 @@ interface FieldRendererProps {
 
 export const FieldRenderer = ({
   field,
-  defaultValue,
+  defaultValue: initialDefault,
   basePath,
   disableSorting,
   hideLabel,
@@ -82,6 +84,20 @@ export const FieldRenderer = ({
   const htmlId = path.replace(/[[\].]/g, '-')
 
   const handleChange = useFieldChangeHandler(field, path)
+  const { getFieldValue } = useFormContext()
+
+  // Conditional visibility (BaseField.condition) — re-evaluated on every form
+  // edit; the field unmounts while its condition is false.
+  const visible = useFieldCondition(field, basePath)
+
+  // Conditional fields unmount while hidden, so on re-show the uncontrolled
+  // widget must be re-seeded from the live form store (which survives the
+  // unmount) rather than the initial document data — otherwise an edit made
+  // before hiding would be visually reverted while the store (and the patch
+  // stream) still carried it. `undefined` means the path was never written,
+  // in which case the initial default stands.
+  const storedValue = field.condition ? getFieldValue(path) : undefined
+  const defaultValue = storedValue !== undefined ? storedValue : initialDefault
 
   // 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.
@@ -90,6 +106,10 @@ export const FieldRenderer = ({
   const badge =
     isLocalised && contentLocale && !hideLabel ? <LocaleBadge locale={contentLocale} /> : null
 
+  // All hooks have run by this point, so a conditional bail-out is safe.
+  // Hiding retains the field's stored value — no clearing patch is emitted.
+  if (!visible) return null
+
   /**
    * Render the underlying field widget. If the field is localised, we wrap it
    * so we can append the locale badge after the label.
@@ -254,6 +274,7 @@ export const FieldRenderer = ({
             }
             defaultValue={defaultValue}
             path={path}
+            collectionPath={collectionPath}
             contentLocale={contentLocale}
           />
         )
@@ -275,6 +296,7 @@ export const FieldRenderer = ({
             defaultValue={defaultValue}
             path={path}
             disableSorting={disableSorting}
+            collectionPath={collectionPath}
             contentLocale={contentLocale}
           />
         )

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

@@ -32,6 +32,12 @@ interface GroupFieldProps {
   field: GroupFieldType
   defaultValue: any
   path: string
+  /**
+   * Collection path forwarded to upload-capable child fields (`file` / `image`),
+   * which need it to reach the `/upload` endpoint. Without it those fields fall
+   * back to their empty placeholder and never render an upload widget.
+   */
+  collectionPath?: string
   /**
    * Active content locale, forwarded to child fields so localized widgets
    * nested inside the group (e.g. a `localized` richText) can render their
@@ -40,7 +46,13 @@ interface GroupFieldProps {
   contentLocale?: string
 }
 
-export const GroupField = ({ field, defaultValue, path, contentLocale }: GroupFieldProps) => {
+export const GroupField = ({
+  field,
+  defaultValue,
+  path,
+  collectionPath,
+  contentLocale,
+}: 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.
@@ -80,6 +92,7 @@ export const GroupField = ({ field, defaultValue, path, contentLocale }: GroupFi
               defaultValue={groupData[innerField.name]}
               basePath={path}
               disableSorting={true}
+              collectionPath={collectionPath}
               contentLocale={contentLocale}
             />
           )

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

@@ -53,6 +53,10 @@ export function useFieldChangeHandler(field: Field, path: string) {
         path,
         field,
         operation: 'change',
+        // Raw store write for cross-field behaviour (e.g. mutual exclusivity
+        // across array items). Deliberately does not run the target field's
+        // own hooks — see FieldHookContext.setFieldValue.
+        setFieldValue,
       }
 
       clearFieldError(path)

package/src/fields/use-field-condition.ts

@@ -0,0 +1,52 @@
+/**
+ * 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, useEffect, useState } from 'react'
+
+import type { Field } from '@byline/core'
+
+import { useFormContext } from '../forms/form-context'
+import { get as getNestedValue } from '../forms/nested-path'
+
+/**
+ * Evaluate a field's visibility `condition` against live form data.
+ *
+ * Subscribes to the form's meta listeners — fired on every field commit, the
+ * same loop `TabDefinition.condition` rides — and recomputes the predicate.
+ * The consumer only re-renders when the boolean actually flips, so a stable
+ * condition costs one function call per form edit, no reconciliation.
+ *
+ * `basePath` is the field's sibling scope: the enclosing group / array item
+ * (e.g. `files[0].filesGroup` for `files[0].filesGroup.thumbnailPage`).
+ * Root-level fields pass no basePath and receive the full form data as their
+ * sibling scope, mirroring `FieldCondition`'s contract.
+ *
+ * Fields without a condition are always visible and no subscription is made.
+ */
+export const useFieldCondition = (field: Field, basePath?: string): boolean => {
+  const { getFieldValues, subscribeMeta } = useFormContext()
+
+  const evaluate = useCallback((): boolean => {
+    if (!field.condition) return true
+    const data = getFieldValues()
+    const siblingData = basePath ? (getNestedValue(data, basePath) ?? {}) : data
+    return Boolean(field.condition(data, siblingData))
+  }, [field, basePath, getFieldValues])
+
+  const [visible, setVisible] = useState<boolean>(evaluate)
+
+  useEffect(() => {
+    if (!field.condition) return undefined
+    // Re-evaluate on (re)subscribe as well as on every subsequent form edit —
+    // the store may have changed between the initial render and this effect.
+    setVisible(evaluate())
+    return subscribeMeta(() => setVisible(evaluate()))
+  }, [field.condition, subscribeMeta, evaluate])
+
+  return visible
+}

package/src/forms/form-context.tsx

@@ -308,10 +308,11 @@ export const FormProvider = ({
       // for patches that don't correspond to a specific field.set.
       dirtyFields.current.add('__patch__')
       notifyMetaListeners()
-      if (process.env.NODE_ENV !== 'production') {
-        // eslint-disable-next-line no-console
-        console.debug('FormContext.appendPatch', { patch, dirtyCount: dirtyFields.current.size })
-      }
+      // Dev-time patch tracing — uncomment when debugging the patch stream.
+      // if (process.env.NODE_ENV !== 'production') {
+      //   // eslint-disable-next-line no-console
+      //   console.debug('FormContext.appendPatch', { patch, dirtyCount: dirtyFields.current.size })
+      // }
     },
     [notifyMetaListeners]
   )
@@ -476,6 +477,12 @@ export const FormProvider = ({
       const data = getFieldValues()
 
       for (const field of fields) {
+        // Condition-hidden fields are exempt from client-side validation — a
+        // field the editor cannot currently see must not block submit. Only
+        // top-level fields flow through this walk, and a root-level field's
+        // sibling scope is the form data itself (see FieldCondition).
+        if (field.condition && !field.condition(data, data)) continue
+
         const value = getFieldValue(field.name)
 
         // Required field validation
@@ -583,6 +590,10 @@ export const FormProvider = ({
         const fns = normalizeHooks(field.hooks?.beforeValidate)
         if (fns.length === 0) continue
 
+        // Condition-hidden fields skip submit-time hooks, mirroring their
+        // exemption from validateForm below.
+        if (field.condition && !field.condition(data, data)) continue
+
         const path = field.name
         const value = getFieldValue(path)
 
@@ -593,6 +604,7 @@ export const FormProvider = ({
           path,
           field,
           operation: 'submit',
+          setFieldValue,
         }
 
         try {