@jay-framework/component 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -41,6 +41,31 @@ declare const forTesting: {
 
 declare const CONTEXT_REACTIVE_SYMBOL_CONTEXT: unique symbol;
 declare function createReactiveContext<T extends object>(mkContext: () => T): T;
+/**
+ * Creates a reactive context and registers it globally.
+ * Use this in `withClient` initialization to create reactive global contexts.
+ *
+ * @param marker - The context marker created with createJayContext()
+ * @param mkContext - Factory function that creates the context (can use createSignal, etc.)
+ * @returns The created context (for immediate use in init)
+ *
+ * @example
+ * ```typescript
+ * export const init = makeJayInit()
+ *   .withClient(async () => {
+ *     const ctx = registerReactiveGlobalContext(MY_CONTEXT, () => {
+ *       const [count, setCount] = createSignal(0);
+ *       return {
+ *         count,
+ *         increment: () => setCount(n => n + 1),
+ *         async init() { await loadData(); },
+ *       };
+ *     });
+ *     await ctx.init();
+ *   });
+ * ```
+ */
+declare function registerReactiveGlobalContext<T extends object>(marker: ContextMarker<T>, mkContext: () => T): T;
 
 type EffectCleanup = () => void;
 declare function createEffect(effect: () => void | EffectCleanup): void;
@@ -66,4 +91,4 @@ interface ComponentContext extends HookContext {
 declare const COMPONENT_CONTEXT: ContextMarker<ComponentContext>;
 declare const CONTEXT_CREATION_CONTEXT: ContextMarker<HookContext>;
 
-export { COMPONENT_CONTEXT, CONTEXT_CREATION_CONTEXT, CONTEXT_REACTIVE_SYMBOL_CONTEXT, type ComponentConstructor, type ComponentContext, type ConcreteJayComponent, type ContextMarkers, type EffectCleanup, type HookContext, type JayComponentCore, type JayTsxComponentConstructor, type JsxNode, type Patcher, type Props, type UpdatableProps, type ViewStateGetters, createDerivedArray, createEffect, createEvent, createMemo, createPatchableSignal, createReactiveContext, createSignal, forTesting, type hasProps, makeJayComponent, makeJayTsxComponent, makePropsProxy, materializeViewState, provideContext, provideReactiveContext, useReactive };
+export { COMPONENT_CONTEXT, CONTEXT_CREATION_CONTEXT, CONTEXT_REACTIVE_SYMBOL_CONTEXT, type ComponentConstructor, type ComponentContext, type ConcreteJayComponent, type ContextMarkers, type EffectCleanup, type HookContext, type JayComponentCore, type JayTsxComponentConstructor, type JsxNode, type Patcher, type Props, type UpdatableProps, type ViewStateGetters, createDerivedArray, createEffect, createEvent, createMemo, createPatchableSignal, createReactiveContext, createSignal, forTesting, type hasProps, makeJayComponent, makeJayTsxComponent, makePropsProxy, materializeViewState, provideContext, provideReactiveContext, registerReactiveGlobalContext, useReactive };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createJayContext, withContext, findContext, useContext } from "@jay-framework/runtime";
+import { createJayContext, withContext, registerGlobalContext, findContext, useContext, VIEW_STATE_CHANGE_EVENT } from "@jay-framework/runtime";
 import { mkReactive, GetterMark, SetterMark, MeasureOfChange } from "@jay-framework/reactive";
 import { patch } from "@jay-framework/json-patch";
 const COMPONENT_CONTEXT = createJayContext();
@@ -34,6 +34,11 @@ function createReactiveContext(mkContext) {
   );
   return newContextProxy(reactive, context);
 }
+function registerReactiveGlobalContext(marker, mkContext) {
+  const context = createReactiveContext(mkContext);
+  registerGlobalContext(marker, context);
+  return context;
+}
 function currentHookContext() {
   return findContext((_) => _ === COMPONENT_CONTEXT || _ === CONTEXT_CREATION_CONTEXT);
 }
@@ -221,9 +226,12 @@ function makeJayComponent(preRender, comp, ...contextMarkers) {
       componentContext.provideContexts.forEach(
         ([marker, context]) => context[CONTEXT_REACTIVE_SYMBOL_CONTEXT] && reactive.enablePairing(context[CONTEXT_REACTIVE_SYMBOL_CONTEXT])
       );
+      let currentViewState;
+      let viewStateChangeListener;
       componentContext.reactive.createReaction(() => {
         let viewStateValueOrGetters = renderViewState();
         let viewState = materializeViewState(viewStateValueOrGetters);
+        currentViewState = viewState;
         if (!element)
           element = renderWithContexts(
             componentContext.provideContexts,
@@ -232,19 +240,24 @@ function makeJayComponent(preRender, comp, ...contextMarkers) {
           );
         else
           element.update(viewState);
+        viewStateChangeListener?.({ event: viewState, viewState, coordinate: [] });
       });
       const [mount, unmount] = mkMounts(componentContext, element);
       let update = (updateProps) => {
         propsProxy.update(updateProps);
       };
-      let events = {};
+      let events = {
+        [VIEW_STATE_CHANGE_EVENT]: (handler) => {
+          viewStateChangeListener = handler;
+        }
+      };
       let component = {
         element,
         update,
         mount,
         unmount,
-        addEventListener: (eventType, handler) => events[eventType](handler),
-        removeEventListener: (eventType) => events[eventType](void 0)
+        addEventListener: (eventType, handler) => events[eventType]?.(handler),
+        removeEventListener: (eventType) => events[eventType]?.(void 0)
       };
       for (let key in api) {
         if (typeof api[key] === "function") {
@@ -260,6 +273,11 @@ function makeJayComponent(preRender, comp, ...contextMarkers) {
           component[key] = api[key];
         }
       }
+      Object.defineProperty(component, "viewState", {
+        get: () => currentViewState,
+        enumerable: false,
+        configurable: true
+      });
       return componentInstance = component;
     });
   };
