@byline/admin 6.1.0 → 6.2.1

package/dist/forms/use-form-submission.d.ts

@@ -0,0 +1,74 @@
+import type { Field } from '@byline/core';
+import type { DocumentPatch } from '@byline/core/patches';
+/**
+ * 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/08-internationalization/index.md.
+ */
+export interface SystemFieldsSubmitPayload {
+    data: any;
+    patches: DocumentPatch[];
+    contentDirty: boolean;
+    pathDirty: boolean;
+    systemPath?: string | null;
+    availableLocalesDirty: boolean;
+    systemAvailableLocales?: string[];
+}
+/**
+ * Where a save has got to. Mutually exclusive by construction: the form cannot
+ * be validating and uploading at once, which two independent booleans allowed.
+ */
+export type SubmissionPhase = {
+    kind: 'idle';
+} | {
+    kind: 'validating';
+} | {
+    kind: 'uploading';
+} | {
+    kind: 'confirmingSystemFields';
+    payload: SystemFieldsSubmitPayload;
+} | {
+    kind: 'submitting';
+};
+export interface UseFormSubmissionOptions {
+    mode: 'create' | 'edit';
+    fields: Field[];
+    /** Persisted document id (edit mode only); feeds server-side upload hooks. */
+    documentId?: string;
+    /**
+     * Only collections that opted into the advertised-locale widget emit the
+     * locale set, so the write path never touches
+     * `byline_document_available_locales` for the others.
+     */
+    advertiseLocales?: boolean;
+    onSubmit: (payload: SystemFieldsSubmitPayload) => void | Promise<void>;
+    /** Mutations blocked (stale/lock/discarding). Read synchronously, per call. */
+    isBlocked: () => boolean;
+    /**
+     * Called immediately before the form becomes `inert` — once before uploads
+     * and once before submission — so the caller can record the focused element
+     * and restore it when busy ends. The DOM refs stay in the component; the
+     * hook only signals the transition.
+     */
+    onBeforeBusy?: () => void;
+}
+export interface UseFormSubmissionResult {
+    phase: SubmissionPhase;
+    isBusy: boolean;
+    submit: () => Promise<void>;
+    confirmSystemFields: () => Promise<void>;
+    cancelSystemFields: () => void;
+}
+/**
+ * Owns one save: validate → upload → (confirm) → submit.
+ *
+ * Admission is decided by a ref, not by `phase`. Rendered state is not a
+ * re-entry guard: two `submit()` calls in the same turn both observe
+ * `phase.kind === 'idle'` because React has not rerendered between them. The
+ * ref is set synchronously at the top of `submit()` and cleared in `finally`,
+ * spanning validation through submission — the whole window, not just the
+ * final request. `phase` drives the UI; the ref decides admission.
+ */
+export declare function useFormSubmission(options: UseFormSubmissionOptions): UseFormSubmissionResult;

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

