@eifi1/ui-kit 0.41.0 → 0.43.0

package/src/shell/admin-menu.tsx

@@ -0,0 +1,146 @@
+import { Link } from "react-router";
+import { ShieldCheck } from "lucide-react";
+import { Chip } from "../components/chip";
+import { MenuItem } from "../components/menu-item";
+import type { LabelOverride } from "../i18n/kit-labels";
+import { DEFAULT_ADMIN_AREA_LABELS, useAdminAreaLabels } from "../admin/admin-area-labels";
+import type { AdminAreaLabels } from "../admin/admin-area-labels";
+import type { TopBarMenuEntry } from "./topbar-action-menu";
+
+/**
+ * The account menu's "Administration" row (0.42.0, docs/admin-harmonization.md §2.1, §6.6,
+ * §7): the way into the admin area everyone finds, in every app, for an admin only. Two
+ * forms of one row — {@link adminMenuEntry} for `TopBarActionMenu`'s `entries`, and
+ * {@link AdminMenuRow} for a menu built from `HoverMenu` children (Kurvenschmiede's).
+ */
+
+/** The badge's text: nothing for none or 0, "99+" past 99. */
+function badgeText(badge: number | null | undefined): string | null {
+  if (typeof badge !== "number" || !(badge > 0)) return null;
+  return badge > 99 ? "99+" : String(Math.floor(badge));
+}
+
+/**
+ * The waiting count at the row's end: the `solid` count pill of {@link Chip}, in the
+ * pending count's tone, with the number for the eye and `adminArea.waiting` for a reader
+ * ("Administration, 3 waiting"). `null` for no count.
+ */
+function WaitingBadge({ badge, labels }: { badge: number | null | undefined; labels: AdminAreaLabels }) {
+  const text = badgeText(badge);
+  if (text === null) return null;
+  return (
+    <Chip size="sm" variant="solid" tone="warning" data-slot="admin-badge">
+      <span aria-hidden>{text}</span>
+      {/* The comma parts it from the row's label in the name: "Administration, 3 waiting". */}
+      <span className="sr-only-fixed">, {labels.waiting(badge as number)}</span>
+    </Chip>
+  );
+}
+
+export interface AdminMenuEntryOptions {
+  /** The admin area. Default `/admin`. */
+  href?: string;
+  /**
+   * The waiting count (§2.4 decision 15, §6.3): only work that waits on this admin —
+   * `adminWaitingCount(attention, […])`. `0`, `null` or none shows no badge.
+   */
+  badge?: number | null;
+  /**
+   * The resolved `adminArea` words — pass `useAdminAreaLabels()`, or the row is ENGLISH
+   * in every language: a plain function reads no provider (kastlan, 0.42 adoption). Builds
+   * no hook, so the entry can be made in the list of entries. {@link useAdminMenuEntry}
+   * (0.43) is the same entry with the provider's words read for you.
+   */
+  labels?: AdminAreaLabels;
+  /** The entry's `key`. Default `"administration"`. */
+  key?: string;
+  /** The page already open: `aria-current` and a check mark. */
+  current?: boolean;
+}
+
+/**
+ * The "Administration" {@link TopBarMenuEntry}: a link row with the `ShieldCheck` icon,
+ * the kit's word and the waiting count as its badge. Put it in the entries for an admin
+ * only — the menu closes on the way, as any link row:
+ *
+ *     const labels = useAdminAreaLabels();
+ *     entries={[…, ...(isAdmin ? [adminMenuEntry({ badge: waiting, labels })] : []), …]}
+ *
+ * A function, not a hook: it reads NO provider, so pass `labels` (`useAdminAreaLabels()`)
+ * or the row says "Administration" in every language — or call {@link useAdminMenuEntry}
+ * at the component's top.
+ */
+export function adminMenuEntry({
+  href = "/admin",
+  badge,
+  labels = DEFAULT_ADMIN_AREA_LABELS,
+  key = "administration",
+  current,
+}: AdminMenuEntryOptions = {}): TopBarMenuEntry {
+  return {
+    kind: "link",
+    key,
+    to: href,
+    icon: <ShieldCheck className="size-4" aria-hidden />,
+    label: labels.title,
+    trailing: badgeText(badge) === null ? undefined : <WaitingBadge badge={badge} labels={labels} />,
+    current,
+  };
+}
+
+export interface UseAdminMenuEntryOptions extends Omit<AdminMenuEntryOptions, "labels"> {
+  /** Over the provider's `adminArea` words: prop > `<UiKitProvider labels={{ adminArea }}>`
+   *  > English. */
+  labels?: LabelOverride<AdminAreaLabels>;
+}
+
+/**
+ * {@link adminMenuEntry} with the provider's words (0.43, kastlan): the hook reads
+ * `useAdminAreaLabels()` itself, so the row is in the app's language without a `labels`
+ * to remember. Call it at the component's top, then put it in the entries:
+ *
+ *     const admin = useAdminMenuEntry({ badge: waiting });
+ *     entries={[…, ...(isAdmin ? [admin] : []), …]}
+ */
+export function useAdminMenuEntry({ labels: labelsProp, ...options }: UseAdminMenuEntryOptions = {}): TopBarMenuEntry {
+  const labels = useAdminAreaLabels(labelsProp);
+  return adminMenuEntry({ ...options, labels });
+}
+
+export interface AdminMenuRowProps {
+  /** The admin area. Default `/admin`. */
+  href?: string;
+  /** As {@link AdminMenuEntryOptions.badge}. */
+  badge?: number | null;
+  /** Runs on the way — `HoverMenu`'s `close`. */
+  onNavigate?: () => void;
+  current?: boolean;
+  /** Prop > `<UiKitProvider labels={{ adminArea }}>` > English. */
+  labels?: LabelOverride<AdminAreaLabels>;
+}
+
+/**
+ * The same row as {@link adminMenuEntry} for a menu drawn from `HoverMenu` children: the
+ * `<li>` holding the router-link {@link MenuItem} `TopBarActionMenu` draws for a link
+ * entry, so the two menus look alike.
+ *
+ *     {(close) => <ul>… {isAdmin && <AdminMenuRow badge={waiting} onNavigate={close} />} …</ul>}
+ */
+export function AdminMenuRow({ href = "/admin", badge, onNavigate, current, labels: labelsProp }: AdminMenuRowProps) {
+  // The provider's words, as every kit part (0.43: through the namespace's own hook).
+  const labels = useAdminAreaLabels(labelsProp);
+  return (
+    <li>
+      <MenuItem
+        href={href}
+        renderLink={({ href: to, ...p }) => <Link to={to} {...p} />}
+        onClick={onNavigate ? () => onNavigate() : undefined}
+        leading={<ShieldCheck className="size-4" aria-hidden />}
+        trailing={badgeText(badge) === null ? undefined : <WaitingBadge badge={badge} labels={labels} />}
+        current={current}
+      >
+        {labels.title}
+      </MenuItem>
+    </li>
+  );
+}

