Skip to content

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

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

/**
 * @fileoverview The text a PowerSearch filter token shows for a value.
 *
 * @input `OperatorValue`, `FilterValue`, a width budget, the locale, and the
 * calendar.
 * @output `formatTokenValueText` — one string, or null for an empty value;
 * `formatTokenLabel` and `formatTokenText` — the token's "field: operator"
 * label and its full text, each one catalog message; `tokenTextKeepsParts` —
 * whether the full text is the label, a space, then the value.
 * @position Shared by the token itself (`PowerSearch.tsx`) and the sheet
 * presentation's Filters rows and removal announcement
 * (`PowerSearchBottomSheet.tsx`), so every reading of a value on the field
 * uses the same words and the same zone handling.
 */

import type {OperatorValue, FilterValue, EnumItem} from './types';
import type {Locale, TranslatorFn} from '../i18n';
import type {CalendarSystem} from '../utils/calendarSystem';
import {truncateCharacters} from '../utils/characters';
import {formatDateAbsolute, formatSharedNumber} from './formatFilterValue';
import {registerEnglishFallback} from '../i18n/englishFallback';
import english from '../i18n/generated-english/PowerSearch/formatTokenValue.generated';

registerEnglishFallback(english);

type ListFormatFn = (items: ReadonlyArray<string>) => string;

/**
 * A filter token's label: its field and operator, joined by one catalog
 * message so a locale can reorder them. A filter with no operator text shows
 * its field alone.
 */
export function formatTokenLabel(
  t: TranslatorFn,
  fieldLabel: string,
  operatorLabel: string,
): string {
  if (operatorLabel === '') {
    return fieldLabel;
  }
  return t('@astryx.powersearch.token.fieldOperator', {
    field: fieldLabel,
    operator: operatorLabel,
  });
}

/** A filter token's full text: its label and its value, in one message. */
export function formatTokenText(
  t: TranslatorFn,
  label: string,
  value: string,
): string {
  return t('@astryx.powersearch.token.labelValue', {label, value});
}

// Characters no message text uses, to find where the catalog puts each part.
const LABEL_MARK = '\uE000';
const VALUE_MARK = '\uE001';

/**
 * Whether the locale writes a token's full text as its label, a space, then
 * its value. Only then can the pill show the label and the styled value as
 * two parts and still read as the full text that names it.
 */
export function tokenTextKeepsParts(t: TranslatorFn): boolean {
  const pattern = formatTokenText(t, LABEL_MARK, VALUE_MARK);
  return new RegExp(`^${LABEL_MARK}\\s+${VALUE_MARK}$`).test(pattern);
}

function truncateString(value: string, limit: number): string {
  // Same semantics as before — strings within limit + 3 pass through, longer
  // ones cut to limit + '...' — but counted in characters, not code units.
  return truncateCharacters(value, limit + 3, '...');
}

function getEnumLabel(values: ReadonlyArray<EnumItem>, value: string): string {
  return values.find(v => v.value === value)?.label ?? value;
}

// Intl's maximum fraction cap: no number the row formats is rounded.
const MAX_FRACTION_DIGITS = 100;

// Whether a locale writes a number with the token's own numerals: Latin
// digits and a `.` decimal mark, so `String(value)` is already the locale's
// reading. Probed once per locale through the shared number helper.
const tokenNumeralLocales = new Map<string, boolean>();
function usesTokenNumerals(locale: Locale): boolean {
  let uses = tokenNumeralLocales.get(locale);
  if (uses == null) {
    uses =
      formatSharedNumber(1234567.5, locale, {
        useGrouping: false,
        maximumFractionDigits: MAX_FRACTION_DIGITS,
      }) === '1234567.5';
    tokenNumeralLocales.set(locale, uses);
  }
  return uses;
}

// A number as the token reads it. Where the locale writes Latin digits and a
// `.` decimal mark, use the token's own text, `String(value)`. Elsewhere, use
// the locale's digits and decimal mark, with no grouping and no rounding: the
// fraction cap is Intl's maximum, so `1e-21` keeps its digits.
function formatNumberAsToken(value: number, locale: Locale): string {
  return usesTokenNumerals(locale)
    ? String(value)
    : formatSharedNumber(value, locale, {
        useGrouping: false,
        maximumFractionDigits: MAX_FRACTION_DIGITS,
      });
}

