react-on-rails-pro 16.2.0-beta.0

package/lib/CallbackRegistry.d.ts

@@ -0,0 +1,18 @@
+export default class CallbackRegistry<T> {
+    private readonly registryType;
+    private registeredItems;
+    private waitingPromises;
+    private notUsedItems;
+    private timeoutEventsInitialized;
+    private timedout;
+    constructor(registryType: string);
+    private initializeTimeoutEvents;
+    set(name: string, item: T): void;
+    get(name: string): T;
+    has(name: string): boolean;
+    clear(): void;
+    getAll(): Map<string, T>;
+    getOrWaitForItem(name: string): Promise<T>;
+    private createNotFoundError;
+}
+//# sourceMappingURL=CallbackRegistry.d.ts.map

package/lib/CallbackRegistry.js

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+import { onPageLoaded, onPageUnloaded } from 'react-on-rails/pageLifecycle';
+import { getRailsContext } from 'react-on-rails/context';
+export default class CallbackRegistry {
+    constructor(registryType) {
+        this.registeredItems = new Map();
+        this.waitingPromises = new Map();
+        this.notUsedItems = new Set();
+        this.timeoutEventsInitialized = false;
+        this.timedout = false;
+        this.registryType = registryType;
+    }
+    initializeTimeoutEvents() {
+        if (this.timeoutEventsInitialized)
+            return;
+        this.timeoutEventsInitialized = true;
+        let timeoutId;
+        const triggerTimeout = () => {
+            this.timedout = true;
+            this.waitingPromises.forEach((waitingPromiseInfo, itemName) => {
+                waitingPromiseInfo.reject(this.createNotFoundError(itemName));
+            });
+            this.notUsedItems.forEach((itemName) => {
+                console.warn(`Warning: ${this.registryType} '${itemName}' was registered but never used. This may indicate unused code that can be removed.`);
+            });
+        };
+        onPageLoaded(() => {
+            const registryTimeout = getRailsContext()?.componentRegistryTimeout;
+            if (!registryTimeout)
+                return;
+            timeoutId = setTimeout(triggerTimeout, registryTimeout);
+        });
+        onPageUnloaded(() => {
+            this.waitingPromises.clear();
+            this.timedout = false;
+            clearTimeout(timeoutId);
+        });
+    }
+    set(name, item) {
+        this.registeredItems.set(name, item);
+        if (this.timedout)
+            return;
+        const waitingPromiseInfo = this.waitingPromises.get(name);
+        if (waitingPromiseInfo) {
+            waitingPromiseInfo.resolve(item);
+            this.waitingPromises.delete(name);
+        }
+        else {
+            this.notUsedItems.add(name);
+        }
+    }
+    get(name) {
+        const item = this.registeredItems.get(name);
+        if (!item) {
+            throw this.createNotFoundError(name);
+        }
+        this.notUsedItems.delete(name);
+        return item;
+    }
+    has(name) {
+        return this.registeredItems.has(name);
+    }
+    clear() {
+        this.registeredItems.clear();
+        this.notUsedItems.clear();
+    }
+    getAll() {
+        return new Map(this.registeredItems);
+    }
+    async getOrWaitForItem(name) {
+        this.initializeTimeoutEvents();
+        try {
+            return this.get(name);
+        }
+        catch (error) {
+            if (this.timedout) {
+                throw error;
+            }
+            const existingWaitingPromiseInfo = this.waitingPromises.get(name);
+            if (existingWaitingPromiseInfo) {
+                return existingWaitingPromiseInfo.promise;
+            }
+            let promiseResolve = () => { };
+            let promiseReject = () => { };
+            const promise = new Promise((resolve, reject) => {
+                promiseResolve = resolve;
+                promiseReject = reject;
+            });
+            this.waitingPromises.set(name, { resolve: promiseResolve, reject: promiseReject, promise });
+            return promise;
+        }
+    }
+    createNotFoundError(itemName) {
+        const keys = Array.from(this.registeredItems.keys()).join(', ');
+        return new Error(`Could not find ${this.registryType} registered with name ${itemName}. ` +
+            `Registered ${this.registryType} names include [ ${keys} ]. ` +
+            `Maybe you forgot to register the ${this.registryType}?`);
+    }
+}
+//# sourceMappingURL=CallbackRegistry.js.map

