feat(view/useFilesGallery): add possibility to override gallery item props (#824)

Author: kseniya57

demo/stories/view/gallery/ViewWithGallery.tsx

@@ -8,8 +8,14 @@ import './ViewWithGallery.scss';
 
 export type ViewWithGalleryProps = YfmStaticViewProps;
 
+const getCopyUrl = (url: string) => url;
+const getDownloadUrl = (url: string) => url;
+
 const ViewWithGalleryContent: FC<ViewWithGalleryProps> = (props) => {
-    const {openFilesGallery} = useFilesGallery();
+    const {openFilesGallery} = useFilesGallery(undefined, {
+        copyUrl: getCopyUrl,
+        download: getDownloadUrl,
+    });
 
     return (
         // eslint-disable-next-line jsx-a11y/click-events-have-key-events,jsx-a11y/no-static-element-interactions

package-lock.json

@@ -229,7 +229,7 @@
     "@diplodoc/quote-link-extension": "0.1.3",
     "@diplodoc/tabs-extension": "^3.5.1",
     "@diplodoc/transform": "^4.58.0",
-    "@gravity-ui/components": "4.2.2",
+    "@gravity-ui/components": "4.10.0",
     "@gravity-ui/eslint-config": "3.3.0",
     "@gravity-ui/gulp-utils": "1.0.3",
     "@gravity-ui/prettier-config": "1.1.0",
@@ -327,7 +327,7 @@
     "@diplodoc/quote-link-extension": "^0.1.3",
     "@diplodoc/tabs-extension": "^3.5.1",
     "@diplodoc/transform": "^4.43.0",
-    "@gravity-ui/components": "^4.2.2",
+    "@gravity-ui/components": "^4.10.0",
     "@gravity-ui/uikit": "^7.1.0",
     "highlight.js": "^11.8.0",
     "katex": "^0.16.9",

package.json

@@ -0,0 +1,5 @@
+{
+  "link_copied": "The link copied",
+  "link_copy": "Copy link",
+  "file_download": "Download"
+}

src/i18n/gallery/en.json

@@ -0,0 +1,8 @@
+import {registerKeyset} from '../i18n';
+
+import en from './en.json';
+import ru from './ru.json';
+
+const KEYSET = 'gallery';
+
+export const i18n = registerKeyset(KEYSET, {en, ru});

src/i18n/gallery/index.ts

@@ -0,0 +1,5 @@
+{
+  "link_copied": "Ссылка скопирована",
+  "link_copy": "Скопировать ссылку",
+  "file_download": "Скачать"
+}

src/i18n/gallery/ru.json

@@ -15,9 +15,19 @@ _GalleryProvider_:
 
 _useFilesGallery_
 
-| Property    | Type                                 | Required | Values | Default | Description                                                                                                                 |
-| :---------- | :----------------------------------- | :------- | :----- | :------ | :-------------------------------------------------------------------------------------------------------------------------- |
-| customFiles | `(GalleryItem & { url?: string })[]` |          |        |         | The additional files list (pass the url to be able to exclude the items from content if they are found in the custom files) |
+| Property    | Type                                         | Required | Values | Default | Description                                                                                                                 |
+|:------------|:---------------------------------------------| :------- | :----- | :------ |:----------------------------------------------------------------------------------------------------------------------------|
+| customFiles | `(GalleryItem & { url?: string })[]`         |          |        |         | The additional files list (pass the url to be able to exclude the items from content if they are found in the custom files) |
+| options     | `UseFilesGalleryOptions` |          |        |         | The files gallery options                                                                                                   |
+
+_UseFilesGalleryOptions_
+
+| Property          | Type                                                                                                           | Required | Values | Default | Description                                                                                   |
+|:------------------|:---------------------------------------------------------------------------------------------------------------|:---------|:-------|:--------|:----------------------------------------------------------------------------------------------|
+| download          | `(url: string, type: FilesGalleryItemType, element: Element) => string or undefined`                              |          |        |         | The file download link getter (if you want to show the download action)                       |
+| copyUrl          | `(url: string, type: FilesGalleryItemType, element: Element) => string or undefined`                              |          |        |         | The file copy link getter (if you want to show the copy link action)                          |
+| overrideItemProps | `(url: string, type: FilesGalleryItemType, element: Element, currentProps: GalleryItemProps) => GalleryItemProps` |          |        |         | The custom gallery item props getter (if you want to override the default gallery item props) |
+
 
 _useFilesGallery returns function `openFilesGallery` with the following args_:
 
@@ -74,3 +84,41 @@ const {openFilesGallery} = useFilesGallery(customFiles);
   <YfmStaticView {...props} />
 </div>;
 ```
+
+If you want to add download and copy link action, provide download and copyUrl options
+
+```tsx
+import {YfmStaticView, useFilesGallery} from '@gravity-ui/markdown-editor/view';
+
+const {openFilesGallery} = useFilesGallery(undefined, {download: urlFromContent => getDownloadUrl(urlFromContent), copyUrl: urlFromContent => getUrlForCopy(urlFromContent)});
+
+<div onClick={openFilesGallery}>
+  <YfmStaticView {...props} />
+</div>;
+```
+
+If you want to override some gallery item props, provide overrideItemProps option
+
+```tsx
+import {YfmStaticView, useFilesGallery} from '@gravity-ui/markdown-editor/view';
+
+function getGalleryItemProps(url: string, type: 'image' | 'video', element: Element, currentProps: GalleryItemProps) {
+    return {
+        actions: [
+          {
+            id: 'download',
+            title: 'Download',
+            icon: <Icon data={ArrowDownToLineIcon} />,
+            href: url,
+            onClick: handleDownload,
+          }
+        ]
+    }
+}
+
+const {openFilesGallery} = useFilesGallery(undefined, {overrideItemProps:getGalleryItemProps});
+
+<div onClick={openFilesGallery}>
+  <YfmStaticView {...props} />
+</div>;
+```

src/view/hooks/useFilesGallery/README.md

@@ -4,3 +4,16 @@ export type GalleryItemPropsWithUrl = GalleryItemProps & {
     // pass the url to be able to exclude the items from content if they are found in the custom files
     url?: string;
 };
+
+export type FilesGalleryItemType = 'image' | 'video';
+
+export type UseFilesGalleryOptions = {
+    download?: (url: string, type: FilesGalleryItemType, element: Element) => string | undefined;
+    copyUrl?: (url: string, type: FilesGalleryItemType, element: Element) => string | undefined;
+    overrideItemProps?: (
+        url: string,
+        type: FilesGalleryItemType,
+        element: Element,
+        currentProps: GalleryItemProps,
+    ) => GalleryItemProps;
+};

src/view/hooks/useFilesGallery/types.ts

@@ -1,13 +1,32 @@
 import * as React from 'react';
 
-import {getGalleryItemImage, getGalleryItemVideo, useGallery} from '@gravity-ui/components';
+import {
+    type GalleryItemAction,
+    getGalleryItemCopyLinkAction,
+    getGalleryItemDownloadAction,
+    getGalleryItemImage,
+    getGalleryItemVideo,
+    useGallery,
+} from '@gravity-ui/components';
+import {useToaster} from '@gravity-ui/uikit';
+
+import {i18n} from 'src/i18n/gallery';
 
 import {extensionRegex, supportedExtensions, supportedVideoExtensions} from './constants';
-import type {GalleryItemPropsWithUrl} from './types';
-
-export function useFilesGallery(customFiles?: GalleryItemPropsWithUrl[]) {
+import type {FilesGalleryItemType, GalleryItemPropsWithUrl, UseFilesGalleryOptions} from './types';
+
+export function useFilesGallery(
+    customFiles?: GalleryItemPropsWithUrl[],
+    {
+        download: getItemDownloladUrl,
+        overrideItemProps,
+        copyUrl: getItemCopyUrl,
+    }: UseFilesGalleryOptions = {},
+) {
     const {openGallery} = useGallery();
 
+    const toaster = useToaster();
+
     return {
         openFilesGallery: React.useCallback(
             (event: React.MouseEvent<HTMLDivElement>) => {
@@ -44,11 +63,61 @@ export function useFilesGallery(customFiles?: GalleryItemPropsWithUrl[]) {
                                     ? element.getAttribute('alt')
                                     : element.getAttribute('title')) || '';
 
-                            result.push({
-                                ...(supportedVideoExtensions.includes(extension)
+                            const filesGalleryItemType: FilesGalleryItemType =
+                                supportedVideoExtensions.includes(extension) ? 'video' : 'image';
+                            const galleryItemActions: GalleryItemAction[] = [];
+
+                            const itemCopyUrl = getItemCopyUrl?.(
+                                link,
+                                filesGalleryItemType,
+                                element,
+                            );
+
+                            if (itemCopyUrl) {
+                                const handleLinkCopied = () => {
+                                    toaster.add({
+                                        theme: 'success',
+                                        name: 'g-md-editor-gallery-copy-link',
+                                        title: i18n('link_copied'),
+                                    });
+                                };
+
+                                galleryItemActions.push(
+                                    getGalleryItemCopyLinkAction({
+                                        copyUrl: itemCopyUrl,
+                                        onCopy: handleLinkCopied,
+                                    }),
+                                );
+                            }
+
+                            const downloadUrl = getItemDownloladUrl?.(
+                                link,
+                                filesGalleryItemType,
+                                element,
+                            );
+
+                            if (downloadUrl) {
+                                galleryItemActions.push(
+                                    getGalleryItemDownloadAction({downloadUrl}),
+                                );
+                            }
+
+                            const galleryItemProps = {
+                                ...(filesGalleryItemType === 'video'
                                     ? getGalleryItemVideo({src: link, name: name})
                                     : getGalleryItemImage({src: link, name: name})),
                                 url: link,
+                                actions: galleryItemActions,
+                            };
+
+                            result.push({
+                                ...galleryItemProps,
+                                ...overrideItemProps?.(
+                                    link,
+                                    filesGalleryItemType,
+                                    element,
+                                    galleryItemProps,
+                                ),
                             });
                         }
                     }
@@ -68,7 +137,14 @@ export function useFilesGallery(customFiles?: GalleryItemPropsWithUrl[]) {
 
                 return false;
             },
-            [customFiles, openGallery],
+            [
+                customFiles,
+                getItemCopyUrl,
+                getItemDownloladUrl,
+                overrideItemProps,
+                toaster,
+                openGallery,
+            ],
         ),
     };
 }