@plone/volto 18.18.0 → 18.20.0

package/src/components/manage/UniversalLink/UniversalLink.test.jsx

@@ -4,7 +4,7 @@ import { Provider } from 'react-intl-redux';
 import configureStore from 'redux-mock-store';
 import { render } from '@testing-library/react';
 import { MemoryRouter } from 'react-router-dom';
-import UniversalLink from './UniversalLink';
+import UniversalLink, { __test } from './UniversalLink';
 import config from '@plone/volto/registry';
 
 const mockStore = configureStore();
@@ -39,7 +39,10 @@ describe('UniversalLink', () => {
     const component = renderer.create(
       <Provider store={store}>
         <MemoryRouter>
-          <UniversalLink href="https://github.com/plone/volto">
+          <UniversalLink
+            href="https://github.com/plone/volto"
+            className="custom-link"
+          >
             <h1>Title</h1>
           </UniversalLink>
         </MemoryRouter>
@@ -213,18 +216,197 @@ describe('UniversalLink', () => {
     expect(json).toMatchSnapshot();
     expect(global.console.error).toHaveBeenCalled();
   });
-});
 
-it('renders a UniversalLink component when url ends with @@display-file', () => {
-  const component = renderer.create(
-    <Provider store={store}>
-      <MemoryRouter>
-        <UniversalLink href="http://localhost:3000/en/welcome-to-volto/@@display-file">
+  it('renders a UniversalLink component when url ends with @@display-file', () => {
+    const component = renderer.create(
+      <Provider store={store}>
+        <MemoryRouter>
+          <UniversalLink href="http://localhost:3000/en/welcome-to-volto/@@display-file">
+            <h1>Title</h1>
+          </UniversalLink>
+        </MemoryRouter>
+      </Provider>,
+    );
+    const json = component.toJSON();
+    expect(json).toMatchSnapshot();
+  });
+
+  test('only one UniversalLink re-renders when prop changes (stable references)', () => {
+    const renderCounter = vi.fn();
+    __test.renderCounter = renderCounter;
+
+    const itemA = { '@id': '/en/a' };
+    const itemB = { '@id': '/en/b' };
+    const itemC = { '@id': '/en/c' };
+
+    const Wrapper = ({ children }) => (
+      <Provider store={store}>
+        <MemoryRouter>{children}</MemoryRouter>
+      </Provider>
+    );
+
+    const { rerender } = render(
+      <>
+        <UniversalLink item={itemA} />
+        <UniversalLink item={itemB} />
+        <UniversalLink item={itemC} />
+      </>,
+      { wrapper: Wrapper },
+    );
+
+    // expect 3 renders
+    expect(renderCounter).toHaveBeenCalledTimes(3);
+
+    const updatedItemB = { '@id': '/en/b-updated' };
+
+    rerender(
+      <>
+        <UniversalLink item={itemA} />
+        <UniversalLink item={updatedItemB} />
+        <UniversalLink item={itemC} />
+      </>,
+    );
+
+    // expect 4 renders (only one UniversalLink re-renders)
+    expect(renderCounter).toHaveBeenCalledTimes(4);
+  });
+
+  test('only one UniversalLink re-renders when prop changes (with children - stable references)', () => {
+    const renderCounter = vi.fn();
+    __test.renderCounter = renderCounter;
+
+    const itemA = { '@id': '/en/a' };
+    const itemB = { '@id': '/en/b' };
+    const itemC = { '@id': '/en/c' };
+    const title = 'Title';
+
+    const Wrapper = ({ children }) => (
+      <Provider store={store}>
+        <MemoryRouter>{children}</MemoryRouter>
+      </Provider>
+    );
+
+    const { rerender } = render(
+      <>
+        <UniversalLink item={itemA}>{title}</UniversalLink>
+        <UniversalLink item={itemB}>{title}</UniversalLink>
+        <UniversalLink item={itemC}>{title}</UniversalLink>
+      </>,
+      { wrapper: Wrapper },
+    );
+
+    // expect 3 renders
+    expect(renderCounter).toHaveBeenCalledTimes(3);
+
+    const updatedItemB = { '@id': '/en/b-updated' };
+
+    rerender(
+      <>
+        <UniversalLink item={itemA}>{title}</UniversalLink>
+        <UniversalLink item={updatedItemB}>{title}</UniversalLink>
+        <UniversalLink item={itemC}>{title}</UniversalLink>
+      </>,
+    );
+
+    // expect 4 renders (only one UniversalLink re-renders)
+    expect(renderCounter).toHaveBeenCalledTimes(4);
+  });
+
+  test('[NEGATIVE TEST] UniversalLink re-renders all instances when children are inline JSX (React.memo ineffective)', () => {
+    // NEGATIVE TEST:
+    // This test demonstrates that React.memo does NOT prevent re-renders
+    // when props like `children` are passed as inline JSX.
+    // This is expected behavior due to unstable object references.
+    // Do NOT use inline props if render optimization is required.
+    const renderCounter = vi.fn();
+    __test.renderCounter = renderCounter;
+
+    const itemA = { '@id': '/en/a' };
+    const itemB = { '@id': '/en/b' };
+    const itemC = { '@id': '/en/c' };
+
+    const Wrapper = ({ children }) => (
+      <Provider store={store}>
+        <MemoryRouter>{children}</MemoryRouter>
+      </Provider>
+    );
+
+    const { rerender } = render(
+      <>
+        <UniversalLink item={itemA}>
+          <h1>Title</h1>
+        </UniversalLink>
+        <UniversalLink item={itemB}>
+          <h1>Title</h1>
+        </UniversalLink>
+        <UniversalLink item={itemC}>
+          <h1>Title</h1>
+        </UniversalLink>
+      </>,
+      { wrapper: Wrapper },
+    );
+
+    // expect 3 renders
+    expect(renderCounter).toHaveBeenCalledTimes(3);
+
+    const updatedItemB = { '@id': '/en/b-updated' };
+
+    rerender(
+      <>
+        <UniversalLink item={itemA}>
           <h1>Title</h1>
         </UniversalLink>
-      </MemoryRouter>
-    </Provider>,
-  );
-  const json = component.toJSON();
-  expect(json).toMatchSnapshot();
+        <UniversalLink item={updatedItemB}>
+          <h1>Title</h1>
+        </UniversalLink>
+        <UniversalLink item={itemC}>
+          <h1>Title</h1>
+        </UniversalLink>
+      </>,
+    );
+
+    // expect 6 renders (React.memo does NOT prevent re-renders when props like `children` are passed as inline JSX.)
+    expect(renderCounter).toHaveBeenCalledTimes(6);
+  });
+
+  test('[NEGATIVE TEST] UniversalLink re-renders all instances when props are inline JSX (React.memo ineffective)', () => {
+    // NEGATIVE TEST:
+    // This test demonstrates that React.memo does NOT prevent re-renders
+    // when props like `item` are passed as inline object.
+    // This is expected behavior due to unstable object references.
+    // Do NOT use inline props if render optimization is required.
+    const renderCounter = vi.fn();
+    __test.renderCounter = renderCounter;
+
+    const title = 'Title';
+
+    const Wrapper = ({ children }) => (
+      <Provider store={store}>
+        <MemoryRouter>{children}</MemoryRouter>
+      </Provider>
+    );
+
+    const { rerender } = render(
+      <>
+        <UniversalLink item={{ '@id': '/en/a' }}>{title}</UniversalLink>
+        <UniversalLink item={{ '@id': '/en/b' }}>{title}</UniversalLink>
+        <UniversalLink item={{ '@id': '/en/c' }}>{title}</UniversalLink>
+      </>,
+      { wrapper: Wrapper },
+    );
+
+    // expect 3 renders
+    expect(renderCounter).toHaveBeenCalledTimes(3);
+
+    rerender(
+      <>
+        <UniversalLink item={{ '@id': '/en/a' }}>{title}</UniversalLink>
+        <UniversalLink item={{ '@id': '/en/b' }}>{title}</UniversalLink>
+        <UniversalLink item={{ '@id': '/en/c' }}>{title}</UniversalLink>
+      </>,
+    );
+
+    // expect 6 renders (React.memo does NOT prevent re-renders when props like `children` are passed as inline JSX.)
+    expect(renderCounter).toHaveBeenCalledTimes(6);
+  });
 });

package/src/components/manage/UniversalLink/UniversalLink.tsx

@@ -0,0 +1,214 @@
+import React from 'react';
+import { HashLink as Link } from 'react-router-hash-link';
+import { useSelector } from 'react-redux';
+import {
+  flattenToAppURL,
+  isInternalURL,
+  URLUtils,
+} from '@plone/volto/helpers/Url/Url';
+import config from '@plone/volto/registry';
+import cx from 'classnames';
+import type { ObjectBrowserItem } from '@plone/types';
+
+type BaseProps = {
+  openLinkInNewTab?: boolean;
+  download?: boolean;
+  children: React.ReactNode;
+  className?: string;
+  title?: string;
+  smooth?: boolean;
+  onClick?: (e: React.MouseEvent) => void;
+  onKeyDown?: (e: React.KeyboardEvent) => void;
+};
+
+type HrefOnly = {
+  href: string;
+  item?: never;
+} & BaseProps;
+
+type ItemOnly = {
+  href?: never;
+  item: Partial<ObjectBrowserItem> & { remoteUrl?: string };
+} & BaseProps;
+
+export type UniversalLinkProps = HrefOnly | ItemOnly;
+export interface AppState {
+  content: {
+    data?: {
+      '@components'?: {
+        translations?: {
+          items?: { language: string; '@id': string }[];
+        };
+      };
+    };
+  };
+  navroot: {
+    data: {
+      navroot: {
+        id: string;
+      };
+    };
+  };
+  intl: {
+    locale: string;
+  };
+  userSession: {
+    token: string | null;
+  };
+}
+
+export const __test = {
+  renderCounter: () => {},
+};
+
+export function getUrl(
+  props: UniversalLinkProps,
+  token: string | null,
+  item: UniversalLinkProps['item'],
+  children: React.ReactNode,
+): string {
+  if ('href' in props && typeof props.href === 'string') {
+    return props.href;
+  }
+
+  if (!item || item['@id'] === '') return config.settings.publicURL;
+  if (!item['@id']) {
+    // eslint-disable-next-line no-console
+    console.error(
+      'Invalid item passed to UniversalLink',
+      item,
+      props,
+      children,
+    );
+    return '#';
+  }
+
+  let url = flattenToAppURL(item['@id']);
+  const remoteUrl = item.remoteUrl || item.getRemoteUrl;
+
+  if (!token && remoteUrl) {
+    url = remoteUrl;
+  }
+
+  if (
+    !token &&
+    item['@type'] &&
+    config.settings.downloadableObjects.includes(item['@type'])
+  ) {
+    url = `${url}/@@download/file`;
+  }
+
+  if (
+    !token &&
+    item['@type'] &&
+    config.settings.viewableInBrowserObjects.includes(item['@type'])
+  ) {
+    url = `${url}/@@display-file/file`;
+  }
+
+  return url;
+}
+
+const UniversalLink = React.memo(
+  React.forwardRef<HTMLAnchorElement | HTMLDivElement, UniversalLinkProps>(
+    function UniversalLink(props, ref) {
+      const {
+        openLinkInNewTab,
+        download,
+        children,
+        className,
+        title,
+        smooth,
+        onClick,
+        onKeyDown,
+        item,
+        ...rest
+      } = props;
+      __test.renderCounter();
+
+      const token = useSelector<AppState, string | null>(
+        (state) => state.userSession?.token,
+      );
+
+      let url = getUrl(props, token, item, children);
+
+      const isExternal = !isInternalURL(url);
+
+      const isDownload =
+        (!isExternal && url.includes('@@download')) || download;
+      const isDisplayFile =
+        (!isExternal && url.includes('@@display-file')) || false;
+
+      const checkedURL = URLUtils.checkAndNormalizeUrl(url);
+
+      url = checkedURL.url;
+      let tag = (
+        <Link
+          to={flattenToAppURL(url)}
+          target={openLinkInNewTab ?? false ? '_blank' : undefined}
+          title={title}
+          className={className}
+          smooth={smooth ?? config.settings.hashLinkSmoothScroll}
+          // @ts-ignore
+          ref={ref}
+          {...rest}
+        >
+          {children}
+        </Link>
+      );
+
+      if (isExternal) {
+        const isTelephoneOrMail = checkedURL.isMail || checkedURL.isTelephone;
+        const getClassName = cx({ external: !isTelephoneOrMail }, className);
+
+        tag = (
+          <a
+            href={url}
+            title={title}
+            target={
+              !isTelephoneOrMail && !(openLinkInNewTab === false)
+                ? '_blank'
+                : undefined
+            }
+            rel="noopener noreferrer"
+            {...rest}
+            className={getClassName}
+            ref={ref as React.Ref<HTMLAnchorElement>}
+          >
+            {children}
+          </a>
+        );
+      } else if (isDownload) {
+        tag = (
+          <a
+            href={flattenToAppURL(url)}
+            download
+            title={title}
+            {...rest}
+            className={className}
+            ref={ref as React.Ref<HTMLAnchorElement>}
+          >
+            {children}
+          </a>
+        );
+      } else if (isDisplayFile) {
+        tag = (
+          <a
+            title={title}
+            target="_blank"
+            rel="noopener noreferrer"
+            {...rest}
+            href={flattenToAppURL(url)}
+            className={className}
+            ref={ref as React.Ref<HTMLAnchorElement>}
+          >
+            {children}
+          </a>
+        );
+      }
+      return tag;
+    },
+  ),
+);
+
+export default UniversalLink;

package/tsconfig.declarations.json

@@ -17,5 +17,15 @@
       "react-dom": ["./node_modules/@types/react-dom"]
     }
   },
