ikoneme-lib

React components to render and edit ikonemes — ordered sequences of ikons ("rich icons" / "super icons") — using the same rich JSON payload produced by the KomunIKON NLP pipeline and consumed by ikonchat.

This package has no server-side logic of its own: it is a pure rendering/editing layer over the ikon JSON payload. The goal is for ikonchat (and any other messaging UI) to depend on this library instead of carrying its own copy of the rich-icon rendering code.

Concepts

• Ikon — a single rich icon: a 6x6 grid of zones (context, reference, role, modes, root, tenses) plus a grammatical border.
• Ikoneme — an ordered list of ikons, e.g. one per word/concept extracted from a sentence. This is what you render in a chat bubble.

JSON payload

An ikoneme is a plain array of ikon objects:

[
  {
    "context": { "name": "Male", "url": "https://.../KomunIKON_Male.svg" },
    "reference": {
      "left": null,
      "right": { "name": "Two", "url": "https://.../KomunIKON_Two.svg" }
    },
    "role": { "name": "agent", "url": "https://.../KomunIKON_agent.svg" },
    "modes": { "name": "Exclam", "url": "https://.../KomunIKON_Exclam.svg" },
    "root": { "name": "Love/Passion", "url": "https://.../ZFcaar88AP.png" },
    "rootName": "Love/Passion",
    "tenses": { "name": "as", "url": "https://.../KomunIKON_Verbal_Tense_as.svg" },
    "border": "verb"
  }
]

This is exactly the shape ikonchat stores per message (message.richIcons). Any extra fields (e.g. a metadata block from the NLP pipeline) are preserved untouched by normalizeIkon/normalizeIkoneme.

It also maps directly onto the NLP "Rich Icon Output Specification" vocabulary:

| This library / ikonchat | NLP spec | | ------------------------------------- | ------------- | | context | gender | | modes | mode | | tenses | time-tenses | | reference, role, root, border | same name |

Components

<Ikoneme>

The main component. Renders a row of ikons for one message.

import { Ikoneme } from 'ikoneme-lib'

// Read-only, for a chat/messaging timeline
<Ikoneme ikons={message.richIcons} mode="view" size={64} />

// Editable: adds hover/tap edit + delete buttons on each ikon and opens
// the full ikon editor. `onChange` receives the updated ikoneme array.
<Ikoneme
  ikons={message.richIcons}
  mode="edit"
  size={64}
  onChange={(nextIkons) => updateMessage(message.id, nextIkons)}
/>

Props:

| Prop | Type | Default | Notes | | -------------------- | -------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ikons | Array<Ikon> | [] | The ikoneme payload. | | mode | 'view' \| 'edit' | 'view' | 'edit' shows per-ikon edit/delete controls and the editor modal. | | size | number | 64 | Pixel size of each ikon. | | gap | number | 6 | Pixel gap between ikons. | | 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. | | onIkonClick | (ikon, index) => void | — | Click handler in view mode only (e.g. show original source text). Fires independently of zoom. | | 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). | | zoomSize | number | 320 | Pixel size of the ikon inside the zoomed view (clamped to fit the viewport). | | 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 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}. | | theme | object | — | Override any --ikoneme-* CSS custom property (see Theming). | | className, style | | | Passed to the wrapper element. |

<Ikon> and <IkonEditor>

Lower-level building blocks, exported for advanced use:

import { Ikon, IkonEditor } from 'ikoneme-lib'

• <Ikon ikon={...} size={64} onClick={...} /> — renders a single ikon. The grammatical border's thickness scales with size (roughly size / 40, min 2px) so it stays legible both tiny in a chat bubble and large in a zoomed view.
• <IkonEditor ikon={...} onSave={...} onClose={...} searchRoot={...} /> — the full-screen zone editor for one ikon.
• <IkonZoomView ikon={...} size={320} onClose={...} /> — the read-only "lightbox" view <Ikoneme zoom> opens on click; exported in case you want to trigger it yourself.

Schema utilities

import {
  ZONE_CONFIG,
  BORDER_CONFIG,
  createDefaultIkon,
  normalizeIkon,
  normalizeIkoneme,
  generateIkonemeFromText
} from 'ikoneme-lib'

• normalizeIkoneme(ikons) — upgrades any legacy/URL-only stored payloads to the { name, url } shape. Run this on data loaded from storage/an API before rendering.
• generateIkonemeFromText(text) — deterministic placeholder generator (hash-based), useful for demos/tests until real NLP output is wired in.

IkonDB helpers

The public IkonDB client backing the default root search, exported for reuse:

import { searchIkons, getIkonDetails, getIkonList, IKONDB_BASE_URL } from 'ikoneme-lib'

• searchIkons(query, { limit }) — { id, name, url }[], matched by name against the full list (fetched once, cached for an hour).
• getIkonDetails(id) — { id, name, url, origin, preview, thumb, svg } for one icon (cached per id), or null if it does not exist.
• getIkonList() — the whole cached list.
• clearIkonDbCache() — drops the in-memory caches.

Icons whose IkonDB record has no image are omitted from search results.

Theming

Components read colors from --ikoneme-* CSS custom properties and ship with sensible dark-mode defaults, so nothing else is required to use them. To match your app's palette, pass a theme override:

<Ikoneme
  ikons={ikons}
  theme={{
    '--ikoneme-primary': '#00a884',
    '--ikoneme-background': '#0c0e12',
    '--ikoneme-panel-bg': '#181b20',
    '--ikoneme-surface': '#080a0e',
    '--ikoneme-border': '#2a2e36',
    '--ikoneme-text-primary': '#e9edef',
    '--ikoneme-text-secondary': '#8696a0',
    '--ikoneme-hover': '#2a2e36'
  }}
/>

Building

npm install
npm run build   # outputs dist/ikoneme-lib.js (ESM) and dist/ikoneme-lib.cjs (CJS)

Using this library in another project (local, no registry)

This package is not published to npm/a registry. Pick one of the following to consume it locally.

Option A — file: dependency (recommended)

1. Build a tarball from this repo:

   cd ikoneme-lib
   npm install
   npm run build
   npm pack   # produces ikoneme-lib-<version>.tgz

2. In the consuming project (e.g. ikonchat), add it as a dependency pointing at the tarball (adjust the relative path to wherever you placed it):

   npm install ../ikoneme-lib/ikoneme-lib-0.1.0.tgz

   This writes a "ikoneme-lib": "file:../ikoneme-lib/ikoneme-lib-0.1.0.tgz" entry to the consumer's package.json and copies/extracts the packed dist/ into node_modules — no symlink, so it behaves like a real registry install (safe for CI/Docker builds too, as long as the tarball path is available at install time).
3. Re-run steps 1–2 whenever you change the library and want the consumer to pick up the new build.

Option B — npm link (fastest for active local development)

cd ikoneme-lib
npm install
npm run build
npm link

cd ../ikonchat
npm link ikoneme-lib

This symlinks ikoneme-lib into the consumer's node_modules, so rebuilding the library (npm run build) is immediately visible to the consumer without reinstalling. Undo with npm unlink ikoneme-lib in the consumer and npm unlink in this repo.

Option C — local npm registry (Verdaccio)

For multi-developer/team setups where file:/link: paths are inconvenient, run a local registry and publish there instead of to the public npm registry:

npx verdaccio                      # starts a registry on http://localhost:4873
npm publish --registry http://localhost:4873
# in the consumer:
npm install ikoneme-lib --registry http://localhost:4873

Example app

example/ is a minimal Vite + React app that installs this library via the file: tarball approach (Option A) and renders an ikoneme in both view and edit mode. Use it to sanity-check changes before wiring the library into ikonchat:

npm run build && npm pack --pack-destination ./example
cd example
npm install
npm run dev

Next step

ikonchat currently has its own copies of this rendering/editing logic (app/components/RichIcon.jsx, RichIconEditor.jsx, app/utils/richIconMapping.js). The follow-up work is to delete those and replace their usages (ChatWindow.jsx, etc.) with <Ikoneme> from this package, keeping ikonchat's own responsibility limited to chat/business logic (messages, contacts, backend sync) rather than ikon rendering.