@@ -0,0 +1,166 @@
+"use client";
+import { useCallback, useRef, useState } from "react";
+import { useTranslation } from "@byline/i18n/react";
+import { useBylineFieldServices } from "../fields/field-services-context.js";
+import { useFormContext } from "./form-context.js";
+import { executeUploadsWithProgress } from "./upload-executor.js";
+const IDLE = {
+    kind: 'idle'
+};
+function useFormSubmission(options) {
+    const { mode, fields, documentId, advertiseLocales, onSubmit, isBlocked, onBeforeBusy } = options;
+    const { getFieldValues, runFieldHooks, validateForm, resetHasChanges, getPatches, getDirtyBreakdown, getSystemPath, getSystemAvailableLocales, setFieldValue, setFieldError, getPendingUploads, clearPendingUploads, setFieldUploading } = useFormContext();
+    const { t } = useTranslation('byline-admin');
+    const { uploadField } = useBylineFieldServices();
+    const [phase, setPhase] = useState(IDLE);
+    const inFlightRef = useRef(false);
+    const isBusy = 'uploading' === phase.kind || 'submitting' === phase.kind;
+    const deliver = useCallback(async (payload)=>{
+        if (isBlocked() || 'function' != typeof onSubmit) return void setPhase(IDLE);
+        onBeforeBusy?.();
+        setPhase({
+            kind: 'submitting'
+        });
+        try {
+            await onSubmit(payload);
+            resetHasChanges();
+        } catch  {} finally{
+            setPhase(IDLE);
+        }
+    }, [
+        isBlocked,
+        onBeforeBusy,
+        onSubmit,
+        resetHasChanges
+    ]);
+    const runUploads = useCallback(async ()=>{
+        const pendingUploads = getPendingUploads();
+        if (0 === pendingUploads.size) return true;
+        onBeforeBusy?.();
+        setPhase({
+            kind: 'uploading'
+        });
+        try {
+            const uploadResult = await executeUploadsWithProgress(pendingUploads, uploadField, ({ fieldPath, status })=>{
+                setFieldUploading(fieldPath, 'uploading' === status);
+            }, {
+                documentId: 'edit' === mode ? documentId : void 0,
+                fields,
+                getFormValues: getFieldValues
+            });
+            if (!uploadResult.allSucceeded) {
+                for (const [fieldPath, errorMessage] of uploadResult.errors.entries())setFieldError(fieldPath, t('forms.uploadFailedFieldError', {
+                    message: errorMessage
+                }));
+                console.error('One or more uploads failed:', uploadResult.errors);
+                return false;
+            }
+            for (const [fieldPath, storedFile] of uploadResult.successful.entries())setFieldValue(fieldPath, storedFile);
+            clearPendingUploads();
+            return true;
+        } catch (err) {
+            console.error('Upload execution error:', err);
+            return false;
+        }
+    }, [
+        clearPendingUploads,
+        documentId,
+        fields,
+        getFieldValues,
+        getPendingUploads,
+        mode,
+        onBeforeBusy,
+        setFieldError,
+        setFieldUploading,
+        setFieldValue,
+        t,
+        uploadField
+    ]);
+    const buildPayload = useCallback(()=>{
+        const { contentDirty, pathDirty, availableLocalesDirty, reason } = getDirtyBreakdown();
+        return {
+            reason,
+            payload: {
+                data: getFieldValues(),
+                patches: getPatches(),
+                contentDirty,
+                pathDirty,
+                systemPath: getSystemPath(),
+                availableLocalesDirty,
+                systemAvailableLocales: advertiseLocales ? getSystemAvailableLocales() : void 0
+            }
+        };
+    }, [
+        advertiseLocales,
+        getDirtyBreakdown,
+        getFieldValues,
+        getPatches,
+        getSystemAvailableLocales,
+        getSystemPath
+    ]);
+    const submit = useCallback(async ()=>{
+        if (isBlocked()) return;
+        if (inFlightRef.current) return;
+        inFlightRef.current = true;
+        try {
+            setPhase({
+                kind: 'validating'
+            });
+            const hookErrors = await runFieldHooks(fields);
+            const formErrors = validateForm(fields);
+            const allErrors = [
+                ...hookErrors,
+                ...formErrors
+            ];
+            if (allErrors.length > 0) {
+                console.error('Form validation failed:', allErrors);
+                setPhase(IDLE);
+                return;
+            }
+            if (isBlocked()) return void setPhase(IDLE);
+            if (!await runUploads()) return void setPhase(IDLE);
+            const { payload, reason } = buildPayload();
+            if ('edit' === mode && ('direct-write' === reason || 'both' === reason)) return void setPhase({
+                kind: 'confirmingSystemFields',
+                payload
+            });
+            await deliver(payload);
+        } finally{
+            inFlightRef.current = false;
+        }
+    }, [
+        buildPayload,
+        deliver,
+        fields,
+        isBlocked,
+        mode,
+        runUploads,
+        runFieldHooks,
+        validateForm
+    ]);
+    const confirmSystemFields = useCallback(async ()=>{
+        if ('confirmingSystemFields' !== phase.kind) return;
+        if (inFlightRef.current) return;
+        inFlightRef.current = true;
+        const { payload } = phase;
+        try {
+            await deliver(payload);
+        } finally{
+            inFlightRef.current = false;
+        }
+    }, [
+        deliver,
+        phase
+    ]);
+    const cancelSystemFields = useCallback(()=>{
+        setPhase((current)=>'confirmingSystemFields' === current.kind ? IDLE : current);
+    }, []);
+    return {
+        phase,
+        isBusy,
+        submit,
+        confirmSystemFields,
+        cancelSystemFields
+    };
+}
+export { useFormSubmission };

