@dxos/plugin-sheet 0.6.11 → 0.6.12-main.15a606f

package/src/hooks/useComputeGraph.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+import { type Space } from '@dxos/react-client/echo';
+import { useAsyncState } from '@dxos/react-hooks';
+
+import { ComputeGraphContext } from '../components';
+import { type ComputeGraph } from '../graph';
+
+/**
+ * Get existing or create new compute graph for the given space.
+ */
+export const useComputeGraph = (space?: Space): ComputeGraph | undefined => {
+  const { registry } = useContext(ComputeGraphContext) ?? raise(new Error('Missing ComputeGraphContext'));
+  return useAsyncState(async () => space && registry.getOrCreateGraph(space), [space, registry]);
+};

package/src/hooks/useFormattingModel.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { type SheetModel, FormattingModel } from '../model';
+
+export const useFormattingModel = (model: SheetModel | undefined): FormattingModel | undefined => {
+  return useMemo(() => model && new FormattingModel(model), [model]);
+};

package/src/hooks/useSheetModel.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+import { type Space } from '@dxos/react-client/echo';
+
+import { useComputeGraph } from './useComputeGraph';
+import { SheetModel } from '../model';
+import { type SheetType } from '../types';
+
+export type UseSheetModelOptions = {
+  readonly?: boolean;
+};
+
+export const useSheetModel = (
+  space?: Space,
+  sheet?: SheetType,
+  { readonly }: UseSheetModelOptions = {},
+): SheetModel | undefined => {
+  const graph = useComputeGraph(space);
+  const [model, setModel] = useState<SheetModel>();
+  useEffect(() => {
+    if (!space || !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();
+    };
+  }, [space, sheet, graph, readonly]);
+
+  return model;
+};

package/src/meta.tsx

@@ -2,9 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-import { GridNine, type IconProps } from '@phosphor-icons/react';
-import React from 'react';
-
 import { pluginMeta } from '@dxos/app-framework';
 
 export const SHEET_PLUGIN = 'dxos.org/plugin/sheet';
@@ -13,6 +10,5 @@ export default pluginMeta({
   id: SHEET_PLUGIN,
   name: 'Sheet',
   description: 'A simple spreadsheet plugin.',
-  iconComponent: (props: IconProps) => <GridNine {...props} />,
-  iconSymbol: 'ph--grid-nine--regular',
+  icon: 'ph--grid-nine--regular',
 });

package/src/{components/Sheet/formatting.ts → model/formatting-model.ts}

@@ -4,17 +4,24 @@
 
 import { type ClassNameValue } from '@dxos/react-ui-types';
 