package/lib/ClientSideRenderer.d.ts

@@ -0,0 +1,8 @@
+export declare function renderOrHydrateComponent(domIdOrElement: string | Element): Promise<void>;
+export declare const renderOrHydrateImmediateHydratedComponents: () => Promise<void>;
+export declare const renderOrHydrateAllComponents: () => Promise<void>;
+export declare function hydrateStore(storeNameOrElement: string | Element): Promise<void>;
+export declare const hydrateImmediateHydratedStores: () => Promise<void>;
+export declare const hydrateAllStores: () => Promise<void>;
+export declare function unmountAll(): void;
+//# sourceMappingURL=ClientSideRenderer.d.ts.map

package/lib/ClientSideRenderer.js

@@ -0,0 +1,238 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+import { getRailsContext, resetRailsContext } from 'react-on-rails/context';
+import createReactOutput from 'react-on-rails/createReactOutput';
+import { isServerRenderHash } from 'react-on-rails/isServerRenderResult';
+import { supportsHydrate, supportsRootApi, unmountComponentAtNode } from 'react-on-rails/reactApis';
+import reactHydrateOrRender from 'react-on-rails/reactHydrateOrRender';
+import { debugTurbolinks } from 'react-on-rails/turbolinksUtils';
+import { onPageLoaded } from 'react-on-rails/pageLifecycle';
+import * as StoreRegistry from "./StoreRegistry.js";
+import * as ComponentRegistry from "./ComponentRegistry.js";
+const REACT_ON_RAILS_STORE_ATTRIBUTE = 'data-js-react-on-rails-store';
+const IMMEDIATE_HYDRATION_PRO_WARNING = "[REACT ON RAILS] The 'immediate_hydration' feature requires a React on Rails Pro license. " +
+    'Please visit https://shakacode.com/react-on-rails-pro to get a license.';
+async function delegateToRenderer(componentObj, props, railsContext, domNodeId, trace) {
+    const { name, component, isRenderer } = componentObj;
+    if (isRenderer) {
+        if (trace) {
+            console.log(`DELEGATING TO RENDERER ${name} for dom node with id: ${domNodeId} with props, railsContext:`, props, railsContext);
+        }
+        await component(props, railsContext, domNodeId);
+        return true;
+    }
+    return false;
+}
+const getDomId = (domIdOrElement) => typeof domIdOrElement === 'string' ? domIdOrElement : domIdOrElement.getAttribute('data-dom-id') || '';
+class ComponentRenderer {
+    constructor(domIdOrElement) {
+        const domId = getDomId(domIdOrElement);
+        this.domNodeId = domId;
+        this.state = 'rendering';
+        const el = typeof domIdOrElement === 'string'
+            ? document.querySelector(`[data-dom-id="${CSS.escape(domId)}"]`)
+            : domIdOrElement;
+        if (!el)
+            return;
+        const storeDependencies = el.getAttribute('data-store-dependencies');
+        const storeDependenciesArray = storeDependencies ? JSON.parse(storeDependencies) : [];
+        const railsContext = getRailsContext();
+        if (!railsContext)
+            return;
+        // Wait for all store dependencies to be loaded
+        this.renderPromise = Promise.all(storeDependenciesArray.map((storeName) => StoreRegistry.getOrWaitForStore(storeName))).then(() => {
+            if (this.state === 'unmounted')
+                return Promise.resolve();
+            return this.render(el, railsContext);
+        });
+    }
+    /**
+     * Used for client rendering by ReactOnRails. Either calls ReactDOM.hydrate, ReactDOM.render, or
+     * delegates to a renderer registered by the user.
+     */
+    async render(el, railsContext) {
+        const isImmediateHydrationRequested = el.getAttribute('data-immediate-hydration') === 'true';
+        const hasProLicense = railsContext.rorPro;
+        // Handle immediate_hydration feature usage without Pro license
+        if (isImmediateHydrationRequested && !hasProLicense) {
+            console.warn(IMMEDIATE_HYDRATION_PRO_WARNING);
+            // Fallback to standard behavior: wait for page load before hydrating
+            if (document.readyState === 'loading') {
+                await new Promise((resolve) => {
+                    onPageLoaded(resolve);
+                });
+            }
+        }
+        // This must match lib/react_on_rails/helper.rb
+        const name = el.getAttribute('data-component-name') || '';
+        const { domNodeId } = this;
+        const props = el.textContent !== null ? JSON.parse(el.textContent) : {};
+        const trace = el.getAttribute('data-trace') === 'true';
+        try {
+            const domNode = document.getElementById(domNodeId);
+            if (domNode) {
+                const componentObj = await ComponentRegistry.getOrWaitForComponent(name);
+                if (this.state === 'unmounted') {
+                    return;
+                }
+                if ((await delegateToRenderer(componentObj, props, railsContext, domNodeId, trace)) ||
+                    // @ts-expect-error The state can change while awaiting delegateToRenderer
+                    this.state === 'unmounted') {
+                    return;
+                }
+                // Hydrate if available and was server rendered
+                const shouldHydrate = supportsHydrate && !!domNode.innerHTML;
+                const reactElementOrRouterResult = createReactOutput({
+                    componentObj,
+                    props,
+                    domNodeId,
+                    trace,
+                    railsContext,
+                    shouldHydrate,
+                });
+                if (isServerRenderHash(reactElementOrRouterResult)) {
+                    throw new Error(`\
+You returned a server side type of react-router error: ${JSON.stringify(reactElementOrRouterResult)}
+You should return a React.Component always for the client side entry point.`);
+                }
+                else {
+                    const rootOrElement = reactHydrateOrRender(domNode, reactElementOrRouterResult, shouldHydrate);
+                    this.state = 'rendered';
+                    if (supportsRootApi) {
+                        this.root = rootOrElement;
+                    }
+                }
+            }
+        }
+        catch (e) {
+            const error = e instanceof Error ? e : new Error(e?.toString() ?? 'Unknown error');
+            console.error(error.message);
+            error.message = `ReactOnRails encountered an error while rendering component: ${name}. See above error message.`;
+            throw error;
+        }
+    }
+    unmount() {
+        if (this.state === 'rendering') {
+            this.state = 'unmounted';
+            return;
+        }
+        this.state = 'unmounted';
+        if (supportsRootApi) {
+            this.root?.unmount();
+            this.root = undefined;
+        }
+        else {
+            const domNode = document.getElementById(this.domNodeId);
+            if (!domNode) {
+                return;
+            }
+            try {
+                unmountComponentAtNode(domNode);
+            }
+            catch (e) {
+                const error = e instanceof Error ? e : new Error('Unknown error');
+                console.info(`Caught error calling unmountComponentAtNode: ${error.message} for domNode`, domNode, error);
+            }
+        }
+    }
+    waitUntilRendered() {
+        if (this.state === 'rendering' && this.renderPromise) {
+            return this.renderPromise;
+        }
+        return Promise.resolve();
+    }
+}
+class StoreRenderer {
+    constructor(storeDataElement) {
+        this.state = 'hydrating';
+        const railsContext = getRailsContext();
+        if (!railsContext) {
+            return;
+        }
+        const name = storeDataElement.getAttribute(REACT_ON_RAILS_STORE_ATTRIBUTE) || '';
+        const props = storeDataElement.textContent !== null
+            ? JSON.parse(storeDataElement.textContent)
+            : {};
+        this.hydratePromise = this.hydrate(railsContext, name, props);
+    }
+    async hydrate(railsContext, name, props) {
+        const storeGenerator = await StoreRegistry.getOrWaitForStoreGenerator(name);
+        if (this.state === 'unmounted') {
+            return;
+        }
+        const store = storeGenerator(props, railsContext);
+        StoreRegistry.setStore(name, store);
+        this.state = 'hydrated';
+    }
+    waitUntilHydrated() {
+        if (this.state === 'hydrating' && this.hydratePromise) {
+            return this.hydratePromise;
+        }
+        return Promise.resolve();
+    }
+    unmount() {
+        this.state = 'unmounted';
+    }
+}
+const renderedRoots = new Map();
+export function renderOrHydrateComponent(domIdOrElement) {
+    const domId = getDomId(domIdOrElement);
+    debugTurbolinks('renderOrHydrateComponent', domId);
+    let root = renderedRoots.get(domId);
+    if (!root) {
+        root = new ComponentRenderer(domIdOrElement);
+        renderedRoots.set(domId, root);
+    }
+    return root.waitUntilRendered();
+}
+async function forAllElementsAsync(selector, callback) {
+    const els = document.querySelectorAll(selector);
+    await Promise.all(Array.from(els).map(callback));
+}
+export const renderOrHydrateImmediateHydratedComponents = () => forAllElementsAsync('.js-react-on-rails-component[data-immediate-hydration="true"]', renderOrHydrateComponent);
+export const renderOrHydrateAllComponents = () => forAllElementsAsync('.js-react-on-rails-component', renderOrHydrateComponent);
+function unmountAllComponents() {
+    renderedRoots.forEach((root) => root.unmount());
+    renderedRoots.clear();
+    resetRailsContext();
+}
+const storeRenderers = new Map();
+export async function hydrateStore(storeNameOrElement) {
+    const storeName = typeof storeNameOrElement === 'string'
+        ? storeNameOrElement
+        : storeNameOrElement.getAttribute(REACT_ON_RAILS_STORE_ATTRIBUTE) || '';
+    let storeRenderer = storeRenderers.get(storeName);
+    if (!storeRenderer) {
+        const storeDataElement = typeof storeNameOrElement === 'string'
+            ? document.querySelector(`[${REACT_ON_RAILS_STORE_ATTRIBUTE}="${CSS.escape(storeNameOrElement)}"]`)
+            : storeNameOrElement;
+        if (!storeDataElement) {
+            return;
+        }
+        storeRenderer = new StoreRenderer(storeDataElement);
+        storeRenderers.set(storeName, storeRenderer);
+    }
+    await storeRenderer.waitUntilHydrated();
+}
+export const hydrateImmediateHydratedStores = () => forAllElementsAsync(`[${REACT_ON_RAILS_STORE_ATTRIBUTE}][data-immediate-hydration="true"]`, hydrateStore);
+export const hydrateAllStores = () => forAllElementsAsync(`[${REACT_ON_RAILS_STORE_ATTRIBUTE}]`, hydrateStore);
+function unmountAllStores() {
+    storeRenderers.forEach((storeRenderer) => storeRenderer.unmount());
+    storeRenderers.clear();
+}
+export function unmountAll() {
+    unmountAllComponents();
+    unmountAllStores();
+}
+//# sourceMappingURL=ClientSideRenderer.js.map

