@byline/admin 6.6.0 → 6.7.0

package/dist/forms/available-locales-widget.d.ts

@@ -14,6 +14,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;
 }
 /**
  * System-managed `availableLocales` widget — the editorial "advertise these
@@ -27,4 +33,4 @@ export interface AvailableLocalesWidgetProps {
  * Stable override handles: `.byline-form-available-locales`,
  * `.byline-form-available-locales-list`.
  */
-export declare const AvailableLocalesWidget: ({ disabled: mutationsBlocked, contentLocales, availableVersionLocales, }: AvailableLocalesWidgetProps) => import("react").JSX.Element | null;
+export declare const AvailableLocalesWidget: ({ disabled: mutationsBlocked, contentLocales, availableVersionLocales, sourceLocale, }: AvailableLocalesWidgetProps) => import("react").JSX.Element | null;

package/dist/forms/available-locales-widget.js

@@ -2,12 +2,12 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 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 clsx from "clsx";
 import { reconcileLocaleState } from "./available-locales-reconcile.js";
 import available_locales_widget_module from "./available-locales-widget.module.js";
 import { useFormContext, useSystemAvailableLocales } from "./form-context.js";
-const AvailableLocalesWidget = ({ disabled: mutationsBlocked = false, contentLocales, availableVersionLocales })=>{
+const AvailableLocalesWidget = ({ disabled: mutationsBlocked = false, contentLocales, availableVersionLocales, sourceLocale })=>{
     const { t } = useTranslation('byline-admin');
     const { setSystemAvailableLocales } = useFormContext();
     const advertised = useSystemAvailableLocales();
@@ -55,10 +55,15 @@ const AvailableLocalesWidget = ({ disabled: mutationsBlocked = false, contentLoc
                         intent: intent,
                         checked: checked,
                         disabled: mutationsBlocked || disabled,
-                        onCheckedChange: (value)=>toggle(code, true === value)
+                        onCheckedChange: (value)=>toggle(code, true === value),
+                        helpText: code === sourceLocale ? t('availableLocalesWidget.sourceRowHint') : void 0
                     }, code);
                 })
             }),
+            /*#__PURE__*/ jsx(HelpText, {
+                className: "byline-form-available-locales-hint",
+                text: t('availableLocalesWidget.hint')
+            }),
             /*#__PURE__*/ jsx("span", {
                 id: "available-locales-description",
                 className: clsx('byline-form-available-locales-sr-only', available_locales_widget_module["sr-only"]),

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

@@ -34,8 +34,9 @@ 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/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';
 export interface DirtyBreakdown {

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

@@ -10,7 +10,11 @@ export declare const UnsavedChangesModal: ({ onClose }: {
  * 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 declare const SystemFieldsConfirmModal: ({ contentDirty, pathDirty, availableLocalesDirty, onCancel, onConfirm, }: {
     contentDirty: boolean;

package/dist/forms/form-modals.js

@@ -81,6 +81,10 @@ const SystemFieldsConfirmModal = ({ contentDirty, pathDirty, availableLocalesDir
                             className: clsx('byline-form-system-fields-content-note', 'm-0 mt-2'),
                             children: t('forms.systemFieldsConfirm.contentNote')
                         }),
+                        contentDirty && availableLocalesDirty && /*#__PURE__*/ jsx("p", {
+                            className: clsx('byline-form-system-fields-locales-note', 'm-0 mt-2'),
+                            children: t('forms.systemFieldsConfirm.localesContentNote')
+                        }),
                         /*#__PURE__*/ jsx("p", {
                             className: "m-0 mt-2",
                             style: contentDirty ? {

package/dist/forms/form-page-chrome.js

@@ -236,7 +236,8 @@ const FormSidebarWidgets = ({ disabled, mode, initialData, collectionPath, defau
             advertiseLocales && /*#__PURE__*/ jsx(AvailableLocalesWidget, {
                 disabled: disabled,
                 contentLocales: contentLocales ?? [],
-                availableVersionLocales: initialData?._availableVersionLocales ?? []
+                availableVersionLocales: initialData?._availableVersionLocales ?? [],
+                sourceLocale: initialData?.sourceLocale ?? defaultLocale
             })
         ]
     });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.6.0",
+  "version": "6.7.0",
   "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-agent": "6.7.0",
+    "@byline/core": "6.7.0",
+    "@byline/i18n": "6.7.0",
+    "@byline/analytics": "6.7.0",
+    "@byline/ui": "6.7.0",
+    "@byline/auth": "6.7.0"
   },
   "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'])
+  })
+})