@byline/admin 2.7.0 → 3.0.0

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

@@ -0,0 +1,30 @@
+/**
+ * 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
+ */
+/**
+ * Pure reconciliation logic for the available-locales widget, kept React- and
+ * CSS-free so it can be unit-tested in the node-mode admin suite (importing the
+ * `.tsx` widget would drag in JSX + a CSS-module import the node runner can't
+ * transform).
+ */
+/** Checkbox intent + interactivity for one reconciled locale row. */
+export interface ReconciledLocaleState {
+    intent: 'success' | 'warning' | 'noeffect';
+    disabled: boolean;
+}
+/**
+ * Reconcile a locale's editorial state (`checked` — in the stored advertised
+ * set) against the ledger fact (`complete` — in `_availableVersionLocales`)
+ * into a checkbox intent + disabled flag. The reconciliation is expressed
+ * entirely through colour/interactivity, with no per-row text:
+ *
+ *   complete                 → `success` (green),  enabled  — toggle on/off
+ *   not complete, advertised → `warning` (amber),  enabled  — advertising an
+ *       incomplete locale; the editor can uncheck to resolve the over-advert
+ *   not complete, not advert → `noeffect` (gray),  disabled — nothing to do
+ */
+export declare function reconcileLocaleState(checked: boolean, complete: boolean): ReconciledLocaleState;

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

@@ -0,0 +1,15 @@
+function reconcileLocaleState(checked, complete) {
+    if (complete) return {
+        intent: 'success',
+        disabled: false
+    };
+    if (checked) return {
+        intent: 'warning',
+        disabled: false
+    };
+    return {
+        intent: 'noeffect',
+        disabled: true
+    };
+}
+export { reconcileLocaleState };

package/dist/forms/available-locales-reconcile.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/available-locales-widget.d.ts

@@ -0,0 +1,29 @@
+export { type ReconciledLocaleState, reconcileLocaleState } from './available-locales-reconcile';
+/** A content locale to render a checkbox for. */
+export interface AvailableLocalesWidgetLocale {
+    code: string;
+    label: string;
+}
+export interface AvailableLocalesWidgetProps {
+    /** All configured content locales — one checkbox each (code + display label). */
+    contentLocales: ReadonlyArray<AvailableLocalesWidgetLocale>;
+    /**
+     * The saved version's ledger-complete locale set (`_availableVersionLocales`,
+     * read-only structural fact). Drives the per-row intent. Empty until the read
+     * surface supplies it (Slice 6) — in which case every row renders neutral.
+     */
+    availableVersionLocales: readonly string[];
+}
+/**
+ * System-managed `availableLocales` widget — the editorial "advertise these
+ * content locales" control. Renders one checkbox per content locale in the
+ * sidebar, directly below the path widget. The checked state reflects the
+ * stored advertised set (`useSystemAvailableLocales`); each row's intent
+ * reconciles that against the structural ledger fact (`availableVersionLocales`)
+ * via {@link reconcileLocaleState}. Opt-in: nothing is advertised until the
+ * editor checks a (green) locale.
+ *
+ * Stable override handles: `.byline-form-available-locales`,
+ * `.byline-form-available-locales-list`.
+ */
+export declare const AvailableLocalesWidget: ({ contentLocales, availableVersionLocales, }: AvailableLocalesWidgetProps) => import("react").JSX.Element | null;

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

@@ -0,0 +1,68 @@
+"use client";
+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 classnames from "classnames";
+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 = ({ contentLocales, availableVersionLocales })=>{
+    const { t } = useTranslation('byline-admin');
+    const { setSystemAvailableLocales } = useFormContext();
+    const advertised = useSystemAvailableLocales();
+    const advertisedSet = useMemo(()=>new Set(advertised), [
+        advertised
+    ]);
+    const ledgerSet = useMemo(()=>new Set(availableVersionLocales), [
+        availableVersionLocales
+    ]);
+    const toggle = useCallback((code, checked)=>{
+        const next = new Set(advertised);
+        if (checked) next.add(code);
+        else next.delete(code);
+        setSystemAvailableLocales([
+            ...next
+        ]);
+    }, [
+        advertised,
+        setSystemAvailableLocales
+    ]);
+    if (0 === contentLocales.length) return null;
+    return /*#__PURE__*/ jsxs("div", {
+        className: classnames('byline-form-available-locales', available_locales_widget_module.container),
+        children: [
+            /*#__PURE__*/ jsx(Label, {
+                id: "available-locales",
+                htmlFor: "available-locales-group",
+                label: t('availableLocalesWidget.label')
+            }),
+            /*#__PURE__*/ jsx("div", {
+                id: "available-locales-group",
+                className: classnames('byline-form-available-locales-list', available_locales_widget_module.list),
+                role: "group",
+                "aria-labelledby": "label-for-available-locales",
+                "aria-describedby": "available-locales-description",
+                children: contentLocales.map(({ code, label })=>{
+                    const checked = advertisedSet.has(code);
+                    const { intent, disabled } = reconcileLocaleState(checked, ledgerSet.has(code));
+                    return /*#__PURE__*/ jsx(Checkbox, {
+                        id: `available-locale-${code}`,
+                        name: `__availableLocale_${code}__`,
+                        label: label,
+                        intent: intent,
+                        checked: checked,
+                        disabled: disabled,
+                        onCheckedChange: (value)=>toggle(code, true === value)
+                    }, code);
+                })
+            }),
+            /*#__PURE__*/ jsx("span", {
+                id: "available-locales-description",
+                className: classnames('byline-form-available-locales-sr-only', available_locales_widget_module["sr-only"]),
+                children: t("availableLocalesWidget.srDescription")
+            })
+        ]
+    });
+};
+export { AvailableLocalesWidget, reconcileLocaleState };

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

