Import .bloomSource files into a collection, with duplicate-by-id handling (BL-16502)

DistFiles/localization/en/BloomMediumPriority.xlf

@@ -739,6 +739,71 @@
         <source xml:lang="en">Problem</source>
         <note>CollectionTab.OnBlorgBadge.Problem</note>
       </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource" translate="no">
+        <source xml:lang="en">Import .bloomSource File(s)</source>
+        <note>ID: CollectionTab.ImportBloomSource</note>
+        <note>Menu command (and dialog title) that imports one or more books from .bloomSource files into the current collection. Keep ".bloomSource" unchanged; it is a file extension.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.ChoiceTitle" translate="no">
+        <source xml:lang="en">Import books</source>
+        <note>ID: CollectionTab.ImportBloomSource.ChoiceTitle</note>
+        <note>Title of the dialogs shown while importing .bloomSource file(s): the one that asks whether to import for editing or as derivatives, and the one that asks how to handle books already in the collection.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.EditChoice" translate="no">
+        <source xml:lang="en">Import for editing</source>
+        <note>ID: CollectionTab.ImportBloomSource.EditChoice</note>
+        <note>Radio-button choice in the import dialog: import the book(s) to edit them directly.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.EditChoiceDescription" translate="no">
+        <source xml:lang="en">Preserve everything.</source>
+        <note>ID: CollectionTab.ImportBloomSource.EditChoiceDescription</note>
+        <note>Explanation shown under the "Import for editing" radio-button choice in the import dialog.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.DerivativeChoice" translate="no">
+        <source xml:lang="en">Import as derivatives — new books based on the originals</source>
+        <note>ID: CollectionTab.ImportBloomSource.DerivativeChoice</note>
+        <note>Radio-button choice in the import dialog: use the imported book(s) as the basis for new derivative books (e.g. translations).</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.DerivativeChoiceDescription" translate="no">
+        <source xml:lang="en">Use a new book ID &amp; make room for new copyright and credits while preserving those of the original.</source>
+        <note>ID: CollectionTab.ImportBloomSource.DerivativeChoiceDescription</note>
+        <note>Explanation shown under the "Import as derivatives" radio-button choice in the import dialog.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.DuplicatePrompt" translate="no">
+        <source xml:lang="en">Some of these books are already in this collection.</source>
+        <note>ID: CollectionTab.ImportBloomSource.DuplicatePrompt</note>
+        <note>Shown once when importing .bloomSource file(s), if any of the books is already in the collection.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.Replace" translate="no">
+        <source xml:lang="en">Replace the existing books</source>
+        <note>ID: CollectionTab.ImportBloomSource.Replace</note>
+        <note>Radio-button choice in the import duplicate prompt: replace the existing book(s) with the imported one(s).</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.ReplaceDescription" translate="no">
+        <source xml:lang="en">The current copies will be overwritten.</source>
+        <note>ID: CollectionTab.ImportBloomSource.ReplaceDescription</note>
+        <note>Secondary line under the "Replace the existing books" choice in the import duplicate prompt.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.ReplaceNeedsCheckout" translate="no">
+        <source xml:lang="en">All books must be checked out</source>
+        <note>ID: CollectionTab.ImportBloomSource.ReplaceNeedsCheckout</note>
+        <note>Secondary line under the "Replace the existing books" choice in the import duplicate prompt, shown (and the choice disabled) when the collection is a Team Collection and one or more of the books being replaced is not checked out.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.AddCopy" translate="no">
+        <source xml:lang="en">Add them as new copies</source>
+        <note>ID: CollectionTab.ImportBloomSource.AddCopy</note>
+        <note>Radio-button choice in the import duplicate prompt: keep the existing book(s) and add the imported one(s) as new copies.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.AddCopyDescription" translate="no">
+        <source xml:lang="en">The existing books stay as they are.</source>
+        <note>ID: CollectionTab.ImportBloomSource.AddCopyDescription</note>
+        <note>Secondary line under the "Add them as new copies" choice in the import duplicate prompt.</note>
+      </trans-unit>
+      <trans-unit id="CollectionTab.ImportBloomSource.Importing" translate="no">
+        <source xml:lang="en">Importing Books</source>
+        <note>ID: CollectionTab.ImportBloomSource.Importing</note>
+        <note>Title of the progress dialog shown while .bloomSource file(s) are being imported.</note>
+      </trans-unit>
       <trans-unit id="BookSettings.LockedByBranding" sil:dynamic="true">
         <source xml:lang="en">Locked by {0} Branding</source>
         <note>BookSettings.LockedByBranding</note>

