@eifi1/ui-kit 0.41.0 → 0.42.0

package/src/shell/topbar-action-menu.tsx

@@ -206,11 +206,13 @@ export function TopBarActionMenu({
   heading,
   header,
   entries,
+  leading,
   children,
   footer,
   footerLabel,
   align,
   panelClassName,
+  triggerAttributes,
 }: {
   /** The trigger's face for the usual icon button. Ignored when `trigger` is given. */
   icon?: ReactNode;
@@ -260,6 +262,13 @@ export function TopBarActionMenu({
    * `close` shuts the menu.
    */
   children?: (close: () => void) => ReactNode;
+  /**
+   * Rows like {@link children}, but BEFORE `entries`, under the header — the account
+   * menu's `AccountMenuLanguage`, which goes first after the app's context rows (§6.5)
+   * in a menu whose other rows are all entries (kastlan, build review B1). Render `<li>`s;
+   * `close` shuts the menu.
+   */
+  leading?: (close: () => void) => ReactNode;
   /**
    * Free content below the rows, behind a rule — the legal links. Its links and
    * buttons are NOT menu rows: the arrow keys skip them and Tab reaches them. Pass a
@@ -272,6 +281,9 @@ export function TopBarActionMenu({
    *  direction (see `HoverMenu`, whose type this is). Default `end`. */
   align?: HoverMenuProps["align"];
   panelClassName?: string;
+  /** `data-*` attributes for the trigger itself — a tour's anchor (`data-tour`), a test
+   *  hook. The parts built on this menu (`TourMenu`) pass theirs through here. */
+  triggerAttributes?: { [key: `data-${string}`]: string | number | boolean | undefined };
 }) {
   // Names the groups' headings for `aria-labelledby`. Positional rather than from the
   // entry's `key`, which is the caller's text and may hold a space — and a space in
@@ -286,11 +298,11 @@ export function TopBarActionMenu({
         // kit's button. Same classes and face either way.
         const control = (className: string, children: ReactNode, label?: string) =>
           href ? (
-            <Link to={href} onClick={close} aria-label={label} className={className}>
+            <Link {...triggerAttributes} to={href} onClick={close} aria-label={label} className={className}>
               {children}
             </Link>
           ) : (
-            <button type="button" onClick={toggle} aria-label={label} className={className}>
+            <button {...triggerAttributes} type="button" onClick={toggle} aria-label={label} className={className}>
               {children}
             </button>
           );
@@ -380,6 +392,7 @@ export function TopBarActionMenu({
                 {heading}
               </li>
             )}
+            {leading?.(close)}
             {toBlocks(entries).map((block, i, blocks) => {
               if (block.kind === "loose") {
                 const entry = block.entry;

package/src/shell/topbar-controls.tsx

@@ -25,16 +25,30 @@ function MenuHeading({ children }: { children: string }) {
   );
 }
 
-/** Sun/Moon toggle for the light/dark theme. Controlled: the app owns the mode. */
+/**
+ * Sun/Moon toggle for the light/dark theme. Controlled: the app owns the mode, and the
+ * toggle keeps no storage key of its own (docs/top-bar-harmonization.md §6.4).
+ *
+ * `mode` is the theme ON SCREEN — the resolved one, so with a "system" preference it is
+ * whatever the OS gives. A tap asks for the opposite of that: `onChange("light")` while
+ * dark is shown, `onChange("dark")` while light is. The app writes it as its theme
+ * preference (an explicit light or dark), where Settings → Appearance keeps the three-way
+ * choice. `onToggle` is the older way to hear the tap, without the next mode; both fire.
+ */
 export function ThemeToggle({
   mode,
   onToggle,
+  onChange,
   "aria-label": ariaLabel,
   title,
   className,
 }: {
+  /** The resolved light/dark on screen (`useThemeStore`'s `mode`, not its preference). */
   mode: ThemeMode;
-  onToggle: () => void;
+  /** Hears a tap. Kept for 0.41's callers; `onChange` says what to switch to. */
+  onToggle?: () => void;
+  /** 0.42: the mode to switch to — always the opposite of `mode`. */
+  onChange?: (next: ThemeMode) => void;
   /** Default: `topBar.theme` from the {@link UiKitProvider}, else English. */
   "aria-label"?: string;
   title?: string;
@@ -48,7 +62,10 @@ export function ThemeToggle({
     <Tooltip label={title} portal>
       <button
         type="button"
-        onClick={onToggle}
+        onClick={() => {
+          onChange?.(mode === "dark" ? "light" : "dark");
+          onToggle?.();
+        }}
         aria-label={labels.theme}
         className={cn(TOPBAR_TRIGGER_CLASS, className)}
       >

package/src/shell/tour-menu.tsx

@@ -0,0 +1,144 @@
+import type { ReactNode } from "react";
+import { useLocation } from "react-router";
+import { Check, Compass } from "lucide-react";
+import { Chip } from "../components/chip";
+import type { LabelOverride } from "../i18n/kit-labels";
+import { TopBarActionMenu, type TopBarMenuEntry } from "./topbar-action-menu";
+import { useTopBarPartsLabels, type TourMenuLabels } from "./top-bar-parts-labels";
+
+/**
+ * One tour as the menu needs it — data, so the menu depends on no app's tour registry.
+ * The kit's tour engine (`TourProvider`) runs steps and keeps none; which tours exist,
+ * which are new and which are taken is the app's (keksdose: `useTours`, `useIsNewTour`,
+ * its progress store).
+ */
+export interface TourMenuTour {
+  id: string;
+  title: ReactNode;
+  /** The page the tour starts on. Its first segment decides "On this page":
+   *  "/reports/spending" belongs to "/reports". */
+  route?: string;
+  /** Shipped after this account was opened and not yet taken: a NEW chip on the row,
+   *  and the dot on the compass. */
+  isNew?: boolean;
+  /** Taken: a ✓ on the row. */
+  completed?: boolean;
+  /** The row's icon, drawn at 16px. */
+  icon?: ReactNode;
+  /** When the tour shipped, as an ISO date: the newest of the new come first. */
+  since?: string;
+}
+
+export interface TourMenuProps {
+  tours: readonly TourMenuTour[];
+  /** Start a tour — `useTour().start(steps, { id })` with the app's steps. */
+  onLaunch: (id: string) => void;
+  /**
+   * The app's tours page (keksdose `/tours`). With it the compass is a LINK there plus a
+   * hover menu, and the menu ends in "All tours…". Without it (§6.7, Kurvenschmiede) the
+   * compass opens the menu, and the tours on neither list follow below a rule.
+   */
+  href?: string;
+  /** The open page's path. Default: the router's location. */
+  pathname?: string;
+  /** How many new tours the menu offers beyond the page's own. Default 3. */
+  maxNew?: number;
+  /**
+   * `"all"`: list every tour — this page's and the new ones first, then the rest below a
+   * rule — with `href` too, before "All tours…". For an app whose tours carry no `route`,
+   * `isNew` or `since` (kastlan, build review A1), where the short list would be empty
+   * off the tours' page. Default `"short"`: with `href`, only this page's and the new.
+   */
+  list?: "short" | "all";
+  /** Prop > `<UiKitProvider labels={{ topBarParts: { tours } }}>` > English. */
+  labels?: LabelOverride<TourMenuLabels>;
+  /** `data-*` attributes go on the compass — a tour's anchor (`data-tour="tours"`). */
+  [key: `data-${string}`]: string | number | boolean | undefined;
+}
+
+/** A path's first segment — "/reports/spending?g=month" → "/reports". */
+const pageOf = (path: string) => `/${path.split(/[?#]/)[0].split("/")[1] ?? ""}`;
+
+const isFresh = (t: TourMenuTour) => !!t.isNew && !t.completed;
+
+/**
+ * The top bar's guided-tours control (docs/top-bar-harmonization.md §2.4, §6.7), lifted
+ * from keksdose's: the lucide `Compass`, with a NEW dot while a tour is new, and a short
+ * list — the tours that start on this page, up to three new ones (newest first), a rule,
+ * and "All tours…". A taken tour's row carries a ✓, a new one a NEW chip.
+ */
+export function TourMenu({
+  tours,
+  onLaunch,
+  href,
+  pathname: pathnameProp,
+  maxNew = 3,
+  list = "short",
+  labels: labelsProp,
+  ...attributes
+}: TourMenuProps) {
+  const words = useTopBarPartsLabels(labelsProp ? { tours: labelsProp } : undefined).tours;
+  const location = useLocation();
+  const here = pageOf(pathnameProp ?? location.pathname);
+
+  const forThisPage = tours.filter((t) => t.route !== undefined && pageOf(t.route) === here);
+  const fresh = tours.filter(isFresh);
+  // ISO dates sort as text; a stable sort keeps one day's tours in the app's order.
+  const newRows = fresh
+    .filter((t) => !forThisPage.includes(t))
+    .sort((a, b) => (b.since ?? "").localeCompare(a.since ?? ""))
+    .slice(0, maxNew);
+  const rest = href && list !== "all" ? [] : tours.filter((t) => !forThisPage.includes(t) && !newRows.includes(t));
+
+  if (tours.length === 0 && !href) return null;
+
+  const entryFor = (tour: TourMenuTour): TopBarMenuEntry => ({
+    key: tour.id,
+    icon: tour.icon,
+    label: tour.title,
+    trailing: tour.completed ? (
+      <>
+        <Check aria-hidden className="size-4 text-success" />
+        <span className="sr-only">{words.completed}</span>
+      </>
+    ) : tour.isNew ? (
+      // The kit's inert Chip: a plain <span>, no role of its own inside the menu.
+      <Chip size="sm" tone="brand" caps className="px-1.5">
+        {words.badgeNew}
+      </Chip>
+    ) : undefined,
+    onSelect: () => onLaunch(tour.id),
+  });
+
+  const blocks = [
+    { key: "this-page", label: words.thisPage, tours: forThisPage },
+    { key: "new", label: words.newTours, tours: newRows },
+  ].filter((b) => b.tours.length > 0);
+  const tail: TopBarMenuEntry[] = [
+    ...rest.map(entryFor),
+    ...(href
+      ? [{ kind: "link" as const, key: "all-tours", icon: <Compass className="size-4" />, label: words.allTours, to: href }]
+      : []),
+  ];
+
+  const entries: TopBarMenuEntry[] = [
+    ...blocks.flatMap((b): TopBarMenuEntry[] => [
+      { kind: "heading", key: `head-${b.key}`, label: b.label },
+      ...b.tours.map(entryFor),
+    ]),
+    ...(blocks.length > 0 && tail.length > 0 ? [{ kind: "divider" as const, key: "sep-all" }] : []),
+    ...tail,
+  ];
+
+  return (
+    <TopBarActionMenu
+      icon={<Compass className="size-5" />}
+      iconBadge={fresh.length > 0 ? { label: words.newDot, tone: "brand" } : null}
+      aria-label={words.menu}
+      href={href}
+      panelClassName="w-72 max-h-[70vh] overflow-y-auto"
+      entries={entries}
+      triggerAttributes={Object.fromEntries(Object.entries(attributes).filter(([k]) => k.startsWith("data-")))}
+    />
+  );
+}

package/src/shell.ts

@@ -13,6 +13,10 @@ export * from "./shell/auth-layout";
 // 0.40.0: the list page's fill (docs/page-layout-harmonization.md §1.3).
 export { FillHeight, FILL_HEIGHT_CLASS } from "./shell/fill-height";
 export type { FillHeightProps } from "./shell/fill-height";
+// 0.42.0: the account menu's "Administration" row, as an entry and as a HoverMenu row
+// (docs/admin-harmonization.md §2.1, §6.6).
+export { adminMenuEntry, AdminMenuRow } from "./shell/admin-menu";
+export type { AdminMenuEntryOptions, AdminMenuRowProps } from "./shell/admin-menu";
 // 0.31.0: the settings and admin pages' shell (docs/settings-harmonization.md §3, §5).
 export { SettingsLayout, SETTINGS_SEARCH_THRESHOLD } from "./settings/settings-layout";
 export type { SettingsLayoutProps, SettingsLayoutWidth, SettingsDocumentTitleParts } from "./settings/settings-layout";
@@ -64,3 +68,23 @@ export type {
 } from "./landing/routing";
 export { PublicHeader } from "./landing/public-header";
 export type { PublicHeaderProps, PublicHeaderBrand } from "./landing/public-header";
+// 0.42.0: the top bar's shared parts (docs/top-bar-harmonization.md §3.1) — the slots in
+// §2.1's order, the account menu's language sub-list, the tours menu, the sync status, the
+// local-dev switchers, and their words.
+export { TopBarActions, TOP_BAR_ACTION_ORDER } from "./shell/top-bar-actions";
+export type { TopBarActionsProps } from "./shell/top-bar-actions";
+export { AccountMenuLanguage } from "./shell/account-menu-language";
+export type { AccountMenuLanguageProps, AccountMenuLanguageOption } from "./shell/account-menu-language";
+export { TourMenu } from "./shell/tour-menu";
+export type { TourMenuProps, TourMenuTour } from "./shell/tour-menu";
+export { SyncStatusIndicator, syncState } from "./shell/sync-status-indicator";
+export type { SyncStatus, SyncState, SyncStatusScope, SyncStatusIndicatorProps } from "./shell/sync-status-indicator";
+export { DevSwitchers, DEV_ORIGINAL_ROLE_KEY } from "./shell/dev-switchers";
+export type { DevSwitchersProps } from "./shell/dev-switchers";
+export { DEFAULT_TOP_BAR_PARTS_LABELS, useTopBarPartsLabels } from "./shell/top-bar-parts-labels";
+export type {
+  TopBarPartsLabels,
+  TourMenuLabels,
+  SyncStatusLabels,
+  DevSwitchersLabels,
+} from "./shell/top-bar-parts-labels";