@tanstack/react-start-client 1.167.3 → 1.168.0

package/src/hydration/load.tsx

@@ -0,0 +1,49 @@
+'use client'
+
+import * as React from 'react'
+
+import {
+  load as coreLoad,
+  withHydrationRenderer,
+} from '@tanstack/start-client-core/hydration'
+import type { HydrationPrefetchStrategy } from '@tanstack/start-client-core/hydration'
+import type { HydrateProps, ReactHydrationStrategy } from '../Hydrate'
+
+function HydratedBoundary(props: {
+  onHydrated?: () => void
+  children: React.ReactNode
+}) {
+  const { onHydrated, children } = props
+  const didHydrateRef = React.useRef(false)
+
+  React.useEffect(() => {
+    if (didHydrateRef.current) return
+    didHydrateRef.current = true
+    onHydrated?.()
+  }, [onHydrated])
+
+  return children as React.JSX.Element
+}
+
+export function LoadHydrate(props: HydrateProps): React.JSX.Element {
+  return (
+    <div>
+      <React.Suspense fallback={props.fallback ?? null}>
+        <HydratedBoundary onHydrated={props.onHydrated}>
+          {props.children}
+        </HydratedBoundary>
+      </React.Suspense>
+    </div>
+  )
+}
+
+const loadStrategy = /* @__PURE__ */ withHydrationRenderer(
+  coreLoad(),
+  LoadHydrate,
+) as ReactHydrationStrategy<'load', true> & HydrationPrefetchStrategy<'load'>
+
+/* @__NO_SIDE_EFFECTS__ */
+export function load(): ReactHydrationStrategy<'load', true> &
+  HydrationPrefetchStrategy<'load'> {
+  return loadStrategy
+}

package/src/hydration/never.tsx

