@qw-ui/core 0.3.0-next.9 → 0.3.0

package/dist/popover/layer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Non-modal layer lifetime shared by Popover and Dropdown: dismissal through Zag's existing layer stack
+ * (no pointer blocking, no new modal owner) and the focus return policy. Every DOM read happens inside
+ * the returned effects, never at import.
+ */
+/** Why a layer asked to open or close. trigger: its trigger toggled; keyboard: a trigger key; api: the owner or setOpen. */
+export type FloatingCloseReason = "trigger" | "keyboard" | "escape" | "outside" | "focus-outside" | "tab" | "select" | "api";
+export type FloatingDismissReason = Extract<FloatingCloseReason, "escape" | "outside" | "focus-outside">;
+/** A pending close request: the reason and whether an outside interaction landed on a focusable node. */
+export interface FloatingCloseRequest {
+    reason: FloatingCloseReason;
+    focusable: boolean;
+}
+export interface FloatingDismissOptions {
+    type: "popover" | "menu";
+    content(): HTMLElement | null;
+    trigger(): HTMLElement | null;
+    closeOnEscape(): boolean;
+    closeOnOutside(): boolean;
+    closeOnFocusOutside(): boolean;
+    onDismiss(request: FloatingCloseRequest): void;
+    /** Called after the existing layer has installed its deferred pointer listener. */
+    onReady?(): void;
+}
+/**
+ * Wait for the content node (a microtask, then up to FLOATING_WAIT_FRAMES frames), then join the layer
+ * stack: only the topmost layer handles Escape, outside pointer/focus excludes the trigger and nested layers,
+ * and nothing outside is blocked. Cleanup leaves the stack or cancels the wait.
+ */
+export declare function trackFloatingDismiss(doc: Document, options: FloatingDismissOptions): () => void;
+/**
+ * Focus return when a layer closes, called while its content is still in the DOM:
+ * - tab / focus-outside: focus already moved on; nothing happens.
+ * - outside: unless the outside target was focusable, focus that was inside the layer (or on the trigger)
+ *   returns to the trigger after the pointer settles, if it ended on <body>.
+ * - everything else (escape, select, trigger, api): focus inside the layer, on <body> or nowhere returns to
+ *   the trigger at once; focus the user moved elsewhere on the page stays put.
+ */
+export declare function restoreFloatingFocus(doc: Document, trigger: HTMLElement | null, content: HTMLElement | null, request: FloatingCloseRequest): void;
+/**
+ * Focus a node once it can take focus: the layer is `visibility: hidden` until the first layout reaches
+ * the DOM, so try on the next frames until it succeeds (bounded). Returns a cancel function.
+ */
+export declare function focusWhenReady(doc: Document, target: () => HTMLElement | null, attempts?: number): () => void;

package/dist/popover/popover.d.ts

