@dxos/plugin-sheet 0.6.12 → 0.6.13-main.548ca8d

package/src/model/sheet-model.ts

@@ -0,0 +1,418 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type SimpleCellRange } from 'hyperformula/typings/AbsoluteCellRange';
+import { type SimpleCellAddress } from 'hyperformula/typings/Cell';
+import { type SimpleDate, type SimpleDateTime } from 'hyperformula/typings/DateTimeHelper';
+
+import { Event } from '@dxos/async';
+import { Resource } from '@dxos/context';
+import { getTypename } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { FieldValueType } from '@dxos/schema';
+
+import { DetailedCellError, ExportedCellChange } from '#hyperformula';
+import {
+  addressFromA1Notation,
+  addressToA1Notation,
+  type CellAddress,
+  type CellRange,
+  MAX_COLUMNS,
+  MAX_ROWS,
+} from '../defs';
+import { addressFromIndex, addressToIndex, initialize, insertIndices, ReadonlyException } from '../defs';
+import { type ComputeNode, type ComputeGraph, createSheetName, type ComputeNodeEvent } from '../graph';
+import { type CellScalarValue, type CellValue, type SheetType } from '../types';
+
+// Map sheet types to system types.
+const typeMap: Record<string, FieldValueType> = {
+  BOOLEAN: FieldValueType.Boolean,
+  NUMBER_RAW: FieldValueType.Number,
+  NUMBER_PERCENT: FieldValueType.Percent,
+  NUMBER_CURRENCY: FieldValueType.Currency,
+  NUMBER_DATETIME: FieldValueType.DateTime,
+  NUMBER_DATE: FieldValueType.Date,
+  NUMBER_TIME: FieldValueType.Time,
+};
+
+const getTopLeft = (range: CellRange): CellAddress => {
+  const to = range.to ?? range.from;
+  return { row: Math.min(range.from.row, to.row), col: Math.min(range.from.col, to.col) };
+};
+
+const toSimpleCellAddress = (sheet: number, cell: CellAddress): SimpleCellAddress => ({
+  sheet,
+  row: cell.row,
+  col: cell.col,
+});
+
+const toModelRange = (sheet: number, range: CellRange): SimpleCellRange => ({
+  start: toSimpleCellAddress(sheet, range.from),
+  end: toSimpleCellAddress(sheet, range.to ?? range.from),
+});
+
+export type SheetModelOptions = {
+  readonly?: boolean;
+};
+
+/**
+ * Spreadsheet data model.
+ *
+ * [ComputeGraphContext] > [SheetContext]:[SheetModel] > [Sheet.Root]
+ */
+// TODO(burdon): Factor out commonality with ComputeNode. Factor out HF.
+export class SheetModel extends Resource {
+  public readonly id = `model-${PublicKey.random().truncate()}`;
+
+  // Wraps compute node.
+  public readonly update = new Event<ComputeNodeEvent>();
+
+  private _node?: ComputeNode;
+
+  constructor(
+    private readonly _graph: ComputeGraph,
+    private readonly _sheet: SheetType,
+    private readonly _options: SheetModelOptions = {},
+  ) {
+    super();
+  }
+
+  get graph() {
+    return this._graph;
+  }
+
+  get sheet() {
+    return this._sheet;
+  }
+
+  get readonly() {
+    return this._options.readonly;
+  }
+
+  get bounds() {
+    return {
+      rows: this._sheet.rows.length,
+      columns: this._sheet.columns.length,
+    };
+  }
+
+  /**
+   * Initialize sheet and engine.
+   */
+  protected override async _open() {
+    log('initialize', { id: this.id });
+    initialize(this._sheet);
+
+    // TODO(burdon): SheetModel should extend ComputeNode and be constructed via the graph.
+    this._node = this._graph.getOrCreateNode(createSheetName({ type: getTypename(this._sheet)!, id: this._sheet.id }));
+    await this._node.open();
+
+    // Listen for model updates (e.g., async calculations).
+    const unsubscribe = this._node.update.on((event) => this.update.emit(event));
+    this._ctx.onDispose(unsubscribe);
+
+    this.reset();
+  }
+
+  /**
+   * Update engine.
+   * NOTE: This resets the undo history.
+   * @deprecated
+   */
+  reset() {
+    invariant(this._node);
+    this._node.graph.hf.clearSheet(this._node.sheetId);
+    Object.entries(this._sheet.cells).forEach(([key, { value }]) => {
+      invariant(this._node);
+      const { col, row } = addressFromIndex(this._sheet, key);
+      if (typeof value === 'string' && value.charAt(0) === '=') {
+        value = this._graph.mapFormulaToNative(
+          this._graph.mapFunctionBindingFromId(this.mapFormulaIndicesToRefs(value)),
+        );
+      }
+
+      this._node.graph.hf.setCellContents({ sheet: this._node.sheetId, row, col }, value);
+    });
+  }
+
+  /**
+   * Recalculate formulas.
+   * NOTE: This resets the undo history.
+   * https://hyperformula.handsontable.com/guide/volatile-functions.html#volatile-actions
+   * @deprecated
+   */
+  // TODO(burdon): Remove.
+  recalculate() {
+    this._node?.graph.hf.rebuildAndRecalculate();
+  }
+
+  insertRows(i: number, n = 1) {
+    insertIndices(this._sheet.rows, i, n, MAX_ROWS);
+    this.reset();
+  }
+
+  insertColumns(i: number, n = 1) {
+    insertIndices(this._sheet.columns, i, n, MAX_COLUMNS);
+    this.reset();
+  }
+
+  //
+  // Undoable actions.
+  // TODO(burdon): Group undoable methods; consistently update hf/sheet.
+  //
+
+  /**
+   * Clear range of values.
+   */
+  clear(range: CellRange) {
+    invariant(this._node);
+    const topLeft = getTopLeft(range);
+    const values = this._iterRange(range, () => null);
+    this._node.graph.hf.setCellContents(toSimpleCellAddress(this._node.sheetId, topLeft), values);
+    this._iterRange(range, (cell) => {
+      const idx = addressToIndex(this._sheet, cell);
+      delete this._sheet.cells[idx];
+    });
+  }
+
+  cut(range: CellRange) {
+    invariant(this._node);
+    this._node.graph.hf.cut(toModelRange(this._node.sheetId, range));
+    this._iterRange(range, (cell) => {
+      const idx = addressToIndex(this._sheet, cell);
+      delete this._sheet.cells[idx];
+    });
+  }
+
+  copy(range: CellRange) {
+    invariant(this._node);
+    this._node.graph.hf.copy(toModelRange(this._node.sheetId, range));
+  }
+
+  paste(cell: CellAddress) {
+    invariant(this._node);
+    if (!this._node.graph.hf.isClipboardEmpty()) {
+      const changes = this._node.graph.hf.paste(toSimpleCellAddress(this._node.sheetId, cell));
+      for (const change of changes) {
+        if (change instanceof ExportedCellChange) {
+          const { address, newValue } = change;
+          const idx = addressToIndex(this._sheet, { row: address.row, col: address.col });
+          this._sheet.cells[idx] = { value: newValue };
+        }
+      }
+    }
+  }
+
+  // TODO(burdon): Display undo/redo state.
+  undo() {
+    invariant(this._node);
+    if (this._node.graph.hf.isThereSomethingToUndo()) {
+      this._node.graph.hf.undo();
+      // this.update.emit();
+    }
+  }
+
+  redo() {
+    invariant(this._node);
+    if (this._node.graph.hf.isThereSomethingToRedo()) {
+      this._node.graph.hf.redo();
+      // this.update.emit();
+    }
+  }
+
+  /**
+   * Get value from sheet.
+   */
+  getCellValue(cell: CellAddress): CellScalarValue {
+    const idx = addressToIndex(this._sheet, cell);
+    return this._sheet.cells[idx]?.value ?? null;
+  }
+
+  /**
+   * Get value as a string for editing.
+   */
+  getCellText(cell: CellAddress): string | undefined {
+    const value = this.getCellValue(cell);
+    if (value == null) {
+      return undefined;
+    }
+
+    if (typeof value === 'string' && value.charAt(0) === '=') {
+      return this._graph.mapFunctionBindingFromId(this.mapFormulaIndicesToRefs(value));
+    } else {
+      return String(value);
+    }
+  }
+
+  /**
+   * Get array of raw values from sheet.
+   */
+  getCellValues(range: CellRange): CellScalarValue[][] {
+    return this._iterRange(range, (cell) => this.getCellValue(cell));
+  }
+
+  /**
+   * Gets the regular or computed value from the engine.
+   */
+  getValue(cell: CellAddress): CellScalarValue {
+    // Applies rounding and post-processing.
+    invariant(this._node);
+    const value = this._node.graph.hf.getCellValue(toSimpleCellAddress(this._node.sheetId, cell));
+    if (value instanceof DetailedCellError) {
+      return value.toString();
+    }
+
+    return value;
+  }
+
+  /**
+   * Get value type.
+   */
+  getValueType(cell: CellAddress): FieldValueType {
+    invariant(this._node);
+    const addr = toSimpleCellAddress(this._node.sheetId, cell);
+    const type = this._node.graph.hf.getCellValueDetailedType(addr);
+    return typeMap[type];
+  }
+
+  /**
+   * Sets the value, updating the sheet and engine.
+   */
+  setValue(cell: CellAddress, value: CellScalarValue) {
+    invariant(this._node);
+    if (this._options.readonly) {
+      throw new ReadonlyException();
+    }
+
+    // Reallocate if > current bounds.
+    let refresh = false;
+    if (cell.row >= this._sheet.rows.length) {
+      insertIndices(this._sheet.rows, cell.row, 1, MAX_ROWS);
+      refresh = true;
+    }
+    if (cell.col >= this._sheet.columns.length) {
+      insertIndices(this._sheet.columns, cell.col, 1, MAX_COLUMNS);
+      refresh = true;
+    }
+
+    if (refresh) {
+      // TODO(burdon): Remove.
+      this.reset();
+    }
+
+    // Insert into engine.
+    this._node.graph.hf.setCellContents({ sheet: this._node.sheetId, row: cell.row, col: cell.col }, [
+      [typeof value === 'string' && value.charAt(0) === '=' ? this._graph.mapFormulaToNative(value) : value],
+    ]);
+
+    // Insert into sheet.
+    const idx = addressToIndex(this._sheet, cell);
+    if (value === undefined || value === null) {
+      delete this._sheet.cells[idx];
+    } else {
+      if (typeof value === 'string' && value.charAt(0) === '=') {
+        value = this._graph.mapFunctionBindingToId(this.mapFormulaRefsToIndices(value));
+      }
+
+      this._sheet.cells[idx] = { value };
+    }
+  }
+
+  /**
+   * Sets values from a simple map.
+   */
+  setValues(values: Record<string, CellValue>) {
+    Object.entries(values).forEach(([key, { value }]) => {
+      this.setValue(addressFromA1Notation(key), value);
+    });
+  }
+
+  /**
+   * Iterate range.
+   */
+  private _iterRange(range: CellRange, cb: (cell: CellAddress) => CellScalarValue | void): CellScalarValue[][] {
+    const to = range.to ?? range.from;
+    const rowRange = [Math.min(range.from.row, to.row), Math.max(range.from.row, to.row)];
+    const columnRange = [Math.min(range.from.col, to.col), Math.max(range.from.col, to.col)];
+    const rows: CellScalarValue[][] = [];
+    for (let row = rowRange[0]; row <= rowRange[1]; row++) {
+      const rowCells: CellScalarValue[] = [];
+      for (let column = columnRange[0]; column <= columnRange[1]; column++) {
+        const value = cb({ row, col: column });
+        if (value !== undefined) {
+          rowCells.push(value);
+        }
+      }
+
+      rows.push(rowCells);
+    }
+
+    return rows;
+  }
+
+  // TODO(burdon): Delete index.
+  private _deleteIndices(indices: string[], i: number, n: number) {
+    throw new Error('Not implemented');
+  }
+
+  // TODO(burdon): Move. Cannot use fractional without changing. Switch back to using unique IDs?
+  private _moveIndices(indices: string[], i: number, j: number, n: number) {
+    throw new Error('Not implemented');
+  }
+
+  //
+  // Indices.
+  //
+
+  /**
+   * Map from A1 notation to indices.
+   */
+  mapFormulaRefsToIndices(formula: string): string {
+    invariant(formula.charAt(0) === '=');
+    return formula.replace(/([a-zA-Z]+)([0-9]+)/g, (match) => {
+      return addressToIndex(this._sheet, addressFromA1Notation(match));
+    });
+  }
+
+  /**
+   * Map from indices to A1 notation.
+   */
+  mapFormulaIndicesToRefs(formula: string): string {
+    invariant(formula.charAt(0) === '=');
+    return formula.replace(/([a-zA-Z0-9]+)@([a-zA-Z0-9]+)/g, (idx) => {
+      return addressToA1Notation(addressFromIndex(this._sheet, idx));
+    });
+  }
+
+  //
+  // Values
+  //
+
+  /**
+   * https://hyperformula.handsontable.com/guide/date-and-time-handling.html#example
+   * https://hyperformula.handsontable.com/api/interfaces/configparams.html#nulldate
+   * NOTE: TODAY() is number of FULL days since nullDate. It will typically be -1 days from NOW().
+   */
+  toLocalDate(num: number): Date {
+    const { year, month, day, hours, minutes, seconds } = this.toDateTime(num);
+    return new Date(year, month - 1, day, hours, minutes, seconds);
+  }
+
+  toDateTime(num: number): SimpleDateTime {
+    invariant(this._node);
+    return this._node.graph.hf.numberToDateTime(num) as SimpleDateTime;
+  }
+
+  toDate(num: number): SimpleDate {
+    invariant(this._node);
+    return this._node.graph.hf.numberToDate(num) as SimpleDate;
+  }
+
+  toTime(num: number): SimpleDate {
+    invariant(this._node);
+    return this._node.graph.hf.numberToTime(num) as SimpleDate;
+  }
+}

