@byline/admin 3.12.0 → 3.12.2

package/dist/forms/use-form-layout.js

@@ -0,0 +1,77 @@
+"use client";
+import { useMemo } from "react";
+function buildFieldToTabPath(adminConfig, fieldByName, rowByName, groupByName) {
+    const map = new Map();
+    const visit = (names, tabSetName, tabName, seen)=>{
+        for (const name of names)if (fieldByName.has(name)) map.set(name, {
+            tabSetName,
+            tabName
+        });
+        else if (seen.has(name)) ;
+        else if (rowByName.has(name)) {
+            const row = rowByName.get(name);
+            const next = new Set(seen).add(name);
+            visit(row.fields, tabSetName, tabName, next);
+        } else if (groupByName.has(name)) {
+            const group = groupByName.get(name);
+            const next = new Set(seen).add(name);
+            visit(group.fields, tabSetName, tabName, next);
+        }
+    };
+    for (const set of adminConfig?.tabSets ?? [])for (const tab of set.tabs)visit(tab.fields, set.name, tab.name, new Set());
+    return map;
+}
+function useFormLayout(adminConfig, fields) {
+    const fieldByName = useMemo(()=>{
+        const map = new Map();
+        for (const field of fields)if ('name' in field) map.set(field.name, field);
+        return map;
+    }, [
+        fields
+    ]);
+    const tabSetByName = useMemo(()=>{
+        const map = new Map();
+        for (const set of adminConfig?.tabSets ?? [])map.set(set.name, set);
+        return map;
+    }, [
+        adminConfig
+    ]);
+    const rowByName = useMemo(()=>{
+        const map = new Map();
+        for (const row of adminConfig?.rows ?? [])map.set(row.name, row);
+        return map;
+    }, [
+        adminConfig
+    ]);
+    const groupByName = useMemo(()=>{
+        const map = new Map();
+        for (const group of adminConfig?.groups ?? [])map.set(group.name, group);
+        return map;
+    }, [
+        adminConfig
+    ]);
+    const layout = useMemo(()=>{
+        if (adminConfig?.layout) return adminConfig.layout;
+        return {
+            main: fields.filter((f)=>'name' in f).map((f)=>f.name)
+        };
+    }, [
+        adminConfig,
+        fields
+    ]);
+    const fieldToTabPath = useMemo(()=>buildFieldToTabPath(adminConfig, fieldByName, rowByName, groupByName), [
+        adminConfig,
+        fieldByName,
+        rowByName,
+        groupByName
+    ]);
+    return {
+        fieldByName,
+        tabSetByName,
+        rowByName,
+        groupByName,
+        layout,
+        fieldToTabPath
+    };
+}
+export { buildFieldToTabPath, useFormLayout };

package/dist/forms/use-form-layout.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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
+ */
+export {};

package/dist/forms/use-tracked-slot.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 RefObject } from 'react';
+/**
+ * A dirty-tracked, ref-backed form slot with its own listener set — the shared
+ * machinery behind the document-grain system fields (`path`, advertised
+ * `availableLocales`, …). Each slot holds the current value, the value it was
+ * loaded with, and a set of subscribers; a `set` that moves the value away from
+ * its loaded baseline registers the slot's `dirtyKey` in the form's shared
+ * dirty set (and clears it again when the value returns to baseline), so the
+ * single Save button can branch on which buckets changed.
+ *
+ * Adding a new system slot is then a one-liner at the call site rather than a
+ * copy of ref + initial-ref + listener-set + get/set/subscribe.
+ */
+export interface TrackedSlot<T> {
+    /** Current value (live ref read — not React state). */
+    get: () => T;
+    /** Write a value; toggles `dirtyKey` against the loaded baseline. */
+    set: (value: T) => void;
+    /** Subscribe to value changes; returns an unsubscribe fn. */
+    subscribe: (listener: (value: T) => void) => () => void;
+    /** Re-baseline: adopt the current value as the new "clean" baseline (called on save). */
+    commitInitial: () => void;
+}
+export interface UseTrackedSlotConfig<T> {
+    /** Initial / loaded value. */
+    initial: T;
+    /** Key registered in the shared dirty set while this slot diverges from baseline. */
+    dirtyKey: string;
+    /** The form's shared dirty-key set. */
+    dirtyFields: RefObject<Set<string>>;
+    /** Notify the form's meta listeners (drives hasChanges → Save button). */
+    notifyMeta: () => void;
+    /** Equality against the baseline. Defaults to `===` (identity). */
+    isEqual?: (a: T, b: T) => boolean;
+    /** Defensive copy on read-in / write. Defaults to identity (fine for immutables). */
+    clone?: (value: T) => T;
+}
+export declare function useTrackedSlot<T>(config: UseTrackedSlotConfig<T>): TrackedSlot<T>;