package/dist/forms/use-form-tabs.d.ts

@@ -0,0 +1,29 @@
+import type { TabDefinition, TabSetDefinition } from '@byline/core';
+/** One tab set, resolved against live form data and current errors. */
+export interface ResolvedTabSet {
+    /** Tabs whose `condition` is satisfied, in declaration order. */
+    visibleTabs: TabDefinition[];
+    /** The tab that should render, after falling back off a hidden selection. */
+    activeTabName: string;
+    activeTab: TabDefinition | undefined;
+    /** Error count per tab name, for the tab bar's badges. */
+    errorCounts: Record<string, number> | undefined;
+}
+export interface UseFormTabsResult {
+    resolve: (set: TabSetDefinition) => ResolvedTabSet;
+    errorCountsBySet: Record<string, Record<string, number>>;
+}
+/**
+ * Tab visibility, per-tab error counts, and fallback when the selected tab is
+ * hidden.
+ *
+ * It deliberately does **not** own the selection. `FormRenderer` lifts that
+ * above the keyed `FormProvider` so the editor's tab choices survive the
+ * remount a locale change triggers; a hook living inside that subtree would
+ * lose them on every switch. The selection arrives as `activeTabBySet` and
+ * changes are reported upward.
+ */
+export declare function useFormTabs(fieldToTabPath: Map<string, {
+    tabSetName: string;
+    tabName: string;
+}>, activeTabBySet: Record<string, string>): UseFormTabsResult;

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

@@ -0,0 +1,45 @@
+"use client";
+import { useEffect, useMemo, useState } from "react";
+import { useFormContext } from "./form-context.js";
+function useFormTabs(fieldToTabPath, activeTabBySet) {
+    const { errors: initialErrors, subscribeErrors, subscribeMeta, getFieldValues } = useFormContext();
+    const [errors, setErrors] = useState(initialErrors);
+    useEffect(()=>subscribeErrors((newErrors)=>setErrors(newErrors)), [
+        subscribeErrors
+    ]);
+    const [formData, setFormData] = useState(()=>getFieldValues());
+    useEffect(()=>subscribeMeta(()=>setFormData(getFieldValues())), [
+        subscribeMeta,
+        getFieldValues
+    ]);
+    const errorCountsBySet = useMemo(()=>{
+        const result = {};
+        for (const err of errors){
+            const path = fieldToTabPath.get(err.field);
+            if (path) {
+                result[path.tabSetName] ??= {};
+                result[path.tabSetName][path.tabName] = (result[path.tabSetName]?.[path.tabName] ?? 0) + 1;
+            }
+        }
+        return result;
+    }, [
+        errors,
+        fieldToTabPath
+    ]);
+    const resolve = (set)=>{
+        const visibleTabs = set.tabs.filter((tab)=>!tab.condition || tab.condition(formData));
+        const requested = activeTabBySet[set.name] ?? '';
+        const activeTabName = visibleTabs.length > 0 && !visibleTabs.some((t)=>t.name === requested) ? visibleTabs[0]?.name ?? requested : requested;
+        return {
+            visibleTabs,
+            activeTabName,
+            activeTab: visibleTabs.find((t)=>t.name === activeTabName),
+            errorCounts: errorCountsBySet[set.name]
+        };
+    };
+    return {
+        resolve,
+        errorCountsBySet
+    };
+}
+export { useFormTabs };

