@uniweb/kit 0.12.3 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.12.3",
+  "version": "0.13.1",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -44,8 +44,8 @@
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
     "temml": "^0.13.2",
-    "@uniweb/core": "^0.10.1",
     "@uniweb/semantic-parser": "^1.2.3",
+    "@uniweb/core": "^0.11.0",
     "@uniweb/scene": "^0.1.3"
   },
   "peerDependencies": {

package/src/hooks/index.js

@@ -41,7 +41,16 @@ export { useFormValues, valueAt } from './useFormValues.js'
 
 // Site tracking — one event stream.
 // `block.track(name, data)` is the common case and needs no hook; these cover
-// events with no block in hand, the consent gate, and opt-in scroll reporting.
+// events with no block in hand, and the consent gate a banner sets.
+//
+// ⛔ `useScrollDepth` was here until 2026-08-19 and is RETIRED, not moved. It
+// measured the DOCUMENT, so two long sections on one page reported the same
+// number and any section added above silently rebased the series — and it had
+// zero callers, so it never emitted anywhere. On pages composed of sections,
+// `section_view` is the same signal with names attached. The case it looked
+// like it served is `useReadingDepth` below, which measures one element.
 export { useTracker } from './useTracker.js'
 export { useTrackingConsent } from './useTrackingConsent.js'
-export { useScrollDepth } from './useScrollDepth.js'
+// Reading depth through ONE long section — the foundation is the only party
+// that knows a section is long-form, which is why it is opt-in and lives here.
+export { useReadingDepth } from './useReadingDepth.js'

package/src/hooks/useReadingDepth.js

@@ -0,0 +1,115 @@
+/**
+ * useReadingDepth — how far through ONE long section a visitor actually read.
+ *
+ * ```jsx
+ * export default function Article({ content, block }) {
+ *   const ref = useRef(null)
+ *   useReadingDepth({ ref, block })
+ *   return <article ref={ref}>{…}</article>
+ * }
+ * ```
+ *
+ * ⭐ **Why this is kit's and not the runtime's.** The runtime emits what the
+ * SITE OWNER buys — it cannot know that one section is five thousand words of
+ * prose and another is a row of logos. **Only the foundation knows a section is
+ * long-form reading**, which is exactly the criterion for living here: declared
+ * by the component that has the knowledge, and tree-shaken to nothing for every
+ * foundation that never asks.
+ *
+ * ⛔ **This is NOT page scroll depth, and the difference is the whole point.**
+ * A page-scoped version measures the document, so on a page holding two long
+ * articles both would report the same number, and adding any section above
+ * silently rebases the series. This measures **the element's own box**, so it
+ * keeps meaning the same thing when the page around it changes.
+ *
+ * ⚖️ **It complements `section_view` rather than duplicating it.** That event
+ * fires once, when the section becomes half visible — it says the reader
+ * *arrived*. This says how far they got, which for a long article is the only
+ * question worth asking.
+ *
+ * ⛔ **No guard is needed at the call site.** With no tracking destination the
+ * report is a silent no-op — and the listener is never attached either, so an
+ * unconfigured site pays nothing for the call.
+ *
+ * @module @uniweb/kit/hooks/useReadingDepth
+ */
+
+import { useEffect } from 'react'
+import { getUniweb } from '@uniweb/core'
+
+const MILESTONES = [25, 50, 75, 100]
+const THROTTLE_MS = 200
+
+/**
+ * How far the viewport has advanced through this element, 0-100.
+ *
+ * Measured against the element's own box: 0 when its top first reaches the
+ * bottom of the viewport, 100 once its bottom has. An element shorter than the
+ * viewport reports 100 as soon as it is fully on screen, which is correct —
+ * there was nothing further to read.
+ */
+function depthOf(el) {
+  const rect = el.getBoundingClientRect()
+  if (rect.height <= 0) return 0
+  const seen = window.innerHeight - rect.top
+  return Math.max(0, Math.min(100, Math.round((seen / rect.height) * 100)))
+}
+
+/**
+ * @param {Object} options
+ * @param {{current: HTMLElement|null}} options.ref - the element to measure
+ * @param {Object} [options.block] - report through the block, so the section
+ *        type, its instance id and the page path ride along for free
+ * @param {string} [options.event='read_depth']
+ */
+export function useReadingDepth({ ref, block, event = 'read_depth' } = {}) {
+  useEffect(() => {
+    const el = ref?.current
+    const tracking = getUniweb()?.tracking
+    // ⛔ `isEnabled()`, NOT `arms()`. A foundation's own events are never gated
+    // by the site's `tracking.emit` or a host's list — the registry is open, and
+    // a client-side allowlist over them would export one collector's policy to
+    // every host. `emit` decides what the RUNTIME arms; this is not that.
+    if (!el || !tracking?.isEnabled?.()) return
+
+    const reported = new Set()
+    let lastCheck = 0
+
+    const report = (depth) => {
+      // Prefer the block: it attaches `section`, `section_id` and `path`, so an
+      // article's depth is attributable to the section it was read in.
+      if (block?.track) block.track(event, { depth })
+      else tracking.track(event, { depth })
+    }
+
+    const onScroll = () => {
+      const now = Date.now()
+      if (now - lastCheck < THROTTLE_MS) return
+      lastCheck = now
+
+      const depth = depthOf(el)
+      for (const milestone of MILESTONES) {
+        if (depth >= milestone && !reported.has(milestone)) {
+          reported.add(milestone)
+          report(milestone)
+        }
+      }
+    }
+
+    onScroll() // an element already fully read at mount reports immediately
+    window.addEventListener('scroll', onScroll, { passive: true })
+    // Resize changes the element's height and the viewport at once, so a
+    // milestone can be crossed without any scrolling at all.
+    window.addEventListener('resize', onScroll, { passive: true })
+
+    return () => {
+      window.removeEventListener('scroll', onScroll)
+      window.removeEventListener('resize', onScroll)
+    }
+    // The reported set is a local of this effect, so a re-run IS the reset —
+    // no ref to remember to clear, which is how the retired page-level hook
+    // shipped a bug where every page after the first reported nothing.
+  }, [ref, block, event])
+}
+
+export default useReadingDepth

package/src/index.js

@@ -95,11 +95,11 @@ export {
   useFormValues,
   valueAt,
   // Site tracking. `block.track(name, data)` is the common case and needs no
-  // hook — these are for events with no block in hand, the consent gate a
-  // banner sets, and opt-in scroll reporting.
+  // hook — these are for events with no block in hand and the consent gate a
+  // banner sets. Scroll depth is the runtime's now; see hooks/index.js.
   useTracker,
   useTrackingConsent,
-  useScrollDepth
+  useReadingDepth
 } from './hooks/index.js'
 
 // ============================================================================

package/src/hooks/useScrollDepth.js

@@ -1,97 +0,0 @@
-/**
- * useScrollDepth — report how far down the page a visitor got.
- *
- * ```jsx
- * useScrollDepth()                       // 25 / 50 / 75 / 100, once each per page
- * ```
- *
- * ⭐ **Opt-in, and in kit rather than the runtime, on purpose.** The runtime
- * auto-emits only what requires runtime privilege — a page view needs the
- * router, so nothing else can emit it. Scroll depth needs nothing but the
- * window, so it is a foundation's choice and lives where tree-shaking can drop
- * it for the foundations that never call it.
- *
- * *(It previously lived in `@uniweb/runtime` as an unexported, unreachable file
- * that reported to a metric baked into the transport. The milestones are now an
- * ordinary event, which is both smaller and more general.)*
- *
- * ⛔ **No guard is needed.** With no tracking destination the report is a
- * silent no-op — but the scroll listener is skipped too, so an unconfigured
- * site pays nothing for the call.
- *
- * @module @uniweb/kit/hooks/useScrollDepth
- */
-
-import { useEffect, useRef } from 'react'
-import { getUniweb } from '@uniweb/core'
-import { useRouting } from './useRouting.js'
-
-const MILESTONES = [25, 50, 75, 100]
-
-/** @returns {number} 0-100; 100 when the page fits in the viewport */
-function getScrollDepth() {
-  const scrollTop = window.scrollY
-  const docHeight = document.documentElement.scrollHeight - window.innerHeight
-  if (docHeight <= 0) return 100
-  return Math.min(100, Math.round((scrollTop / docHeight) * 100))
-}
-
-/**
- * @param {Object} [options]
- * @param {boolean} [options.enabled=true]
- * @param {number} [options.throttleMs=200]
- * @param {string} [options.event='scroll_depth'] - override the event name
- */
-export function useScrollDepth(options = {}) {
-  const { enabled = true, throttleMs = 200, event = 'scroll_depth' } = options
-
-  const lastCheck = useRef(0)
-  const reported = useRef(new Set())
-
-  // ⛔ **Keyed on the path, or "once each per page" is not true.** The milestone
-  // set lives in a ref, so without this the effect runs once at mount and the
-  // set is never cleared again — a second page reports nothing at all. That bites
-  // exactly where this hook is most naturally called: once, in a layout
-  // component, which persists across SPA navigation (`PageRenderer` does not
-  // remount — the router declares a single catch-all route). Calling it in every
-  // section would have hidden the bug and multiplied the events instead.
-  //
-  // ⭐ `pathname` rather than a route object, deliberately: it is the same
-  // boundary `usePageView` emits on, so a `scroll_depth` always pairs with the
-  // `page_view` it belongs to. `useRouting` returns a default location when there
-  // is no Router, so this stays SSG-safe.
-  const { useLocation } = useRouting()
-  const { pathname } = useLocation()
-
-  useEffect(() => {
-    const tracking = getUniweb()?.tracking
-    // Skip the listener entirely when there is nowhere to report — the calls
-    // would be no-ops, but the scroll handler would still run on every frame.
-    if (!enabled || !tracking?.isEnabled?.()) return
-
-    reported.current.clear()
-    // Reset the throttle too: a navigation within the throttle window would
-    // otherwise make the immediate check below return early and miss the fold.
-    lastCheck.current = 0
-
-    const handleScroll = () => {
-      const now = Date.now()
-      if (now - lastCheck.current < throttleMs) return
-      lastCheck.current = now
-
-      const depth = getScrollDepth()
-      for (const milestone of MILESTONES) {
-        if (depth >= milestone && !reported.current.has(milestone)) {
-          reported.current.add(milestone)
-          tracking.track(event, { depth: milestone })
-        }
-      }
-    }
-
-    handleScroll() // a page that fits the viewport is already at 100
-    window.addEventListener('scroll', handleScroll, { passive: true })
-    return () => window.removeEventListener('scroll', handleScroll)
-  }, [enabled, throttleMs, event, pathname])
-}
-
-export default useScrollDepth