@dxos/web-context 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,49 @@
+# @dxos/web-context
+
+Framework-agnostic definitions for the Web Component Context Protocol.
+
+## Overview
+
+This package provides the core types and event definitions for the [Web Component Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md). It is intended to be used by framework-specific implementations (providers and consumers) to ensure interoperability.
+
+## Installation
+
+```bash
+npm install @dxos/web-context
+```
+
+## Usage
+
+### Context Definitions
+
+```typescript
+import { createContext } from '@dxos/web-context';
+
+export const ThemeContext = createContext<{ color: string }>('theme');
+```
+
+### Requesting Context
+
+```typescript
+import { ContextRequestEvent } from '@dxos/web-context';
+
+const event = new ContextRequestEvent(ThemeContext, (value, unsubscribe) => {
+  console.log('Context value:', value);
+  // Optional: unsubscribe()
+}, { subscribe: true });
+
+element.dispatchEvent(event);
+```
+
+### Providing Context
+
+```typescript
+import { ContextProviderEvent } from '@dxos/web-context';
+
+element.addEventListener('context-request', (event) => {
+  if (event.context === ThemeContext) {
+    event.stopPropagation();
+    event.callback({ color: 'blue' });
+  }
+});
+```

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@dxos/web-context",
+  "version": "0.0.0",
+  "description": "Web Component Context Protocol definitions",
+  "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"
+  ],
+  "devDependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './protocol';

package/src/protocol.test.ts

