cms-admin: Add in-toolbar translate button to TipTap rich text block

.changeset/tiptap-translate-button.md

@@ -0,0 +1,13 @@
+---
+"@dextinity/cms-admin": minor
+---
+
+Add an in-toolbar translate button to the TipTap rich text block
+
+The Draft.js-based rich text block already has a toolbar button to translate a single field, with an optional dialog to review the translation before applying it. The TipTap rich text block had no equivalent, leaving document-wide translation as the only option for TipTap fields.
+
+The button now appears in the TipTap toolbar whenever a `ContentTranslationServiceProvider` is enabled, and can be hidden per block with the new `contentTranslation` option:
+
+```tsx
+createTipTapRichTextBlock({ contentTranslation: false });
+```

packages/admin/cms-admin/src/blocks/tipTap/TipTapContentTranslationDialog.tsx

@@ -0,0 +1,45 @@
+import { BaseTranslationDialog } from "@dextinity/admin";
+import type { JSONContent } from "@tiptap/react";
+
+import { TipTapEditor, type TipTapEditorProps } from "./createTipTapRichTextBlock";
+
+interface TipTapContentTranslationDialogProps {
+    open: boolean;
+    onClose: () => void;
+    originalContent: JSONContent;
+    translatedContent: JSONContent;
+    onApplyTranslation: (content: JSONContent) => void;
+    editorProps: Pick<
+        TipTapEditorProps,
+        "resolvedOptions" | "textBlockStyles" | "inlineStyles" | "placeholders" | "linkBlock" | "childBlocks" | "maxTextBlocks" | "listLevelMax"
+    >;
+}
+
+export const TipTapContentTranslationDialog = ({
+    open,
+    onClose,
+    originalContent,
+    translatedContent,
+    onApplyTranslation,
+    editorProps,
+}: TipTapContentTranslationDialogProps) => (
+    <BaseTranslationDialog
+        open={open}
+        onClose={onClose}
+        originalText={originalContent}
+        translatedText={translatedContent}
+        onApplyTranslation={onApplyTranslation}
+        renderOriginalText={(content) => <TipTapEditor state={{ tipTapContent: content }} updateState={() => {}} {...editorProps} readOnly />}
+        renderTranslatedText={(content, onChange) => (
+            <TipTapEditor
+                state={{ tipTapContent: content }}
+                updateState={(next) => {
+                    const nextState = typeof next === "function" ? next({ tipTapContent: content }) : next;
+                    onChange(nextState.tipTapContent);
+                }}
+                {...editorProps}
+                resolvedOptions={{ ...editorProps.resolvedOptions, contentTranslation: false }}
+            />
+        )}
+    />
+);

packages/admin/cms-admin/src/blocks/tipTap/TipTapToolbar.tsx

