@dxos/plugin-sheet 0.6.8-main.046e6cf

package/src/model/model.ts

@@ -0,0 +1,480 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { DetailedCellError, ExportedCellChange } from 'hyperformula';
+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 { Context } from '@dxos/context';
+import { invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { addressFromA1Notation, addressToA1Notation, type CellAddress, type CellRange } from './types';
+import { createIndices, RangeException, ReadonlyException } from './util';
+import { type ComputeGraph } from '../components';
+import { type CellScalarValue, type CellValue, type SheetType, ValueTypeEnum } from '../types';
+
+// TODO(burdon): Defaults or Max?
+const DEFAULT_ROWS = 500;
+const DEFAULT_COLUMNS = 26 * 2;
+
+export type CellIndex = string;
+
+export type CellContentValue = number | string | boolean | null;
+
+export type SheetModelOptions = {
+  readonly?: boolean;
+  rows: number;
+  columns: number;
+};
+
+const typeMap: Record<string, ValueTypeEnum> = {
+  BOOLEAN: ValueTypeEnum.Boolean,
+  NUMBER_RAW: ValueTypeEnum.Number,
+  NUMBER_PERCENT: ValueTypeEnum.Percent,
+  NUMBER_CURRENCY: ValueTypeEnum.Currency,
+  NUMBER_DATETIME: ValueTypeEnum.DateTime,
+  NUMBER_DATE: ValueTypeEnum.Date,
+  NUMBER_TIME: ValueTypeEnum.Time,
+};
+
+export const defaultOptions: SheetModelOptions = {
+  rows: 50,
+  columns: 26,
+};
+
+const getTopLeft = (range: CellRange) => {
+  const to = range.to ?? range.from;
+  return { row: Math.min(range.from.row, to.row), column: Math.min(range.from.column, to.column) };
+};
+
+const toSimpleCellAddress = (sheet: number, cell: CellAddress): SimpleCellAddress => ({
+  sheet,
+  row: cell.row,
+  col: cell.column,
+});
+
+const toModelRange = (sheet: number, range: CellRange): SimpleCellRange => ({
+  start: toSimpleCellAddress(sheet, range.from),
+  end: toSimpleCellAddress(sheet, range.to ?? range.from),
+});
+
+/**
+ * Spreadsheet data model.
+ *
+ * [ComputeGraphContext] > [SheetContext]:[SheetModel] > [Sheet.Root]
+ */
+export class SheetModel {
+  public readonly id = `model-${PublicKey.random().truncate()}`;
+  private _ctx?: Context = undefined;
+
+  /**
+   * Formula engine.
+   * Acts as a write through cache for scalar and computed values.
+   */
+  private readonly _sheetId: number;
+  private readonly _options: SheetModelOptions;
+
+  public readonly update = new Event();
+
+  constructor(
+    private readonly _graph: ComputeGraph,
+    private readonly _sheet: SheetType,
+    options: Partial<SheetModelOptions> = {},
+  ) {
+    // Sheet for this object.
+    const name = this._sheet.id;
+    if (!this._graph.hf.doesSheetExist(name)) {
+      this._graph.hf.addSheet(name);
+    }
+    this._sheetId = this._graph.hf.getSheetId(name)!;
+    this._options = { ...defaultOptions, ...options };
+    this.reset();
+  }
+
+  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,
+    };
+  }
+
+  get functions(): string[] {
+    return this._graph.hf.getRegisteredFunctionNames();
+  }
+
+  get initialized(): boolean {
+    return !!this._ctx;
+  }
+
+  /**
+   * Initialize sheet and engine.
+   */
+  async initialize() {
+    log('initialize', { id: this.id });
+    invariant(!this.initialized, 'Already initialized.');
+    this._ctx = new Context();
+    if (!this._sheet.rows.length) {
+      this._insertIndices(this._sheet.rows, 0, this._options.rows, DEFAULT_ROWS);
+    }
+    if (!this._sheet.columns.length) {
+      this._insertIndices(this._sheet.columns, 0, this._options.columns, DEFAULT_COLUMNS);
+    }
+    this.reset();
+
+    // Listen for model updates (e.g., async calculations).
+    const unsubscribe = this._graph.update.on(() => this.update.emit());
+    this._ctx.onDispose(unsubscribe);
+
+    return this;
+  }
+
+  async destroy() {
+    log('destroy', { id: this.id });
+    if (this._ctx) {
+      await this._ctx.dispose();
+      this._ctx = undefined;
+    }
+  }
+
+  /**
+   * Update engine.
+   * NOTE: This resets the undo history.
+   * @deprecated
+   */
+  reset() {
+    this._graph.hf.clearSheet(this._sheetId);
+    Object.entries(this._sheet.cells).forEach(([key, { value }]) => {
+      const { column, row } = this.addressFromIndex(key);
+      if (typeof value === 'string' && value.charAt(0) === '=') {
+        value = this.mapFormulaIndicesToRefs(value);
+      }
+
+      this._graph.hf.setCellContents({ sheet: this._sheetId, row, col: column }, 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._graph.hf.rebuildAndRecalculate();
+  }
+
+  insertRows(i: number, n = 1) {
+    this._insertIndices(this._sheet.rows, i, n, DEFAULT_ROWS);
+    this.reset();
+  }
+
+  insertColumns(i: number, n = 1) {
+    this._insertIndices(this._sheet.columns, i, n, DEFAULT_COLUMNS);
+    this.reset();
+  }
+
+  //
+  // Undoable actions.
+  // TODO(burdon): Group undoable methods; consistently update hf/sheet.
+  //
+
+  /**
+   * Clear range of values.
+   */
+  clear(range: CellRange) {
+    const topLeft = getTopLeft(range);
+    const values = this._iterRange(range, () => null);
+    this._graph.hf.setCellContents(toSimpleCellAddress(this._sheetId, topLeft), values);
+    this._iterRange(range, (cell) => {
+      const idx = this.addressToIndex(cell);
+      delete this._sheet.cells[idx];
+    });
+  }
+
+  cut(range: CellRange) {
+    this._graph.hf.cut(toModelRange(this._sheetId, range));
+    this._iterRange(range, (cell) => {
+      const idx = this.addressToIndex(cell);
+      delete this._sheet.cells[idx];
+    });
+  }
+
+  copy(range: CellRange) {
+    this._graph.hf.copy(toModelRange(this._sheetId, range));
+  }
+
+  paste(cell: CellAddress) {
+    if (!this._graph.hf.isClipboardEmpty()) {
+      const changes = this._graph.hf.paste(toSimpleCellAddress(this._sheetId, cell));
+      for (const change of changes) {
+        if (change instanceof ExportedCellChange) {
+          const { address, newValue } = change;
+          const idx = this.addressToIndex({ row: address.row, column: address.col });
+          this._sheet.cells[idx] = { value: newValue };
+        }
+      }
+    }
+  }
+
+  // TODO(burdon): Display undo/redo state.
+  undo() {
+    if (this._graph.hf.isThereSomethingToUndo()) {
+      this._graph.hf.undo();
+      this.update.emit();
+    }
+  }
+
+  redo() {
+    if (this._graph.hf.isThereSomethingToRedo()) {
+      this._graph.hf.redo();
+      this.update.emit();
+    }
+  }
+
+  /**
+   * Get value from sheet.
+   */
+  getCellValue(cell: CellAddress): CellScalarValue {
+    const idx = this.addressToIndex(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.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.
+    const value = this._graph.hf.getCellValue(toSimpleCellAddress(this._sheetId, cell));
+    if (value instanceof DetailedCellError) {
+      return value.toString();
+    }
+
+    return value;
+  }
+
+  /**
+   * Get value type.
+   */
+  getValueType(cell: CellAddress): ValueTypeEnum {
+    const addr = toSimpleCellAddress(this._sheetId, cell);
+    const type = this._graph.hf.getCellValueDetailedType(addr);
+    return typeMap[type];
+  }
+
+  /**
+   * Sets the value, updating the sheet and engine.
+   */
+  setValue(cell: CellAddress, value: CellScalarValue) {
+    if (this._options.readonly) {
+      throw new ReadonlyException();
+    }
+
+    // Reallocate if > current bounds.
+    let refresh = false;
+    if (cell.row >= this._sheet.rows.length) {
+      this._insertIndices(this._sheet.rows, cell.row, 1, DEFAULT_ROWS);
+      refresh = true;
+    }
+    if (cell.column >= this._sheet.columns.length) {
+      this._insertIndices(this._sheet.columns, cell.column, 1, DEFAULT_COLUMNS);
+      refresh = true;
+    }
+    if (refresh) {
+      // TODO(burdon): Remove.
+      this.reset();
+    }
+
+    // Insert into engine.
+    this._graph.hf.setCellContents({ sheet: this._sheetId, row: cell.row, col: cell.column }, [[value]]);
+
+    // Insert into sheet.
+    const idx = this.addressToIndex(cell);
+    if (value === undefined || value === null) {
+      delete this._sheet.cells[idx];
+    } else {
+      if (typeof value === 'string' && value.charAt(0) === '=') {
+        value = 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.column, to.column), Math.max(range.from.column, to.column)];
+    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, column });
+        if (value !== undefined) {
+          rowCells.push(value);
+        }
+      }
+      rows.push(rowCells);
+    }
+
+    return rows;
+  }
+
+  /**
+   *
+   */
+  // TODO(burdon): Insert indices into sheet.
+  private _insertIndices(indices: string[], i: number, n: number, max: number) {
+    if (i + n > max) {
+      throw new RangeException(i + n);
+    }
+
+    const idx = createIndices(n);
+    indices.splice(i, 0, ...idx);
+  }
+
+  // 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.
+  //
+
+  /**
+   * E.g., "A1" => "x1@y1".
+   */
+  addressToIndex(cell: CellAddress): CellIndex {
+    return `${this._sheet.columns[cell.column]}@${this._sheet.rows[cell.row]}`;
+  }
+
+  /**
+   * E.g., "x1@y1" => "A1".
+   */
+  addressFromIndex(idx: CellIndex): CellAddress {
+    const [column, row] = idx.split('@');
+    return {
+      column: this._sheet.columns.indexOf(column),
+      row: this._sheet.rows.indexOf(row),
+    };
+  }
+
+  /**
+   * E.g., "A1:B2" => "x1@y1:x2@y2".
+   */
+  rangeToIndex(range: CellRange): string {
+    return [range.from, range.to ?? range.from].map((cell) => this.addressToIndex(cell)).join(':');
+  }
+
+  /**
+   * E.g., "x1@y1:x2@y2" => "A1:B2".
+   */
+  rangeFromIndex(idx: string): CellRange {
+    const [from, to] = idx.split(':').map((idx) => this.addressFromIndex(idx));
+    return { from, to };
+  }
+
+  /**
+   * 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 this.addressToIndex(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(this.addressFromIndex(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 {
+    return this._graph.hf.numberToDateTime(num) as SimpleDateTime;
+  }
+
+  toDate(num: number): SimpleDate {
+    return this._graph.hf.numberToDate(num) as SimpleDate;
+  }
+
+  toTime(num: number): SimpleDate {
+    return this._graph.hf.numberToTime(num) as SimpleDate;
+  }
+}

package/src/model/types.test.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { getIndices, sortByIndex, getIndicesBelow, getIndicesAbove, getIndicesBetween } from '@tldraw/indices';
+import { expect } from 'chai';
+import { describe, test } from 'vitest';
+
+import { inRange, addressFromA1Notation, addressToA1Notation, rangeFromA1Notation, rangeToA1Notation } from './types';
+
+describe('cell', () => {
+  test('posToA1Notation', () => {
+    expect(addressToA1Notation({ column: 0, row: 0 })).to.eq('A1');
+    expect(addressFromA1Notation('C2')).to.deep.eq({ column: 2, row: 1 });
+  });
+
+  test('rangeToA1Notation', () => {
+    expect(rangeToA1Notation({ from: addressFromA1Notation('A1'), to: addressFromA1Notation('A5') })).to.eq('A1:A5');
+  });
+
+  test('inRange', () => {
+    const range = rangeFromA1Notation('A1:C5');
+    expect(inRange(range, addressFromA1Notation('A1'))).to.be.true;
+    expect(inRange(range, addressFromA1Notation('C5'))).to.be.true;
+    expect(inRange(range, addressFromA1Notation('A6'))).to.be.false;
+    expect(inRange(range, addressFromA1Notation('D5'))).to.be.false;
+  });
+
+  // TODO(burdon): Move to model.test.ts
+  test('index', () => {
+    // Pre-allocated grid.
+    const n = 5;
+    const columns = getIndices(n - 1);
+    const rows = getIndices(n - 1);
+
+    const pickOne = (indices: string[]) => indices[Math.floor(Math.random() * indices.length)];
+
+    /**
+     * Insert an index into the allocated list.
+     * Randomly picks from n values between indexes to support probabilistic concurrency.
+     */
+    const insertIndex = (indices: string[], i: number, n = 20) => {
+      if (i === 0) {
+        const idx = pickOne(getIndicesBelow(indices[0], n));
+        indices.splice(0, 0, idx);
+      } else if (i >= indices.length) {
+        // Reallocate if > current bounds.
+        // TODO(burdon): Is this OK if this happens concurrently?
+        indices.splice(indices.length, 0, ...getIndicesAbove(indices[indices.length - 1], i + 1 - indices.length));
+      } else {
+        const idx = pickOne(getIndicesBetween(indices[i - 1], indices[i], n));
+        indices.splice(i, 0, idx);
+      }
+    };
+
+    // Values.
+    const cells: Record<string, any> = {};
+    const setCell = (cell: string, value: any) => {
+      const { column, row } = addressFromA1Notation(cell);
+      // Reallocate if > current bounds.
+      if (column >= columns.length) {
+        insertIndex(columns, column);
+      }
+      if (row >= rows.length) {
+        insertIndex(rows, row);
+      }
+      const index = `${columns[column]}@${rows[row]}`;
+      cells[index] = value;
+    };
+
+    expect(addressFromA1Notation('A1')).to.deep.eq({ column: 0, row: 0 });
+
+    expect(columns).to.deep.eq(['a1', 'a2', 'a3', 'a4', 'a5']);
+    insertIndex(columns, 7);
+    expect(columns).to.deep.eq(['a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'a7', 'a8']);
+
+    setCell('A1', 100);
+    setCell('B1', 101);
+
+    insertIndex(columns, 1);
+    setCell('B1', 102);
+
+    setCell('J10', 104);
+    expect(columns).to.have.length(10);
+    expect(rows).to.have.length(10);
+
+    const entries = Object.entries(cells).map(([key, value]) => ({ index: key.split('@')[0], value }));
+    const sorted = entries.sort(sortByIndex);
+    const values = sorted.map(({ value }) => value);
+    expect(values).to.deep.eq([100, 102, 101, 104]);
+  });
+});