@@ -0,0 +1,104 @@
+import { type Machine, type Service } from "@zag-js/core";
+import type { NormalizeProps, PropTypes } from "@zag-js/types";
+import { type FloatingAlign, type FloatingLayout, type FloatingPlacement, type FloatingSide } from "./positioning.js";
+import { type FloatingCloseRequest } from "./layer.js";
+/** Stable DOM parts shared by every adapter. */
+export declare const POPOVER_PARTS: readonly ["trigger", "positioner", "arrow", "content"];
+export type PopoverPlacement = FloatingPlacement;
+export declare const POPOVER_DEFAULT_PLACEMENT: PopoverPlacement;
+/** trigger: the trigger toggled; escape / outside: dismissal; api: setOpen. */
+export type PopoverOpenChangeReason = "trigger" | "escape" | "outside" | "api";
+export interface PopoverOpenChangeDetails {
+    open: boolean;
+    reason: PopoverOpenChangeReason;
+}
+export interface QwPopoverProps {
+    /** Page-unique instance identity; adapters generate one when omitted. */
+    id?: string;
+    /** Controlled open state; undefined lets Core own it. */
+    open?: boolean;
+    /** Initial open state when uncontrolled. */
+    defaultOpen?: boolean;
+    /** Every open/close request (trigger, Escape, outside, setOpen), controlled or not. Controlled owners accept by updating open, or refuse by keeping it. */
+    onOpenChange?: (details: PopoverOpenChangeDetails) => void;
+    /** Preferred placement (default bottom; unknown values use bottom). Flips to the opposite side when space is short; start/end mirror on top/bottom in RTL. */
+    placement?: PopoverPlacement;
+    /** Main-axis gap between the trigger and the panel in CSS px; default 8. */
+    offset?: number;
+    /** Arrow pointing at the trigger; default true. */
+    arrow?: boolean;
+    /** Accessible name of the dialog; omitted names it by the trigger (aria-labelledby). */
+    label?: string;
+    /** Escape closes the topmost open layer; default true. */
+    closeOnEscape?: boolean;
+    /** A pointer interaction outside the panel and the trigger closes; default true. */
+    closeOnInteractOutside?: boolean;
+}
+export interface ResolvedPopoverState {
+    placement: PopoverPlacement;
+    offset: number;
+    arrow: boolean;
+    label: string | undefined;
+    closeOnEscape: boolean;
+    closeOnInteractOutside: boolean;
+}
+export declare function resolvePopoverState(props?: QwPopoverProps): ResolvedPopoverState;
+export declare function createPopoverProps(props?: QwPopoverProps): QwPopoverProps;
+export interface QwPopoverSchema {
+    props: QwPopoverProps;
+    context: {
+        dismissReady: boolean;
+        layout: FloatingLayout | null;
+    };
+    refs: {
+        request: FloatingCloseRequest | null;
+    };
+    state: "open" | "closed";
+    guard: "isControlled";
+    action: "notifyOpen" | "notifyClose" | "restoreFocus" | "setLayout" | "dismissReady" | "clearLayout" | "syncControlled";
+    effect: "trackLayout" | "trackDismiss";
+    event: {
+        type: "OPEN" | "TOGGLE";
+        reason?: PopoverOpenChangeReason;
+    } | {
+        type: "CLOSE";
+        reason?: PopoverOpenChangeReason;
+        focusable?: boolean;
+    } | {
+        type: "CONTROLLED.OPEN" | "CONTROLLED.CLOSE";
+    } | {
+        type: "LAYOUT";
+        layout: FloatingLayout;
+    } | {
+        type: "DISMISS.READY";
+    };
+}
+export type QwPopoverMachine = Machine<QwPopoverSchema>;
+export type QwPopoverService = Service<QwPopoverSchema>;
+/**
+ * Core owns open/close (controlled requests and refusals), positioning while open, dismissal through the
+ * shared non-modal layer stack (Escape, outside pointer; focus may leave freely) and the focus return.
+ */
+export declare const popoverMachine: QwPopoverMachine;
+/** Minimal event surface shared by React, Vue and native events. */
+export interface PopoverDomEvent {
+    readonly defaultPrevented: boolean;
+}
+export interface QwPopoverApi<T extends PropTypes = PropTypes> {
+    open: boolean;
+    /** The measured placement while open (after flipping), otherwise the preferred one. */
+    placement: PopoverPlacement;
+    side: FloatingSide;
+    align: FloatingAlign;
+    /** The open panel has been measured and is visible. */
+    positioned: boolean;
+    arrow: boolean;
+    /** Request a state; controlled owners decide through onOpenChange (reason api). */
+    setOpen(open: boolean): void;
+    /** Merge onto the caller's own trigger node: its other props and handlers stay; preventDefault() in its onClick skips the toggle. */
+    getTriggerProps(): T["element"];
+    getPositionerProps(): T["element"];
+    getArrowProps(): T["element"];
+    getContentProps(): T["element"];
+}
+export declare function connectPopover<T extends PropTypes>(service: QwPopoverService, normalize: NormalizeProps<T>): QwPopoverApi<T>;

