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

package/src/graph/compute-graph.ts

@@ -0,0 +1,290 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type FunctionPluginDefinition } from 'hyperformula';
+import { type ConfigParams } from 'hyperformula/typings/ConfigParams';
+import { type FunctionTranslationsPackage } from 'hyperformula/typings/interpreter';
+
+import { Event } from '@dxos/async';
+import { type SpaceId, type Space, Filter, fullyQualifiedId } from '@dxos/client/echo';
+import { Resource } from '@dxos/context';
+import { invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { FunctionType } from '@dxos/plugin-script/types';
+import { nonNullable } from '@dxos/util';
+
+import { HyperFormula } from '#hyperformula';
+import { FunctionContext, type FunctionContextOptions } from './async-function';
+import { ComputeNode } from './compute-node';
+import { EdgeFunctionPlugin, EdgeFunctionPluginTranslations } from './edge-function';
+import { defaultFunctions, type FunctionDefinition } from './function-defs';
+
+//
+// NOTE: The package.json file defines the packaged #hyperformula module.
+//
+
+// TODO(wittjosiah): Factor out.
+const OBJECT_ID_LENGTH = 60; // 33 (space id) + 26 (object id) + 1 (separator).
+
+// TODO(burdon): Change to "DX".
+const CUSTOM_FUNCTION = 'ECHO';
+
+export type ComputeGraphPlugin = {
+  plugin: FunctionPluginDefinition;
+  translations: FunctionTranslationsPackage;
+};
+
+export type ComputeGraphOptions = {
+  plugins?: ComputeGraphPlugin[];
+} & Partial<FunctionContextOptions> &
+  Partial<ConfigParams>;
+
+export const defaultOptions: ComputeGraphOptions = {
+  licenseKey: 'gpl-v3',
+  plugins: [
+    {
+      plugin: EdgeFunctionPlugin,
+      translations: EdgeFunctionPluginTranslations,
+    },
+  ],
+};
+
+/**
+ * Marker for sheets that are managed by an ECHO object.
+ */
+const PREFIX = '__';
+export const createSheetName = (id: string) => `${PREFIX}${id}`;
+export const getSheetId = (name: string): string | undefined =>
+  name.startsWith(PREFIX) ? name.slice(PREFIX.length) : undefined;
+
+/**
+ * NOTE: Async imports to decouple hyperformula deps.
+ */
+export const createComputeGraphRegistry = (options: Partial<FunctionContextOptions> = {}) => {
+  return new ComputeGraphRegistry({
+    ...defaultOptions,
+    ...options,
+  });
+};
+
+/**
+ * Manages a collection of ComputeGraph instances for each space.
+ *
+ * [ComputePlugin] => [ComputeGraphRegistry] => [ComputeGraph(Space)] => [ComputeNode(Object)]
+ */
+// TODO(burdon): Move graph into separate plugin; isolate HF deps.
+export class ComputeGraphRegistry extends Resource {
+  private readonly _registry = new Map<SpaceId, ComputeGraph>();
+
+  constructor(private readonly _options: ComputeGraphOptions = defaultOptions) {
+    super();
+    this._options.plugins?.forEach(({ plugin, translations }) => {
+      HyperFormula.registerFunctionPlugin(plugin, translations);
+    });
+  }
+
+  getGraph(spaceId: SpaceId): ComputeGraph | undefined {
+    return this._registry.get(spaceId);
+  }
+
+  async getOrCreateGraph(space: Space): Promise<ComputeGraph> {
+    let graph = this.getGraph(space.id);
+    if (!graph) {
+      log.info('create graph', { space: space.id });
+      graph = await this.createGraph(space);
+    }
+
+    return graph;
+  }
+
+  async createGraph(space: Space): Promise<ComputeGraph> {
+    invariant(!this._registry.has(space.id), `ComputeGraph already exists for space: ${space.id}`);
+    const hf = HyperFormula.buildEmpty(this._options);
+    const graph = new ComputeGraph(hf, space, this._options);
+    await graph.open(this._ctx);
+    this._registry.set(space.id, graph);
+    return graph;
+  }
+}
+
+/**
+ * Per-space compute and dependency graph.
+ * Consists of multiple ComputeNode (corresponding to a HyperFormula sheet).
+ * Manages the set of custom functions.
+ * HyperFormula manages the dependency graph.
+ */
+// TODO(burdon): Tests.
+export class ComputeGraph extends Resource {
+  public readonly id = `graph-${PublicKey.random().truncate()}`;
+
+  // Map of nodes indexed by sheet number.
+  private readonly _nodes = new Map<number, ComputeNode>();
+
+  // Cached function objects.
+  private _functions: FunctionType[] = [];
+
+  // The context is passed to all functions.
+  public readonly context = new FunctionContext(this._hf, this._space, this.refresh.bind(this), this._options);
+
+  // TODO(burdon): Typed events.
+  // TODO(burdon): Tie into HyperFormula dependency graph.
+  // TODO(burdon): Event propagation.
+  public readonly update = new Event();
+
+  constructor(
+    private readonly _hf: HyperFormula,
+    private readonly _space?: Space,
+    private readonly _options?: Partial<FunctionContextOptions>,
+  ) {
+    super();
+
+    this._hf.updateConfig({ context: this.context });
+  }
+
+  // TODO(burdon): Remove.
+  get hf() {
+    return this._hf;
+  }
+
+  refresh() {
+    log('refresh', { id: this.id });
+    this.update.emit();
+  }
+
+  getFunctions({ standard = true, echo = true }: { standard?: boolean; echo?: boolean } = {}): FunctionDefinition[] {
+    return [
+      ...(standard
+        ? this._hf
+            .getRegisteredFunctionNames()
+            .map((name) => defaultFunctions.find((fn) => fn.name === name) ?? { name })
+        : []),
+      ...(echo ? this._functions.map((fn) => ({ name: fn.binding! })) : []),
+    ];
+  }
+
+  /**
+   * Get or create cell representing a sheet.
+   */
+  // TODO(burdon): Async (open node).
+  //  The graph should be an extensible factory that plugins extend with model constructors.
+  //  This would enable on-the-fly instantiation of new models when then are referenced.
+  //  E.g., Cross-object reference would be stored as "ObjectId!A1"
+  //  The graph would then load the object and create a ComputeNode (model) of the appropriate type.
+  getOrCreateNode(name: string): ComputeNode {
+    invariant(name.length);
+    if (!this._hf.doesSheetExist(name)) {
+      log.info('created node', { space: this._space?.id, name });
+      this._hf.addSheet(name);
+      this.update.emit();
+    }
+
+    const sheetId = this._hf.getSheetId(name);
+    invariant(sheetId !== undefined);
+
+    // TODO(burdon): Chain context?
+    const node = new ComputeNode(this, sheetId);
+    this._nodes.set(sheetId, node);
+    return node;
+  }
+
+  /**
+   * Map bound value to custom function invocation.
+   * E.g., "HELLO(...args)" => "EDGE("HELLO", ...args)".
+   */
+  mapFormulaToNative(formula: string): string {
+    return (
+      formula
+        // Sheet references.
+        // https://hyperformula.handsontable.com/guide/cell-references.html#cell-references
+        .replace(/['"]?([ \w]+)['"]?!/, (_match, name) => {
+          if (name) {
+            // TODO(burdon): What if not loaded?
+            const objects = this._hf
+              .getSheetNames()
+              .map((name) => {
+                const id = getSheetId(name);
+                return id ? this._space?.db.getObjectById(id) : undefined;
+              })
+              .filter(nonNullable);
+
+            for (const obj of objects) {
+              if (obj.name === name || obj.title === name) {
+                return `${createSheetName(obj.id)}!`;
+              }
+            }
+          }
+
+          return `${name}!`;
+        })
+
+        // Functions.
+        .replace(/(\w+)\((.*)\)/g, (match, binding, args) => {
+          const fn = this._functions.find((fn) => fn.binding === binding);
+          if (!fn) {
+            return match;
+          }
+
+          if (args.trim() === '') {
+            return `${CUSTOM_FUNCTION}("${binding}")`;
+          } else {
+            return `${CUSTOM_FUNCTION}("${binding}", ${args})`;
+          }
+        })
+    );
+  }
+
+  /**
+   * Map from binding to fully qualified ECHO ID (to store).
+   * E.g., HELLO() => spaceId:objectId()
+   */
+  mapFunctionBindingToId(formula: string) {
+    return formula.replace(/(\w+)\((.*)\)/g, (match, binding, args) => {
+      if (binding === CUSTOM_FUNCTION || defaultFunctions.find((fn) => fn.name === binding)) {
+        return match;
+      }
+
+      const fn = this._functions.find((fn) => fn.binding === binding);
+      if (fn) {
+        const id = fullyQualifiedId(fn);
+        return `${id}(${args})`;
+      } else {
+        return match;
+      }
+    });
+  }
+
+  /**
+   * Map from fully qualified ECHO ID to binding (from store).
+   * E.g., spaceId:objectId() => HELLO()
+   */
+  mapFunctionBindingFromId(formula: string) {
+    return formula.replace(/(\w+):([a-zA-Z0-9]+)\((.*)\)/g, (match, spaceId, objectId, args) => {
+      const id = `${spaceId}:${objectId}`;
+      if (id.length !== OBJECT_ID_LENGTH) {
+        return match;
+      }
+
+      const fn = this._functions.find((fn) => fullyQualifiedId(fn) === id);
+      if (fn?.binding) {
+        return `${fn.binding}(${args})`;
+      } else {
+        return match;
+      }
+    });
+  }
+
+  protected override async _open() {
+    if (this._space) {
+      // Subscribe to remote function definitions.
+      const query = this._space.db.query(Filter.schema(FunctionType));
+      const unsubscribe = query.subscribe(({ objects }) => {
+        this._functions = objects.filter(({ binding }) => binding);
+        this.update.emit();
+      });
+
+      this._ctx.onDispose(unsubscribe);
+    }
+  }
+}

package/src/graph/compute-node.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Event } from '@dxos/async';
+import { Resource } from '@dxos/context';
+
+import { DetailedCellError } from '#hyperformula';
+import { type ComputeGraph } from './compute-graph';
+import { type CellAddress } from '../defs';
+import { type CellScalarValue } from '../types';
+
+/**
+ * Individual "sheet" (typically corresponds to an ECHO object).
+ */
+// TODO(burdon): Factor out common HF wrapper from from SheetModel.
+export class ComputeNode extends Resource {
+  // TODO(burdon): Chaing events.
+  public readonly update = new Event();
+
+  constructor(
+    private readonly _graph: ComputeGraph,
+    public readonly sheetId: number,
+  ) {
+    super();
+  }
+
+  // TODO(burdon): Remove?
+  get graph() {
+    return this._graph;
+  }
+
+  get hf() {
+    return this._graph.hf;
+  }
+
+  getValue(cell: CellAddress): CellScalarValue {
+    const value = this._graph.hf.getCellValue({ sheet: this.sheetId, row: cell.row, col: cell.col });
+    if (value instanceof DetailedCellError) {
+      return null;
+    }
+
+    return value;
+  }
+
+  setValue(cell: CellAddress, value: CellScalarValue) {
+    const mappedValue =
+      typeof value === 'string' && value.charAt(0) === '=' ? this._graph.mapFormulaToNative(value) : value;
+    this._graph.hf.setCellContents({ sheet: this.sheetId, row: cell.row, col: cell.col }, [[mappedValue]]);
+  }
+}

