feat(strategy): add hover and event-based island mounting

Author: unadlib

README.md

@@ -193,6 +193,8 @@ Control when each island mounts on the client:
 | `'load'`    | Mount immediately (via microtask). **Default.**                                                                          |
 | `'idle'`    | Mount during idle time (`requestIdleCallback`, falls back to `setTimeout(…, 1)`)                                         |
 | `'visible'` | Mount when the host element enters the viewport (`IntersectionObserver` with configurable `rootMargin`, default `200px`) |
+| `'hover'`   | Mount on first `mouseover` or `focusin` on the host                                                                      |
+| `'event'`   | Mount on configured host events (`event` option or `data-fict-react-event`; defaults to `click`)                         |
 | `'only'`    | Client-only rendering — no SSR, no hydration                                                                             |
 
 When `ssr` is `true` (the default), the React subtree is rendered to HTML on the server. On the client, the island hydrates (`hydrateRoot`) if SSR content is present, otherwise it creates a fresh root (`createRoot`).
@@ -205,13 +207,14 @@ Wraps a React component as a Fict component. Props flow reactively from the Fict
 
 **Options** (`ReactInteropOptions`):
 
-| Option              | Type              | Default   | Description                                   |
-| ------------------- | ----------------- | --------- | --------------------------------------------- |
-| `ssr`               | `boolean`         | `true`    | Server-side render the React subtree          |
-| `client`            | `ClientDirective` | `'load'`  | Client mount strategy                         |
-| `visibleRootMargin` | `string`          | `'200px'` | Margin for `'visible'` strategy               |
-| `identifierPrefix`  | `string`          | `''`      | React `useId` prefix for multi-root pages     |
-| `actionProps`       | `string[]`        | `[]`      | Additional callback prop names to materialize |
+| Option              | Type                 | Default   | Description                                   |
+| ------------------- | -------------------- | --------- | --------------------------------------------- |
+| `ssr`               | `boolean`            | `true`    | Server-side render the React subtree          |
+| `client`            | `ClientDirective`    | `'load'`  | Client mount strategy                         |
+| `event`             | `string \| string[]` | —         | Event names for `client: 'event'` mounts      |
+| `visibleRootMargin` | `string`             | `'200px'` | Margin for `'visible'` strategy               |
+| `identifierPrefix`  | `string`             | `''`      | React `useId` prefix for multi-root pages     |
+| `actionProps`       | `string[]`           | `[]`      | Additional callback prop names to materialize |
 
 ### `ReactIsland<P>(props)`
 
@@ -265,20 +268,21 @@ Returns Vite plugins that scope the React JSX transform to a directory.
 
 When using the loader or resumable mode, the following data attributes control island behavior:
 
-| Attribute                      | Mutable | Purpose                                                |
-| ------------------------------ | ------- | ------------------------------------------------------ |
-| `data-fict-react`              | `*`     | QRL pointing to the React component module             |
-| `data-fict-react-props`        | yes     | URL-encoded serialized props                           |
-| `data-fict-react-action-props` | yes     | URL-encoded JSON array of custom action prop names     |
-| `data-fict-react-client`       | no      | Client strategy (`load` / `idle` / `visible` / `only`) |
-| `data-fict-react-ssr`          | no      | `'1'` if SSR content is present                        |
-| `data-fict-react-prefix`       | no      | React `useId` identifier prefix                        |
-| `data-fict-react-host`         | —       | Marks element as a React island host                   |
-| `data-fict-react-mounted`      | —       | Set to `'1'` after the island mounts                   |
+| Attribute                      | Mutable | Purpose                                                                    |
+| ------------------------------ | ------- | -------------------------------------------------------------------------- |
+| `data-fict-react`              | `*`     | QRL pointing to the React component module                                 |
+| `data-fict-react-props`        | yes     | URL-encoded serialized props                                               |
+| `data-fict-react-action-props` | yes     | URL-encoded JSON array of custom action prop names                         |
+| `data-fict-react-client`       | no      | Client strategy (`load` / `idle` / `visible` / `hover` / `event` / `only`) |
+| `data-fict-react-event`        | no      | Comma-separated mount events for `client="event"`                          |
+| `data-fict-react-ssr`          | no      | `'1'` if SSR content is present                                            |
+| `data-fict-react-prefix`       | no      | React `useId` identifier prefix                                            |
+| `data-fict-react-host`         | —       | Marks element as a React island host                                       |
+| `data-fict-react-mounted`      | —       | Set to `'1'` after the island mounts                                       |
 
 `*` Changing the QRL disposes the current root and creates a new one.
 
