@eifi1/ui-kit 0.24.1 → 0.25.1

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,18 @@ 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`.
+     *
+     * A field passed here is the app's, and the control shows what the app says: one the app
+     * passes but does not write back from `onFilterChange` is a control that does nothing.
+     * A development build warns about that once per field (0.25.1, Kurvenschmiede); a field
+     * left out entirely is fine — the panel keeps it.
      */
     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 +107,101 @@ 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), and a folded group's
+     * rows are not rendered at all — only its header. Which groups start open is
+     * {@link defaultGroupsOpen}: by default, 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 — and on a wide screen they start open while that is cheap (see there).
+     */
+    groupBy?: TranslationReviewGroupBy;
+    /**
+     * Which groups start open under {@link groupBy} (0.25.1). A group the reviewer opens or
+     * folds keeps that; this is what every other group follows.
+     *
+     * - `"auto"` (default): on a phone, open when there is one group and folded when there
+     *   are several, as in 0.25.0. On a wide screen, open while opening every group renders
+     *   at most 100 rows (each group shows up to `pageSize` of them; the budget is one page
+     *   where `pageSize` is larger) — and folded above that, the headers then being the area
+     *   list, as on a phone.
+     * - `true`: every group starts open, on a phone too.
+     * - `false`: every group starts folded, on a wide screen too.
+     *
+     * WHY A BUDGET OF ROWS (keksdose, measured on 0.25.0): a wide screen opened EVERY group.
+     * keksdose's /translations has 122 areas and ~4700 strings — 122 tables and 2053 rows at
+     * once, ~46 000 elements, 5.2 s before the panel appeared and 2.5 s for a filter click
+     * to paint, against 50 rows and 0.34 s ungrouped; its page test went from 4 s to 146 s.
+     * kastlan (~31 areas, ~1300 rows open) and Kurvenschmiede (28, ~700) had the same page.
+     * What costs is the rows on screen, so the rule counts them rather than the groups:
+     * 100 rows is two of the panel's default pages — any one or two areas still open as
+     * before, however long, and so do a dozen small ones, or a search whose hits fall in
+     * many areas — while a whole catalogue starts as its list of areas: keksdose's shape
+     * in jsdom, 122 headers and ~2100 elements instead of ~44 000 (the ungrouped panel has
+     * ~1200). The rule follows the filters: narrow them and the groups open.
+     *
+     * A boolean rather than a controlled open state: the panel already keeps each group's
+     * own state, and an app that only wants "all open" or "all folded" should not have to
+     * keep a record of 122 flags to say it.
+     */
+    defaultGroupsOpen?: boolean | "auto";
+    /** 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 +217,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, defaultGroupsOpen, className, labels: labelsProp, }: TranslationReviewPanelProps): react.JSX.Element;
 
-export { TranslationReviewLabels, TranslationReviewPanel, type TranslationReviewPanelProps };
+export { type TranslationReviewGroupBy, TranslationReviewLabels, type TranslationReviewOrigin, TranslationReviewPanel, type TranslationReviewPanelProps, type TranslationReviewSaveInfo };