@zeyos/zx 4.2.0 → 4.3.4

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/component.d.ts

@@ -73,10 +73,15 @@ export declare class Component<TOptions extends ComponentOptions = ComponentOpti
      * Dispatches a component event and a bubbling, composed `zx-*` DOM event.
      * @param {string} type Lowercase event name.
      * @param {Record<string, unknown>} [detail={}] Single event detail object.
+     * @param {{honorDomCancellation?:boolean}} [options={}] Mirrored DOM-event behavior. Components
+     * with a cancelable mutation boundary may opt into treating `preventDefault()` on the bubbling
+     * `zx-*` event exactly like cancellation of the component event.
      * @returns {Event & {detail: Record<string, unknown>}}
      * @fires Component#event
      */
-    emit(type: string, detail?: Record<string, unknown>): Event & {
+    emit(type: string, detail?: Record<string, unknown>, options?: {
+        honorDomCancellation?: boolean;
+    }): Event & {
         detail: Record<string, unknown>;
     };
     /**

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;

package/dist/types/index.d.ts

@@ -78,12 +78,13 @@ export { DateRangePicker, clampRange, defaultDateRangePresets, normalizeRange, r
 export { DateRangeBox, formatRangeText, parseRangeText } from './components/datebox/date-range-box.js';
 export { Timebox, splitTime, joinTime } from './components/timebox/timebox.js';
 export { Calendar } from './components/calendar/calendar.js';
-export { CALENDAR_VIEWS, addCalendarDays, calendarDayDifference, calendarDayKey, calendarEventIntersects, calendarEventSpansDays, calendarRange, cloneCalendarEvent, layoutCalendarSpans, layoutTimedCalendarEvents, normalizeCalendarEvents, shiftCalendarEvent, startOfCalendarDay, startOfCalendarWeek } from './components/calendar/calendar-model.js';
+export { CALENDAR_VIEWS, addCalendarDays, addCalendarMonths, calendarDayDifference, calendarDayKey, calendarEventIntersects, calendarEventSpansDays, calendarPageDate, calendarRange, cloneCalendarEvent, layoutCalendarSpans, layoutTimedCalendarEvents, normalizeCalendarEvents, shiftCalendarEvent, startOfCalendarDay, startOfCalendarWeek } from './components/calendar/calendar-model.js';
 export { RecordView, normalizeViewFields, reconcileFieldOrder, moveViewField, readViewField, renderViewField, sortViewRecords, normalizeViewState, viewRecordId } from './components/view/record-view.js';
 export { Table, reorderTableRows } from './components/table/table.js';
 export { TableView } from './components/table-view/table-view.js';
 export { CardView } from './components/card-view/card-view.js';
 export { KanbanView } from './components/kanban-view/kanban-view.js';
+export { absoluteKanbanIndex, allowsKanbanTransition, createKanbanHistory, evaluateKanbanMove, kanbanSearchTerms, locateKanbanRecord, matchesKanbanSearch, normalizeKanbanRules, reorderKanbanRecords, resolveKanbanRules } from './components/kanban-view/kanban-policy.js';
 export { Grid, billingColumns, isBillingLine } from './components/grid/grid.js';
 export { Chart, ChartJsAdapter, chartSummaryTable, cloneChartValue, isEmptyChartData } from './components/chart/chart.js';
 export { TreeView } from './components/tree/tree.js';