@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/side-sheet/SideSheet.svelte

@@ -1,356 +1,255 @@
 <!--
-  SideSheet — 侧边滑出浮层。see specs/components/feedback/SideSheet.spec.md
-  从视口四边（left/right/top/bottom）滑入的浮层容器，承载次要任务流/详情/筛选/表单。
-  与 Modal 同构复用浮层基建：portal 到 body（或 getContainer）脱离父层叠上下文，
-  role=dialog（mask 时 aria-modal），useFocusTrap 焦点捕获+归还（仅 mask）、
-  useDismiss Esc 关闭、mask 时 useScrollLock 锁背景滚动，
-  堆叠 z-index 复用 modal/z-stack 模块级计数器（与 Modal 统一层栈，后开者在上）。
-  滑入过渡：CSS transform/opacity（token 时长缓动），reduced-motion / motionDisabled 退化为即时显隐。
-  受控 open（红线 #1）：不回写 open，仅经 onOpenChange({open, reason}) 通知。
-  mask=true 模态：遮罩 + focus trap + scroll lock；mask=false 非模态：无遮罩、不锁滚动、
-  不抢焦点（不启用 focus trap），outsideClosable 时点击外部关闭。
-  lazyMount：首开前惰性挂载；destroyOnClose：关闭即卸载内容（出场过渡结束后），重开重建。
+  SideSheet — 滑动侧边栏。严格镜像 Semi Design（semi-foundation/sideSheet + semi-ui/sideSheet）。
+  从视口四边（left/right/top/bottom）滑入的浮层容器，承载二级操作页面 / 详情 / 表单 / 筛选。
+
+  DOM 结构对齐 Semi：
+    .cd-sidesheet.cd-sidesheet-{placement}[-horizontal][-rtl][-popup][-fixed][-hidden]  ← wrapper（Portal 内）
+      ├ .cd-sidesheet-mask[.动画类]                        ← 遮罩（aria-hidden；mask=true）
+      └ .cd-sidesheet-inner.cd-sidesheet-inner-wrap.cd-sidesheet-size-{size}[.动画类]  ← role=dialog tabindex=-1
+          └ .cd-sidesheet-content
+              ├ .cd-sidesheet-header（role=heading aria-level=1）
+              │    ├ .cd-sidesheet-title（有 title）
+              │    └ IconButton.cd-sidesheet-close（closable）
+              ├ .cd-sidesheet-body
+              └ .cd-sidesheet-footer（footer 时）
+
+  API 严格镜像 Semi 名：visible（受控不回写）/ onCancel / afterVisibleChange / placement /
+    size(small|medium|large，默认 small) / width(默认 448) / height(默认 400) / title / footer /
+    closable / closeIcon / closeOnEsc(默认 false) / mask / maskClosable / disableScroll /
+    keepDOM / getPopupContainer / zIndex(默认 1000) / motion / style / bodyStyle / headerStyle /
+    maskStyle / className。ReactNode→Snippet、className→class（本库 Svelte 惯例）。
+
+  进出场动画对齐 Semi CSSAnimation：mask 淡入淡出 + inner 按 placement 滑入滑出；JS 状态机
+    以 animationState(enter/leave) 驱动动画类，动画结束（animationend）后收起 displayNone 卸载。
+    motion=false 或 prefers-reduced-motion 退化为即时显隐。
+
+  浮层基建：Portal 到 getPopupContainer()/body 脱离父层叠上下文；mask=true 默认锁 body 滚动
+    （disableScroll）；closeOnEsc 时 window keydown 监听 Esc 关闭；堆叠 z-index 复用 modal/z-stack
+    模块级计数器（zIndex prop 优先），与 Modal 统一层栈、后开者在上。
 -->
 <script lang="ts">
   import type { Snippet } from 'svelte';
-  import {
-    useId,
-    useFocusTrap,
-    useDismiss,
-    useScrollLock,
-    useInertBackground,
-  } from '@chenzy-design/core';
+  import { untrack } from 'svelte';
+  import { useId, useScrollLock } from '@chenzy-design/core';
+  import { IconClose } from '@chenzy-design/icons';
+  import { IconButton } from '../iconbutton/index.js';
   import { useLocale } from '../locale-provider/index.js';
+  import { getGlobalPopupContainer } from '../config-provider/index.js';
   import { acquireZIndex } from '../modal/z-stack.js';
 
   type Placement = 'left' | 'right' | 'top' | 'bottom';
