@gen-epix/ui 1.14.4 → 1.15.0

package/src/components/form/fields/RichTextEditor/RichTextEditor.tsx

@@ -0,0 +1,321 @@
+import type { ReactElement } from 'react';
+import {
+  useCallback,
+  useId,
+  useRef,
+} from 'react';
+import {
+  FormControl,
+  IconButton,
+  FormGroup,
+  FormHelperText,
+  FormLabel,
+  useTheme,
+  Alert,
+  AlertTitle,
+} from '@mui/material';
+import ClearIcon from '@mui/icons-material/Clear';
+import type { RichTextEditorRef } from 'mui-tiptap';
+import {
+  isTouchDevice,
+  LinkBubbleMenu,
+  MenuButtonAddTable,
+  MenuButtonBlockquote,
+  MenuButtonBold,
+  MenuButtonBulletedList,
+  MenuButtonEditLink,
+  MenuButtonHighlightColor,
+  MenuButtonHorizontalRule,
+  MenuButtonIndent,
+  MenuButtonItalic,
+  MenuButtonOrderedList,
+  MenuButtonRedo,
+  MenuButtonRemoveFormatting,
+  MenuButtonStrikethrough,
+  MenuButtonSubscript,
+  MenuButtonSuperscript,
+  MenuButtonTaskList,
+  MenuButtonTextColor,
+  MenuButtonUnderline,
+  MenuButtonUndo,
+  MenuButtonUnindent,
+  MenuControlsContainer,
+  MenuDivider,
+  MenuSelectFontSize,
+  MenuSelectHeading,
+  MenuSelectTextAlign,
+  RichTextEditor as RichTextEditorComponent,
+  TableBubbleMenu,
+} from 'mui-tiptap';
+import type {
+  FieldValues,
+  UseControllerReturn,
+  PathValue,
+  Path,
+} from 'react-hook-form';
+import {
+  Controller,
+  useFormContext,
+} from 'react-hook-form';
+import { useTranslation } from 'react-i18next';
+
+import { FormUtil } from '../../../../utils/FormUtil';
+import { TestIdUtil } from '../../../../utils/TestIdUtil';
+import { FormFieldHelperText } from '../../helpers/FormFieldHelperText';
+import { FormFieldLoadingIndicator } from '../../helpers/FormFieldLoadingIndicator';
+
+import { useRichTextEditorExtensions } from './useRichTextEditorExtensions';
+
+export type RichTextEditorProps<TFieldValues extends FieldValues, TName extends Path<TFieldValues> = Path<TFieldValues>> = {
+  readonly disabled?: boolean;
+  readonly label: string;
+  readonly name: TName;
+  readonly onChange?: (value: string) => void;
+  readonly required?: boolean;
+  readonly warningMessage?: string | boolean;
+  readonly loading?: boolean;
+};
+
+export const RichTextEditor = <TFieldValues extends FieldValues, TName extends Path<TFieldValues> = Path<TFieldValues>>({
+  label,
+  name,
+  disabled,
+  onChange: onChangeProp,
+  required,
+  loading,
+  warningMessage,
+}: RichTextEditorProps<TFieldValues, TName>): ReactElement => {
+  const { t } = useTranslation();
+  const theme = useTheme();
+  const extensions = useRichTextEditorExtensions({
+    placeholder: '',
+  });
+  const id = useId();
+  const { control, formState: { errors } } = useFormContext<TFieldValues>();
+  const errorMessage = FormUtil.getFieldErrorMessage(errors, name);
+  const hasError = !!errorMessage;
+  const rteRef = useRef<RichTextEditorRef>(null);
+
+  const renderController = useCallback(({ field: { onChange, onBlur, value, ref } }: UseControllerReturn<TFieldValues, TName>) => {
+    rteRef.current?.editor.on('blur', () => onBlur());
+    rteRef.current?.editor.on('update', () => {
+      const newValue = rteRef.current?.editor.getHTML();
+      if (newValue === value) {
+        return;
+      }
+      if (onChangeProp) {
+        onChangeProp(newValue);
+      }
+      onChange(newValue);
+    });
+    ref({
+      focus: () => {
+        rteRef.current?.editor.commands.focus();
+      },
+    });
+
+    const onResetButtonClick = () => {
+      onChange('');
+    };
+
+    return (
+      <FormControl
+        component={'fieldset'}
+        error={hasError}
+        {...TestIdUtil.createAttributes('CheckboxGroup', { label, name: name as string })}
+        fullWidth
+        sx={{
+          'legend button': {
+            display: 'none',
+          },
+          '&:hover legend button, &:focus-within legend button': {
+            display: 'initial',
+          },
+        }}
+      >
+        {!disabled && (
+          <Alert
+            severity={'info'}
+            sx={{ mt: 0.5 }}
+          >
+            <AlertTitle>
+              {t`Privacy notice`}
+            </AlertTitle>
+            {t`Do not enter any personal information here (such as name, address, telephone number or government-issued personal identifier).`}
+          </Alert>
+        )}
+        <FormLabel
+          component={'legend'}
+          disabled={disabled || loading}
+          id={id}
+          required={required}
+
+        >
+          {label}
+          {!disabled && (
+            <IconButton
+              {...TestIdUtil.createAttributes('DateRangePicker-reset')}
+              sx={{
+                position: 'absolute',
+                top: '-10px',
+                '& svg': {
+                  fontSize: '16px',
+                },
+              }}
+              tabIndex={-1}
+              aria-label={t`Clear rich text editor content`}
+              // eslint-disable-next-line react/jsx-no-bind
+              onClick={onResetButtonClick}
+            >
+              <ClearIcon />
+            </IconButton>
+          )}
+        </FormLabel>
+        { !loading && (
+          <FormGroup
+            aria-labelledby={id}
+            onBlur={onBlur}
+          >
+            <RichTextEditorComponent
+              ref={rteRef}
+              RichTextFieldProps={{
+                // The "outlined" variant is the default (shown here only as
+                // example), but can be changed to "standard" to remove the outlined
+                // field border from the editor
+                variant: 'outlined',
+              }}
+              content={value}
+              extensions={extensions}
+              editable={!disabled}
+              sx={{
+                '& .ProseMirror': {
+                  whiteSpace: 'pre-wrap',
+                },
+              }}
+              // eslint-disable-next-line react/jsx-no-bind
+              renderControls={() => (
+                <MenuControlsContainer>
+                  <MenuDivider />
+                  <MenuSelectHeading />
+                  <MenuDivider />
+                  <MenuSelectFontSize />
+                  <MenuDivider />
+                  <MenuButtonBold />
+                  <MenuButtonItalic />
+                  <MenuButtonUnderline />
+                  <MenuButtonStrikethrough />
+                  <MenuButtonSubscript />
+                  <MenuButtonSuperscript />
+                  <MenuDivider />
+                  <MenuButtonTextColor
+                    defaultTextColor={theme.palette.text.primary}
+                    swatchColors={[
+                      { value: '#000000', label: 'Black' },
+                      { value: '#ffffff', label: 'White' },
+                      { value: '#888888', label: 'Grey' },
+                      { value: '#ff0000', label: 'Red' },
+                      { value: '#ff9900', label: 'Orange' },
+                      { value: '#ffff00', label: 'Yellow' },
+                      { value: '#00d000', label: 'Green' },
+                      { value: '#0000ff', label: 'Blue' },
+                    ]}
+                  />
+                  <MenuButtonHighlightColor
+                    swatchColors={[
+                      { value: '#595959', label: 'Dark grey' },
+                      { value: '#dddddd', label: 'Light grey' },
+                      { value: '#ffa6a6', label: 'Light red' },
+                      { value: '#ffd699', label: 'Light orange' },
+                      // Plain yellow matches the browser default `mark` like when using Cmd+Shift+H
+                      { value: '#ffff00', label: 'Yellow' },
+                      { value: '#99cc99', label: 'Light green' },
+                      { value: '#90c6ff', label: 'Light blue' },
+                      { value: '#8085e9', label: 'Light purple' },
+                    ]}
+                  />
+                  <MenuDivider />
+                  <MenuButtonEditLink />
+                  <MenuDivider />
+                  <MenuSelectTextAlign />
+                  <MenuDivider />
+                  <MenuButtonOrderedList />
+                  <MenuButtonBulletedList />
+                  <MenuButtonTaskList />
+                  {isTouchDevice() && (
+                    <>
+                      <MenuButtonIndent />
+                      <MenuButtonUnindent />
+                    </>
+                  )}
+                  <MenuDivider />
+                  <MenuButtonBlockquote />
+                  <MenuDivider />
+                  <MenuButtonHorizontalRule />
+                  <MenuButtonAddTable />
+                  <MenuDivider />
+                  <MenuButtonRemoveFormatting />
+                  <MenuDivider />
+                  <MenuButtonUndo />
+                  <MenuButtonRedo />
+                </MenuControlsContainer>
+              )}
+            >
+              {() => (
+                <>
+                  <LinkBubbleMenu
+                    labels={{
+                      viewLinkEditButtonLabel: t`Edit link`,
+                      viewLinkRemoveButtonLabel: t`Remove link`,
+                      editLinkAddTitle: t`Add new link`,
+                      editLinkEditTitle: t`Update this link`,
+                      editLinkCancelButtonLabel: t`Cancel changes`,
+                      editLinkTextInputLabel: t`Text content`,
+                      editLinkHrefInputLabel: t`URL`,
+                      editLinkSaveButtonLabel: t`Save changes`,
+                    }}
+
+                  />
+                  <TableBubbleMenu
+                    labels={{
+                      insertColumnBefore: t`Insert column before`,
+                      insertColumnAfter: t`Insert column after`,
+                      deleteColumn: t`Delete column`,
+                      insertRowAbove: t`Insert row above`,
+                      insertRowBelow: t`Insert row below`,
+                      deleteRow: t`Delete row`,
+                      mergeCells: t`Merge cells`,
+                      splitCell: t`Split cell`,
+                      toggleHeaderRow: t`Toggle header row`,
+                      toggleHeaderColumn: t`Toggle header column`,
+                      toggleHeaderCell: t`Toggle header cell`,
+                      deleteTable: t`Delete table`,
+                    }}
+                  />
+                </>
+              )}
+            </RichTextEditorComponent>
+          </FormGroup>
+        )}
+        { !!loading && <FormFieldLoadingIndicator inline />}
+        <FormHelperText sx={{ ml: 0 }}>
+          <FormFieldHelperText
+            noIndent
+            errorMessage={errorMessage}
+            warningMessage={warningMessage}
+          />
+        </FormHelperText>
+      </FormControl>
+    );
+
+
+  }, [disabled, errorMessage, extensions, hasError, id, label, loading, name, onChangeProp, required, t, theme.palette.text.primary, warningMessage]);
+
+  return (
+    <Controller
+      control={control}
+      defaultValue={'' as PathValue<TFieldValues, TName>}
+      name={name}
+      render={renderController}
+    />
+  );
+};

