@eifi1/ui-kit 0.26.0 → 0.27.0

package/src/feedback/feedback-status-undo.ts

@@ -0,0 +1,111 @@
+import { useCallback } from "react";
+import { toast } from "../components/toast";
+import type { FeedbackStatus } from "./feedback-inbox";
+import {
+  useFeedbackStatusLabels,
+  useFeedbackToastLabels,
+  type FeedbackStatusLabels,
+  type FeedbackToastLabels,
+} from "./feedback-labels";
+import type { FeedbackRecord } from "./feedback-record";
+
+/**
+ * A status change that can be taken back — §4.5 of the feedback contract, lifted from
+ * keksdose's `changeStatusUndoably` (`frontend/src/features/feedback/feedback-page.tsx`,
+ * dev #587: *"Just clicked somewhere and a feedback row disappeared without knowing what
+ * I set as new status."*).
+ *
+ * An inbox is usually filtered by status, so a row whose new status falls outside the
+ * filter leaves the table the moment the change lands, with nothing on screen saying what
+ * it became. The toast says it, names the report, and offers the old status back for 8 s
+ * (the window keksdose's transactions Undo uses, feedback #184). Undo PATCHes the old
+ * status and confirms that too. kastlan and Kurvenschmiede had no Undo at all.
+ */
+
+/** The one PATCH a status change is: `PATCH /feedback/{id}` with `{ status }`. */
+export interface FeedbackStatusPatch {
+  id: number;
+  status: FeedbackStatus;
+}
+
+/**
+ * The page's status mutation. **TanStack Query's `mutate` fits as it stands** — pass
+ * `updateMutation.mutate` (stable across renders), not `mutateAsync`. A hand-written
+ * one sends the PATCH and calls `onSuccess` once it has landed, and only then.
+ *
+ * Failure is the mutation's own business: its `onError` toasts the server's `detail`,
+ * else `feedbackToast.updateFailed` (§4.4) — this hook adds no second error toast.
+ */
+export type FeedbackStatusMutate = (
+  patch: FeedbackStatusPatch,
+  callbacks: { onSuccess: () => void },
+) => void;
+
+/** What the change needs to know about the row: which one, what it is called in the
+ *  toast, and where it stood (the status Undo goes back to). */
+export type FeedbackStatusRow = Pick<FeedbackRecord, "id" | "title" | "status">;
+
+/** Set `row` to `status`, with the Undo toast. A no-op when it is already there. */
+export type FeedbackStatusChange = (row: FeedbackStatusRow, status: FeedbackStatus) => void;
+
+export interface FeedbackStatusUndoOptions {
+  /** Over the `feedbackToast` namespace (the toast's words). */
+  labels?: Partial<FeedbackToastLabels>;
+  /** Over the `feedbackStatus` namespace (the status names inside them). */
+  statusLabels?: Partial<FeedbackStatusLabels>;
+}
+
+/** How long the Undo stays reachable: 8 s, keksdose's window (feedback #184). */
+export const FEEDBACK_UNDO_DURATION = 8000;
+
+/**
+ * The undoable status change — for the table's status cell, the row detail's pills and
+ * the phone swipes alike (§4.5, §7.10: swipes included, Marcel 2026-10-04 — keksdose's
+ * swipe commits go through its `changeStatusUndoably` too). Wire every one of them
+ * through the function this returns:
+ *
+ * ```tsx
+ * const update = useMutation({ mutationFn: api.updateFeedback, onError: … });
+ * const changeStatus = useFeedbackStatusUndo(update.mutate);
+ * <FeedbackStatusTransitions … onPick={(status) => changeStatus(row, status)} />
+ * ```
+ *
+ * Give it the PAGE's mutation, not one a row owns: TanStack only calls per-call
+ * callbacks while the observer that started the mutation is mounted, and a row the new
+ * status filters out unmounts before the PATCH answers — the toast would never come.
+ *
+ * The flow: PATCH `{ id, status }` → on success a success toast
+ * `statusChanged(newName, title)` with the action `statusUndo`, 8 s → Undo PATCHes
+ * `{ id, status: previous }` → on success `statusRestored(previousName, title)`.
+ */
+export function useFeedbackStatusUndo(
+  mutate: FeedbackStatusMutate,
+  { labels, statusLabels }: FeedbackStatusUndoOptions = {},
+): FeedbackStatusChange {
+  const words = useFeedbackToastLabels(labels);
+  const names = useFeedbackStatusLabels(statusLabels);
+  return useCallback<FeedbackStatusChange>(
+    (row, status) => {
+      const { id, title, status: previous } = row;
+      if (status === previous) return;
+      const nameOf = (value: FeedbackStatus) => names[value] ?? value;
+      mutate(
+        { id, status },
+        {
+          onSuccess: () => {
+            toast.undo(words.statusChanged(nameOf(status), title), {
+              label: words.statusUndo,
+              duration: FEEDBACK_UNDO_DURATION,
+              onUndo: () =>
+                mutate(
+                  { id, status: previous },
+                  { onSuccess: () => void toast.success(words.statusRestored(nameOf(previous), title)) },
+                ),
+            });
+          },
+        },
+      );
+    },
+    [mutate, words, names],
+  );
+}

