@svgrid/enterprise 3.1.21 → 3.1.23

package/dist/review/index.js

@@ -0,0 +1,36 @@
+/**
+ * @svgrid/enterprise/review - change review. Writes nobody typed (AI helper
+ * results, agent edits, imports, syncs) arrive as proposals held apart from
+ * the data, grouped by the transformation they apply, and are accepted or
+ * rejected a group at a time. Accepted values are written to the app's data,
+ * a cell that changed since the proposal was made is never overwritten, and
+ * every decision is one Ctrl+Z.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { SvGrid } from '@svgrid/grid'
+ *   import { createReview, reviewSmartFill, SvReviewPanel } from '@svgrid/enterprise/review'
+ *
+ *   let rows = $state(initialRows)
+ *   let api = $state()
+ *   const review = createReview({ api: () => api, setRows: (next) => (rows = next) })
+ * </script>
+ *
+ * <SvGrid data={rows} columns={review.columns(columns)} getRowId={(r) => r.id}
+ *   conditionalFormats={review.formats} onApiReady={(a) => (api = a)} />
+ * <SvReviewPanel {review} />
+ * ```
+ *
+ * Adds nothing to `@svgrid/grid`: the tint is `conditionalFormats`, the
+ * proposed value is a wrapped `cell`, the undo step is the public command
+ * context.
+ */
+export { createReview } from './model.svelte.js';
+export { createGridTools, registerWebMcpTools } from './agent.js';
+export { clusterProposals, showValue } from './cluster.js';
+export { sameValue, isBlank } from './equal.js';
+export { REVIEW_MESSAGES } from './messages.js';
+export { pendingFormats, PENDING_BG, PENDING_ICON, CONFLICT_BG, CONFLICT_ICON } from './formats.js';
+export { canGhost } from './ghost.js';
+export { fromSmartFill, fromClassify, fromRows, fromStaged, reviewSmartFill, reviewClassify, blankTargets } from './adapters.js';
+export { default as SvReviewPanel } from './SvReviewPanel.svelte';

package/dist/review/messages.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Every string change review shows: the panel, the group labels, the card and
+ * cell marks. English defaults; pass any subset as `createReview({ messages })`
+ * (and `<SvReviewPanel messages>` for one panel), unset keys stay English. The
+ * idiom of the grid's own `localization.text`: a flat map, `{name}`
+ * placeholders. Kept free of imports: the clustering uses it in plain Node.
+ */
+export declare const REVIEW_MESSAGES: {
+    title: string;
+    decided: string;
+    pendingInGroups: string;
+    pendingInOneGroup: string;
+    nothingPending: string;
+    inConflict: string;
+    acceptAll: string;
+    rejectAll: string;
+    acceptRuleGroups: string;
+    resolveFirst: string;
+    onlyRowsWithChanges: string;
+    confirmAcceptGroup: string;
+    confirmRejectGroup: string;
+    confirmAcceptAll: string;
+    confirmRejectAll: string;
+    confirmAcceptRules: string;
+    confirmYes: string;
+    cancel: string;
+    conflictsTitle: string;
+    conflictCell: string;
+    keep: string;
+    badgeRule: string;
+    hintRule: string;
+    hintMapping: string;
+    hintFill: string;
+    hintConstant: string;
+    hintEach: string;
+    oneChange: string;
+    changes: string;
+    sure: string;
+    sureRange: string;
+    accept: string;
+    reject: string;
+    acceptGroupLabel: string;
+    rejectGroupLabel: string;
+    from: string;
+    otherValues: string;
+    sampleOf: string;
+    everyChange: string;
+    firstN: string;
+    showRow: string;
+    rowId: string;
+    acceptOne: string;
+    rejectOne: string;
+    showAll: string;
+    keysHint: string;
+    showInGrid: string;
+    nextInGrid: string;
+    hiddenRows: string;
+    allReviewed: string;
+    reviewedSummary: string;
+    reviewedStale: string;
+    noProposals: string;
+    noProposalsHint: string;
+    notWritten: string;
+    rowField: string;
+    decidedLabel: string;
+    noteCellChanged: string;
+    noteRowGone: string;
+    noteRowEditing: string;
+    noteGridNotReady: string;
+    noteSavedStale: string;
+    noteConflict: string;
+    undoHint: string;
+    announceAccepted: string;
+    announceRejected: string;
+    announceStale: string;
+    announceSkipped: string;
+    announceCommittedStale: string;
+    announceNotSaved: string;
+    announceNothing: string;
+    undoFailed: string;
+    redoFailed: string;
+    cardProposed: string;
+    proposes: string;
+    nowValue: string;
+    empty: string;
+    labelWhitespace: string;
+    labelCase: string;
+    caseUpper: string;
+    caseLower: string;
+    caseTitle: string;
+    caseMixed: string;
+    labelToNumber: string;
+    labelDates: string;
+    datesAsDates: string;
+    labelShape: string;
+    labelPunct: string;
+    punctRemove: string;
+    punctAdd: string;
+    punctSpaces: string;
+    labelDivide: string;
+    labelMultiply: string;
+    labelMapping: string;
+    mappingValues: string;
+    labelFill: string;
+    labelFillVarious: string;
+    labelConstant: string;
+    labelUnpatterned: string;
+};
+export type ReviewMessages = typeof REVIEW_MESSAGES;
+/** English, with `overrides` laid over it (blank values ignored). */
+export declare function reviewMessages(...overrides: Array<Partial<ReviewMessages> | null | undefined>): ReviewMessages;
+/** A template with its `{name}` placeholders filled. */
+export declare function fill(template: string, vars: Record<string, string | number>): string;

