@byline/admin 6.6.0 → 6.7.1

package/dist/modules/auth/safe-redirect.test.node.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeRootRelativeRedirect, resolveSignInFormRedirect } from './safe-redirect.js';
+describe('normalizeRootRelativeRedirect', () => {
+    it.each([
+        ['/cms', '/cms'],
+        ['/cms/account?tab=profile#name', '/cms/account?tab=profile#name'],
+    ])('accepts %j', (value, expected) => {
+        expect(normalizeRootRelativeRedirect(value)).toBe(expected);
+    });
+    it.each([
+        '',
+        ' /cms',
+        'https://evil.test',
+        '//evil.test',
+        '/\\evil.test',
+        '/cms\\account',
+        '/cms\naccount',
+        '%2Fcms',
+        '/%2F%2Fevil.test',
+        '/cms/%5cevil.test',
+        '/cms/%2e/account',
+        '/cms/../account',
+        '/cms/./account',
+        '/cms\u0085account',
+    ])('rejects %j', (value) => {
+        expect(normalizeRootRelativeRedirect(value)).toBeUndefined();
+    });
+});
+describe('resolveSignInFormRedirect', () => {
+    it('uses a safe redirectTo without evaluating the fallback', () => {
+        expect(resolveSignInFormRedirect('/cms/account', '/cms')).toBe('/cms/account');
+        expect(resolveSignInFormRedirect('/cms/account', () => {
+            throw new Error('fallback must be lazy');
+        })).toBe('/cms/account');
+    });
+    it('uses the safe configured fallback without permitting an open redirect', () => {
+        expect(resolveSignInFormRedirect('//evil.test', '/cms')).toBe('/cms');
+        expect(resolveSignInFormRedirect(undefined, 'https://evil.test')).toBe('/');
+    });
+});

package/dist/modules/auth/sign-in-form-props.test.node.js

@@ -0,0 +1,7 @@
+import { describe, expectTypeOf, it } from 'vitest';
+describe('SignInFormProps', () => {
+    it('accepts redirectTo and no destination prop', () => {
+        expectTypeOf().toMatchTypeOf();
+        expectTypeOf().toMatchTypeOf();
+    });
+});

package/dist/presentation/group.jsx

@@ -0,0 +1,26 @@
+/**
+ * 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 cx from 'clsx';
+import styles from './group.module.css';
+/**
+ * Labelled fieldset clustering related fields together.
+ *
+ * Used by `FormRenderer` when a `CollectionAdminConfig` declares a `groups`
+ * primitive. Renders a bordered, padded `<fieldset>` with an optional
+ * `<legend>` for the label.
+ *
+ * Stable override handles: `.byline-admin-group` on the fieldset and
+ * `.byline-admin-group-legend` on the legend (alongside the hashed
+ * CSS-modules locals).
+ */
+export const AdminGroup = ({ label, children, className }) => {
+    return (<fieldset className={cx('byline-admin-group', styles.group, className)}>
+      {label && <legend className={cx('byline-admin-group-legend', styles.legend)}>{label}</legend>}
+      {children}
+    </fieldset>);
+};

package/dist/presentation/row.jsx

@@ -0,0 +1,23 @@
+/**
+ * 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 cx from 'clsx';
+import styles from './row.module.css';
+/**
+ * Horizontal flex-row layout for admin form fields.
+ *
+ * Used by `FormRenderer` when a `CollectionAdminConfig` declares a `rows`
+ * primitive. Members are rendered side-by-side above the `sm` breakpoint
+ * and stack vertically below it. `flex-1` + `min-width: 0` lets two text
+ * inputs share the row evenly without overflowing.
+ *
+ * The element carries `.byline-admin-row` as a stable global class for
+ * host overrides (alongside the hashed CSS-modules local).
+ */
+export const AdminRow = ({ children, className }) => {
+    return <div className={cx('byline-admin-row', styles.row, className)}>{children}</div>;
+};

package/dist/presentation/tabs.jsx

