@dxos/plugin-sheet 0.6.13 → 0.6.14-main.7bd9c89

package/src/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/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/graph/testing/index.ts

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

package/src/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 → 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/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,53 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import '@dxos-theme';
+
+import { type Meta } from '@storybook/react';
+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 DefaultStory = () => {
+  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 const Default = {};
+
+const meta: Meta = {
+  title: 'plugins/plugin-sheet/hooks',
+  component: ComputeGraphContextProvider,
+  render: DefaultStory,
+  decorators: [
+    withClientProvider({ types: [SheetType], createIdentity: true, createSpace: true }),
+    withComputeGraphDecorator(),
+    withTheme,
+  ],
+};
+
+export default meta;

package/src/hooks/index.ts

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

package/src/hooks/threads.ts

@@ -0,0 +1,147 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { effect } from '@preact/signals-core';
+import { type MutableRefObject, useCallback, useEffect, useMemo } from 'react';
+
+import { type IntentResolver, LayoutAction, useIntentDispatcher, useIntentResolver } from '@dxos/app-framework';
+import { debounce } from '@dxos/async';
+import { fullyQualifiedId } from '@dxos/react-client/echo';
+import { type DxGridElement, type DxGridPosition } from '@dxos/react-ui-grid';
+
+import { addressFromIndex, addressToIndex, type CellAddress, closest } from '../defs';
+import { SHEET_PLUGIN } from '../meta';
+import { type SheetModel, type Decoration, type Decorations } from '../model';
+
+export const useUpdateFocusedCellOnThreadSelection = (
+  model: SheetModel,
+  grid: MutableRefObject<DxGridElement | null>,
+) => {
+  const handleScrollIntoView: IntentResolver = useCallback(
+    ({ action, data }) => {
+      switch (action) {
+        case LayoutAction.SCROLL_INTO_VIEW: {
+          if (!data?.id || data?.cursor === undefined || data?.id !== fullyQualifiedId(model.sheet)) {
+            return;
+          }
+
+          // TODO(Zan): Everywhere we refer to the cursor in a thread context should change to `anchor`.
+          const cellAddress = addressFromIndex(model.sheet, data.cursor);
+          grid.current?.setFocus({ ...cellAddress, plane: 'grid' }, true);
+        }
+      }
+    },
+    [model.sheet],
+  );
+
+  useIntentResolver(SHEET_PLUGIN, handleScrollIntoView);
+};
+
+export const useSelectThreadOnCellFocus = (model: SheetModel, cursor?: CellAddress) => {
+  const dispatch = useIntentDispatcher();
+
+  const activeThreads = useMemo(
+    () =>
+      model.sheet.threads?.filter(
+        (thread): thread is NonNullable<typeof thread> => !!thread && thread.status === 'active',
+      ) ?? [],
+    [
+      // TODO(thure): Surely we can find a better dependency for this…
+      JSON.stringify(model.sheet.threads),
+    ],
+  );
+
+  const activeThreadAddresses = useMemo(
+    () =>
+      activeThreads
+        .map((thread) => thread.anchor)
+        .filter((anchor): anchor is NonNullable<typeof anchor> => anchor !== undefined)
+        .map((anchor) => addressFromIndex(model.sheet, anchor)),
+    [activeThreads, model.sheet],
+  );
+
+  const selectClosestThread = useCallback(
+    (cellAddress: CellAddress) => {
+      if (!cellAddress || !activeThreads) {
+        return;
+      }
+
+      const closestThreadAnchor = closest(cellAddress, activeThreadAddresses);
+      if (closestThreadAnchor) {
+        const closestThread = activeThreads.find(
+          (thread) => thread && thread.anchor === addressToIndex(model.sheet, closestThreadAnchor),
+        );
+
+        if (closestThread) {
+          void dispatch([
+            { action: 'dxos.org/plugin/thread/action/select', data: { current: fullyQualifiedId(closestThread) } },
+          ]);
+        }
+      }
+    },
+    [dispatch, activeThreads, activeThreadAddresses, model.sheet],
+  );
+
+  const debounced = useMemo(() => {
+    return debounce((cellCoords: DxGridPosition) => requestAnimationFrame(() => selectClosestThread(cellCoords)), 50);
+  }, [selectClosestThread]);
+
+  useEffect(() => {
+    if (!cursor) {
+      return;
+    }
+    debounced(cursor);
+  }, [cursor, selectClosestThread]);
+};
+
+const createThreadDecoration = (cellIndex: string, threadId: string, sheetId: string): Decoration => {
+  return {
+    type: 'comment',
+    classNames: ['bg-greenFill'],
+    cellIndex,
+  };
+};
+
+export const useThreadDecorations = (model: SheetModel, decorations: Decorations) => {
+  const sheet = useMemo(() => model.sheet, [model.sheet]);
+  const sheetId = useMemo(() => fullyQualifiedId(sheet), [sheet]);
+
+  useEffect(() => {
+    const unsubscribe = effect(() => {
+      const activeThreadAnchors = new Set<string>();
+      if (!sheet.threads) {
+        return;
+      }
+
+      // Process active threads
+      for (const thread of sheet.threads) {
+        if (!thread || thread.anchor === undefined || thread.status === 'resolved') {
+          continue;
+        }
+
+        activeThreadAnchors.add(thread.anchor);
+        const index = thread.anchor;
+
+        // Add decoration only if it doesn't already exist
+        const existingDecorations = decorations.getDecorationsForCell(index);
+        if (!existingDecorations || !existingDecorations.some((d) => d.type === 'comment')) {
+          decorations.addDecoration(index, createThreadDecoration(index, thread.id, sheetId));
+        }
+      }
+
+      // Remove decorations for resolved or deleted threads
+      for (const decoration of decorations.getAllDecorations()) {
+        if (decoration.type !== 'comment') {
+          continue;
+        }
+
+        if (!activeThreadAnchors.has(decoration.cellIndex)) {
+          decorations.removeDecoration(decoration.cellIndex, 'comment');
+        }
+      }
+    });
+
+    return () => unsubscribe();
+  });
+};

package/src/hooks/useComputeGraph.ts

@@ -0,0 +1,28 @@
+//
+// 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 () => {
+    if (space) {
+      const graph = registry.getOrCreateGraph(space);
+      await graph.open();
+      return graph;
+    }
+  }, [space, registry]);
+
+  return graph;
+};