package/dist/review/messages.js

@@ -0,0 +1,135 @@
+/**
+ * Every string change review shows: the panel, the group labels, the card and
+ * cell marks. English defaults; pass any subset as `createReview({ messages })`
+ * (and `<SvReviewPanel messages>` for one panel), unset keys stay English. The
+ * idiom of the grid's own `localization.text`: a flat map, `{name}`
+ * placeholders. Kept free of imports: the clustering uses it in plain Node.
+ */
+export const REVIEW_MESSAGES = {
+    // Panel header
+    title: 'Review changes',
+    decided: '{decided} of {total} decided',
+    pendingInGroups: '{count} pending in {groups} groups',
+    pendingInOneGroup: '{count} pending in 1 group',
+    nothingPending: 'Nothing pending',
+    inConflict: ', {count} in conflict',
+    acceptAll: 'Accept all',
+    rejectAll: 'Reject all',
+    acceptRuleGroups: 'Accept rule groups ({count})',
+    resolveFirst: 'Resolve the conflicts before accepting everything.',
+    onlyRowsWithChanges: 'Only rows with changes',
+    // Confirm
+    confirmAcceptGroup: 'Accept {count} changes: {label}?',
+    confirmRejectGroup: 'Reject {count} changes: {label}?',
+    confirmAcceptAll: 'Accept all {count} changes?',
+    confirmRejectAll: 'Reject all {count} changes?',
+    confirmAcceptRules: 'Accept {groups} rule groups ({count} changes)?',
+    confirmYes: 'Yes, {count}',
+    cancel: 'Cancel',
+    // Conflicts
+    conflictsTitle: 'Two sources disagree',
+    conflictCell: '{row}, {field}: now {value}',
+    keep: 'Keep {value}',
+    // Groups
+    badgeRule: 'Rule',
+    hintRule: 'Every change in this group follows the rule.',
+    hintMapping: 'Check the mapping before accepting.',
+    hintFill: 'Check the sample: the least sure ones come first.',
+    hintConstant: 'Many different values set to one: check what they were.',
+    hintEach: 'No shared pattern: look at each change.',
+    oneChange: '{count} change',
+    changes: '{count} changes',
+    sure: '{pct} sure',
+    sureRange: '{min} to {avg} sure',
+    accept: 'Accept',
+    reject: 'Reject',
+    acceptGroupLabel: 'Accept {count}: {label}',
+    rejectGroupLabel: 'Reject {count}: {label}',
+    from: 'From',
+    otherValues: 'other values',
+    sampleOf: 'Sample of {count}',
+    everyChange: 'Every change',
+    firstN: 'First {count}',
+    showRow: 'Show {row} in the grid',
+    rowId: 'Row {row}',
+    acceptOne: 'Accept this change',
+    rejectOne: 'Reject this change',
+    showAll: 'Show all {count}',
+    keysHint: 'J / K move between groups, Enter opens one, A accepts it, R rejects it.',
+    showInGrid: 'Show in grid',
+    nextInGrid: 'Next in grid',
+    hiddenRows: '{count} hidden by filters or grouping',
+    // Empty and done
+    allReviewed: 'All {count} reviewed',
+    reviewedSummary: '{accepted} accepted, {rejected} rejected',
+    reviewedStale: ', {count} not written because the cell changed',
+    noProposals: 'No proposals yet',
+    noProposalsHint: 'Edits an agent, an import or an AI helper proposes show up here, grouped by what they change.',
+    notWritten: '{count} not written',
+    rowField: '{row}, {field}',
+    decidedLabel: 'Decided',
+    // Why a proposal was not written or is waiting (shown in the panel)
+    noteCellChanged: 'the cell changed after this was proposed',
+    noteRowGone: 'the row no longer exists',
+    noteRowEditing: 'the row is being edited',
+    noteGridNotReady: 'the grid is not ready',
+    noteSavedStale: 'saved, but the cell changed before it was written here',
+    noteConflict: 'another source proposed a different value',
+    undoHint: 'Ctrl+Z in the grid undoes the last decision.',
+    // Announced after a decision
+    announceAccepted: '{count} accepted',
+    announceRejected: '{count} rejected',
+    announceStale: '{count} not written: the cell changed',
+    announceSkipped: '{count} left pending',
+    announceCommittedStale: '{count} saved but not shown: the cell changed while saving',
+    announceNotSaved: 'not saved: {error}',
+    announceNothing: 'Nothing to decide',
+    undoFailed: 'Undo not saved: {error}',
+    redoFailed: 'Redo not saved: {error}',
+    // Marks
+    cardProposed: '{count} proposed',
+    proposes: '{source} proposes {value}',
+    nowValue: 'Now: {value}',
+    empty: '(empty)',
+    // Group labels ({field} is the column header)
+    labelWhitespace: 'Trim spaces in {field}',
+    labelCase: 'Change {field} to {case}',
+    caseUpper: 'UPPER CASE',
+    caseLower: 'lower case',
+    caseTitle: 'Title Case',
+    caseMixed: 'a different case',
+    labelToNumber: 'Convert {field} text to numbers',
+    labelDates: 'Reformat {field} dates as {shape}',
+    datesAsDates: 'dates',
+    labelShape: 'Reformat {field} as {shape}',
+    labelPunct: '{change} in {field}',
+    punctRemove: 'remove {chars}',
+    punctAdd: 'add {chars}',
+    punctSpaces: 'spaces',
+    labelDivide: 'Divide {field} by {n}',
+    labelMultiply: 'Multiply {field} by {n}',
+    labelMapping: '{field}: {from} → {to}',
+    mappingValues: '{count} values',
+    labelFill: 'Fill empty {field} with {value}',
+    labelFillVarious: 'Fill empty {field} (different values)',
+    labelConstant: 'Set {field} to {value}',
+    labelUnpatterned: '{field}: no shared pattern',
+};
+/** English, with `overrides` laid over it (blank values ignored). */
+export function reviewMessages(...overrides) {
+    const out = { ...REVIEW_MESSAGES };
+    for (const o of overrides) {
+        if (!o)
+            continue;
+        for (const k in o) {
+            const v = o[k];
+            if (v != null && v !== '')
+                out[k] = v;
+        }
+    }
+    return out;
+}
+/** A template with its `{name}` placeholders filled. */
+export function fill(template, vars) {
+    return template.replace(/\{(\w+)\}/g, (whole, key) => (key in vars ? String(vars[key]) : whole));
+}

package/dist/review/model.svelte.d.ts

@@ -0,0 +1,262 @@
+/**
+ * A change review: proposals held apart from the grid's data until a person
+ * accepts them, grouped for review, written to the app's data on accept, and
+ * undone with one Ctrl+Z per decision.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createReview, SvReviewPanel } from '@svgrid/enterprise/review'
+ *   let orders = $state(initial)
+ *   let api = $state()
+ *   const review = createReview({ api: () => api, setRows: (next) => (orders = next) })
+ *   review.add({ source: { kind: 'agent', id: 'cleanup', label: 'Cleanup agent' }, proposals })
+ * </script>
+ *
+ * <SvGrid data={orders} columns={review.columns(columns)} getRowId={(r) => r.id}
+ *   conditionalFormats={review.formats} onApiReady={(a) => (api = a)} />
+ * <SvReviewPanel {review} />
+ * ```
+ *
+ * Why the app's data and not the grid's writers: `api.setCellValue` and the
+ * command context write by view index into the grid's own copy, which the
+ * next `data` prop discards. Reads go through `api.getData()` instead, which
+ * includes the grid's own writes (paste, fill, addRows), so `next` carries
+ * them forward. `setRows` must apply synchronously.
+ */
+import type { ConditionalFormat, SvGridApi } from '@svgrid/grid';
+import { type ClusterOptions } from './cluster.js';
+import { type ReviewMessages } from './messages.js';
+import type { ChangeSet, Proposal, ProposalGroup, ProposalInput, ProposalSource } from './types.js';
+/** The part of the grid api a review uses. Any `SvGridApi` satisfies it. */
+export type ReviewGridApi = Pick<SvGridApi<any, any>, 'getData' | 'getOption' | 'getActiveCell' | 'getRowId' | 'getColumns' | 'getCommandContext' | 'stopEditing' | 'scrollToRow' | 'getDisplayedRows' | 'getAdvancedFilter' | 'setAdvancedFilter' | 'getRowPosition' | 'getPageInfo' | 'setPage' | 'getState'>;
+export type ReviewOptions<TData> = {
+    /** The grid api, or a getter for it (it is bound after mount). */
+    api: ReviewGridApi | (() => ReviewGridApi | undefined | null);
+    /** Replace the app's rows. Required unless `server` is set. Must apply synchronously. */
+    setRows?: (next: TData[]) => void;
+    /**
+     * Server row model: the controller passed to the grid as `rowModel`.
+     * Accept and undo commit through `onCommit` and then refresh it.
+     */
+    server?: {
+        refresh(): void;
+    };
+    /** Persist accepted values. Reject (throw) to keep them pending. Required with `server`. */
+    onCommit?: (accepted: Proposal[]) => void | Promise<void>;
+    /** Who decides, stamped on each decided proposal. */
+    user?: string;
+    cluster?: ClusterOptions;
+    /** Wording of everything the review shows (panel, group labels, marks); English by default. */
+    messages?: Partial<ReviewMessages>;
+    /**
+     * Called after every decision, its undo and its redo, with copies of the
+     * proposals it moved. Write these to an audit log of your own.
+     */
+    onDecision?: (decision: ReviewDecision) => void;
+    /**
+     * Called as accepted values (or an undo / redo of them) are written, with
+     * the proposals and the new rows just before they go to `setRows`, so
+     * bookkeeping that edits a row lands in the same write. SvGrid Base stamps
+     * "last modified" and notes the record's activity with
+     * `baseReviewApplied(api)` from `@svgrid/enterprise/base`. With a server
+     * row model there are no rows to edit: `rows` is undefined.
+     */
+    onApply?: (applied: Proposal[], how: 'accept' | 'undo' | 'redo', rows?: TData[]) => void;
+    /**
+     * An undo or redo whose `onCommit` failed: nothing was written and the
+     * decision stands. Also kept as `review.lastError`, which the panel announces.
+     */
+    onError?: (error: unknown, during: 'undo' | 'redo') => void;
+    /**
+     * What names a row on the panel's lines, such as its company, so a reviewer
+     * knows whose record a change is in. Default: the row's first visible text
+     * column, left out when that column is the one the change is to.
+     */
+    rowLabel?: (row: TData) => string | null | undefined;
+};
+export type ReviewDecision = {
+    action: 'accept' | 'reject' | 'undo' | 'redo';
+    /** For undo / redo: which decision was undone or redone. */
+    of?: 'accept' | 'reject';
+    proposals: Proposal[];
+    by?: string;
+    at: number;
+};
+export type ReviewOutcome = {
+    accepted: string[];
+    rejected: string[];
+    /** The cell changed since the proposal was made, or its row is gone. Never written. */
+    stale: string[];
+    /** Left pending: the row is being edited, the proposal is already being accepted, or the grid is not ready. */
+    skipped: string[];
+    /**
+     * Saved by `onCommit`, then not written here because the cell changed while
+     * it was saving. The backend holds the proposed value; reload or save the
+     * cell's value back.
+     */
+    committedStale: string[];
+    /** What `onCommit` threw; nothing was written and the proposals stay pending. */
+    error?: unknown;
+};
+export type AddInput = {
+    source: ProposalSource;
+    title?: string;
+    id?: string;
+    proposals: ReadonlyArray<ProposalInput>;
+};
+export type ReviewJSON = {
+    v: 1;
+    sets: ChangeSet[];
+};
+export type Review<TData = unknown> = ReturnType<typeof createReview<TData>>;
+export declare function createReview<TData = unknown>(opts: ReviewOptions<TData>): {
+    readonly version: number;
+    /** The wording in effect: English with `messages` laid over it. */
+    messages: {
+        title: string;
+        decided: string;
+        pendingInGroups: string;
+        pendingInOneGroup: string;
+        nothingPending: string;
+        inConflict: string;
+        acceptAll: string;
+        rejectAll: string;
+        acceptRuleGroups: string;
+        resolveFirst: string;
+        onlyRowsWithChanges: string;
+        confirmAcceptGroup: string;
+        confirmRejectGroup: string;
+        confirmAcceptAll: string;
+        confirmRejectAll: string;
+        confirmAcceptRules: string;
+        confirmYes: string;
+        cancel: string;
+        conflictsTitle: string;
+        conflictCell: string;
+        keep: string;
+        badgeRule: string;
+        hintRule: string;
+        hintMapping: string;
+        hintFill: string;
+        hintConstant: string;
+        hintEach: string;
+        oneChange: string;
+        changes: string;
+        sure: string;
+        sureRange: string;
+        accept: string;
+        reject: string;
+        acceptGroupLabel: string;
+        rejectGroupLabel: string;
+        from: string;
+        otherValues: string;
+        sampleOf: string;
+        everyChange: string;
+        firstN: string;
+        showRow: string;
+        rowId: string;
+        acceptOne: string;
+        rejectOne: string;
+        showAll: string;
+        keysHint: string;
+        showInGrid: string;
+        nextInGrid: string;
+        hiddenRows: string;
+        allReviewed: string;
+        reviewedSummary: string;
+        reviewedStale: string;
+        noProposals: string;
+        noProposalsHint: string;
+        notWritten: string;
+        rowField: string;
+        decidedLabel: string;
+        noteCellChanged: string;
+        noteRowGone: string;
+        noteRowEditing: string;
+        noteGridNotReady: string;
+        noteSavedStale: string;
+        noteConflict: string;
+        undoHint: string;
+        announceAccepted: string;
+        announceRejected: string;
+        announceStale: string;
+        announceSkipped: string;
+        announceCommittedStale: string;
+        announceNotSaved: string;
+        announceNothing: string;
+        undoFailed: string;
+        redoFailed: string;
+        cardProposed: string;
+        proposes: string;
+        nowValue: string;
+        empty: string;
+        labelWhitespace: string;
+        labelCase: string;
+        caseUpper: string;
+        caseLower: string;
+        caseTitle: string;
+        caseMixed: string;
+        labelToNumber: string;
+        labelDates: string;
+        datesAsDates: string;
+        labelShape: string;
+        labelPunct: string;
+        punctRemove: string;
+        punctAdd: string;
+        punctSpaces: string;
+        labelDivide: string;
+        labelMultiply: string;
+        labelMapping: string;
+        mappingValues: string;
+        labelFill: string;
+        labelFillVarious: string;
+        labelConstant: string;
+        labelUnpatterned: string;
+    };
+    /** The last undo or redo whose save failed, or null. */
+    readonly lastError: {
+        error: unknown;
+        during: "undo" | "redo";
+        at: number;
+    } | null;
+    add: (input: AddInput) => ChangeSet;
+    get: (id: string) => Proposal | undefined;
+    proposals: () => Proposal[];
+    /** What names the proposal's row (`rowLabel`), or null. */
+    rowLabel: (p: Proposal) => string | null;
+    /** A field's column header, as the group labels show it. */
+    fieldLabel: (field: string) => string;
+    pending: () => Proposal[];
+    conflicts: () => Proposal[];
+    groups: () => ProposalGroup[];
+    pendingFor: (rowId: string, field: string) => Proposal | undefined;
+    accept: (ids: ReadonlyArray<string>) => Promise<ReviewOutcome>;
+    reject: (ids: ReadonlyArray<string>) => ReviewOutcome;
+    acceptGroup: (key: string, shownIds: ReadonlyArray<string>) => Promise<ReviewOutcome>;
+    rejectGroup: (key: string, shownIds: ReadonlyArray<string>) => ReviewOutcome;
+    resolveConflict: (keepId: string) => void;
+    readonly formats: ConditionalFormat<any>[];
+    columns: <C extends ReadonlyArray<any>>(cols: C) => C;
+    reveal: (ids: ReadonlyArray<string>, fromId?: string) => {
+        id: string | null;
+        hidden: number;
+    };
+    showPendingOnly: (on: boolean) => void;
+    /** On while our condition is in the grid's advanced filter (the grid's own Clear takes it out too). */
+    readonly pendingOnly: boolean;
+    toJSON: (opts?: {
+        setIds?: ReadonlyArray<string>;
+    }) => ReviewJSON;
+    load: (json: ReviewJSON) => {
+        dropped: number;
+    };
+    merge: (json: ReviewJSON) => {
+        dropped: number;
+    };
+    log: () => Proposal[];
+    revertSet: (setId: string) => ChangeSet | null;
+    sets: () => Array<Omit<ChangeSet, "proposals"> & {
+        count: number;
+    }>;
+    clear: () => void;
+};