@astryxdesign/core 0.7.6 → 0.7.7-canary.0eb44a2

package/dist/DropdownMenu/useMenuOverflow.js

@@ -4,24 +4,44 @@
 
 /**
  * @file useMenuOverflow.ts
- * @input Menu element ref, rendered content, and open state
+ * @input Menu element ref, rendered content, open state, and optionally the
+ *   overflow its owner expects from the content alone
  * @output Returns whether the open menu overflows its block-size constraint
  * @position Shared responsive helper for DropdownMenu and DropdownMenuSubMenu
  */
-import { useCallback, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
 import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
 
-/** Detect block-axis overflow without making a fitting menu a scroll container. */
-export function useMenuOverflow(menuRef, content, isOpen) {
-  const [hasOverflow, setHasOverflow] = useState(false);
+/**
+ * Detect block-axis overflow without making a fitting menu a scroll container.
+ *
+ * `expectedOverflow` is the answer the owner can give before any measure (a
+ * long option list cannot fit). Until a measure of the same `content` says
+ * otherwise, it is the result, so the first open already renders the right
+ * class: a class that flips after the open measure restyles the whole list
+ * a second time. A measure still runs on every open and corrects a wrong
+ * guess.
+ */
+export function useMenuOverflow(menuRef, content, isOpen, expectedOverflow) {
+  // The content each measure stands for, kept only for an owner that gives
+  // an expected answer (a caller whose content is a new element on every
+  // render compares nothing); set before the measuring effects run.
+  const contentRef = useRef(null);
+  useIsomorphicLayoutEffect(() => {
+    contentRef.current = expectedOverflow === undefined ? null : content;
+  });
+  const [measured, setMeasured] = useState(null);
   const measureOverflow = useCallback(() => {
     const menu = menuRef.current;
     if (!menu) {
       return;
     }
-    const nextHasOverflow = menu.scrollHeight > menu.clientHeight + 1;
+    const hasOverflow = menu.scrollHeight > menu.clientHeight + 1;
     // eslint-disable-next-line @eslint-react/set-state-in-effect -- DOM overflow measurement controls whether this menu becomes a scroll container
-    setHasOverflow(current => current === nextHasOverflow ? current : nextHasOverflow);
+    setMeasured(current => current != null && current.hasOverflow === hasOverflow && Object.is(current.content, contentRef.current) ? current : {
+      content: contentRef.current,
+      hasOverflow
+    });
   }, [menuRef]);
   useIsomorphicLayoutEffect(() => {
     if (!isOpen) {
@@ -56,5 +76,8 @@ export function useMenuOverflow(menuRef, content, isOpen) {
       measureOverflow();
     }
   }, [content, isOpen, measureOverflow]);
-  return hasOverflow;
+  if (expectedOverflow === undefined) {
+    return measured?.hasOverflow ?? false;
+  }
+  return measured != null && Object.is(measured.content, content) ? measured.hasOverflow : expectedOverflow;
 }

package/dist/Field/PanelSearchInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PanelSearchInput.d.ts","sourceRoot":"","sources":["../../src/Field/PanelSearchInput.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAwB,KAAK,GAAG,EAAC,MAAM,OAAO,CAAC;AAEtD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAenD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAgF5C,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CACjD,SAAS,CAAC,gBAAgB,CAAC,EAC3B,UAAU,CACX;IACC,iEAAiE;IACjE,GAAG,CAAC,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAE5B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IAEnB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IAEd,kEAAkE;IAClE,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEvC,wCAAwC;IACxC,SAAS,CAAC,EAAE,KAAK,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;IAEzD,0EAA0E;IAC1E,OAAO,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;IAEpD,yEAAyE;IACzE,MAAM,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;IAEnD;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,oBAAoB,CAAC,cAAc,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,GAAG,EACH,KAAK,EACL,UAAU,EACV,WAAW,EACX,KAAK,EACL,aAAa,EACb,SAAS,EACT,OAAO,EACP,MAAM,EACN,kBAAkB,EAClB,WAAW,EACX,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,qBAAqB,+BA8EvB;yBA9Fe,gBAAgB"}
+{"version":3,"file":"PanelSearchInput.d.ts","sourceRoot":"","sources":["../../src/Field/PanelSearchInput.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAwB,KAAK,GAAG,EAAC,MAAM,OAAO,CAAC;AAEtD,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAenD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiF5C,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CACjD,SAAS,CAAC,gBAAgB,CAAC,EAC3B,UAAU,CACX;IACC,iEAAiE;IACjE,GAAG,CAAC,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAE5B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IAEnB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IAEd,kEAAkE;IAClE,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEvC,wCAAwC;IACxC,SAAS,CAAC,EAAE,KAAK,CAAC,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;IAEzD,0EAA0E;IAC1E,OAAO,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;IAEpD,yEAAyE;IACzE,MAAM,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;IAEnD;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,oBAAoB,CAAC,cAAc,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,GAAG,EACH,KAAK,EACL,UAAU,EACV,WAAW,EACX,KAAK,EACL,aAAa,EACb,SAAS,EACT,OAAO,EACP,MAAM,EACN,kBAAkB,EAClB,WAAW,EACX,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,qBAAqB,+BAmFvB;yBAnGe,gBAAgB"}

package/dist/Field/PanelSearchInput.js

@@ -47,6 +47,7 @@ import { useInteractionModalityTracking } from "../utils/interactionModality.js"
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, durationVars, easeVars, radiusVars, spacingVars, typeScaleVars, typographyVars } from "../theme/tokens.stylex.js";
+import { textEntryTraitAttributes } from "./textEntryTraits.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const styles = {
   wrapper: {
@@ -153,7 +154,13 @@ export function PanelSearchInput({
         xstyle: styles.icon
       }), /*#__PURE__*/_jsx("input", {
         ref: mergedInputRef,
-        type: "text",
+        type: "text"
+        // Autocorrect would rewrite names and identifiers.
+        ,
+        ...textEntryTraitAttributes({
+          enterKeyHint: 'search',
+          hasAutoCorrect: false
+        }),
         "aria-label": label,
         placeholder: placeholder,
         value: value,

package/dist/Field/textEntryTraits.d.ts

@@ -1,16 +1,16 @@
 /**
  * @file textEntryTraits.ts
  * @input The keyboard-trait props a text field accepts
- * @output Exports the closed value unions EnterKeyHint, InputMode and
- *   AutoCapitalize (the package entry exports these three), the fields' prop
- *   mixin TextEntryTraitProps, and textEntryTraitAttributes, which maps the
- *   props onto the native attributes of the editable element
- * @position Shared by TextInput and TextArea: the one place that says how a
- *   field tells a touch keyboard what it holds
+ * @output EnterKeyHint, InputMode and AutoCapitalize (the package entry exports
+ *   these), TextEntryTraitProps and textEntryTraitAttributes
+ * @position Shared by TextInput, TextArea and the search inputs: the one place
+ *   that says how a field tells a touch keyboard what it holds
  *
  * SYNC: When modified, update:
  * - /packages/core/src/TextInput/TextInput.tsx and TextInput.doc.mjs
  * - /packages/core/src/TextArea/TextArea.tsx and TextArea.doc.mjs
+ * - /packages/core/src/Typeahead/BaseTypeahead.tsx, Field/PanelSearchInput.tsx
+ *   and CommandPalette/CommandPaletteInput.tsx (the search inputs)
  * - /packages/core/src/Field/index.ts (type exports)
  */
 /**

package/dist/Field/textEntryTraits.js

@@ -3,16 +3,16 @@
 /**
  * @file textEntryTraits.ts
  * @input The keyboard-trait props a text field accepts
- * @output Exports the closed value unions EnterKeyHint, InputMode and
- *   AutoCapitalize (the package entry exports these three), the fields' prop
- *   mixin TextEntryTraitProps, and textEntryTraitAttributes, which maps the
- *   props onto the native attributes of the editable element
- * @position Shared by TextInput and TextArea: the one place that says how a
- *   field tells a touch keyboard what it holds
+ * @output EnterKeyHint, InputMode and AutoCapitalize (the package entry exports
+ *   these), TextEntryTraitProps and textEntryTraitAttributes
+ * @position Shared by TextInput, TextArea and the search inputs: the one place
+ *   that says how a field tells a touch keyboard what it holds
  *
  * SYNC: When modified, update:
  * - /packages/core/src/TextInput/TextInput.tsx and TextInput.doc.mjs
  * - /packages/core/src/TextArea/TextArea.tsx and TextArea.doc.mjs
+ * - /packages/core/src/Typeahead/BaseTypeahead.tsx, Field/PanelSearchInput.tsx
+ *   and CommandPalette/CommandPaletteInput.tsx (the search inputs)
  * - /packages/core/src/Field/index.ts (type exports)
  */
 

package/dist/Layer/layerClickBoundary.d.ts

@@ -2,7 +2,7 @@
  * @file layerClickBoundary.ts
  * @input React pointer, mouse, touch and click events on a layer root
  * @output Exports layerClickBoundary, the props every layer content root
- *   spreads, including the layer-root mark
+ *   spreads, including the layer-root mark; also stopInReactTree
  * @position Internal to Layer; used by useLayer's renderers and the Dialog,
  *   Drawer, Lightbox, MobileNav, BottomSheetPanel and ToastViewport roots.
  *   Not exported from the package.
@@ -21,6 +21,12 @@ declare const BOUNDARY_EVENTS: readonly ["onClick", "onAuxClick", "onDoubleClick
 type BoundaryEvent = (typeof BOUNDARY_EVENTS)[number];
 type Handler = (event: SyntheticEvent) => void;
 export type LayerClickBoundaryProps = Record<BoundaryEvent, Handler> & Readonly<Record<`data-${string}`, string>>;
+/**
+ * Stop a synthetic event at this element for the rest of the React tree only.
+ * React's dispatch asks `isPropagationStopped()` before each further
+ * listener; the native event is left alone.
+ */
+export declare function stopInReactTree(event: SyntheticEvent): void;
 /**
  * The boundary props for a layer content root. Pass the root's own props
  * (its caller's rest props and its own handlers): for each boundary event, a

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

@@ -1 +1 @@
-{"version":3,"file":"layerClickBoundary.d.ts","sourceRoot":"","sources":["../../src/Layer/layerClickBoundary.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,OAAO,CAAC;AAG1C,uDAAuD;AACvD,QAAA,MAAM,eAAe,gWAsBX,CAAC;AAEX,KAAK,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AACtD,KAAK,OAAO,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAE/C,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,GAClE,QAAQ,CAAC,MAAM,CAAC,QAAQ,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;AAa7C;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GAC1C,uBAAuB,CAkBzB"}
+{"version":3,"file":"layerClickBoundary.d.ts","sourceRoot":"","sources":["../../src/Layer/layerClickBoundary.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,OAAO,CAAC;AAG1C,uDAAuD;AACvD,QAAA,MAAM,eAAe,gWAsBX,CAAC;AAEX,KAAK,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AACtD,KAAK,OAAO,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAE/C,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,GAClE,QAAQ,CAAC,MAAM,CAAC,QAAQ,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;AAI7C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GAC1C,uBAAuB,CAkBzB"}

package/dist/Layer/layerClickBoundary.js

@@ -6,7 +6,7 @@
  * @file layerClickBoundary.ts
  * @input React pointer, mouse, touch and click events on a layer root
  * @output Exports layerClickBoundary, the props every layer content root
- *   spreads, including the layer-root mark
+ *   spreads, including the layer-root mark; also stopInReactTree
  * @position Internal to Layer; used by useLayer's renderers and the Dialog,
  *   Drawer, Lightbox, MobileNav, BottomSheetPanel and ToastViewport roots.
  *   Not exported from the package.
@@ -30,7 +30,7 @@ const returnTrue = () => true;
  * React's dispatch asks `isPropagationStopped()` before each further
  * listener; the native event is left alone.
  */
-function stopInReactTree(event) {
+export function stopInReactTree(event) {
   event.isPropagationStopped = returnTrue;
 }
 

package/dist/Layer/usePressPin.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @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
+ * @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.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Tooltip/useTooltip.tsx
+ * - /packages/core/src/Layer/usePressPin.test.tsx
+ */
+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.
+ */
+export type LayerTriggerBehavior = 'adaptive' | 'hover' | '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.
+ * No clickable row, card, or container around the trigger then receives it,
+ * and document and window listeners still do. An anchored trigger has no
+ * wrapper, so a plain `onClick` element around it still receives the press.
+ */
+export declare function stopPressPinClick(event: ReactMouseEvent): void;
+/** Whether presses on this element can pin a layer: a button, by role. */
+export declare function isPressPinTrigger(element: Element): boolean;
+export interface UsePressPinOptions {
+    /** The layer's `triggerBehavior`. */
+    triggerBehavior: LayerTriggerBehavior;
+    /** Whether the layer's triggers are live at all. */
+    isEnabled: boolean;
+    /** The controlled open value, or `undefined` when uncontrolled. */
+    isOpen: boolean | undefined;
+    /** Whether the layer shows now. */
+    isLayerOpen: boolean;
+    /** The layer surface's element id. */
+    layerId: string;
+    /** The component its development warning names. */
+    component: string;
+    /** Shows the layer now, with no delay. */
+    show: () => void;
+    /** Hides the layer now. */
+    hide: () => void;
+    /** Reports a controlled layer's toggled value without changing it. */
+    report: (isOpen: boolean) => void;
+    /** The layer's `label`: a press that pins the layer says it once, in place of its text. */
+    label?: string;
+    /** The layer's `touchTrigger`, which decides taps only under `adaptive`. */
+    touchTrigger: LayerTouchTrigger;
+    /** The host's trigger element, which the touch trigger reads. */
+    triggerRef: RefObject<HTMLElement | null>;
+}
+export interface UsePressPinReturn {
+    /** Whether presses on this trigger pin the layer: toggle mode and a button. */
+    isToggleTrigger: (element: HTMLElement | null) => boolean;
+    /**
+     * Whether a press holds the layer open now: a pin on a wired trigger while
+     * the layer shows, or a controlled layer's open value. The host's hover and
+     * focus hides ask it.
+     */
+    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. */
+    unpin: () => void;
+    /**
+     * 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
+     * trigger, and a host calls it for the layer's own content.
+     */
+    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`.
+     */
+    isPinShown: boolean;
+    /** The layer's touch trigger (useTouchTriggerInternal), wired to the pin. */
+    touch: Pick<UseTouchTriggerReturn, 'isTouchPointerRef' | 'isTouchInteraction' | 'handlePointerEnter' | 'handlePointerDown' | 'clearTapOpen'>;
+}
+/**
+ * Pins a hover layer open on a press of a button trigger, under
+ * `triggerBehavior="toggle"`. The same press closes it, and so do Escape, a
+ * press or scroll outside, and focus that leaves the trigger and the layer.
+ * The press stops at the trigger. A trigger that is not a button gets a
+ * development warning and keeps tap-only opening.
+ */
+export declare function usePressPin(options: UsePressPinOptions): UsePressPinReturn;
+//# sourceMappingURL=usePressPin.d.ts.map

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

@@ -0,0 +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"}

package/dist/Layer/usePressPin.js

@@ -0,0 +1,365 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @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
+ * @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.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Tooltip/useTooltip.tsx
+ * - /packages/core/src/Layer/usePressPin.test.tsx
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useAnnounce } from "../hooks/useAnnounce.js";
+import { useDevWarning } from "../hooks/useDevWarning.js";
+import { stopInReactTree } from "./layerClickBoundary.js";
+import { useTouchTriggerInternal } 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.
+ */
+
+/** The clicks a press pin answered, so the wrapper can stop them (`stopPressPinClick`). */
+const pressPinClicks = new WeakSet();
+
+/**
+ * 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.
+ * No clickable row, card, or container around the trigger then receives it,
+ * and document and window listeners still do. An anchored trigger has no
+ * wrapper, so a plain `onClick` element around it still receives the press.
+ */
+export function stopPressPinClick(event) {
+  if (pressPinClicks.has(event.nativeEvent)) {
+    stopInReactTree(event);
+  }
+}
+
+/** Whether presses on this element can pin a layer: a button, by role. */
+export function isPressPinTrigger(element) {
+  const role = element.getAttribute('role');
+  if (role != null && role !== '') {
+    return role === 'button';
+  }
+  return element.tagName === 'BUTTON';
+}
+function restoreAttribute(element, name, value) {
+  if (value == null) {
+    element.removeAttribute(name);
+  } else {
+    element.setAttribute(name, value);
+  }
+}
+function writeAttribute(element, name, value) {
+  if (element.getAttribute(name) !== value) {
+    restoreAttribute(element, name, value);
+  }
+}
+
+/**
+ * Pins a hover layer open on a press of a button trigger, under
+ * `triggerBehavior="toggle"`. The same press closes it, and so do Escape, a
+ * press or scroll outside, and focus that leaves the trigger and the layer.
+ * The press stops at the trigger. A trigger that is not a button gets a
+ * development warning and keeps tap-only opening.
+ */
+export function usePressPin(options) {
+  const {
+    triggerBehavior,
+    isOpen,
+    isLayerOpen,
+    layerId
+  } = options;
+  const isToggleMode = triggerBehavior === 'toggle';
+
+  // DOM listeners read the latest options and announcer through refs. The
+  // announcer is the layer's own: inside a modal, the modal's region.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const announce = useAnnounce();
+  const announceRef = useRef(announce);
+  announceRef.current = announce;
+  const isPinnedRef = useRef(false);
+  const [isPinned, setIsPinnedState] = useState(false);
+  const setPinned = useCallback(next => {
+    isPinnedRef.current = next;
+    setIsPinnedState(next);
+  }, []);
+
+  // The last offered element lets a `triggerBehavior` change rewire it.
+  const triggerRef = useRef(null);
+  const offeredRef = useRef(null);
+  // A primitive: re-attaching the same trigger renders nothing.
+  const [offeredKind, setOfferedKind] = useState('none');
+  // The trigger's own aria-expanded and aria-controls, restored on unwiring.
+  const ownStateRef = useRef(null);
+
+  // The touch trigger's outside dismissal (a press or scroll outside) closes
+  // a pinned layer through the pin, so the pin drops with it.
+  const hideFromTouch = useCallback(() => {
+    const current = optionsRef.current;
+    if (current.triggerBehavior === 'toggle' && triggerRef.current != null) {
+      if (current.isOpen !== undefined) {
+        current.report(false);
+        return;
+      }
+      if (isPinnedRef.current) {
+        setPinned(false);
+      }
+    }
+    current.hide();
+  }, [setPinned]);
+  const {
+    isTouchPointerRef,
+    isTouchInteraction,
+    handlePointerEnter,
+    handlePointerDown,
+    clearTapOpen,
+    armOutsideDismiss
+  } = useTouchTriggerInternal({
+    touchTrigger: isToggleMode ? 'tap' : triggerBehavior === 'hover' ? 'none' : options.touchTrigger,
+    isEnabled: options.isEnabled,
+    isControlled: isOpen !== undefined,
+    isOpen: isLayerOpen,
+    layerId,
+    triggerRef: options.triggerRef,
+    show: options.show,
+    hide: hideFromTouch
+  });
+  const isToggleTrigger = useCallback(element => optionsRef.current.triggerBehavior === 'toggle' && element != null && isPressPinTrigger(element), []);
+  const close = useCallback(() => {
+    const current = optionsRef.current;
+    clearTapOpen();
+    if (current.isOpen !== undefined) {
+      current.report(false);
+      return;
+    }
+    setPinned(false);
+    current.hide();
+  }, [setPinned, clearTapOpen]);
+  const announceName = useCallback(() => {
+    const current = optionsRef.current;
+    const name = current.label?.trim() ?? '';
+    if (name !== '') {
+      announceRef.current(name, 'polite');
+    }
+  }, []);
+  const toggle = useCallback(() => {
+    const current = optionsRef.current;
+    if (current.isOpen !== undefined) {
+      if (!current.isOpen) {
+        armOutsideDismiss();
+        announceName();
+      } else {
+        clearTapOpen();
+      }
+      current.report(!current.isOpen);
+      return;
+    }
+    // A pin counts only while its layer shows; a closed layer pins again.
+    if (isPinnedRef.current && current.isLayerOpen) {
+      setPinned(false);
+      clearTapOpen();
+      current.hide();
+    } else {
+      setPinned(true);
+      current.show();
+      armOutsideDismiss();
+      announceName();
+    }
+  }, [setPinned, announceName, armOutsideDismiss, clearTapOpen]);
+
+  // A non-native button gets no click from the browser for a key. So Enter
+  // presses it on keydown, and Space on keyup, as on a native button. A click
+  // with no pointer (`detail` 0) while Space is down, or in a key press's
+  // task, is that same press.
+  const keyPressedRef = useRef(false);
+  const spaceHeldRef = useRef(false);
+  const handlePress = useCallback(event => {
+    const current = optionsRef.current;
+    if (!current.isEnabled || current.triggerBehavior !== 'toggle') {
+      return;
+    }
+    // The press stops at its trigger: no label control, link, or submit.
+    event.preventDefault();
+    pressPinClicks.add(event);
+    if (event.detail === 0 && (keyPressedRef.current || spaceHeldRef.current)) {
+      return;
+    }
+    toggle();
+  }, [toggle]);
+  const pressFromKey = useCallback(() => {
+    keyPressedRef.current = true;
+    setTimeout(() => {
+      keyPressedRef.current = false;
+    }, 0);
+    toggle();
+  }, [toggle]);
+  const handleKeyDown = useCallback(event => {
+    const current = optionsRef.current;
+    if (!current.isEnabled || current.triggerBehavior !== 'toggle' || event.isComposing || event.key !== 'Enter' && event.key !== ' ') {
+      return;
+    }
+    // The press replaces the key's own action, such as a page scroll on Space.
+    event.preventDefault();
+    if (event.repeat) {
+      return;
+    }
+    if (event.key === ' ') {
+      spaceHeldRef.current = true;
+      return;
+    }
+    pressFromKey();
+  }, [pressFromKey]);
+  // Only a Space that went down on the trigger presses it when it comes up.
+  const handleKeyUp = useCallback(event => {
+    if (event.key !== ' ' || !spaceHeldRef.current) {
+      return;
+    }
+    spaceHeldRef.current = false;
+    const current = optionsRef.current;
+    if (!current.isEnabled || current.triggerBehavior !== 'toggle') {
+      return;
+    }
+    pressFromKey();
+  }, [pressFromKey]);
+  const isHeldOpen = useCallback(() => {
+    const current = optionsRef.current;
+    if (current.triggerBehavior !== 'toggle' || triggerRef.current == null) {
+      return false;
+    }
+    return current.isOpen !== undefined ? current.isOpen && current.isLayerOpen : isPinnedRef.current && current.isLayerOpen;
+  }, []);
+  const handleFocusLeave = useCallback(event => {
+    // A Space that comes up after focus left presses nothing.
+    spaceHeldRef.current = false;
+    if (!isHeldOpen()) {
+      return false;
+    }
+    const next = event.relatedTarget;
+    const trigger = triggerRef.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;
+    if (view == null || !(next instanceof view.Node)) {
+      return true;
+    }
+    const surface = trigger?.ownerDocument.getElementById(optionsRef.current.layerId) ?? null;
+    if (trigger?.contains(next) === true || surface?.contains(next) === true) {
+      return true;
+    }
+    close();
+    return true;
+  }, [isHeldOpen, close]);
+  const unwire = useCallback(() => {
+    const previous = triggerRef.current;
+    if (previous == null) {
+      return;
+    }
+    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);
+      restoreAttribute(previous, 'aria-controls', own.controls);
+    }
+    ownStateRef.current = null;
+    triggerRef.current = null;
+  }, [handlePress, handleKeyDown, handleKeyUp, handleFocusLeave]);
+
+  // The element and mode last settled; the same pair again does nothing.
+  const settledRef = useRef(null);
+  const wire = useCallback(element => {
+    const current = optionsRef.current;
+    const settled = settledRef.current;
+    if (settled != null && settled.element === element && settled.mode === current.triggerBehavior) {
+      return;
+    }
+    settledRef.current = {
+      element,
+      mode: current.triggerBehavior
+    };
+    unwire();
+    if (element == null || current.triggerBehavior !== 'toggle') {
+      return;
+    }
+    if (!isPressPinTrigger(element)) {
+      return;
+    }
+    element.addEventListener('click', handlePress);
+    if (element.tagName !== 'BUTTON') {
+      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')
+    };
+    triggerRef.current = element;
+  }, [unwire, handlePress, handleKeyDown, handleKeyUp, handleFocusLeave]);
+  const attach = useCallback(element => {
+    offeredRef.current = element;
+    // Hosts detach and re-attach within one commit, so a detach is not kept.
+    if (element != null) {
+      setOfferedKind(isPressPinTrigger(element) ? 'button' : 'other');
+    }
+    wire(element);
+  }, [wire]);
+  const isWired = isToggleMode && offeredKind === 'button';
+  useDevWarning(options.component, '`triggerBehavior="toggle"` pins only a button trigger (a <button> or role="button"); this trigger keeps tap-only opening.', isToggleMode && offeredKind === 'other');
+
+  // A later `triggerBehavior` change rewires here; the ref does not rerun.
+  useEffect(() => {
+    wire(offeredRef.current);
+  }, [triggerBehavior, wire]);
+  const unpin = useCallback(() => {
+    if (isPinnedRef.current) {
+      setPinned(false);
+    }
+  }, [setPinned]);
+
+  // Each path that hides a pinned layer drops the pin itself, so a layer that
+  // does not show is never reported expanded.
+  const isExpanded = (isOpen !== undefined ? isOpen : isPinned) && isLayerOpen;
+
+  // The trigger's aria-expanded and aria-controls follow the pin. No deps: a
+  // host can swap the trigger on any commit; equal values are not rewritten.
+  useEffect(() => {
+    const trigger = triggerRef.current;
+    if (!isToggleMode || !isWired || trigger == null) {
+      return;
+    }
+    writeAttribute(trigger, 'aria-expanded', isExpanded ? 'true' : 'false');
+    writeAttribute(trigger, 'aria-controls', isLayerOpen ? layerId : null);
+  });
+  const isPinShown = isToggleMode && isWired && isExpanded;
+  return {
+    isToggleTrigger,
+    isHeldOpen,
+    attach,
+    unpin,
+    handleFocusLeave,
+    isPinShown,
+    touch: {
+      isTouchPointerRef,
+      isTouchInteraction,
+      handlePointerEnter,
+      handlePointerDown,
+      clearTapOpen
+    }
+  };
+}