emoji-picker-react 4.22.3 → 5.0.1

package/src/dataUtils/nativeEmojiSupport.ts

@@ -0,0 +1,160 @@
+import { isJsdom } from '../DomUtils/isJsdom';
+
+import { createNativeEmojiSequenceSupport } from './nativeEmojiSequenceSupport';
+
+// Native emoji support detection.
+//
+// The native emoji style renders with the platform's emoji font, which lags
+// behind the dataset: an emoji newer than the OS font draws as a blank box
+// ("tofu") or decomposes into several glyphs, and Windows has no country
+// flag glyphs at all. The picker probes the platform on the client and
+// refreshes after emoji font changes or loading. SSR output is unaffected;
+// detected unsupported glyphs are hidden.
+//
+// Detection runs in two phases so it never stalls the first paint.
+// Drawing every sequence costs 0.2-0.8 s of main-thread time, depending
+// on the browser and font, so before paint the picker samples one glyph
+// per emoji version and a country flag, and predicts from that. Sequences
+// about to be shown (cells near the viewport, their skin tones and the
+// reactions) are then checked exactly in cached pixel batches between
+// tasks. Exact results replace predictions: one version sample cannot
+// prove font coverage.
+
+export const DEFAULT_NATIVE_EMOJI_FONT =
+  '"Segoe UI Emoji", "Segoe UI Symbol", "Segoe UI", "Apple Color Emoji", "Twemoji Mozilla", "Noto Color Emoji", "EmojiOne Color", "Android Emoji"';
+
+const BASELINE_EMOJI = '\u{1F600}'; // grinning face (Emoji 1.0)
+
+const FLAG_SAMPLE = '1f1fa-1f1f8'; // regional indicators U + S
+
+export type NativeEmojiProbe = ReturnType<
+  typeof createNativeEmojiSequenceSupport
+>;
+
+/**
+ * Platform support as filtering reads it. `supports` returns a probed
+ * identity's exact result (null when inconclusive, undefined when not
+ * probed yet); the version and flag fields predict the rest.
+ */
+export type NativeEmojiSupport = {
+  supports: (unified: string) => boolean | null | undefined;
+  /** Emoji versions whose sample the font cannot draw. */
+  failedVersions: Set<number>;
+  countryFlags: boolean;
+};
+
+export const UNKNOWN_SUPPORT = {};
+
+let cache = new WeakMap<
+  Document,
+  Map<string, NativeEmojiProbe | typeof UNKNOWN_SUPPORT>
+>();
+
+/**
+ * Probes the font synchronously, sampling versions and flags only.
+ * Exact sequence results accumulate on the returned probe through
+ * `prime`, which pickers call in background batches.
+ */
+export function detectNativeEmojiSupport(
+  fontFamily: string = DEFAULT_NATIVE_EMOJI_FONT,
+  refresh = false,
+  ownerDocument: Document | undefined = typeof document === 'undefined'
+    ? undefined
+    : document,
+): NativeEmojiProbe | typeof UNKNOWN_SUPPORT {
+  if (!ownerDocument) return UNKNOWN_SUPPORT;
+  const fonts =
+    cache.get(ownerDocument) ||
+    new Map<string, NativeEmojiProbe | typeof UNKNOWN_SUPPORT>();
+  cache.set(ownerDocument, fonts);
+  if (refresh) fonts.delete(fontFamily);
+  const cached = fonts.get(fontFamily);
+  if (cached) {
+    return cached;
+  }
+  const result = probe(fontFamily, ownerDocument);
+  // Bound retained font caches even when an application switches themes
+  // through many dynamically named families. Mounted Roots retain theirs.
+  if (fonts.size >= 16) fonts.clear();
+  fonts.set(fontFamily, result);
+  return result;
+}
+
+/**
+ * Whether a rendered identity should show. An exact result wins; until
+ * one exists, flags and emojis of a version whose sample failed are
+ * predicted unsupported. `addedIn` is the emoji's version, when known.
+ */
+export function isNativeEmojiSupported(
+  support: NativeEmojiSupport | null,
+  unified: string,
+  addedIn = 0,
+): boolean {
+  const exact = support && support.supports(unified);
+  return typeof exact === 'boolean'
+    ? exact
+    : !support ||
+        !(
+          support.failedVersions.has(addedIn) ||
+          (!support.countryFlags && isCountryFlagUnified(unified))
+        );
+}
+
+/** The picker's view of a probe: frozen results, never drawing. */
+/**
+ * The picker's view of a probe: frozen results, never drawing, plus a
+ * prediction for identities not checked yet. `samples` maps each emoji
+ * version to one emoji introduced in it. Versions are judged one by one:
+ * fonts often draw a newer version's single glyphs but not an older
+ * version's sequences.
+ */
+export function nativeSupportSnapshot(
+  probe: NativeEmojiProbe,
+  samples: Map<number, string>,
+): NativeEmojiSupport {
+  probe.prime([FLAG_SAMPLE, ...samples.values()]);
+  const failedVersions = new Set<number>();
+  samples.forEach((unified, version) => {
+    if (probe.supports(unified) === false) failedVersions.add(version);
+  });
+  return {
+    supports: probe.snapshot(),
+    failedVersions,
+    // Only a definite failure predicts missing flags.
+    countryFlags: probe.supports(FLAG_SAMPLE) !== false,
+  };
+}
+
+/** Test-only: forget cached probe results. */
+export function __resetNativeEmojiSupportForTest(): void {
+  cache = new WeakMap();
+}
+
+function probe(
+  fontFamily: string,
+  ownerDocument: Document,
+): NativeEmojiProbe | typeof UNKNOWN_SUPPORT {
+  if (isJsdom()) return UNKNOWN_SUPPORT;
+  try {
+    const canvas = ownerDocument.createElement('canvas');
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    if (!ctx) return UNKNOWN_SUPPORT;
+    ctx.font = `24px ${fontFamily}`;
+    ctx.textBaseline = 'top';
+    const baselineWidth = ctx.measureText(BASELINE_EMOJI).width;
+    const sequences = createNativeEmojiSequenceSupport(ctx, baselineWidth);
+    // A stable baseline rejects text fallback, noise and blocked readbacks.
+    if (!baselineWidth || sequences.supports('1f600') !== true)
+      return UNKNOWN_SUPPORT;
+    return sequences;
+  } catch {
+    return UNKNOWN_SUPPORT;
+  }
+}
+
+/** Whether a unified code is a regional-indicator country flag. */
+export function isCountryFlagUnified(unified: string): boolean {
+  // Regional-indicator pairs, plus tag-sequence subdivision flags: fonts
+  // without the former lack the latter too.
+  return /^(1f1[ef][\da-f]-1f1[ef][\da-f]$|1f3f4-e00)/i.test(unified);
+}

