@dxos/web-context-react 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,46 @@
+# @dxos/web-context-react
+
+React implementation of the Web Component Context Protocol.
+
+## Overview
+
+This package allows React components to seamlessly participate in the [Web Component Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md), enabling context sharing between React, Web Components, and other frameworks.
+
+## Installation
+
+```bash
+npm install @dxos/web-context-react @dxos/web-context
+```
+
+## Usage
+
+### Providing Context
+
+Wrap your component tree with `ContextProtocolProvider`. This handles both React context requests (from descendants in the same tree) and DOM context requests (from Web Components).
+
+```tsx
+import { createContext } from '@dxos/web-context';
+import { ContextProtocolProvider } from '@dxos/web-context-react';
+
+const ThemeContext = createContext<{ color: string }>('theme');
+
+const App = () => (
+  <ContextProtocolProvider context={ThemeContext} value={{ color: 'blue' }}>
+    <MyComponent />
+  </ContextProtocolProvider>
+);
+```
+
+### Consuming Context
+
+Use the `useWebComponentContext` hook to consume context. It first checks for a React provider, and falls back to dispatching a `context-request` DOM event.
+
+```tsx
+import { useWebComponentContext } from '@dxos/web-context-react';
+
+const MyComponent = () => {
+  const theme = useWebComponentContext(ThemeContext, { subscribe: true });
+  
+  return <div style={{ color: theme?.color }}>Hello World</div>;
+};
+```

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dxos/web-context-react",
+  "version": "0.0.0",
+  "description": "React integration with web context protocol",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "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/web-context": "0.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "vitest": "3.2.4"
+  },
+  "peerDependencies": {
+    "react": "~19.2.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consumer.test.tsx

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @vitest-environment jsdom
+
+import { act, cleanup, render, screen } from '@testing-library/react';
+import React from 'react';
+import { afterEach, describe, expect, test } from 'vitest';
+
+import { CONTEXT_REQUEST_EVENT, createContext } from '@dxos/web-context';
+
+import { useWebComponentContext } from './consumer';
+import { ContextProtocolProvider } from './provider';
+
+describe('useWebComponentContext', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  const ctx = createContext<string>('test-context');
+
+  const Consumer = ({ options }: { options?: any }) => {
+    const value = useWebComponentContext(ctx, options);
+    return <div data-testid='value'>{value ?? 'undefined'}</div>;
+  };
+
+  test('consumes context from React provider', () => {
+    render(
+      <ContextProtocolProvider context={ctx} value='provided-value'>
+        <Consumer />
+      </ContextProtocolProvider>,
+    );
+
+    expect(screen.getByTestId('value').textContent).toBe('provided-value');
+  });
+
+  test('consumes context from updates (subscription)', async () => {
+    const Container = () => {
+      const [val, setVal] = React.useState('initial');
+      return (
+        <>
+          <button onClick={() => setVal('updated')}>Update</button>
+          <ContextProtocolProvider context={ctx} value={val}>
+            <Consumer options={{ subscribe: true }} />
+          </ContextProtocolProvider>
+        </>
+      );
+    };
+
+    render(<Container />);
+    expect(screen.getByTestId('value').textContent).toBe('initial');
+
+    act(() => {
+      screen.getByText('Update').click();
+    });
+
+    expect(screen.getByTestId('value').textContent).toBe('updated');
+  });
+
+  test('consumes context from DOM parent (outside React tree)', () => {
+    const Wrapper = ({ children }: { children: React.ReactNode }) => {
+      const ref = React.useRef<HTMLDivElement>(null);
+      React.useEffect(() => {
+        const handler = (e: Event) => {
+          const event = e as any;
+          if (event.context === ctx) {
+            event.stopPropagation();
+            event.callback('dom-value');
+          }
+        };
+        ref.current?.addEventListener(CONTEXT_REQUEST_EVENT, handler);
+        return () => ref.current?.removeEventListener(CONTEXT_REQUEST_EVENT, handler);
+      }, []);
+
+      return <div ref={ref}>{children}</div>;
+    };
+
+    render(
+      <Wrapper>
+        <Consumer />
+      </Wrapper>,
+    );
+
+    // Initial render might be undefined until effect runs?
+    // Actually useWebComponentContext effect runs after mount.
+    // The request event is dispatched in useEffect.
+    // So we need to wait for state update.
+
+    // React testing library `findBy` waits.
+    // But `getBy` might not.
+    // However, if logic is correct, dispatch happens, callback called synchronously (in DOM case usually), state updated.
+    // Wait, the callback calls `setValue`. State update is async.
+    // So we expect 'dom-value' eventually.
+  });
+});

