@zeyos/zx 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -8,6 +8,43 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 4.3.0 — 2026-08-26
+
+### Added
+
+- **Scoped top-layer ownership.** Dropdown, Modal, Dialog, Sheet, Launcher, and floating Message
+  regions accept an optional `scope` context and otherwise resolve the opener's nearest Zx theme
+  scope. Native popovers and dialogs still use the browser top layer, while material, density,
+  product-token, and nested-theme inheritance remain intact.
+
+### Changed
+
+- **Liquid glass is now a real overlay material.** Compact overlays and reading panels use
+  separate translucent bases, restrained specular and Aurora-response layers, blur/saturation,
+  shadows, borders, dividers, and interaction-state tokens. Menus, Select, TagPicker, date
+  popovers, tooltips, table column controls, and Toast use compact glass; Launcher, Modal, Dialog,
+  and floating Sheets use the calmer reading material. Docked Sheets remain opaque.
+- **Theme Studio makes optical differences visible.** Its overlay specimen now sits on a
+  multicolour Aurora field, while Flat, Glass, and Deep glass expose materially different alpha,
+  refraction, and elevation in both light and dark themes.
+- **Accessible material fallbacks are deterministic.** Reduced-transparency, increased-contrast,
+  forced-colour, and unsupported-filter environments remove reflection and backdrop effects and
+  restore solid surfaces; blurred Sheet backdrops follow the same rule.
+
+### Fixed
+
+- Toast intent colours no longer turn the surface effectively opaque, modal backdrops no longer
+  erase the content meant to refract through the panel, scoped modals lock page scrolling again,
+  and DatePicker controls no longer tile the owning surface's reflection gradient.
+- Floating non-modal Sheets now remain viewport-anchored inside transformed or clipped theme
+  scopes, and generation-aware lifecycle handling prevents queued close events from invalidating
+  a reopened Sheet during rapid dock/release handoffs.
+- Documentation search now consumes the same compact overlay material, interaction states, and
+  accessibility fallbacks as library popovers; fallback tokens cover every supported theme scope.
+- Calendar drag operations preserve the grabbed time/day offset, resize previews track their
+  proposed duration, pointer capture is resilient, and agenda/month layouts keep their event and
+  day controls aligned across desktop and mobile views.
+
 ## 4.2.0 — 2026-08-26
 
 ### Added

package/README.md