package/dist/popover/positioning.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Core-owned anchored positioning shared by Popover and Dropdown.
+ *
+ * `computeFloatingPosition` is a pure function (rects in → coordinates / placement / arrow out).
+ * `measureFloatingLayout` / `trackFloatingLayout` are the only DOM binding: they read rects and
+ * CSS-provided insets, never write the DOM, and hand a rounded layout to the machine. Adapters
+ * render it through `getFloatingPositionerStyle`, so SSR, hydration and every stack share one path.
+ */
+/** Physical sides of the anchor. */
+export declare const FLOATING_SIDES: readonly ["top", "right", "bottom", "left"];
+/** Cross-axis alignments. start/end follow the inline direction on top/bottom (mirrored in RTL) and the block direction on left/right. */
+export declare const FLOATING_ALIGNS: readonly ["center", "start", "end"];
+export declare const FLOATING_PLACEMENTS: readonly ["top", "top-start", "top-end", "right", "right-start", "right-end", "bottom", "bottom-start", "bottom-end", "left", "left-start", "left-end"];
+export type FloatingSide = (typeof FLOATING_SIDES)[number];
+export type FloatingAlign = (typeof FLOATING_ALIGNS)[number];
+export type FloatingPlacement = (typeof FLOATING_PLACEMENTS)[number];
+/** Default main-axis gap between the anchor edge and the floating box, in CSS px. */
+export declare const FLOATING_DEFAULT_OFFSET = 8;
+export interface FloatingRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FloatingPositionInput {
+    /** Anchor border box in viewport coordinates (getBoundingClientRect). */
+    anchor: FloatingRect;
+    /** Floating border-box size. */
+    floating: {
+        width: number;
+        height: number;
+    };
+    /** Usable area in viewport coordinates (viewport minus padding and safe areas). */
+    boundary: FloatingRect;
+    /** Preferred placement; unknown values use `fallback`. */
+    placement?: unknown;
+    /** Placement used for unknown values; defaults to bottom. */
+    fallback?: FloatingPlacement;
+    /** Main-axis gap in CSS px; non-finite values use 8. */
+    offset?: number;
+    /** Arrow square size and the minimum distance from the floating corners; omit or null without an arrow. */
+    arrow?: {
+        size: number;
+        padding?: number;
+    } | null;
+    /** Mirror start/end on the inline axis (top/bottom sides). */
+    rtl?: boolean;
+}
+export interface FloatingPosition {
+    /** Floating top-left corner in viewport coordinates. */
+    x: number;
+    y: number;
+    /** Resolved placement after flipping; align stays logical. */
+    placement: FloatingPlacement;
+    side: FloatingSide;
+    align: FloatingAlign;
+    /** The preferred side lacked space and the opposite side had more. */
+    flipped: boolean;
+    /** Arrow start on the cross axis relative to the floating box (from its left edge on top/bottom, its top edge on left/right); null without an arrow. */
+    arrow: number | null;
+    /** Space on the resolved side (main axis) and the boundary extent (cross axis), never negative. */
+    availableWidth: number;
+    availableHeight: number;
+}
+/** Unknown values fall back (default bottom). */
+export declare function resolveFloatingPlacement(value: unknown, fallback?: FloatingPlacement): FloatingPlacement;
+export declare function splitFloatingPlacement(placement: FloatingPlacement): {
+    side: FloatingSide;
+    align: FloatingAlign;
+};
+export declare function joinFloatingPlacement(side: FloatingSide, align: FloatingAlign): FloatingPlacement;
+/**
+ * Place the floating box next to the anchor: flip to the opposite side when the preferred side lacks
+ * space and the opposite has more, align on the cross axis (start/end mirrored on top/bottom in RTL),
+ * shift into the boundary while staying attached to the anchor, and point the arrow at the anchor center.
+ */
+export declare function computeFloatingPosition(input: FloatingPositionInput): FloatingPosition;
+/** Layout written by adapters from Core context: rounded, containing-block compensated, plus the anchor size. */
+export interface FloatingLayout {
+    x: number;
+    y: number;
+    placement: FloatingPlacement;
+    side: FloatingSide;
+    align: FloatingAlign;
+    arrow: number | null;
+    availableWidth: number;
+    availableHeight: number;
+    anchorWidth: number;
+    anchorHeight: number;
+}
+export declare function sameFloatingLayout(a: FloatingLayout | null | undefined, b: FloatingLayout | null | undefined): boolean;
+/** Private custom properties written inline on the positioner; component CSS consumes them. */
+export declare const FLOATING_STYLE_VARS: {
+    readonly x: "--qw-floating-x";
+    readonly y: "--qw-floating-y";
+    readonly arrow: "--qw-floating-arrow";
+    readonly availableWidth: "--qw-floating-available-width";
+    readonly availableHeight: "--qw-floating-available-height";
+    readonly anchorWidth: "--qw-floating-anchor-width";
+};
+/**
+ * Inline positioner style. Before the first measurement (SSR, hydration, the first client frame) the
+ * layer is laid out at the containing-block origin but `visibility: hidden`; afterwards it is translated
+ * (layout at the origin keeps its shrink-to-fit width independent of the position).
+ */
+export declare function getFloatingPositionerStyle(layout: FloatingLayout | null): Record<string, string>;
+export interface FloatingTrackOptions {
+    /** Elements are looked up on every update: layers mount after the effect starts and may be replaced. */
+    anchor(): HTMLElement | null;
+    positioner(): HTMLElement | null;
+    content(): HTMLElement | null;
+    arrow(): HTMLElement | null;
+    placement(): unknown;
+    offset(): number | undefined;
+    fallback: FloatingPlacement;
+    onLayout(layout: FloatingLayout): void;
+}
+/**
+ * One measurement. The boundary is the visual viewport (layout viewport without visualViewport) minus the
+ * positioner's CSS scroll-margin (gap + safe area, so env() stays in the style layer). The arrow padding is
+ * the content's corner radius. A transformed/filtered ancestor offsets fixed boxes: the difference between
+ * where the box is and the translate that was applied is subtracted.
+ */
+export declare function measureFloatingLayout(options: FloatingTrackOptions): FloatingLayout | null;
+/** Frames to wait for the layer nodes to mount before giving up (about one second). */
+export declare const FLOATING_WAIT_FRAMES = 60;
+/**
+ * Track while open: one rAF-coalesced measurement per scroll (any scroller, captured), window or visual
+ * viewport resize, and anchor/positioner ResizeObserver change. The returned cleanup removes every listener,
+ * disconnects the observer and cancels the pending frame.
+ */
+export declare function trackFloatingLayout(doc: Document, options: FloatingTrackOptions): () => void;

