@astryxdesign/core 0.7.8 → 0.7.9-canary.07992bb

package/src/Layer/preserveAnimations.ts

@@ -11,245 +11,23 @@
  *
  * Taking an element out of rendering cancels every CSS animation and
  * transition of it and its subtree. When it returns, the browser creates the
- * animations again from the stylesheet, at their start, and the transitions
- * not at all; script-created animations are untouched. `preserveAnimations`
- * reads every animation's state first and, afterwards, gives each recreated
- * CSS animation that state and resumes each cancelled transition with a
- * script animation at the same point.
- *
- * The state is read generically, from what the platform exposes: every
- * accessor with a setter on the animation's and its effect's prototype
- * chains, every field of the effect's timing, and its keyframes. Only values
- * that differ from the recreated animation's are written, so a value the
- * stylesheet controls stays under its control. A few members are not plain
- * state and are handled in their own step (`ORDERED`); the rest need no
- * handling (`DERIVED`). What cannot be carried over is the Animation and
- * effect objects themselves: the old ones are idle, their `addEventListener`
- * listeners and `finished`/`ready` promises stay with them, and the browser
- * fires `animationcancel`/`transitioncancel` for them and `animationstart`
+ * animations again from the stylesheet, at their start. It starts no
+ * transition but one from `@starting-style`, and script-created animations
+ * are untouched. `preserveAnimations` reads every animation's state first.
+ * Afterwards it gives each recreated CSS animation that state, and resumes
+ * each cancelled transition with a script animation at the same point. Any
+ * other animation the return started is finished, unless it never ends
+ * (motion/carryAnimations.ts). The browser fires
+ * `animationcancel`/`transitioncancel` for the old ones and `animationstart`
  * for the new ones.
  */
 
