4-05 · 浮层体系（上）：三态状态机与全局浮层栈

const visible = ref(false);

function open() {
  visible.value = true;
}

function close() {
  visible.value = false;
}

export interface FloatingVisibilityOptions {
  modelValue?: MaybeRefOrGetter<boolean | undefined>;
  disabled?: MaybeRefOrGetter<boolean | undefined>;
  persistent?: MaybeRefOrGetter<boolean | undefined>;
  openDelay?: MaybeRefOrGetter<number | undefined>;
  closeDelay?: MaybeRefOrGetter<number | undefined>;
  beforeOpen?: (source: "internal" | "external") => void;
  beforeClose?: (source: "internal" | "external") => void;
  emitModelValue?: (value: boolean) => void;
  onOpen?: (source: "internal" | "external") => void;
  onClose?: (source: "internal" | "external") => void;
  immediateExternal?: MaybeRefOrGetter<boolean | undefined>;
  /**
   * 探测面板关闭动画是否仍在播放（仅在真实浏览器检测到 CSS transition/animation 时为 true）。
   * 用于在关闭动画未结束前忽略触发器的 toggle 请求，避免"开→关→又开"的时序错乱。
   */
  isLeaveAnimating?: () => boolean;
}

export function useFloatingVisibility(options: FloatingVisibilityOptions = {}) {
  const visible = ref(false);
  const rendered = ref(Boolean(toValue(options.modelValue)) || Boolean(toValue(options.persistent)));
  const isAnimating = ref(false);
  let openTimer: number | null = null;
  let closeTimer: number | null = null;

/**
 * 读取元素当前计算样式的动画总时长（transition 与 animation 中的最大值，单位毫秒）。
 * 只有真实浏览器把 CSS 规则应用到元素上时才会返回大于 0 的值；
 * jsdom 等无法应用样式表的环境恒返回 0。
 */
export function readFloatingAnimationDuration(element: HTMLElement | null): number {
  if (!element || typeof window === "undefined" || typeof window.getComputedStyle !== "function") {
    return 0;
  }

  const styles = window.getComputedStyle(element);
  const readMaxDuration = (raw: string | null | undefined) =>
    String(raw ?? "")
      .split(",")
      .reduce((max, part) => {
        const seconds = Number.parseFloat(part.trim());
        return Number.isFinite(seconds) && seconds > 0 ? Math.max(max, seconds * 1000) : max;
      }, 0);

  return Math.max(
    readMaxDuration(styles.transitionDuration),
    readMaxDuration(styles.animationDuration)
  );
}

  function setVisible(
    nextVisible: boolean,
    { emitModelValue = true, source = "internal" }: FloatingVisibilityChangeOptions = {}
  ) {
    clearTimers();

    if (nextVisible) {
      rendered.value = true;
      isAnimating.value = true;
    }

    if (visible.value === nextVisible) {
      isAnimating.value = false;
      return;
    }

    if (nextVisible) {
      options.beforeOpen?.(source);
    } else {
      options.beforeClose?.(source);
    }

    visible.value = nextVisible;

    if (emitModelValue) {
      options.emitModelValue?.(nextVisible);
    }

    if (nextVisible) {
      options.onOpen?.(source);
      return;
    }

    options.onClose?.(source);
  }

  function open(
    optionsOverride: FloatingVisibilityChangeOptions & { immediate?: boolean } = {}
  ) {
    if (toValue(options.disabled)) {
      return;
    }

    clearTimers();

    if (visible.value) {
      return;
    }

    const delay = optionsOverride.immediate ? 0 : (toValue(options.openDelay) ?? 0);

    if (delay > 0) {
      openTimer = typeof window !== "undefined"
        ? window.setTimeout(() => {
            setVisible(true, optionsOverride);
          }, delay)
        : null;
      return;
    }

    setVisible(true, optionsOverride);
  }

  function close(
    optionsOverride: FloatingVisibilityChangeOptions & { immediate?: boolean } = {}
  ) {
    clearTimers();

    const delay = optionsOverride.immediate ? 0 : (toValue(options.closeDelay) ?? 0);

    if (delay > 0) {
      closeTimer = typeof window !== "undefined"
        ? window.setTimeout(() => {
            setVisible(false, optionsOverride);
          }, delay)
        : null;
      return;
    }

    setVisible(false, optionsOverride);
  }

  function toggle(optionsOverride: FloatingVisibilityChangeOptions = {}) {
    // 关闭动画仍在播放时（真实浏览器下 after-leave 尚未触发）忽略触发器的 toggle 请求，
    // 防止"开→关→又开/又关"的双重状态切换；无动画环境（如 jsdom）行为保持不变。
    if (!visible.value && options.isLeaveAnimating?.()) {
      return;
    }

    if (visible.value) {
      close({
        ...optionsOverride,
        immediate: true
      });
      return;
    }

    open({
      ...optionsOverride,
      immediate: true
    });
  }

  function handleAfterLeave() {
    isAnimating.value = false;
    if (!toValue(options.persistent) && !visible.value) {
      rendered.value = false;
    }
  }

    if (!visible.value && options.isLeaveAnimating?.()) {
      return;
    }

    isLeaveAnimating: () => readFloatingAnimationDuration(contentRef.value) > 0,

  watch(
    () => toValue(options.modelValue),
    (value) => {
      if (value == null) {
        return;
      }

      if (value) {
        open({
          emitModelValue: false,
          source: "external",
          immediate: Boolean(toValue(options.immediateExternal))
        });
        return;
      }

      close({
        emitModelValue: false,
        source: "external",
        immediate: Boolean(toValue(options.immediateExternal))
      });
    },
    {
      immediate: true
    }
  );

  watch(
    () => toValue(options.persistent),
    (value) => {
      if (value) {
        rendered.value = true;
        return;
      }

      if (!visible.value) {
        rendered.value = false;
      }
    }
  );

  watch(
    () => toValue(options.disabled),
    (value) => {
      if (value && visible.value) {
        close({
          immediate: true
        });
      }
    }
  );

  return {
    visible,
    rendered,
    isAnimating,
    clearTimers,
    setVisible,
    open,
    close,
    toggle,
    handleAfterLeave
  };
}

  const contentRendered = computed(() => {
    if (callbacks.destroyStrategy === "content" && toValue(options.destroyOnClose)) {
      return visible.value;
    }

    return rendered.value;
  });