package/src/{components/ComputeGraph/custom.ts → graph/custom-function.ts}

@@ -2,18 +2,14 @@
 // 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 { FunctionArgumentType } from '#hyperformula';
 import { type AsyncFunction, FunctionPluginAsync } from './async-function';
-
-// TODO(burdon): Factor out.
-const parseNumberString = (str: string): number => {
-  return parseFloat(str.replace(/[^\d.]/g, ''));
-};
+import { parseNumberString } from './util';
 
 /**
  * https://hyperformula.handsontable.com/guide/custom-functions.html#add-a-simple-custom-function

package/src/{components/ComputeGraph → graph}/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,6 +12,7 @@ import { getUserFunctionUrlInMetadata } from '@dxos/plugin-script/edge';
 import { FunctionType } from '@dxos/plugin-script/types';
 import { nonNullable } from '@dxos/util';
 
+import { CellError, ErrorType, FunctionArgumentType } from '#hyperformula';
 import { type AsyncFunction, FunctionPluginAsync } from './async-function';
 
 const EDGE_FUNCTION_TTL = 10_000;
@@ -59,6 +59,7 @@ export class EdgeFunctionPlugin extends FunctionPluginAsync {
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({ args: args.filter(nonNullable) }),
         });
+
         return await result.text();
       };
 

package/src/graph/hyperformula.test.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { describe, test, expect } from 'vitest';
+
+import { HyperFormula } from '#hyperformula';
+
+describe('hyperformula', () => {
+  test('sanity', async () => {
+    // TODO(burdon): Throws "Cannot convert undefined or null to object" in vitest (without browser).
+    const hf = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
+    expect(hf).to.exist;
+  });
+});

package/src/graph/index.ts

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

package/src/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/hooks/hooks.stories.tsx

@@ -0,0 +1,50 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import '@dxos-theme';
+
+import React, { useEffect, useState } from 'react';
+
+import { useSpace } from '@dxos/react-client/echo';
+import { withClientProvider } from '@dxos/react-client/testing';
+import { SyntaxHighlighter } from '@dxos/react-ui-syntax-highlighter';
+import { withTheme } from '@dxos/storybook-utils';
+
+import { ComputeGraphContextProvider } from '../components';
+import { createSheet } from '../defs';
+import { useComputeGraph, useSheetModel } from '../hooks';
+import { withGraphDecorator } from '../testing';
+import { SheetType } from '../types';
+
+const Story = () => {
+  const space = useSpace();
+  const graph = useComputeGraph(space);
+  const [sheet, setSheet] = useState<SheetType>();
+  const model = useSheetModel(space, sheet);
+  useEffect(() => {
+    if (space) {
+      const sheet = space.db.add(createSheet());
+      setSheet(sheet);
+    }
+  }, [space]);
+
+  return (
+    <SyntaxHighlighter language='json'>
+      {JSON.stringify({ space: space?.id, graph: graph?.id, sheet: sheet?.id, model: model?.id }, null, 2)}
+    </SyntaxHighlighter>
+  );
+};
+
+export default {
+  title: 'plugin-sheet/hooks',
+  component: ComputeGraphContextProvider,
+  decorators: [
+    withClientProvider({ types: [SheetType], createIdentity: true, createSpace: true }),
+    withGraphDecorator,
+    withTheme,
+  ],
+  render: (args: any) => <Story {...args} />,
+};
+
+export const Default = {};

package/src/hooks/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './useComputeGraph';
+export * from './useFormattingModel';
+export * from './useSheetModel';

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';