@eifi1/ui-kit 0.48.2 → 0.50.0

package/src/shell/app-shell.tsx

@@ -50,6 +50,19 @@ export interface AppShellNavItem {
    *  from Large up (keksdose dev#613, which read `useTextSize()` in its layout to decide).
    *  Default `"normal"`: the short label at every size, as before. */
   shortLabelFrom?: TextSize;
+  /** 0.49: `shortLabel` is another word for the page, not a shortening of `label` —
+   *  keksdose's "Activity" for "Transactions". Without it a development build warns once
+   *  when `shortLabel` does not start with `label`'s first word (an abbreviation of that
+   *  word, "Trans." for "Transactions", counts), because a bar cell that names a page
+   *  differently from the sidebar, the title and the palette is a page the reader
+   *  looks for twice. */
+  shortLabelIsAlias?: boolean;
+  /** 0.49: which entries sit in the phone bar when they do not all fit
+   *  ({@link AppShellProps.mobileMaxItems}). Lower first: the entries with a priority take
+   *  the bar's cells in its order, then the rest in the list's order; the bar still shows
+   *  its entries in the list's order, and the others go under "More". Unset: the list's
+   *  order decides (as before). */
+  mobilePriority?: number;
   /** 0.31.0: leave this entry out of the MOBILE BOTTOM BAR; the sidebar keeps it.
    *  For an entry a phone reaches another way — the brand link to the start page —
    *  when one cell fewer is what keeps the others' labels whole (the bar divides its
@@ -65,8 +78,10 @@ export interface AppShellNavItem {
   dataTour?: string;
   /** Optional sub-items. When present, hovering (or focusing) the item opens a
    *  flyout to the right of the sidebar with a header (this item's label) and the
-   *  sub-items as icon + title links. Works collapsed or expanded; the mobile
-   *  bottom bar ignores sub-items and links to `to`. */
+   *  sub-items as icon + title links. Works collapsed or expanded. On the phone (0.49)
+   *  the bar's cell opens a sheet of them instead of linking to `to` — the sheet lists
+   *  `to` first as "Overview" when no sub-item is that page — and the pages of the group
+   *  the reader is in show as the row above the bar (`mobileSubNav`). */
   items?: AppShellSubItem[];
 }
 
@@ -128,22 +143,65 @@ export interface AppShellMoreLabels {
   more: string;
   /** The sheet's heading, and so its accessible name. */
   moreTitle: string;
+  /** 0.49: a parent entry's own page in the sheet its bar cell opens, above its pages,
+   *  when no page is that one — "Overview". */
+  overview: string;
 }
 
 // Defined in ./app-shell-labels, which holds no component code (0.34, KS U8).
 export { DEFAULT_APP_SHELL_MORE_LABELS };
 
 /**
- * The most entries the phone bar shows before the rest go under "More", per text size
- * (§10.7): every entry at Normal, four at Large, three at Extra large. A fifth of a
- * 360 px phone at 150 % is 48 px of Normal-sized room, and the cells hold a word each.
+ * The most cells the phone bar holds, "More" included, per text size (0.49 KIT-6; 0.32
+ * §10.7): five at Normal and Large, four at Extra large. Eight entries are four and
+ * "More" at Normal; a fifth of a 390 px phone holds one word of the bar's type, and a
+ * sixth no longer does once the type grows. A fifth of a 360 px phone at 150 % is 48 px
+ * of Normal-sized room.
+ */
+export const DEFAULT_MOBILE_MAX_ITEMS: Readonly<Record<TextSize, number>> = {
+  normal: 5,
+  large: 5,
+  xlarge: 4,
+};
+
+/**
+ * @deprecated 0.49 — use {@link DEFAULT_MOBILE_MAX_ITEMS} and `AppShell`'s
+ * `mobileMaxItems`: the bar is sized in cells, "More" included; removed in 0.51. This is
+ * the same default counted as entries before "More" (one fewer).
  */
 export const DEFAULT_MOBILE_BAR_MAX: Readonly<Record<TextSize, number>> = {
-  normal: Number.POSITIVE_INFINITY,
-  large: 4,
-  xlarge: 3,
+  normal: DEFAULT_MOBILE_MAX_ITEMS.normal - 1,
+  large: DEFAULT_MOBILE_MAX_ITEMS.large - 1,
+  xlarge: DEFAULT_MOBILE_MAX_ITEMS.xlarge - 1,
 };
 
+/**
+ * The phone bar's cells (0.49 KIT-6): every entry when there are at most `maxItems`,
+ * else `maxItems − 1` entries and a "More" cell for the rest. Which entries stay is
+ * `priority`'s call — lower first, entries without one after them in the list's order —
+ * and both halves keep the list's order. Never fewer than one entry beside More.
+ */
+export function pickMobileBar<T>(
+  entries: readonly T[],
+  maxItems: number,
+  priority?: (entry: T) => number | undefined,
+): { shown: T[]; hidden: T[] } {
+  const cells = Math.max(1, Math.floor(maxItems));
+  if (entries.length <= cells) return { shown: [...entries], hidden: [] };
+  const keep = Math.max(1, cells - 1);
+  const rank = (i: number) => priority?.(entries[i]!) ?? Number.POSITIVE_INFINITY;
+  const chosen = new Set(
+    entries
+      .map((_, i) => i)
+      .sort((a, b) => rank(a) - rank(b) || a - b)
+      .slice(0, keep),
+  );
+  return {
+    shown: entries.filter((_, i) => chosen.has(i)),
+    hidden: entries.filter((_, i) => !chosen.has(i)),
+  };
+}
+
 /**
  * Split the bar's entries into the cells shown and the ones under "More", in the app's
  * order (§10.7: the app puts its four most used first, or orders by role). One hidden
@@ -151,11 +209,87 @@ export const DEFAULT_MOBILE_BAR_MAX: Readonly<Record<TextSize, number>> = {
  * all: the cell count is the same either way, and a real entry beats a detour.
  */
 export function splitMobileBar<T>(entries: readonly T[], max: number): { shown: T[]; hidden: T[] } {
+  // Entries before More, as 0.32 counted them; {@link pickMobileBar} counts cells.
   const limit = Math.max(1, Math.floor(max));
   if (entries.length <= limit + 1) return { shown: [...entries], hidden: [] };
   return { shown: entries.slice(0, limit), hidden: entries.slice(limit) };
 }
 
+/** The bar's cell count at `size`: `mobileMaxItems`, else the deprecated `mobileBarMax`
+ *  read as cells (one more), else the default. */
+function mobileCells(
+  maxItems: AppShellProps["mobileMaxItems"],
+  barMax: AppShellProps["mobileBarMax"],
+  size: TextSize,
+): number {
+  if (maxItems !== undefined) {
+    return typeof maxItems === "number" ? maxItems : (maxItems[size] ?? DEFAULT_MOBILE_MAX_ITEMS[size]);
+  }
+  if (barMax !== undefined) {
+    const entries = typeof barMax === "number" ? barMax : barMax[size];
+    if (entries !== undefined) return entries + 1;
+  }
+  return DEFAULT_MOBILE_MAX_ITEMS[size];
+}
+
+/** The kit's dev switch, as `lib/logger.ts` reads it: a development build, never a
+ *  production one, never under vitest. Read per call so a test can switch it on. */
+function devWarnings(): boolean {
+  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
+}
+
+const warnedNav = new Set<string>();
+
+function warnNavOnce(key: string, message: string): void {
+  if (warnedNav.has(key)) return;
+  warnedNav.add(key);
+  console.warn(message);
+}
+
+/** The first word of a label, lower-cased: letters and digits up to the first other
+ *  character ("Import & Export" → "import", "Trans." → "trans"). */
+function firstWord(text: string): string {
+  return (text.trim().match(/^[\p{L}\p{N}]+/u)?.[0] ?? "").toLocaleLowerCase();
+}
+
+/** Whether `short` names `label`: its first word is `label`'s first word or an
+ *  abbreviation of it ("Trans." for "Transactions"), or the other way round. */
+function shortLabelNamesLabel(short: string, label: string): boolean {
+  const s = firstWord(short);
+  const l = firstWord(label);
+  return s === "" || l === "" || l.startsWith(s) || s.startsWith(l);
+}
+
+const TEXT_SIZE_WORDS: Record<TextSize, string> = { normal: "Normal", large: "Large", xlarge: "Extra large" };
+
+/** A development build's notes on `nav` (0.49 KIT-6): a `shortLabel` that is another word
+ *  than its `label` without `shortLabelIsAlias`, and the deprecated `mobileBarMax`. */
+function useNavDevWarnings(nav: AppShellNavItem[], deprecatedBarMax: boolean): void {
+  useEffect(() => {
+    if (!devWarnings()) return;
+    if (deprecatedBarMax) {
+      warnNavOnce(
+        "mobileBarMax",
+        "[ui-kit] AppShell mobileBarMax is deprecated: use mobileMaxItems, which counts the bar's cells with " +
+          '"More" (mobileBarMax={4} is mobileMaxItems={5}). Removed in 0.51.',
+      );
+    }
+    for (const item of nav) {
+      if (item.shortLabel === undefined || item.shortLabelIsAlias) continue;
+      if (shortLabelNamesLabel(item.shortLabel, item.label)) continue;
+      const from = item.shortLabelFrom ?? "normal";
+      const where = from === "normal" ? "at every text size" : `from ${TEXT_SIZE_WORDS[from]} text up`;
+      warnNavOnce(
+        `shortLabel|${item.to}|${item.shortLabel}|${item.label}`,
+        `[ui-kit] AppShell nav "${item.to}": shortLabel "${item.shortLabel}" does not start with ` +
+          `"${item.label.trim().split(/\s+/)[0]}", the first word of its label "${item.label}". The phone bar ` +
+          `shows it ${where}, so the page has another name there than in the sidebar and its title. ` +
+          "Shorten the label instead, or pass shortLabelIsAlias: true if the other word is meant.",
+      );
+    }
+  }, [nav, deprecatedBarMax]);
+}
+
 /**
  * Exported and `<div>`-shaped. This is the outermost element of every consuming app, so
  * there is nothing above it to hang an id, a landmark label or a `data-tour` anchor on —
@@ -222,17 +356,23 @@ export interface AppShellProps extends ComponentPropsWithoutRef<"div"> {
    */
   mobileSubNavLayout?: "wrap" | "scroll";
   /**
-   * The most entries the phone bar shows; the rest move into a "More" cell that opens a
-   * sheet listing them, each group with its pages (0.32, docs/text-size-harmonization.md
-   * §4, §10.7). The bar takes `nav` in the app's order — after `mobileHidden` — so the
-   * app puts its most used entries first (or orders by role: kastlan's manager and
-   * accountant see different firsts).
+   * The most cells the phone bar holds, "More" included (0.49 KIT-6). When `nav` (after
+   * `mobileHidden`) has more entries, the bar keeps `mobileMaxItems − 1` of them and a
+   * last "More" cell opens a sheet with the rest, each group with its pages. Which
+   * entries stay is the items' `mobilePriority`, else the list's order (so the app puts
+   * its most used entries first, or orders by role: kastlan's manager and accountant see
+   * different firsts).
    *
-   * Default {@link DEFAULT_MOBILE_BAR_MAX}: unlimited at Normal, 4 at Large, 3 at Extra
-   * large, because the cells' words grow with the text and the phone does not. A number
-   * replaces the default at every size; `{ large: 5 }` replaces it at one size only.
-   * Never fewer than one entry; and one entry over the limit shows in full rather than
-   * behind a More that would take the same cell.
+   * Default {@link DEFAULT_MOBILE_MAX_ITEMS}: 5 at Normal and Large, 4 at Extra large —
+   * eight entries are four and "More". A number replaces the default at every size;
+   * `{ xlarge: 5 }` replaces it at one size only. Never fewer than one entry beside More.
+   */
+  mobileMaxItems?: number | Partial<Record<TextSize, number>>;
+  /**
+   * @deprecated 0.49 — use `mobileMaxItems`, which counts the bar's cells, "More"
+   * included: `mobileBarMax={4}` is `mobileMaxItems={5}`; removed in 0.51. Read as that
+   * (one more, per size), with a development warning; ignored when `mobileMaxItems` is
+   * given.
    */
   mobileBarMax?: number | Partial<Record<TextSize, number>>;
   /** The More cell's words over the provider's `appShellMore`. */
@@ -357,6 +497,7 @@ export function AppShell({
   subNav = "flyout",
   mobileSubNav = true,
   mobileSubNavLayout: mobileSubNavLayoutProp,
+  mobileMaxItems,
   mobileBarMax,
   moreLabels,
   toggleGroupLabel,
@@ -370,15 +511,14 @@ export function AppShell({
   const large = textSize !== "normal";
   const mobileSubNavLayout = mobileSubNavLayoutProp ?? (large ? "scroll" : "wrap");
   // The bottom bar's cells: every entry the phone does not reach another way, up to the
-  // text size's limit; the rest go under More (§10.7).
-  const barMax =
-    typeof mobileBarMax === "number"
-      ? mobileBarMax
-      : (mobileBarMax?.[textSize] ?? DEFAULT_MOBILE_BAR_MAX[textSize]);
-  const { shown: barNav, hidden: moreNav } = splitMobileBar(
+  // text size's limit, More included; the rest go under More (§10.7, KIT-6).
+  const maxItems = mobileCells(mobileMaxItems, mobileBarMax, textSize);
+  const { shown: barNav, hidden: moreNav } = pickMobileBar(
     nav.filter((item) => !item.mobileHidden),
-    barMax,
+    maxItems,
+    (item) => item.mobilePriority,
   );
+  useNavDevWarnings(nav, mobileBarMax !== undefined && mobileMaxItems === undefined);
   // An embedded shell sharing the default key would overwrite the outer app's sidebar
   // preference with its own — so it persists only when given a key of its own.
   const collapseStorageKey =
@@ -552,10 +692,12 @@ export function AppShell({
             {/* Below `md` the bottom room is the nav plus the larger of 1.5rem and what the
                 floating launchers take above it (`--app-float-clearance`, published by
                 every kit FAB, FloatingPanel and FloatingActionGroup while mounted — keksdose
-                dev#612: the last row ended under the help launcher). */}
+                dev#612: the last row ended under the help launcher). From `md` up, where
+                there is no nav, the launchers' room alone (0.49 KIT-11): the last row
+                scrolls clear of a corner button there too. */}
             <main
               className={cn(
-                "relative flex-1 max-w-full overflow-x-clip pb-[calc(var(--app-nav-h,4rem)+max(1.5rem,var(--app-float-clearance,0px)))] md:pb-0 md:min-h-0 md:overflow-y-auto md:[scrollbar-gutter:stable_both-edges]",
+                "relative flex-1 max-w-full overflow-x-clip pb-[calc(var(--app-nav-h,4rem)+max(1.5rem,var(--app-float-clearance,0px)))] md:pb-[var(--app-float-clearance,0px)] md:min-h-0 md:overflow-y-auto md:[scrollbar-gutter:stable_both-edges]",
                 // The list page's fill (0.40, docs/page-layout-harmonization.md §1.3): while
                 // a `fillHeight` DataTable is inside, a flex column — a banner above the
                 // page keeps its own height and the page (a `FillHeight`) takes the rest,
@@ -597,9 +739,13 @@ export function AppShell({
             className="grid"
             style={{ gridTemplateColumns: `repeat(${barNav.length + (moreNav.length ? 1 : 0)}, minmax(0, 1fr))` }}
           >
-            {barNav.map((item) => (
-              <MobileNavItem key={item.to} item={item} />
-            ))}
+            {barNav.map((item) =>
+              item.items?.length ? (
+                <MobileGroupCell key={item.to} item={item} labels={moreLabels} />
+              ) : (
+                <MobileNavItem key={item.to} item={item} />
+              ),
+            )}
             {moreNav.length > 0 && <MobileMoreCell hidden={moreNav} labels={moreLabels} />}
           </nav>
         </div>
@@ -779,11 +925,7 @@ function MobileCellLabel({ children }: { children: ReactNode }) {
  *  nothing marked on every sub-page (the same defect the sidebar had). */
 function MobileNavItem({ item }: { item: AppShellNavItem }) {
   const subActive = useSubItemActive(item);
-  const { size } = useTextSize();
-  const short =
-    item.shortLabel !== undefined && TEXT_SIZES.indexOf(size) >= TEXT_SIZES.indexOf(item.shortLabelFrom ?? "normal")
-      ? item.shortLabel
-      : undefined;
+  const label = useCellLabel(item);
   return (
     <NavLink
       to={item.to}
@@ -794,11 +936,122 @@ function MobileNavItem({ item }: { item: AppShellNavItem }) {
       <span className="relative">
         <item.icon className="size-5" />
       </span>
-      <MobileCellLabel>{short ?? item.label}</MobileCellLabel>
+      <MobileCellLabel>{label}</MobileCellLabel>
+    </NavLink>
+  );
+}
+
+/** The bar cell's label: `shortLabel` from its text size up (0.48), else `label`. */
+function useCellLabel(item: AppShellNavItem): string {
+  const { size } = useTextSize();
+  return item.shortLabel !== undefined &&
+    TEXT_SIZES.indexOf(size) >= TEXT_SIZES.indexOf(item.shortLabelFrom ?? "normal")
+    ? item.shortLabel
+    : item.label;
+}
+
+/** A link in one of the phone's sheets — an entry (`level="entry"`) or a page under one. */
+function SheetLink({
+  to,
+  end,
+  icon: Icon,
+  label,
+  onClick,
+  level,
+}: {
+  to: string;
+  end?: boolean;
+  icon: LucideIcon;
+  label: string;
+  onClick: () => void;
+  level: "entry" | "page";
+}) {
+  return (
+    <NavLink
+      to={to}
+      end={end ?? true}
+      onClick={onClick}
+      className={({ isActive }) =>
+        cn(
+          level === "entry"
+            ? "flex min-h-11 items-center gap-3 rounded-md px-3 py-2 text-sm transition-colors"
+            : "flex min-h-11 items-center gap-2.5 rounded-md px-2.5 py-1.5 text-sm transition-colors",
+          isActive ? "bg-inverse text-inverse" : level === "entry" ? "text-primary hover:bg-hover" : "text-secondary hover:bg-hover",
+        )
+      }
+    >
+      <Icon aria-hidden className={level === "entry" ? "size-5 shrink-0" : "size-4 shrink-0 opacity-70"} />
+      <span className="min-w-0 break-words leading-snug">{label}</span>
     </NavLink>
   );
 }
 
+/**
+ * A bar cell for an entry with pages (0.49 KIT-6): on a phone the entry opens a sheet of
+ * its pages instead of linking to its own `to` — a tap on "Reports" used to land on the
+ * overview with the pages one more step away, in the row above the bar, which only
+ * appears once you are in the group. The sheet lists the entry's own page first, as
+ * "Overview", when none of the pages is that page. Marked while the entry's page or one
+ * of its pages is current, as the link was.
+ *
+ * Tours find the entry by `a[href]` or its `dataTour`, as on the More cell: an inert,
+ * pointer-transparent anchor over the button carries them (see {@link MobileMoreCell}).
+ */
+function MobileGroupCell({
+  item,
+  labels: labelsProp,
+}: {
+  item: AppShellNavItem;
+  labels?: LabelOverride<AppShellMoreLabels>;
+}) {
+  const labels: AppShellMoreLabels = useKitLabels("appShellMore", DEFAULT_APP_SHELL_MORE_LABELS, labelsProp);
+  const { pathname } = useLocation();
+  const [open, setOpen] = useState(false);
+  const label = useCellLabel(item);
+  const active = entryIsCurrent(item, pathname);
+  const close = () => setOpen(false);
+  const pages = item.items ?? [];
+  const ownPageListed = pages.some((sub) => sub.to === item.to);
+  return (
+    <div data-slot="app-shell-group" className="relative min-w-0">
+      <button
+        type="button"
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        // The cell may show a shortLabel; the button's name is the entry's.
+        aria-label={label === item.label ? undefined : item.label}
+        onClick={() => setOpen(true)}
+        className={mobileCellClass(active)}
+      >
+        <span className="relative">
+          <item.icon aria-hidden className="size-5" />
+        </span>
+        <MobileCellLabel>{label}</MobileCellLabel>
+      </button>
+      <TourAnchor to={item.to} dataTour={item.dataTour} />
+      {pages
+        .filter((sub) => sub.to !== item.to)
+        .map((sub) => (
+          <TourAnchor key={sub.to} to={sub.to} />
+        ))}
+      <DialogFrame open={open} onClose={close} title={item.label} closeButton bodyClassName="space-y-1">
+        <ul className="space-y-1">
+          {!ownPageListed && (
+            <li>
+              <SheetLink to={item.to} end={item.end} icon={item.icon} label={labels.overview} onClick={close} level="entry" />
+            </li>
+          )}
+          {pages.map((sub) => (
+            <li key={sub.to}>
+              <SheetLink to={sub.to} end={sub.end} icon={sub.icon} label={sub.label} onClick={close} level="entry" />
+            </li>
+          ))}
+        </ul>
+      </DialogFrame>
+    </div>
+  );
+}
+
 /** Whether the current route is `item`'s page or one of its pages. */
 function entryIsCurrent(item: AppShellNavItem, pathname: string): boolean {
   return (
@@ -874,42 +1127,12 @@ function MobileMoreCell({
         <ul className="space-y-1">
           {hidden.map((item) => (
             <li key={item.to}>
-              <NavLink
-                to={item.to}
-                end={item.end ?? true}
-                onClick={close}
-                className={({ isActive }) =>
-                  cn(
-                    "flex min-h-11 items-center gap-3 rounded-md px-3 py-2 text-sm transition-colors",
-                    isActive
-                      ? "bg-inverse text-inverse"
-                      : "text-primary hover:bg-hover",
-                  )
-                }
-              >
-                <item.icon aria-hidden className="size-5 shrink-0" />
-                <span className="min-w-0 break-words leading-snug">{item.label}</span>
-              </NavLink>
+              <SheetLink to={item.to} end={item.end} icon={item.icon} label={item.label} onClick={close} level="entry" />
               {!!item.items?.length && (
                 <ul aria-label={item.label} className="ms-[1.3rem] mt-0.5 space-y-0.5 border-s border-subtle ps-2">
                   {item.items.map((sub) => (
                     <li key={sub.to}>
-                      <NavLink
-                        to={sub.to}
-                        end={sub.end ?? true}
-                        onClick={close}
-                        className={({ isActive }) =>
-                          cn(
-                            "flex min-h-11 items-center gap-2.5 rounded-md px-2.5 py-1.5 text-sm transition-colors",
-                            isActive
-                              ? "bg-inverse text-inverse"
-                              : "text-secondary hover:bg-hover",
-                          )
-                        }
-                      >
-                        <sub.icon aria-hidden className="size-4 shrink-0 opacity-70" />
-                        <span className="min-w-0 break-words leading-snug">{sub.label}</span>
-                      </NavLink>
+                      <SheetLink to={sub.to} end={sub.end} icon={sub.icon} label={sub.label} onClick={close} level="page" />
                     </li>
                   ))}
                 </ul>

package/src/shell/language-code.ts

@@ -0,0 +1,5 @@
+/** "de-CH" → "DE": the language subtag in capitals, the code the language triggers show
+ *  (0.49 KIT-10). Internal. */
+export function languageCodeLabel(code: string): string {
+  return code.split(/[-_]/)[0].toUpperCase();
+}

package/src/shell/topbar-controls.tsx

@@ -5,6 +5,7 @@ import type { PalettePreset } from "../theme/palette-presets";
 import type { ThemeMode } from "../theme/theme-store";
 import { Tooltip } from "../components/tooltip";
 import { DEFAULT_TOP_BAR_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { languageCodeLabel } from "./language-code";
 
 /** Shared square icon-button styling for top-bar triggers, so app-owned controls
  *  (account/feedback menus) line up with the shared ones. */
@@ -179,33 +180,51 @@ export interface LanguageOption {
   country: string;
 }
 
+/** What {@link LanguageMenu}'s trigger shows of the active language (0.49 KIT-10). */
+export type LanguageMenuTrigger = "flag+code" | "code" | "flag";
+
+/** The trigger with a code: as tall as the others, as wide as flag and code need. */
+const LANGUAGE_TRIGGER_WIDE_CLASS = TOPBAR_TRIGGER_CLASS.replace("size-9", "h-9 min-w-9 gap-1.5 px-2");
+
+const FLAG_CLASS =
+  "inline-block h-[0.9375rem] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]";
+
 /** Language switcher: a hover menu of options with flags and a check on the
  *  active one. Controlled — the app owns the current code and change handler.
  *
- *  The trigger is the *active* option's flag, not an icon: lucide's `Languages`
+ *  The trigger is the *active* option's flag and its language code in capitals
+ *  ("DE", "FR", "IT"; `trigger`, 0.49 KIT-10), not an icon: lucide's `Languages`
  *  glyph (文A) is the same mark Chrome puts in the omnibox for "translate this
  *  page", so it read as machine-translation rather than "pick the UI language"
- *  (Keksdose feedback #121). The flag also shows which language is currently on,
- *  which no icon can, and costs the same width on a crowded mobile bar. A globe
- *  covers the case where `current` matches nothing in `options`. */
+ *  (Keksdose feedback #121). A flag alone could not tell de-CH, fr-CH and it-CH
+ *  apart — one Swiss flag each — so the code is beside it. It is named "Choose
+ *  language, current: Deutsch" (`topBar.languageCurrent`). A globe covers the
+ *  case where `current` matches nothing in `options`. */
 export function LanguageMenu({
   options,
   current,
   onChange,
   "aria-label": ariaLabel,
   heading,
+  trigger = "flag+code",
 }: {
   options: LanguageOption[];
   current: string | undefined;
   onChange: (code: string) => void;
-  /** Default: `topBar.language` from the {@link UiKitProvider}, else English. */
+  /** The menu's name, and the trigger's as given. Default: the menu `topBar.language`,
+   *  the trigger `topBar.languageCurrent(<the active label>)`, from the
+   *  {@link UiKitProvider}, else English. */
   "aria-label"?: string;
   /** Optional small heading row above the list — as on `TopBarActionMenu`,
    *  `OptionSwitcherMenu` and `PaletteMenu`. */
   heading?: string;
+  /** What the trigger shows: `"flag+code"` (default), `"code"` or `"flag"`. */
+  trigger?: LanguageMenuTrigger;
 }) {
   const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { language: ariaLabel });
   const active = options.find((o) => o.code === current);
+  const triggerName = ariaLabel ?? (active ? labels.languageCurrent(active.label) : labels.language);
+  const showsCode = active !== undefined && trigger !== "flag";
   return (
     <HoverMenu
       aria-label={labels.language}
@@ -214,14 +233,18 @@ export function LanguageMenu({
           <button
             type="button"
             onClick={toggle}
-            aria-label={labels.language}
-            className={TOPBAR_TRIGGER_CLASS}
+            aria-label={triggerName}
+            className={showsCode ? LANGUAGE_TRIGGER_WIDE_CLASS : TOPBAR_TRIGGER_CLASS}
           >
             {active ? (
-              <span
-                aria-hidden
-                className={`fi fi-${active.country} inline-block h-[0.9375rem] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]`}
-              />
+              <>
+                {trigger !== "code" && <span aria-hidden className={`fi fi-${active.country} ${FLAG_CLASS}`} />}
+                {showsCode && (
+                  <span aria-hidden className="text-xs font-semibold tabular-nums tracking-wide">
+                    {languageCodeLabel(active.code)}
+                  </span>
+                )}
+              </>
             ) : (
               <Globe className="size-5" />
             )}
@@ -245,10 +268,7 @@ export function LanguageMenu({
                   className={TOPBAR_MENU_ITEM_CLASS}
                 >
                   <span className="flex items-center gap-2">
-                    <span
-                      aria-hidden
-                      className={`fi fi-${lang.country} inline-block h-[0.9375rem] w-5 shrink-0 rounded-sm shadow-[0_0_0_1px_rgba(0,0,0,0.08)]`}
-                    />
+                    <span aria-hidden className={`fi fi-${lang.country} ${FLAG_CLASS}`} />
                     {lang.label}
                   </span>
                   {isActive && <Check className="size-4 text-secondary" />}

package/src/testing/css-variables.generated.ts

@@ -3,16 +3,16 @@
 // fails while this is stale.
 
 /** Every custom property tokens.css declares, `@theme inline` names and `--app-nav-h`
- *  left out (100 names). */
+ *  left out (102 names). */
 export const KIT_NAMES =
   "--bg-active --bg-hover --bg-inverse --bg-page --bg-surface --bg-surface-2 --border " +
   "--border-strong --brand --brand-bg --brand-bg-hover --brand-contrast --brand-hover --brand-muted " +
   "--breakpoint-3xl --chart-1 --chart-2 --chart-3 --chart-4 --chart-5 --chart-6 --chart-7 --chart-8 " +
-  "--chart-9 --danger --danger-bg --danger-border --danger-border-strong --danger-contrast " +
-  "--danger-hover --flyout-from --focus-ring-width --hue-blue --hue-blue-bg --hue-blue-border " +
-  "--hue-blue-contrast --hue-indigo --hue-indigo-bg --hue-indigo-border --hue-indigo-contrast " +
-  "--hue-orange --hue-orange-bg --hue-orange-border --hue-orange-contrast --hue-purple " +
-  "--hue-purple-bg --hue-purple-border --hue-purple-contrast --hue-teal --hue-teal-bg " +
+  "--chart-9 --chart-ink --chart-muted --danger --danger-bg --danger-border --danger-border-strong " +
+  "--danger-contrast --danger-hover --flyout-from --focus-ring-width --hue-blue --hue-blue-bg " +
+  "--hue-blue-border --hue-blue-contrast --hue-indigo --hue-indigo-bg --hue-indigo-border " +
+  "--hue-indigo-contrast --hue-orange --hue-orange-bg --hue-orange-border --hue-orange-contrast " +
+  "--hue-purple --hue-purple-bg --hue-purple-border --hue-purple-contrast --hue-teal --hue-teal-bg " +
   "--hue-teal-border --hue-teal-contrast --info --info-bg --info-border --info-contrast --media-ink " +
   "--media-scrim --media-scrim-hover --money-expense --money-expense-contrast --money-income " +
   "--money-income-contrast --money-net --money-net-contrast --money-neutral " +

package/src/testing/react.ts

@@ -0,0 +1,59 @@
+import { fireEvent, screen, within } from "@testing-library/react";
+
+// `@eifi1/ui-kit/testing/react` (0.50) — helpers that drive the kit's components through
+// Testing Library, from an app's own test suite.
+//
+// A sibling of `@eifi1/ui-kit/testing`, not part of it: that entry is pure (it reaches no
+// package, so it runs under node or jsdom alike), and this one needs
+// `@testing-library/react`, an optional peer only a test suite installs. Neither is part of
+// the barrel, so an app's production bundle never carries either.
+
+/** The words of the row's "⋯" button, when the app's tests render translated kit labels. */
+export interface RowMenuLabels {
+  /** The button's name on a row with no `name`. Default "Actions". */
+  actions?: string;
+  /** The button's name given the row's. Default `Actions for ${name}`. */
+  actionsFor?: (name: string) => string;
+}
+
+// The kit's English defaults (DEFAULT_ROW_ACTIONS_LABELS, and the user roster's), written
+// out rather than imported: the label module's type import would walk this entry into the
+// components. src/testing/__tests__/react.test.tsx holds them equal.
+const ACTIONS = "Actions";
+const ACTIONS_FOR = (name: string) => `Actions for ${name}`;
+
+/**
+ * Open a row's "⋯" menu and find one of its actions — the entry, unclicked, so a test can
+ * check it (locked, described) before it clicks it.
+ *
+ * `row` is the row's name as the app gave it to `RowActions` / `rowActionsColumn` /
+ * `UserRoster` ("Actions for <row>"); `undefined` takes the FIRST "⋯" on the page, named
+ * or not. Since 0.49 (KIT-12) a `tone: "danger"` action lives in that menu rather than as
+ * an icon in the row, and at Large text every action does.
+ *
+ * The entries are BUTTONS in a dialog popover named like the "⋯" button — not `menuitem`s:
+ * `getByRole("menuitem")` finds nothing there. A danger action asks for confirmation once
+ * clicked (an `alertdialog`), unless the app turned that off.
+ *
+ * @example
+ *   fireEvent.click(await rowMenuAction("Ada Example", "Delete"));
+ *   fireEvent.click(await screen.findByRole("button", { name: "Confirm" }));
+ */
+export async function rowMenuAction(
+  row: string | undefined,
+  action: string | RegExp,
+  labels: RowMenuLabels = {},
+): Promise<HTMLElement> {
+  const actions = labels.actions ?? ACTIONS;
+  const actionsFor = labels.actionsFor ?? ACTIONS_FOR;
+  // Any row's name: the words around the name, whatever the language puts first.
+  const [before, after] = actionsFor("\u0000").split("\u0000");
+  const anyRow = (name: string) =>
+    name === actions ||
+    (name.length > before.length + after.length && name.startsWith(before) && name.endsWith(after));
+  const trigger = (await screen.findAllByRole("button", { name: row === undefined ? anyRow : actionsFor(row) }))[0];
+  fireEvent.click(trigger);
+  const title = trigger.getAttribute("aria-label") ?? trigger.textContent ?? "";
+  const menu = await screen.findByRole("dialog", { name: title });
+  return within(menu).getByRole("button", { name: action });
+}