view-anchor 0.2.2 → 1.0.0-beta.0

package/src/react.ts

@@ -1,11 +1,6 @@
-import { useCallback, useEffect, useRef } from 'react'
-import {
-  createPlacementAnchor,
-  createViewAnchor,
-  type PlacementAnchorHandle,
-  type PlacementAnchorOptions,
-} from './view-anchor.js'
-import type { Bounds, ViewAnchorHandle, ViewAnchorOptions } from './types.js'
+import { useCallback, useEffect, useInsertionEffect, useRef, version } from 'react'
+import { createViewAnchor, type ViewAnchorHandle } from './view-anchor.js'
+import type { ViewAnchorOptions } from './view-anchor.js'
 
 export interface UseViewAnchorOptions extends ViewAnchorOptions {
   /**
@@ -18,24 +13,13 @@ export interface UseViewAnchorOptions extends ViewAnchorOptions {
 /** Compatible with React 18's null callback and React 19's ref cleanup. */
 export type ViewAnchorRef = (el: HTMLElement | null) => void | (() => void)
 
-export interface UsePlacementAnchorOptions extends PlacementAnchorOptions {
-  /**
-   * Values that re-apply the anchor when changed. Keep this array's length
-   * stable across renders.
-   */
-  deps?: ReadonlyArray<unknown>
-}
-
-/** Callback ref for the explicit-visibility Placement API. */
-export type PlacementAnchorRef = ViewAnchorRef
-
 type AnchorHandle = { dispose(): void }
 
 interface LifecycleAdapter<Options, Handle extends AnchorHandle> {
   create(target: HTMLElement, options: Options): Handle
   update(handle: Handle, options: Options): void
   collapse(handle: Handle, options: Options): void
-  isCollapsed(options: Options): boolean
+  isCollapsed(handle: Handle, options: Options): boolean
 }
 
 // Callback refs own the imperative anchor because React invokes them during commit.
@@ -50,12 +34,16 @@ function useAnchorRef<Options, Handle extends AnchorHandle>(
   const handleRef = useRef<Handle | null>(null)
   const elementRef = useRef<HTMLElement | null>(null)
   const optionsRef = useRef(options)
-  optionsRef.current = options
   const adapterRef = useRef(adapter)
-  adapterRef.current = adapter
   const appliedRef = useRef(applied)
   const currentAppliedRef = useRef(applied)
-  currentAppliedRef.current = applied
+  // Renders discarded before commit (e.g. suspended transitions) must not
+  // update optionsRef. Insertion effects run before callback refs in the same commit.
+  useInsertionEffect(() => {
+    optionsRef.current = options
+    adapterRef.current = adapter
+    currentAppliedRef.current = applied
+  })
   // Options handed to the adapter on the last create/update call.
   // Tracks applied state across renders where the deps array reference changes.
   const lastAppliedOptionsRef = useRef(options)
@@ -69,7 +57,7 @@ function useAnchorRef<Options, Handle extends AnchorHandle>(
     const handle = handleRef.current
     if (!handle) return
     const adapter = adapterRef.current
-    const alreadyCollapsed = adapter.isCollapsed(lastAppliedOptionsRef.current)
+    const alreadyCollapsed = adapter.isCollapsed(handle, lastAppliedOptionsRef.current)
     try {
       if (!alreadyCollapsed) adapter.collapse(handle, optionsRef.current)
     } finally {
@@ -87,10 +75,15 @@ function useAnchorRef<Options, Handle extends AnchorHandle>(
     })
   }
 
+  // React 19 invokes the cleanup returned from a callback ref instead of calling
+  // ref(null). React 18 warns about the returned function and still calls ref(null).
+  const detachCleanup = (element: HTMLElement): (() => void) | undefined =>
+    Number.parseInt(version, 10) >= 19 ? () => deferDetach(element) : undefined
+
   const ref = useCallback<ViewAnchorRef>((element) => {
     if (element === elementRef.current) {
       cancelPendingDetach()
-      return element ? () => deferDetach(element) : undefined
+      return element ? detachCleanup(element) : undefined
     }
 
     cancelPendingDetach()
@@ -110,7 +103,7 @@ function useAnchorRef<Options, Handle extends AnchorHandle>(
       handleRef.current = adapterRef.current.create(element, optionsRef.current)
       appliedRef.current = currentAppliedRef.current
       lastAppliedOptionsRef.current = optionsRef.current
-      return () => deferDetach(element)
+      return detachCleanup(element)
     }
     return undefined
   }, [])
@@ -141,62 +134,56 @@ function useAnchorRef<Options, Handle extends AnchorHandle>(
   return ref
 }
 
-const viewAdapter: LifecycleAdapter<ViewAnchorOptions, ViewAnchorHandle> = {
-  create: createViewAnchor,
-  update(handle, options) {
-    handle.update(options)
-  },
-  collapse(handle, options) {
-    handle.update({ present: false, publish: options.publish })
-  },
-  isCollapsed(options) {
-    return !options.present
+// Whether each handle's latest { visible: false } was accepted. The core does
+// not retry a rejected hidden placement, so unmount must send it again.
+type HideState = { accepted: boolean }
+const hideStates = new WeakMap<ViewAnchorHandle, HideState>()
+
+const trackHide = (options: ViewAnchorOptions, state: HideState): ViewAnchorOptions => ({
+  ...options,
+  publish(placement) {
+    if (placement.visible) return options.publish(placement)
+    state.accepted = false
+    const result = options.publish(placement)
+    state.accepted = result !== false
+    return result
   },
-}
-
-/** Bind zero-bounds visibility to a DOM element callback ref. */
-export function useViewAnchor(options: UseViewAnchorOptions): ViewAnchorRef {
-  return useAnchorRef(
-    options,
-    [options.present, options.publish, ...(options.deps ?? [])],
-    viewAdapter,
-  )
-}
+})
 
-const placementAdapter: LifecycleAdapter<PlacementAnchorOptions, PlacementAnchorHandle> = {
-  create: createPlacementAnchor,
+const viewAdapter: LifecycleAdapter<ViewAnchorOptions, ViewAnchorHandle> = {
+  create(target, options) {
+    const state: HideState = { accepted: false }
+    const handle = createViewAnchor(target, trackHide(options, state))
+    hideStates.set(handle, state)
+    return handle
+  },
   update(handle, options) {
-    // In React, an omitted option represents "off" for that render,
-    // rather than keeping the previous value.
-    handle.update({
-      ...options,
-      guardDisplayNone: options.guardDisplayNone ?? false,
-      followScroll: options.followScroll ?? false,
-      followGeometry: options.followGeometry ?? false,
-    })
+    // Options are forwarded as-is; the hook applies the same "omitted resets
+    // to default" rule as the core's update().
+    handle.update(trackHide(options, hideStates.get(handle)!))
   },
   collapse(handle, options) {
-    handle.update({ ...options, visible: false })
+    handle.update(trackHide({ ...options, visible: false }, hideStates.get(handle)!))
   },
-  isCollapsed(options) {
-    return !options.visible
+  isCollapsed(handle, options) {
+    return !options.visible && hideStates.get(handle)!.accepted
   },
 }
 
 /** Bind the explicit Placement API to a DOM element callback ref. */
-export function usePlacementAnchor(options: UsePlacementAnchorOptions): PlacementAnchorRef {
+export function useViewAnchor(options: UseViewAnchorOptions): ViewAnchorRef {
   return useAnchorRef(
     options,
     [
       options.visible,
       options.publish,
-      options.guardDisplayNone,
+      options.treatZeroAreaAsHidden,
       options.followScroll,
       options.followGeometry,
+      options.holdSelector,
+      options.dedupe,
       ...(options.deps ?? []),
     ],
-    placementAdapter,
+    viewAdapter,
   )
 }
-
-export type { Bounds }

package/src/size-anchor.ts

@@ -0,0 +1,131 @@
+import type { SizeAnchorOptions, SizeAnchorHandle } from './types.js'
+import { watchAbort } from './abort.js'
+
+// Replaces a disposed instance's publish callback so a retained handle does
+// not keep the caller's original callback (and whatever it captured) alive.
+const NOOP_PUBLISH = (): false => false
+
+/**
+ * Report content size for a single axis back to the host.
+ *
+ * Runs in a downstream document, reads the content size from
+ * `ResizeObserverEntry.borderBoxSize` without triggering reflow, and
+ * publishes at most once per animation frame, skipping unchanged extents by
+ * default (see the `dedupe` option).
+ *
+ * Measurements are rounded to integer pixels and clamped to >= 0.
+ *
+ * `target` must be a shrink-to-fit wrapper on the owned axis.
+ * If its size is driven by the host view itself (such as `<body>` or `<html>`),
+ * updates will not shrink back to content size.
+ */
+export function createSizeAnchor(target: HTMLElement, opts: SizeAnchorOptions): SizeAnchorHandle {
+  const axis = opts.axis
+  let dedupe = opts.dedupe ?? true
+  let publish = opts.publish
+  let observer: ResizeObserver | null = null
+  let rafId: number | null = null
+  let disposed = false
+  // Latest border-box recorded by the ResizeObserver callback.
+  let latestBoxSize: ResizeObserverSize | null = null
+  // Last extent passed to publish; null until one is accepted.
+  let lastPublished: number | null = null
+  let publicationRevision = 0
+
+  const measure = (): number | null => {
+    if (!latestBoxSize) return null
+    const raw = axis === 'block' ? latestBoxSize.blockSize : latestBoxSize.inlineSize
+    if (!Number.isFinite(raw)) return null
+    return Math.max(0, Math.round(raw))
+  }
+
+  const publishExtent = (extent: number): void => {
+    const previous = lastPublished
+    const attempt = ++publicationRevision
+    lastPublished = extent
+    try {
+      const accepted = publish({ axis, extent }) !== false
+      // A reentrant update() or dispose() during publish() already moved the
+      // baseline; do not roll back over that newer state.
+      if (!accepted && publicationRevision === attempt && !disposed) lastPublished = previous
+    } catch (error) {
+      if (publicationRevision === attempt && !disposed) lastPublished = previous
+      throw error
+    }
+  }
+
+  const publishFrame = (): void => {
+    rafId = null
+    if (disposed) return
+    const extent = measure()
+    if (extent === null) return
+    if (dedupe && extent === lastPublished) return
+    publishExtent(extent)
+  }
+
+  const onResize: ResizeObserverCallback = (entries) => {
+    // A callback queued before disconnect() can still fire once more; do not
+    // let it write `latestBoxSize` after dispose() has already cleared it.
+    if (disposed) return
+    const entry = entries[entries.length - 1]
+    if (entry) {
+      latestBoxSize = entry.borderBoxSize?.[0] ?? entry.contentBoxSize?.[0] ?? latestBoxSize
+    }
+    if (rafId === null) rafId = requestAnimationFrame(publishFrame)
+  }
+
+  // Warn if measuring body or documentElement, whose size matches the view.
+  const doc = target.ownerDocument
+  if (target === doc.body || target === doc.documentElement) {
+    console.warn(
+      `[view-anchor] size-anchor: <${target === doc.body ? 'body' : 'html'}>'s ` +
+        `${axis} size is the view size, not content size. The size anchor will ` +
+        `never shrink to content; measure a shrink-to-fit wrapper instead.`,
+    )
+  }
+
+  let removeAbortListener = (): void => {}
+
+  const dispose = (): void => {
+    if (disposed) return
+    disposed = true
+    removeAbortListener()
+    removeAbortListener = (): void => {}
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId)
+      rafId = null
+    }
+    if (observer) {
+      observer.disconnect()
+      observer = null
+    }
+    publish = NOOP_PUBLISH
+    latestBoxSize = null
+    lastPublished = null
+  }
+
+  if (opts.signal?.aborted) dispose()
+  else {
+    removeAbortListener = watchAbort(opts.signal, dispose)
+    observer = new ResizeObserver(onResize)
+    observer.observe(target)
+  }
+
+  return {
+    update(next: Omit<SizeAnchorOptions, 'signal' | 'axis'>): void {
+      if (disposed) return
+      publish = next.publish
+      dedupe = next.dedupe ?? true
+      // The new callback has not accepted anything yet, so an extent the old
+      // callback rejected (or never saw) must not stay latched as the dedupe
+      // baseline — otherwise a later identical tick would be silently
+      // deduped against a value this callback was never actually given.
+      lastPublished = null
+      // Re-publish the current size to the new sink immediately so it is not
+      // empty until the next ResizeObserver tick.
+      const extent = measure()
+      if (extent !== null) publishExtent(extent)
+    },
+    dispose,
+  }
+}

package/src/types.ts

@@ -27,54 +27,46 @@ export type Publisher<T> = (value: T) => PublishResult
  */
 export type Placement = { visible: true; bounds: Bounds } | { visible: false }
 
-export interface ViewAnchorOptions {
-  /**
-   * Whether the native view should be attached. When false, publishes
-   * zero bounds ({ x: 0, y: 0, width: 0, height: 0 }) so the host can detach
-   * the view while keeping its instance alive.
-   */
-  present: boolean
-  /** Receives the live rect, or zero bounds when detached. */
-  publish: Publisher<Bounds>
-  /** Stops this anchor when aborted. An already-aborted signal starts no work. */
-  signal?: AbortSignal
-}
-
-export interface ViewAnchorHandle {
-  /** Apply new options and re-publish immediately. */
-  update(opts: ViewAnchorOptions): void
-  /** Stop observing and clean up listeners. After disposal no further values are published. */
-  dispose(): void
-}
-
-// --- Reverse direction: size advertiser ---
+// --- Reverse direction: size anchor ---
 //
 // Runs in a downstream document to report content size back to the host,
 // allowing the host's DOM placeholder to match the content.
 
-/** Which axis this advertiser reports: 'block' (height) or 'inline' (width). */
-export type AdvertisedAxis = 'block' | 'inline'
+/** Which axis this size anchor reports: 'block' (height) or 'inline' (width). */
+export type SizeAxis = 'block' | 'inline'
 
-/** One frame of advertised size on the owned axis. */
-export interface AdvertisedSize {
-  /** The axis this advertiser reports ('block' or 'inline'). */
-  readonly axis: AdvertisedAxis
-  /** The content extent in CSS pixels, rounded and non-negative. */
+/** One measured size on the owned axis. */
+export interface SizeMeasurement {
+  /** The axis this size anchor reports ('block' or 'inline'). */
+  readonly axis: SizeAxis
+  /**
+   * The target's border-box size on this axis in CSS pixels, rounded and
+   * non-negative. Falls back to the content box where no border box is reported.
+   */
   readonly extent: number
 }
 
-export interface SizeAdvertiserOptions {
-  /** The single axis this advertiser owns. Fixed for the advertiser's lifetime. */
-  axis: AdvertisedAxis
-  /** Receives each advertised size. */
-  publish: Publisher<AdvertisedSize>
-  /** Stops this advertiser when aborted. An already-aborted signal starts no work. */
+export interface SizeAnchorOptions {
+  /** The single axis this size anchor owns. Fixed for its lifetime. */
+  axis: SizeAxis
+  /** Receives each measured size. */
+  publish: Publisher<SizeMeasurement>
+  /** Stops this size anchor when aborted. An already-aborted signal starts no work. */
   signal?: AbortSignal
+  /**
+   * When true (the default), a measurement identical to the last published
+   * extent is not published again. When false, every measurement publishes,
+   * even an unchanged extent. Omitting it in update() resets to true.
+   */
+  dedupe?: boolean
 }
 
-export interface SizeAdvertiserHandle {
-  /** Swap the publish callback and re-advertise the current size immediately. */
-  update(publish: Publisher<AdvertisedSize>): void
+export interface SizeAnchorHandle {
+  /**
+   * Apply a full set of options and re-publish the current size
+   * immediately. Like creation, an omitted dedupe resets to true.
+   */
+  update(opts: Omit<SizeAnchorOptions, 'signal' | 'axis'>): void
   /** Stop observing and cancel any pending animation frame. */
   dispose(): void
 }