package/lib/ComponentRegistry.d.ts

@@ -0,0 +1,22 @@
+import { type RegisteredComponent, type ReactComponentOrRenderFunction } from 'react-on-rails/types';
+/**
+ * @param components { component1: component1, component2: component2, etc. }
+ * @public
+ */
+export declare function register(components: Record<string, ReactComponentOrRenderFunction>): void;
+/**
+ * @param name
+ * @returns { name, component, isRenderFunction, isRenderer }
+ */
+export declare const get: (name: string) => RegisteredComponent;
+export declare const getOrWaitForComponent: (name: string) => Promise<RegisteredComponent>;
+/**
+ * Get a Map containing all registered components. Useful for debugging.
+ * @returns Map where key is the component name and values are the
+ * { name, component, renderFunction, isRenderer}
+ * @public
+ */
+export declare const components: () => Map<string, RegisteredComponent>;
+/** @internal Exported only for tests */
+export declare function clear(): void;
+//# sourceMappingURL=ComponentRegistry.d.ts.map

package/lib/ComponentRegistry.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+import isRenderFunction from 'react-on-rails/isRenderFunction';
+import CallbackRegistry from "./CallbackRegistry.js";
+const componentRegistry = new CallbackRegistry('component');
+/**
+ * @param components { component1: component1, component2: component2, etc. }
+ * @public
+ */
+export function register(components) {
+    Object.keys(components).forEach((name) => {
+        if (componentRegistry.has(name)) {
+            console.warn('Called register for component that is already registered', name);
+        }
+        const component = components[name];
+        if (!component) {
+            throw new Error(`Called register with null component named ${name}`);
+        }
+        const renderFunction = isRenderFunction(component);
+        const isRenderer = renderFunction && component.length === 3;
+        componentRegistry.set(name, {
+            name,
+            component,
+            renderFunction,
+            isRenderer,
+        });
+    });
+}
+/**
+ * @param name
+ * @returns { name, component, isRenderFunction, isRenderer }
+ */
+export const get = (name) => componentRegistry.get(name);
+export const getOrWaitForComponent = (name) => componentRegistry.getOrWaitForItem(name);
+/**
+ * Get a Map containing all registered components. Useful for debugging.
+ * @returns Map where key is the component name and values are the
+ * { name, component, renderFunction, isRenderer}
+ * @public
+ */
+export const components = () => componentRegistry.getAll();
+/** @internal Exported only for tests */
+export function clear() {
+    componentRegistry.clear();
+}
+//# sourceMappingURL=ComponentRegistry.js.map