package/dist/presentation/tab-strip-drag.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 state for click-and-drag scrolling of the tab strip.
+ *
+ * The DOM plumbing — pointer capture, the click suppression, the cursor —
+ * lives in `tabs.tsx`; the rules it follows are here so they can be tested
+ * without a pointer.
+ */
+/**
+ * How far the pointer must travel before the gesture stops being a click and
+ * becomes a drag.
+ *
+ * Without a threshold every click on a tab would nudge the strip by a pixel or
+ * two, and the click suppression that follows a drag would swallow the very
+ * clicks that select tabs.
+ */
+export declare const DRAG_THRESHOLD_PX = 5;
+/**
+ * How long after a drag a click is treated as that drag's own click.
+ *
+ * A window rather than a consume-once flag, because the click is not
+ * guaranteed to arrive: a drag released outside the strip produces none, and
+ * a flag left armed would swallow the reader's next deliberate click on a tab.
+ * Far longer than the browser's synthetic click takes to arrive, far shorter
+ * than anyone can release and deliberately click again.
+ */
+export declare const CLICK_SUPPRESSION_MS = 100;
+/** Where a gesture began. An internal part of `DragState`, not a public type. */
+interface DragOrigin {
+    /** Pointer x at the moment the button went down. */
+    pointerX: number;
+    /** The viewport's scroll offset at that same moment. */
+    scrollLeft: number;
+}
+export interface DragState {
+    origin: DragOrigin;
+    /** Whether the threshold has already been crossed. */
+    dragging: boolean;
+}
+export interface DragAdvance {
+    dragging: boolean;
+    /** The offset to scroll to, or `null` while the gesture is still a click. */
+    scrollLeft: number | null;
+}
+/**
+ * Whether a `pointerdown` should begin a potential drag.
+ *
+ * Mouse only. Touch and pen already scroll the viewport natively, with
+ * momentum and rubber-banding that a hand-rolled drag does not reproduce, so
+ * taking the gesture over would trade a good interaction for a worse one.
+ */
+export declare function shouldStartDrag({ pointerType, button, overflowing, }: {
+    pointerType: string;
+    button: number;
+    overflowing: boolean;
+}): boolean;
+/**
+ * Advance a gesture given the pointer's current x.
+ *
+ * Returns `scrollLeft: null` while the pointer is still within the threshold,
+ * so the caller leaves the viewport alone and lets the click through.
+ */
+export declare function advanceDrag({ origin, dragging }: DragState, pointerX: number, maxScroll: number): DragAdvance;
+/**
+ * Whether a click arriving now belongs to a drag that has just ended, and
+ * should therefore not reach the tab underneath.
+ */
+export declare function shouldSuppressClick(dragEndedAt: number | null, now: number): boolean;
+export {};

package/dist/presentation/tab-strip-drag.js

@@ -0,0 +1,25 @@
+const DRAG_THRESHOLD_PX = 5;
+const CLICK_SUPPRESSION_MS = 100;
+function shouldStartDrag({ pointerType, button, overflowing }) {
+    if ('mouse' !== pointerType) return false;
+    if (0 !== button) return false;
+    return overflowing;
+}
+function advanceDrag({ origin, dragging }, pointerX, maxScroll) {
+    const delta = pointerX - origin.pointerX;
+    const isDragging = dragging || Math.abs(delta) >= DRAG_THRESHOLD_PX;
+    if (false === isDragging) return {
+        dragging: false,
+        scrollLeft: null
+    };
+    const next = origin.scrollLeft - delta;
+    return {
+        dragging: true,
+        scrollLeft: Math.min(Math.max(next, 0), maxScroll)
+    };
+}
+function shouldSuppressClick(dragEndedAt, now) {
+    if (null == dragEndedAt) return false;
+    return now - dragEndedAt < CLICK_SUPPRESSION_MS;
+}
+export { CLICK_SUPPRESSION_MS, DRAG_THRESHOLD_PX, advanceDrag, shouldStartDrag, shouldSuppressClick };