@@ -318,5 +336,6 @@ export {
   materializeViewState,
   provideContext,
   provideReactiveContext,
+  registerReactiveGlobalContext,
   useReactive
 };

package/docs/register-reactive-global-context.md

@@ -0,0 +1,128 @@
+# registerReactiveGlobalContext
+
+Creates a reactive context and registers it globally for use across the application.
+
+Use this in `withClient` initialization (via `makeJayInit`) to create reactive global contexts
+that are available to all components without needing a parent component to provide them.
+
+```typescript
+declare function registerReactiveGlobalContext<T extends object>(
+  marker: ContextMarker<T>,
+  mkContext: () => T,
+): T;
+```
+
+## Parameters:
+
+- `marker`: A unique symbol identifying the context, created using `createJayContext`.
+- `mkContext`: A function that creates the initial context value.
+  The function may use any of the Jay Hooks (`createSignal`, `createEffect`, etc.) and should return an object which represents the context.
+
+## Returns:
+
+The created reactive context value, which can be used immediately in the init function.
+
+## Behavior
+
+- Creates a `Reactive` instance for signal tracking
+- Sets up the context creation environment so `createSignal()` and other hooks work
+- Returns a proxy that batches reactions for function calls (same as `provideReactiveContext`)
+- Registers the context in the global registry so it's available via `useContext()`
+
+## Examples:
+
+### Basic Counter Context
+
+```typescript
+import { createJayContext } from '@jay-framework/runtime';
+import { createSignal, registerReactiveGlobalContext } from '@jay-framework/component';
+import { makeJayInit } from '@jay-framework/fullstack-component';
+
+interface CounterContext {
+  count: () => number;
+  increment: () => void;
+}
+
+export const COUNTER_CTX = createJayContext<CounterContext>();
+
+export const init = makeJayInit().withClient(() => {
+  registerReactiveGlobalContext(COUNTER_CTX, () => {
+    const [count, setCount] = createSignal(0);
+    return {
+      count,
+      increment: () => setCount((n) => n + 1),
+    };
+  });
+});
+```
+
+### Async Initialization Pattern
+
+For contexts that need async initialization, expose an `init()` method:
+
+```typescript
+interface WixClientContext {
+  client: WixClient;
+  isReady: () => boolean;
+  init: () => Promise<void>;
+}
+
+export const WIX_CLIENT_CTX = createJayContext<WixClientContext>();
+
+export const init = makeJayInit().withClient(async () => {
+  const ctx = registerReactiveGlobalContext(WIX_CLIENT_CTX, () => {
+    const [isReady, setIsReady] = createSignal(false);
+
+    return {
+      client: wixClient,
+      isReady,
+      async init() {
+        const tokens = await wixClient.auth.generateVisitorTokens();
+        wixClient.auth.setTokens(tokens);
+        setIsReady(true);
+      },
+    };
+  });
+
+  // Call init immediately
+  await ctx.init();
+});
+```
+
+### Using the Context in Components
+
+```typescript
+import { useContext } from '@jay-framework/runtime';
+import { COUNTER_CTX } from '../lib/init';
+
+function MyComponent(props, refs) {
+  // Access the global context
+  const counter = useContext(COUNTER_CTX);
+
+  refs.incrementButton.onclick(() => {
+    counter.increment();
+  });
+
+  return {
+    render: () => ({
+      count: counter.count(),
+    }),
+  };
+}
+```
+
+## Comparison with provideReactiveContext
+
+| Feature       | `provideReactiveContext`                     | `registerReactiveGlobalContext` |
+| ------------- | -------------------------------------------- | ------------------------------- |
+| Scope         | Component subtree                            | Entire application              |
+| When to use   | Component provides context to children       | App initialization              |
+| Where to call | Inside component constructor                 | Inside `withClient`             |
+| Override      | Child components can provide different value | Cannot be overridden            |
+
+## Design Log
+
+For additional information on the design decisions, read:
+
+- [67 - registerReactiveGlobalContext.md](../../../../design-log/67%20-%20registerReactiveGlobalContext.md)
+- [65 - makeJayInit builder pattern.md](../../../../design-log/65%20-%20makeJayInit%20builder%20pattern.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/component",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -21,12 +21,12 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/json-patch": "^0.9.0",
-    "@jay-framework/reactive": "^0.9.0",
-    "@jay-framework/runtime": "^0.9.0"
+    "@jay-framework/json-patch": "^0.11.0",
+    "@jay-framework/reactive": "^0.11.0",
+    "@jay-framework/runtime": "^0.11.0"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.9.0",
+    "@jay-framework/dev-environment": "^0.11.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/node": "^20.11.5",
     "rimraf": "^5.0.5",

package/readme.md

@@ -27,6 +27,7 @@ Hooks for providing context:
 
 - [provideContext](./docs/provide-context.md)
 - [provideReactiveContext](./docs/provide-reactive-context.md)
+- [registerReactiveGlobalContext](./docs/register-reactive-global-context.md)
 
 Hooks to get Component Reactive Instance: