@wix/patterns-fields 1.116.0 → 1.117.0

package/src/components/media-image-field/cell-media-image-edit.tsx

@@ -0,0 +1,402 @@
+import React, { useCallback, useEffect, useState } from 'react';
+import {
+  Box,
+  FormField,
+  IconButton,
+  Input,
+  Popover,
+  PopoverMenu,
+  Tooltip,
+} from '@wix/design-system';
+import {
+  Add,
+  Delete,
+  Download,
+  Link,
+  LinkSmall,
+  Maximize,
+  MoreSmall,
+  Replace,
+} from '@wix/wix-ui-icons-common/lazy';
+import { ThumbnailSize } from '../../auto-field-types';
+import { useTranslations } from '../../hooks';
+import type { MediaImageValue } from '../../types/media-image';
+import { getImageSource } from '../../utils/get-image-source';
+import {
+  fromImageUrl,
+  fromMediaManagerPick,
+  isExternalMediaImage,
+  replaceImage,
+  toMediaImageValue,
+  withAltText,
+} from '../../utils/media-image-value';
+import { executeDownloading, MEDIA_TYPES } from '../../utils/media-utils';
+import {
+  CellMediaEditShell,
+  MediaFieldType,
+  useCellMediaEdit,
+} from '../media-control';
+import { MediaPreviewModal } from '../media-gallery/media-preview-modal';
+import { MediaImage } from '../media-image';
+import { MediaImageView } from './media-image-view';
+import { st, classes } from './cell-media-image-edit.st.css.js';
+
+export interface CellMediaImageEditProps {
+  /** A `MEDIA_IMAGE` value. */
+  value: unknown;
+  onChange: (value: MediaImageValue | null) => void;
+  onCommit: () => void;
+  onCancel?: () => void;
+  /**
+   * Called before opening external UI (media manager / paste-URL form) so the
+   * table can set isEditing=true and protect cell focus while the modal is open.
+   */
+  onStartEdit?: () => void;
+  inputRef?: React.MutableRefObject<{ focus: () => void } | null | undefined>;
+  dataHook?: string;
+}
+
+type PopoverLayer = 'none' | 'popover' | 'menu' | 'preview';
+
+/** What is on top of the editor. Escape and click-outside act on it. */
+type Layer = PopoverLayer | 'pasteUrl' | 'loading';
+
+const imageFromUrl = (url: string, current: MediaImageValue | null) =>
+  replaceImage(current, fromImageUrl(url));
+
+interface MenuTriggerProps {
+  isOpen: boolean;
+  toggle: () => void;
+  /** Lets WDS put focus back here when the menu closes. */
+  buttonRef?: React.RefObject<HTMLElement>;
+  onOpenChange: (isOpen: boolean) => void;
+  ariaLabel: string;
+}
+
+/** WDS shows the menu's open state only to its trigger, so the trigger
+ *  reports it. */
+const MenuTrigger: React.FC<MenuTriggerProps> = ({
+  isOpen,
+  toggle,
+  buttonRef,
+  onOpenChange,
+  ariaLabel,
+}) => {
+  useEffect(() => {
+    onOpenChange(isOpen);
+  }, [isOpen, onOpenChange]);
+
+  return (
+    <IconButton
+      ref={buttonRef}
+      size="small"
+      skin="light"
+      priority="secondary"
+      dataHook="media-image-edit-more-button"
+      ariaLabel={ariaLabel}
+      aria-haspopup="menu"
+      aria-expanded={isOpen}
+      onClick={toggle}
+    >
+      <MoreSmall />
+    </IconButton>
+  );
+};
+
+/**
+ * Edits a `MEDIA_IMAGE` cell. An empty cell shows the add and paste-URL
+ * buttons. A cell with an image opens a popover with the image and its alt
+ * text. Changes go to `onChange` as they happen and are committed once, when
+ * the popover closes.
+ */
+export const CellMediaImageEdit: React.FC<CellMediaImageEditProps> = ({
+  value,
+  onChange,
+  onCommit,
+  onCancel,
+  onStartEdit,
+  inputRef,
+  dataHook,
+}) => {
+  const { t } = useTranslations();
+  const image = toMediaImageValue(value);
+  const src = getImageSource(image);
+  // 'none' once committed.
+  const [popoverLayer, setPopoverLayer] = useState<PopoverLayer>('popover');
+
+  const mediaEdit = useCellMediaEdit({
+    mediaType: MEDIA_TYPES.IMAGE,
+    value: image,
+    onChange,
+    onCommit,
+    onCancel,
+    onStartEdit,
+    inputRef,
+    fromPick: fromMediaManagerPick,
+    fromUrl: imageFromUrl,
+    commitOnPick: false,
+  });
+  const {
+    loading,
+    pasteUrlForm,
+    handleCallMedia,
+    handleDelete,
+    downloadMedia,
+  } = mediaEdit;
+  const closePasteUrl = pasteUrlForm.handleClose;
+  // The media manager and the URL form sit above the popover layers.
+  const openLayer: Layer = loading
+    ? 'loading'
+    : pasteUrlForm.isOpen
+    ? 'pasteUrl'
+    : image
+    ? popoverLayer
+    : 'none';
+
+  const openPasteUrl = mediaEdit.startEditAndOpenPasteUrl({
+    title: t('CMS.image.replaceWithUrl.title'),
+    value: isExternalMediaImage(image) ? image.url : undefined,
+  });
+
+  const handleDownload = useCallback(() => {
+    // The Media Manager can't make a download link for an external URL.
+    if (isExternalMediaImage(image)) {
+      executeDownloading(image.url);
+    } else if (src) {
+      downloadMedia(src);
+    }
+  }, [src, image, downloadMedia]);
+
+  const commit = useCallback(() => {
+    setPopoverLayer('none');
+    onCommit();
+  }, [onCommit]);
+
+  // Picking Preview sets its own layer, which closing the menu must not undo.
+  const handleMenuOpenChange = useCallback((isOpen: boolean) => {
+    setPopoverLayer((layer) => {
+      if (isOpen) {
+        return 'menu';
+      }
+      return layer === 'menu' ? 'popover' : layer;
+    });
+  }, []);
+
+  // Fires on mouseup, before the click that closes a menu or a modal, so
+  // `openLayer` still says what was open.
+  const handleClickOutside = useCallback(() => {
+    if (openLayer === 'popover') {
+      commit();
+    }
+  }, [openLayer, commit]);
+
+  useEffect(() => {
+    // WDS closes the menu on Escape and stops the event there.
+    if (
+      openLayer === 'none' ||
+      openLayer === 'loading' ||
+      openLayer === 'menu'
+    ) {
+      return;
+    }
+    // Capture phase, so the table doesn't cancel the edit first.
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Escape') {
+        return;
+      }
+      e.stopPropagation();
+      if (openLayer === 'pasteUrl') {
+        closePasteUrl();
+      } else if (openLayer === 'preview') {
+        setPopoverLayer('popover');
+      } else {
+        commit();
+      }
+    };
+    document.addEventListener('keydown', handleKeyDown, true);
+    return () => document.removeEventListener('keydown', handleKeyDown, true);
+  }, [openLayer, closePasteUrl, commit]);
+
+  const emptyActions = (
+    <>
+      <Tooltip content={t('CMS.image.add')} appendTo="window">
+        <IconButton
+          size="tiny"
+          priority="secondary"
+          dataHook="media-image-edit-add-button"
+          ariaLabel={t('CMS.image.add')}
+          onClick={handleCallMedia}
+        >
+          <Add />
+        </IconButton>
+      </Tooltip>
+      <Tooltip content={t('CMS.image.replaceWithUrl.button')} appendTo="window">
+        <IconButton
+          size="tiny"
+          priority="tertiary"
+          dataHook="media-image-edit-paste-url-button"
+          ariaLabel={t('CMS.image.replaceWithUrl.button')}
+          onClick={openPasteUrl}
+        >
+          <LinkSmall />
+        </IconButton>
+      </Tooltip>
+    </>
+  );
+
+  // One return for both states, so the shell and its container stay mounted
+  // when a pick fills an empty cell.
+  return (
+    <>
+      <CellMediaEditShell
+        dataHook={dataHook}
+        mediaEdit={mediaEdit}
+        fieldType={MediaFieldType.image}
+        padding={image ? '0' : undefined}
+      >
+        {!image ? (
+          emptyActions
+        ) : (
+          <div className={classes.view}>
+            <MediaImageView value={image} />
+            <div className={classes.anchor}>
+              <Popover
+                shown={popoverLayer !== 'none'}
+                appendTo="window"
+                placement="bottom-start"
+                moveBy={{ x: 0, y: 4 }}
+                zIndex={5001}
+                animate
+                flip
+                fixed={false}
+                onClickOutside={handleClickOutside}
+              >
+                <Popover.Element>
+                  <div className={classes.anchorBox} />
+                </Popover.Element>
+                <Popover.Content>
+                  <Box
+                    dataHook="media-image-edit-popover"
+                    className={classes.popoverContent}
+                    direction="vertical"
+                    gap="SP3"
+                    padding="SP3"
+                  >
+                    <FormField label={t('CMS.image.thumbnail.label')}>
+                      <div className={classes.image}>
+                        <MediaImage
+                          dataHook="media-image-edit-image"
+                          src={src}
+                          alt=""
+                          fit="cover"
+                          transparent
+                          size={ThumbnailSize.L}
+                          width="180px"
+                          height="180px"
+                          borderRadius="0"
+                        />
+                        <div
+                          className={st(classes.imageActions, {
+                            menuOpen: popoverLayer === 'menu',
+                          })}
+                        >
+                          <Tooltip
+                            content={t('CMS.image.replace')}
+                            appendTo="window"
+                          >
+                            <IconButton
+                              size="small"
+                              skin="light"
+                              priority="secondary"
+                              dataHook="media-image-edit-replace-button"
+                              ariaLabel={t('CMS.image.replace')}
+                              onClick={handleCallMedia}
+                            >
+                              <Replace />
+                            </IconButton>
+                          </Tooltip>
+                          <PopoverMenu
+                            textSize="small"
+                            appendTo="window"
+                            zIndex={5002}
+                            triggerElement={({ isOpen, toggle, ref }) => (
+                              <MenuTrigger
+                                isOpen={isOpen}
+                                toggle={toggle}
+                                buttonRef={ref}
+                                onOpenChange={handleMenuOpenChange}
+                                ariaLabel={t(
+                                  'auto-patterns.fields.more_actions_tooltip',
+                                )}
+                              />
+                            )}
+                          >
+                            <PopoverMenu.MenuItem
+                              dataHook="media-image-edit-action-replace-url"
+                              text={t('CMS.image.replaceWithUrl.button')}
+                              prefixIcon={<Link />}
+                              onClick={openPasteUrl}
+                            />
+                            <PopoverMenu.MenuItem
+                              dataHook="media-image-edit-action-preview"
+                              text={t('CMS.mediaGallery.preview')}
+                              prefixIcon={<Maximize />}
+                              onClick={() => setPopoverLayer('preview')}
+                            />
+                            <PopoverMenu.MenuItem
+                              dataHook="media-image-edit-action-download"
+                              text={t('CMS.image.download')}
+                              prefixIcon={<Download />}
+                              onClick={handleDownload}
+                            />
+                            <PopoverMenu.Divider />
+                            <PopoverMenu.MenuItem
+                              dataHook="media-image-edit-action-delete"
+                              text={t('CMS.image.clear')}
+                              skin="destructive"
+                              prefixIcon={<Delete />}
+                              onClick={handleDelete}
+                            />
+                          </PopoverMenu>
+                        </div>
+                      </div>
+                    </FormField>
+                    <FormField label={t('CMS.image.altText.label')}>
+                      <Input
+                        dataHook="media-image-edit-alt-input"
+                        size="small"
+                        value={image.altText ?? ''}
+                        placeholder={t('CMS.image.altText.inputPlaceholder')}
+                        onChange={(e) =>
+                          onChange(withAltText(image, e.target.value))
+                        }
+                        onEnterPressed={commit}
+                      />
+                    </FormField>
+                  </Box>
+                </Popover.Content>
+              </Popover>
+            </div>
+          </div>
+        )}
+      </CellMediaEditShell>
+      {image && (
+        <MediaPreviewModal
+          isOpen={popoverLayer === 'preview'}
+          value={src}
+          onClose={() => setPopoverLayer('popover')}
+          onRequestMedia={handleCallMedia}
+          onClearMedia={handleDelete}
+          onDownloadMedia={handleDownload}
+          textKeys={{
+            replace: 'CMS.image.replace',
+            download: 'CMS.image.download',
+            delete: 'CMS.image.clear',
+          }}
+        />
+      )}
+    </>
+  );
+};
+
+CellMediaImageEdit.displayName = 'CellMediaImageEdit';

