@zyncat/ui 0.11.0 → 0.13.0

package/src/components/composites/emoji-picker/EmojiPickerPanel.tsx

@@ -0,0 +1,153 @@
+'use client';
+
+import './styles.css';
+
+import { useImperativeHandle, useMemo, useState, type ReactElement, type Ref } from 'react';
+
+import { useMediaQuery } from '../../internal/hooks/use-media-query';
+import { Icon } from '../../internal/icon/Icon';
+import type { ActivateOn } from '../../internal/utils/activation';
+import { TextField } from '../../primitives/input/TextField';
+import { Popover, type PopoverProps, type VirtualAnchor } from '../popover/Popover';
+import { Sheet, type SheetProps } from '../sheet/Sheet';
+import { CategoryBar } from './react/category-bar';
+import { useEmojiPicker, type EmojiPickerStore } from './react/useEmojiPicker';
+import type { GetEmojiUrl } from './types';
+
+export { loadEmojiData, onEmojiDataLoaded, type EmojiData, type Emoji } from './data';
+export { getEmojiUrl } from './getEmojiUrl';
+export type { GetEmojiUrl, EmojiUrlSource } from './types';
+
+export const SHEET_BREAKPOINT = '(max-width: 40rem)';
+
+type Forwarded = 'open' | 'onOpenChange' | 'trigger' | 'children' | 'htmlProps';
+
+export type EmojiPickerHandle = Pick<EmojiPickerStore, 'renderAll' | 'renderFiltered' | 'handleKey' | 'selectFocused'>;
+
+export interface EmojiPickerPanelProps {
+  /** Controlled open state - the panel has no uncontrolled mode. */
+  open: boolean;
+  /** Fires whenever the panel asks to open or close: trigger press, Esc, outside press, sheet drag. */
+  onOpenChange: (open: boolean) => void;
+  /** Fires on pick, with the primary shortcode (`smile`, no colons) and the emoji's hex id. */
+  onSelect: (shortcode: string, hexId: string) => void;
+  /** Builds the image URL for one emoji at one call site. Pass the bundled `getEmojiUrl` to use Twemoji and Noto. */
+  getEmojiUrl: GetEmojiUrl;
+  /** Element that both opens the panel and anchors it, when there is no anchor. */
+  trigger?: ReactElement | null;
+  /** Gap in pixels between a custom `popoverProps.anchor` and the panel. Ignored when the panel anchors to its trigger. */
+  offset?: number;
+  /** Render the panel's own search field. Always on in sheet mode, where the
+   *  sheet traps focus and an outside query can no longer reach the panel. */
+  search?: boolean;
+  /** Drive the results from outside — a `:` chip in a document, your own input. */
+  query?: string;
+  /** Whether the trigger, an emoji and a category fire on `pointerdown` (snappier) or wait for `click`. @default 'click' */
+  activateOn?: ActivateOn;
+  /** Viewport at which the panel becomes a bottom sheet. */
+  breakpoint?: string;
+  /** Desktop placement — `anchor`, `side`, `align`, `arrow`, and every other Popover knob. */
+  popoverProps?: Omit<PopoverProps, Forwarded>;
+  /** Narrow-viewport docking — `container`, `dismissible`, and every other Sheet knob. */
+  sheetProps?: Omit<SheetProps, Forwarded | 'side'>;
+  /** Extra class(es) merged onto the panel frame. */
+  className?: string;
+  /** Imperative handle - drive the grid from your own field: `handleKey`, `selectFocused`, `renderAll`, `renderFiltered`. */
+  ref?: Ref<EmojiPickerHandle>;
+}
+
+const inflate = (anchor: VirtualAnchor | null | undefined, by: number): VirtualAnchor | null => {
+  if (!anchor || !by) return anchor ?? null;
+  return {
+    getBoundingClientRect: () => {
+      const r = anchor.getBoundingClientRect();
+      return new DOMRect(r.x - by, r.y - by, r.width + by * 2, r.height + by * 2);
+    },
+  };
+};
+
+export function EmojiPickerPanel({
+  open,
+  onOpenChange,
+  onSelect,
+  getEmojiUrl,
+  trigger = null,
+  offset = 0,
+  search = false,
+  query,
+  activateOn,
+  breakpoint = SHEET_BREAKPOINT,
+  popoverProps,
+  sheetProps,
+  className,
+  ref,
+}: EmojiPickerPanelProps) {
+  const asSheet = useMediaQuery(breakpoint);
+  const [ownQuery, setOwnQuery] = useState('');
+  const drivenFromOutside = !asSheet && query !== undefined;
+  const picker = useEmojiPicker({ onSelect, getEmojiUrl, query: drivenFromOutside ? query : ownQuery, activateOn });
+
+  useImperativeHandle(ref, () => picker, [picker]);
+
+  const { mount, searchRef, searchProps, handleKey } = picker;
+  const anchor = popoverProps?.anchor;
+  const positioned = useMemo(() => inflate(anchor, offset), [anchor, offset]);
+
+  const frame = (
+    <div className={['on-emoji', asSheet && 'on-emoji--sheet', className].filter(Boolean).join(' ')}>
+      {asSheet || search ? (
+        <div className="on-emoji-search" ref={searchRef}>
+          <TextField
+            size="sm"
+            type="search"
+            clearable
+            placeholder="Search emoji"
+            leadingIcon={<Icon name="magnifying-glass" size="sm" />}
+            value={ownQuery}
+            onChange={(e) => setOwnQuery(e.target.value)}
+            onKeyDown={(e) => {
+              const horizontal = e.key === 'ArrowLeft' || e.key === 'ArrowRight';
+              if (horizontal && e.currentTarget.value) return;
+              if (e.key.startsWith('Arrow') || e.key === 'Enter') handleKey(e.nativeEvent);
+            }}
+            htmlProps={{ ...searchProps, autoFocus: true, spellCheck: false, 'aria-label': 'Search emoji' }}
+          />
+        </div>
+      ) : null}
+      <CategoryBar store={picker} activateOn={activateOn} />
+      <div ref={mount} />
+    </div>
+  );
+
+  return asSheet ? (
+    <Sheet
+      {...sheetProps}
+      open={open}
+      onOpenChange={onOpenChange}
+      side="bottom"
+      trigger={trigger}
+      activateOn={activateOn}
+      htmlProps={{ className: 'on-emoji-sheet' }}
+    >
+      <div role="dialog" aria-label="Emoji picker">
+        {frame}
+      </div>
+    </Sheet>
+  ) : (
+    <Popover
+      side="right"
+      align="center"
+      {...popoverProps}
+      anchor={positioned}
+      open={open}
+      onOpenChange={onOpenChange}
+      trigger={trigger}
+      activateOn={activateOn}
+      // Its exit because, emojipicker as of now looses frames during entry and entry animation is non existence on the "entrance" curve as a result
+      animation={{ ease: { open: 'exit' } }}
+      htmlProps={{ className: 'on-emoji-pop', 'aria-label': 'Emoji picker' }}
+    >
+      {frame}
+    </Popover>
+  );
+}

package/src/components/composites/emoji-picker/EmojiPickerPanel.usage.md

@@ -0,0 +1,26 @@
+# EmojiPickerPanel - @zyncat/ui/emoji-picker
+
+Group: overlays
+Docs: https://ui.zyncat.app/emoji-picker
+
+Searchable emoji panel - grid, scrollspy category rail, recents in localStorage - living in a Popover, becoming a bottom Sheet on narrow viewports.
+
+Matching is word-based, not fuzzy. The dataset is NOT bundled: call loadEmojiData(url | EmojiData)
+once before the panel first opens or it throws; onEmojiDataLoaded(cb) fires when it lands.
+getEmojiUrl is REQUIRED. Two shapes. search renders the panel's own field, opened from trigger.
+query drives the grid from an input YOU own - point popoverProps.anchor at the caret rect and
+forward keys through the ref.
+
+```tsx
+import { EmojiPickerPanel, getEmojiUrl, loadEmojiData } from '@zyncat/ui/emoji-picker';
+
+loadEmojiData('/emojis.json'); // once, before the panel first opens
+<EmojiPickerPanel
+  open={open}
+  onOpenChange={setOpen}
+  onSelect={addReaction}
+  getEmojiUrl={getEmojiUrl}
+  search
+  trigger={<Button variant="secondary">Add reaction</Button>}
+/>;
+```

package/src/components/composites/emoji-picker/category-icons.ts

@@ -0,0 +1,29 @@
+export const CATEGORY_ICONS: Record<string, string> = {
+  recent: '<circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/>',
+  'smileys-emotion':
+    '<circle cx="12" cy="12" r="10"/><path d="M8 14s1.5 2 4 2 4-2 4-2"/><line x1="9" x2="9.01" y1="9" y2="9"/><line x1="15" x2="15.01" y1="9" y2="9"/>',
+  'people-body':
+    '<path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2"/><circle cx="9" cy="7" r="4"/><path d="M22 21v-2a4 4 0 0 0-3-3.87"/><path d="M16 3.13a4 4 0 0 1 0 7.75"/>',
+  'animals-nature':
+    '<path d="M11 20A7 7 0 0 1 9.8 6.1C15.5 5 17 4.48 19 2c1 2 2 4.18 2 8 0 5.5-4.78 10-10 10Z"/><path d="M2 21c0-3 1.85-5.36 5.08-6C9.5 14.52 12 13 13 12"/>',
+  'food-drink':
+    '<path d="M3 2v7c0 1.1.9 2 2 2h4a2 2 0 0 0 2-2V2"/><path d="M7 2v20"/><path d="M21 15V2a5 5 0 0 0-5 5v6c0 1.1.9 2 2 2h3Zm0 0v7"/>',
+  'travel-places':
+    '<path d="M17.8 19.2 16 11l3.5-3.5C21 6 21.5 4 21 3c-1-.5-3 0-4.5 1.5L13 8 4.8 6.2c-.5-.1-.9.1-1.1.5l-.3.5c-.2.5-.1 1 .3 1.3L9 12l-2 3H4l-1 1 3 2 2 3 1-1v-3l3-2 3.5 5.3c.3.4.8.5 1.3.3l.5-.2c.4-.3.6-.7.5-1.2z"/>',
+  activities:
+    '<path d="M6 9H4.5a2.5 2.5 0 0 1 0-5H6"/><path d="M18 9h1.5a2.5 2.5 0 0 0 0-5H18"/><path d="M4 22h16"/><path d="M10 14.66V17c0 .55-.47.98-.97 1.21C7.85 18.75 7 20.24 7 22"/><path d="M14 14.66V17c0 .55.47.98.97 1.21C16.15 18.75 17 20.24 17 22"/><path d="M18 2H6v7a6 6 0 0 0 12 0V2Z"/>',
+  objects:
+    '<path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/>',
+  symbols:
+    '<line x1="4" x2="20" y1="9" y2="9"/><line x1="4" x2="20" y1="15" y2="15"/><line x1="10" x2="8" y1="3" y2="21"/><line x1="16" x2="14" y1="3" y2="21"/>',
+  flags: '<path d="M4 15s1-1 4-1 5 2 8 2 4-1 4-1V3s-1 1-4 1-5-2-8-2-4 1-4 1z"/><line x1="4" x2="4" y1="22" y2="15"/>',
+};
+
+export const CATEGORY_ICON_ATTRS = {
+  viewBox: '0 0 24 24',
+  fill: 'none',
+  stroke: 'currentColor',
+  strokeWidth: 2,
+  strokeLinecap: 'round',
+  strokeLinejoin: 'round',
+} as const;

package/src/components/composites/emoji-picker/data.ts

@@ -0,0 +1,83 @@
+export interface EmojiSkin {
+  unified: string;
+  native: string;
+  tone?: number | number[];
+}
+
+export interface Emoji {
+  id: string;
+  name: string;
+  unicode: string;
+  tags: string[];
+  skins: EmojiSkin[];
+  group: number;
+  shortcodes: string[];
+}
+
+export interface EmojiCategory {
+  id: string;
+  icon: string;
+  emojis: string[];
+}
+
+export interface EmojiData {
+  emojis: Record<string, Emoji>;
+  categories: EmojiCategory[];
+}
+
+let _cache: EmojiData | null = null;
+let _emojiArray: Emoji[] | null = null;
+let _inflight: Promise<EmojiData> | null = null;
+const _listeners = new Set<() => void>();
+
+const _setEmojiData = (data: EmojiData) => {
+  _cache = data;
+  _emojiArray = Object.values(data.emojis);
+  for (const cb of _listeners) cb();
+  _listeners.clear();
+  return data;
+};
+
+/** Run `cb` once the emoji data is available. Fires immediately if already loaded. */
+export function onEmojiDataLoaded(cb: () => void): () => void {
+  if (_cache) {
+    cb();
+    return () => {};
+  }
+  _listeners.add(cb);
+  return () => {
+    _listeners.delete(cb);
+  };
+}
+
+/**
+ * Load the emoji dataset. Pass a URL to fetch it, or an already-parsed
+ * `EmojiData` object to install it directly. Idempotent — the first call wins.
+ */
+export async function loadEmojiData(loader: string | EmojiData) {
+  if (!_inflight) {
+    if (typeof loader !== 'string') {
+      _setEmojiData(loader);
+      return;
+    }
+
+    _inflight = fetch(loader)
+      .then((r) => r.json())
+      .then(_setEmojiData)
+      .catch((err) => {
+        _inflight = null;
+        throw err;
+      });
+  }
+
+  return _inflight;
+}
+
+/** Synchronous access — only valid after loadEmojiData() has resolved */
+export function getEmojiData(): EmojiData | null {
+  return _cache;
+}
+
+export function getEmojiArray(): Emoji[] {
+  return _emojiArray ? _emojiArray : [];
+}

package/src/components/composites/emoji-picker/dom.ts

@@ -0,0 +1,79 @@
+import { getEmojiData, type Emoji } from './data';
+import type { GetEmojiUrl } from './types';
+
+export const COLUMN_COUNT = 8;
+
+export interface GridSection {
+  key: string;
+  header: HTMLElement;
+  start: number;
+  count: number;
+}
+
+export const el = <K extends keyof HTMLElementTagNameMap>(tag: K, className: string): HTMLElementTagNameMap[K] => {
+  const node = document.createElement(tag);
+  node.className = className;
+  return node;
+};
+
+const attr = (value: string) => value.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
+
+export function createEmojiGrid(scroll: HTMLDivElement, getEmojiUrl: GetEmojiUrl, tileIdPrefix: string) {
+  const buttons: HTMLButtonElement[] = [];
+  const sections: GridSection[] = [];
+  const timers: number[] = [];
+
+  const swapInNativeGlyph = (e: Event) => {
+    const img = e.target as HTMLImageElement;
+    if (img.matches?.('.on-emoji-btn-img')) img.parentElement!.textContent = img.alt;
+  };
+  scroll.addEventListener('error', swapInNativeGlyph, true);
+
+  const tile = (emoji: Emoji, idx: number, order: number) =>
+    `<button type="button" role="option" tabindex="-1" class="on-emoji-btn" id="${attr(tileIdPrefix + idx)}" aria-label="${attr(emoji.name)}" data-id="${emoji.id}" data-idx="${idx}" style="--i:${order}">` +
+    `<img class="on-emoji-btn-img" src="${attr(getEmojiUrl(emoji.id, 'picker-grid'))}" loading="lazy" draggable="false" alt="${attr(emoji.unicode)}"></button>`;
+
+  const addCategory = (title: string, key: string, ids: string[]) => {
+    const data = getEmojiData();
+    if (!data) return;
+
+    const header = el('div', 'on-emoji-header');
+    header.textContent = title;
+    header.setAttribute('aria-hidden', 'true');
+    scroll.appendChild(header);
+
+    const start = buttons.length;
+    const emojis = ids.map((id) => data.emojis[id]).filter(Boolean);
+    const grid = el('div', 'on-emoji-grid');
+    grid.setAttribute('role', 'group');
+    grid.setAttribute('aria-label', title);
+    grid.style.setProperty('--cols', String(COLUMN_COUNT));
+    grid.style.setProperty('--rows', String(Math.ceil(emojis.length / COLUMN_COUNT)));
+    grid.innerHTML = emojis.map((emoji, i) => tile(emoji, start + i, i)).join('');
+    scroll.appendChild(grid);
+
+    buttons.push(...(grid.children as HTMLCollectionOf<HTMLButtonElement>));
+    if (emojis.length) sections.push({ key, header, start, count: emojis.length });
+  };
+
+  const indexOfKey = (key: string) => sections.findIndex((s) => s.key === key);
+
+  const showEmpty = (message: string) => {
+    scroll.insertAdjacentHTML('beforeend', `<div class="on-emoji-empty">${attr(message)}</div>`);
+  };
+
+  const clear = () => {
+    timers.forEach(clearTimeout);
+    timers.length = 0;
+    scroll.innerHTML = '';
+    buttons.length = 0;
+    sections.length = 0;
+  };
+
+  const destroy = () => {
+    clear();
+    scroll.removeEventListener('error', swapInNativeGlyph, true);
+  };
+
+  return { buttons, sections, timers, addCategory, showEmpty, clear, indexOfKey, destroy };
+}