-  type Size = 'small' | 'default' | 'large';
-  type Reason = 'esc' | 'mask' | 'outside' | 'closeButton' | 'programmatic';
+  type Size = 'small' | 'medium' | 'large';
 
   interface Props {
-    open?: boolean;
+    /** 面板是否可见（受控；受控时不回写）。对齐 Semi visible。 */
+    visible?: boolean;
+    /** 滑出位置，支持 top/bottom/left/right。对齐 Semi placement。 */
     placement?: Placement;
+    /** 尺寸：small(448)/medium(684)/large(920)，仅 left/right 生效。对齐 Semi size。 */
     size?: Size;
+    /** 宽度，位置为 left/right 时生效。对齐 Semi width（默认 448）。 */
     width?: number | string;
+    /** 高度，位置为 top/bottom 时生效。对齐 Semi height（默认 400）。 */
     height?: number | string;
+    /** 标题（string）。对齐 Semi title。 */
     title?: string;
-    /** 自定义标题区，覆盖 title prop。 */
+    /** 自定义标题区（Snippet），覆盖 title。对齐 Semi title(ReactNode)。 */
     titleSnippet?: Snippet;
-    /** Header 右侧额外操作（关闭按钮之前）。 */
-    headerExtra?: Snippet;
-    /** 自定义关闭图标。 */
-    closeIcon?: Snippet;
+    /** 是否显示右上角关闭按钮。对齐 Semi closable。 */
+    closable?: boolean;
+    /** 自定义关闭图标（Snippet）。传 null 不显示图标。对齐 Semi closeIcon。 */
+    closeIcon?: Snippet | null;
+    /** 是否显示遮罩；false 时允许操作外部区域。对齐 Semi mask。 */
     mask?: boolean;
+    /** 点击遮罩是否关闭。对齐 Semi maskClosable。 */
     maskClosable?: boolean;
-    /** mask=false 时点击面板外部是否关闭。默认 false。 */
-    outsideClosable?: boolean;
+    /** Esc 是否关闭。对齐 Semi closeOnEsc（默认 false）。 */
     closeOnEsc?: boolean;
-    closable?: boolean;
-    /** 首次打开前是否惰性挂载内容。默认 true。 */
-    lazyMount?: boolean;
-    /** keepDOM=false 等价于 lazyMount=true 的反义（保留 DOM）。lazyMount 优先。 */
+    /** 关闭后是否保留内部组件不销毁。对齐 Semi keepDOM。 */
     keepDOM?: boolean;
-    /** 关闭后是否销毁内部内容（释放资源）。默认 false。 */
-    destroyOnClose?: boolean;
-    /** Portal 挂载容器，缺省 document.body。 */
-    getContainer?: () => HTMLElement | null;
-    zIndex?: number;
-    /** 强制不锁背景滚动（即便 mask=true）。 */
-    disableScrollLock?: boolean;
-    /** 打开时给 body 加 overflow:hidden 防背景滚动。默认 true。false 等价于 disableScrollLock=true。 */
+    /** 渲染在 body 层时是否禁止 body 滚动（overflow:hidden）。对齐 Semi disableScroll。 */
     disableScroll?: boolean;
-    /** 关闭后焦点返回目标，缺省为打开时的触发元素。 */
-    returnFocusTo?: HTMLElement | (() => HTMLElement | null) | null;
-    /** 关闭进出动效（独立于 reduced-motion）。 */
-    motionDisabled?: boolean;
-    /** 是否启用动画过渡。false 等价于 motionDisabled=true。默认 true。 */
+    /** 指定父级 DOM，弹层渲染至该 DOM。对齐 Semi getPopupContainer。 */
+    getPopupContainer?: () => HTMLElement | null;
+    /** 弹层 z-index。对齐 Semi zIndex（默认 1000）。 */
+    zIndex?: number;
+    /** 是否允许动画。对齐 Semi motion。 */
     motion?: boolean;
-    /** Header 区域 style 字符串。 */
-    headerStyle?: string;
-    /** 内容区域 style 字符串。 */
+    /** 面板根内联样式。对齐 Semi style。 */
+    style?: string;
+    /** 内容区域内联样式。对齐 Semi bodyStyle。 */
     bodyStyle?: string;
-    /** 遮罩 style 字符串。 */
+    /** Header 区域内联样式。对齐 Semi headerStyle。 */
+    headerStyle?: string;
+    /** 遮罩内联样式。对齐 Semi maskStyle。 */
     maskStyle?: string;
-    /** Footer 操作区；提供 close() 以便按钮关闭面板。未提供不渲染。 */
+    /** 底部区域（Snippet），提供 close() 关闭面板。对齐 Semi footer(ReactNode)。 */
     footer?: Snippet<[{ close: () => void }]> | null;
+    /** 主内容区（可滚动）。对齐 Semi children。 */
     children?: Snippet;
-    /** 无可见标题时的 aria-label 兜底。 */
+    /** 无可见标题时的 aria-label。对齐 Semi aria-label。 */
     ariaLabel?: string;
+    /** 根元素自定义类名。对齐 Semi className。 */
     class?: string;
-    bodyClass?: string;
-    maskClass?: string;
-    /** 显隐意图变化（受控，需外部回写 open）。 */
-    onOpenChange?: (e: { open: boolean; reason: Reason }) => void;
-    /** 进入动效结束、内容完全可见后触发。 */
-    onAfterOpen?: () => void;
-    /** 退出动效结束、DOM 卸载（如适用）后触发。 */
-    onAfterClose?: () => void;
-    /** 动画结束后（入场或出场）触发，isVisible 为当前可见状态。 */
+    /** 面板展示/隐藏动画结束触发。对齐 Semi afterVisibleChange。 */
     afterVisibleChange?: (isVisible: boolean) => void;
-    /** 用户主动取消（Esc/遮罩/外部/关闭按钮）的语义快捷事件。 */
-    onCancel?: (e: { reason: Reason }) => void;
+    /** 取消面板时的回调。对齐 Semi onCancel。 */
+    onCancel?: (e: MouseEvent | KeyboardEvent) => void;
   }
 
   let {
-    open,
+    visible,
     placement = 'right',
-    size = 'default',
+    size = 'small',
     width,
     height,
     title,
     titleSnippet,
-    headerExtra,
+    closable = true,
     closeIcon,
     mask = true,
     maskClosable = true,
-    outsideClosable = false,
-    closeOnEsc = true,
-    closable = true,
-    lazyMount = true,
-    keepDOM,
-    destroyOnClose = false,
-    getContainer,
-    zIndex,
-    disableScrollLock = false,
+    closeOnEsc = false,
+    keepDOM = false,
     disableScroll = true,
-    returnFocusTo,
-    motionDisabled = false,
+    getPopupContainer,
+    zIndex = 1000,
     motion = true,
-    headerStyle,
+    style,
     bodyStyle,
+    headerStyle,
     maskStyle,
     footer,
     children,
     ariaLabel,
     class: className,
-    bodyClass,
-    maskClass,
-    onOpenChange,
-    onAfterOpen,
-    onAfterClose,
     afterVisibleChange,
     onCancel,
   }: Props = $props();
 
   const loc = useLocale();
   const titleId = useId('cd-sidesheet-title');
+  const globalPopupContainer = getGlobalPopupContainer();
 
-  // --- 受控 open (红线 #1)：不无条件回写 open，仅经 onOpenChange/onCancel 通知 ---
-  const isControlled = $derived(open !== undefined);
+  // 受控 visible（红线 #1）：不无条件回写，仅 onCancel 通知。
+  const isControlled = $derived(visible !== undefined);
   let innerOpen = $state(false);
-  const isOpen = $derived(isControlled ? !!open : innerOpen);
+  const isOpen = $derived(isControlled ? !!visible : innerOpen);
 
   const hasTitle = $derived(Boolean(titleSnippet) || Boolean(title));
-  const isHorizontal = $derived(placement === 'left' || placement === 'right');
+  const isVertical = $derived(placement === 'left' || placement === 'right');
+  const isHorizontal = $derived(placement === 'top' || placement === 'bottom');
 
