@uniweb/kit 0.9.40 → 0.9.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.40",
+  "version": "0.9.42",
   "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.32",
     "@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/hooks/useShortcut.js

@@ -191,10 +191,22 @@ export function matchesShortcut(event, descriptor) {
  * `userAgentData.platform` is the modern signal; `navigator.platform` is
  * deprecated but still the most widely accurate fallback.
  *
- * @returns {boolean} false when there is no navigator (SSR).
+ * **A `navigator` check alone is not enough, and the failure is nasty.**
+ * Node 21+ defines `globalThis.navigator`, and on macOS its `platform` reads
+ * `'MacIntel'` — so during prerender this returned true and baked ⌘ into
+ * static HTML based on the machine that ran the BUILD. Every visitor then got
+ * the build box's platform, and the same source produced different output on a
+ * Mac laptop and a Linux CI runner.
+ *
+ * `document` is the discriminator: Node defines a navigator but never a DOM.
+ * Prerender therefore emits the non-Apple spelling, and the client corrects it
+ * on mount — which is safe here because the runtime always createRoots and
+ * never hydrates, so there is no mismatch to reconcile.
+ *
+ * @returns {boolean} false anywhere that is not a real browser.
  */
 export function isApplePlatform() {
-  if (typeof navigator === 'undefined') return false
+  if (typeof document === 'undefined' || typeof navigator === 'undefined') return false
   const modern = navigator.userAgentData?.platform
   if (typeof modern === 'string' && modern) return /mac|ios|iphone|ipad/i.test(modern)
   return /mac|iphone|ipad|ipod/i.test(navigator.platform || navigator.userAgent || '')

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'