fix: support direct image hyperlinks

[raymondanythings]

fix #637

Description

adds native support for hyperlinks applied directly to image blocks. While Notion allows hyperlinks via image captions, exposing the link as a caption feels intrusive and affects the user experience.

To address this, we modify the asset-wrapper logic to properly detect and wrap images in anchor tags when a valid image_hyperlink is present.

Solution

1. Introduced getURLInfo()

• Determines whether the image should link to
  • a Notion page (/xxx pattern with UUID),
  • an external URL (validated using a URL regex).

2. Improved link handling logic

• Fallback order: imageHyperlink → caption
• Automatically wraps the image with <components.PageLink> only when a valid link is detected.
• Maintains support for internal Notion page routing via mapPageUrl.

Notion Test Page ID

2061b06afbf1807b8e35d35e7a7fd146

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
react-notion-x	✅ Ready (Inspect)	Visit Preview	Jun 6, 2025 3:54pm
react-notion-x-minimal-demo	✅ Ready (Inspect)	Visit Preview	Jun 6, 2025 3:54pm

[graphite-app]

The caption is now always displayed, even when it's being used as a link URL. This appears to contradict the PR description which mentions "exposing the link as a caption feels intrusive and affects the user experience."

Consider restoring the condition to hide captions when they're used as links:

{value?.properties?.caption && (!urlInfo || imageHyperlink) && (
  <figcaption className='notion-asset-caption'>
    <Text value={value.properties.caption} block={block} />
  </figcaption>
)}

This would hide the caption when it's being used as a link URL (unless imageHyperlink is also present), which aligns with the stated goal of the PR.

Suggested change

	{value?.properties?.caption && (
	<figcaption className='notion-asset-caption'>
	<Text value={value.properties.caption} block={block} />
	</figcaption>
	{value?.properties?.caption && (!urlInfo || imageHyperlink) && (
	<figcaption className='notion-asset-caption'>
	<Text value={value.properties.caption} block={block} />
	</figcaption>
	)}

Spotted by Diamond

Is this helpful? React 👍 or 👎 to let us know.

[graphite-app]

The image_hyperlink property should be marked as optional since it won't be present on all image blocks. Consider updating the type definition to:

format?: {
  image_hyperlink?: string
} & BaseContentBlock['format']

This ensures type safety when working with image blocks that don't contain hyperlinks.

Suggested change

	format: {
	image_hyperlink: string
	} & BaseContentBlock['format']
	format?: {
	image_hyperlink?: string
	} & BaseContentBlock['format']

Spotted by Diamond

Is this helpful? React 👍 or 👎 to let us know.