@@ -0,0 +1,8 @@
+import "./available-locales-widget_module.css";
+const available_locales_widget_module = {
+    container: "container-exFiHE",
+    list: "list-q2z1qA",
+    "sr-only": "sr-only-duiY99",
+    srOnly: "sr-only-duiY99"
+};
+export default available_locales_widget_module;

package/dist/forms/available-locales-widget_module.css

@@ -0,0 +1,18 @@
+:is(.container-exFiHE, .byline-form-available-locales), :is(.list-q2z1qA, .byline-form-available-locales-list) {
+  gap: var(--spacing-8);
+  flex-direction: column;
+  display: flex;
+}
+
+:is(.sr-only-duiY99, .byline-form-available-locales-sr-only) {
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  position: absolute;
+  overflow: hidden;
+}
+

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

@@ -28,6 +28,7 @@ type FieldListener = (value: any) => void;
 type ErrorsListener = (errors: FormError[]) => void;
 type MetaListener = () => void;
 type SystemPathListener = (value: string | null) => void;
+type SystemAvailableLocalesListener = (value: string[]) => void;
 type FieldUploadingListener = (uploading: boolean) => void;
 interface FormContextType {
     setFieldValue: (name: string, value: any) => void;
@@ -61,6 +62,9 @@ interface FormContextType {
     getSystemPath: () => string | null;
     setSystemPath: (value: string | null) => void;
     subscribeSystemPath: (listener: SystemPathListener) => () => void;
+    getSystemAvailableLocales: () => string[];
+    setSystemAvailableLocales: (value: string[]) => void;
+    subscribeSystemAvailableLocales: (listener: SystemAvailableLocalesListener) => () => void;
 }
 export declare const useFormContext: () => FormContextType;
 export declare const FormProvider: ({ children, initialData, }: {
@@ -72,6 +76,12 @@ export declare const FormProvider: ({ children, initialData, }: {
  * Returns the current value (or `null` when no override is set).
  */
 export declare const useSystemPath: () => string | null;
+/**
+ * Subscribe to the system `availableLocales` slot edited by the
+ * available-locales widget. Returns the current advertised set (or `[]` when
+ * nothing is advertised / not yet surfaced).
+ */
+export declare const useSystemAvailableLocales: () => string[];
 export declare const useFormStore: () => FormContextType;
 export declare const useFieldError: (name: string) => string | undefined;
 export declare const useFormMeta: () => {

package/dist/forms/form-context.js

@@ -3,6 +3,16 @@ import { jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useRef, useState } from "react";
 import { normalizeHooks } from "@byline/core";
 import { get, set as external_lodash_es_set } from "lodash-es";
+const sameLocaleSet = (a, b)=>{
+    if (a.length !== b.length) return false;
+    const sa = [
+        ...a
+    ].sort();
+    const sb = [
+        ...b
+    ].sort();
+    return sa.every((v, i)=>v === sb[i]);
+};
 const FormContext = /*#__PURE__*/ createContext(null);
 const useFormContext = ()=>{
     const context = useContext(FormContext);
@@ -24,6 +34,13 @@ const FormProvider = ({ children, initialData = {} })=>{
     const systemPathRef = useRef('string' == typeof initialData?.path && initialData.path.length > 0 ? initialData.path : null);
     const initialSystemPath = useRef(systemPathRef.current);
     const systemPathListeners = useRef(new Set());
+    const systemAvailableLocalesRef = useRef(Array.isArray(initialData?.availableLocales) ? [
+        ...initialData.availableLocales
+    ] : []);
+    const initialSystemAvailableLocales = useRef([
+        ...systemAvailableLocalesRef.current
+    ]);
+    const systemAvailableLocalesListeners = useRef(new Set());
     const subscribeField = useCallback((name, listener)=>{
         if (!fieldListeners.current.has(name)) fieldListeners.current.set(name, new Set());
         fieldListeners.current.get(name)?.add(listener);
@@ -134,6 +151,9 @@ const FormProvider = ({ children, initialData = {} })=>{
         dirtyFields.current.clear();
         patchesRef.current = [];
         initialSystemPath.current = systemPathRef.current;
+        initialSystemAvailableLocales.current = [
+            ...systemAvailableLocalesRef.current
+        ];
         notifyMetaListeners();
     }, [
         notifyMetaListeners
@@ -157,6 +177,27 @@ const FormProvider = ({ children, initialData = {} })=>{
             systemPathListeners.current.delete(listener);
         };
     }, []);
+    const getSystemAvailableLocales = useCallback(()=>systemAvailableLocalesRef.current, []);
+    const setSystemAvailableLocales = useCallback((value)=>{
+        const next = [
+            ...value
+        ];
+        systemAvailableLocalesRef.current = next;
+        if (sameLocaleSet(next, initialSystemAvailableLocales.current)) dirtyFields.current.delete('__systemAvailableLocales__');
+        else dirtyFields.current.add('__systemAvailableLocales__');
+        systemAvailableLocalesListeners.current.forEach((listener)=>{
+            listener(next);
+        });
+        notifyMetaListeners();
+    }, [
+        notifyMetaListeners
+    ]);
+    const subscribeSystemAvailableLocales = useCallback((listener)=>{
+        systemAvailableLocalesListeners.current.add(listener);
+        return ()=>{
+            systemAvailableLocalesListeners.current.delete(listener);
+        };
+    }, []);
     const addPendingUpload = useCallback((fieldPath, upload)=>{
         const existing = pendingUploadsRef.current.get(fieldPath);
         if (existing) URL.revokeObjectURL(existing.previewUrl);
@@ -378,7 +419,10 @@ const FormProvider = ({ children, initialData = {} })=>{
             subscribeFieldUploading,
             getSystemPath,
             setSystemPath,
-            subscribeSystemPath
+            subscribeSystemPath,
+            getSystemAvailableLocales,
+            setSystemAvailableLocales,
+            subscribeSystemAvailableLocales
         },
         children: children
     });
@@ -391,6 +435,14 @@ const useSystemPath = ()=>{
     ]);
     return value;
 };
+const useSystemAvailableLocales = ()=>{
+    const { getSystemAvailableLocales, subscribeSystemAvailableLocales } = useFormContext();
+    const [value, setValue] = useState(()=>getSystemAvailableLocales());
+    useEffect(()=>subscribeSystemAvailableLocales((next)=>setValue(next)), [
+        subscribeSystemAvailableLocales
+    ]);
+    return value;
+};
 const useFormStore = ()=>useFormContext();
 const useFieldError = (name)=>{
     const { getErrors, subscribeErrors } = useFormContext();
@@ -463,4 +515,4 @@ const useIsFieldUploading = (fieldPath)=>{
     ]);
     return uploading;
 };
-export { FormProvider, useFieldError, useFieldValue, useFormContext, useFormMeta, useFormStore, useIsDirty, useIsFieldUploading, useSystemPath };
+export { FormProvider, useFieldError, useFieldValue, useFormContext, useFormMeta, useFormStore, useIsDirty, useIsFieldUploading, useSystemAvailableLocales, useSystemPath };

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

@@ -66,6 +66,13 @@ export interface FormRendererProps {
      * present the path widget renders in the sidebar.
      */
     useAsPath?: string;
+    /**
+     * Opts the available-locales widget into the sidebar (below the path
+     * widget). Sourced from `CollectionDefinition.advertiseLocales` by the
+     * caller. When true, one checkbox per content locale renders, reconciled
+     * against the document's `_availableVersionLocales` ledger fact.
+     */
+    advertiseLocales?: boolean;
     headingLabel?: string;
     headerSlot?: ReactNode;
     /** Collection path forwarded to upload-capable fields (e.g. `'media'`). */
@@ -95,4 +102,4 @@ export interface FormRendererProps {
      */
     useNavigationGuard?: UseNavigationGuard;
 }
-export declare const FormRenderer: ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, contentLocales, nextStatus, workflowStatuses, publishedVersion, initialData, adminConfig, useAsTitle, useAsPath, headingLabel, headerSlot, collectionPath, initialLocale, onLocaleChange, defaultLocale, useNavigationGuard, restoreWarnings, }: FormRendererProps) => import("react").JSX.Element;
+export declare const FormRenderer: ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, contentLocales, nextStatus, workflowStatuses, publishedVersion, initialData, adminConfig, useAsTitle, useAsPath, advertiseLocales, headingLabel, headerSlot, collectionPath, initialLocale, onLocaleChange, defaultLocale, useNavigationGuard, restoreWarnings, }: FormRendererProps) => import("react").JSX.Element;

package/dist/forms/form-renderer.js

@@ -10,6 +10,7 @@ import { LocalDateTime } from "../fields/local-date-time.js";
 import { AdminGroup } from "../presentation/group.js";
 import { AdminRow } from "../presentation/row.js";
 import { AdminTabs } from "../presentation/tabs.js";
+import { AvailableLocalesWidget } from "./available-locales-widget.js";
 import { DocumentActions } from "./document-actions.js";
 import { FormProvider, useFieldValue, useFormContext } from "./form-context.js";
 import form_renderer_module from "./form-renderer.module.js";
@@ -139,8 +140,8 @@ function computeStatusTransitions(currentStatus, workflowStatuses, nextStatus) {
         isTerminal: false
     };
 }
-const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, contentLocales, nextStatus, workflowStatuses, publishedVersion, initialData, adminConfig, useAsTitle, useAsPath, headingLabel, headerSlot, collectionPath, initialLocale, onLocaleChange, defaultLocale = 'en', useNavigationGuard: useNavigationGuardProp, restoreWarnings, _activeTabBySet, _onTabChange })=>{
-    const { getFieldValues, runFieldHooks, validateForm, errors: initialErrors, hasChanges: hasChangesFn, resetHasChanges, getPatches, getSystemPath, subscribeErrors, subscribeMeta, setFieldValue, setFieldError, getPendingUploads, clearPendingUploads, setFieldUploading } = useFormContext();
+const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, 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 { t } = useTranslation('byline-admin');
     const [errors, setErrors] = useState(initialErrors);
     const [hasChanges, setHasChanges] = useState(hasChangesFn());
@@ -302,11 +303,13 @@ const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpub
             const data = getFieldValues();
             const patches = getPatches();
             const systemPath = getSystemPath();
+            const systemAvailableLocales = advertiseLocales ? getSystemAvailableLocales() : void 0;
             if (onSubmit && 'function' == typeof onSubmit) {
                 onSubmit({
                     data,
                     patches,
-                    systemPath
+                    systemPath,
+                    systemAvailableLocales
                 });
                 resetHasChanges();
             }
@@ -503,6 +506,10 @@ const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpub
                                 activeLocale: contentLocale,
                                 mode: mode
                             }),
