haze-ui 1.22.0 → 1.24.0

package/dist/types/utils/floating.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentProps, CSSProperties, Dispatch, ReactNode, RefObject, SetStateAction } from 'react';
+import type { CollisionStrategy } from './collision';
 /** Lazy feature detection so tests can flip between native and fallback. */
 export declare function supportsNativePopover(): boolean;
 /**
@@ -7,6 +8,20 @@ export declare function supportsNativePopover(): boolean;
  * be trusted on its own.
  */
 export declare function supportsAnchorPositioning(): boolean;
+/**
+ * Fallback path: panel visually hidden while closed. Exported so tests
+ * can assert the (animated-delayed) hidden handover like any consumer.
+ */
+export declare const floatingHidden: import("@linaria/core").LinariaClassName;
+/**
+ * Animated panels fade in/out through `data-state` — opacity only.
+ * Transform is banned on floating panels: both JS-positioned tiers
+ * measure the panel's rect, and getBoundingClientRect includes
+ * transforms, so a translating/scaling panel would poison placement.
+ * `forwards` keeps a finished fade-out at opacity 0 until the hidden
+ * handover lands (a one-frame flash-back would otherwise show).
+ */
+export declare const floatingAnimated: import("@linaria/core").LinariaClassName;
 declare const anchoredPlacements: {
     readonly bottom: import("@linaria/core").LinariaClassName;
     readonly 'bottom-span': import("@linaria/core").LinariaClassName;
@@ -29,6 +44,19 @@ type UseFloatingOptions = {
     triggerRef: RefObject<HTMLElement | null>;
     /** The floating panel element. */
     panelRef: RefObject<HTMLElement | null>;
+    /**
+     * Fade the panel in/out via `data-state` (opacity only) and keep it
+     * visible until its exit animation settles, instead of hiding the
+     * instant `open` flips false. Enables `dataState`/`exited` below; in
+     * jsdom (no CSS durations) the exit settles within two frames, so
+     * tests observe the handover with waitFor.
+     */
+    animated?: boolean;
+    /**
+     * Collision knobs consumed by useFloatingPosition on the JS-positioned
+     * tiers (the tier-2 flip/shift and the tier-1 cross-axis nudge).
+     */
+    collision?: CollisionStrategy;
 };
 export type FloatingBehavior = {
     open: boolean;
@@ -44,6 +72,23 @@ export type FloatingBehavior = {
      * display:none element and is silently dropped (Chromium).
      */
     shown: boolean;
+    /**
+     * Panel lifecycle phase for CSS: 'open' while `open` is true (enter
+     * animation), 'closed' the moment it flips false (exit animation runs
+     * while the panel is still visible). `undefined` when not animated.
+     * Render as the panel's `data-state` attribute.
+     */
+    dataState: 'open' | 'closed' | undefined;
+    /**
+     * True when the panel is fully closed — nothing visible, nothing
+     * animating. Animated: false from the moment `open` flips true until
+     * the exit settles, then true again (and true before the first open).
+     * Non-animated: mirrors `!open`. Consumers that unmount panel content
+     * gate on `!open && exited`.
+     */
+    exited: boolean;
+    /** Collision strategy FloatingPanel forwards to useFloatingPosition. */
+    collision: CollisionStrategy | undefined;
     /** Unique CSS anchor name for this instance (anchored path). */
     anchorName: string;
     /** Inline style for the trigger: declares `anchor-name`. */
@@ -57,35 +102,60 @@ export type FloatingBehavior = {
         popover: 'auto' | undefined;
         style: CSSProperties | undefined;
     };
-    /** Positioning-skeleton entries for the panel's x-class array. */
+    /**
+     * Positioning-skeleton entries for the panel's x-class array. With
+     * `animated`, the fallback hidden class is only applied once the exit
+     * settled (`exited`), keeping the panel measurable/visible through its
+     * fade-out.
+     */
     panelClasses: (string | false)[];
     triggerRef: RefObject<HTMLElement | null>;
     panelRef: RefObject<HTMLElement | null>;
 };
-export declare function useFloating({ open, setOpen, triggerRef, panelRef, }: UseFloatingOptions): FloatingBehavior;
+export declare function useFloating({ open, setOpen, triggerRef, panelRef, animated, collision, }: UseFloatingOptions): FloatingBehavior;
 /** x-class entries placing the panel relative to the trigger, per tier. */
 export declare function floatingPlacementClasses(behavior: Pick<FloatingBehavior, 'native' | 'anchored'>, placement: FloatingPlacement): (string | false)[];
 /**
  * Place a fixed panel from the trigger's rect (tier 2). Centers compute
- * from the panel's own rect, so this needs layout — fine in real engines,
- * and unreachable in jsdom where the fallback tier renders instead.
+ * from the panel's own rect, so this needs the panel to be laid out —
+ * fine in real engines once shown, and unreachable in jsdom where the
+ * fallback tier renders instead.
  *
- * Viewport awareness: a placement that would push the panel past the
- * viewport edge flips to the opposite side when that side has room for
- * it (bottom↔top, left↔right — the secondary-axis alignment stays as
- * chosen); when neither side fits, the position is clamped into the
- * viewport instead. Exported for direct testing like
- * `supportsNativePopover` above.
+ * Collision handling: a placement that would push the panel past the
+ * (optionally padded) viewport edge flips to the opposite side when that
+ * side has room, slides along the cross axis, and finally clamps into
+ * view when neither side fits — all in computeFloatingPosition. With no
+ * `collision` the output is pixel-identical to the legacy inline math
+ * (the parity cases in collision.test.ts and the tier-2 regression
+ * cases in Popover.test.tsx guard this). Exported for direct testing
+ * like `supportsNativePopover` above.
  */
-export declare function placeFloatingPanel(panel: HTMLElement, trigger: HTMLElement, placement: FloatingPlacement): void;
+export declare function placeFloatingPanel(panel: HTMLElement, trigger: HTMLElement, placement: FloatingPlacement, collision?: CollisionStrategy): void;
 /**
- * Tier 2 positioning: place the panel under/over/beside the trigger and
- * re-place on scroll/resize while open. No-op on the anchored and
- * fallback tiers.
+ * JS-assisted positioning:
+ *
+ * - Tier 2 (popover API, no anchor positioning): place the panel from
+ *   the trigger's rect and re-place on scroll/resize while shown.
+ * - Tier 1 (anchored): `position-area` + `position-try-fallbacks` handle
+ *   the primary axis declaratively; the cross axis is measured here and
+ *   nudged back into the padded viewport via `translate`, re-measured on
+ *   scroll/resize. Collision padding applies to the cross axis only —
+ *   the primary-axis flip is the browser's and cannot see padding
+ *   (position-try has no padding concept), a documented limitation.
+ *
+ * Both tiers gate on actual visibility (`shown`), not `open`: child
+ * effects run before the behavior effect that calls showPopover(), and a
+ * native popover is `display: none` until then — placing on the `open`
+ * commit would measure a zero-size rect and mis-center/mis-align the
+ * panel on first open in real engines (jsdom's permissive mocks hide
+ * it). The extra render pass after the toggle event is the price for
+ * correct geometry.
  */
-export declare function useFloatingPosition({ behavior, placement, }: {
+export declare function useFloatingPosition({ behavior, placement, collision, }: {
     behavior: FloatingBehavior;
     placement: FloatingPlacement;
+    /** Collision knobs; defaults to the behavior's own strategy. */
+    collision?: CollisionStrategy;
 }): void;
 type FloatingPanelProps = {
     /** Behavior record produced by `useFloating` at the floating root. */
@@ -95,6 +165,11 @@ type FloatingPanelProps = {
      * consumer positions the panel itself, e.g. ContextMenu at the pointer.
      */
     placement?: FloatingPlacement;
+    /**
+     * Collision strategy for the JS-assisted tiers (tier-2 flip/shift,
+     * tier-1 cross-axis nudge); defaults to the behavior's own strategy.
+     */
+    collision?: CollisionStrategy;
     /** Consumer visual skin: border, background, shadow, padding. */
     visualClass?: string;
     className?: string;
@@ -104,9 +179,10 @@ type FloatingPanelProps = {
 } & Omit<ComponentProps<'div'>, 'className' | 'children' | 'style'>;
 /**
  * The panel element of a floating pair: applies the popover attribute,
- * the anchor custom property and the tier/placement classes, and runs the
- * tier-2 position effect. Everything else (id, role, handlers, ref) is
- * passed through to the underlying div.
+ * the anchor custom property and the tier/placement classes, mirrors the
+ * animated lifecycle as `data-state`, and runs the JS-assisted position
+ * effect. Everything else (id, role, handlers, ref) is passed through to
+ * the underlying div.
  */
-export declare function FloatingPanel({ behavior, placement, visualClass, className, style, children, ...rest }: FloatingPanelProps): import("react").JSX.Element;
+export declare function FloatingPanel({ behavior, placement, collision, visualClass, className, style, children, ...rest }: FloatingPanelProps): import("react").JSX.Element;
 export {};

package/dist/types/utils/focus-scope.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 焦点域 hook（Radix FocusScope 的简化版，headless：返回 ref 回调，
+ * 由消费方挂到容器元素上）。负责弹层的初始聚焦 / 焦点归还 / 可选困焦，
+ * 无 CSS 依赖，不进 src/lib/index.ts barrel。
+ */
+export type FocusScopeOptions = {
+    /**
+     * true=激活（挂载语义：记录归还目标、派发 hazefocusmount、自动聚焦、
+     * 可选困焦）；false=停用（卸载语义：派发 hazefocusunmount、归还焦点）。
+     * effect 依赖只有 enabled —— 其余选项经 optionsRef 读取最新值，
+     * 内联箭头函数 props 不会触发重新激活。
+     */
+    enabled: boolean;
+    /** Tab 循环锁定在容器内（document 级 Tab 拦截 + focusout 拉回），默认 false */
+    trapped?: boolean;
+    /** enabled 翻 true 时聚焦首个 tabbable（无则容器自身），默认 true */
+    autoFocus?: boolean;
+    /** enabled 翻 false 时归还焦点到激活前的元素，默认 true */
+    returnFocus?: boolean;
+    /** 挂载事件回调；在事件上 preventDefault 可阻止默认聚焦 */
+    onMountAutoFocus?: (event: Event) => void;
+    /** 卸载事件回调；在事件上 preventDefault 可阻止默认归还 */
+    onUnmountAutoFocus?: (event: Event) => void;
+};
+export declare function useFocusScope(options: FocusScopeOptions): (node: HTMLElement | null) => void;

package/dist/types/utils/focus.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 纯焦点工具：tabbable 元素查询与首个聚焦目标计算。
+ *
+ * 无 React、无 CSS 依赖，可在任意 DOM 环境（含 jsdom）直接复用。
+ * 与 floating.tsx 一样属于内部原语，不进 src/lib/index.ts barrel。
+ */
+/**
+ * Tab 序候选元素选择器。仅做结构性筛选；disabled / hidden /
+ * tabindex="-1" / 可见性等运行时状态由 isTabbable 二次过滤
+ * （选择器里的 :not([disabled]) 分支只覆盖各自的元素形态）。
+ */
+export declare const TABBABLE_SELECTOR: string;
+/** 元素是否在 Tab 序内（选择器命中 + 非 disabled + 非 hidden + 可见）。 */
+export declare function isTabbable(el: Element): el is HTMLElement;
+/** 容器内按 DOM 顺序排列的全部 tabbable 元素（不含容器自身）。 */
+export declare function getTabbables(container: ParentNode | null | undefined): HTMLElement[];
+/**
+ * 聚焦容器内第一个 tabbable 元素；无 tabbable 时聚焦容器自身
+ * （容器需 tabIndex=-1 才可编程聚焦，未显式设置时补设）。
+ * 返回是否聚焦成功 —— 以 activeElement 实际转移为准，兜住
+ * disabled / 脱离文档等 focus() 静默失效的场景。
+ */
+export declare function focusFirst(container: HTMLElement): boolean;

package/dist/types/utils/presence.d.ts

@@ -0,0 +1,22 @@
+import type { ReactElement, Ref } from 'react';
+/**
+ * Wait for `el`'s exit animation/transition to finish. Resolves immediately
+ * when no positive duration is declared. Returns `null` for an element
+ * outside the document (nothing visible to wait for), and the in-flight
+ * promise for a repeated call — settles are not re-entrant per element.
+ */
+export declare function whenExitSettles(el: HTMLElement): Promise<void> | null;
+type PresenceChildProps = {
+    'data-state'?: string;
+    ref?: Ref<HTMLElement>;
+};
+export type PresenceProps = {
+    /** While true the child is mounted with `data-state="open"`. */
+    present: boolean;
+    /** Single element child; receives `data-state` and a merged ref. */
+    children: ReactElement;
+    /** Called when the exit has settled and the child is about to unmount. */
+    onExited?: () => void;
+};
+export declare function Presence({ present, children, onExited }: PresenceProps): ReactElement<PresenceChildProps, string | import("react").JSXElementConstructor<any>> | null;
+export {};

package/dist/utils/collision.js

@@ -0,0 +1,73 @@
+//#region src/lib/utils/collision.ts
+function e(e) {
+	return typeof e == "number" ? {
+		top: e,
+		right: e,
+		bottom: e,
+		left: e
+	} : {
+		top: e?.top ?? 0,
+		right: e?.right ?? 0,
+		bottom: e?.bottom ?? 0,
+		left: e?.left ?? 0
+	};
+}
+function t(e, t, n) {
+	return Math.min(Math.max(e, t), Math.max(t, n));
+}
+var n = {
+	bottom: {
+		side: "bottom",
+		align: "start"
+	},
+	"bottom-span": {
+		side: "bottom",
+		align: "start"
+	},
+	"bottom-center": {
+		side: "bottom",
+		align: "center"
+	},
+	"bottom-end": {
+		side: "bottom",
+		align: "end"
+	},
+	top: {
+		side: "top",
+		align: "center"
+	}
+};
+function r({ trigger: e, panel: r, viewport: i, placement: a, gap: o, strategy: s }) {
+	let { flip: c, shift: l, padding: u } = s, d = {
+		top: u.top,
+		bottom: i.height - u.bottom,
+		left: u.left,
+		right: i.width - u.right
+	}, f = e.left + e.width / 2 - r.width / 2, p = e.top + e.height / 2 - r.height / 2, m = (t, n) => ({
+		top: t === "bottom" ? e.bottom + o.below : e.top - r.height - o.above,
+		left: n === "start" ? e.left : n === "end" ? e.right - r.width : f
+	}), h = (t) => ({
+		top: p,
+		left: t === "right" ? e.right + o.after : e.left - r.width - o.before
+	}), g = a === "left" || a === "right", { top: _, left: v } = g ? h(a) : m(n[a].side, n[a].align), y = g ? a : n[a].side;
+	if (g) {
+		let t = a === "right" ? v + r.width > d.right : v < d.left, n = a === "right" ? e.left - r.width - o.before >= d.left : e.right + r.width + o.after <= d.right;
+		if (c && t && n) {
+			let e = a === "right" ? "left" : "right";
+			({top: _, left: v} = h(e)), y = e;
+		}
+	} else {
+		let { side: t, align: i } = n[a], s = t === "bottom" ? _ + r.height > d.bottom : _ < d.top, l = t === "bottom" ? e.top - r.height - o.above >= d.top : e.bottom + r.height + o.below <= d.bottom;
+		if (c && s && l) {
+			let e = t === "bottom" ? "top" : "bottom";
+			({top: _, left: v} = m(e, i)), y = e;
+		}
+	}
+	return l && (g ? _ = t(_, d.top, d.bottom - r.height) : v = t(v, d.left, d.right - r.width)), g ? v = t(v, d.left, d.right - r.width) : _ = t(_, d.top, d.bottom - r.height), {
+		top: _,
+		left: v,
+		placement: y
+	};
+}
+//#endregion
+export { r as computeFloatingPosition, e as resolvePadding };