@dxos/plugin-sheet 0.6.13 → 0.6.14-main.1366248

package/src/model/sheet-model.ts

@@ -0,0 +1,495 @@
+//
+// 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, FormatEnum, TypeEnum } from '@dxos/echo-schema';
+import { invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { DetailedCellError, ExportedCellChange } from '#hyperformula';
+import { type ComputeGraph, type ComputeNode, type ComputeNodeEvent, createSheetName } from '../compute-graph';
+import {
+  addressFromA1Notation,
+  addressFromIndex,
+  addressToA1Notation,
+  addressToIndex,
+  initialize,
+  insertIndices,
+  isFormula,
+  type CellAddress,
+  type CellRange,
+  ReadonlyException,
+  MAX_COLUMNS,
+  MAX_ROWS,
+} from '../defs';
+import { type CellScalarValue, type CellValue, type SheetType, type RestoreAxis } from '../types';
+
+// Map sheet types to system types.
+// https://hyperformula.handsontable.com/guide/types-of-values.html
+//  - https://github.com/handsontable/hyperformula/blob/master/src/Cell.ts (CellValueType)
+//  - https://github.com/handsontable/hyperformula/blob/master/src/interpreter/InterpreterValue.ts (NumberType)
+const typeMap: Record<string, { type: TypeEnum; format?: FormatEnum }> = {
+  BOOLEAN: { type: TypeEnum.Boolean },
+  NUMBER_RAW: { type: TypeEnum.Number },
+  NUMBER_PERCENT: { type: TypeEnum.Number, format: FormatEnum.Percent },
+  NUMBER_CURRENCY: { type: TypeEnum.Number, format: FormatEnum.Currency },
+  NUMBER_DATETIME: { type: TypeEnum.String, format: FormatEnum.DateTime },
+  NUMBER_DATE: { type: TypeEnum.String, format: FormatEnum.Date },
+  NUMBER_TIME: { type: TypeEnum.String, format: FormatEnum.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);
+
+    this._graph.update.on((event) => {
+      if (event.type === 'functionsUpdated') {
+        this.reset();
+      }
+    });
+
+    // 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 (isFormula(value)) {
+        const binding = this._graph.mapFunctionBindingFromId(this.mapFormulaIndicesToRefs(value));
+        if (binding) {
+          value = this._graph.mapFormulaToNative(binding);
+        } else {
+          // If binding is not found, render the cell as empty.
+          // This prevents the cell from momentarily rendering an error while the binding is being loaded.
+          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) {
+    const idx = insertIndices(this._sheet.rows, i, n, MAX_ROWS);
+    this.reset();
+    return idx;
+  }
+
+  insertColumns(i: number, n = 1) {
+    const idx = insertIndices(this._sheet.columns, i, n, MAX_COLUMNS);
+    this.reset();
+    return idx;
+  }
+
+  dropRow(rowIndex: string): RestoreAxis {
+    const range = {
+      from: addressFromIndex(this._sheet, `${this._sheet.columns[0]}@${rowIndex}`),
+      to: addressFromIndex(this._sheet, `${this._sheet.columns[this._sheet.columns.length - 1]}@${rowIndex}`),
+    };
+    const values = this.getCellValues(range).flat();
+    const index = this._sheet.rows.indexOf(rowIndex);
+    this.clear(range);
+    this._sheet.rows.splice(index, 1);
+    delete this._sheet.rowMeta[rowIndex];
+    this.reset();
+    return { axis: 'row', index, axisIndex: rowIndex, axisMeta: this._sheet.rowMeta[rowIndex], values };
+  }
+
+  dropColumn(colIndex: string): RestoreAxis {
+    const range = {
+      from: addressFromIndex(this._sheet, `${colIndex}@${this._sheet.rows[0]}`),
+      to: addressFromIndex(this._sheet, `${colIndex}@${this._sheet.rows[this._sheet.rows.length - 1]}`),
+    };
+    const values = this.getCellValues(range).flat();
+    const index = this._sheet.columns.indexOf(colIndex);
+    this.clear(range);
+    this._sheet.columns.splice(index, 1);
+    delete this._sheet.columnMeta[colIndex];
+    this.reset();
+    return { axis: 'col', index, axisIndex: colIndex, axisMeta: this._sheet.rowMeta[colIndex], values };
+  }
+
+  restoreRow({ index, axisIndex, axisMeta, values }: RestoreAxis) {
+    this._sheet.rows.splice(index, 0, axisIndex);
+    values.forEach((value, col) => {
+      if (value) {
+        this._sheet.cells[`${this._sheet.columns[col]}@${axisIndex}`] = { value };
+      }
+    });
+    if (axisMeta) {
+      this._sheet.rowMeta[axisIndex] = axisMeta;
+    }
+    this.reset();
+  }
+
+  restoreColumn({ index, axisIndex, axisMeta, values }: RestoreAxis) {
+    this._sheet.columns.splice(index, 0, axisIndex);
+    values.forEach((value, row) => {
+      if (value) {
+        this._sheet.cells[`${axisIndex}@${this._sheet.rows[row]}`] = { value };
+      }
+    });
+    if (axisMeta) {
+      this._sheet.columnMeta[axisIndex] = axisMeta;
+    }
+    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 (isFormula(value)) {
+      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 address = toSimpleCellAddress(this._node.sheetId, cell);
+    const value = this._node.graph.hf.getCellValue(address);
+    if (value instanceof DetailedCellError) {
+      // TODO(wittjosiah): Error details should be shown in cell `title`.
+      log.info('cell error', { cell, error: value });
+      return value.toString();
+    }
+
+    return value;
+  }
+
+  /**
+   * Get value type.
+   */
+  getValueDescription(cell: CellAddress): { type: TypeEnum; format?: FormatEnum } | undefined {
+    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 }, [
+      [isFormula(value) ? 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 (isFormula(value)) {
+        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(isFormula(formula));
+    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(isFormula(formula));
+    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/model/useSheetModel.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+import { type ComputeGraph } from '../compute-graph';
+import { SheetModel } from '../model';
+import { type SheetType } from '../types';
+
+export type UseSheetModelOptions = {
+  readonly?: boolean;
+};
+
+export const useSheetModel = (
+  graph?: ComputeGraph,
+  sheet?: SheetType,
+  { readonly }: UseSheetModelOptions = {},
+): SheetModel | undefined => {
+  const [model, setModel] = useState<SheetModel>();
+  useEffect(() => {
+    if (!graph || !sheet) {
+      return;
+    }
+
+    let model: SheetModel | undefined;
+    const t = setTimeout(async () => {
+      model = new SheetModel(graph, sheet, { readonly });
+      await model.open();
+      setModel(model);
+    });
+
+    return () => {
+      clearTimeout(t);
+      void model?.close();
+    };
+  }, [graph, sheet, readonly]);
+
+  return model;
+};

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/serializer.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type TypedObjectSerializer } from '@dxos/plugin-space/types';
+import { create, getObjectCore } from '@dxos/react-client/echo';
+
+import { SheetType } from './types';
+
+export const serializer: TypedObjectSerializer<SheetType> = {
+  serialize: async ({ object }): Promise<string> => {
+    const { threads: _threads, ...sheet } = object;
+    return JSON.stringify(sheet, null, 2);
+  },
+
+  deserialize: async ({ content, newId }) => {
+    const { id, ...parsed } = JSON.parse(content);
+    const sheet = create(SheetType, parsed);
+
+    if (!newId) {
+      const core = getObjectCore(sheet);
+      core.id = id;
+    }
+
+    return sheet;
+  },
+};

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 { type ComputeGraph, type ComputeGraphOptions, ComputeGraphRegistry } from '../compute-graph';
+import { createSheet } from '../defs';
+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>
+    );
+  };