@astryxdesign/core 0.7.7 → 0.7.8-canary.0d54fd3

package/src/Layer/usePressPin.ts

@@ -1,510 +0,0 @@
-// 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 `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' | '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);
-  }, []);
-
-  // The last offered element lets a `triggerBehavior` change rewire it.
-  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' : 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]);
-
-  // 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: 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 (
-        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: KeyboardEvent) => {
-      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: KeyboardEvent) => {
-      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: FocusEvent) => {
-      // 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<{
-    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);
-        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: 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,
-    'A press-to-pin tooltip 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/internal/touch-sheet.ts

@@ -1,21 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-/**
- * @file touch-sheet.ts
- * @input The touch sheets' shared confirmation, search-drag dismissal and
- *   draft rules
- * @output `@astryxdesign/core/internal/touch-sheet`: SheetConfirmation,
- *   useDismissSearchOnTouchDrag, hasSameSelection and nameSheetDraftChange,
- *   re-exported by name for Lab's sheets
- * @position An internal entry reserved for Astryx's own packages:
- *   undocumented, outside the public API and its compatibility promise,
- *   versioned in lockstep with Core, and allowed only in Core and Lab by the
- *   `@astryx/no-core-internal-import` lint rule. Core components import the
- *   same modules by relative path. Named re-exports only.
- *
- * SYNC: When modified, update scripts/sync-exports.js.
- */
-export {SheetConfirmation} from './SheetConfirmation';
-export type {SheetConfirmationProps} from './SheetConfirmation';
-export {useDismissSearchOnTouchDrag} from './useDismissSearchOnTouchDrag';
-export {hasSameSelection, nameSheetDraftChange} from './sheetDraft';
-export type {SheetDraftChange} from './sheetDraft';