package/lib/PostSSRHookTracker.d.ts

@@ -0,0 +1,32 @@
+type PostSSRHook = () => void;
+/**
+ * Post-SSR Hook Tracker - manages post-SSR hooks for a single request.
+ *
+ * This class provides a local alternative to the global hook management,
+ * allowing each request to have its own isolated hook tracker without sharing state.
+ *
+ * The tracker ensures that:
+ * - Hooks are executed exactly once when SSR ends
+ * - No hooks can be added after SSR has completed
+ * - Proper cleanup occurs to prevent memory leaks
+ */
+declare class PostSSRHookTracker {
+    private hooks;
+    private hasSSREnded;
+    /**
+     * Adds a hook to be executed when SSR ends for this request.
+     *
+     * @param hook - Function to call when SSR ends
+     * @throws Error if called after SSR has already ended
+     */
+    addPostSSRHook(hook: PostSSRHook): void;
+    /**
+     * Notifies all registered hooks that SSR has ended and clears the hook list.
+     * This should be called exactly once when server-side rendering is complete.
+     *
+     * @throws Error if called multiple times
+     */
+    notifySSREnd(): void;
+}
+export default PostSSRHookTracker;
+//# sourceMappingURL=PostSSRHookTracker.d.ts.map

package/lib/PostSSRHookTracker.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025 Shakacode LLC
+ *
+ * This file is NOT licensed under the MIT (open source) license.
+ * It is part of the React on Rails Pro offering and is licensed separately.
+ *
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without a valid license agreement
+ * from Shakacode LLC.
+ *
+ * For licensing terms, please see:
+ * https://github.com/shakacode/react_on_rails/blob/master/REACT-ON-RAILS-PRO-LICENSE.md
+ */
+/**
+ * Post-SSR Hook Tracker - manages post-SSR hooks for a single request.
+ *
+ * This class provides a local alternative to the global hook management,
+ * allowing each request to have its own isolated hook tracker without sharing state.
+ *
+ * The tracker ensures that:
+ * - Hooks are executed exactly once when SSR ends
+ * - No hooks can be added after SSR has completed
+ * - Proper cleanup occurs to prevent memory leaks
+ */
+class PostSSRHookTracker {
+    constructor() {
+        this.hooks = [];
+        this.hasSSREnded = false;
+    }
+    /**
+     * Adds a hook to be executed when SSR ends for this request.
+     *
+     * @param hook - Function to call when SSR ends
+     * @throws Error if called after SSR has already ended
+     */
+    addPostSSRHook(hook) {
+        if (this.hasSSREnded) {
+            console.error('Cannot add post-SSR hook: SSR has already ended for this request. ' +
+                'Hooks must be registered before or during the SSR process.');
+            return;
+        }
+        this.hooks.push(hook);
+    }
+    /**
+     * Notifies all registered hooks that SSR has ended and clears the hook list.
+     * This should be called exactly once when server-side rendering is complete.
+     *
+     * @throws Error if called multiple times
+     */
+    notifySSREnd() {
+        if (this.hasSSREnded) {
+            console.warn('notifySSREnd() called multiple times. This may indicate a bug in the SSR lifecycle.');
+            return;
+        }
+        this.hasSSREnded = true;
+        // Execute all hooks and handle any errors gracefully
+        this.hooks.forEach((hook, index) => {
+            try {
+                hook();
+            }
+            catch (error) {
+                console.error(`Error executing post-SSR hook ${index}:`, error);
+            }
+        });
+        // Clear hooks to free memory
+        this.hooks = [];
+    }
+}
+export default PostSSRHookTracker;
+//# sourceMappingURL=PostSSRHookTracker.js.map