src/BloomBrowserUI/collectionsTab/CollectionsTabPane.tsx

@@ -1,6 +1,6 @@
 import { css } from "@emotion/react";
 import * as React from "react";
-import { get, post, postString } from "../utils/bloomApi";
+import { get, post, postData, postString } from "../utils/bloomApi";
 import { BooksOfCollection, IBookInfo } from "./BooksOfCollection";
 import { makeMenuItems, MenuItemSpec } from "./menuHelpers";
 import { Transition } from "react-transition-group";
@@ -25,6 +25,7 @@ import { EmbeddedProgressDialog } from "../react_components/Progress/ProgressDia
 import { useSubscribeToWebSocketForObject } from "../utils/WebSocketManager";
 import CloseIcon from "@mui/icons-material/Close";
 import FolderOpenOutlinedIcon from "@mui/icons-material/FolderOpenOutlined";
+import { ImportIcon } from "../react_components/icons/ImportIcon";
 import { kBloomBlue } from "../bloomMaterialUITheme";
 import { BloomTooltip } from "../react_components/BloomToolTip";
 import { Link } from "../react_components/link";
@@ -37,6 +38,7 @@ import {
     showMakeReaderTemplateBloomPackDialog,
 } from "../react_components/makeReaderTemplateBloomPackDialog";
 import { AboutDialogLauncher } from "../react_components/aboutDialog";
+import { RadioChoiceDialog } from "./RadioChoiceDialog";
 
 const kResizerSize = 10;
 