package/src/sanity.test.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { describe, test, expect } from 'vitest';
+
+// Part 2.
+// TODO(burdon): Cannot test outside of browser.
+//  - Cannot test Hyperformula
+//    - throws "Cannot convert undefined or null to object" in vitest (no browser).
+//    - throws "process.nextTick is not a function" (if browser)
+
+import { Client } from '@dxos/client';
+import { create } from '@dxos/client/echo';
+import { FunctionType } from '@dxos/plugin-script/types';
+
+// TODO(burdon): Fix test infrastructure:
+//  - Need docs? esp. needed for config. need pristine example package?
+//    - NOTE for non browser tests, import types from x-plugin/types (otherwise will bring in react deps).
+//  - Can't add flags to our tools?
+//  - .only / .skip ignored (have to comment out tests)
+
+describe('test', () => {
+  test('test', async () => {
+    const client = new Client();
+    client.addTypes([FunctionType]);
+    await client.initialize();
+    await client.halo.createIdentity();
+
+    // Part 1.
+    // Create script.
+    // VITEST_ENV=chromium p test
+    // TODO(burdon): Test after initialize.
+    //  - ERROR "process.nextTick is not a function"
+    //  - ERROR "Identifier 'Buffer' has already been declared" if { nodeExternal: true }
+    const space = await client.spaces.create();
+    const fn = space.db.add(create(FunctionType, { version: 1, binding: 'HELLO' }));
+    expect(fn).to.exist;
+  });
+});