@@ -19,6 +19,7 @@ import {
     RteUl,
     RteUnderlined,
     RteUndo,
+    Translate,
 } from "@dextinity/admin-icons";
 import {
     Box,
@@ -166,6 +167,8 @@ export const TipTapToolbar = ({
     linkBlock,
     childBlocks,
     listLevelMax,
+    canTranslate,
+    onTranslateClick,
 }: {
     editor: Editor;
     resolvedOptions: TipTapResolvedOptions;
@@ -175,6 +178,8 @@ export const TipTapToolbar = ({
     linkBlock?: BlockInterface & LinkBlockInterface;
     childBlocks: Record<string, TipTapChildBlock>;
     listLevelMax?: number;
+    canTranslate?: boolean;
+    onTranslateClick?: () => void;
 }) => {
     const intl = useIntl();
     const [moreAnchorEl, setMoreAnchorEl] = useState<null | HTMLElement>(null);
@@ -453,6 +458,16 @@ export const TipTapToolbar = ({
                     </FormControl>
                 </ToolbarGroup>
             )}
+            {canTranslate && (
+                <ToolbarGroup>
+                    <ToolbarButton
+                        editor={editor}
+                        icon={Translate}
+                        tooltip={<FormattedMessage id="dextinity.blocks.tipTapRichText.translate.tooltip" defaultMessage="Translate" />}
+                        onToggle={() => onTranslateClick?.()}
+                    />
+                </ToolbarGroup>
+            )}
             {(hasInlineFormatButtons || moreOptions || applicableInlineStyles.length > 0) && (
                 <ToolbarGroup>
                     {resolvedOptions.bold && (

packages/admin/cms-admin/src/blocks/tipTap/__stories__/TipTapRichTextBlockTranslation.stories.tsx

@@ -0,0 +1,205 @@
+import { ContentTranslationServiceProvider } from "@dextinity/admin";
+import { Box } from "@mui/material";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { type PropsWithChildren, type ReactNode, useState } from "react";
+import { expect, waitFor, within } from "storybook/test";
+
+import { createTipTapRichTextBlock, type TipTapRichTextBlockState } from "../createTipTapRichTextBlock";
+
+function StatePreview({ state }: { state: TipTapRichTextBlockState }) {
+    return (
+        <Box component="pre" sx={{ mt: 2, p: 2, backgroundColor: "#f5f5f5", fontSize: 12, overflow: "auto", borderRadius: 1 }}>
+            {JSON.stringify(state, null, 2)}
+        </Box>
+    );
+}
+
+function StoryWrapper({ children, state }: { children: ReactNode; state: TipTapRichTextBlockState }) {
+    return (
+        <>
+            {children}
+            <StatePreview state={state} />
+        </>
+    );
+}
+
+const config: Meta = {
+    title: "blocks/TipTapRichTextBlock/Translation",
+};
+
+export default config;
+
+const uppercaseTranslate = async (text: string): Promise<string> => text.toUpperCase();
+
+// Disabling every other feature makes the translate button the toolbar's sole (and thus unambiguous) button.
+const TranslationBlock = createTipTapRichTextBlock({
+    undoRedoButtons: false,
+    bold: false,
+    italic: false,
+    strike: false,
+    sub: false,
+    sup: false,
+    heading: false,
+    orderedList: false,
+    unorderedList: false,
+    nonBreakingSpace: false,
+    softHyphen: false,
+});
+
+const translationInitialState: TipTapRichTextBlockState = {
+    tipTapContent: { type: "doc", content: [{ type: "paragraph", content: [{ type: "text", text: "Hello world" }] }] },
+};
+
+function TranslationProvider({ children, showApplyTranslationDialog }: PropsWithChildren<{ showApplyTranslationDialog?: boolean }>) {
+    return (
+        <ContentTranslationServiceProvider enabled translate={uppercaseTranslate} showApplyTranslationDialog={showApplyTranslationDialog}>
+            {children}
+        </ContentTranslationServiceProvider>
+    );
+}
+
+function TranslationStory({ showApplyTranslationDialog }: { showApplyTranslationDialog?: boolean }) {
+    const [state, setState] = useState<TipTapRichTextBlockState>(translationInitialState);
+
+    return (
+        <TranslationProvider showApplyTranslationDialog={showApplyTranslationDialog}>
+            <StoryWrapper state={state}>
+                <TranslationBlock.AdminComponent state={state} updateState={setState} />
+            </StoryWrapper>
+        </TranslationProvider>
+    );
+}
+
+export const Translation: StoryObj<typeof TranslationStory> = {
+    render: () => <TranslationStory />,
+    play: async ({ canvas, userEvent, step }) => {
+        await step("Editor is ready with a translate button", async () => {
+            await waitFor(
+                () => {
+                    expect(canvas.getByRole("textbox")).toBeInTheDocument();
+                    expect(canvas.getByRole("button")).toBeInTheDocument();
+                },
+                { timeout: 5000 },
+            );
+        });
+
+        await step("Clicking translate replaces the content immediately (no review dialog)", async () => {
+            await userEvent.click(canvas.getByRole("button"));
+
+            await waitFor(
+                () => {
+                    expect(canvas.getByRole("textbox")).toHaveTextContent("HELLO WORLD");
+                },
+                { timeout: 3000 },
+            );
+        });
+    },
+};
+
+export const TranslationWithApplyDialog: StoryObj<typeof TranslationStory> = {
+    render: () => <TranslationStory showApplyTranslationDialog />,
+    play: async ({ canvas, userEvent, step }) => {
+        await step("Editor is ready with a translate button", async () => {
+            await waitFor(
+                () => {
+                    expect(canvas.getByRole("button")).toBeInTheDocument();
+                },
+                { timeout: 5000 },
+            );
+        });
+
+        await step("Clicking translate opens a review dialog with the original and translated content", async () => {
+            await userEvent.click(canvas.getByRole("button"));
+
+            await waitFor(
+                () => {
+                    expect(within(document.body).getByRole("heading", { name: "Translation", level: 2 })).toBeInTheDocument();
+                },
+                { timeout: 3000 },
+            );
+
+            const dialog = within(document.body).getByRole("dialog");
+            expect(within(dialog).getByText("Hello world")).toBeInTheDocument();
+            expect(within(dialog).getByText("HELLO WORLD")).toBeInTheDocument();
+        });
+
+        await step("Applying the translation updates the editor and closes the dialog", async () => {
+            await userEvent.click(within(document.body).getByRole("button", { name: "Apply" }));
+
+            await waitFor(
+                () => {
+                    expect(canvas.getByRole("textbox")).toHaveTextContent("HELLO WORLD");
+                    expect(within(document.body).queryByRole("dialog")).not.toBeInTheDocument();
+                },
+                { timeout: 3000 },
+            );
+        });
+    },
+};
+
+const TranslationHeadingLevelsBlock = createTipTapRichTextBlock({
+    undoRedoButtons: false,
+    bold: false,
+    italic: false,
+    strike: false,
+    sub: false,
+    sup: false,
+    heading: { levels: [2, 3] },
+    orderedList: false,
+    unorderedList: false,
+    nonBreakingSpace: false,
+    softHyphen: false,
+});
+
+function TranslationHeadingLevelsStory() {
+    const [state, setState] = useState<TipTapRichTextBlockState>(translationInitialState);
+
+    return (
+        <TranslationProvider showApplyTranslationDialog>
+            <StoryWrapper state={state}>
+                <TranslationHeadingLevelsBlock.AdminComponent state={state} updateState={setState} />
+            </StoryWrapper>
+        </TranslationProvider>
+    );
+}
+
+export const TranslationRespectsHeadingLevels: StoryObj<typeof TranslationHeadingLevelsStory> = {
+    render: () => <TranslationHeadingLevelsStory />,
+    play: async ({ canvas, userEvent, step }) => {
+        await step("Editor is ready with a translate button", async () => {
+            await waitFor(
+                () => {
+                    expect(canvas.getByRole("button")).toBeInTheDocument();
+                },
+                { timeout: 5000 },
+            );
+        });
+
+        await step("Open the translation review dialog", async () => {
+            await userEvent.click(canvas.getByRole("button"));
+
+            await waitFor(
+                () => {
+                    expect(within(document.body).getByRole("dialog")).toBeInTheDocument();
+                },
+                { timeout: 3000 },
+            );
+        });
+
+        await step("The translated-side heading dropdown only offers Heading 2-3, matching the block's headingLevels", async () => {
+            const dialog = within(document.body).getByRole("dialog");
+            await userEvent.click(within(dialog).getByRole("combobox"));
+
+            await waitFor(
+                () => {
+                    const body = within(document.body);
+                    expect(body.getByText("Heading 2")).toBeInTheDocument();
+                    expect(body.getByText("Heading 3")).toBeInTheDocument();
+                    expect(body.queryByText("Heading 1")).not.toBeInTheDocument();
+                    expect(body.queryByText("Heading 4")).not.toBeInTheDocument();
+                },
+                { timeout: 3000 },
+            );
+        });
+    },
+};