@speednexus_messenger/smileed-nexus 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SpeedNexus
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,173 @@
1
- # Temporary Holding Version
1
+ # smileed-nexus
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Emoji-пикер для React без внешних зависимостей. Эмодзи рисуются из встроенного SVG-спрайта Twemoji, поэтому выглядят одинаково на всех платформах.
4
+
5
+ - поиск по русским и английским названиям и ключевым словам
6
+ - категории и список недавних (хранится в `localStorage`, синхронизируется между вкладками)
7
+ - навигация с клавиатуры: стрелки, `Home`, `End`, `Enter`, `Escape`
8
+ - светлая и тёмная темы, настройка через CSS-переменные
9
+ - спрайт подгружается отдельным чанком только при первом показе эмодзи
10
+ - безопасен для SSR: до загрузки спрайта показываются обычные символы
11
+ - `EmojiText` заменяет эмодзи в строке на SVG, при этом текст остаётся выделяемым и копируемым
12
+
13
+ В наборе 1906 эмодзи (Unicode 16, включая все флаги). Варианты с тонами кожи (👍🏽) подгружаются отдельным чанком, когда такой эмодзи встречается в тексте. Названия на русском, поиск работает и по английским ключевым словам.
14
+
15
+ ## Установка
16
+
17
+ ```bash
18
+ npm install smileed-nexus
19
+ ```
20
+
21
+ Нужен React 17 или новее.
22
+
23
+ ## Использование
24
+
25
+ ```tsx
26
+ import { useState } from 'react';
27
+ import { SmileedNexus, EmojiText } from 'smileed-nexus';
28
+ import 'smileed-nexus/styles.css';
29
+
30
+ export function Chat() {
31
+ const [open, setOpen] = useState(false);
32
+ const [text, setText] = useState('');
33
+
34
+ return (
35
+ <div>
36
+ <p>
37
+ <EmojiText text={text} />
38
+ </p>
39
+
40
+ <button data-smileed-nexus-ignore onClick={() => setOpen((value) => !value)}>
41
+ Эмодзи
42
+ </button>
43
+
44
+ {open && (
45
+ <div style={{ width: 360, height: 400 }}>
46
+ <SmileedNexus
47
+ onSelect={(emoji) => setText((value) => value + emoji)}
48
+ onClose={() => setOpen(false)}
49
+ autoFocus
50
+ />
51
+ </div>
52
+ )}
53
+ </div>
54
+ );
55
+ }
56
+ ```
57
+
58
+ Пикер занимает всю ширину и высоту родителя, размер и позицию задаёте вы.
59
+
60
+ Атрибут `data-smileed-nexus-ignore` на кнопке-переключателе нужен, чтобы клик по ней не считался кликом вне пикера. Без него кнопка сначала закроет пикер, а затем откроет его снова.
61
+
62
+ ### Next.js и другие SSR-фреймворки
63
+
64
+ Бандл помечен директивой `"use client"`, так что компоненты можно импортировать из клиентских компонентов App Router без обёрток.
65
+
66
+ ## API
67
+
68
+ ### `<SmileedNexus />`
69
+
70
+ | Проп | Тип | По умолчанию | Описание |
71
+ | --- | --- | --- | --- |
72
+ | `onSelect` | `(emoji: string) => void` | обязательный | Вызывается при выборе эмодзи |
73
+ | `onClose` | `() => void` | нет | Клик вне пикера или `Escape` |
74
+ | `className` | `string` | нет | Дополнительный класс корневого элемента |
75
+ | `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | `auto` следует за `prefers-color-scheme` |
76
+ | `labels` | `PartialLabels` | русские | Тексты интерфейса |
77
+ | `storageKey` | `string` | `'smileed-nexus:recent'` | Ключ `localStorage` для недавних |
78
+ | `maxRecent` | `number` | `24` | Сколько недавних хранить |
79
+ | `autoFocus` | `boolean` | `false` | Фокус на поле поиска при показе |
80
+
81
+ `Escape` в поле поиска сначала очищает запрос, повторное нажатие вызывает `onClose`. `Enter` выбирает первый результат поиска. `ArrowDown` из поля поиска переводит фокус в сетку, `ArrowUp` из первой строки возвращает обратно.
82
+
83
+ ### `<EmojiText />`
84
+
85
+ | Проп | Тип | Описание |
86
+ | --- | --- | --- |
87
+ | `text` | `string` | Строка с эмодзи |
88
+ | `className` | `string` | Класс внешнего `span` |
89
+ | `emojiClassName` | `string` | Дополнительный класс каждого эмодзи |
90
+
91
+ ### `<Emoji />`
92
+
93
+ Один эмодзи. Пропы: `char`, `className`, `selectable`. Если эмодзи нет в спрайте, выводится обычный символ.
94
+
95
+ ### Остальное
96
+
97
+ ```ts
98
+ useRecentEmojis({ storageKey?, max? }) // { recent, push, clear }
99
+ searchEmojis(query) // EmojiEntry[]
100
+ findEmoji(char) // EmojiEntry | undefined
101
+ emojisByCategory(id) // readonly EmojiEntry[]
102
+ splitEmoji(text) // { emoji: boolean; value: string }[]
103
+ loadSprite() // Promise<void>, прогрев спрайта заранее
104
+ EMOJIS, CATEGORIES, DEFAULT_LABELS
105
+ ```
106
+
107
+ ## Тексты интерфейса
108
+
109
+ ```tsx
110
+ <SmileedNexus
111
+ onSelect={add}
112
+ labels={{
113
+ search: 'Search',
114
+ empty: 'Nothing found',
115
+ recentEmpty: 'No recent emoji yet',
116
+ categories: { people: 'Smileys', nature: 'Nature' },
117
+ }}
118
+ />
119
+ ```
120
+
121
+ Названия самих эмодзи (всплывающие подсказки) хранятся в `src/data.ts` на русском.
122
+
123
+ ## Оформление
124
+
125
+ Все цвета и размеры заданы CSS-переменными на `.sn-picker`:
126
+
127
+ ```css
128
+ .sn-picker {
129
+ --sn-bg: var(--bg-card);
130
+ --sn-bg-muted: var(--bg-page);
131
+ --sn-bg-hover: var(--bg-hover);
132
+ --sn-border: var(--border-light);
133
+ --sn-text: var(--text-primary);
134
+ --sn-text-muted: var(--text-tertiary);
135
+ --sn-accent: var(--accent);
136
+ --sn-accent-soft: var(--accent-soft);
137
+ --sn-radius: var(--radius-md);
138
+ --sn-radius-sm: var(--radius-sm);
139
+ --sn-columns: 8;
140
+ --sn-emoji-size: 26px;
141
+ }
142
+ ```
143
+
144
+ Для тёмной темы приложения, которая не зависит от настроек системы, передайте `theme="dark"` или переопределите переменные сами.
145
+
146
+ ## Как это работает
147
+
148
+ Спрайт лежит в `src/generated/sprite.ts` как набор `<symbol>`. При первом показе эмодзи он подгружается динамическим `import()` и один раз добавляется в `document.body`. Каждый эмодзи на странице это маленький `<svg><use href="#sn-…"/></svg>`, а не копия всей разметки. Спрайт добавляется через DOM API, без инлайновых стилей в разметке, поэтому строгий CSP с `style-src` без `unsafe-inline` не мешает.
149
+
150
+ В CommonJS-сборке динамический `import()` не разделяется на чанк, спрайт входит в основной файл. Ленивая подгрузка работает в ESM-сборке.
151
+
152
+ ## Свой набор эмодзи
153
+
154
+ 1. Измените список в `src/data.ts`.
155
+ 2. Выполните `npm run gen:sprite`. Скрипт скачивает SVG Twemoji, кеширует их в `scripts/.cache` и пересобирает `src/generated/sprite.ts`. Эмодзи, для которых SVG не найден, будут перечислены в выводе, а скрипт завершится с ошибкой.
156
+ 3. Запустите `npm test`: тесты проверяют, что для каждого эмодзи и иконки категории есть символ в спрайте.
157
+
158
+ ## Разработка
159
+
160
+ ```bash
161
+ npm install
162
+ npm run typecheck
163
+ npm test
164
+ npm run build
165
+ ```
166
+
167
+ ## Лицензии
168
+
169
+ Код распространяется под лицензией MIT, см. `LICENSE`.
170
+
171
+ Графика эмодзи это [Twemoji](https://github.com/jdecked/twemoji) версии 15.0.3, Copyright 2020 Twitter, Inc и другие участники, лицензия [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). При распространении приложения, использующего эту графику, нужно указать авторство.
172
+
173
+ Названия и ключевые слова эмодзи получены из данных Unicode CLDR через пакет [emojibase-data](https://github.com/milesj/emojibase) (MIT).