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 +322 -274
- package/dist/Ikon.d.ts +2 -1
- package/dist/ikonDb.d.ts +8 -0
- package/dist/ikonLayout.d.ts +5 -2
- package/dist/ikonSchema.d.ts +12 -3
- package/dist/ikonSlots.d.ts +50 -0
- package/dist/ikoneme-lib.cjs +9 -9
- package/dist/ikoneme-lib.cjs.map +1 -1
- package/dist/ikoneme-lib.js +884 -944
- package/dist/ikoneme-lib.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/package.json +53 -53
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
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
"
|
|
35
|
-
"
|
|
36
|
-
"
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
###
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
-
|
|
126
|
-
the
|
|
127
|
-
|
|
128
|
-
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
- `
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
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.
|