import { computed, onBeforeUnmount, ref, shallowRef } from "vue";
import type { ComputedRef, Ref } from "vue";

interface OverlayEntry {
  id: symbol;
  zIndex: Ref<number>;
  isTopMost: () => boolean;
  openLayer: () => void;
  closeLayer: () => void;
}

function createStack() {
  // 栈容器必须用 shallowRef：深层 ref 会把每个 entry 代理化并自动解包其 zIndex，
  // 导致 getTopEntry 比较时读到 undefined。栈更新本就通过 notifyStackChange
  // 整体重赋值来触发响应，深层响应式从未被依赖。
  const stack = shallowRef<Set<OverlayEntry>>(new Set());
  const zIndexCounter = ref(2000);

  function notifyStackChange() {
    stack.value = new Set(stack.value);
  }

  function getTopEntry(): OverlayEntry | undefined {
    let top: OverlayEntry | undefined;
    let maxZ = -Infinity;

    for (const entry of stack.value) {
      if (entry.zIndex.value > maxZ) {
        maxZ = entry.zIndex.value;
        top = entry;
      }
    }

    return top;
  }

  function createOverlayEntry(): OverlayEntry {
    const id = Symbol("overlay");
    let opened = false;
    const disposed = false;

    const entry: OverlayEntry = {
      id,
      zIndex: ref(-1),
      isTopMost: () => {
        if (disposed || !opened) return false;
        const top = getTopEntry();
        return top?.id === id;
      },
      openLayer: () => {
        if (disposed) return;
        entry.zIndex.value = ++zIndexCounter.value;
        if (!opened) {
          stack.value.add(entry);
          opened = true;
        }
        notifyStackChange();
      },
      closeLayer: () => {
        if (disposed || !opened) return;
        opened = false;
        entry.zIndex.value = -1;
        if (stack.value.delete(entry)) {
          notifyStackChange();
        }
      }
    };

    return entry;
  }

  return { createOverlayEntry };
}

const globalStack = createStack();

export interface OverlayStackEntry {
  zIndex: ComputedRef<number>;
  isTopMost: () => boolean;
  openLayer: () => void;
  closeLayer: () => void;
}