package/src/shell/app-shell.tsx

@@ -91,6 +91,16 @@ export type AppShellSidebarFooterItem =
       hint?: string;
       /** Leaves the app: a plain `<a target="_blank" rel="noopener noreferrer">`. */
       external?: boolean;
+      /**
+       * 0.42.0 (docs/admin-harmonization.md §6.9): a count of what waits behind the link —
+       * kastlan's "Administration" with its To-triage count. A pill at the end of the
+       * expanded link, a corner dot on the collapsed icon; `0`, `null` or none shows
+       * nothing, and above 99 it reads "99+". The count joins the link's name, in
+       * `badgeLabel`'s words when given ("Administration, 3 waiting").
+       */
+      badge?: number | null;
+      /** The badge's words for a reader — `adminArea.waiting(count)`. Default: the number. */
+      badgeLabel?: string;
     }
   | {
       kind: "links";
@@ -589,6 +599,17 @@ const plainLink: KitLinkComponent = ({ children, ...p }) => <a {...p}>{children}
 const FOOTER_ICON_LINK =
   "flex min-h-8 items-center justify-center rounded-md text-muted hover:bg-hover hover:text-secondary";
 
+/** A footer link's count as drawn: nothing for none, "99+" past 99. */
+function footerBadgeText(badge: number | null | undefined): string | null {
+  if (typeof badge !== "number" || !(badge > 0)) return null;
+  return badge > 99 ? "99+" : String(Math.floor(badge));
+}
+
+/** The count's pill — the solid "count" look of `Chip` (warning, the pending count's
+ *  tone, as `FloatingActionGroup`'s badge), sized for the footer's small text. */
+const FOOTER_BADGE =
+  "inline-flex h-4 min-w-4 shrink-0 items-center justify-center rounded-full bg-warning px-1 text-micro font-semibold leading-4 tabular-nums text-warning-contrast";
+
 /** Calls the link renderer as a component, so a router link's hooks are its own. */
 function RenderedLink({ render, ...props }: KitLinkProps & { render: KitLinkComponent }) {
   return render(props);
@@ -627,12 +648,23 @@ function SidebarFooterItems({
           const to = item.kind === "links" ? (item.to ?? item.links[0]?.to) : item.to;
           if (!to) return null;
           const external = item.kind === "links" ? item.links.find((l) => l.to === to)?.external : item.external;
+          const count = item.kind === "links" ? null : footerBadgeText(item.badge);
+          const spoken = count === null || item.kind === "links" ? null : (item.badgeLabel ?? count);
           return (
             <Tooltip key={item.key} label={item.label} side="end" portal className="block">
               {linkTo(to, external, {
-                "aria-label": item.label,
-                className: FOOTER_ICON_LINK,
-                children: <item.icon className="size-4" aria-hidden />,
+                "aria-label": spoken === null ? item.label : `${item.label}, ${spoken}`,
+                className: cn(FOOTER_ICON_LINK, count !== null && "relative"),
+                children: (
+                  <>
+                    <item.icon className="size-4" aria-hidden />
+                    {count !== null && (
+                      <span aria-hidden data-badge="" className={cn(FOOTER_BADGE, "absolute -top-0.5 end-0.5")}>
+                        {count}
+                      </span>
+                    )}
+                  </>
+                ),
               })}
             </Tooltip>
           );
@@ -655,6 +687,7 @@ function SidebarFooterItems({
             </nav>
           );
         }
+        const count = footerBadgeText(item.badge);
         const link = linkTo(item.to, item.external, {
           className: cn(FOOTER_ICON_LINK, "gap-1.5 text-xs font-medium"),
           children: (
@@ -663,6 +696,14 @@ function SidebarFooterItems({
               {/* Wraps from Large up (text size §10.17, round 0.34 T1): the link is
                   `min-h-8`, so it grows a line rather than cut "Feedb…". */}
               <span className="min-w-0 truncate-until-large">{item.text ?? item.label}</span>
+              {count !== null && (
+                <>
+                  <span aria-hidden data-badge="" className={FOOTER_BADGE}>
+                    {count}
+                  </span>
+                  <span className="sr-only">, {item.badgeLabel ?? count}</span>
+                </>
+              )}
             </>
           ),
         });

package/src/shell/dev-switchers.tsx

@@ -0,0 +1,179 @@
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { FlaskConical, Undo2 } from "lucide-react";
+import { DEFAULT_TOP_BAR_LABELS, useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { TopBarActionMenu, type TopBarMenuEntry } from "./topbar-action-menu";
+import { useTopBarPartsLabels, type DevSwitchersLabels } from "./top-bar-parts-labels";
+
+/** Where the role the session started with is kept, unless the app names its own key. */
+export const DEV_ORIGINAL_ROLE_KEY = "ui-kit:dev-original-role";
+
+function readKey(key: string): string | null {
+  try {
+    return sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeKey(key: string, value: string | null): void {
+  try {
+    if (value === null) sessionStorage.removeItem(key);
+    else sessionStorage.setItem(key, value);
+  } catch {
+    /* storage blocked: "Back to" lasts as long as this page */
+  }
+}
+
+export interface DevSwitchersProps<R extends string, P extends string> {
+  /** Draw anything at all: the app passes `import.meta.env.DEV`, so a production build
+   *  tree-shakes the switchers with the constant. */
+  enabled: boolean;
+  roles?: readonly R[];
+  /** The role the server enforces now. Named `currentRole`, not `role`, because `role` on
+   *  a JSX element is the ARIA role (as `RoleChip`'s `value`). */
+  currentRole?: R;
+  /** Apply a role — the app calls server-kit's `POST /dev/switch {role}` and re-reads
+   *  `/auth/me` (§2.7, §6.2). */
+  onRole?: (role: R) => void;
+  plans?: readonly P[];
+  /** The plan the server enforces now. Left out (not known yet — kastlan's overview is a
+   *  404 while billing is off), the plan menu still renders, with no row checked; a
+   *  `GET /dev/switch` answers it. */
+  currentPlan?: P;
+  /** Apply a plan — `POST /dev/switch {plan}`, then the overview (§6.3). */
+  onPlan?: (plan: P) => void;
+  /**
+   * The role to offer "Back to {role}" for. Left out, the kit keeps it itself: the role
+   * before the first switch of this browser session, in `sessionStorage` under
+   * `storageKey` — the server answers with the NEW role after a switch, so only the
+   * browser still knows the old one.
+   */
+  originalRole?: R;
+  /** The `sessionStorage` key for the kept role. Default {@link DEV_ORIGINAL_ROLE_KEY};
+   *  an app with several accounts on one browser may scope it per user. */
+  storageKey?: string;
+  /** Billing is off locally: the plan menu says plans change nothing, and stays usable
+   *  (§6.3). */
+  billingOff?: boolean;
+  /** A role's or a plan's words in the menu. Default: the value itself. */
+  roleLabel?: (role: R) => ReactNode;
+  planLabel?: (plan: P) => ReactNode;
+  /** Prop > `<UiKitProvider labels={{ topBarParts: { dev } }}>` > English. */
+  labels?: LabelOverride<DevSwitchersLabels>;
+}
+
+const flask = <FlaskConical className="size-5 text-warning" />;
+
+/** A label's text for a sentence, or the raw value when the label is not text. */
+const textOf = (label: ReactNode, value: string) =>
+  typeof label === "string" || typeof label === "number" ? String(label) : value;
+
+/**
+ * The top bar's local-dev switchers (docs/top-bar-harmonization.md §2.7, §6.2, §6.3): the
+ * role, then the plan, each a menu behind `RoleSwitcher`'s amber flask. Nothing renders
+ * unless `enabled`; either menu renders only with its list and handler.
+ *
+ * The role menu ends in "Back to {role}" once the role differs from the one the session
+ * started with: the dev route needs only a signed-in user, so a switch to a lesser role
+ * can always switch back. With `billingOff` the plan menu notes that plans change nothing
+ * while billing is off.
+ */
+export function DevSwitchers<R extends string, P extends string>({
+  enabled,
+  roles,
+  currentRole: role,
+  onRole,
+  plans,
+  currentPlan: plan,
+  onPlan,
+  originalRole,
+  storageKey = DEV_ORIGINAL_ROLE_KEY,
+  billingOff = false,
+  roleLabel = (r) => r,
+  planLabel = (p) => p,
+  labels: labelsProp,
+}: DevSwitchersProps<R, P>) {
+  const bar = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS);
+  const words = useTopBarPartsLabels(labelsProp ? { dev: labelsProp } : undefined).dev;
+  const [kept, setKept] = useState<string | null>(() => (enabled ? readKey(storageKey) : null));
+  // 0.43 (keksdose): `enabled` may start false and turn true — an app's GET probe of the
+  // dev route — so the kept role is read again then, or "Back to {role}" is lost after a
+  // reload. Adjusted during render, React's pattern for state that follows a prop.
+  const [wasEnabled, setWasEnabled] = useState(enabled);
+  if (wasEnabled !== enabled) {
+    setWasEnabled(enabled);
+    if (enabled) setKept(readKey(storageKey));
+  }
+  if (!enabled) return null;
+
+  const original = (originalRole ?? kept ?? undefined) as R | undefined;
+
+  const pickRole = (next: R) => {
+    if (originalRole === undefined) {
+      if (next === original) {
+        // Back where the session began: nothing left to go back to.
+        writeKey(storageKey, null);
+        setKept(null);
+      } else if (kept === null && role !== undefined && next !== role) {
+        writeKey(storageKey, role);
+        setKept(role);
+      }
+    }
+    onRole?.(next);
+  };
+
+  const roleMenu =
+    roles && roles.length > 0 && role !== undefined && onRole ? (
+      <TopBarActionMenu
+        icon={flask}
+        aria-label={`${bar.switchRole} · ${bar.role(role)}`}
+        entries={[
+          { kind: "heading", key: "head-role", label: words.roleHeading },
+          ...roles.map(
+            (r): TopBarMenuEntry => ({ key: `role-${r}`, label: roleLabel(r), checked: r === role, onSelect: () => pickRole(r) }),
+          ),
+          ...(original !== undefined && original !== role
+            ? ([
+                { kind: "divider", key: "sep-back" },
+                {
+                  key: "back",
+                  icon: <Undo2 className="size-4" />,
+                  label: words.backTo(textOf(roleLabel(original), original)),
+                  onSelect: () => pickRole(original),
+                },
+              ] satisfies TopBarMenuEntry[])
+            : []),
+        ]}
+      />
+    ) : null;
+
+  const planMenu =
+    plans && plans.length > 0 && onPlan ? (
+      <TopBarActionMenu
+        icon={flask}
+        aria-label={plan !== undefined ? `${words.switchPlan} · ${words.plan(plan)}` : words.switchPlan}
+        entries={[
+          { kind: "heading", key: "head-plan", label: words.planHeading },
+          ...plans.map(
+            (p): TopBarMenuEntry => ({ key: `plan-${p}`, label: planLabel(p), checked: p === plan, onSelect: () => onPlan(p) }),
+          ),
+        ]}
+      >
+        {billingOff
+          ? () => (
+              <li data-dev-billing-off="" className="mt-1 max-w-64 border-t border-subtle px-3 py-2 text-xs text-muted">
+                {words.billingOff}
+              </li>
+            )
+          : undefined}
+      </TopBarActionMenu>
+    ) : null;
+
+  return (
+    <>
+      {roleMenu}
+      {planMenu}
+    </>
+  );
+}