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

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,49 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type ClassNameValue } from '@dxos/react-ui';
+
+import { type SheetType } from '../types';
+
+export const alignKey = 'alignment';
+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' | 'softwrap';
+
+// TODO(burdon): Reconcile with plugin-table.
+export const cellClassNameForRange = ({ key, value }: SheetType['ranges'][number]): ClassNameValue => {
+  switch (key) {
+    case alignKey:
+      switch (value) {
+        case 'start':
+          return 'text-start';
+        case 'center':
+          return 'text-center';
+        case 'end':
+          return 'text-end';
+        default:
+          return undefined;
+      }
+    case commentKey:
+      return 'bg-gridComment';
+    case styleKey:
+      switch (value) {
+        case 'highlight':
+          return '!bg-gridHighlight';
+        case 'softwrap':
+          return '!whitespace-normal';
+        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,136 @@
+//
+// 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);
+  return 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;
+  }
+};

package/src/extensions/compute.stories.tsx

@@ -0,0 +1,155 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type Meta } from '@storybook/react';
+import React, { useEffect, useMemo } from 'react';
+
+import { PublicKey } from '@dxos/keys';
+import { useSpace } from '@dxos/react-client/echo';
+import { withClientProvider } from '@dxos/react-client/testing';
+import { useThemeContext } from '@dxos/react-ui';
+import {
+  createBasicExtensions,
+  createMarkdownExtensions,
+  createThemeExtensions,
+  decorateMarkdown,
+  documentId,
+  useTextEditor,
+} from '@dxos/react-ui-editor';
+import { withTheme, withLayout } from '@dxos/storybook-utils';
+import { nonNullable } from '@dxos/util';
+
+import { compute, computeGraphFacet } from './compute';
+import { GridSheet, SheetProvider, useComputeGraph } from '../components';
+import { useSheetModel } from '../model';
+import { useTestSheet, withComputeGraphDecorator } from '../testing';
+import { SheetType } from '../types';
+
+const str = (...lines: string[]) => lines.join('\n');
+
+type EditorProps = {
+  text?: string;
+};
+
+// TODO(burdon): Implement named expressions.
+//  https://hyperformula.handsontable.com/guide/cell-references.html
+
+// TODO(burdon): Inline Adobe eCharts.
+
+const SHEET_NAME = 'Test Sheet';
+
+const EditorStory = ({ text }: EditorProps) => {
+  const id = useMemo(() => PublicKey.random(), []);
+  const { themeMode } = useThemeContext();
+  const space = useSpace();
+  const computeGraph = useComputeGraph(space);
+  const { parentRef, focusAttributes } = useTextEditor(
+    () => ({
+      initialValue: text,
+      extensions: [
+        createBasicExtensions(),
+        createMarkdownExtensions({ themeMode }),
+        createThemeExtensions({ themeMode, syntaxHighlighting: true }),
+        documentId.of(id.toHex()),
+        computeGraph && computeGraphFacet.of(computeGraph),
+        compute(),
+        decorateMarkdown(),
+      ].filter(nonNullable),
+    }),
+    [computeGraph, themeMode],
+  );
+
+  return <div className='w-[40rem] overflow-hidden' ref={parentRef} {...focusAttributes} />;
+};
+
+const Grid = () => {
+  const space = useSpace();
+  const graph = useComputeGraph(space);
+  const sheet = useTestSheet(space, graph, { name: SHEET_NAME });
+  const model = useSheetModel(graph, sheet);
+  useEffect(() => {
+    if (model) {
+      model.setValues({ A1: { value: 100 }, A2: { value: 200 }, A3: { value: 300 }, A5: { value: '=SUM(A1:A3)' } });
+    }
+  }, [model]);
+
+  if (!graph || !sheet) {
+    return null;
+  }
+
+  return (
+    <div className='flex w-[40rem] overflow-hidden'>
+      <SheetProvider graph={graph} sheet={sheet}>
+        <GridSheet />
+      </SheetProvider>
+    </div>
+  );
+};
+
+const GraphStory = (props: EditorProps) => {
+  return (
+    <div className='grid grid-rows-2'>
+      <EditorStory {...props} />
+      <Grid />
+    </div>
+  );
+};
+
+// TODO(burdon): Inline formulae.
+export const Default = {
+  render: EditorStory,
+  args: {
+    text: str(
+      //
+      '# Compute Graph',
+      '',
+      'This is a compute expression:',
+      '',
+      '```dx',
+      '=SUM(1, 2)',
+      '```',
+      '',
+      'It should change in realtime.',
+      '',
+      '```dx',
+      '=SUM(3, 5)',
+      '```',
+      '',
+      '',
+    ),
+  },
+};
+
+export const Graph = {
+  render: GraphStory,
+  args: {
+    text: str(
+      //
+      '# Compute Graph',
+      '',
+      'The total projected cost is:',
+      '',
+      '```dx',
+      `="${SHEET_NAME}"!A5`,
+      '```',
+      '',
+      '',
+    ),
+  },
+};
+
+const meta: Meta = {
+  title: 'plugins/plugin-sheet/extensions',
+  decorators: [
+    withClientProvider({ types: [SheetType], createIdentity: true, createSpace: true }),
+    withComputeGraphDecorator(),
+    withTheme,
+    withLayout({ fullscreen: true, classNames: 'justify-center' }),
+  ],
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;