export function useOverlayStack(): OverlayStackEntry {
  const entry = globalStack.createOverlayEntry();

  onBeforeUnmount(() => {
    entry.closeLayer();
  });

  return {
    // entry.zIndex 是 ref，computed 必须显式读取 .value 建立依赖，
    // 否则依赖集为空、首次读取后永久缓存（重开浮层拿到旧 z 值、预读恒 -1）。
    zIndex: computed(() => entry.zIndex.value),
    isTopMost: entry.isTopMost,
    openLayer: entry.openLayer,
    closeLayer: entry.closeLayer
  };
}

// getTopEntry 里的比较，修复前的实态推演：
if (entry.zIndex.value > maxZ) {   // undefined > -Infinity → false

// 修复前（HEAD 版本，dc9ca28，2026-09-14）：
interface OverlayEntry {
  id: symbol;
  zIndex: number;              // 裸 number
  // ...
}
const stack = ref<Set<OverlayEntry>>(new Set());   // 深层 ref
// getTopEntry: if (entry.zIndex > maxZ)           // 直接比数字
// openLayer:   entry.zIndex = ++zIndexCounter.value
// 对外: zIndex: computed(() => entry.zIndex)       // 依赖收集即失效

// 修复后（当前工作区实态）：
interface OverlayEntry {
  id: symbol;
  zIndex: Ref<number>;         // Ref 化
  // ...
}
const stack = shallowRef<Set<OverlayEntry>>(new Set());  // 浅层
// getTopEntry: if (entry.zIndex.value > maxZ)     // 显式 .value
// openLayer:   entry.zIndex.value = ++zIndexCounter.value
// 对外: zIndex: computed(() => entry.zIndex.value) // 显式解包建立依赖

const { visible, rendered, open, close, toggle, clearTimers, handleAfterLeave } =
  useFloatingVisibility({
    modelValue: () => props.modelValue,
    disabled: () => props.disabled,
    persistent: () => props.persistent,
    openDelay: () => props.showAfter ?? props.openDelay,
    closeDelay: () => props.hideAfter ?? props.closeDelay,
    immediateExternal: true,
    isLeaveAnimating: () => readFloatingAnimationDuration(contentRef.value) > 0,
    beforeOpen: () => {
      emit("before-show");
    },
    beforeClose: () => {
      emit("before-hide");
    },
    emitModelValue: (value) => {
      emit("update:modelValue", value);
    },
    onOpen: () => {
      emit("open");
      openLayer();
    },
    onClose: () => {
      emit("close");
      closeLayer();
      stopAutoUpdate();
    }
  });

  <teleport :to="props.appendTo" :disabled="!props.teleported">
    <transition
      :name="props.transition"
      @after-enter="emit('afterEnter')"
      @after-leave="emit('afterLeave')"
    >
      <div
        v-if="props.rendered"
        v-show="props.visible"
        :id="props.id"
        ref="contentElementRef"
        role="tooltip"
        :aria-hidden="!props.visible"
        :aria-label="props.ariaLabel"
        :data-placement="props.actualPlacement"
        :class="[
          `${ns.base.value}__content`,
          `${ns.base.value}__content--${props.effect}`,
          `${ns.base.value}__content--${placementSide}`,
          props.popperClass
        ]"
        :style="[props.floatingStyle, maxWidthStyle, props.popperStyle]"
        @mouseenter="emit('requestOpen', $event)"
        @mouseleave="emit('requestClose', $event)"
        @keydown="emit('keydown', $event)"
        @focusout="emit('focusout', $event)"
      >
        <span
          v-if="props.showArrow"
          ref="arrowElementRef"
          :class="['xy-popper__arrow', `${ns.base.value}__arrow`]"
          :style="props.arrowStyle"
        />
        <slot name="content">
          <!-- eslint-disable-next-line vue/no-v-html -->
          <span v-if="props.rawContent" v-html="props.content" />
          <template v-else>{{ props.content }}</template>
        </slot>
      </div>
    </transition>
  </teleport>

  function handleEscape(event: KeyboardEvent) {
    if (!props.closeOnEsc || isManualTrigger.value || !visible.value || !isTopMost()) {
      return;
    }

    event.preventDefault();
    hide();
  }

useDismissibleLayer({
  enabled: () => visible.value && !isManualTrigger.value,
  refs: [triggerRef, contentRef],
  closeOnEscape: props.closeOnEsc,
  closeOnOutside: closeOnOutsideEnabled,
  isTopMost: () => isTopMost(),
  onDismiss: () => {
    hide();
  }
});

.xy-dialog-fade-enter-active,
.xy-dialog-fade-leave-active {
  transition: opacity var(--xy-transition-duration-fast) var(--xy-transition-timing);
}