package/src/{components/Sheet → testing}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './Sheet';
+export * from './testing';

package/src/testing/testing.tsx

@@ -0,0 +1,68 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Decorator } from '@storybook/react';
+import React, { useState } from 'react';
+
+import { type Space } from '@dxos/react-client/echo';
+import { useAsyncState } from '@dxos/react-hooks';
+
+import { ComputeGraphContextProvider } from '../components';
+import { createSheet } from '../defs';
+import { type ComputeGraph, type ComputeGraphOptions, ComputeGraphRegistry } from '../graph';
+import { type CellValue, type CreateSheetOptions } from '../types';
+
+const testSheetName = 'test';
+
+export const createTestCells = (): Record<string, CellValue> => ({
+  B1: { value: 'Qty2' },
+  B3: { value: 1 },
+  B4: { value: 2 },
+  B5: { value: 3 },
+  B7: { value: 'Total' },
+
+  C1: { value: 'Price' },
+  C3: { value: 2_000 },
+  C4: { value: 2_500 },
+  C5: { value: 3_000 },
+  C7: { value: '=SUMPRODUCT(B2:B6, C2:C6)' },
+  // C8: { value: '=C7*CRYPTO(D7)' },
+  C8: { value: '=C7*TEST()' },
+
+  D7: { value: 'USD' },
+  D8: { value: 'BTC' },
+
+  E3: { value: '=TODAY()' },
+  E4: { value: '=NOW()' },
+
+  F1: { value: `=${testSheetName}!A1` }, // Ref test sheet.
+  F3: { value: true },
+  F4: { value: false },
+  F5: { value: '8%' },
+  F6: { value: '$10000' },
+});
+
+export const useTestSheet = (space?: Space, graph?: ComputeGraph, options?: CreateSheetOptions) => {
+  const [sheet] = useAsyncState(async () => {
+    if (!space || !graph) {
+      return;
+    }
+
+    const sheet = createSheet(options);
+    space.db.add(sheet);
+    return sheet;
+  }, [space, graph]);
+  return sheet;
+};
+
+export const withComputeGraphDecorator =
+  (options?: ComputeGraphOptions): Decorator =>
+  (Story) => {
+    const [registry] = useState(new ComputeGraphRegistry(options));
+    return (
+      <ComputeGraphContextProvider registry={registry}>
+        <Story />
+      </ComputeGraphContextProvider>
+    );
+  };

