@wix/patterns-fields 1.0.0

package/src/components/media-control/use-media-control.ts

@@ -0,0 +1,258 @@
+import { useRef, useState, useEffect, useCallback } from 'react';
+import { dashboard } from '@wix/dashboard';
+import { files } from '@wix/media';
+
+import type { MEDIA_TYPES } from '../../utils/media-utils';
+import { executeDownloading } from '../../utils/media-utils';
+import { getMediaURL } from '../../auto-field-types';
+
+type Focusable = { focus: () => void };
+type FocusableRef =
+  | React.RefObject<Focusable | undefined>
+  | React.MutableRefObject<Focusable | undefined>;
+
+interface UseMediaControlBaseParams {
+  mediaType: MEDIA_TYPES;
+  autoFocus?: boolean;
+  onFocus?: () => void;
+  onBlur?: () => void;
+  readOnly?: boolean;
+  initialLoading?: boolean;
+  inputRef?: FocusableRef;
+  viewRef?: FocusableRef;
+}
+
+interface UseSingleMediaControlParams extends UseMediaControlBaseParams {
+  value?: string;
+  onChange?: (value: string) => void;
+  multiSelect?: false;
+}
+
+interface UseMultiMediaControlParams extends UseMediaControlBaseParams {
+  value?: string[];
+  onChange?: (value: string[]) => void;
+  multiSelect: true;
+}
+
+export type UseMediaControlParams =
+  | UseSingleMediaControlParams
+  | UseMultiMediaControlParams;
+
+interface UseMediaControlBaseReturnType {
+  loading: boolean;
+  onMediaLoad: () => void;
+}
+
+interface UseSingleMediaControlReturnType
+  extends UseMediaControlBaseReturnType {
+  callMedia(): Promise<void>;
+  downloadMedia(mediaUri?: string): Promise<void>;
+}
+
+interface UseMultiMediaControlReturnType extends UseMediaControlBaseReturnType {
+  callMedia(index?: number): Promise<void>;
+  downloadMedia(mediaUri?: string): Promise<void>;
+}
+
+export type UseMediaControlReturnType =
+  | UseSingleMediaControlReturnType
+  | UseMultiMediaControlReturnType;
+
+const MEDIA_TYPE_TO_CATEGORY: Record<string, string | undefined> = {
+  IMAGE: 'IMAGE',
+  VIDEO: 'VIDEO',
+  MUSIC: 'MUSIC', // MEDIA_TYPES.AUDIO = 'MUSIC'
+  DOCUMENT: 'DOCUMENT',
+  ALL_MEDIA: undefined,
+};
+
+/**
+ * Extracts a playable URL from media.audio, which may be:
+ *   - a string (wix:audio:// URI or direct URL)
+ *   - an object with { audio: string } (nested URI)
+ *   - an object with { assets: [{ url }] } or { assets: [string] }
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const extractAudioUrl = (audio: any): string | undefined => {
+  if (audio) {
+    if (typeof audio === 'string') {
+      return audio;
+    }
+    if (typeof audio.audio === 'string') {
+      return audio.audio;
+    }
+    const firstAsset = audio.assets?.[0];
+    if (typeof firstAsset === 'string') {
+      return firstAsset;
+    }
+    if (typeof firstAsset?.url === 'string') {
+      return firstAsset.url;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Extracts the Wix media URI from media manager result.
+ * Media manager returns different structures for different media types.
+ */
+const extractMediaUri = (mediaItem: any): string => {
+  const { media } = mediaItem || {};
+  if (media) {
+    return (
+      // Try each media type: the URI is nested under media.[type].[type], fallback for direct string values
+      media.image?.image ||
+      (typeof media.image === 'string' && media.image) ||
+      media.video?.video ||
+      (typeof media.video === 'string' && media.video) ||
+      media.document?.document ||
+      (typeof media.document === 'string' && media.document) ||
+      extractAudioUrl(media.audio) ||
+      ''
+    );
+  }
+
+  return '';
+};
+
+export function useMediaControl(
+  params: UseSingleMediaControlParams,
+): UseSingleMediaControlReturnType;
+
+export function useMediaControl(
+  params: UseMultiMediaControlParams,
+): UseMultiMediaControlReturnType;
+
+export function useMediaControl({
+  mediaType,
+  readOnly,
+  autoFocus,
+  initialLoading,
+  inputRef,
+  viewRef,
+  onFocus,
+  onBlur,
+  ...params
+}: UseMediaControlParams): UseMediaControlReturnType {
+  const { value, multiSelect } = params;
+
+  const [loading, setLoading] = useState(Boolean(initialLoading && value));
+  const mediaRequested = useRef(false);
+
+  const setActive = useCallback(() => {
+    if (!autoFocus) {
+      return;
+    }
+
+    if (value) {
+      viewRef && viewRef?.current?.focus();
+      !viewRef && inputRef?.current?.focus();
+    } else {
+      inputRef?.current?.focus();
+    }
+  }, [autoFocus, value, inputRef, viewRef]);
+
+  useEffect(() => setActive(), [setActive]);
+
+  const onMediaLoad = useCallback(() => setLoading(false), []);
+
+  const callMedia = useCallback(
+    async (index?: number) => {
+      if (mediaRequested.current || readOnly) {
+        return;
+      }
+
+      if (!params.onChange) {
+        return;
+      }
+
+      mediaRequested.current = true;
+
+      onFocus?.();
+      setLoading(true);
+
+      try {
+        const category = MEDIA_TYPE_TO_CATEGORY[mediaType];
+        const mediaManagerData = await dashboard.openMediaManager({
+          multiSelect: Boolean(multiSelect),
+          ...(category && { category }),
+        });
+
+        onBlur?.();
+        setLoading(false);
+
+        setActive();
+
+        mediaRequested.current = false;
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const items =
+          mediaManagerData?.items || (mediaManagerData as any)?.files;
+
+        if (!items?.length) {
+          return;
+        }
+
+        if (params.multiSelect) {
+          const newURIs = items.map(extractMediaUri);
+
+          if (!newURIs.length) {
+            throw new Error(
+              `Media Control Error: Media Manager returns not-covered Multi-Document data.`,
+            );
+          }
+
+          if (typeof index === 'number') {
+            const newValue = value ? [...value] : [];
+            newValue.splice(index, 1, ...newURIs);
+            params.onChange(newValue);
+          } else {
+            params.onChange([...((value as string[]) ?? []), ...newURIs]);
+          }
+        } else {
+          params.onChange(extractMediaUri(items[0]));
+        }
+      } catch (e) {
+        setLoading(false);
+        mediaRequested.current = false;
+        console.error(`Media Control Error:`, e);
+      }
+    },
+    [
+      mediaType,
+      multiSelect,
+      onBlur,
+      onFocus,
+      params,
+      readOnly,
+      setActive,
+      value,
+    ],
+  );
+
+  const downloadMedia = useCallback(async (mediaUri?: string) => {
+    if (!mediaUri) {
+      return;
+    }
+
+    try {
+      const result = await files.generateFileDownloadUrl(mediaUri);
+      const downloadUrl = result.downloadUrls?.[0]?.url;
+      if (!downloadUrl) {
+        throw new Error('No download URL returned');
+      }
+      return executeDownloading(downloadUrl);
+    } catch (error) {
+      // Fallback: open the static URL in a new tab
+      console.error('Media download error, falling back to static URL:', error);
+      return executeDownloading(getMediaURL(mediaUri));
+    }
+  }, []);
+
+  return {
+    loading,
+    callMedia,
+    downloadMedia,
+    onMediaLoad,
+  };
+}