package/dist/forms/use-tracked-slot.js

@@ -0,0 +1,46 @@
+"use client";
+import { useCallback, useRef } from "react";
+function useTrackedSlot(config) {
+    const cfgRef = useRef(config);
+    cfgRef.current = config;
+    const clone = useCallback((value)=>{
+        const fn = cfgRef.current.clone;
+        return fn ? fn(value) : value;
+    }, []);
+    const valueRef = useRef(clone(config.initial));
+    const initialRef = useRef(clone(config.initial));
+    const listeners = useRef(new Set());
+    const get = useCallback(()=>valueRef.current, []);
+    const set = useCallback((value)=>{
+        const { dirtyKey, dirtyFields, notifyMeta, isEqual } = cfgRef.current;
+        const next = clone(value);
+        valueRef.current = next;
+        const equal = isEqual ? isEqual(next, initialRef.current) : next === initialRef.current;
+        if (equal) dirtyFields.current.delete(dirtyKey);
+        else dirtyFields.current.add(dirtyKey);
+        listeners.current.forEach((listener)=>{
+            listener(next);
+        });
+        notifyMeta();
+    }, [
+        clone
+    ]);
+    const subscribe = useCallback((listener)=>{
+        listeners.current.add(listener);
+        return ()=>{
+            listeners.current.delete(listener);
+        };
+    }, []);
+    const commitInitial = useCallback(()=>{
+        initialRef.current = clone(valueRef.current);
+    }, [
+        clone
+    ]);
+    return {
+        get,
+        set,
+        subscribe,
+        commitInitial
+    };
+}
+export { useTrackedSlot };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.12.0",
+  "version": "3.12.2",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -151,10 +151,10 @@
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
     "zod-form-data": "^3.0.1",
-    "@byline/ui": "3.12.0",
-    "@byline/auth": "3.12.0",
-    "@byline/core": "3.12.0",
-    "@byline/i18n": "3.12.0"
+    "@byline/auth": "3.12.2",
+    "@byline/ui": "3.12.2",
+    "@byline/core": "3.12.2",
+    "@byline/i18n": "3.12.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/forms/form-context.tsx

@@ -20,6 +20,7 @@ import type { DocumentPatch, FieldSetPatch } from '@byline/core/patches'
 // ~85KB chunk that leaks onto the public frontend bundle (form-context is
 // reachable from the layout graph).
 import { get as getNestedValue, set as setNestedValue } from './nested-path'
