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

package/dist/InfoTip/InfoTip.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @file InfoTip.tsx
+ * @input Uses React, StyleX, Tooltip, Icon, useComponentTranslator, the shared
+ *   touch hit area, color/spacing/radius/duration/ease tokens
+ * @output Exports InfoTip component, InfoTipProps, InfoTipSize types
+ * @position Core implementation; consumed by index.ts, tested by
+ *   InfoTip.test.tsx; `@astryxdesign/lab` re-exports it, deprecated
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/InfoTip/InfoTip.doc.mjs (props table, features)
+ * - /docs/specs/components/InfoTip/InfoTip.spec.md (contract)
+ * - /packages/core/src/InfoTip/InfoTip.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/InfoTip/index.ts (exports if types change)
+ */
+import { type ReactNode, type Ref } from 'react';
+import type { BaseProps } from '../BaseProps.js';
+import { type IconSize } from '../Icon/Icon.js';
+/**
+ * Size of the info icon. Maps 1:1 to Icon sizes
+ * (xsm: 12px, sm: 16px, md: 20px, lg: 24px).
+ */
+export type InfoTipSize = IconSize;
+export interface InfoTipProps extends Pick<BaseProps, 'xstyle' | 'className' | 'style'> {
+    /** Ref forwarded to the info button. */
+    ref?: Ref<HTMLButtonElement>;
+    /**
+     * The help the button reveals. Short, noninteractive text; for links or
+     * buttons, use HoverCard.
+     */
+    content: ReactNode;
+    /**
+     * Accessible name of the button.
+     * @default A translated "More information"
+     */
+    label?: string;
+    /**
+     * Size of the info icon.
+     * @default 'sm'
+     */
+    size?: InfoTipSize;
+}
+/**
+ * An info icon that reveals help: a small "i" button. Hover and keyboard
+ * focus preview the help. A click, tap, Enter, or Space pins it open until
+ * Escape, a second press, a press outside, or focus leaving. Use it next to
+ * labels, values, and metrics for permission notes, metric definitions, and
+ * field help.
+ *
+ * InfoTip is a press-to-pin Tooltip on a named button: Tooltip opens, pins,
+ * announces, and closes the help. The info icon resolves from
+ * the icon registry, so themes can replace it.
+ *
+ * @example
+ * ```
+ * <InfoTip content="Editors can change this field; viewers cannot." />
+ * <InfoTip content="30-day rolling average." label="About this metric" />
+ * ```
+ */
+export declare function InfoTip({ content, label, size, ref, xstyle, className, style, }: InfoTipProps): ReactNode;
+export declare namespace InfoTip {
+    var displayName: string;
+}
+//# sourceMappingURL=InfoTip.d.ts.map

package/dist/InfoTip/InfoTip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InfoTip.d.ts","sourceRoot":"","sources":["../../src/InfoTip/InfoTip.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAc,KAAK,SAAS,EAAE,KAAK,GAAG,EAAC,MAAM,OAAO,CAAC;AAG5D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAO,KAAK,QAAQ,EAAC,MAAM,cAAc,CAAC;AAoBjD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEnC,MAAM,WAAW,YAAa,SAAQ,IAAI,CACxC,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC7B;;;OAGG;IACH,OAAO,EAAE,SAAS,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AA8CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,EACtB,OAAO,EACP,KAAK,EACL,IAAW,EACX,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,YAAY,GAAG,SAAS,CAyC1B;yBAjDe,OAAO"}

