@astryxdesign/core 0.4.2 → 0.4.3

package/src/utils/characters.test.ts

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file characters.test.ts
+ * @input character-counting utilities
+ * @output Tests for characterCount, firstCharacter, truncateCharacters
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {characterCount, firstCharacter, truncateCharacters} from './characters';
+
+// Multi-code-unit fixtures: an emoji surrogate pair (2 units), a flag
+// sequence (4 units), a ZWJ family (11 units), and a combining mark (2 units).
+const EMOJI = '\u{1F600}'; // 😀
+const FLAG = '\u{1F1F9}\u{1F1F7}'; // 🇹🇷
+const FAMILY = '\u{1F468}‍\u{1F469}‍\u{1F467}‍\u{1F466}'; // 👨‍👩‍👧‍👦
+// é as base + combining mark, spelled as an escape so NFC-normalizing
+// tools cannot silently precompose the fixture into single-code-unit é.
+const E_ACUTE = 'e\u0301';
+
+describe('characterCount', () => {
+  it('returns 0 for the empty string', () => {
+    expect(characterCount('')).toBe(0);
+  });
+
+  it('counts ASCII one per character', () => {
+    expect(characterCount('hello')).toBe(5);
+  });
+
+  it('counts an emoji surrogate pair as one', () => {
+    expect(characterCount(EMOJI.repeat(2))).toBe(2);
+    expect(EMOJI.repeat(2).length).toBe(4); // sanity: code units differ
+  });
+
+  it('counts a flag sequence as one', () => {
+    expect(characterCount(FLAG)).toBe(1);
+  });
+
+  it('counts a ZWJ family emoji as one', () => {
+    expect(characterCount(FAMILY)).toBe(1);
+    expect(FAMILY.length).toBe(11); // sanity: code units differ
+  });
+
+  it('counts a combining-mark character as one', () => {
+    expect(characterCount(E_ACUTE)).toBe(1);
+    expect(E_ACUTE.length).toBe(2); // sanity: code units differ
+  });
+
+  it('counts mixed content by user-perceived characters', () => {
+    expect(characterCount(`a${EMOJI}b`)).toBe(3);
+  });
+});
+
+describe('firstCharacter', () => {
+  it('returns the empty string for the empty string', () => {
+    expect(firstCharacter('')).toBe('');
+  });
+
+  it('returns the first ASCII character', () => {
+    expect(firstCharacter('abc')).toBe('a');
+  });
+
+  it('returns a whole emoji, not half a surrogate pair', () => {
+    expect(firstCharacter(`${EMOJI}x`)).toBe(EMOJI);
+  });
+
+  it('returns a whole ZWJ family emoji', () => {
+    expect(firstCharacter(`${FAMILY}x`)).toBe(FAMILY);
+  });
+
+  it('keeps a combining mark attached to its base', () => {
+    expect(firstCharacter(`${E_ACUTE}cole`)).toBe(E_ACUTE);
+  });
+});
+
+describe('truncateCharacters', () => {
+  it('returns strings within max unchanged', () => {
+    expect(truncateCharacters('abc', 5)).toBe('abc');
+  });
+
+  it('returns strings exactly at max unchanged', () => {
+    expect(truncateCharacters('abcde', 5)).toBe('abcde');
+  });
+
+  it('truncates so the result, including the ellipsis, is max characters', () => {
+    expect(truncateCharacters('abcdefghij', 5)).toBe('abcd…');
+  });
+
+  it('counts a multi-character ellipsis against max', () => {
+    // "..." is 3 characters, so 5 content characters remain.
+    expect(truncateCharacters('aaaaaaaaaa', 8, '...')).toBe('aaaaa...');
+  });
+
+  it('passes strings within max through under a multi-character ellipsis', () => {
+    expect(truncateCharacters('aaaaaaaa', 8, '...')).toBe('aaaaaaaa');
+  });
+
+  it('cuts between characters, never splitting an emoji', () => {
+    // The exact-string assertion also proves no surrogate pair was split.
+    expect(truncateCharacters(EMOJI.repeat(4), 3)).toBe(`${EMOJI.repeat(2)}…`);
+  });
+
+  it('treats a ZWJ family emoji as a single unit when cutting', () => {
+    expect(truncateCharacters(`${FAMILY}abc`, 2)).toBe(`${FAMILY}…`);
+  });
+
+  it('returns the empty string unchanged', () => {
+    expect(truncateCharacters('', 5)).toBe('');
+  });
+
+  it('degrades to just the ellipsis when max is smaller than the ellipsis', () => {
+    // Documented degenerate behavior: no consumer passes max below the
+    // ellipsis length, but the clamp must stay predictable.
+    expect(truncateCharacters('abcdef', 2, '...')).toBe('...');
+    expect(truncateCharacters('abcdef', 0)).toBe('…');
+  });
+});
+
+describe('code-point fallback (no Intl.Segmenter)', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it('keeps surrogate pairs intact while counting by code points', async () => {
+    vi.resetModules();
+    // characters.ts only reads Intl.Segmenter, so a minimal stub suffices.
+    vi.stubGlobal('Intl', {Segmenter: undefined});
+    const fallback = await import('./characters');
+
+    expect(fallback.characterCount(EMOJI.repeat(2))).toBe(2);
+    expect(fallback.firstCharacter(`${EMOJI}x`)).toBe(EMOJI);
+    expect(fallback.firstCharacter('')).toBe('');
+    expect(fallback.truncateCharacters(EMOJI.repeat(4), 3)).toBe(
+      `${EMOJI.repeat(2)}…`,
+    );
+    // Documented degradation: a flag sequence splits into its two
+    // regional-indicator code points under the fallback.
+    expect(fallback.characterCount(FLAG)).toBe(2);
+  });
+});

