goemoji 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+Формат: [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/),
+версии — [Semantic Versioning](https://semver.org/lang/ru/).
+
+## [0.3.0] — 2026-09-25
+
+### Добавлено
+
+- `useEmojiData` возвращает `loading` и сбрасывает данные при смене `deps`.
+- Меню тонов кожи управляется с клавиатуры (стрелки, Home/End, Escape).
+
+### Исправлено
+
+- `columns <= 0` больше не зацикливает раскладку сетки; некорректные
+  `columns` и `cellSize` приводятся к безопасным значениям.
+- `sameEmojiValue` больше не путает id серверного эмодзи с его суффиксом.
+- Смена `recentKey` перечитывает «Недавние» из localStorage.
+- Активная ячейка сбрасывается при смене данных и раскладки.
+- Escape закрывает открытое меню тонов, не закрывая весь пикер.
+- Анимация скролла учитывает `prefers-reduced-motion`.
+- `customEmojiUrl` клампит размер картинки к диапазону Discord.
+
+## [0.2.0] — 2026-09-22
+
+### Изменено
+
+- Секция и вкладка серверных эмодзи переехали в начало списка.
+- Вкладки категорий помещаются в одну строку.
+- Фон поповера тонов кожи сделан непрозрачным.
+
+### Производительность
+
+- Плавный доезд до секции вместо нативного `scroll-behavior: smooth`.
+- Окно виртуализации пересчитывается в rAF, перерисовка — только при сдвиге.
+
+## [0.1.0] — 2026-09-22
+
+Первый выпуск: виртуализированный эмодзи-пикер на React с вкладками категорий,
+поиском по названиям и тегам, тонами кожи, «Недавними» и серверными эмодзи Discord.
+Словари ru/en собраны из emojibase-data.
+
+[0.3.0]: https://github.com/VolRencs/goemoji/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/VolRencs/goemoji/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/VolRencs/goemoji/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VolRencs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# goemoji
+
+An emoji picker for React 19 with category tabs, search by name and tags, skin
+tones, recents, and Discord server emoji. The only dependency is `react` (a peer
+dependency). The `ru`/`en` dictionaries ship inside the package, so nothing is
+fetched from a third-party CDN at runtime.
+
+The build is about 6.2 KB gzip of JavaScript and 1.2 KB gzip of CSS. The
+dictionaries are 50.2 KB gzip (`ru`) and 38.1 KB gzip (`en`) and are loaded
+lazily, so they never end up in the initial bundle.
+
+## Features
+
+- 1914 emoji per locale across 9 categories, with tabs and sticky section headers.
+- Search over localized names and tags, with exact matches ranked first. Server
+  emoji are searchable alongside Unicode and get their own section.
+- Skin tones: one base glyph plus five modifiers. Variants are generated at
+  runtime instead of being stored, and are checked against emojibase in the test
+  suite (1650+ comparisons, no mismatches).
+- Recents: up to 24 emoji in `localStorage`, with a configurable key (for
+  example, one per Discord guild).
+- Server emoji rendered as images, searchable, with an optional guild icon on
+  the tab.
+- A row-virtualized list: while scrolling, React re-renders only the changed
+  window, and tab switches are instant.
+- Keyboard navigation and ARIA markup for `combobox`, `listbox`, `tablist`, and
+  `menu`.
+- SSR-friendly: components carry `"use client"`, and data is loaded on the
+  client through `useEmojiData`.
+
+## Install
+
+```bash
+npm install goemoji
+pnpm add goemoji
+yarn add goemoji
+bun add goemoji
+```
+
+Requires React 19 or newer and a bundler that understands `exports` (Vite,
+Next.js, webpack 5+, Rollup). The package is ESM-only and ships its own type
+declarations.
+
+Install straight from the repository by tag:
+
+```bash
+pnpm add github:VolRencs/goemoji#v0.3.0
+```
+
+## Quick start
+
+```tsx
+import { useState } from "react";
+import { EmojiPicker, useEmojiData, type Emoji, type ServerEmoji } from "goemoji";
+import "goemoji/styles.css";
+
+const serverEmojis: ServerEmoji[] = [
+  { id: "100000000000000001", name: "party_parrot", animated: false },
+  { id: "100000000000000002", name: "cat_jam", animated: true },
+];
+
+export function ReactionPicker() {
+  const [picked, setPicked] = useState("");
+  const { data, error, loading } = useEmojiData(() => import("goemoji/data/ru.json"));
+
+  if (error) return <p>Could not load emoji: {error.message}</p>;
+  if (loading || !data) return <p>Loading emoji…</p>;
+
+  return (
+    <EmojiPicker
+      data={data}
+      serverEmojis={serverEmojis}
+      recentKey="guild:123"
+      onSelect={(emoji: Emoji) => setPicked(emoji.value)}
+    />
+  );
+}
+```
+
+`onSelect` receives an `Emoji`. For Unicode, `value` is the glyph itself
+(`"😀"`); for a server emoji it is a ready-to-store Discord value
+(`"<:name:id>"`, or `"<a:name:id>"` when animated).
+
+If the dictionary is known ahead of time, import it statically:
+
+```ts
+import ru from "goemoji/data/ru.json";
+import { parseEmojiData } from "goemoji";
+
+const data = parseEmojiData(ru);
+```
+
+`parseEmojiData` accepts both the JSON object itself and the namespace object
+(`{ default: … }`) returned by `import()`.
+
+## Data
+
+`data/ru.json` and `data/en.json` are generated from
+[`emojibase-data`](https://github.com/milesj/emojibase) by
+`scripts/build-data.ts` and shipped with the package. The format (v1) is:
+
+```json
+{
+  "v": 1,
+  "locale": "ru",
+  "categories": [{ "key": "smileys-emotion", "label": "Смайлики и люди" }],
+  "emojis": [["😀", "улыбающееся лицо", "улыбка смех", 0]]
+}
+```
+
+Each emoji row is `[emoji, label, space-separated tags, category index]`.
+Skin-tone components (the `component` group) and standalone regional indicators
+are excluded; full flags remain. Skin-tone variants are produced at runtime by
+`skinToneVariation`.
+
+You can build a custom dictionary in the same format and pass it to
+`parseEmojiData`; the component does not require data to come from this package.
+
+## API
+
+### `EmojiPicker`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `EmojiData` | — | Parsed dictionary: `parseEmojiData(...)` or the result of `useEmojiData` |
+| `serverEmojis` | `readonly ServerEmoji[]` | — | Server emoji: their own tab and search entries |
+| `columns` | `number` | `8` | Grid columns; minimum 1, `NaN` falls back to the default |
+| `cellSize` | `number` | `34` | Cell size in pixels; minimum 1, `NaN` falls back to the default |
+| `locale` | `string` | `"ru"` | Built-in label locale: `ru` or `en` |
+| `labels` | `Partial<Labels>` | — | Overrides for individual UI strings |
+| `skinTone` | `SkinTone` | — | Controlled tone; when omitted, the tone is kept in `localStorage` |
+| `onSkinToneChange` | `(tone: SkinTone) => void` | — | Called when the tone changes |
+| `recentKey` | `string \| false` | `"goemoji:recent"` | `localStorage` key for recents; `false` disables them |
+| `onSelect` | `(emoji: Emoji) => void` | — | Required selection handler |
+| `onEscape` | `() => void` | — | Called on Escape once the tone menu is closed |
+| `serverIconUrl` | `string` | — | Image used on the server tab instead of the default icon |
+| `className` | `string` | — | Extra class on the root `.ge-root` element |
+
+The selected tone is stored under the `goemoji:tone` `localStorage` key unless
+`skinTone` is passed. `SkinTone` is one of `"none"`, `"light"`,
+`"medium-light"`, `"medium"`, `"medium-dark"`, `"dark"`.
+
+### `useEmojiData`
+
+```ts
+const { data, error, loading } = useEmojiData(load, deps?);
+```
+
+Loads a dictionary and parses it with `parseEmojiData`. The loader runs on mount
+and again whenever `deps` change; an in-flight request is ignored, and data is
+reset to `null` until the new one resolves. Effects do not run during SSR, so
+`loading` stays `true` there.
+
+### Types
+
+| Type | Fields |
+| --- | --- |
+| `Emoji` | `value: string`, `label: string`, `tags: string`, `category: number`, `server?: { id: string; animated: boolean }` |
+| `ServerEmoji` | `id: string`, `name: string`, `animated: boolean` |
+| `EmojiData` | `locale: string`, `categories: Category[]`, `emojis: Emoji[]` |
+| `Category` | `key: string`, `label: string` |
+| `SlimEmoji` | `[emoji, label, tags, category]` — a raw dictionary row |
+| `Labels` | `search`, `empty`, `recent`, `server`, `skinTone`, `skinTones` |
+
+All types, including `EmojiPickerProps`, are exported from the package root.
+
+### `goemoji/discord`
+
+A React-free entry point for bots, API routes, and reaction handling.
+
+| Function | Description |
+| --- | --- |
+| `parseCustomEmoji(value)` | Parses `<:name:id>` / `<a:name:id>`; returns `null` for Unicode |
+| `customEmojiToString({ name, id, animated? })` | Builds `<a:name:id>` / `<:name:id>` |
+| `customEmojiUrl(id, animated?, size?)` | Discord CDN URL; `size` is clamped to 16–4096 and defaults to 48 |
+| `normalizeEmojiText(value)` | Strips U+FE0E/U+FE0F variation selectors and ZWJ |
+| `sameEmojiValue(saved, name, identifier)` | Matches a stored value against a reaction: custom emoji by id, Unicode by normalized text |
+
+```ts
+import { sameEmojiValue } from "goemoji/discord";
+
+sameEmojiValue("<a:blob:777>", "blob", "blob:777"); // true
+sameEmojiValue("❤️", "❤", "❤"); // true
+```
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| `←` / `→` | Previous or next emoji; wraps to the adjacent row at the edge |
+| `↑` / `↓` | Row above or below, keeping the column where possible |
+| `PageUp` / `PageDown` | Five rows up or down |
+| `Home` / `End` | First or last emoji in the list |
+| `Enter` | Select the active emoji |
+| `Esc` | Close the tone menu, then call `onEscape` |
+
+Focus stays in the search field; the list is linked to it through
+`aria-activedescendant`, following the combobox pattern. While the tone menu is
+open, arrows, `Home`, `End`, and `Esc` control the menu rather than the list.
+
+## Styling
+
+The theme is driven by CSS variables on `.ge-root` (or any ancestor). No
+`!important` is used:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `--ge-bg` | `#1e1f22` | Picker background |
+| `--ge-panel` | `#2b2d31` | Search field and buttons |
+| `--ge-surface` | `#232428` | Tone popover |
+| `--ge-border` | `#1a1b1e` | Borders |
+| `--ge-text` | `#dbdee1` | Primary text |
+| `--ge-muted` | `#949ba4` | Captions and section headers |
+| `--ge-hover` | `rgba(255, 255, 255, 0.06)` | Hover state |
+| `--ge-active` | `rgba(88, 101, 242, 0.4)` | Active cell |
+| `--ge-accent` | `#5865f2` | Accent, focus ring, active tab |
+| `--ge-radius` | `6px` | Corner radius |
+| `--ge-list-height` | `320px` | List height |
+| `--ge-font` | system stack | UI font |
+| `--ge-font-emoji` | system emoji stack | Unicode emoji font |
+
+```css
+.my-picker {
+  --ge-accent: #f2a65a;
+  --ge-list-height: 420px;
+}
+```
+
+Every element uses a `ge-` prefixed class (`ge-root`, `ge-search`, `ge-list`,
+`ge-cell`, `ge-tabs`, and so on), so targeted overrides are possible too, but
+the variables cover most cases.
+
+## Accessibility
+
+- The search field is a `combobox` with `aria-controls` and
+  `aria-activedescendant`; the list is a `listbox`, and cells are `option`
+  elements with `aria-selected`.
+- Category tabs use `tablist`/`tab` with `aria-selected`.
+- The tone menu uses `menu`/`menuitemradio` with `aria-checked`; focus returns
+  to the button on selection or close. Navigation supports arrows, `Home`,
+  `End`, and `Esc`.
+- Clicking outside the popover closes it without stealing focus.
+- The section-scroll animation is disabled under
+  `prefers-reduced-motion: reduce`.
+- Built-in labels are provided for `ru` and `en`; pass `labels` for anything
+  else.
+
+## Performance
+
+The list renders row by row: only the rows inside the virtualization window,
+plus a small overscan, exist in the DOM. On scroll the range is recomputed in a
+`requestAnimationFrame` callback, and React receives new state only when the
+window actually moves. Section headers stick to the top edge, and clicking a tab
+highlights it immediately and glides to the section with a short animation.
+
+Search runs over the in-memory emoji array (1914 entries per locale), so results
+update on every keystroke without debouncing.
+
+## License
+
+Code is MIT. Emoji names and tags come from
+[emojibase](https://github.com/milesj/emojibase) (MIT) and the Unicode CLDR
+annotations (Unicode License v3); see `THIRD_PARTY_NOTICES.md` for details.

package/README.ru.md

@@ -0,0 +1,258 @@
+# goemoji
+
+Пикер эмодзи для React 19: категории с вкладками, поиск по названию и тегам,
+тона кожи, «Недавние» и серверные эмодзи Discord. Единственная зависимость —
+`react` (peer), словари `ru`/`en` лежат внутри пакета, внешние CDN в рантайме не
+нужны.
+
+Размер сборки: около 6.2 КБ gzip JS и 1.2 КБ gzip CSS. Словари занимают
+50.2 КБ gzip (`ru`) и 38.1 КБ gzip (`en`), но подключаются лениво, поэтому в
+первый бандл не попадают.
+
+## Возможности
+
+- 1914 эмодзи в каждой локали, 9 категорий с вкладками и липкими заголовками.
+- Поиск по локализованному названию и тегам с приоритетом точных совпадений;
+  серверные эмодзи ищутся вместе с юникодом и получают отдельную секцию.
+- Тона кожи: базовый глиф и пять модификаторов. Варианты не хранятся в данных,
+  а собираются на лету и сверены с emojibase (1650+ сравнений, расхождений нет).
+- «Недавние» — до 24 эмодзи в localStorage; ключ можно задать свой, например
+  для каждого сервера Discord.
+- Серверные эмодзи рендерятся картинкой, участвуют в поиске и могут иметь
+  собственную иконку на вкладке.
+- Список виртуализирован по строкам: при скролле React перерисовывает только
+  изменившееся окно, вкладки переключаются мгновенно.
+- Управление с клавиатуры и ARIA-разметка `combobox`/`listbox`/`tablist`/`menu`.
+- SSR-совместимость: компоненты помечены `"use client"`, данные грузятся на
+  клиенте через `useEmojiData`.
+
+## Установка
+
+```bash
+npm install goemoji
+pnpm add goemoji
+yarn add goemoji
+bun add goemoji
+```
+
+Нужен React 19 или новее и сборщик, понимающий `exports` (Vite, Next.js,
+webpack 5+, Rollup). Пакет поставляется как ESM вместе с объявлениями типов.
+
+Установка напрямую из репозитория по тегу:
+
+```bash
+pnpm add github:VolRencs/goemoji#v0.3.0
+```
+
+## Быстрый старт
+
+```tsx
+import { useState } from "react";
+import { EmojiPicker, useEmojiData, type Emoji, type ServerEmoji } from "goemoji";
+import "goemoji/styles.css";
+
+const serverEmojis: ServerEmoji[] = [
+  { id: "100000000000000001", name: "party_parrot", animated: false },
+  { id: "100000000000000002", name: "cat_jam", animated: true },
+];
+
+export function ReactionPicker() {
+  const [picked, setPicked] = useState("");
+  const { data, error, loading } = useEmojiData(() => import("goemoji/data/ru.json"));
+
+  if (error) return <p>Не удалось загрузить эмодзи: {error.message}</p>;
+  if (loading || !data) return <p>Загружаем эмодзи…</p>;
+
+  return (
+    <EmojiPicker
+      data={data}
+      serverEmojis={serverEmojis}
+      recentKey="guild:123"
+      onSelect={(emoji: Emoji) => setPicked(emoji.value)}
+    />
+  );
+}
+```
+
+`onSelect` получает объект `Emoji`. У юникода поле `value` содержит глиф
+(`"😀"`), у серверного эмодзи — готовую строку для Discord API и БД
+(`"<:name:id>"` или `"<a:name:id>"` для анимированного).
+
+Если словарь известен заранее, его можно импортировать статически:
+
+```ts
+import ru from "goemoji/data/ru.json";
+import { parseEmojiData } from "goemoji";
+
+const data = parseEmojiData(ru);
+```
+
+`parseEmojiData` принимает как сам JSON-объект, так и namespace ES-модуля вида
+`{ default: … }`, который возвращает `import()`.
+
+## Данные
+
+Файлы `data/ru.json` и `data/en.json` собираются из
+[`emojibase-data`](https://github.com/milesj/emojibase) скриптом
+`scripts/build-data.ts` и лежат в пакете. Формат (v1):
+
+```json
+{
+  "v": 1,
+  "locale": "ru",
+  "categories": [{ "key": "smileys-emotion", "label": "Смайлики и люди" }],
+  "emojis": [["😀", "улыбающееся лицо", "улыбка смех", 0]]
+}
+```
+
+Строка эмодзи — это `[эмодзи, название, теги через пробел, индекс категории]`.
+Из данных исключены компоненты тонов кожи (группа `component`) и региональные
+индикаторы без группы: самостоятельных флагов в списке нет, а тона собираются
+функцией `skinToneVariation` в рантайме.
+
+Свой словарь можно собрать в том же формате и передать в `parseEmojiData` —
+компонент не требует, чтобы данные пришли именно из этого пакета.
+
+## API
+
+### `EmojiPicker`
+
+| Проп | Тип | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `data` | `EmojiData` | — | Разобранный словарь: `parseEmojiData(...)` или результат `useEmojiData` |
+| `serverEmojis` | `readonly ServerEmoji[]` | — | Серверные эмодзи: отдельная вкладка и участие в поиске |
+| `columns` | `number` | `8` | Колонок в сетке; минимум 1, `NaN` заменяется на значение по умолчанию |
+| `cellSize` | `number` | `34` | Сторона ячейки в пикселях; минимум 1, `NaN` заменяется на значение по умолчанию |
+| `locale` | `string` | `"ru"` | Локаль встроенных подписей: `ru` или `en` |
+| `labels` | `Partial<Labels>` | — | Переопределение отдельных строк интерфейса |
+| `skinTone` | `SkinTone` | — | Контролируемый тон кожи; без пропа хранится в localStorage |
+| `onSkinToneChange` | `(tone: SkinTone) => void` | — | Вызывается при смене тона |
+| `recentKey` | `string \| false` | `"goemoji:recent"` | Ключ localStorage для «Недавних»; `false` отключает их |
+| `onSelect` | `(emoji: Emoji) => void` | — | Обязательный обработчик выбора |
+| `onEscape` | `() => void` | — | Вызывается после Escape, если меню тонов закрыто |
+| `serverIconUrl` | `string` | — | Картинка для вкладки «Сервер» вместо стандартной иконки |
+| `className` | `string` | — | Дополнительный класс на корневой элемент `.ge-root` |
+
+Тон кожи хранится в localStorage под ключом `goemoji:tone`, пока не передан
+проп `skinTone`. Значения `SkinTone`: `"none"`, `"light"`, `"medium-light"`,
+`"medium"`, `"medium-dark"`, `"dark"`.
+
+### `useEmojiData`
+
+```ts
+const { data, error, loading } = useEmojiData(load, deps?);
+```
+
+Загружает словарь и разбирает его через `parseEmojiData`. Загрузчик вызывается
+при монтировании и заново при изменении `deps`; незавершённый запрос
+игнорируется, данные сбрасываются в `null` до прихода новых. В SSR эффект не
+выполняется, поэтому `loading` остаётся `true`.
+
+### Типы
+
+| Тип | Поля |
+| --- | --- |
+| `Emoji` | `value: string`, `label: string`, `tags: string`, `category: number`, `server?: { id: string; animated: boolean }` |
+| `ServerEmoji` | `id: string`, `name: string`, `animated: boolean` |
+| `EmojiData` | `locale: string`, `categories: Category[]`, `emojis: Emoji[]` |
+| `Category` | `key: string`, `label: string` |
+| `SlimEmoji` | `[emoji, label, tags, category]` — строка сырого словаря |
+| `Labels` | `search`, `empty`, `recent`, `server`, `skinTone`, `skinTones` |
+
+Все типы экспортируются из корня пакета вместе с `EmojiPickerProps`.
+
+### `goemoji/discord`
+
+Модуль без React: подходит для ботов, API-роутов и обработки реакций.
+
+| Функция | Описание |
+| --- | --- |
+| `parseCustomEmoji(value)` | Разбирает `<:name:id>` / `<a:name:id>`, для юникода вернёт `null` |
+| `customEmojiToString({ name, id, animated? })` | Собирает строку `<a:name:id>` / `<:name:id>` |
+| `customEmojiUrl(id, animated?, size?)` | Ссылка на CDN Discord; размер клампится к 16…4096, по умолчанию 48 |
+| `normalizeEmojiText(value)` | Убирает вариационные селекторы U+FE0E/U+FE0F и ZWJ |
+| `sameEmojiValue(saved, name, identifier)` | Сравнивает сохранённое значение с реакцией: серверные — по id, юникод — по нормализованному виду |
+
+```ts
+import { sameEmojiValue } from "goemoji/discord";
+
+sameEmojiValue("<a:blob:777>", "blob", "blob:777"); // true
+sameEmojiValue("❤️", "❤", "❤"); // true
+```
+
+## Клавиатура
+
+| Клавиша | Действие |
+| --- | --- |
+| `←` / `→` | Предыдущий или следующий эмодзи; на краю строки — переход на соседнюю |
+| `↑` / `↓` | Строка выше или ниже с выравниванием по колонке |
+| `PageUp` / `PageDown` | На пять строк вверх или вниз |
+| `Home` / `End` | Первый или последний эмодзи списка |
+| `Enter` | Выбрать активный эмодзи |
+| `Esc` | Закрыть меню тонов, затем вызвать `onEscape` |
+
+Фокус остаётся в поле поиска: список связан с ним через
+`aria-activedescendant`, как и положено combobox. При открытом меню тонов
+стрелки, `Home`, `End` и `Esc` управляют меню, а не списком.
+
+## Стилизация
+
+Тема задаётся CSS-переменными на `.ge-root` (или на любом родителе) и не
+использует `!important`:
+
+| Переменная | По умолчанию | Назначение |
+| --- | --- | --- |
+| `--ge-bg` | `#1e1f22` | Фон пикера |
+| `--ge-panel` | `#2b2d31` | Поле поиска, кнопки |
+| `--ge-surface` | `#232428` | Поповер тонов |
+| `--ge-border` | `#1a1b1e` | Рамки |
+| `--ge-text` | `#dbdee1` | Основной текст |
+| `--ge-muted` | `#949ba4` | Подписи и заголовки секций |
+| `--ge-hover` | `rgba(255, 255, 255, 0.06)` | Наведение |
+| `--ge-active` | `rgba(88, 101, 242, 0.4)` | Активная ячейка |
+| `--ge-accent` | `#5865f2` | Акцент, фокус, активная вкладка |
+| `--ge-radius` | `6px` | Скругление углов |
+| `--ge-list-height` | `320px` | Высота списка |
+| `--ge-font` | системный стек | Шрифт интерфейса |
+| `--ge-font-emoji` | системный эмодзи-стек | Шрифт юникод-эмодзи |
+
+```css
+.my-picker {
+  --ge-accent: #f2a65a;
+  --ge-list-height: 420px;
+}
+```
+
+Все элементы используют классы с префиксом `ge-` (`ge-root`, `ge-search`,
+`ge-list`, `ge-cell`, `ge-tabs` и т. д.), поэтому точечные правки тоже
+возможны, но обычно достаточно переменных.
+
+## Доступность
+
+- Поле поиска — `role="combobox"` с `aria-controls` и `aria-activedescendant`,
+  список — `role="listbox"`, ячейки — `role="option"` с `aria-selected`.
+- Вкладки категорий — `tablist`/`tab` с `aria-selected`.
+- Меню тонов — `menu`/`menuitemradio` с `aria-checked`; фокус возвращается на
+  кнопку при выборе и закрытии. Навигация: стрелки, `Home`, `End`, `Esc`.
+- Клик вне поповера закрывает его, не перехватывая фокус.
+- Анимация перехода к секции отключается при `prefers-reduced-motion: reduce`.
+- Подписи по умолчанию есть для `ru` и `en`, остальные можно передать через
+  `labels`.
+
+## Производительность
+
+Список рендерится построчно: в DOM находятся только строки из окна
+виртуализации плюс несколько строк запаса. При скролле диапазон
+пересчитывается в `requestAnimationFrame`, и React получает новое состояние
+только если окно действительно сдвинулось. Заголовки секций прилипают к
+верхней границе, а клик по вкладке подсвечивает её сразу и доезжает до секции
+короткой анимацией.
+
+Поиск выполняется по массиву эмодзи в памяти (1914 записей на локаль), поэтому
+выдача обновляется на каждое нажатие клавиши без задержек.
+
+## Лицензия
+
+Код — MIT. Названия и теги эмодзи происходят из
+[emojibase](https://github.com/milesj/emojibase) (MIT) и аннотаций Unicode CLDR
+(Unicode License v3); подробности — в `THIRD_PARTY_NOTICES.md`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,18 @@
+# Сторонние данные и лицензии
+
+## emojibase-data
+
+Файлы `data/ru.json` и `data/en.json` сгенерированы из пакета
+[`emojibase-data`](https://github.com/milesj/emojibase) (лицензия MIT) скриптом
+`scripts/build-data.ts`.
+
+## Unicode CLDR
+
+Названия и теги эмодзи в `emojibase-data` основаны на аннотациях
+[Unicode CLDR](https://cldr.unicode.org/), которые распространяются по
+[Unicode License v3](https://www.unicode.org/license.txt).
+
+## Шрифт эмодзи
+
+Пикер не поставляет изображений юникод-эмодзи и рендерит их системным шрифтом.
+Список семейств задаётся переменной `--ge-font-emoji`.