-  const panelCls = $derived(
-    ['cd-sidesheet__panel', `cd-sidesheet__panel--${placement}`, className]
-      .filter(Boolean)
-      .join(' '),
+  // 尺寸解析（对齐 Semi）：left/right 用 width（缺省走 size class）；top/bottom 用 height（缺省 448）。
+  // Semi：sheetHeight = isHorizontal ? (height || 400) : '100%'；宽度经 size class 或 width 内联。
+  const widthPx = $derived(
+    width === undefined ? undefined : typeof width === 'number' ? `${width}px` : width,
   );
-
-  // --- 尺寸解析 (红线 #2 纯函数派生)：width/height 显式优先于 size 预设 token ---
-  const sizeToken = $derived(
-    size === 'small'
-      ? isHorizontal
-        ? 'var(--cd-sidesheet-width-small)'
-        : 'var(--cd-sidesheet-height-small)'
-      : size === 'large'
-        ? isHorizontal
-          ? 'var(--cd-sidesheet-width-large)'
-          : 'var(--cd-sidesheet-height-large)'
-        : isHorizontal
-          ? 'var(--cd-sidesheet-width)'
-          : 'var(--cd-sidesheet-height)',
+  const heightPx = $derived(
+    height === undefined ? undefined : typeof height === 'number' ? `${height}px` : height,
   );
+  const sheetHeight = $derived(isHorizontal ? (heightPx ?? '400px') : '100%');
+  // 仅 left/right 时把 width 作为内联宽（Semi：isVertical 时才设 width）。
+  const innerWidth = $derived(isVertical ? widthPx : undefined);
 
-  const explicit = $derived(isHorizontal ? width : height);
+  // getPopupContainer 指向非 body 时 popup 模式（wrapper position:static，mask/inner absolute）。
+  const container = $derived(getPopupContainer ?? undefined);
+  const isPopup = $derived(typeof container === 'function' && container() != null);
 
-  const sizeValue = $derived(
-    explicit === undefined
-      ? sizeToken
-      : typeof explicit === 'number'
-        ? `${explicit}px`
-        : explicit,
-  );
+  const rtl = $derived(loc().direction === 'rtl');
 
-  const panelStyle = $derived(
-    isHorizontal ? `inline-size: ${sizeValue}` : `block-size: ${sizeValue}`,
-  );
+  // —— 进出场动画状态机（对齐 Semi CSSAnimation）——
+  // animationState：enter（入场）/ leave（出场）。displayNone：动画结束后卸载/隐藏内容。
+  // 初值：受控看 visible，非受控起始为关（!innerOpen 即 true）；untrack 表明仅取初次快照。
+  let displayNone = $state(untrack(() => (visible === undefined ? true : !visible)));
 
-  let rootEl = $state<HTMLElement | null>(null);
-
-  // 出场过渡时长：从 CSS 读取 token（reduced-motion 下为 0）；motionDisabled/motion=false 强制 0。
-  function motionDurationMs(): number {
-    if (motionDisabled || !motion) return 0;
-    if (typeof window === 'undefined' || !rootEl) return 0;
-    const raw = getComputedStyle(rootEl)
-      .getPropertyValue('--cd-sidesheet-motion-duration')
-      .trim();
-    if (!raw) return 0;
-    if (raw.endsWith('ms')) return parseFloat(raw) || 0;
-    if (raw.endsWith('s')) return (parseFloat(raw) || 0) * 1000;
-    return parseFloat(raw) || 0;
-  }
-
-  // --- lazyMount / destroyOnClose / 出场过渡 ---
-  // lazyMount=true（默认）：首开前不挂载；keepDOM=true 显式禁用惰性。
-  const lazy = $derived(keepDOM === true ? false : lazyMount);
-  let hasBeenOpened = $state(false);
-  let exiting = $state(false);
-  let entered = $state(false);
-
-  // 单一 open 边沿副作用 (红线 #3)：仅依赖 isOpen，内部不读所写状态（hasBeenOpened/
-  // entered/exiting 只写不在依赖图触发自身重入），避免重入循环。
-  // entered 驱动 --open，入场下一帧置 true 触发位移过渡；动效时长从 CSS 读取（非响应式）。
+  function motionEnabled(): boolean {
+    if (!motion) return false;
+    if (typeof window === 'undefined') return true;
+    return !window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+  }
+
+  // isOpen 边沿：打开→立即显示并入场；关闭→出场，动画结束（或无动画）后 displayNone。
   $effect(() => {
     const opening = isOpen;
-    let raf = 0;
-    let closeTimer: ReturnType<typeof setTimeout> | undefined;
-    let openTimer: ReturnType<typeof setTimeout> | undefined;
     if (opening) {
-      hasBeenOpened = true;
-      exiting = false;
-      if (motionDisabled || !motion) {
-        entered = true;
-        onAfterOpen?.();
-        afterVisibleChange?.(true);
-      } else {
-        // 下一帧再切到开启态，确保起始（贴边收起）态先绘制再过渡。
-        // motionDurationMs() 读 rootEl，必须在 raf 回调（非响应式作用域）内调用，
-        // 否则 open 分支把 rootEl 纳入依赖、与挂载形成回环（effect_update_depth_exceeded）。
-        raf = requestAnimationFrame(() => {
-          raf = requestAnimationFrame(() => {
-            entered = true;
-            const ms = motionDurationMs();
-            openTimer = setTimeout(() => {
-              onAfterOpen?.();
-              afterVisibleChange?.(true);
-            }, ms);
-          });
-        });
+      displayNone = false;
+      if (!motionEnabled()) {
+        // 无动画：下一微任务通知可见（DOM 已挂载）。
+        queueMicrotask(() => afterVisibleChange?.(true));
       }
-    } else {
-      entered = false;
-      if (hasBeenOpened) {
-        const ms = (motionDisabled || !motion) ? 0 : motionDurationMs();
-        closeTimer = setTimeout(() => {
-          if (destroyOnClose) hasBeenOpened = false;
-          exiting = false;
-          onAfterClose?.();
-          afterVisibleChange?.(false);
-        }, ms);
-        if (destroyOnClose) exiting = true;
+    } else if (!displayNone) {
+      if (!motionEnabled()) {
+        displayNone = true;
+        queueMicrotask(() => afterVisibleChange?.(false));
       }
+      // 有动画：等 inner/mask animationend 再置 displayNone（onAnimationEnd）。
     }
-    return () => {
-      if (raf) cancelAnimationFrame(raf);
-      if (closeTimer) clearTimeout(closeTimer);
-      if (openTimer) clearTimeout(openTimer);
-    };
   });
 
-  // 渲染条件：lazy 且从未打开 → 不渲染（关闭态零成本）；
-  // destroyOnClose → 仅开/出场期间；否则首开后常驻（仅切换显隐）。
+  // 动画结束回调：出场结束收起 displayNone 卸载；入场结束通知可见。
+  function onAnimationEnd() {
+    if (!isOpen) {
+      if (!displayNone) {
+        displayNone = true;
+        afterVisibleChange?.(false);
+      }
+    } else {
+      afterVisibleChange?.(true);
+    }
+  }
+
+  // 渲染条件（对齐 Semi shouldRender）：可见 或 keepDOM 或（有动画且出场未结束）。
   const shouldRender = $derived(
-    destroyOnClose
-      ? isOpen || exiting
-      : lazy
-        ? isOpen || hasBeenOpened
-        : true,
+    isOpen || keepDOM || (motion && !displayNone),
   );
 
-  function emitClose(reason: Reason) {
+  // —— 关闭编排 ——
+  function emitCancel(e: MouseEvent | KeyboardEvent) {
     if (!isControlled) innerOpen = false;
-    onOpenChange?.({ open: false, reason });
-    if (reason !== 'programmatic') onCancel?.({ reason });
+    onCancel?.(e);
   }
 
-  // footer snippet 暴露的 close()：语义为程序化关闭。
+  // footer snippet 暴露的 close()：合成一个 click 语义事件传给 onCancel。
   function close() {
-    emitClose('programmatic');
+    if (!isControlled) innerOpen = false;
+    onCancel?.(new MouseEvent('click'));
   }
 
+  let mouseDownOnMask = false;
+  function onMaskMouseDown(e: MouseEvent) {
+    mouseDownOnMask = e.target === e.currentTarget;
+  }
   function onMaskClick(e: MouseEvent) {
-    if (mask && maskClosable && e.target === e.currentTarget) {
-      emitClose('mask');
+    if (maskClosable && e.target === e.currentTarget && mouseDownOnMask) {
+      emitCancel(e);
     }
+    mouseDownOnMask = false;
   }
 
-  // --- 浮层命令式编排 (红线 #3)：open 且面板就绪时，
-  //     mask 时 activate focus-trap（捕获/归还焦点）、加 scroll-lock；
-  //     绑 dismiss（Esc + 非模态外部点击）；cleanup 里逐一释放。 ---
-  let panelEl = $state<HTMLElement | null>(null);
-  let triggerEl: HTMLElement | null = null;
-
-  function resolveReturnFocus(): HTMLElement | null {
-    if (typeof returnFocusTo === 'function') return returnFocusTo();
-    if (returnFocusTo) return returnFocusTo;
-    return triggerEl;
-  }
-
+  // —— Esc 关闭（对齐 Semi window keydown 监听）——
   $effect(() => {
-    if (!isOpen || !panelEl) return;
-    const el = panelEl;
-
-    // 记录触发元素以便关闭归还焦点（mask=false 不抢焦点，故仅 mask 时记录）。
-    triggerEl =
-      typeof document !== 'undefined'
-        ? (document.activeElement as HTMLElement | null)
-        : null;
-
-    // focus trap 仅 mask=true 启用；mask=false 允许焦点离开（非模态）。
-    const trap = mask ? useFocusTrap(el) : null;
-    trap?.activate();
-
-    // scroll lock 仅 mask=true 且未 disableScrollLock，且 disableScroll=true（默认）。
-    const releaseScroll = (mask && !disableScrollLock && disableScroll) ? useScrollLock() : () => {};
-
-    // 模态（mask=true）时背景内容对 SR/键盘 inert+aria-hidden（spec §6）；
-    // 以 portal 根 rootEl 为锚隐藏其兄弟。非模态不抢占背景，跳过。
-    const releaseInert = mask && rootEl ? useInertBackground(rootEl) : () => {};
-
-    // dismiss：Esc（closeOnEsc）+ 非模态外部点击（outsideClosable）。
-    const wantOutside = !mask && outsideClosable;
-    let undismiss = () => {};
-    if (closeOnEsc || wantOutside) {
-      undismiss = useDismiss(el, {
-        onDismiss: (r) => emitClose(r === 'esc' ? 'esc' : 'outside'),
-        escape: closeOnEsc,
-        outsideClick: wantOutside,
-      });
-    }
-
-    return () => {
-      undismiss();
-      releaseInert();
-      releaseScroll();
-      if (trap) {
-        // 归还焦点：默认触发元素 / returnFocusTo。trap.deactivate 默认归还到
-        // 记录的 previouslyFocused（即触发元素）；若显式指定 returnFocusTo 则覆盖。
-        trap.deactivate();
-        const target = resolveReturnFocus();
-        if (target && target !== triggerEl) target.focus();
+    if (!isOpen || !closeOnEsc || typeof window === 'undefined') return;
+    function handleKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape' || e.keyCode === 27) {
+        e.stopPropagation();
+        emitCancel(e);
       }
-      triggerEl = null;
-    };
+    }
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
   });
 
-  // disableScroll：mask=false 时 useScrollLock 不生效，手动给 body 加 overflow:hidden。
+  // —— 背景滚动锁（对齐 Semi beforeShow disabledBodyScroll）——
+  // 仅默认渲染在 body（无 getPopupContainer）且 disableScroll 时锁；对齐 Semi。
   $effect(() => {
-    if (!isOpen || !disableScroll || mask || typeof document === 'undefined') return;
-    const prev = document.body.style.overflow;
-    document.body.style.overflow = 'hidden';
-    return () => {
-      document.body.style.overflow = prev;
-    };
+    if (!isOpen || !disableScroll || isPopup || typeof document === 'undefined') return;
+    const release = useScrollLock();
+    return release;
   });
 
-  // --- 堆叠 z-index (红线 #3)：每次打开向 modal/z-stack 计数器申请一层，关闭回收。
-  //     与 Modal、命令式 modal.confirm 共享同一计数器，多层叠放后开者在上。
-  //     zIndex prop 作为 CSS var 基准（栈内自动递增叠加）。 ---
+  // —— 堆叠 z-index：zIndex prop 优先，否则模块计数器分配 ——
   let stackZ = $state<number | undefined>(undefined);
-
   $effect(() => {
     if (!isOpen) return;
     const { zIndex: z, release } = acquireZIndex();
@@ -360,25 +259,12 @@
       release();
     };
   });
+  const effectiveZ = $derived(stackZ ?? zIndex);
 
-  const rootStyle = $derived(
-    [
-      stackZ !== undefined ? `--cd-sidesheet-z:${stackZ}` : undefined,
-      zIndex !== undefined && stackZ === undefined
-        ? `--cd-sidesheet-z:${zIndex}`
-        : undefined,
-    ]
-      .filter(Boolean)
-      .join('; ') || undefined,
-  );
-
-  // --- portal action (红线 #3)：命令式 appendChild 到 getContainer()/body，
-  //     脱离父 DOM 层叠上下文；destroy 时 removeChild 归还/清理。 ---
+  // —— portal（红线 #3）：命令式挂到 getPopupContainer()/body，脱离父层叠上下文 ——
   function portal(node: HTMLElement) {
-    if (typeof document === 'undefined') {
-      return { destroy() {} };
-    }
-    const target = getContainer?.() ?? document.body;
+    if (typeof document === 'undefined') return { destroy() {} };
+    const target = container?.() ?? globalPopupContainer?.() ?? document.body;
     target.appendChild(node);
     return {
       destroy() {
@@ -387,273 +273,428 @@
     };
   }
 
-  const bodyCls = $derived(
-    ['cd-sidesheet__body', bodyClass].filter(Boolean).join(' '),
+  // wrapper class（对齐 Semi classList）。
+  const wrapperCls = $derived(
+    [
+      'cd-sidesheet',
+      `cd-sidesheet-${placement}`,
+      isHorizontal && 'cd-sidesheet-horizontal',
+      isPopup && 'cd-sidesheet-popup',
+      rtl && 'cd-sidesheet-rtl',
+      !mask && 'cd-sidesheet-fixed',
+      !mask && `cd-sidesheet-size-${size}`,
+      keepDOM && displayNone && 'cd-sidesheet-hidden',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  // inner class（对齐 Semi -inner -inner-wrap -size-{size} + 动画类）。
+  const animate = $derived(motion);
+  const innerAnimCls = $derived(
+    !animate
+      ? ''
+      : isOpen
+        ? `cd-sidesheet-animation-content_show_${placement}`
+        : `cd-sidesheet-animation-content_hide_${placement}`,
+  );
+  const maskAnimCls = $derived(
+    !animate ? '' : isOpen ? 'cd-sidesheet-animation-mask_show' : 'cd-sidesheet-animation-mask_hide',
+  );
+
+  const innerCls = $derived(
+    ['cd-sidesheet-inner', 'cd-sidesheet-inner-wrap', `cd-sidesheet-size-${size}`, innerAnimCls]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  // inner 内联尺寸样式（对齐 Semi getDialogElement）：width（mask=false 时 100%，宽度在 wrapper）、height。
+  const innerStyle = $derived(
+    [
+      style,
+      innerWidth !== undefined ? `width: ${mask ? innerWidth : '100%'}` : undefined,
+      isHorizontal ? `height: ${sheetHeight}` : undefined,
+    ]
+      .filter(Boolean)
+      .join('; ') || undefined,
   );
-  const maskCls = $derived(
-    ['cd-sidesheet__mask', maskClass].filter(Boolean).join(' '),
+
+  // wrapper 内联样式：z-index；popup 时 position:static；mask=false 且 left/right 时宽度在 wrapper。
+  const wrapperStyle = $derived(
+    [
+      `z-index: ${effectiveZ}`,
+      isPopup ? 'position: static' : undefined,
+      !mask && innerWidth !== undefined ? `width: ${innerWidth}` : undefined,
+    ]
+      .filter(Boolean)
+      .join('; '),
   );
 </script>
 
 {#if shouldRender}
-  <!-- use:portal 命令式挂载到 getContainer()/body，脱离父层叠上下文。
-       cd-sidesheet--open 由 isOpen && entered 驱动 transform/opacity 过渡。 -->
-  <div
-    bind:this={rootEl}
-    class="cd-sidesheet cd-sidesheet--{placement}"
-    class:cd-sidesheet--open={isOpen && entered}
-    class:cd-sidesheet--no-mask={!mask}
-    class:cd-sidesheet--no-motion={motionDisabled || !motion}
-    style={rootStyle}
-    use:portal
-  >
+  <!-- use:portal 命令式挂载到 getPopupContainer()/body，脱离父层叠上下文。 -->
+  <div class={wrapperCls} style={wrapperStyle} use:portal>
     {#if mask}
-      <!-- 遮罩 role=presentation：点击关闭为鼠标增强，键盘等价为 Esc -->
-      <div class={maskCls} style={maskStyle} onclick={onMaskClick} role="presentation"></div>
+      <!-- 遮罩 aria-hidden；点击关闭为鼠标增强（键盘等价 Esc）。 -->
+      <div
+        aria-hidden="true"
+        class="cd-sidesheet-mask {maskAnimCls}"
+        style={maskStyle}
+        onmousedown={maskClosable ? onMaskMouseDown : undefined}
+        onclick={maskClosable ? onMaskClick : undefined}
+        onanimationend={onAnimationEnd}
+      ></div>
     {/if}
     <div
-      class={panelCls}
-      bind:this={panelEl}
+      class={innerCls}
       role="dialog"
+      tabindex="-1"
       aria-modal={mask ? 'true' : undefined}
       aria-labelledby={hasTitle ? titleId : undefined}
       aria-label={hasTitle ? undefined : ariaLabel}
-      style={panelStyle}
+      style={innerStyle}
+      onanimationend={onAnimationEnd}
     >
-      {#if hasTitle || closable || headerExtra}
-        <header class="cd-sidesheet__header" style={headerStyle}>
-          {#if hasTitle}
-            <h2 id={titleId} class="cd-sidesheet__title">
-              {#if titleSnippet}
-                {@render titleSnippet()}
-              {:else}
-                {title}
-              {/if}
-            </h2>
-          {:else}
-            <span></span>
-          {/if}
-          <div class="cd-sidesheet__header-actions">
-            {#if headerExtra}
-              {@render headerExtra()}
+      <div class="cd-sidesheet-content">
+        {#if hasTitle || closable}
+          <div class="cd-sidesheet-header" role="heading" aria-level="1" style={headerStyle}>
+            {#if hasTitle}
+              <div id={titleId} class="cd-sidesheet-title">
+                {#if titleSnippet}
+                  {@render titleSnippet()}
+                {:else}
+                  {title}
+                {/if}
+              </div>
             {/if}
             {#if closable}
-              <button
-                type="button"
-                class="cd-sidesheet__close"
-                aria-label={loc().t('SideSheet.closeAriaLabel')}
-                onclick={() => emitClose('closeButton')}
+              <IconButton
+                class="cd-sidesheet-close"
+                type="tertiary"
+                theme="borderless"
+                size="small"
+                ariaLabel={loc().t('SideSheet.closeAriaLabel')}
+                onclick={emitCancel}
               >
-                {#if closeIcon}
-                  {@render closeIcon()}
-                {:else}
-                  <svg
-                    width="16"
-                    height="16"
-                    viewBox="0 0 16 16"
-                    fill="none"
-                    aria-hidden="true"
-                  >
-                    <path
-                      d="M3 3l10 10M13 3L3 13"
-                      stroke="currentColor"
-                      stroke-width="1.5"
-                      stroke-linecap="round"
-                    />
-                  </svg>
-                {/if}
-              </button>
+                {#snippet icon()}
+                  {#if closeIcon}
+                    {@render closeIcon()}
+                  {:else}
+                    <IconClose />
+                  {/if}
+                {/snippet}
+              </IconButton>
             {/if}
           </div>
-        </header>
-      {/if}
+        {/if}
 
-      <div class={bodyCls} style={bodyStyle}>
-        {@render children?.()}
-      </div>
+        <div class="cd-sidesheet-body" style={bodyStyle}>
+          {@render children?.()}
+        </div>
 
-      {#if footer}
-        <footer class="cd-sidesheet__footer">
-          {@render footer({ close })}
-        </footer>
-      {/if}
+        {#if footer}
+          <div class="cd-sidesheet-footer">
+            {@render footer({ close })}
+          </div>
+        {/if}
+      </div>
     </div>
   </div>
 {/if}
 
 <style>
+  /* 严格镜像 Semi semi-foundation/sideSheet/sideSheet.scss。变量 → --cd-*-side-sheet-* 对齐层。 */
   .cd-sidesheet {
     position: fixed;
-    inset: 0;
-    z-index: var(--cd-sidesheet-z);
+    top: 0;
+    left: 0;
+    height: 100%;
+    margin: var(--cd-spacing-side-sheet-margin);
+    color: var(--cd-color-side-sheet-main-text);
+    font-size: var(--cd-font-size-regular, 14px);
   }
-  /* mask=false 时容器不拦截指针，仅面板可交互（协作式非模态） */
-  .cd-sidesheet--no-mask {
-    pointer-events: none;
-  }
-  .cd-sidesheet--no-mask .cd-sidesheet__panel {
-    pointer-events: auto;
+  .cd-sidesheet-inner:focus,
+  .cd-sidesheet-content:focus {
+    outline: none;
   }
-  .cd-sidesheet__mask {
+  .cd-sidesheet-inner-wrap {
     position: absolute;
-    inset: 0;
-    background: var(--cd-sidesheet-mask-bg);
-    pointer-events: auto;
-    opacity: 0;
-    transition: opacity var(--cd-sidesheet-motion-duration)
-      var(--cd-motion-ease-standard, ease);
-  }
-  .cd-sidesheet--open .cd-sidesheet__mask {
-    opacity: 1;
   }
-  .cd-sidesheet__panel {
-    position: absolute;
-    box-sizing: border-box;
-    display: flex;
-    flex-direction: column;
-    overflow: hidden;
-    background: var(--cd-sidesheet-bg);
-    color: var(--cd-sidesheet-color);
-    box-shadow: var(--cd-sidesheet-shadow);
-    transition:
-      transform var(--cd-sidesheet-motion-duration)
-        var(--cd-motion-ease-standard, ease),
-      opacity var(--cd-sidesheet-motion-duration)
-        var(--cd-motion-ease-standard, ease);
-    will-change: transform, opacity;
-    opacity: 0;
-  }
-  /* 朝向内容侧圆角：仅贴边对侧 */
-  .cd-sidesheet__panel--right {
-    inset-block: 0;
-    inset-inline-end: 0;
-    block-size: 100%;
-    max-inline-size: 100vw;
-    transform: translateX(100%);
-    border-start-start-radius: var(--cd-sidesheet-radius);
-    border-end-start-radius: var(--cd-sidesheet-radius);
-  }
-  .cd-sidesheet__panel--left {
-    inset-block: 0;
-    inset-inline-start: 0;
-    block-size: 100%;
-    max-inline-size: 100vw;
-    transform: translateX(-100%);
-    border-start-end-radius: var(--cd-sidesheet-radius);
-    border-end-end-radius: var(--cd-sidesheet-radius);
-  }
-  .cd-sidesheet__panel--top {
-    inset-inline: 0;
-    inset-block-start: 0;
-    inline-size: 100%;
-    max-block-size: 100vh;
-    transform: translateY(-100%);
-    border-end-start-radius: var(--cd-sidesheet-radius);
-    border-end-end-radius: var(--cd-sidesheet-radius);
-  }
-  .cd-sidesheet__panel--bottom {
-    inset-inline: 0;
-    inset-block-end: 0;
-    inline-size: 100%;
-    max-block-size: 100vh;
-    transform: translateY(100%);
-    border-start-start-radius: var(--cd-sidesheet-radius);
-    border-start-end-radius: var(--cd-sidesheet-radius);
-  }
-  /* RTL：left/right 贴边随书写方向镜像，translateX 方向需翻转 */
-  :global([dir='rtl']) .cd-sidesheet__panel--right {
-    transform: translateX(-100%);
-  }
-  :global([dir='rtl']) .cd-sidesheet__panel--left {
-    transform: translateX(100%);
-  }
-  .cd-sidesheet--open .cd-sidesheet__panel {
-    transform: translateX(0) translateY(0);
-    opacity: 1;
+
+  /* —— 四方向贴边（对齐 Semi -left/-right/-top/-bottom）—— */
+  .cd-sidesheet-left,
+  .cd-sidesheet-right {
+    top: 0;
+    width: 0%;
+    height: 100%;
   }
-  /* 窄视口近铺满 */
-  @media (max-width: 480px) {
-    .cd-sidesheet__panel--left,
-    .cd-sidesheet__panel--right {
-      inline-size: 100vw !important;
-    }
-    .cd-sidesheet__panel--top,
-    .cd-sidesheet__panel--bottom {
-      block-size: 100vh !important;
-    }
+  .cd-sidesheet-left .cd-sidesheet-inner-wrap,
+  .cd-sidesheet-right .cd-sidesheet-inner-wrap {
+    height: 100%;
+  }
+  .cd-sidesheet-left.cd-sidesheet,
+  .cd-sidesheet-right.cd-sidesheet {
+    width: 100%;
+  }
+  .cd-sidesheet-right {
+    right: 0;
+  }
+  .cd-sidesheet-right .cd-sidesheet-inner-wrap {
+    right: 0;
+  }
+  .cd-sidesheet-top,
+  .cd-sidesheet-bottom {
+    left: 0;
+    width: 100%;
+    height: 0%;
+  }
+  .cd-sidesheet-top .cd-sidesheet-inner-wrap,
+  .cd-sidesheet-bottom .cd-sidesheet-inner-wrap {
+    width: 100%;
   }
-  .cd-sidesheet__header {
+  .cd-sidesheet-top.cd-sidesheet,
+  .cd-sidesheet-bottom.cd-sidesheet {
+    height: 100%;
+  }
+  .cd-sidesheet-top {
+    top: 0;
+  }
+  .cd-sidesheet-bottom {
+    bottom: 0;
+  }
+  .cd-sidesheet-bottom .cd-sidesheet-inner-wrap {
+    bottom: 0;
+  }
+
+  /* —— title（对齐 Semi -title）—— */
+  .cd-sidesheet-title {
+    flex: 1 0 auto;
+    margin: var(--cd-spacing-side-sheet-title-margin);
+    color: var(--cd-color-side-sheet-main-text);
+    font-weight: var(--cd-font-side-sheet-title-fontweight);
+    font-size: var(--cd-font-side-sheet-title-fontsize);
+    line-height: 1.5;
+    text-align: left;
+  }
+
+  /* —— inner（对齐 Semi -inner）—— */
+  .cd-sidesheet-inner {
+    z-index: 1;
+    overflow: auto;
+    background-color: var(--cd-color-side-sheet-bg);
+    backdrop-filter: var(--cd-filter-side-sheet-bg);
+    border: 0;
+  }
+
+  /* —— header（对齐 Semi -header）—— */
+  .cd-sidesheet-header {
     display: flex;
-    align-items: center;
-    justify-content: space-between;
-    gap: var(--cd-spacing-base-tight, 12px);
-    padding: var(--cd-sidesheet-header-padding);
-    border-block-end: 1px solid var(--cd-sidesheet-border);
-  }
-  .cd-sidesheet__title {
-    margin: 0;
-    overflow: hidden;
-    color: var(--cd-sidesheet-title-color);
-    font-size: var(--cd-sidesheet-title-size);
-    font-weight: 600;
-    line-height: 1.4;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-  }
-  .cd-sidesheet__header-actions {
-    display: inline-flex;
-    flex-shrink: 0;
-    align-items: center;
-    gap: var(--cd-spacing-tight, 8px);
-  }
-  .cd-sidesheet__close {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    inline-size: 28px;
-    block-size: 28px;
-    padding: 0;
-    border: none;
-    border-radius: var(--cd-border-radius-medium, 4px);
-    background: transparent;
-    color: var(--cd-sidesheet-close-color);
-    cursor: pointer;
-  }
-  .cd-sidesheet__close:hover {
-    background: var(--cd-sidesheet-close-hover-bg);
-    color: var(--cd-sidesheet-close-color-hover);
-  }
-  .cd-sidesheet__close:focus-visible {
-    outline: none;
-    box-shadow: var(--cd-focus-ring);
+    align-items: flex-start;
+    padding: var(--cd-spacing-side-sheet-header-padding);
+    padding-bottom: var(--cd-spacing-side-sheet-header-padding-bottom);
+    border-bottom: var(--cd-width-side-sheet-header-border-bottom) solid
+      var(--cd-color-side-sheet-header-border-bottom);
   }
-  .cd-sidesheet__body {
+
+  /* —— body（对齐 Semi -body）—— */
+  .cd-sidesheet-body {
     flex: 1;
     overflow: auto;
-    padding: var(--cd-sidesheet-padding);
-    color: var(--cd-sidesheet-color);
+    padding: var(--cd-spacing-side-sheet-body-paddingy) var(--cd-spacing-side-sheet-body-paddingx);
+  }
+
+  /* —— size（对齐 Semi -size-small/medium/large）—— */
+  .cd-sidesheet-size-small {
+    width: var(--cd-width-side-sheet-size-small);
+  }
+  .cd-sidesheet-size-medium {
+    width: var(--cd-width-side-sheet-size-medium);
+  }
+  .cd-sidesheet-size-large {
+    width: var(--cd-width-side-sheet-size-large);
+  }
+  .cd-sidesheet-size-small.cd-sidesheet {
+    width: var(--cd-width-side-sheet-size-small);
+  }
+  .cd-sidesheet-size-medium.cd-sidesheet {
+    width: var(--cd-width-side-sheet-size-medium);
+  }
+  .cd-sidesheet-size-large.cd-sidesheet {
+    width: var(--cd-width-side-sheet-size-large);
   }
-  .cd-sidesheet__footer {
-    position: sticky;
-    inset-block-end: 0;
+
+  /* —— content（对齐 Semi -content）—— */
+  .cd-sidesheet-content {
     display: flex;
-    flex-shrink: 0;
-    justify-content: flex-end;
-    gap: var(--cd-spacing-tight, 8px);
-    padding: var(--cd-sidesheet-footer-padding);
-    background: var(--cd-sidesheet-bg);
-    border-block-start: 1px solid var(--cd-sidesheet-border);
+    flex-direction: column;
+    box-sizing: border-box;
+    height: 100%;
+    overflow: hidden;
+  }
+
+  /* —— mask（对齐 Semi -mask）—— */
+  .cd-sidesheet-mask {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background-color: var(--cd-color-side-sheet-mask-bg);
+    backdrop-filter: var(--cd-filter-side-sheet-mask-bg);
+    opacity: 1;
+  }
+
+  /* —— footer（对齐 Semi -footer）—— */
+  .cd-sidesheet-footer {
+    padding: var(--cd-spacing-side-sheet-footer-padding);
   }
 
-  /* reduced-motion / motionDisabled：禁用位移过渡，立即显隐 */
-  .cd-sidesheet--no-motion .cd-sidesheet__panel,
-  .cd-sidesheet--no-motion .cd-sidesheet__mask {
-    transition: none;
+  /* —— fixed（mask=false；对齐 Semi -fixed，阴影 + 贴边定位）—— */
+  .cd-sidesheet-fixed .cd-sidesheet-inner {
+    box-shadow: var(--cd-shadow-elevated);
   }
+  .cd-sidesheet-fixed.cd-sidesheet-left {
+    left: 0;
+  }
+  .cd-sidesheet-fixed.cd-sidesheet-left .cd-sidesheet-inner {
+    left: 0;
+  }
+  .cd-sidesheet-fixed.cd-sidesheet-right {
+    left: auto;
+  }
+  .cd-sidesheet-fixed.cd-sidesheet-right .cd-sidesheet-inner {
+    right: 0;
+  }
+  .cd-sidesheet-fixed.cd-sidesheet-top,
+  .cd-sidesheet-fixed.cd-sidesheet-bottom {
+    height: auto;
+  }
+  .cd-sidesheet-fixed.cd-sidesheet-bottom {
+    top: auto;
+  }
+  .cd-sidesheet-fixed.cd-sidesheet-bottom .cd-sidesheet-inner {
+    bottom: 0;
+  }
+
+  /* —— popup（getPopupContainer 非 body；对齐 Semi -popup）—— */
+  .cd-sidesheet.cd-sidesheet-popup {
+    position: absolute;
+  }
+
+  /* —— hidden（keepDOM 且关闭；对齐 Semi -hidden）—— */
+  .cd-sidesheet-hidden {
+    display: none;
+  }
+
+  /* —— RTL（对齐 Semi rtl.scss）—— */
+  .cd-sidesheet-rtl .cd-sidesheet-inner {
+    direction: rtl;
+  }
+  .cd-sidesheet-rtl .cd-sidesheet-title {
+    text-align: right;
+  }
+
+  /* —— 关闭按钮（Semi 用 IconButton；此处仅补 x-semi-prop 无关的对齐视觉，实际样式由 Button 承担）—— */
+
+  /* —— 进出场动画（对齐 Semi animation.scss keyframes + animation-content/mask 类）—— */
+  @keyframes cd-sidesheet-slideShow_top {
+    from { transform: translateY(-100%); }
+    to { transform: translateY(0); }
+  }
+  @keyframes cd-sidesheet-slideHide_top {
+    from { transform: translateY(0); }
+    to { transform: translateY(-100%); }
+  }
+  @keyframes cd-sidesheet-slideShow_bottom {
+    from { transform: translateY(100%); }
+    to { transform: translateY(0); }
+  }
+  @keyframes cd-sidesheet-slideHide_bottom {
+    from { transform: translateY(0); }
+    to { transform: translateY(100%); }
+  }
+  @keyframes cd-sidesheet-slideShow_left {
+    from { transform: translateX(-100%); }
+    to { transform: translateX(0); }
+  }
+  @keyframes cd-sidesheet-slideHide_left {
+    from { transform: translateX(0); }
+    to { transform: translateX(-100%); }
+  }
+  @keyframes cd-sidesheet-slideShow_right {
+    from { transform: translateX(100%); }
+    to { transform: translateX(0); }
+  }
+  @keyframes cd-sidesheet-slideHide_right {
+    from { transform: translateX(0); }
+    to { transform: translateX(100%); }
+  }
+  @keyframes cd-sidesheet-opacityShow {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+  @keyframes cd-sidesheet-opacityHide {
+    from { opacity: 1; }
+    to { opacity: 0; }
+  }
+
+  .cd-sidesheet-animation-content_show_top {
+    animation: cd-sidesheet-slideShow_top var(--cd-animation-duration-side-sheet-inner-show)
+      var(--cd-animation-function-side-sheet-inner-show) var(--cd-animation-delay-side-sheet-inner-show);
+    animation-fill-mode: forwards;
+  }
+  .cd-sidesheet-animation-content_hide_top {
+    animation: cd-sidesheet-slideHide_top var(--cd-animation-duration-side-sheet-inner-hide)
+      var(--cd-animation-function-side-sheet-inner-hide) var(--cd-animation-delay-side-sheet-inner-hide);
+    animation-fill-mode: forwards;
+  }
+  .cd-sidesheet-animation-content_show_bottom {
+    animation: cd-sidesheet-slideShow_bottom var(--cd-animation-duration-side-sheet-inner-show)
+      var(--cd-animation-function-side-sheet-inner-show) var(--cd-animation-delay-side-sheet-inner-show);
+    animation-fill-mode: forwards;
+  }
+  .cd-sidesheet-animation-content_hide_bottom {
+    animation: cd-sidesheet-slideHide_bottom var(--cd-animation-duration-side-sheet-inner-hide)
+      var(--cd-animation-function-side-sheet-inner-hide) var(--cd-animation-delay-side-sheet-inner-hide);
+    animation-fill-mode: forwards;
+  }
+  .cd-sidesheet-animation-content_show_left {
+    animation: cd-sidesheet-slideShow_left var(--cd-animation-duration-side-sheet-inner-show)
+      var(--cd-animation-function-side-sheet-inner-show) var(--cd-animation-delay-side-sheet-inner-show);
+    animation-fill-mode: forwards;
+  }
+  .cd-sidesheet-animation-content_hide_left {
+    animation: cd-sidesheet-slideHide_left var(--cd-animation-duration-side-sheet-inner-hide)
+      var(--cd-animation-function-side-sheet-inner-hide) var(--cd-animation-delay-side-sheet-inner-hide);
+    animation-fill-mode: forwards;
+  }
+  .cd-sidesheet-animation-content_show_right {
+    animation: cd-sidesheet-slideShow_right var(--cd-animation-duration-side-sheet-inner-show)
+      var(--cd-animation-function-side-sheet-inner-show) var(--cd-animation-delay-side-sheet-inner-show);
+    animation-fill-mode: forwards;
+  }
+  .cd-sidesheet-animation-content_hide_right {
+    animation: cd-sidesheet-slideHide_right var(--cd-animation-duration-side-sheet-inner-hide)
+      var(--cd-animation-function-side-sheet-inner-hide) var(--cd-animation-delay-side-sheet-inner-hide);
+    animation-fill-mode: forwards;
+  }
+  .cd-sidesheet-animation-mask_show {
+    animation: cd-sidesheet-opacityShow var(--cd-animation-duration-side-sheet-mask-show)
+      var(--cd-animation-function-side-sheet-mask-show) var(--cd-animation-delay-side-sheet-mask-show);
+    animation-fill-mode: forwards;
+  }
+  .cd-sidesheet-animation-mask_hide {
+    animation: cd-sidesheet-opacityHide var(--cd-animation-duration-side-sheet-mask-hide)
+      var(--cd-animation-function-side-sheet-mask-hide) var(--cd-animation-delay-side-sheet-mask-hide);
+    animation-fill-mode: forwards;
+  }
+
+  /* reduced-motion：禁用位移/淡入动画，立即显隐（motion=false 时 JS 已不加动画类） */
   @media (prefers-reduced-motion: reduce) {
-    .cd-sidesheet__panel,
-    .cd-sidesheet__mask {
-      transition: none;
+    .cd-sidesheet-inner,
+    .cd-sidesheet-mask {
+      animation: none !important;
     }
   }
 </style>