ikoneme-lib 0.4.0 → 0.6.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/README.md CHANGED
@@ -1,274 +1,322 @@
1
- # ikoneme-lib
2
-
3
- React components to render and edit **ikonemes** — ordered sequences of **ikons**
4
- ("rich icons" / "super icons") — using the same rich JSON payload produced by
5
- the KomunIKON NLP pipeline and consumed by [ikonchat](../ikonchat).
6
-
7
- This package has no server-side logic of its own: it is a pure rendering/editing
8
- layer over the ikon JSON payload. The goal is for ikonchat (and any other
9
- messaging UI) to depend on this library instead of carrying its own copy of the
10
- rich-icon rendering code.
11
-
12
- ## Concepts
13
-
14
- - **Ikon** — a single rich icon: a 6x6 grid of zones (`context`, `reference`,
15
- `role`, `modes`, `root`, `tenses`) plus a grammatical `border`.
16
- - **Ikoneme** — an ordered list of ikons, e.g. one per word/concept extracted
17
- from a sentence. This is what you render in a chat bubble.
18
-
19
- ### JSON payload
20
-
21
- An ikoneme is a plain array of ikon objects:
22
-
23
- ```json
24
- [
25
- {
26
- "context": { "name": "Male", "url": "https://.../KomunIKON_Male.svg" },
27
- "reference": {
28
- "left": null,
29
- "right": { "name": "Two", "url": "https://.../KomunIKON_Two.svg" }
30
- },
31
- "role": { "name": "agent", "url": "https://.../KomunIKON_agent.svg" },
32
- "modes": { "name": "Exclam", "url": "https://.../KomunIKON_Exclam.svg" },
33
- "root": { "name": "Love/Passion", "url": "https://.../ZFcaar88AP.png" },
34
- "rootName": "Love/Passion",
35
- "tenses": { "name": "as", "url": "https://.../KomunIKON_Verbal_Tense_as.svg" },
36
- "border": "verb"
37
- }
38
- ]
39
- ```
40
-
41
- This is **exactly** the shape ikonchat stores per message (`message.richIcons`).
42
- Any extra fields (e.g. a `metadata` block from the NLP pipeline) are preserved
43
- untouched by `normalizeIkon`/`normalizeIkoneme`.
44
-
45
- It also maps directly onto the NLP "Rich Icon Output Specification" vocabulary:
46
-
47
- | This library / ikonchat | NLP spec |
48
- | ------------------------------------- | ------------- |
49
- | `context` | `gender` |
50
- | `modes` | `mode` |
51
- | `tenses` | `time-tenses` |
52
- | `reference`, `role`, `root`, `border` | same name |
53
-
54
- ## Components
55
-
56
- ### `<Ikoneme>`
57
-
58
- The main component. Renders a row of ikons for one message.
59
-
60
- ```jsx
61
- import { Ikoneme } from 'ikoneme-lib'
62
-
63
- // Read-only, for a chat/messaging timeline
64
- <Ikoneme ikons={message.richIcons} mode="view" size={64} />
65
-
66
- // Editable: adds hover/tap edit + delete buttons on each ikon and opens
67
- // the full ikon editor. `onChange` receives the updated ikoneme array.
68
- <Ikoneme
69
- ikons={message.richIcons}
70
- mode="edit"
71
- size={64}
72
- onChange={(nextIkons) => updateMessage(message.id, nextIkons)}
73
- />
74
- ```
75
-
76
- Props:
77
-
78
- | Prop | Type | Default | Notes |
79
- | -------------------- | -------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80
- | `ikons` | `Array<Ikon>` | `[]` | The ikoneme payload. |
81
- | `mode` | `'view' \| 'edit'` | `'view'` | `'edit'` shows per-ikon edit/delete controls and the editor modal. |
82
- | `size` | `number` | `64` | Pixel size of each ikon. |
83
- | `gap` | `number` | `6` | Pixel gap between ikons. |
84
- | `onChange` | `(nextIkons) => void` | — | Called after an edit is saved or an ikon is deleted. Required for edit/delete to do anything — the component is otherwise controlled. |
85
- | `onIkonClick` | `(ikon, index) => void` | — | Click handler in `view` mode only (e.g. show original source text). Fires independently of `zoom`. |
86
- | `zoom` | `boolean` | `true` | `true`: clicking any ikon (in either mode) opens a large read-only view of it. `false`: the click is ignored for zoom purposes (`onIkonClick` still fires as usual). |
87
- | `zoomSize` | `number` | `320` | Pixel size of the ikon inside the zoomed view (clamped to fit the viewport). |
88
- | `searchRoot` | `(query) => Promise<{id?,name,url}[]>` | IkonDB (public) | Overrides the root-icon search backend used by the editor. Default: `defaultSearchRoot`, which searches the public [IkonDB](https://ikondb.iigap.com/api/docs) icon database (full list fetched once and cached for an hour; matched client-side by name). On select, the editor fetches that icon's fuller media set (`svg`/`thumb`/`preview`) via `GET /api/ikons/{id}`. |
89
- | `theme` | `object` | — | Override any `--ikoneme-*` CSS custom property (see Theming). |
90
- | `className`, `style` | | | Passed to the wrapper element. |
91
-
92
- ### `<Ikon>` and `<IkonEditor>`
93
-
94
- Lower-level building blocks, exported for advanced use:
95
-
96
- ```jsx
97
- import { Ikon, IkonEditor } from 'ikoneme-lib'
98
- ```
99
-
100
- - `<Ikon ikon={...} size={64} onClick={...} />` — renders a single ikon. The
101
- grammatical border is the official KomunIKON artwork (`src/borders`: one
102
- colour and dash pattern per category, single frame for singular, double
103
- frame for plural), scaled with `size` so it stays legible both tiny in a chat
104
- bubble and large in a zoomed view. The ikon stays square either way.
105
- - `<IkonEditor ikon={...} onSave={...} onClose={...} searchRoot={...} />` —
106
- the full-screen zone editor for one ikon.
107
- - `<IkonZoomView ikon={...} size={320} onClose={...} />` — the read-only
108
- "lightbox" view `<Ikoneme zoom>` opens on click; exported in case you want
109
- to trigger it yourself.
110
-
111
- ### Schema utilities
112
-
113
- ```js
114
- import {
115
- ZONE_CONFIG,
116
- BORDER_CONFIG,
117
- getBorderImageStyle,
118
- createDefaultIkon,
119
- normalizeIkon,
120
- normalizeIkoneme,
121
- generateIkonemeFromText
122
- } from 'ikoneme-lib'
123
- ```
124
-
125
- - `normalizeIkoneme(ikons)` — upgrades any legacy/URL-only stored payloads to
126
- the `{ name, url }` shape. Run this on data loaded from storage/an API
127
- before rendering.
128
- - `generateIkonemeFromText(text)` — deterministic placeholder generator
129
- (hash-based), useful for demos/tests until real NLP output is wired in.
130
- - `BORDER_CONFIG` — the 12 border types (`{ id, label, color, plural, image }`);
131
- `image` is the artwork as a data URI, `color` its main colour.
132
- - `getBorderImageStyle(border, size)` — inline style that draws a border's
133
- artwork around a square box of `size` px (what `<Ikon>` uses).
134
- - `createEmptyIkon()` — an ikon with every zone empty and no border.
135
-
136
- ### Image export
137
-
138
- ```js
139
- import { renderIkonemeToPng, renderIkonemeToCanvas, drawIkon } from 'ikoneme-lib'
140
-
141
- const blob = await renderIkonemeToPng(ikons, { size: 120, perRow: 8, title: 'hello' })
142
- ```
143
-
144
- Draws ikons on a canvas with the same layout, tints and border artwork as
145
- `<Ikon>`. Options: `size`, `gap`, `padding`, `perRow`, `background`, `title`,
146
- `titleColor`, `titleFont`, `pixelRatio`. Remote icons are loaded with CORS, so
147
- an image host without `Access-Control-Allow-Origin` is skipped (the browser
148
- won't let it into an exportable canvas).
149
-
150
- ### IkonDB helpers
151
-
152
- The public [IkonDB](https://ikondb.iigap.com/api/docs) client backing the
153
- default root search, exported for reuse:
154
-
155
- ```js
156
- import { searchIkons, getIkonDetails, getIkonList, IKONDB_BASE_URL } from 'ikoneme-lib'
157
- ```
158
-
159
- - `searchIkons(query, { limit })` — `{ id, name, url }[]`, matched by name
160
- against the full list (fetched once, cached for an hour).
161
- - `getIkonDetails(id)` — `{ id, name, url, origin, preview, thumb, svg }` for one
162
- icon (cached per id), or `null` if it does not exist.
163
- - `getIkonList()` — the whole cached list.
164
- - `clearIkonDbCache()` — drops the in-memory caches.
165
-
166
- Icons whose IkonDB record has no image are omitted from search results.
167
-
168
- ## Theming
169
-
170
- Components read colors from `--ikoneme-*` CSS custom properties and ship with
171
- sensible dark-mode defaults, so nothing else is required to use them. To match
172
- your app's palette, pass a `theme` override:
173
-
174
- ```jsx
175
- <Ikoneme
176
- ikons={ikons}
177
- theme={{
178
- '--ikoneme-primary': '#00a884',
179
- '--ikoneme-background': '#0c0e12',
180
- '--ikoneme-panel-bg': '#181b20',
181
- '--ikoneme-surface': '#080a0e',
182
- '--ikoneme-border': '#2a2e36',
183
- '--ikoneme-text-primary': '#e9edef',
184
- '--ikoneme-text-secondary': '#8696a0',
185
- '--ikoneme-hover': '#2a2e36'
186
- }}
187
- />
188
- ```
189
-
190
- ## Building
191
-
192
- ```bash
193
- npm install
194
- npm run build # outputs dist/ikoneme-lib.js (ESM) and dist/ikoneme-lib.cjs (CJS)
195
- ```
196
-
197
- ## Using this library in another project (local, no registry)
198
-
199
- This package is not published to npm/a registry. Pick one of the following to
200
- consume it locally.
201
-
202
- ### Option A — `file:` dependency (recommended)
203
-
204
- 1. Build a tarball from this repo:
205
- ```bash
206
- cd ikoneme-lib
207
- npm install
208
- npm run build
209
- npm pack # produces ikoneme-lib-<version>.tgz
210
- ```
211
- 2. In the consuming project (e.g. ikonchat), add it as a dependency pointing
212
- at the tarball (adjust the relative path to wherever you placed it):
213
- ```bash
214
- npm install ../ikoneme-lib/ikoneme-lib-0.1.0.tgz
215
- ```
216
- This writes a `"ikoneme-lib": "file:../ikoneme-lib/ikoneme-lib-0.1.0.tgz"`
217
- entry to the consumer's `package.json` and copies/extracts the packed
218
- `dist/` into `node_modules` — no symlink, so it behaves like a real
219
- registry install (safe for CI/Docker builds too, as long as the tarball
220
- path is available at install time).
221
- 3. Re-run steps 1–2 whenever you change the library and want the consumer to
222
- pick up the new build.
223
-
224
- ### Option B — `npm link` (fastest for active local development)
225
-
226
- ```bash
227
- cd ikoneme-lib
228
- npm install
229
- npm run build
230
- npm link
231
-
232
- cd ../ikonchat
233
- npm link ikoneme-lib
234
- ```
235
-
236
- This symlinks `ikoneme-lib` into the consumer's `node_modules`, so rebuilding
237
- the library (`npm run build`) is immediately visible to the consumer without
238
- reinstalling. Undo with `npm unlink ikoneme-lib` in the consumer and
239
- `npm unlink` in this repo.
240
-
241
- ### Option C — local npm registry (Verdaccio)
242
-
243
- For multi-developer/team setups where `file:`/`link:` paths are inconvenient,
244
- run a local registry and publish there instead of to the public npm registry:
245
-
246
- ```bash
247
- npx verdaccio # starts a registry on http://localhost:4873
248
- npm publish --registry http://localhost:4873
249
- # in the consumer:
250
- npm install ikoneme-lib --registry http://localhost:4873
251
- ```
252
-
253
- ## Example app
254
-
255
- `example/` is a minimal Vite + React app that installs this library via the
256
- `file:` tarball approach (Option A) and renders an ikoneme in both `view` and
257
- `edit` mode. Use it to sanity-check changes before wiring the library into
258
- ikonchat:
259
-
260
- ```bash
261
- npm run build && npm pack --pack-destination ./example
262
- cd example
263
- npm install
264
- npm run dev
265
- ```
266
-
267
- ## Next step
268
-
269
- `ikonchat` currently has its own copies of this rendering/editing logic
270
- (`app/components/RichIcon.jsx`, `RichIconEditor.jsx`,
271
- `app/utils/richIconMapping.js`). The follow-up work is to delete those and
272
- replace their usages (`ChatWindow.jsx`, etc.) with `<Ikoneme>` from this
273
- package, keeping ikonchat's own responsibility limited to chat/business logic
274
- (messages, contacts, backend sync) rather than ikon rendering.
1
+ # ikoneme-lib
2
+
3
+ React components to render and edit **ikonemes** — ordered sequences of **ikons**
4
+ ("rich icons" / "super icons") — using the same rich JSON payload produced by
5
+ the KomunIKON NLP pipeline and consumed by [ikonchat](../ikonchat).
6
+
7
+ This package has no server-side logic of its own: it is a pure rendering/editing
8
+ layer over the ikon JSON payload. The goal is for ikonchat (and any other
9
+ messaging UI) to depend on this library instead of carrying its own copy of the
10
+ rich-icon rendering code.
11
+
12
+ ## Concepts
13
+
14
+ - **Ikon** — a single rich icon: a 6x6 grid of equal squares. The centre 4x4
15
+ is the `root` image; around it, 20 **slots** (`slots`), each one square. A
16
+ slot is free: tap it, pick a category (Gender, Reference, Role, Mode, Tense)
17
+ and one of that category's small icons. Plus a grammatical `border`. A new
18
+ ikon starts grey and empty: neutral border, every slot free.
19
+ - **Ikoneme** — an ordered list of ikons, e.g. one per word/concept extracted
20
+ from a sentence. This is what you render in a chat bubble.
21
+
22
+ ### JSON payload
23
+
24
+ An ikoneme is a plain array of ikon objects:
25
+
26
+ ```json
27
+ [
28
+ {
29
+ "context": { "name": "Male", "url": "https://.../KomunIKON_Male.svg" },
30
+ "reference": {
31
+ "left": null,
32
+ "right": { "name": "Two", "url": "https://.../KomunIKON_Two.svg" }
33
+ },
34
+ "role": { "name": "agent", "url": "https://.../KomunIKON_agent.svg" },
35
+ "modes": { "name": "Exclam", "url": "https://.../KomunIKON_Exclam.svg" },
36
+ "root": { "name": "Love/Passion", "url": "https://.../ZFcaar88AP.png" },
37
+ "rootName": "Love/Passion",
38
+ "tenses": { "name": "as", "url": "https://.../KomunIKON_Verbal_Tense_as.svg" },
39
+ "border": "verb",
40
+ "slots": [
41
+ { "category": "context", "name": "Male", "url": "https://.../KomunIKON_Male.svg" },
42
+ null,
43
+ "... 20 entries in all, null for an empty slot ..."
44
+ ],
45
+ "word": "amore"
46
+ }
47
+ ]
48
+ ```
49
+
50
+ `slots` holds the 20 squares around the root, numbered clockwise from the
51
+ top-left corner (`SLOT_POSITIONS` gives each one's row and column); each is
52
+ `null` or `{ category, name, url }`. It is the source of truth for what the
53
+ ring shows. The fixed zone fields (`context`, `reference`, `role`, `modes`,
54
+ `tenses`) are still written, derived from the slots (the first slot of each
55
+ category, the first two for `reference`), so consumers that read them keep
56
+ working. An ikon saved before 0.6 has no `slots`: `normalizeIkon` builds them
57
+ from its zones, so it shows in about the same places. `word` is the word an
58
+ ikon was generated from, handy as a caption.
59
+
60
+ This is **exactly** the shape ikonchat stores per message (`message.richIcons`).
61
+ Any extra fields (e.g. a `metadata` block from the NLP pipeline) are preserved
62
+ untouched by `normalizeIkon`/`normalizeIkoneme`.
63
+
64
+ It also maps directly onto the NLP "Rich Icon Output Specification" vocabulary:
65
+
66
+ | This library / ikonchat | NLP spec |
67
+ | ------------------------------------- | ------------- |
68
+ | `context` | `gender` |
69
+ | `modes` | `mode` |
70
+ | `tenses` | `time-tenses` |
71
+ | `reference`, `role`, `root`, `border` | same name |
72
+
73
+ ## Components
74
+
75
+ ### `<Ikoneme>`
76
+
77
+ The main component. Renders a row of ikons for one message.
78
+
79
+ ```jsx
80
+ import { Ikoneme } from 'ikoneme-lib'
81
+
82
+ // Read-only, for a chat/messaging timeline
83
+ <Ikoneme ikons={message.richIcons} mode="view" size={64} />
84
+
85
+ // Editable: adds hover/tap edit + delete buttons on each ikon and opens
86
+ // the full ikon editor. `onChange` receives the updated ikoneme array.
87
+ <Ikoneme
88
+ ikons={message.richIcons}
89
+ mode="edit"
90
+ size={64}
91
+ onChange={(nextIkons) => updateMessage(message.id, nextIkons)}
92
+ />
93
+ ```
94
+
95
+ Props:
96
+
97
+ | Prop | Type | Default | Notes |
98
+ | -------------------- | -------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99
+ | `ikons` | `Array<Ikon>` | `[]` | The ikoneme payload. |
100
+ | `mode` | `'view' \| 'edit'` | `'view'` | `'edit'` shows per-ikon edit/delete controls and the editor modal. |
101
+ | `size` | `number` | `64` | Pixel size of each ikon. |
102
+ | `gap` | `number` | `6` | Pixel gap between ikons. |
103
+ | `onChange` | `(nextIkons) => void` | — | Called after an edit is saved or an ikon is deleted. Required for edit/delete to do anything — the component is otherwise controlled. |
104
+ | `onIkonClick` | `(ikon, index) => void` | — | Click handler in `view` mode only (e.g. show original source text). Fires independently of `zoom`. |
105
+ | `zoom` | `boolean` | `true` | `true`: clicking any ikon (in either mode) opens a large read-only view of it. `false`: the click is ignored for zoom purposes (`onIkonClick` still fires as usual). |
106
+ | `zoomSize` | `number` | `320` | Pixel size of the ikon inside the zoomed view (clamped to fit the viewport). |
107
+ | `searchRoot` | `(query) => Promise<{id?,name,url}[]>` | IkonDB (public) | Overrides the root-icon search backend used by the editor. Default: `defaultSearchRoot`, which searches the public [IkonDB](https://ikondb.iigap.com/api/docs) icon database (full list fetched once and cached for an hour; matched client-side by name). On select, the editor fetches that icon's fuller media set (`svg`/`thumb`/`preview`) via `GET /api/ikons/{id}`. |
108
+ | `theme` | `object` | — | Override any `--ikoneme-*` CSS custom property (see Theming). |
109
+ | `className`, `style` | | | Passed to the wrapper element. |
110
+
111
+ ### `<Ikon>` and `<IkonEditor>`
112
+
113
+ Lower-level building blocks, exported for advanced use:
114
+
115
+ ```jsx
116
+ import { Ikon, IkonEditor } from 'ikoneme-lib'
117
+ ```
118
+
119
+ - `<Ikon ikon={...} size={64} onClick={...} label="perro" />` — renders a
120
+ single ikon; `label` (optional) is a caption under it, e.g. its word. The
121
+ grammatical border is the official KomunIKON artwork (`src/borders`: one
122
+ colour and dash pattern per category, single frame for singular, double
123
+ frame for plural), scaled with `size` so it stays legible both tiny in a chat
124
+ bubble and large in a zoomed view. The ikon stays square either way.
125
+ - `<IkonEditor ikon={...} onSave={...} onClose={...} searchRoot={...} />` —
126
+ the full-screen editor for one ikon: tap a square, pick a category, then an
127
+ icon; or the centre image (searched in IkonDB) or the border.
128
+ - `<IkonZoomView ikon={...} size={320} onClose={...} />` — the read-only
129
+ "lightbox" view `<Ikoneme zoom>` opens on click; exported in case you want
130
+ to trigger it yourself.
131
+
132
+ ### Schema utilities
133
+
134
+ ```js
135
+ import {
136
+ ZONE_CONFIG,
137
+ BORDER_CONFIG,
138
+ getBorderImageStyle,
139
+ createDefaultIkon,
140
+ normalizeIkon,
141
+ normalizeIkoneme,
142
+ generateIkonemeFromText
143
+ } from 'ikoneme-lib'
144
+ ```
145
+
146
+ - `normalizeIkoneme(ikons)` — upgrades any legacy/URL-only stored payloads to
147
+ the `{ name, url }` shape. Run this on data loaded from storage/an API
148
+ before rendering.
149
+ - `generateIkonemeFromText(text, { search })` — one ikon per word, grey and
150
+ empty (neutral border, free slots) with only its root, looked up with
151
+ `search(word, { limit })`, which defaults to `searchIkons`; pass one built on
152
+ `searchIkonsV2` to match words in any language. Each ikon keeps its `word`.
153
+ - `BORDER_CONFIG` — the 12 border types (`{ id, label, color, plural, image }`);
154
+ `image` is the artwork as a data URI, `color` its main colour.
155
+ - `getBorderImageStyle(border, size)` — inline style that draws a border's
156
+ artwork around a square box of `size` px (what `<Ikon>` uses).
157
+ - `createEmptyIkon({ root, rootName })` — a grey, empty ikon: neutral border
158
+ (`DEFAULT_BORDER`), every slot free, and no root unless one is given.
159
+ - `SLOT_CATEGORIES`, `getCategoryIcons(category)`, `slotsOf(ikon)`,
160
+ `setSlot(ikon, index, { category, url } | null)` — work with the 20 slots;
161
+ `setSlot` keeps the fixed zone fields in step.
162
+
163
+ ### Image export
164
+
165
+ ```js
166
+ import { renderIkonemeToPng, renderIkonemeToCanvas, drawIkon } from 'ikoneme-lib'
167
+
168
+ const blob = await renderIkonemeToPng(ikons, { size: 120, perRow: 8, title: 'hello' })
169
+ ```
170
+
171
+ Draws ikons on a canvas with the same layout, tints and border artwork as
172
+ `<Ikon>`. Options: `size`, `gap`, `padding`, `perRow`, `background`, `title`,
173
+ `titleColor`, `titleFont`, `pixelRatio`. Remote icons are loaded with CORS, so
174
+ an image host without `Access-Control-Allow-Origin` is skipped (the browser
175
+ won't let it into an exportable canvas).
176
+
177
+ ### IkonDB helpers
178
+
179
+ The public [IkonDB](https://ikondb.iigap.com/api/docs) client backing the
180
+ default root search, exported for reuse:
181
+
182
+ ```js
183
+ import {
184
+ searchIkons,
185
+ searchIkonsV2,
186
+ getIkonDetails,
187
+ getIkonList,
188
+ IKONDB_BASE_URL
189
+ } from 'ikoneme-lib'
190
+ ```
191
+
192
+ - `searchIkons(query, { limit })` — `{ id, name, url }[]`, matched by name
193
+ against the full list (fetched once, cached for an hour). Public, but it only
194
+ knows each icon's base name (mostly Esperanto), so "perro" or "dog" find
195
+ nothing.
196
+ - `searchIkonsV2(query, { token, lang, limit })` — same result shape, from
197
+ `/api/v2/icons/search`: also matches translated titles and tags in 16
198
+ languages, with exact matches first. Needs a logged-in user's access token
199
+ (`POST /api/v2/auth/login`); on failure it throws an `Error` whose `status`
200
+ is the HTTP status, so a host can renew the token on `401` and retry. `lang`
201
+ (e.g. `"it"`) limits matches to that language and picks the name shown.
202
+
203
+ ```js
204
+ const searchRoot = (query, opts) => searchIkonsV2(query, { token, ...opts })
205
+ <IkonEditor ikon={ikon} searchRoot={searchRoot} onSave={save} onClose={close} />
206
+ const ikons = await generateIkonemeFromText(text, { search: searchRoot })
207
+ ```
208
+
209
+ - `getIkonDetails(id)` — `{ id, name, url, origin, preview, thumb, svg }` for one
210
+ icon (cached per id), or `null` if it does not exist.
211
+ - `getIkonList()` — the whole cached list.
212
+ - `clearIkonDbCache()` — drops the in-memory caches.
213
+
214
+ Icons whose IkonDB record has no image are omitted from search results.
215
+
216
+ ## Theming
217
+
218
+ Components read colors from `--ikoneme-*` CSS custom properties and ship with
219
+ sensible dark-mode defaults, so nothing else is required to use them. To match
220
+ your app's palette, pass a `theme` override:
221
+
222
+ ```jsx
223
+ <Ikoneme
224
+ ikons={ikons}
225
+ theme={{
226
+ '--ikoneme-primary': '#00a884',
227
+ '--ikoneme-background': '#0c0e12',
228
+ '--ikoneme-panel-bg': '#181b20',
229
+ '--ikoneme-surface': '#080a0e',
230
+ '--ikoneme-border': '#2a2e36',
231
+ '--ikoneme-text-primary': '#e9edef',
232
+ '--ikoneme-text-secondary': '#8696a0',
233
+ '--ikoneme-hover': '#2a2e36'
234
+ }}
235
+ />
236
+ ```
237
+
238
+ ## Building
239
+
240
+ ```bash
241
+ npm install
242
+ npm run build # outputs dist/ikoneme-lib.js (ESM) and dist/ikoneme-lib.cjs (CJS)
243
+ ```
244
+
245
+ ## Using this library in another project (local, no registry)
246
+
247
+ This package is not published to npm/a registry. Pick one of the following to
248
+ consume it locally.
249
+
250
+ ### Option A — `file:` dependency (recommended)
251
+
252
+ 1. Build a tarball from this repo:
253
+ ```bash
254
+ cd ikoneme-lib
255
+ npm install
256
+ npm run build
257
+ npm pack # produces ikoneme-lib-<version>.tgz
258
+ ```
259
+ 2. In the consuming project (e.g. ikonchat), add it as a dependency pointing
260
+ at the tarball (adjust the relative path to wherever you placed it):
261
+ ```bash
262
+ npm install ../ikoneme-lib/ikoneme-lib-0.1.0.tgz
263
+ ```
264
+ This writes a `"ikoneme-lib": "file:../ikoneme-lib/ikoneme-lib-0.1.0.tgz"`
265
+ entry to the consumer's `package.json` and copies/extracts the packed
266
+ `dist/` into `node_modules` — no symlink, so it behaves like a real
267
+ registry install (safe for CI/Docker builds too, as long as the tarball
268
+ path is available at install time).
269
+ 3. Re-run steps 1–2 whenever you change the library and want the consumer to
270
+ pick up the new build.
271
+
272
+ ### Option B — `npm link` (fastest for active local development)
273
+
274
+ ```bash
275
+ cd ikoneme-lib
276
+ npm install
277
+ npm run build
278
+ npm link
279
+
280
+ cd ../ikonchat
281
+ npm link ikoneme-lib
282
+ ```
283
+
284
+ This symlinks `ikoneme-lib` into the consumer's `node_modules`, so rebuilding
285
+ the library (`npm run build`) is immediately visible to the consumer without
286
+ reinstalling. Undo with `npm unlink ikoneme-lib` in the consumer and
287
+ `npm unlink` in this repo.
288
+
289
+ ### Option C — local npm registry (Verdaccio)
290
+
291
+ For multi-developer/team setups where `file:`/`link:` paths are inconvenient,
292
+ run a local registry and publish there instead of to the public npm registry:
293
+
294
+ ```bash
295
+ npx verdaccio # starts a registry on http://localhost:4873
296
+ npm publish --registry http://localhost:4873
297
+ # in the consumer:
298
+ npm install ikoneme-lib --registry http://localhost:4873
299
+ ```
300
+
301
+ ## Example app
302
+
303
+ `example/` is a minimal Vite + React app that installs this library via the
304
+ `file:` tarball approach (Option A) and renders an ikoneme in both `view` and
305
+ `edit` mode. Use it to sanity-check changes before wiring the library into
306
+ ikonchat:
307
+
308
+ ```bash
309
+ npm run build && npm pack --pack-destination ./example
310
+ cd example
311
+ npm install
312
+ npm run dev
313
+ ```
314
+
315
+ ## Next step
316
+
317
+ `ikonchat` currently has its own copies of this rendering/editing logic
318
+ (`app/components/RichIcon.jsx`, `RichIconEditor.jsx`,
319
+ `app/utils/richIconMapping.js`). The follow-up work is to delete those and
320
+ replace their usages (`ChatWindow.jsx`, etc.) with `<Ikoneme>` from this
321
+ package, keeping ikonchat's own responsibility limited to chat/business logic
322
+ (messages, contacts, backend sync) rather than ikon rendering.