package/src/translations.ts

@@ -16,7 +16,12 @@ export default [
         'toolbar left label': 'Align left',
         'toolbar left center': 'Align center',
         'toolbar left right': 'Align right',
+        'selection overlaps existing comment label': 'Selected cell already has a comment',
+        'comment label': 'Add comment',
+        'comment ranges not supported label': 'Commenting on ranges is not yet supported',
+        'no cursor label': 'Select a cell to comment',
+        'open comment for sheet cell': 'View comments for cell',
       },
     },
   },
-];
+] as const;

package/src/types.ts

@@ -9,9 +9,13 @@ import type {
   SurfaceProvides,
   TranslationsProvides,
 } from '@dxos/app-framework';
-import { create, S, TypedObject } from '@dxos/echo-schema';
+import { ref, S, TypedObject } from '@dxos/echo-schema';
 import { type SchemaProvides } from '@dxos/plugin-client';
+import { type MarkdownExtensionProvides } from '@dxos/plugin-markdown';
+import { type SpaceInitProvides } from '@dxos/plugin-space';
+import { ThreadType } from '@dxos/plugin-space/types';
 import { type StackProvides } from '@dxos/plugin-stack';
+import { FieldValueType } from '@dxos/schema';
 
 import { SHEET_PLUGIN } from './meta';
 
@@ -21,13 +25,26 @@ export enum SheetAction {
   CREATE = `${SHEET_ACTION}/create`,
 }
 
+// TODO(Zan): Move this to the plugin-space plugin or another common location
+// when we implement comments in sheets.
+// This is currently duplicated in a few places.
+type ThreadProvides<T> = {
+  thread: {
+    predicate: (obj: any) => obj is T;
+    createSort: (obj: T) => (anchorA: string | undefined, anchorB: string | undefined) => number;
+  };
+};
+
 export type SheetPluginProvides = SurfaceProvides &
   IntentResolverProvides &
   GraphBuilderProvides &
+  MarkdownExtensionProvides &
   MetadataRecordsProvides &
   TranslationsProvides &
   SchemaProvides &
-  StackProvides;
+  SpaceInitProvides &
+  StackProvides &
+  ThreadProvides<SheetType>;
 
 export type CellScalarValue = number | string | boolean | null;
 
@@ -35,41 +52,15 @@ export const CellValue = S.Struct({
   // TODO(burdon): How to store dates (datetime, date, time), percentages, etc.
   //  Consider import/export; natural access for other plugins. Special handling for currency (precision).
   // TODO(burdon): Automerge (long string) or short string or number.
-  // TODO(burdon): Arrays?
   value: S.Any,
 });
 
 export type CellValue = S.Schema.Type<typeof CellValue>;
 