-  "include": ["src/**/*.js", "src/**/*.jsx", "src/**/*.tsx"]
+  "include": ["src/**/*.js", "src/**/*.jsx", "src/**/*.tsx"],
+  "exclude": [
+    "node_modules",
+    "build",
+    "coverage",
+    "dist",
+    "types",
+    "**/*.test.js",
+    "**/*.test.tsx",
+    "**/*.test.ts"
+  ]
 }

package/tsconfig.json

@@ -1,15 +1,8 @@
 {
   "compilerOptions": {
     "target": "ESNext",
-    "lib": [
-      "DOM",
-      "DOM.Iterable",
-      "ESNext"
-    ],
-    "types": [
-      "vitest/globals",
-      "jest"
-    ],
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "types": ["vitest/globals", "jest"],
     "module": "commonjs",
     "allowJs": true,
     "skipLibCheck": true,
@@ -24,22 +17,12 @@
     "noEmit": true,
     "jsx": "react-jsx",
     "paths": {
-      "@plone/volto/*": [
-        "./src/*"
-      ],
-      "@plone/volto-slate/*": [
-        "../volto-slate/src/*"
-      ],
-      "@root/*": [
-        "./src/*"
-      ]
+      "@plone/volto/*": ["./src/*"],
+      "@plone/volto-slate/*": ["../volto-slate/src/*"],
+      "@root/*": ["./src/*"]
     }
   },
-  "include": [
-    "src",
-    "packages",
-    "vitest.config.ts"
-  ],
+  "include": ["src", "packages", "types", "vitest.config.ts"],
   "exclude": [
     "node_modules",
     "build",
@@ -49,4 +32,4 @@
     "src/**/*.spec.{js,jsx,ts,tsx}",
     "src/**/*.stories.{js,jsx,ts,tsx}"
   ]
-}
+}