-/**
- * Animation members written in a fixed order rather than generically: the
- * timeline before the range that is measured on it, the rate before the
- * time, and the start time (or, for a paused animation, the current time)
- * last, once the play state is set. `effect` is not
- * replaced, because a CSS animation whose effect script replaces leaves the
- * stylesheet's control; its state is copied onto the new effect instead.
- */
-const ORDERED = new Set([
-  'effect',
-  'timeline',
-  'rangeStart',
-  'rangeEnd',
-  'playbackRate',
-  'startTime',
-  'currentTime',
-]);
-
-type Writable = Record<string, unknown>;
-
-/** Every accessor with a setter on `object`'s prototype chain. */
-function writableAccessors(object: object): string[] {
-  const names = new Set<string>();
-  for (
-    let proto: object | null = Object.getPrototypeOf(object);
-    proto != null && proto !== Object.prototype;
-    proto = Object.getPrototypeOf(proto)
-  ) {
-    for (const [name, descriptor] of Object.entries(
-      Object.getOwnPropertyDescriptors(proto),
-    )) {
-      if (descriptor.set != null) {
-        names.add(name);
-      }
-    }
-  }
-  return [...names];
-}
-
-/**
- * A textual form of a value that is compared by content rather than by
- * identity: a CSS numeric value (as in a timeline range offset) through its
- * serialization, a plain object (a range) through its members. Anything else
- * is compared by identity (`null`).
- */
-function contentOf(value: unknown): string | null {
-  if (
-    typeof CSSNumericValue !== 'undefined' &&
-    value instanceof CSSNumericValue
-  ) {
-    return value.toString();
-  }
-  if (
-    value != null &&
-    typeof value === 'object' &&
-    Object.getPrototypeOf(value) === Object.prototype
-  ) {
-    return Object.entries(value)
-      .map(([key, inner]) => `${key}:${contentOf(inner) ?? String(inner)}`)
-      .join(';');
-  }
-  return null;
-}
-
-function differs(a: unknown, b: unknown): boolean {
-  if (a === b) {
-    return false;
-  }
-  const textA = contentOf(a);
-  return textA == null || textA !== contentOf(b);
-}
-
-interface Saved {
-  animation: Animation;
-  name: string;
-  target: Element | null;
-  pseudoElement: string | null;
-  values: Writable;
-  effectValues: Writable;
-  timing: EffectTiming | null;
-  keyframes: ComputedKeyframe[] | null;
-  playState: AnimationPlayState;
-  replaceState: AnimationReplaceState;
-}
-
-function save(animation: Animation): Saved {
-  const effect = animation.effect as KeyframeEffect | null;
-  const values: Writable = {};
-  for (const name of writableAccessors(animation)) {
-    values[name] = (animation as unknown as Writable)[name];
-  }
-  const effectValues: Writable = {};
-  if (effect != null) {
-    for (const name of writableAccessors(effect)) {
-      effectValues[name] = (effect as unknown as Writable)[name];
-    }
-  }
-  return {
-    animation,
-    name:
-      (animation as Animation & {animationName?: string}).animationName ?? '',
-    target: effect?.target ?? null,
-    pseudoElement: effect?.pseudoElement ?? null,
-    values,
-    effectValues,
-    timing: effect?.getTiming() ?? null,
-    keyframes: effect?.getKeyframes() ?? null,
-    playState: animation.playState,
-    replaceState: animation.replaceState,
-  };
-}
-
-function write(object: object, name: string, value: unknown): void {
-  (object as Writable)[name] = value;
-}
-
-/** Give `next` the effect state `saved` had: every writable member. */
-function restoreEffect(next: KeyframeEffect, saved: Saved): void {
-  for (const name of writableAccessors(next)) {
-    if (
-      name in saved.effectValues &&
-      differs(saved.effectValues[name], (next as unknown as Writable)[name])
-    ) {
-      write(next, name, saved.effectValues[name]);
-    }
-  }
-  if (saved.timing != null) {
-    const timing = next.getTiming() as unknown as Writable;
-    const changed: Writable = {};
-    for (const [field, value] of Object.entries(saved.timing)) {
-      if (differs(value, timing[field])) {
-        changed[field] = value;
-      }
-    }
-    if (Object.keys(changed).length > 0) {
-      next.updateTiming(changed);
-    }
-  }
-  if (
-    saved.keyframes != null &&
-    JSON.stringify(saved.keyframes) !== JSON.stringify(next.getKeyframes())
-  ) {
-    next.setKeyframes(saved.keyframes);
-  }
-}
-
-/** Give `next` the state `saved` had, member by member. */
-function restore(next: Animation, saved: Saved): void {
-  const effect = next.effect as KeyframeEffect | null;
-  if (effect != null) {
-    restoreEffect(effect, saved);
-  }
-  const current = next as unknown as Writable;
-  for (const name of ['timeline', 'rangeStart', 'rangeEnd']) {
-    if (name in saved.values && differs(saved.values[name], current[name])) {
-      write(next, name, saved.values[name]);
-    }
-  }
-  for (const name of writableAccessors(next)) {
-    if (
-      !ORDERED.has(name) &&
-      name in saved.values &&
-      differs(saved.values[name], current[name])
-    ) {
-      write(next, name, saved.values[name]);
-    }
-  }
-  if (saved.replaceState === 'persisted' && next.replaceState !== 'persisted') {
-    next.persist();
-  }
-  const rate = saved.values.playbackRate;
-  if (typeof rate === 'number' && rate !== next.playbackRate) {
-    next.playbackRate = rate;
-  }
-  if (saved.playState === 'paused' && next.playState !== 'paused') {
-    next.pause();
-  } else if (saved.playState !== 'paused' && next.playState === 'paused') {
-    next.play();
-  }
-  // A running animation is anchored to its timeline by its start time, which
-  // carries its current time on exactly. A paused one has none and keeps its
-  // current time. A finished one holds its end: finishing it again holds the
-  // same time, though its start time is then counted from now, since script
-  // cannot set a start time and a held time together.
-  const start = saved.values.startTime as CSSNumberish | null | undefined;
-  const time = saved.values.currentTime as CSSNumberish | null | undefined;
-  if (saved.playState === 'finished') {
-    next.finish();
-  } else if (start != null) {
-    next.startTime = start;
-  } else if (time != null) {
-    next.currentTime = time;
-  }
-}
-
-/** Resume a cancelled CSS transition with a script animation in its state. */
-function resumeTransition(saved: Saved): void {
-  if (saved.target == null || saved.keyframes == null) {
-    return;
-  }
-  const replacement = saved.target.animate(saved.keyframes, {
-    pseudoElement: saved.pseudoElement ?? undefined,
-  });
-  restore(replacement, saved);
-}
-
-function isTransition(animation: Animation): boolean {
-  return (
-    typeof CSSTransition !== 'undefined' && animation instanceof CSSTransition
-  );
-}
+import {restoreAnimations, saveAnimation} from '../motion/carryAnimations';
 
 /**
  * Run `reset`, which takes `root` out of rendering and back, and put every
  * CSS animation and transition of `root` and its subtree back in the state it
- * was in before. Recreated animations are matched to the ones they replace by
- * element, pseudo-element and name, in order, and then by name alone (an
- * effect script moved to another element or pseudo-element); a recreated
- * animation with no predecessor (an entry animation that had already played
- * and been dropped) is finished.
+ * was in before.
  */
 export function preserveAnimations(root: Element, reset: () => void): void {
   if (typeof root.getAnimations !== 'function') {
@@ -257,48 +35,7 @@ export function preserveAnimations(root: Element, reset: () => void): void {
     return;
   }
   const before = root.getAnimations({subtree: true});
-  const saved = before.map(save);
+  const saved = before.map(saveAnimation);
   reset();
-  const after = root.getAnimations({subtree: true});
-  const current = new Set(after);
-  const survivors = new Set(before);
-  const cancelled: Saved[] = [];
-  for (const state of saved) {
-    if (current.has(state.animation)) {
-      continue;
-    }
-    if (isTransition(state.animation)) {
-      resumeTransition(state);
-    } else {
-      cancelled.push(state);
-    }
-  }
-  const recreated = after.filter(animation => !survivors.has(animation));
-  const unmatched: Animation[] = [];
-  for (const animation of recreated) {
-    const effect = animation.effect as KeyframeEffect | null;
-    const name =
-      (animation as Animation & {animationName?: string}).animationName ?? '';
-    const index = cancelled.findIndex(
-      state =>
-        state.name === name &&
-        state.target === (effect?.target ?? null) &&
-        state.pseudoElement === (effect?.pseudoElement ?? null),
-    );
-    if (index === -1) {
-      unmatched.push(animation);
-    } else {
-      restore(animation, cancelled.splice(index, 1)[0]);
-    }
-  }
-  for (const animation of unmatched) {
-    const name =
-      (animation as Animation & {animationName?: string}).animationName ?? '';
-    const index = cancelled.findIndex(state => state.name === name);
-    if (index === -1) {
-      animation.finish();
-    } else {
-      restore(animation, cancelled.splice(index, 1)[0]);
-    }
-  }
+  restoreAnimations(root, saved, new Set(before));
 }

package/src/Layer/useLayer.tsx

@@ -354,13 +354,15 @@ export interface FixedLayerOptions extends BaseLayerOptions {
 export interface ContextLayerReturn {
   /**
    * Ref to attach to trigger element.
-   * Injects anchorName style for CSS anchor positioning.
+   * While the layer is shown, and until its exit animation ends, the trigger
+   * carries the layer's CSS anchor name.
    */
   ref: RefCallback<HTMLElement>;
 
   /**
    * The CSS anchor name to use for positioning.
    * Use this when you need to set anchorName manually (e.g., display:contents wrapper).
+   * Set it only while the layer is shown or its exit animation runs.
    */
   anchorId: string;
 
@@ -547,6 +549,24 @@ function untransform(
   return new DOMRect(left, top, width, height);
 }
 
+/**
+ * The finite animations still running on `layer` and its content. A layer
+ * that fades out keeps running them after the browser hides it, and it stays
+ * placed against its anchor until they end.
+ */
+function exitAnimations(layer: HTMLElement | null): Animation[] {
+  if (layer == null || typeof layer.getAnimations !== 'function') {
+    return [];
+  }
+  return layer
+    .getAnimations({subtree: true})
+    .filter(
+      animation =>
+        animation.playState === 'running' &&
+        animation.effect?.getComputedTiming().endTime !== Infinity,
+    );
+}
+
 /**
  * The layer's box where its position option put it, without the transform an
  * entry animation (or anything else) applies to it: a Tooltip enters from a
@@ -1216,6 +1236,41 @@ function useLayerImplementation(
   // stale-closure reads of the previous isOpen value.
   const isOpenRef = useRef(false);
 
+  // The exit of the layer that closed last, while it still paints. Its
+  // trigger stays an anchor until it ends, also when the trigger attaches
+  // again during it. Null once it has ended.
+  const exitRef = useRef<object | null>(null);
+
+  // A closed trigger is no anchor, once the layer stops painting. A show
+  // during the exit keeps the name, and so does a later exit.
+  const releaseAnchor = useCallback(
+    (layer: HTMLElement | null) => {
+      const exit = {};
+      exitRef.current = exit;
+      const release = () => {
+        if (exitRef.current !== exit) {
+          return;
+        }
+        exitRef.current = null;
+        const trigger = triggerRef.current;
+        if (!isOpenRef.current && trigger != null) {
+          removeAnchorName(trigger, anchorId);
+        }
+      };
+      const running = exitAnimations(layer);
+      if (running.length === 0) {
+        release();
+        return;
+      }
+      void Promise.all(
+        running.map(async animation =>
+          animation.finished.catch(() => undefined),
+        ),
+      ).then(release);
+    },
+    [anchorId],
+  );
+
   // The gesture during which the browser last closed this layer on its own.
   // Read through wasJustDismissed by triggers deciding whether a click is
   // theirs to act on.
@@ -1416,6 +1471,12 @@ function useLayerImplementation(
       popover.removeAttribute(LAYER_CLEARS_ANCHOR_ATTRIBUTE);
       popover.removeAttribute(LAYER_SCROLLS_ATTRIBUTE);
       applyDeferredWritingContext(popover);
+      // The trigger takes the layer's anchor name in the task that shows the
+      // layer, so the layer's first frame is placed against it.
+      const anchor = triggerRef.current;
+      if (anchor != null) {
+        addAnchorName(anchor, anchorId);
+      }
       // A hide the browser runs itself (an Escape its close watcher answers)
       // is counted too, from `beforetoggle` until the element's `toggle`, a
       // task after the hide has returned. The show is asked of the browser
@@ -1423,6 +1484,11 @@ function useLayerImplementation(
       // light dismiss at pointerup, then this show at the click); only a show
       // it refuses replays once the hide's count has ended.
       if (!showPopoverElement(popover)) {
+        // The replay anchors the trigger again; until then it is closed. An
+        // exit still running keeps the name.
+        if (anchor != null && exitRef.current == null) {
+          removeAnchorName(anchor, anchorId);
+        }
         replayWhenSettled();
         return;
       }
@@ -1434,6 +1500,7 @@ function useLayerImplementation(
       onShow?.();
     }
   }, [
+    anchorId,
     onShow,
     keepsAnchorClear,
     requestContextMount,
@@ -1470,8 +1537,9 @@ function useLayerImplementation(
       setIsOpen(false);
       onHide?.();
     }
+    releaseAnchor(popoverRef.current);
     clearContextMount();
-  }, [onHide, clearContextMount]);
+  }, [onHide, clearContextMount, releaseAnchor]);
 
   // A deferred show() replays through a ref so the queued closure reaches the
   // current callback rather than the one captured when it was queued.
@@ -1493,7 +1561,11 @@ function useLayerImplementation(
         removeAnchorName(triggerRef.current, anchorId);
       }
 
-      if (el) {
+      // Only a shown layer's trigger is an anchor. WebKit's Linux ports run the
+      // transform animation of an element that holds an anchor on the main
+      // thread. A busy task would then freeze a surface that moves around a
+      // closed trigger.
+      if (el && (isOpenRef.current || exitRef.current != null)) {
         addAnchorName(el, anchorId);
       }
 
@@ -1603,12 +1675,13 @@ function useLayerImplementation(
         rememberDismissal(
           (e.currentTarget as HTMLElement | null)?.ownerDocument ?? document,
         );
+        releaseAnchor(e.currentTarget as HTMLElement | null);
         setIsOpen(false);
         onHide?.();
         clearContextMount();
       }
     },
-    [onHide, clearContextMount, rememberDismissal],
+    [onHide, clearContextMount, rememberDismissal, releaseAnchor],
   );
 
   // Ref callback for popover element — sets up the `toggle` listener.

package/src/Layout/LayoutContent.doc.mjs

@@ -30,7 +30,8 @@ export const docs = {
     {
       name: 'label',
       type: 'string',
-      description: 'Accessible label for the landmark element.',
+      description:
+        'Accessible label for the landmark element. While the region scrolls, it also names the scrolling region, which otherwise takes a translated "Content".',
     },
     {
       name: 'role',
@@ -66,7 +67,8 @@ export const docsZh = {
     {
       name: 'label',
       type: 'string',
-      description: '地标元素的无障碍标签。',
+      description:
+        '地标元素的无障碍标签。区域滚动时，它也为滚动区域命名；未提供时使用已翻译的“Content”（内容）。',
     },
     {
       name: 'role',
@@ -86,7 +88,8 @@ export const docsDense = {
     padding: 'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable:
       'Enable scrollable overflow. With arithmetic contentWidth values, the scrollport reaches open sides while context-aware insets align children.',
-    label: 'Accessible label for landmark element.',
+    label:
+      'Accessible label for landmark element; also names the region while it scrolls (default "Content").',
     role: 'ARIA landmark role.',
   },
 };

package/src/Layout/LayoutContent.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file LayoutContent.tsx
- * @input Uses React StyleX, LayoutSlotsContext
+ * @input Uses React StyleX, LayoutSlotsContext, useScrollRegionProps
  * @output Exports LayoutContent component and LayoutContentProps
  * @position Scrollable main content area for Layout. Wraps the primary body content
  *   with automatic scroll containment and context-aware padding.
@@ -21,6 +21,8 @@ import {use} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {LayoutSlotsContext} from './LayoutSlotsContext';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useScrollRegionProps} from '../hooks/useScrollRegionProps';
 import {mergeProps} from '../utils/mergeProps';
 import type {SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
@@ -132,6 +134,8 @@ export interface LayoutContentProps extends BaseProps<HTMLDivElement> {
   /**
    * Accessible label for the landmark.
    * Required when role is set and multiple landmarks of the same type exist.
+   * While the content scrolls, it also names the scrolling region, which
+   * otherwise takes a translated "Content".
    */
   label?: string;
 
@@ -192,12 +196,14 @@ export function LayoutContent({
   const {hasHeader, hasFooter, hasStart, hasEnd} = use(LayoutSlotsContext);
 
   const isZeroPadding = padding === 0;
+  const region = useScrollRegionProps({isScrollable, role, label});
+  const mergedRef = useMergedRefs(ref, region.ref);
 
   return (
     <div
-      ref={ref}
-      role={role}
-      aria-label={label}
+      ref={mergedRef}
+      role={region.role}
+      aria-label={region['aria-label']}
       {...mergeProps(
         themeProps('layout-content'),
         stylex.props(

package/src/Layout/LayoutPanel.doc.mjs

@@ -53,7 +53,8 @@ export const docs = {
     {
       name: 'label',
       type: 'string',
-      description: 'Accessible label for the landmark element.',
+      description:
+        'Accessible label for the landmark element. While the region scrolls, it also names the scrolling region, which otherwise takes a translated "Content".',
     },
     {
       name: 'role',
@@ -106,7 +107,8 @@ export const docsZh = {
     {
       name: 'label',
       type: 'string',
-      description: '地标元素的无障碍标签。',
+      description:
+        '地标元素的无障碍标签。区域滚动时，它也为滚动区域命名；未提供时使用已翻译的“Content”（内容）。',
     },
     {
       name: 'role',
@@ -139,7 +141,8 @@ export const docsDense = {
     padding:
       'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable: 'Enable scrollable overflow.',
-    label: 'Accessible label for landmark element.',
+    label:
+      'Accessible label for landmark element; also names the region while it scrolls (default "Content").',
     role: 'ARIA landmark role.',
     width:
       'Panel width. Numbers = pixels, strings as-is. Ignored when resizable provided; hook controls width.',

package/src/Layout/LayoutPanel.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file LayoutPanel.tsx
- * @input Uses React StyleX, LayoutAreaContext, LayoutSlotsContext
+ * @input Uses React StyleX, LayoutAreaContext, LayoutSlotsContext,
+ *   useScrollRegionProps
  * @output Exports LayoutPanel component and LayoutPanelProps
  * @position Sidebar panel for Layout start/end slots. Use for navigation panels,
  *   settings sidebars, detail panels, or any fixed-width side content.
@@ -22,6 +23,8 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
 import {LayoutAreaContext} from './LayoutAreaContext';
 import {LayoutSlotsContext} from './LayoutSlotsContext';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useScrollRegionProps} from '../hooks/useScrollRegionProps';
 import {mergeProps} from '../utils';
 import type {SizeValue, SpacingStep} from '../utils/types';
 import type {ResizableProps} from '../Resizable/useResizable';
@@ -144,6 +147,8 @@ export interface LayoutPanelProps extends BaseProps<HTMLDivElement> {
   /**
    * Accessible label for the landmark.
    * Required when role is set and multiple landmarks of the same type exist.
+   * While the panel scrolls, it also names the scrolling region, which
+   * otherwise takes a translated "Content".
    */
   label?: string;
 
@@ -235,6 +240,8 @@ export function LayoutPanel({
   // When no divider, collapse spacing for seamless visual flow
   const shouldCollapseSpacing =
     !hasDivider && !isZeroPadding && padding == null;
+  const region = useScrollRegionProps({isScrollable, role, label});
+  const mergedRef = useMergedRefs(ref, region.ref);
 
   // Select divider style based on position
   const dividerStyle = isStartPanel
@@ -252,9 +259,9 @@ export function LayoutPanel({
 
   return (
     <div
-      ref={ref}
-      role={role}
-      aria-label={label}
+      ref={mergedRef}
+      role={region.role}
+      aria-label={region['aria-label']}
       {...mergeProps(
         themeProps('layout-panel'),
         stylex.props(

package/src/Lightbox/Lightbox.tsx

@@ -46,6 +46,7 @@ import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 import {overlayPaddingReset} from '../Layout/overlayPaddingReset.stylex';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
+import {useFocusRegionContainment} from '../hooks/useFocusTrap';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {isRtlElement} from '../hooks/isRtlElement';
@@ -341,6 +342,9 @@ export function Lightbox({
   const t = useComponentTranslator();
   const dialogRef = useRef<HTMLDialogElement>(null);
   const mergedDialogRef = useMergedRefs(ref, dialogRef);
+  // Native showModal() lets Tab leave for the browser's own UI, so the shared
+  // module wraps it.
+  useFocusRegionContainment(dialogRef, isOpen);
   const containerRef = useRef<HTMLDivElement>(null);
   const imageWrapperRef = useRef<HTMLDivElement>(null);
   const triggerElementRef = useRef<Element | null>(null);

package/src/MetadataList/MetadataList.tsx

@@ -158,7 +158,7 @@ const styles = stylex.create({
       default: 'pointer',
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
-    color: colorVars['--color-accent'],
+    color: colorVars['--color-text-accent'],
     fontSize: typeScaleVars['--text-body-size'],
     lineHeight: typeScaleVars['--text-body-leading'],
     fontWeight: fontWeightVars['--font-weight-medium'],

package/src/MobileNav/MobileNav.doc.mjs

@@ -98,7 +98,7 @@ export const docs = {
           name: 'onOpenChange',
           type: '(isOpen: boolean) => void',
           description:
-            'Called when the drawer visibility changes (backdrop click, Escape key, or close button). Inside AppShell, this is managed automatically via context.',
+            'Called when the drawer visibility changes (backdrop click, Escape key, or close button). Inside AppShell, this is managed automatically via context. On a phone or tablet (a coarse primary pointer), the drawer takes no tap or drag while it slides in; keys and assistive technology still act. After a close, focus returns to the element that opened it once its dialog closes.',
         },
         {
           name: 'children',
@@ -203,7 +203,7 @@ export const docsZh = {
       name: 'onOpenChange',
       type: '(isOpen: boolean) => void',
       description:
-        '当抽屉可见性变化时调用（点击背景遮罩、按 Escape 键或点击关闭按钮）。',
+        '当抽屉可见性变化时调用（点击背景遮罩、按 Escape 键或点击关闭按钮）。在手机或平板上（主指针为粗指针时），抽屉滑入期间不接受点按或拖动；键盘和辅助技术仍可操作。关闭后，焦点会在对话框关闭时回到打开它的元素。',
       required: true,
     },
     {
@@ -311,7 +311,7 @@ export const docsDense = {
   propDescriptions: {
     isOpen: 'whether drawer is open',
     onOpenChange:
-      'called when drawer visibility changes (backdrop click, Escape, close button)',
+      'called when drawer visibility changes (backdrop click, Escape, close button); under a coarse primary pointer the drawer takes no tap or drag while it slides in (keys still act)',
     children:
       'drawer content; typically SideNavSection/SideNavItem or any ReactNode',
     header: