@gemboss/ui 0.45.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/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}>