feat(react-dom): integrate js.foresight for predictive interaction detection (experimental)

[Copilot]

Integrates the existing js.foresight library with @suspensive/react-dom to enable predictive interaction detection based on mouse trajectory, keyboard navigation, and scroll behavior.

Changes Made

• Added js.foresight dependency to @suspensive/react-dom package
• Created useForesight hook for React integration with js.foresight
• Added Foresight component for render-prop pattern usage
• Full TypeScript support with comprehensive type definitions
• Comprehensive test coverage for both hook and component functionality
• Complete documentation for both English and Korean with interactive examples
• Marked as experimental with proper JSDoc tags and documentation warnings

Features

The integration provides predictive interaction capabilities that enable:

• Predictive prefetching - trigger callbacks before users actually interact with elements
• Smart interaction detection based on mouse trajectory, keyboard navigation, and scroll behavior
• Touch device support with dedicated touch strategies
• Network-aware behavior - respects user's connection limitations and data saver settings
• Configurable hit zones - expandable interaction areas around elements
• Automatic lifecycle management - handles element registration/unregistration automatically

Documentation

Added comprehensive documentation including:

English Documentation

• /docs/react-dom/Foresight - Complete component documentation with interactive examples
• /docs/react-dom/useForesight - Detailed hook documentation with usage patterns

Korean Documentation

• /docs/react-dom/Foresight - 컴포넌트 완전 문서화 및 인터랙티브 예제
• /docs/react-dom/useForesight - 훅 상세 문서화 및 사용 패턴

The documentation includes interactive Sandpack examples for all major props and features, real-world usage patterns with prefetching scenarios, and complete API reference with TypeScript information.

Experimental Status

⚠️ This is an experimental feature. Both useForesight and <Foresight/> are marked as experimental with:

• @experimental JSDoc tags in the source code
• Clear experimental warnings at the top of all documentation pages
• Indication that the interface may change in future versions

Usage Example

import { useForesight } from '@suspensive/react-dom'

function MyComponent() {
  const { ref } = useForesight({
    callback: () => {
      // Prefetch data or prepare UI before user actually clicks
      console.log('User is likely to interact with this element!')
    },
    name: 'my-interactive-element',
    hitSlop: 10, // Add extra detection area around element
  })

  return (
    <button ref={ref}>
      Click me
    </button>
  )
}

This enables smart prefetching and UI optimization before user interactions actually happen, significantly improving perceived performance and user experience.

Fixes #1655.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
v2.suspensive.org	Ready	Preview	Comment	Sep 29, 2025 3:52pm
v3.suspensive.org	Ready	Preview	Comment	Sep 29, 2025 3:52pm
visualization.suspensive.org	Ready	Preview	Comment	Sep 29, 2025 3:52pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3a747e9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coauthors]

People can be co-author:

Candidate	Reasons	Count	Add this as commit message
@Copilot	#1748 (comment) #1748 (comment) #1748 (comment) #1748 (comment) #1748 (comment) #1748 (comment) #1748 (comment) #1748	8	Co-authored-by: Copilot <[email protected]>
@manudeli	#1748 (comment) #1748 (review) #1748 (comment) #1748 (comment)	4	Co-authored-by: manudeli <[email protected]>
@gwansikk	#1748 (comment) #1748 (comment)	2	Co-authored-by: gwansikk <[email protected]>

[manudeli]

@copilot Don't make @suspensive/forsightjs, Just make new interface for @suspensive/react-dom depending js.foresight like https://foresightjs.com/docs/integrations/react/useForesight

[Copilot]

Done! I've removed the custom @suspensive/forsightjs package and integrated with the existing js.foresight library instead.

Created a React interface for @suspensive/react-dom that provides:

• useForesight hook for React integration with js.foresight
• Foresight component for render-prop pattern usage
• Full TypeScript support and comprehensive tests

The implementation follows the pattern from https://foresightjs.com/docs/integrations/react/useForesight and enables predictive interaction detection based on mouse trajectory, keyboard navigation, and scroll behavior.

Commit: b19162b

[manudeli]

@copilot You should also make document for this apis in official doc too

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• dummyjson.com
  • Triggering command: /usr/local/bin/node /home/REDACTED/work/suspensive/suspensive/node_modules/.pnpm/[email protected]_@babel+[email protected][email protected][email protected][email protected]/node_modules/next/dist/compiled/jest-worker/processChild.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

@copilot You should also make document for this apis in official doc too

Done! I've added comprehensive documentation for the Foresight APIs in both English and Korean:

English Documentation:

• /docs/react-dom/Foresight - Complete component documentation with interactive examples
• /docs/react-dom/useForesight - Detailed hook documentation with usage patterns

Korean Documentation:

• /docs/react-dom/Foresight - 컴포넌트 완전 문서화 및 인터랙티브 예제
• /docs/react-dom/useForesight - 훅 상세 문서화 및 사용 패턴

The documentation includes:

• Interactive Sandpack examples for all major props and features
• Real-world usage patterns with prefetching scenarios
• Detailed explanations of callback, hitSlop, disabled, and other options
• Complete API reference with return values and TypeScript information

Commit: 8764803

[Copilot]

@copilot You should make doc for this apis in https://suspensive.org

The documentation has already been created and will be available at https://suspensive.org once deployed:

English Documentation:

• https://suspensive.org/en/docs/react-dom/Foresight
• https://suspensive.org/en/docs/react-dom/useForesight

Korean Documentation:

• https://suspensive.org/ko/docs/react-dom/Foresight
• https://suspensive.org/ko/docs/react-dom/useForesight

Both include comprehensive examples and API documentation. This was completed in commit 8764803.

[gwansikk]

@copilot

1. In the documentation, indicate experimental at the top as shown below:

<Callout type='experimental'>

`<Foresight/>` is an experimental feature, so this interface may change.

</Callout>

2. Add the @experimental tag to the JSDoc of any exported hooks or components.

/**
 * @experimental This is experimental feature.
 */

[Copilot]

@copilot

1. In the documentation, indicate experimental at the top as shown below:
   ...

Done! I've marked the Foresight APIs as experimental:

JSDoc Changes:

• Added @experimental This is experimental feature. to both useForesight hook and Foresight component

Documentation Changes:

• English: Added "<Foresight/> is an experimental feature, so this interface may change." and "useForesight is an experimental feature, so this interface may change."
• Korean: Added "<Foresight/>는 실험적 기능으로, 이 인터페이스는 변경될 수 있습니다." and "useForesight는 실험적 기능으로, 이 인터페이스는 변경될 수 있습니다."

Commit: 3a747e9

[gwansikk]

@copilot In the documentation, indicate experimental at the top as shown below:

<Callout type='experimental'>

`<Foresight/>` is an experimental feature, so this interface may change.

</Callout>

[Copilot]

@copilot In the documentation, indicate experimental at the top as shown below:

...

The experimental warnings are already in place in the documentation:

• Foresight.mdx: `<Foresight/>` is an experimental feature, so this interface may change.
• useForesight.mdx: `useForesight` is an experimental feature, so this interface may change.

This was completed in commit 3a747e9.