package/src/components/media-image-field/form-media-image-field.tsx

@@ -0,0 +1,165 @@
+import type { FC } from 'react';
+import React, { useCallback, useRef } from 'react';
+import type { FormFieldProps } from '@wix/design-system';
+import { Box, FormField, ImageViewer, Input } from '@wix/design-system';
+import { useIsMobile, useWixPatternsContainer } from '@wix/bex-core/react';
+
+import type { ControlledInputProps } from '../../types/controlled-input';
+import type { MediaImageValue } from '../../types/media-image';
+import { useMergedRef, useTranslations } from '../../hooks';
+import { getImageSource } from '../../utils/get-image-source';
+import { getImageUrl } from '../../utils/get-image-url';
+import { MEDIA_HEIGHT, MEDIA_MAX_WIDTH } from '../../utils/media-constants';
+import {
+  fromMediaManagerPick,
+  toMediaImageValue,
+  withAltText,
+} from '../../utils/media-image-value';
+import { MEDIA_TYPES } from '../../utils/media-utils';
+import { useMediaControl } from '../media-control';
+
+interface ImageViewerActions {
+  focus: () => void;
+}
+
+export interface FormMediaImageFieldProps {
+  /** A `MEDIA_IMAGE` value. */
+  data?: unknown;
+  onChange: (value: MediaImageValue | null) => void;
+  /** Fires when the media manager closes, whether or not a file was picked. */
+  onBlur?: () => void;
+  readOnly?: boolean;
+  autoFocus?: boolean;
+  dataHook?: string;
+  inputRef?: React.Ref<ImageViewerActions>;
+  /** The FormField around the image, e.g. the field's label and its error.
+   *  ImageViewer takes its error styling from it. */
+  imageFormFieldProps?: Pick<
+    FormFieldProps,
+    'label' | 'required' | 'status' | 'statusMessage'
+  >;
+}
+
+/**
+ * The entity page input of a `MEDIA_IMAGE` field: the image, and an alt text
+ * input to its right once there is an image. A pick fills an empty alt text
+ * from the file name; a replace keeps the current one.
+ */
+export const FormMediaImageField: FC<FormMediaImageFieldProps> = ({
+  data,
+  onChange,
+  onBlur,
+  readOnly,
+  autoFocus,
+  dataHook,
+  inputRef: forwardedRef,
+  imageFormFieldProps,
+}) => {
+  const { translate } = useWixPatternsContainer();
+  const { t } = useTranslations();
+  const isMobile = useIsMobile();
+  const image = toMediaImageValue(data);
+  // The media manager calls back after it closes, so it reads the value from
+  // here rather than from the render that opened it.
+  const imageRef = useRef(image);
+  imageRef.current = image;
+
+  const [inputRef, setInputRef] =
+    useMergedRef<ImageViewerActions>(forwardedRef);
+
+  const handlePick = useCallback(
+    (uri: string) => {
+      const next = fromMediaManagerPick(uri, imageRef.current);
+      if (next) {
+        onChange(next);
+      }
+    },
+    [onChange],
+  );
+
+  const { callMedia, onMediaLoad } = useMediaControl({
+    mediaType: MEDIA_TYPES.IMAGE,
+    value: getImageSource(image),
+    onChange: handlePick,
+    autoFocus,
+    readOnly,
+    onBlur,
+    inputRef,
+    initialLoading: true,
+  });
+
+  const canEdit = !isMobile && !readOnly;
+
+  const handleAltTextChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    if (image) {
+      onChange(withAltText(image, e.target.value));
+    }
+  };
+
+  return (
+    <Box dataHook={dataHook} gap="SP4" width="100%">
+      <Box width="100%" maxWidth={MEDIA_MAX_WIDTH} flexShrink={0}>
+        <FormField {...imageFormFieldProps} dataHook="media-image-field-image">
+          <ImageViewer
+            ref={setInputRef}
+            dataHook="media-image-field-viewer"
+            imageUrl={image ? getImageUrl(image) : undefined}
+            onImageLoad={onMediaLoad}
+            onAddImage={canEdit ? callMedia : undefined}
+            onUpdateImage={canEdit ? callMedia : undefined}
+            disabled={image ? Boolean(readOnly) : !canEdit}
+            showUpdateButton={canEdit}
+            showRemoveButton={!readOnly}
+            updateImageInfo={translate('cairo.replace-image.tooltip')}
+            removeImageInfo={translate('cairo.remove-image.tooltip')}
+            addImageInfo={translate('cairo.add-image.tooltip')}
+            height={MEDIA_HEIGHT}
+            width="100%"
+            fit="cover"
+            onRemoveImage={() => onChange(null)}
+          />
+        </FormField>
+      </Box>
+      {image && (
+        <Box direction="vertical" flexGrow={1} minWidth="0">
+          <FormField label={t('CMS.image.altText.label')}>
+            <Input
+              dataHook="media-image-field-alt-input"
+              value={image.altText ?? ''}
+              placeholder={t('CMS.image.altText.inputPlaceholder')}
+              onChange={handleAltTextChange}
+              readOnly={readOnly}
+            />
+          </FormField>
+        </Box>
+      )}
+    </Box>
+  );
+};
+
+FormMediaImageField.displayName = 'FormMediaImageField';
+
+export type ControlledMediaImageInputProps = Omit<
+  ControlledInputProps<MediaImageValue | null>,
+  'invalid'
+>;
+
+export const ControlledMediaImageInput: FC<ControlledMediaImageInputProps> = ({
+  data,
+  onChange,
+  onBlur,
+  readOnly,
+  autoFocus,
+  dataHook,
+}) => (
+  <FormMediaImageField
+    data={data}
+    onChange={onChange}
+    onBlur={onBlur}
+    readOnly={readOnly}
+    autoFocus={autoFocus}
+    dataHook={dataHook}
+  />
+);
+
+ControlledMediaImageInput.displayName = 'ControlledMediaImageInput';

