@eifi1/ui-kit 0.4.1 → 0.5.0

package/dist/wizard/wizard-summary.js

@@ -1,13 +1,15 @@
+"use client";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Pencil } from "lucide-react";
 import { Card, CardAction, CardContent, CardHeader, CardTitle, IconButton } from "../components/ui.js";
-import { resolveWizardLabels } from "./types.js";
+import { DEFAULT_WIZARD_LABELS } from "./types.js";
+import { useKitLabels } from "../i18n/kit-labels.js";
 function WizardSummary({
   sections,
   onEditStep,
   labels
 }) {
-  const l = resolveWizardLabels(labels);
+  const l = useKitLabels("wizard", DEFAULT_WIZARD_LABELS, labels);
   return /* @__PURE__ */ jsxs("div", { className: "space-y-4", children: [
     /* @__PURE__ */ jsx("h2", { className: "text-lg font-semibold text-[var(--text-primary)]", children: l.reviewTitle }),
     sections.map((section, sIdx) => /* @__PURE__ */ jsxs(Card, { children: [
@@ -28,7 +30,7 @@ function WizardSummary({
       /* @__PURE__ */ jsx(CardContent, { children: /* @__PURE__ */ jsx("dl", { className: "grid gap-2 text-sm", children: section.items.map((item, iIdx) => /* @__PURE__ */ jsxs("div", { children: [
         iIdx > 0 && /* @__PURE__ */ jsx("div", { className: "mb-2 border-t border-[var(--border)]", role: "presentation" }),
         /* @__PURE__ */ jsxs("div", { className: "flex items-start justify-between gap-4", children: [
-          /* @__PURE__ */ jsx("dt", { className: "text-slate-500 dark:text-slate-400", children: item.label }),
+          /* @__PURE__ */ jsx("dt", { className: "text-[var(--text-muted)]", children: item.label }),
           /* @__PURE__ */ jsx("dd", { className: "text-right font-medium text-[var(--text-primary)]", children: item.value })
         ] })
       ] }, iIdx)) }) })

package/dist/wizard/wizard-summary.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/wizard/wizard-summary.tsx"],"sourcesContent":["import { Pencil } from \"lucide-react\";\nimport { Card, CardAction, CardContent, CardHeader, CardTitle, IconButton } from \"../components/ui\";\nimport type { SummarySection, WizardLabels } from \"./types\";\nimport { resolveWizardLabels } from \"./types\";\n\n/**\n * The review step: one card per section, each row a label/value pair, each card\n * carrying an edit button back to the step it came from.\n *\n * Sections are data, not children, because \"jump back to step N\" is the whole\n * point of the component and a caller assembling its own cards invariably drops\n * it. Labels and values are `ReactNode`, so a value can be a badge or a link.\n */\nexport function WizardSummary({\n  sections,\n  onEditStep,\n  labels,\n}: {\n  sections: SummarySection[];\n  onEditStep: (stepIndex: number) => void;\n  labels?: Partial<WizardLabels>;\n}) {\n  const l = resolveWizardLabels(labels);\n\n  return (\n    <div className=\"space-y-4\">\n      <h2 className=\"text-lg font-semibold text-[var(--text-primary)]\">{l.reviewTitle}</h2>\n      {sections.map((section, sIdx) => (\n        <Card key={sIdx}>\n          {/* CardHeader is a grid, and CardAction is the top-right column it\n              reserves — the edit button has to go through it or it stacks under\n              the title instead of sitting beside it. */}\n          <CardHeader className=\"pb-2\">\n            <CardTitle className=\"text-base\">{section.label}</CardTitle>\n            <CardAction>\n              <IconButton\n                size=\"sm\"\n                variant=\"ghost\"\n                aria-label={l.edit}\n                title={l.edit}\n                onClick={() => onEditStep(section.stepIndex)}\n              >\n                <Pencil />\n              </IconButton>\n            </CardAction>\n          </CardHeader>\n          <CardContent>\n            <dl className=\"grid gap-2 text-sm\">\n              {section.items.map((item, iIdx) => (\n                <div key={iIdx}>\n                  {iIdx > 0 && (\n                    <div className=\"mb-2 border-t border-[var(--border)]\" role=\"presentation\" />\n                  )}\n                  <div className=\"flex items-start justify-between gap-4\">\n                    <dt className=\"text-slate-500 dark:text-slate-400\">{item.label}</dt>\n                    <dd className=\"text-right font-medium text-[var(--text-primary)]\">\n                      {item.value}\n                    </dd>\n                  </div>\n                </div>\n              ))}\n            </dl>\n          </CardContent>\n        </Card>\n      ))}\n    </div>\n  );\n}\n"],"mappings":"AA0BM,cAMI,YANJ;AA1BN,SAAS,cAAc;AACvB,SAAS,MAAM,YAAY,aAAa,YAAY,WAAW,kBAAkB;AAEjF,SAAS,2BAA2B;AAU7B,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AACF,GAIG;AACD,QAAM,IAAI,oBAAoB,MAAM;AAEpC,SACE,qBAAC,SAAI,WAAU,aACb;AAAA,wBAAC,QAAG,WAAU,oDAAoD,YAAE,aAAY;AAAA,IAC/E,SAAS,IAAI,CAAC,SAAS,SACtB,qBAAC,QAIC;AAAA,2BAAC,cAAW,WAAU,QACpB;AAAA,4BAAC,aAAU,WAAU,aAAa,kBAAQ,OAAM;AAAA,QAChD,oBAAC,cACC;AAAA,UAAC;AAAA;AAAA,YACC,MAAK;AAAA,YACL,SAAQ;AAAA,YACR,cAAY,EAAE;AAAA,YACd,OAAO,EAAE;AAAA,YACT,SAAS,MAAM,WAAW,QAAQ,SAAS;AAAA,YAE3C,8BAAC,UAAO;AAAA;AAAA,QACV,GACF;AAAA,SACF;AAAA,MACA,oBAAC,eACC,8BAAC,QAAG,WAAU,sBACX,kBAAQ,MAAM,IAAI,CAAC,MAAM,SACxB,qBAAC,SACE;AAAA,eAAO,KACN,oBAAC,SAAI,WAAU,wCAAuC,MAAK,gBAAe;AAAA,QAE5E,qBAAC,SAAI,WAAU,0CACb;AAAA,8BAAC,QAAG,WAAU,sCAAsC,eAAK,OAAM;AAAA,UAC/D,oBAAC,QAAG,WAAU,qDACX,eAAK,OACR;AAAA,WACF;AAAA,WATQ,IAUV,CACD,GACH,GACF;AAAA,SAlCS,IAmCX,CACD;AAAA,KACH;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/wizard/wizard-summary.tsx"],"sourcesContent":["import { Pencil } from \"lucide-react\";\nimport { Card, CardAction, CardContent, CardHeader, CardTitle, IconButton } from \"../components/ui\";\nimport type { SummarySection, WizardLabels } from \"./types\";\nimport { DEFAULT_WIZARD_LABELS } from \"./types\";\nimport { useKitLabels } from \"../i18n/kit-labels\";\n\n/**\n * The review step: one card per section, each row a label/value pair, each card\n * carrying an edit button back to the step it came from.\n *\n * Sections are data, not children, because \"jump back to step N\" is the whole\n * point of the component and a caller assembling its own cards invariably drops\n * it. Labels and values are `ReactNode`, so a value can be a badge or a link.\n */\nexport function WizardSummary({\n  sections,\n  onEditStep,\n  labels,\n}: {\n  sections: SummarySection[];\n  onEditStep: (stepIndex: number) => void;\n  labels?: Partial<WizardLabels>;\n}) {\n  const l = useKitLabels(\"wizard\", DEFAULT_WIZARD_LABELS, labels);\n\n  return (\n    <div className=\"space-y-4\">\n      <h2 className=\"text-lg font-semibold text-[var(--text-primary)]\">{l.reviewTitle}</h2>\n      {sections.map((section, sIdx) => (\n        <Card key={sIdx}>\n          {/* CardHeader is a grid, and CardAction is the top-right column it\n              reserves — the edit button has to go through it or it stacks under\n              the title instead of sitting beside it. */}\n          <CardHeader className=\"pb-2\">\n            <CardTitle className=\"text-base\">{section.label}</CardTitle>\n            <CardAction>\n              <IconButton\n                size=\"sm\"\n                variant=\"ghost\"\n                aria-label={l.edit}\n                title={l.edit}\n                onClick={() => onEditStep(section.stepIndex)}\n              >\n                <Pencil />\n              </IconButton>\n            </CardAction>\n          </CardHeader>\n          <CardContent>\n            <dl className=\"grid gap-2 text-sm\">\n              {section.items.map((item, iIdx) => (\n                <div key={iIdx}>\n                  {iIdx > 0 && (\n                    <div className=\"mb-2 border-t border-[var(--border)]\" role=\"presentation\" />\n                  )}\n                  <div className=\"flex items-start justify-between gap-4\">\n                    <dt className=\"text-[var(--text-muted)]\">{item.label}</dt>\n                    <dd className=\"text-right font-medium text-[var(--text-primary)]\">\n                      {item.value}\n                    </dd>\n                  </div>\n                </div>\n              ))}\n            </dl>\n          </CardContent>\n        </Card>\n      ))}\n    </div>\n  );\n}\n"],"mappings":";AA2BM,cAMI,YANJ;AA3BN,SAAS,cAAc;AACvB,SAAS,MAAM,YAAY,aAAa,YAAY,WAAW,kBAAkB;AAEjF,SAAS,6BAA6B;AACtC,SAAS,oBAAoB;AAUtB,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AACF,GAIG;AACD,QAAM,IAAI,aAAa,UAAU,uBAAuB,MAAM;AAE9D,SACE,qBAAC,SAAI,WAAU,aACb;AAAA,wBAAC,QAAG,WAAU,oDAAoD,YAAE,aAAY;AAAA,IAC/E,SAAS,IAAI,CAAC,SAAS,SACtB,qBAAC,QAIC;AAAA,2BAAC,cAAW,WAAU,QACpB;AAAA,4BAAC,aAAU,WAAU,aAAa,kBAAQ,OAAM;AAAA,QAChD,oBAAC,cACC;AAAA,UAAC;AAAA;AAAA,YACC,MAAK;AAAA,YACL,SAAQ;AAAA,YACR,cAAY,EAAE;AAAA,YACd,OAAO,EAAE;AAAA,YACT,SAAS,MAAM,WAAW,QAAQ,SAAS;AAAA,YAE3C,8BAAC,UAAO;AAAA;AAAA,QACV,GACF;AAAA,SACF;AAAA,MACA,oBAAC,eACC,8BAAC,QAAG,WAAU,sBACX,kBAAQ,MAAM,IAAI,CAAC,MAAM,SACxB,qBAAC,SACE;AAAA,eAAO,KACN,oBAAC,SAAI,WAAU,wCAAuC,MAAK,gBAAe;AAAA,QAE5E,qBAAC,SAAI,WAAU,0CACb;AAAA,8BAAC,QAAG,WAAU,4BAA4B,eAAK,OAAM;AAAA,UACrD,oBAAC,QAAG,WAAU,qDACX,eAAK,OACR;AAAA,WACF;AAAA,WATQ,IAUV,CACD,GACH,GACF;AAAA,SAlCS,IAmCX,CACD;AAAA,KACH;AAEJ;","names":[]}

package/dist/wizard.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_WIZARD_LABELS, FieldErrors, StepStatus, SummaryItem, SummarySection, UseWizardOptions, UseWizardReturn, ValidateResult, WizardLabels, WizardStepConfig, resolveWizardLabels } from './wizard/types.js';
+export { useWizard } from './wizard/use-wizard.js';
+export { WizardContextProvider, WizardContextValue, useWizardContext } from './wizard/wizard-context.js';
+export { RequiredFieldSpec, requiredFieldsValidator } from './wizard/validation.js';
+export { WizardStep } from './wizard/wizard-step.js';
+export { WizardSummary } from './wizard/wizard-summary.js';
+export { StepperNav } from './wizard/stepper-nav.js';
+import 'react';

package/dist/wizard.js

@@ -0,0 +1,9 @@
+"use client";
+export * from "./wizard/types.js";
+export * from "./wizard/use-wizard.js";
+export * from "./wizard/wizard-context.js";
+export * from "./wizard/validation.js";
+export * from "./wizard/wizard-step.js";
+export * from "./wizard/wizard-summary.js";
+export * from "./wizard/stepper-nav.js";
+//# sourceMappingURL=wizard.js.map

package/dist/wizard.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wizard.ts"],"sourcesContent":["// `@eifi1/ui-kit/wizard` — the multi-step engine, its chrome and its review step.\n//\n// A re-slicing of the main barrel, not a new API. This entry point requires\n// `react-router`: useWizard syncs the active step to `?step=` via useSearchParams.\n//\n// NOT the same thing as `WizardStepper` in components/wizard-stepper, which is a bare\n// two-step indicator with no engine and stays on the main barrel.\nexport * from \"./wizard/types\";\nexport * from \"./wizard/use-wizard\";\nexport * from \"./wizard/wizard-context\";\nexport * from \"./wizard/validation\";\nexport * from \"./wizard/wizard-step\";\nexport * from \"./wizard/wizard-summary\";\nexport * from \"./wizard/stepper-nav\";\n"],"mappings":";AAOA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@eifi1/ui-kit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "App-agnostic shared design system: domain-free React components, theme and tokens.",
-  "_sideEffects": "The barrel (src/index.ts) re-exports EVERY component, including components/chart, which statically imports recharts. Without this field a bundler must assume each of those modules has side effects, so it cannot drop the unused ones: importing a Button from '@eifi1/ui-kit' dragged all 433KB of recharts into the consumer's ENTRY chunk, and Keksdose was preloading it on every page load, login included. Nothing in src/ imports for side effects (no bare imports, no CSS imports from JS, no module-level global writes) — the token stylesheet is its own './tokens.css' export — so this is safe. CSS is still listed so any future stylesheet survives.",
+  "_sideEffects": "The barrel (src/index.ts) re-exports EVERY component, including components/chart, which statically imports recharts. Without this field a bundler must assume each of those modules has side effects, so it cannot drop the unused ones: importing a Button from '@eifi1/ui-kit' dragged all 433KB of recharts into the consumer's ENTRY chunk, and Keksdose was preloading it on every page load, login included. Nothing in src/ imports for side effects (no bare imports, no CSS imports from JS, no module-level global writes) — the token stylesheet is its own './tokens.css' export — so this is safe. CSS is still listed so any future stylesheet survives. Re-checked when `flag-icons` left `dependencies` and tsup started emitting a `\"use client\"` banner: neither touches this. The flag stylesheet was never imported from JS in the first place (that was the finding), and a directive prologue is a string literal every bundler lifts out before it decides whether a module is inert.",
   "sideEffects": [
     "**/*.css"
   ],
@@ -12,6 +12,34 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./chart": {
+      "types": "./dist/chart.d.ts",
+      "import": "./dist/chart.js"
+    },
+    "./shell": {
+      "types": "./dist/shell.d.ts",
+      "import": "./dist/shell.js"
+    },
+    "./data-table": {
+      "types": "./dist/data-table.d.ts",
+      "import": "./dist/data-table.js"
+    },
+    "./wizard": {
+      "types": "./dist/wizard.d.ts",
+      "import": "./dist/wizard.js"
+    },
+    "./tour": {
+      "types": "./dist/tour.d.ts",
+      "import": "./dist/tour.js"
+    },
+    "./feedback": {
+      "types": "./dist/feedback.d.ts",
+      "import": "./dist/feedback.js"
+    },
+    "./search": {
+      "types": "./dist/search.d.ts",
+      "import": "./dist/search.js"
+    },
     "./dates": {
       "types": "./dist/lib/dates.d.ts",
       "import": "./dist/lib/dates.js"
@@ -21,52 +49,74 @@
   },
   "files": [
     "dist",
-    "tokens.css"
+    "src",
+    "!src/**/__tests__",
+    "!src/test",
+    "tokens.css",
+    "LICENSE"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "check:tokens": "node scripts/check-token-discipline.mjs",
+    "check": "npm run typecheck && npm run lint && npm run check:tokens && npm test && npm run build && node scripts/verify-package.mjs && npm run build:showcase",
     "test": "vitest run",
     "test:watch": "vitest",
     "build": "tsup && node scripts/fix-esm-extensions.mjs",
+    "verify:package": "npm run build && node scripts/verify-package.mjs",
+    "dev": "tsup --watch",
+    "dev:showcase": "vite --config showcase/vite.config.ts",
+    "build:showcase": "vite build --config showcase/vite.config.ts",
+    "preview:showcase": "vite preview --config showcase/vite.config.ts",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
+    "lucide-react": ">=0.400.0 <2",
     "react": ">=19",
     "react-dom": ">=19",
     "react-router": ">=7",
-    "recharts": ">=3",
+    "recharts": ">=3.8",
     "sonner": ">=2"
   },
   "peerDependenciesMeta": {
-    "react-router": {
-      "optional": true
-    },
-    "recharts": {
-      "optional": true
-    },
     "sonner": {
       "optional": true
     }
   },
+  "_dependencies": "Only what the package imports AND owns the version of. `lucide-react` is a PEER: every consumer already declares `lucide-react: ^0.511.0` itself, so a hard dependency here bought each of them a second copy of the icon set in node_modules — and pinned to 0.511.x it held all three behind a release line that is now at 1.x. The range is deliberately wide (`>=0.400.0 <2`): the kit imports named icon components and nothing else, which has been stable across that whole span, so the app picks the version. `flag-icons` was never imported at all — 5.6 MB of stylesheet and SVG installed into every consumer to support class NAMES (`fi fi-xx`) that CurrencyFlag, CurrencySelect and LanguageMenu render as strings. The host supplies that stylesheet; see the dependency section of README.md. It stays a devDependency because the showcase imports it.",
   "dependencies": {
     "clsx": "^2.1.1",
-    "flag-icons": "^7.5.0",
-    "lucide-react": "^0.511.0",
     "tailwind-merge": "^3.3.0",
     "zustand": "^5.0.5"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@tailwindcss/vite": "^4.3.3",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.7",
+    "@types/node": "^24.13.6",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^4.5.2",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^9.39.5",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "flag-icons": "^7.5.0",
+    "globals": "^17.12.0",
     "jsdom": "^30.0.1",
+    "lucide-react": "^0.511.0",
     "react-router": "^8.3.0",
     "recharts": "^3.8.1",
     "sonner": "^2.0.7",
+    "tailwindcss": "^4.3.3",
     "tsup": "^8.5.0",
     "typescript": "~5.9.3",
+    "typescript-eslint": "^8.70.1",
+    "vite": "^7.3.6",
     "vitest": "^4.1.11"
   },
   "license": "MIT",
@@ -83,5 +133,8 @@
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
-  "types": "./dist/index.d.ts"
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=20.18"
+  }
 }

package/src/chart.ts

@@ -0,0 +1,22 @@
+// `@eifi1/ui-kit/chart` — the chart shell and its colour system.
+//
+// A re-slicing of what the main barrel already exports, not a new API. It exists so a
+// consumer can reach the chart kit WITHOUT the barrel: `import("@eifi1/ui-kit/chart")`
+// is a 31KB chunk, where the same lazy import through the barrel pulls 221KB, because
+// a dynamic import of the barrel cannot be tree-shaken down to one of its members.
+//
+// This is also the only entry point in the package that requires `recharts`.
+export * from "./components/chart";
+export * from "./theme/chart-palette";
+
+// The tile chart (treemap) the apps share — moved here from keksdose so every consumer
+// derives it from the package rather than from a copy.
+export * from "./components/treemap";
+
+// lenkbank's zoomable series chart, its synced x-zoom, the toggle legend and the
+// mirrored-pair axis geometry — moved here so the apps derive them from the package.
+export * from "./components/series-chart";
+export * from "./components/chart-zoom";
+export * from "./components/toggle-legend";
+export * from "./components/facing-pair";
+export * from "./components/series-chart-labels";

package/src/components/account-settings.tsx

@@ -0,0 +1,275 @@
+import { useState } from "react";
+import type { KeyboardEvent, ReactNode } from "react";
+import { Button, Card, FIELD_WRITABLE_LOOK, Input } from "./ui";
+import { UserAvatar } from "./user-avatar";
+import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
+
+/**
+ * App-agnostic account-settings SECTIONS (feedback #333). The presentation lives
+ * in @hb/ui; each app injects its own auth-API handlers + translated labels and
+ * arranges these next to its own app-specific cards (appearance, budgets, …).
+ * Every section is a self-contained <Card> owning its transient form state.
+ */
+
+export interface ProfileSettingLabels {
+  title: string;
+  email: string;
+  role: string;
+  memberSince: string;
+  displayName: string;
+  save: string;
+}
+
+export function ProfileSetting({
+  name,
+  email,
+  role,
+  memberSince,
+  value,
+  onChange,
+  onSave,
+  saving,
+  labels,
+}: {
+  name?: string | null;
+  email?: string | null;
+  role?: ReactNode;
+  memberSince?: ReactNode;
+  value: string;
+  onChange: (value: string) => void;
+  onSave: () => void;
+  saving?: boolean;
+  labels: ProfileSettingLabels;
+}) {
+  const dirty = value.trim().length > 0 && value.trim() !== (name ?? "");
+  return (
+    <Card className="p-4 space-y-3">
+      <div className="flex items-center gap-3">
+        <UserAvatar name={name} email={email} size="lg" />
+        <div className="min-w-0">
+          <div className="text-sm font-medium">{labels.title}</div>
+          <div className="truncate font-mono text-xs text-[var(--text-muted)]">{email ?? "—"}</div>
+        </div>
+      </div>
+      <div className="grid grid-cols-[max-content_1fr] gap-x-3 gap-y-1 text-sm">
+        <span className="text-[var(--text-muted)]">{labels.role}</span>
+        <span>{role ?? "—"}</span>
+        <span className="text-[var(--text-muted)]">{labels.memberSince}</span>
+        <span>{memberSince ?? "—"}</span>
+      </div>
+      <Input
+        id="display-name"
+        label={labels.displayName}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        maxLength={120}
+      />
+      <Button onClick={onSave} disabled={!dirty || saving}>
+        {labels.save}
+      </Button>
+    </Card>
+  );
+}
+
+export interface PasswordSettingLabels {
+  title: string;
+  current: string;
+  next: string;
+  confirm: string;
+  submit: string;
+  tooShort: string;
+  mismatch: string;
+}
+
+export function PasswordSetting({
+  onSubmit,
+  pending,
+  minLength = 8,
+  labels,
+}: {
+  /** Called with the validated (current, new) pair; return a promise to auto-clear on success. */
+  onSubmit: (currentPassword: string, newPassword: string) => void | Promise<unknown>;
+  pending?: boolean;
+  minLength?: number;
+  labels: PasswordSettingLabels;
+}) {
+  const [current, setCurrent] = useState("");
+  const [next, setNext] = useState("");
+  const [confirm, setConfirm] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  const submit = async () => {
+    if (next.length < minLength) {
+      setError(labels.tooShort);
+      return;
+    }
+    if (next !== confirm) {
+      setError(labels.mismatch);
+      return;
+    }
+    setError(null);
+    try {
+      await onSubmit(current, next);
+      setCurrent("");
+      setNext("");
+      setConfirm("");
+    } catch {
+      // The app surfaces the failure (e.g. a toast); keep the fields for a retry.
+    }
+  };
+
+  return (
+    <Card className="p-4 space-y-3">
+      <div className="text-sm font-medium">{labels.title}</div>
+      <Input type="password" autoComplete="current-password" label={labels.current} value={current} onChange={(e) => setCurrent(e.target.value)} />
+      <Input type="password" autoComplete="new-password" label={labels.next} value={next} onChange={(e) => setNext(e.target.value)} />
+      <Input type="password" autoComplete="new-password" label={labels.confirm} value={confirm} onChange={(e) => setConfirm(e.target.value)} />
+      {error && <p className="text-xs text-[var(--danger)]">{error}</p>}
+      <Button onClick={() => void submit()} disabled={!current || !next || !confirm || pending}>
+        {labels.submit}
+      </Button>
+    </Card>
+  );
+}
+
+export interface TwoFactorSettingLabels {
+  status: string;
+  enabledText: string;
+  disabledText: string;
+  enable: string;
+  scanHint: string;
+  codeLabel: string;
+  verify: string;
+  disableSection: string;
+  password: string;
+  disable: string;
+  /**
+   * Alt text for the setup QR image, which shipped as a hardcoded `alt="QR"`.
+   *
+   * OPTIONAL, alone among these keys, and not because it matters less: this
+   * interface is annotated at consumer call sites (`const LABELS:
+   * TwoFactorSettingLabels = {…}`), so a new REQUIRED key is a compile error in
+   * every app on the next `npm update` — the additive-API rule in the README. It
+   * falls back to English here the way `AmountInput`'s label keys do. Make it
+   * required in the next major, when the three apps can be updated with it.
+   */
+  qrAlt?: string;
+}
+
+/** `qrAlt`'s English fallback, kept beside the interface rather than inline so the
+ *  one English word in this section is findable by the same `DEFAULT_*` grep as
+ *  every other one. Module-private: the key goes required in the next major. */
+const DEFAULT_QR_ALT = "QR code";
+
+export function TwoFactorSetting({
+  enabled,
+  setup,
+  onStartSetup,
+  onEnable,
+  onDisable,
+  busy,
+  labels,
+}: {
+  enabled: boolean;
+  /** QR + secret returned by the app's setup call; null before setup starts. */
+  setup: { qrSvg: string; secret: string } | null;
+  onStartSetup: () => void;
+  onEnable: (code: string) => void;
+  onDisable: (password: string, code: string) => void;
+  busy?: boolean;
+  labels: TwoFactorSettingLabels;
+}) {
+  const [code, setCode] = useState("");
+  const [password, setPassword] = useState("");
+  // Browsers autofill one-time-code fields with the saved username; keep the
+  // field readOnly until focus to block that. It therefore has to keep the LOOK of
+  // an editable field (FIELD_WRITABLE_LOOK): this is the one place where readOnly
+  // does not mean "you may not type here", and without the opt-out the field would
+  // sit there greyed until the moment it is focused.
+  const [otpReadonly, setOtpReadonly] = useState(true);
+  const onOtpFocus = () => setOtpReadonly(false);
+  // Only for the "Status: Enabled" composition — the punctuation between a field's
+  // name and its value is the language's (see `CommonLabels.fieldValue`).
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+
+  return (
+    <Card className="p-4 space-y-3">
+      <div className="text-sm">
+        {common.fieldValue(labels.status, enabled ? labels.enabledText : labels.disabledText)}
+      </div>
+
+      {!enabled && !setup && (
+        <Button onClick={onStartSetup} disabled={busy}>
+          {labels.enable}
+        </Button>
+      )}
+
+      {setup && (
+        <div className="space-y-2">
+          <div className="text-xs text-[var(--text-secondary)]">{labels.scanHint}</div>
+          {/* `bg-white`, NOT `--bg-surface`, and it must stay that way: a QR code is
+              read by a camera looking for maximum contrast between the modules and
+              their quiet zone. On the dark theme a surface-coloured backing makes it
+              slow to acquire, and on a warm light preset it lowers the contrast ratio
+              the spec is written against. This is the one place in the kit where a
+              literal colour is the correct answer. */}
+          <div className="inline-block rounded-md bg-white p-2">
+            <img
+              alt={labels.qrAlt ?? DEFAULT_QR_ALT}
+              src={`data:image/svg+xml;base64,${setup.qrSvg}`}
+              className="h-48 w-48"
+            />
+          </div>
+          <div className="break-all font-mono text-xs">{setup.secret}</div>
+          <Input
+            inputMode="numeric"
+            autoComplete="one-time-code"
+            readOnly={otpReadonly}
+            inputClassName={FIELD_WRITABLE_LOOK}
+            onFocus={onOtpFocus}
+            maxLength={8}
+            label={labels.codeLabel}
+            value={code}
+            onChange={(e) => setCode(e.target.value)}
+            onKeyDown={(e: KeyboardEvent<HTMLInputElement>) => {
+              if (e.key === "Enter" && code && !busy) {
+                e.preventDefault();
+                onEnable(code);
+              }
+            }}
+          />
+          <Button onClick={() => onEnable(code)} disabled={!code || busy}>
+            {labels.verify}
+          </Button>
+        </div>
+      )}
+
+      {enabled && (
+        <div className="space-y-3 border-t border-[var(--border)] pt-3">
+          <div className="text-sm font-medium">{labels.disableSection}</div>
+          <Input type="password" autoComplete="current-password" label={labels.password} value={password} onChange={(e) => setPassword(e.target.value)} />
+          <Input
+            inputMode="numeric"
+            autoComplete="one-time-code"
+            readOnly={otpReadonly}
+            inputClassName={FIELD_WRITABLE_LOOK}
+            onFocus={onOtpFocus}
+            maxLength={8}
+            label={labels.codeLabel}
+            value={code}
+            onChange={(e) => setCode(e.target.value)}
+            onKeyDown={(e: KeyboardEvent<HTMLInputElement>) => {
+              if (e.key === "Enter" && password && code && !busy) {
+                e.preventDefault();
+                onDisable(password, code);
+              }
+            }}
+          />
+          <Button variant="danger" onClick={() => onDisable(password, code)} disabled={!password || !code || busy}>
+            {labels.disable}
+          </Button>
+        </div>
+      )}
+    </Card>
+  );
+}

package/src/components/alert-banner.tsx

@@ -0,0 +1,75 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { AlertTriangle } from "lucide-react";
+import { cn } from "../lib/cn";
+
+export type AlertTone = "danger" | "warning" | "neutral";
+
+/** Border + surface per tone, WITHOUT a radius or padding, so a caller that owns
+ * its own box (a Card, say) can take the tone alone. Single source for both
+ * {@link alertFrameClass} and {@link toneFrameClass}.
+ *
+ * The colored tones are 2px, not 1px, and that is load-bearing rather than
+ * decorative. A 1px border is 1.25 device pixels on a 125%-scaled display — the
+ * usual Windows setting — so whether it renders as a solid line or as two
+ * half-lit pixels depends on where the box happens to land in device-pixel space.
+ * The same card then shows a heavy left edge and a right edge that fades out,
+ * which is what feedback #264, #277, #491 and #498 all reported. A 2px border is
+ * 2.5 device pixels: it always covers at least two pixels fully, on both edges,
+ * at any offset. Callers compensate the extra pixel in their own padding so
+ * switching tones never shifts the layout. */
+const TONE_FRAME: Record<AlertTone, string> = {
+  danger: "border-2 border-[var(--danger-border)] bg-[var(--danger-bg)]",
+  warning: "border-2 border-[var(--warning-border)] bg-[var(--warning-bg)]",
+  neutral: "border border-[var(--border)]",
+};
+
+/** The tone's border + surface on their own — for a caller that already has a box
+ * with its own radius and padding (e.g. a Card). Remember to shave 1px off that
+ * padding for the colored tones, whose border is 2px wide. */
+export function toneFrameClass(tone: AlertTone): string {
+  return TONE_FRAME[tone];
+}
+
+/** Single source for the warning-callout frame (feedback #277): the tone's border
+ * and surface plus this component's own radius and padding, the latter
+ * compensating the 2px colored border so toggling tones never shifts layout. */
+export function alertFrameClass(tone: AlertTone): string {
+  const box = tone === "neutral" ? "rounded-md p-3" : "rounded-md p-[11px]";
+  return `${box} ${TONE_FRAME[tone]}`;
+}
+
+const TONE_TEXT: Record<Exclude<AlertTone, "neutral">, string> = {
+  danger: "text-[var(--danger)]",
+  warning: "text-[var(--warning)]",
+};
+
+const TONE_ICON: Record<Exclude<AlertTone, "neutral">, string> = {
+  danger: "text-[var(--danger)]",
+  warning: "text-[var(--warning)]",
+};
+
+export interface AlertBannerProps extends ComponentPropsWithoutRef<"div"> {
+  /** `neutral` is deliberately not offered: a callout with a warning triangle in it
+   *  and no colour is a warning that looks like a note, which is the one thing this
+   *  box must never be. The neutral frame is still available on its own through
+   *  {@link toneFrameClass}. */
+  tone?: Exclude<AlertTone, "neutral">;
+  children: ReactNode;
+}
+
+/** Static warning/danger callout box with the shared frame and an icon. */
+export function AlertBanner({ tone = "danger", className, children, ...rest }: AlertBannerProps) {
+  return (
+    <div
+      // Arbitrary attributes first — a `data-tour` anchor, a test id, an
+      // `aria-describedby` — then the layout and tone classes, which are merged
+      // through `cn` rather than spread so a caller's `className` refines the box
+      // instead of replacing it.
+      {...rest}
+      className={cn("flex items-start gap-2 text-sm", alertFrameClass(tone), TONE_TEXT[tone], className)}
+    >
+      <AlertTriangle className={cn("mt-0.5 size-4 shrink-0", TONE_ICON[tone])} />
+      <span className="flex-1">{children}</span>
+    </div>
+  );
+}