@@ -197,6 +199,89 @@ export const CollectionsTabPane: React.FunctionComponent = () => {
         | undefined
     >();
 
+    // The .bloomSource import decision. The file(s) are chosen first (via C#), which in the same
+    // reply tells us whether any chosen book is already in the collection; based on that we show the
+    // user exactly one dialog for the whole batch. If none are present, Dialog 1 asks whether to edit
+    // the book(s) or make derivatives. If any are present, Dialog 2 asks whether to replace the
+    // existing book(s) or add the imported ones as new copies. The user never sees both. We hold the
+    // chosen paths here and pass them back to the import call; the backend keeps no state between
+    // calls.
+    const [importFiles, setImportFiles] = useState<string[]>([]);
+    const [showImportSourceChoiceDialog, setShowImportSourceChoiceDialog] =
+        useState(false);
+    const [showImportDuplicateDialog, setShowImportDuplicateDialog] =
+        useState(false);
+    // Whether the "Replace" duplicate choice is allowed for this batch. In a Team Collection a book
+    // can only be replaced if it is checked out here; when any duplicate isn't, Replace is disabled.
+    const [importCanReplace, setImportCanReplace] = useState(true);
+
+    const importChoiceTitle = useL10n(
+        "Import books",
+        "CollectionTab.ImportBloomSource.ChoiceTitle",
+    );
+    const importEditChoiceLabel = useL10n(
+        "Import for editing",
+        "CollectionTab.ImportBloomSource.EditChoice",
+    );
+    const importEditChoiceDescription = useL10n(
+        "Preserve everything.",
+        "CollectionTab.ImportBloomSource.EditChoiceDescription",
+    );
+    const importDerivativeChoiceLabel = useL10n(
+        "Import as derivatives — new books based on the originals",
+        "CollectionTab.ImportBloomSource.DerivativeChoice",
+    );
+    const importDerivativeChoiceDescription = useL10n(
+        "Use a new book ID & make room for new copyright and credits while preserving those of the original.",
+        "CollectionTab.ImportBloomSource.DerivativeChoiceDescription",
+    );
+    const importDuplicateMessage = useL10n(
+        "Some of these books are already in this collection.",
+        "CollectionTab.ImportBloomSource.DuplicatePrompt",
+    );
+    const importReplaceLabel = useL10n(
+        "Replace the existing books",
+        "CollectionTab.ImportBloomSource.Replace",
+    );
+    const importReplaceDescription = useL10n(
+        "The current copies will be overwritten.",
+        "CollectionTab.ImportBloomSource.ReplaceDescription",
+    );
+    const importReplaceNeedsCheckoutDescription = useL10n(
+        "All books must be checked out",
+        "CollectionTab.ImportBloomSource.ReplaceNeedsCheckout",
+    );
+    const importAddCopyLabel = useL10n(
+        "Add them as new copies",
+        "CollectionTab.ImportBloomSource.AddCopy",
+    );
+    const importAddCopyDescription = useL10n(
+        "The existing books stay as they are.",
+        "CollectionTab.ImportBloomSource.AddCopyDescription",
+    );
+
+    // Dialog 1 (shown only when no chosen book is already in the collection): the user chose to
+    // edit the book(s) as-is or make derivatives (or cancelled). Neither path has a duplicate to
+    // resolve, so import immediately.
+    const handleImportSourceChoice = (choice?: string) => {
+        setShowImportSourceChoiceDialog(false);
+        if (!choice) return;
+        const mode = choice === "derivative" ? "derivative" : "edit";
+        postData(`collections/importBloomSource?mode=${mode}`, importFiles);
+    };
+
+    // Dialog 2 (shown only when at least one chosen book is already in the collection): the user
+    // chose to replace the existing book(s) or add the imported ones as new copies. That single
+    // choice applies to every duplicate in the batch.
+    const handleImportDuplicateChoice = (choice?: string) => {
+        setShowImportDuplicateDialog(false);
+        if (!choice) return;
+        postData(
+            `collections/importBloomSource?mode=edit&onDuplicate=${choice}`,
+            importFiles,
+        );
+    };
+
     const setAdjustedContextMenuPoint = (x: number, y: number) => {
         setContextMousePoint({
             mouseX: x - 2,
@@ -277,6 +362,33 @@ export const CollectionsTabPane: React.FunctionComponent = () => {
             command: "workspace/openOrCreateCollection",
             addEllipsis: true,
         },
+        {
+            label: "Import .bloomSource File(s)",
+            l10nId: "CollectionTab.ImportBloomSource",
+            icon: <ImportIcon />,
+            onClick: () => {
+                handleClose();
+                // Choose the file(s) first; the reply tells us both the chosen paths and whether any
+                // chosen book is already in the collection, so we can show the one dialog that fits.
+                //
+                // Note that when a chosen book is already in the collection we deliberately do NOT
+                // offer the edit-vs-derivative choice: the duplicate dialog always imports in edit
+                // mode, so you can't make a derivative of a book that's already in your collection. We
+                // couldn't think of a plausible scenario where you have a book and a true derivative
+                // of it in the same collection, so this path isn't worth the extra complexity. Easy
+                // to reverse if that turns out to be wrong.
+                post("collections/chooseBloomSourceFilesToImport", (r) => {
+                    const files: string[] = r.data.files;
+                    if (!files || files.length === 0) return; // the user cancelled the picker
+                    setImportFiles(files);
+                    if (r.data.anyDuplicates) {
+                        setImportCanReplace(r.data.canReplace);
+                        setShowImportDuplicateDialog(true);
+                    } else setShowImportSourceChoiceDialog(true);
+                });
+            },
+            addEllipsis: true,
+        },
         {
             label: "Make Bloom Pack of Shell Books",
             l10nId: "CollectionTab.MakeBloomPackOfShellBooks",
@@ -587,6 +699,44 @@ export const CollectionsTabPane: React.FunctionComponent = () => {
             <CollectionSettingsDialog />
             <EmbeddedProgressDialog id="collectionTab" />
             <MakeReaderTemplateBloomPackDialog />
+            <RadioChoiceDialog
+                open={showImportSourceChoiceDialog}
+                title={importChoiceTitle}
+                options={[
+                    {
+                        value: "edit",
+                        label: importEditChoiceLabel,
+                        description: importEditChoiceDescription,
+                    },
+                    {
+                        value: "derivative",
+                        label: importDerivativeChoiceLabel,
+                        description: importDerivativeChoiceDescription,
+                    },
+                ]}
+                onClose={handleImportSourceChoice}
+            />
+            <RadioChoiceDialog
+                open={showImportDuplicateDialog}
+                title={importChoiceTitle}
+                message={importDuplicateMessage}
+                options={[
+                    {
+                        value: "replace",
+                        label: importReplaceLabel,
+                        description: importCanReplace
+                            ? importReplaceDescription
+                            : importReplaceNeedsCheckoutDescription,
+                        disabled: !importCanReplace,
+                    },
+                    {
+                        value: "addCopy",
+                        label: importAddCopyLabel,
+                        description: importAddCopyDescription,
+                    },
+                ]}
+                onClose={handleImportDuplicateChoice}
+            />
         </div>
     );
 };

src/BloomBrowserUI/collectionsTab/RadioChoiceDialog.tsx

@@ -0,0 +1,98 @@
+import { css } from "@emotion/react";
+import * as React from "react";
+import { useState, useEffect } from "react";
+import { RadioGroup } from "@mui/material";
+import { MuiRadio } from "../react_components/muiRadio";
+import {
+    BloomDialog,
+    DialogTitle,
+    DialogMiddle,
+    DialogBottomButtons,
+} from "../react_components/BloomDialog/BloomDialog";
+import {
+    DialogOkButton,
+    DialogCancelButton,
+} from "../react_components/BloomDialog/commonDialogComponents";
+
+export interface IRadioChoice {
+    value: string;
+    label: string; // already localized
+    description?: string; // optional already-localized secondary line shown under the label
+    disabled?: boolean; // when true the choice can't be selected (e.g. not currently allowed)
+}
+
+// A small, reusable dialog that offers a set of mutually-exclusive radio choices with OK and
+// Cancel. OK is disabled until the user selects one; Cancel is always available. It is rendered
+// inline as part of its parent screen; the parent controls `open` and receives the chosen value
+// (or undefined if the user cancelled) via `onClose`. All strings are passed in already localized.
+export const RadioChoiceDialog: React.FunctionComponent<{
+    open: boolean;
+    title: string;
+    message?: string;
+    options: IRadioChoice[];
+    onClose: (value?: string) => void;
+}> = (props) => {
+    const [choice, setChoice] = useState<string>();
+
+    // Start with nothing selected each time the dialog opens, so OK is disabled until the user picks.
+    // A useEffect is warranted here (per the repo's useEffect guidance) rather than the usual
+    // key-prop remount: this dialog is rendered inline and permanently mounted by its parent, which
+    // toggles `open` rather than mounting/unmounting us, so there is no remount to hang a key on.
+    // Keying the reset off `open` keeps that concern owned by the component that holds the state.
+    useEffect(() => {
+        if (props.open) setChoice(undefined);
+    }, [props.open]);
+
+    const cancel = () => props.onClose(undefined);
+
+    return (
+        <BloomDialog
+            open={props.open}
+            onClose={cancel}
+            onCancel={cancel}
+            dialogFrameProvidedExternally={false}
+        >
+            <DialogTitle title={props.title} />
+            <DialogMiddle
+                css={css`
+                    width: 400px;
+                `}
+            >
+                {props.message && (
+                    <p
+                        css={css`
+                            margin-top: 0;
+                        `}
+                    >
+                        {props.message}
+                    </p>
+                )}
+                <RadioGroup
+                    value={choice ?? ""}
+                    onChange={(e) => setChoice(e.target.value)}
+                >
+                    {props.options.map((o) => (
+                        <MuiRadio
+                            key={o.value}
+                            value={o.value}
+                            label={o.label}
+                            description={o.description}
+                            disabled={o.disabled}
+                            // The labels arrive already localized from the caller.
+                            alreadyLocalized={true}
+                            l10nKey=""
+                        />
+                    ))}
+                </RadioGroup>
+            </DialogMiddle>
+            <DialogBottomButtons>
+                <DialogOkButton
+                    default={true}
+                    enabled={choice !== undefined}
+                    onClick={() => props.onClose(choice)}
+                />
+                <DialogCancelButton />
+            </DialogBottomButtons>
+        </BloomDialog>
+    );
+};

src/BloomBrowserUI/react_components/icons/ImportIcon.tsx

@@ -0,0 +1,15 @@
+import SvgIcon, { SvgIconProps } from "@mui/material/SvgIcon";
+
+// An "import into a document" icon (arrow pointing into a page), used for the
+// "Import .bloomSource File(s)" collection menu item. Uses currentColor so it follows
+// the menu text color.
+export const ImportIcon = (props: SvgIconProps) => (
+    <SvgIcon viewBox="0 0 18 16" {...props}>
+        <path
+            d="M12 8L8 4V7H0V9H8V12M18 14V2C18 1.46957 17.7893 0.960859 17.4142 0.585786C17.0391 0.210714 16.5304 0 16 0H4C3.46957 0 2.96086 0.210714 2.58579 0.585786C2.21071 0.960859 2 1.46957 2 2V5H4V2H16V14H4V11H2V14C2 14.5304 2.21071 15.0391 2.58579 15.4142C2.96086 15.7893 3.46957 16 4 16H16C16.5304 16 17.0391 15.7893 17.4142 15.4142C17.7893 15.0391 18 14.5304 18 14Z"
+            fill="currentColor"
+        />
+    </SvgIcon>
+);
+
+export default ImportIcon;