@@ -0,0 +1,312 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, test, vi } from 'vitest';
+
+import {
+  CONTEXT_REQUEST_EVENT,
+  type ContextCallback,
+  ContextRequestEvent,
+  type ContextType,
+  type UnknownContext,
+  createContext,
+} from './protocol';
+
+describe('protocol', () => {
+  describe('createContext', () => {
+    test('creates a context with string key', () => {
+      const ctx = createContext<number>('my-context');
+      expect(ctx).toBe('my-context');
+    });
+
+    test('creates a context with symbol key', () => {
+      const key = Symbol('my-context');
+      const ctx = createContext<string>(key);
+      expect(ctx).toBe(key);
+    });
+
+    test('creates a context with object key', () => {
+      const key = { name: 'my-context' };
+      const ctx = createContext<boolean>(key);
+      expect(ctx).toBe(key);
+    });
+
+    test('contexts with same string key are strictly equal', () => {
+      const ctx1 = createContext<number>('shared-key');
+      const ctx2 = createContext<number>('shared-key');
+      expect(ctx1 === ctx2).toBe(true);
+    });
+
+    test('contexts with unique symbols are not equal', () => {
+      const ctx1 = createContext<number>(Symbol('unique'));
+      const ctx2 = createContext<number>(Symbol('unique'));
+      expect(ctx1 === ctx2).toBe(false);
+    });
+
+    test('contexts with Symbol.for are equal', () => {
+      const ctx1 = createContext<number>(Symbol.for('shared'));
+      const ctx2 = createContext<number>(Symbol.for('shared'));
+      expect(ctx1 === ctx2).toBe(true);
+    });
+  });
+
+  describe('ContextRequestEvent', () => {
+    test('creates event with correct type', () => {
+      const ctx = createContext<string>('test');
+      const target = document.createElement('div');
+      const callback = vi.fn();
+      const event = new ContextRequestEvent(ctx, callback, { target });
+
+      expect(event.type).toBe('context-request');
+    });
+
+    test('event bubbles', () => {
+      const ctx = createContext<string>('test');
+      const target = document.createElement('div');
+      const callback = vi.fn();
+      const event = new ContextRequestEvent(ctx, callback, { target });
+
+      expect(event.bubbles).toBe(true);
+    });
+
+    test('event is composed (crosses shadow DOM boundaries)', () => {
+      const ctx = createContext<string>('test');
+      const target = document.createElement('div');
+      const callback = vi.fn();
+      const event = new ContextRequestEvent(ctx, callback, { target });
+
+      expect(event.composed).toBe(true);
+    });
+
+    test('carries context key', () => {
+      const ctx = createContext<string>('my-key');
+      const target = document.createElement('div');
+      const callback = vi.fn();
+      const event = new ContextRequestEvent(ctx, callback, { target });
+
+      expect(event.context).toBe(ctx);
+    });
+
+    test('carries contextTarget', () => {
+      const ctx = createContext<string>('test');
+      const target = document.createElement('div');
+      const callback = vi.fn();
+      const event = new ContextRequestEvent(ctx, callback, { target });
+
+      expect(event.contextTarget).toBe(target);
+    });
+
+    test('carries callback', () => {
+      const ctx = createContext<string>('test');
+      const target = document.createElement('div');
+      const callback = vi.fn();
+      const event = new ContextRequestEvent(ctx, callback, { target });
+
+      expect(event.callback).toBe(callback);
+    });
+
+    test('subscribe defaults to undefined', () => {
+      const ctx = createContext<string>('test');
+      const target = document.createElement('div');
+      const callback = vi.fn();
+      const event = new ContextRequestEvent(ctx, callback, { target });
+
+      expect(event.subscribe).toBeUndefined();
+    });
+
+    test('subscribe can be set to true', () => {
+      const ctx = createContext<string>('test');
+      const target = document.createElement('div');
+      const callback = vi.fn();
+      const event = new ContextRequestEvent(ctx, callback, { subscribe: true, target });
+
+      expect(event.subscribe).toBe(true);
+    });
+
+    test('subscribe can be set to false', () => {
+      const ctx = createContext<string>('test');
+      const target = document.createElement('div');
+      const callback = vi.fn();
+      const event = new ContextRequestEvent(ctx, callback, { subscribe: false, target });
+
+      expect(event.subscribe).toBe(false);
+    });
+  });
+
+  describe('ContextRequestEvent integration', () => {
+    test('event bubbles through DOM', () => {
+      const ctx = createContext<string>('test');
+      const callback = vi.fn();
+
+      const parent = document.createElement('div');
+      const child = document.createElement('div');
+      parent.appendChild(child);
+      document.body.appendChild(parent);
+
+      const handler = vi.fn((e: Event) => {
+        const event = e as ContextRequestEvent<typeof ctx>;
+        if (event.context === ctx) {
+          event.stopImmediatePropagation();
+          event.callback('provided-value');
+        }
+      });
+
+      parent.addEventListener(CONTEXT_REQUEST_EVENT, handler);
+
+      const event = new ContextRequestEvent(ctx, callback, { target: child });
+      child.dispatchEvent(event);
+
+      expect(handler).toHaveBeenCalled();
+      expect(callback).toHaveBeenCalledWith('provided-value');
+
+      // Cleanup
+      parent.removeEventListener(CONTEXT_REQUEST_EVENT, handler);
+      document.body.removeChild(parent);
+    });
+
+    test('stopImmediatePropagation prevents other handlers', () => {
+      const ctx = createContext<string>('test');
+      const callback = vi.fn();
+
+      const grandparent = document.createElement('div');
+      const parent = document.createElement('div');
+      const child = document.createElement('div');
+      grandparent.appendChild(parent);
+      parent.appendChild(child);
+      document.body.appendChild(grandparent);
+
+      const parentHandler = vi.fn((e: Event) => {
+        const event = e as ContextRequestEvent<typeof ctx>;
+        if (event.context === ctx) {
+          event.stopImmediatePropagation();
+          event.callback('parent-value');
+        }
+      });
+
+      const grandparentHandler = vi.fn((e: Event) => {
+        const event = e as ContextRequestEvent<typeof ctx>;
+        if (event.context === ctx) {
+          event.callback('grandparent-value');
+        }
+      });
+
+      parent.addEventListener(CONTEXT_REQUEST_EVENT, parentHandler);
+      grandparent.addEventListener(CONTEXT_REQUEST_EVENT, grandparentHandler);
+
+      const event = new ContextRequestEvent(ctx, callback, { target: child });
+      child.dispatchEvent(event);
+
+      expect(parentHandler).toHaveBeenCalled();
+      expect(grandparentHandler).not.toHaveBeenCalled();
+      expect(callback).toHaveBeenCalledWith('parent-value');
+      expect(callback).toHaveBeenCalledTimes(1);
+
+      // Cleanup
+      parent.removeEventListener(CONTEXT_REQUEST_EVENT, parentHandler);
+      grandparent.removeEventListener(CONTEXT_REQUEST_EVENT, grandparentHandler);
+      document.body.removeChild(grandparent);
+    });
+
+    test('provider can invoke callback multiple times for subscriptions', () => {
+      const ctx = createContext<number>('counter');
+      const callback = vi.fn();
+      const unsubscribe = vi.fn();
+
+      const parent = document.createElement('div');
+      const child = document.createElement('div');
+      parent.appendChild(child);
+      document.body.appendChild(parent);
+
+      let storedCallback: ContextCallback<number> | null = null;
+
+      const handler = vi.fn((e: Event) => {
+        const event = e as ContextRequestEvent<typeof ctx>;
+        if (event.context === ctx) {
+          event.stopImmediatePropagation();
+          // Provide initial value
+          event.callback(0, unsubscribe);
+          // Store callback for future updates if subscribing
+          if (event.subscribe) {
+            storedCallback = event.callback;
+          }
+        }
+      });
+
+      parent.addEventListener(CONTEXT_REQUEST_EVENT, handler);
+
+      const event = new ContextRequestEvent(ctx, callback, { subscribe: true, target: child });
+      child.dispatchEvent(event);
+
+      expect(callback).toHaveBeenCalledWith(0, unsubscribe);
+
+      // Simulate value update
+      storedCallback!(1, unsubscribe);
+      storedCallback!(2, unsubscribe);
+
+      expect(callback).toHaveBeenCalledTimes(3);
+      expect(callback).toHaveBeenLastCalledWith(2, unsubscribe);
+
+      // Cleanup
+      parent.removeEventListener(CONTEXT_REQUEST_EVENT, handler);
+      document.body.removeChild(parent);
+    });
+
+    test('context matching uses strict equality', () => {
+      const ctx1 = createContext<string>('test');
+      const ctx2 = createContext<string>('test'); // Same key, should match
+      const ctx3 = createContext<string>('other');
+
+      const callback = vi.fn();
+      const parent = document.createElement('div');
+      const child = document.createElement('div');
+      parent.appendChild(child);
+      document.body.appendChild(parent);
+
+      const handler = vi.fn((e: Event) => {
+        const event = e as ContextRequestEvent<UnknownContext>;
+        // Only respond to ctx1 (or ctx2 since they're equal)
+        if (event.context === ctx1) {
+          event.stopImmediatePropagation();
+          event.callback('matched');
+        }
+      });
+
+      parent.addEventListener(CONTEXT_REQUEST_EVENT, handler);
+
+      // Request with ctx2 (equal to ctx1)
+      child.dispatchEvent(new ContextRequestEvent(ctx2, callback, { target: child }));
+      expect(callback).toHaveBeenCalledWith('matched');
+
+      callback.mockClear();
+
+      // Request with ctx3 (different)
+      child.dispatchEvent(new ContextRequestEvent(ctx3, callback, { target: child }));
+      expect(callback).not.toHaveBeenCalled();
+
+      // Cleanup
+      parent.removeEventListener(CONTEXT_REQUEST_EVENT, handler);
+      document.body.removeChild(parent);
+    });
+  });
+
+  describe('Type utilities', () => {
+    test('ContextType extracts value type', () => {
+      const ctx = createContext<{ name: string }>('user');
+
+      // This is a compile-time check - if it compiles, the types work
+      type ExtractedType = ContextType<typeof ctx>;
+      const value: ExtractedType = { name: 'test' };
+      expect(value.name).toBe('test');
+    });
+
+    test('Context type carries both key and value type info', () => {
+      const stringCtx = createContext<number>('key');
+      const symbolCtx = createContext<string>(Symbol('key'));
+
+      // These are compile-time checks
+      expect(typeof stringCtx).toBe('string');
+      expect(typeof symbolCtx).toBe('symbol');
+    });
+  });
+});

