@dxos/plugin-sheet 0.6.13 → 0.6.14-staging.9e90729

package/src/{components/ComputeGraph → compute-graph/functions}/edge-function.ts

@@ -3,7 +3,6 @@
 //
 
 import { effect } from '@preact/signals-core';
-import { CellError, ErrorType, FunctionArgumentType } from 'hyperformula';
 import { type InterpreterState } from 'hyperformula/typings/interpreter/InterpreterState';
 import { type ProcedureAst } from 'hyperformula/typings/parser';
 
@@ -13,17 +12,20 @@ import { getUserFunctionUrlInMetadata } from '@dxos/plugin-script/edge';
 import { FunctionType } from '@dxos/plugin-script/types';
 import { nonNullable } from '@dxos/util';
 
-import { type AsyncFunction, FunctionPluginAsync } from './async-function';
+import { CellError, ErrorType, FunctionArgumentType } from '#hyperformula';
+import { type AsyncFunction, AsyncFunctionPlugin } from './async-function';
 
-const EDGE_FUNCTION_TTL = 10_000;
+export const EDGE_FUNCTION_NAME = 'DX';
+
+const FUNCTION_TTL = 10_000;
 
 /**
- * A hyperformula function plugin for calling EDGE functions.
+ * A hyperformula function plugin for calling remote (EDGE) functions.
  *
  * https://hyperformula.handsontable.com/guide/custom-functions.html#add-a-simple-custom-function
  */
