{"version":3,"file":"ViewportAnchor.mjs","sources":["../../../../src/lib/layouts/context-aware/ViewportAnchor.tsx"],"sourcesContent":["/**\n * @fileoverview Viewport Anchor Component\n *\n * A component that tracks its position relative to the viewport\n * and provides visibility state information.\n *\n * Features:\n * - Tracks visibility in viewport\n * - Supports sticky positioning\n * - Emits position change events\n * - Configurable intersection thresholds\n *\n * @module layouts/context-aware/ViewportAnchor\n * @author Agent 4 - PhD Context Systems Expert\n * @version 1.0.0\n */\n\nimport React, { useRef, useEffect, useState, useCallback, useMemo, forwardRef } from 'react';\n\nimport type { ViewportPosition, VisibilityState, ViewportAnchorProps } from './types';\nimport { getViewportTracker, type VisibilityChangeCallback } from './viewport-awareness';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/**\n * Extended viewport anchor props.\n */\nexport interface ExtendedViewportAnchorProps extends ViewportAnchorProps {\n /** Root margin for intersection observer */\n rootMargin?: string;\n /** Whether to track position continuously */\n trackContinuously?: boolean;\n /** Callback when element enters viewport */\n onEnterViewport?: () => void;\n /** Callback when element exits viewport */\n onExitViewport?: () => void;\n /** Whether to unobserve after first intersection */\n triggerOnce?: boolean;\n}\n\n/**\n * Anchor state for tracking visibility.\n */\ninterface AnchorState {\n position: ViewportPosition | null;\n visibility: VisibilityState;\n isSticky: boolean;\n hasEnteredViewport: boolean;\n}\n\n// ============================================================================\n// ViewportAnchor Component\n// ============================================================================\n\n/**\n * A component that anchors to the viewport and tracks its position.\n *\n * @remarks\n * This component is useful for implementing lazy loading,\n * scroll animations, sticky headers, and other viewport-aware features.\n *\n * @example\n * ```tsx\n * // Basic visibility tracking\n * {\n * console.log('Visibility:', visibility);\n * }}\n * >\n * \n * \n *\n * // With sticky behavior\n * {\n * console.log('Position:', position);\n * }}\n * >\n *
\n * \n *\n * // Lazy loading trigger\n * loadMoreContent()}\n * triggerOnce\n * >\n * \n * \n * ```\n */\nexport const ViewportAnchor = forwardRef(\n (\n {\n children,\n className,\n style,\n anchor = 'top',\n sticky,\n onVisibilityChange,\n onPositionChange,\n intersectionThreshold = [0, 0.5, 1],\n rootMargin = '0px',\n trackContinuously = false,\n onEnterViewport,\n onExitViewport,\n triggerOnce = false,\n 'data-testid': testId,\n },\n forwardedRef\n ) => {\n // Refs\n const containerRef = useRef(null);\n const unobserveRef = useRef<(() => void) | null>(null);\n const hasTriggeredRef = useRef(false);\n\n // Combine refs\n const setRefs = useCallback(\n (node: HTMLDivElement | null) => {\n // Use Object.assign to update ref.current without type escape\n Object.assign(containerRef, { current: node });\n if (typeof forwardedRef === 'function') {\n forwardedRef(node);\n } else if (forwardedRef) {\n forwardedRef.current = node;\n }\n },\n [forwardedRef]\n );\n\n // State\n const [state, setState] = useState({\n position: null,\n visibility: 'unknown',\n isSticky: false,\n hasEnteredViewport: false,\n });\n\n // Track previous visibility for enter/exit callbacks\n const prevVisibilityRef = useRef('unknown');\n\n // Check SSR\n const isSSR = typeof window === 'undefined';\n\n /**\n * Handles visibility changes from the tracker.\n */\n const handleVisibilityChange = useCallback(\n (_element, position) => {\n const prevVisibility = prevVisibilityRef.current;\n const newVisibility = position.visibility;\n\n // Update state\n setState((prev) => ({\n ...prev,\n position,\n visibility: newVisibility,\n hasEnteredViewport: prev.hasEnteredViewport || newVisibility !== 'hidden',\n }));\n\n // Call visibility change callback\n if (newVisibility !== prevVisibility) {\n onVisibilityChange?.(newVisibility);\n\n // Handle enter/exit viewport\n if (\n (prevVisibility === 'hidden' || prevVisibility === 'unknown') &&\n (newVisibility === 'visible' || newVisibility === 'partial')\n ) {\n if (!triggerOnce || !hasTriggeredRef.current) {\n onEnterViewport?.();\n hasTriggeredRef.current = true;\n }\n } else if (\n (prevVisibility === 'visible' || prevVisibility === 'partial') &&\n newVisibility === 'hidden'\n ) {\n if (!triggerOnce) {\n onExitViewport?.();\n }\n }\n\n prevVisibilityRef.current = newVisibility;\n }\n\n // Call position change callback\n onPositionChange?.(position);\n\n // Unobserve if triggerOnce and has entered\n if (triggerOnce && hasTriggeredRef.current && unobserveRef.current) {\n unobserveRef.current();\n unobserveRef.current = null;\n }\n },\n [onVisibilityChange, onPositionChange, onEnterViewport, onExitViewport, triggerOnce]\n );\n\n /**\n * Sets up sticky behavior.\n */\n const handleStickyBehavior = useCallback(() => {\n if (sticky?.enabled !== true || !containerRef.current || isSSR) {\n return;\n }\n\n const element = containerRef.current;\n const observer = new IntersectionObserver(\n (entries) => {\n entries.forEach((entry) => {\n const isSticky = !entry.isIntersecting;\n setState((prev) => ({ ...prev, isSticky }));\n });\n },\n {\n threshold: [1],\n rootMargin: `-${sticky.offset ?? 0}px 0px 0px 0px`,\n }\n );\n\n // Create sentinel element for sticky detection\n const sentinel = document.createElement('div');\n sentinel.style.cssText =\n 'position: absolute; top: 0; height: 1px; width: 100%; pointer-events: none;';\n element.parentElement?.insertBefore(sentinel, element);\n\n observer.observe(sentinel);\n\n return () => {\n observer.disconnect();\n sentinel.remove();\n };\n }, [sticky, isSSR]);\n\n // Set up visibility observation\n useEffect(() => {\n if (isSSR || !containerRef.current) {\n return;\n }\n\n const tracker = getViewportTracker();\n const unobserve = tracker.observeVisibility(containerRef.current, handleVisibilityChange, {\n thresholds: Array.isArray(intersectionThreshold)\n ? intersectionThreshold\n : [intersectionThreshold],\n rootMargin,\n trackPosition: trackContinuously,\n });\n\n unobserveRef.current = unobserve;\n\n return () => {\n unobserve();\n unobserveRef.current = null;\n };\n }, [isSSR, handleVisibilityChange, intersectionThreshold, rootMargin, trackContinuously]);\n\n // Set up sticky behavior\n useEffect(() => {\n return handleStickyBehavior();\n }, [handleStickyBehavior]);\n\n /**\n * Computes container styles.\n */\n const containerStyle = useMemo((): React.CSSProperties => {\n const baseStyle: React.CSSProperties = { ...style };\n\n if (sticky?.enabled === true) {\n baseStyle.position = 'sticky';\n baseStyle[sticky.edge ?? 'top'] = sticky.offset ?? 0;\n\n if (state.isSticky && sticky.zIndex !== undefined) {\n baseStyle.zIndex = sticky.zIndex;\n }\n }\n\n return baseStyle;\n }, [style, sticky, state.isSticky]);\n\n /**\n * Computes data attributes.\n */\n const dataAttributes = useMemo((): Record => {\n const attrs: Record = {\n 'data-viewport-anchor': 'true',\n 'data-anchor-point': anchor,\n 'data-visibility': state.visibility,\n };\n\n if (sticky?.enabled === true) {\n attrs['data-sticky'] = String(state.isSticky);\n }\n\n if (state.hasEnteredViewport) {\n attrs['data-has-entered-viewport'] = 'true';\n }\n\n return attrs;\n }, [anchor, state.visibility, state.isSticky, state.hasEnteredViewport, sticky]);\n\n return (\n \n {children}\n \n );\n }\n);\n\n// ============================================================================\n// Specialized Viewport Components\n// ============================================================================\n\n/**\n * Props for LazyLoad component.\n */\nexport interface LazyLoadProps {\n /** Content to load when visible */\n children: React.ReactNode;\n /** Placeholder while not visible */\n placeholder?: React.ReactNode;\n /** Root margin for early loading */\n rootMargin?: string;\n /** Whether content has been loaded */\n onLoad?: () => void;\n /** Minimum height to prevent layout shift */\n minHeight?: number | string;\n /** Optional className */\n className?: string;\n /** Optional style */\n style?: React.CSSProperties;\n}\n\n/**\n * Lazy loading component using viewport detection.\n *\n * @example\n * ```tsx\n * }\n * rootMargin=\"200px\"\n * onLoad={() => console.log('Loaded!')}\n * >\n * \n * \n * ```\n */\nexport function LazyLoad({\n children,\n placeholder = null,\n rootMargin = '100px',\n onLoad,\n minHeight,\n className,\n style,\n}: LazyLoadProps): React.JSX.Element {\n const [isLoaded, setIsLoaded] = useState(false);\n\n const handleEnterViewport = useCallback(() => {\n setIsLoaded(true);\n onLoad?.();\n }, [onLoad]);\n\n let minHeightValue: string | number | undefined;\n if (minHeight !== undefined) {\n minHeightValue = typeof minHeight === 'number' ? `${minHeight}px` : minHeight;\n }\n\n const containerStyle: React.CSSProperties = {\n ...style,\n minHeight: minHeightValue,\n };\n\n return (\n \n {isLoaded ? children : placeholder}\n \n );\n}\n\n/**\n * Props for StickyHeader component.\n */\nexport interface StickyHeaderProps {\n children: React.ReactNode;\n /** Offset from top when sticky */\n offset?: number;\n /** Z-index when sticky */\n zIndex?: number;\n /** Callback when sticky state changes */\n onStickyChange?: (isSticky: boolean) => void;\n /** Optional className */\n className?: string;\n /** Optional style */\n style?: React.CSSProperties;\n}\n\n/**\n * Sticky header component with state tracking.\n *\n * @example\n * ```tsx\n * console.log('Sticky:', sticky)}\n * >\n *
\n * \n * ```\n */\nexport function StickyHeader({\n children,\n offset = 0,\n zIndex = 100,\n onStickyChange,\n className,\n style,\n}: StickyHeaderProps): React.JSX.Element {\n const handleVisibilityChange = useCallback(\n (visibility: VisibilityState) => {\n // Sticky when partially visible (top is outside viewport)\n const isSticky = visibility === 'partial';\n onStickyChange?.(isSticky);\n },\n [onStickyChange]\n );\n\n return (\n \n {children}\n \n );\n}\n\n/**\n * Props for ScrollTrigger component.\n */\nexport interface ScrollTriggerProps {\n /** Callback when triggered */\n onTrigger: () => void;\n /** Threshold for triggering (0-1) */\n threshold?: number;\n /** Root margin */\n rootMargin?: string;\n /** Whether to trigger only once */\n triggerOnce?: boolean;\n /** Visual indicator (optional) */\n indicator?: React.ReactNode;\n /** Optional className */\n className?: string;\n}\n\n/**\n * Scroll trigger component for infinite scroll or animations.\n *\n * @example\n * ```tsx\n * // Infinite scroll\n * \n *\n * // Animation trigger\n * setAnimate(true)}\n * threshold={0.5}\n * triggerOnce\n * />\n * ```\n */\nexport function ScrollTrigger({\n onTrigger,\n threshold = 0,\n rootMargin = '0px',\n triggerOnce = false,\n indicator,\n className,\n}: ScrollTriggerProps): React.JSX.Element {\n return (\n \n {indicator}\n \n );\n}\n"],"names":["ViewportAnchor","forwardRef","children","className","style","anchor","sticky","onVisibilityChange","onPositionChange","intersectionThreshold","rootMargin","trackContinuously","onEnterViewport","onExitViewport","triggerOnce","testId","forwardedRef","containerRef","useRef","unobserveRef","hasTriggeredRef","setRefs","useCallback","node","state","setState","useState","prevVisibilityRef","isSSR","handleVisibilityChange","_element","position","prevVisibility","newVisibility","prev","handleStickyBehavior","element","observer","entries","entry","isSticky","sentinel","useEffect","unobserve","getViewportTracker","containerStyle","useMemo","baseStyle","dataAttributes","attrs","jsx","LazyLoad","placeholder","onLoad","minHeight","isLoaded","setIsLoaded","handleEnterViewport","minHeightValue","StickyHeader","offset","zIndex","onStickyChange","visibility","ScrollTrigger","onTrigger","threshold","indicator"],"mappings":"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"}