package/src/components/form/fields/RichTextEditor/RichTextEditorContent.tsx

@@ -0,0 +1,34 @@
+import {
+  useTheme,
+  Box,
+} from '@mui/material';
+import { RichTextReadOnly } from 'mui-tiptap';
+
+import { useRichTextEditorExtensions } from './useRichTextEditorExtensions';
+
+export type RichTextEditorContentProps = {
+  readonly source: string;
+};
+
+export const RichTextEditorContent = ({ source }: RichTextEditorContentProps) => {
+  const extensions = useRichTextEditorExtensions({
+    placeholder: '',
+  });
+  const theme = useTheme();
+
+  return (
+    <Box
+      sx={{
+        '& *': {
+          fontSize: '1rem',
+          fontFamily: theme.typography.fontFamily,
+        },
+      }}
+    >
+      <RichTextReadOnly
+        content={source}
+        extensions={extensions}
+      />
+    </Box>
+  );
+};

package/src/components/form/fields/RichTextEditor/index.ts

@@ -0,0 +1,2 @@
+export * from './RichTextEditor';
+export * from './RichTextEditorContent';

package/src/components/form/fields/RichTextEditor/useRichTextEditorExtensions.ts

@@ -0,0 +1,174 @@
+import type { EditorOptions } from '@tiptap/core';
+import { Blockquote } from '@tiptap/extension-blockquote';
+import { Bold } from '@tiptap/extension-bold';
+import { BulletList } from '@tiptap/extension-bullet-list';
+import { CodeBlock } from '@tiptap/extension-code-block';
+import { Color } from '@tiptap/extension-color';
+import { Document } from '@tiptap/extension-document';
+import { Dropcursor } from '@tiptap/extension-dropcursor';
+import { FontFamily } from '@tiptap/extension-font-family';
+import { Gapcursor } from '@tiptap/extension-gapcursor';
+import { HardBreak } from '@tiptap/extension-hard-break';
+import { Highlight } from '@tiptap/extension-highlight';
+import { History } from '@tiptap/extension-history';
+import { HorizontalRule } from '@tiptap/extension-horizontal-rule';
+import { Italic } from '@tiptap/extension-italic';
+import { Link } from '@tiptap/extension-link';
+import { ListItem } from '@tiptap/extension-list-item';
+import { OrderedList } from '@tiptap/extension-ordered-list';
+import { Paragraph } from '@tiptap/extension-paragraph';
+import { Placeholder } from '@tiptap/extension-placeholder';
+import { Strike } from '@tiptap/extension-strike';
+import { Subscript } from '@tiptap/extension-subscript';
+import { Superscript } from '@tiptap/extension-superscript';
+import { TableCell } from '@tiptap/extension-table-cell';
+import { TableHeader } from '@tiptap/extension-table-header';
+import { TableRow } from '@tiptap/extension-table-row';
+import { TaskItem } from '@tiptap/extension-task-item';
+import { TaskList } from '@tiptap/extension-task-list';
+import { Text } from '@tiptap/extension-text';
+import { TextAlign } from '@tiptap/extension-text-align';
+import { TextStyle } from '@tiptap/extension-text-style';
+import { Underline } from '@tiptap/extension-underline';
+import { useMemo } from 'react';
+import {
+  FontSize,
+  HeadingWithAnchor,
+  LinkBubbleMenuHandler,
+  ResizableImage,
+  TableImproved,
+} from 'mui-tiptap';
+
+export type UseRichTextEditorExtensionsOptions = {
+  /** Placeholder hint to show in the text input area before a user types a message. */
+  placeholder?: string;
+};
+
+// Don't treat the end cursor as "inclusive" of the Link mark, so that users can
+// actually "exit" a link if it's the last element in the editor (see
+// https://tiptap.dev/api/schema#inclusive and
+// https://github.com/ueberdosis/tiptap/issues/2572#issuecomment-1055827817).
+// This also makes the `isActive` behavior somewhat more consistent with
+// `extendMarkRange` (as described here
+// https://github.com/ueberdosis/tiptap/issues/2535), since a link won't be
+// treated as active if the cursor is at the end of the link. One caveat of this
+// approach: it seems that after creating or editing a link with the link menu
+// (as opposed to having a link created via autolink), the next typed character
+// will be part of the link unexpectedly, and subsequent characters will not be.
+// This may have to do with how we're using `insertContent` and `setLink` in
+// the LinkBubbleMenu, but I can't figure out an alternative approach that
+// avoids the issue. This is arguably better than being "stuck" in the link
+// without being able to leave it, but it is still not quite right. See the
+// related open issues here:
+// https://github.com/ueberdosis/tiptap/issues/2571,
+// https://github.com/ueberdosis/tiptap/issues/2572, and
+// https://github.com/ueberdosis/tiptap/issues/514
+const CustomLinkExtension = Link.extend({
+  inclusive: false,
+});
+
+// Make subscript and superscript mutually exclusive
+// https://github.com/ueberdosis/tiptap/pull/1436#issuecomment-1031937768
+
+const CustomSubscript = Subscript.extend({
+  excludes: 'superscript',
+});
+
+const CustomSuperscript = Superscript.extend({
+  excludes: 'subscript',
+});
+
+/**
+ * A hook for providing a default set of useful extensions for the MUI-Tiptap
+ * editor.
+ */
+export const useRichTextEditorExtensions = ({
+  placeholder,
+}: UseRichTextEditorExtensionsOptions = {}): EditorOptions['extensions'] => {
+  return useMemo(() => {
+    return [
+      // We incorporate all of the functionality that's part of
+      // https://tiptap.dev/api/extensions/starter-kit, plus a few additional
+      // extensions, including mui-tiptap's
+
+      // Note that the Table extension must come before other nodes that also have "tab"
+      // shortcut keys so that when using the tab key within a table on a node that also
+      // responds to that shortcut, it respects that inner node with higher precedence
+      // than the Table. For instance, if you want to indent or dedent a list item
+      // inside a table, you should be able to do that by pressing tab. Tab should only
+      // move between table cells if not within such a nested node. See comment here for
+      // notes on extension ordering
+      // https://github.com/ueberdosis/tiptap/issues/1547#issuecomment-890848888, and
+      // note in prosemirror-tables on the need to have these plugins be lower
+      // precedence
+      // https://github.com/ueberdosis/prosemirror-tables/blob/1a0428af3ca891d7db648ce3f08a2c74d47dced7/src/index.js#L26-L30
+      TableImproved.configure({
+        resizable: true,
+      }),
+      TableRow,
+      TableHeader,
+      TableCell,
+      BulletList,
+      CodeBlock,
+      Document,
+      HardBreak,
+      ListItem,
+      OrderedList,
+      Paragraph,
+      CustomSubscript,
+      CustomSuperscript,
+      Text,
+
+      // Blockquote must come after Bold, since we want the "Cmd+B" shortcut to
+      // have lower precedence than the Blockquote "Cmd+Shift+B" shortcut.
+      // Otherwise using "Cmd+Shift+B" will mistakenly toggle the bold mark.
+      // (See https://github.com/ueberdosis/tiptap/issues/4005,
+      // https://github.com/ueberdosis/tiptap/issues/4006)
+      Bold,
+      Blockquote,
+      Italic,
+      Underline,
+      Strike,
+      CustomLinkExtension.configure({
+        // autolink is generally useful for changing text into links if they
+        // appear to be URLs (like someone types in literally "example.com"),
+        // though it comes with the caveat that if you then *remove* the link
+        // from the text, and then add a space or newline directly after the
+        // text, autolink will turn the text back into a link again. Not ideal,
+        // but probably still overall worth having autolink enabled, and that's
+        // how a lot of other tools behave as well.
+        autolink: true,
+        linkOnPaste: true,
+        openOnClick: false,
+      }),
+      LinkBubbleMenuHandler,
+
+      // Extensions
+      Gapcursor,
+      HeadingWithAnchor,
+      TextAlign.configure({
+        types: ['heading', 'paragraph', 'image'],
+      }),
+      TextStyle,
+      Color,
+      FontFamily,
+      FontSize,
+      Highlight.configure({ multicolor: true }),
+      HorizontalRule,
+      ResizableImage,
+      // When images are dragged, we want to show the "drop cursor" for where they'll
+      // land
+      Dropcursor,
+      TaskList,
+      TaskItem.configure({
+        nested: true,
+      }),
+      Placeholder.configure({
+        placeholder,
+      }),
+      // We use the regular `History` (undo/redo) extension when not using
+      // collaborative editing
+      History,
+    ];
+  }, [placeholder]);
+};