package/src/components/composites/emoji-picker/getEmojiUrl.ts

@@ -0,0 +1,17 @@
+import type { GetEmojiUrl } from './types';
+
+const TWEMOJI = 'https://cdn.jsdelivr.net/gh/jdecked/twemoji@latest/assets';
+const NOTO_ANIMATED = 'https://fonts.gstatic.com/s/e/notoemoji/latest';
+
+export const getEmojiUrl: GetEmojiUrl = (hexId, source): string => {
+  const lower = hexId.toLowerCase();
+  switch (source) {
+    case 'inline':
+      return `${TWEMOJI}/svg/${lower}.svg`;
+    case 'picker-grid':
+      return `${TWEMOJI}/72x72/${lower}.png`;
+    case 'category-bar':
+    case 'callout-icon':
+      return `${NOTO_ANIMATED}/${lower.replace(/-/g, '_')}/512.webp`;
+  }
+};

package/src/components/composites/emoji-picker/navigation.ts

@@ -0,0 +1,86 @@
+import { COLUMN_COUNT, type GridSection } from './dom';
+
+const MOVES: Record<string, [number, number]> = {
+  ArrowRight: [1, 0],
+  ArrowLeft: [-1, 0],
+  ArrowDown: [0, 1],
+  ArrowUp: [0, -1],
+};
+
+export function createNavigator(
+  buttons: HTMLButtonElement[],
+  sections: GridSection[],
+  onFocus: (button: HTMLButtonElement | null) => void,
+) {
+  let focusedIdx = -1;
+  let desiredCol = 0;
+
+  const sectionOf = (idx: number) => sections.findIndex((s) => idx >= s.start && idx < s.start + s.count);
+
+  const landAt = (si: number, rowStart: number, col: number) => {
+    const s = sections[si];
+    return s.start + rowStart + Math.min(col, Math.min(COLUMN_COUNT, s.count - rowStart) - 1);
+  };
+
+  const focusAt = (next: number, scroll = true) => {
+    if (!buttons.length) return;
+    const clamped = Math.max(0, Math.min(next, buttons.length - 1));
+    if (clamped === focusedIdx) return;
+    onFocus(buttons[clamped]);
+    if (scroll) buttons[clamped].scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+    focusedIdx = clamped;
+  };
+
+  const setFocus = (next: number, scroll = true) => {
+    focusAt(next, scroll);
+    const si = sectionOf(focusedIdx);
+    desiredCol = si >= 0 ? (focusedIdx - sections[si].start) % COLUMN_COUNT : 0;
+  };
+
+  const move = (dx: number, dy: number) => {
+    if (focusedIdx < 0) return setFocus(0);
+    const si = sectionOf(focusedIdx);
+    if (si < 0) return;
+    const s = sections[si];
+    const local = focusedIdx - s.start;
+    const rowStart = local - (local % COLUMN_COUNT);
+
+    if (dx) {
+      const next = focusedIdx + dx;
+      if (next >= s.start && next < s.start + s.count) return setFocus(next);
+      if (dx > 0 && si + 1 < sections.length) return setFocus(sections[si + 1].start);
+      if (dx < 0 && si > 0) return setFocus(sections[si - 1].start + sections[si - 1].count - 1);
+      return;
+    }
+
+    const targetRow = rowStart + dy * COLUMN_COUNT;
+    if (targetRow >= 0 && targetRow < s.count) focusAt(landAt(si, targetRow, desiredCol));
+    else if (dy > 0 && si + 1 < sections.length) focusAt(landAt(si + 1, 0, desiredCol));
+    else if (dy < 0 && si > 0) {
+      const prev = sections[si - 1];
+      focusAt(landAt(si - 1, Math.floor((prev.count - 1) / COLUMN_COUNT) * COLUMN_COUNT, desiredCol));
+    } else setFocus(dy > 0 ? buttons.length - 1 : 0);
+  };
+
+  const handleKey = (event: KeyboardEvent, onEnter: () => void): boolean => {
+    if (!buttons.length) return false;
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      onEnter();
+      return true;
+    }
+    const delta = MOVES[event.key];
+    if (!delta) return false;
+    event.preventDefault();
+    move(delta[0], delta[1]);
+    return true;
+  };
+
+  const reset = () => {
+    focusedIdx = -1;
+    desiredCol = 0;
+    onFocus(null);
+  };
+
+  return { setFocus, handleKey, reset, getFocusedIdx: () => focusedIdx };
+}

