add image zoom component (#3829)

* add image zoom component

* tweaks

* lint

* style tweaks

* fix ssr error

* do not add zoom for images inside anchor

* polish

* polish

* polish

* final polish

* add doc

* Create sweet-ears-pump.md

* lint

* polish

* polish

* lgtm

* Update docs/pages/docs/guide/image.mdx

---------

Co-authored-by: Dimitri POSTOLOV <dmytropostolov@gmail.com>

Author: jellli

.changeset/sweet-ears-pump.md

@@ -0,0 +1,8 @@
+---
+"nextra-theme-blog": minor
+"nextra-theme-docs": minor
+"nextra": minor
+---
+
+add [image zoom feature](http://nextra.site/docs/guide/image#image-zoom) for all images written via [GFM syntax](https://github.github.com/gfm/#images)
+in md/mdx files (except images inside links)

docs/next-env.d.ts

@@ -3,4 +3,4 @@
 /// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

docs/pages/docs/guide/image.mdx

@@ -39,3 +39,46 @@ With Next.js Image, there will be no layout shift, and a beautiful blurry
 placeholder will be shown by default when loading the images:
 
 ![Nextra](/og.jpeg)
+
+## Image Zoom
+
+<Callout>The image zoom feature is enabled globally by default.</Callout>
+
+In the default configuration, if you want to use this feature, simply insert
+images using `![]()` Markdown syntax.
+
+### Disable Image Zoom
+
+For `nextra-docs-theme` and `nextra-blog-theme`, you can disable image zoom by
+replacing the `img` component used in MDX.
+
+```jsx filename="theme.config.jsx"
+import { Image } from 'nextra/components'
+
+export default {
+  // ... your other configurations
+  components: {
+    img: props => <Image {...props} />
+  }
+}
+```
+
+### Enable/Disable Image Zoom for Specific Images
+
+When zoom is **disabled globally**, but you want to enable it for specific
+images, you can do so by using the `<ImageZoom>` component:
+
+```mdx
+import { ImageZoom } from 'nextra/components'
+
+<ImageZoom src="/demo.png" />
+```
+
+When zoom is **enabled globally**, and you want to disable zoom for a specific
+image, you can simply use the `<Image>` component:
+
+```mdx
+import { Image } from 'nextra/components'
+
+<Image src="/demo.png" />
+```

package.json

@@ -22,7 +22,7 @@
     "version": "changeset version"
   },
   "devDependencies": {
-    "@changesets/cli": "2.27.9",
+    "@changesets/cli": "2.27.11",
     "@ianvs/prettier-plugin-sort-imports": "4.4.0",
     "@next/eslint-plugin-next": "15.1.0",
     "@rollup/plugin-alias": "^5.1.1",
@@ -53,7 +53,7 @@
       "next": "15.1.0"
     },
     "patchedDependencies": {
-      "@changesets/assemble-release-plan@6.0.4": "patches/@changesets__assemble-release-plan.patch",
+      "@changesets/assemble-release-plan@6.0.5": "patches/@changesets__assemble-release-plan.patch",
       "eslint-plugin-deprecation@3.0.0": "patches/eslint-plugin-deprecation.patch",
       "tsup@8.3.5": "patches/tsup@8.3.5.patch"
     }

packages/nextra-theme-blog/src/styles.css

@@ -6,6 +6,7 @@
 @import 'nextra/styles/scrollbar.css';
 @import 'nextra/styles/steps.css';
 @import 'nextra/styles/cards.css';
+@import 'nextra/styles/react-medium-image-zoom.css';
 
 html {
   @apply _scroll-pt-5;
@@ -32,6 +33,7 @@ h1 {
   &:after {
     @apply _hidden;
   }
+
   .line {
     @apply _font-normal;
   }

packages/nextra-theme-docs/css/styles.css

@@ -6,6 +6,7 @@
 @import 'nextra/styles/scrollbar.css';
 @import 'nextra/styles/steps.css';
 @import 'nextra/styles/cards.css';
+@import 'nextra/styles/react-medium-image-zoom.css';
 @import './hamburger.css';
 @import './typesetting-article.css';
 

packages/nextra/package.json

@@ -150,6 +150,7 @@
     "mdast-util-to-hast": "^13.2.0",
     "negotiator": "^1.0.0",
     "p-limit": "^6.0.0",
+    "react-medium-image-zoom": "^5.2.12",
     "rehype-katex": "^7.0.0",
     "rehype-pretty-code": "0.14.0",
     "rehype-raw": "^7.0.0",

packages/nextra/src/client/components/image-zoom.tsx

@@ -0,0 +1,46 @@
+'use client'
+
+import { type ImageProps } from 'next/image'
+import { useEffect, useRef, useState, type FC } from 'react'
+import Zoom from 'react-medium-image-zoom'
+import { Image } from './image.js'
+
+function getImageSrc(src: ImageProps['src']): string {
+  if (typeof src === 'string') {
+    return src
+  }
+  if ('default' in src) {
+    return src.default.src
+  }
+  return src.src
+}
+
+export const ImageZoom: FC<ImageProps> = props => {
+  const imgRef = useRef<HTMLImageElement>(null!)
+  const [isInsideAnchor, setIsInsideAnchor] = useState(false)
+
+  useEffect(() => {
+    setIsInsideAnchor(imgRef.current.closest('a') !== null)
+  }, [])
+
+  const img = <Image {...props} ref={imgRef} />
+
+  if (isInsideAnchor) {
+    // There is no need to add zoom for images inside anchor tags
+    return img
+  }
+
+  return (
+    <Zoom
+      zoomMargin={40}
+      zoomImg={{
+        src: getImageSrc(props.src),
+        alt: props.alt
+      }}
+      // fix Expected server HTML to contain a matching <div> in <p>.
+      wrapElement="span"
+    >
+      {img}
+    </Zoom>
+  )
+}

packages/nextra/src/client/components/image.tsx

@@ -0,0 +1,12 @@
+import type { ImageProps } from 'next/image'
+import NextImage from 'next/image'
+import { forwardRef } from 'react'
+
+export const Image = forwardRef<HTMLImageElement, ImageProps>((props, ref) => {
+  const ComponentToUse = typeof props.src === 'object' ? NextImage : 'img'
+
+  // @ts-expect-error -- fixme
+  return <ComponentToUse {...props} ref={ref} />
+})
+
+Image.displayName = 'Image'

packages/nextra/src/client/components/index.ts

@@ -4,6 +4,8 @@ export { Cards } from './cards.js'
 export { Code } from './code.js'
 export { CopyToClipboard } from './copy-to-clipboard.js'
 export { FileTree } from './file-tree.js'
+export { Image } from './image.js'
+export { ImageZoom } from './image-zoom.js'
 export { Pre } from './pre.js'
 export { RemoteContent, evaluate } from './remote-content.js'
 export { Steps } from './steps.js'

packages/nextra/src/client/mdx.ts

@@ -1,15 +1,11 @@
 import { useMDXComponents as originalUseMDXComponents } from '@mdx-js/react'
-import Image, { type ImageProps } from 'next/image'
-import { createElement } from 'react'
+import type { ComponentPropsWithoutRef, FC } from 'react'
+import { ImageZoom } from './components/image-zoom.js'
 
 type MDXComponents = ReturnType<typeof originalUseMDXComponents>
 
 const DEFAULT_COMPONENTS = {
-  img: props =>
-    createElement(
-      typeof props.src === 'object' ? Image : 'img',
-      props as ImageProps
-    )
+  img: ImageZoom as FC<ComponentPropsWithoutRef<'img'>>
 } satisfies MDXComponents
 
 export const useMDXComponents: typeof originalUseMDXComponents = components => {

packages/nextra/styles/react-medium-image-zoom.css

@@ -0,0 +1,101 @@
+[data-rmiz-ghost] {
+  position: absolute;
+  pointer-events: none;
+}
+
+[data-rmiz-btn-zoom],
+[data-rmiz-btn-unzoom] {
+  @apply _bg-black/70 _text-white dark:_bg-white/70 dark:_text-black _rounded-full _size-10;
+  outline-offset: 2px;
+  padding: 9px;
+  touch-action: manipulation;
+  appearance: none;
+}
+
+[data-rmiz-btn-zoom] {
+  position: absolute;
+  inset: 10px 10px auto auto;
+  cursor: zoom-in;
+
+  &:not(:focus):not(:active) {
+    position: absolute;
+    clip: rect(0 0 0 0);
+    clip-path: inset(50%);
+    height: 1px;
+    overflow: hidden;
+    pointer-events: none;
+    white-space: nowrap;
+    width: 1px;
+  }
+}
+
+[data-rmiz-btn-unzoom] {
+  position: absolute;
+  inset: 20px 20px auto auto;
+  cursor: zoom-out;
+  z-index: 1;
+}
+
+[data-rmiz-content='found'] {
+  img,
+  svg,
+  [role='img'],
+  [data-zoom] {
+    cursor: zoom-in;
+  }
+}
+
+[data-rmiz-modal]::backdrop {
+  display: none;
+}
+
+[data-rmiz-modal][open] {
+  position: fixed;
+  width: 100vw;
+  width: 100dvw;
+  height: 100vh;
+  height: 100dvh;
+  max-width: none;
+  max-height: none;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  overflow: hidden;
+}
+
+[data-rmiz-modal-overlay] {
+  position: absolute;
+  inset: 0;
+  transition: opacity 0.3s;
+  background: rgba(var(--nextra-bg), 0.8);
+}
+
+[data-rmiz-modal-overlay='hidden'] {
+  opacity: 0%;
+}
+
+[data-rmiz-modal-overlay='visible'] {
+  opacity: 100%;
+}
+
+[data-rmiz-modal-content] {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+[data-rmiz-modal-img] {
+  position: absolute;
+  cursor: zoom-out;
+  image-rendering: high-quality;
+  transform-origin: top left;
+  transition: transform 0.3s;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-rmiz-modal-overlay],
+  [data-rmiz-modal-img] {
+    transition-duration: 0.01ms;
+  }
+}

patches/@changesets__assemble-release-plan.patch

@@ -1,5 +1,5 @@
 diff --git a/dist/changesets-assemble-release-plan.cjs.js b/dist/changesets-assemble-release-plan.cjs.js
-index 4f7b5e5b37bb05874a5c1d8e583e29d4a9593ecf..118d3eaaa2e0615b6813f48fe2618bfebd82a5ca 100644
+index e32a5e5d39c3bd920201b5694632d2b44c92d486..08b9a101d13d112cfaa39f91fdb3a5e8c29bbedc 100644
 --- a/dist/changesets-assemble-release-plan.cjs.js
 +++ b/dist/changesets-assemble-release-plan.cjs.js
 @@ -347,7 +347,7 @@ function shouldBumpMajor({