// The summaries, lists, and numbers the token writes as English literals, and
// the locale-aware readings of the same: with a translator (the sheet
// presentation's rows and announcements) the summaries resolve through the
// catalog, lists through the provider locale's list format, and numbers
// through its number format; without one they stay the token's own literals,
// the released popover token's text. In English the two read identically.
function itemsSummary(count: number, t: TranslatorFn | undefined): string {
  return t
    ? t('@astryx.powersearch.valueEditor.itemsCount', {count})
    : // eslint-disable-next-line @astryx/no-hardcoded-i18n-string -- the popover token's released English text; translating it is a separate stable change
      `${count} items`;
}

function formatListText(
  labels: ReadonlyArray<string>,
  maxLength: number,
  t: TranslatorFn | undefined,
  formatList: ListFormatFn | undefined,
): string | null {
  if (labels.length === 0) {
    return null;
  }
  if (labels.length === 1) {
    return truncateString(labels[0], maxLength);
  }
  const totalLength = labels.reduce((sum, s) => sum + s.length, 0);
  if (totalLength > maxLength) {
    return itemsSummary(labels.length, t);
  }
  return formatList ? formatList(labels) : labels.join(', ');
}

/**
 * The text a filter token shows for a value: the one place that decides how
 * a value reads on the field, so every other reading of the same value —
 * the sheet presentation's Filters rows and its removal announcement — can
 * use the same words and the same zone handling. `maxLength` is the token's
 * width budget; pass `Number.MAX_SAFE_INTEGER` for the untruncated text.
 * A `date_absolute` value is written in `calendar`, the calendar that the
 * provider resolves.
 * With `t`, the list, date-range and nested summaries resolve through the
 * catalog (`@astryx.powersearch.valueEditor.*`); without it they are the
 * token's own literals. With `formatList` (the provider's list formatter),
 * several labels join as a list in the locale; without it they join with
 * the token's literal ", ".
 */
export function formatTokenValueText(
  operatorValue: OperatorValue,
  filterValue: FilterValue,
  maxLength: number,
  locale: Locale,
  calendar: CalendarSystem,
  t?: TranslatorFn,
  formatList?: ListFormatFn,
  timezoneID?: string,
): string | null {
  switch (filterValue.type) {
    case 'empty':
      return null;

    case 'string':
      return truncateString(filterValue.value, maxLength);

    case 'integer':
    case 'float':
      return t
        ? formatNumberAsToken(filterValue.value, locale)
        : String(filterValue.value);

    case 'enum':
      if (operatorValue.type === 'enum') {
        return truncateString(
          getEnumLabel(operatorValue.values, filterValue.value),
          maxLength,
        );
      }
      return truncateString(filterValue.value, maxLength);

    case 'string_list':
      return formatListText(filterValue.value, maxLength, t, formatList);

    case 'enum_list': {
      const items = filterValue.value;
      if (items.length === 0) {
        return null;
      }
      if (operatorValue.type === 'enum_list') {
        return formatListText(
          items.map(v => getEnumLabel(operatorValue.values, v)),
          maxLength,
          t,
          formatList,
        );
      }
      if (items.length === 1) {
        return truncateString(items[0], maxLength);
      }
      return itemsSummary(items.length, t);
    }

    case 'entity_list':
      return formatListText(
        filterValue.value.map(e => e.label),
        maxLength,
        t,
        formatList,
      );

    case 'time':
      return filterValue.value;

    case 'date_absolute':
      // The token reads a value in the zone its editor uses.
      return truncateString(
        formatDateAbsolute(
          filterValue.unixSeconds,
          locale,
          timezoneID,
          operatorValue.type !== 'date_absolute' ||
            operatorValue.isDateOnly !== false,
          calendar,
        ),
        maxLength,
      );

    case 'date_relative':
      return truncateString(filterValue.value, maxLength);

    case 'date_range':
      if (t) {
        return t('@astryx.powersearch.valueEditor.dateRange');
      }
      // eslint-disable-next-line @astryx/no-hardcoded-i18n-string -- the popover token's released English text; translating it is a separate stable change
      return 'date range';

    case 'custom':
      if (operatorValue.type === 'custom') {
        return truncateString(
          operatorValue.getString(filterValue.value),
          maxLength,
        );
      }
      return filterValue.value;

    case 'nested': {
      const count = filterValue.value.length;
      if (t) {
        return t('@astryx.powersearch.valueEditor.filtersCount', {count});
      }
      // eslint-disable-next-line @astryx/no-hardcoded-i18n-string -- the popover token's released English text; translating it is a separate stable change
      return count === 1 ? '1 filter' : `${count} filters`;
    }

    default:
      return null;
  }
}