emoji-picker-react 4.22.2 → 5.0.0

package/src/config/useConfig.ts

@@ -1,24 +1,25 @@
 import * as React from 'react';
 
-import { usePickerConfig } from '../components/context/PickerConfigContext';
+import {
+  usePickerConfig,
+  useSearchSliceConfig,
+} from '../components/context/PickerConfigContext';
 import { useReactionsModeState } from '../components/context/PickerContext';
 import {
   EmojiClickData,
-  EmojiStyle,
+  EmojiStyleValue,
   SkinTonePickerLocation,
   SkinTones,
-  SuggestionMode,
-  Theme,
+  SuggestionModeValue,
+  ThemeValue,
 } from '../types/exposedTypes';
 
 import { CategoriesConfig } from './categoryConfig';
 import {
+  DEFAULT_LABELS,
   DEFAULT_SEARCH_PLACEHOLDER,
-  DEFAULT_SEARCH_CLEAR_BUTTON_LABEL,
-  SEARCH_RESULTS_NO_RESULTS_FOUND,
-  SEARCH_RESULTS_ONE_RESULT_FOUND,
-  SEARCH_RESULTS_MULTIPLE_RESULTS_FOUND,
   PickerDimensions,
+  PickerLabels,
   PreviewConfig,
 } from './config';
 import { CustomEmoji } from './customEmojiConfig';
@@ -29,23 +30,68 @@ export enum MOUSE_EVENT_SOURCE {
   PICKER = 'picker',
 }
 
+/**
+ * Resolved user-facing strings: English defaults, then the legacy
+ * individual props, then `labels` (highest precedence).
+ */
+export function useLabels(): PickerLabels {
+  const {
+    labels,
+    searchPlaceHolder,
+    searchPlaceholder,
+    searchLabel,
+    searchClearButtonLabel,
+  } = usePickerConfig();
+  return React.useMemo(() => {
+    const legacyPlaceholder = [searchPlaceHolder, searchPlaceholder].find(
+      (p) => p !== undefined && p !== DEFAULT_SEARCH_PLACEHOLDER,
+    );
+    const resolved: PickerLabels = { ...DEFAULT_LABELS };
+    if (legacyPlaceholder !== undefined) {
+      resolved.searchPlaceholder = legacyPlaceholder;
+    }
+    if (searchLabel !== undefined) {
+      resolved.searchLabel = searchLabel;
+    }
+    if (searchClearButtonLabel !== undefined) {
+      resolved.searchClear = searchClearButtonLabel;
+    }
+    if (labels) {
+      for (const key of Object.keys(labels) as Array<keyof PickerLabels>) {
+        const value = labels[key];
+        if (value !== undefined) {
+          resolved[key] = value;
+        }
+      }
+    }
+    return resolved;
+  }, [
+    labels,
+    searchPlaceHolder,
+    searchPlaceholder,
+    searchLabel,
+    searchClearButtonLabel,
+  ]);
+}
+
 export function useSearchPlaceHolderConfig(): string {
-  const { searchPlaceHolder, searchPlaceholder } = usePickerConfig();
-  return (
-    [searchPlaceHolder, searchPlaceholder].find(
-      (p) => p !== DEFAULT_SEARCH_PLACEHOLDER,
-    ) ?? DEFAULT_SEARCH_PLACEHOLDER
-  );
+  return useLabels().searchPlaceholder;
 }
 
 export function useSearchClearButtonLabelConfig(): string {
-  const { searchClearButtonLabel } = usePickerConfig();
-  return searchClearButtonLabel ?? DEFAULT_SEARCH_CLEAR_BUTTON_LABEL;
+  return useLabels().searchClear;
 }
 
