@uniweb/runtime 1.1.20 → 1.2.0

package/src/sticky-check.js

@@ -4,13 +4,23 @@
  *
  * `position: sticky` keeps an element inside its parent's box. When the parent is no taller than
  * the element (no wider, for one that sticks sideways), the element has no room and scrolls away
- * with the page, and nothing says so. The two ways it happens:
+ * with the page, and nothing says so. Whose box the parent is says what to do (`unmovableAdvice`):
  *
- *   - a component's own `sticky top-0`: a section's markup sits in boxes as tall as itself, so it
- *     never moves. The section's `sticky: true` asks the runtime to make sticky the box that can
- *     (`sticky.js`).
- *   - a layout that wraps a sticky area in an element of its own, which confines the area's box.
- *     The layout makes its element sticky when `page.isSticky(area)`.
+ *   - a component's outermost element — a header's own `sticky top-0` — sits in the section's
+ *     wrapper, as tall as itself, so it never moves. The section's `sticky: true` asks the runtime
+ *     to make sticky the box that can (`sticky.js`).
+ *   - a box the runtime made sticky (`data-uw-sticky`) in an element a layout wraps it in, which
+ *     confines it. The layout makes its element sticky when `page.isSticky(area)`.
+ *   - an element inside a component sits in a box the component draws. A side panel beside a list
+ *     sticks within the row the two share, and cannot when its box is only as tall as the panel:
+ *     the fix is the component's, to give that box room or make it the sticky one.
+ *
+ * ⭐ MEASURED ON THE SETTLED PAGE. A box's height can wait on the page's data — a list fills its
+ * column once its records arrive — so the check runs once nothing is in flight (the layout passes
+ * `website.dataStore.whenIdle` as `settled`), after the page's fonts, in the frames after that:
+ * React has committed what arrived, and the browser has laid it out. ⛔ Until 2026-10-25 it
+ * measured in the first frame after the page mounted, while the page's fetches were still out,
+ * and named a side panel whose column was waiting for its records as one that could never move.
  *
  * Table parts are left out: a sticky table header cell sticks within its table, though its row is
  * no taller than it is. So is a child section the runtime made sticky (`data-uw-sticky="child"`):
@@ -25,6 +35,22 @@
 
 const warned = new WeakSet()
 