-export class EdgeFunctionPlugin extends FunctionPluginAsync {
-  edge(ast: ProcedureAst, state: InterpreterState) {
+export class EdgeFunctionPlugin extends AsyncFunctionPlugin {
+  dx(ast: ProcedureAst, state: InterpreterState) {
     const handler =
       (subscribe = false): AsyncFunction =>
       async (binding: string, ...args: any) => {
@@ -47,7 +49,7 @@ export class EdgeFunctionPlugin extends FunctionPluginAsync {
 
             // TODO(wittjosiah): `ttl` should be 0 to force a recalculation when a new version is deployed.
             //  This needs a ttl to prevent a binding change from causing the function not to be found.
-            this.runAsyncFunction(ast, state, handler(false), { ttl: EDGE_FUNCTION_TTL });
+            this.runAsyncFunction(ast, state, handler(false), { ttl: FUNCTION_TTL });
           });
 
           this.context.createSubscription(ast.procedureName, unsubscribe);
@@ -59,22 +61,22 @@ export class EdgeFunctionPlugin extends FunctionPluginAsync {
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({ args: args.filter(nonNullable) }),
         });
+
         return await result.text();
       };
 
-    return this.runAsyncFunction(ast, state, handler(true), { ttl: EDGE_FUNCTION_TTL });
+    return this.runAsyncFunction(ast, state, handler(true), { ttl: FUNCTION_TTL });
   }
 }
 
 EdgeFunctionPlugin.implementedFunctions = {
-  EDGE: {
-    method: 'edge',
+  [EDGE_FUNCTION_NAME]: {
+    method: 'dx',
     parameters: [
       // Binding
       { argumentType: FunctionArgumentType.STRING },
 
-      // Remote function arguments (currently supporting up to 9).
-      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+      // Remote function arguments (currently supporting up to 8).
       { argumentType: FunctionArgumentType.ANY, optionalArg: true },
       { argumentType: FunctionArgumentType.ANY, optionalArg: true },
       { argumentType: FunctionArgumentType.ANY, optionalArg: true },
@@ -90,9 +92,9 @@ EdgeFunctionPlugin.implementedFunctions = {
 
 export const EdgeFunctionPluginTranslations = {
   enGB: {
-    EDGE: 'EDGE',
+    [EDGE_FUNCTION_NAME]: 'Remote function',
   },
   enUS: {
-    EDGE: 'EDGE',
+    [EDGE_FUNCTION_NAME]: 'Remote function',
   },
 };

package/src/compute-graph/functions/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './async-function';
+export * from './edge-function';
+export * from './function-defs';

package/src/compute-graph/hyperformula.test.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { describe, test, expect } from 'vitest';
+
+import { HyperFormula } from '#hyperformula';
+
+describe('hyperformula', () => {
+  test('sanity test', async () => {
+    const hf = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
+    expect(hf).to.exist;
+  });
+});

package/src/compute-graph/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './compute-graph';
+export * from './compute-graph-registry';
+export * from './compute-node';
+export * from './functions';

package/src/compute-graph/testing/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './test-builder';
+export * from './test-plugin';

package/src/compute-graph/testing/test-builder.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Client, type ClientOptions } from '@dxos/client';
+import { type Context, Resource } from '@dxos/context';
+import { invariant } from '@dxos/invariant';
+
+import { type ComputeGraphOptions, ComputeGraphRegistry } from '../compute-graph-registry';
+
+export type TestBuilderOptions = ClientOptions & ComputeGraphOptions;
+
+// TODO(burdon): Reconcile with @dxos/client/testing.
+export class TestBuilder extends Resource {
+  private _client?: Client;
+  private _registry?: ComputeGraphRegistry;
+
+  constructor(private readonly _options: TestBuilderOptions = {}) {
+    super();
+  }
+
+  get ctx(): Context {
+    return this._ctx;
+  }
+
+  get client(): Client {
+    invariant(this._client);
+    return this._client;
+  }
+
+  get registry(): ComputeGraphRegistry {
+    invariant(this._registry);
+    return this._registry;
+  }
+
+  override async _open() {
+    const client = new Client(this._options);
+    await client.initialize();
+    await client.halo.createIdentity();
+    this._client = client;
+    this._ctx.onDispose(async () => {
+      await client.destroy();
+      this._client = undefined;
+    });
+
+    const registry = new ComputeGraphRegistry(this._options);
+    await registry.open();
+    this._registry = registry;
+    this._ctx.onDispose(async () => {
+      await registry.close();
+      this._registry = undefined;
+    });
+  }
+}

package/src/{components/ComputeGraph/custom.ts → compute-graph/testing/test-plugin.ts}

@@ -2,24 +2,36 @@
 // Copyright 2024 DXOS.org
 //
 
-import { FunctionArgumentType } from 'hyperformula';
 import { type InterpreterState } from 'hyperformula/typings/interpreter/InterpreterState';
 import { type ProcedureAst } from 'hyperformula/typings/parser';
 
 import { getDeep } from '@dxos/util';
 
-import { type AsyncFunction, FunctionPluginAsync } from './async-function';
-
-// TODO(burdon): Factor out.
-const parseNumberString = (str: string): number => {
-  return parseFloat(str.replace(/[^\d.]/g, ''));
-};
+import { FunctionArgumentType } from '#hyperformula';
+import { type ComputeGraphPlugin } from '../compute-graph-registry';
+import { type AsyncFunction, AsyncFunctionPlugin } from '../functions';
+import { parseNumberString } from '../util';
 
 /**
+ * Testing functions run locally (not run via EDGE).
  * https://hyperformula.handsontable.com/guide/custom-functions.html#add-a-simple-custom-function
  */
-export class CustomPlugin extends FunctionPluginAsync {
+export class TestPlugin extends AsyncFunctionPlugin {
+  /**
+   * Simple local function returns input value.
+   */
   test(ast: ProcedureAst, state: InterpreterState) {
+    const handler: AsyncFunction = async (_value) => {
+      return _value;
+    };
+
+    return this.runAsyncFunction(ast, state, handler);
+  }
+
+  /**
+   * Simple local function returns random number.
+   */
+  random(ast: ProcedureAst, state: InterpreterState) {
     const handler: AsyncFunction = async () => {
       return Math.random();
     };
@@ -27,6 +39,9 @@ export class CustomPlugin extends FunctionPluginAsync {
     return this.runAsyncFunction(ast, state, handler);
   }
 
+  /**
+   * Async HTTP function.
+   */
   crypto(ast: ProcedureAst, state: InterpreterState) {
     const handler: AsyncFunction = async (_currency) => {
       const currency = (_currency || 'USD').toUpperCase();
@@ -44,9 +59,15 @@ export class CustomPlugin extends FunctionPluginAsync {
   }
 }
 
-CustomPlugin.implementedFunctions = {
+TestPlugin.implementedFunctions = {
   TEST: {
     method: 'test',
+    parameters: [{ argumentType: FunctionArgumentType.NUMBER, optionalArg: false }],
+    isVolatile: true,
+  },
+
+  RANDOM: {
+    method: 'random',
     parameters: [],
     isVolatile: true,
   },
@@ -58,13 +79,22 @@ CustomPlugin.implementedFunctions = {
   },
 };
 
-export const CustomPluginTranslations = {
+export const TestPluginTranslations = {
   enGB: {
-    TEST: 'TEST',
-    CRYPTO: 'CRYPTO',
+    TEST: 'Returns input value',
+    RANDOM: 'Random number',
+    CRYPTO: 'Crypto token value',
   },
   enUS: {
-    TEST: 'TEST',
-    CRYPTO: 'CRYPTO',
+    TEST: 'Returns input value',
+    RANDOM: 'Random number',
+    CRYPTO: 'Crypto token value',
   },
 };
+
+export const testFunctionPlugins: ComputeGraphPlugin[] = [
+  {
+    plugin: TestPlugin,
+    translations: TestPluginTranslations,
+  },
+];

package/src/compute-graph/util.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// TODO(burdon): Factor out.
+export const parseNumberString = (str: string): number => {
+  return parseFloat(str.replace(/[^\d.]/g, ''));
+};

package/src/defs/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './sheet-range-types';
+export * from './types';
+export * from './util';

package/src/defs/sheet-range-types.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type ClassNameValue } from '@dxos/react-ui';
+
+import { type SheetType } from '../types';
+
+export const alignKey = 'align';
+export type AlignKey = typeof alignKey;
+export type AlignValue = 'start' | 'center' | 'end' | 'unset';
+
+export const commentKey = 'comment';
+export type CommentKey = typeof commentKey;
+export type CommentValue = string;
+
+export const styleKey = 'style';
+export type StyleKey = typeof styleKey;
+export type StyleValue = 'highlight' | 'unset';
+
+// TODO(burdon): Reconcile with plugin-table.
+export const cellClassNameForRange = ({ key, value }: SheetType['ranges'][number]): ClassNameValue => {
+  switch (key) {
+    case 'align':
+      switch (value) {
+        case 'start':
+          return 'text-start';
+        case 'center':
+          return 'text-center';
+        case 'end':
+          return 'text-end';
+        default:
+          return undefined;
+      }
+    case 'comment':
+      return 'bg-gridComment';
+    case 'style':
+      switch (value) {
+        case 'highlight':
+          return 'bg-gridHighlight';
+        default:
+          return undefined;
+      }
+    default:
+      return undefined;
+  }
+};

package/src/{model → defs}/types.test.ts

@@ -3,15 +3,14 @@
 //
 
 import { getIndices, sortByIndex, getIndicesBelow, getIndicesAbove, getIndicesBetween } from '@tldraw/indices';
-import { expect } from 'chai';
-import { describe, test } from 'vitest';
+import { describe, expect, 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 });
+    expect(addressToA1Notation({ col: 0, row: 0 })).to.eq('A1');
+    expect(addressFromA1Notation('C2')).to.deep.eq({ col: 2, row: 1 });
   });
 
   test('rangeToA1Notation', () => {
@@ -56,19 +55,19 @@ describe('cell', () => {
     // Values.
     const cells: Record<string, any> = {};
     const setCell = (cell: string, value: any) => {
-      const { column, row } = addressFromA1Notation(cell);
+      const { col, row } = addressFromA1Notation(cell);
       // Reallocate if > current bounds.
-      if (column >= columns.length) {
-        insertIndex(columns, column);
+      if (col >= columns.length) {
+        insertIndex(columns, col);
       }
       if (row >= rows.length) {
         insertIndex(rows, row);
       }
-      const index = `${columns[column]}@${rows[row]}`;
+      const index = `${columns[col]}@${rows[row]}`;
       cells[index] = value;
     };
 
-    expect(addressFromA1Notation('A1')).to.deep.eq({ column: 0, row: 0 });
+    expect(addressFromA1Notation('A1')).to.deep.eq({ col: 0, row: 0 });
 
     expect(columns).to.deep.eq(['a1', 'a2', 'a3', 'a4', 'a5']);
     insertIndex(columns, 7);

package/src/defs/types.ts

@@ -0,0 +1,86 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+
+export const DEFAULT_ROWS = 50;
+export const DEFAULT_COLUMNS = 26;
+
+export const MAX_ROWS = 500;
+export const MAX_COLUMNS = 26 * 2;
+
+export type CellAddress = { col: number; row: number };
+
+export type CellRange = { from: CellAddress; to?: CellAddress };
+export type CompleteCellRange = { from: CellAddress; to: CellAddress };
+
+export type CellIndex = string;
+
+export type CellContentValue = number | string | boolean | null;
+
+export const RANGE_NOTATION = /^[A-Z]+[0-9]+(:[A-Z]+[0-9]+)?$/;
+
+export const isFormula = (value: any): value is string => typeof value === 'string' && value.charAt(0) === '=';
+
+export const posEquals = (a: CellAddress | undefined, b: CellAddress | undefined) => {
+  return a?.col === b?.col && a?.row === b?.row;
+};
+
+export const columnLetter = (col: number): string => {
+  invariant(col < MAX_COLUMNS, `Invalid column: ${col}`);
+  return (
+    (col >= 26 ? String.fromCharCode('A'.charCodeAt(0) + Math.floor(col / 26) - 1) : '') +
+    String.fromCharCode('A'.charCodeAt(0) + (col % 26))
+  );
+};
+
+export const addressToA1Notation = ({ col, row }: CellAddress): string => {
+  return `${columnLetter(col)}${row + 1}`;
+};
+
+// TODO(burdon): See (HF) simpleCellAddressFromString.
+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,
+    col: 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 { col: c1, row: r1 } = from;
+  const { col: 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 { col, row } = cell;
+  return col >= cMin && col <= cMax && row >= rMin && row <= rMax;
+};

package/src/defs/util.ts

@@ -0,0 +1,135 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { randomBytes } from '@dxos/crypto';
+import { create } from '@dxos/echo-schema';
+
+import {
+  addressFromA1Notation,
+  type CellAddress,
+  type CellRange,
+  type CompleteCellRange,
+  DEFAULT_COLUMNS,
+  DEFAULT_ROWS,
+  MAX_COLUMNS,
+  MAX_ROWS,
+} from './types';
+import { type CreateSheetOptions, type SheetSize, SheetType } from '../types';
+
+// 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());
+
+export const 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);
+};
+
+export const initialize = (
+  sheet: SheetType,
+  { rows = DEFAULT_ROWS, columns = DEFAULT_COLUMNS }: Partial<SheetSize> = {},
+) => {
+  if (!sheet.rows.length) {
+    insertIndices(sheet.rows, 0, rows, MAX_ROWS);
+  }
+  if (!sheet.columns.length) {
+    insertIndices(sheet.columns, 0, columns, MAX_COLUMNS);
+  }
+};
+
+export const createSheet = ({ name, cells, ...size }: CreateSheetOptions = {}): SheetType => {
+  const sheet = create(SheetType, {
+    name,
+    cells: {},
+    rows: [],
+    columns: [],
+    rowMeta: {},
+    columnMeta: {},
+    ranges: [],
+    threads: [],
+  });
+
+  initialize(sheet, size);
+
+  if (cells) {
+    Object.entries(cells).forEach(([key, { value }]) => {
+      const idx = addressToIndex(sheet, addressFromA1Notation(key));
+      sheet.cells[idx] = { value };
+    });
+  }
+
+  return sheet;
+};
+
+/**
+ * E.g., "A1" => "CA2@CB3".
+ */
+export const addressToIndex = (sheet: SheetType, cell: CellAddress): string => {
+  return `${sheet.columns[cell.col]}@${sheet.rows[cell.row]}`;
+};
+
+/**
+ * E.g., "CA2@CB3" => "A1".
+ */
+export const addressFromIndex = (sheet: SheetType, idx: string): CellAddress => {
+  const [column, row] = idx.split('@');
+  return {
+    col: sheet.columns.indexOf(column),
+    row: sheet.rows.indexOf(row),
+  };
+};
+
+/**
+ * E.g., "A1:B2" => "CA2@CB3:CC4@CD5".
+ */
+export const rangeToIndex = (sheet: SheetType, range: CellRange): string => {
+  return [range.from, range.to ?? range.from].map((cell) => addressToIndex(sheet, cell)).join(':');
+};
+
+/**
+ * E.g., "CA2@CB3:CC4@CD5" => "A1:B2".
+ */
+export const rangeFromIndex = (sheet: SheetType, idx: string): CompleteCellRange => {
+  const [from, to] = idx.split(':').map((index) => addressFromIndex(sheet, index));
+  return { from, to };
+};
+
+/**
+ * Compares the positions of two cell indexes in a sheet.
+ * Sorts primarily by row, then by column if rows are equal.
+ */
+export const compareIndexPositions = (sheet: SheetType, indexA: string, indexB: string): number => {
+  const { row: rowA, col: columnA } = addressFromIndex(sheet, indexA);
+  const { row: rowB, col: columnB } = addressFromIndex(sheet, indexB);
+
+  // Sort by row first, then by column.
+  if (rowA !== rowB) {
+    return rowA - rowB;
+  } else {
+    return columnA - columnB;
+  }
+};