Skip to content

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

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

'use client';

/**
 * @file LineClamp.tsx
 * @input Uses React, stylex, useTruncation + Tooltip + BaseProps from
 *   @astryxdesign/core, and Core's canonical focusable selector and shared
 *   mutation observer through `@astryxdesign/core/internal/line-clamp`
 * @output Exports LineClamp component, LineClampProps
 * @position Lab experiment (facebook/astryx#4180); consumed by index.ts
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/lab/src/LineClamp/LineClamp.doc.mjs (props table, features)
 * - /packages/lab/src/LineClamp/LineClamp.test.tsx (tests for new/changed behavior)
 * - /packages/lab/src/LineClamp/index.ts (exports if types change)
 * - /apps/storybook/stories/LineClamp.stories.tsx (storybook stories)
 */

import {
  useCallback,
  useLayoutEffect,
  useRef,
  type FocusEvent,
  type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';

import type {BaseProps} from '@astryxdesign/core';
import {useTruncation} from '@astryxdesign/core/Text';
import {truncationTooltipStyles} from '@astryxdesign/core/Text/text.stylex';
import type {LayerPlacement} from '@astryxdesign/core/Layer';
import {
  composeEventHandlers,
  focusOutlineStyles,
  mergeProps,
  themeProps,
  observeResize,
} from '@astryxdesign/core/utils';
import {useMergedRefs} from '@astryxdesign/core/hooks';
import {
  FOCUSABLE_SELECTOR,
  flushMutations,
  observeMutations,
  TruncationTooltip,
  useTruncationTooltipInterest,
} from '@astryxdesign/core/internal/line-clamp';

const styles = stylex.create({
  clamp: {
    display: '-webkit-box',
    WebkitBoxOrient: 'vertical',
    // `clip`, not `hidden`: both clip the same way visually, but `hidden`
    // makes the box a scroll container, so a browser bringing a focused
    // descendant into view scrolls it, which, against a clamped box, means
    // focusing a clipped link replaces the visible line with the hidden one
    // out from under the reader. `clip` clips without becoming scrollable,
    // so that scroll-into-view path never triggers.
    overflow: 'clip',
    wordBreak: 'break-word',
    overflowWrap: 'break-word',
  },
});

const HIDDEN_ATTRIBUTE = 'data-line-clamp-hidden';
const ROOT_ATTRIBUTE = 'data-line-clamp-root';

/**
 * Whether `container` is the nearest clamp around `el`. A clamp nested inside
 * another manages its own descendants, so the outer one must not hide, restore
 * or disown them: it would undo the inner clamp's decisions with the outer
 * clamp's box in mind, not the inner one's.
 */
function isOwnedBy(container: HTMLElement, el: Element): boolean {
  // A popover or dialog renders in the top layer, which the clamp does not
  // clip, so ownership stops at that layer boundary.
  return (
    el.parentElement?.closest(`[${ROOT_ATTRIBUTE}], [popover], dialog`) ===
    container
  );
}

/**
 * Take a clipped descendant out of the tab order and the accessibility tree by
 * marking it `inert`. The element's own `tabindex` and `aria-hidden` are never
 * rewritten, so a caller's `tabIndex={-1}` or `aria-hidden="true"` survives
 * whatever the clamp does, and there is nothing to restore but the one
 * attribute this adds.
 */
function hideFromTabOrder(el: HTMLElement) {
  if (el.hasAttribute(HIDDEN_ATTRIBUTE)) {
    return;
  }
  // Already inert because the caller made it so: not ours to manage.
  if (el.hasAttribute('inert')) {
    return;
  }
  el.setAttribute('inert', '');
  el.setAttribute(HIDDEN_ATTRIBUTE, '');
}

/** Make a descendant this clamp hid reachable again. */
function restoreFromClip(el: HTMLElement) {
  el.removeAttribute('inert');
  el.removeAttribute(HIDDEN_ATTRIBUTE);
}

/**
 * Scan a clamp container for focusable descendants that fall on a visually
 * clipped line, and hide exactly those from the tab order (see the fuller
 * comment where this runs, in the component). Also includes elements this
 * already hid (`[data-line-clamp-hidden]`) so a previously-clipped descendant
 * that becomes visible again (a resize, more space) is found and restored.
 *
 * `focusTarget` is where focus is going when this runs from a `focusout`,
 * which fires before `document.activeElement` has moved.
 */
function syncFocusableClipping(
  container: HTMLElement,
  focusTarget?: Element | null,
) {
  const containerBottom = container.getBoundingClientRect().bottom;
  const candidates = container.querySelectorAll<HTMLElement>(
    `${FOCUSABLE_SELECTOR}, [data-line-clamp-hidden]`,
  );
  for (const el of candidates) {
    if (!isOwnedBy(container, el)) {
      continue;
    }
    const box = flowBox(container, el);
    if (box == null) {
      if (el.hasAttribute(HIDDEN_ATTRIBUTE)) {
        restoreFromClip(el);
      }
      continue;
    }
    // Never take the element that holds focus out of the tab order: focus
    // would be lost from under the reader.
    const isFocused =
      el.contains(document.activeElement) ||
      (focusTarget != null && el.contains(focusTarget));
    // A candidate with no box has an all-zero rect, so the rect rule cannot
    // judge it. `display: none` cannot show, so it stays inert until the edge
    // observer sees it on a visible line. `display: contents` has no box of
    // its own; its children are the candidates.
    if (el.getClientRects().length === 0) {
      if (getComputedStyle(el).display === 'contents') {
        if (el.hasAttribute(HIDDEN_ATTRIBUTE)) {
          restoreFromClip(el);
        }
      } else if (!isFocused) {
        hideFromTabOrder(el);
      }
      continue;
    }
    const isClipped =
      !isFocused && box.getBoundingClientRect().top >= containerBottom;
    if (isClipped) {
      hideFromTabOrder(el);
    } else if (el.hasAttribute('data-line-clamp-hidden')) {
      restoreFromClip(el);
    }
  }
}

/**
 * The box whose position decides whether `el` is cut off, or null when `el`
 * starts or sits in a subtree that is never made inert. A `fixed` box, or an
 * `absolute` box whose containing block is the clamp or lies outside it,
 * starts such a subtree. An `absolute` box placed against a containing block
 * in the clamp's flow (a control's own positioned wrapper) stays in the flow,
 * and that containing block's box decides. A popover or dialog stops
 * ownership in `isOwnedBy`, and a portal renders outside the clamp.
 */
function containingBlock(node: Element): Element | null {
  if (node instanceof HTMLElement && node.offsetParent != null) {
    return node.offsetParent;
  }
  // A node with no box (for example under `display: none`) has no
  // `offsetParent`, so find its containing block from computed style.
  if (node.getClientRects().length > 0) {
    return null;
  }
  for (
    let ancestor = node.parentElement;
    ancestor != null;
    ancestor = ancestor.parentElement
  ) {
    if (getComputedStyle(ancestor).position !== 'static') {
      return ancestor;
    }
  }
  return null;
}

function flowBox(container: HTMLElement, el: Element): Element | null {
  let box: Element = el;
  for (
    let node: Element | null = el;
    node != null && node !== container;
    node = node.parentElement
  ) {
    const {position} = getComputedStyle(node);
    if (position === 'fixed') {
      return null;
    }
    if (position === 'absolute') {
      const block = containingBlock(node);
      if (block == null || block === container || !container.contains(block)) {
        return null;
      }
      box = block;
    }
  }
  return box;
}

/**
 * Lines can re-wrap at the same box size with no render, mutation or resize.
 * An IntersectionObserver rooted at the clamp reports each managed focusable
 * that crosses the clip edge. A link whose top touches the edge intersects at
 * ratio 0 but is clipped, so a threshold just above 0 reports that move too.
 */
function observeEdgeCrossings(container: HTMLElement, onCross: () => void) {
  if (typeof IntersectionObserver === 'undefined') {
    return {refresh: () => {}, disconnect: () => {}};
  }
  const observer = new IntersectionObserver(onCross, {
    root: container,
    threshold: EDGE_THRESHOLDS,
  });
  const refresh = () => {
    observer.disconnect();
    const candidates = container.querySelectorAll(CANDIDATE_SELECTOR);
    for (const el of candidates) {
      if (isOwnedBy(container, el)) {
        observer.observe(el);
      }
    }
  };
  refresh();
  return {refresh, disconnect: () => observer.disconnect()};
}

const EDGE_THRESHOLDS = [0, 1e-6];

const CANDIDATE_SELECTOR = `${FOCUSABLE_SELECTOR}, [${HIDDEN_ATTRIBUTE}]`;
const BOX_ATTRIBUTES = new Set(['hidden', 'class', 'style']);

function isBoxRecord(record: MutationRecord): boolean {
  return BOX_ATTRIBUTES.has(record.attributeName ?? '');
}

/** A record that can change which descendants are focusable. */
function changesFocusables(record: MutationRecord): boolean {
  return (
    record.type === 'childList' ||
    (record.attributeName !== 'inert' && !isBoxRecord(record))
  );
}

/**
 * A `hidden`, `class` or `style` change matters only on a candidate or an
 * ancestor of one. Decorative animation inside the clamp runs no pass.
 */
function needsPass(record: MutationRecord): boolean {
  if (!isBoxRecord(record)) {
    return true;
  }
  const target = record.target;
  return (
    target instanceof Element &&
    (target.matches(CANDIDATE_SELECTOR) ||
      target.querySelector(CANDIDATE_SELECTOR) != null)
  );
}

const MUTATION_OPTIONS: MutationObserverInit = {
  childList: true,
  subtree: true,
  attributes: true,
  attributeOldValue: true,
  // `hidden`, `class` and `style` can show a focusable past the edge with no
  // other change, so they run the pass too.
  attributeFilter: [
    'tabindex',
    'disabled',
    'href',
    'inert',
    'contenteditable',
    'hidden',
    'class',
    'style',
  ],
};

/**
 * A caller writing `inert` on a link this clamp had hidden makes the attribute
 * theirs: drop the clamp's marker, so un-clipping the link leaves it as they
 * set it. The clamp's own writes are told apart by what they do rather than
 * counted, so this does not depend on when the observer attached. It only ever
 * adds or removes the attribute, so a record that goes from present to present
 * is the caller writing it again, and a hidden link left without it had it
 * taken away.
 */
function handBackCallerInert(
  container: HTMLElement,
  records: ReadonlyArray<MutationRecord>,
) {
  const inertRecords = records.filter(
    (record): record is MutationRecord & {target: HTMLElement} =>
      record.type === 'attributes' &&
      record.attributeName === 'inert' &&
      record.target instanceof HTMLElement &&
      isOwnedBy(container, record.target),
  );
  for (const [index, record] of inertRecords.entries()) {
    const target = record.target;
    // What the attribute was set to by this record: the next record for the
    // same element reports it as its old value, and the last one is the
    // element's current state.
    const next = inertRecords
      .slice(index + 1)
      .find(candidate => candidate.target === target);
    const value = next ? next.oldValue : target.getAttribute('inert');
    if (record.oldValue != null && value != null) {
      target.removeAttribute(HIDDEN_ATTRIBUTE);
    }
  }
  for (const record of inertRecords) {
    if (!record.target.hasAttribute('inert')) {
      record.target.removeAttribute(HIDDEN_ATTRIBUTE);
    }
  }
}

/**
 * A release runs in React's commit, before the new line count is written, so
 * a clipping pass there would lay the page out a second time. While a release
 * flushes the queued records, every clamp hands back its caller's `inert` at
 * once and defers its pass until the commit is done. The releasing clamp
 * skips its own pass: its layout effect syncs it.
 */
let isReleaseFlushing = false;
const deferredSyncs = new Set<() => void>();

function deferSync(sync: () => void) {
  if (deferredSyncs.size === 0) {
    queueMicrotask(() => {
      const syncs = [...deferredSyncs];
      deferredSyncs.clear();
      syncs.forEach(run => run());
    });
  }
  deferredSyncs.add(sync);
}

function releaseFlush() {
  isReleaseFlushing = true;
  try {
    flushMutations(MUTATION_OPTIONS);
  } finally {
    isReleaseFlushing = false;
  }
}

export interface LineClampProps extends BaseProps<HTMLElement> {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLElement>;
  /**
   * Content to clamp: mixed inline content, nested elements, anything you
   * would rather not wrap in a single `Text`.
   */
  children: ReactNode;
  /**
   * Maximum number of lines to show before clamping with an ellipsis.
   */
  maxLines: number;
  /**
   * Show a tooltip with the full text content on hover or keyboard focus when
   * clamped. A clamped root is focusable so the tooltip can be reached without a
   * pointer.
   * @default true
   */
  hasTruncateTooltip?: boolean;
  /**
   * Where the truncation tooltip opens.
   * @default 'above'
   */
  truncateTooltipPlacement?: LayerPlacement;
  /**
   * HTML element to render.
   * @default 'div'
   */
  as?: 'div' | 'span' | 'p';
}

/**
 * Clamps arbitrary content to a fixed number of lines with an ellipsis.
 *
 * `Text`'s `maxLines` clamps a `Text` element. `LineClamp` clamps whatever it
 * wraps and adds no typography of its own, so it fits content that is not a
 * single `Text` (mixed inline content, nested elements) without changing its
 * font, color or wrapping.
 *
 * Truncation detection reuses `useTruncation` (the same hook `Text` uses),
 * so overflow is measured correctly even while `-webkit-line-clamp` clips
 * `scrollHeight`.
 *
 * @example
 * ```
 * <LineClamp maxLines={2}>
 *   Some <strong>mixed</strong> inline content that may run long.
 * </LineClamp>
 * <LineClamp maxLines={3} hasTruncateTooltip={false}>{longDescription}</LineClamp>
 * ```
 */
export function LineClamp({
  children,
  maxLines,
  hasTruncateTooltip = true,
  truncateTooltipPlacement = 'above',
  as: Component = 'div',
  xstyle,
  className,
  style,
  ref,
  onBlur,
  onFocus,
  onPointerEnter,
  onPointerLeave,
  onPointerDown,
  ...props
}: LineClampProps): ReactNode {
  // The clamp is height-based at every line count, so a single line must be
  // measured the way a multi-line clamp is. `useTruncation({maxLines: 1})`
  // compares horizontal overflow, which a wrapping box never has, so the
  // tooltip would never appear.
  const truncation = useTruncation({
    maxLines: maxLines > 0 ? Math.max(maxLines, 2) : 0,
  });
  const elementRef = useRef<HTMLElement>(null);

  // A resize, a re-wrap of the lines or a child's new focusable can move a
  // descendant across the edge without a render. The shared observers and
  // the edge observer run the sync for those. A callback ref attaches them
  // with the root and releases them when it goes, including when `as`
  // replaces it.
  const observeRoot = useCallback((container: HTMLElement | null) => {
    if (container == null) {
      return;
    }
    const sync = () => syncFocusableClipping(container);
    let isReleased = false;
    const edge = observeEdgeCrossings(container, () => {
      if (!isReleased) {
        sync();
      }
    });
    const unobserveMutations = observeMutations(
      container,
      MUTATION_OPTIONS,
      records => {
        handBackCallerInert(container, records);
        if (isReleased) {
          return;
        }
        if (records.some(changesFocusables)) {
          edge.refresh();
        }
        if (!records.some(needsPass)) {
          return;
        }
        if (isReleaseFlushing) {
          deferSync(sync);
          return;
        }
        sync();
      },
    );
    const unobserveResize = observeResize(container, sync);
    return () => {
      // The shared observer disconnects when its last registration goes, and
      // a disconnect drops the records it holds. Hand a caller's queued
      // `inert` back first, while this registration still receives it.
      isReleased = true;
      releaseFlush();
      edge.disconnect();
      unobserveResize();
      unobserveMutations();
    };
  }, []);
  const mergedRef = useMergedRefs(ref, truncation.ref, elementRef, observeRoot);

  const tooltipEnabled =
    hasTruncateTooltip && maxLines > 0 && truncation.isTruncated;
  // The tooltip mounts on the first hover, completed tap or focus, as Text's
  // does, so a page of clamped content mounts no tooltip layers at load.
  const tooltipInterest = useTruncationTooltipInterest(tooltipEnabled);

  // Line clamping clips paint only. A link on a clipped line stays in the Tab
  // order, so mark it inert. This runs on every render; the observers above
  // cover changes that do not render.
  useLayoutEffect(() => {
    const container = elementRef.current;
    if (container) {
      // A caller's `inert` written in this render must reach the hand-off
      // before the sync can un-clip that link.
      flushMutations(MUTATION_OPTIONS);
      syncFocusableClipping(container);
    }
  });

  // Focus has moved by now, so a link that was skipped while it held focus can
  // be hidden if it is clipped. `relatedTarget` is where focus is going.
  const handleBlur = (event: FocusEvent<HTMLElement>) => {
    syncFocusableClipping(
      event.currentTarget,
      event.relatedTarget instanceof Element ? event.relatedTarget : null,
    );
  };

  return (
    <>
      <Component
        ref={mergedRef}
        {...mergeProps(
          themeProps('line-clamp'),
          stylex.props(focusOutlineStyles.focusVisible, styles.clamp, xstyle),
          className,
          {...style, WebkitLineClamp: maxLines},
        )}
        // A truncated clamp is a tab stop so keyboard users can reveal the
        // full text through the tooltip, which opens on focus. A caller's own
        // `tabIndex` wins.
        tabIndex={tooltipEnabled ? 0 : undefined}
        {...{[ROOT_ATTRIBUTE]: ''}}
        onPointerEnter={composeEventHandlers(
          tooltipInterest.onPointerEnter,
          onPointerEnter,
        )}
        onPointerLeave={composeEventHandlers(
          tooltipInterest.onPointerLeave,
          onPointerLeave,
        )}
        onPointerDown={composeEventHandlers(
          tooltipInterest.onPointerDown,
          onPointerDown,
        )}
        onFocus={composeEventHandlers(tooltipInterest.onFocus, onFocus)}
        onBlur={composeEventHandlers(
          tooltipInterest.onBlur,
          composeEventHandlers(handleBlur, onBlur),
        )}
        {...props}>
        {children}
      </Component>
      {tooltipEnabled && tooltipInterest.isWanted && (
        <TruncationTooltip
          anchorRef={elementRef}
          content={
            <span {...stylex.props(truncationTooltipStyles.content)}>
              {truncation.fullText}
            </span>
          }
          placement={truncateTooltipPlacement}
          interest={tooltipInterest}
        />
      )}
    </>
  );
}

LineClamp.displayName = 'LineClamp';