@@ -0,0 +1,39 @@
+'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 { Badge } from '@byline/ui/react';
+import cx from 'clsx';
+import styles from './tabs.module.css';
+/**
+ * Tabs navigation bar for admin form layouts.
+ *
+ * Used by FormRenderer when a CollectionAdminConfig declares a `tabs` array.
+ * Each tab is a simple button with a bottom-border active indicator.
+ * Inactive tabs show a subtle hover state. Fully dark-mode aware.
+ *
+ * Stable override handles: `.byline-admin-tabs`, `.byline-admin-tab`,
+ * `.byline-admin-tab-active`, `.byline-admin-tab-label`,
+ * `.byline-admin-tab-badge`.
+ */
+export const AdminTabs = ({ tabs, activeTab, onChange, errorCounts, className, }) => {
+    const { t } = useTranslation('byline-admin');
+    return (<div role="tablist" aria-label={t('presentation.formTabsAriaLabel')} className={cx('byline-admin-tabs', styles.tabs, className)}>
+      {tabs.map((tab) => {
+            const isActive = tab.name === activeTab;
+            return (<button key={tab.name} type="button" role="tab" aria-selected={isActive} onClick={() => onChange(tab.name)} className={cx('byline-admin-tab', styles.tab, isActive && ['byline-admin-tab-active', styles['tab-active']])}>
+            <span className={cx('byline-admin-tab-label', styles.label)}>
+              {tab.label}
+              {(errorCounts?.[tab.name] ?? 0) > 0 && (<Badge intent="danger" className={cx('byline-admin-tab-badge', styles.badge)}>
+                  {errorCounts?.[tab.name]}
+                </Badge>)}
+            </span>
+          </button>);
+        })}
+    </div>);
+};

package/dist/services/admin-services-context.jsx

