@astryxdesign/core 0.7.7-canary.bf14580 → 0.7.7-canary.c19ca12

package/src/HoverCard/useHoverCard.tsx

@@ -16,9 +16,11 @@ import {
   useCallback,
   useEffect,
   useRef,
+  useState,
   type ReactNode,
   type RefCallback,
 } from 'react';
+import {createTriggerFocusGate} from '../utils/triggerFocus';
 import * as stylex from '@stylexjs/stylex';
 import {
   useLayer,
@@ -60,7 +62,7 @@ const styles = stylex.create({
 });
 
 /**
- * Focus trigger behavior for hover cards
+ * When focus on the trigger opens the hover card
  */
 export type HoverCardFocusTrigger = 'auto' | 'always' | 'never';
 
@@ -96,9 +98,10 @@ export interface HoverCardOptions {
 
   /**
    * When to trigger on focus:
-   * - `auto`: Only if element is naturally focusable
-   * - `always`: Always attach focus listeners
-   * - `never`: Never attach focus listeners (for composite widgets)
+   * - `auto`: focus on the trigger itself, or within a trigger that is
+   *   focusable when focus arrives
+   * - `always`: focus on the trigger or anything inside it
+   * - `never`: never on focus (for composite widgets)
    *
    * @default 'auto'
    */
@@ -235,29 +238,6 @@ export interface HoverCardReturn {
   hide: () => void;
 }
 
-/**
- * Check if an element is naturally focusable
- */
-function isFocusable(element: HTMLElement): boolean {
-  // Elements with explicit tabindex
-  if (element.hasAttribute('tabindex')) {
-    return element.tabIndex >= 0;
-  }
-
-  // Naturally focusable elements
-  const focusableTags = ['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA'];
-  if (focusableTags.includes(element.tagName)) {
-    return !(element as HTMLButtonElement).disabled;
-  }
-
-  // Elements with contenteditable
-  if (element.isContentEditable) {
-    return true;
-  }
-
-  return false;
-}
-
 /**
  * Hook for hover card behavior with hover/focus triggers.
  *
@@ -426,27 +406,44 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     [handleTouchPointerDown],
   );
 
-  const handleFocusIn = useCallback(() => {
-    if (!isEnabled) {
-      return;
-    }
-    // A tap focuses the trigger it activates. Opening on that focus would
-    // reinstate exactly the behavior the touch path just decided against —
-    // and on an action trigger it covers the thing the user tapped.
-    if (isTouchInteraction()) {
-      return;
-    }
-    // Skip showing if we're in the middle of an Escape dismiss
-    if (isEscapeDismissingRef.current) {
-      isEscapeDismissingRef.current = false;
-      return;
-    }
-    clearTimeouts();
-    showLayer();
-  }, [isEnabled, isTouchInteraction, clearTimeouts, showLayer]);
+  // Under `auto`, whether focus counts is decided when it arrives, and a
+  // focus that counted still hides on blur (utils/triggerFocus.ts).
+  const [focusGate] = useState(createTriggerFocusGate);
+
+  const handleFocusIn = useCallback(
+    (e: Event) => {
+      if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
+        return;
+      }
+      // A tap focuses the trigger it activates. Opening on that focus would
+      // reinstate exactly the behavior the touch path just decided against —
+      // and on an action trigger it covers the thing the user tapped.
+      if (isTouchInteraction()) {
+        return;
+      }
+      // Skip showing if we're in the middle of an Escape dismiss
+      if (isEscapeDismissingRef.current) {
+        isEscapeDismissingRef.current = false;
+        return;
+      }
+      clearTimeouts();
+      showLayer();
+    },
+    [
+      focusGate,
+      focusTrigger,
+      isEnabled,
+      isTouchInteraction,
+      clearTimeouts,
+      showLayer,
+    ],
+  );
 
   const handleFocusOut = useCallback(
     (e: FocusEvent) => {
+      if (!focusGate.focusOut(e, focusTrigger)) {
+        return;
+      }
       // Check if focus is moving to the hover card content
       const relatedTarget = e.relatedTarget as HTMLElement | null;
       const popoverElement = document.getElementById(layerId);
@@ -458,7 +455,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
       scheduleHide();
     },
-    [layerId, scheduleHide],
+    [focusGate, focusTrigger, layerId, scheduleHide],
   );
 
   // Escape dismissal (WCAG 1.4.13) goes through the shared layer stack: a
@@ -558,12 +555,9 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
         el.addEventListener('mouseleave', handleMouseLeave);
         el.addEventListener('pointerdown', handlePointerDown);
 
-        // Attach focus listeners based on focusTrigger option
-        const shouldAttachFocus =
-          focusTrigger === 'always' ||
-          (focusTrigger === 'auto' && isFocusable(el));
-
-        if (shouldAttachFocus) {
+        // Focus listeners unless focus never opens the card; `auto` decides
+        // per event (utils/triggerFocus.ts).
+        if (focusTrigger !== 'never') {
           el.addEventListener('focusin', handleFocusIn);
           el.addEventListener('focusout', handleFocusOut as EventListener);
         }

package/src/Icon/Icon.doc.mjs

@@ -71,15 +71,16 @@ export const docs = {
   props: [
     {
       name: 'icon',
-      type: 'IconName | ComponentType<SVGProps>',
+      type: 'IconName | NamespacedIconName | ComponentType<SVGProps>',
       description:
-        'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
+        'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. A namespaced key such as `richtext:bold` names a glyph that one component or library registers, and a theme can replace it by key; a namespaced key that nothing registers renders nothing. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
       required: true,
     },
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: 'Color variant mapped to Astryx icon color tokens.',
+      description:
+        'Color variant mapped to Astryx icon color tokens. Semantic values (primary through warning) follow the role, and inherit uses the surrounding text color. On the web, Icon also accepts the palette values blue, red, green, gray, cyan, teal, yellow, orange, pink, and purple, which pick a non-semantic hue.',
       default: "'inherit'",
     },
     {
@@ -107,6 +108,24 @@ export const docs = {
       description:
         "StyleX styles for customization (color, size, opacity). Folded into the icon's own stylex.props() call so it composes with the base color/size styles. Must be a stylex.create() value, not an inline style object like style={{}}.",
     },
+    {
+      name: 'className',
+      type: 'string',
+      description:
+        'Class name added to the rendered glyph, beside the astryx-icon target class.',
+    },
+    {
+      name: 'style',
+      type: 'CSSProperties',
+      description:
+        "Inline styles merged onto the rendered glyph after Icon's own size and color styles.",
+    },
+    {
+      name: 'ref',
+      type: 'Ref<SVGSVGElement>',
+      description:
+        'Ref to the rendered SVG element when icon is an icon component. A semantic or namespaced name renders inside an internal wrapper, and the ref is not attached.',
+    },
   ],
   theming: {
     targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
@@ -207,15 +226,16 @@ export const docsZh = {
   props: [
     {
       name: 'icon',
-      type: 'IconName | ComponentType<SVGProps>',
+      type: 'IconName | NamespacedIconName | ComponentType<SVGProps>',
       description:
-        '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
+        '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。命名空间键（如 `richtext:bold`）指向某个组件或库注册的图标，主题可以按键替换它；没有注册的命名空间键不渲染任何内容。列表之外的图标请直接传入 SVG 组件。',
       required: true,
     },
     {
       name: 'color',
       type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: '映射到 Astryx 图标颜色令牌的颜色变体。',
+      description:
+        '映射到 Astryx 图标颜色令牌的颜色变体。语义值（primary 到 warning）跟随角色，inherit 使用周围文字的颜色。在 Web 上，Icon 还接受调色板值 blue、red、green、gray、cyan、teal、yellow、orange、pink 和 purple，它们选择非语义色相。',
       default: "'inherit'",
     },
     {
@@ -243,6 +263,23 @@ export const docsZh = {
       description:
         '用于自定义的 StyleX 样式（颜色、尺寸、不透明度）。会并入图标自身的 stylex.props() 调用，从而与基础的颜色/尺寸样式组合。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。',
     },
+    {
+      name: 'className',
+      type: 'string',
+      description: '添加到渲染图标上的类名，与 astryx-icon 目标类名并列。',
+    },
+    {
+      name: 'style',
+      type: 'CSSProperties',
+      description:
+        '合并到渲染图标上的内联样式，位于 Icon 自身的尺寸和颜色样式之后。',
+    },
+    {
+      name: 'ref',
+      type: 'Ref<SVGSVGElement>',
+      description:
+        'icon 为图标组件时，指向渲染的 SVG 元素的 ref。语义名称或命名空间名称在内部包装元素中渲染，不会附加 ref。',
+    },
   ],
   theming: {
     targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
@@ -390,8 +427,9 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
-    color: 'Color variant mapped to Astryx icon color tokens.',
+    icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. A namespaced key (`richtext:bold`) names a glyph a component or library registers; an unregistered one renders nothing. For others, pass an SVG component.',
+    color:
+      'Color variant mapped to Astryx icon color tokens; inherit = surrounding text color. Web also accepts the non-semantic palette: blue, red, green, gray, cyan, teal, yellow, orange, pink, purple.',
     size: "xsm/sm/md/lg = 12/16/20/24px at a 16px root, scale w/ root font size; theme sets a size's glyph dimension via width + height (px or rem) on components.icon['size:sm'] etc. Explicit Icon size; otherwise nearest owning-component default, then 'md' when no contextual default exists",
     variant:
       "Requests the active theme's alternate artwork (e.g. 'filled'); names from augmentable IconVariantMap. Reaches the entry only if the active theme's iconVariants lists it (and an inherited entry's defining theme does too); else normal artwork. Ignored by a directly passed component; never in the DOM; no theming selector.",
@@ -399,5 +437,8 @@ export const docsDense = {
       'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
     xstyle:
       'StyleX styles (color, size, opacity) via stylex.create(); composes with the base color/size styles.',
+    className: 'Class added to the rendered glyph beside astryx-icon.',
+    style: "Inline styles merged after Icon's size and color styles.",
+    ref: 'Reaches the SVG only when icon is a component; a semantic or namespaced name renders in a wrapper and gets no ref.',
   },
 };

package/src/Icon/Icon.tsx

@@ -176,7 +176,11 @@ export interface IconProps extends Omit<
   SVGProps<SVGSVGElement>,
   'ref' | 'color'
 > {
-  /** Ref forwarded to the root element */
+  /**
+   * Ref to the rendered SVG element when `icon` is an icon component. A
+   * semantic or namespaced name renders inside an internal wrapper, and the
+   * ref is not attached.
+   */
   ref?: React.Ref<SVGSVGElement>;
   /**
    * Icon to render. Can be:
@@ -267,22 +271,26 @@ export interface IconProps extends Omit<
   xstyle?: StyleXStyles;
 }
 
+type IconA11yProps =
+  | {role: 'img'; 'aria-label': string; 'aria-hidden': undefined}
+  | {'aria-hidden': 'true'};
+
 /**
  * Derives the ARIA attributes for an icon from its `label` prop.
  *
  * - Non-empty `label` → meaningful image: `role="img"` + `aria-label`, and no
  *   `aria-hidden` (an `aria-hidden` element is removed from the accessibility
- *   tree, so its accessible name would be ignored).
+ *   tree, so its accessible name would be ignored). Icon passes
+ *   `aria-hidden: undefined`. Many icon components, such as Heroicons, write
+ *   `aria-hidden="true"` unless a prop replaces it.
  * - Omitted or empty `label` → decorative default: `aria-hidden="true"`.
  *
  * The result is spread BEFORE `{...props}` in both render modes so an explicit
  * `aria-hidden` / `role` / `aria-label` from the consumer always wins.
  */
-function getIconA11yProps(
-  label: string | undefined,
-): {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'} {
+function getIconA11yProps(label: string | undefined): IconA11yProps {
   return label != null && label !== ''
-    ? {role: 'img', 'aria-label': label}
+    ? {role: 'img', 'aria-label': label, 'aria-hidden': undefined}
     : {'aria-hidden': 'true'};
 }
 
@@ -392,7 +400,7 @@ function IconFromRegistry({
   color: IconColor;
   size: IconSize;
   variant: IconVariant | undefined;
-  a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};
+  a11yProps: IconA11yProps;
   className?: string;
   style?: React.CSSProperties;
   xstyle?: StyleXStyles;

package/src/Layer/layerAnimations.stylex.ts

@@ -2,7 +2,8 @@
 
 /**
  * @file layerAnimations.stylex.ts
- * @input Uses StyleX, theme duration/easing tokens
+ * @input Uses StyleX, theme duration/easing tokens, the Reduce Motion fade
+ *   constants
  * @output Exports shared entry animation styles for layer-based components
  * @position Shared animation primitives; consumed by DropdownMenu, Popover,
  *   HoverCard, Tooltip, Selector, and any component using useLayer
@@ -27,6 +28,7 @@
  */
 
 import * as stylex from '@stylexjs/stylex';
+import {reducedMotionFadeConsts} from '../motion/reducedMotion.stylex';
 import {durationVars, easeVars, spacingVars} from '../theme/tokens.stylex';
 
 const enterBelow = stylex.keyframes({
@@ -84,17 +86,21 @@ const enterStartRtl = stylex.keyframes({
 
 // Reduce Motion under a finger: the same entrance without its travel. A touch
 // presentation substitutes a cross-fade for motion, never a jump.
+// The fade's curve rides in its first keyframe, so the published class type
+// of `animationTimingFunction` stays the theme ease's.
 const fadeIn = stylex.keyframes({
-  from: {opacity: 0},
+  from: {opacity: 0, animationTimingFunction: reducedMotionFadeConsts.easing},
   to: {opacity: 1},
 });
 
+// No theme value lengthens the Reduce Motion fade, so its values are constants.
+// The media keys stay literal: StyleX gives an imported at-rule key a later
+// priority layer (see reducedMotionKeys).
 const animationBase = {
   animationDuration: {
     default: durationVars['--duration-fast-max'],
-    // The cross-fade is 200 ms or less, whatever the theme's duration
-    // (design:reduced-motion DR2).
-    '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': `min(${durationVars['--duration-fast-max']}, 200ms)`,
+    '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+      reducedMotionFadeConsts.duration,
   },
   animationTimingFunction: easeVars['--ease-standard'],
   animationFillMode: 'backwards' as const,
@@ -106,19 +112,18 @@ const animationBase = {
  * Keyed by LayerPlacement ('above' | 'below' | 'start' | 'end')
  * for easy lookup: `layerAnimations[placement]`.
  *
- * Each entry disables its keyframe animation under
- * `prefers-reduced-motion: reduce` so the layer appears instantly instead of
- * translating/scaling in (infra-6). Under a finger (the primary pointer is
- * coarse) it fades in instead, opacity only and in 200 ms or less: on a touch
- * screen Reduce Motion replaces motion with a cross-fade rather than a jump
- * (design:reduced-motion DR2, DR3), as iOS does for its menus, popovers and
- * tips.
+ * Under `prefers-reduced-motion: reduce` each entry drops its travel and
+ * scale. Under a finger (the primary pointer is coarse) the layer fades in,
+ * opacity only, in 200 ms on easeInOut: on a touch screen Reduce Motion
+ * replaces motion with a cross-fade rather than a jump; under any other
+ * pointer it appears at once.
  */
 export const layerAnimations = stylex.create({
   below: {
     animationName: {
       default: enterBelow,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
@@ -126,7 +131,8 @@ export const layerAnimations = stylex.create({
   above: {
     animationName: {
       default: enterAbove,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
@@ -135,7 +141,8 @@ export const layerAnimations = stylex.create({
     animationName: {
       default: enterEnd,
       ':is([dir="rtl"] *)': enterEndRtl,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
@@ -144,7 +151,8 @@ export const layerAnimations = stylex.create({
     animationName: {
       default: enterStart,
       ':is([dir="rtl"] *)': enterStartRtl,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,

package/src/Layer/usePressPin.ts

@@ -6,8 +6,9 @@
  * @file usePressPin.ts
  * @input A hover layer's trigger, open state, show and hide, and its
  *   `triggerBehavior` and `touchTrigger` options
- * @output usePressPin, the press toggle that pins a hover layer open;
- *   isPressPinTrigger; stopPressPinClick; the LayerTriggerBehavior type
+ * @output usePressPin, the press toggle that pins a hover layer open, and
+ *   the app hold behind useTooltip's show() and hide(); isPressPinTrigger;
+ *   stopPressPinClick; the LayerTriggerBehavior type
  * @position Core-internal: one call per hover layer, useTooltip's. It owns
  *   the layer's touch trigger, so the host makes no second touch-trigger call.
  *
@@ -103,8 +104,18 @@ export interface UsePressPinReturn {
   isHeldOpen: () => boolean;
   /** Wires the trigger element, or unwires it with `null`. */
   attach: (element: HTMLElement | null) => void;
-  /** Drops the pin: Escape, or a hide that came from elsewhere. */
+  /** Drops the pin and the app hold: Escape, or a hide from elsewhere. */
   unpin: () => void;
+  /**
+   * The app's `show()`: shows the layer and holds it open, as a pin does,
+   * until `release`, Escape, a press outside, or focus leaving the trigger
+   * and the layer. A controlled layer reports the request instead.
+   */
+  hold: () => void;
+  /** The app's `hide()`: drops the hold and hides the layer. */
+  release: () => void;
+  /** Whether the app's `show()` holds the layer open now. */
+  isAppHeld: () => boolean;
   /**
    * While pinned, focus moving onto an element outside the trigger and the
    * layer closes it. Returns whether the pin decided. The pin calls it for its
@@ -112,8 +123,9 @@ export interface UsePressPinReturn {
    */
   handleFocusLeave: (event: FocusEvent) => boolean;
   /**
-   * Whether the layer shows pinned on a wired trigger. The host then announces
-   * its rendered text, unless the layer has a `label`.
+   * Whether the layer shows pinned on a wired trigger, or held by the app's
+   * `show()`. The host then announces its rendered text, unless the layer has
+   * a `label`.
    */
   isPinShown: boolean;
   /** The layer's touch trigger (useTouchTriggerInternal), wired to the pin. */
@@ -175,8 +187,19 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     setIsPinnedState(next);
   }, []);
 
+  // The app's show() holds the layer on any trigger, in any mode.
+  const isAppHeldRef = useRef(false);
+  const [isAppHeldState, setIsAppHeldState] = useState(false);
+  const setAppHeld = useCallback((next: boolean) => {
+    isAppHeldRef.current = next;
+    setIsAppHeldState(next);
+  }, []);
+
   // The last offered element lets a `triggerBehavior` change rewire it.
   const triggerRef = useRef<HTMLElement | null>(null);
+  // Every offered trigger, in any mode, so focus leaving ends a pin or an
+  // app hold.
+  const focusTargetRef = useRef<HTMLElement | null>(null);
   const offeredRef = useRef<HTMLElement | null>(null);
   // A primitive: re-attaching the same trigger renders nothing.
   const [offeredKind, setOfferedKind] = useState<'none' | 'other' | 'button'>(
@@ -192,6 +215,13 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   // a pinned layer through the pin, so the pin drops with it.
   const hideFromTouch = useCallback(() => {
     const current = optionsRef.current;
+    if (isAppHeldRef.current) {
+      setAppHeld(false);
+      if (current.isOpen !== undefined) {
+        current.report(false);
+        return;
+      }
+    }
     if (current.triggerBehavior === 'toggle' && triggerRef.current != null) {
       if (current.isOpen !== undefined) {
         current.report(false);
@@ -202,7 +232,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
       }
     }
     current.hide();
-  }, [setPinned]);
+  }, [setPinned, setAppHeld]);
 
   const {
     isTouchPointerRef,
@@ -233,13 +263,14 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   const close = useCallback(() => {
     const current = optionsRef.current;
     clearTapOpen();
+    setAppHeld(false);
     if (current.isOpen !== undefined) {
       current.report(false);
       return;
     }
     setPinned(false);
     current.hide();
-  }, [setPinned, clearTapOpen]);
+  }, [setPinned, setAppHeld, clearTapOpen]);
 
   const announceName = useCallback(() => {
     const current = optionsRef.current;
@@ -348,6 +379,9 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
 
   const isHeldOpen = useCallback(() => {
     const current = optionsRef.current;
+    if (isAppHeldRef.current && current.isLayerOpen) {
+      return current.isOpen !== false;
+    }
     if (current.triggerBehavior !== 'toggle' || triggerRef.current == null) {
       return false;
     }
@@ -364,7 +398,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
         return false;
       }
       const next = event.relatedTarget;
-      const trigger = triggerRef.current;
+      const trigger = focusTargetRef.current;
       // Focus that leaves for no element is a press's to decide. The trigger
       // can sit in another document, so the check uses its own window.
       const view = trigger?.ownerDocument.defaultView;
@@ -387,6 +421,8 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   );
 
   const unwire = useCallback(() => {
+    focusTargetRef.current?.removeEventListener('focusout', handleFocusLeave);
+    focusTargetRef.current = null;
     const previous = triggerRef.current;
     if (previous == null) {
       return;
@@ -394,7 +430,6 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     previous.removeEventListener('click', handlePress);
     previous.removeEventListener('keydown', handleKeyDown);
     previous.removeEventListener('keyup', handleKeyUp);
-    previous.removeEventListener('focusout', handleFocusLeave);
     const own = ownStateRef.current;
     if (own != null) {
       restoreAttribute(previous, 'aria-expanded', own.expanded);
@@ -423,10 +458,14 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
       }
       settledRef.current = {element, mode: current.triggerBehavior};
       unwire();
-      if (element == null || current.triggerBehavior !== 'toggle') {
+      if (element == null) {
         return;
       }
-      if (!isPressPinTrigger(element)) {
+      // Its own focus-leave listener, in any mode: `focusTrigger="never"`
+      // attaches none, and an app hold needs it on any trigger.
+      element.addEventListener('focusout', handleFocusLeave);
+      focusTargetRef.current = element;
+      if (current.triggerBehavior !== 'toggle' || !isPressPinTrigger(element)) {
         return;
       }
       element.addEventListener('click', handlePress);
@@ -434,8 +473,6 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
         element.addEventListener('keydown', handleKeyDown);
         element.addEventListener('keyup', handleKeyUp);
       }
-      // Its own focus-leave listener: `focusTrigger="never"` attaches none.
-      element.addEventListener('focusout', handleFocusLeave);
       ownStateRef.current = {
         expanded: element.getAttribute('aria-expanded'),
         controls: element.getAttribute('aria-controls'),
@@ -473,7 +510,31 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     if (isPinnedRef.current) {
       setPinned(false);
     }
-  }, [setPinned]);
+    if (isAppHeldRef.current) {
+      setAppHeld(false);
+    }
+  }, [setPinned, setAppHeld]);
+
+  const hold = useCallback(() => {
+    const current = optionsRef.current;
+    if (!current.isEnabled) {
+      return;
+    }
+    setAppHeld(true);
+    armOutsideDismiss();
+    announceName();
+    if (current.isOpen !== undefined) {
+      current.report(true);
+      return;
+    }
+    current.show();
+  }, [setAppHeld, armOutsideDismiss, announceName]);
+
+  const release = useCallback(() => {
+    close();
+  }, [close]);
+
+  const isAppHeld = useCallback(() => isAppHeldRef.current, []);
 
   // Each path that hides a pinned layer drops the pin itself, so a layer that
   // does not show is never reported expanded.
@@ -490,13 +551,18 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     writeAttribute(trigger, 'aria-controls', isLayerOpen ? layerId : null);
   });
 
-  const isPinShown = isToggleMode && isWired && isExpanded;
+  const isPinShown =
+    (isToggleMode && isWired && isExpanded) ||
+    (isAppHeldState && isLayerOpen && isOpen !== false);
 
   return {
     isToggleTrigger,
     isHeldOpen,
     attach,
     unpin,
+    hold,
+    release,
+    isAppHeld,
     handleFocusLeave,
     isPinShown,
     touch: {

package/src/Lightbox/Lightbox.tsx

@@ -55,6 +55,7 @@ import {
 } from '../i18n/useComponentTranslator';
 import english from '../i18n/generated-english/Lightbox/Lightbox.generated';
 import {isRenderable} from '../utils/isRenderable';
+import {prepareFocusReturnOnRemoval} from '../utils/focusReturn';
 
 registerEnglishFallback(english);
 /**
@@ -445,6 +446,23 @@ export function Lightbox({
     }
   }, [isOpen, hasItem]);
 
+  // A viewer that unmounts while open (rendered only while open, or removed
+  // with the rest of a view) never runs the close branch above. Focus the
+  // removal lost goes back to the opener while the opener is still on the
+  // page.
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog == null) {
+      return;
+    }
+    const returnFocusOnRemoval = prepareFocusReturnOnRemoval(dialog);
+    return () => {
+      if (dialog.open) {
+        returnFocusOnRemoval(triggerElementRef.current);
+      }
+    };
+  }, [hasItem]);
+
   const handleClose = useCallback(() => {
     onOpenChange(false);
   }, [onOpenChange]);