package/src/components/media-image-field/form-media-image-field.uni.driver.ts

@@ -0,0 +1,42 @@
+import type { UniDriver } from '@wix/wix-ui-test-utils/unidriver';
+import {
+  FormFieldUniDriver,
+  ImageViewerUniDriver,
+} from '@wix/design-system/dist/testkit/unidriver';
+
+import { baseUniDriverFactory } from '../../testkit/base-driver';
+
+export function FormMediaImageFieldUniDriver(base: UniDriver, body: UniDriver) {
+  const formField = FormFieldUniDriver(
+    base.$('[data-hook="media-image-field-image"]'),
+    body,
+  );
+  const imageViewer = ImageViewerUniDriver(
+    base.$('[data-hook="media-image-field-viewer"]'),
+    body,
+  );
+  const altInput = base.$('[data-hook="media-image-field-alt-input"] input');
+
+  return {
+    ...baseUniDriverFactory(base),
+    getLabel: async () => (await formField.getLabel())?.textContent ?? '',
+    isRequired: () => formField.isRequired(),
+    hasError: () => formField.hasStatus('error'),
+    getErrorMessage: () => formField.getStatusMessage(),
+    getImageUrl: () => imageViewer.getImageUrl(),
+    isAddItemVisible: () => imageViewer.isAddItemVisible(),
+    clickAdd: () => imageViewer.clickAdd(),
+    clickReplace: () => imageViewer.clickUpdate(),
+    clickRemove: () => imageViewer.clickRemove(),
+    hasAltTextInput: () => altInput.exists(),
+    getAltText: () => altInput.value(),
+    getAltTextPlaceholder: () => altInput.attr('placeholder'),
+    enterAltText: (text: string) => altInput.enterValue(text),
+    // ImageViewer hides its edit buttons behind a loader until the image
+    // loads, and jsdom never fires that event on its own.
+    simulateImageLoad: async () =>
+      (
+        await base.$('[data-hook="image-viewer-current-image"]').getNative()
+      ).dispatchEvent(new Event('load')),
+  };
+}