@@ -0,0 +1,17 @@
+/**
+ * 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 { createContext, useContext } from 'react';
+const AdminServicesContext = createContext(null);
+export const BylineAdminServicesProvider = ({ services, children, }) => (<AdminServicesContext.Provider value={services}>{children}</AdminServicesContext.Provider>);
+export const useBylineAdminServices = () => {
+    const ctx = useContext(AdminServicesContext);
+    if (!ctx) {
+        throw new Error('@byline/admin: BylineAdminServicesProvider missing. Wrap your admin tree with <BylineAdminServicesProvider services={…} />.');
+    }
+    return ctx;
+};

package/dist/widgets/diff-viewer/diff-modal.jsx

@@ -0,0 +1,110 @@
+'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 { useEffect, useState } from 'react';
+import { useTranslation } from '@byline/i18n/react';
+import { CloseIcon, IconButton, LoaderRing, Modal } from '@byline/ui/react';
+import cx from 'clsx';
+import ReactDiffViewer, { DiffMethod } from 'react-diff-viewer-continued';
+import styles from './diff-modal.module.css';
+// Keys that are per-version metadata rather than content — strip before diffing
+// so the diff focuses on meaningful content changes. ClientDocument-shape
+// metadata keys after the Phase 7 admin migration.
+const STRIP_KEYS = new Set([
+    'id',
+    'versionId',
+    'path',
+    'status',
+    'createdAt',
+    'updatedAt',
+    'hasPublishedVersion',
+    '_publishedVersion',
+]);
+function stripMeta(doc) {
+    // With the nested document shape, extract just the fields for diffing.
+    if (doc.fields && typeof doc.fields === 'object') {
+        return doc.fields;
+    }
+    return Object.fromEntries(Object.entries(doc).filter(([k]) => !STRIP_KEYS.has(k)));
+}
+export function DiffModal({ isOpen, onDismiss, collection, documentId, versionId, versionLabel, currentDocument, locale, loadHistoricalVersion, }) {
+    const { t } = useTranslation('byline-admin');
+    const [historicalDoc, setHistoricalDoc] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!isOpen || !versionId)
+            return;
+        let cancelled = false;
+        setLoading(true);
+        setError(null);
+        setHistoricalDoc(null);
+        loadHistoricalVersion(collection, documentId, versionId, locale)
+            .then((doc) => {
+            if (cancelled)
+                return;
+            setHistoricalDoc(doc);
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            setError(err instanceof Error ? err.message : t('diffModal.loadFailed'));
+        })
+            .finally(() => {
+            if (!cancelled)
+                setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [isOpen, collection, documentId, versionId, locale, loadHistoricalVersion, t]);
+    const currentStr = currentDocument ? JSON.stringify(stripMeta(currentDocument), null, 2) : '';
+    const historicalStr = historicalDoc ? JSON.stringify(stripMeta(historicalDoc), null, 2) : '';
+    return (<Modal isOpen={isOpen} closeOnOverlayClick={true} onDismiss={onDismiss}>
+      <Modal.Container style={{
+            width: '96vw',
+            maxWidth: '96vw',
+            height: '90vh',
+            maxHeight: '90vh',
+            display: 'flex',
+            flexDirection: 'column',
+            overflow: 'hidden',
+        }}>
+        <Modal.Header className={cx('byline-diff-modal-header', styles.header)}>
+          <div className={cx('byline-diff-modal-title-stack', styles['title-stack'])}>
+            <h3 className={cx('byline-diff-modal-title', styles.title)}>{t('diffModal.title')}</h3>
+            <p className={cx('byline-diff-modal-subtitle', styles.subtitle)}>
+              {t('diffModal.subtitleBefore')}{' '}
+              <span className={cx('byline-diff-modal-version', styles.version)}>
+                {versionLabel}
+              </span>{' '}
+              {t('diffModal.subtitleAfter')}
+            </p>
+          </div>
+          <IconButton onClick={onDismiss} size="xs" aria-label={t('diffModal.closeAriaLabel')}>
+            <CloseIcon width="15px" height="15px"/>
+          </IconButton>
+        </Modal.Header>
+
+        <Modal.Content className={cx('byline-diff-modal-content', styles.content)} style={{ minHeight: 0 }}>
+          {loading && (<div className={cx('byline-diff-modal-state', styles.state)}>
+              <LoaderRing size={28} color="#666666"/>
+              <span>{t('diffModal.loading')}</span>
+            </div>)}
+
+          {error && (<div className={cx('byline-diff-modal-state', 'byline-diff-modal-error', styles.state, styles.error)}>
+              {error}
+            </div>)}
+
+          {!loading && !error && historicalDoc && (<div className={cx('byline-diff-modal-viewer', styles.viewer)}>
+              <ReactDiffViewer oldValue={historicalStr} newValue={currentStr} splitView={true} compareMethod={DiffMethod.LINES} useDarkTheme={true} leftTitle={versionLabel} rightTitle={t('diffModal.currentVersion')} hideLineNumbers={false}/>
+            </div>)}
+        </Modal.Content>
+      </Modal.Container>
+    </Modal>);
+}

package/dist/widgets/source-locale-badge/source-locale-badge.jsx

@@ -0,0 +1,28 @@
+/**
+ * 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 { Badge } from '@byline/ui/react';
+import cx from 'clsx';
+import styles from './source-locale-badge.module.css';
+/**
+ * Small neutral badge indicating a document's content **source locale** — the
+ * locale it was authored in (its anchor: fallback floor, path locale,
+ * completeness yardstick). Rendered next to the document title in the edit and
+ * list views. Mirrors the localized-field {@link LocaleBadge} in spirit but uses
+ * the shared {@link Badge} with the `noeffect` (neutral) intent.
+ *
+ * NOTE: currently rendered for *every* document so the anchor is visible during
+ * development. The intended end state is to show it only when `locale` differs
+ * from the system's current default content locale (a normal single-default
+ * install then shows nothing). See docs/08-internationalization/index.md.
+ *
+ * Stable override handle: `.byline-source-locale-badge`.
+ */
+export const SourceLocaleBadge = ({ locale, className }) => (<Badge intent="noeffect" render={<span />} title={`Primary content language: ${locale.toUpperCase()}`} className={cx('byline-source-locale-badge', styles.badge, className)}>
+    {locale.toUpperCase()}
+  </Badge>);
+SourceLocaleBadge.displayName = 'SourceLocaleBadge';

package/dist/widgets/status-badge/status-badge.jsx