-/**
- * https://www.tutorialsteacher.com/typescript/typescript-number
- */
-// TODO(burdon): Format vs. value.
-export enum ValueTypeEnum {
-  Null = 0,
-  Number = 1,
-  Boolean = 2,
-  String = 3,
-
-  // Special numbers.
-  Percent = 10,
-  Currency = 11,
-
-  // Dates.
-  DateTime = 20,
-  Date = 21,
-  Time = 22,
-
-  // Validated string types.
-  // TODO(burdon): Define effect types.
-  URL = 30,
-  DID = 31,
-}
-
-export const ValueType = S.Enums(ValueTypeEnum);
-
+// TODO(burdon): IMPORTANT: Reconcile with Field definition.
 export const Formatting = S.Struct({
-  type: S.optional(ValueType),
+  range: S.String,
+  type: S.optional(S.Enums(FieldValueType)),
   format: S.optional(S.String),
   precision: S.optional(S.Number),
   classNames: S.optional(S.Array(S.String)),
@@ -83,13 +74,11 @@ export const RowColumnMeta = S.Struct({
 });
 
 // TODO(burdon): Index to all updates when rows/columns are inserted/deleted.
-// TODO(wittjosiah): Migrate typename to remove `Type` suffix.
-// TODO(wittjosiah): Rename title to name to align with other schemas.
 export class SheetType extends TypedObject({ typename: 'dxos.org/type/SheetType', version: '0.1.0' })({
-  title: S.optional(S.String),
+  name: S.optional(S.String),
 
   // Sparse map of cells referenced by index.
-  cells: S.mutable(S.Record(S.String, S.mutable(CellValue))),
+  cells: S.mutable(S.Record({ key: S.String, value: S.mutable(CellValue) })),
 
   // Ordered row indices.
   rows: S.mutable(S.Array(S.String)),
@@ -98,15 +87,25 @@ export class SheetType extends TypedObject({ typename: 'dxos.org/type/SheetType'
   columns: S.mutable(S.Array(S.String)),
 
   // Row metadata referenced by index.
-  rowMeta: S.mutable(S.Record(S.String, S.mutable(RowColumnMeta))),
+  rowMeta: S.mutable(S.Record({ key: S.String, value: S.mutable(RowColumnMeta) })),
 
   // Column metadata referenced by index.
-  columnMeta: S.mutable(S.Record(S.String, S.mutable(RowColumnMeta))),
+  columnMeta: S.mutable(S.Record({ key: S.String, value: S.mutable(RowColumnMeta) })),
 
+  // TODO(burdon): Change to array.
   // Cell formatting referenced by indexed range.
-  formatting: S.mutable(S.Record(S.String, S.mutable(Formatting))),
+  formatting: S.mutable(S.Array(Formatting)),
+
+  // Threads associated with the sheet
+  threads: S.optional(S.mutable(S.Array(ref(ThreadType)))),
 }) {}
 
-// TODO(burdon): Fix defaults.
-export const createSheet = (title?: string): SheetType =>
-  create(SheetType, { title, cells: {}, rows: [], columns: [], rowMeta: {}, columnMeta: {}, formatting: {} });
+export type SheetSize = {
+  rows: number;
+  columns: number;
+};
+
+export type CreateSheetOptions = {
+  name?: string;
+  cells?: Record<string, CellValue>;
+} & Partial<SheetSize>;