@astryxdesign/core 0.7.6 → 0.7.7-canary.1d04d40

package/src/Layer/usePressPin.ts

@@ -0,0 +1,481 @@
+// 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,
+  type MouseEvent as ReactMouseEvent,
+  type RefObject,
+} from 'react';
+import {useAnnounce} from '../hooks/useAnnounce';
+import {useDevWarning} from '../hooks/useDevWarning';
+import {stopInReactTree} from './layerClickBoundary';
+import {
+  useTouchTriggerInternal,
+  type LayerTouchTrigger,
+  type UseTouchTriggerReturn,
+} from './useTouchTrigger';
+
+/**
+ * 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 clicks a press pin answered, so the wrapper can stop them (`stopPressPinClick`). */
+const pressPinClicks = new WeakSet<Event>();
+
+/**
+ * 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: ReactMouseEvent): void {
+  if (pressPinClicks.has(event.nativeEvent)) {
+    stopInReactTree(event);
+  }
+}
+
+/** Whether presses on this element can pin a layer: a button, by role. */
+export function isPressPinTrigger(element: Element): boolean {
+  const role = element.getAttribute('role');
+  if (role != null && role !== '') {
+    return role === 'button';
+  }
+  return element.tagName === 'BUTTON';
+}
+
+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'
+  >;
+}
+
+function restoreAttribute(
+  element: HTMLElement,
+  name: string,
+  value: string | null,
+): void {
+  if (value == null) {
+    element.removeAttribute(name);
+  } else {
+    element.setAttribute(name, value);
+  }
+}
+
+function writeAttribute(
+  element: HTMLElement,
+  name: string,
+  value: string | null,
+): void {
+  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: UsePressPinOptions): UsePressPinReturn {
+  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: boolean) => {
+    isPinnedRef.current = next;
+    setIsPinnedState(next);
+  }, []);
+
+  // Refs hold the wired trigger and last offered element for a later rewire.
+  const triggerRef = 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'>(
+    'none',
+  );
+  // The trigger's own aria-expanded and aria-controls, restored on unwiring.
+  const ownStateRef = useRef<{
+    expanded: string | null;
+    controls: string | null;
+  } | null>(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: HTMLElement | null) =>
+      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]);
+
+  // Enter or Space presses a non-native button, which gets no click from the
+  // browser. A same-task click from its own key handler is that press.
+  const keyPressedRef = useRef(false);
+  const handlePress = useCallback(
+    (event: MouseEvent) => {
+      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 (keyPressedRef.current && event.detail === 0) {
+        return;
+      }
+      toggle();
+    },
+    [toggle],
+  );
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      const current = optionsRef.current;
+      if (
+        !current.isEnabled ||
+        current.triggerBehavior !== 'toggle' ||
+        event.repeat ||
+        event.isComposing ||
+        (event.key !== 'Enter' && event.key !== ' ')
+      ) {
+        return;
+      }
+      event.preventDefault();
+      keyPressedRef.current = true;
+      setTimeout(() => {
+        keyPressedRef.current = false;
+      }, 0);
+      toggle();
+    },
+    [toggle],
+  );
+
+  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: FocusEvent) => {
+      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('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, handleFocusLeave]);
+
+  // The element and mode last settled; the same pair again does nothing.
+  const settledRef = useRef<{
+    element: HTMLElement | null;
+    mode: LayerTriggerBehavior;
+  } | null>(null);
+
+  const wire = useCallback(
+    (element: HTMLElement | null) => {
+      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);
+      }
+      // 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, handleFocusLeave],
+  );
+
+  const attach = useCallback(
+    (element: HTMLElement | null) => {
+      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,
+    },
+  };
+}

package/src/Layer/useTouchTrigger.ts

@@ -7,7 +7,8 @@
  * @input Touch trigger mode, layer open state, trigger ref, show/hide callbacks
  * @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type,
  *   tapLandsOnDisabledControl, TOUCH_POINTER_TYPES and useTapStop (internal:
- *   not re-exported from index)
+ *   not re-exported from index). Also useTouchTriggerInternal, with the
+ *   outside dismissal's arm for the press pin (Core-internal).
  * @position Layer hook; shared touch behavior for useTooltip and useHoverCard
  *
  * SYNC: When modified, update:
@@ -281,6 +282,21 @@ export interface UseTouchTriggerReturn {
   clearTapOpen: () => void;
 }
 
+/**
+ * useTouchTrigger's return plus the outside dismissal's arm, for Core's own
+ * press pin (usePressPin). Not exported from the Layer entry point.
+ *
+ * @internal
+ */
+export interface UseTouchTriggerInternalReturn extends UseTouchTriggerReturn {
+  /**
+   * Arms the outside dismissal a tap-open gets: a press that lifts outside
+   * the trigger and the layer, or a scroll that starts there, hides it. A
+   * press pin arms it too.
+   */
+  armOutsideDismiss: () => void;
+}
+
 /**
  * Touch behavior shared by the hover layers.
  *
@@ -301,6 +317,25 @@ export interface UseTouchTriggerReturn {
 export function useTouchTrigger(
   options: UseTouchTriggerOptions,
 ): UseTouchTriggerReturn {
+  const touch = useTouchTriggerInternal(options);
+  return {
+    isTouchPointerRef: touch.isTouchPointerRef,
+    isTouchInteraction: touch.isTouchInteraction,
+    handlePointerEnter: touch.handlePointerEnter,
+    handlePointerDown: touch.handlePointerDown,
+    clearTapOpen: touch.clearTapOpen,
+  };
+}
+
+/**
+ * useTouchTrigger, plus the outside dismissal's arm that a press pin uses to
+ * close on a press or scroll outside.
+ *
+ * @internal
+ */
+export function useTouchTriggerInternal(
+  options: UseTouchTriggerOptions,
+): UseTouchTriggerInternalReturn {
   const {
     touchTrigger,
     isEnabled,
@@ -503,5 +538,6 @@ export function useTouchTrigger(
     handlePointerEnter,
     handlePointerDown,
     clearTapOpen: disarmOutsideDismiss,
+    armOutsideDismiss,
   };
 }

package/src/Link/Link.tsx

@@ -98,6 +98,9 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     borderStyle: 'none',
     padding: 0,
+    // Browsers centre a button's text; a wrapped label lines up as an
+    // anchor's does.
+    textAlign: 'inherit',
     pointerEvents: 'auto',
     position: 'relative',
   },

package/src/ProgressBar/ProgressBar.doc.mjs

@@ -160,7 +160,7 @@ export const docs = {
   usage: {
     anatomy,
     description:
-      "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.",
+      "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting. Under a finger a new value animates as on iOS: linearly, in proportion to how far it moves (a full track takes one second at the theme's default tempo), and the fill keeps a minimum visible length above zero.",
     bestPractices: [
       {
         guidance: true,
@@ -304,7 +304,7 @@ export const docsZh = {
   usage: {
     anatomy,
     description:
-      "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.",
+      "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting. Under a finger a new value animates as on iOS: linearly, in proportion to how far it moves (a full track takes one second at the theme's default tempo), and the fill keeps a minimum visible length above zero.",
     bestPractices: [
       {
         guidance: true,
@@ -347,7 +347,7 @@ export const docsDense = {
   usage: {
     anatomy,
     description:
-      "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.",
+      "A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting. Under a finger a new value animates as on iOS: linearly, in proportion to how far it moves (a full track takes one second at the theme's default tempo), and the fill keeps a minimum visible length above zero.",
     bestPractices: [
       {
         guidance: true,