-import { type SheetModel, type CellAddress, inRange } from '../../model';
-import { ValueTypeEnum } from '../../types';
+import { type SheetModel } from './sheet-model';
+import { type CellAddress, inRange } from '../defs';
+import { addressToIndex, rangeFromIndex } from '../defs';
+import { ValueTypeEnum } from '../types';
+
+export type CellFormat = {
+  value?: string;
+  classNames?: ClassNameValue;
+};
 
 export class FormattingModel {
-  constructor(private readonly model: SheetModel) {}
+  constructor(private readonly _model: SheetModel) {}
 
   /**
    * Get formatted string value and className for cell.
    */
-  getFormatting(cell: CellAddress): { value?: string; classNames?: ClassNameValue } {
-    const value = this.model.getValue(cell);
+  getFormatting(cell: CellAddress): CellFormat {
+    const value = this._model.getValue(cell);
     if (value === undefined || value === null) {
       return {};
     }
@@ -23,15 +30,15 @@ export class FormattingModel {
     const locales = undefined;
 
     // Cell-specific formatting.
-    const idx = this.model.addressToIndex(cell);
-    let formatting = this.model.sheet.formatting?.[idx] ?? {};
+    const idx = addressToIndex(this._model.sheet, cell);
+    let formatting = this._model.sheet.formatting?.[idx] ?? {};
     const classNames = [...(formatting?.classNames ?? [])];
 
     // Range formatting.
     // TODO(burdon): NOTE: D0 means the D column.
     // TODO(burdon): Cache model formatting (e.g., for ranges). Create class out of this function.
-    for (const [idx, _formatting] of Object.entries(this.model.sheet.formatting)) {
-      const range = this.model.rangeFromIndex(idx);
+    for (const [idx, _formatting] of Object.entries(this._model.sheet.formatting)) {
+      const range = rangeFromIndex(this._model.sheet, idx);
       if (inRange(range, cell)) {
         if (_formatting.classNames) {
           classNames.push(..._formatting.classNames);
@@ -46,7 +53,7 @@ export class FormattingModel {
 
     const defaultNumber = 'justify-end font-mono';
 
-    const type = formatting?.type ?? this.model.getValueType(cell);
+    const type = formatting?.type ?? this._model.getValueType(cell);
     switch (type) {
       case ValueTypeEnum.Boolean: {
         return {
@@ -84,17 +91,17 @@ export class FormattingModel {
       //
 
       case ValueTypeEnum.DateTime: {
-        const date = this.model.toLocalDate(value as number);
+        const date = this._model.toLocalDate(value as number);
         return { value: date.toLocaleString(locales), classNames };
       }
 
       case ValueTypeEnum.Date: {
-        const date = this.model.toLocalDate(value as number);
+        const date = this._model.toLocalDate(value as number);
         return { value: date.toLocaleDateString(locales), classNames };
       }
 
       case ValueTypeEnum.Time: {
-        const date = this.model.toLocalDate(value as number);
+        const date = this._model.toLocalDate(value as number);
         return { value: date.toLocaleTimeString(locales), classNames };
       }
 

package/src/model/index.ts

@@ -2,6 +2,5 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './functions';
-export * from './model';
-export * from './types';
+export * from './formatting-model';
+export * from './sheet-model';

package/src/model/sheet-model.ts

@@ -0,0 +1,399 @@
+//
+// 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 { invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+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 } from '../graph';
+import { type CellScalarValue, type CellValue, type SheetType, ValueTypeEnum } from '../types';
+
+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,
+};
+
+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.
+export class SheetModel extends Resource {
+  public readonly id = `model-${PublicKey.random().truncate()}`;
+
+  public readonly update = new Event();
+
+  private readonly _node: ComputeNode;
+
+  constructor(
+    private readonly _graph: ComputeGraph,
+    private readonly _sheet: SheetType,
+    private readonly _options: SheetModelOptions = {},
+  ) {
+    super();
+    // TODO(burdon): SheetModel should extend ComputeNode and be constructed via the graph.
+    this._node = this._graph.getOrCreateNode(createSheetName(this._sheet.id));
+    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,
+    };
+  }
+
+  /**
+   * Initialize sheet and engine.
+   */
+  protected override async _open() {
+    log('initialize', { id: this.id });
+    initialize(this._sheet);
+    this.reset();
+
+    // TODO(burdon): Event hierarchy?
+    // Listen for model updates (e.g., async calculations).
+    const unsubscribe = this._graph.update.on(() => this.update.emit());
+    this._ctx.onDispose(unsubscribe);
+  }
+
+  /**
+   * Update engine.
+   * NOTE: This resets the undo history.
+   * @deprecated
+   */
+  reset() {
+    this._node.hf.clearSheet(this._node.sheetId);
+    Object.entries(this._sheet.cells).forEach(([key, { value }]) => {
+      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.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.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) {
+    const topLeft = getTopLeft(range);
+    const values = this._iterRange(range, () => null);
+    this._node.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) {
+    this._node.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) {
+    this._node.hf.copy(toModelRange(this._node.sheetId, range));
+  }
+
+  paste(cell: CellAddress) {
+    if (!this._node.hf.isClipboardEmpty()) {
+      const changes = this._node.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() {
+    if (this._node.hf.isThereSomethingToUndo()) {
+      this._node.hf.undo();
+      this.update.emit();
+    }
+  }
+
+  redo() {
+    if (this._node.hf.isThereSomethingToRedo()) {
+      this._node.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.
+    const value = this._node.hf.getCellValue(toSimpleCellAddress(this._node.sheetId, cell));
+    if (value instanceof DetailedCellError) {
+      return value.toString();
+    }
+
+    return value;
+  }
+
+  /**
+   * Get value type.
+   */
+  getValueType(cell: CellAddress): ValueTypeEnum {
+    const addr = toSimpleCellAddress(this._node.sheetId, cell);
+    const type = this._node.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) {
+      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.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 {
+    return this._node.hf.numberToDateTime(num) as SimpleDateTime;
+  }
+
+  toDate(num: number): SimpleDate {
+    return this._node.hf.numberToDate(num) as SimpleDate;
+  }
+
+  toTime(num: number): SimpleDate {
+    return this._node.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/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './testing';

package/src/testing/testing.tsx

@@ -0,0 +1,66 @@
+//
+// 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, ComputeGraphRegistry } from '../graph';
+import { type CellValue, type CreateSheetOptions } from '../types';
+
+export const testSheetName = 'test';
+
+// TODO(thure): Remove this from the `/testing` entrypoint.
+export const createCells = (): Record<string, CellValue> => ({
+  B1: { value: 'Qty' },
+  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) => {
+  return useAsyncState(async () => {
+    if (!space || !graph) {
+      return;
+    }
+
+    const sheet = createSheet(options);
+    space.db.add(sheet);
+    return sheet;
+  }, [space, graph]);
+};
+
+export const withGraphDecorator: Decorator = (Story) => {
+  const [registry] = useState(new ComputeGraphRegistry());
+  return (
+    <ComputeGraphContextProvider registry={registry}>
+      <Story />
+    </ComputeGraphContextProvider>
+  );
+};