@byline/admin 3.2.1 → 3.3.0

package/dist/forms/form-context.d.ts

@@ -30,6 +30,23 @@ type MetaListener = () => void;
 type SystemPathListener = (value: string | null) => void;
 type SystemAvailableLocalesListener = (value: string[]) => void;
 type FieldUploadingListener = (uploading: boolean) => void;
+/**
+ * Why the form is dirty, partitioned by write semantics — drives the single
+ * Save button. `content` mints a new version (normal workflow). `direct-write`
+ * is an immediate, non-versioned write of the document-grain system fields
+ * (path / advertised locales) that does NOT reset workflow status. `both` does
+ * each through its own write path. See docs/I18N.md.
+ */
+export type DirtyReason = 'none' | 'content' | 'direct-write' | 'both';
+export interface DirtyBreakdown {
+    reason: DirtyReason;
+    /** Document field data / patches changed → versioned write. */
+    contentDirty: boolean;
+    /** Path widget changed → non-versioned direct write. */
+    pathDirty: boolean;
+    /** Available-locales widget changed → non-versioned direct write. */
+    availableLocalesDirty: boolean;
+}
 interface FormContextType {
     setFieldValue: (name: string, value: any) => void;
     setFieldStore: (name: string, value: any) => void;
@@ -48,6 +65,12 @@ interface FormContextType {
     setFieldError: (field: string, message: string) => void;
     clearFieldError: (field: string) => void;
     isDirty: (fieldName: string) => boolean;
+    /**
+     * Partition the current dirty state into content vs. system-field (path /
+     * advertised-locales) writes so the Save button can branch. See
+     * docs/I18N.md.
+     */
+    getDirtyBreakdown: () => DirtyBreakdown;
     subscribeField: (name: string, listener: FieldListener) => () => void;
     subscribeErrors: (listener: ErrorsListener) => () => void;
     subscribeMeta: (listener: MetaListener) => () => void;

package/dist/forms/form-context.js

@@ -13,6 +13,8 @@ const sameLocaleSet = (a, b)=>{
     ].sort();
     return sa.every((v, i)=>v === sb[i]);
 };
+const SYSTEM_PATH_DIRTY_KEY = '__systemPath__';
+const SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY = '__systemAvailableLocales__';
 const FormContext = /*#__PURE__*/ createContext(null);
 const useFormContext = ()=>{
     const context = useContext(FormContext);
@@ -159,11 +161,29 @@ const FormProvider = ({ children, initialData = {} })=>{
         notifyMetaListeners
     ]);
     const isDirty = useCallback((fieldName)=>dirtyFields.current.has(fieldName), []);
+    const getDirtyBreakdown = useCallback(()=>{
+        const keys = dirtyFields.current;
+        const pathDirty = keys.has(SYSTEM_PATH_DIRTY_KEY);
+        const availableLocalesDirty = keys.has(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY);
+        let contentDirty = false;
+        for (const key of keys)if (key !== SYSTEM_PATH_DIRTY_KEY && key !== SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY) {
+            contentDirty = true;
+            break;
+        }
+        const directWrite = pathDirty || availableLocalesDirty;
+        const reason = contentDirty && directWrite ? 'both' : contentDirty ? 'content' : directWrite ? 'direct-write' : 'none';
+        return {
+            reason,
+            contentDirty,
+            pathDirty,
+            availableLocalesDirty
+        };
+    }, []);
     const getSystemPath = useCallback(()=>systemPathRef.current, []);
     const setSystemPath = useCallback((value)=>{
         systemPathRef.current = value;
-        if (value !== initialSystemPath.current) dirtyFields.current.add('__systemPath__');
-        else dirtyFields.current.delete('__systemPath__');
+        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);
         });
@@ -183,8 +203,8 @@ const FormProvider = ({ children, initialData = {} })=>{
             ...value
         ];
         systemAvailableLocalesRef.current = next;
