@eifi1/ui-kit 0.24.0 → 0.25.0

package/dist/components/translation-review.d.ts

@@ -27,6 +27,30 @@ import 'lucide-react';
  * write to the server's batch limit is the app's; the panel sends one call per action.
  */
 type MaybePromise = void | Promise<unknown>;
+/** What asked for a write — see {@link TranslationReviewSaveInfo}. */
+type TranslationReviewOrigin = "editor" | "row" | "swipe" | "group" | "selection" | "undo";
+/**
+ * The second argument of `onSave` and `onClear` (0.25): where the write came from, and
+ * whether the panel answers it with a toast of its own.
+ *
+ * WHY THE APP IS TOLD. keksdose and kastlan toast "Saved" from their mutation on every
+ * save. With {@link TranslationReviewPanelProps.undo} on, an approval is answered by the
+ * kit's Undo toast instead — and a reviewer swiping through a list then read two toasts
+ * per card. The app skips its own where `toasted` is true:
+ *
+ *     onSave={(writes, { toasted }) => save.mutateAsync({ items: writes.map(toApiWrite), quiet: toasted })}
+ *
+ * An app that ignores the argument keeps working; it only says "Saved" twice.
+ */
+interface TranslationReviewSaveInfo {
+    /** The open editor, a row's approve button, a swipe on a phone card, a group's
+     *  "Approve unreviewed", the selection's bulk bar, or an Undo pressed on the toast. */
+    origin: TranslationReviewOrigin;
+    /** The panel shows its own toast for this write (an approval's Undo toast). */
+    toasted: boolean;
+}
+/** How {@link TranslationReviewPanelProps.groupBy} names a row's group. */
+type TranslationReviewGroupBy = "namespace" | "source" | ((row: TranslationRow) => string);
 interface TranslationReviewPanelProps {
     /** One locale's rows, from `translationRows`. */
     rows: readonly TranslationRow[];
@@ -35,10 +59,12 @@ interface TranslationReviewPanelProps {
     /** The reference language's own name — the reference column's header. */
     referenceLabel: string;
     /** Store verdicts: one for an editor or a row's approve button, many for a bulk
-     *  approve. Left out (or `readOnly`): nothing can be changed. */
-    onSave?: (writes: TranslationReviewWrite[]) => MaybePromise;
-    /** Clear verdicts — back to unreviewed. Left out: no reset. */
-    onClear?: (keys: TranslationReviewKey[]) => MaybePromise;
+     *  approve. Left out (or `readOnly`): nothing can be changed. The second argument
+     *  says where the write came from ({@link TranslationReviewSaveInfo}). */
+    onSave?: (writes: TranslationReviewWrite[], info: TranslationReviewSaveInfo) => MaybePromise;
+    /** Clear verdicts — back to unreviewed. Left out: no reset, and an approval of a row
+     *  that had no verdict cannot be undone. */
+    onClear?: (keys: TranslationReviewKey[], info: TranslationReviewSaveInfo) => MaybePromise;
     /** A locale the viewer may read but not review: the rows and their verdicts, no
      *  actions, and a line saying so. */
     readOnly?: boolean;
@@ -58,9 +84,13 @@ interface TranslationReviewPanelProps {
     sourceLabels?: Readonly<Record<string, string>>;
     /**
      * Controlled filters — for an app that keeps them in the URL (keksdose's `?status=`,
-     * `?area=`, `?q=`). Whatever is left out is the panel's own. Pair with `onFilterChange`.
+     * `?ns=`, `?q=`). Whatever is left out is the panel's own. Pair with `onFilterChange`.
      */
     filter?: Partial<TranslationReviewFilter>;
+    /** Every filter, on every change — write them in ONE update: `useSearchParamsState`'s
+     *  setter takes this object as it is (`filter={filter} onFilterChange={setFilter}`).
+     *  Single `useSearchParamState` setters compose since 0.25; before, four in a row
+     *  clobbered each other (keksdose live #378). */
     onFilterChange?: (filter: TranslationReviewFilter) => void;
     /** The progress bar over the filters. Default true. */
     progress?: boolean;
@@ -72,6 +102,70 @@ interface TranslationReviewPanelProps {
     formatDate?: (iso: string) => string;
     /** Turns a callback's rejection into words. Default {@link TranslationReviewLabels.failed}. */
     formatError?: (error: unknown) => ReactNode;
+    /**
+     * Swipe the phone cards (0.25, keksdose live #377 — Marcel reviewing on a phone): toward
+     * the reading END to approve, toward the START for "Needs a change", which OPENS the
+     * editor with the cursor in the wording rather than sending the string back blind — a
+     * verdict without a note or a better wording tells whoever fixes it nothing. In a
+     * right-to-left page the two sides mirror with the reading direction.
+     *
+     * DataTable's swipe sides (`mobileSwipeActions`) on {@link SwipeableRow}: the same
+     * gesture, the same feedback, and the same keyboard path — every swipe is also a real
+     * button, read out and reachable by Tab, so the gesture is a shortcut and never the only
+     * way. A row has no swipe while the editor under it is open, while its own write is out,
+     * under a {@link WriteLockProvider} lock, in a `readOnly` locale, and toward "Approve"
+     * where there is nothing to approve (a missing string, an approved one). A reviewer
+     * limited to `areas` never sees a row outside them, so never swipes one.
+     *
+     * Off by default, so no existing page gains a gesture on the bump. Phones only; the
+     * desktop table keeps its approve button.
+     */
+    swipe?: boolean;
+    /**
+     * Answer every approval with the kit's Undo toast (`toast.undo`): a row's button, a
+     * swipe, the editor's Approve, a group's and the selection's bulk approve. Undo stores
+     * again what the rows said before ({@link reviewUndo}) — or clears them, for rows that
+     * had no verdict, which needs `onClear` (without it the toast reports and offers
+     * nothing). A batch has ONE Undo.
+     *
+     * Default: on with `swipe` or `groupBy` — the two ways to approve in one movement or many
+     * rows at once bring their way back — and off otherwise, so an existing page does not
+     * gain a toast on the bump. Needs the app's `<Toaster>`. Tell the app's own "Saved"
+     * toast apart with the `toasted` flag ({@link TranslationReviewSaveInfo}).
+     */
+    undo?: boolean;
+    /**
+     * Group the strings under a header per area (0.25, keksdose live #377: *"grouping to the
+     * translation review entries for faster reviewing"*): `"namespace"` — the row's
+     * `namespace`, which `translationRows` derives from the key (`budget`, `kit.dataTable`
+     * with keksdose's `namespaceOf`) — `"source"`, or a function of the row.
+     *
+     * Each group is a section with a heading ({@link groupHeadingAs}): its name, "n
+     * unreviewed / total", and "Approve unreviewed (n)", which approves the group's rows
+     * nobody has given a verdict ({@link unreviewedRows}) under the same rules as one
+     * approval — write lock, `readOnly`, one write at a time — with one Undo for the batch.
+     * A batch larger than `pageSize` asks first, inside the opened group: more than a page
+     * is more than the reviewer can have had on screen.
+     *
+     * WHAT IT MEANS FOR THE FILTERS, THE SORT AND THE PAGES. The filters narrow the rows
+     * first, then the rows are grouped: a header counts what the filters show in it (so
+     * "Approve unreviewed" never takes a row the reviewer filtered away), and an area with
+     * nothing left is not shown. Groups stand in the order their first string has in the
+     * reference; a column sort orders the rows INSIDE every group alike. Each group pages
+     * on its own, `pageSize` rows at a time — a header then always stands over its own
+     * rows, and paging one area does not move another — rather than one pager cutting
+     * through the headers. `storageKey` keeps persisting the ungrouped table only.
+     *
+     * Groups fold (each on its own, remembered while the panel lives). On a phone they
+     * start folded when there are several — the headers are then the area list, and the
+     * reviewer opens the one to work through; on a wide screen they start open.
+     */
+    groupBy?: TranslationReviewGroupBy;
+    /** A group's name. Default: `sourceLabels` for `groupBy="source"`, else the key. */
+    groupLabel?: (group: string) => string;
+    /** The level of the group headings. Default `h2`: the panel is a page's body, under
+     *  the page's `h1`. */
+    groupHeadingAs?: "h2" | "h3" | "h4";
     className?: string;
     labels?: Partial<TranslationReviewLabels>;
 }
@@ -87,8 +181,15 @@ interface TranslationReviewPanelProps {
  * Bulk approve takes the selected rows that are not approved yet and have a text:
  * approving an absent string says nothing, and re-approving one says it again. On a
  * phone the table has no checkboxes, so "Select all shown" selects what the filters
- * show — filter to `Unreviewed` in one area, read, select, approve.
+ * show — filter to `Unreviewed` in one area, read, select, approve. With `groupBy`, a
+ * group's own "Approve unreviewed" is the shorter way, and with `swipe` a card is approved
+ * by a swipe.
+ *
+ * The panel's writes go out ONE AT A TIME, in the order they were asked for: two writes on
+ * one locale's verdicts can answer out of order, and an Undo must not overtake the
+ * approval it takes back. A swipe on the next card while one is out is queued rather than
+ * refused — a reviewer swiping down a list is faster than the server.
  */
-declare function TranslationReviewPanel({ rows: rowsProp, localeLabel, referenceLabel, onSave, onClear, readOnly, areas, areaLabels, inArea, sourceLabels, filter: filterProp, onFilterChange, progress, pageSize, storageKey, formatDate, formatError, className, labels: labelsProp, }: TranslationReviewPanelProps): react.JSX.Element;
+declare function TranslationReviewPanel({ rows: rowsProp, localeLabel, referenceLabel, onSave, onClear, readOnly, areas, areaLabels, inArea, sourceLabels, filter: filterProp, onFilterChange, progress, pageSize, storageKey, formatDate, formatError, swipe, undo: undoProp, groupBy, groupLabel, groupHeadingAs, className, labels: labelsProp, }: TranslationReviewPanelProps): react.JSX.Element;
 
-export { TranslationReviewLabels, TranslationReviewPanel, type TranslationReviewPanelProps };
+export { type TranslationReviewGroupBy, TranslationReviewLabels, type TranslationReviewOrigin, TranslationReviewPanel, type TranslationReviewPanelProps, type TranslationReviewSaveInfo };