Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
14.6 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file useCommentThreadDismissal.ts
 * @input Uses React, the shared layer dismissal stack (useLayerDismissal), the
 *   theme's motion and spacing tokens, the translator, and the Comments
 *   controller's reply and edit drafts
 * @output Exports useCommentThreadDismissal, unsavedDraftOf, and their types
 * @position Light dismissal for a CommentThread whose host passes `onDismiss`.
 *   A press outside the thread and an Escape no nested layer claimed both
 *   request dismissal; while the thread holds an unsaved draft, the first
 *   request shakes the thread, returns focus to the draft, and announces
 *   instead, and the next consecutive one dismisses.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/lab/src/Comments/CommentThread.tsx
 * - /packages/lab/src/Comments/CommentThread.doc.mjs
 * - /packages/lab/src/Comments/CommentThread.test.tsx
 * - /packages/core/locales/en.json (@astryx.comments.unsavedDraft)
 *
 * ## Why the thread owns the outside press
 *
 * A host surface with native light dismiss (`popover="auto"`) closes before
 * script can veto it, so nothing can keep it open for a draft. The host turns
 * its own light and Escape dismissal off and hands the decision to the thread
 * through `onDismiss`.
 *
 * ## Inside versus outside
 *
 * React synthetic events bubble through portals, so the thread root's
 * pointer-down capture handler sees every press inside the thread, including
 * presses in layers it opened (the emoji picker, typeahead and action menus,
 * the delete and history dialogs) wherever they render. It marks that event;
 * the document listener, which runs after React's root listener, judges any
 * unmarked press as outside. Presses on the host surface around the thread
 * (its padding, its fallback close control) are inside too.
 *
 * The press acts on its pointer-up, as native light dismiss does, so a touch
 * that becomes a scroll (`pointercancel`) never dismisses.
 *
 * ## One layer at a time
 *
 * The thread registers on the shared layer stack, deeper than its host, and
 * wraps its content so layers it opens register deeper still. An Escape goes
 * to the top-most layer only, and an outside press counts only while the
 * thread is that layer: with the emoji picker open, the picker's own light
 * dismiss takes the press and the thread ignores it.
 */

import {
  useEffect,
  useLayoutEffect,
  useRef,
  type PointerEvent as ReactPointerEvent,
  type RefObject,
} from 'react';
import type {AnnouncePoliteness} from '@astryxdesign/core/hooks';
import {useTranslator} from '@astryxdesign/core/i18n';
import {useLayerDismissal} from '@astryxdesign/core/Layer';
import {useTheme} from '@astryxdesign/core/theme';
import type {CommentsContextValue} from './CommentsContext';
import {commentAnchorId, replyComposerId} from './utils';

/** A reply or edit holding text the viewer would lose on dismissal. */
export type UnsavedDraft =
  | {kind: 'reply'; parentId: string; signature: string}
  | {kind: 'edit'; commentId: string; signature: string};

/**
 * The thread's unsaved draft, derived from the controller's state: a reply
 * holding more than its seeded mention, or an edit whose text differs from
 * the saved body. Whitespace alone is never a draft.
 */
export function unsavedDraftOf({
  replyTarget,
  replyDraft,
  editTarget,
}: Pick<
  CommentsContextValue,
  'replyTarget' | 'replyDraft' | 'editTarget'
>): UnsavedDraft | null {
  if (
    editTarget != null &&
    editTarget.value.trim() !== editTarget.comment.body.trim()
  ) {
    return {
      kind: 'edit',
      commentId: editTarget.comment.id,
      signature: `edit:${editTarget.comment.id}:${editTarget.value}`,
    };
  }
  if (replyTarget != null) {
    const typed = replyDraft.trim();
    if (typed !== '' && typed !== (replyTarget.seed ?? '').trim()) {
      return {
        kind: 'reply',
        parentId: replyTarget.parentId,
        signature: `reply:${replyTarget.parentId}:${replyDraft}`,
      };
    }
  }
  return null;
}

type RequestOutcome = 'dismissed' | 'guarded';

export interface CommentThreadDismissalOptions {
  /** The host's dismissal; `undefined` turns the whole behavior off. */
  onDismiss: (() => void) | undefined;
  /** The thread root: the boundary, the shake target, and the stack container. */
  rootRef: RefObject<HTMLElement | null>;
  /** The draft a dismissal would discard, derived during render. */
  draft: UnsavedDraft | null;
  /** The controller's announcer. */
  announce: (message: string, politeness?: AnnouncePoliteness) => void;
}

export interface CommentThreadDismissalReturn {
  /** Whether the thread owns its dismissal, so its content nests a layer. */
  isEnabled: boolean;
  /** The root's pointer-down capture handler: marks the press as inside. */
  onRootPointerDownCapture: (event: ReactPointerEvent<HTMLElement>) => void;
}

