@gemboss/ui 0.44.0 → 0.46.0

package/src/language-switcher.tsx

@@ -0,0 +1,206 @@
+"use client";
+
+/**
+ * LanguageSwitcher — @gemboss/ui (21/10/2026): the one language button of the fleet.
+ *
+ * Chris 21/10/2026: "bộ switch ngôn ngữ ở gemcommunity, gemnews … chuẩn hoá ở gemboss ui để khi chọn một ngôn ngữ nó
+ * hiển thị lên trên cái icon luôn ví dụ là VI, EN hay chữ Zhong của trung quốc … để dễ hiểu hơn là icon quả địa cầu như
+ * hiện tại". Every surface drew its own (GemCommunity's topbar a bare globe, its sign-in pages "🌐 EN ⌄", GemNews its own),
+ * so the button now SAYS the language it is in: the globe and the short label ("EN", "VI", "中").
+ *
+ * The kit's menu, not a new one: a `details.ui-menu` whose list is `ui-menu__list gemboss-popover-surface` and whose rows
+ * are `ui-menu__item`, floated in the top layer by ./menu-layer exactly like `Menu`, so it opens with no JavaScript,
+ * closes the way every kit menu does (outside click, Escape with focus back on the button; kit-plain.js's initMenus too)
+ * and looks like the account menu. What it adds is a menu's keys (↑ ↓ Home End, Tab leaves), the current row checked
+ * (`menuitemradio`), each name in its own language (`lang`), and an optional suggested row first.
+ *
+ * The app keeps the storage: `onChange(code)` is all it gets (a cookie, localStorage, the profile, a redirect), and it
+ * passes the new `value` back. A language with an `href` is a link instead (a site whose languages are paths), so a
+ * server-rendered page switches with no script at all.
+ *
+ * language-switcher-plain.js draws the same DOM for a page with no React (`gembossUI.languageSwitcher`), held to this file
+ * node for node by language-switcher-browser.test.ts. language-switcher.css is its own entry, imported here.
+ */
+import "./language-switcher.css";
+import React, { useEffect, useRef } from "react";
+import { Icon } from "./icons";
+import { canFloatMenus, floatMenu, listenForDetachedMenus, sinkMenu } from "./menu-layer";
+
+/** One language: `code` (what `onChange` gets, and the `lang` its name is spoken in), `label` (its NATIVE name: the menu
+ *  lists every language in its own words), `short` (what the button shows; default the code's first part, upper case),
+ *  `href` (optional: the row is a link to that page in this language). */
+export interface Language {
+  code: string;
+  label: string;
+  short?: string;
+  href?: string;
+}
+
+/** The fleet's three languages, in this order. "中" for Chinese, not "ZH": the button is read by people, not by a parser. */
+export const FLEET_LANGUAGES: readonly Readonly<Language>[] = Object.freeze([
+  Object.freeze({ code: "en", label: "English", short: "EN" }),
+  Object.freeze({ code: "vi", label: "Tiếng Việt", short: "VI" }),
+  Object.freeze({ code: "zh", label: "中文", short: "中" }),
+]);
+
+/** The words it writes. The button's name is `<trigger>: <the current language's label>` ("Language: Tiếng Việt"), the
+ *  menu's name is `trigger`, the suggested row's hint is `suggested`. */
+export interface LanguageSwitcherLabels {
+  trigger: string;
+  suggested: string;
+}
+export const LANGUAGE_SWITCHER_LABELS: Readonly<LanguageSwitcherLabels> = Object.freeze({ trigger: "Language", suggested: "Suggested" });
+
+export interface LanguageSwitcherProps {
+  /** The current language's code. One not in `languages` still shows (its code, upper case). */
+  value: string;
+  /** Default `FLEET_LANGUAGES`. */
+  languages?: readonly Language[];
+  /** A row was chosen that is not the current one. The app stores it and passes the new `value`. */
+  onChange?: (code: string) => void;
+  /** A code listed first with the `suggested` hint, then a separator (GemCommunity puts the browser's language first). */
+  suggested?: string;
+  labels?: Partial<LanguageSwitcherLabels>;
+  /** `topbar` (default): the topbar end slot's ghost button, 36px (44 under a finger). `inline`: a bordered pill with a
+   *  caret, for a sign-in page, a site header or a footer. */
+  variant?: "topbar" | "inline";
+  /** The menu's right edge on the button's (default). `false`: its left edge. */
+  end?: boolean;
+  /** Added to the `<details>`'s class. */
+  className?: string;
+}
+
+/** What the button shows for a language: its `short`, else its code's first part upper case ("pt-BR" → "PT"). */
+export function languageShort(language: Language): string {
+  return language.short || language.code.split(/[-_]/)[0].toUpperCase();
+}
+
+/** The first of `wanted` (`navigator.languages`, an Accept-Language list, one tag) that `languages` has: the exact code,
+ *  else the same base language ("zh-CN" → "zh", "vi-VN" → "vi"). Undefined when none is. Pure: the app passes the list. */
+export function matchLanguage(languages: readonly Language[], wanted: string | readonly string[] | null | undefined): string | undefined {
+  const list = typeof wanted === "string" ? wanted.split(",") : wanted ?? [];
+  const base = (s: string) => s.split(/[-_]/)[0];
+  for (const raw of list) {
+    const tag = String(raw).split(";")[0].trim().toLowerCase();
+    if (!tag) continue;
+    const hit = languages.find((l) => l.code.toLowerCase() === tag) ?? languages.find((l) => base(l.code.toLowerCase()) === base(tag));
+    if (hit) return hit.code;
+  }
+  return undefined;
+}
+
+const ITEM = ".gb-lang__item";
+const rowsOf = (d: HTMLDetailsElement) => Array.from(d.querySelectorAll<HTMLElement>(ITEM));
+/** Focus the checked row (else the first): where a menu opens. */
+function focusCurrent(d: HTMLDetailsElement) {
+  const rows = rowsOf(d);
+  (rows.find((r) => r.getAttribute("aria-checked") === "true") ?? rows[0])?.focus();
+}
+function openMenu(d: HTMLDetailsElement) {
+  d.open = true;
+  if (canFloatMenus()) floatMenu(d);
+}
+function closeMenu(d: HTMLDetailsElement) {
+  d.open = false;
+  d.querySelector<HTMLElement>(":scope > summary")?.focus();
+}
+
+export function LanguageSwitcher({ value, languages = FLEET_LANGUAGES, onChange, suggested, labels, variant = "topbar", end = true, className }: LanguageSwitcherProps) {
+  const ref = useRef<HTMLDetailsElement>(null);
+  const L = { ...LANGUAGE_SWITCHER_LABELS, ...labels };
+  const current = languages.find((l) => l.code === value);
+  const name = `${L.trigger}: ${current ? current.label : value}`;
+  const first = suggested ? languages.find((l) => l.code === suggested) : undefined;
+  const rest = first ? languages.filter((l) => l !== first) : languages;
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return undefined;
+    // Menu's three (menu.tsx): an outside click closes it, Escape closes it with focus back on the button, and an open
+    // menu floats. Plus: an opening puts focus on the checked row, as a menu button does.
+    const onDoc = (e: MouseEvent) => { if (el.open && !el.contains(e.target as Node)) el.open = false; };
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape" && el.open && !e.isComposing) closeMenu(el); };
+    const onToggle = () => {
+      if (!el.open) { sinkMenu(el); return; }
+      if (canFloatMenus()) floatMenu(el);
+      focusCurrent(el);
+    };
+    document.addEventListener("click", onDoc);
+    document.addEventListener("keydown", onKey);
+    el.addEventListener("toggle", onToggle);
+    if (canFloatMenus()) {
+      listenForDetachedMenus();
+      if (el.open) floatMenu(el);
+    }
+    return () => {
+      document.removeEventListener("click", onDoc);
+      document.removeEventListener("keydown", onKey);
+      el.removeEventListener("toggle", onToggle);
+    };
+  }, []);
+
+  // As Menu: the summary opens it and floats it in the same task, so the list is never painted in place first.
+  const onSummary = (e: React.MouseEvent<HTMLElement>) => {
+    const el = ref.current;
+    if (!el || !canFloatMenus()) return;
+    e.preventDefault();
+    if (el.open) el.open = false; else openMenu(el);
+  };
+  const onKeyDown = (e: React.KeyboardEvent<HTMLDetailsElement>) => {
+    const el = e.currentTarget;
+    const t = e.target as HTMLElement;
+    if (t.tagName === "SUMMARY") {
+      // ↓ / ↑ on the button open the menu (or go into it), on the checked row.
+      if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
+      e.preventDefault();
+      if (el.open) focusCurrent(el); else openMenu(el);
+      return;
+    }
+    const rows = rowsOf(el);
+    const i = rows.indexOf(t);
+    if (i < 0) return;
+    // Tab leaves the menu: it closes and focus goes on from the button, forward or back (not prevented).
+    if (e.key === "Tab") { closeMenu(el); return; }
+    const next = e.key === "ArrowDown" ? (i + 1) % rows.length : e.key === "ArrowUp" ? (i - 1 + rows.length) % rows.length
+      : e.key === "Home" ? 0 : e.key === "End" ? rows.length - 1 : -1;
+    if (next < 0) return;
+    e.preventDefault();
+    rows[next].focus();
+  };
+  const pick = (code: string) => (e: React.MouseEvent<HTMLElement>) => {
+    const el = e.currentTarget.closest("details");
+    if (el) closeMenu(el);
+    if (code !== value) onChange?.(code);
+  };
+
+  const row = (l: Language, hint?: string) => {
+    const on = l.code === value;
+    const body = (
+      <>
+        <span className="gb-lang__check" aria-hidden="true"><Icon name="check" size={16} /></span>
+        <span className="gb-lang__name" lang={l.code}>{l.label}</span>
+        {hint ? <span className="ui-menu__hint">{hint}</span> : null}
+      </>
+    );
+    const common = { role: "menuitemradio", "aria-checked": on, className: "ui-menu__item gb-lang__item", tabIndex: -1, "data-lang": l.code, onClick: pick(l.code) } as const;
+    return l.href
+      ? <a key={l.code} {...common} href={l.href} hrefLang={l.code}>{body}</a>
+      : <button key={l.code} type="button" {...common}>{body}</button>;
+  };
+
+  return (
+    <details ref={ref} onKeyDown={onKeyDown}
+      className={["ui-menu", end ? "ui-menu--end" : "", "gb-lang", `gb-lang--${variant}`, className ?? ""].filter(Boolean).join(" ")}>
+      <summary className="gb-lang__btn" aria-label={name} title={name} aria-haspopup="menu" onClick={onSummary}>
+        <Icon name="globe" size={18} />
+        {/* In its language too: "中" drawn with a Chinese font's glyph, not a Japanese one. */}
+        <span className="gb-lang__short" lang={current?.code}>{current ? languageShort(current) : value.toUpperCase()}</span>
+        {variant === "inline" ? <Icon name="chevronDown" size={14} className="gb-lang__caret" /> : null}
+      </summary>
+      <div className="ui-menu__list gemboss-popover-surface gb-lang__list" role="menu" aria-label={L.trigger}>
+        {first ? <>{row(first, L.suggested)}<hr className="ui-menu__sep" /></> : null}
+        {rest.map((l) => row(l))}
+      </div>
+    </details>
+  );
+}