+/** Every section wrapper the browser's renderer drew, noted in dev (`BlockRenderer.jsx`). */
+const sectionWrappers = new WeakSet()
+
+/** How long the check waits on the page's fetches before it measures anyway. */
+const SETTLE_CAP_MS = 10_000
+
+/**
+ * Note a section's wrapper, so the check can tell a component's outermost element — the one in
+ * it — from an element inside a component. A ref callback's argument: null on unmount.
+ *
+ * @param {Element|null} element
+ */
+export function noteSectionWrapper(element) {
+  if (element) sectionWrappers.add(element)
+}
+
 /** The nearest ancestor that draws a box — `display: contents` draws none. */
 function boxParent(el) {
   let parent = el.parentElement
@@ -73,38 +99,85 @@ export function clippingAncestor(el) {
 }
 
 /**
- * Warn, once per element, about each sticky element on the page that cannot move.
+ * What to do about a sticky element that cannot move, by whose box holds it (see above).
  *
- * @param {Document} [doc]
- * @returns {() => void} cancels a check not yet run
+ * @param {Element} el
+ * @returns {string}
  */
-export function warnUnmovableSticky(doc = globalThis.document) {
-  if (!doc?.body || typeof requestAnimationFrame !== 'function') return () => {}
-  const frame = requestAnimationFrame(() => {
-    for (const el of doc.body.querySelectorAll('*')) {
-      if (warned.has(el) || getComputedStyle(el).position !== 'sticky') continue
-      const clip = clippingAncestor(el)
-      if (clip) {
-        warned.add(el)
-        console.warn(
-          '[uniweb] This element is sticky but sits in a box that clips its overflow (`overflow: hidden`, ' +
-            'or `overflow-x: hidden`), so it sticks to that box, which does not scroll, and never moves. ' +
-            'Clip with `overflow: clip` instead: it clips the same and keeps the element sticking.',
-          el,
-          clip,
-        )
-        continue
-      }
-      if (el.getAttribute('data-uw-sticky') === 'child' || canStick(el)) continue
+export function unmovableAdvice(el) {
+  if (el.getAttribute('data-uw-sticky')) {
+    return (
+      'It is the box the runtime makes sticky for a section, and an element of the layout around it ' +
+      'confines it: a layout that wraps an area in an element of its own makes that element sticky ' +
+      'when `page.isSticky(area)`.'
+    )
+  }
+  if (sectionWrappers.has(boxParent(el))) {
+    return (
+      "It is a section's outermost element, and the section's wrapper is as tall as it is. To keep the " +
+      'section in view, give it `sticky: true` (its type may default it in meta.js), and the runtime ' +
+      'makes sticky the box that can.'
+    )
+  }
+  return (
+    'It sits in a box the component draws. Give that box room — let it stretch with its row rather ' +
+    'than fit its content (`items-start` or `self-start` shrinks it) — or make that box the sticky one.'
+  )
+}
+
+/** Warn, once per element, about each sticky element on the page that cannot move. */
+function checkPage(doc) {
+  for (const el of doc.body.querySelectorAll('*')) {
+    if (warned.has(el) || getComputedStyle(el).position !== 'sticky') continue
+    const clip = clippingAncestor(el)
+    if (clip) {
       warned.add(el)
       console.warn(
-        '[uniweb] This element is sticky but cannot move: its parent is no taller than it is, so it ' +
-          'scrolls away with the page. To keep a section in view, give the section `sticky: true` ' +
-          '(its type may default it in meta.js) — no box a component draws can stick. A layout that ' +
-          'wraps an area in an element of its own makes that element sticky when `page.isSticky(area)`.',
+        '[uniweb] This element is sticky but sits in a box that clips its overflow (`overflow: hidden`, ' +
+          'or `overflow-x: hidden`), so it sticks to that box, which does not scroll, and never moves. ' +
+          'Clip with `overflow: clip` instead: it clips the same and keeps the element sticking.',
         el,
+        clip,
       )
+      continue
     }
-  })
-  return () => cancelAnimationFrame(frame)
+    if (el.getAttribute('data-uw-sticky') === 'child' || canStick(el)) continue
+    warned.add(el)
+    console.warn(
+      '[uniweb] This element is sticky but cannot move: its parent is no taller than it is, so it ' +
+        `scrolls away with the page. ${unmovableAdvice(el)}`,
+      el,
+    )
+  }
+}
+
+/**
+ * Check the page once it has settled: when `settled()` resolves (or after `SETTLE_CAP_MS`, so a
+ * fetch that never answers does not silence the check), its fonts have loaded, and two frames have
+ * passed — the first for React to commit what arrived, the second to lay it out.
+ *
+ * @param {Document} [doc]
+ * @param {{ settled?: () => Promise<unknown> }} [options] - what the page waits on: its data
+ * @returns {() => void} cancels a check not yet run
+ */
+export function warnUnmovableSticky(doc = globalThis.document, { settled } = {}) {
+  if (!doc?.body || typeof requestAnimationFrame !== 'function') return () => {}
+  let cancelled = false
+  let frame = 0
+  let cap = 0
+  const nextFrame = () => new Promise((resolve) => { frame = requestAnimationFrame(resolve) })
+  const capped = new Promise((resolve) => { cap = setTimeout(resolve, SETTLE_CAP_MS) })
+  ;(async () => {
+    await Promise.race([Promise.resolve(settled?.()).catch(() => {}), capped])
+    clearTimeout(cap)
+    await doc.fonts?.ready
+    if (!cancelled) await nextFrame()
+    if (!cancelled) await nextFrame()
+    if (!cancelled) checkPage(doc)
+  })()
+  return () => {
+    cancelled = true
+    clearTimeout(cap)
+    cancelAnimationFrame(frame)
+  }
 }

package/src/sticky.js

@@ -3,9 +3,11 @@
  * (`components/Layout.jsx`, `BlockRenderer.jsx`) and the prerender's (`ssr-renderer.js`) make the
  * same boxes sticky, and a prerendered page does not change when the browser renders over it.
  *
- * ⭐ NO BOX A COMPONENT DRAWS CAN STICK. `position: sticky` moves an element only within its
- * parent's box, and a component's markup sits in boxes as tall as itself: the section's wrapper,
- * the layout area's wrapper (`area-wrappers.js`), the built-in layout's zone (`default-layout.js`).
+ * ⭐ A COMPONENT'S OUTERMOST ELEMENT CANNOT STICK. `position: sticky` moves an element only within
+ * its parent's box, and a component sits in boxes as tall as itself: the section's wrapper, the
+ * layout area's wrapper (`area-wrappers.js`), the built-in layout's zone (`default-layout.js`). (An
+ * element inside a component can stick within a taller box the component draws — a side panel in
+ * the row beside a list — which is the component's own layout and asks nothing of this module.)
  * So a section asks — `sticky:`, one of a section's own settings (`@uniweb/schemas/section`),
  * defaulted by its type's `meta.js` — and the runtime makes sticky the box that can:
  *