@@ -238,6 +238,11 @@ the document. Select a built-in theme and density on any ancestor (normally `<ht
 <html data-zx-theme="dark" data-zx-density="compact">
 ```
 
+Top-layer menus, dialogs, tooltips, launchers, and toast regions stay under the nearest Zx theme
+scope in the DOM, so a theme or product-token override on a nested application shell also applies
+to its overlays. Pass the optional `scope` context to Modal, Dialog, Sheet, Launcher, or static
+Message calls when the opener is not inside the intended scope.
+
 Theme values are `light`, `dark`, and `auto`; density values are `cozy` and `compact`. `auto`
 follows the operating-system color preference.
 

package/dist/types/components/calendar/calendar.d.ts

@@ -283,6 +283,8 @@ export declare class Calendar extends Component<CalendarOptions> {
         event: import("./calendar-model.js").CalendarEvent;
         action: string;
         control: any;
+        timeOffsetMinutes: number;
+        dayOffset: number;
         moved: boolean;
         start?: undefined;
         end?: undefined;
@@ -290,6 +292,8 @@ export declare class Calendar extends Component<CalendarOptions> {
         oldEvent?: undefined;
         event?: undefined;
         action?: undefined;
+        timeOffsetMinutes?: undefined;
+        dayOffset?: undefined;
         type: string;
         pointerId: number;
         startX: number;
@@ -424,10 +428,23 @@ export declare class Calendar extends Component<CalendarOptions> {
     _cancelPointer(event: PointerEvent): void;
     /** @param {CalendarEvent} event @param {'move'|'resize'} action @param {number} x @param {number} y @returns {CalendarEvent|null} */
     _proposalAtPoint(event: CalendarEvent, action: 'move' | 'resize', x: number, y: number): CalendarEvent | null;
-    /** @param {number} x @param {number} y @returns {Date|null} */
-    _timeAtPoint(x: number, y: number): Date | null;
+    /** @param {number} x @param {number} y @param {Date|null} [fixedDay=null] @returns {Date|null} */
+    _timeAtPoint(x: number, y: number, fixedDay?: Date | null): Date | null;
     /** @param {number} x @param {number} y @returns {Date|null} */
     _dayAtPoint(x: number, y: number): Date | null;
+    /** @param {CalendarEvent} event @param {number} x @param {number} y @returns {{minutes: number, days: number}} */
+    _dragOffsetForEvent(event: CalendarEvent, x: number, y: number): {
+        minutes: number;
+        days: number;
+    };
+    /** @param {Date} day @returns {number} */
+    _timeGridDayIndex(day: Date): number;
+    /** @param {CalendarEvent} event @returns {string|null} */
+    _timedPreviewHeight(event: CalendarEvent): string | null;
+    /** @param {number} pointerId @returns {void} */
+    _capturePointer(pointerId: number): void;
+    /** @param {number} pointerId @returns {void} */
+    _releasePointerCapture(pointerId: number): void;
     /** @param {Date} start @param {Date} end @returns {void} */
     _previewSelection(start: Date, end: Date): void;
     /** @returns {void} */

package/dist/types/components/dialog/dialog.d.ts

@@ -41,6 +41,10 @@ export type DialogOptions = {
     content?: Node | string | number | {
         toElement: () => Node | null;
     } | null;
+    /**
+     * Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+     */
+    scope?: Element | string | null;
     /**
      * Open event listener.
      */
@@ -159,6 +163,7 @@ export type PromptOptions = {
  * @property {DialogButton[]} [buttons=[]] Footer buttons.
  * @property {boolean} [closable=true] Whether Escape and the header button may close the dialog.
  * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Body content.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -209,7 +214,7 @@ export declare class Dialog extends Modal {
     /** @type {Readonly<DialogOptions>} */
     static defaults: Readonly<DialogOptions>;
     /**
-     * Creates a structured dialog appended to `document.body`.
+     * Creates a structured dialog in the configured theme scope, or at document level when unscoped.
      * @param {Element|string|null} [_target=null] Ignored; Dialog always owns its root.
      * @param {DialogOptions} [options={}] Dialog options.
      */

package/dist/types/components/dropdown/dropdown.d.ts

@@ -28,6 +28,10 @@ export type DropdownOptions = {
      * Whether a click within the panel closes it.
      */
     closeOnSelect?: boolean;
+    /**
+     * Element whose nearest Zx theme scope owns the panel; defaults to the anchor.
+     */
+    scope?: Element | string | null;
     /**
      * Open event listener.
      */
@@ -45,6 +49,7 @@ export type DropdownOptions = {
  * @property {boolean} [matchWidth=false] Whether the panel matches the anchor width.
  * @property {'click'|'manual'} [openOn='click'] Trigger behavior.
  * @property {boolean} [closeOnSelect=false] Whether a click within the panel closes it.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the panel; defaults to the anchor.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
  */

package/dist/types/components/launcher/launcher.d.ts

@@ -162,6 +162,10 @@ export type LauncherOptions = {
         open?: string;
         close?: string;
     };
+    /**
+     * Element whose nearest Zx theme scope owns an internally created launcher; defaults to the opener.
+     */
+    scope?: Element | string | null;
     /**
      * Preventable selection listener.
      */
@@ -244,6 +248,7 @@ export type RankedLauncherItem = LauncherItem & {
  * @property {string} [loadingText='Searching…'] Loading-state text.
  * @property {'mod+k'|false} [shortcut='mod+k'] Optional global keyboard shortcut.
  * @property {false|{move?: string, open?: string, close?: string}} [hints] Visible keyboard hints, or false.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns an internally created launcher; defaults to the opener.
  * @property {(event: CustomEvent<LauncherSelectDetail>) => void} [onselect] Preventable selection listener.
  * @property {(event: CustomEvent<{query: string}>) => void} [onquery] Query-change listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open listener.

package/dist/types/components/message/message.d.ts

@@ -13,6 +13,10 @@ export type MessageShowOptions = {
      * Whether to render a close button.
      */
     closable?: boolean;
+    /**
+     * Element whose nearest Zx theme scope owns a floating toast.
+     */
+    scope?: Element | string | null;
 };
 export type MessageOptions = {
     /**
@@ -55,6 +59,7 @@ export type ProgressHandle = {
  * @property {MessageKind|'danger'} [kind='info'] Message intent (`danger` aliases `error`).
  * @property {number} [timeout=4000] Auto-dismiss delay in milliseconds; zero persists.
  * @property {boolean} [closable=true] Whether to render a close button.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns a floating toast.
  */
 /**
  * @typedef {Object} MessageOptions
@@ -176,9 +181,12 @@ export declare class Message extends Component<MessageOptions> {
     /**
      * Shows a floating progress status.
      * @param {string} text Initial status text.
+     * @param {{scope?: Element|string|null}} [options={}] Floating-region scope.
      * @returns {ProgressHandle}
      */
-    static progress(text: string): ProgressHandle;
+    static progress(text: string, options?: {
+        scope?: Element | string | null;
+    }): ProgressHandle;
     /** @returns {void} */
     destroy(): void;
     /** @param {string} text @returns {ProgressHandle} */

package/dist/types/components/modal/modal.d.ts

@@ -22,6 +22,10 @@ export type ModalOptions = {
      * Whether to destroy the modal after it closes.
      */
     destroyOnClose?: boolean;
+    /**
+     * Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+     */
+    scope?: Element | string | null;
     /**
      * Open event listener.
      */
@@ -44,6 +48,7 @@ export type ModalOptions = {
  * @property {boolean} [closable=true] Whether Escape may close the modal.
  * @property {boolean} [lightDismiss=false] Whether a backdrop click closes the modal.
  * @property {boolean} [destroyOnClose=false] Whether to destroy the modal after it closes.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -62,7 +67,7 @@ export declare class Modal extends Component<ModalOptions> {
     /** @type {Readonly<ModalOptions>} */
     static defaults: Readonly<ModalOptions>;
     /**
-     * Creates a modal appended to `document.body`.
+     * Creates a modal in the configured theme scope, or at document level when none is present.
      * @param {Element|string|null} [_target=null] Ignored; Modal always owns its root dialog.
      * @param {ModalOptions} [options={}] Modal options.
      */
@@ -81,17 +86,49 @@ export declare class Modal extends Component<ModalOptions> {
      * @returns {void}
      */
     _show(): void;
+    /**
+     * Removes the dialog from its current presentation layer.
+     * Subclasses may replace native dialog presentation while preserving Modal lifecycle events.
+     * @param {string} [result=''] Native string return value.
+     * @param {number} [presentation=this.#presentation] Presentation generation being hidden.
+     * @returns {void}
+     */
+    _hide(result?: string, presentation?: number): void;
+    /**
+     * Shows a new presentation and gives it a generation of its own. Close events are queued by the
+     * platform, so the generation lets an event from an earlier presentation expire harmlessly if
+     * the same overlay has already reopened.
+     * @returns {void}
+     */
+    _present(): void;
+    /**
+     * Hides the current presentation and records which generation its queued close event belongs to.
+     * @param {string} [result=''] Native string return value.
+     * @returns {void}
+     */
+    _dismiss(result?: string): void;
+    /**
+     * Reports whether the current presentation layer is visible.
+     * @returns {boolean}
+     */
+    _isShown(): boolean;
     /**
      * Whether an incoming `close` event is a real dismissal.
      *
-     * A dialog cannot move between the top layer and the page flow while it is open, so a subclass
-     * that re-hosts itself has to close and immediately reopen. `close` is dispatched in a queued
-     * task, not synchronously, so that stale event arrives once the dialog is already open again —
-     * late enough to clobber `data-state`, fire a `close` nobody asked for, and trip
-     * `destroyOnClose`. Returning false from an override drops it at the source instead.
+     * `close` is dispatched in a queued task, not synchronously. By the time it arrives the overlay
+     * may have reopened or crossed presentation layers, so only the event for the current hidden
+     * generation may settle state, emit lifecycle events, or trigger `destroyOnClose`.
+     * @param {number|undefined} closingPresentation Presentation that produced the event, if known.
      * @returns {boolean}
      */
-    _isRealClose(): boolean;
+    _isRealClose(closingPresentation: number | undefined): boolean;
+    /**
+     * Settles one presentation's close without allowing a queued event to invalidate a newer one.
+     * Popover-based subclasses call this directly; native dialog events arrive through the listener.
+     * @param {number|undefined} closingPresentation Presentation that was hidden, if known.
+     * @returns {boolean} Whether this event closed the current presentation.
+     */
+    _settleClose(closingPresentation: number | undefined): boolean;
     /**
      * Creates the owned native dialog.
      * @returns {HTMLDialogElement}

package/dist/types/components/sheet/sheet.d.ts

@@ -80,6 +80,10 @@ export type SheetOptions = {
      * Whether to destroy the sheet after it closes.
      */
     destroyOnClose?: boolean;
+    /**
+     * Element whose nearest Zx theme scope owns a floating sheet; defaults to the opener.
+     */
+    scope?: Element | string | null;
     /**
      * Open event listener.
      */
@@ -138,6 +142,7 @@ export type SheetOptions = {
  * @property {boolean} [lightDismiss=true] Whether a click outside closes the sheet — the backdrop
  *   when modal, a document-level pointer press when not.
  * @property {boolean} [destroyOnClose=false] Whether to destroy the sheet after it closes.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns a floating sheet; defaults to the opener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -153,9 +158,11 @@ export type SheetOptions = {
  *
  * Modality is a three-way choice rather than a boolean because the three real behaviours do not
  * collapse into two: a modal sheet delegates focus containment, page inertness, and Escape to the
- * browser via `showModal()`; the other two open with `show()` and re-implement only what they still
- * want. That is also why `backdrop` applies only to `modal: true` — `::backdrop` does not render
- * for a non-modal dialog, and painting a fake one would make a sheet look blocking while it is not.
+ * browser via `showModal()`; floating non-modal sheets use the manual Popover top layer so a
+ * transformed or clipped application scope cannot displace them, and re-implement only what they
+ * still want. Docked sheets remain native non-modal dialogs in flow. That is also why `backdrop`
+ * applies only to `modal: true`: painting one for either non-modal mode would make the sheet look
+ * blocking while it is not.
  * @fires Sheet#open
  * @fires Sheet#close
  * @fires Sheet#cancel
@@ -165,7 +172,6 @@ export type SheetOptions = {
 export declare class Sheet extends Dialog {
     #private;
     _dock: any;
-    _handoff: boolean;
     static cssName: string;
     /** @type {Readonly<SheetOptions>} */
     static defaults: Readonly<SheetOptions>;
@@ -217,17 +223,12 @@ export declare class Sheet extends Dialog {
     /**
      * Moves the dialog to its current mount and, when it was open, reopens it there.
      *
-     * The close is unavoidable — a dialog cannot cross between the top layer and the flow while
-     * open — but it is invisible: `_isRealClose()` drops the stale event, and reopening bypasses
-     * `open()` so no lifecycle event is emitted for what is only a change of address.
+     * The close is unavoidable — a dialog cannot cross between presentation layers while open —
+     * but it is invisible: Modal's presentation generation drops the stale event, and reopening
+     * bypasses `open()` so no lifecycle event is emitted for what is only a change of address.
      * @returns {void}
      */
     _rehost(): void;
-    /**
-     * Drops the stale `close` a re-hosting handoff leaves behind.
-     * @returns {boolean}
-     */
-    _isRealClose(): boolean;
     /**
      * Opens the sheet, trapping focus first where the modality asks for it.
      * @returns {this}
@@ -276,6 +277,15 @@ export declare class Sheet extends Dialog {
      * @returns {void}
      */
     _show(): void;
+    /**
+     * Hides a native dialog or a non-modal Sheet promoted through the popover top layer.
+     * @param {string} [result=''] Native string return value.
+     * @param {number} [presentation] Presentation generation being hidden.
+     * @returns {void}
+     */
+    _hide(result?: string, presentation?: number): void;
+    /** @returns {boolean} */
+    _isShown(): boolean;
     /**
      * Releases the focus trap and the owned dialog.
      * @returns {void}

package/dist/types/core/overlay-host.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finds the closest styling scope for a top-layer element.
+ *
+ * Popovers and dialogs escape clipping even when their DOM parent is inside an application shell,
+ * so keeping them below that parent preserves inherited theme, density, material, and product
+ * token overrides without sacrificing top-layer behaviour. The document body remains the safe
+ * fallback for unscoped applications.
+ *
+ * @param {Element|string|null} [source=null] Element or selector whose styling scope should own the overlay.
+ * @returns {Element}
+ */
+export declare function overlayHost(source?: Element | string | null): Element;