package/src/model/types.ts

@@ -0,0 +1,71 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+
+export const MAX_COLUMNS = 26 * 26;
+
+export type CellAddress = { column: number; row: number };
+export type CellRange = { from: CellAddress; to?: CellAddress };
+
+export const posEquals = (a: CellAddress | undefined, b: CellAddress | undefined) => {
+  return a?.column === b?.column && a?.row === b?.row;
+};
+
+export const columnLetter = (column: number): string => {
+  invariant(column < MAX_COLUMNS, `Invalid column: ${column}`);
+  return (
+    (column >= 26 ? String.fromCharCode('A'.charCodeAt(0) + Math.floor(column / 26) - 1) : '') +
+    String.fromCharCode('A'.charCodeAt(0) + (column % 26))
+  );
+};
+
+export const addressToA1Notation = ({ column, row }: CellAddress): string => {
+  return `${columnLetter(column)}${row + 1}`;
+};
+
+export const addressFromA1Notation = (ref: string): CellAddress => {
+  const match = ref.match(/([A-Z]+)(\d+)/);
+  invariant(match, `Invalid notation: ${ref}`);
+  return {
+    row: parseInt(match[2], 10) - 1,
+    column: match[1].split('').reduce((acc, c) => acc * 26 + c.charCodeAt(0) - 'A'.charCodeAt(0) + 1, 0) - 1,
+  };
+};
+
+export const rangeToA1Notation = (range: CellRange) => {
+  return [range?.from && addressToA1Notation(range?.from), range?.to && addressToA1Notation(range?.to)]
+    .filter(Boolean)
+    .join(':');
+};
+
+export const rangeFromA1Notation = (ref: string): CellRange => {
+  const [from, to] = ref.split(':').map(addressFromA1Notation);
+  return { from, to };
+};
+
+export const inRange = (range: CellRange | undefined, cell: CellAddress): boolean => {
+  if (!range) {
+    return false;
+  }
+
+  const { from, to } = range;
+  if ((from && posEquals(from, cell)) || (to && posEquals(to, cell))) {
+    return true;
+  }
+
+  if (!from || !to) {
+    return false;
+  }
+
+  const { column: c1, row: r1 } = from;
+  const { column: c2, row: r2 } = to;
+  const cMin = Math.min(c1, c2);
+  const cMax = Math.max(c1, c2);
+  const rMin = Math.min(r1, r2);
+  const rMax = Math.max(r1, r2);
+
+  const { column, row } = cell;
+  return column >= cMin && column <= cMax && row >= rMin && row <= rMax;
+};