package/dist/InfoTip/InfoTip.js

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InfoTip.tsx
+ * @input Uses React, StyleX, Tooltip, Icon, useComponentTranslator, the shared
+ *   touch hit area, color/spacing/radius/duration/ease tokens
+ * @output Exports InfoTip component, InfoTipProps, InfoTipSize types
+ * @position Core implementation; consumed by index.ts, tested by
+ *   InfoTip.test.tsx; `@astryxdesign/lab` re-exports it, deprecated
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/InfoTip/InfoTip.doc.mjs (props table, features)
+ * - /docs/specs/components/InfoTip/InfoTip.spec.md (contract)
+ * - /packages/core/src/InfoTip/InfoTip.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/InfoTip/index.ts (exports if types change)
+ */
+import { useCallback } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
+import { Icon } from "../Icon/Icon.js";
+import { TooltipWithTriggerBehavior } from "../Tooltip/Tooltip.js";
+import { registerEnglishFallback, useComponentTranslator } from "../i18n/useComponentTranslator.js";
+import english from "../i18n/generated-english/InfoTip/InfoTip.generated.js";
+import "../theme/tokens.stylex.js";
+import { colorVars, durationVars, easeVars, radiusVars, spacingVars } from "../theme/tokens.stylex.js";
+import { focusOutlineStyles } from "../utils/focusOutline.stylex.js";
+import { mergeProps } from "../utils/mergeProps.js";
+import { watchHitArea, writeHitInsets } from "../utils/hitArea.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+registerEnglishFallback(english);
+
+/**
+ * Size of the info icon. Maps 1:1 to Icon sizes
+ * (xsm: 12px, sm: 16px, md: 20px, lg: 24px).
+ */
+
+const styles = {
+  trigger: {
+    kVAEAm: "x1n2onr6",
+    k1xSpc: "x3nfvp2",
+    kGNEyG: "x6s0dn4",
+    kjj79g: "xl56j7k",
+    kXLuUW: "xxymvpz",
+    kmVPX3: "x12nba7r",
+    kogj98: "x1ghz6dp",
+    ksu8eU: "xng3xce",
+    kWkggS: "xjbqb8w",
+    kaIpWk: "xjspbzw",
+    kkrTdU: "x1ypdohk x16khyan",
+    kMwMTN: "xv9yike x10ue8fs",
+    k1ekBW: "xt3l3uh",
+    kIyJzY: "xuedmi6",
+    kAMwcw: "xlr8y92",
+    $$css: true
+  },
+  hitArea: {
+    k5JduY: "x1s928wv",
+    kwXMNM: "x1j6awrg",
+    kv0HGH: "xzdy5ak",
+    $$css: true
+  }
+};
+
+/**
+ * An info icon that reveals help: a small "i" button. Hover and keyboard
+ * focus preview the help. A click, tap, Enter, or Space pins it open until
+ * Escape, a second press, a press outside, or focus leaving. Use it next to
+ * labels, values, and metrics for permission notes, metric definitions, and
+ * field help.
+ *
+ * InfoTip is a press-to-pin Tooltip on a named button: Tooltip opens, pins,
+ * announces, and closes the help. The info icon resolves from
+ * the icon registry, so themes can replace it.
+ *
+ * @example
+ * ```
+ * <InfoTip content="Editors can change this field; viewers cannot." />
+ * <InfoTip content="30-day rolling average." label="About this metric" />
+ * ```
+ */
+export function InfoTip({
+  content,
+  label,
+  size = 'sm',
+  ref,
+  xstyle,
+  className,
+  style
+}) {
+  const t = useComponentTranslator();
+  // Under a coarse pointer the button takes taps out toward 44 px. The watch
+  // lives as long as the button is attached: the ref's cleanup stops it, and a
+  // replaced button starts its own.
+  const watchButtonHitArea = useCallback(button => {
+    if (button == null) {
+      return;
+    }
+    return watchHitArea(button, insets => writeHitInsets(button, insets));
+  }, []);
+  const mergedRef = useMergedRefs(ref, watchButtonHitArea);
+
+  // No Escape handler of its own. Tooltip's entry in the shared dismissal
+  // stack takes Escape, so one press never closes both the help and an
+  // enclosing Dialog.
+  return /*#__PURE__*/_jsx(TooltipWithTriggerBehavior, {
+    content: content
+    // The tooltip is the button's only purpose. A click, a tap, Enter, or
+    // Space pins it open, and the press stops at the button. So an InfoTip's
+    // content is reachable on a phone and from the keyboard alike.
+    ,
+    triggerBehavior: "toggle",
+    children: /*#__PURE__*/_jsx("button", {
+      ref: mergedRef,
+      type: "button",
+      "aria-label": label ?? t('@astryx.infoTip.label'),
+      ...mergeProps(stylex.props(focusOutlineStyles.focusVisible, styles.trigger, styles.hitArea, xstyle), className, style),
+      children: /*#__PURE__*/_jsx(Icon, {
+        icon: "info",
+        size: size
+      })
+    })
+  });
+}
+InfoTip.displayName = 'InfoTip';

