@eifi1/ui-kit 0.51.7 → 0.52.0

package/src/shell/account-menu-language.tsx

@@ -39,13 +39,11 @@ function flagOf(lang: AccountMenuLanguageOption): ReactNode {
   );
 }
 
-export interface AccountMenuLanguageProps {
+/** {@link AccountMenuLanguageProps} but the handler. */
+interface AccountMenuLanguageBaseProps {
   languages: readonly AccountMenuLanguageOption[];
   /** The active language's code. */
   value: string | undefined;
-  /** A pick: the app sets the device's language and, signed in, the account's
-   *  (settings §6.2). */
-  onPick: (code: string) => void;
   /** The account menu's `close` (from `TopBarActionMenu`'s `children`): a pick shuts it. */
   close?: () => void;
   /** The row's name. Default: `topBar.language` ("Language"). */
@@ -54,6 +52,28 @@ export interface AccountMenuLanguageProps {
   defaultOpen?: boolean;
 }
 
+/**
+ * `onChange`, or the deprecated `onPick`, is required: with both optional, a row an app
+ * moved off `onPick` without adding `onChange` — or with it misspelt — compiled, and a
+ * pick only closed the menu (0.52 code review, account-menu-language.tsx).
+ */
+export type AccountMenuLanguageProps = AccountMenuLanguageBaseProps &
+  (
+    | {
+        /** A pick: the app sets the device's language and, signed in, the account's
+         *  (settings §6.2). `value` + `onChange`, as every kit control pairs them
+         *  (CONTRIBUTING §4; refactor audit 2026-10-30, API-5). */
+        onChange: (code: string) => void;
+        /** @deprecated 0.52 — `onChange` (the same call); removed in 0.53. */
+        onPick?: (code: string) => void;
+      }
+    | {
+        onChange?: undefined;
+        /** @deprecated 0.52 — `onChange` (the same call); removed in 0.53. */
+        onPick: (code: string) => void;
+      }
+  );
+
 /**
  * The language choice INSIDE the account menu (docs/top-bar-harmonization.md §2.3),
  * keksdose's sub-list: a `Disclosure variant="menu"` row — the globe, "Language", the
@@ -68,11 +88,13 @@ export interface AccountMenuLanguageProps {
 export function AccountMenuLanguage({
   languages,
   value,
+  onChange,
   onPick,
   close,
   label,
   defaultOpen = false,
 }: AccountMenuLanguageProps) {
+  const change = onChange ?? onPick;
   const words = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS);
   const [open, setOpen] = useState(defaultOpen);
   const active = languages.find((l) => l.code === value);
@@ -109,7 +131,7 @@ export function AccountMenuLanguage({
               <MenuItem
                 checked={lang.code === value}
                 onClick={() => {
-                  onPick(lang.code);
+                  change?.(lang.code);
                   setOpen(false);
                   close?.();
                 }}

package/src/shell/account-menu-text-size.tsx

@@ -4,23 +4,44 @@ import { useAppearanceLabels, type AppearanceLabels } from "../components/appear
 import type { LabelOverride } from "../i18n/kit-labels";
 import { TEXT_SIZES, useTextSize, type TextSize } from "../theme/text-size";
 
-export interface AccountMenuTextSizeProps {
+/** {@link AccountMenuTextSizeProps} but the handler. */
+interface AccountMenuTextSizeBaseProps {
   /** The size in force. Default: the one on `<html>` ({@link useTextSize}), which is the
    *  size whoever applied it put there. */
   value?: TextSize;
-  /**
-   * A step: the next size down or up. The app applies it and keeps it as its Settings ▸
-   * Appearance does — `useAccountAppearance`'s `pickTextSize` (this device, and the
-   * account when signed in), with `appearance.saveFailed` as the toast when the account
-   * refused. The kit does not apply it itself, so the two places can never disagree.
-   */
-  onPick: (size: TextSize) => void;
   /** The row's name. Default: `appearance.textSize` ("Text size"). */
   label?: string;
   /** The `appearance` words (`textSize`, `textSizes`, `textSmaller`, `textLarger`). */
   labels?: LabelOverride<AppearanceLabels>;
 }
 
+/**
+ * `onChange`, or the deprecated `onPick`, is required: with both optional, a row an app
+ * moved off `onPick` without adding `onChange` — or with it misspelt — compiled, and A− /
+ * A+ stayed enabled and changed nothing (0.52 code review, account-menu-language.tsx).
+ */
+export type AccountMenuTextSizeProps = AccountMenuTextSizeBaseProps &
+  (
+    | {
+        /**
+         * A step: the next size down or up. The app applies it and keeps it as its
+         * Settings ▸ Appearance does — `useAccountAppearance`'s `pickTextSize` (this
+         * device, and the account when signed in), with `appearance.saveFailed` as the
+         * toast when the account refused. The kit does not apply it itself, so the two
+         * places can never disagree. `value` + `onChange`, as every kit control pairs them
+         * (CONTRIBUTING §4; refactor audit 2026-10-30, API-5).
+         */
+        onChange: (size: TextSize) => void;
+        /** @deprecated 0.52 — `onChange` (the same call); removed in 0.53. */
+        onPick?: (size: TextSize) => void;
+      }
+    | {
+        onChange?: undefined;
+        /** @deprecated 0.52 — `onChange` (the same call); removed in 0.53. */
+        onPick: (size: TextSize) => void;
+      }
+  );
+
 /**
  * The text size one tap away, INSIDE the account menu (0.46, keksdose live #426, its
  * `TextSizeRow`): the row's icon and name, the size in force, and A− / A+, which step
@@ -34,14 +55,15 @@ export interface AccountMenuTextSizeProps {
  * behind it and can step again. The size's name is a polite live region, so a step is
  * announced.
  */
-export function AccountMenuTextSize({ value, onPick, label, labels: labelsProp }: AccountMenuTextSizeProps) {
+export function AccountMenuTextSize({ value, onChange, onPick, label, labels: labelsProp }: AccountMenuTextSizeProps) {
+  const change = onChange ?? onPick;
   const labels = useAppearanceLabels(labelsProp);
   const onHtml = useTextSize().size;
   const size = value ?? onHtml;
   const index = TEXT_SIZES.indexOf(size);
   const step = (by: -1 | 1) => {
     const next = TEXT_SIZES[index + by];
-    if (next) onPick(next);
+    if (next) change?.(next);
   };
   return (
     <li data-account-menu-text-size="" className="flex items-center gap-2 px-3 py-1.5 text-sm">

package/src/shell/dev-menu.tsx

@@ -4,27 +4,13 @@ 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";
+// The kit's one storage guard, which 0.51 wrote here again by hand (DUP-8, refactor audit
+// 2026-10-30). Storage blocked, "Back to" lasts as long as this page.
+import { readSessionStored, writeSessionStored } from "../lib/safe-storage";
 
 /** 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 */
-  }
-}
-
 /**
  * One of the app's own groups in the {@link DevMenu} (docs/top-bar-harmonization.md
  * §2.7.1): keksdose's budget role, its "today" override, its resets.
@@ -151,14 +137,14 @@ export function DevMenu<R extends string, P extends string>({
 }: DevMenuProps<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));
+  const [kept, setKept] = useState<string | null>(() => (enabled ? readSessionStored(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) setKept(readSessionStored(storageKey));
   }
   if (!enabled) return null;
 
@@ -168,10 +154,10 @@ export function DevMenu<R extends string, P extends string>({
     if (originalRole === undefined) {
       if (next === original) {
         // Back where the session began: nothing left to go back to.
-        writeKey(storageKey, null);
+        writeSessionStored(storageKey, null);
         setKept(null);
       } else if (kept === null && role !== undefined && next !== role) {
-        writeKey(storageKey, role);
+        writeSessionStored(storageKey, role);
         setKept(role);
       }
     }

package/src/shell/role-switcher.tsx

@@ -2,6 +2,7 @@ import { FlaskConical } from "lucide-react";
 import { OptionSwitcherMenu } from "./option-switcher-menu";
 import { DEFAULT_TOP_BAR_LABELS, useKitLabels } from "../i18n/kit-labels";
 
+/** @deprecated 0.52 — `DevMenuProps` (`roles`, `currentRole`, `onRole`) (MOD-5); removed in 0.53. */
 export interface RoleSwitcherProps<R extends string> {
   roles: readonly R[];
   value: R;
@@ -22,6 +23,12 @@ export interface RoleSwitcherProps<R extends string> {
  * The flask wears `--warning` rather than a fixed `amber-500`: it is a caution
  * marker — the app is not showing you your own role — and the token carries that
  * amber across both themes instead of pinning one hue onto every palette.
+ *
+ * Deprecated in 0.52, removed in 0.53 (decision 4 of the refactor audit 2026-10-30,
+ * MOD-5): the role switch every app draws is `DevMenu`'s Account section (0.51), and no
+ * app renders this one.
+ *
+ * @deprecated 0.52 — `DevMenu` with `roles`, `currentRole` and `onRole` (MOD-5); removed in 0.53.
  */
 export function RoleSwitcher<R extends string>({
   roles,

package/src/shell/top-bar-actions.tsx

@@ -23,7 +23,7 @@ export interface TopBarActionsProps {
   /** `DevMenu` (0.51, docs/top-bar-harmonization.md §2.7.1): the one flask — the role,
    *  the plan, then the app's own dev sections. Fill it only behind
    *  `import.meta.env.DEV`, so a production build drops the branch. (0.42's
-   *  `DevSwitchers`, deprecated, is a DevMenu with no sections.) */
+   *  `DevSwitchers` was a DevMenu with no sections; removed in 0.52.) */
   dev?: ReactNode;
   /** kastlan's platform button. */
   platform?: ReactNode;

package/src/shell/top-bar-parts-labels.ts

@@ -82,8 +82,6 @@ export interface DevSwitchersLabels {
   overridesOn: string;
   /** The heading of the role group. */
   roleHeading: string;
-  /** @deprecated 0.51 — DevMenu's one flask is named by `menu`; removed in 0.52. */
-  switchPlan: string;
   /** The plan in the flask's name, given the active plan. */
   plan: (value: string) => string;
   /** The heading of the plan group. */
@@ -137,7 +135,6 @@ export const DEFAULT_TOP_BAR_PARTS_LABELS: TopBarPartsLabels = {
     menu: "Dev tools",
     overridesOn: "Overrides on",
     roleHeading: "Dev · role",
-    switchPlan: "Switch plan",
     plan: (value) => `Plan: ${value}`,
     planHeading: "Dev · plan",
     backTo: (role) => `Back to ${role}`,

package/src/shell.ts

@@ -5,6 +5,14 @@
 export * from "./shell/topbar-controls";
 export * from "./shell/top-bar";
 export * from "./shell/app-shell";
+// 0.52: the slice's share of the 55 names no app reads (refactor audit 2026-10-30, API-4,
+// decision 4), tagged on their specifiers as the barrel's are — the modules keep them.
+export {
+  /** @deprecated 0.52 — `AppShell`, which picks its phone bar with it (API-4); removed in 0.53 */
+  pickMobileBar,
+  /** @deprecated 0.52 — `AppShell`, which splits its phone bar with it (API-4); removed in 0.53 */
+  splitMobileBar,
+} from "./shell/app-shell";
 export * from "./shell/option-switcher-menu";
 export * from "./shell/role-switcher";
 export * from "./shell/topbar-action-menu";
@@ -25,12 +33,18 @@ export type { UseAdminMenuEntryOptions } from "./shell/admin-menu";
 export { AdminWaitingBadge } from "./shell/admin-menu";
 export type { AdminWaitingBadgeProps } 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 {
+  SettingsLayout,
+  /** @deprecated 0.52 — `SettingsLayout`, which shows its search past that many entries (API-4); removed in 0.53 */
+  SETTINGS_SEARCH_THRESHOLD,
+} from "./settings/settings-layout";
 export type { SettingsLayoutProps, SettingsLayoutWidth, SettingsDocumentTitleParts } from "./settings/settings-layout";
 export {
   useSettingsRoute,
+  /** @deprecated 0.52 — `useSettingsRoute`, which resolves the location with it (API-4); removed in 0.53 */
   resolveSettingsLocation,
   settingsFromListState,
+  /** @deprecated 0.52 — `settingsFromListState` and `useSettingsRoute`, which write and read it (API-4); removed in 0.53 */
   SETTINGS_FROM_LIST_STATE,
 } from "./settings/use-settings-route";
 export type {
@@ -41,7 +55,14 @@ export type {
   SettingsLocationRules,
   SettingsLocationResult,
 } from "./settings/use-settings-route";
-export { useSettingsFocus, useFocusParam, SETTINGS_FOCUS_RING, SETTINGS_FOCUS_MS } from "./settings/use-settings-focus";
+export {
+  useSettingsFocus,
+  useFocusParam,
+  /** @deprecated 0.52 — `useSettingsFocus` / `useFocusParam`, which ring the card with it (API-4); removed in 0.53 */
+  SETTINGS_FOCUS_RING,
+  /** @deprecated 0.52 — `useSettingsFocus` / `useFocusParam`, which hold the ring that long (API-4); removed in 0.53 */
+  SETTINGS_FOCUS_MS,
+} from "./settings/use-settings-focus";
 export { SettingsSection } from "./settings/settings-section";
 export type { SettingsSectionProps } from "./settings/settings-section";
 export { useSettingsLayout } from "./settings/settings-context";
@@ -77,8 +98,12 @@ 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";
+// local-dev menu, and their words.
+export {
+  TopBarActions,
+  /** @deprecated 0.52 — `TopBarActions`, which puts its slots in that order (API-4); removed in 0.53 */
+  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";
@@ -87,14 +112,20 @@ export { AccountMenuTextSize } from "./shell/account-menu-text-size";
 export type { AccountMenuTextSizeProps } from "./shell/account-menu-text-size";
 export { TourMenu } from "./shell/tour-menu";
 export type { TourMenuProps, TourMenuTour } from "./shell/tour-menu";
-export { SyncStatusIndicator, syncState } from "./shell/sync-status-indicator";
+export {
+  SyncStatusIndicator,
+  /** @deprecated 0.52 — `SyncStatusIndicator`, which derives its state with it (API-4); removed in 0.53 */
+  syncState,
+} from "./shell/sync-status-indicator";
 export type { SyncStatus, SyncState, SyncStatusScope, SyncStatusIndicatorProps } from "./shell/sync-status-indicator";
 // 0.51 (§2.7.1, keksdose): one flask, the kit's Account section and the app's own dev
-// sections; `DevSwitchers` is a deprecated wrapper over it until 0.52.
-export { DevMenu, DEV_ORIGINAL_ROLE_KEY } from "./shell/dev-menu";
+// sections. 0.42's `DevSwitchers`, a DevMenu with no sections since 0.51, went in 0.52.
+export {
+  DevMenu,
+  /** @deprecated 0.52 — `DevMenu`, which keeps the role there unless `storageKey` names another key (API-4); removed in 0.53 */
+  DEV_ORIGINAL_ROLE_KEY,
+} from "./shell/dev-menu";
 export type { DevMenuProps, DevMenuSection } from "./shell/dev-menu";
-export { DevSwitchers } 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,