package/src/components/media-control/use-paste-url-form.ts

@@ -0,0 +1,58 @@
+import { useState, useCallback } from 'react';
+
+import { useOpenState } from '../../hooks';
+
+export interface UsePasteURLFormParams {
+  onChange: (value: string, indexToReplace?: number) => void;
+}
+
+export interface OpenPasteURLFormParams {
+  title: string;
+  value?: string;
+  index?: number;
+}
+
+export type UsePasteURLFormHook = (params: UsePasteURLFormParams) => {
+  isOpen: boolean;
+  title: string;
+  onOpen: (params: OpenPasteURLFormParams) => () => void;
+  onClose: () => void;
+  onSave: (value: string) => void;
+  value?: string;
+};
+
+export const usePasteURLForm: UsePasteURLFormHook = ({ onChange }) => {
+  const { isOpen, onOpen: onOpenModal, onClose } = useOpenState(false);
+  const [title, setTitle] = useState('');
+  const [value, setValue] = useState('');
+  const [indexToReplace, setIndexToReplace] = useState<number | undefined>(
+    undefined,
+  );
+
+  const onOpen = useCallback(
+    ({ title, value, index }: OpenPasteURLFormParams) =>
+      () => {
+        setTitle(title);
+        setValue(value ?? '');
+        onOpenModal();
+        setIndexToReplace(index);
+      },
+    [onOpenModal],
+  );
+
+  const onSave = useCallback(
+    (value: string) => {
+      onChange(value, indexToReplace);
+    },
+    [onChange, indexToReplace],
+  );
+
+  return {
+    isOpen,
+    title,
+    onOpen,
+    onClose,
+    onSave,
+    value,
+  };
+};

