@eifi1/ui-kit 0.7.1 → 0.8.0

package/src/components/confirm-dialog.tsx

@@ -0,0 +1,242 @@
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from "react";
+import type { ReactNode } from "react";
+
+import { useKitLabels } from "../i18n/kit-labels";
+import { DialogFrame } from "./dialog-frame";
+import { Button } from "./ui";
+
+/**
+ * The `confirmDialog` namespace of `<UiKitProvider labels>`: the two buttons' fallback
+ * text. A call that knows what it is confirming says so per call (`confirmLabel:
+ * "Delete budget"`), which is what the dialog is for — these are for the rest.
+ */
+export interface ConfirmDialogLabels {
+  confirm: string;
+  cancel: string;
+}
+
+export const DEFAULT_CONFIRM_DIALOG_LABELS: ConfirmDialogLabels = {
+  confirm: "Confirm",
+  cancel: "Cancel",
+};
+
+export type ConfirmTone = "danger" | "warning" | "neutral";
+
+export interface ConfirmOptions {
+  /** The question, and the dialog's accessible name. */
+  title: ReactNode;
+  /** The smaller line under it — the consequence. Wired to `aria-describedby`. */
+  body?: ReactNode;
+  /** Default: `confirmDialog.confirm` from the provider, else "Confirm". */
+  confirmLabel?: ReactNode;
+  /** Default: `confirmDialog.cancel` from the provider, else "Cancel". */
+  cancelLabel?: ReactNode;
+  /**
+   * `"danger"` for what cannot be undone (a delete): the confirm is the destructive
+   * button and focus starts on CANCEL. `"warning"` and `"neutral"` (default) start on
+   * the confirm. See {@link ConfirmProvider} for why the two differ.
+   */
+  tone?: ConfirmTone;
+}
+
+export type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;
+
+const ConfirmContext = createContext<ConfirmFn | null>(null);
+
+/**
+ * `const confirm = useConfirm()` → `if (!(await confirm({ title }))) return`.
+ *
+ * The returned function is STABLE for the life of the provider, so it can sit in an
+ * effect's or a `useCallback`'s dependency list without re-running it.
+ *
+ * Throws outside a {@link ConfirmProvider}, rather than falling back to
+ * `window.confirm`: a silent fallback is exactly the native dialog the three apps are
+ * migrating away from, and it would look like the migration had worked.
+ */
+export function useConfirm(): ConfirmFn {
+  const confirm = useContext(ConfirmContext);
+  if (!confirm) {
+    throw new Error("useConfirm() must be called below a <ConfirmProvider>.");
+  }
+  return confirm;
+}
+
+interface Request extends ConfirmOptions {
+  id: number;
+  resolve: (answer: boolean) => void;
+}
+
+export interface ConfirmProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * The host for {@link useConfirm}: ONE confirm dialog for the whole app, rendered on
+ * {@link DialogFrame}, answering a promise.
+ *
+ * Asked for by all three apps at once — keksdose has 20+ `window.confirm` calls,
+ * kastlan 7, lenkbank 1. The native dialog cannot be translated past its OK/Cancel
+ * (those are the BROWSER's language, not the app's), cannot say which button is the
+ * destructive one, and on an installed PWA it prints the origin over the question.
+ * A promise is what lets each of those call sites change by one `await`:
+ *
+ *     if (!window.confirm(t("budget.delete_confirm"))) return;
+ *     // becomes
+ *     if (!(await confirm({ title: t("budget.delete_confirm"), tone: "danger" }))) return;
+ *
+ * ## Its own provider, not part of `UiKitProvider`
+ *
+ * `UiKitProvider` renders nothing: it is strings and a locale, it is optional, and it
+ * NESTS (an inner one re-labels one table). A dialog host inside it would mount a host
+ * per nested provider, and a component under the inner one would open a second dialog
+ * layer of its own. So the host is its own component, mounted once — inside the
+ * `UiKitProvider` whose strings it should speak, which is also the order the labels
+ * need.
+ *
+ * ## Focus
+ *
+ * On CANCEL for `tone: "danger"`, on CONFIRM otherwise. A confirm is often answered by
+ * a reflexive Enter — the key that pressed the Delete button in the first place may
+ * still be down — and for an action that cannot be undone that reflex must land on the
+ * harmless answer; `DangerConfirm` makes the same call ("never to the destructive
+ * button itself"). For everything else the confirm is the expected answer and Enter
+ * accepting it is what `window.confirm` taught users, which the migrating call sites'
+ * users already rely on. Focus returns to whatever opened it, through `Modal`'s trap.
+ *
+ * ## Escape, the backdrop, Back and Cancel all answer `false`
+ *
+ * Only the confirm button answers `true`. Anything that merely dismisses is a no.
+ *
+ * ## A second `confirm` while one is open QUEUES
+ *
+ * It is shown when the first is answered, and each call gets its own answer. The
+ * alternative — answering the open one `false` to make room — would answer a question
+ * the user never answered: a background prompt ("your session is about to expire")
+ * would cancel the delete they were reading. `false` has to mean "the user said no".
+ * A double-click cannot queue two of the same: the first click opens the modal
+ * synchronously (a discrete event's update is flushed before the next one), so the
+ * second lands on the open dialog rather than on the button — at worst on its
+ * backdrop, which answers `false`, the safe way to be wrong.
+ *
+ * Unmounting the provider answers everything still pending `false`, so no caller's
+ * `await` hangs forever.
+ *
+ * ## keksdose's synchronous call (transaction-swipe-plan.ts)
+ *
+ * `buildTxSwipeActions` is synchronous, but its `window.confirm` sits inside the
+ * action THUNK (`confirmed(key, run)` returns `() => { if (confirm(…)) run() }`), and a
+ * thunk may be async without its caller knowing. So the plan builder stays
+ * synchronous; it takes the confirm as an argument and the thunk awaits it:
+ *
+ *     // mobile-transaction-list.tsx
+ *     const confirm = useConfirm();
+ *     buildTxSwipeActions({ tx, …, confirm });
+ *
+ *     // transaction-swipe-plan.ts
+ *     const confirmed = (messageKey: string, run: () => void) => () => {
+ *       void confirm({ title: t(messageKey), tone: "danger" }).then((ok) => ok && run());
+ *     };
+ *
+ * Its test then passes `confirm: vi.fn(async () => false)` instead of stubbing the
+ * global, and asserts after an `await` (the mutation now runs a microtask later). The
+ * row snaps back when the swipe commits, before the answer — which is right: the
+ * dialog, not the half-swiped row, is where the question now is.
+ */
+export function ConfirmProvider({ children }: ConfirmProviderProps) {
+  const [queue, setQueue] = useState<Request[]>([]);
+  const nextId = useRef(0);
+  // Every unanswered request, including the ones not yet in state — the unmount
+  // cleanup below must reach a request made in the same tick it unmounts.
+  const pending = useRef(new Set<Request>());
+
+  const confirm = useCallback<ConfirmFn>(
+    (options) =>
+      new Promise<boolean>((resolve) => {
+        const request: Request = { ...options, id: ++nextId.current, resolve };
+        pending.current.add(request);
+        setQueue((q) => [...q, request]);
+      }),
+    [],
+  );
+
+  useEffect(() => {
+    const open = pending.current;
+    return () => {
+      for (const r of open) r.resolve(false);
+      open.clear();
+    };
+  }, []);
+
+  const answer = useCallback((request: Request, value: boolean) => {
+    if (!pending.current.delete(request)) return;
+    request.resolve(value);
+    setQueue((q) => q.filter((r) => r !== request));
+  }, []);
+
+  const current = queue[0];
+  return (
+    <ConfirmContext.Provider value={confirm}>
+      {children}
+      {current && (
+        // Keyed per request, so a queued one gets a fresh Modal: the first one's trap
+        // hands focus back to the page, and the next one's captures that as its own
+        // restore target instead of a button that has just been unmounted.
+        <ConfirmDialogView key={current.id} request={current} onAnswer={answer} />
+      )}
+    </ConfirmContext.Provider>
+  );
+}
+
+function ConfirmDialogView({
+  request,
+  onAnswer,
+}: {
+  request: Request;
+  onAnswer: (request: Request, value: boolean) => void;
+}) {
+  const labels = useKitLabels("confirmDialog", DEFAULT_CONFIRM_DIALOG_LABELS);
+  const tone = request.tone ?? "neutral";
+  const confirmRef = useRef<HTMLButtonElement>(null);
+  const cancelRef = useRef<HTMLButtonElement>(null);
+  // Set by the confirm button, read once the panel has finished lowering. Everything
+  // else that ends in `onClose` — Escape, the backdrop, Back, Cancel — leaves it false.
+  const accepted = useRef(false);
+
+  // In THIS component's effect, which runs after `Modal`'s own (a parent's effects run
+  // after its children's). `Modal` engages its focus trap on the panel first — and
+  // records the page's focused element as the restore target — and only then does
+  // focus move to the button. Focusing it from inside the panel would run first and
+  // make the button the restore target.
+  useEffect(() => {
+    (tone === "danger" ? cancelRef : confirmRef).current?.focus();
+  }, [tone]);
+
+  return (
+    <DialogFrame
+      title={request.title}
+      description={request.body}
+      onClose={() => onAnswer(request, accepted.current)}
+      // A confirmation interrupts to ask a question that must be answered.
+      role="alertdialog"
+      data-confirm-tone={tone}
+      actions={(close) => (
+        <>
+          <Button ref={cancelRef} type="button" variant="ghost" onClick={close}>
+            {request.cancelLabel ?? labels.cancel}
+          </Button>
+          <Button
+            ref={confirmRef}
+            type="button"
+            variant={tone === "danger" ? "danger" : "primary"}
+            onClick={() => {
+              accepted.current = true;
+              close();
+            }}
+          >
+            {request.confirmLabel ?? labels.confirm}
+          </Button>
+        </>
+      )}
+    />
+  );
+}

package/src/components/copy-button.tsx

@@ -0,0 +1,158 @@
+import type { ButtonHTMLAttributes } from "react";
+import { Check, Copy, X } from "lucide-react";
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { useAnnounce } from "../hooks/use-announce";
+import { useCopyToClipboard } from "../hooks/use-copy-to-clipboard";
+import type { CopyState } from "../hooks/use-copy-to-clipboard";
+import { Button, IconButton } from "./ui";
+import type { ButtonVariant, IconButtonSize } from "./ui";
+import { Tooltip } from "./tooltip";
+import type { TooltipSide } from "./tooltip";
+
+/** The words a copy button says. The visible three are short on purpose (they
+ *  replace the button's own text in the `label` variant); the two announcements
+ *  are the sentences a screen reader hears, since the button's focus never moves. */
+export interface CopyButtonLabels {
+  copy: string;
+  copied: string;
+  failed: string;
+  copiedAnnouncement: string;
+  failedAnnouncement: string;
+}
+
+export const DEFAULT_COPY_BUTTON_LABELS: CopyButtonLabels = {
+  copy: "Copy",
+  copied: "Copied",
+  failed: "Couldn’t copy",
+  copiedAnnouncement: "Copied to clipboard",
+  failedAnnouncement: "Couldn’t copy to the clipboard",
+};
+
+export interface CopyButtonProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onClick"> {
+  /** What to copy. A function is read at click time — for a value that is expensive
+   *  to build (a CSV of the table) or that changes under the button. */
+  text: string | (() => string);
+  /** `icon` (default): a square icon button whose tooltip states the result.
+   *  `label`: a text button whose words change to the result. */
+  variant?: "icon" | "label";
+  /** The idle accessible name — and, in the `label` variant, the visible text:
+   *  "Copy IBAN" says WHAT is copied, which a row of three copy icons needs. Default
+   *  `copyButton.copy`. */
+  label?: string;
+  /** The button's own look. Default: `ghost` for the icon, `secondary` for the label. */
+  buttonVariant?: ButtonVariant;
+  /** Icon variant only. */
+  size?: IconButtonSize;
+  /** Icon variant only: where the result tooltip opens. */
+  tooltipSide?: TooltipSide;
+  /** Pass through to the tooltip — needed inside a scroll container (see Tooltip). */
+  tooltipPortal?: boolean;
+  /** ms until the button returns to idle. Default 2000. */
+  resetAfter?: number;
+  /** Called with the real outcome once the copy settles. */
+  onCopied?: (ok: boolean) => void;
+  labels?: Partial<CopyButtonLabels>;
+}
+
+const ICONS: Record<CopyState, typeof Copy> = { idle: Copy, copied: Check, failed: X };
+
+/**
+ * A button that copies a value and tells the truth about whether it did.
+ *
+ * keksdose asked for it after two of its own copy buttons said "Copied" on a build
+ * where the copy had failed (no Clipboard API over plain http). This one takes its
+ * state from {@link useCopyToClipboard}, which reads the result, and has a `failed`
+ * state that looks and sounds different from success.
+ *
+ * The result is spoken through {@link useAnnounce}: activating the button moves no
+ * focus, so without a live region a screen-reader user hears nothing at all. A
+ * failure goes through an ASSERTIVE region and a success through a polite one — the
+ * failure is the news that changes what they do next.
+ *
+ * The icon variant keeps the SAME accessible name in every state. A button renaming
+ * itself under the focus is announced inconsistently across readers; the live region
+ * is the channel that is actually heard.
+ */
+export function CopyButton({
+  text,
+  variant = "icon",
+  label,
+  buttonVariant,
+  size = "sm",
+  tooltipSide = "top",
+  tooltipPortal = false,
+  resetAfter = 2000,
+  onCopied,
+  labels,
+  className,
+  disabled,
+  ...rest
+}: CopyButtonProps) {
+  const words = useKitLabels("copyButton", DEFAULT_COPY_BUTTON_LABELS, labels);
+  const { state, copy } = useCopyToClipboard({ resetAfter });
+  const polite = useAnnounce();
+  const assertive = useAnnounce({ politeness: "assertive" });
+
+  const idleText = label ?? words.copy;
+  const stateText = state === "copied" ? words.copied : state === "failed" ? words.failed : idleText;
+  const Icon = ICONS[state];
+  const iconTone =
+    state === "copied" ? "text-[var(--success)]" : state === "failed" ? "text-[var(--danger)]" : undefined;
+
+  const onClick = async () => {
+    const ok = await copy(typeof text === "function" ? text() : text);
+    if (ok) polite.announce(words.copiedAnnouncement);
+    else assertive.announce(words.failedAnnouncement);
+    onCopied?.(ok);
+  };
+
+  const regions = (
+    <>
+      <span {...polite.regionProps} />
+      <span {...assertive.regionProps} />
+    </>
+  );
+
+  if (variant === "label") {
+    return (
+      <>
+        <Button
+          type="button"
+          {...rest}
+          disabled={disabled}
+          variant={buttonVariant ?? "secondary"}
+          data-state={state}
+          onClick={onClick}
+          className={className}
+        >
+          <Icon aria-hidden className={cn("size-4 shrink-0", iconTone)} />
+          {stateText}
+        </Button>
+        {regions}
+      </>
+    );
+  }
+
+  return (
+    <>
+      <Tooltip label={stateText} side={tooltipSide} portal={tooltipPortal}>
+        <IconButton
+          type="button"
+          {...rest}
+          disabled={disabled}
+          aria-label={idleText}
+          variant={buttonVariant ?? "ghost"}
+          size={size}
+          data-state={state}
+          onClick={onClick}
+          className={cn(iconTone, className)}
+        >
+          <Icon aria-hidden />
+        </IconButton>
+      </Tooltip>
+      {regions}
+    </>
+  );
+}

package/src/components/data-table-pagination.tsx

@@ -19,6 +19,10 @@ interface PaginationProps {
   labels?: Partial<DataTableLabels>;
   /** For the page numbers and page-size options; falls back to the provider's. */
   locale?: string;
+  /** `"compact"` for a pager under a compact {@link DataTable} (lenkbank's in-card
+   *  tables): a slimmer footer and page buttons, so the pager is not the tallest row
+   *  of a table that was made compact on purpose. */
+  density?: "comfortable" | "compact";
 }
 
 /** Footer for {@link DataTable}: range summary, page-size select, and a
@@ -32,7 +36,9 @@ export function Pagination({
   onPageSize,
   labels: labelsProp,
   locale: localeProp,
+  density = "comfortable",
 }: PaginationProps) {
+  const compact = density === "compact";
   // prop > provider > English, like every other kit component. This defaulted straight
   // to the English object, so a standalone pager under a translated provider still
   // said "Rows per page" — only the pager INSIDE a DataTable was translated, because
@@ -61,7 +67,13 @@ export function Pagination({
   });
 
   return (
-    <div className="flex flex-wrap items-center justify-between gap-2 border-t border-[var(--border)] px-3 py-2 text-xs text-[var(--text-secondary)]">
+    <div
+      data-density={density}
+      className={cn(
+        "flex flex-wrap items-center justify-between gap-2 border-t border-[var(--border)] text-xs text-[var(--text-secondary)]",
+        compact ? "px-2 py-1" : "px-3 py-2",
+      )}
+    >
       <div className="flex items-center gap-2">
         <span>
           {pageSize === Infinity
@@ -92,11 +104,11 @@ export function Pagination({
             type="button"
             onClick={() => onPage(Math.max(0, page - 1))}
             disabled={page === 0}
-            className="rounded p-1 hover:bg-[var(--bg-hover)] disabled:opacity-40"
+            className={cn("rounded hover:bg-[var(--bg-hover)] disabled:opacity-40", compact ? "p-0.5" : "p-1")}
             aria-label={labels.prevPage}
           >
             {/* "Previous" points back along the line — left in LTR, right in RTL. */}
