Truncation Component

/* ------------ Truncation ------------ */

/* A one-line value that trims itself only while it overflows the space its container offers.
   The plain text is its own overflow probe: an `overflow: hidden` box has a scroll timeline only
   while its content overflows, and the animation bound to that timeline flips the state both
   branches read. It is measured at the full width the Reveal Button never takes, so showing the
   button cannot change the answer. */
.c-truncation {
  /* The Reveal Button's focus ring: `.c-button--icon-only` draws a 2px outline 2px outside it.
     The button and its ring must fit inside the space the value takes, because table cells and
     their lines clip with `overflow: hidden` and leave no padding for it. */
  --c-truncation-focus-ring: 4px;

  align-items: center;
  animation: c-truncation-overflowing linear both;
  animation-timeline: --c-truncation;
  display: flex;
  flex: 0 1 auto;
  min-inline-size: 0;
  position: relative;
  timeline-scope: --c-truncation;
}

@keyframes c-truncation-overflowing {
  from,
  to {
    --c-truncation-overflowing: 1;
  }
}

.c-truncation__plain {
  min-inline-size: 0;
  overflow: hidden;
  scroll-timeline: --c-truncation inline;
  white-space: nowrap;
}

.c-truncation__overflow {
  align-items: center;
  column-gap: var(--spacing-3xs);
  display: none;
  min-inline-size: 0;
  padding-inline-end: var(--c-truncation-focus-ring);
}