@@ -0,0 +1,46 @@
+/**
+ * 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 { WORKFLOW_STATUS_ARCHIVED, WORKFLOW_STATUS_DRAFT, WORKFLOW_STATUS_PUBLISHED, } from '@byline/core';
+import { useTranslation } from '@byline/i18n/react';
+import { Badge } from '@byline/ui/react';
+import cx from 'clsx';
+import styles from './status-badge.module.css';
+function statusIntent(status) {
+    switch (status) {
+        case WORKFLOW_STATUS_PUBLISHED:
+            return 'success';
+        case WORKFLOW_STATUS_DRAFT:
+            return 'warning';
+        case WORKFLOW_STATUS_ARCHIVED:
+            return 'info';
+        default:
+            return 'noeffect';
+    }
+}
+/**
+ * Compact badge for workflow status values. Maps the three built-in
+ * statuses (draft, published, archived) to semantic intents and falls
+ * back to `noeffect` for any custom workflow statuses.
+ *
+ * When `hasPublishedVersion` is true and the current status is not
+ * `published`, a small green dot is rendered before the badge to
+ * indicate that a published version is live.
+ *
+ * Stable override handles: `.byline-status-badge-wrap`,
+ * `.byline-status-badge-dot`, `.byline-status-badge`.
+ */
+export const StatusBadge = ({ status, workflowStatuses, hasPublishedVersion, }) => {
+    const { t } = useTranslation('byline-admin');
+    const label = workflowStatuses.find((s) => s.name === status)?.label ?? String(status ?? '');
+    return (<span className={cx('byline-status-badge-wrap', styles.wrap)}>
+      {hasPublishedVersion === true && status !== 'published' && (<span title={t('statusBadge.publishedVersionLive')} className={cx('byline-status-badge-dot', styles.dot)}/>)}
+      <Badge intent={statusIntent(status)} className={cx('byline-status-badge', styles.badge)}>
+        {label}
+      </Badge>
+    </span>);
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.6.0",
+  "version": "6.7.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -183,12 +183,12 @@
     "react-diff-viewer-continued": "^4.4.0",
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
-    "@byline/analytics": "6.6.0",
-    "@byline/i18n": "6.6.0",
-    "@byline/core": "6.6.0",
-    "@byline/auth": "6.6.0",
-    "@byline/analytics-agent": "6.6.0",
-    "@byline/ui": "6.6.0"
+    "@byline/analytics": "6.7.1",
+    "@byline/auth": "6.7.1",
+    "@byline/core": "6.7.1",
+    "@byline/analytics-agent": "6.7.1",
+    "@byline/i18n": "6.7.1",
+    "@byline/ui": "6.7.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/forms/available-locales-widget.tsx

@@ -11,7 +11,7 @@
 import { useCallback, useMemo } from 'react'
 
 import { useTranslation } from '@byline/i18n/react'
-import { Checkbox, Label } from '@byline/ui/react'
+import { Checkbox, HelpText, Label } from '@byline/ui/react'
 import cx from 'clsx'
 
 import { reconcileLocaleState } from './available-locales-reconcile'
@@ -36,6 +36,12 @@ export interface AvailableLocalesWidgetProps {
    * surface supplies it (Slice 6) — in which case every row renders neutral.
    */
   availableVersionLocales: readonly string[]
+  /**
+   * The document's source language. Its row explains that the source stays
+   * available while published whether or not it is checked; the checkbox only
+   * controls whether it is advertised.
+   */
+  sourceLocale?: string
 }
 
 /**
@@ -54,6 +60,7 @@ export const AvailableLocalesWidget = ({
   disabled: mutationsBlocked = false,
   contentLocales,
   availableVersionLocales,
+  sourceLocale,
 }: AvailableLocalesWidgetProps) => {
   const { t } = useTranslation('byline-admin')
   const { setSystemAvailableLocales } = useFormContext()
@@ -107,10 +114,17 @@ export const AvailableLocalesWidget = ({
               checked={checked}
               disabled={mutationsBlocked || disabled}
               onCheckedChange={(value) => toggle(code, value === true)}
+              helpText={
+                code === sourceLocale ? t('availableLocalesWidget.sourceRowHint') : undefined
+              }
             />
           )
         })}
       </div>
+      <HelpText
+        className="byline-form-available-locales-hint"
+        text={t('availableLocalesWidget.hint')}
+      />
       <span
         id="available-locales-description"
         className={cx('byline-form-available-locales-sr-only', styles['sr-only'])}

package/src/forms/form-context.tsx

@@ -73,8 +73,9 @@ const sameLocaleSet = (a: string[], b: string[]): boolean => {
  * 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/08-internationalization/index.md.
+ * (path / advertised locales) that does NOT reset workflow status. `both`
+ * saves the two together: one request, one guarded transaction, so both commit
+ * or neither does. See docs/08-internationalization/03-content-locales.md.
  */
 export type DirtyReason = 'none' | 'content' | 'direct-write' | 'both'
 

package/src/forms/form-modals.tsx

@@ -54,7 +54,11 @@ export const UnsavedChangesModal = ({ onClose }: { onClose: () => void }) => {
  * 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/08-internationalization/index.md.
+ * follow the normal revision + publish workflow, and, for a locale change,
+ * explains that locale and content changes commit together (one guarded
+ * transaction, so a failed save applies neither), that an already-published
+ * checked translation becomes public once saved, and that a draft-only
+ * translation stays withheld until it is published. See docs/08-internationalization/index.md.
  */
 export const SystemFieldsConfirmModal = ({
   contentDirty,
@@ -92,6 +96,13 @@ export const SystemFieldsConfirmModal = ({
               {t('forms.systemFieldsConfirm.contentNote')}
             </p>
           )}
+          {/* Locale and content changes commit together. Say what the locale
+              change does to public delivery once the save succeeds. */}
+          {contentDirty && availableLocalesDirty && (
+            <p className={cx('byline-form-system-fields-locales-note', 'm-0 mt-2')}>
+              {t('forms.systemFieldsConfirm.localesContentNote')}
+            </p>
+          )}
           <p
             className="m-0 mt-2"
             style={

package/src/forms/form-page-chrome.tsx

@@ -437,6 +437,7 @@ export const FormSidebarWidgets = ({
         availableVersionLocales={
           (initialData?._availableVersionLocales as string[] | undefined) ?? []
         }
+        sourceLocale={(initialData?.sourceLocale as string | undefined) ?? defaultLocale}
       />
     )}
   </>

package/src/forms/locale-visibility-copy.test.tsx

@@ -0,0 +1,180 @@
+/**
+ * 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
+ */
+
+/**
+ * The advertised-locales widget and the immediate-save confirmation explain
+ * what a checkbox does to public delivery. Rendered with the real English
+ * admin bundle, so a renamed or deleted key fails here rather than showing a
+ * raw key to an editor.
+ */
+
+import { act, type ReactNode } from 'react'
+
+import { adminTranslations } from '@byline/i18n/admin'
+import { I18nProvider } from '@byline/i18n/react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@byline/ui/react', () => {
+  const Modal = ({ children }: { children?: ReactNode }) => <div>{children}</div>
+  const Part = ({ children }: { children?: ReactNode }) => <div>{children}</div>
+  Modal.Container = Part
+  Modal.Header = Part
+  Modal.Content = Part
+  Modal.Actions = Part
+  return {
+    Label: ({ label }: { label?: string }) => <span>{label}</span>,
+    HelpText: ({ text }: { text: string }) => <p data-testid="group-hint">{text}</p>,
+    Checkbox: ({ id, label, helpText }: { id: string; label: string; helpText?: string }) => (
+      <div data-testid={id}>
+        <span>{label}</span>
+        {helpText ? <span data-testid={`${id}-hint`}>{helpText}</span> : null}
+      </div>
+    ),
+    Modal,
+    Button: ({ children }: { children?: ReactNode }) => <button type="button">{children}</button>,
+    IconButton: ({ children }: { children?: ReactNode }) => (
+      <button type="button">{children}</button>
+    ),
+    CloseIcon: () => null,
+  }
+})
+
+vi.mock('./form-context', () => ({
+  useFormContext: () => ({ setSystemAvailableLocales: vi.fn() }),
+  useSystemAvailableLocales: () => ['en'],
+}))
+
+import { AvailableLocalesWidget } from './available-locales-widget'
+import { SystemFieldsConfirmModal } from './form-modals'
+
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+const en: Record<string, string> = adminTranslations({ locales: ['en'] }).en?.['byline-admin'] ?? {}
+
+describe('locale visibility copy', () => {
+  let container: HTMLDivElement
+  let root: Root
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(() => {
+    act(() => {
+      root.unmount()
+    })
+    container.remove()
+  })
+
+  const render = (node: ReactNode) => {
+    act(() => {
+      root.render(
+        <I18nProvider
+          bundle={adminTranslations({ locales: ['en'] })}
+          activeLocale="en"
+          defaultLocale="en"
+          localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
+        >
+          {node}
+        </I18nProvider>
+      )
+    })
+  }
+
+  const text = (testId: string) =>
+    container.querySelector(`[data-testid="${testId}"]`)?.textContent ?? null
+
+  it('explains source availability on the source row only, and delivery for the group', () => {
+    render(
+      <AvailableLocalesWidget
+        contentLocales={[
+          { code: 'en', label: 'English' },
+          { code: 'es', label: 'Español' },
+        ]}
+        availableVersionLocales={['en', 'es']}
+        sourceLocale="en"
+      />
+    )
+
+    expect(text('available-locale-en-hint')).toBe(en['availableLocalesWidget.sourceRowHint'])
+    expect(text('available-locale-en-hint')).toContain('available while published')
+    expect(text('available-locale-es-hint')).toBeNull()
+    expect(text('group-hint')).toBe(en['availableLocalesWidget.hint'])
+    expect(text('group-hint')).toContain('unpublished draft')
+    expect(container.textContent).toContain('whether or not it is checked')
+  })
+
+  it('moves the source note with the document source language', () => {
+    render(
+      <AvailableLocalesWidget
+        contentLocales={[
+          { code: 'en', label: 'English' },
+          { code: 'es', label: 'Español' },
+        ]}
+        availableVersionLocales={['en', 'es']}
+        sourceLocale="es"
+      />
+    )
+
+    expect(text('available-locale-es-hint')).toBe(en['availableLocalesWidget.sourceRowHint'])
+    expect(text('available-locale-en-hint')).toBeNull()
+  })
+
+  it('explains immediate public delivery for a locale-only save', () => {
+    render(
+      <SystemFieldsConfirmModal
+        contentDirty={false}
+        pathDirty={false}
+        availableLocalesDirty={true}
+        onCancel={() => {}}
+        onConfirm={() => {}}
+      />
+    )
+
+    expect(container.textContent).toContain(en['forms.systemFieldsConfirm.bulletLocales'])
+    expect(container.textContent).toContain('appears on the public site straight away')
+    expect(container.textContent).not.toContain(en['forms.systemFieldsConfirm.localesContentNote'])
+  })
+
+  it('explains the save order when locale and content changes are saved together', () => {
+    render(
+      <SystemFieldsConfirmModal
+        contentDirty={true}
+        pathDirty={false}
+        availableLocalesDirty={true}
+        onCancel={() => {}}
+        onConfirm={() => {}}
+      />
+    )
+
+    const note = en['forms.systemFieldsConfirm.localesContentNote']
+    expect(container.textContent).toContain(note)
+    // The combined save is one guarded commit: a failed save applies neither.
+    expect(note).toContain('saved together')
+    expect(note).toContain('neither is applied')
+    expect(note).toContain('stays hidden until it is published')
+  })
+
+  it('adds no locale note to a combined path and content save', () => {
+    render(
+      <SystemFieldsConfirmModal
+        contentDirty={true}
+        pathDirty={true}
+        availableLocalesDirty={false}
+        onCancel={() => {}}
+        onConfirm={() => {}}
+      />
+    )
+
+    expect(container.textContent).not.toContain(en['forms.systemFieldsConfirm.localesContentNote'])
+    expect(container.textContent).not.toContain(en['forms.systemFieldsConfirm.bulletLocales'])
+  })
+})