+// Literal values are the enum members' own strings, so the public
+// SkinTonesValue narrows to the enum the engine compares against.
 export function useDefaultSkinToneConfig(): SkinTones {
   const { defaultSkinTone } = usePickerConfig();
-  return defaultSkinTone;
+  return defaultSkinTone as SkinTones;
+}
+
+export function useSkinToneConfig(): SkinTones | undefined {
+  const { skinTone } = usePickerConfig();
+  return skinTone as SkinTones | undefined;
 }
 
 export function useAllowExpandReactions(): boolean {
@@ -58,7 +104,7 @@ export function useSkinTonesDisabledConfig(): boolean {
   return skinTonesDisabled;
 }
 
-export function useEmojiStyleConfig(): EmojiStyle {
+export function useEmojiStyleConfig(): EmojiStyleValue {
   const { emojiStyle } = usePickerConfig();
   return emojiStyle;
 }
@@ -91,23 +137,36 @@ export function useOpenConfig(): boolean {
 export function useOnEmojiClickConfig(
   mouseEventSource: MOUSE_EVENT_SOURCE,
 ): (emoji: EmojiClickData, event: MouseEvent) => void {
+  // The ref object is stable; callbacks are read at call time so a
+  // subscribed listener always invokes the latest parent callback even
+  // when the memoized tree skips rerendering on callback-only updates.
+  // Reading them during render would freeze the first-render callback
+  // into every listener closure.
   const { current } = useMutableConfig();
   const [, setReactionsOpen] = useReactionsModeState();
 
-  const handler = current.onEmojiClick || (() => {});
-  const { onReactionClick } = current;
-
-  if (mouseEventSource === MOUSE_EVENT_SOURCE.REACTIONS && onReactionClick) {
-    return (...args) =>
-      onReactionClick(...args, {
+  if (mouseEventSource === MOUSE_EVENT_SOURCE.REACTIONS) {
+    return (...args) => {
+      const onReactionClick = current.onReactionClick;
+      if (onReactionClick) {
+        return onReactionClick(...args, {
+          collapseToReactions: () => {
+            setReactionsOpen(true);
+          },
+        });
+      }
+      const onEmojiClick = current.onEmojiClick || noop;
+      return onEmojiClick(...args, {
         collapseToReactions: () => {
-          setReactionsOpen((o) => o);
+          setReactionsOpen(true);
         },
       });
+    };
   }
 
   return (...args) => {
-    handler(...args, {
+    const onEmojiClick = current.onEmojiClick || noop;
+    return onEmojiClick(...args, {
       collapseToReactions: () => {
         setReactionsOpen(true);
       },
@@ -118,7 +177,9 @@ export function useOnEmojiClickConfig(
 export function useOnSkinToneChangeConfig(): (skinTone: SkinTones) => void {
   const { current } = useMutableConfig();
 
-  return current.onSkinToneChange || (() => {});
+  return (skinTone: SkinTones) => {
+    current.onSkinToneChange?.(skinTone);
+  };
 }
 
 export function usePreviewConfig(): PreviewConfig {
@@ -126,13 +187,13 @@ export function usePreviewConfig(): PreviewConfig {
   return previewConfig;
 }
 
-export function useThemeConfig(): Theme {
+export function useThemeConfig(): ThemeValue {
   const { theme } = usePickerConfig();
 
   return theme;
 }
 
-export function useSuggestedEmojisModeConfig(): SuggestionMode {
+export function useSuggestedEmojisModeConfig(): SuggestionModeValue {
   const { suggestedEmojisMode } = usePickerConfig();
   return suggestedEmojisMode;
 }
@@ -157,6 +218,17 @@ export function useReactionsOpenConfig(): boolean {
   return reactionsDefaultOpen;
 }
 
+export function useColumnsConfig(): number | undefined {
+  const { columns } = usePickerConfig();
+  return validColumns(columns);
+}
+
+export function validColumns(columns: unknown): number | undefined {
+  return Number.isInteger(columns) && (columns as number) > 0
+    ? (columns as number)
+    : undefined;
+}
+
 export function useEmojiVersionConfig(): string | null {
   const { emojiVersion } = usePickerConfig();
   return emojiVersion;
@@ -184,30 +256,51 @@ export function useReactionsConfig(): string[] {
 
 export function useGetEmojiUrlConfig(): (
   unified: string,
-  style: EmojiStyle,
+  style: EmojiStyleValue,
 ) => string {
   const { getEmojiUrl } = usePickerConfig();
   return getEmojiUrl;
 }
 
+export function useSearchValueConfig(): string | undefined {
+  const { searchValue } = useSearchSliceConfig();
+  return searchValue;
+}
+
+export function useDefaultSearchValueConfig(): string | undefined {
+  const { defaultSearchValue } = useSearchSliceConfig();
+  return defaultSearchValue;
+}
+
+export function useSearchLabelConfig(): string {
+  return useLabels().searchLabel;
+}
+
+export function useSuggestedEmojisConfig(): string[] | undefined {
+  const { suggestedEmojis } = usePickerConfig();
+  return suggestedEmojis;
+}
+
+function noop() {}
+
 function getDimension(dimensionConfig: PickerDimensions): PickerDimensions {
   return typeof dimensionConfig === 'number'
     ? `${dimensionConfig}px`
     : dimensionConfig;
 }
 
-export function useSearchResultsConfig(searchResultsCount: number): string {
+export function formatSearchResultsLabel(
+  labels: PickerLabels,
+  searchResultsCount: number,
+): string {
   const hasResults = searchResultsCount > 0;
   const isPlural = searchResultsCount > 1;
 
   if (hasResults) {
     return isPlural
-      ? SEARCH_RESULTS_MULTIPLE_RESULTS_FOUND.replace(
-          '%n',
-          searchResultsCount.toString(),
-        )
-      : SEARCH_RESULTS_ONE_RESULT_FOUND;
+      ? labels.searchResultsMany.replace('%n', searchResultsCount.toString())
+      : labels.searchResultsOne;
   }
 
-  return SEARCH_RESULTS_NO_RESULTS_FOUND;
+  return labels.searchResultsNone;
 }

package/src/data/defaultEmojiData.ts

@@ -0,0 +1,49 @@
+import type { EmojiData } from '../types/exposedTypes';
+
+// The bundled English dataset is no longer a static dependency of the
+// picker core. Entry points that promise synchronous data (the default
+// `emoji-picker-react` entry and `emoji-picker-react/data`) register it on
+// import; `emoji-picker-react/primitives` does not, so a lean composition
+// ships without it and loads it on demand (a separate chunk in ESM builds)
+// unless `emojiData` is supplied.
+
+let registered: EmojiData | null = null;
+
+export function registerDefaultEmojiData(data: EmojiData): void {
+  registered = data;
+}
+
+export function getRegisteredDefaultEmojiData(): EmojiData | null {
+  return registered;
+}
+
+/** Stable empty dataset used while data is loading. */
+export const EMPTY_EMOJI_DATA: EmojiData = Object.freeze({
+  categories: {},
+  emojis: {},
+}) as EmojiData;
+
+/** The registered dataset, or the empty placeholder before registration. */
+export function defaultEmojiDataOrEmpty(): EmojiData {
+  return registered ?? EMPTY_EMOJI_DATA;
+}
+
+let pending: Promise<EmojiData> | null = null;
+
+/** Load (once) and register the bundled English dataset. */
+export function loadDefaultEmojiData(): Promise<EmojiData> {
+  if (registered) {
+    return Promise.resolve(registered);
+  }
+  if (!pending) {
+    pending = import('./emojis').then((module) => {
+      const data = (module.default ?? module) as unknown as EmojiData;
+      registered = registered ?? data;
+      return registered;
+    }).catch((error) => {
+      pending = null;
+      throw error;
+    });
+  }
+  return pending;
+}

package/src/data/registerDefaultEmojiData.ts

@@ -0,0 +1,8 @@
+// Side-effect module: makes the bundled English dataset available
+// synchronously. Imported by entries that guarantee sync data.
+import type { EmojiData } from '../types/exposedTypes';
+
+import { registerDefaultEmojiData } from './defaultEmojiData';
+import emojis from './emojis';
+
+registerDefaultEmojiData(emojis as unknown as EmojiData);

package/src/data-core/pickerData.ts

@@ -0,0 +1,173 @@
+// Shared picker-data derivation.
+//
+// Requirements:
+// - prepare/search-index immutable emoji data outside transient UI state;
+// - cache prepared base data by `emojiData` object identity (WeakMap);
+// - default packaged data shares one prepared base core across Roots;
+// - custom-emoji derivation cached separately by `customEmojis` identity;
+// - `emojiVersion` and `hiddenEmojis` stay per-Root filtering layers and MUST NOT
+//   force rebuilding the base index;
+// - caller-provided `emojiData` and `customEmojis` are never mutated;
+// - do not JSON stringify/parse the complete dataset on each Root mount;
+// - no React / ShipStyles imports in this module graph.
+
+import type { CustomEmoji } from '../config/customEmojiConfig';
+import { defaultEmojiDataOrEmpty } from '../data/defaultEmojiData';
+import {
+  DataEmoji,
+  DataEmojis,
+  EmojiProperties,
+  EmojiProperties as Keys,
+} from '../dataUtils/DataTypes';
+import { Categories, type EmojiData } from '../types/exposedTypes';
+
+import { getPreparedCore } from './prepare';
+
+export interface PickerDataSnapshot {
+  emojiData: EmojiData;
+  allEmojis: DataEmojis;
+  allEmojisByUnified: Record<string, DataEmoji>;
+  customGroups: Record<string, DataEmojis>;
+}
+
+interface CustomLayer {
+  /** Ungrouped customs: becomes `emojis[CUSTOM]` when customs are present. */
+  ungrouped: DataEmojis;
+  groups: Record<string, DataEmojis>;
+}
+
+const customLayerCache = new WeakMap<object, CustomLayer>();
+const EMPTY_CUSTOM_LAYER: CustomLayer = {
+  ungrouped: [],
+  groups: Object.create(null),
+};
+
+// Outer key: dataset source object. Inner key: customEmojis array identity,
+// or NO_CUSTOM sentinel when no customs are supplied.
+const snapshotCache = new WeakMap<object, WeakMap<object, PickerDataSnapshot>>();
+const NO_CUSTOM: object = {};
+
+function customToRegularEmoji(emoji: CustomEmoji): DataEmoji {
+  return {
+    [EmojiProperties.name]: emoji.names.map((name: string) =>
+      name.toLowerCase(),
+    ),
+    [EmojiProperties.unified]: emoji.id.toLowerCase(),
+    [EmojiProperties.added_in]: '0',
+    [EmojiProperties.imgUrl]: emoji.imgUrl,
+  };
+}
+
+function getCustomLayer(customEmojis?: CustomEmoji[]): CustomLayer {
+  if (!customEmojis || customEmojis.length === 0) {
+    return EMPTY_CUSTOM_LAYER;
+  }
+  const cached = customLayerCache.get(customEmojis);
+  if (cached) {
+    return cached;
+  }
+  // Never mutate caller data: derive fresh objects/arrays only.
+  const groups: Record<string, DataEmojis> = Object.create(null);
+  const ungrouped: DataEmojis = [];
+  for (const emoji of customEmojis) {
+    const derived = customToRegularEmoji(emoji);
+    if (emoji.group) {
+      groups[emoji.group] = groups[emoji.group] ?? [];
+      groups[emoji.group].push(derived);
+    } else {
+      ungrouped.push(derived);
+    }
+  }
+  const layer: CustomLayer = { ungrouped, groups };
+  customLayerCache.set(customEmojis, layer);
+  return layer;
+}
+
+export function getPickerDataSnapshot(
+  genericEmojiData?: EmojiData,
+  customEmojis?: CustomEmoji[],
+): PickerDataSnapshot {
+  const source = (genericEmojiData ??
+    defaultEmojiDataOrEmpty()) as EmojiData;
+
+  // Warm the shared prepared core the picker actually searches through
+  // (queryFilterDict in PickerDataContext). One construction per dataset
+  // identity backs the "one base index for 10 same-dataset Roots"
+  // invariant; there is no second per-snapshot index.
+  getPreparedCore(source);
+
+  const hasCustoms = !!customEmojis && customEmojis.length > 0;
+  const customKey: object = hasCustoms
+    ? (customEmojis as object)
+    : NO_CUSTOM;
+
+  let inner = snapshotCache.get(source);
+  if (inner) {
+    const hit = inner.get(customKey);
+    if (hit) {
+      return hit;
+    }
+  } else {
+    inner = new WeakMap<object, PickerDataSnapshot>();
+    snapshotCache.set(source, inner);
+  }
+
+  const customLayer = getCustomLayer(customEmojis);
+
+  // Shallow structural copy only: every non-custom category array keeps its
+  // shared source reference. No JSON clone of the full dataset, no mutation
+  // (and no freezing) of caller-provided data.
+  const sourceEmojis = source.emojis ?? {};
+  const nextEmojis: Record<string, DataEmoji[]> = { ...sourceEmojis };
+  if (hasCustoms) {
+    nextEmojis[Categories.CUSTOM] = customLayer.ungrouped as DataEmoji[];
+  }
+
+  const emojiData = {
+    ...source,
+    emojis: nextEmojis,
+  } as EmojiData;
+
+  const customGroups = customLayer.groups;
+
+  const allEmojis: DataEmojis = Object.values(nextEmojis)
+    .concat(Object.values(customGroups))
+    .flat();
+
+  const allEmojisByUnified: Record<string, DataEmoji> = Object.create(null);
+
+  allEmojis.forEach((emoji) => {
+    const unified = emoji[Keys.unified];
+    allEmojisByUnified[unified] = emoji;
+
+    if (emoji[Keys.variations]) {
+      emoji[Keys.variations]?.forEach((variation) => {
+        allEmojisByUnified[variation] = emoji;
+      });
+    }
+  });
+
+  const snapshot: PickerDataSnapshot = {
+    emojiData,
+    allEmojis,
+    allEmojisByUnified,
+    customGroups,
+  };
+  inner.set(customKey, snapshot);
+  return snapshot;
+}
+
+/** Test-only: expose cache state without breaking WeakMap encapsulation. */
+export function __isSnapshotCached(
+  genericEmojiData?: EmojiData,
+  customEmojis?: CustomEmoji[],
+): boolean {
+  const source = (genericEmojiData ??
+    defaultEmojiDataOrEmpty()) as EmojiData;
+  const inner = snapshotCache.get(source);
+  if (!inner) {
+    return false;
+  }
+  const hasCustoms = !!customEmojis && customEmojis.length > 0;
+  return inner.has(hasCustoms ? (customEmojis as object) : NO_CUSTOM);
+}

package/src/data-core/prepare.ts

@@ -0,0 +1,178 @@
+// Pure immutable prepared-data core for v5.
+//
+// Requirements (see also docs/v5/DATA_API.md):
+// - prepare/search-index immutable emoji data outside transient UI state;
+// - cache prepared base data by `emojiData` object identity (WeakMap);
+// - default packaged data shares one prepared core across Roots;
+// - caller-provided data is never mutated or frozen;
+// - prepared public records are deeply frozen once and safely shared;
+// - no JSON stringify/parse of the full dataset per Root;
+// - no React / ShipStyles imports in this module graph.
+
+import { defaultEmojiDataOrEmpty } from '../data/defaultEmojiData';
+import { parseNativeEmoji } from '../dataUtils/parseNativeEmoji';
+import type { EmojiData } from '../types/exposedTypes';
+
+import type { EmojiInfo } from './types';
+
+export interface PreparedCore {
+  /** Stable dataset order of canonical base records. */
+  readonly records: readonly EmojiInfo[];
+  /** Base unified -> record plus variation unified -> base record. */
+  readonly byUnified: ReadonlyMap<string, EmojiInfo>;
+  /**
+   * Single-character bucket: char -> base records whose joined lowercase
+   * names include it, in dataset order. Preserves v4's useful O(1)
+   * first-keystroke narrowing on top of the shared immutable core, so
+   * cold single-char queries never pay a full scan.
+   */
+  readonly byChar: ReadonlyMap<string, readonly EmojiInfo[]>;
+  /** Per-core query memo: normalized query -> matching records. */
+  readonly queryMemo: Map<string, readonly EmojiInfo[]>;
+}
+
+const coreCache = new WeakMap<object, PreparedCore>();
+
+// Instrumentation for the deterministic multi-root sharing invariant:
+// mounting N Roots against the same dataset identity must construct the
+// base index exactly once. Tests assert on this counter, not on timing.
+let prepareCount = 0;
+
+export function __getPrepareCount(): number {
+  return prepareCount;
+}
+
+export function __resetPrepareCount(): void {
+  prepareCount = 0;
+}
+
+export function __clearCoreCacheForTest(): void {
+  // WeakMap has no clear(); tests that need a cold cache can use a fresh
+  // dataset object identity instead. Kept as explicit no-op guard.
+}
+
+export function normalizeUnified(input: string): string {
+  return input.trim().toLowerCase();
+}
+
+export function normalizeQuery(input: string): string {
+  if (!input || typeof input !== 'string') {
+    return '';
+  }
+  return input.trim().toLowerCase();
+}
+
+function toEmojiInfo(
+  unified: string,
+  names: readonly string[],
+  variations: readonly string[] | undefined,
+  addedIn: string,
+): EmojiInfo {
+  return Object.freeze({
+    unified,
+    emoji: parseNativeEmoji(unified),
+    name: names[names.length - 1] || '',
+    names: Object.freeze([...names]),
+    variations: Object.freeze([...(variations ?? [])]),
+    addedIn,
+  });
+}
+
+function readStringArray(raw: unknown): string[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return (raw.filter((n) => typeof n === 'string') as string[]).map((n) =>
+    n.toLowerCase(),
+  );
+}
+
+function appendEntry(
+  byUnified: Map<string, EmojiInfo>,
+  byCharMutable: Map<string, EmojiInfo[]>,
+  records: EmojiInfo[],
+  entry: unknown,
+): void {
+  // Never mutate caller data: read raw fields defensively.
+  const rawUnified = (entry as { u?: unknown }).u;
+  if (typeof rawUnified !== 'string' || rawUnified.length === 0) {
+    return;
+  }
+  const unified = rawUnified.toLowerCase();
+  if (byUnified.has(unified)) {
+    return;
+  }
+
+  const names = readStringArray((entry as { n?: unknown }).n);
+  const variations = readStringArray((entry as { v?: unknown }).v);
+
+  const rawAddedIn = (entry as { a?: unknown }).a;
+  const addedIn =
+    typeof rawAddedIn === 'string' ? rawAddedIn : String(rawAddedIn ?? '');
+
+  const info = toEmojiInfo(unified, names, variations, addedIn);
+  records.push(info);
+  byUnified.set(unified, info);
+  for (const variation of info.variations) {
+    if (!byUnified.has(variation)) {
+      byUnified.set(variation, info);
+    }
+  }
+  indexCharBucket(byCharMutable, names, info);
+}
+
+// One bucket entry per distinct character keeps the per-record cost
+// proportional to name length, not name length squared.
+function indexCharBucket(
+  byCharMutable: Map<string, EmojiInfo[]>,
+  names: readonly string[],
+  info: EmojiInfo,
+): void {
+  const distinctChars = Array.from(new Set(names.join('')));
+  for (const char of distinctChars) {
+    const bucket = byCharMutable.get(char);
+    if (bucket) {
+      bucket.push(info);
+    } else {
+      byCharMutable.set(char, [info]);
+    }
+  }
+}
+
+export function getPreparedCore(emojiData?: EmojiData): PreparedCore {
+  const source = (emojiData ?? defaultEmojiDataOrEmpty()) as EmojiData;
+  const cached = coreCache.get(source);
+  if (cached) {
+    return cached;
+  }
+
+  prepareCount += 1;
+
+  const byUnified = new Map<string, EmojiInfo>();
+  const byCharMutable = new Map<string, EmojiInfo[]>();
+  const records: EmojiInfo[] = [];
+
+  const groups = source.emojis ?? {};
+
+  for (const key of Object.keys(groups)) {
+    const list = groups[key] ?? [];
+    for (const entry of list) {
+      appendEntry(byUnified, byCharMutable, records, entry);
+    }
+  }
+
+  const byChar = new Map<string, readonly EmojiInfo[]>();
+  byCharMutable.forEach((bucket, char) => {
+    byChar.set(char, Object.freeze(bucket));
+  });
+
+  const core: PreparedCore = {
+    records,
+    byUnified,
+    byChar,
+    queryMemo: new Map<string, readonly EmojiInfo[]>(),
+  };
+
+  coreCache.set(source, core);
+  return core;
+}