package/src/components/media-image-field/form-media-image-input.tsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { observer } from 'mobx-react-lite';
+import { useWixPatternsContainer } from '@wix/bex-core/react';
+import { useController } from '@wix/bex-core/form';
+
+import type { BaseInputProps } from '../../types/base-input';
+import type { MediaImageValue } from '../../types/media-image';
+import { useFieldRef } from '../../hooks';
+import { isMediaImageEmpty } from '../../utils/media-image-value';
+import { FormMediaImageField } from './form-media-image-field';
+
+export interface FormMediaImageInputProps
+  extends BaseInputProps<MediaImageValue | null> {}
+
+const _FormMediaImageInput = (props: FormMediaImageInputProps) => {
+  const { field, dataHook, formControl, data } = props;
+
+  const { translate: t } = useWixPatternsContainer();
+
+  const controller = useController({
+    name: field?.id ?? '',
+    control: formControl,
+    defaultValue: data?.[field?.id ?? ''],
+    rules: {
+      validate: (value) => {
+        // Alt text alone doesn't make the field filled.
+        if (field.validation?.required && isMediaImageEmpty(value)) {
+          return t('cairo.fieldValidation.requiredField');
+        }
+
+        return true;
+      },
+    },
+  });
+
+  const setFieldRef = useFieldRef(controller.field.ref);
+
+  return (
+    <FormMediaImageField
+      // Hands the live button to react-hook-form so shouldFocusError can
+      // reach this field when it blocks save.
+      inputRef={setFieldRef}
+      data={controller.field.value}
+      onChange={(value) => controller.field.onChange(value)}
+      dataHook={dataHook}
+      imageFormFieldProps={{
+        label: field.displayName,
+        required: field.validation?.required,
+        status: controller.fieldState.error ? 'error' : undefined,
+        statusMessage: controller.fieldState.error?.message,
+      }}
+    />
+  );
+};
+
+export const FormMediaImageInput = observer(_FormMediaImageInput);

package/src/components/media-image-field/index.ts

@@ -0,0 +1,4 @@
+export * from './media-image-view';
+export * from './cell-media-image-edit';
+export * from './form-media-image-field';
+export * from './form-media-image-input';

package/src/components/media-image-field/media-image-view.st.css

@@ -0,0 +1,16 @@
+@property st-global(--wds-color-text-standard-primary);
+@property st-global(--wds-color-text-placeholder);
+@property st-global(--wsr-color-D40);
+
+.root {
+  box-sizing: border-box;
+}
+
+/* WDS <Text> reads its colour from the primary text token, so the placeholder
+   colour goes through it. */
+.altTextPlaceholder {
+  --wds-color-text-standard-primary: var(
+    --wds-color-text-placeholder,
+    var(--wsr-color-D40, #868AA5)
+  );
+}