-Immutable attributes (`data-fict-react-client`, `data-fict-react-ssr`, `data-fict-react-prefix`) emit a warning in development if mutated at runtime. To change them, recreate the host element.
+Immutable attributes (`data-fict-react-client`, `data-fict-react-ssr`, `data-fict-react-prefix`, `data-fict-react-event`) emit a warning in development if mutated at runtime. To change them, recreate the host element.
 
 ## Package Exports
 

src/constants.ts

@@ -6,6 +6,7 @@ export const DATA_FICT_REACT_PROPS = 'data-fict-react-props'
 export const DATA_FICT_REACT_ACTION_PROPS = 'data-fict-react-action-props'
 export const DATA_FICT_REACT_SSR = 'data-fict-react-ssr'
 export const DATA_FICT_REACT_CLIENT = 'data-fict-react-client'
+export const DATA_FICT_REACT_EVENT = 'data-fict-react-event'
 export const DATA_FICT_REACT_MOUNTED = 'data-fict-react-mounted'
 export const DATA_FICT_REACT_PREFIX = 'data-fict-react-prefix'
 

src/eager.ts

@@ -6,19 +6,22 @@ import { renderToString } from 'react-dom/server'
 import { materializeReactProps } from './action'
 import {
   DATA_FICT_REACT_CLIENT,
+  DATA_FICT_REACT_EVENT,
   DATA_FICT_REACT_HOST,
   DATA_FICT_REACT_MOUNTED,
   DATA_FICT_REACT_PREFIX,
   DATA_FICT_REACT_SSR,
   DEFAULT_CLIENT_DIRECTIVE,
 } from './constants'
