@dxos/plugin-sheet 0.6.12-main.f9d0246 → 0.6.12-staging.0b4bb48

package/src/graph/compute-graph.ts

@@ -1,313 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { type FunctionPluginDefinition } from 'hyperformula';
-import { type ConfigParams } from 'hyperformula/typings/ConfigParams';
-import { type Listeners } from 'hyperformula/typings/Emitter';
-import { type FunctionTranslationsPackage } from 'hyperformula/typings/interpreter';
-import defaultsDeep from 'lodash.defaultsdeep';
-
-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 { ExportedCellChange, 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',
-};
-
-export const defaultPlugins: ComputeGraphPlugin[] = [
-  {
-    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;
-
-/**
- * Manages a collection of ComputeGraph instances for each space.
- *
- * [ComputePlugin] => [ComputeGraphRegistry] => [ComputeGraph(Space)] => [ComputeNode(Object)]
- *
- * NOTE: The ComputeGraphRegistry manages the hierarchy of resources via its root Context.
- */
-// TODO(burdon): Move graph into separate plugin; isolate HF deps.
-export class ComputeGraphRegistry extends Resource {
-  private readonly _graphs = new Map<SpaceId, ComputeGraph>();
-
-  private readonly _options: ComputeGraphOptions;
-
-  constructor(options: ComputeGraphOptions = { plugins: defaultPlugins }) {
-    super();
-    this._options = defaultsDeep({}, options, defaultOptions);
-    this._options.plugins?.forEach(({ plugin, translations }) => {
-      HyperFormula.registerFunctionPlugin(plugin, translations);
-    });
-  }
-
-  getGraph(spaceId: SpaceId): ComputeGraph | undefined {
-    return this._graphs.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._graphs.has(space.id), `ComputeGraph already exists for space: ${space.id}`);
-    const hf = HyperFormula.buildEmpty(this._options);
-    const graph = new ComputeGraph(hf, space, this._options);
-    this._graphs.set(space.id, graph);
-    await graph.open();
-    return graph;
-  }
-
-  protected override async _close() {
-    for (const graph of this._graphs.values()) {
-      await graph.close();
-    }
-  }
-}
-
-export type ComputeGraphEvent = 'functionsUpdated';
-
-/**
- * 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.
- */
-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[] = [];
-
-  public readonly update = new Event<{ type: ComputeGraphEvent }>();
-
-  // The context is passed to all functions.
-  public readonly context = new FunctionContext(this._hf, this._space, this._options);
-
-  constructor(
-    private readonly _hf: HyperFormula,
-    private readonly _space?: Space,
-    private readonly _options?: Partial<FunctionContextOptions>,
-  ) {
-    super();
-    this._hf.updateConfig({ context: this.context });
-    // TODO(burdon): If debounce then aggregate changes.
-    const onValuesUpdate: Listeners['valuesUpdated'] = (changes) => {
-      for (const change of changes) {
-        if (change instanceof ExportedCellChange) {
-          const { sheet } = change;
-          const node = this._nodes.get(sheet);
-          if (node) {
-            node.update.emit({ type: 'valuesUpdated', change });
-          }
-        }
-      }
-    };
-
-    this._hf.on('valuesUpdated', onValuesUpdate);
-    this._ctx.onDispose(() => this._hf.off('valuesUpdated', onValuesUpdate));
-  }
-
-  get hf() {
-    return this._hf;
-  }
-
-  // refresh() {
-  //   log('refresh', { id: this.id });
-  //   this.update.emit();
-  // }
-
-  getFunctions(
-    { standard, echo }: { standard?: boolean; echo?: boolean } = { standard: true, echo: true },
-  ): 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.
-  async getOrCreateNode(name: string): Promise<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);
-
-    const node = new ComputeNode(this, sheetId);
-    await node.open();
-    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({ type: 'functionsUpdated' });
-      });
-
-      this._ctx.onDispose(unsubscribe);
-    }
-  }
-
-  protected override async _close() {
-    for (const node of this._nodes.values()) {
-      await node.close();
-    }
-  }
-}

package/src/graph/compute-node.ts

@@ -1,62 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { type Listeners } from 'hyperformula/typings/Emitter';
-import { type ExportedCellChange } from 'hyperformula/typings/Exporter';
-
-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';
-
-export type ComputeNodeEvent = {
-  type: keyof Listeners;
-  change?: ExportedCellChange;
-};
-
-/**
- * Individual "sheet" (typically corresponds to an ECHO object).
- */
-// TODO(burdon): Factor out common HF wrapper from from SheetModel.
-export class ComputeNode extends Resource {
-  public readonly update = new Event<ComputeNodeEvent>();
-
-  constructor(
-    private readonly _graph: ComputeGraph,
-    public readonly sheetId: number,
-  ) {
-    super();
-  }
-
-  get graph() {
-    return this._graph;
-  }
-
-  clear() {
-    this._graph.hf.clearSheet(this.sheetId);
-  }
-
-  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]]);
-  }
-
-  protected override async _open() {
-    // const unsubscribe = this._graph.update.on(this.update.emit);
-    // this._ctx.onDispose(unsubscribe);
-  }
-}

package/src/graph/hyperformula.test.ts

@@ -1,15 +0,0 @@
-//
-// 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

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

package/src/graph/testing/index.ts

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

package/src/graph/util.ts

@@ -1,8 +0,0 @@
-//
-// 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

@@ -1,50 +0,0 @@
-//
-// 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 { withComputeGraphDecorator } from '../testing';
-import { SheetType } from '../types';
-
-const Story = () => {
-  const space = useSpace();
-  const graph = useComputeGraph(space);
-  const [sheet, setSheet] = useState<SheetType>();
-  const model = useSheetModel(graph, 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 }),
-    withComputeGraphDecorator(),
-    withTheme,
-  ],
-  render: (args: any) => <Story {...args} />,
-};
-
-export const Default = {};

package/src/hooks/index.ts

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

package/src/hooks/useComputeGraph.ts

@@ -1,21 +0,0 @@
-//
-// 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'));
-  const [graph] = useAsyncState(async () => space && registry.getOrCreateGraph(space), [space, registry]);
-  return graph;
-};

package/src/hooks/useFormattingModel.ts

@@ -1,11 +0,0 @@
-//
-// 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

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