package/dist/InfoTip/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file InfoTip component barrel export
+ * @input InfoTip.tsx
+ * @output Exports InfoTip, InfoTipProps, InfoTipSize
+ * @position Barrel; consumed by packages/core/src/index.ts and the
+ *   `@astryxdesign/core/InfoTip` entry
+ */
+export { InfoTip } from './InfoTip.js';
+export type { InfoTipProps, InfoTipSize } from './InfoTip.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/InfoTip/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/InfoTip/index.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAClC,YAAY,EAAC,YAAY,EAAE,WAAW,EAAC,MAAM,WAAW,CAAC"}

package/dist/InfoTip/index.js

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InfoTip component barrel export
+ * @input InfoTip.tsx
+ * @output Exports InfoTip, InfoTipProps, InfoTipSize
+ * @position Barrel; consumed by packages/core/src/index.ts and the
+ *   `@astryxdesign/core/InfoTip` entry
+ */
+export { InfoTip } from "./InfoTip.js";

package/dist/Layer/layerAnimations.stylex.d.ts

@@ -1,6 +1,7 @@
 /**
  * @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
@@ -30,13 +31,11 @@ import * as stylex from '@stylexjs/stylex';
  * 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 declare const layerAnimations: Readonly<{
     readonly below: Readonly<{

package/dist/Layer/layerAnimations.stylex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layerAnimations.stylex.d.ts","sourceRoot":"","sources":["../../src/Layer/layerAnimations.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AA0E3C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;EAmC1B,CAAC"}
+{"version":3,"file":"layerAnimations.stylex.d.ts","sourceRoot":"","sources":["../../src/Layer/layerAnimations.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AA+E3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;EAuC1B,CAAC"}

package/dist/Layer/layerAnimations.stylex.js

@@ -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,8 @@
  */
 
 import * as stylex from '@stylexjs/stylex';
+import "../motion/reducedMotion.stylex.js";
+import { reducedMotionFadeConsts } from "../motion/reducedMotion.stylex.js";
 import "../theme/tokens.stylex.js";
 import { durationVars, easeVars, spacingVars } from "../theme/tokens.stylex.js";
 const enterBelow = "xv1hr86-B";
@@ -44,13 +47,17 @@ const enterStartRtl = "xwmkjkf-B";
 
 // Reduce Motion under a finger: the same entrance without its travel. A touch
 // presentation substitutes a cross-fade for motion, never a jump.