package/src/components/media-gallery/form-media-gallery-field.st.css

@@ -0,0 +1,51 @@
+.container {
+  display: flex;
+  min-height: 128px;
+  max-height: 259px;
+}
+
+.viewBox {
+  display: flex;
+  height: 100%;
+  width: 100%;
+  flex-wrap: wrap;
+}
+
+.addItemWrapper {
+  height: 128px;
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.addItem {
+  -st-states: error;
+  box-sizing: border-box;
+}
+
+.overlay {
+  width: initial !important;
+  min-width: 382px !important;
+}
+
+.image {
+  -st-states: withMarginRight, withMarginTop;
+}
+
+.image:withMarginRight {
+  margin-right: 3px;
+}
+
+.image:withMarginTop {
+  margin-top: 3px;
+}
+
+/* Preview modal styles */
+.previewImage {
+  max-height: calc(100% - 12px) !important;
+}
+
+.previewVideo {
+  border-radius: 8px;
+  max-width: 100%;
+  max-height: calc(100% - 12px) !important;
+}

package/src/components/media-gallery/form-media-gallery-field.st.css.ts

@@ -0,0 +1,25 @@
+// @ts-nocheck
+
+
+import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
+
+
+
+var _namespace_ = "formmediagalleryfield2735002816";
+var _style_ = classesRuntime.bind(null, _namespace_);
+
+export var cssStates = statesRuntime.bind(null, _namespace_);
+export var style: import("@stylable/runtime").STFunction = _style_;
+export var st: import("@stylable/runtime").STFunction = _style_;
+
+export var namespace = _namespace_;
+export var classes = {"root":"formmediagalleryfield2735002816__root","container":"formmediagalleryfield2735002816__container","viewBox":"formmediagalleryfield2735002816__viewBox","addItemWrapper":"formmediagalleryfield2735002816__addItemWrapper","addItem":"formmediagalleryfield2735002816__addItem","overlay":"formmediagalleryfield2735002816__overlay","image":"formmediagalleryfield2735002816__image","previewImage":"formmediagalleryfield2735002816__previewImage","previewVideo":"formmediagalleryfield2735002816__previewVideo"};
+export var keyframes = {}; 
+export var layers = {};
+export var containers = {};
+export var stVars = {}; 
+export var vars = {}; 
+
+
+
+

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

@@ -0,0 +1,216 @@
+import React, { useRef, useState, useCallback, useEffect } from 'react';
+import type { AddItemActions } from '@wix/design-system';
+import {
+  AddItem,
+  Box,
+  Button,
+  IconButton,
+  MediaOverlay,
+  Tooltip,
+} from '@wix/design-system';
+import {
+  Refresh as RefreshIcon,
+  Delete as DeleteIcon,
+  Maximize as MaximizeIcon,
+} from '@wix/wix-ui-icons-common';
+import type { WixCodeGalleryItem } from '../../auto-field-types';
+import { useTranslations } from '../../hooks';
+import { executeDownloading } from '../../utils/media-utils';
+import { getMediaURL } from '../../auto-field-types';
+import { files } from '@wix/media';
+
+import { style, classes } from './form-media-gallery-field.st.css.js';
+import { FormMediaGalleryItemsPreview } from './form-media-gallery-items-preview';
+import { MediaPreviewModal } from './media-preview-modal';
+import { useMediaGalleryDialog } from './media-gallery-dialog/hooks';
+import { MediaGalleryDialog } from './media-gallery-dialog/media-gallery-dialog';
+
+export interface FormMediaGalleryFieldProps {
+  data?: WixCodeGalleryItem[];
+  onChange: (value: WixCodeGalleryItem[]) => void;
+  onClear?: () => void;
+  readOnly?: boolean;
+  invalid?: boolean;
+  autoFocus?: boolean;
+  dataHook?: string;
+}
+
+const mediaGalleryPreviewTextKeys = {
+  replace: 'CMS.mediaGallery.preview.replace',
+  download: 'CMS.mediaGallery.preview.download',
+  delete: 'CMS.mediaGallery.preview.delete',
+} as const;
+
+export const FormMediaGalleryField: React.FC<FormMediaGalleryFieldProps> = ({
+  data,
+  onChange,
+  onClear,
+  readOnly,
+  invalid,
+  autoFocus,
+  dataHook,
+}) => {
+  const { t } = useTranslations();
+  const boxRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<AddItemActions>(null);
+  const [boxWidth, setBoxWidth] = useState(0);
+  const [hovered, setHovered] = useState(false);
+  const [isPreviewOpen, setIsPreviewOpen] = useState(false);
+
+  const hasValue = Boolean(data?.length);
+
+  // autoFocus support
+  useEffect(() => {
+    if (!autoFocus) {
+      return;
+    }
+    boxRef.current?.focus();
+    inputRef.current?.focus();
+  }, [autoFocus]);
+
+  // Responsive width tracking
+  useEffect(() => {
+    const el = boxRef.current;
+    if (!el) {
+      return;
+    }
+    setBoxWidth(el.clientWidth);
+    const ro = new ResizeObserver(([entry]) =>
+      setBoxWidth(entry.contentRect.width),
+    );
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  const { openMediaGalleryDialog, ...mediaGalleryDialogProps } =
+    useMediaGalleryDialog({
+      initialOpen: false,
+      items: data,
+      onChange,
+    });
+
+  const onMouseEnter = useCallback(
+    () => hasValue && setHovered(true),
+    [hasValue],
+  );
+  const onMouseLeave = useCallback(
+    () => hasValue && setHovered(false),
+    [hasValue],
+  );
+
+  // Download using Wix media API (consistent with useMediaControl)
+  const onDownloadMedia = useCallback(async (mediaUri?: string) => {
+    if (!mediaUri) {
+      return;
+    }
+    try {
+      const result = await files.generateFileDownloadUrl(mediaUri);
+      const downloadUrl = result.downloadUrls?.[0]?.url;
+      if (!downloadUrl) {
+        throw new Error('No download URL returned');
+      }
+      executeDownloading(downloadUrl);
+    } catch (error) {
+      // Fallback: open the static URL in a new tab
+      console.error('Media download error, falling back to static URL:', error);
+      executeDownloading(getMediaURL(mediaUri));
+    }
+  }, []);
+
+  const onRequestMedia = useCallback(() => {
+    openMediaGalleryDialog();
+    setIsPreviewOpen(false);
+    setHovered(false);
+  }, [openMediaGalleryDialog]);
+
+  return (
+    <div
+      data-hook={dataHook}
+      ref={boxRef}
+      tabIndex={hasValue ? 0 : -1}
+      className={classes.container}
+      onMouseEnter={onMouseEnter}
+      onMouseLeave={onMouseLeave}
+      onFocus={onMouseEnter}
+      onBlur={onMouseLeave}
+    >
+      {!hasValue ? (
+        <div className={classes.addItemWrapper}>
+          <AddItem
+            ref={inputRef}
+            className={style(classes.addItem, { error: invalid })}
+            size="tiny"
+            theme="dashes"
+            onClick={onRequestMedia}
+            disabled={readOnly}
+            dataHook={`${dataHook}-add`}
+            subtitle={t('CMS.mediaGallery.emptyHint')}
+          >
+            {t('CMS.mediaGallery.addGallery')}
+          </AddItem>
+        </div>
+      ) : (
+        <>
+          <MediaOverlay
+            hovered={hovered}
+            className={classes.overlay}
+            hoverSkin="dark"
+            borderRadius={0}
+            media={
+              <FormMediaGalleryItemsPreview width={boxWidth} value={data} />
+            }
+          >
+            <MediaOverlay.Content visible="hover">
+              <Box gap="SP2" align="center">
+                <Button
+                  skin="inverted"
+                  prefixIcon={<RefreshIcon />}
+                  onClick={onRequestMedia}
+                  disabled={readOnly}
+                  dataHook={`${dataHook}-manage`}
+                >
+                  {t('CMS.mediaGallery.manageGallery')}
+                </Button>
+                <Tooltip content={t('CMS.mediaGallery.preview')}>
+                  <IconButton
+                    skin="inverted"
+                    onClick={() => setIsPreviewOpen(true)}
+                    dataHook={`${dataHook}-preview`}
+                  >
+                    <MaximizeIcon />
+                  </IconButton>
+                </Tooltip>
+                <Tooltip content={t('CMS.mediaGallery.clear')}>
+                  <IconButton
+                    skin="inverted"
+                    onClick={onClear}
+                    disabled={readOnly}
+                    dataHook={`${dataHook}-clear`}
+                  >
+                    <DeleteIcon />
+                  </IconButton>
+                </Tooltip>
+              </Box>
+            </MediaOverlay.Content>
+          </MediaOverlay>
+          <MediaPreviewModal
+            isOpen={isPreviewOpen}
+            onClose={() => setIsPreviewOpen(false)}
+            value={data?.map((d) => d.src)}
+            onRequestMedia={onRequestMedia}
+            onClearMedia={onClear}
+            onDownloadMedia={onDownloadMedia}
+            textKeys={mediaGalleryPreviewTextKeys}
+            readOnly={readOnly}
+          />
+        </>
+      )}
+
+      {mediaGalleryDialogProps.isOpen && (
+        <MediaGalleryDialog {...mediaGalleryDialogProps} />
+      )}
+    </div>
+  );
+};
+
+FormMediaGalleryField.displayName = 'FormMediaGalleryField';

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

@@ -0,0 +1,14 @@
+import { UniDriver } from '@wix/wix-ui-test-utils/unidriver';
+
+export function FormMediaGalleryFieldUniDriver(
+  base: UniDriver,
+  dataHook: string,
+) {
+  return {
+    exists: () => base.exists(),
+    getAddButton: () => base.$(`[data-hook="${dataHook}-add"]`),
+    getManageButton: () => base.$(`[data-hook="${dataHook}-manage"]`),
+    getPreviewButton: () => base.$(`[data-hook="${dataHook}-preview"]`),
+    getClearButton: () => base.$(`[data-hook="${dataHook}-clear"]`),
+  };
+}