package/src/components/composites/emoji-picker/picker.ts

@@ -0,0 +1,169 @@
+import {
+  clickActivates,
+  declinePointerDown,
+  pointerDownActivates,
+  type ActivateOn,
+} from '../../internal/utils/activation';
+import { getEmojiData } from './data';
+import { createEmojiGrid } from './dom';
+import { createNavigator } from './navigation';
+import { createScaffold } from './scaffold';
+import { getRankedEmojiIds } from './search';
+import type { GetEmojiUrl } from './types';
+
+const STORAGE_KEY = 'recentEmojis';
+const MAX_RECENT = 18;
+const SPY_READING_LINE = 12;
+
+export interface EmojiPickerOptions {
+  onSelect: (shortcode: string, id: string) => void;
+  getEmojiUrl: GetEmojiUrl;
+  listboxId: string;
+  getFocusHost?: () => HTMLElement | null;
+  getActivateOn?: () => ActivateOn | undefined;
+  onCategoriesChange?: (keys: string[]) => void;
+  onActiveCategoryChange?: (key: string | null) => void;
+}
+
+export type EmojiPickerApi = ReturnType<typeof createEmojiPicker>;
+
+export function createEmojiPicker(root: HTMLElement, options: EmojiPickerOptions) {
+  const emojiData = getEmojiData();
+  if (!emojiData) throw new Error('Emoji data not found');
+
+  let recent: string[] =
+    typeof localStorage !== 'undefined' ? JSON.parse(localStorage.getItem(STORAGE_KEY) || '[]') : [];
+  let activeKey: string | null = null;
+  let spyFrame = 0;
+
+  const ui = createScaffold(root, emojiData, options.getEmojiUrl, options.listboxId);
+  const area = createEmojiGrid(ui.scroll, options.getEmojiUrl, `${options.listboxId}-o`);
+
+  let activeTile: HTMLButtonElement | null = null;
+  const nav = createNavigator(area.buttons, area.sections, (btn) => {
+    activeTile?.removeAttribute('aria-selected');
+    btn?.setAttribute('aria-selected', 'true');
+    activeTile = btn;
+    const host = options.getFocusHost?.();
+    if (btn) host?.setAttribute('aria-activedescendant', btn.id);
+    else host?.removeAttribute('aria-activedescendant');
+    ui.positionMarker(btn);
+    ui.setCaption(btn);
+  });
+
+  const spy = () => {
+    spyFrame = 0;
+    const line = ui.scroll.scrollTop + SPY_READING_LINE;
+    let current = 0;
+    for (let i = 0; i < area.sections.length; i++) {
+      if (area.sections[i].header.offsetTop <= line) current = i;
+      else break;
+    }
+    const key = area.sections[current]?.key ?? null;
+    if (key === activeKey) return;
+    activeKey = key;
+    options.onActiveCategoryChange?.(key);
+  };
+
+  const scheduleSpy = () => {
+    if (!spyFrame) spyFrame = requestAnimationFrame(spy);
+  };
+
+  const selectById = (id: string) => {
+    const shortcode = emojiData.emojis[id]?.shortcodes[0];
+    if (!shortcode) return;
+    recent = [id, ...recent.filter((x) => x !== id)].slice(0, MAX_RECENT);
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(recent));
+    options.onSelect(shortcode, id);
+  };
+
+  const selectFocused = () => {
+    const id = area.buttons[nav.getFocusedIdx()]?.dataset.id;
+    if (id) selectById(id);
+  };
+
+  const handleMouseMove = (e: MouseEvent) => {
+    const btn = (e.target as HTMLElement).closest('button');
+    if (btn?.dataset.idx) nav.setFocus(parseInt(btn.dataset.idx));
+  };
+
+  const selectPressed = (e: Event) => {
+    const btn = (e.target as HTMLElement).closest('button');
+    if (btn?.dataset.id && ui.scroll.contains(btn)) selectById(btn.dataset.id);
+  };
+
+  const handlePointerDown = (e: PointerEvent) => {
+    if (options.getActivateOn?.() !== 'pointerdown') return declinePointerDown();
+    if (pointerDownActivates(e, true)) selectPressed(e);
+  };
+
+  const handleClick = (e: PointerEvent) => {
+    e.preventDefault();
+    if (clickActivates(e)) selectPressed(e);
+  };
+
+  ui.scroll.addEventListener('scroll', scheduleSpy, { passive: true });
+  ui.scroll.addEventListener('mousemove', handleMouseMove, { passive: true });
+  root.addEventListener('pointerdown', handlePointerDown);
+  root.addEventListener('click', handleClick);
+
+  const beginRender = (keys: string[]) => {
+    area.clear();
+    nav.reset();
+    ui.mountMarker();
+    activeKey = null;
+    options.onCategoriesChange?.(keys);
+    options.onActiveCategoryChange?.(null);
+  };
+
+  const renderAll = () => {
+    const keys = emojiData.categories.map((c) => c.id);
+    const hasRecent = recent.length > 0;
+    beginRender(hasRecent ? ['recent', ...keys] : keys);
+    if (hasRecent) area.addCategory('Recently Used', 'recent', recent);
+
+    let i = 0;
+    const step = () => {
+      const category = emojiData.categories[i++];
+      if (!category) return;
+      area.addCategory(category.id.replace('-', ' & '), category.id, category.emojis);
+      spy();
+      area.timers.push(window.setTimeout(step, 200));
+    };
+    step();
+  };
+
+  const renderFiltered = (query: string) => {
+    beginRender([]);
+    const ids = getRankedEmojiIds(query);
+    if (!ids.length) return area.showEmpty('No emojis found');
+    area.addCategory('Results', 'search', ids);
+    nav.setFocus(0, false);
+  };
+
+  const scrollToCategory = (key: string) => {
+    const section = area.sections[area.indexOfKey(key)];
+    if (!section) return;
+    area.buttons[section.start].scrollIntoView({ block: 'start', behavior: 'smooth' });
+    nav.setFocus(section.start, false);
+  };
+
+  const destroy = () => {
+    area.destroy();
+    if (spyFrame) cancelAnimationFrame(spyFrame);
+    ui.scroll.removeEventListener('scroll', scheduleSpy);
+    ui.scroll.removeEventListener('mousemove', handleMouseMove);
+    root.removeEventListener('pointerdown', handlePointerDown);
+    root.removeEventListener('click', handleClick);
+    root.innerHTML = '';
+  };
+
+  return {
+    renderAll,
+    renderFiltered,
+    scrollToCategory,
+    handleKey: (event: KeyboardEvent) => nav.handleKey(event, selectFocused),
+    selectFocused,
+    destroy,
+  };
+}