package/src/feedback/feedback-submit.tsx

@@ -0,0 +1,224 @@
+import { useRef, useState } from "react";
+import type { ReactNode } from "react";
+import { toast } from "../components/toast";
+import { DEFAULT_MAX_ATTACHMENTS } from "./feedback-attachment";
+import { captureAppScreenshot } from "./feedback-capture";
+import { FeedbackContextBox, feedbackContext, type FeedbackSubmitter } from "./feedback-context";
+import { FeedbackDialog, type FeedbackMultipleSubmission } from "./feedback-dialog";
+import type { FeedbackCategory } from "./feedback-inbox";
+import { useFeedbackCategoryLabels, useFeedbackToastLabels } from "./feedback-labels";
+import {
+  FEEDBACK_ATTACHMENT_ACCEPT,
+  FEEDBACK_PICKABLE_CATEGORIES,
+  type FeedbackContext,
+  type FeedbackEnvironment,
+} from "./feedback-record";
+
+/**
+ * `FeedbackCreate` — the body of `POST /feedback` (keksdose `schemas/feedback.py:25`, §3.4
+ * of docs/feedback-harmonization.md), as {@link useFeedbackSubmit} hands it to the app's
+ * `create`.
+ */
+export interface FeedbackCreatePayload {
+  /** Trimmed; never blank (the dialog will not send a subject of spaces). */
+  title: string;
+  /** `""` when the reporter wrote nothing or only whitespace — the server stores `""`. */
+  body: string;
+  /** Never `CRASH` — the server answers that with a 422 (§3.4). */
+  category: FeedbackCategory;
+  /** §3.2, built by `feedbackContext` from what the context box showed. */
+  context: FeedbackContext;
+  /** The captured screenshot's upload URL, or `null`. */
+  screenshot_url: string | null;
+  /** The picked and pasted files' upload URLs, in the order they were added — `[]` when
+   *  none, as keksdose sends it. At most 5. */
+  attachment_urls: string[];
+}
+
+export interface UseFeedbackSubmitOptions<R = unknown> {
+  /**
+   * `POST /feedback/attachments` for ONE file → its URL (§3.3) — the app's authed client.
+   * Every file goes up BEFORE the report is created, so a row never names a file that did
+   * not arrive (keksdose `use-feedback-dialog.tsx:89`); if any upload rejects, nothing is
+   * created and the failure toast says so.
+   */
+  upload: (file: File) => Promise<string>;
+  /** `POST /feedback` with the payload. Whatever it resolves with reaches `onSubmitted`. */
+  create: (payload: FeedbackCreatePayload) => Promise<R>;
+  /** Who is filing — shown in the context box and sent in `context.user_*`. */
+  user?: FeedbackSubmitter | null;
+  /** `context.environment` — the app's own reading of which copy it is (keksdose
+   *  `deployEnvironment()`). */
+  environment?: FeedbackEnvironment | (string & {});
+  /** `context.version` — the app build (`__APP_VERSION__`). */
+  version?: string;
+  /** The report was filed: after the "Thanks for the feedback!" toast and the close. The
+   *  place to invalidate the app's feedback queries. */
+  onSubmitted?: (result: R) => void;
+  /**
+   * The failure toast's text from what `upload` or `create` rejected with — the app's own
+   * `extractApiErrorMessage(err, fallback)` (keksdose) / `apiErrorMessage` (Kurvenschmiede),
+   * so the server's `detail` wins (§3.7: a 413, a 415, keksdose's demo-session 403). Without
+   * it every failure says `feedbackToast.submitFailed`.
+   */
+  errorMessage?: (error: unknown, fallback: string) => string;
+  /**
+   * The "Capture screenshot" button's capture. Default {@link captureAppScreenshot} of
+   * `#root`; another root is `() => captureAppScreenshot({ rootId: "app" })`. `false`
+   * hides the button — for an app that does not install the optional peer
+   * `modern-screenshot`. A rejection becomes the `captureFailed` toast.
+   */
+  capture?: false | (() => Promise<File | null>);
+}
+
+export interface FeedbackSubmit {
+  /**
+   * Open the dialog on `category` — a `FeedbackMenu` row's (§4.2: "default category when
+   * opened from a row: that row's"). Without one, or with `CRASH` (never pickable), it
+   * opens on `OTHER`, the server's own default (§3.4). Each open starts a fresh form,
+   * reads `location.href` for the context box and ticks "Attach current page URL" again.
+   */
+  open: (category?: FeedbackCategory) => void;
+  /** Close it, as Cancel does. */
+  close: () => void;
+  /** The dialog — render it once, anywhere (it portals). `null` while closed. */
+  dialog: ReactNode;
+}
+
+/**
+ * The feedback submit dialog, wired (0.27.0, docs/feedback-harmonization.md §4.2): the
+ * one call that replaces keksdose's `use-feedback-dialog.tsx`, kastlan's `FeedbackButton`
+ * and Kurvenschmiede's `use-feedback-dialog.tsx`.
+ *
+ * ```tsx
+ * const feedback = useFeedbackSubmit({
+ *   upload: (file) => feedbackApi.uploadAttachment(file),
+ *   create: (payload) => feedbackApi.create(payload),
+ *   user, environment: deployEnvironment(), version: __APP_VERSION__,
+ *   errorMessage: extractApiErrorMessage,
+ *   onSubmitted: () => qc.invalidateQueries({ queryKey: queryKeys.feedback.all }),
+ * });
+ * <FeedbackMenu onFile={feedback.open} isAdmin={user?.role === "ADMIN"} />
+ * {feedback.dialog}
+ * ```
+ *
+ * What it settles, so no app restates it:
+ *
+ * - `FeedbackDialog` in `attachments="multiple"` with `requireBody={false}` (§7.4): a
+ *   subject alone is a report. One captured screenshot in its own slot plus up to 5
+ *   picked or pasted files, `FEEDBACK_ATTACHMENT_ACCEPT` (images, PDF, text), 10 MB each.
+ * - The pickable categories — Bug, Idea, Question, Other, in the kit's words. `CRASH` is
+ *   filed by the error boundary and is never offered (keksdose feedback #160).
+ * - The context box, built from the same values as the `context` it sends
+ *   ({@link FeedbackContextBox} / `feedbackContext`), the URL read when the dialog OPENS.
+ * - Upload every file, then create (keksdose `use-feedback-dialog.tsx:89`): the
+ *   screenshot to `screenshot_url`, the rest to `attachment_urls`, all in parallel.
+ * - The toasts, from `feedbackToast`: filed, failed (the server's `detail` through
+ *   `errorMessage`), a refused file's type, size or count, a failed capture.
+ *
+ * What stays the app's: the API client, the user, the environment and version, and what
+ * to refresh afterwards. No TanStack in here — `create` is a plain promise, so the hook
+ * runs in any app; the app's mutation, if it wants one, lives inside `create`.
+ *
+ * A failure keeps the dialog open with the draft, as keksdose's did. A dialog closed and
+ * opened again while a send is still running is NOT closed by that send's success — the
+ * new draft is somebody's next report.
+ */
+export function useFeedbackSubmit<R = unknown>(options: UseFeedbackSubmitOptions<R>): FeedbackSubmit {
+  const { upload, create, user, environment, version, onSubmitted, errorMessage, capture } = options;
+  const toastText = useFeedbackToastLabels();
+  const categoryLabels = useFeedbackCategoryLabels();
+  const [isOpen, setIsOpen] = useState(false);
+  const [category, setCategory] = useState<FeedbackCategory>("OTHER");
+  const [url, setUrl] = useState("");
+  const [attachUrl, setAttachUrl] = useState(true);
+  const [submitting, setSubmitting] = useState(false);
+  // Which opening a send belongs to — see "closed and opened again" above.
+  const opening = useRef(0);
+  const inFlight = useRef(false);
+
+  const open = (next?: FeedbackCategory) => {
+    opening.current += 1;
+    setCategory(next && FEEDBACK_PICKABLE_CATEGORIES.includes(next) ? next : "OTHER");
+    setUrl(typeof window === "undefined" ? "" : window.location.href);
+    // Fresh every time (Kurvenschmiede use-feedback-dialog.tsx:80): a reporter who left the
+    // page out of one idea is not saying the bug report after it is unrelated too.
+    setAttachUrl(true);
+    setIsOpen(true);
+  };
+  const close = () => setIsOpen(false);
+
+  const submit = async (data: FeedbackMultipleSubmission) => {
+    if (inFlight.current) return;
+    inFlight.current = true;
+    setSubmitting(true);
+    const from = opening.current;
+    let result: R;
+    try {
+      const [screenshot_url, attachment_urls] = await Promise.all([
+        data.screenshot ? upload(data.screenshot) : Promise.resolve(null),
+        Promise.all(data.attachments.map((file) => upload(file))),
+      ]);
+      result = await create({
+        title: data.title.trim(),
+        body: data.body.trim() ? data.body : "",
+        category: data.category as FeedbackCategory,
+        context: feedbackContext({ user, attachUrl, url, environment, version }),
+        screenshot_url,
+        attachment_urls,
+      });
+    } catch (error) {
+      toast.error(errorMessage ? errorMessage(error, toastText.submitFailed) : toastText.submitFailed);
+      return;
+    } finally {
+      inFlight.current = false;
+      setSubmitting(false);
+    }
+    toast.success(toastText.submitted);
+    if (opening.current === from) setIsOpen(false);
+    onSubmitted?.(result);
+  };
+
+  const onCaptureScreenshot =
+    capture === false
+      ? undefined
+      : async () => {
+          try {
+            return await (capture ?? (() => captureAppScreenshot()))();
+          } catch {
+            toast.error(toastText.captureFailed);
+            return null;
+          }
+        };
+
+  const dialog = isOpen ? (
+    <FeedbackDialog
+      open
+      onClose={close}
+      categories={FEEDBACK_PICKABLE_CATEGORIES.map((value) => ({ value, label: categoryLabels[value] }))}
+      category={category}
+      onCategoryChange={(value) => setCategory(value as FeedbackCategory)}
+      submitting={submitting}
+      attachments="multiple"
+      maxAttachments={DEFAULT_MAX_ATTACHMENTS}
+      requireBody={false}
+      attachmentAccept={FEEDBACK_ATTACHMENT_ACCEPT}
+      onAttachmentError={(kind, info) =>
+        toast.error(
+          kind === "type"
+            ? toastText.attachmentUnsupported
+            : kind === "size"
+              ? toastText.attachmentTooLarge
+              : // More files at once than there was room for: the surplus was dropped, the
+                // rest kept. The count is how many fit, as keksdose says it.
+                toastText.attachmentTooMany(info.max ?? DEFAULT_MAX_ATTACHMENTS),
+        )
+      }
+      onCaptureScreenshot={onCaptureScreenshot}
+      onSubmit={submit}
+      contextSlot={<FeedbackContextBox user={user} url={url} attachUrl={attachUrl} onAttachUrlChange={setAttachUrl} />}
+    />
+  ) : null;
+
+  return { open, close, dialog };
+}