package/types/components/manage/ConditionalLink/ConditionalLink.d.ts

@@ -1,15 +1,11 @@
-export default ConditionalLink;
-declare function ConditionalLink({ condition, to, item, ...props }: {
-    [x: string]: any;
-    condition: any;
-    to: any;
-    item: any;
-}): import("react/jsx-runtime").JSX.Element;
-declare namespace ConditionalLink {
-    namespace propTypes {
-        let condition: any;
-        let to: any;
-        let item: any;
-        let children: any;
-    }
-}
+import React from 'react';
+import type { UniversalLinkProps } from '@plone/volto/components/manage/UniversalLink/UniversalLink';
+declare const _default: React.MemoExoticComponent<React.ForwardRefExoticComponent<{
+    condition?: boolean;
+    to?: string;
+    children: React.ReactNode;
+} & Omit<UniversalLinkProps, "href" | "item"> & {
+    href?: string;
+    item?: UniversalLinkProps["item"];
+} & React.RefAttributes<HTMLAnchorElement | HTMLDivElement>>>;
+export default _default;

package/types/components/manage/UniversalLink/UniversalLink.d.ts

@@ -1,22 +1,56 @@
-export default UniversalLink;
-declare function UniversalLink({ href, item, openLinkInNewTab, download, children, className, title, ...props }: {
-    [x: string]: any;
-    href: any;
-    item?: any;
-    openLinkInNewTab: any;
+import React from 'react';
+import type { ObjectBrowserItem } from '@plone/types';
+type BaseProps = {
+    openLinkInNewTab?: boolean;
     download?: boolean;
-    children: any;
-    className?: any;
-    title?: any;
-}): import("react/jsx-runtime").JSX.Element;
-declare namespace UniversalLink {
-    namespace propTypes {
-        let href: any;
-        let openLinkInNewTab: any;
-        let download: any;
-        let className: any;
-        let title: any;
-        let item: any;
-        let children: any;
-    }
+    children: React.ReactNode;
+    className?: string;
+    title?: string;
+    smooth?: boolean;
+    onClick?: (e: React.MouseEvent) => void;
+    onKeyDown?: (e: React.KeyboardEvent) => void;
+};
+type HrefOnly = {
+    href: string;
+    item?: never;
+} & BaseProps;
+type ItemOnly = {
+    href?: never;
+    item: Partial<ObjectBrowserItem> & {
+        remoteUrl?: string;
+    };
+} & BaseProps;
+export type UniversalLinkProps = HrefOnly | ItemOnly;
+export interface AppState {
+    content: {
+        data?: {
+            '@components'?: {
+                translations?: {
+                    items?: {
+                        language: string;
+                        '@id': string;
+                    }[];
+                };
+            };
+        };
+    };
+    navroot: {
+        data: {
+            navroot: {
+                id: string;
+            };
+        };
+    };
+    intl: {
+        locale: string;
+    };
+    userSession: {
+        token: string | null;
+    };
 }
+export declare const __test: {
+    renderCounter: () => void;
+};
+export declare function getUrl(props: UniversalLinkProps, token: string | null, item: UniversalLinkProps['item'], children: React.ReactNode): string;
+declare const UniversalLink: React.MemoExoticComponent<React.ForwardRefExoticComponent<UniversalLinkProps & React.RefAttributes<HTMLAnchorElement | HTMLDivElement>>>;
+export default UniversalLink;

package/types/react-router-hash-link.d.ts

@@ -0,0 +1,12 @@
+declare module 'react-router-hash-link' {
+  import { ComponentType } from 'react';
+  import { NavLinkProps } from 'react-router-dom';
+
+  interface HashLinkProps extends NavLinkProps {
+    smooth?: boolean;
+    scroll?: (element: HTMLElement) => void;
+  }
+
+  export const HashLink: ComponentType<HashLinkProps>;
+  export const NavHashLink: ComponentType<HashLinkProps>;
+}

package/src/components/manage/ConditionalLink/ConditionalLink.jsx

@@ -1,27 +0,0 @@
-import React from 'react';
-import UniversalLink from '@plone/volto/components/manage/UniversalLink/UniversalLink';
-import PropTypes from 'prop-types';
-
-const ConditionalLink = ({ condition, to, item, ...props }) => {
-  if (condition) {
-    return (
-      <UniversalLink href={to} item={item} {...props}>
-        {props.children}
-      </UniversalLink>
-    );
-  } else {
-    return <>{props.children}</>;
-  }
-};
-
-ConditionalLink.propTypes = {
-  condition: PropTypes.bool,
-  to: PropTypes.string,
-  item: PropTypes.shape({
-    '@id': PropTypes.string,
-    remoteUrl: PropTypes.string, //of plone @type 'Link'
-  }),
-  children: PropTypes.node,
-};
-
-export default ConditionalLink;

package/src/components/manage/ConditionalLink/ConditionalLink.test.jsx

@@ -1,30 +0,0 @@
-import React from 'react';
-import renderer from 'react-test-renderer';
-import { MemoryRouter } from 'react-router-dom';
-
-import ConditionalLink from './ConditionalLink';
-
-describe('ConditionalLink', () => {
-  it('renders a ConditionalLink component not link', () => {
-    const component = renderer.create(
-      <MemoryRouter>
-        <ConditionalLink>
-          <h1>Title</h1>
-        </ConditionalLink>
-      </MemoryRouter>,
-    );
-    const json = component.toJSON();
-    expect(json).toMatchSnapshot();
-  });
-  it('renders a ConditionalLink component with link', () => {
-    const component = renderer.create(
-      <MemoryRouter>
-        <ConditionalLink isLink>
-          <h1>Title</h1>
-        </ConditionalLink>
-      </MemoryRouter>,
-    );
-    const json = component.toJSON();
-    expect(json).toMatchSnapshot();
-  });
-});