logisheets 1.1.0 → 1.2.0

package/dist/src/api/author.d.ts

@@ -0,0 +1,41 @@
+import { AuthorInput } from '../bindings';
+/**
+ * A person the host knows about — the comment author or an `@mention` target.
+ *
+ * `displayName` is always present. `userId` + `providerId` are the enterprise
+ * directory hooks: enterprise builds fill them from their corporate user
+ * system (e.g. `providerId: 'AD'`), while the open-source `src` app leaves them
+ * unset and only supplies a typed-in `displayName`.
+ *
+ * This is structurally the generated {@link AuthorInput} payload shape, re-aliased
+ * here so host code can depend on the concept without importing a payload type.
+ */
+export type Author = AuthorInput;
+/**
+ * The single seam an enterprise deployment overrides to wire LogiSheets
+ * comments into its user directory.
+ *
+ * - `getCurrentAuthor` resolves who is authoring a comment right now.
+ * - `searchUsers` backs `@mention` autocomplete.
+ *
+ * The Rust core stays identity-provider agnostic: it only ever stores the
+ * `Author` records this service produces. Nothing in the engine calls a
+ * directory — all remote calls live behind an implementation of this interface.
+ */
+export interface AuthorService {
+    getCurrentAuthor(): Promise<Author>;
+    searchUsers(query: string): Promise<Author[]>;
+}
+/**
+ * Default {@link AuthorService} for the open-source `src` app: the author types
+ * their own name and there is no directory to search. Enterprise builds inject
+ * their own implementation instead of using this.
+ */
+export declare class DefaultAuthorService implements AuthorService {
+    constructor(author?: Author);
+    /** Update the manually-entered author (e.g. from a name input field). */
+    setAuthor(author: Author): void;
+    getCurrentAuthor(): Promise<Author>;
+    searchUsers(_query: string): Promise<Author[]>;
+    private _author;
+}

package/dist/src/api/author.js

@@ -0,0 +1,22 @@
+/**
+ * Default {@link AuthorService} for the open-source `src` app: the author types
+ * their own name and there is no directory to search. Enterprise builds inject
+ * their own implementation instead of using this.
+ */
+export class DefaultAuthorService {
+    constructor(author = { displayName: '' }) {
+        this._author = author;
+    }
+    /** Update the manually-entered author (e.g. from a name input field). */
+    setAuthor(author) {
+        this._author = author;
+    }
+    async getCurrentAuthor() {
+        return this._author;
+    }
+    // No directory in the open-source build — `@mention` autocomplete is empty.
+    async searchUsers(_query) {
+        return [];
+    }
+    _author;
+}

package/dist/src/api/index.d.ts

@@ -1,5 +1,7 @@
 export * from './workbook';
 export * from './worksheet';
+export { DefaultAuthorService } from './author';
+export type { Author, AuthorService } from './author';
 export { CalcException, CustomFunc, Calculator } from './calculator';
 export type { Executor } from './calculator';
 export * from './cell';

package/dist/src/api/index.js

@@ -1,5 +1,6 @@
 export * from './workbook';
 export * from './worksheet';
+export { DefaultAuthorService } from './author';
 export { CustomFunc, Calculator } from './calculator';
 export * from './cell';
 export { CraftCalc, acquireCraftCalc } from './craft-calc';

package/dist/src/api/workbook.d.ts

@@ -1,8 +1,9 @@
-import { ActionEffect, BlockField, BlockInfo, FormulaDisplayInfo, ShadowCellInfo, SheetCellId, SheetInfo, SaveFileResult, AppData, CellInfo, CellCoordinateWithSheet, Transaction, GetBlockValuesParams, GetCellIdParams, GetShadowCellIdParams, GetShadowCellIdsParams, GetAvailableBlockIdParams, TempStatusDiff, BlockDataRow } from '../bindings';
+import { ActionEffect, BlockField, BlockInfo, FormulaDisplayInfo, ShadowCellInfo, SheetCellId, SheetInfo, SaveFileResult, AppData, CellInfo, CellCoordinateWithSheet, Transaction, GetBlockValuesParams, GetCellIdParams, GetShadowCellIdParams, GetShadowCellIdsParams, GetAvailableBlockIdParams, TempStatusDiff, BlockDataRow, CommentMention } from '../bindings';
 import { ColId, RowId } from '../types';
 import { Worksheet } from './worksheet';
 import { CustomFunc } from './calculator';
 import { Result } from './utils';
+import { Author } from './author';
 export type ReturnCode = number;
 export type Callback = () => void;
 export type CellIdCallback = (cellId: SheetCellId) => void;