-const fadeIn = "x18re5ia-B";
+// The fade's curve rides in its first keyframe, so the published class type
+// of `animationTimingFunction` stays the theme ease's.
+const fadeIn = "x12p7u8f-B";
+
+// 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'
@@ -62,39 +69,37 @@ 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 = {
   below: {
-    kKVMdj: "xl1vlw0 xa4pr1u xajy0lc",
-    k44tkh: "x9uej1z x13pi3j7",
+    kKVMdj: "xl1vlw0 x2g3n7u xaqowwx",
+    k44tkh: "x9uej1z x10got5w",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true
   },
   above: {
-    kKVMdj: "x3psbcj xa4pr1u xajy0lc",
-    k44tkh: "x9uej1z x13pi3j7",
+    kKVMdj: "x3psbcj x2g3n7u xaqowwx",
+    k44tkh: "x9uej1z x10got5w",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true
   },
   end: {
-    kKVMdj: "x1i331go x1vxsm5i xa4pr1u xajy0lc",
-    k44tkh: "x9uej1z x13pi3j7",
+    kKVMdj: "x1i331go x1vxsm5i x2g3n7u xaqowwx",
+    k44tkh: "x9uej1z x10got5w",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true
   },
   start: {
-    kKVMdj: "xck01x9 x18lne9g xa4pr1u xajy0lc",
-    k44tkh: "x9uej1z x13pi3j7",
+    kKVMdj: "xck01x9 x18lne9g x2g3n7u xaqowwx",
+    k44tkh: "x9uej1z x10got5w",
     kyAemX: "x128ha8g",
     kWV6AL: "xskzprw",
     $$css: true

package/dist/Layer/useBackdropPress.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file useBackdropPress.ts
+ * @input A modal layer's backdrop dismissal and whether it is allowed now
+ * @output Capture-phase pointer handlers and a click handler for the layer's
+ *   <dialog> root
+ * @position Shared backdrop-press rule for Dialog and Drawer
+ */
+import { type PointerEvent, type MouseEvent } from 'react';
+export interface BackdropPressHandlers {
+    onPointerDownCapture: (event: PointerEvent<HTMLElement>) => void;
+    onPointerUpCapture: (event: PointerEvent<HTMLElement>) => void;
+    onPointerCancelCapture: (event: PointerEvent<HTMLElement>) => void;
+    onClick: (event: MouseEvent<HTMLElement>) => void;
+}
+/**
+ * A press on a modal layer's backdrop targets the <dialog> root itself. A
+ * click there is also what the browser sends when a press starts on one side
+ * of the layer's edge and ends on the other (it goes to the nearest common
+ * ancestor), so a backdrop press dismisses only when its pointer-down and its
+ * pointer-up both landed on the backdrop. A cancelled pointer ends the press.
+ *
+ * The pointer handlers run in the capture phase. A nested layer, such as a
+ * popover open in the dialog, stops its presses at its own root, so a
+ * bubble-phase handler here does not see them.
+ */
+export declare function useBackdropPress(onBackdropPress: () => void, isEnabled: boolean): BackdropPressHandlers;
+//# sourceMappingURL=useBackdropPress.d.ts.map

package/dist/Layer/useBackdropPress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBackdropPress.d.ts","sourceRoot":"","sources":["../../src/Layer/useBackdropPress.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AAEH,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,UAAU,EAAC,MAAM,OAAO,CAAC;AAE9E,MAAM,WAAW,qBAAqB;IACpC,oBAAoB,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACjE,kBAAkB,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAC/D,sBAAsB,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACnE,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,eAAe,EAAE,MAAM,IAAI,EAC3B,SAAS,EAAE,OAAO,GACjB,qBAAqB,CA6CvB"}

package/dist/Layer/useBackdropPress.js

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useBackdropPress.ts
+ * @input A modal layer's backdrop dismissal and whether it is allowed now
+ * @output Capture-phase pointer handlers and a click handler for the layer's
+ *   <dialog> root
+ * @position Shared backdrop-press rule for Dialog and Drawer
+ */
+import { useCallback, useRef } from 'react';
+/**
+ * A press on a modal layer's backdrop targets the <dialog> root itself. A
+ * click there is also what the browser sends when a press starts on one side
+ * of the layer's edge and ends on the other (it goes to the nearest common
+ * ancestor), so a backdrop press dismisses only when its pointer-down and its
+ * pointer-up both landed on the backdrop. A cancelled pointer ends the press.
+ *
+ * The pointer handlers run in the capture phase. A nested layer, such as a
+ * popover open in the dialog, stops its presses at its own root, so a
+ * bubble-phase handler here does not see them.
+ */
+export function useBackdropPress(onBackdropPress, isEnabled) {
+  const startedOnBackdropRef = useRef(false);
+  const endedOnBackdropRef = useRef(false);
+  const onPointerDownCapture = useCallback(event => {
+    startedOnBackdropRef.current = event.target === event.currentTarget;
+    endedOnBackdropRef.current = false;
+  }, []);
+  const onPointerUpCapture = useCallback(event => {
+    endedOnBackdropRef.current = startedOnBackdropRef.current && event.target === event.currentTarget;
+    startedOnBackdropRef.current = false;
+  }, []);
+  const onPointerCancelCapture = useCallback(() => {
+    startedOnBackdropRef.current = false;
+    endedOnBackdropRef.current = false;
+  }, []);
+  const onClick = useCallback(event => {
+    const pressWasOnBackdrop = endedOnBackdropRef.current;
+    startedOnBackdropRef.current = false;
+    endedOnBackdropRef.current = false;
+    if (isEnabled && pressWasOnBackdrop && event.target === event.currentTarget) {
+      onBackdropPress();
+    }
+  }, [isEnabled, onBackdropPress]);
+  return {
+    onPointerDownCapture,
+    onPointerUpCapture,
+    onPointerCancelCapture,
+    onClick
+  };
+}

package/dist/Layer/usePressPin.d.ts

@@ -2,8 +2,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.
  *
@@ -15,12 +16,10 @@ import { type MouseEvent as ReactMouseEvent, type RefObject } from 'react';
 import { type LayerTouchTrigger, type UseTouchTriggerReturn } from './useTouchTrigger.js';
 /**
  * How the trigger opens the layer. `adaptive`, the default, previews it on
- * hover and focus, and a tap opens it unless the trigger acts. While
- * `touchTrigger` remains, it decides those taps. `hover` previews it on hover
- * and focus, and no touch or pen tap opens it. `toggle` pins it on every
- * press of a button trigger.
+ * hover and focus, and `touchTrigger` decides taps. `toggle` pins it on every
+ * press of a button trigger. Internal: InfoTip's press-to-pin uses `toggle`.
  */
-export type LayerTriggerBehavior = 'adaptive' | 'hover' | 'toggle';
+export type LayerTriggerBehavior = 'adaptive' | 'toggle';
 /**
  * The layer component's wrapper handler. It stops a press that pinned or
  * closed the layer in the React tree only, after the trigger's own handlers.
@@ -68,8 +67,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
@@ -77,8 +86,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. */

package/dist/Layer/usePressPin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePressPin.d.ts","sourceRoot":"","sources":["../../src/Layer/usePressPin.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAKL,KAAK,UAAU,IAAI,eAAe,EAClC,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAIf,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAKnE;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAI9D;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAM3D;AAED,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,eAAe,EAAE,oBAAoB,CAAC;IACtC,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,mCAAmC;IACnC,WAAW,EAAE,OAAO,CAAC;IACrB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,sEAAsE;IACtE,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,YAAY,EAAE,iBAAiB,CAAC;IAChC,iEAAiE;IACjE,UAAU,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,eAAe,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,OAAO,CAAC;IAC1D;;;;OAIG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9C,iEAAiE;IACjE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC;IACjD;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,KAAK,EAAE,IAAI,CACT,qBAAqB,EACnB,mBAAmB,GACnB,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,GACnB,cAAc,CACjB,CAAC;CACH;AAwBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAmW1E"}
+{"version":3,"file":"usePressPin.d.ts","sourceRoot":"","sources":["../../src/Layer/usePressPin.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAKL,KAAK,UAAU,IAAI,eAAe,EAClC,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAIf,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAKzD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAI9D;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAM3D;AAED,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,eAAe,EAAE,oBAAoB,CAAC;IACtC,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,mCAAmC;IACnC,WAAW,EAAE,OAAO,CAAC;IACrB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,sEAAsE;IACtE,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,YAAY,EAAE,iBAAiB,CAAC;IAChC,iEAAiE;IACjE,UAAU,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,eAAe,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,OAAO,CAAC;IAC1D;;;;OAIG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9C,wEAAwE;IACxE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;OAIG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC;IACjD;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,KAAK,EAAE,IAAI,CACT,qBAAqB,EACnB,mBAAmB,GACnB,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,GACnB,cAAc,CACjB,CAAC;CACH;AAwBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAqZ1E"}