@tensor_1/react 2.18.0 → 2.19.0

package/README.md

@@ -7,7 +7,7 @@ Thin React wrappers over the UIx v2 CSS component library — every component is
 ```sh
 npm i @tensor_1/react @tensor_1/tokens
 ```
-Peer deps: `react` / `react-dom` (`^18` or `^19`). Install `echarts` only when using a chart entry.
+Peer deps: `react` / `react-dom` (`^18` or `^19`). Install `echarts` only when using a chart entry, and the Tiptap/`marked`/`emojibase-data` peers only for `./rich-text` and `./emoji` (see below).
 
 ## Use
 
@@ -45,6 +45,89 @@ workflow surfaces, the main entry exports `Pipeline`/`PipelineStage` (compact or
 Large fixed-height tables can use `useVirtualRows(rows, { rowHeight })`; attach its `containerRef` to
 `TableWrap` and render the returned row window between spacer rows.
 
+## Rich text, markdown and emoji
+
+Three optional entries (RTE-01). None of them is imported by the root entry.
+
+| Entry | Exports | Needs |
+|---|---|---|
+| `@tensor_1/react/markdown` | `Markdown`, `parseMarkdown`, `parseInline`, `plainText`, `defaultMarkdownIsSafeUrl` | nothing (server-component safe: no hooks, no `"use client"`) |
+| `@tensor_1/react/rich-text` | `RichTextEditor`, `RichTextEditorFallback`, `roundTripMarkdown`, `DEFAULT_RICH_TEXT_LABELS`, `emojiImageFileName` | the optional peers below |
+| `@tensor_1/react/emoji` | `EmojiPicker`, `ReactionBar`, `loadEmojiData`, `buildEmojiData`, `searchEmoji`, `canRenderEmoji`, `emojiImageFileName`, `normalizeEmojiImageBaseUrl` | `emojibase-data` (dynamic import on first open) |
+
+Install the optional peers at exactly the versions `@tensor_1/react` declares (`npm view @tensor_1/react peerDependencies`):
+`@tiptap/core`, `@tiptap/pm`, `@tiptap/react`, `@tiptap/starter-kit`, `@tiptap/markdown`, `@tiptap/extension-list`,
+`@tiptap/extension-table`, `@tiptap/extension-image`, `@tiptap/extension-emoji`, `@tiptap/extensions`,
+`@tiptap/suggestion`, `marked`, `emojibase-data` — all MIT. Styles ship in `@tensor_1/tokens` (`.uix-rich-text`,
+`.uix-prose`, `.uix-emoji-picker`, `.uix-reactions`); the editor injects no `<style>` at runtime.
+
+```tsx
+import { RichTextEditor } from "@tensor_1/react/rich-text";
+import { Markdown } from "@tensor_1/react/markdown";
+
+<RichTextEditor value={body} onChange={setBody} aria-labelledby="body-label" features="full" maxLength={20000} />;
+<Markdown resolveImageSrc={(src) => (isOurImage(src) ? withBasePath(src) : null)}>{body}</Markdown>;
+```
+
+**Markdown is the stored format, and the editor never rewrites it silently.**
+`onChange` fires only for user edits, never on mount or when `value` changes from outside. Blocks the user did not
+touch keep their exact source bytes, including their spacing, list markers, table alignment, CRLF line endings,
+`{{variables}}`, umlauts and emoji ZWJ sequences. Only edited blocks are re-serialized, and their text is escaped
+only where a markdown reader would misread it (`Tom & Jerry` and `snake_case` stay as typed). Raw HTML is never
+interpreted; it stays literal text. The one exception is `<br>`, which is read as a line break because GFM table cells have no other way to hold one. Gate your own content with the same pipeline, which runs without a DOM:
+
+```ts
+import { roundTripMarkdown } from "@tensor_1/react/rich-text";
+for (const doc of corpus) expect(await roundTripMarkdown(doc.body)).toBe(doc.body);
+```
+
+Pass the markdown from `onChange` back as `value` in the same update, as React state does. The editor treats any
+other `value` as an outside change and replaces its content.
+
+Markdown cannot represent everything a user can type. When the editor re-serializes an edited block:
+
+- Leading spaces on a line are dropped.
+- Tabs in list items and table cells, and runs of spaces in table cells, become single spaces.
+- A line break inside a checklist item is saved as a new paragraph of that item.
+- Reference definitions (`[id]: url`) are kept. If their surrounding block is deleted, they move to the end.
+
+Editor props: `features` (`full` / `comment` / `template`), `headingLevels` (limits the toolbar and input rules;
+existing headings at other levels keep their level), `onUploadImage` (enables the image button and image paste/drop),
+`isSafeUrl`, `resolveImageSrc` (its return value is used verbatim), `onSubmitShortcut` (Ctrl/Cmd+Enter), `emoji`,
+`emojiImageBaseUrl`, `maxLength` (counter; over the limit sets `aria-invalid`), `placeholder`, `disabled`, `readOnly`,
+`labels` (every string, placeholders `{count}` `{max}`), `emojiPickerLabels`, `emojiLocale`, `id`, `name` (adds a
+hidden input), ARIA props, `variant` (`field` / `composer`, which renders in `Composer` with the toolbar in `ComposerBar`),
+`toolbarEnd`, `minRows`, `className`, `onBlur`. Markdown shortcuts (`## `, `- `, `1. `, `[ ] `, `> `, triple backtick)
+work in every preset; the toolbar is one tab stop with arrow-key navigation and scrolls sideways on narrow screens.
+`RichTextEditorFallback` takes the same props and renders a plain textarea, for loading and error-boundary states.
+
+**No network access.** The editor, picker and reaction bar make no requests. `@tiptap/extension-emoji` is configured
+with a list stripped of its CDN `fallbackImage` URLs and GitHub image emoji (`forceFallbackImages: false`), and the
+emoji dataset is a bundled dynamic-import chunk. A jsdom egress test guards this.
+
+**Emoji fallback images (`emojiImageBaseUrl`).** Unset by default, which means native emoji only; UIx ships no image
+set. On clients without a colour emoji font (VDI, thin clients), pass a same-origin folder (`"/static/emoji"` or
+`"./emoji"`). Values with a scheme or `//` are ignored, with a development warning. Emoji the device cannot draw then
+render as `<img class="uix-emoji-img" src="{base}/{file}" alt="{emoji}">`. `{file}` is every code point of the emoji
+in lowercase hex, joined with `-`, keeping `fe0f` and `200d`:
+
+| Emoji | File |
+|---|---|
+| 👍 | `1f44d.png` |
+| ❤️ | `2764-fe0f.png` |
+| 👩‍💻 | `1f469-200d-1f4bb.png` |
+| 👍🏽 | `1f44d-1f3fd.png` |
+| 🇩🇪 | `1f1e9-1f1ea.png` |
+
+Image sets that drop `fe0f` from file names (Twemoji, for example) need copies under the full name.
+`emojiImageFileName(emoji)` generates the mapping.
+
+`EmojiPicker` (`onSelect`, `trigger`, `locale: 'en' | 'de'`, `labels`, `quickPicks`, `emojiImageBaseUrl`,
+`loadData`) searches localized names, remembers recent picks in `localStorage` and loads its data on first open.
+`ReactionBar` (`reactions`, `onToggle`, `disabled`, `quickPicks`, `labels`, `pickerLabels`, `locale`,
+`emojiImageBaseUrl`) renders `aria-pressed` toggle chips named after the reactors (`{names} reacted with {emoji}`),
+plus an add-reaction picker.
+
 ## UIX-V3 capability components
 
 Phase 46.9 adds eleven controlled, domain-neutral components:
@@ -90,4 +173,22 @@ Rules the component cannot enforce for you:
 - **Dimming is not a signal.** `dimmedNodeIds` must be accompanied by text that says what is dimmed and why.
 - **Localise everything.** Every visible and announced string comes from `labels`; the English defaults live in `DEFAULT_RELATIONSHIP_GRAPH_LABELS`.
 
+Radial mode still shortens long labels to fit its ring, but every node carries its full label in a `<title>`, and the `viewBox` grows to contain every node, including nodes you position yourself. Use `layout="layered"` when the labels matter more than the ring.
+
+### Conversations, save feedback and kept tabs
+
+- **`Comment variant="system"`** marks a product event, such as a status change, apart from people. It has no speech bubble and a `systemLabel` byline (default "System").
+- **`Comment replyTo`** quotes the answered message above the body. Its label comes from `replyToLabel` (default "In reply to"). Mentions in a body use the `.uix-mention` class.
+- **`SaveStatus`** shows `idle`, `saving`, `saved` or `failed` for inline edits and autosave. It offers `onRetry` when a save fails, and every string comes from `labels`. The status text sits in a polite live region that stays mounted while idle, so keep one `SaveStatus` mounted and change its `state`. Mounting it only when a save starts means the first announcement is lost.
+- **`TabPanel keepMounted`** keeps an inactive panel in the DOM, `hidden` and out of the tab order, so switching back keeps its state and data. It is off by default.
+
+```tsx
+<Comment variant="system" systemLabel={t('system')} meta={ago}>{t('statusChanged', { to })}</Comment>
+<Comment author={name} meta={ago} replyTo={<a href={`#c-${parent.id}`}>{parent.excerpt}</a>} replyToLabel={t('inReplyTo')}>
+  {body}
+</Comment>
+<SaveStatus state={saveState} onRetry={save} labels={{ saving: t('saving'), saved: t('saved'), failed: t('saveFailed'), retry: t('retry') }} />
+<TabPanel value="history" keepMounted>{history}</TabPanel>
+```
+
 Ships **ESM + CJS + types**, with per-file `"use client"` so it's safe under React Server Components. Part of the **[UIx v2 styleguide](https://github.com/COx-ORG-H/UIx)**.

package/dist/components/Comments.d.ts

@@ -16,8 +16,24 @@ interface CommentProps extends HTMLAttributes<HTMLDivElement> {
     author?: ReactNode;
     meta?: ReactNode;
     children?: ReactNode;
+    /**
+     * `person` (default) is someone's message. `system` is an event the product recorded —
+     * a status change, an assignment — drawn as chrome rather than as a speech bubble, and
+     * bylined with `systemLabel` instead of a person's name.
+     */
+    variant?: 'person' | 'system';
+    /** Byline for `variant="system"` when no `author` is given. Default "System". */
+    systemLabel?: string;
+    /** The message this one answers, quoted above the body. Text or a link to it. */
+    replyTo?: ReactNode;
+    /** Label on the quote. Default "In reply to". */
+    replyToLabel?: string;
 }
-/** A single comment over `.uix-comment` (avatar column + body). */
-declare function Comment({ avatar, author, meta, children, className, ...props }: CommentProps): react.JSX.Element;
+/**
+ * A single comment over `.uix-comment` (avatar column + body). `variant="system"` marks
+ * product events apart from people; `replyTo` quotes the answered message. Mentions
+ * inside the body use the `.uix-mention` token.
+ */
+declare function Comment({ avatar, author, meta, children, className, variant, systemLabel, replyTo, replyToLabel, ...props }: CommentProps): react.JSX.Element;
 
 export { Comment, type CommentProps, Comments, type CommentsProps };

package/dist/components/Comments.js

@@ -3,18 +3,43 @@ import { cx } from "../cx.js";
 function Comments({ children, className, ...props }) {
   return /* @__PURE__ */ jsx("div", { role: "log", className: cx("uix-comments", className), ...props, children });
 }
-function Comment({ avatar, author, meta, children, className, ...props }) {
-  return /* @__PURE__ */ jsxs("div", { className: cx("uix-comment", className), ...props, children: [
-    avatar ?? /* @__PURE__ */ jsx("span", { "aria-hidden": "true" }),
-    /* @__PURE__ */ jsxs("div", { className: "uix-comment__body", children: [
-      (author != null || meta != null) && /* @__PURE__ */ jsxs("div", { className: "uix-comment__meta", children: [
-        author != null && /* @__PURE__ */ jsx("span", { className: "uix-comment__author", children: author }),
-        author != null && meta != null ? " \xB7 " : null,
-        meta
-      ] }),
-      children
-    ] })
-  ] });
+function Comment({
+  avatar,
+  author,
+  meta,
+  children,
+  className,
+  variant = "person",
+  systemLabel = "System",
+  replyTo,
+  replyToLabel = "In reply to",
+  ...props
+}) {
+  const system = variant === "system";
+  const byline = author ?? (system ? systemLabel : void 0);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cx("uix-comment", system && "uix-comment--system", className),
+      "data-variant": system ? "system" : void 0,
+      ...props,
+      children: [
+        avatar ?? /* @__PURE__ */ jsx("span", { "aria-hidden": "true" }),
+        /* @__PURE__ */ jsxs("div", { className: "uix-comment__body", children: [
+          (byline != null || meta != null) && /* @__PURE__ */ jsxs("div", { className: "uix-comment__meta", children: [
+            byline != null && /* @__PURE__ */ jsx("span", { className: "uix-comment__author", children: byline }),
+            byline != null && meta != null ? " \xB7 " : null,
+            meta
+          ] }),
+          replyTo != null && /* @__PURE__ */ jsxs("blockquote", { className: "uix-comment__reply", children: [
+            /* @__PURE__ */ jsx("span", { className: "uix-comment__reply-label", children: replyToLabel }),
+            /* @__PURE__ */ jsx("span", { className: "uix-comment__reply-body", children: replyTo })
+          ] }),
+          children
+        ] })
+      ]
+    }
+  );
 }
 export {
   Comment,

package/dist/components/EditorIcons.d.ts

@@ -0,0 +1,39 @@
+import * as react from 'react';
+import { SVGProps } from 'react';
+
+declare const PATHS: {
+    readonly heading1: "M4 12h8M4 18V6M12 18V6M17 12l3-2v8";
+    readonly heading2: "M4 12h8M4 18V6M12 18V6M21 18h-4c0-4 4-3 4-6 0-1.5-2-2.5-4-1";
+    readonly heading3: "M4 12h8M4 18V6M12 18V6M17.5 10.5c1.7-1 3.5 0 3.5 1.5a2 2 0 0 1-2 2M17 17.5c2 1.5 4 .3 4-1.5a2 2 0 0 0-2-2";
+    readonly bold: "M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8";
+    readonly italic: "M19 4h-9M14 20H5M15 4 9 20";
+    readonly strike: "M16 4H9a3 3 0 0 0-2.83 4M14 12a4 4 0 0 1 0 8H6M4 12h16";
+    readonly code: "m16 18 6-6-6-6M8 6l-6 6 6 6";
+    readonly bulletList: "M3 12h.01M3 18h.01M3 6h.01M8 12h13M8 18h13M8 6h13";
+    readonly orderedList: "M10 12h11M10 18h11M10 6h11M4 10h2M4 6h1v4M6 18H4c0-1 2-2 2-3s-1-1.5-2-1";
+    readonly taskList: "m3 17 2 2 4-4M3 7l2 2 4-4M13 6h8M13 12h8M13 18h8";
+    readonly blockquote: "M17 6H3M21 12H8M21 18H8M3 12v6";
+    readonly codeBlock: "m10 9-3 3 3 3M14 15l3-3-3-3M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2Z";
+    readonly horizontalRule: "M5 12h14";
+    readonly link: "M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71";
+    readonly table: "M12 3v18M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2ZM3 9h18M3 15h18";
+    readonly tableAddRow: "M4 3h16a1 1 0 0 1 1 1v6a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1ZM12 15v6M9 18h6";
+    readonly tableAddColumn: "M4 3h6a1 1 0 0 1 1 1v16a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1ZM18 9v6M15 12h6";
+    readonly tableDeleteRow: "M4 3h16a1 1 0 0 1 1 1v6a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1ZM9 18h6";
+    readonly tableDeleteColumn: "M4 3h6a1 1 0 0 1 1 1v16a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1ZM15 12h6";
+    readonly trash: "M3 6h18M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2";
+    readonly image: "M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2ZM9 7a2 2 0 1 0 0 4 2 2 0 0 0 0-4ZM21 15l-3.09-3.09a2 2 0 0 0-2.82 0L6 21";
+    readonly emoji: "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20ZM8 14s1.5 2 4 2 4-2 4-2M9 9h.01M15 9h.01";
+    readonly addReaction: "M22 11v1a10 10 0 1 1-9-10M8 14s1.5 2 4 2 4-2 4-2M9 9h.01M15 9h.01M16 5h6M19 2v6";
+    readonly undo: "M9 14 4 9l5-5M4 9h10.5a5.5 5.5 0 0 1 0 11H11";
+    readonly redo: "m15 14 5-5-5-5M20 9H9.5a5.5 5.5 0 0 0 0 11H13";
+    readonly sourceMode: "M10 12.5 8 15l2 2.5M14 12.5l2 2.5-2 2.5M14 2v4a2 2 0 0 0 2 2h4M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z";
+    readonly richMode: "M14 2v4a2 2 0 0 0 2 2h4M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7ZM8 13h8M8 17h5";
+    readonly clock: "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20ZM12 6v6l4 2";
+};
+type EditorIconName = keyof typeof PATHS;
+declare function EditorIcon({ name, ...props }: {
+    name: EditorIconName;
+} & SVGProps<SVGSVGElement>): react.JSX.Element;
+
+export { EditorIcon, type EditorIconName };

package/dist/components/EditorIcons.js

@@ -0,0 +1,51 @@
+import { jsx } from "react/jsx-runtime";
+const PATHS = {
+  heading1: "M4 12h8M4 18V6M12 18V6M17 12l3-2v8",
+  heading2: "M4 12h8M4 18V6M12 18V6M21 18h-4c0-4 4-3 4-6 0-1.5-2-2.5-4-1",
+  heading3: "M4 12h8M4 18V6M12 18V6M17.5 10.5c1.7-1 3.5 0 3.5 1.5a2 2 0 0 1-2 2M17 17.5c2 1.5 4 .3 4-1.5a2 2 0 0 0-2-2",
+  bold: "M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8",
+  italic: "M19 4h-9M14 20H5M15 4 9 20",
+  strike: "M16 4H9a3 3 0 0 0-2.83 4M14 12a4 4 0 0 1 0 8H6M4 12h16",
+  code: "m16 18 6-6-6-6M8 6l-6 6 6 6",
+  bulletList: "M3 12h.01M3 18h.01M3 6h.01M8 12h13M8 18h13M8 6h13",
+  orderedList: "M10 12h11M10 18h11M10 6h11M4 10h2M4 6h1v4M6 18H4c0-1 2-2 2-3s-1-1.5-2-1",
+  taskList: "m3 17 2 2 4-4M3 7l2 2 4-4M13 6h8M13 12h8M13 18h8",
+  blockquote: "M17 6H3M21 12H8M21 18H8M3 12v6",
+  codeBlock: "m10 9-3 3 3 3M14 15l3-3-3-3M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2Z",
+  horizontalRule: "M5 12h14",
+  link: "M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71",
+  table: "M12 3v18M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2ZM3 9h18M3 15h18",
+  tableAddRow: "M4 3h16a1 1 0 0 1 1 1v6a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1ZM12 15v6M9 18h6",
+  tableAddColumn: "M4 3h6a1 1 0 0 1 1 1v16a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1ZM18 9v6M15 12h6",
+  tableDeleteRow: "M4 3h16a1 1 0 0 1 1 1v6a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1ZM9 18h6",
+  tableDeleteColumn: "M4 3h6a1 1 0 0 1 1 1v16a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1ZM15 12h6",
+  trash: "M3 6h18M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2",
+  image: "M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2ZM9 7a2 2 0 1 0 0 4 2 2 0 0 0 0-4ZM21 15l-3.09-3.09a2 2 0 0 0-2.82 0L6 21",
+  emoji: "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20ZM8 14s1.5 2 4 2 4-2 4-2M9 9h.01M15 9h.01",
+  addReaction: "M22 11v1a10 10 0 1 1-9-10M8 14s1.5 2 4 2 4-2 4-2M9 9h.01M15 9h.01M16 5h6M19 2v6",
+  undo: "M9 14 4 9l5-5M4 9h10.5a5.5 5.5 0 0 1 0 11H11",
+  redo: "m15 14 5-5-5-5M20 9H9.5a5.5 5.5 0 0 0 0 11H13",
+  sourceMode: "M10 12.5 8 15l2 2.5M14 12.5l2 2.5-2 2.5M14 2v4a2 2 0 0 0 2 2h4M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z",
+  richMode: "M14 2v4a2 2 0 0 0 2 2h4M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7ZM8 13h8M8 17h5",
+  clock: "M12 2a10 10 0 1 0 0 20 10 10 0 0 0 0-20ZM12 6v6l4 2"
+};
+function EditorIcon({ name, ...props }) {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: 2,
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true",
+      focusable: "false",
+      ...props,
+      children: /* @__PURE__ */ jsx("path", { d: PATHS[name] })
+    }
+  );
+}
+export {
+  EditorIcon
+};

package/dist/components/EmojiGlyph.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+
+/**
+ * Returns a renderer for emoji glyphs. Without a (valid, same-origin) `emojiImageBaseUrl`
+ * it returns the emoji text unchanged. With one, emoji this device cannot draw become a
+ * same-origin `<img class="uix-emoji-img">` after mount (the server render is always text).
+ */
+declare function useEmojiRenderer(emojiImageBaseUrl: string | undefined): (emoji: string) => ReactNode;
+
+export { useEmojiRenderer };

package/dist/components/EmojiGlyph.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { canRenderEmoji, emojiImageSrc, normalizeEmojiImageBaseUrl } from "../emoji-image.js";
+function useEmojiRenderer(emojiImageBaseUrl) {
+  const base = useMemo(() => normalizeEmojiImageBaseUrl(emojiImageBaseUrl), [emojiImageBaseUrl]);
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => {
+    if (base) setMounted(true);
+  }, [base]);
+  return useCallback((emoji) => {
+    if (!base || !mounted || canRenderEmoji(emoji)) return emoji;
+    return /* @__PURE__ */ jsx("img", { className: "uix-emoji-img", src: emojiImageSrc(base, emoji), alt: emoji, draggable: false, decoding: "async" });
+  }, [base, mounted]);
+}
+export {
+  useEmojiRenderer
+};

package/dist/components/EmojiPicker.d.ts

@@ -0,0 +1,60 @@
+import * as react from 'react';
+import { ReactElement } from 'react';
+import { Placement } from '../overlay-position.js';
+import { EmojiLocale, EmojiDataLoader } from '../emoji-model.js';
+
+interface EmojiPickerLabels {
+    /** Accessible name of the picker dialog. */
+    dialog: string;
+    /** Search field label and placeholder. */
+    search: string;
+    /** Heading of the recently-used section. */
+    recent: string;
+    /** Heading of the quick-pick section. */
+    quickPicks: string;
+    /** Accessible name of the category navigation. */
+    categories: string;
+    /** Shown when a search matches nothing. */
+    noResults: string;
+    /** Shown while the emoji data loads. */
+    loading: string;
+    /** Shown when the emoji data cannot be loaded. */
+    loadFailed: string;
+}
+declare const DEFAULT_EMOJI_PICKER_LABELS: EmojiPickerLabels;
+interface EmojiPickerProps {
+    /** Called with the chosen emoji as Unicode text. The picker then closes. */
+    onSelect: (emoji: string) => void;
+    /** The button that opens the picker. It receives `aria-haspopup`, `aria-expanded` and a click handler. */
+    trigger: ReactElement;
+    labels?: Partial<EmojiPickerLabels>;
+    /** Language of emoji names and search terms. Default `'en'`. */
+    locale?: EmojiLocale;
+    /** Emoji shown first, before recents and categories. */
+    quickPicks?: ReadonlyArray<string>;
+    /**
+     * Same-origin folder of fallback PNGs for emoji this device cannot draw (see
+     * `emojiImageFileName` for the naming). Unset = native emoji only.
+     */
+    emojiImageBaseUrl?: string;
+    /**
+     * Replace the emojibase loader (tests, or another bundled dataset). The default loads
+     * a bundled chunk through dynamic `import()`; it never fetches a URL.
+     */
+    loadData?: EmojiDataLoader;
+    /** localStorage key for recently used emoji. */
+    recentStorageKey?: string;
+    placement?: Placement;
+    onOpenChange?: (open: boolean) => void;
+    className?: string;
+}
+/** Fixed column count; the CSS grid uses the same number. */
+declare const EMOJI_GRID_COLUMNS = 8;
+/**
+ * Emoji picker in a native popover: search, quick picks, recently used and the
+ * Unicode categories, with names in English or German. The emoji dataset loads on
+ * first open. The grid is one tab stop; arrow keys, Home and End move within it.
+ */
+declare function EmojiPicker({ onSelect, trigger, labels: labelOverrides, locale, quickPicks, loadData, recentStorageKey, placement, onOpenChange, className, emojiImageBaseUrl, }: EmojiPickerProps): react.JSX.Element;
+
+export { DEFAULT_EMOJI_PICKER_LABELS, EMOJI_GRID_COLUMNS, EmojiPicker, type EmojiPickerLabels, type EmojiPickerProps };