@wippy-fe/theme 0.0.42 → 0.0.44

package/THEMING.md

@@ -676,6 +676,22 @@ The CSS files use theme variables via Tailwind classes. Example from `button.css
 
 The `tailwind.css` master file imports all component CSS files organized by category (form, button, data, overlay, menu, panel, file, message, media, misc).
 
+### Overlays render inside the shadow root
+
+PrimeVue overlays — `Dialog`, `Drawer`, `Select`, `Popover`, `Menu`, `MultiSelect`, … — teleport their panel through one shared primitive (`primevue/portal`) whose default target is `document.body`. Inside a **web component** that escapes the shadow root, so the panel loses the module's shadow-scoped CSS (and the injected `primeVueCssUrl`) and renders unstyled next to `<body>`.
+
+`PrimeVuePlugin` handles this for you: at `install()` it rewrites the shared Portal so the default `appendTo` (`'body'`) teleports each overlay to a per-shadow-root `position: fixed` zero-size anchor. The overlay stays **inside the shadow root** (so the shadow-scoped CSS and the injected `primeVueCssUrl` apply) and — because `appendTo` is not `'self'` — PrimeVue positions it with `absolutePosition` at the trigger, **unclipped** by any scrolling ancestor (e.g. a `Dialog` / `Drawer` body with `overflow: auto`). Outside a shadow root (the host SPA) it falls back to `document.body`. You do nothing per component.
+
+The anchor is **measured, not assumed**. `absolutePosition` writes *document* coordinates, so the anchor must sit at the true viewport origin for an absolutely-positioned overlay to land correctly. A `position: fixed` element is only at the viewport origin when no ancestor establishes a containing block — but `transform` / `filter` / `perspective` / `will-change` / `contain` on any ancestor (a `translateZ(0)` GPU hint, a slide/scale animation, a virtualized list) makes *that* ancestor the containing block instead, and a scrolled window shifts it too. So the plugin reads the anchor's own `getBoundingClientRect()` and offsets it by `-scrollX / -scrollY` to pin it at viewport `(0,0)`, re-syncing when an overlay opens (a `MutationObserver`) and on scroll/resize. This is what keeps overlays aligned under a transformed ancestor or a scrolled page. A reactive `append-to` is honored (`resolvedTarget` is a computed). **`Tooltip` is the one exception** — it is a directive that appends to `document.body`, bypassing `primevue/portal`, so it renders in the light DOM and is not shadow-scoped by this plugin.
+
+> **Do not set `append-to="self"`.** `'self'` makes PrimeVue render the overlay *inline* and position it relatively, so an overlay whose trigger sits inside a scrolling `Dialog` / `Drawer` body gets clipped — this was the regression in `@wippy-fe/theme` ≤ 0.0.43 (web-host ≤ 1.0.43). With this plugin, leave `appendTo` unset and inherit the shadow-root portal. (PrimeVue 4 has no global `appendTo` config and the `@primeuix/utils` positioning helpers are immutable, but the shared Portal is a singleton rewritten once at install — no per-app `patch-package` needed.)
+>
+> **Residuals** (all uncommon; none affects a static, translation-only layout):
+> - **Scale / rotate / skew ancestor:** the compensation cancels a containing block's *translation* only, so a `scale()`/`rotate()`/`skew()` ancestor mis-positions the overlay. `translate` / `translateZ(0)` (the common case) is handled.
+> - **Clipping:** an ancestor that both establishes the fixed containing block *and* clips (`transform`/`contain`/`will-change` + `overflow != visible`, or `contain: paint/strict/content`, or `overflow: clip`) can still clip an overlay extending beyond its box — intrinsic to staying in the shadow root.
+> - **Animating ancestor:** a transform animating while an overlay is open lags until the next scroll/resize.
+> - **`Toast`:** it self-positions `position: fixed`, so under a transformed ancestor it resolves against that ancestor, not the viewport. Wippy routes toasts to the host, so this isn't hit in practice.
+
 ### Available PrimeVue component styles
 
 **Form**: autocomplete, cascadeselect, checkbox, colorpicker, datepicker, iconfield, iftalabel, inputgroup, inputnumber, inputotp, inputtext, floatlabel, knob, listbox, multiselect, password, radiobutton, rating, select, selectbutton, slider, textarea, togglebutton, toggleswitch, treeselect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wippy-fe/theme",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "description": "Theme variables, shared Tailwind config, and PrimeVue styling for Wippy web components.",
   "type": "module",
   "main": "theme-config.css",

package/primevue/common.css

@@ -50,6 +50,34 @@
     @apply w-4 h-4
 }
 
+/*
+ * Screen-reader-only content. PrimeVue marks accessibility text with these classes
+ * and expects the theme's base CSS to hide them — e.g. Select's `aria-live` selection
+ * announcer ("No selected item"), and dialog focus-trap sentinels. In `theme: 'none'`
+ * mode we own the base CSS, so without this the announcer text renders VISIBLY (it
+ * showed up under an open Select once overlays moved into the shadow root). Matches
+ * PrimeVue's canonical `.p-hidden-accessible` definition.
+ */
+.p-hidden-accessible,
+.p-hidden-focusable {
+    border: 0;
+    clip: rect(0 0 0 0);
+    clip-path: inset(50%);
+    height: 1px;
+    margin: -1px;
+    overflow: hidden;
+    padding: 0;
+    position: absolute;
+    width: 1px;
+    white-space: nowrap;
+    user-select: none;
+}
+
+.p-hidden-accessible input,
+.p-hidden-accessible select {
+    transform: scale(0);
+}
+
 .p-overlay-mask {
     @apply bg-black/50 text-surface-200 transition-colors duration-150 fixed top-0 start-0 w-full h-full
 }

package/primevue-plugin.ts

@@ -1,8 +1,244 @@
-import type { App } from 'vue'
-import PrimeVue from 'primevue/config'
-
-export const PrimeVuePlugin = {
-  install: (app: App) => app.use(PrimeVue, { theme: 'none' }),
-}
-
-export default PrimeVuePlugin
+import type { App, VNode } from 'vue'
+import PrimeVue from 'primevue/config'
+import Portal from 'primevue/portal'
+import { createCommentVNode, h, renderSlot, Teleport } from 'vue'
+
+const LAYER_ATTR = 'data-wippy-overlay-layer'
+
+/**
+ * Client (browser) guard, equivalent to `@primeuix/utils`' `isClient` — inlined so
+ * this plugin (which ships as raw `.ts` that every consumer typechecks) takes no
+ * dependency on `@primeuix/utils`, which is only a transitive dep of `primevue` and
+ * is not guaranteed to resolve at the `/dom` subpath in a consumer's build.
+ */
+function isClient(): boolean {
+  return typeof window !== 'undefined' && typeof window.document !== 'undefined'
+}
+
+/** The `ShadowRoot` a node lives in, or null (light DOM). */
+function shadowRootOf(el: Node | null): ShadowRoot | null {
+  const root = el && typeof el.getRootNode === 'function' ? el.getRootNode() : null
+  return root instanceof ShadowRoot ? root : null
+}
+
+/**
+ * Pin `layer` (a `position: fixed` element) so its viewport origin is exactly
+ * `(-scrollX, -scrollY)` — i.e. document coordinate `(0,0)` maps to the layer's
+ * top-left corner.
+ *
+ * PrimeVue's `absolutePosition` writes DOCUMENT coordinates to an overlay
+ * (`trigger.getBoundingClientRect()` + window scroll). The overlay is
+ * `position: absolute`, so those coordinates resolve against this layer. Placing
+ * the layer at `(-scrollX, -scrollY)` makes an absolute child at document coord D
+ * render at viewport `D - scroll` — the correct on-screen spot.
+ *
+ * We MEASURE instead of assuming "fixed == viewport origin": a fixed element's
+ * containing block is the nearest ancestor with `transform` / `filter` /
+ * `perspective` / `will-change` / `contain` (extremely common — `translateZ(0)`
+ * GPU hints, slide animations, virtualized lists), NOT necessarily the viewport.
+ * Reading the rect at `top:0;left:0` yields that containing block's viewport
+ * origin; we then offset by it plus the scroll. This holds for any
+ * TRANSLATION-only containing block and any window scroll.
+ *
+ * Residuals (documented):
+ *  - SCALE / ROTATE / SKEW containing block: compensating via CSS `top`/`left`
+ *    only cancels the containing block's translation, not a non-identity linear
+ *    transform, so a `scale()`/`rotate()`/`skew()` ancestor mispositions the
+ *    overlay (by `(s-1)·distance` under `scale(s)`). Rare for a shadow-host
+ *    ancestor; a full fix would need the ancestor's transform matrix. Translation
+ *    (`translate`, `translateZ(0)`) is the common case and is handled.
+ *  - CLIPPING: an ancestor that both establishes the fixed containing block AND
+ *    clips (`transform`/`contain`/`will-change` + `overflow != visible`, or
+ *    `contain: paint/strict/content`, or `overflow: clip`) can still clip an
+ *    overlay that extends beyond its box — intrinsic to staying in the shadow root.
+ *  - ANIMATING ancestor: if the containing block MOVES between resyncs (a
+ *    transform animating while an overlay is open) the overlay lags until the
+ *    next scroll/resize.
+ *  - `position: fixed` self-positioning overlays (Toast) resolve against a
+ *    transformed containing block, not the viewport, so they are offset under such
+ *    an ancestor (their own fixed CSS, not `absolutePosition`, is unaffected by the
+ *    layer). Wippy bridges toasts to the host, so this is not hit in practice.
+ */
+function syncLayer(layer: HTMLElement): void {
+  layer.style.top = '0px'
+  layer.style.left = '0px'
+  const rect = layer.getBoundingClientRect()
+  layer.style.top = `${-window.scrollY - rect.top}px`
+  layer.style.left = `${-window.scrollX - rect.left}px`
+}
+
+// A SINGLE viewport-driven resync loop shared by every shadow-root layer — not a
+// listener pair per layer. When a `view.component` unmounts, its layer detaches with
+// the shadow root; this loop prunes detached layers on the next scroll/resize, so a
+// mount/unmount cycle leaks no window listeners, observers, or detached subtree.
+const activeLayers = new Set<HTMLElement>()
+const layerObservers = new WeakMap<HTMLElement, MutationObserver>()
+let viewportListenersAttached = false
+let viewportSyncScheduled = false
+
+function syncActiveLayers(): void {
+  viewportSyncScheduled = false
+  for (const layer of activeLayers) {
+    if (!layer.isConnected) {
+      activeLayers.delete(layer)
+      layerObservers.get(layer)?.disconnect()
+      continue
+    }
+    if (layer.childElementCount > 0)
+      syncLayer(layer)
+  }
+}
+
+function onViewportChange(): void {
+  if (viewportSyncScheduled)
+    return
+  viewportSyncScheduled = true
+  requestAnimationFrame(syncActiveLayers)
+}
+
+/**
+ * Get (or create) the per-shadow-root overlay layer, pinned to viewport origin and
+ * kept in sync as overlays open (a per-layer `MutationObserver`) and as the page
+ * scrolls/resizes (the one shared listener pair over {@link activeLayers}).
+ */
+function ensureLayer(root: ShadowRoot): HTMLElement {
+  const existing = root.querySelector<HTMLElement>(`[${LAYER_ATTR}]`)
+  if (existing)
+    return existing
+
+  const layer = document.createElement('div')
+  layer.setAttribute(LAYER_ATTR, '')
+  layer.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;'
+  root.appendChild(layer)
+  syncLayer(layer)
+
+  // Re-pin whenever an overlay is inserted — it may open after the page scrolled or
+  // the layout shifted (the layer isn't synced while empty). syncLayer only mutates
+  // the layer's own style, so it never re-triggers this childList observer. The
+  // observer is referenced only via the WeakMap, so it is disconnected when the layer
+  // detaches (in syncActiveLayers) and otherwise GC'd with the layer.
+  const observer = new MutationObserver(() => {
+    if (layer.isConnected && layer.childElementCount > 0)
+      syncLayer(layer)
+  })
+  observer.observe(layer, { childList: true })
+  layerObservers.set(layer, observer)
+
+  activeLayers.add(layer)
+  if (!viewportListenersAttached) {
+    viewportListenersAttached = true
+    // Capture phase so a scrolling ancestor (not just the window) also triggers a
+    // resync; passive since we never preventDefault. One pair total, for all layers.
+    window.addEventListener('scroll', onViewportChange, { capture: true, passive: true })
+    window.addEventListener('resize', onViewportChange, { passive: true })
+  }
+  return layer
+}
+
+/**
+ * PrimeVue's shared `primevue/portal` is an Options-API component object (a singleton
+ * shared by every overlay). We rewrite the render-relevant options on it in place.
+ */
+interface PortalOptions {
+  computed?: Record<string, (this: PortalInstance) => unknown>
+  data?: (this: PortalInstance) => Record<string, unknown>
+  mounted?: (this: PortalInstance) => void
+  render?: (this: PortalInstance) => VNode
+}
+
+interface PortalInstance {
+  /** The Portal's `$el` — a comment `Node` (placeholder vnode) before teleport. */
+  $el: Node | null
+  $slots: Record<string, unknown>
+  disabled?: boolean
+  /** `'self'` (inline), `'body'`/null/undefined (teleport), or an explicit target. */
+  appendTo?: unknown
+  inline: boolean
+  mounted: boolean
+  /** The shadow root this overlay lives in (captured once on mount), or null. */
+  hostRoot: ShadowRoot | null
+  resolvedTarget: Element | string | null
+}
+
+let patched = false
+
+/**
+ * Make PrimeVue overlays render inside the shadow root — unclipped and correctly
+ * positioned — by default, without any per-component `appendTo`.
+ *
+ * PrimeVue 4 has no global `appendTo` config, and the `@primeuix/utils` positioning
+ * helpers are immutable ESM bindings. But every overlay teleports through the ONE
+ * shared `primevue/portal`, whose options object is a mutable singleton. We rewrite it
+ * so the DEFAULT `appendTo` (`'body'`, or null/undefined) teleports to a per-shadow-root
+ * layer ({@link ensureLayer}) that is measured-and-pinned to true viewport origin
+ * ({@link syncLayer}) instead of `document.body`.
+ *
+ * Because `appendTo` is then not `'self'`, PrimeVue positions with `absolutePosition`
+ * (document-origin coords), which the pinned layer matches — so overlays are NOT
+ * clipped by a scrolling Dialog/Drawer body and land at the trigger, even under a
+ * transformed/filtered ancestor or a scrolled window. `'self'` keeps its inline
+ * semantics (explicit opt-in); outside a shadow root everything falls back to
+ * `document.body`. `resolvedTarget` is a computed, so a reactive `appendTo` is honored.
+ *
+ * Runs once at plugin install (before the first overlay renders); the guard makes
+ * repeat installs safe.
+ */
+export function patchOverlayPortal(): void {
+  if (patched)
+    return
+  patched = true
+
+  const portal = Portal as unknown as PortalOptions
+
+  portal.computed = portal.computed || {}
+  portal.computed.inline = function (this: PortalInstance) {
+    return Boolean(this.disabled) || this.appendTo === 'self'
+  }
+  // Reactive to `appendTo`: the default ('body'/null) resolves to the shadow-root
+  // layer (or document.body in light DOM); an explicit target passes through.
+  portal.computed.resolvedTarget = function (this: PortalInstance) {
+    if (this.appendTo == null || this.appendTo === 'body')
+      return this.hostRoot ? ensureLayer(this.hostRoot) : document.body
+    return this.appendTo as Element | string
+  }
+
+  portal.data = function (this: PortalInstance) {
+    return { mounted: false, hostRoot: null }
+  }
+
+  portal.mounted = function (this: PortalInstance) {
+    // Match upstream Portal: teleport is client-only. Guards DOM access below
+    // (ensureLayer → createElement) if this ever runs without a document.
+    if (!isClient())
+      return
+    // `$el` here is the placeholder comment node — capture its shadow root once.
+    this.hostRoot = shadowRootOf(this.$el)
+    this.mounted = true
+    // Ensure the layer (and its resync observers) exist before the first render.
+    // The per-open re-pin is driven by the layer's MutationObserver, not here —
+    // this hook fires when the overlay component mounts, not when it opens.
+    if (this.hostRoot)
+      ensureLayer(this.hostRoot)
+  }
+
+  portal.render = function (this: PortalInstance) {
+    // Keys mirror upstream's `key: 0`/`key: 1` so Vue replaces (never patches)
+    // across the inline↔teleport branches if `inline` ever toggles reactively.
+    if (this.inline)
+      return renderSlot(this.$slots as never, 'default', { key: 0 }) as unknown as VNode
+    if (!this.mounted)
+      return createCommentVNode('', true)
+    return h(Teleport, { key: 1, to: this.resolvedTarget || document.body } as never, [
+      renderSlot(this.$slots as never, 'default'),
+    ])
+  }
+}
+
+export const PrimeVuePlugin = {
+  install: (app: App) => {
+    patchOverlayPortal()
+    app.use(PrimeVue, { theme: 'none' })
+  },
+}
+
+export default PrimeVuePlugin

package/tokens.json

@@ -1,6 +1,6 @@
 {
   "generatedFrom": "theme-config.css",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "grammar": "every color family = --p-<fam> + --p-<fam>-{50..950} + --p-<fam>-{color,contrast-color,hover-color,active-color}; --p-surface-<shade>; text/content/highlight semantic aliases; --p-font-<role>-<prop>",
   "families": [
     "primary",