@astryxdesign/core 0.7.7 → 0.7.8-canary.30b1896

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/IconButton/IconButton.doc.mjs

@@ -20,7 +20,8 @@ export const docs = {
     {
       name: 'icon',
       type: 'ReactNode',
-      description: 'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
+      description:
+        'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
       required: true,
       slotElements: [{__element: 'Icon', props: {icon: 'check'}}],
     },
@@ -46,19 +47,22 @@ export const docs = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
+      description:
+        'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
       default: 'false',
     },
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Disables the button.',
+      description:
+        'Disables the button. When a tooltip is present, uses aria-disabled instead of native disabled so the button stays focusable.',
       default: 'false',
     },
     {
       name: 'tooltip',
       type: 'string',
-      description: 'Tooltip text shown on hover.',
+      description:
+        "Tooltip text shown on hover and keyboard focus. It also describes the button, unless it repeats the button's accessible name.",
     },
     {
       name: 'onClick',
@@ -70,10 +74,69 @@ export const docs = {
       type: '(e: MouseEvent) => void | Promise<void>',
       description: 'Async click handler with automatic loading state.',
     },
+    {
+      name: 'isInterruptible',
+      type: 'boolean',
+      description:
+        'Keep the button clickable while a clickAction is pending: the spinner and aria-busy still show, but the button is not disabled and the action is not deduped, so a re-click lands and interrupts the in-flight action with a fresh one. Use it for interruptible actions, not fire-once actions (submit, save, pay).',
+      default: 'false',
+    },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the button. Numbers are treated as pixels, strings are used as-is. Without it the button keeps its icon-only aspect, square by default; with it the button takes that width.',
+    },
+    {
+      name: 'type',
+      type: "'button' | 'submit' | 'reset'",
+      description: 'HTML button type attribute.',
+      default: "'button'",
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description: 'HTML name attribute for form submission.',
+    },
+    {
+      name: 'value',
+      type: 'string | number | readonly string[]',
+      description: 'HTML value attribute for form submission.',
+    },
+    {
+      name: 'form',
+      type: 'string',
+      description: 'Associates the button with a form element by ID.',
+    },
+    {
+      name: 'href',
+      type: 'string',
+      description:
+        'When provided, renders the button as a link element (<a> or custom link component). A disabled IconButton still renders a <button>.',
+    },
+    {
+      name: 'as',
+      type: 'ComponentType',
+      description:
+        'Custom link component to use when href is provided (e.g. Next.js Link).',
+    },
+    {
+      name: 'target',
+      type: 'string',
+      description:
+        'HTML target attribute when rendered as a link (e.g. "_blank").',
+    },
+    {
+      name: 'rel',
+      type: 'string',
+      description:
+        'HTML rel attribute when rendered as a link (e.g. "noopener noreferrer").',
+    },
   ],
 
   usage: {
-    description: 'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
+    description:
+      'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
     accessibility: [
       {
         name: 'Essential icon or spinner arc',
@@ -113,26 +176,68 @@ export const docs = {
       },
     ],
     bestPractices: [
-      { guidance: true, description: 'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.' },
-      { guidance: true, description: 'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.' },
-      { guidance: true, description: 'Use ghost in toolbars and dense areas to reduce visual clutter.' },
-      { guidance: false, description: 'Use IconButton if the action isn\'t obvious from the icon alone; use Button with text.' },
-      { guidance: false, description: 'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.' },
+      {
+        guidance: true,
+        description:
+          'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use ghost in toolbars and dense areas to reduce visual clutter.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use IconButton if the action isn't obvious from the icon alone; use Button with text.",
+      },
+      {
+        guidance: false,
+        description:
+          'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.',
+      },
     ],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+  description:
+    'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
   usage: {
-    description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+    description:
+      'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
     bestPractices: [
-      { guidance: true, description: 'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.' },
-      { guidance: true, description: 'Add tooltip: even gear icon can mean Settings/Preferences/Configure.' },
-      { guidance: true, description: 'Use ghost in toolbars + dense areas to reduce visual clutter.' },
-      { guidance: false, description: "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead." },
-      { guidance: false, description: 'Skip tooltip: label only reaches screen readers; sighted users need hover hint.' },
+      {
+        guidance: true,
+        description:
+          'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add tooltip: even gear icon can mean Settings/Preferences/Configure.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use ghost in toolbars + dense areas to reduce visual clutter.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead.",
+      },
+      {
+        guidance: false,
+        description:
+          'Skip tooltip: label only reaches screen readers; sighted users need hover hint.',
+      },
     ],
   },
   propDescriptions: {
@@ -140,11 +245,26 @@ export const docsDense = {
     icon: 'icon element rendered inside button; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
     variant: 'visual style variant',
     size: 'size variant',
-    elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
-    isLoading: 'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
-    isDisabled: 'disables button',
-    tooltip: 'tooltip text shown on hover',
+    elevation:
+      'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
+    isLoading:
+      'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
+    isDisabled: 'disables button; uses aria-disabled when tooltip present',
+    tooltip:
+      'tooltip on hover + keyboard focus; also describes the button unless it repeats the accessible name',
     onClick: 'standard click handler',
     clickAction: 'async click handler w/ automatic loading state',
+    isInterruptible:
+      'keeps button clickable while clickAction pending; a re-click interrupts it. Not for fire-once actions (submit/save/pay)',
+    width:
+      'button width; numbers=pixels, strings=as-is; without it keeps the icon-only aspect (square by default)',
+    type: 'HTML button type; defaults to "button"',
+    name: 'HTML name for form submission',
+    value: 'HTML value for form submission',
+    form: 'associates button with form element by ID',
+    href: 'renders as a link; a disabled IconButton stays a <button>',
+    as: 'custom link component used with href',
+    target: 'HTML target when rendered as a link',
+    rel: 'HTML rel when rendered as a link',
   },
 };

package/src/Item/useSwipeAction.ts

@@ -237,6 +237,8 @@ export function useSwipeAction({
     reducedMotionRef.current = isReducedMotion;
   });
 
+  // Releases the settle timer, the animation frame and the pinch watch on
+  // unmount.
   useEffect(
     () => () => {
       if (settleTimerRef.current != null) {

package/src/Layer/modalOutlet.ts

@@ -188,6 +188,8 @@ export function useModalOutlet(
   const isLatestRef = useRef(isLatest);
   isLatestRef.current = isLatest;
   const suppliedRef = useRef<HTMLDialogElement | null>(null);
+  // Syncs the module registry of modal outlets with this dialog while it is
+  // active. It also follows the dialog's native `close` event.
   useEffect(() => {
     const element = ref.current;
     if (!isActive || element == null) {

package/src/Layer/outsidePress.ts

@@ -96,6 +96,7 @@ export function useOutsidePress(): OutsidePressWatch {
     },
     [],
   );
+  // Stops the outside-press listeners on unmount.
   useEffect(() => stop, [stop]);
   return useMemo(() => ({start, stop}), [start, stop]);
 }

package/src/Layer/useLayer.tsx

@@ -1560,6 +1560,8 @@ function useLayerImplementation(
     forgetDismissalRef.current = forget;
   }, []);
 
+  // Syncs the document's capture-phase gesture tracking with this mount.
+  // Unmount forgets the layer's dismissal.
   useEffect(() => {
     // Install capture-phase gesture tracking before the first interaction.
     currentGesture();

package/src/Layer/useLayerDismissal.ts

@@ -155,6 +155,8 @@ export function useLayerDismissal(
 
   const isRegistered = isActive && isEnabled;
 
+  // Syncs the shared dismissal stack with `isRegistered`. A registered layer
+  // gets Escape and outside presses in stack order.
   useEffect(() => {
     if (!isRegistered) {
       wasRegisteredRef.current = false;

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/Layer/useTouchTrigger.ts

@@ -436,7 +436,9 @@ export function useTouchTriggerInternal(
     }
   }, [triggerRef, disarmOutsideDismiss]);
 
+  // Releases the outside-dismiss listener on unmount.
   useEffect(() => disarmOutsideDismiss, [disarmOutsideDismiss]);
+  // Releases a pending tap on unmount.
   useEffect(() => () => forgetPendingTapRef.current?.(), []);
 
   const isTouchInteraction = useCallback(