package/dist/presentation/tab-strip-drag.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/presentation/tab-strip-geometry.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 StripMeasurements {
+    /**
+     * Intrinsic content width of the tablist row.
+     *
+     * The row is laid out at `max-content`, so this is the width the tabs want
+     * regardless of how much room the viewport currently gives them. A row that
+     * shrank to its container would report the container's width back and the
+     * strip could never detect overflow at all.
+     */
+    rowWidth: number;
+    /**
+     * Usable width of the strip container.
+     *
+     * Independent of whether the trigger is rendered — the container is sized by
+     * the layout above it, not by its own children.
+     */
+    containerWidth: number;
+    /** Width the overflow trigger occupies when it is rendered. */
+    triggerWidth: number;
+    /** Gap between the viewport and the trigger. */
+    triggerGap: number;
+    /** Current horizontal scroll offset of the viewport. */
+    scrollLeft: number;
+}
+export interface StripState {
+    /** Whether the row needs the scrolling viewport and the overflow trigger. */
+    overflowing: boolean;
+    /** Width available to the scrolling viewport. */
+    viewportWidth: number;
+    /** Whether the viewport is scrolled fully left (hides the leading fade). */
+    atStart: boolean;
+    /** Whether the viewport is scrolled fully right (hides the trailing fade). */
+    atEnd: boolean;
+}
+export interface RevealMeasurements {
+    viewportWidth: number;
+    scrollLeft: number;
+    /** The tab's offset from the start of the row. */
+    tabOffsetLeft: number;
+    tabWidth: number;
+    rowWidth: number;
+    padding?: number;
+}
+/**
+ * Resolve whether the strip overflows, and where it sits within its scroll
+ * range.
+ *
+ * Overflow is decided against the bare container, and deliberately takes no
+ * account of the trigger: a row that fits the container fits, and reserving
+ * the trigger's width first would summon a menu for tabs that were never cut
+ * off. The trigger is subtracted only afterwards, to size the viewport it now
+ * shares the container with.
+ *
+ * That ordering is also what keeps the result stable. The trigger's presence
+ * changes the viewport but never `containerWidth` — which the layout above
+ * sets — and never `rowWidth`, which the row holds at `max-content`. So the
+ * overflow answer cannot feed back into its own inputs.
+ */
+export declare function computeStripState({ rowWidth, containerWidth, triggerWidth, triggerGap, scrollLeft, }: StripMeasurements): StripState;
+/**
+ * The scroll offset that brings one tab into view, or `null` when the tab is
+ * already visible and the viewport should be left untouched.
+ *
+ * Returning `null` rather than the current offset is the point: this runs on
+ * selection and on focus, and writing `scrollLeft` unconditionally would
+ * cancel a scroll the reader is in the middle of.
+ */
+export declare function computeRevealScroll({ viewportWidth, scrollLeft, tabOffsetLeft, tabWidth, rowWidth, padding, }: RevealMeasurements): number | null;

package/dist/presentation/tab-strip-geometry.js