+import { normalizeMountEvents } from './mount-events'
 import { mountReactRoot, type MountedReactRoot } from './react-root'
 import { scheduleByClientDirective } from './strategy'
 import type { ReactIslandProps, ReactInteropOptions } from './types'
 
 interface NormalizedReactInteropOptions {
   client: NonNullable<ReactInteropOptions['client']>
   ssr: boolean
+  events: string[]
   visibleRootMargin: string
   identifierPrefix: string
   actionProps: string[]
@@ -29,10 +32,12 @@ function normalizeOptions(options?: ReactInteropOptions): NormalizedReactInterop
   const actionProps = Array.from(
     new Set((options?.actionProps ?? []).map((name) => name.trim()).filter(Boolean)),
   )
+  const events = normalizeMountEvents(options?.event)
 
   return {
     client,
     ssr: client === 'only' ? false : options?.ssr !== false,
+    events,
     visibleRootMargin: options?.visibleRootMargin ?? '200px',
     identifierPrefix: options?.identifierPrefix ?? '',
     actionProps,
@@ -93,6 +98,9 @@ function createReactHost<P extends Record<string, unknown>>(runtime: ReactHostRu
   if (normalized.identifierPrefix) {
     hostProps[DATA_FICT_REACT_PREFIX] = normalized.identifierPrefix
   }
+  if (normalized.events.length > 0) {
+    hostProps[DATA_FICT_REACT_EVENT] = normalized.events.join(',')
+  }
 
   if (isSSR && normalized.ssr) {
     const ssrNode = createReactElement(
@@ -139,6 +147,7 @@ function createReactHost<P extends Record<string, unknown>>(runtime: ReactHostRu
       }
 
       mountCleanup = scheduleByClientDirective(normalized.client, host, mount, {
+        events: normalized.events,
         visibleRootMargin: normalized.visibleRootMargin,
       })
     })
@@ -191,6 +200,9 @@ export function ReactIsland<P extends Record<string, unknown>>(props: ReactIslan
   if (props.actionProps !== undefined) {
     islandOptions.actionProps = props.actionProps
   }
+  if (props.event !== undefined) {
+    islandOptions.event = props.event
+  }
 
   return createReactHost({
     component: props.component,

src/loader.ts

@@ -5,13 +5,15 @@ import { loadLoaderComponentModule } from './component-module-loader'
 import {
   DATA_FICT_REACT_ACTION_PROPS,
   DATA_FICT_REACT_CLIENT,
+  DATA_FICT_REACT_EVENT,
   DATA_FICT_REACT_MOUNTED,
   DATA_FICT_REACT_PREFIX,
   DATA_FICT_REACT_PROPS,
   DATA_FICT_REACT_QRL,
   DATA_FICT_REACT_SSR,
   DEFAULT_CLIENT_DIRECTIVE,
 } from './constants'
+import { normalizeMountEvents } from './mount-events'
 import { parseQrl, resolveModuleUrl } from './qrl'
 import { mountReactRoot, type MountedReactRoot } from './react-root'
 import { decodePropsFromAttribute } from './serialization'
@@ -98,7 +100,14 @@ function warnImmutableAttrMutation(host: HTMLElement, attrName: string): void {
 }
 
 function isClientDirective(value: string | null | undefined): value is ClientDirective {
-  return value === 'load' || value === 'idle' || value === 'visible' || value === 'only'
+  return (
+    value === 'load' ||
+    value === 'idle' ||
+    value === 'visible' ||
+    value === 'hover' ||
+    value === 'event' ||
+    value === 'only'
+  )
 }
 
 function pickClientDirective(host: HTMLElement, fallback: ClientDirective): ClientDirective {
@@ -162,6 +171,10 @@ function readIdentifierPrefix(host: HTMLElement): string | undefined {
   return value ?? undefined
 }
 
+function readMountEvents(host: HTMLElement): string[] {
+  return normalizeMountEvents(host.getAttribute(DATA_FICT_REACT_EVENT))
+}
+
 function createIslandRuntime(
   host: HTMLElement,
   options: Required<ReactIslandsLoaderOptions>,
@@ -177,6 +190,7 @@ function createIslandRuntime(
   const client = pickClientDirective(host, options.defaultClient)
   const canHydrate = host.getAttribute(DATA_FICT_REACT_SSR) === '1' && client !== 'only'
   const identifierPrefix = readIdentifierPrefix(host)
+  const mountEvents = readMountEvents(host)
 
   let disposed = false
   let root: MountedReactRoot | null = null
@@ -274,8 +288,10 @@ function createIslandRuntime(
     document?: Document
     window?: Window
     visibleRootMargin?: string
+    events?: string[]
   } = {
     document: host.ownerDocument,
+    events: mountEvents,
     visibleRootMargin: options.visibleRootMargin,
   }
   const ownerWindow = host.ownerDocument.defaultView
@@ -378,7 +394,8 @@ export function installReactIslands(rawOptions: ReactIslandsLoaderOptions = {}):
           if (
             mutation.attributeName === DATA_FICT_REACT_CLIENT ||
             mutation.attributeName === DATA_FICT_REACT_SSR ||
-            mutation.attributeName === DATA_FICT_REACT_PREFIX
+            mutation.attributeName === DATA_FICT_REACT_PREFIX ||
+            mutation.attributeName === DATA_FICT_REACT_EVENT
           ) {
             if (runtimes.has(target)) {
               warnImmutableAttrMutation(target, mutation.attributeName)
@@ -415,6 +432,7 @@ export function installReactIslands(rawOptions: ReactIslandsLoaderOptions = {}):
         DATA_FICT_REACT_CLIENT,
         DATA_FICT_REACT_SSR,
         DATA_FICT_REACT_PREFIX,
+        DATA_FICT_REACT_EVENT,
       ],
     })
   }

src/mount-events.ts

@@ -0,0 +1,41 @@
+function pushEventNames(raw: string, out: string[]): void {
+  const input = raw.trim()
+  if (!input) return
+
+  if (input.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(input) as unknown
+      if (Array.isArray(parsed)) {
+        for (const name of parsed) {
+          if (typeof name !== 'string') continue
+          const trimmed = name.trim()
+          if (trimmed) out.push(trimmed)
+        }
+        return
+      }
+    } catch {
+      // Fall through to comma parsing.
+    }
+  }
+
+  for (const part of input.split(',')) {
+    const trimmed = part.trim()
+    if (trimmed) out.push(trimmed)
+  }
+}
+
+export function normalizeMountEvents(value: string | string[] | null | undefined): string[] {
+  if (value == null) return []
+
+  const values: string[] = []
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item !== 'string') continue
+      pushEventNames(item, values)
+    }
+  } else if (typeof value === 'string') {
+    pushEventNames(value, values)
+  }
+
+  return Array.from(new Set(values))
+}

src/resumable.ts

@@ -8,6 +8,7 @@ import { loadResumableComponentModule } from './component-module-loader'
 import {
   DATA_FICT_REACT_ACTION_PROPS,
   DATA_FICT_REACT_CLIENT,
+  DATA_FICT_REACT_EVENT,
   DATA_FICT_REACT_HOST,
   DATA_FICT_REACT_MOUNTED,
   DATA_FICT_REACT_PREFIX,
@@ -16,6 +17,7 @@ import {
   DATA_FICT_REACT_SSR,
   DEFAULT_CLIENT_DIRECTIVE,
 } from './constants'
+import { normalizeMountEvents } from './mount-events'
 import { parseQrl, resolveModuleUrl } from './qrl'
 import { mountReactRoot, type MountedReactRoot } from './react-root'
 import { encodePropsForAttribute } from './serialization'
@@ -29,6 +31,7 @@ const COMPONENT_LOAD_RETRY_MAX_FAILURES = 5
 interface NormalizedReactInteropOptions {
   client: NonNullable<ReactInteropOptions['client']>
   ssr: boolean
+  events: string[]
   visibleRootMargin: string
   identifierPrefix: string
   actionProps: string[]
@@ -41,10 +44,12 @@ function normalizeOptions(options?: ReactInteropOptions): NormalizedReactInterop
   const actionProps = Array.from(
     new Set((options?.actionProps ?? []).map((name) => name.trim()).filter(Boolean)),
   )
+  const events = normalizeMountEvents(options?.event)
 
   return {
     client,
     ssr: client === 'only' ? false : options?.ssr !== false,
+    events,
     visibleRootMargin: options?.visibleRootMargin ?? '200px',
     identifierPrefix: options?.identifierPrefix ?? '',
     actionProps,
@@ -178,6 +183,9 @@ export function reactify$<P extends Record<string, unknown>>(
         JSON.stringify(normalized.actionProps),
       )
     }
+    if (normalized.events.length > 0) {
+      hostProps[DATA_FICT_REACT_EVENT] = normalized.events.join(',')
+    }
 
     if (isSSR && normalized.ssr && resolvedComponent) {
       const ssrNode = createReactElement(
@@ -258,6 +266,7 @@ export function reactify$<P extends Record<string, unknown>>(
         }
 
         mountCleanup = scheduleByClientDirective(normalized.client, host, mount, {
+          events: normalized.events,
           visibleRootMargin: normalized.visibleRootMargin,
         })
       })

src/strategy.ts

@@ -5,6 +5,7 @@ interface ClientScheduleOptions {
   document?: Document
   window?: Window
   visibleRootMargin?: string
+  events?: string[]
 }
 
 export function scheduleByClientDirective(
@@ -24,6 +25,26 @@ export function scheduleByClientDirective(
     mount()
   }
 
+  const bindHostEvents = (eventNames: readonly string[]) => {
+    const names = eventNames.length > 0 ? eventNames : ['click']
+    const listeners: { name: string; handler: EventListener }[] = []
+
+    for (const name of names) {
+      const handler: EventListener = () => {
+        runMount()
+      }
+      listeners.push({ name, handler })
+      host.addEventListener(name, handler, { once: true })
+    }
+
+    return () => {
+      canceled = true
+      for (const { name, handler } of listeners) {
+        host.removeEventListener(name, handler)
+      }
+    }
+  }
+
   const scheduleLoad = () => {
     queueMicrotask(runMount)
     return () => {
@@ -86,6 +107,14 @@ export function scheduleByClientDirective(
     return () => observer.disconnect()
   }
 
+  if (strategy === 'hover') {
+    return bindHostEvents(['mouseover', 'focusin'])
+  }
+
+  if (strategy === 'event') {
+    return bindHostEvents(options.events ?? [])
+  }
+
   runMount()
   return () => {}
 }

src/types.ts

@@ -4,7 +4,7 @@ import type { ComponentType } from 'react'
 /**
  * Controls when the React island mounts on the client.
  */
-export type ClientDirective = 'load' | 'idle' | 'visible' | 'only'
+export type ClientDirective = 'load' | 'idle' | 'visible' | 'hover' | 'event' | 'only'
 
 export interface ReactInteropOptions {
   /**
@@ -17,6 +17,13 @@ export interface ReactInteropOptions {
    * @default 'load'
    */
   client?: ClientDirective
+  /**
+   * Custom DOM event names that trigger mounting when `client: 'event'`.
+   * String values accept comma-separated names.
+   * @example 'click'
+   * @example ['focusin', 'keydown']
+   */
+  event?: string | string[]
   /**
    * Root margin for visible strategy.
    * @default '200px'