package/dist/popup/index.d.ts

@@ -0,0 +1,2 @@
+export { popupMachine, createPopupProps, connectPopup, resolvePopupPlacement, getPopupAccessibleName, getPopupDataAttrs, getPopupPartProps, } from "./popup.js";
+export type { PopupPlacement, QwPopupProps, QwPopupApi } from "./popup.js";

package/dist/popup/index.js

@@ -0,0 +1,2 @@
+import { a as getPopupPartProps, i as getPopupDataAttrs, n as createPopupProps, o as popupMachine, r as getPopupAccessibleName, s as resolvePopupPlacement, t as connectPopup } from "../popup-z5d8IYCt.js";
+export { connectPopup, createPopupProps, getPopupAccessibleName, getPopupDataAttrs, getPopupPartProps, popupMachine, resolvePopupPlacement };

package/dist/popup/popup.d.ts

@@ -0,0 +1,60 @@
+import { connect, type Api, type Props as ZagDialogProps, type Service, type machine } from "@zag-js/dialog";
+import { type ModalRenderRuntime } from "../modal-render-runtime.js";
+/** Popup 的 Core machine；共享声明归属与焦点策略，按物理节点准入关闭监听。 */
+export declare const popupMachine: typeof machine;
+export type PopupPlacement = "bottom" | "top";
+/**
+ * QwPopupProps — 贴边弹出层的跨框架行为输入。
+ * modal / role / Esc 是内部无障碍政策，不作为业务开关。
+ */
+export interface QwPopupProps {
+    /** 唯一 id；也是 modal-registry 的键。不传时由适配层提供。 */
+    id?: string;
+    /** 受控开关。传入即受控。 */
+    open?: boolean;
+    /** 非受控初值，默认 false。 */
+    defaultOpen?: boolean;
+    /** 贴底或贴顶，默认 bottom。未知值回退 bottom。 */
+    placement?: PopupPlacement;
+    /** 点击遮罩关闭，默认 true。 */
+    closeOnMaskClick?: boolean;
+    /** 打开时禁止 body 滚动，默认 true。 */
+    disableBodyScroll?: boolean;
+    /** 为 false 时不加安全区留白，默认 true。 */
+    safeArea?: boolean;
+    /** 可访问名称的首选。trim 后为空视为缺省。 */
+    title?: string;
+    /** 无标题时的可访问名称。trim 后为空视为缺省。 */
+    ariaLabel?: string;
+    /** 关闭按钮的可访问名称，默认「关闭」。组件不按语言翻译。 */
+    closeLabel?: string;
+    /** 关闭后的焦点目标。只透传给 zag finalFocusEl，不解析 selector。 */
+    returnFocus?: () => HTMLElement | null;
+    /** 每次开合请求通知一次。被拒的打开通知一次 false。 */
+    onOpenChange?: (open: boolean) => void;
+}
+/** 同 Zag dialog Api。setOpen 与 getTriggerProps 已包装单层模态拒绝。 */
+export type QwPopupApi = Api;
+type PopupNormalize = Parameters<typeof connect>[1];
+/** 未知 placement 回退 bottom。 */
+export declare function resolvePopupPlacement(value: unknown): PopupPlacement;
+/** 可访问名称：title → ariaLabel → 「弹出层」。空白视为缺省。 */
+export declare function getPopupAccessibleName(props: Pick<QwPopupProps, "title" | "ariaLabel">): string;
+/** positioner 与 content 共用的 data 属性。safeArea 缺省为开启。 */
+export declare function getPopupDataAttrs(props: Pick<QwPopupProps, "placement" | "safeArea">): Record<string, string | undefined>;
+/** header / body / footer 没有 Zag part，scope 与 part 由 Core 输出。 */
+export declare function getPopupPartProps(part: "header" | "body" | "footer"): {
+    "data-scope": "popup";
+    "data-part": "header" | "body" | "footer";
+};
+/** 把公开 props 转成 zag dialog context。受控 open:true 被拒时映射为关闭。 */
+export declare function createPopupProps(props?: QwPopupProps, runtime?: ModalRenderRuntime): Partial<ZagDialogProps>;
+/**
+ * 包装 zag connect。触发器 onClick 与 setOpen(true) 先查登记；
+ * 被拒时 onClick 调 preventDefault，让 zag 看到 defaultPrevented 后不发 TOGGLE。
+ * setOpen(true) 被拒则直接返回，不向 zag 发事件。
+ */
+export declare function connectPopup(service: Service, normalize: PopupNormalize, props?: QwPopupProps, runtime?: ModalRenderRuntime): QwPopupApi & {
+    getOriginProps(): ReturnType<PopupNormalize["element"]>;
+};
+export {};