@@ -17,6 +18,56 @@ export declare class Workbook {
      * It is caller's responsibility to store the block id.
      */
     createBlockForNewCraft(sheetIdx: number, masterRow: number, masterCol: number, rowCnt: number, colCnt: number): Result<number>;
+    /**
+     * Add a comment (a new root thread, or a reply when `parentId` is given) to
+     * a cell. `author` and any `mentions[].author` are identities resolved by
+     * the host's {@link AuthorService}; the core dedupes them into stable
+     * persons. The note id (GUID) and timestamp are generated here and the id
+     * is returned so the host can later edit / reply to / delete this note.
+     */
+    addComment(p: {
+        sheetIdx: number;
+        row: number;
+        col: number;
+        author: Author;
+        content: string;
+        mentions?: readonly CommentMention[];
+        parentId?: string;
+        undoable?: boolean;
+    }): {
+        commentId: string;
+        effect: ActionEffect;
+    };
+    /** Replace an existing note's text + mentions. */
+    editComment(p: {
+        sheetIdx: number;
+        commentId: string;
+        content: string;
+        mentions?: readonly CommentMention[];
+        undoable?: boolean;
+    }): ActionEffect;
+    /**
+     * Delete a note. Deleting a thread's root note removes the whole thread
+     * (root + all replies).
+     */
+    deleteComment(p: {
+        sheetIdx: number;
+        commentId: string;
+        undoable?: boolean;
+    }): ActionEffect;
+    /** Mark a comment thread resolved / reopened. */
+    resolveComment(p: {
+        sheetIdx: number;
+        commentId: string;
+        resolved: boolean;
+        undoable?: boolean;
+    }): ActionEffect;
+    /**
+     * Pre-register (or refresh) a directory person so they can be `@mentioned`
+     * before they've authored anything. Typically fed from an enterprise
+     * {@link AuthorService.searchUsers} result.
+     */
+    upsertPerson(author: Author): ActionEffect;
     undo(): boolean;
     redo(): boolean;
     registerCellUpdatedCallback(callback: Callback): void;

package/dist/src/api/workbook.js

@@ -9,6 +9,11 @@ function rpc(method, params, bookId
     const msg = params === undefined ? method : { method, value: params };
     return handle(msg, bookId ?? null);
 }
+// GUID for comment / thread ids, wrapped in braces to match the OOXML
+// threaded-comment convention (`{XXXX-...}`).
+function newGuid() {
+    return `{${crypto.randomUUID()}}`;
+}
 export class Workbook {
     constructor() {
         this._id = rpc('newWorkbook');
@@ -66,6 +71,100 @@ export class Workbook {
         }
         return id;
     }
+    /**
+     * Add a comment (a new root thread, or a reply when `parentId` is given) to
+     * a cell. `author` and any `mentions[].author` are identities resolved by
+     * the host's {@link AuthorService}; the core dedupes them into stable
+     * persons. The note id (GUID) and timestamp are generated here and the id
+     * is returned so the host can later edit / reply to / delete this note.
+     */
+    addComment(p) {
+        const commentId = newGuid();
+        const effect = this.execTransaction({
+            payloads: [
+                {
+                    type: 'addComment',
+                    value: {
+                        sheetIdx: p.sheetIdx,
+                        row: p.row,
+                        col: p.col,
+                        commentId,
+                        parentId: p.parentId,
+                        author: p.author,
+                        dt: new Date().toISOString(),
+                        content: p.content,
+                        mentions: p.mentions ?? [],
+                    },
+                },
+            ],
+            undoable: p.undoable ?? true,
+            temp: false,
+        });
+        return { commentId, effect };
+    }
+    /** Replace an existing note's text + mentions. */
+    editComment(p) {
+        return this.execTransaction({
+            payloads: [
+                {
+                    type: 'editComment',
+                    value: {
+                        sheetIdx: p.sheetIdx,
+                        commentId: p.commentId,
+                        content: p.content,
+                        mentions: p.mentions ?? [],
+                    },
+                },
+            ],
+            undoable: p.undoable ?? true,
+            temp: false,
+        });
+    }
+    /**
+     * Delete a note. Deleting a thread's root note removes the whole thread
+     * (root + all replies).
+     */
+    deleteComment(p) {
+        return this.execTransaction({
+            payloads: [
+                {
+                    type: 'deleteComment',
+                    value: { sheetIdx: p.sheetIdx, commentId: p.commentId },
+                },
+            ],
+            undoable: p.undoable ?? true,
+            temp: false,
+        });
+    }
+    /** Mark a comment thread resolved / reopened. */
+    resolveComment(p) {
+        return this.execTransaction({
+            payloads: [
+                {
+                    type: 'resolveComment',
+                    value: {
+                        sheetIdx: p.sheetIdx,
+                        commentId: p.commentId,
+                        resolved: p.resolved,
+                    },
+                },
+            ],
+            undoable: p.undoable ?? true,
+            temp: false,
+        });
+    }
+    /**
+     * Pre-register (or refresh) a directory person so they can be `@mentioned`
+     * before they've authored anything. Typically fed from an enterprise
+     * {@link AuthorService.searchUsers} result.
+     */
+    upsertPerson(author) {
+        return this.execTransaction({
+            payloads: [{ type: 'upsertPerson', value: author }],
+            undoable: false,
+            temp: false,
+        });
+    }
     undo() {
         const result = rpc('undo', undefined, this._id);
         if (result) {

package/dist/src/api/worksheet.d.ts

@@ -1,4 +1,4 @@
-import { BlockInfo, CellPosition, ColInfo, DisplayWindow, DisplayWindowWithStartPoint, RowInfo, Style, Value, CellInfo, SheetDimension, MergeCell, AppendixWithCell, ReproducibleCell, SheetCoordinate, CellInput } from '../bindings';
+import { BlockInfo, CellPosition, ColInfo, DisplayWindow, DisplayWindowWithStartPoint, RowInfo, Style, Value, CellInfo, SheetDimension, MergeCell, AppendixWithCell, ReproducibleCell, SheetCoordinate, CellInput, Comment } from '../bindings';
 import { Cell } from './cell';
 import { Result } from './utils';
 export declare class Worksheet {
@@ -55,6 +55,13 @@ export declare class Worksheet {
     getValue(rowIdx: number, colIdx: number): Result<Value>;
     getDiyCellIdWithBlockId(blockId: number, row: number, col: number): Result<number>;
     lookupAppendixUpward(blockId: number, row: number, col: number, craftId: string, tag: number): Result<AppendixWithCell>;
+    /**
+     * All comment threads on this sheet. Each `Comment` is a cell-anchored
+     * thread whose `notes` carry author identity, timestamp, text and resolved
+     * `@mentions`. Mutations go through the workbook transaction API
+     * (`addComment` / `editComment` / `deleteComment` / `resolveComment`).
+     */
+    getComments(): Result<Comment[]>;
     getFullyCoveredBlocks(rowIdx: number, colIdx: number, rowCnt: number, colCnt: number): Result<BlockInfo[]>;
     private _id;
     private _sheetId;

package/dist/src/api/worksheet.js

@@ -197,6 +197,15 @@ export class Worksheet {
             tag,
         }, this._id);
     }
+    /**
+     * All comment threads on this sheet. Each `Comment` is a cell-anchored
+     * thread whose `notes` carry author identity, timestamp, text and resolved
+     * `@mentions`. Mutations go through the workbook transaction API
+     * (`addComment` / `editComment` / `deleteComment` / `resolveComment`).
+     */
+    getComments() {
+        return rpc('getComments', { sheetIdx: this._sheetIdx }, this._id);
+    }
     getFullyCoveredBlocks(rowIdx, colIdx, rowCnt, colCnt) {
         return rpc('getFullyCoveredBlocks', {
             sheetId: this._sheetId,

package/dist/src/bindings/add_comment.d.ts

@@ -0,0 +1,44 @@
+import { AuthorInput } from './author_input';
+import { CommentMention } from './comment_mention';
+export interface AddComment {
+    sheetIdx: number;
+    row: number;
+    col: number;
+    commentId: string;
+    parentId?: string;
+    author: AuthorInput;
+    dt: string;
+    content: string;
+    mentions: readonly CommentMention[];
+}
+export declare class AddCommentBuilder {
+    private _sheetIdx;
+    private _row;
+    private _col;
+    private _commentId;
+    private _parentId?;
+    private _author;
+    private _dt;
+    private _content;
+    private _mentions;
+    sheetIdx(value: number): this;
+    row(value: number): this;
+    col(value: number): this;
+    commentId(value: string): this;
+    parentId(value: string): this;
+    author(value: AuthorInput): this;
+    dt(value: string): this;
+    content(value: string): this;
+    mentions(value: readonly CommentMention[]): this;
+    build(): {
+        sheetIdx: number;
+        row: number;
+        col: number;
+        commentId: string;
+        parentId: string | undefined;
+        author: AuthorInput;
+        dt: string;
+        content: string;
+        mentions: readonly CommentMention[];
+    };
+}

package/dist/src/bindings/add_comment.js

@@ -0,0 +1,66 @@
+export class AddCommentBuilder {
+    _sheetIdx;
+    _row;
+    _col;
+    _commentId;
+    _parentId;
+    _author;
+    _dt;
+    _content;
+    _mentions;
+    sheetIdx(value) {
+        this._sheetIdx = value;
+        return this;
+    }
+    row(value) {
+        this._row = value;
+        return this;
+    }
+    col(value) {
+        this._col = value;
+        return this;
+    }
+    commentId(value) {
+        this._commentId = value;
+        return this;
+    }
+    parentId(value) {
+        this._parentId = value;
+        return this;
+    }
+    author(value) {
+        this._author = value;
+        return this;
+    }
+    dt(value) {
+        this._dt = value;
+        return this;
+    }
+    content(value) {
+        this._content = value;
+        return this;
+    }
+    mentions(value) {
+        this._mentions = value;
+        return this;
+    }
+    build() {
+        if (this._sheetIdx === undefined)
+            throw new Error('missing sheetIdx');
+        if (this._row === undefined)
+            throw new Error('missing row');
+        if (this._col === undefined)
+            throw new Error('missing col');
+        if (this._commentId === undefined)
+            throw new Error('missing commentId');
+        if (this._author === undefined)
+            throw new Error('missing author');
+        if (this._dt === undefined)
+            throw new Error('missing dt');
+        if (this._content === undefined)
+            throw new Error('missing content');
+        if (this._mentions === undefined)
+            throw new Error('missing mentions');
+        return { sheetIdx: this._sheetIdx, row: this._row, col: this._col, commentId: this._commentId, parentId: this._parentId, author: this._author, dt: this._dt, content: this._content, mentions: this._mentions };
+    }
+}

package/dist/src/bindings/author_input.d.ts

@@ -0,0 +1,5 @@
+export interface AuthorInput {
+    displayName: string;
+    userId?: string;
+    providerId?: string;
+}

package/dist/src/bindings/author_input.js

@@ -0,0 +1 @@
+export {};

package/dist/src/bindings/comment.d.ts

@@ -1,6 +1,6 @@
+import { CommentNote } from './comment_note';
 export interface Comment {
     row: number;
     col: number;
-    author: string;
-    content: string;
+    notes: readonly CommentNote[];
 }

package/dist/src/bindings/comment_mention.d.ts

@@ -0,0 +1,7 @@
+import { AuthorInput } from './author_input';
+export interface CommentMention {
+    start: number;
+    len: number;
+    author: AuthorInput;
+    mentionId?: string;
+}

package/dist/src/bindings/comment_mention.js

@@ -0,0 +1 @@
+export {};

package/dist/src/bindings/comment_mention_info.d.ts

@@ -0,0 +1,6 @@
+import { CommentPerson } from './comment_person';
+export interface CommentMentionInfo {
+    start: number;
+    len: number;
+    person: CommentPerson;
+}

package/dist/src/bindings/comment_mention_info.js

@@ -0,0 +1 @@
+export {};

package/dist/src/bindings/comment_note.d.ts

@@ -0,0 +1,11 @@
+import { CommentMentionInfo } from './comment_mention_info';
+import { CommentPerson } from './comment_person';
+export interface CommentNote {
+    id: string;
+    author: CommentPerson;
+    dt: string;
+    content: string;
+    parentId?: string;
+    mentions: readonly CommentMentionInfo[];
+    resolved: boolean;
+}

package/dist/src/bindings/comment_note.js

@@ -0,0 +1 @@
+export {};

package/dist/src/bindings/comment_person.d.ts

@@ -0,0 +1,5 @@
+export interface CommentPerson {
+    displayName: string;
+    userId?: string;
+    providerId?: string;
+}

package/dist/src/bindings/comment_person.js

@@ -0,0 +1 @@
+export {};

package/dist/src/bindings/delete_comment.d.ts

@@ -0,0 +1,14 @@
+export interface DeleteComment {
+    sheetIdx: number;
+    commentId: string;
+}
+export declare class DeleteCommentBuilder {
+    private _sheetIdx;
+    private _commentId;
+    sheetIdx(value: number): this;
+    commentId(value: string): this;
+    build(): {
+        sheetIdx: number;
+        commentId: string;
+    };
+}

package/dist/src/bindings/delete_comment.js

@@ -0,0 +1,19 @@
+export class DeleteCommentBuilder {
+    _sheetIdx;
+    _commentId;
+    sheetIdx(value) {
+        this._sheetIdx = value;
+        return this;
+    }
+    commentId(value) {
+        this._commentId = value;
+        return this;
+    }
+    build() {
+        if (this._sheetIdx === undefined)
+            throw new Error('missing sheetIdx');
+        if (this._commentId === undefined)
+            throw new Error('missing commentId');
+        return { sheetIdx: this._sheetIdx, commentId: this._commentId };
+    }
+}

package/dist/src/bindings/edit_comment.d.ts

@@ -0,0 +1,23 @@
+import { CommentMention } from './comment_mention';
+export interface EditComment {
+    sheetIdx: number;
+    commentId: string;
+    content: string;
+    mentions: readonly CommentMention[];
+}
+export declare class EditCommentBuilder {
+    private _sheetIdx;
+    private _commentId;
+    private _content;
+    private _mentions;
+    sheetIdx(value: number): this;
+    commentId(value: string): this;
+    content(value: string): this;
+    mentions(value: readonly CommentMention[]): this;
+    build(): {
+        sheetIdx: number;
+        commentId: string;
+        content: string;
+        mentions: readonly CommentMention[];
+    };
+}

package/dist/src/bindings/edit_comment.js

@@ -0,0 +1,33 @@
+export class EditCommentBuilder {
+    _sheetIdx;
+    _commentId;
+    _content;
+    _mentions;
+    sheetIdx(value) {
+        this._sheetIdx = value;
+        return this;
+    }
+    commentId(value) {
+        this._commentId = value;
+        return this;
+    }
+    content(value) {
+        this._content = value;
+        return this;
+    }
+    mentions(value) {
+        this._mentions = value;
+        return this;
+    }
+    build() {
+        if (this._sheetIdx === undefined)
+            throw new Error('missing sheetIdx');
+        if (this._commentId === undefined)
+            throw new Error('missing commentId');
+        if (this._content === undefined)
+            throw new Error('missing content');
+        if (this._mentions === undefined)
+            throw new Error('missing mentions');
+        return { sheetIdx: this._sheetIdx, commentId: this._commentId, content: this._content, mentions: this._mentions };
+    }
+}

package/dist/src/bindings/edit_payload.d.ts

@@ -1,3 +1,4 @@
+import { AddComment } from './add_comment';
 import { BindFormSchema } from './bind_form_schema';
 import { BindRandomSchema } from './bind_random_schema';
 import { BlockInput } from './block_input';
@@ -16,9 +17,11 @@ import { CreateDiyCellById } from './create_diy_cell_by_id';
 import { CreateSheet } from './create_sheet';
 import { DeleteCols } from './delete_cols';
 import { DeleteColsInBlock } from './delete_cols_in_block';
+import { DeleteComment } from './delete_comment';
 import { DeleteRows } from './delete_rows';
 import { DeleteRowsInBlock } from './delete_rows_in_block';
 import { DeleteSheet } from './delete_sheet';
+import { EditComment } from './edit_comment';
 import { EphemeralCellInput } from './ephemeral_cell_input';
 import { EphemeralCellRemove } from './ephemeral_cell_remove';
 import { EphemeralCellStyleUpdate } from './ephemeral_cell_style_update';
@@ -38,6 +41,7 @@ import { RemoveDiyCellById } from './remove_diy_cell_by_id';
 import { ReorderBlockLines } from './reorder_block_lines';
 import { ReproduceCells } from './reproduce_cells';
 import { ResizeBlock } from './resize_block';
+import { ResolveComment } from './resolve_comment';
 import { RestoreCheckpoint } from './restore_checkpoint';
 import { SetColWidth } from './set_col_width';
 import { SetRowHeight } from './set_row_height';
@@ -48,6 +52,7 @@ import { SheetRename } from './sheet_rename';
 import { SplitMergedCells } from './split_merged_cells';
 import { UpsertFieldFormulas } from './upsert_field_formulas';
 import { UpsertFieldRenderInfo } from './upsert_field_render_info';
+import { UpsertPerson } from './upsert_person';
 export type EditPayload = {
     type: 'blockInput';
     value: BlockInput;
@@ -153,6 +158,21 @@ export type EditPayload = {
 } | {
     type: 'splitMergedCells';
     value: SplitMergedCells;
+} | {
+    type: 'addComment';
+    value: AddComment;
+} | {
+    type: 'editComment';
+    value: EditComment;
+} | {
+    type: 'deleteComment';
+    value: DeleteComment;
+} | {
+    type: 'resolveComment';
+    value: ResolveComment;
+} | {
+    type: 'upsertPerson';
+    value: UpsertPerson;
 } | {
     type: 'sheetRename';
     value: SheetRename;