@@ -0,0 +1,36 @@
+const EDGE_EPSILON = 1;
+const DEFAULT_REVEAL_PADDING = 8;
+function computeStripState({ rowWidth, containerWidth, triggerWidth, triggerGap, scrollLeft }) {
+    const measured = containerWidth > 0;
+    const overflowing = measured && rowWidth > containerWidth;
+    if (false === overflowing) return {
+        overflowing: false,
+        viewportWidth: Math.max(0, containerWidth),
+        atStart: true,
+        atEnd: true
+    };
+    const viewportWidth = Math.max(0, containerWidth - triggerWidth - triggerGap);
+    const maxScroll = Math.max(0, rowWidth - viewportWidth);
+    return {
+        overflowing: true,
+        viewportWidth,
+        atStart: scrollLeft <= EDGE_EPSILON,
+        atEnd: scrollLeft >= maxScroll - EDGE_EPSILON
+    };
+}
+function computeRevealScroll({ viewportWidth, scrollLeft, tabOffsetLeft, tabWidth, rowWidth, padding = DEFAULT_REVEAL_PADDING }) {
+    const maxScroll = Math.max(0, rowWidth - viewportWidth);
+    const clamp = (value)=>Math.min(Math.max(value, 0), maxScroll);
+    const leadingEdge = tabOffsetLeft - padding;
+    const trailingEdge = tabOffsetLeft + tabWidth + padding;
+    let next;
+    if (tabWidth + 2 * padding >= viewportWidth) next = leadingEdge;
+    else if (leadingEdge < scrollLeft) next = leadingEdge;
+    else {
+        if (!(trailingEdge > scrollLeft + viewportWidth)) return null;
+        next = trailingEdge - viewportWidth;
+    }
+    const clamped = clamp(next);
+    return clamped === scrollLeft ? null : clamped;
+}
+export { computeRevealScroll, computeStripState };

package/dist/presentation/tab-strip-geometry.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/presentation/tabs.d.ts

@@ -6,20 +6,43 @@ interface AdminTabsProps {
     tabs: AdminTabItem[];
     activeTab: string;
     onChange: (name: string) => void;
+    /**
+     * Prefix for the generated tab and panel ids. The consumer that renders the
+     * panels builds its panel ids from the same base via `tabPanelId`, which is
+     * what associates the two halves for assistive technology.
+     */
+    idBase: string;
     /** Error counts keyed by tab name — shows a danger badge when > 0. */
     errorCounts?: Record<string, number>;
     className?: string;
 }
+/** Id of the button for one tab. */
+export declare const tabTriggerId: (idBase: string, name: string) => string;
+/** Id the consumer must put on the panel belonging to one tab. */
+export declare const tabPanelId: (idBase: string, name: string) => string;
 /**
  * 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.
+ * Used by FormRenderer when a CollectionAdminConfig declares a `tabs` array,
+ * and by the collection history view. The number of tabs a collection can
+ * declare is unbounded while the column they sit in is not, so the strip
+ * scrolls horizontally and — only once the tabs genuinely exceed the column —
+ * grows a menu listing every tab.
  *
- * Stable override handles: `.byline-admin-tabs`, `.byline-admin-tab`,
- * `.byline-admin-tab-active`, `.byline-admin-tab-label`,
- * `.byline-admin-tab-badge`.
+ * The menu is a jump list rather than a list of the tabs that happen to be
+ * out of view: its contents stay put as the strip scrolls, and no tab ever
+ * changes position in the strip as a result of being selected. Editors learn
+ * where a tab lives and it stays there.
+ *
+ * Scroll position is moved only when the selection changes or a tab takes
+ * focus. A reader who scrolls the strip to look at other labels keeps their
+ * position through re-measurement, re-render and resize.
+ *
+ * Stable override handles: `.byline-admin-tabs`, `.byline-admin-tabs-viewport`,
+ * `.byline-admin-tablist`, `.byline-admin-tab`, `.byline-admin-tab-active`,
+ * `.byline-admin-tab-label`, `.byline-admin-tab-badge`,
+ * `.byline-admin-tabs-overflow-trigger`, `.byline-admin-tabs-overflow-menu`,
+ * `.byline-admin-tabs-overflow-item`.
  */
-export declare const AdminTabs: ({ tabs, activeTab, onChange, errorCounts, className, }: AdminTabsProps) => import("react").JSX.Element;
+export declare const AdminTabs: ({ tabs, activeTab, onChange, idBase, errorCounts, className, }: AdminTabsProps) => import("react").JSX.Element;
 export {};