package/src/utils/characters.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file characters.ts
+ * @input Strings that may contain characters made of several code units
+ *        (emoji, flags, joined emoji sequences, accented letters)
+ * @output Exports characterCount, firstCharacter, truncateCharacters —
+ *         replacements for .length / .charAt(0) / .slice(0, n) that measure
+ *         and cut user-visible strings the way a person reads them
+ * @position Shared utility; consumed by Avatar, TextArea, PowerSearch, Table
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/utils/characters.test.ts
+ * - /packages/core/src/utils/index.ts
+ */
+
+/**
+ * Reuse a single segmenter when the runtime supports Intl.Segmenter.
+ * `grapheme` is the Intl granularity name for a user-perceived character.
+ */
+const characterSegmenter =
+  typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, {granularity: 'grapheme'})
+    : null;
+
+/**
+ * Split a string into user-perceived characters. The code-point fallback
+ * keeps surrogate pairs intact but may split joined emoji sequences and flag
+ * pairs on runtimes without Intl.Segmenter.
+ */
+function splitCharacters(str: string): string[] {
+  if (characterSegmenter) {
+    return [...characterSegmenter.segment(str)].map(s => s.segment);
+  }
+  return [...str];
+}
+
+/**
+ * Number of characters in a string — the count a person would give, where one
+ * emoji, flag, or accented letter is one character. Replacement for `.length`
+ * on user-visible strings, which counts internal storage units instead.
+ */
+export function characterCount(str: string): number {
+  if (str === '') {
+    return 0;
+  }
+  return splitCharacters(str).length;
+}
+
+/**
+ * The first character of a string, or '' when empty. Replacement for
+ * `.charAt(0)`, which can return half of an emoji. Reads only the first
+ * character, so cost does not scale with the length of the string.
+ */
+export function firstCharacter(str: string): string {
+  if (characterSegmenter) {
+    const first = characterSegmenter.segment(str)[Symbol.iterator]().next();
+    return first.done ? '' : first.value.segment;
+  }
+  const codePoint = str.codePointAt(0);
+  return codePoint == null ? '' : String.fromCodePoint(codePoint);
+}
+
+/**
+ * Truncate to at most `max` characters, ellipsis included: strings within
+ * `max` characters pass through unchanged; longer strings are cut so the
+ * result — content plus `ellipsis` — is exactly `max` characters (or just the
+ * ellipsis, when `max` is smaller than the ellipsis itself). Replacement for
+ * `str.slice(0, n) + '…'`, which can cut an emoji in half.
+ *
+ * @example
+ * ```
+ * truncateCharacters('abcdefghij', 5) // 'abcd…'
+ * truncateCharacters('abcdefghij', 8, '...') // 'abcde...'
+ * ```
+ */
+export function truncateCharacters(
+  str: string,
+  max: number,
+  ellipsis = '…',
+): string {
+  const characters = splitCharacters(str);
+  if (characters.length <= max) {
+    return str;
+  }
+  const keep = Math.max(max - characterCount(ellipsis), 0);
+  return characters.slice(0, keep).join('') + ellipsis;
+}

package/src/utils/index.ts

@@ -70,6 +70,8 @@ export type {ISOTimeString, ParsedTime} from './timeParser';
 export {parseStyleKey} from './parseStyleKey';
 export {getKey, type Key, type KeyFallback} from './getKey';
 
+export {characterCount, firstCharacter, truncateCharacters} from './characters';
+
 export {mergeProps} from './mergeProps';
 export {mergeRefs} from './mergeRefs';
 export {isFocusDetached} from './focusReturn';