@uniweb/kit 0.9.41 → 0.9.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.41",
+  "version": "0.9.43",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -40,7 +40,7 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/core": "0.7.31",
+    "@uniweb/core": "0.7.33",
     "@uniweb/scene": "0.1.2"
   },
   "peerDependencies": {

package/src/components/Overlay/Overlay.jsx

@@ -0,0 +1,118 @@
+/**
+ * Overlay — render above the page, from anywhere in the tree.
+ *
+ * ## Why this exists (it is not "a portal wrapper")
+ *
+ * The runtime gives every layout area its own `view-transition-name` so the
+ * browser can animate header, sidebars and body independently instead of
+ * crossfading the whole page. That is on by default.
+ *
+ * A `view-transition-name` makes the element **a stacking context** and **a
+ * containing block for fixed-position descendants**. Both consequences bite
+ * the most ordinary thing a foundation builds: a modal opened from the header.
+ *
+ *   div[view-transition-name: uw-header]     ← area wrapper, z-index: auto
+ *     └ div.fixed.inset-0.z-[100]            ← your modal
+ *   div[view-transition-name: uw-body]       ← sibling area, z-index: auto
+ *
+ * The modal's `z-index: 100` is scoped *inside* `uw-header`. Both wrappers sit
+ * at `auto` in the root stacking context, so they paint in DOM order — and the
+ * body comes second. No z-index a foundation can write will lift the modal
+ * above the page content, because the two are not competing in the same
+ * stacking context. Raising the number looks like it should work and never
+ * does, which is what makes this worth a component rather than a doc note.
+ *
+ * Rendering into `document.body` leaves every area wrapper behind, so the
+ * overlay competes in the root stacking context where its z-index means what
+ * the author expects.
+ *
+ * ## Usage
+ *
+ *   {isOpen && (
+ *     <Overlay onClose={close}>
+ *       <div role="dialog" aria-modal="true">…</div>
+ *     </Overlay>
+ *   )}
+ *
+ * Owns only what every overlay needs and nothing about how it looks: the
+ * portal, the scrim, Escape, a click outside, and the page-scroll lock. The
+ * dialog itself — its shape, its focus handling, its content — is the
+ * foundation's design, the same way kit ships no layout.
+ */
+
+import { useEffect } from 'react'
+import { createPortal } from 'react-dom'
+import { cn } from '../../utils/index.js'
+
+/**
+ * @param {object} props
+ * @param {React.ReactNode} props.children - The overlay content (your dialog).
+ * @param {Function} [props.onClose] - Called on Escape and on a scrim click.
+ *   Omit for a non-dismissible overlay.
+ * @param {boolean} [props.lockScroll=true] - Prevent the page behind from
+ *   scrolling while open.
+ * @param {boolean} [props.closeOnEscape=true]
+ * @param {boolean} [props.closeOnScrimClick=true]
+ * @param {string} [props.className] - Classes for the scrim/positioning layer.
+ *   Defaults place the content centred near the top, the usual command-palette
+ *   position; pass your own to change it.
+ * @param {number|string} [props.zIndex=100]
+ */
+export function Overlay({
+  children,
+  onClose,
+  lockScroll = true,
+  closeOnEscape = true,
+  closeOnScrimClick = true,
+  className,
+  zIndex = 100,
+  ...rest
+}) {
+  useEffect(() => {
+    if (!closeOnEscape || !onClose) return
+    const onKeyDown = (event) => {
+      if (event.key === 'Escape') {
+        event.preventDefault()
+        onClose(event)
+      }
+    }
+    // Capture phase: a dialog's own input may stop propagation on keydown,
+    // and Escape still has to close the thing it is typed into.
+    document.addEventListener('keydown', onKeyDown, true)
+    return () => document.removeEventListener('keydown', onKeyDown, true)
+  }, [closeOnEscape, onClose])
+
+  useEffect(() => {
+    if (!lockScroll) return
+    // Restore the previous value rather than clearing: two stacked overlays
+    // would otherwise have the inner one unlock the page on close.
+    const previous = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    return () => {
+      document.body.style.overflow = previous
+    }
+  }, [lockScroll])
+
+  // No DOM: prerender and any Node render. An overlay is by definition
+  // interactive, so there is nothing meaningful to emit into static HTML —
+  // and emitting it would put a scrim over the prerendered page.
+  if (typeof document === 'undefined') return null
+
+  return createPortal(
+    <div
+      className={cn('fixed inset-0 flex items-start justify-center', className)}
+      style={{ zIndex }}
+      onClick={closeOnScrimClick && onClose ? (e) => {
+        // Only a click on the scrim itself, never one that bubbled out of the
+        // dialog — otherwise selecting text and releasing outside closes it.
+        if (e.target === e.currentTarget) onClose(e)
+      } : undefined}
+      {...rest}
+    >
+      {children}
+    </div>,
+    document.body
+  )
+}
+
+export default Overlay

package/src/components/Overlay/index.js

@@ -0,0 +1 @@
+export { Overlay, default } from './Overlay.jsx'

package/src/index.js

@@ -15,6 +15,9 @@
 // Navigation
 export { Link } from './components/Link/index.js'
 export { Image } from './components/Image/index.js'
+// Renders above the page from anywhere in the tree — see Overlay.jsx for why
+// a plain fixed+z-index element cannot escape a layout area.
+export { Overlay } from './components/Overlay/index.js'
 export { SafeHtml } from './components/SafeHtml/index.js'
 export { Icon } from './components/Icon/index.js'
 

package/src/search/providers/index-provider.js

@@ -22,8 +22,12 @@ import { emptyResult } from './result.js'
 const indexCache = new Map()
 const fuseCache = new Map()
 
-const STORAGE_VERSION = 'v1'
-const STORAGE_PREFIX = `uniweb:search:${STORAGE_VERSION}:`
+// Bumped to v2 when stored entries gained a validator. The version is part of
+// the key, so every v1 entry — which had no way to be revalidated and could
+// outlive any number of rebuilds — is orphaned rather than trusted.
+const STORAGE_VERSION = 'v2'
+const STORAGE_PREFIX = 'uniweb:search:'
+const STORAGE_KEY = (cacheKey) => `${STORAGE_PREFIX}${STORAGE_VERSION}:${cacheKey}`
 
 /**
  * Default Fuse.js options optimized for site search
@@ -63,14 +67,12 @@ function loadFromStorage(cacheKey) {
   const storage = getStorage()
   if (!storage) return null
 
-  const raw = storage.getItem(`${STORAGE_PREFIX}${cacheKey}`)
+  const raw = storage.getItem(STORAGE_KEY(cacheKey))
   if (!raw) return null
 
   try {
     const parsed = JSON.parse(raw)
-    if (Array.isArray(parsed.entries)) {
-      return parsed
-    }
+    if (Array.isArray(parsed.payload?.entries)) return parsed
     return null
   } catch {
     return null
@@ -78,21 +80,52 @@ function loadFromStorage(cacheKey) {
 }
 
 /**
- * Save index to localStorage
+ * Save index to localStorage, together with the validator that lets a later
+ * load ask the server whether it is still current.
+ *
  * @param {string} cacheKey - Cache key
  * @param {Object} payload - Index data
+ * @param {{etag?: string|null, lastModified?: string|null}} [validator]
  */
-function saveToStorage(cacheKey, payload) {
+function saveToStorage(cacheKey, payload, validator = {}) {
   const storage = getStorage()
   if (!storage) return
 
   try {
-    storage.setItem(`${STORAGE_PREFIX}${cacheKey}`, JSON.stringify(payload))
+    storage.setItem(
+      STORAGE_KEY(cacheKey),
+      JSON.stringify({
+        payload,
+        etag: validator.etag || null,
+        lastModified: validator.lastModified || null,
+      })
+    )
   } catch {
     // Ignore quota errors
   }
 }
 
+/**
+ * Drop entries written by an older storage schema.
+ *
+ * A search index runs to hundreds of kilobytes, so an orphaned one is a real
+ * bite out of a origin's storage quota rather than a tidiness issue.
+ */
+function pruneOldVersions() {
+  const storage = getStorage()
+  if (!storage) return
+
+  const current = `${STORAGE_PREFIX}${STORAGE_VERSION}:`
+  const stale = []
+  for (let i = 0; i < storage.length; i++) {
+    const key = storage.key(i)
+    if (key?.startsWith(STORAGE_PREFIX) && !key.startsWith(current)) stale.push(key)
+  }
+  stale.forEach((key) => {
+    try { storage.removeItem(key) } catch { /* ignore */ }
+  })
+}
+
 /**
  * Load search index for a locale
  * @param {string} indexUrl - URL to fetch the index from
@@ -104,32 +137,72 @@ function saveToStorage(cacheKey, payload) {
 export async function loadSearchIndex(indexUrl, options = {}) {
   const { cacheKey = indexUrl, useStorage = true } = options
 
-  // Check memory cache first
+  // Memory cache: scoped to one page load, where the index cannot change
+  // underneath us. This is the only cache read that needs no validation.
   if (indexCache.has(cacheKey)) {
     return indexCache.get(cacheKey)
   }
 
-  // Check localStorage cache
-  if (useStorage) {
-    const cached = loadFromStorage(cacheKey)
+  if (useStorage) pruneOldVersions()
+  const cached = useStorage ? loadFromStorage(cacheKey) : null
+
+  // ALWAYS ask the server, even holding a stored copy.
+  //
+  // Returning the stored index unconditionally — what this did before — has no
+  // expiry and no way to notice a rebuild, so a visitor who searched once kept
+  // answering from that index for as long as the entry survived. A redeploy
+  // did not dislodge it.
+  //
+  // It also collided across sites. The key is the index URL, which is
+  // `/search-index.json` for every Uniweb project, and localStorage is scoped
+  // to an origin — so two projects sharing a dev port shared one entry, and a
+  // search on one could return the other's pages. Revalidating settles that
+  // too: a different server answers 200 with its own index and replaces it.
+  const headers = {}
+  if (cached?.etag) headers['If-None-Match'] = cached.etag
+  else if (cached?.lastModified) headers['If-Modified-Since'] = cached.lastModified
+
+  let response
+  try {
+    // `no-cache` = revalidate, not "don't cache". `force-cache` (the previous
+    // value) told the browser to prefer any stored response regardless of age,
+    // which defeated revalidation a second time over.
+    response = await fetch(indexUrl, { headers, cache: 'no-cache' })
+  } catch (error) {
+    // Offline or unreachable. A stored index is better than no search at all,
+    // and this is the one path where serving it unvalidated is the right call.
     if (cached) {
-      indexCache.set(cacheKey, cached)
-      return cached
+      indexCache.set(cacheKey, cached.payload)
+      return cached.payload
     }
+    throw error
+  }
+
+  // Unchanged since we stored it — the whole point of keeping the validator.
+  if (response.status === 304 && cached) {
+    indexCache.set(cacheKey, cached.payload)
+    return cached.payload
   }
 
-  // Fetch from server
-  const response = await fetch(indexUrl, { cache: 'force-cache' })
   if (!response.ok) {
+    if (cached) {
+      indexCache.set(cacheKey, cached.payload)
+      return cached.payload
+    }
     throw new Error(`Failed to load search index: ${response.status}`)
   }
 
   const payload = await response.json()
 
-  // Cache the result
   indexCache.set(cacheKey, payload)
   if (useStorage) {
-    saveToStorage(cacheKey, payload)
+    // A host that sends no validator still gets stored — it just costs a full
+    // fetch next time instead of a 304. What it never does is get served as
+    // though it were known to be current.
+    saveToStorage(cacheKey, payload, {
+      etag: response.headers?.get?.('etag'),
+      lastModified: response.headers?.get?.('last-modified'),
+    })
   }
 
   return payload
@@ -145,7 +218,7 @@ export function clearSearchCache(cacheKey) {
     fuseCache.delete(cacheKey)
     const storage = getStorage()
     if (storage) {
-      storage.removeItem(`${STORAGE_PREFIX}${cacheKey}`)
+      storage.removeItem(STORAGE_KEY(cacheKey))
     }
   } else {
     indexCache.clear()