-            <ChevronLeft className="size-4 rtl:-scale-x-100" />
+            <ChevronLeft className={cn("rtl:-scale-x-100", compact ? "size-3.5" : "size-4")} />
           </button>
           {items.map((it, i) =>
             it === "ellipsis" ? (
@@ -113,7 +125,8 @@ export function Pagination({
                 // else to tell them apart.
                 aria-current={it === page ? "page" : undefined}
                 className={cn(
-                  "min-w-7 rounded px-2 py-0.5",
+                  "rounded",
+                  compact ? "min-w-6 px-1.5 py-0" : "min-w-7 px-2 py-0.5",
                   it === page
                     ? "bg-[var(--bg-inverse)] text-[var(--text-inverse)]"
                     : "hover:bg-[var(--bg-hover)]",
@@ -127,10 +140,10 @@ export function Pagination({
             type="button"
             onClick={() => onPage(Math.min(totalPages - 1, page + 1))}
             disabled={page >= totalPages - 1}
-            className="rounded p-1 hover:bg-[var(--bg-hover)] disabled:opacity-40"
+            className={cn("rounded hover:bg-[var(--bg-hover)] disabled:opacity-40", compact ? "p-0.5" : "p-1")}
             aria-label={labels.nextPage}
           >
-            <ChevronRight className="size-4 rtl:-scale-x-100" />
+            <ChevronRight className={cn("rtl:-scale-x-100", compact ? "size-3.5" : "size-4")} />
           </button>
         </div>
       )}

package/src/components/data-table-sort.ts

@@ -50,21 +50,60 @@ export function decodeSorts(raw: string | null, validKeys: ReadonlySet<string>):
   return out;
 }
 
+/**
+ * How a header click steps through the directions (see {@link nextSorts}).
+ *
+ * * `"tri"` — first direction → the other → unsorted. The default, and the only cycle
+ *   before 0.8.0.
+ * * `"toggle"` — first direction ⇄ the other, never unsorted: a report table that is
+ *   ALWAYS ranked by something (keksdose's aggregated tables) must not have a third
+ *   click that silently drops the ranking. Clicking another column still replaces
+ *   the sort, so the table can always be re-ranked; a shift-click criterion flips in
+ *   place and stays for the same reason.
+ */
+export type SortCycle = "tri" | "toggle";
+
+/** Per-click options for {@link nextSorts}; every field is optional and the
+ *  defaults reproduce the pre-0.8.0 cycle exactly. */
+export interface SortStepOptions {
+  /** The direction a column starts in on its first click. `"desc"` for money and
+   *  count columns, where the interesting rows are the large ones. Default `"asc"`. */
+  firstDir?: SortDir;
+  /** Default `"tri"`. */
+  cycle?: SortCycle;
+}
+
+const flip = (d: SortDir): SortDir => (d === "asc" ? "desc" : "asc");
+
 /** Header-click semantics. Plain click: make `key` the only sort — cycling
- *  asc → desc → none when it already is the sole criterion. Shift-click
- *  (`additive`): append `key` as the next-priority sort, or cycle an existing
- *  entry's direction in place (asc → desc → removed). */
-export function nextSorts(prev: SortState[], key: string, additive: boolean): SortState[] {
+ *  first → other → none (`"tri"`) or first ⇄ other (`"toggle"`) when it already is
+ *  the sole criterion. Shift-click (`additive`): append `key` as the next-priority
+ *  sort, or step an existing entry in place (first → other → removed under `"tri"`,
+ *  a plain flip under `"toggle"`). `firstDir` defaults to `"asc"`, `cycle` to
+ *  `"tri"` — the cycle every table had before the options existed. */
+export function nextSorts(
+  prev: SortState[],
+  key: string,
+  additive: boolean,
+  options: SortStepOptions = {},
+): SortState[] {
+  const first = options.firstDir ?? "asc";
+  const toggle = options.cycle === "toggle";
   const idx = prev.findIndex((s) => s.key === key);
+  // One step from `dir`: the second direction after the first, then either back to
+  // the first (toggle) or off (null). Judged against THIS column's first direction,
+  // so a desc-first column goes desc → asc → none rather than skipping a step.
+  const step = (dir: SortDir): SortDir | null =>
+    dir === first ? flip(first) : toggle ? first : null;
   if (!additive) {
     if (prev.length === 1 && idx === 0) {
-      return prev[0].dir === "asc" ? [{ key, dir: "desc" }] : [];
+      const dir = step(prev[0].dir);
+      return dir ? [{ key, dir }] : [];
     }
-    return [{ key, dir: "asc" }];
-  }
-  if (idx === -1) return [...prev, { key, dir: "asc" }];
-  if (prev[idx].dir === "asc") {
-    return prev.map((s, i) => (i === idx ? { key, dir: "desc" as SortDir } : s));
+    return [{ key, dir: first }];
   }
+  if (idx === -1) return [...prev, { key, dir: first }];
+  const dir = step(prev[idx].dir);
+  if (dir) return prev.map((s, i) => (i === idx ? { key, dir } : s));
   return prev.filter((_, i) => i !== idx);
 }