-        if (sameLocaleSet(next, initialSystemAvailableLocales.current)) dirtyFields.current.delete('__systemAvailableLocales__');
-        else dirtyFields.current.add('__systemAvailableLocales__');
+        if (sameLocaleSet(next, initialSystemAvailableLocales.current)) dirtyFields.current.delete(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY);
+        else dirtyFields.current.add(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY);
         systemAvailableLocalesListeners.current.forEach((listener)=>{
             listener(next);
         });
@@ -406,6 +426,7 @@ const FormProvider = ({ children, initialData = {} })=>{
             setFieldError,
             clearFieldError,
             isDirty,
+            getDirtyBreakdown,
             subscribeField,
             subscribeErrors,
             subscribeMeta,

package/dist/forms/form-renderer.d.ts

@@ -7,6 +7,7 @@
  */
 import { type ReactNode } from 'react';
 import type { CollectionAdminConfig, Field, WorkflowStatus } from '@byline/core';
+import type { DocumentPatch } from '@byline/core/patches';
 import { type DocumentActionsLocaleOption } from './document-actions';
 import type { UseNavigationGuard } from './navigation-guard';
 /** Metadata about a previously published version that is still live. */
@@ -17,6 +18,22 @@ export interface PublishedVersionInfo {
     createdAt: string | Date;
     updatedAt: string | Date;
 }
+/**
+ * Payload emitted by the form on Save. Carries the content (field data +
+ * patches) alongside the document-grain system fields (path / advertised
+ * locales) and per-bucket dirty flags so the host can route each piece to the
+ * right write path — versioned for content, immediate/non-versioned for the
+ * system fields. See docs/I18N.md.
+ */
+export interface SystemFieldsSubmitPayload {
+    data: any;
+    patches: DocumentPatch[];
+    contentDirty: boolean;
+    pathDirty: boolean;
+    systemPath?: string | null;
+    availableLocalesDirty: boolean;
+    systemAvailableLocales?: string[];
+}
 /** Props shared by both the public FormRenderer and its internal FormContent component. */
 export interface FormRendererProps {
     mode: 'create' | 'edit';

package/dist/forms/form-renderer.js

@@ -2,7 +2,7 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from "@byline/i18n/react";
-import { Alert, Button, ComboButton, Modal } from "@byline/ui/react";
+import { Alert, Button, CloseIcon, ComboButton, IconButton, Modal } from "@byline/ui/react";
 import classnames from "classnames";
 import { FieldRenderer } from "../fields/field-renderer.js";
 import { useBylineFieldServices } from "../fields/field-services-context.js";
@@ -141,13 +141,14 @@ function computeStatusTransitions(currentStatus, workflowStatuses, nextStatus) {
     };
 }
 const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, onDeleteLocale, contentLocales, nextStatus, workflowStatuses, publishedVersion, initialData, adminConfig, useAsTitle, useAsPath, advertiseLocales, headingLabel, headerSlot, collectionPath, initialLocale, onLocaleChange, defaultLocale = 'en', useNavigationGuard: useNavigationGuardProp, restoreWarnings, _activeTabBySet, _onTabChange })=>{
-    const { getFieldValues, runFieldHooks, validateForm, errors: initialErrors, hasChanges: hasChangesFn, resetHasChanges, getPatches, getSystemPath, getSystemAvailableLocales, subscribeErrors, subscribeMeta, setFieldValue, setFieldError, getPendingUploads, clearPendingUploads, setFieldUploading } = useFormContext();
+    const { getFieldValues, runFieldHooks, validateForm, errors: initialErrors, hasChanges: hasChangesFn, resetHasChanges, getPatches, getDirtyBreakdown, getSystemPath, getSystemAvailableLocales, subscribeErrors, subscribeMeta, setFieldValue, setFieldError, getPendingUploads, clearPendingUploads, setFieldUploading } = useFormContext();
     const { t } = useTranslation('byline-admin');
     const [errors, setErrors] = useState(initialErrors);
     const [hasChanges, setHasChanges] = useState(hasChangesFn());
     const [statusBusy, setStatusBusy] = useState(false);
     const [isUploading, setIsUploading] = useState(false);
     const [showUnsavedModal, setShowUnsavedModal] = useState(false);
+    const [pendingSystemFieldsSubmit, setPendingSystemFieldsSubmit] = useState(null);
     const [contentLocale, setContentLocale] = useState(initialLocale ?? defaultLocale);
     const { uploadField } = useBylineFieldServices();
     useEffect(()=>{
@@ -267,6 +268,15 @@ const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpub
     const handleCancel = ()=>{
         if (onCancel && 'function' == typeof onCancel) onCancel();
     };
+    const submitPayload = useCallback((payload)=>{
+        if (onSubmit && 'function' == typeof onSubmit) {
+            onSubmit(payload);
+            resetHasChanges();
+        }
+    }, [
+        onSubmit,
+        resetHasChanges
+    ]);
     const handleSubmit = (e)=>{
         e.preventDefault();
         (async ()=>{
@@ -303,17 +313,20 @@ const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpub
             }
             const data = getFieldValues();
             const patches = getPatches();
+            const { contentDirty, pathDirty, availableLocalesDirty, reason } = getDirtyBreakdown();
             const systemPath = getSystemPath();
             const systemAvailableLocales = advertiseLocales ? getSystemAvailableLocales() : void 0;
-            if (onSubmit && 'function' == typeof onSubmit) {
-                onSubmit({
-                    data,
-                    patches,
-                    systemPath,
-                    systemAvailableLocales
-                });
-                resetHasChanges();
-            }
+            const payload = {
+                data,
+                patches,
+                contentDirty,
+                pathDirty,
+                systemPath,
+                availableLocalesDirty,
+                systemAvailableLocales
+            };
+            if ('edit' === mode && ('direct-write' === reason || 'both' === reason)) return void setPendingSystemFieldsSubmit(payload);
+            submitPayload(payload);
         })();
     };
     const tabErrorCountsBySet = useMemo(()=>{
@@ -560,6 +573,103 @@ const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpub
                     ]
                 })
             }),