const DRAFT_INPUT_SELECTOR = [
  '[contenteditable="true"]',
  '[role="textbox"]',
  'textarea',
  'input:not([type="hidden"]):not([type="file"])',
].join(', ');

const DEFAULT_SHAKE_DURATION_MS = 410;
const DEFAULT_SHAKE_DISTANCE = '4px';

function parseDuration(value: string | undefined): number | null {
  const normalized = value?.trim() ?? '';
  const amount = Number.parseFloat(normalized);
  if (!Number.isFinite(amount)) {
    return null;
  }
  if (normalized.endsWith('ms')) {
    return amount;
  }
  return normalized.endsWith('s') ? amount * 1000 : null;
}

/** The top-layer host surface the thread renders in, such as a Popover. */
function hostSurfaceOf(root: HTMLElement): HTMLElement | null {
  return root.parentElement?.closest<HTMLElement>('[popover]') ?? null;
}

/** The control that toggles `host`, found through its `aria-controls`. */
function hostTriggerOf(doc: Document, host: HTMLElement): Element | null {
  if (host.id === '') {
    return null;
  }
  for (const element of doc.querySelectorAll('[aria-controls]')) {
    if (
      element.getAttribute('aria-controls')?.split(/\s+/).includes(host.id) ===
      true
    ) {
      return element;
    }
  }
  return null;
}

/**
 * Swallow the next `type` event of this gesture when `owns` its target. Lets
 * go at the next press or key so it can never reach a later gesture.
 */
function claimNext(
  doc: Document,
  type: 'mousedown' | 'click',
  owns: (target: EventTarget | null) => boolean,
): void {
  const release = () => {
    doc.removeEventListener(type, claim, true);
    doc.removeEventListener('pointerdown', release, true);
    doc.removeEventListener('keydown', release, true);
  };
  const claim = (event: Event) => {
    release();
    if (owns(event.target)) {
      event.preventDefault();
      event.stopPropagation();
    }
  };
  doc.addEventListener(type, claim, true);
  doc.addEventListener('pointerdown', release, true);
  doc.addEventListener('keydown', release, true);
}

/** Focus the draft's input, keeping the viewer's caret or landing after the text. */
function focusDraftInput(root: HTMLElement, draft: UnsavedDraft): void {
  const doc = root.ownerDocument;
  const region = doc.getElementById(
    draft.kind === 'reply'
      ? replyComposerId(draft.parentId)
      : commentAnchorId(draft.commentId),
  );
  let input: HTMLElement | null = null;
  for (const candidate of region?.querySelectorAll<HTMLElement>(
    DRAFT_INPUT_SELECTOR,
  ) ?? []) {
    // A layer the composer opened (the picker's search field) is not the draft.
    const layer = candidate.closest('[popover], [role="dialog"]');
    if (layer == null || !region?.contains(layer)) {
      input = candidate;
      break;
    }
  }
  if (input == null) {
    root.focus();
    return;
  }
  const selection = doc.getSelection();
  const existing =
    selection != null &&
    selection.rangeCount > 0 &&
    input.contains(selection.getRangeAt(0).commonAncestorContainer)
      ? selection.getRangeAt(0).cloneRange()
      : null;
  input.focus();
  if (selection == null || input.getAttribute('contenteditable') !== 'true') {
    return;
  }
  // A bare focus() collapses an editable's caret to its start; restore the
  // viewer's caret, or land after the draft.
  let range = existing;
  if (range == null) {
    range = doc.createRange();
    range.selectNodeContents(input);
    range.collapse(false);
  }
  selection.removeAllRanges();
  selection.addRange(range);
}

function prefersReducedMotion(element: HTMLElement): boolean {
  return (
    element.ownerDocument.defaultView?.matchMedia?.(
      '(prefers-reduced-motion: reduce)',
    ).matches === true
  );
}

/**
 * Own light dismissal for a CommentThread: outside presses and unclaimed
 * Escape presses request it, and an unsaved draft turns the first request
 * into a shake, a focus move, and a polite announcement.
 */
