@speednexus_messenger/smileed-nexus 1.0.1 → 1.0.2
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/README.md +29 -153
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,173 +1,49 @@
|
|
|
1
|
-
#
|
|
1
|
+
# SmileedNexus
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Красивая, быстрая и лёгкая панель эмодзи для React.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
- категории и список недавних (хранится в `localStorage`, синхронизируется между вкладками)
|
|
7
|
-
- навигация с клавиатуры: стрелки, `Home`, `End`, `Enter`, `Escape`
|
|
8
|
-
- светлая и тёмная темы, настройка через CSS-переменные
|
|
9
|
-
- спрайт подгружается отдельным чанком только при первом показе эмодзи
|
|
10
|
-
- безопасен для SSR: до загрузки спрайта показываются обычные символы
|
|
11
|
-
- `EmojiText` заменяет эмодзи в строке на SVG, при этом текст остаётся выделяемым и копируемым
|
|
5
|
+
## Особенности
|
|
12
6
|
|
|
13
|
-
|
|
7
|
+
- **Поиск по русским и английским названиям и ключевым словам** — `привет`, `hello`, `flag`, `флаг` — всё находится.
|
|
8
|
+
- **Совместимость с React 16.8 – 19** — хуки, `lazy`/`Suspense`, `createRoot`. Никаких конфликтов зависимостей.
|
|
9
|
+
- **Текстуры Twemoji** — одинаковые смайлы на Windows, macOS, Android и Linux.
|
|
10
|
+
- Без сторонних зависимостей. **React и React DOM** — peer-зависимости (устанавливаются в вашем проекте).
|
|
11
|
+
- **Интеграция с `contenteditable`** — вставляет эмодзи точно туда, где стоит курсор.
|
|
12
|
+
- **Идеальный рендер составных эмодзи** (радужный флаг 🏳️🌈, семьи 👨👩👧👦, тона кожи 👍🏽) благодаря `Intl.Segmenter`.
|
|
13
|
+
- **941 эмодзи** в наборе, включая 259 флагов стран с русскими названиями (`Россия`, `Германия`, `США`).
|
|
14
|
+
- **Локализация** — подписи, категории и поиск на русском и английском.
|
|
15
|
+
- **Недавние эмодзи** — сохраняются в `localStorage`.
|
|
16
|
+
|
|
17
|
+
## Поддержка платформ и браузеров
|
|
18
|
+
|
|
19
|
+
Благодаря локальному SVG-спрайту (Twemoji) и нативному API `Intl.Segmenter`, панель **работает одинаково** на всех операционных системах. На старых браузерах, где `Intl.Segmenter` отсутствует, используется fallback через `Array.from` (составные эмодзи могут разбиваться, но базовые работают).
|
|
14
20
|
|
|
15
21
|
## Установка
|
|
16
22
|
|
|
17
23
|
```bash
|
|
18
|
-
npm install smileed-nexus
|
|
24
|
+
npm install @speednexus_messenger/smileed-nexus
|
|
19
25
|
```
|
|
20
26
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
## Использование
|
|
27
|
+
**Пример**:
|
|
24
28
|
|
|
25
|
-
```
|
|
29
|
+
```jsx
|
|
26
30
|
import { useState } from 'react';
|
|
27
|
-
import { SmileedNexus
|
|
28
|
-
import 'smileed-nexus/styles.css';
|
|
31
|
+
import { SmileedNexus } from '@speednexus_messenger/smileed-nexus';
|
|
32
|
+
import '@speednexus_messenger/smileed-nexus/styles.css';
|
|
29
33
|
|
|
30
|
-
|
|
34
|
+
function App() {
|
|
31
35
|
const [open, setOpen] = useState(false);
|
|
32
|
-
const [text, setText] = useState('');
|
|
33
36
|
|
|
34
37
|
return (
|
|
35
|
-
|
|
36
|
-
<
|
|
37
|
-
<EmojiText text={text} />
|
|
38
|
-
</p>
|
|
39
|
-
|
|
40
|
-
<button data-smileed-nexus-ignore onClick={() => setOpen((value) => !value)}>
|
|
41
|
-
Эмодзи
|
|
42
|
-
</button>
|
|
43
|
-
|
|
38
|
+
<>
|
|
39
|
+
<button onClick={() => setOpen(true)}>😀</button>
|
|
44
40
|
{open && (
|
|
45
|
-
<
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
autoFocus
|
|
50
|
-
/>
|
|
51
|
-
</div>
|
|
41
|
+
<SmileedNexus
|
|
42
|
+
onSelect={(emoji) => console.log(emoji)}
|
|
43
|
+
onClose={() => setOpen(false)}
|
|
44
|
+
/>
|
|
52
45
|
)}
|
|
53
|
-
|
|
46
|
+
</>
|
|
54
47
|
);
|
|
55
48
|
}
|
|
56
49
|
```
|
|
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).
|