+            null != pendingSystemFieldsSubmit && /*#__PURE__*/ jsx(Modal, {
+                isOpen: true,
+                closeOnOverlayClick: true,
+                onDismiss: ()=>setPendingSystemFieldsSubmit(null),
+                children: /*#__PURE__*/ jsxs(Modal.Container, {
+                    style: {
+                        maxWidth: '520px'
+                    },
+                    children: [
+                        /*#__PURE__*/ jsxs(Modal.Header, {
+                            className: classnames('byline-form-guard-modal-head', form_renderer_module["guard-modal-head"]),
+                            children: [
+                                /*#__PURE__*/ jsx("h3", {
+                                    className: classnames('byline-form-guard-modal-title', form_renderer_module["guard-modal-title"]),
+                                    children: pendingSystemFieldsSubmit.contentDirty ? t('forms.systemFieldsConfirm.bothTitle') : t('forms.systemFieldsConfirm.title')
+                                }),
+                                /*#__PURE__*/ jsx(IconButton, {
+                                    "aria-label": t('common.actions.close'),
+                                    size: "xs",
+                                    onClick: ()=>setPendingSystemFieldsSubmit(null),
+                                    children: /*#__PURE__*/ jsx(CloseIcon, {
+                                        width: "16px",
+                                        height: "16px",
+                                        svgClassName: "white-icon"
+                                    })
+                                })
+                            ]
+                        }),
+                        /*#__PURE__*/ jsxs(Modal.Content, {
+                            className: "prose",
+                            children: [
+                                pendingSystemFieldsSubmit.contentDirty && /*#__PURE__*/ jsx("p", {
+                                    className: classnames('byline-form-system-fields-content-note', 'm-0'),
+                                    children: t('forms.systemFieldsConfirm.contentNote')
+                                }),
+                                /*#__PURE__*/ jsx("p", {
+                                    className: "m-0",
+                                    style: pendingSystemFieldsSubmit.contentDirty ? {
+                                        marginTop: 'var(--spacing-8)',
+                                        paddingTop: 'var(--spacing-12)',
+                                        borderTop: '1px solid var(--border-color)'
+                                    } : void 0,
+                                    children: t('forms.systemFieldsConfirm.intro')
+                                }),
+                                /*#__PURE__*/ jsxs("ul", {
+                                    className: classnames('byline-form-system-fields-list', form_renderer_module["guard-modal-text"]),
+                                    children: [
+                                        pendingSystemFieldsSubmit.pathDirty && /*#__PURE__*/ jsx("li", {
+                                            children: t('forms.systemFieldsConfirm.bulletPath')
+                                        }),
+                                        pendingSystemFieldsSubmit.availableLocalesDirty && /*#__PURE__*/ jsx("li", {
+                                            children: t('forms.systemFieldsConfirm.bulletLocales')
+                                        })
+                                    ]
+                                }),
+                                /*#__PURE__*/ jsx("p", {
+                                    className: classnames('byline-form-system-fields-effect', form_renderer_module["guard-modal-text"]),
+                                    style: {
+                                        marginTop: 'var(--spacing-4)',
+                                        marginBottom: 0,
+                                        color: 'var(--text-subtle)'
+                                    },
+                                    children: t('forms.systemFieldsConfirm.effectLine')
+                                })
+                            ]
+                        }),
+                        /*#__PURE__*/ jsxs(Modal.Actions, {
+                            children: [
+                                /*#__PURE__*/ jsx(Button, {
+                                    size: "sm",
+                                    style: {
+                                        minWidth: '80px'
+                                    },
+                                    intent: "noeffect",
+                                    type: "button",
+                                    onClick: ()=>setPendingSystemFieldsSubmit(null),
+                                    children: t('common.actions.cancel')
+                                }),
+                                /*#__PURE__*/ jsx(Button, {
+                                    size: "sm",
+                                    style: {
+                                        minWidth: '80px'
+                                    },
+                                    intent: "primary",
+                                    type: "button",
+                                    onClick: ()=>{
+                                        const payload = pendingSystemFieldsSubmit;
+                                        setPendingSystemFieldsSubmit(null);
+                                        submitPayload(payload);
+                                    },
+                                    children: t('forms.systemFieldsConfirm.confirmButton')
+                                })
+                            ]
+                        })
+                    ]
+                })
+            }),
             guard.isBlocked && /*#__PURE__*/ jsx(Modal, {
                 isOpen: true,
                 closeOnOverlayClick: false,

package/dist/modules/admin-permissions/schemas.d.ts

@@ -27,10 +27,10 @@ export declare const abilityDescriptorResponseSchema: z.ZodObject<{
     description: z.ZodNullable<z.ZodString>;
     group: z.ZodString;
     source: z.ZodNullable<z.ZodEnum<{
-        admin: "admin";
         collection: "collection";
         plugin: "plugin";
         core: "core";
+        admin: "admin";
     }>>;
 }, z.core.$strip>;
 export type AbilityDescriptorResponse = z.infer<typeof abilityDescriptorResponseSchema>;
@@ -42,10 +42,10 @@ export declare const abilityGroupResponseSchema: z.ZodObject<{
         description: z.ZodNullable<z.ZodString>;
         group: z.ZodString;
         source: z.ZodNullable<z.ZodEnum<{
-            admin: "admin";
             collection: "collection";
             plugin: "plugin";
             core: "core";
+            admin: "admin";
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -61,10 +61,10 @@ export declare const listRegisteredAbilitiesResponseSchema: z.ZodObject<{
         description: z.ZodNullable<z.ZodString>;
         group: z.ZodString;
         source: z.ZodNullable<z.ZodEnum<{
-            admin: "admin";
             collection: "collection";
             plugin: "plugin";
             core: "core";
+            admin: "admin";
         }>>;
     }, z.core.$strip>>;
     groups: z.ZodArray<z.ZodObject<{
@@ -75,10 +75,10 @@ export declare const listRegisteredAbilitiesResponseSchema: z.ZodObject<{
             description: z.ZodNullable<z.ZodString>;
             group: z.ZodString;
             source: z.ZodNullable<z.ZodEnum<{
-                admin: "admin";
                 collection: "collection";
                 plugin: "plugin";
                 core: "core";
+                admin: "admin";
             }>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;

package/package.json

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

package/src/forms/form-context.tsx

@@ -58,6 +58,29 @@ const sameLocaleSet = (a: string[], b: string[]): boolean => {
   return sa.every((v, i) => v === sb[i])
 }
 
+/**
+ * Why the form is dirty, partitioned by write semantics — drives the single
+ * Save button. `content` mints a new version (normal workflow). `direct-write`
+ * is an immediate, non-versioned write of the document-grain system fields
+ * (path / advertised locales) that does NOT reset workflow status. `both` does
+ * each through its own write path. See docs/I18N.md.
+ */
+export type DirtyReason = 'none' | 'content' | 'direct-write' | 'both'
+
+export interface DirtyBreakdown {
+  reason: DirtyReason
+  /** Document field data / patches changed → versioned write. */
+  contentDirty: boolean
+  /** Path widget changed → non-versioned direct write. */
+  pathDirty: boolean
+  /** Available-locales widget changed → non-versioned direct write. */
+  availableLocalesDirty: boolean
+}
+
+/** Dirty-tracking keys for the two system-managed, document-grain slots. */
+const SYSTEM_PATH_DIRTY_KEY = '__systemPath__'
+const SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY = '__systemAvailableLocales__'
+
 interface FormContextType {
   setFieldValue: (name: string, value: any) => void
   setFieldStore: (name: string, value: any) => void
@@ -76,6 +99,12 @@ interface FormContextType {
   setFieldError: (field: string, message: string) => void
   clearFieldError: (field: string) => void
   isDirty: (fieldName: string) => boolean
+  /**
+   * Partition the current dirty state into content vs. system-field (path /
+   * advertised-locales) writes so the Save button can branch. See
+   * docs/I18N.md.
+   */
+  getDirtyBreakdown: () => DirtyBreakdown
   subscribeField: (name: string, listener: FieldListener) => () => void
   subscribeErrors: (listener: ErrorsListener) => () => void
   subscribeMeta: (listener: MetaListener) => () => void
@@ -310,6 +339,34 @@ export const FormProvider = ({
     return dirtyFields.current.has(fieldName)
   }, [])
 
+  // Partition the current dirty set by write semantics so the single Save
+  // button can route each piece correctly: content → versioned write; the
+  // document-grain system fields (path / advertised locales) → immediate,
+  // non-versioned direct write that leaves workflow status untouched.
+  // See docs/I18N.md.
+  const getDirtyBreakdown = useCallback((): DirtyBreakdown => {
+    const keys = dirtyFields.current
+    const pathDirty = keys.has(SYSTEM_PATH_DIRTY_KEY)
+    const availableLocalesDirty = keys.has(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY)
+    let contentDirty = false
+    for (const key of keys) {
+      if (key !== SYSTEM_PATH_DIRTY_KEY && key !== SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY) {
+        contentDirty = true
+        break
+      }
+    }
+    const directWrite = pathDirty || availableLocalesDirty
+    const reason: DirtyReason =
+      contentDirty && directWrite
+        ? 'both'
+        : contentDirty
+          ? 'content'
+          : directWrite
+            ? 'direct-write'
+            : 'none'
+    return { reason, contentDirty, pathDirty, availableLocalesDirty }
+  }, [])
+
   // -------------------------------------------------------------------------
   // System path slot
   // -------------------------------------------------------------------------
@@ -320,9 +377,9 @@ export const FormProvider = ({
     (value: string | null) => {
       systemPathRef.current = value
       if (value !== initialSystemPath.current) {
-        dirtyFields.current.add('__systemPath__')
+        dirtyFields.current.add(SYSTEM_PATH_DIRTY_KEY)
       } else {
-        dirtyFields.current.delete('__systemPath__')
+        dirtyFields.current.delete(SYSTEM_PATH_DIRTY_KEY)
       }
       systemPathListeners.current.forEach((listener) => {
         listener(value)
@@ -350,9 +407,9 @@ export const FormProvider = ({
       const next = [...value]
       systemAvailableLocalesRef.current = next
       if (!sameLocaleSet(next, initialSystemAvailableLocales.current)) {
-        dirtyFields.current.add('__systemAvailableLocales__')
+        dirtyFields.current.add(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY)
       } else {
-        dirtyFields.current.delete('__systemAvailableLocales__')
+        dirtyFields.current.delete(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY)
       }
       systemAvailableLocalesListeners.current.forEach((listener) => {
         listener(next)
@@ -646,6 +703,7 @@ export const FormProvider = ({
         setFieldError,
         clearFieldError,
         isDirty,
+        getDirtyBreakdown,
         subscribeField,
         subscribeErrors,
         subscribeMeta,

package/src/forms/form-renderer.tsx

@@ -18,8 +18,9 @@ import type {
   TabSetDefinition,
   WorkflowStatus,
 } from '@byline/core'
+import type { DocumentPatch } from '@byline/core/patches'
 import { useTranslation } from '@byline/i18n/react'
-import { Alert, Button, ComboButton, Modal } from '@byline/ui/react'
+import { Alert, Button, CloseIcon, ComboButton, IconButton, Modal } from '@byline/ui/react'
 import cx from 'classnames'
 
 import { FieldRenderer } from '../fields/field-renderer'
@@ -46,6 +47,24 @@ export interface PublishedVersionInfo {
   updatedAt: string | Date
 }
 
+/**
+ * Payload emitted by the form on Save. Carries the content (field data +
+ * patches) alongside the document-grain system fields (path / advertised
+ * locales) and per-bucket dirty flags so the host can route each piece to the
+ * right write path — versioned for content, immediate/non-versioned for the
+ * system fields. See docs/I18N.md.
+ */
+export interface SystemFieldsSubmitPayload {
+  // biome-ignore lint/suspicious/noExplicitAny: data is collection-specific
+  data: any
+  patches: DocumentPatch[]
+  contentDirty: boolean
+  pathDirty: boolean
+  systemPath?: string | null
+  availableLocalesDirty: boolean
+  systemAvailableLocales?: string[]
+}
+
 /** Props shared by both the public FormRenderer and its internal FormContent component. */
 export interface FormRendererProps {
   mode: 'create' | 'edit'
@@ -340,6 +359,7 @@ const FormContent = ({
     hasChanges: hasChangesFn,
     resetHasChanges,
     getPatches,
+    getDirtyBreakdown,
     getSystemPath,
     getSystemAvailableLocales,
     subscribeErrors,
@@ -361,6 +381,11 @@ const FormContent = ({
   // is dirty — those actions operate on the saved version, so unsaved edits
   // would be silently excluded.
   const [showUnsavedModal, setShowUnsavedModal] = useState(false)
+  // Holds the pending Save payload while the editor confirms an immediate,
+  // non-versioned system-field write (path / advertised locales). Non-null
+  // means the confirmation modal is open. See docs/I18N.md.
+  const [pendingSystemFieldsSubmit, setPendingSystemFieldsSubmit] =
+    useState<SystemFieldsSubmitPayload | null>(null)
   const [contentLocale, setContentLocale] = useState(initialLocale ?? defaultLocale)
   const { uploadField } = useBylineFieldServices()
 
@@ -528,6 +553,18 @@ const FormContent = ({
     }
   }
 
+  // Emit the payload and optimistically clear dirty state (parity with the
+  // prior submit behaviour — the host surfaces failures via toast).
+  const submitPayload = useCallback(
+    (payload: SystemFieldsSubmitPayload) => {
+      if (onSubmit && typeof onSubmit === 'function') {
+        onSubmit(payload)
+        resetHasChanges()
+      }
+    },
+    [onSubmit, resetHasChanges]
+  )
+
   const handleSubmit = (e: React.SubmitEvent<HTMLFormElement>) => {
     e.preventDefault()
 
@@ -583,16 +620,33 @@ const FormContent = ({
 
       const data = getFieldValues()
       const patches = getPatches()
+      const { contentDirty, pathDirty, availableLocalesDirty, reason } = getDirtyBreakdown()
       const systemPath = getSystemPath()
       // Only emit the advertised-locale set for collections that opted into the
       // widget — otherwise leave it undefined so the write path never touches
       // `byline_document_available_locales` for non-advertising collections.
       const systemAvailableLocales = advertiseLocales ? getSystemAvailableLocales() : undefined
 
-      if (onSubmit && typeof onSubmit === 'function') {
-        onSubmit({ data, patches, systemPath, systemAvailableLocales })
-        resetHasChanges()
+      const payload: SystemFieldsSubmitPayload = {
+        data,
+        patches,
+        contentDirty,
+        pathDirty,
+        systemPath,
+        availableLocalesDirty,
+        systemAvailableLocales,
       }
+
+      // Editing the document-grain system fields (path / advertised locales) is
+      // an immediate, non-versioned write that does NOT reset workflow status,
+      // so confirm it before saving. Create mode writes everything as part of
+      // the initial version, so no confirmation applies there.
+      if (mode === 'edit' && (reason === 'direct-write' || reason === 'both')) {
+        setPendingSystemFieldsSubmit(payload)
+        return
+      }
+
+      submitPayload(payload)
     })()
   }
 
@@ -875,6 +929,98 @@ const FormContent = ({
           </Modal.Container>
         </Modal>
       )}
+      {pendingSystemFieldsSubmit != null && (
+        <Modal
+          isOpen={true}
+          closeOnOverlayClick={true}
+          onDismiss={() => setPendingSystemFieldsSubmit(null)}
+        >
+          <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'])}>
+                {pendingSystemFieldsSubmit.contentDirty
+                  ? t('forms.systemFieldsConfirm.bothTitle')
+                  : t('forms.systemFieldsConfirm.title')}
+              </h3>
+              <IconButton
+                aria-label={t('common.actions.close')}
+                size="xs"
+                onClick={() => setPendingSystemFieldsSubmit(null)}
+              >
+                <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. */}
+              {pendingSystemFieldsSubmit.contentDirty && (
+                <p className={cx('byline-form-system-fields-content-note', 'm-0')}>
+                  {t('forms.systemFieldsConfirm.contentNote')}
+                </p>
+              )}
+              <p
+                className="m-0"
+                style={
+                  pendingSystemFieldsSubmit.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'])}>
+                {pendingSystemFieldsSubmit.pathDirty && (
+                  <li>{t('forms.systemFieldsConfirm.bulletPath')}</li>
+                )}
+                {pendingSystemFieldsSubmit.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={() => setPendingSystemFieldsSubmit(null)}
+              >
+                {t('common.actions.cancel')}
+              </Button>
+              <Button
+                size="sm"
+                style={{ minWidth: '80px' }}
+                intent="primary"
+                type="button"
+                onClick={() => {
+                  const payload = pendingSystemFieldsSubmit
+                  setPendingSystemFieldsSubmit(null)
+                  submitPayload(payload)
+                }}
+              >
+                {t('forms.systemFieldsConfirm.confirmButton')}
+              </Button>
+            </Modal.Actions>
+          </Modal.Container>
+        </Modal>
+      )}
       {guard.isBlocked && (
         <Modal isOpen={true} closeOnOverlayClick={false} onDismiss={guard.stay}>
           <Modal.Container style={{ maxWidth: '460px' }}>