export function useCommentThreadDismissal({
  onDismiss,
  rootRef,
  draft,
  announce,
}: CommentThreadDismissalOptions): CommentThreadDismissalReturn {
  const t = useTranslator();
  const {tokens} = useTheme();
  const isEnabled = onDismiss != null;
  // The draft the last request guarded. The next request dismisses only while
  // the draft still matches it; an edit or a press inside clears it.
  const guardedSignatureRef = useRef<string | null>(null);
  // The pointer-down the root last saw, compared by identity so a press whose
  // native propagation stopped short of the document cannot leak forward.
  const insidePressRef = useRef<Event | null>(null);
  const shakeRef = useRef<Animation | null>(null);

  const shake = (root: HTMLElement) => {
    shakeRef.current?.cancel();
    shakeRef.current = null;
    const duration =
      parseDuration(tokens['--duration-medium']) ?? DEFAULT_SHAKE_DURATION_MS;
    if (
      duration <= 0 ||
      typeof root.animate !== 'function' ||
      prefersReducedMotion(root)
    ) {
      return;
    }
    // Symmetric about the resting position, so it reads the same in RTL.
    const distance = tokens['--spacing-1'] ?? DEFAULT_SHAKE_DISTANCE;
    const at = (factor: number) => ({
      transform: `translateX(calc(${distance} * ${factor}))`,
    });
    try {
      const animation = root.animate(
        [at(0), at(-1), at(1), at(-0.5), at(0.5), at(0)],
        {duration, easing: 'ease-in-out', composite: 'add'},
      );
      shakeRef.current = animation;
      const forget = () => {
        if (shakeRef.current === animation) {
          shakeRef.current = null;
        }
      };
      animation.addEventListener('finish', forget);
      animation.addEventListener('cancel', forget);
    } catch {
      // Motion is progressive enhancement; focus and the announcement remain.
    }
  };

  const request = (): RequestOutcome => {
    if (draft == null || guardedSignatureRef.current === draft.signature) {
      guardedSignatureRef.current = null;
      onDismiss?.();
      return 'dismissed';
    }
    guardedSignatureRef.current = draft.signature;
    const root = rootRef.current;
    if (root != null) {
      shake(root);
      focusDraftInput(root, draft);
    }
    announce(t('@astryx.comments.unsavedDraft'), 'polite');
    return 'guarded';
  };

  // The document listeners run outside render and reach the latest draft
  // through this ref, as the composer's own listeners do. The ref is written
  // at commit: a render React discards, as a suspended transition does, must
  // not leave its draft for the listeners.
  const wouldGuard = () =>
    draft != null && guardedSignatureRef.current !== draft.signature;
  const latestRef = useRef<{
    request: () => RequestOutcome;
    wouldGuard: () => boolean;
  } | null>(null);
  // Syncs the document listeners' draft with the committed render.
  useLayoutEffect(() => {
    latestRef.current = {request, wouldGuard};
  });

  const {shouldDismissOnCloseRequest} = useLayerDismissal({
    isActive: isEnabled,
    onDismiss: () => void latestRef.current?.request(),
    getContainer: () => rootRef.current,
  });

  // External subscription: outside presses on the thread's document.
  useEffect(() => {
    if (!isEnabled) {
      return;
    }
    const doc = rootRef.current?.ownerDocument ?? document;
    let pending: {pointerId: number; trigger: Element | null} | null = null;

    const handlePointerDown = (event: PointerEvent) => {
      pending = null;
      const insidePress = insidePressRef.current;
      insidePressRef.current = null;
      if (insidePress === event || !event.isPrimary || event.button !== 0) {
        return;
      }
      const root = rootRef.current;
      const target = event.target;
      if (root == null || !(target instanceof Node) || root.contains(target)) {
        return;
      }
      const host = hostSurfaceOf(root);
      if (host?.contains(target) === true) {
        return;
      }
      // A layer above the thread (an open picker or menu) takes this press
      // through its own light dismiss.
      if (!shouldDismissOnCloseRequest()) {
        return;
      }
      const trigger = host == null ? null : hostTriggerOf(doc, host);
      pending = {
        pointerId: event.pointerId,
        trigger: trigger?.contains(target) === true ? trigger : null,
      };
      // A guarded press keeps focus and selection where they are.
      if (latestRef.current?.wouldGuard() === true) {
        claimNext(doc, 'mousedown', () => true);
      }
    };

    const handlePointerUp = (event: PointerEvent) => {
      if (pending == null || event.pointerId !== pending.pointerId) {
        return;
      }
      const {trigger} = pending;
      pending = null;
      if (latestRef.current?.request() === 'guarded') {
        // The press was spent on the warning; it activates nothing.
        claimNext(doc, 'click', () => true);
      } else if (trigger != null) {
        // The host's trigger would reopen the surface this press just closed.
        claimNext(
          doc,
          'click',
          target => target instanceof Node && trigger.contains(target),
        );
      }
    };

    const handlePointerCancel = (event: PointerEvent) => {
      if (pending?.pointerId === event.pointerId) {
        pending = null;
      }
    };

    doc.addEventListener('pointerdown', handlePointerDown);
    doc.addEventListener('pointerup', handlePointerUp, true);
    doc.addEventListener('pointercancel', handlePointerCancel, true);
    return () => {
      doc.removeEventListener('pointerdown', handlePointerDown);
      doc.removeEventListener('pointerup', handlePointerUp, true);
      doc.removeEventListener('pointercancel', handlePointerCancel, true);
    };
  }, [isEnabled, rootRef, shouldDismissOnCloseRequest]);

  return {
    isEnabled,
    onRootPointerDownCapture: event => {
      if (!isEnabled) {
        return;
      }
      insidePressRef.current = event.nativeEvent;
      // A press inside re-arms the guard.
      guardedSignatureRef.current = null;
    },
  };
}