package/src/protocol.ts

@@ -0,0 +1,115 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Web Component Context Protocol Implementation
+ *
+ * Follows the specification at:
+ * https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md
+ *
+ * Also implements extensions from @lit/context for better interop:
+ * - contextTarget property on ContextRequestEvent
+ * - ContextProviderEvent for late provider registration
+ */
+
+/**
+ * A context key.
+ *
+ * A context key can be any type of object, including strings and symbols. The
+ * Context type brands the key type with the `__context__` property that
+ * carries the type of the value the context references.
+ */
+export type Context<KeyType, ValueType> = KeyType & { __context__: ValueType };
+
+/**
+ * An unknown context type
+ */
+export type UnknownContext = Context<unknown, unknown>;
+
+/**
+ * A helper type which can extract a Context value type from a Context type
+ */
+export type ContextType<T extends UnknownContext> = T extends Context<infer _, infer V> ? V : never;
+
+/**
+ * A function which creates a Context value object
+ */
+export const createContext = <ValueType>(key: unknown) => key as Context<typeof key, ValueType>;
+
+/**
+ * A callback which is provided by a context requester and is called with the
+ * value satisfying the request. This callback can be called multiple times by
+ * context providers as the requested value is changed.
+ */
+export type ContextCallback<ValueType> = (value: ValueType, unsubscribe?: () => void) => void;
+
+/**
+ * An event fired by a context requester to signal it desires a named context.
+ *
+ * A provider should inspect the `context` property of the event to determine
+ * if it has a value that can satisfy the request, calling the `callback` with
+ * the requested value if so.
+ *
+ * If the requested context event contains a truthy `subscribe` value, then a
+ * provider can call the callback multiple times if the value is changed, if
+ * this is the case the provider should pass an `unsubscribe` function to the
+ * callback which requesters can invoke to indicate they no longer wish to
+ * receive these updates.
+ */
+export class ContextRequestEvent<T extends UnknownContext> extends Event {
+  /**
+   * @param context - The context key being requested
+   * @param callback - The callback to invoke with the context value
+   * @param options - Options for the request:
+   *   - `subscribe`: Whether to subscribe to future updates.
+   *   - `target`: The element that originally requested the context.
+   *     This is preserved when events are re-dispatched for re-parenting.
+   */
+  public readonly subscribe?: boolean;
+  public readonly contextTarget?: Element;
+
+  public constructor(
+    public readonly context: T,
+    public readonly callback: ContextCallback<ContextType<T>>,
+    options?: { subscribe?: boolean; target?: Element },
+  ) {
+    super(CONTEXT_REQUEST_EVENT, { bubbles: true, composed: true });
+    this.subscribe = options?.subscribe;
+    this.contextTarget = options?.target;
+  }
+}
+
+/**
+ * The event name for context requests
+ */
+export const CONTEXT_REQUEST_EVENT = 'context-request' as const;
+
+/**
+ * An event fired by a context provider to signal it is available.
+ *
+ * This allows ContextRoot implementations to replay pending context requests
+ * when providers are registered after consumers, and allows parent providers
+ * to re-parent their subscriptions when a closer provider appears.
+ */
+export class ContextProviderEvent<T extends UnknownContext> extends Event {
+  /**
+   * @param context - The context key this provider can provide
+   * @param contextTarget - The element hosting this provider
+   */
+  public constructor(
+    public readonly context: T,
+    public readonly contextTarget: Element,
+  ) {
+    super('context-provider', { bubbles: true, composed: true });
+  }
+}
+
+/**
+ * The event name for context provider announcements
+ */
+export const CONTEXT_PROVIDER_EVENT = 'context-provider' as const;
+
+// Note: We don't declare the global HTMLElementEventMap augmentation here
+// to avoid conflicts with @lit/context which also declares it.
+// Both follow the same protocol, so they're compatible.