@dxos/app-solid 0.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+MIT License
+Copyright (c) 2025 DXOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @dxos/app-solid
+
+SolidJS integration for @dxos/app-framework.
+
+## Installation
+
+```bash
+pnpm i @dxos/app-solid
+```
+
+## DXOS Resources
+
+- [Website](https://dxos.org)
+- [Developer Documentation](https://docs.dxos.org)
+- Talk to us on [Discord](https://dxos.org/discord)
+
+## Contributions
+
+Your ideas, issues, and code are most welcome. Please take a look at our [community code of conduct](https://github.com/dxos/dxos/blob/main/CODE_OF_CONDUCT.md), the [issue guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-issues), and the [PR contribution guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-prs).
+
+License: [MIT](./LICENSE) Copyright 2025 © DXOS

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@dxos/app-solid",
+  "version": "0.0.0",
+  "description": "SolidJS integration for @dxos/app-framework",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {}
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@dxos/app-framework": "0.8.3",
+    "@dxos/effect-atom-solid": "0.0.0",
+    "@dxos/operation": "0.0.0",
+    "@dxos/web-context-solid": "0.0.0",
+    "@dxos/invariant": "0.8.3"
+  },
+  "devDependencies": {
+    "@effect-atom/atom": "^0.4.10",
+    "@solidjs/testing-library": "^0.8.10",
+    "effect": "3.19.11",
+    "solid-js": "^1.9.9",
+    "vite-plugin-solid": "^2.11.10"
+  },
+  "peerDependencies": {
+    "effect": "3.19.11",
+    "solid-js": "^1.9.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/common.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Accessor } from 'solid-js';
+
+import { Common } from '@dxos/app-framework';
+
+import { useCapability } from './useCapabilities';
+
+export const useOperationInvoker = (): Accessor<Common.Capability.OperationInvoker> =>
+  useCapability(Common.Capability.OperationInvoker);
+
+export const useAppGraph = (): Accessor<Common.Capability.AppGraph> => useCapability(Common.Capability.AppGraph);
+
+export const useLayout = () => useCapability(Common.Capability.Layout);

package/src/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from '@dxos/app-framework';
+
+export * from './common';
+export * from './useCapabilities';
+export * from './useOperationResolver';
+export * from './usePluginManager';

package/src/useCapabilities.test.tsx

@@ -0,0 +1,78 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import { render, screen } from '@solidjs/testing-library';
+import { describe, expect, test } from 'vitest';
+
+import { Capability, type PluginManager, PluginManagerContext } from '@dxos/app-framework';
+import { ContextProtocolProvider } from '@dxos/web-context-solid';
+
+import { useCapabilities, useCapability } from './useCapabilities';
+
+const TestCapability = Capability.make<{ value: string }>('test.capability');
+
+const mockAtom = Atom.make([{ value: 'hello' }]);
+
+const mockManager = {
+  capabilities: {
+    atom: () => mockAtom,
+  },
+} as unknown as PluginManager.PluginManager;
+
+describe('useCapabilities', () => {
+  test('returns capabilities from the plugin manager', () => {
+    const TestComponent = () => {
+      const capabilities = useCapabilities(TestCapability);
+      return <div data-testid='caps-length'>{capabilities().length}</div>;
+    };
+
+    render(() => (
+      <ContextProtocolProvider context={PluginManagerContext} value={mockManager}>
+        <TestComponent />
+      </ContextProtocolProvider>
+    ));
+
+    expect(screen.getByTestId('caps-length').textContent).toBe('1');
+  });
+});
+
+describe('useCapability', () => {
+  test('returns a single capability', () => {
+    const TestComponent = () => {
+      const capability = useCapability(TestCapability);
+      return <div data-testid='cap-value'>{capability().value}</div>;
+    };
+
+    render(() => (
+      <ContextProtocolProvider context={PluginManagerContext} value={mockManager}>
+        <TestComponent />
+      </ContextProtocolProvider>
+    ));
+
+    expect(screen.getByTestId('cap-value').textContent).toBe('hello');
+  });
+
+  test('throws if no capability is found', () => {
+    const emptyAtom = Atom.make([]);
+    const emptyManager = {
+      capabilities: {
+        atom: () => emptyAtom,
+      },
+    } as unknown as PluginManager.PluginManager;
+
+    const TestComponent = () => {
+      const capability = useCapability(TestCapability);
+      return <div>{capability().value}</div>; // This read triggers the invariant
+    };
+
+    expect(() =>
+      render(() => (
+        <ContextProtocolProvider context={PluginManagerContext} value={emptyManager}>
+          <TestComponent />
+        </ContextProtocolProvider>
+      )),
+    ).toThrow(/No capability found/);
+  });
+});

package/src/useCapabilities.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Accessor } from 'solid-js';
+
+import { type Capability } from '@dxos/app-framework';
+import { useAtomValue } from '@dxos/effect-atom-solid';
+import { invariant } from '@dxos/invariant';
+
+import { usePluginManager } from './usePluginManager';
+
+/**
+ * Hook to request capabilities from the plugin context.
+ * @returns An array of capabilities.
+ */
+export const useCapabilities = <T>(interfaceDef: Capability.InterfaceDef<T>): Accessor<T[]> => {
+  const manager = usePluginManager();
+  return useAtomValue(manager.capabilities.atom(interfaceDef));
+};
+
+/**
+ * Hook to request a capability from the plugin context.
+ * @returns The capability.
+ * @throws If no capability is found.
+ */
+export const useCapability = <T>(interfaceDef: Capability.InterfaceDef<T>): Accessor<T> => {
+  const capabilities = useCapabilities(interfaceDef);
+  return (() => {
+    const caps = capabilities();
+    invariant(caps.length > 0, `No capability found for ${interfaceDef.identifier}`);
+    return caps[0];
+  }) as Accessor<T>;
+};

package/src/useOperationResolver.test.tsx

@@ -0,0 +1,63 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { render } from '@solidjs/testing-library';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { describe, expect, test, vi } from 'vitest';
+
+import { type PluginManager, PluginManagerContext } from '@dxos/app-framework';
+import { Operation, OperationResolver } from '@dxos/operation';
+import { ContextProtocolProvider } from '@dxos/web-context-solid';
+
+import { useOperationResolver } from './useOperationResolver';
+
+const TestOperation = Operation.make({
+  meta: { key: 'test/operation', name: 'Test Operation' },
+  schema: {
+    input: Schema.Struct({ value: Schema.String }),
+    output: Schema.Struct({ result: Schema.String }),
+  },
+});
+
+describe('useOperationResolver', () => {
+  test('registers and unregisters operation resolver', () => {
+    const contributeMock = vi.fn();
+    const removeMock = vi.fn();
+
+    const mockManager = {
+      capabilities: {
+        contribute: contributeMock,
+        remove: removeMock,
+      },
+    } as unknown as PluginManager.PluginManager;
+
+    const resolver = OperationResolver.make({
+      operation: TestOperation,
+      handler: ({ value }) => Effect.succeed({ result: value }),
+    });
+
+    const TestComponent = () => {
+      useOperationResolver('test-module', resolver);
+      return <div />;
+    };
+
+    const { unmount } = render(() => (
+      <ContextProtocolProvider context={PluginManagerContext} value={mockManager}>
+        <TestComponent />
+      </ContextProtocolProvider>
+    ));
+
+    expect(contributeMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        module: 'test-module',
+        implementation: [resolver],
+      }),
+    );
+
+    unmount();
+
+    expect(removeMock).toHaveBeenCalled();
+  });
+});

package/src/useOperationResolver.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createEffect, onCleanup } from 'solid-js';
+
+import { Common } from '@dxos/app-framework';
+import { type OperationResolver } from '@dxos/operation';
+
+import { usePluginManager } from './usePluginManager';
+
+export const useOperationResolver = (module: string, resolver: OperationResolver.OperationResolver) => {
+  const manager = usePluginManager();
+
+  createEffect(() => {
+    const implementation = [resolver];
+
+    manager.capabilities.contribute({
+      module,
+      interface: Common.Capability.OperationResolver,
+      implementation,
+    });
+
+    onCleanup(() => {
+      manager.capabilities.remove(Common.Capability.OperationResolver, implementation);
+    });
+  });
+};