package/src/model/util.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { randomBytes } from '@dxos/crypto';
+
+// TODO(burdon): Factor out from dxos/protocols to new common package.
+export class ApiError extends Error {}
+export class ReadonlyException extends ApiError {}
+export class RangeException extends ApiError {
+  constructor(n: number) {
+    super();
+  }
+}
+
+/**
+ * With a string length of 8, the chance of a collision is 0.02% for a sheet with 10,000 strings.
+ */
+export const createIndex = (length = 8): string => {
+  const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  const charactersLength = characters.length;
+  const randomBuffer = randomBytes(length);
+  return Array.from(randomBuffer, (byte) => characters[byte % charactersLength]).join('');
+};
+
+export const createIndices = (length: number): string[] => Array.from({ length }).map(() => createIndex());
+
+// TODO(burdon): Factor out.
+export const pickOne = <T>(values: T[]): T => values[Math.floor(Math.random() * values.length)];
+export const pickSome = <T>(values: T[], n = 1): T[] => {
+  const result = new Set<T>();
+  while (result.size < n) {
+    result.add(pickOne(values));
+  }
+  return Array.from(result.values());
+};

package/src/translations.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { SHEET_PLUGIN } from './meta';
+
+export default [
+  {
+    'en-US': {
+      [SHEET_PLUGIN]: {
+        'plugin name': 'Sheets',
+        'sheet title placeholder': 'New sheet',
+        'create sheet label': 'Create sheet',
+        'create sheet section label': 'Create sheet',
+        'cell placeholder': 'Cell value...',
+        'toolbar left label': 'Align left',
+        'toolbar left center': 'Align center',
+        'toolbar left right': 'Align right',
+      },
+    },
+  },
+];