package/src/dataUtils/parseNativeEmoji.ts

@@ -1,6 +1,5 @@
 export function parseNativeEmoji(unified: string): string {
-  return unified
-    .split('-')
-    .map((hex) => String.fromCodePoint(parseInt(hex, 16)))
-    .join('');
+  return String.fromCodePoint(
+    ...unified.split('-').map((hex) => parseInt(hex, 16)),
+  );
 }

package/src/dataUtils/suggested.ts

@@ -1,7 +1,11 @@
-import { SkinTones, SuggestionMode } from '../types/exposedTypes';
+import {
+  SkinTones,
+  SuggestionMode,
+  SuggestionModeValue,
+} from '../types/exposedTypes';
 
 import { DataEmoji } from './DataTypes';
-import { emojiUnified } from './emojiUtils';
+import { emojiUnified, emojiCanonicalUnified } from './emojiUtils';
 
 const SUGGESTED_LS_KEY = 'epr_suggested';
 
@@ -13,7 +17,7 @@ type SuggestedItem = {
 
 type Suggested = SuggestedItem[];
 
-export function getSuggested(mode?: SuggestionMode): Suggested {
+export function getSuggested(mode?: SuggestionModeValue): Suggested {
   try {
     if (typeof window === 'undefined' || !window.localStorage) {
       return [];
@@ -36,7 +40,7 @@ export function setSuggested(emoji: DataEmoji, skinTone: SkinTones) {
   const recent = getSuggested();
 
   const unified = emojiUnified(emoji, skinTone);
-  const originalUnified = emojiUnified(emoji);
+  const originalUnified = emojiCanonicalUnified(emoji);
 
   let existing = recent.find(({ unified: u }) => u === unified);
 

package/src/dataUtils/suggestedEmojis.ts

@@ -0,0 +1,92 @@
+import { DataEmoji, EmojiProperties } from './DataTypes';
+
+// Caller-defined Suggested contents.
+//
+// While `suggestedEmojis` is present it fully determines the Suggested
+// category contents/order and `suggestedEmojisMode` is ignored for
+// selection/order. One case-insensitive rule covers both Unicode and
+// custom IDs, matching how `customEmojis` are indexed (lowercased on
+// entry). A valid skin-tone variation keeps that exact variation for
+// rendering rather than collapsing to the neutral base. Unknown entries
+// are ignored; duplicates collapse by resolved render identity with first
+// occurrence winning; caller order is otherwise preserved. The input
+// array is never mutated. Native emoji characters ("🧠", "©️") are accepted
+// too and resolved to their unified ID, so apps that store recents as the
+// characters they insert can pass them through unchanged.
+
+export function resolveSuggestedRenderIds(
+  entries: readonly string[],
+  lookup: (normalizedId: string) => DataEmoji | undefined,
+): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const entry of entries) {
+    if (typeof entry !== 'string') {
+      continue;
+    }
+    const id = resolveEntryId(entry.trim().toLowerCase(), lookup);
+    if (!id || seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    result.push(id);
+  }
+
+  return result;
+}
+
+/**
+ * A lowercased unified ID, custom ID or emoji character, resolved to a
+ * known render identity (see resolveSuggestedRenderIds).
+ */
+export function resolveEntryId(
+  id: string,
+  lookup: (normalizedId: string) => DataEmoji | undefined,
+): string | undefined {
+  if (!id) {
+    return undefined;
+  }
+  if (isKnownRenderId(id, lookup)) {
+    return id;
+  }
+  // Unified IDs and custom IDs are ASCII; anything else may be the
+  // emoji character itself.
+  if (Array.from(id).every((char) => (char.codePointAt(0) as number) < 0x80)) {
+    return undefined;
+  }
+  return nativeToUnifiedCandidates(id).find((candidate) =>
+    isKnownRenderId(candidate, lookup),
+  );
+}
+
+// Dataset IDs are zero-padded code points joined by "-", and carry U+FE0F
+// where the emoji presentation needs it; typed or stored characters often
+// omit or add it. Try the exact sequence, then without FE0F, then with
+// FE0F after the first code point (e.g. "©" -> "00a9-fe0f").
+function nativeToUnifiedCandidates(native: string): string[] {
+  const codePoints = Array.from(native).map((char) =>
+    (char.codePointAt(0) as number).toString(16).padStart(4, '0'),
+  );
+  const exact = codePoints.join('-');
+  const bare = codePoints.filter((codePoint) => codePoint !== 'fe0f');
+  const withPresentation = [bare[0], 'fe0f', ...bare.slice(1)];
+  return [exact, bare.join('-'), withPresentation.join('-')];
+}
+
+// A render identity is valid only as the base unified or a listed
+// variation. Anything else — e.g. a nonexistent variation that fell back
+// to the base record — is unknown and ignored.
+function isKnownRenderId(
+  id: string,
+  lookup: (normalizedId: string) => DataEmoji | undefined,
+): boolean {
+  const record = lookup(id);
+  if (!record) {
+    return false;
+  }
+  return (
+    record[EmojiProperties.unified] === id ||
+    (record[EmojiProperties.variations] ?? []).includes(id)
+  );
+}

package/src/env.d.ts

@@ -0,0 +1,4 @@
+// Build-time environment flag, replaced or provided by the consumer's
+// bundler/runtime. Declared minimally so the library does not depend on
+// Node's type definitions.
+declare const process: { env: { NODE_ENV?: string } };

package/src/hooks/preloadEmoji.ts

@@ -1,57 +1,12 @@
 import { GetEmojiUrl } from '../components/emoji/BaseEmojiProps';
 import { DataEmoji } from '../dataUtils/DataTypes';
 import { emojiUnified, emojiVariations } from '../dataUtils/emojiUtils';
-import { EmojiStyle } from '../types/exposedTypes';
-import { Dimensions } from '../virtualization/virtualizationHelpers';
-
-// eslint-disable-next-line max-params
-export function preloadEmojiIfNeeded(
-  emoji: undefined | DataEmoji,
-  emojiStyles: EmojiStyle,
-  scrollTop: number,
-  clientHeight: number,
-  topOffset: number,
-  style: { top: number } | undefined,
-  dimensions: Dimensions,
-  getEmojiUrl: GetEmojiUrl,
-): void {
-  if (!emoji) {
-    return;
-  }
-
-  if (emojiStyles === EmojiStyle.NATIVE) {
-    return;
-  }
-
-  const unified = emojiUnified(emoji);
-
-  if (preloadedEmojs.has(unified)) {
-    return;
-  }
-
-  // preload only if the emoji is a few rows below the viewport
-  if (!style || !dimensions) {
-    return;
-  }
-
-  setTimeout(() => {
-    const emojiTop = topOffset + style.top;
-    const viewportBottom = scrollTop + clientHeight;
-
-    const isJustBelowViewport =
-      emojiTop >= viewportBottom &&
-      emojiTop < viewportBottom + dimensions.emojiSize * 2;
-
-    if (isJustBelowViewport) {
-      preloadEmoji(getEmojiUrl, emoji, emojiStyles);
-    }
-  });
-}
+import { EmojiStyleValue } from '../types/exposedTypes';
 
 export function preloadEmoji(
   getEmojiUrl: GetEmojiUrl,
   emoji: undefined | DataEmoji,
-  emojiStyle: EmojiStyle,
+  emojiStyle: EmojiStyleValue,
 ): void {
   if (!emoji) {
     return;

package/src/hooks/useActiveCategoryScrollDetection.ts

@@ -1,9 +1,12 @@
 import { useEffect } from 'react';
 
 import { categoryNameFromDom } from '../DomUtils/categoryNameFromDom';
-import { asSelectors, ClassNames } from '../DomUtils/classNames';
+import { ClassNames } from '../DomUtils/classNames';
 import { useBodyRef } from '../components/context/ElementRefContext';
-import { CategoriesConfig } from '../config/categoryConfig';
+import {
+  CategoriesConfig,
+  categoryIdFromCategoryConfig,
+} from '../config/categoryConfig';
 
 export function useActiveCategoryScrollDetection({
   setActiveCategory,
@@ -22,8 +25,11 @@ export function useActiveCategoryScrollDetection({
   const BodyRef = useBodyRef();
 
   useEffect(() => {
-    const visibleCategories = new Map<string, number>();
-    const intersectingCategories = new Map<string, boolean>();
+    if (typeof IntersectionObserver === 'undefined') {
+      setVisibleCategories(categories.map(categoryIdFromCategoryConfig));
+      return;
+    }
+    const observed = new Map<string, IntersectionObserverEntry>();
     const bodyRef = BodyRef.current;
     const observer = new IntersectionObserver(
       (entries) => {
@@ -38,24 +44,32 @@ export function useActiveCategoryScrollDetection({
             continue;
           }
 
-          visibleCategories.set(id, entry.intersectionRatio);
-          intersectingCategories.set(id, entry.isIntersecting);
+          observed.set(id, entry);
         }
 
-        const ratios = Array.from(visibleCategories);
+        const ratios = Array.from(observed);
         const visibleCats = ratios
-          .filter(([id, ratio]) => ratio > 0 || intersectingCategories.get(id))
+          .filter(
+            ([, entry]) => entry.intersectionRatio > 0 || entry.isIntersecting,
+          )
           .map(([id]) => id);
 
         setVisibleCategories(visibleCats);
         const lastCategory = ratios[ratios.length - 1];
 
-        if (lastCategory?.[1] == 1) {
+        if (lastCategory?.[1].intersectionRatio === 1) {
           return setActiveCategory(lastCategory[0]);
         }
 
-        for (const [id, ratio] of ratios) {
-          if (ratio) {
+        const viewportTop = bodyRef.getBoundingClientRect().top;
+        for (const [id, entry] of ratios) {
+          // Fractional offsets can leave less than a pixel of the preceding
+          // section intersecting after a jump. It must not steal the tab
+          // highlight from the section aligned with the viewport top.
+          if (
+            entry.intersectionRatio &&
+            entry.target.getBoundingClientRect().bottom > viewportTop + 1
+          ) {
             setActiveCategory(id);
             break;
           }
@@ -66,11 +80,9 @@ export function useActiveCategoryScrollDetection({
         threshold: [0, 1],
       },
     );
-    bodyRef
-      ?.querySelectorAll(asSelectors(ClassNames.category))
-      .forEach((el) => {
-        observer.observe(el);
-      });
+    bodyRef?.querySelectorAll(`.${ClassNames.category}`).forEach((el) => {
+      observer.observe(el);
+    });
 
     return () => {
       observer.disconnect();

package/src/hooks/useCategoryHeight.ts

@@ -1,35 +1,94 @@
 import * as React from 'react';
 
-import { EmojiButtonSelector } from '../DomUtils/selectors';
+import { ClassNames } from '../DomUtils/classNames';
 import {
+  elementBorderBoxHeight,
+  EmojiButtonSelector,
+} from '../DomUtils/selectors';
+import {
+  useBodyRef,
   useEmojiListRef,
   usePickerMainRef,
 } from '../components/context/ElementRefContext';
 import {
+  useNavigationRegistry,
   useReactionsModeState,
   useVisibleCategoriesState,
   useEmojiSizeState,
 } from '../components/context/PickerContext';
+import { useColumnsConfig } from '../config/useConfig';
+
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
 
 const EMOJI_SIZE_DEFAULT = 40;
 
-export function useCategoryHeight(emojiCount: number):
+// Rows live inside the category content box, not the full list:
+// category margins/padding shrink the usable width, and dividing
+// the raw list width would overcount columns so the last emoji in
+// every row spills past the content edge (into the scrollbar).
+// Measure a rendered, visible content box when one exists; fall back
+// to the list width (identical when categories carry no horizontal
+// inset). Hidden categories report zero width and are skipped.
+function firstVisibleContentWidth(
+  listEl: HTMLElement,
+  fallbackWidth: number,
+): number {
+  const contentBoxes = listEl.querySelectorAll(
+    `.${ClassNames.categoryContent}`,
+  );
+  for (const box of Array.from(contentBoxes)) {
+    const width = (box as HTMLElement).clientWidth;
+    if (width > 0) {
+      return width;
+    }
+  }
+  return fallbackWidth;
+}
+
+// A column-count change obsoletes rows computed by pending keyboard
+// navigation.
+function trackColumnCount(
+  previousRef: React.MutableRefObject<number | undefined>,
+  emojisPerRow: number,
+  registry: { invalidate(): void },
+): void {
+  if (
+    previousRef.current !== undefined &&
+    previousRef.current !== emojisPerRow
+  ) {
+    registry.invalidate();
+  }
+  previousRef.current = emojisPerRow;
+}
+
+export function useCategoryHeight(
+  emojiCount: number,
+  ready = true,
+):
   | {
       categoryHeight: number;
       emojisPerRow: number;
       emojiSize: number;
+      rowWidth: number;
+      viewportHeight?: number;
     }
   | undefined {
   const EmojiListRef = useEmojiListRef();
+  const BodyRef = useBodyRef();
   const [isReactionsMode] = useReactionsModeState();
   const PickerMainRef = usePickerMainRef();
-  const emojiSizeRef = React.useRef<number | undefined>();
+  const emojiSizeRef = React.useRef<number | undefined>(undefined);
+  const emojisPerRowRef = React.useRef<number | undefined>(undefined);
+  const registry = useNavigationRegistry();
   const [visibleCategories] = useVisibleCategoriesState();
   const [emojiSizeFromContext] = useEmojiSizeState();
+  const columns = useColumnsConfig();
   const [dimensions, setDimensions] = React.useState<{
     categoryHeight: number;
     emojisPerRow: number;
     emojiSize: number;
+    rowWidth: number;
+    viewportHeight?: number;
   }>();
 
   // Helper to compute and store dimensions based on current DOM
@@ -41,36 +100,83 @@ export function useCategoryHeight(emojiCount: number):
       EmojiButtonSelector,
     ) as HTMLElement | null;
 
-    const measured = emojiElement?.clientHeight;
+    // Border-box geometry includes design-library button borders.
+    const measured = elementBorderBoxHeight(emojiElement);
     if (measured) {
       emojiSizeRef.current = measured;
     }
     const emojiSize =
-      emojiSizeFromContext ||
       measured ||
+      emojiSizeFromContext ||
       emojiSizeRef.current ||
       EMOJI_SIZE_DEFAULT;
     const pickerWidth = listEl.clientWidth;
 
     if (pickerWidth === 0 || emojiSize === 0) return;
 
-    const emojisPerRow = Math.max(1, Math.floor(pickerWidth / emojiSize));
+    const rowWidth = firstVisibleContentWidth(listEl, pickerWidth);
+    const fit = Math.max(1, Math.floor(rowWidth / emojiSize));
+    const emojisPerRow = columns ? Math.min(columns, fit) : fit;
     const rowCount = Math.ceil(emojiCount / emojisPerRow);
     const categoryHeight = rowCount * emojiSize;
 
-    setDimensions({ categoryHeight, emojisPerRow, emojiSize });
-  }, [EmojiListRef, emojiCount, emojiSizeFromContext]);
+    const next = {
+      categoryHeight,
+      emojisPerRow,
+      emojiSize,
+      rowWidth,
+      // Virtualization reads the viewport height during render, so a picker
+      // that mounts collapsed (reactions first) must re-render once it opens.
+      viewportHeight: BodyRef.current?.clientHeight,
+    };
 
-  // Recompute on data-count changes and when reactions mode toggles
-  React.useEffect(() => {
+    trackColumnCount(emojisPerRowRef, emojisPerRow, registry);
+    // Returning `previous` when nothing changed is what stops the layout
+    // effect below, which depends on `dimensions`, from looping forever.
+    // Both objects come from the literal above, so their keys share an order.
+    setDimensions((previous) =>
+      JSON.stringify(previous) === JSON.stringify(next) ? previous : next,
+    );
+  }, [
+    EmojiListRef,
+    BodyRef,
+    emojiCount,
+    emojiSizeFromContext,
+    registry,
+    columns,
+  ]);
+
+  // Restore measured row heights in the same commit as the filtered
+  // contents. A passive effect leaves one frame of stale offsets that
+  // category navigation can observe immediately after clearing search.
+  // Recheck an estimated size when positioned/visible cells first mount.
+  useIsomorphicLayoutEffect(() => {
     computeAndSetDimensions();
   }, [
     emojiCount,
     isReactionsMode,
     computeAndSetDimensions,
     visibleCategories.length,
+    dimensions,
+    ready,
   ]);
 
+  // Fluid layouts (width: 100%, sheets, docks) resize without a CSS
+  // transition: recompute columns when the list's width changes.
+  React.useEffect(() => {
+    const listEl = EmojiListRef.current;
+    if (!listEl || typeof ResizeObserver === 'undefined') return;
+    let lastWidth = listEl.clientWidth;
+    const observer = new ResizeObserver(() => {
+      const width = listEl.clientWidth;
+      if (width === lastWidth) return;
+      lastWidth = width;
+      computeAndSetDimensions();
+    });
+    observer.observe(listEl);
+    return () => observer.disconnect();
+  }, [EmojiListRef, computeAndSetDimensions]);
+
   // Listen to transitionend on the picker root (where height transition occurs)
   React.useEffect(() => {
     const rootEl = PickerMainRef.current;