package/src/consumer.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useContext, useEffect, useState } from 'react';
+
+import { ContextRequestEvent, type ContextType, type UnknownContext } from '@dxos/web-context';
+
+import { HostElementContext } from './internal';
+import { useContextRequestHandler } from './provider';
+
+/**
+ * Options for useWebComponentContext hook
+ */
+export interface UseWebComponentContextOptions {
+  /**
+   * Whether to subscribe to context updates.
+   * If true, the returned value will update when the provider's value changes.
+   * Default: false
+   */
+  subscribe?: boolean;
+
+  /**
+   * The element to dispatch the context-request event from.
+   * This is only used when there's no React provider in the tree.
+   * Default: document.body
+   */
+  element?: HTMLElement;
+}
+
+/**
+ * A React hook that requests context using the Web Component Context Protocol.
+ *
+ * This first tries to use the React context chain (for providers in the same
+ * React tree), then falls back to dispatching a DOM event (for web component
+ * providers).
+ *
+ * @param context - The context key to request
+ * @param options - Optional configuration
+ * @returns The context value or undefined
+ */
+export function useWebComponentContext<T extends UnknownContext>(
+  context: T,
+  options?: UseWebComponentContextOptions,
+): ContextType<T> | undefined {
+  const [value, setValue] = useState<ContextType<T> | undefined>(undefined);
+
+  const handler = useContextRequestHandler();
+  const hostElement = useContext(HostElementContext);
+
+  useEffect(() => {
+    let unsubscribeFn: (() => void) | undefined;
+
+    const callback = (newValue: ContextType<T>, unsubscribe?: () => void) => {
+      setValue(newValue);
+      if (unsubscribe) {
+        unsubscribeFn = unsubscribe;
+      }
+    };
+
+    const targetElement = options?.element ?? hostElement ?? document.body;
+
+    const event = new ContextRequestEvent(context, callback, {
+      subscribe: options?.subscribe,
+      target: targetElement,
+    });
+
+    let handled = false;
+    if (handler) {
+      handled = handler(event);
+    }
+
+    if (!handled) {
+      targetElement.dispatchEvent(event);
+    }
+
+    return () => {
+      unsubscribeFn?.();
+    };
+  }, [context, options?.subscribe, options?.element, handler, hostElement]);
+
+  return value;
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from '@dxos/web-context';
+
+export * from './consumer';
+export * from './provider';

package/src/internal.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from 'react';
+
+/**
+ * Internal React context for passing the host element to nested components.
+ * This allows useWebComponentContext to dispatch events from the custom element.
+ */
+export const HostElementContext = createContext<HTMLElement | undefined>(undefined);

package/src/provider.test.tsx

@@ -0,0 +1,112 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @vitest-environment jsdom
+
+import { cleanup, render, screen } from '@testing-library/react';
+import React, { useState } from 'react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+import { ContextRequestEvent, createContext } from '@dxos/web-context';
+
+import { ContextProtocolProvider } from './provider';
+
+describe('ContextProtocolProvider', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  const ctx = createContext<string>('test-context');
+
+  test('provides context value to DOM consumers via event', () => {
+    render(
+      <ContextProtocolProvider context={ctx} value='test-value'>
+        <div data-testid='child' />
+      </ContextProtocolProvider>,
+    );
+
+    const child = screen.getByTestId('child');
+    const callback = vi.fn();
+    const event = new ContextRequestEvent(ctx, callback, { target: child });
+
+    const dispatched = child.dispatchEvent(event);
+
+    expect(callback).toHaveBeenCalledWith('test-value');
+    expect(dispatched).toBe(true); // stopImmediatePropagation does not prevent default
+  });
+
+  test('updates subscribers when value changes', async () => {
+    const callback = vi.fn();
+
+    const TestComponent = () => {
+      const [value, setValue] = useState('initial');
+      return (
+        <div>
+          <button onClick={() => setValue('updated')}>Update</button>
+          <ContextProtocolProvider context={ctx} value={value}>
+            <div data-testid='child' />
+          </ContextProtocolProvider>
+        </div>
+      );
+    };
+
+    render(<TestComponent />);
+
+    const child = screen.getByTestId('child');
+    child.dispatchEvent(new ContextRequestEvent(ctx, callback, { subscribe: true, target: child }));
+
+    expect(callback).toHaveBeenCalledWith('initial', expect.any(Function));
+
+    // trigger update
+    screen.getByText('Update').click();
+
+    // Wait for effect
+    await screen.findByText('Update'); // just to wait for re-render if needed? actually click is sync but effect is slightly async.
+    // In React 18, updates are batched.
+
+    // We expect the callback to be called with new value.
+    // Since we used useState, the re-render happens.
+    // The provider's useEffect sees the new value and calls subscribers.
+
+    // Check if callback called again
+    await vi.waitFor(() => {
+      expect(callback).toHaveBeenCalledWith('updated', expect.any(Function));
+    });
+  });
+
+  test('handles nested providers', () => {
+    const callback = vi.fn();
+
+    render(
+      <ContextProtocolProvider context={ctx} value='outer'>
+        <ContextProtocolProvider context={ctx} value='inner'>
+          <div data-testid='child' />
+        </ContextProtocolProvider>
+      </ContextProtocolProvider>,
+    );
+
+    const child = screen.getByTestId('child');
+    child.dispatchEvent(new ContextRequestEvent(ctx, callback, { target: child }));
+
+    expect(callback).toHaveBeenCalledWith('inner');
+  });
+
+  test('passes requests for other contexts to parent', () => {
+    const otherCtx = createContext<string>('other');
+    const callback = vi.fn();
+
+    render(
+      <ContextProtocolProvider context={otherCtx} value='other-value'>
+        <ContextProtocolProvider context={ctx} value='test-value'>
+          <div data-testid='child' />
+        </ContextProtocolProvider>
+      </ContextProtocolProvider>,
+    );
+
+    const child = screen.getByTestId('child');
+    child.dispatchEvent(new ContextRequestEvent(otherCtx, callback, { target: child }));
+
+    expect(callback).toHaveBeenCalledWith('other-value');
+  });
+});