+                            advertiseLocales && /*#__PURE__*/ jsx(AvailableLocalesWidget, {
+                                contentLocales: contentLocales ?? [],
+                                availableVersionLocales: initialData?._availableVersionLocales ?? []
+                            }),
                             (layout.sidebar ?? []).map((name)=>renderItem(name))
                         ]
                     })
@@ -554,7 +561,7 @@ const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpub
         ]
     });
 };
-const FormRenderer = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, contentLocales, nextStatus, workflowStatuses, publishedVersion, initialData, adminConfig, useAsTitle, useAsPath, headingLabel, headerSlot, collectionPath, initialLocale, onLocaleChange, defaultLocale, useNavigationGuard, restoreWarnings })=>{
+const FormRenderer = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, contentLocales, nextStatus, workflowStatuses, publishedVersion, initialData, adminConfig, useAsTitle, useAsPath, advertiseLocales, headingLabel, headerSlot, collectionPath, initialLocale, onLocaleChange, defaultLocale, useNavigationGuard, restoreWarnings })=>{
     const savedTabsRef = useRef({});
     return /*#__PURE__*/ jsx(FormProvider, {
         initialData: initialData,
@@ -576,6 +583,7 @@ const FormRenderer = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpu
             adminConfig: adminConfig,
             useAsTitle: useAsTitle,
             useAsPath: useAsPath,
+            advertiseLocales: advertiseLocales,
             headingLabel: headingLabel,
             headerSlot: headerSlot,
             collectionPath: collectionPath,

package/dist/react.d.ts

@@ -62,5 +62,6 @@ export * from './presentation/group.js';
 export * from './presentation/row.js';
 export * from './presentation/tabs.js';
 export * from './widgets/diff-viewer/diff-modal.js';
+export * from './widgets/source-locale-badge/source-locale-badge.js';
 export * from './widgets/status-badge/status-badge.js';
 export type { BylineFieldServices, CollectionListDoc, CollectionListParams, CollectionListResponse, GetCollectionDocumentsFn, UploadedFileResult, UploadFieldFn, } from './fields/field-services-types.js';

package/dist/react.js

@@ -33,4 +33,5 @@ export * from "./presentation/group.js";
 export * from "./presentation/row.js";
 export * from "./presentation/tabs.js";
 export * from "./widgets/diff-viewer/diff-modal.js";
+export * from "./widgets/source-locale-badge/source-locale-badge.js";
 export * from "./widgets/status-badge/status-badge.js";

package/dist/widgets/source-locale-badge/source-locale-badge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 interface SourceLocaleBadgeProps {
+    /** The document's content source locale code (e.g. `en`, `fr`). */
+    locale: string;
+    className?: string;
+}
+/**
+ * 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/DEFAULT-LOCALE-SWITCHING.md (Slice 6).
+ *
+ * Stable override handle: `.byline-source-locale-badge`.
+ */
+export declare const SourceLocaleBadge: {
+    ({ locale, className }: SourceLocaleBadgeProps): import("react").JSX.Element;
+    displayName: string;
+};

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

@@ -0,0 +1,13 @@
+import { jsx } from "react/jsx-runtime";
+import { Badge } from "@byline/ui/react";
+import classnames from "classnames";
+import source_locale_badge_module from "./source-locale-badge.module.js";
+const SourceLocaleBadge = ({ locale, className })=>/*#__PURE__*/ jsx(Badge, {
+        intent: "noeffect",
+        render: /*#__PURE__*/ jsx("span", {}),
+        title: `Primary content language: ${locale.toUpperCase()}`,
+        className: classnames('byline-source-locale-badge', source_locale_badge_module.badge, className),
+        children: locale.toUpperCase()
+    });
+SourceLocaleBadge.displayName = 'SourceLocaleBadge';
+export { SourceLocaleBadge };

package/dist/widgets/source-locale-badge/source-locale-badge.module.js

@@ -0,0 +1,5 @@
+import "./source-locale-badge_module.css";
+const source_locale_badge_module = {
+    badge: "badge-agHrzy"
+};
+export default source_locale_badge_module;

package/dist/widgets/source-locale-badge/source-locale-badge_module.css

@@ -0,0 +1,10 @@
+:is(.badge-agHrzy, .byline-source-locale-badge) {
+  font-size: .65rem;
+  font-weight: var(--font-weight-semibold);
+  letter-spacing: var(--letter-spacing-wide);
+  vertical-align: middle;
+  margin-left: .5rem;
+  padding: 0 .375rem;
+  line-height: 1.5;
+}
+

package/package.json

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

package/src/forms/available-locales-reconcile.test.node.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { describe, expect, it } from 'vitest'
+
+import { reconcileLocaleState } from './available-locales-reconcile.js'
+
+/**
+ * The widget's reconciliation is expressed purely as Checkbox intent +
+ * disabled state — no per-row text. `reconcileLocaleState` is the pure heart
+ * of that mapping; the four cells below are the full truth table from
+ * docs/AVAILABLE-LOCALES.md.
+ */
+describe('reconcileLocaleState', () => {
+  it('ledger-complete + advertised → green, enabled (advertised & complete)', () => {
+    expect(reconcileLocaleState(true, true)).toEqual({ intent: 'success', disabled: false })
+  })
+
+  it('ledger-complete + not advertised → green, enabled (invitation to advertise)', () => {
+    expect(reconcileLocaleState(false, true)).toEqual({ intent: 'success', disabled: false })
+  })
+
+  it('not complete + advertised → amber, enabled (advertising an incomplete locale)', () => {
+    // The ⚠ row: surfaced as `warning` and kept enabled so the editor can
+    // uncheck to resolve the over-advertisement.
+    expect(reconcileLocaleState(true, false)).toEqual({ intent: 'warning', disabled: false })
+  })
+
+  it('not complete + not advertised → gray, disabled (nothing to advertise)', () => {
+    expect(reconcileLocaleState(false, false)).toEqual({ intent: 'noeffect', disabled: true })
+  })
+
+  it('completeness drives green regardless of advertised state', () => {
+    // The ledger fact wins the colour when complete; only the disabled/amber
+    // distinction depends on the advertised flag.
+    expect(reconcileLocaleState(true, true).intent).toBe('success')
+    expect(reconcileLocaleState(false, true).intent).toBe('success')
+  })
+
+  it('only the not-complete + not-advertised cell is non-interactive', () => {
+    expect(reconcileLocaleState(true, true).disabled).toBe(false)
+    expect(reconcileLocaleState(false, true).disabled).toBe(false)
+    expect(reconcileLocaleState(true, false).disabled).toBe(false)
+    expect(reconcileLocaleState(false, false).disabled).toBe(true)
+  })
+})

package/src/forms/available-locales-reconcile.ts

@@ -0,0 +1,37 @@
+/**
+ * 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
+ */
+
+/**
+ * Pure reconciliation logic for the available-locales widget, kept React- and
+ * CSS-free so it can be unit-tested in the node-mode admin suite (importing the
+ * `.tsx` widget would drag in JSX + a CSS-module import the node runner can't
+ * transform).
+ */
+
+/** Checkbox intent + interactivity for one reconciled locale row. */
+export interface ReconciledLocaleState {
+  intent: 'success' | 'warning' | 'noeffect'
+  disabled: boolean
+}
+
+/**
+ * Reconcile a locale's editorial state (`checked` — in the stored advertised
+ * set) against the ledger fact (`complete` — in `_availableVersionLocales`)
+ * into a checkbox intent + disabled flag. The reconciliation is expressed
+ * entirely through colour/interactivity, with no per-row text:
+ *
+ *   complete                 → `success` (green),  enabled  — toggle on/off
+ *   not complete, advertised → `warning` (amber),  enabled  — advertising an
+ *       incomplete locale; the editor can uncheck to resolve the over-advert
+ *   not complete, not advert → `noeffect` (gray),  disabled — nothing to do
+ */
+export function reconcileLocaleState(checked: boolean, complete: boolean): ReconciledLocaleState {
+  if (complete) return { intent: 'success', disabled: false }
+  if (checked) return { intent: 'warning', disabled: false }
+  return { intent: 'noeffect', disabled: true }
+}

package/src/forms/available-locales-widget.module.css

@@ -0,0 +1,39 @@
+/**
+ * AvailableLocalesWidget — system-managed `availableLocales` form widget.
+ *
+ * The editorial "advertise these locales" checkbox list, rendered in the
+ * sidebar below the path widget. Per-row reconciliation against the ledger is
+ * conveyed by Checkbox `intent` (green/amber/gray) — no per-row text.
+ *
+ * Override handles:
+ *   .byline-form-available-locales         — wrapper div
+ *   .byline-form-available-locales-list    — checkbox group
+ *   .byline-form-available-locales-sr-only — visually-hidden screen-reader hint
+ */
+
+.container,
+:global(.byline-form-available-locales) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-8);
+}
+
+.list,
+:global(.byline-form-available-locales-list) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-8);
+}
+
+.sr-only,
+:global(.byline-form-available-locales-sr-only) {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

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

@@ -0,0 +1,119 @@
+'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 { useCallback, useMemo } from 'react'
+
+import { useTranslation } from '@byline/i18n/react'
+import { Checkbox, Label } from '@byline/ui/react'
+import cx from 'classnames'
+
+import { reconcileLocaleState } from './available-locales-reconcile'
+import styles from './available-locales-widget.module.css'
+import { useFormContext, useSystemAvailableLocales } from './form-context'
+
+export { type ReconciledLocaleState, reconcileLocaleState } from './available-locales-reconcile'
+
+/** A content locale to render a checkbox for. */
+export interface AvailableLocalesWidgetLocale {
+  code: string
+  label: string
+}
+
+export interface AvailableLocalesWidgetProps {
+  /** All configured content locales — one checkbox each (code + display label). */
+  contentLocales: ReadonlyArray<AvailableLocalesWidgetLocale>
+  /**
+   * The saved version's ledger-complete locale set (`_availableVersionLocales`,
+   * read-only structural fact). Drives the per-row intent. Empty until the read
+   * surface supplies it (Slice 6) — in which case every row renders neutral.
+   */
+  availableVersionLocales: readonly string[]
+}
+
+/**
+ * System-managed `availableLocales` widget — the editorial "advertise these
+ * content locales" control. Renders one checkbox per content locale in the
+ * sidebar, directly below the path widget. The checked state reflects the
+ * stored advertised set (`useSystemAvailableLocales`); each row's intent
+ * reconciles that against the structural ledger fact (`availableVersionLocales`)
+ * via {@link reconcileLocaleState}. Opt-in: nothing is advertised until the
+ * editor checks a (green) locale.
+ *
+ * Stable override handles: `.byline-form-available-locales`,
+ * `.byline-form-available-locales-list`.
+ */
+export const AvailableLocalesWidget = ({
+  contentLocales,
+  availableVersionLocales,
+}: AvailableLocalesWidgetProps) => {
+  const { t } = useTranslation('byline-admin')
+  const { setSystemAvailableLocales } = useFormContext()
+  const advertised = useSystemAvailableLocales()
+
+  const advertisedSet = useMemo(() => new Set(advertised), [advertised])
+  const ledgerSet = useMemo(() => new Set(availableVersionLocales), [availableVersionLocales])
+
+  const toggle = useCallback(
+    (code: string, checked: boolean) => {
+      const next = new Set(advertised)
+      if (checked) {
+        next.add(code)
+      } else {
+        next.delete(code)
+      }
+      setSystemAvailableLocales([...next])
+    },
+    [advertised, setSystemAvailableLocales]
+  )
+
+  if (contentLocales.length === 0) {
+    return null
+  }
+
+  return (
+    <div className={cx('byline-form-available-locales', styles.container)}>
+      <Label
+        id="available-locales"
+        htmlFor="available-locales-group"
+        label={t('availableLocalesWidget.label')}
+      />
+      <div
+        id="available-locales-group"
+        className={cx('byline-form-available-locales-list', styles.list)}
+        role="group"
+        aria-labelledby="label-for-available-locales"
+        aria-describedby="available-locales-description"
+      >
+        {contentLocales.map(({ code, label }) => {
+          const checked = advertisedSet.has(code)
+          const { intent, disabled } = reconcileLocaleState(checked, ledgerSet.has(code))
+          return (
+            <Checkbox
+              key={code}
+              id={`available-locale-${code}`}
+              name={`__availableLocale_${code}__`}
+              label={label}
+              intent={intent}
+              checked={checked}
+              disabled={disabled}
+              onCheckedChange={(value) => toggle(code, value === true)}
+            />
+          )
+        })}
+      </div>
+      <span
+        id="available-locales-description"
+        className={cx('byline-form-available-locales-sr-only', styles['sr-only'])}
+      >
+        {t('availableLocalesWidget.srDescription')}
+      </span>
+    </div>
+  )
+}

package/src/forms/form-context.tsx

@@ -38,8 +38,21 @@ type FieldListener = (value: any) => void
 type ErrorsListener = (errors: FormError[]) => void
 type MetaListener = () => void
 type SystemPathListener = (value: string | null) => void
+type SystemAvailableLocalesListener = (value: string[]) => void
 type FieldUploadingListener = (uploading: boolean) => void
 
+/**
+ * Order-insensitive set equality for the advertised-locale slot. The slot
+ * holds an array, so a fresh array reference is never `===` its initial — dirty
+ * tracking must compare membership, not identity.
+ */
+const sameLocaleSet = (a: string[], b: string[]): boolean => {
+  if (a.length !== b.length) return false
+  const sa = [...a].sort()
+  const sb = [...b].sort()
+  return sa.every((v, i) => v === sb[i])
+}
+
 interface FormContextType {
   setFieldValue: (name: string, value: any) => void
   setFieldStore: (name: string, value: any) => void
@@ -80,6 +93,13 @@ interface FormContextType {
   getSystemPath: () => string | null
   setSystemPath: (value: string | null) => void
   subscribeSystemPath: (listener: SystemPathListener) => () => void
+  // System-managed `availableLocales` slot (the editorial advertised-locale
+  // set, persisted in `byline_document_available_locales`), edited by the
+  // available-locales widget. Holds the full set; the value is sent verbatim
+  // to the server. Document-grain and sticky, like the path slot above.
+  getSystemAvailableLocales: () => string[]
+  setSystemAvailableLocales: (value: string[]) => void
+  subscribeSystemAvailableLocales: (listener: SystemAvailableLocalesListener) => () => void
 }
 
 const FormContext = createContext<FormContextType | null>(null)
@@ -125,6 +145,16 @@ export const FormProvider = ({
   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())
@@ -267,6 +297,7 @@ export const FormProvider = ({
     dirtyFields.current.clear()
     patchesRef.current = []
     initialSystemPath.current = systemPathRef.current
+    initialSystemAvailableLocales.current = [...systemAvailableLocalesRef.current]
     notifyMetaListeners()
   }, [notifyMetaListeners])
 
@@ -303,6 +334,39 @@ export const FormProvider = ({
     }
   }, [])
 
+  // -------------------------------------------------------------------------
+  // 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('__systemAvailableLocales__')
+      } else {
+        dirtyFields.current.delete('__systemAvailableLocales__')
+      }
+      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)
   // ---------------------------------------------------------------------------