package/lib/RSCProvider.d.ts

@@ -0,0 +1,52 @@
+import { type ReactNode } from 'react';
+import type { ClientGetReactServerComponentProps } from './getReactServerComponent.client.ts';
+type RSCContextType = {
+    getComponent: (componentName: string, componentProps: unknown) => Promise<ReactNode>;
+    refetchComponent: (componentName: string, componentProps: unknown) => Promise<ReactNode>;
+};
+/**
+ * Creates a provider context for React Server Components.
+ *
+ * RSCProvider is a foundational component that:
+ * 1. Provides caching for server components to prevent redundant requests
+ * 2. Manages the fetching of server components through getComponent
+ * 3. Offers environment-agnostic access to server components
+ *
+ * This factory function accepts an environment-specific getServerComponent implementation,
+ * allowing it to work correctly in both client and server environments.
+ *
+ * @param railsContext - Context for the current request
+ * @param getServerComponent - Environment-specific function for fetching server components
+ * @returns A provider component that wraps children with RSC context
+ *
+ * @important This is an internal function. End users should not use this directly.
+ * Instead, use wrapServerComponentRenderer from 'react-on-rails/wrapServerComponentRenderer/client'
+ * for client-side rendering or 'react-on-rails/wrapServerComponentRenderer/server' for server-side rendering.
+ */
+export declare const createRSCProvider: ({ getServerComponent, }: {
+    getServerComponent: (props: ClientGetReactServerComponentProps) => Promise<ReactNode>;
+}) => ({ children }: {
+    children: ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the RSC context within client components.
+ *
+ * This hook provides access to:
+ * - getComponent: For fetching and rendering server components
+ * - refetchComponent: For refetching server components
+ *
+ * It must be used within a component wrapped by RSCProvider (typically done
+ * automatically by wrapServerComponentRenderer).
+ *
+ * @returns The RSC context containing methods for working with server components
+ * @throws Error if used outside of an RSCProvider
+ *
+ * @example
+ * ```tsx
+ * const { getComponent } = useRSC();
+ * const serverComponent = use(getComponent('MyServerComponent', props));
+ * ```
+ */
+export declare const useRSC: () => RSCContextType;
+export {};
+//# sourceMappingURL=RSCProvider.d.ts.map