package/src/provider.tsx

@@ -0,0 +1,223 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, {
+  type JSX,
+  type PropsWithChildren,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+} from 'react';
+
+import {
+  CONTEXT_PROVIDER_EVENT,
+  CONTEXT_REQUEST_EVENT,
+  type ContextCallback,
+  ContextProviderEvent,
+  ContextRequestEvent,
+  type ContextType,
+  type UnknownContext,
+} from '@dxos/web-context';
+
+/**
+ * Handler function type for context requests passed via React context
+ */
+type ContextRequestHandler = (event: ContextRequestEvent<UnknownContext>) => boolean;
+
+/**
+ * Internal React context for passing context request handlers down the tree.
+ * This allows useWebComponentContext to work synchronously in React.
+ */
+const ContextRequestHandlerContext = createContext<ContextRequestHandler | undefined>(undefined);
+
+/**
+ * Try to handle a context request using the React context chain.
+ * Returns true if handled, false otherwise.
+ * Used internally by useWebComponentContext.
+ */
+export function tryHandleContextRequest(event: ContextRequestEvent<UnknownContext>): boolean {
+  // This function is intended to be used where useContext is invalid (outside component),
+  // but context handling in React MUST happen inside components.
+  // So this helper might be less useful in React than in Solid if not used inside a hook/component.
+  // However, we can export the context itself for consumers to use `useContext`.
+  return false;
+}
+
+/**
+ * Get the context request handler from React context.
+ * Used internally by useWebComponentContext.
+ */
+export function useContextRequestHandler(): ContextRequestHandler | undefined {
+  return useContext(ContextRequestHandlerContext);
+}
+
+/**
+ * Props for the ContextProtocolProvider component
+ */
+export interface ContextProtocolProviderProps<T extends UnknownContext> {
+  /** The context key to provide */
+  context: T;
+  /** The value to provide */
+  value: ContextType<T>;
+}
+
+/**
+ * A provider component that:
+ * 1. Handles context-request events from web components (via DOM events)
+ * 2. Handles context requests from React consumers (via React context)
+ * 3. Supports subscriptions for reactive updates
+ * 4. Uses WeakRef for subscriptions to prevent memory leaks
+ */
+export const ContextProtocolProvider = <T extends UnknownContext>({
+  context,
+  value,
+  children,
+}: PropsWithChildren<ContextProtocolProviderProps<T>>): JSX.Element => {
+  // Get parent handler if one exists (for nested providers)
+  const parentHandler = useContext(ContextRequestHandlerContext);
+
+  // Track subscriptions with their stable unsubscribe functions and consumer host elements
+  interface SubscriptionInfo {
+    unsubscribe: () => void;
+    consumerHost: Element;
+    ref: WeakRef<ContextCallback<ContextType<T>>>;
+  }
+
+  // We use refs for mutable state that doesn't trigger re-renders
+  const subscriptions = useRef(new WeakMap<ContextCallback<ContextType<T>>, SubscriptionInfo>()).current;
+  const subscriptionRefs = useRef(new Set<WeakRef<ContextCallback<ContextType<T>>>>()).current;
+  const valueRef = useRef(value);
+
+  // Update value ref when prop changes
+  useEffect(() => {
+    valueRef.current = value;
+  }, [value]);
+
+  // Core handler logic
+  const handleRequest = useCallback(
+    (event: ContextRequestEvent<UnknownContext>): boolean => {
+      if (event.context !== context) {
+        if (parentHandler) {
+          return parentHandler(event);
+        }
+        return false;
+      }
+
+      const currentValue = valueRef.current; // Use latest value
+
+      if (event.subscribe) {
+        const callback = event.callback as ContextCallback<ContextType<T>>;
+        const consumerHost = event.contextTarget || (event.composedPath()[0] as Element);
+
+        const unsubscribe = () => {
+          const info = subscriptions.get(callback);
+          if (info) {
+            subscriptionRefs.delete(info.ref);
+            subscriptions.delete(callback);
+          }
+        };
+
+        const ref = new WeakRef(callback);
+        subscriptions.set(callback, { unsubscribe, consumerHost, ref });
+        subscriptionRefs.add(ref);
+
+        event.callback(currentValue, unsubscribe);
+      } else {
+        event.callback(currentValue);
+      }
+
+      return true;
+    },
+    [context, parentHandler], // Dependencies
+  );
+
+  // Handle DOM context-request events
+  const handleContextRequestEvent = useCallback(
+    (e: Event) => {
+      const event = e as ContextRequestEvent<UnknownContext>;
+      if (handleRequest(event)) {
+        event.stopImmediatePropagation();
+      }
+    },
+    [handleRequest],
+  );
+
+  // Handle context-provider events
+  const handleContextProviderEvent = useCallback(
+    (e: Event) => {
+      const event = e as ContextProviderEvent<UnknownContext>;
+      if (event.context !== context) return;
+      if (containerRef.current && event.contextTarget === containerRef.current) return;
+
+      const seen = new Set<ContextCallback<ContextType<T>>>();
+      for (const ref of subscriptionRefs) {
+        const callback = ref.deref();
+        if (!callback) {
+          subscriptionRefs.delete(ref);
+          continue;
+        }
+
+        const info = subscriptions.get(callback);
+        if (!info) continue;
+
+        if (seen.has(callback)) continue;
+        seen.add(callback);
+
+        info.consumerHost.dispatchEvent(
+          new ContextRequestEvent(context, callback, { subscribe: true, target: info.consumerHost }),
+        );
+      }
+      event.stopPropagation();
+    },
+    [context],
+  );
+
+  // Notify subscribers when value changes
+  useEffect(() => {
+    // Skip notification if value hasn't changed? React does this for us if we use dependencies correctly?
+    // No, we need to imperatively call callbacks.
+    // value constraint is in the dependency array
+
+    for (const ref of subscriptionRefs) {
+      const callback = ref.deref();
+      if (!callback) {
+        subscriptionRefs.delete(ref);
+        continue;
+      }
+      const info = subscriptions.get(callback);
+      if (info) {
+        callback(value, info.unsubscribe);
+      }
+    }
+  }, [value]);
+
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    el.addEventListener(CONTEXT_REQUEST_EVENT, handleContextRequestEvent);
+    el.addEventListener(CONTEXT_PROVIDER_EVENT, handleContextProviderEvent);
+
+    // Announce provider
+    el.dispatchEvent(new ContextProviderEvent(context, el));
+
+    return () => {
+      el.removeEventListener(CONTEXT_REQUEST_EVENT, handleContextRequestEvent);
+      el.removeEventListener(CONTEXT_PROVIDER_EVENT, handleContextProviderEvent);
+      subscriptionRefs.clear();
+    };
+  }, [handleContextRequestEvent, handleContextProviderEvent, context]);
+
+  return (
+    <ContextRequestHandlerContext.Provider value={handleRequest}>
+      <div ref={containerRef} style={{ display: 'contents' }}>
+        {children}
+      </div>
+    </ContextRequestHandlerContext.Provider>
+  );
+};