@@ -591,6 +655,9 @@ export const FormProvider = ({
         getSystemPath,
         setSystemPath,
         subscribeSystemPath,
+        getSystemAvailableLocales,
+        setSystemAvailableLocales,
+        subscribeSystemAvailableLocales,
       }}
     >
       {children}
@@ -613,6 +680,22 @@ export const useSystemPath = (): string | null => {
   return value
 }
 
+/**
+ * Subscribe to the system `availableLocales` slot edited by the
+ * available-locales widget. Returns the current advertised set (or `[]` when
+ * nothing is advertised / not yet surfaced).
+ */
+export const useSystemAvailableLocales = (): string[] => {
+  const { getSystemAvailableLocales, subscribeSystemAvailableLocales } = useFormContext()
+  const [value, setValue] = useState<string[]>(() => getSystemAvailableLocales())
+
+  useEffect(() => {
+    return subscribeSystemAvailableLocales((next) => setValue(next))
+  }, [subscribeSystemAvailableLocales])
+
+  return value
+}
+
 export const useFormStore = () => {
   return useFormContext()
 }

package/src/forms/form-renderer.tsx

@@ -28,6 +28,7 @@ import { LocalDateTime } from '../fields/local-date-time'
 import { AdminGroup } from '../presentation/group'
 import { AdminRow } from '../presentation/row'
 import { AdminTabs } from '../presentation/tabs'