.xy-dialog-fade-enter-active .xy-dialog__panel,
.xy-dialog-fade-leave-active .xy-dialog__panel {
  transition:
    transform var(--xy-transition-duration-fast) var(--xy-transition-timing),
    opacity var(--xy-transition-duration-fast) var(--xy-transition-timing);
}

.xy-dialog-fade-enter-from,
.xy-dialog-fade-leave-to {
  opacity: 0;
}

.xy-dialog-fade-enter-from .xy-dialog__panel,
.xy-dialog-fade-leave-to .xy-dialog__panel {
  transform: translateY(-10px) scale(0.985);
  opacity: 0;
}

.xy-fade-enter-active,
.xy-fade-leave-active {
  transition:
    opacity var(--xy-transition-duration-fast) var(--xy-transition-timing),
    transform var(--xy-transition-duration-fast) var(--xy-transition-timing);
}

.xy-fade-enter-from,
.xy-fade-leave-to {
  opacity: 0;
  transform: translateY(4px);
}

  const showModal = computed(() => {
    return Boolean(toValue(options.modal) && visible.value);
  });

  const zIndex = computed(() => {
    const base = toValue(options.zIndex);
    if (base != null) return base;
    return overlayStack.zIndex.value;
  });

  watch(
    visible,
    (value) => {
      if (value) {
        overlayStack.openLayer();
        return;
      }

      overlayStack.closeLayer();
    },
    { immediate: true }
  );

import { computed, ref } from "vue";

const seed = ref(0);

export function useZIndex() {
  const zIndex = computed(() => 2000);

  const next = () => {
    seed.value += 1;
    return zIndex.value + seed.value;
  };

  return {
    current: computed(() => zIndex.value + seed.value),
    next
  };
}

describe("useOverlayStack zIndex 响应式", () => {
  it("打开前预读 -1，openLayer 后 computed 立即更新", () => {
    const { entry } = mountWithOverlayStack();

    expect(entry.zIndex.value).toBe(-1);

    entry.openLayer();
    expect(entry.zIndex.value).toBeGreaterThan(0);

    entry.closeLayer();
    expect(entry.zIndex.value).toBe(-1);
  });

  it("close 后 reopen 拿到更大的新 zIndex（computed 不残留旧缓存）", () => {
    const { entry } = mountWithOverlayStack();

    entry.openLayer();
    const firstZIndex = entry.zIndex.value;

    entry.closeLayer();
    entry.openLayer();

    expect(entry.zIndex.value).toBeGreaterThan(firstZIndex);
  });

  it("isTopMost 语义保持：只有已打开且位于栈顶的 entry 为 true", () => {
    const first = mountWithOverlayStack();
    const second = mountWithOverlayStack();

    // 未打开的 entry 恒为 false
    expect(first.entry.isTopMost()).toBe(false);
    expect(second.entry.isTopMost()).toBe(false);

    first.entry.openLayer();
    expect(first.entry.isTopMost()).toBe(true);

    second.entry.openLayer();
    expect(first.entry.isTopMost()).toBe(false);
    expect(second.entry.isTopMost()).toBe(true);

    second.entry.closeLayer();
    expect(first.entry.isTopMost()).toBe(true);
    expect(second.entry.isTopMost()).toBe(false);

    first.entry.closeLayer();
    expect(first.entry.isTopMost()).toBe(false);
  });
});

describe("useFloatingVisibility isLeaveAnimating 守卫", () => {
  it("关闭动画期间（isLeaveAnimating 为 true）toggle 不应重新打开面板", () => {
    const floating = useFloatingVisibility({
      isLeaveAnimating: () => true
    });

    floating.open();
    expect(floating.visible.value).toBe(true);

    // 模拟真实浏览器：关闭后离开动画尚未结束
    floating.close();
    expect(floating.visible.value).toBe(false);

    floating.toggle();
    expect(floating.visible.value).toBe(false);
  });

  it("无动画环境（isLeaveAnimating 未提供/返回 false）toggle 行为保持不变", () => {
    const floating = useFloatingVisibility({
      isLeaveAnimating: () => false
    });

    floating.open();
    expect(floating.visible.value).toBe(true);
    floating.close();
    expect(floating.visible.value).toBe(false);

    floating.toggle();
    expect(floating.visible.value).toBe(true);

    floating.toggle();
    expect(floating.visible.value).toBe(false);
  });
});