package/src/feedback/feedback-swipe.tsx

@@ -0,0 +1,170 @@
+import { Ban, Check, ChevronsRight } from "lucide-react";
+import type { SwipeAction } from "../components/swipeable-row";
+import type { MobileSwipeActions } from "../components/data-table";
+import { nextFeedbackStatus, type FeedbackStatus } from "./feedback-inbox";
+import type { FeedbackStatusLabels } from "./feedback-labels";
+import type { FeedbackStatusChange, FeedbackStatusRow } from "./feedback-status-undo";
+
+/**
+ * Swipes on the admin inbox's phone cards — §4.5 of the feedback contract, keksdose's
+ * (`feedback-page.tsx:990`, feedback #144 rework item 4: *"it is a queue, and triaging it
+ * one tap-into-the-row at a time is the slow way"*), for every app.
+ *
+ * - `advance` — one step along the chain (`nextFeedbackStatus`: OPEN → IN_PROGRESS →
+ *   IN_EVALUATION → DONE), labelled with the status it goes to;
+ * - `done` — straight to DONE, for a row that plainly needs no stop on the way;
+ * - `wont_do` — dismiss as WONT_DO.
+ *
+ * The same transitions the status column offers, so nothing is reachable by gesture that
+ * is not reachable by tap. keksdose lets the user rebind them (Settings → Interaction,
+ * feedback #404) and keeps that storage; kastlan and Kurvenschmiede take the default.
+ */
+export const FEEDBACK_SWIPE_ACTIONS = ["advance", "done", "wont_do"] as const;
+
+/** One of {@link FEEDBACK_SWIPE_ACTIONS}. */
+export type FeedbackSwipeAction = (typeof FEEDBACK_SWIPE_ACTIONS)[number];
+
+/**
+ * Which swipe does what — the same shape as 0.26's `TranslationReviewSwipeBinding`: per
+ * LOGICAL side an ordered ladder, index 0 at the first threshold, index 1 at the longer
+ * drag. `end` is a drag toward the reading end (right in a left-to-right page), `start`
+ * the other way. keksdose stores PHYSICAL `right` / `left` ladders and hands
+ * `{ end: right, start: left }`, as its translations page does
+ * (`translations-page.tsx:280`).
+ *
+ * The ids are typed loosely on purpose: a stored binding carries keksdose's `"none"`
+ * fillers and may carry an id from another version or another surface — they are
+ * dropped (see {@link feedbackSwipePlan}), so it is passed in without a cast.
+ */
+export interface FeedbackSwipeBinding {
+  /** A drag toward the reading START, nearest threshold first. */
+  start?: readonly (FeedbackSwipeAction | (string & {}))[];
+  /** A drag toward the reading END, nearest threshold first. */
+  end?: readonly (FeedbackSwipeAction | (string & {}))[];
+}
+
+/** keksdose's shipped binding (`swipe-prefs-store.ts:99`): toward the end advance, then
+ *  done on the longer drag; toward the start won't do. A settings page's reset goes here. */
+export const DEFAULT_FEEDBACK_SWIPE: FeedbackSwipeBinding = Object.freeze({
+  start: Object.freeze(["wont_do"] as const),
+  end: Object.freeze(["advance", "done"] as const),
+});
+
+export interface FeedbackSwipeOptions {
+  /** What a swipe commits through: the undoable change from `useFeedbackStatusUndo`, the
+   *  same one the status cell and the detail's pills use — so a swipe gets the same 8 s
+   *  "Set to …" toast with Undo as a tap (§4.5, §7.10, Marcel 2026-10-04; keksdose's
+   *  `changeStatusUndoably` on its swipes too). A swipe is the easiest status change to
+   *  make by accident. The plan calls it and nothing else, so the page owns the PATCH. */
+  change: FeedbackStatusChange;
+  /** The status names the panels show — `useFeedbackStatusLabels()`. The `done` panel
+   *  reads DONE's, `wont_do` WONT_DO's, `advance` the next status's. */
+  labels: FeedbackStatusLabels;
+}
+
+/** Where an action takes a row, or null when it would do nothing from there. */
+function targetOf(id: string, status: FeedbackStatus): FeedbackStatus | null {
+  switch (id) {
+    case "advance":
+      // Null at the chain's end (DONE) and off it (NEEDS_LIVE_TEST, POSTPONED, WONT_DO):
+      // "advance" has no meaning there, and a threshold that commits nothing is a trap.
+      return nextFeedbackStatus(status);
+    case "done":
+      return status === "DONE" ? null : "DONE";
+    case "wont_do":
+      return status === "WONT_DO" ? null : "WONT_DO";
+    default:
+      // "none", or an id this version does not know: an empty slot.
+      return null;
+  }
+}
+
+/** One action's panel. Each fill carries its text colour (0.26): the fills turn pastel
+ *  in dark mode, where SwipeableRow's default white text was unreadable. `--info` has no
+ *  contrast token, so `advance` writes in the surface colour — white on sky in light
+ *  mode, the dark page on the pale sky in dark (the translation list's reset does the
+ *  same on its grey). */
+function panel(
+  id: FeedbackSwipeAction,
+  target: FeedbackStatus,
+  row: FeedbackStatusRow,
+  { change, labels }: FeedbackSwipeOptions,
+): SwipeAction {
+  const onCommit = () => change(row, target);
+  switch (id) {
+    case "advance":
+      return {
+        onCommit,
+        label: labels[target],
+        icon: <ChevronsRight className="size-4" aria-hidden />,
+        className: "bg-[var(--info)] text-[var(--info-contrast)]",
+        armedClassName: "bg-[var(--info)] text-[var(--info-contrast)]",
+      };
+    case "done":
+      return {
+        onCommit,
+        label: labels.DONE,
+        icon: <Check className="size-4" aria-hidden />,
+        className: "bg-[var(--success)] text-[var(--success-contrast)]",
+        armedClassName: "bg-[var(--success)] text-[var(--success-contrast)]",
+      };
+    case "wont_do":
+      return {
+        onCommit,
+        label: labels.WONT_DO,
+        icon: <Ban className="size-4" aria-hidden />,
+        className: "bg-[var(--danger)] text-[var(--danger-contrast)]",
+        armedClassName: "bg-[var(--danger-hover)] text-[var(--danger-contrast)]",
+      };
+  }
+}
+
+/**
+ * The binding resolved against one row — what DataTable's `mobileSwipeActions` returns
+ * for it, or `null` when the row offers no swipe at all:
+ *
+ * ```tsx
+ * const changeStatus = useFeedbackStatusUndo(update.mutate);
+ * const statusLabels = useFeedbackStatusLabels();
+ * <DataTable
+ *   mobileSwipeActions={isAdmin && !mine
+ *     ? (row) => feedbackSwipePlan(DEFAULT_FEEDBACK_SWIPE, row, { change: changeStatus, labels: statusLabels })
+ *     : undefined}
+ * />
+ * ```
+ *
+ * Modelled on 0.26's `translationReviewSwipePlan` (keksdose's `resolveSwipePlan`): an
+ * action the row cannot take DROPS OUT and the ladder closes up behind it, so the second
+ * stage becomes the first instead of the side going dead behind an unreachable stage:
+ *
+ * - `advance` on DONE and off the chain (NEEDS_LIVE_TEST, POSTPONED, WONT_DO);
+ * - `done` on DONE, `wont_do` on WONT_DO;
+ * - `"none"` and any id this version does not know;
+ * - a later stage that lands where an earlier one on the same side already does — the id
+ *   named twice, or `done` behind `advance` on IN_EVALUATION (both go to DONE): a longer
+ *   drag to the same effect would arm a threshold that adds nothing.
+ *
+ * Only what the ROW decides. Whether the page may write at all — the admin inbox, not
+ * `/my-feedback`; no write lock — is the caller's, by passing no `mobileSwipeActions`.
+ */
+export function feedbackSwipePlan(
+  binding: FeedbackSwipeBinding,
+  row: FeedbackStatusRow,
+  options: FeedbackSwipeOptions,
+): MobileSwipeActions | null {
+  const side = (ids: FeedbackSwipeBinding["start"]): SwipeAction[] => {
+    const reached = new Set<FeedbackStatus>();
+    const out: SwipeAction[] = [];
+    for (const id of ids ?? []) {
+      const target = targetOf(id, row.status);
+      if (target === null || reached.has(target)) continue;
+      reached.add(target);
+      out.push(panel(id as FeedbackSwipeAction, target, row, options));
+    }
+    return out;
+  };
+  const start = side(binding.start);
+  const end = side(binding.end);
+  if (start.length === 0 && end.length === 0) return null;
+  return { start, end };
+}