+import { AvailableLocalesWidget } from './available-locales-widget'
 import { DocumentActions, type DocumentActionsLocaleOption } from './document-actions'
 import { FormProvider, useFieldValue, useFormContext } from './form-context'
 import styles from './form-renderer.module.css'
@@ -91,6 +92,13 @@ export interface FormRendererProps {
    * present the path widget renders in the sidebar.
    */
   useAsPath?: string
+  /**
+   * Opts the available-locales widget into the sidebar (below the path
+   * widget). Sourced from `CollectionDefinition.advertiseLocales` by the
+   * caller. When true, one checkbox per content locale renders, reconciled
+   * against the document's `_availableVersionLocales` ledger fact.
+   */
+  advertiseLocales?: boolean
   headingLabel?: string
   headerSlot?: ReactNode
   /** Collection path forwarded to upload-capable fields (e.g. `'media'`). */
@@ -299,6 +307,7 @@ const FormContent = ({
   adminConfig,
   useAsTitle,
   useAsPath,
+  advertiseLocales,
   headingLabel,
   headerSlot,
   collectionPath,
@@ -323,6 +332,7 @@ const FormContent = ({
     resetHasChanges,
     getPatches,
     getSystemPath,
+    getSystemAvailableLocales,
     subscribeErrors,
     subscribeMeta,
     setFieldValue,
@@ -560,9 +570,13 @@ const FormContent = ({
       const data = getFieldValues()
       const patches = getPatches()
       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 })
+        onSubmit({ data, patches, systemPath, systemAvailableLocales })
         resetHasChanges()
       }
     })()
@@ -658,6 +672,10 @@ const FormContent = ({
     <form noValidate onSubmit={handleSubmit} className={cx('byline-form', styles.form)}>
       <div className={cx('byline-form-heading-row', styles['heading-row'])}>
         <h1 className={cx('byline-form-heading', styles.heading)}>{heading}</h1>
+        {/* Source-locale anchor indicator removed pending heading-layout work.
+            To re-enable: render `<SourceLocaleBadge locale={sourceLocale} />`
+            here from `initialData.sourceLocale` (mismatch-only is the intended
+            end state). See docs/DEFAULT-LOCALE-SWITCHING.md (Slice 6). */}
         {headerSlot}
       </div>
       <div className={cx('byline-form-status-bar', styles['status-bar'])}>
@@ -786,6 +804,14 @@ const FormContent = ({
               mode={mode}
             />
           )}
+          {advertiseLocales && (
+            <AvailableLocalesWidget
+              contentLocales={contentLocales ?? []}
+              availableVersionLocales={
+                (initialData?._availableVersionLocales as string[] | undefined) ?? []
+              }
+            />
+          )}
           {(layout.sidebar ?? []).map((name) => renderItem(name))}
         </div>
       </div>
@@ -837,6 +863,7 @@ export const FormRenderer = ({
   adminConfig,
   useAsTitle,
   useAsPath,
+  advertiseLocales,
   headingLabel,
   headerSlot,
   collectionPath,
@@ -873,6 +900,7 @@ export const FormRenderer = ({
         adminConfig={adminConfig}
         useAsTitle={useAsTitle}
         useAsPath={useAsPath}
+        advertiseLocales={advertiseLocales}
         headingLabel={headingLabel}
         headerSlot={headerSlot}
         collectionPath={collectionPath}

package/src/react.ts

@@ -71,6 +71,7 @@ export * from './presentation/row.js'
 export * from './presentation/tabs.js'
 // Collection-editor-shared widgets.
 export * from './widgets/diff-viewer/diff-modal.js'
+export * from './widgets/source-locale-badge/source-locale-badge.js'
 export * from './widgets/status-badge/status-badge.js'
 // Field-side service contract types.
 export type {

package/src/widgets/source-locale-badge/source-locale-badge.module.css

@@ -0,0 +1,17 @@
+/**
+ * SourceLocaleBadge — compact neutral pill marking a document's content source
+ * locale, shown next to the document title in edit and list views.
+ *
+ * Override handle: `.byline-source-locale-badge`
+ */
+
+.badge,
+:global(.byline-source-locale-badge) {
+  margin-left: 0.5rem;
+  padding: 0 0.375rem;
+  font-size: 0.65rem;
+  font-weight: var(--font-weight-semibold);
+  line-height: 1.5;
+  letter-spacing: var(--letter-spacing-wide);
+  vertical-align: middle;
+}

package/src/widgets/source-locale-badge/source-locale-badge.tsx

@@ -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 { Badge } from '@byline/ui/react'
+import cx from 'classnames'
+
+import styles from './source-locale-badge.module.css'
+
+export interface SourceLocaleBadgeProps {
+  /** The document's content source locale code (e.g. `en`, `fr`). */
+  locale: string
+  className?: string
+}
+
+/**
+ * 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/DEFAULT-LOCALE-SWITCHING.md (Slice 6).
+ *
+ * Stable override handle: `.byline-source-locale-badge`.
+ */
+export const SourceLocaleBadge = ({ locale, className }: SourceLocaleBadgeProps) => (
+  <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'