snapshot of https://github.com/tldraw/tldraw.git (main, 2026-09-23; blobs > 131072B omitted)

packages/utils/src/lib/string.ts

@@ -0,0 +1,58 @@
+let graphemeSegmenter: Intl.Segmenter | undefined
+let checkedForSegmenter = false
+
+/**
+ * Resolve a shared grapheme `Intl.Segmenter`, or `undefined` when the runtime has no
+ * `Intl.Segmenter`. `Intl.Segmenter` is unavailable on some older browsers (notably Firefox before
+ * 125), so feature-detect it once rather than constructing it eagerly, which would throw at module
+ * load and take down the whole app.
+ */
+function getGraphemeSegmenter(): Intl.Segmenter | undefined {
+	if (!checkedForSegmenter) {
+		checkedForSegmenter = true
+		if (typeof Intl !== 'undefined' && 'Segmenter' in Intl) {
+			graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+		}
+	}
+	return graphemeSegmenter
+}
+
+/**
+ * Iterate over the grapheme clusters of a string — user-perceived characters such as emoji
+ * sequences, flags, and accented letters — instead of UTF-16 code units. Uses `Intl.Segmenter`
+ * where available and falls back to iterating by code point on browsers that lack it, where a
+ * multi-code-point cluster is yielded as its component code points rather than as one segment.
+ *
+ * @public
+ */
+export function* iterateGraphemes(str: string): IterableIterator<string> {
+	const segmenter = getGraphemeSegmenter()
+	if (segmenter) {
+		for (const { segment } of segmenter.segment(str)) yield segment
+	} else {
+		yield* str
+	}
+}
+
+/**
+ * Get the first character of a string, treating a multi-code-unit character such as an emoji as a
+ * single character. Unlike `str[0]` or `str.charAt(0)`, which return one UTF-16 code unit and so
+ * split an emoji into a broken half, this returns the first whole grapheme cluster. Returns an
+ * empty string when the input is empty.
+ *
+ * @example
+ * ```ts
+ * getFirstCharacter('hello') // 'h'
+ * getFirstCharacter('😀 hello') // '😀'
+ * getFirstCharacter('') // ''
+ * ```
+ *
+ * @public
+ */
+export function getFirstCharacter(str: string): string {
+	if (!str) return ''
+	for (const segment of iterateGraphemes(str)) {
+		return segment
+	}
+	return ''
+}