package/src/reactions-data.ts

@@ -8,7 +8,8 @@
  * Plain TypeScript (no React): a server, a plain-HTML surface and the React component all import it.
  */
 
-/** [group name, [emoji, search words][]][] — the picker draws the groups in this order. */
+/** [group id, [emoji, search words][]][] — the picker draws the groups in this order. The id is English and stays: it is the
+ *  heading's default and the key a translation is looked up by (`labels.groupName(id)`, reactions.tsx). */
 export const REACTION_GROUPS: ReadonlyArray<readonly [string, ReadonlyArray<readonly [string, string]>]> = [
   ["Smileys", [["😀", "grin smile happy"], ["😃", "smile happy"], ["😄", "smile laugh happy"], ["😁", "grin beam"], ["😆", "laugh squint"], ["😅", "sweat smile relief"], ["😂", "joy tears laugh lol"], ["🤣", "rofl rolling laugh"], ["😊", "blush smile"], ["😇", "innocent halo"], ["🙂", "slight smile ok"], ["😉", "wink"], ["😍", "heart eyes love"], ["🥰", "love hearts"], ["😘", "kiss"], ["😋", "yum tasty"], ["😜", "wink tongue"], ["🤪", "zany crazy"], ["🤗", "hug"], ["🤭", "oops giggle"], ["🤔", "think hmm"], ["🤨", "raised eyebrow doubt"], ["😐", "neutral"], ["😶", "no words"], ["🙄", "eye roll"], ["😏", "smirk"], ["😬", "grimace awkward"], ["😌", "relieved"], ["😴", "sleep tired"], ["😷", "mask sick"], ["🤯", "mind blown"], ["🥳", "party celebrate"], ["😎", "cool sunglasses"], ["🤓", "nerd"], ["😕", "confused"], ["😟", "worried"], ["😮", "wow surprised"], ["😲", "astonished"], ["😳", "flushed embarrassed"], ["🥺", "pleading please"], ["😢", "cry sad"], ["😭", "sob crying"], ["😱", "scream shock"], ["😤", "huff frustrated"], ["😡", "angry mad"], ["🤬", "swear"], ["💀", "dead skull"], ["🫠", "melting"], ["🫡", "salute"]]],
   ["Hands", [["👍", "like thumbs up yes ok"], ["👎", "dislike thumbs down no"], ["👌", "ok perfect"], ["✌️", "peace victory"], ["🤞", "fingers crossed luck"], ["🤟", "love you"], ["🤘", "rock"], ["👏", "clap applause"], ["🙌", "raise hands hooray"], ["👐", "open hands"], ["🤝", "handshake deal"], ["🙏", "thanks please pray"], ["💪", "strong muscle"], ["👀", "eyes looking"], ["🫶", "heart hands"], ["✍️", "writing"], ["👋", "wave hi bye"], ["☝️", "point up"], ["👇", "point down"], ["👉", "point right"], ["👈", "point left"], ["🤙", "call me"], ["🖐️", "stop hand"], ["🤌", "pinched"]]],
@@ -45,10 +46,20 @@ export function reactionWords(e: string): string {
   return KEYS.get(e) ?? "";
 }
 
-/** Emoji whose search words contain the query (any case); all of them for an empty query. */
-export function searchReactions(query: string): string[] {
+const GROUP_OF = new Map<string, string>(REACTION_GROUPS.flatMap(([id, items]) => items.map(([e]) => [e, id] as [string, string])));
+/** A name as a search compares it: lower case, Vietnamese marks and the like dropped ("Mặt cười" → "mat cuoi"), đ → d. */
+const fold = (s: string) => s.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/\u0111/g, "d");
+
+/** Emoji whose search words contain the query (any case); all of them for an empty query. The search words are English.
+ *  `groupName` (the picker's `labels.groupName`, 21/10/2026): a query found in a TRANSLATED group name ("mặt cười", "mat cuoi"
+ *  for a group called "Mặt cười") adds that whole group, in picker order. A name left as its English id adds nothing, so a
+ *  picker in English searches exactly as before. */
+export function searchReactions(query: string, groupName?: (id: string) => string): string[] {
   const t = query.trim().toLowerCase();
-  return t ? REACTION_EMOJI.filter((e) => KEYS.get(e)!.includes(t)) : [...REACTION_EMOJI];
+  if (!t) return [...REACTION_EMOJI];
+  const q = fold(t), groups = new Set<string>();
+  if (groupName) for (const [id] of REACTION_GROUPS) { const name = groupName(id); if (name !== id && fold(String(name)).includes(q)) groups.add(id); }
+  return REACTION_EMOJI.filter((e) => KEYS.get(e)!.includes(t) || groups.has(GROUP_OF.get(e)!));
 }
 
 /** One emoji on one thing: who put it there. `mine` is the viewer's own. */

package/src/reactions.tsx

@@ -18,12 +18,55 @@
  *
  * Each target is 44px (a control, CLAUDE.md §9.1) while the visible pill is 26px: transparent padding carries the rest,
  * so a message with reactions does not grow a whole line.
+ *
+ * Every word both write is in `REACTION_LABELS` (21/10/2026: GemCommunity's Vietnamese chat showed "Search emoji" and
+ * "Smileys"); pass `labels` (any subset) to translate. The team chat's `TEAM_CHAT_LABELS` carries the same keys and its
+ * components pass their `labels` on. reactions.test.tsx holds this file to it: no word outside the table.
  */
 import "./reactions.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
 import React, { useEffect, useId, useRef, useState } from "react";
 import { Icon } from "./icons";
 import { frequentReactions, REACTION_GROUPS, reactionLabel, reactionWords, searchReactions, type Reaction } from "./reactions-data";
 
+// labels:begin
+/** Every word `Reactions` and `ReactionPicker` write themselves. Pass `labels` (any subset) to translate. */
+export type ReactionLabels = {
+  /** The picker's accessible name (a `label` prop wins). */
+  pickReaction: string;
+  /** The picker's search field: its placeholder and its accessible name. */
+  searchEmoji: string;
+  /** What the picker says when the search finds nothing. */
+  noEmojiMatches: string;
+  /** The heading of this browser's row. */
+  frequentlyUsed: string;
+  /** A group's heading, by its English id in `REACTION_GROUPS` ("Smileys", "Hands", "Marks", "Work"). The id stays the key;
+   *  a translated name is also searched (`searchReactions`). The emoji's own search words are English. */
+  groupName: (id: string) => string;
+  /** A picker button's accessible name where the picker puts reactions (the composer's names a button by the emoji and its
+   *  search words alone): "Add 🎉 party tada celebrate", "Remove 👍 like thumbs up yes ok". */
+  pickReactionEmoji: (emoji: string, words: string, mine: boolean) => string;
+  /** The tooltip of the button that opens the picker (the reaction row's, and the team chat's action bar). */
+  addReaction: string;
+  /** The reaction row's "Add reaction" accessible name; `target` is the `target` prop, absent for none. */
+  addReactionTo: (target?: string) => string;
+  /** A chip's accessible name: its emoji, who put it (`names`, joined by ", ") and what a click does. */
+  reactionChip: (emoji: string, names: string, mine: boolean) => string;
+};
+
+export const REACTION_LABELS: ReactionLabels = {
+  pickReaction: "Pick a reaction",
+  searchEmoji: "Search emoji",
+  noEmojiMatches: "No emoji matches.",
+  frequentlyUsed: "Frequently used",
+  groupName: (id) => id,
+  pickReactionEmoji: (e, w, mine) => `${mine ? "Remove" : "Add"} ${e} ${w}`,
+  addReaction: "Add reaction",
+  addReactionTo: (target) => `Add a reaction to ${target ?? "this"}`,
+  reactionChip: (e, names, mine) => `${e}, ${names}. ${mine ? "Remove yours" : "Add yours"}`,
+};
+// labels:end
+const words = (labels?: Partial<ReactionLabels>): ReactionLabels => (labels ? { ...REACTION_LABELS, ...labels } : REACTION_LABELS);
+
 const RECENT_KEY = "gemboss-ui:reactions-recent";
 const RECENT_MAX = 9;
 
@@ -47,16 +90,19 @@ export type ReactionsProps = {
   /** Put or take back the viewer's emoji. The caller decides add or remove from its own state (a click on a chip that is
    *  `mine` takes it back); `toggleReaction` is the optimistic guess to draw before the server answers. */
   onToggle?: (emoji: string) => void;
-  /** Who or what is reacted to, for screen readers: "the comment from Linh". */
+  /** Who or what is reacted to, for screen readers: "the comment from Linh" (default: `labels.addReactionTo()`'s "this"). */
   target?: string;
   /** Show "Add reaction" (default true). A signed-out reader sees the chips only. */
   canReact?: boolean;
   /** The text a signed-out reader's click should lead to instead (e.g. open sign-in); chips are buttons either way. */
   onSignIn?: () => void;
   className?: string;
+  /** The words (`REACTION_LABELS`, any subset), the picker's included. */
+  labels?: Partial<ReactionLabels>;
 };
 
-export function Reactions({ items, onToggle, target = "this", canReact = true, onSignIn, className }: ReactionsProps) {
+export function Reactions({ items, onToggle, target, canReact = true, onSignIn, className, labels }: ReactionsProps) {
+  const t = words(labels);
   const [open, setOpen] = useState(false);
   const addRef = useRef<HTMLButtonElement>(null);
   const pickerId = useId();
@@ -71,21 +117,21 @@ export function Reactions({ items, onToggle, target = "this", canReact = true, o
       <div className="ui-reactions__row">
         {items.map((r) => (
           <button key={r.emoji} type="button" className={`ui-reaction${r.mine ? " is-mine" : ""}`} aria-pressed={r.mine}
-            title={r.names.join(", ")} aria-label={`${r.emoji}, ${r.names.join(", ")}. ${r.mine ? "Remove yours" : "Add yours"}`}
+            title={r.names.join(", ")} aria-label={t.reactionChip(r.emoji, r.names.join(", "), r.mine)}
             onClick={() => act(r.emoji)}>
             <span className="ui-reaction__emoji">{r.emoji}</span>
             <span className="ui-reaction__names">{reactionLabel(r.names)}</span>
           </button>
         ))}
         {canReact ? (
-          <button ref={addRef} type="button" className="ui-reaction-add" title="Add reaction" aria-label={`Add a reaction to ${target}`}
+          <button ref={addRef} type="button" className="ui-reaction-add" title={t.addReaction} aria-label={t.addReactionTo(target)}
             aria-expanded={open} aria-controls={open ? pickerId : undefined} onClick={() => setOpen((o) => !o)}>
             <Icon name="reaction" size={18} />
           </button>
         ) : null}
       </div>
       {open ? (
-        <ReactionPicker id={pickerId} items={items}
+        <ReactionPicker id={pickerId} items={items} labels={t}
           onPick={(emoji) => { setOpen(false); act(emoji); addRef.current?.focus(); }}
           onClose={() => { setOpen(false); addRef.current?.focus(); }} />
       ) : null}
@@ -101,15 +147,18 @@ export type ReactionPickerProps = {
   /** Escape. */
   onClose: () => void;
   id?: string;
-  /** The group's accessible name. Default "Pick a reaction". */
+  /** The group's accessible name. Default `labels.pickReaction` ("Pick a reaction"). */
   label?: string;
   className?: string;
   /** Where focus goes when it opens: the search (default), or the first emoji (under a finger, where a focused search
    *  brings the keyboard up over the picker). */
   initialFocus?: "search" | "emoji";
+  /** The words (`REACTION_LABELS`, any subset): the search, "No emoji matches.", "Frequently used", the group headings. */
+  labels?: Partial<ReactionLabels>;
 };
 
-export function ReactionPicker({ items, onPick, onClose, id, label = "Pick a reaction", className, initialFocus = "search" }: ReactionPickerProps) {
+export function ReactionPicker({ items, onPick, onClose, id, label, className, initialFocus = "search", labels }: ReactionPickerProps) {
+  const t = words(labels);
   const [q, setQ] = useState("");
   const [recent, setRecent] = useState<readonly string[]>(() => frequentReactions([]));
   const search = useRef<HTMLInputElement>(null);
@@ -124,11 +173,11 @@ export function ReactionPicker({ items, onPick, onClose, id, label = "Pick a rea
   const mine = (e: string) => Boolean(items?.some((r) => r.emoji === e && r.mine));
   const btn = (e: string) => (
     <button key={e} type="button" className="ui-reaction-picker__btn" title={reactionWords(e).split(" ")[0] || e}
-      aria-label={(items ? `${mine(e) ? "Remove" : "Add"} ${e} ${reactionWords(e)}` : `${e} ${reactionWords(e)}`).trim()}
+      aria-label={(items ? t.pickReactionEmoji(e, reactionWords(e), mine(e)) : `${e} ${reactionWords(e)}`).trim()}
       aria-pressed={items ? mine(e) : undefined} onClick={() => onPick(e)}>{e}</button>
   );
   const grid = (list: readonly string[]) => <div className="ui-reaction-picker__grid">{list.map(btn)}</div>;
-  const found = q.trim() ? searchReactions(q) : null;
+  const found = q.trim() ? searchReactions(q, t.groupName) : null;
   const onKeyDown = (ev: React.KeyboardEvent) => {
     if (ev.key === "Escape") { ev.preventDefault(); ev.stopPropagation(); onClose(); return; }
     const all = [...(body.current?.querySelectorAll<HTMLButtonElement>(".ui-reaction-picker__btn") ?? [])];
@@ -148,15 +197,15 @@ export function ReactionPicker({ items, onPick, onClose, id, label = "Pick a rea
     all[Math.min(all.length - 1, at + step)]?.focus();
   };
   return (
-    <div id={id} className={["ui-reaction-picker", className].filter(Boolean).join(" ")} role="group" aria-label={label} onKeyDown={onKeyDown}>
-      <input ref={search} type="search" className="gemboss-field ui-reaction-picker__search" placeholder="Search emoji" aria-label="Search emoji"
+    <div id={id} className={["ui-reaction-picker", className].filter(Boolean).join(" ")} role="group" aria-label={label ?? t.pickReaction} onKeyDown={onKeyDown}>
+      <input ref={search} type="search" className="gemboss-field ui-reaction-picker__search" placeholder={t.searchEmoji} aria-label={t.searchEmoji}
         autoComplete="off" value={q} onChange={(e) => setQ(e.target.value)} />
       <div ref={body} className="ui-reaction-picker__body">
-        {found ? (found.length ? grid(found) : <p className="ui-reaction-picker__empty">No emoji matches.</p>) : (
+        {found ? (found.length ? grid(found) : <p className="ui-reaction-picker__empty">{t.noEmojiMatches}</p>) : (
           <>
-            <p className="ui-reaction-picker__head">Frequently used</p>{grid(recent)}
-            {REACTION_GROUPS.map(([name, list]) => (
-              <React.Fragment key={name}><p className="ui-reaction-picker__head">{name}</p>{grid(list.map(([e]) => e))}</React.Fragment>
+            <p className="ui-reaction-picker__head">{t.frequentlyUsed}</p>{grid(recent)}
+            {REACTION_GROUPS.map(([gid, list]) => (
+              <React.Fragment key={gid}><p className="ui-reaction-picker__head">{t.groupName(gid)}</p>{grid(list.map(([e]) => e))}</React.Fragment>
             ))}
           </>
         )}

package/src/setup-guide.css

@@ -1 +1 @@
-.ui-setup,.ui-setup__inner{display:grid;gap:var(--ui-space-3, 12px)}.ui-setup__head,.ui-setup__row{display:flex;align-items:center;gap:var(--ui-space-3, 12px);list-style:none;cursor:pointer;border-radius:var(--ui-radius-md, 8px);color:inherit;transition:background-color .12s ease}.ui-setup__head::-webkit-details-marker,.ui-setup__row::-webkit-details-marker{display:none}div.ui-setup__head{cursor:auto}summary.ui-setup__head{padding:6px 8px;margin:-6px -8px 0}.ui-setup__title{margin:0;font-size:var(--ui-fs-body, 13px);line-height:20px;font-weight:650;color:var(--ui-text-strong, var(--ui-text))}.ui-setup__desc{margin:0;font-size:var(--ui-fs-body, 13px);line-height:20px;color:var(--ui-text-muted)}.ui-setup__row{padding:8px;margin:0 -8px}summary.ui-setup__head:hover,summary.ui-setup__row:hover{background:var(--ui-surface-2, #eceef2)}.ui-setup__row--static{cursor:auto}.ui-setup__row.ui-setup__row--static:after{content:none}summary.ui-setup__head:active,summary.ui-setup__row:active{background:var(--ui-border, #e5e7ea)}summary.ui-setup__head:focus-visible,summary.ui-setup__row:focus-visible{outline:2px solid var(--ui-focus, #5661f5);outline-offset:2px}summary.ui-setup__head:after,.ui-setup__row:after{content:"\25be";margin-left:auto;font-size:11px;color:var(--ui-text-muted);transition:transform .12s ease}.ui-setup:not([open])>summary.ui-setup__head:after,.ui-setup__step:not([open])>.ui-setup__row:after{transform:rotate(-90deg)}.ui-setup__bar{appearance:none;-webkit-appearance:none;display:block;width:100%;height:6px;border:0;border-radius:999px;overflow:hidden;background:var(--ui-border, #e5e7ea);color:var(--ui-accent, #1b1c1e)}.ui-setup__bar::-webkit-progress-bar{background:var(--ui-border, #e5e7ea);border-radius:inherit}.ui-setup__bar::-webkit-progress-value{background:currentColor;border-radius:inherit;transition:width .15s ease}.ui-setup__bar::-moz-progress-bar{background:currentColor;border-radius:inherit}.ui-setup__bar--done{color:var(--ui-success-fg, #007f5f)}.ui-setup__steps{display:grid;gap:2px}.ui-setup__mark{flex:0 0 16px;text-align:center;line-height:20px;color:var(--ui-text-muted)}.ui-setup__step[data-state=done] .ui-setup__mark{color:var(--ui-success-fg, #007f5f)}.ui-setup__label{min-width:0;overflow-wrap:anywhere;font-size:var(--ui-fs-body, 13px);line-height:20px;font-weight:550;color:var(--ui-text)}.ui-setup__step[data-state=done] .ui-setup__label{font-weight:450;color:var(--ui-text-muted)}.ui-setup__body{padding:4px 0 12px 28px;font-size:var(--ui-fs-body, 13px);line-height:20px;color:var(--ui-text)}.ui-setup__body>:first-child{margin-top:0}.ui-setup__body>:last-child{margin-bottom:0}@media (pointer: coarse),(max-width: 47.9975em){summary.ui-setup__head,.ui-setup__row{min-height:44px;box-sizing:border-box}}@media (prefers-reduced-motion: reduce){.ui-setup__head,.ui-setup__row,summary.ui-setup__head:after,.ui-setup__row:after,.ui-setup__bar::-webkit-progress-value{transition:none}}
+.ui-setup{--ui-setup-done: var(--gemboss-success, #007f5f)}.ui-setup,.ui-setup__inner{display:grid;gap:var(--ui-space-3, 12px)}.ui-setup__head,.ui-setup__row{display:flex;align-items:center;gap:var(--ui-space-3, 12px);list-style:none;cursor:pointer;border-radius:var(--ui-radius-md, 8px);color:inherit;transition:background-color .12s ease}.ui-setup__head::-webkit-details-marker,.ui-setup__row::-webkit-details-marker{display:none}div.ui-setup__head{cursor:auto}summary.ui-setup__head{padding:6px 8px;margin:-6px -8px 0}.ui-setup__title{margin:0;font-size:var(--ui-fs-body, 13px);line-height:20px;font-weight:650;color:var(--ui-text-strong, var(--ui-text))}.ui-setup .ui-badge--warning{background:var(--gemboss-warning-soft);color:var(--gemboss-warning)}.ui-setup .ui-badge--success{background:var(--gemboss-success-soft);color:var(--gemboss-success-strong)}.ui-setup__desc{margin:0;font-size:var(--ui-fs-body, 13px);line-height:20px;color:var(--ui-text-muted)}.ui-setup__row{padding:8px;margin:0 -8px}summary.ui-setup__head:hover,summary.ui-setup__row:hover,.ui-setup__x:hover{background:var(--ui-surface-2, #eceef2)}.ui-setup__row--static{cursor:auto}.ui-setup__row.ui-setup__row--static:after{content:none}summary.ui-setup__head:active,summary.ui-setup__row:active,.ui-setup__x:active{background:var(--ui-border, #e5e7ea)}summary.ui-setup__head:focus-visible,summary.ui-setup__row:focus-visible,.ui-setup__x:focus-visible{outline:2px solid var(--ui-focus, #5661f5);outline-offset:2px}summary.ui-setup__head:after,.ui-setup__row:after{content:"\25be";margin-left:auto;font-size:11px;color:var(--ui-text-muted);transition:transform .12s ease}.ui-setup:not([open])>summary.ui-setup__head:after,:is(.ui-setup__step,.ui-setup__done):not([open])>.ui-setup__row:after{transform:rotate(-90deg)}.ui-setup__bar{appearance:none;display:block;width:100%;height:6px;border:0;border-radius:999px;overflow:hidden;background:var(--ui-border, #e5e7ea);color:var(--ui-setup-done)}.ui-setup__bar::-webkit-progress-bar{background:inherit;border-radius:inherit}.ui-setup__bar::-webkit-progress-value{background:currentColor;border-radius:inherit;transition:width .15s ease}.ui-setup__bar::-moz-progress-bar{background:currentColor;border-radius:inherit}.ui-setup__steps{display:grid;gap:2px}.ui-setup__mark{flex:0 0 18px;width:18px;height:18px;box-sizing:border-box;display:inline-grid;place-items:center;position:relative;border:1.5px solid color-mix(in srgb,var(--ui-text-muted, #686b71) 50%,transparent);border-radius:50%;font-size:0;color:var(--ui-text-muted, #686b71)}:is(.ui-setup__step[data-state=done],.ui-setup__done)>.ui-setup__row>.ui-setup__mark{background:var(--ui-setup-done);border-color:var(--ui-setup-done)}:is(.ui-setup__step[data-state=done],.ui-setup__done)>.ui-setup__row>.ui-setup__mark:before{content:"";position:absolute;left:5px;top:2px;width:4px;height:8px;box-sizing:content-box;border:solid #fff;border-width:0 1.75px 1.75px 0;transform:rotate(45deg)}.ui-setup__step[data-state=unknown]>.ui-setup__row>.ui-setup__mark{border-style:dashed;font-size:10px;font-weight:650}.ui-setup__label{min-width:0;overflow-wrap:anywhere;font-size:var(--ui-fs-body, 13px);line-height:20px;font-weight:550;color:var(--ui-text)}:is(.ui-setup__step[data-state=done],.ui-setup__done)>.ui-setup__row>.ui-setup__label,.ui-setup__optional .ui-setup__label{font-weight:450;color:var(--ui-text-muted)}.ui-setup__action{flex:none;display:inline-flex;gap:8px;margin:-4px 0 -4px auto}.ui-setup__actions{display:flex;flex-wrap:wrap;gap:8px;margin-top:8px}.ui-setup__body{padding:4px 0 12px 30px;font-size:var(--ui-fs-body, 13px);line-height:20px;color:var(--ui-text)}.ui-setup__body>:first-child{margin-top:0}.ui-setup__body>:last-child{margin-bottom:0}.ui-setup__optional{display:grid;gap:8px;padding-top:12px;border-top:1px solid var(--ui-border, #e5e7ea)}.ui-setup__subtitle{margin:0;font-size:13px;line-height:20px;font-weight:650;color:var(--ui-text-muted)}.ui-setup__x{flex:none;display:inline-grid;place-items:center;width:28px;height:28px;margin:-4px -4px -4px auto;padding:0;border:0;border-radius:8px;background:none;color:var(--ui-text-muted);cursor:pointer}.ui-setup__x svg{width:16px;height:16px}@media (pointer: coarse),(max-width: 47.9975em){summary.ui-setup__head,.ui-setup__row{min-height:44px;box-sizing:border-box}.ui-setup__x{width:44px;height:44px;margin:-12px -12px -12px auto}:is(.ui-setup__body,.ui-setup__action) :is(button,a.ui-btn){min-height:44px}}@media (prefers-reduced-motion: reduce){.ui-setup__head,.ui-setup__row,summary.ui-setup__head:after,.ui-setup__row:after,.ui-setup__bar::-webkit-progress-value{transition:none}}

package/src/setup-guide.tsx

@@ -9,6 +9,14 @@
  * Why it moved here (08/10/2026): gemform's Telegram alerts page drew its own numbered steps (1 The bot, 2 Where alerts
  * go), the admin has this one in Polaris, and a third surface with a "connect this, then that" page would write a third.
  *
+ * ONE checklist for the fleet (21/10/2026, Chris: "cái onboarding checklist của gemcommunity với của gemboss nút tick
+ * màu xanh progress bar nên đồng bộ nhé để dùng cùng một gemboss ui kit"). GemBoss' "Set up your store" and
+ * GemCommunity's "Start here" were two drawings of one thing: grey ✓ glyphs and a black bar on one, filled green ticks,
+ * an iris bar and a "✓ 2 completed" fold on the other. Both now render this, so the guide took what each did better:
+ * the filled green tick (todo is an empty ring), a bar in the same green (it counts the ticks), the steps already done
+ * folded behind one "✓ N completed" row, an "Optional" group under the counted steps (the admin's notes), a step's own
+ * control at the end of its row (`action`), and a × for a guide that is dismissed rather than folded (`onDismiss`).
+ *
  * Native `<details>` all the way down, so a page that writes the markup by hand gets the same behaviour with no script:
  * the guide is a `<details>` whose `<summary>` folds it away, each step is a `<details name>` of one group, which the
  * browser keeps to one open at a time. The ROW reveals; what changes something is a button the surface puts in the
@@ -16,8 +24,10 @@
  * nothing.
  *
  * The step open at first is the first one not done, decided ONCE, like the admin: a step's state changing while the
- * person reads it must not slam it shut (finishing step 1 leaves its confirmation on screen). The bar is a <progress>,
- * not a width in a style attribute, so it fills under a CSP that forbids inline style.
+ * person reads it must not slam it shut (finishing step 1 leaves its confirmation on screen). The fold is decided once
+ * for the same reason: a step finished while the guide is on screen stays where it is and turns green, it does not
+ * vanish into the fold under the person's eyes; the next visit folds it. The bar is a <progress>, not a width in a
+ * style attribute, so it fills under a CSP that forbids inline style.
  */
 import "./setup-guide.css"; // its own entry (0.30.0)
 import React, { useEffect, useId, useRef, useState } from "react";
@@ -33,32 +43,57 @@ export interface SetupStep {
   state?: SetupState;
   /** What the open step shows: a sentence and the control that does it. Without one the row is not a toggle. */
   body?: React.ReactNode;
+  /** The control that does the step (21/10/2026): at the end of its row when the step has no body, under the body
+   *  when it has one (a control inside the row would be a control inside a toggle). */
+  action?: React.ReactNode;
+  /** A class on the step, for the surface's own rule (GemCommunity hides its Telegram step where the rail asks). */
+  className?: string;
+}
+
+export interface SetupGuideLabels {
+  progress?: string;
+  notMeasured?: (n: number) => string;
+  /** The fold of the steps already done: "2 completed". */
+  completed?: (n: number) => string;
+  /** The heading of the `optional` group. */
+  optional?: string;
+  /** The × of a guide with `onDismiss`. */
+  dismiss?: string;
 }
 
 const MARK: Record<SetupState, string> = { done: "✓", todo: "○", unknown: "?" };
 
-export function SetupGuide({ title, description, steps, open, collapsible = true, rememberKey, group, labels, className }: {
+export function SetupGuide({ title, description, steps, optional, open, collapsible = true, foldDone = true, onDismiss, rememberKey, group, labels, className }: {
   title: React.ReactNode;
   description?: React.ReactNode;
   steps: readonly SetupStep[];
+  /** Steps worth doing that the count leaves out (the admin's "Optional" notes): under a divider, never progress. */
+  optional?: readonly SetupStep[];
   /** The step to show open at first; defaults to the first one not done. */
   open?: string;
   /** false: the head is a plain heading, the guide cannot be folded away. */
   collapsible?: boolean;
+  /** Fold the steps done when the guide first renders behind one "✓ N completed" row (default). false lists them. */
+  foldDone?: boolean;
+  /** Put the guide away with a × instead of folding it (the surface remembers and stops rendering it). A guide that
+   *  can be dismissed does not also fold: two ways to put one card away is one too many. */
+  onDismiss?: () => void;
   /** Remember a folded guide in localStorage under this key, so someone not setting up today is not asked again on every
    *  visit. Give each place its own key (folding it on one page is not folding it everywhere). */
   rememberKey?: string;
   /** The steps' shared `name`. Defaults to a useId(), unique within one React root; pass one when two guides render in
    *  separate roots or separate static renders. */
   group?: string;
-  labels?: { progress?: string; notMeasured?: (n: number) => string };
+  labels?: SetupGuideLabels;
   className?: string;
 }) {
   const auto = useId();
   const name = group ?? `gb-setup${auto}`;
-  // Decided once (see the header): later renders keep whatever the person opened.
+  // Decided once (see the header): later renders keep whatever the person opened, and what was folded.
   const [first] = useState(() => open ?? steps.find((s) => s.state !== "done" && s.body)?.id);
+  const [folded] = useState(() => new Set(foldDone ? steps.filter((s) => s.state === "done").map((s) => s.id) : []));
   const guide = useRef<HTMLDetailsElement>(null);
+  const folds = collapsible && !onDismiss;
   useEffect(() => {
     const el = guide.current;
     if (!el || !rememberKey) return undefined;
@@ -66,13 +101,32 @@ export function SetupGuide({ title, description, steps, open, collapsible = true
     const onToggle = () => { try { localStorage.setItem(rememberKey, el.open ? "open" : "folded"); } catch { /* ignore */ } };
     el.addEventListener("toggle", onToggle);
     return () => el.removeEventListener("toggle", onToggle);
-  }, [rememberKey]);
+  }, [rememberKey, folds]);
 
   if (!steps.length) return null; // nothing to set up is no guide, not a "0/0" card
   const total = steps.length;
   const done = steps.filter((s) => s.state === "done").length;
   const unknown = steps.filter((s) => s.state === "unknown").length;
   const all = done === total;
+  // Folded = done when the guide first rendered AND still done (a step that came undone is back in the list).
+  const inFold = steps.filter((s) => folded.has(s.id) && s.state === "done");
+  const listed = steps.filter((s) => !inFold.includes(s));
+
+  const step = (s: SetupStep) => {
+    const state = s.state ?? "todo";
+    const row = (as: "summary" | "div") => React.createElement(as, { className: cx("ui-setup__row", as === "div" && "ui-setup__row--static") },
+      <span className="ui-setup__mark" aria-hidden="true">{MARK[state]}</span>,
+      <span className="ui-setup__label">{s.title}</span>,
+      as === "div" && s.action ? <span className="ui-setup__action">{s.action}</span> : null);
+    if (!s.body) return <div key={s.id} className={cx("ui-setup__step", s.className)} data-state={state}>{row("div")}</div>;
+    return (
+      <details key={s.id} className={cx("ui-setup__step", s.className)} name={name} open={s.id === first} data-state={state}>
+        {row("summary")}
+        <div className="ui-setup__body">{s.body}{s.action ? <div className="ui-setup__actions">{s.action}</div> : null}</div>
+      </details>
+    );
+  };
+
   const head = (
     <>
       <h2 className="ui-setup__title">{title}</h2>
@@ -85,27 +139,43 @@ export function SetupGuide({ title, description, steps, open, collapsible = true
   const inner = (
     <div className="ui-setup__inner">
       {description ? <p className="ui-setup__desc">{description}</p> : null}
-      <progress className={cx("ui-setup__bar", all && "ui-setup__bar--done")} value={done} max={total}
+      <progress className="ui-setup__bar" value={done} max={total}
         aria-label={labels?.progress ?? "Setup progress"}>{`${done}/${total}`}</progress>
       <div className="ui-setup__steps">
-        {steps.map((s) => {
-          const state = s.state ?? "todo";
-          const row = (as: "summary" | "div") => React.createElement(as, { className: cx("ui-setup__row", as === "div" && "ui-setup__row--static") },
-            <span className="ui-setup__mark" aria-hidden="true">{MARK[state]}</span>,
-            <span className="ui-setup__label">{s.title}</span>);
-          if (!s.body) return <div key={s.id} className="ui-setup__step" data-state={state}>{row("div")}</div>;
-          return (
-            <details key={s.id} className="ui-setup__step" name={name} open={s.id === first} data-state={state}>
-              {row("summary")}
-              <div className="ui-setup__body">{s.body}</div>
-            </details>
-          );
-        })}
+        {inFold.length ? (
+          // Not in the steps' `name` group: opening the fold must not shut the step that is open below it.
+          <details className="ui-setup__done">
+            <summary className="ui-setup__row">
+              <span className="ui-setup__mark" aria-hidden="true">{MARK.done}</span>
+              <span className="ui-setup__label">{labels?.completed?.(inFold.length) ?? `${inFold.length} completed`}</span>
+            </summary>
+            <div className="ui-setup__steps">{inFold.map(step)}</div>
+          </details>
+        ) : null}
+        {listed.map(step)}
       </div>
+      {optional?.length ? (
+        <div className="ui-setup__optional">
+          <h3 className="ui-setup__subtitle">{labels?.optional ?? "Optional"}</h3>
+          <div className="ui-setup__steps">{optional.map(step)}</div>
+        </div>
+      ) : null}
     </div>
   );
-  if (!collapsible) {
-    return <section className={cx("ui-card ui-setup", className)}><div className="ui-setup__head">{head}</div>{inner}</section>;
+  if (!folds) {
+    return (
+      <section className={cx("ui-card ui-setup", className)}>
+        <div className="ui-setup__head">
+          {head}
+          {onDismiss ? (
+            <button type="button" className="ui-setup__x" aria-label={labels?.dismiss ?? "Dismiss"} onClick={onDismiss}>
+              <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8" /></svg>
+            </button>
+          ) : null}
+        </div>
+        {inner}
+      </section>
+    );
   }
   return (
     <details className={cx("ui-card ui-setup", className)} open ref={guide}>