package/src/hooks/useSheetModel.ts

@@ -0,0 +1,40 @@
+//
+// 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;
+};

package/src/meta.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type PluginMeta } from '@dxos/app-framework';
+
+export const SHEET_PLUGIN = 'dxos.org/plugin/sheet';
+
+export default {
+  id: SHEET_PLUGIN,
+  name: 'Sheet',
+  description: 'A simple spreadsheet plugin.',
+  icon: 'ph--grid-nine--regular',
+} satisfies PluginMeta;

package/src/model/decorations.ts

@@ -0,0 +1,66 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type ReactNode } from 'react';
+
+import { create } from '@dxos/echo-schema';
+
+export type Decoration = {
+  type: string;
+  /**
+   * A wrapping render function to encapsulate cell content. This function is applied between
+   * the cell's border and its padding/layout/content, allowing for custom rendering or
+   * additional elements to be inserted around the cell's main content.
+   */
+  decorate?: (props: { children: ReactNode }) => ReactNode;
+  /**
+   * An array of CSS class names to be applied to the content of the SheetCell.
+   * These classes can be used to style the cell's content independently of its structure.
+   */
+  classNames?: string[];
+  cellIndex: string;
+};
+
+export const createDecorations = () => {
+  // Reactive object to hold decorations
+  // TODO(Zan): Use CELL ID's to key the decoration map.
+  // TODO(Zan): Consider maintaining an index of decorations by type.
+  const { decorations } = create<{ decorations: Record<string, Decoration[]> }>({ decorations: {} });
+
+  const addDecoration = (cellIndex: string, decorator: Decoration) => {
+    decorations[cellIndex] = [...(decorations[cellIndex] || []), decorator];
+  };
+
+  const removeDecoration = (cellIndex: string, type?: string) => {
+    if (type) {
+      decorations[cellIndex] = (decorations[cellIndex] || []).filter((d) => d.type !== type);
+    } else {
+      delete decorations[cellIndex];
+    }
+  };
+
+  // TODO(Zan): I should check if returning the a value from a map in a deep signal is a reactive slice.
+  const getDecorationsForCell = (cellIndex: string): Decoration[] | undefined => {
+    return decorations[cellIndex];
+  };
+
+  const getAllDecorations = (): Decoration[] => {
+    const result: Decoration[] = [];
+    for (const decoratorArray of Object.values(decorations)) {
+      for (const decorator of decoratorArray) {
+        result.push(decorator);
+      }
+    }
+    return result;
+  };
+
+  return {
+    addDecoration,
+    removeDecoration,
+    getDecorationsForCell,
+    getAllDecorations,
+  } as const;
+};
+
+export type Decorations = ReturnType<typeof createDecorations>;

package/src/model/index.ts

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

package/src/model/sheet-model.test.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { Trigger } from '@dxos/async';
+import { FunctionType } from '@dxos/plugin-script/types';
+
+import { SheetModel } from './sheet-model';
+import { addressFromA1Notation, createSheet } from '../defs';
+import { TestBuilder, testFunctionPlugins } from '../graph/testing';
+import { type CellScalarValue } from '../types';
+
+describe('SheetModel', () => {
+  let testBuilder: TestBuilder;
+  beforeEach(async () => {
+    testBuilder = new TestBuilder({ types: [FunctionType], plugins: testFunctionPlugins });
+    await testBuilder.open();
+  });
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('async function', async () => {
+    const space = await testBuilder.client.spaces.create();
+    const graph = testBuilder.registry.createGraph(space);
+    await graph.open();
+
+    // TODO(burdon): Create via factory.
+    const sheet = createSheet({ rows: 5, columns: 5 });
+    const model = new SheetModel(graph, sheet);
+    await model.open();
+    testBuilder.ctx.onDispose(() => model.close());
+
+    // Trigger waits for function invocation.
+    const trigger = new Trigger<CellScalarValue>();
+    model.setValue(addressFromA1Notation('A1'), '=TEST(100)');
+    model.update.once((update) => {
+      const { type } = update;
+      if (type === 'valuesUpdated') {
+        const value = model.getValue(addressFromA1Notation('A1'));
+        trigger.wake(value);
+      }
+    });
+
+    // Initial value will be null.
+    const v1 = model.getValue(addressFromA1Notation('A1'));
+    expect(v1).to.be.null;
+    expect(graph.context.info.invocations.TEST).not.to.exist;
+
+    // Wait until async update triggered.
+    const v2 = await trigger.wait();
+    expect(v2).to.eq(100);
+    expect(graph.context.info.invocations.TEST).to.eq(1);
+  });
+});