@@ -0,0 +1,97 @@
+'use client'
+
+import * as React from 'react'
+
+import { reactUse, useHydrated } from '@tanstack/react-router'
+import { isServer } from '@tanstack/router-core/isServer'
+import {
+  never as coreNever,
+  withHydrationRenderer,
+} from '@tanstack/start-client-core/hydration'
+import {
+  hydrateIdAttribute,
+  hydrateWhenAttribute,
+} from '@tanstack/start-client-core/hydration/constants'
+import {
+  getFallbackHtml,
+  saveFallbackHtml,
+} from '@tanstack/start-client-core/hydration/runtime'
+import type {
+  HydrateProps,
+  InternalHydrateProps,
+  ReactHydrationStrategy,
+} from '../Hydrate'
+
+const neverType = 'never'
+const neverPromise = new Promise<void>(() => {})
+
+function NeverGate(props: { children: React.ReactNode }) {
+  if (
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    isServer ??
+    typeof window === 'undefined'
+  ) {
+    return props.children as React.JSX.Element
+  }
+
+  if (!reactUse) {
+    throw neverPromise
+  }
+
+  reactUse(neverPromise)
+
+  return props.children as React.JSX.Element
+}
+
+export function NeverHydrate(props: HydrateProps): React.JSX.Element {
+  const internalProps = props as InternalHydrateProps
+  const hydrated = useHydrated()
+  const reactId = React.useId()
+  const id = internalProps.h ? `${internalProps.h}${reactId}` : reactId
+  const shouldPreserveServerHTMLRef = React.useRef<boolean | undefined>(
+    undefined,
+  )
+  shouldPreserveServerHTMLRef.current ??=
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    (isServer ?? typeof window === 'undefined') || !hydrated
+  const markerRef = React.useCallback(
+    (element: HTMLDivElement | null) => {
+      if (!element) return
+      if (!shouldPreserveServerHTMLRef.current) {
+        element.replaceChildren()
+      } else {
+        saveFallbackHtml(id, element)
+      }
+    },
+    [id],
+  )
+  const markerProps = {
+    ref: markerRef,
+    [hydrateIdAttribute]: id,
+    [hydrateWhenAttribute]: neverType,
+  }
+  const fallback = (() => {
+    const html = getFallbackHtml(id)
+    return html ? (
+      <div
+        style={{ display: 'contents' }}
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    ) : (
+      (props.fallback ?? null)
+    )
+  })()
+
+  return (
+    <div {...markerProps}>
+      <React.Suspense fallback={fallback}>
+        <NeverGate>{props.children}</NeverGate>
+      </React.Suspense>
+    </div>
+  )
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export function never(): ReactHydrationStrategy<'never', false> {
+  return /* @__PURE__ */ withHydrationRenderer(coreNever(), NeverHydrate)
+}

package/src/hydration/visible.tsx

@@ -0,0 +1,139 @@
+'use client'
+
+import * as React from 'react'
+
+import { reactUse } from '@tanstack/react-router'
+import { isServer } from '@tanstack/router-core/isServer'
+import type {
+  HydrationPrefetchStrategy,
+  VisibleHydrationOptions,
+} from '@tanstack/start-client-core/hydration'
+import type {
+  HydrateProps,
+  InternalHydrateProps,
+  ReactHydrationStrategy,
+} from '../Hydrate'
+
+type VisibleGate = {
+  p: Promise<void>
+  r: boolean
+  s: () => void
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+function HydrationBoundary(props: {
+  g: VisibleGate
+  o?: () => void
+  children?: React.ReactNode
+}) {
+  const { g, o } = props
+
+  if (!g.r) {
+    if (!reactUse) {
+      throw g.p
+    }
+
+    reactUse(g.p)
+  }
+
+  React.useEffect(() => {
+    o?.()
+  }, [o])
+
+  return props.children as React.JSX.Element
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export function VisibleHydrate(
+  this: ReactHydrationStrategy,
+  props: HydrateProps,
+): React.JSX.Element {
+  const strategy = this as ReactHydrationStrategy<'visible', true>
+  const prefetchStrategy = props.prefetch
+  const preload = (props as InternalHydrateProps).p
+  const markerRef = React.useRef<HTMLDivElement | null>(null)
+  const [gate] = React.useState<VisibleGate>(() => {
+    let resolvePromise!: () => void
+    const nextGate: VisibleGate = {
+      p: new Promise<void>((resolve) => {
+        resolvePromise = resolve
+      }),
+      r: false,
+      s: () => {
+        nextGate.r = true
+        resolvePromise()
+      },
+    }
+    if (
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      isServer ??
+      typeof window === 'undefined'
+    ) {
+      nextGate.s()
+    }
+
+    return nextGate
+  })
+
+  React.useEffect(() => {
+    if (!preload || typeof prefetchStrategy === 'function') {
+      return
+    }
+
+    return prefetchStrategy?._s?.({
+      element: markerRef.current,
+      prefetch: preload,
+    })
+  }, [prefetchStrategy, preload])
+
+  React.useEffect(() => {
+    if (gate.r) return
+
+    return strategy._s?.({
+      element: markerRef.current,
+      gate: gate as never,
+    })
+  }, [gate, strategy])
+
+  return (
+    <div ref={markerRef}>
+      <React.Suspense fallback={props.fallback}>
+        <HydrationBoundary g={gate} o={props.onHydrated}>
+          {props.children}
+        </HydrationBoundary>
+      </React.Suspense>
+    </div>
+  )
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export function visible(
+  options?: VisibleHydrationOptions,
+): ReactHydrationStrategy<'visible', true> &
+  HydrationPrefetchStrategy<'visible'> {
+  const rootMargin = options?.rootMargin ?? '600px'
+  const threshold = options?.threshold ?? 0
+
+  return {
+    _s: ({ element, gate, prefetch }) => {
+      const callback = prefetch || (gate as never as VisibleGate).s
+
+      if (!element) {
+        callback()
+        return
+      }
+
+      const observer = new IntersectionObserver(
+        (entries) => {
+          if (!entries[0]!.isIntersecting) return
+          observer.disconnect()
+          callback()
+        },
+        { rootMargin, threshold },
+      )
+      observer.observe(element)
+      return () => observer.disconnect()
+    },
+    _h: VisibleHydrate,
+  }
+}

package/src/hydration.ts

@@ -0,0 +1,22 @@
+'use client'
+
+export { condition, interaction, media } from './hydration/generic'
+export { idle } from './hydration/idle'
+export { load } from './hydration/load'
+export { never } from './hydration/never'
+export { visible } from './hydration/visible'
+export type {
+  HydrationCondition,
+  HydrationInteractionEvent,
+  HydrationInteractionEvents,
+  IdleHydrationOptions,
+  HydrationPrefetchContext,
+  HydrationPrefetchFunction,
+  HydrationPrefetchWhen,
+  HydrationPrefetchStrategy,
+  HydrationPrefetchWaitReason,
+  HydrationStrategyTypes,
+  HydrationWhen,
+  VisibleHydrationOptions,
+} from '@tanstack/start-client-core/hydration'
+export type { HydrationStrategy, ReactHydrationStrategy } from './Hydrate'

package/src/index.tsx

@@ -1,2 +1,18 @@
+'use client'
+
 export { StartClient } from './StartClient'
 export { hydrateStart } from './hydrateStart'
+export { Hydrate } from './Hydrate'
+export type {
+  HydrateOptions,
+  HydrateProps,
+  HydrateWhen,
+  HydrationInteractionEvent,
+  HydrationInteractionEvents,
+  HydrationPrefetchContext,
+  HydrationPrefetchFunction,
+  HydrationPrefetchStrategy,
+  HydrationPrefetchWaitReason,
+  HydrationStrategy,
+  HydrationWhen,
+} from './Hydrate'

package/src/tests/Hydrate.test-d.tsx

@@ -0,0 +1,147 @@
+import { expectTypeOf, test } from 'vitest'
+import { visible } from '../hydration'
+import { Hydrate } from '../Hydrate'
+import type {
+  HydrateOptions,
+  HydrateProps,
+  HydrationPrefetchFunction,
+  HydrationPrefetchStrategy,
+  HydrationStrategy,
+} from '../Hydrate'
+import type { HydrationStrategy as CoreHydrationStrategy } from '@tanstack/start-client-core/hydration'
+import type { ReactNode } from 'react'
+
+type CommonHydrateProps = {
+  fallback?: ReactNode
+  onHydrated?: () => void
+  children: ReactNode
+}
+
+type SplitHydrateProps = CommonHydrateProps & {
+  when: HydrationStrategy | (() => HydrationStrategy)
+  prefetch?: never
+  split?: boolean
+}
+
+type PrefetchHydrateProps = CommonHydrateProps & {
+  when: HydrationStrategy | (() => HydrationStrategy)
+  prefetch: HydrationPrefetchStrategy
+  split?: true
+}
+
+type FunctionPrefetchHydrateProps = CommonHydrateProps & {
+  when: HydrationStrategy | (() => HydrationStrategy)
+  prefetch: HydrationPrefetchFunction
+  split?: boolean
+}
+
+test('Hydrate component accepts the public HydrateProps type', () => {
+  expectTypeOf(Hydrate).toBeFunction()
+  expectTypeOf(Hydrate).parameter(0).branded.toEqualTypeOf<HydrateProps>()
+})
+
+test('HydrateOptions supports reusable spread props', () => {
+  const belowFoldProps = {
+    when: () => visible({ rootMargin: '800px' }),
+  } satisfies HydrateOptions
+
+  expectTypeOf(belowFoldProps).toMatchTypeOf<HydrateOptions>()
+
+  const withFunctionPrefetch = {
+    when: visible(),
+    split: false,
+    prefetch: (ctx) => {
+      expectTypeOf(ctx.element).toEqualTypeOf<Element | null>()
+      expectTypeOf(ctx.signal).toEqualTypeOf<AbortSignal>()
+      expectTypeOf(ctx.preload).returns.toEqualTypeOf<Promise<void>>()
+      expectTypeOf(ctx.waitFor).returns.toEqualTypeOf<
+        Promise<'prefetch' | 'hydrate' | 'abort'>
+      >()
+    },
+  } satisfies HydrateOptions
+
+  expectTypeOf(withFunctionPrefetch).toMatchTypeOf<HydrateOptions>()
+})
+
+test('Hydrate props are exact for strategy and prefetch forms', () => {
+  expectTypeOf<
+    Extract<HydrateProps, { prefetch?: never }>
+  >().branded.toEqualTypeOf<SplitHydrateProps>()
+  expectTypeOf<
+    Extract<HydrateProps, { prefetch: HydrationPrefetchStrategy }>
+  >().branded.toEqualTypeOf<PrefetchHydrateProps>()
+  expectTypeOf<
+    Extract<HydrateProps, { prefetch: HydrationPrefetchFunction }>
+  >().branded.toEqualTypeOf<FunctionPrefetchHydrateProps>()
+})
+
+test('Hydrate requires a strategy', () => {
+  expectTypeOf<{
+    when: HydrationStrategy
+    children: ReactNode
+  }>().toMatchTypeOf<HydrateProps>()
+
+  expectTypeOf<{
+    when: () => HydrationStrategy
+    children: ReactNode
+  }>().toMatchTypeOf<HydrateProps>()
+
+  expectTypeOf<{
+    children: ReactNode
+  }>().not.toMatchTypeOf<HydrateProps>()
+
+  expectTypeOf<{
+    when: () => true
+    children: ReactNode
+  }>().not.toMatchTypeOf<HydrateProps>()
+
+  expectTypeOf<{
+    when: false
+    children: ReactNode
+  }>().not.toMatchTypeOf<HydrateProps>()
+})
+
+test('Hydrate requires a framework-renderable strategy', () => {
+  expectTypeOf<CoreHydrationStrategy>().not.toMatchTypeOf<HydrationStrategy>()
+  expectTypeOf<ReturnType<typeof visible>>().toMatchTypeOf<HydrationStrategy>()
+
+  expectTypeOf<{
+    when: CoreHydrationStrategy
+    children: ReactNode
+  }>().not.toMatchTypeOf<HydrateProps>()
+})
+
+test('Hydrate enforces prefetch only with split boundaries', () => {
+  expectTypeOf<{
+    when: HydrationStrategy
+    prefetch: HydrationPrefetchStrategy
+    children: ReactNode
+  }>().toMatchTypeOf<HydrateProps>()
+
+  expectTypeOf<{
+    when: HydrationStrategy
+    prefetch: HydrationPrefetchStrategy
+    split: true
+    children: ReactNode
+  }>().toMatchTypeOf<HydrateProps>()
+
+  expectTypeOf<{
+    when: HydrationStrategy
+    prefetch: HydrationPrefetchStrategy
+    split: false
+    children: ReactNode
+  }>().not.toMatchTypeOf<HydrateProps>()
+
+  expectTypeOf<{
+    when: HydrationStrategy
+    prefetch: HydrationPrefetchFunction
+    split: false
+    children: ReactNode
+  }>().toMatchTypeOf<HydrateProps>()
+
+  expectTypeOf<{
+    when: HydrationStrategy
+    prefetch: HydrationPrefetchFunction
+    children: ReactNode
+  }>().toMatchTypeOf<HydrateProps>()
+})