.c-truncation__text {
  mask-image: linear-gradient(to left, transparent, #000 2.5ch);
  min-inline-size: 0;
  overflow: hidden;
  text-overflow: clip;
  white-space: nowrap;
}

/* Clips at its start: an end-aligned flex item that is too wide overflows toward the start. */
.c-truncation__text--start {
  display: flex;
  justify-content: flex-end;
  mask-image: linear-gradient(to right, transparent, #000 2.5ch);
}

.c-truncation__text--start > span {
  flex: none;
}

/* The last segment stays whole until the head is gone; past that it clips at its start. */
.c-truncation__text--whole {
  flex-shrink: 0;
  mask-image: none;
  max-inline-size: calc(100% - 1.375rem - var(--spacing-3xs) - var(--c-truncation-focus-ring));
}

/* The focus-ring budget follows the Reveal Button to wherever the cut is. */
.c-truncation--start .c-truncation__overflow {
  padding-inline: var(--c-truncation-focus-ring) 0;
}

.c-truncation--middle .c-truncation__overflow {
  padding-inline-end: 0;
}

/* A collapsed head still leaves room for the Reveal Button's focus ring. */
.c-truncation--middle .c-truncation__text:first-child {
  min-inline-size: calc(var(--c-truncation-focus-ring) - var(--spacing-3xs));
}

@container style(--c-truncation-overflowing: 1) {
  .c-truncation__plain {
    block-size: 0;
    inset-block-start: 0;
    inset-inline: 0;
    position: absolute;
    visibility: hidden;
  }

  .c-truncation__overflow {
    display: flex;
  }
}

/* Rests on accent-200, darker than a selected row's background, so it never merges into a
   selected row; hover and focus deepen to accent-300. The dots stay in the text color. */
.c-truncation__reveal {
  background-color: var(--color-accent-200);

  /* One line tall including its ring, so revealing never changes the line's height. */
  block-size: calc(1lh - 2 * var(--c-truncation-focus-ring));
  border: 1px solid var(--color-accent-300);
  border-radius: 2px;
  color: var(--color-text);
  flex: none;
  inline-size: 1.375rem;
}

/* The whole border, because .c-button--reset:focus removes it. */
.c-truncation__reveal:hover,
.c-truncation__reveal:focus,
.c-truncation__reveal:focus-visible {
  background-color: var(--color-accent-300);
  border: 1px solid var(--color-accent-500);
}

.c-truncation__reveal-icon {
  fill: currentcolor;
  inline-size: 0.75rem;
}

/* Without scroll-driven animations the value wraps, which loses nothing. */
@supports not ((animation-timeline: --a) and (timeline-scope: --a)) {
  .c-truncation__plain {
    overflow-wrap: anywhere;
    white-space: normal;
  }
}

/* An element that is already interactive keeps a native ellipsis; its own tooltip reveals the rest. */
.c-truncation-host {
  display: block;
  max-inline-size: 100%;
  min-inline-size: 0;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

/* Native ellipsis at the start. The isolated inner span keeps a URL or path left to right. */
.c-truncation-host--start {
  direction: rtl;
  text-align: left;
}

.c-truncation-host--start > span {
  direction: ltr;
  unicode-bidi: isolate;
}

import type { TOC } from '@ember/component/template-only';
import { concat, hash } from '@ember/helper';
import EllipsisDots from 'my-design-system/icons/ellipsis-dots';
import Button from 'my-design-system/components/button';
import attachTooltip from 'my-design-system/modifiers/attach-tooltip';

export type TruncationPosition = 'end' | 'start' | 'middle';

export interface Signature {
  Args: {
    text: string;
    /** Where the cut falls while the value overflows. Defaults to `'end'`. */
    position?: TruncationPosition;
  };
  Element: HTMLSpanElement;
}

const SEPARATORS = ['/', '\\', '›', '»'];

// The faded copy, split around the Reveal Button: `head` clips at its end, `tail` at its start.
function splitText(text: string, position: TruncationPosition = 'end') {
  if (position === 'start') return { head: '', tail: text };
  if (position === 'end') return { head: text, tail: '' };

  // A trailing separator doesn't count, so `/docs/src/` keeps `/src/` whole rather than splitting off `/`.
  const at = Math.max(...SEPARATORS.map((separator) => text.lastIndexOf(separator, text.length - 2)));

  if (at > 0) return { head: text.slice(0, at), tail: text.slice(at), wholeTail: true };

  // Between graphemes, so an emoji or accented letter is never cut in two.
  const graphemes = Array.from(new Intl.Segmenter().segment(text), ({ segment }) => segment);
  const half = Math.ceil(graphemes.length / 2);

  return { head: graphemes.slice(0, half).join(''), tail: graphemes.slice(half).join('') };
}

// Which branch shows is decided in CSS (`styles/components/_truncation.css`): the plain text
// measures its own overflow, so there is nothing to observe, settle, or re-measure here.
const TruncationComponent: TOC<Signature> = <template>
  <span class='c-truncation {{if @position (concat "c-truncation--" @position)}}' data-test-truncation ...attributes>
    <span class='c-truncation__plain' data-test-truncation-plain>{{@text}}</span>
    <span class='c-truncation__overflow'>
      {{#let (splitText @text @position) as |copy|}}
        {{#if copy.head}}
          <span class='c-truncation__text' aria-hidden='true' data-truncation-copy>{{copy.head}}</span>
        {{/if}}
        <Button
          class='c-button--reset c-button--icon-only c-truncation__reveal'
          aria-label={{@text}}
          data-test-truncation-reveal
          {{attachTooltip (hash content=@text hideOnClick=false)}}
        >
          <EllipsisDots class='c-truncation__reveal-icon' />
        </Button>
        {{#if copy.tail}}
          <span class='c-truncation__text c-truncation__text--start {{if copy.wholeTail "c-truncation__text--whole"}}' aria-hidden='true' data-truncation-copy><span>{{copy.tail}}</span></span>
        {{/if}}
      {{/let}}
    </span>
  </span>
</template>;

export default TruncationComponent;

import { modifier } from 'ember-modifier';
import { applyTooltip, revealHostContent } from 'my-design-system/utils/tooltips';
import type { TooltipTrigger } from 'my-design-system/utils/tooltips';

// For an element that is already interactive (a link, a button, a select trigger, a menu button):
// it keeps a native ellipsis (`c-truncation-host`) and its own tooltip shows the full value, only
// while clipped. Without text, the tooltip shows the host's clipped lines (`data-truncation-clip`)
// as they read when it shows. Visual only, because the element's accessible name already
// carries the full value.
const truncationHostModifier = modifier((element: TooltipTrigger, [text]: [string?]) =>
  applyTooltip(element, {
    content: text ?? revealHostContent,
    showWhen: 'overflowing',
    aria: { content: null, expanded: false },
  }),
);

export default truncationHostModifier;

// A Reveal Host reads its state when it shows, so the answer is always current. A function
// `content` is read then too, for a host whose value is rendered markup rather than a string.
// It never shows over the popup it controls (a select's options, a menu).
function showAsRevealHost(
  content: Content | undefined,
  reason?: TooltipOpts['reason'],
  formatReason: NonNullable<TooltipOpts['formatReason']> = (value, why) => `${value}: ${why}`,
) {
  return (instance: Instance) => {
    if (isExpanded(instance.reference)) return false;

    const isClipped = isTextOverflowing(instance.reference);
    const why = reason?.();

    if (!isClipped && !why) return false;

    if (why) {
      const value = clippedTextLines(instance.reference).join(' ');

      instance.setContent(isClipped && value ? formatReason(value, why) : why);
    } else if (typeof content === 'function') {
      instance.setContent(content(instance.reference));
    } else if (content !== undefined) {
      instance.setContent(content);
    }

    return undefined;
  };
}

const CLIP = '[data-truncation-clip]';

// The elements whose text a Reveal Host clips: the host itself when it is marked, else every
// clip marked inside it (a menu button clips a name and an email separately), else every clip in
// its labels (a file upload's file name sits beside the input in its label), else the host.
export function truncationClips(host: Element): Element[] {
  if (host.matches(CLIP)) return [host];

  const clips = [...host.querySelectorAll(CLIP)];

  if (clips.length) return clips;

  const labelClips = [...((host as Partial<HTMLInputElement>).labels ?? [])].flatMap((label) => [
    ...label.querySelectorAll(CLIP),
  ]);

  return labelClips.length ? labelClips : [host];
}

export function isTextOverflowing(element: Element): boolean {
  return truncationClips(element).some(isClipOverflowing);
}

// One entry per line of a host's clipped text, as rendered: a clip whose children are blocks
// (a name over an email) gives one line per child; any other clip is one line. Children with
// `display: none` are neither lines nor text.
export function clippedTextLines(host: Element): string[] {
  return truncationClips(host)
    .flatMap((clip) => {
      const blocks = [...clip.children].filter(isBlockLine);

      return blocks.length ? blocks : [clip];
    })
    .map((line) => renderedText(line).replace(/\s+/g, ' ').trim())
    .filter(Boolean);
}

function isBlockLine(element: Element): boolean {
  const { display } = getComputedStyle(element);

  return display !== 'none' && display !== 'contents' && !display.startsWith('inline');
}

const renderedText = (element: Element) =>
  (element instanceof HTMLElement ? element.innerText : element.textContent) ?? '';

// Fractional on purpose: scrollWidth and clientWidth are rounded, so text that overflows by a
// fraction of a pixel shows an ellipsis while the integer comparison still says it fits.
// Both sides come from getBoundingClientRect so zoom and transforms cancel out.
function isClipOverflowing(clip: Element): boolean {
  if (!(clip instanceof HTMLElement) || clip.offsetWidth === 0) return false;

  const range = document.createRange();

  range.selectNodeContents(clip);

  const textWidth = range.getBoundingClientRect().width;
  const box = clip.getBoundingClientRect();
  const scale = box.width / clip.offsetWidth;
  const { paddingInlineStart, paddingInlineEnd } = getComputedStyle(clip);
  const contentWidth = box.width - (parseFloat(paddingInlineStart) + parseFloat(paddingInlineEnd)) * scale;

  return textWidth > contentWidth;
}

const isExpanded = (element: Element) => element.getAttribute('aria-expanded') === 'true';

const isRevealHost = (instance: Instance) => instance.props.plugins.includes(hideWhenExpanded);

const isFileInput = (element: Element) => element instanceof HTMLInputElement && element.type === 'file';

// Opening a host's popup from the keyboard leaves focus on the host, so the tooltip would stay
// up and cover the popup. Watch for that only while the tooltip is visible. A file input's popup
// is the native picker, which opens on any click the input doesn't cancel: Enter and Space
// arrive as a click with no mousedown, so tippy's own hideOnClick never sees them.
const hideWhenExpanded: Plugin = {
  fn(instance) {
    const observer = new MutationObserver(() => {
      if (isExpanded(instance.reference)) instance.hide();
    });
    const hideAsPickerOpens = (event: Event) => {
      if (!event.defaultPrevented) instance.hide();
    };
    const stopWatching = () => {
      observer.disconnect();
      instance.reference.removeEventListener('click', hideAsPickerOpens);
    };

    return {
      onShow() {
        observer.observe(instance.reference, { attributeFilter: ['aria-expanded'] });

        if (isFileInput(instance.reference)) instance.reference.addEventListener('click', hideAsPickerOpens);
      },
      onHide: stopWatching,
      onDestroy: stopWatching,
    };
  },
};

// Tooltip content for a host without a string value: one row per line of its clipped text.
export function revealHostContent(host: Element): HTMLElement {
  const content = document.createElement('div');

  for (const line of clippedTextLines(host)) {
    const row = document.createElement('div');

    row.textContent = line;
    content.append(row);
  }

  return content;
}

export function applyTooltip(element: TooltipTrigger, opts: TooltipOpts | undefined): (() => void) | undefined {
  // tippy.js keeps its instance on the trigger element, as `_tippy`.
  const existingTooltip = (element as TooltipTrigger & { _tippy?: Instance })._tippy;
  const options = { ...(opts ?? {}) };
  const tooltipInactive = !options.content || options.hideTooltip;

  if (tooltipInactive && !existingTooltip) return;

  if (tooltipInactive && existingTooltip) {
    destroyInstance(existingTooltip);

    return () => {};
  }

  // Types can't see an anchor without href, splatted attributes landing on the wrong element, or
  // native `disabled`, which takes a control out of the tab order along with its tooltip.
  assert(
    `A tooltip needs a trigger a keyboard can reach, but this <${element.localName}> ${
      element.matches(':disabled') ? 'is natively disabled; use aria-disabled instead' : 'is not focusable'
    }.`,
    isFocusable(element) && !element.matches(':disabled'),
  );

  if (existingTooltip && options.content) {
    // One tooltip per trigger: a second source here only swaps the content and keeps the first
    // one's behavior, as when a form field's help tooltip lands on a select trigger that is
    // already a Reveal Host.
    warn(
      'A plain tooltip and a Reveal Host tooltip were both attached to the same trigger; only the first one\'s behavior applies.',
      isRevealHost(existingTooltip) === (options.showWhen === 'overflowing'),
      { id: 'my-design-system.tooltip-second-source' },
    );
    existingTooltip.setContent(options.content);

    return () => {
      destroyInstance(existingTooltip);
    };
  }

  if (!opts) return () => {};

  const reference: Element = element;
  const instance = tippy(reference, {
    content: opts.content,
    placement: opts.placement || 'top',
    // Mounted beside its trigger so the tooltip follows it through focus order, dialogs, and
    // scroll containers; the trigger's container decides stacking.
    appendTo: opts.appendTo ?? 'parent',
    // Positioned against the viewport, so a scrolling or clipping container around the trigger
    // (a side nav, a table cell, a filter bar) can't cut the tooltip off. Popper still tracks the
    // trigger as those containers scroll.
    popperOptions: { ...opts.popperOptions, strategy: opts.popperOptions?.strategy ?? 'fixed' },
    theme: opts.theme,
    // WCAG 1.4.13 hoverable: the pointer can move onto the tooltip without it closing.
    interactive: opts.interactive ?? true,
    // `interactive` would otherwise drop the describedby link and stamp aria-expanded on the trigger.
    aria: opts.aria ?? { content: 'describedby', expanded: false },
    hideOnClick: opts.hideOnClick,
    maxWidth: opts.maxWidth ?? VIEWPORT_MAX_WIDTH,
    triggerTarget: opts.triggerTarget,
    getReferenceClientRect: opts.getReferenceClientRect,
    plugins: opts.showWhen === 'overflowing' ? [hideOnEscape, hideWhenExpanded] : [hideOnEscape],
    onShow: opts.showWhen === 'overflowing' ? showAsRevealHost(opts.content, opts.reason, opts.formatReason) : undefined,
  });

  // A Reveal Host's tooltip only repeats what the host already says, so assistive technology skips
  // it. Mounted inside a <label>, it would also join the name of the label's control.
  if (opts.showWhen === 'overflowing') instance.popper.setAttribute('aria-hidden', 'true');

  return () => {
    destroyInstance(instance);
  };
}

<a
  class='c-truncation-host'
  href='/documents/42'
  {{truncationHost 'Link Host with Overflowing Text'}}
>Link Host with Overflowing Text</a>

<a
  class='c-message__link c-truncation-host c-truncation-host--start'
  href={{@url}}
  {{truncationHost}}
><span>{{@url}}</span></a>

<button type='button' class='c-button c-button--with-icon' {{truncationHost}} {{on 'click' this.download}}>
  <DownloadIcon class='c-button__icon' aria-hidden='true' />
  <span class='c-truncation-host' data-truncation-clip>Button Host with an Overflowing Label</span>
</button>

<button
  type='button'
  class='c-select__trigger'
  aria-haspopup='listbox'
  aria-expanded={{if this.isOpen 'true' 'false'}}
  {{truncationHost this.selected.label}}
  {{on 'click' this.toggle}}
>
  <span class='c-truncation-host' data-truncation-clip>{{this.selected.label}}</span>
  <ChevronDownIcon class='c-select__chevron' aria-hidden='true' />
</button>

<button
  type='button'
  class='c-profile-chip'
  aria-haspopup='menu'
  aria-expanded={{if this.isOpen 'true' 'false'}}
  {{truncationHost}}
  {{on 'click' this.toggle}}
>
  <Avatar class='c-profile-chip__avatar' @src={{@user.avatarUrl}} />
  <span class='c-profile-chip__lines' data-truncation-clip>
    <span class='c-truncation-host'>My Long Breakable Display Name</span>
    <span class='c-truncation-host'>my.long.breakable.email.address@example.com</span>
  </span>
</button>

const TextCell: TOC<Signature> = <template>
  <td
    class='c-table__cell {{if @cell.isVisuallyHidden "c-visually-hidden"}}'
    data-test-text-cell
  >
    {{! A visually hidden copy is read, never seen; a Reveal Button would be an invisible tab stop. }}
    {{#if @cell.isVisuallyHidden}}
      {{@cell.text}}
    {{else if @cell.text}}
      <Truncation data-test-text @text={{@cell.text}} />
    {{/if}}
  </td>
</template>;

export default TextCell;

const LocationCell: TOC<{ Args: { location: string; path: string } }> = <template>
  <td class='c-table__cell'>
    {{! Home › Projects › … › Network Migration Plan }}
    <Truncation @text={{@location}} @position='start' />
  </td>
  <td class='c-table__cell'>
    {{! /src/compon…/Menu.module.css }}
    <Truncation @text={{@path}} @position='middle' />
  </td>
</template>;

const LinkCell: TOC<{ Args: { href: string; lines: string[] } }> = <template>
  <td class='c-table__cell'>
    <a class='c-link' href={{@href}} data-test-link-cell {{truncationHost}}>
      {{#each @lines as |line|}}
        <span class='c-truncation-host' data-truncation-clip data-test-link-cell-line>{{line}}</span>
      {{/each}}
    </a>
  </td>
</template>;

const NameCell: TOC<{ Args: { name: string; href?: string } }> = <template>
  {{#if @href}}
    <a class='c-truncation-host' href={{@href}} {{truncationHost @name}}>{{@name}}</a>
  {{else}}
    <Truncation @text={{@name}} />
  {{/if}}
</template>;

export default NameCell;

type TextVariation = 'clip' | 'reveal';

const isClip = (variation: TextVariation) => variation === 'clip';

const TitleWithId: TOC<{
  Args: { identifier?: string; title?: string; titleVariation: TextVariation };
}> = <template>
  {{#if @identifier}}
    <span class='c-title-with-id__identifier' data-test-identifier>{{@identifier}}</span>
  {{/if}}
  {{#if @title}}
    {{#if (isClip @titleVariation)}}
      <span
        class='c-title-with-id__title c-truncation-host'
        data-test-title
        data-truncation-clip
      >{{@title}}</span>
    {{else}}
      <Truncation class='c-title-with-id__title' data-test-title @text={{@title}} />
    {{/if}}
  {{/if}}
</template>;

get titleVariation(): TextVariation {
  return this.args.insideLink || this.showLink ? 'clip' : 'reveal';
}

// A group's Reveal Button is always there: it lists every item, and it stands in for the
// ellipsis when the first item's name is trimmed.
export const ItemsSummary: TOC<ItemsSummarySignature> = <template>
  <div class='c-items-summary' data-test-items-summary ...attributes>
    {{#if @group.hasMany}}
      <span class='c-items-summary__name' data-test-items-name>{{@group.firstName}}</span>
      <Button
        class='c-button--reset c-button--icon-only c-truncation__reveal c-items-summary__reveal'
        aria-label={{@group.allNames}}
        data-test-items-reveal
        {{attachTooltip (hash content=@group.allNames hideOnClick=false)}}
      >
        <EllipsisDots class='c-truncation__reveal-icon' />
      </Button>
      <span class='c-items-summary__count' data-test-items-count>{{@group.countLabel}}</span>
    {{else}}
      <Truncation data-test-items-name @text={{@group.firstName}} />
    {{/if}}
  </div>
</template>;

// Translated in place of the person's name, so the copy around the name can be split off it.
const NAME_PLACEHOLDER = '\uE000';