package/src/usePluginManager.test.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { render, screen } from '@solidjs/testing-library';
+import { describe, expect, test } from 'vitest';
+
+import { type PluginManager, PluginManagerContext } from '@dxos/app-framework';
+import { ContextProtocolProvider } from '@dxos/web-context-solid';
+
+import { usePluginManager } from './usePluginManager';
+
+describe('usePluginManager', () => {
+  test('returns the plugin manager from context', () => {
+    const mockManager = {
+      context: {
+        capabilities: () => ({ pipe: () => {} }),
+      },
+    } as unknown as PluginManager.PluginManager;
+
+    const TestComponent = () => {
+      const manager = usePluginManager();
+      return <div data-testid='manager-check'>{manager === mockManager ? 'match' : 'mismatch'}</div>;
+    };
+
+    render(() => (
+      <ContextProtocolProvider context={PluginManagerContext} value={mockManager}>
+        <TestComponent />
+      </ContextProtocolProvider>
+    ));
+
+    expect(screen.getByTestId('manager-check').textContent).toBe('match');
+  });
+
+  test('throws if plugin manager is missing', () => {
+    const TestComponent = () => {
+      // @ts-ignore
+      usePluginManager(); // This should throw
+      return <div />;
+    };
+
+    // Use a custom error boundary or just try/catch mechanism if simple render throws.
+    // However, Solid's reactivity system might make catching errors tricky during render phase directly in test if not handled.
+    // Given the invariant check is inside the hook, it executes during component initialization.
+
+    expect(() => render(() => <TestComponent />)).toThrow('PluginManager not found');
+  });
+});

package/src/usePluginManager.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type PluginManager, PluginManagerContext } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
+import { useWebComponentContext } from '@dxos/web-context-solid';
+
+/**
+ * Hook to access the plugin manager.
+ * @returns The plugin manager.
+ */
+export const usePluginManager = (): PluginManager.PluginManager => {
+  const manager = useWebComponentContext(PluginManagerContext);
+  const value = manager();
+  invariant(value, 'PluginManager not found');
+  return value;
+};