+import { useTrackedSlot } from './use-tracked-slot'
 
 interface FormError {
   field: string
@@ -168,27 +169,6 @@ export const FormProvider = ({
   const errorListeners = useRef<Set<ErrorsListener>>(new Set())
   const metaListeners = useRef<Set<MetaListener>>(new Set())
 
-  // System path slot — initialised from the loaded version's top-level
-  // `path` (edit mode) or `null` (create mode). Edits via `setSystemPath`
-  // mark the form dirty so the Save button enables.
-  const systemPathRef = useRef<string | null>(
-    typeof initialData?.path === 'string' && (initialData.path as string).length > 0
-      ? (initialData.path as string)
-      : null
-  )
-  const initialSystemPath = useRef<string | null>(systemPathRef.current)
-  const systemPathListeners = useRef<Set<SystemPathListener>>(new Set())
-
-  // System available-locales slot — initialised from the loaded version's
-  // top-level `availableLocales` (edit mode) or `[]` (create mode / not yet
-  // surfaced). Edits via `setSystemAvailableLocales` mark the form dirty so
-  // the Save button enables. Stored as a defensive copy.
-  const systemAvailableLocalesRef = useRef<string[]>(
-    Array.isArray(initialData?.availableLocales) ? [...initialData.availableLocales] : []
-  )
-  const initialSystemAvailableLocales = useRef<string[]>([...systemAvailableLocalesRef.current])
-  const systemAvailableLocalesListeners = useRef<Set<SystemAvailableLocalesListener>>(new Set())
-
   const subscribeField = useCallback((name: string, listener: FieldListener) => {
     if (!fieldListeners.current.has(name)) {
       fieldListeners.current.set(name, new Set())
@@ -240,6 +220,32 @@ export const FormProvider = ({
     })
   }, [])
 
+  // Document-grain system-field slots — dirty-tracked, ref-backed, each with
+  // its own listener set. The `path` slot is initialised from the loaded
+  // version's top-level `path` (edit) or `null` (create); the available-locales
+  // slot from `availableLocales` (edit) or `[]`. Edits toggle the slot's dirty
+  // key so the single Save button can branch. See ./use-tracked-slot.
+  const pathSlot = useTrackedSlot<string | null>({
+    initial:
+      typeof initialData?.path === 'string' && (initialData.path as string).length > 0
+        ? (initialData.path as string)
+        : null,
+    dirtyKey: SYSTEM_PATH_DIRTY_KEY,
+    dirtyFields,
+    notifyMeta: notifyMetaListeners,
+  })
+
+  const availableLocalesSlot = useTrackedSlot<string[]>({
+    initial: Array.isArray(initialData?.availableLocales) ? [...initialData.availableLocales] : [],
+    dirtyKey: SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY,
+    dirtyFields,
+    notifyMeta: notifyMetaListeners,
+    // The slot holds an array; a fresh reference is never `===` its baseline,
+    // so dirty tracking compares membership, not identity. Stored as a copy.
+    isEqual: sameLocaleSet,
+    clone: (value) => [...value],
+  })
+
   const updateFieldStoreInternal = useCallback(
     (name: string, value: any) => {
       const newFieldValues = { ...fieldValues.current }
@@ -330,10 +336,10 @@ export const FormProvider = ({
   const resetHasChanges = useCallback(() => {
     dirtyFields.current.clear()
     patchesRef.current = []
-    initialSystemPath.current = systemPathRef.current
-    initialSystemAvailableLocales.current = [...systemAvailableLocalesRef.current]
+    pathSlot.commitInitial()
+    availableLocalesSlot.commitInitial()
     notifyMetaListeners()
-  }, [notifyMetaListeners])
+  }, [notifyMetaListeners, pathSlot.commitInitial, availableLocalesSlot.commitInitial])
 
   const isDirty = useCallback((fieldName: string) => {
     return dirtyFields.current.has(fieldName)
@@ -367,68 +373,6 @@ export const FormProvider = ({
     return { reason, contentDirty, pathDirty, availableLocalesDirty }
   }, [])
 
-  // -------------------------------------------------------------------------
-  // System path slot
-  // -------------------------------------------------------------------------
-
-  const getSystemPath = useCallback(() => systemPathRef.current, [])
-
-  const setSystemPath = useCallback(
-    (value: string | null) => {
-      systemPathRef.current = value
-      if (value !== initialSystemPath.current) {
-        dirtyFields.current.add(SYSTEM_PATH_DIRTY_KEY)
-      } else {
-        dirtyFields.current.delete(SYSTEM_PATH_DIRTY_KEY)
-      }
-      systemPathListeners.current.forEach((listener) => {
-        listener(value)
-      })
-      notifyMetaListeners()
-    },
-    [notifyMetaListeners]
-  )
-
-  const subscribeSystemPath = useCallback((listener: SystemPathListener) => {
-    systemPathListeners.current.add(listener)
-    return () => {
-      systemPathListeners.current.delete(listener)
-    }
-  }, [])
-
-  // -------------------------------------------------------------------------
-  // System available-locales slot
-  // -------------------------------------------------------------------------
-
-  const getSystemAvailableLocales = useCallback(() => systemAvailableLocalesRef.current, [])
-
-  const setSystemAvailableLocales = useCallback(
-    (value: string[]) => {
-      const next = [...value]
-      systemAvailableLocalesRef.current = next
-      if (!sameLocaleSet(next, initialSystemAvailableLocales.current)) {
-        dirtyFields.current.add(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY)
-      } else {
-        dirtyFields.current.delete(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY)
-      }
-      systemAvailableLocalesListeners.current.forEach((listener) => {
-        listener(next)
-      })
-      notifyMetaListeners()
-    },
-    [notifyMetaListeners]
-  )
-
-  const subscribeSystemAvailableLocales = useCallback(
-    (listener: SystemAvailableLocalesListener) => {
-      systemAvailableLocalesListeners.current.add(listener)
-      return () => {
-        systemAvailableLocalesListeners.current.delete(listener)
-      }
-    },
-    []
-  )
-
   // ---------------------------------------------------------------------------
   // Pending uploads (deferred until save)
   // ---------------------------------------------------------------------------
@@ -715,12 +659,12 @@ export const FormProvider = ({
         setFieldUploading,
         getIsFieldUploading,
         subscribeFieldUploading,
-        getSystemPath,
-        setSystemPath,
-        subscribeSystemPath,
-        getSystemAvailableLocales,
-        setSystemAvailableLocales,
-        subscribeSystemAvailableLocales,
+        getSystemPath: pathSlot.get,
+        setSystemPath: pathSlot.set,
+        subscribeSystemPath: pathSlot.subscribe,
+        getSystemAvailableLocales: availableLocalesSlot.get,
+        setSystemAvailableLocales: availableLocalesSlot.set,
+        subscribeSystemAvailableLocales: availableLocalesSlot.subscribe,
       }}
     >
       {children}

package/src/forms/form-modals.tsx

@@ -0,0 +1,186 @@
+'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 { Button, CloseIcon, IconButton, Modal } from '@byline/ui/react'
+import cx from 'classnames'
+
+import styles from './form-renderer.module.css'
+
+/**
+ * Shown when the editor triggers a guarded action (status change, duplicate,
+ * copy-to-locale) while the form is dirty. Those actions operate on the saved
+ * version, so the editor must save first.
+ */
+export const UnsavedChangesModal = ({ onClose }: { onClose: () => void }) => {
+  const { t } = useTranslation('byline-admin')
+  return (
+    <Modal isOpen={true} closeOnOverlayClick={true} onDismiss={onClose}>
+      <Modal.Container style={{ maxWidth: '460px' }}>
+        <Modal.Header className={cx('byline-form-guard-modal-head', styles['guard-modal-head'])}>
+          <h3 className={cx('byline-form-guard-modal-title', styles['guard-modal-title'])}>
+            {t('forms.unsavedChanges.title')}
+          </h3>
+        </Modal.Header>
+        <Modal.Content>
+          <p className={cx('byline-form-guard-modal-text', styles['guard-modal-text'])}>
+            {t('forms.unsavedChanges.message')}
+          </p>
+        </Modal.Content>
+        <Modal.Actions>
+          <Button
+            size="sm"
+            style={{ minWidth: '60px' }}
+            intent="primary"
+            type="button"
+            onClick={onClose}
+          >
+            {t('forms.unsavedChanges.okButton')}
+          </Button>
+        </Modal.Actions>
+      </Modal.Container>
+    </Modal>
+  )
+}
+
+/**
+ * Confirms an immediate, non-versioned write of the document-grain system
+ * fields (path / advertised locales) — which does NOT reset workflow status.
+ * When content is also dirty, the copy reassures that content edits still
+ * follow the normal revision + publish workflow. See docs/I18N.md.
+ */
+export const SystemFieldsConfirmModal = ({
+  contentDirty,
+  pathDirty,
+  availableLocalesDirty,
+  onCancel,
+  onConfirm,
+}: {
+  contentDirty: boolean
+  pathDirty: boolean
+  availableLocalesDirty: boolean
+  onCancel: () => void
+  onConfirm: () => void
+}) => {
+  const { t } = useTranslation('byline-admin')
+  return (
+    <Modal isOpen={true} closeOnOverlayClick={true} onDismiss={onCancel}>
+      <Modal.Container style={{ maxWidth: '520px' }}>
+        <Modal.Header className={cx('byline-form-guard-modal-head', styles['guard-modal-head'])}>
+          <h3 className={cx('byline-form-guard-modal-title', styles['guard-modal-title'])}>
+            {contentDirty
+              ? t('forms.systemFieldsConfirm.bothTitle')
+              : t('forms.systemFieldsConfirm.title')}
+          </h3>
+          <IconButton aria-label={t('common.actions.close')} size="xs" onClick={onCancel}>
+            <CloseIcon width="16px" height="16px" svgClassName="white-icon" />
+          </IconButton>
+        </Modal.Header>
+        <Modal.Content className="prose">
+          {/* Lead with reassurance: content edits follow the normal
+              revision + publish workflow. The immediate, document-level
+              system-field write is explained below the divider. */}
+          {contentDirty && (
+            <p className={cx('byline-form-system-fields-content-note', 'm-0 mt-2')}>
+              {t('forms.systemFieldsConfirm.contentNote')}
+            </p>
+          )}
+          <p
+            className="m-0 mt-2"
+            style={
+              contentDirty
+                ? {
+                    marginTop: 'var(--spacing-8)',
+                    paddingTop: 'var(--spacing-12)',
+                    borderTop: '1px solid var(--border-color)',
+                  }
+                : undefined
+            }
+          >
+            {t('forms.systemFieldsConfirm.intro')}
+          </p>
+          <ul className={cx('byline-form-system-fields-list', styles['guard-modal-text'], 'm-0')}>
+            {pathDirty && <li>{t('forms.systemFieldsConfirm.bulletPath')}</li>}
+            {availableLocalesDirty && <li>{t('forms.systemFieldsConfirm.bulletLocales')}</li>}
+          </ul>
+          <p
+            className={cx('byline-form-system-fields-effect', styles['guard-modal-text'])}
+            style={{
+              marginTop: 'var(--spacing-4)',
+              marginBottom: 0,
+              color: 'var(--text-subtle)',
+            }}
+          >
+            {t('forms.systemFieldsConfirm.effectLine')}
+          </p>
+        </Modal.Content>
+        <Modal.Actions>
+          <Button
+            size="sm"
+            style={{ minWidth: '80px' }}
+            intent="noeffect"
+            type="button"
+            onClick={onCancel}
+          >
+            {t('common.actions.cancel')}
+          </Button>
+          <Button
+            size="sm"
+            style={{ minWidth: '80px' }}
+            intent="primary"
+            type="button"
+            onClick={onConfirm}
+          >
+            {t('forms.systemFieldsConfirm.confirmButton')}
+          </Button>
+        </Modal.Actions>
+      </Modal.Container>
+    </Modal>
+  )
+}
+
+/**
+ * Blocks router navigation / browser unload while the form is dirty. Driven by
+ * the navigation-guard adapter's `isBlocked` state; `onStay` keeps the editor
+ * on the page, `onProceed` discards and continues.
+ */
+export const NavigationGuardModal = ({
+  onStay,
+  onProceed,
+}: {
+  onStay: () => void
+  onProceed: () => void
+}) => {
+  const { t } = useTranslation('byline-admin')
+  return (
+    <Modal isOpen={true} closeOnOverlayClick={false} onDismiss={onStay}>
+      <Modal.Container style={{ maxWidth: '460px' }}>
+        <Modal.Header className={cx('byline-form-guard-modal-head', styles['guard-modal-head'])}>
+          <h3 className={cx('byline-form-guard-modal-title', styles['guard-modal-title'])}>
+            {t('forms.navigationGuard.title')}
+          </h3>
+        </Modal.Header>
+        <Modal.Content>
+          <p className={cx('byline-form-guard-modal-text', styles['guard-modal-text'])}>
+            {t('forms.navigationGuard.message')}
+          </p>
+        </Modal.Content>
+        <Modal.Actions>
+          <Button size="sm" intent="noeffect" type="button" onClick={onStay}>
+            {t('forms.navigationGuard.stayButton')}
+          </Button>
+          <Button size="sm" intent="danger" type="button" onClick={onProceed}>
+            {t('forms.navigationGuard.leaveButton')}
+          </Button>
+        </Modal.Actions>
+      </Modal.Container>
+    </Modal>
+  )
+}