feat(api): support configurable island host tagName

Author: unadlib

README.md

@@ -214,6 +214,7 @@ Wraps a React component as a Fict component. Props flow reactively from the Fict
 | `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     |
+| `tagName`           | `string`             | `'div'`   | Host element tag used by the island wrapper   |
 | `actionProps`       | `string[]`           | `[]`      | Additional callback prop names to materialize |
 
 ### `ReactIsland<P>(props)`

src/eager.ts

@@ -24,9 +24,15 @@ interface NormalizedReactInteropOptions {
   events: string[]
   visibleRootMargin: string
   identifierPrefix: string
+  tagName: string
   actionProps: string[]
 }
 
+function normalizeHostTagName(tagName: string | undefined): string {
+  const normalized = tagName?.trim()
+  return normalized && normalized.length > 0 ? normalized : 'div'
+}
+
 function normalizeOptions(options?: ReactInteropOptions): NormalizedReactInteropOptions {
   const client = options?.client ?? DEFAULT_CLIENT_DIRECTIVE
   const actionProps = Array.from(
@@ -40,6 +46,7 @@ function normalizeOptions(options?: ReactInteropOptions): NormalizedReactInterop
     events,
     visibleRootMargin: options?.visibleRootMargin ?? '200px',
     identifierPrefix: options?.identifierPrefix ?? '',
+    tagName: normalizeHostTagName(options?.tagName),
     actionProps,
   }
 }
@@ -165,7 +172,7 @@ function createReactHost<P extends Record<string, unknown>>(runtime: ReactHostRu
   }
 
   return {
-    type: 'div',
+    type: normalized.tagName,
     props: hostProps,
   }
 }
@@ -197,6 +204,9 @@ export function ReactIsland<P extends Record<string, unknown>>(props: ReactIslan
   if (props.identifierPrefix !== undefined) {
     islandOptions.identifierPrefix = props.identifierPrefix
   }
+  if (props.tagName !== undefined) {
+    islandOptions.tagName = props.tagName
+  }
   if (props.actionProps !== undefined) {
     islandOptions.actionProps = props.actionProps
   }

src/resumable.ts

@@ -34,11 +34,17 @@ interface NormalizedReactInteropOptions {
   events: string[]
   visibleRootMargin: string
   identifierPrefix: string
+  tagName: string
   actionProps: string[]
 }
 
 type ReactComponentModule = Record<string, unknown>
 
+function normalizeHostTagName(tagName: string | undefined): string {
+  const normalized = tagName?.trim()
+  return normalized && normalized.length > 0 ? normalized : 'div'
+}
+
 function normalizeOptions(options?: ReactInteropOptions): NormalizedReactInteropOptions {
   const client = options?.client ?? DEFAULT_CLIENT_DIRECTIVE
   const actionProps = Array.from(
@@ -52,6 +58,7 @@ function normalizeOptions(options?: ReactInteropOptions): NormalizedReactInterop
     events,
     visibleRootMargin: options?.visibleRootMargin ?? '200px',
     identifierPrefix: options?.identifierPrefix ?? '',
+    tagName: normalizeHostTagName(options?.tagName),
     actionProps,
   }
 }
@@ -286,7 +293,7 @@ export function reactify$<P extends Record<string, unknown>>(
     }
 
     return {
-      type: 'div',
+      type: normalized.tagName,
       props: hostProps,
     }
   }

src/types.ts

@@ -33,6 +33,11 @@ export interface ReactInteropOptions {
    * Stable React identifier prefix for useId in multi-root pages.
    */
   identifierPrefix?: string
+  /**
+   * Host element tag used by Fict wrappers (`reactify`, `ReactIsland`, `reactify$`).
+   * @default 'div'
+   */
+  tagName?: string
   /**
    * Additional prop names that should be treated as action callbacks.
    * By default only /^on[A-Z]/ props are materialized.

test/reactify.test.ts

@@ -221,6 +221,28 @@ describe('reactify', () => {
 
     dispose()
   })
+
+  it('uses a custom host tag name when configured', async () => {
+    const CustomHost = reactify(
+      ({ value }: { value: string }) => React.createElement('span', { id: 'custom-host' }, value),
+      {
+        tagName: 'section',
+      },
+    )
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+
+    const dispose = render(() => ({ type: CustomHost, props: { value: 'ok' } }), container)
+    await tick()
+
+    const host = container.querySelector('[data-fict-react-host]') as HTMLElement | null
+    expect(host).not.toBeNull()
+    expect(host?.tagName).toBe('SECTION')
+    expect(container.querySelector('#custom-host')?.textContent).toBe('ok')
+
+    dispose()
+  })
 })
 
 describe('ReactIsland', () => {
@@ -270,4 +292,33 @@ describe('ReactIsland', () => {
 
     dispose()
   })
+
+  it('supports custom host tag name on ReactIsland', async () => {
+    function Label(props: { text: string }) {
+      return React.createElement('p', { id: 'island-custom-host' }, props.text)
+    }
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+
+    const dispose = render(
+      () => ({
+        type: ReactIsland,
+        props: {
+          component: Label,
+          tagName: 'article',
+          props: { text: 'custom' },
+        },
+      }),
+      container,
+    )
+    await tick()
+
+    const host = container.querySelector('[data-fict-react-host]') as HTMLElement | null
+    expect(host).not.toBeNull()
+    expect(host?.tagName).toBe('ARTICLE')
+    expect(container.querySelector('#island-custom-host')?.textContent).toBe('custom')
+
+    dispose()
+  })
 })

test/resumable.test.ts

@@ -297,6 +297,38 @@ describe('reactify$', () => {
       dispose()
     }
   })
+
+  it('uses a custom host tag name when configured', async () => {
+    const fixtureModule = new URL('./fixtures/loader-component.ts', import.meta.url).href
+    const Remote = reactify$<{ label: string; count: number }>({
+      module: fixtureModule,
+      export: 'LoaderComponent',
+      ssr: false,
+      tagName: 'section',
+    })
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+
+    const dispose = render(
+      () => ({
+        type: Remote,
+        props: { label: 'host-tag', count: 8 },
+      }),
+      container,
+    )
+    try {
+      const host = container.querySelector('[data-fict-react]') as HTMLElement | null
+      expect(host).not.toBeNull()
+      expect(host?.tagName).toBe('SECTION')
+
+      await waitForExpectation(() => {
+        expect(container.textContent).toContain('host-tag:8')
+      })
+    } finally {
+      dispose()
+    }
+  })
 })
 
 describe('installReactIslands', () => {