react-on-rails 17.0.0-rc.6 → 17.0.0-rc.7

package/README.md

@@ -81,11 +81,12 @@ ReactOnRails.register({
 
 ## Exports
 
-| Export Path             | Description                         |
-| ----------------------- | ----------------------------------- |
-| `react-on-rails`        | Full build with SSR utilities       |
-| `react-on-rails/client` | Client-only build (smaller, no SSR) |
-| `react-on-rails/types`  | TypeScript type exports             |
+| Export Path                  | Description                          |
+| ---------------------------- | ------------------------------------ |
+| `react-on-rails`             | Full build with SSR utilities        |
+| `react-on-rails/client`      | Client-only build (smaller, no SSR)  |
+| `react-on-rails/railsAction` | CSRF-aware typed Rails action caller |
+| `react-on-rails/types`       | TypeScript type exports              |
 
 ## Rails-Side Setup
 

package/lib/ClientRenderer.js

@@ -17,8 +17,8 @@ const renderedRoots = new Map();
  * Invokes a renderer teardown, swallowing async rejections so a failing teardown cannot produce an
  * unhandled promise rejection. Synchronous throws propagate to the caller's try/catch. `domNodeId`
  * is included in the log so a failure can be traced to its mount.
- * MUST SYNC: A sibling helper exists in packages/react-on-rails-pro/src/ClientSideRenderer.ts. If you
- * change the error-handling logic or log format here, update that copy too.
+ * MIRROR OF: packages/react-on-rails-pro/src/ClientSideRenderer.ts (sibling helper). If you change
+ * the error-handling logic or log format here, update that copy too.
  */
 function invokeRendererTeardown(teardown, domNodeId) {
     if (!teardown)
@@ -118,6 +118,7 @@ function scheduleWhenVisible(domNode, callback) {
         const target = entries[0]?.target;
         if (target && !target.isConnected) {
             observer.disconnect();
+            callback();
             return;
         }
         const isVisible = entries.some((entry) => entry.isIntersecting || entry.intersectionRatio > 0);
@@ -270,7 +271,9 @@ function trackRendererMount(domNodeId, domNode, result) {
  * delegates to a renderer registered by the user.
  */
 function renderElement(el, railsContext) {
-    // This must match lib/react_on_rails/helper.rb
+    // This must match the data-* attributes emitted by lib/react_on_rails/pro_helper.rb.
+    // Covered end-to-end by every spec/dummy client-rendering test (renaming either side fails
+    // loudly), so no MIRROR VALUES guard is added here.
     const name = el.getAttribute('data-component-name') || '';
     const domNodeId = domNodeIdForEl(el);
     const props = el.textContent !== null ? JSON.parse(el.textContent) : {};

package/lib/StoreRegistry.d.ts

@@ -29,6 +29,10 @@ declare const _default: {
      * Internally used function to completely clear hydratedStores Map.
      */
     clearHydratedStores(): void;
+    /**
+     * Internally used function to completely clear registeredStoreGenerators Map.
+     */
+    clearStoreGenerators(): void;
     /**
      * Get a Map containing all registered store generators. Useful for debugging.
      * @returns Map where key is the component name and values are the store generators.

package/lib/StoreRegistry.js

@@ -33,6 +33,9 @@ export default {
         if (hydratedStores.has(name)) {
             return hydratedStores.get(name);
         }
+        if (!throwIfMissing) {
+            return undefined;
+        }
         const storeKeys = Array.from(hydratedStores.keys()).join(', ');
         if (storeKeys.length === 0) {
             const msg = `There are no stores hydrated and you are requesting the store ${name}.
@@ -42,12 +45,8 @@ This can happen if you are server rendering and either:
 2. You do not render redux_store_hydration_data anywhere on your page.`;
             throw new Error(msg);
         }
-        if (throwIfMissing) {
-            console.log('storeKeys', storeKeys);
-            throw new Error(`Could not find hydrated store with name '${name}'. ` +
-                `Hydrated store names include [${storeKeys}].`);
-        }
-        return undefined;
+        console.log('storeKeys', storeKeys);
+        throw new Error(`Could not find hydrated store with name '${name}'. Hydrated store names include [${storeKeys}].`);
     },
     /**
      * Internally used function to get the store creator that was passed to `register`.
@@ -77,6 +76,12 @@ This can happen if you are server rendering and either:
     clearHydratedStores() {
         hydratedStores.clear();
     },
+    /**
+     * Internally used function to completely clear registeredStoreGenerators Map.
+     */
+    clearStoreGenerators() {
+        registeredStoreGenerators.clear();
+    },
     /**
      * Get a Map containing all registered store generators. Useful for debugging.
      * @returns Map where key is the component name and values are the store generators.

package/lib/base/client.d.ts

@@ -16,6 +16,7 @@ interface Registries {
         getStoreGenerator: (name: string) => StoreGenerator;
         setStore: (name: string, store: Store) => void;
         clearHydratedStores: () => void;
+        clearStoreGenerators: () => void;
         storeGenerators: () => Map<string, StoreGenerator>;
         stores: () => Map<string, Store>;
     };

package/lib/base/client.js

@@ -2,23 +2,27 @@
  * @deprecated Use `capabilities/core.ts` instead. This file is kept for backward compatibility
  * with older versions of react-on-rails-pro that import from `react-on-rails/@internal/base/client`.
  */
-import * as Authenticity from "../Authenticity.js";
-import buildConsoleReplay, { consoleReplay } from "../buildConsoleReplay.js";
-import reactHydrateOrRender from "../reactHydrateOrRender.js";
-import createReactOutput from "../createReactOutput.js";
-import componentRegistrationMetric from "../componentRegistrationMetric.js";
-import { buildRootErrorCallbackOptions, getRootErrorHandlers, resetRootErrorHandlers, setRootErrorHandlers, } from "../rootErrorHandlers.js";
-const DEFAULT_OPTIONS = {
-    traceTurbolinks: false,
-    turbo: false,
-    debugMode: false,
-    logComponentRegistration: false,
-};
+import { createCoreCapability } from "../capabilities/core.js";
+// Pro-only methods that `createCoreCapability` includes as stubs but the historical base
+// surface omits. This list drives the runtime key-stripping in `createBaseClientObject`.
+// `satisfies readonly (keyof ReactOnRailsInternal)[]` makes a typo or a stale name a compile
+// error, and the `assertProOnlyMethodsMatchOmit` guard inside `createBaseClientObject` pins this
+// list to the `Omit<...>` in `BaseClientObjectType` so the runtime list and the exported type can
+// never drift.
+const PRO_ONLY_METHODS = [
+    'getOrWaitForComponent',
+    'getOrWaitForStore',
+    'getOrWaitForStoreGenerator',
+    'reactOnRailsStoreLoaded',
+    'streamServerRenderedReactComponent',
+    'serverRenderRSCReactComponent',
+    'addAsyncPropsCapabilityToComponentProps',
+    'getOrCreateAsyncPropsManager',
+];
 // Cache to track created objects and their registries
 let cachedObject = null;
 let cachedRegistries = null;
 export function createBaseClientObject(registries, currentObject = null) {
-    const { ComponentRegistry, StoreRegistry } = registries;
     // Error detection: currentObject is null but we have a cached object
     // This indicates webpack misconfiguration (multiple runtime chunks)
     if (currentObject === null && cachedObject !== null) {
@@ -60,168 +64,25 @@ Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
     if (cachedObject !== null) {
         return cachedObject;
     }
-    // Create and return new object
-    const obj = {
-        options: {},
-        isRSCBundle: false,
-        // ===================================================================
-        // STABLE METHOD IMPLEMENTATIONS - Core package implementations
-        // ===================================================================
-        authenticityToken() {
-            return Authenticity.authenticityToken();
-        },
-        authenticityHeaders(otherHeaders = {}) {
-            return Authenticity.authenticityHeaders(otherHeaders);
-        },
-        reactHydrateOrRender(domNode, reactElement, hydrate) {
-            // The component name is unknown on this low-level path; the dom id still ties errors to a mount.
-            const rootErrorCallbackOptions = buildRootErrorCallbackOptions({ domNodeId: domNode.id || undefined }, hydrate);
-            return reactHydrateOrRender(domNode, reactElement, hydrate, rootErrorCallbackOptions);
-        },
-        setOptions(newOptions) {
-            const { traceTurbolinks, turbo, debugMode, logComponentRegistration, rootErrorHandlers, ...rest } = newOptions;
-            if (typeof traceTurbolinks !== 'undefined') {
-                this.options.traceTurbolinks = traceTurbolinks;
-            }
-            if (typeof turbo !== 'undefined') {
-                this.options.turbo = turbo;
-            }
-            if (typeof debugMode !== 'undefined') {
-                this.options.debugMode = debugMode;
-                if (debugMode) {
-                    console.log('[ReactOnRails] Debug mode enabled');
-                }
-            }
-            if (typeof logComponentRegistration !== 'undefined') {
-                this.options.logComponentRegistration = logComponentRegistration;
-                if (logComponentRegistration) {
-                    console.log('[ReactOnRails] Component registration logging enabled');
-                }
-            }
-            if (Object.prototype.hasOwnProperty.call(newOptions, 'rootErrorHandlers')) {
-                // MUST SYNC: sibling implementation exists in packages/react-on-rails/src/capabilities/core.ts.
-                // Validates and merges the handlers per key (partial updates keep previously registered
-                // callbacks); warns when the React runtime cannot support them. Store the merged result so
-                // `option('rootErrorHandlers')` reflects the effective registration.
-                if (typeof rootErrorHandlers === 'undefined') {
-                    resetRootErrorHandlers();
-                    this.options.rootErrorHandlers = undefined;
-                }
-                else {
-                    setRootErrorHandlers(rootErrorHandlers);
-                    this.options.rootErrorHandlers = getRootErrorHandlers();
-                }
-            }
-            if (Object.keys(rest).length > 0) {
-                throw new Error(`Invalid options passed to ReactOnRails.options: ${JSON.stringify(rest)}`);
-            }
-        },
-        option(key) {
-            return this.options[key];
-        },
-        buildConsoleReplay() {
-            return buildConsoleReplay();
-        },
-        getConsoleReplayScript() {
-            return consoleReplay();
-        },
-        resetOptions() {
-            this.options = { ...DEFAULT_OPTIONS };
-            resetRootErrorHandlers();
-        },
-        // ===================================================================
-        // REGISTRY METHOD IMPLEMENTATIONS - Using provided registries
-        // ===================================================================
-        register(components) {
-            if (this.options.debugMode || this.options.logComponentRegistration) {
-                // Use performance.now() if available, otherwise fallback to Date.now()
-                const perf = typeof performance !== 'undefined' ? performance : { now: () => Date.now() };
-                const startTime = perf.now();
-                const componentNames = Object.keys(components);
-                console.log(`[ReactOnRails] Registering ${componentNames.length} component(s): ${componentNames.join(', ')}`);
-                ComponentRegistry.register(components);
-                const endTime = perf.now();
-                console.log(`[ReactOnRails] Component registration completed in ${(endTime - startTime).toFixed(2)}ms`);
-                // Log individual component details if in full debug mode
-                if (this.options.debugMode) {
-                    componentNames.forEach((name) => {
-                        const component = components[name];
-                        const registrationMetric = componentRegistrationMetric(component);
-                        console.log(`[ReactOnRails] ✅ Registered: ${name} (${registrationMetric.value} ${registrationMetric.label})`);
-                    });
-                }
-            }
-            else {
-                ComponentRegistry.register(components);
-            }
-        },
-        registerStore(stores) {
-            this.registerStoreGenerators(stores);
-        },
-        registerStoreGenerators(storeGenerators) {
-            if (!storeGenerators) {
-                throw new Error('Called ReactOnRails.registerStoreGenerators with a null or undefined, rather than ' +
-                    'an Object with keys being the store names and the values are the store generators.');
-            }
-            StoreRegistry.register(storeGenerators);
-        },
-        getStore(name, throwIfMissing = true) {
-            return StoreRegistry.getStore(name, throwIfMissing);
-        },
-        getStoreGenerator(name) {
-            return StoreRegistry.getStoreGenerator(name);
-        },
-        setStore(name, store) {
-            StoreRegistry.setStore(name, store);
-        },
-        clearHydratedStores() {
-            StoreRegistry.clearHydratedStores();
-        },
-        getComponent(name) {
-            return ComponentRegistry.get(name);
-        },
-        registeredComponents() {
-            return ComponentRegistry.components();
-        },
-        storeGenerators() {
-            return StoreRegistry.storeGenerators();
-        },
-        stores() {
-            return StoreRegistry.stores();
-        },
-        render(name, props, domNodeId, hydrate) {
-            const componentObj = ComponentRegistry.get(name);
-            const reactElement = createReactOutput({ componentObj, props, domNodeId });
-            return reactHydrateOrRender(document.getElementById(domNodeId), reactElement, hydrate, buildRootErrorCallbackOptions({ componentName: name || undefined, domNodeId: domNodeId || undefined }, hydrate));
-        },
-        // ===================================================================
-        // CLIENT-SIDE RENDERING STUBS - To be overridden by createReactOnRails
-        // ===================================================================
-        reactOnRailsPageLoaded() {
-            throw new Error('ReactOnRails.reactOnRailsPageLoaded is not initialized. This is a bug in react-on-rails.');
-        },
-        reactOnRailsComponentLoaded(domId) {
-            void domId; // Mark as used
-            throw new Error('ReactOnRails.reactOnRailsComponentLoaded is not initialized. This is a bug in react-on-rails.');
-        },
-        // ===================================================================
-        // SSR STUBS - Will throw errors in client bundle, overridden in full
-        // ===================================================================
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        serverRenderReactComponent(...args) {
-            void args; // Mark as used
-            throw new Error('serverRenderReactComponent is not available in "react-on-rails/client". Import "react-on-rails" server-side.');
-        },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        handleError(...args) {
-            void args; // Mark as used
-            throw new Error('handleError is not available in "react-on-rails/client". Import "react-on-rails" server-side.');
-        },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        prepareRenderResult(...args) {
-            void args; // Mark as used
-            throw new Error('prepareRenderResult is not available in "react-on-rails/client". Import "react-on-rails" server-side.');
-        },
+    const assertProOnlyMethodsMatchOmit = true;
+    void assertProOnlyMethodsMatchOmit;
+    // Delegate the core method implementations to `createCoreCapability` (the canonical source),
+    // then re-shape to the historical base surface: strip the Pro-only stubs (using the shared
+    // `PRO_ONLY_METHODS` list that the drift guard above pins to `BaseClientObjectType`, so runtime
+    // and type can never drift) and add the client-side lifecycle stubs that `createReactOnRails`
+    // overrides at initialization.
+    const proOnlyMethods = new Set(PRO_ONLY_METHODS);
+    const core = createCoreCapability(registries);
+    const obj = Object.fromEntries(Object.entries(core).filter(([key]) => !proOnlyMethods.has(key)));
+    // ===================================================================
+    // CLIENT-SIDE RENDERING STUBS - To be overridden by createReactOnRails
+    // ===================================================================
+    obj.reactOnRailsPageLoaded = () => {
+        throw new Error('ReactOnRails.reactOnRailsPageLoaded is not initialized. This is a bug in react-on-rails.');
+    };
+    obj.reactOnRailsComponentLoaded = (domId) => {
+        void domId; // Mark as used
+        throw new Error('ReactOnRails.reactOnRailsComponentLoaded is not initialized. This is a bug in react-on-rails.');
     };
     // Cache the object and registries
     cachedObject = obj;

package/lib/base/full.js

@@ -2,35 +2,17 @@
  * @deprecated Use `capabilities/ssr.ts` instead. This file is kept for backward compatibility
  * with older versions of react-on-rails-pro that import from `react-on-rails/@internal/base/full`.
  */
+// This is a thin compatibility shim: the SSR implementations live in `capabilities/ssr.ts`
+// (`createSSRCapability`). This file composes them onto the base client object, preserving
+// the historical `createBaseFullObject` surface old Pro consumers rely on.
 import { createBaseClientObject } from "./client.js";
-import handleError from "../handleError.js";
-import serverRenderReactComponent from "../serverRenderReactComponent.js";
-import { buildLengthPrefixedResult } from "../serverRenderUtils.js";
-// Warn about bundle size when included in browser bundles
-if (typeof window !== 'undefined') {
-    console.warn('Optimization opportunity: "react-on-rails" includes ~14KB of server-rendering code. ' +
-        'Browsers may not need it. See https://forum.shakacode.com/t/how-to-use-different-versions-of-a-file-for-client-and-server-rendering/1352 ' +
-        '(Requires creating a free account). Click this for the stack trace.');
-}
+import { createSSRCapability } from "../capabilities/ssr.js";
 export function createBaseFullObject(registries, currentObject = null) {
     // Get or create client object (with caching logic)
     const clientObject = createBaseClientObject(registries, currentObject);
-    // Define SSR-specific functions with proper types
-    // This object acts as a type-safe specification of what we're adding to the base object
-    const reactOnRailsFullSpecificFunctions = {
-        handleError(options) {
-            return handleError(options);
-        },
-        serverRenderReactComponent(options) {
-            return serverRenderReactComponent(options);
-        },
-        prepareRenderResult(html, consoleReplayScript, hasErrors, renderingError) {
-            return buildLengthPrefixedResult(html, consoleReplayScript, {
-                hasErrors,
-                error: renderingError ?? undefined,
-            });
-        },
-    };
+    // Delegate the SSR-specific functions to `createSSRCapability` (the canonical source).
+    // Typed to ReactOnRailsFullSpecificFunctions so we add exactly the SSR surface, nothing more.
+    const reactOnRailsFullSpecificFunctions = createSSRCapability();
     // Type assertion is safe here because:
     // 1. We start with BaseClientObjectType (from createBaseClientObject)
     // 2. We add exactly the methods defined in ReactOnRailsFullSpecificFunctions

package/lib/base/full.rsc.js

@@ -2,23 +2,17 @@
  * @deprecated Use `capabilities/ssr.rsc.ts` instead. This file is kept for backward compatibility
  * with older versions of react-on-rails-pro that import from `react-on-rails/@internal/base/full`.
  */
+// This is a thin compatibility shim: the RSC SSR stubs live in `capabilities/ssr.rsc.ts`
+// (`createSSRCapability`). This file composes them onto the base client object, preserving
+// the historical `createBaseFullObject` surface old Pro consumers rely on.
 import { createBaseClientObject } from "./client.js";
+import { createSSRCapability } from "../capabilities/ssr.rsc.js";
 export function createBaseFullObject(registries, currentObject = null) {
     // Get or create client object (with caching logic)
     const clientObject = createBaseClientObject(registries, currentObject);
-    // Define SSR-specific functions with proper types
-    // This object acts as a type-safe specification of what we're adding to the base object
-    const reactOnRailsFullSpecificFunctions = {
-        handleError() {
-            throw new Error('"handleError" function is not supported in RSC bundle');
-        },
-        serverRenderReactComponent() {
-            throw new Error('"serverRenderReactComponent" function is not supported in RSC bundle');
-        },
-        prepareRenderResult() {
-            throw new Error('"prepareRenderResult" function is not supported in RSC bundle');
-        },
-    };
+    // Delegate the RSC SSR stubs to `createSSRCapability` (the canonical source).
+    // Typed to ReactOnRailsFullSpecificFunctions so we add exactly the SSR surface, nothing more.
+    const reactOnRailsFullSpecificFunctions = createSSRCapability();
     // Type assertion is safe here because:
     // 1. We start with BaseClientObjectType (from createBaseClientObject)
     // 2. We add exactly the methods defined in ReactOnRailsFullSpecificFunctions

package/lib/capabilities/core.d.ts

@@ -13,6 +13,7 @@ export interface Registries {
         getStoreGenerator: (name: string) => StoreGenerator;
         setStore: (name: string, store: Store) => void;
         clearHydratedStores: () => void;
+        clearStoreGenerators: () => void;
         storeGenerators: () => Map<string, StoreGenerator>;
         stores: () => Map<string, Store>;
     };
@@ -39,6 +40,7 @@ export declare function createCoreCapability(registries: Registries): {
     getStoreGenerator(name: string): StoreGenerator;
     setStore(name: string, store: Store): void;
     clearHydratedStores(): void;
+    clearStoreGenerators(): void;
     getComponent(name: string): RegisteredComponentEntry;
     registeredComponents(): Map<string, RegisteredComponentEntry>;
     storeGenerators(): Map<string, StoreGenerator>;

package/lib/capabilities/core.js

@@ -54,7 +54,6 @@ export function createCoreCapability(registries) {
                 }
             }
             if (Object.prototype.hasOwnProperty.call(newOptions, 'rootErrorHandlers')) {
-                // MUST SYNC: sibling implementation exists in packages/react-on-rails/src/base/client.ts.
                 // Validates and merges the handlers per key (partial updates keep previously registered
                 // callbacks); warns when the React runtime cannot support them. Store the merged result so
                 // `option('rootErrorHandlers')` reflects the effective registration.
@@ -132,6 +131,9 @@ export function createCoreCapability(registries) {
         clearHydratedStores() {
             StoreRegistry.clearHydratedStores();
         },
+        clearStoreGenerators() {
+            StoreRegistry.clearStoreGenerators();
+        },
         getComponent(name) {
             return ComponentRegistry.get(name);
         },

package/lib/railsAction.d.ts

@@ -0,0 +1,68 @@
+export type RailsActionMethod = 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'post' | 'put' | 'patch' | 'delete';
+export type RailsActionPath<TVariables> = string | ((variables: TVariables) => string);
+export interface RailsActionOptions<TVariables> {
+    path: RailsActionPath<TVariables>;
+    method?: RailsActionMethod;
+    /**
+     * Maps variables to the JSON request body. Omit to send variables verbatim;
+     * supply `() => null` to send no body when variables only populate the path.
+     * DELETE requests never send a body; identify the resource in the URL instead.
+     */
+    body?: (variables: TVariables) => unknown;
+    /**
+     * Additional request headers. `X-CSRF-Token`, `X-Requested-With`, and the JSON-body
+     * `Content-Type` are controlled by this helper. `Accept` defaults to `application/json`
+     * but can be overridden here. When no JSON body is sent, `Content-Type` is removed after
+     * these headers are merged.
+     */
+    headers?: HeadersInit | ((variables: TVariables) => HeadersInit);
+}
+export interface RailsActionCallOptions {
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+}
+export interface RailsActionMutationFunctionContext {
+    client: unknown;
+    meta: Record<string, unknown> | undefined;
+    mutationKey?: readonly unknown[];
+}
+export type RailsActionCallerOptions = RailsActionCallOptions | RailsActionMutationFunctionContext;
+type RailsActionNoVariables = ReturnType<() => void>;
+export type RailsActionCaller<TVariables, TResponse> = [TVariables] extends [RailsActionNoVariables] ? (variables?: RailsActionNoVariables, options?: RailsActionCallerOptions) => Promise<TResponse> : (variables: TVariables, options?: RailsActionCallerOptions) => Promise<TResponse>;
+export declare class RailsActionRequestError<TResponseBody = unknown> extends Error {
+    readonly response: Response;
+    readonly responseBody: TResponseBody;
+    readonly cause?: unknown;
+    constructor(response: Response, responseBody: TResponseBody, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Creates a CSRF-aware JSON caller for a Rails controller action.
+ *
+ * Supply the response generic from the generated Rails response declarations:
+ *
+ * ```ts
+ * type CreateProjectResponse = RailsResponseType<'projects.create'>;
+ * const createProject = createRailsAction<CreateProjectVariables, CreateProjectResponse>({
+ *   path: '/api/projects',
+ * });
+ * ```
+ *
+ * The returned function is directly usable as a TanStack Query `mutationFn`.
+ * It always requests JSON, rejects browser-followed redirects, and resolves 204 or non-JSON success
+ * responses as `null`. Include `null` in `TResponse` when a successful empty response is expected.
+ * A 200 response with `text/html`, such as an unexpected Rails error page, also resolves as `null`.
+ * `options.headers` can override the default `Accept: application/json`; include `null` in `TResponse`
+ * when that custom Accept header may produce a successful non-JSON response.
+ * Omitting `body` sends `variables` as the JSON body verbatim; supply `body` to map or filter fields before
+ * serialization.
+ * Body values that would serialize lossy or outside JSON, including nested `undefined`, `BigInt`, and
+ * non-finite numbers, are rejected before `fetch` runs.
+ * When `variables` only populate `path`, supply `body: () => null` or a mapper to avoid forwarding them.
+ * Return `null` or `undefined` from `body` when the request should not send JSON. DELETE requests never
+ * send a JSON body; identify the resource in the URL instead.
+ */
+export declare function createRailsAction<TVariables = undefined, TResponse = unknown>(options: RailsActionOptions<TVariables>): RailsActionCaller<TVariables, TResponse>;
+export {};
+//# sourceMappingURL=railsAction.d.ts.map

package/lib/railsAction.js

@@ -0,0 +1,373 @@
+import { authenticityToken } from "./Authenticity.js";
+export class RailsActionRequestError extends Error {
+    constructor(response, responseBody, options = {}) {
+        super(`Rails action request failed with status ${response.status}`);
+        this.name = 'RailsActionRequestError';
+        this.response = response;
+        this.responseBody = responseBody;
+        if (options.cause !== undefined) {
+            Object.defineProperty(this, 'cause', {
+                configurable: true,
+                value: options.cause,
+                writable: true,
+            });
+        }
+    }
+}
+const resolveSameOriginRequestUrl = (url) => {
+    try {
+        // Ignore document.baseURI so a page-level <base> tag cannot rewrite Rails action paths before the origin check.
+        const resolvedUrl = new URL(url, window.location.href);
+        if ((resolvedUrl.protocol === 'http:' || resolvedUrl.protocol === 'https:') &&
+            resolvedUrl.origin === window.location.origin) {
+            return resolvedUrl.href;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+};
+const JSON_CONTENT_TYPE_PATTERN = /^(application\/json|[^/]+\/[^;]+\+json)(?:\s*;|\s*$)/i;
+const isJsonResponse = (response) => JSON_CONTENT_TYPE_PATTERN.test(response.headers.get('Content-Type') ?? '');
+const isAbortError = (error) => typeof error === 'object' && error !== null && 'name' in error && error.name === 'AbortError';
+const parseOptionalJsonBody = async (response) => {
+    if (!isJsonResponse(response)) {
+        return null;
+    }
+    try {
+        return (await response.json());
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError)) {
+            throw error;
+        }
+        return null;
+    }
+};
+const parseSuccessJsonBody = async (response) => {
+    if (response.status === 204 || response.status === 205) {
+        return null;
+    }
+    if (!isJsonResponse(response)) {
+        return null;
+    }
+    const responseText = await response.text();
+    return responseText.trim() === '' ? null : JSON.parse(responseText);
+};
+const warnOnPossibleRedirectFetchError = (fetchError) => {
+    if (process.env.NODE_ENV === 'production' || !(fetchError instanceof TypeError)) {
+        return;
+    }
+    if (!/failed to fetch|networkerror|load failed/i.test(fetchError.message)) {
+        return;
+    }
+    console.warn('[createRailsAction] The request may have failed because the server responded with a redirect or ' +
+        'because the network is unavailable. createRailsAction requires JSON responses; Rails `redirect_to` ' +
+        'is not supported for mutation endpoints.');
+};
+const warnOnDiscardedDeleteBody = (requestBody) => {
+    if (requestBody === undefined || requestBody === null) {
+        return false;
+    }
+    console.warn('[createRailsAction] A DELETE request resolved a JSON body that will not be sent. ' +
+        'Use `body: () => null` when variables only populate the path, or identify the resource in the URL instead.');
+    return true;
+};
+const warnOnImplicitBodyWithDynamicPath = () => {
+    console.warn('[createRailsAction] A dynamic path with no `body` mapper sends all variables as the JSON body. ' +
+        'Supply `body` to choose which fields are serialized, or `body: () => null` when variables only populate the path.');
+};
+const nonJsonBodyTypeName = (requestBody) => {
+    if (requestBody === undefined) {
+        return 'undefined';
+    }
+    if (typeof requestBody === 'number' && !Number.isFinite(requestBody)) {
+        return 'non-finite number';
+    }
+    if (typeof Date !== 'undefined' && requestBody instanceof Date && Number.isNaN(requestBody.getTime())) {
+        return 'invalid Date';
+    }
+    if (typeof Number !== 'undefined' &&
+        requestBody instanceof Number &&
+        !Number.isFinite(requestBody.valueOf())) {
+        return 'non-finite Number';
+    }
+    if (typeof FormData !== 'undefined' && requestBody instanceof FormData) {
+        return 'FormData';
+    }
+    if (typeof File !== 'undefined' && requestBody instanceof File) {
+        return 'File';
+    }
+    if (typeof Blob !== 'undefined' && requestBody instanceof Blob) {
+        return 'Blob';
+    }
+    if (typeof Headers !== 'undefined' && requestBody instanceof Headers) {
+        return 'Headers';
+    }
+    if (typeof Request !== 'undefined' && requestBody instanceof Request) {
+        return 'Request';
+    }
+    if (typeof Response !== 'undefined' && requestBody instanceof Response) {
+        return 'Response';
+    }
+    if (typeof URLSearchParams !== 'undefined' && requestBody instanceof URLSearchParams) {
+        return 'URLSearchParams';
+    }
+    if (typeof ArrayBuffer !== 'undefined' && requestBody instanceof ArrayBuffer) {
+        return 'ArrayBuffer';
+    }
+    if (typeof ArrayBuffer !== 'undefined' && ArrayBuffer.isView(requestBody)) {
+        return requestBody.constructor.name || 'ArrayBufferView';
+    }
+    if (typeof Map !== 'undefined' && requestBody instanceof Map) {
+        return 'Map';
+    }
+    if (typeof Set !== 'undefined' && requestBody instanceof Set) {
+        return 'Set';
+    }
+    if (typeof WeakMap !== 'undefined' && requestBody instanceof WeakMap) {
+        return 'WeakMap';
+    }
+    if (typeof WeakSet !== 'undefined' && requestBody instanceof WeakSet) {
+        return 'WeakSet';
+    }
+    if (typeof Error !== 'undefined' && requestBody instanceof Error) {
+        return requestBody.name || 'Error';
+    }
+    if (typeof RegExp !== 'undefined' && requestBody instanceof RegExp) {
+        return 'RegExp';
+    }
+    if (typeof requestBody === 'bigint') {
+        return 'BigInt';
+    }
+    if (typeof requestBody === 'function') {
+        return 'Function';
+    }
+    if (typeof requestBody === 'symbol') {
+        return 'Symbol';
+    }
+    if (typeof ReadableStream !== 'undefined' && requestBody instanceof ReadableStream) {
+        return 'ReadableStream';
+    }
+    if (typeof requestBody !== 'object' || requestBody === null) {
+        return null;
+    }
+    const maybeThenable = requestBody;
+    if (typeof maybeThenable.then === 'function') {
+        return 'Promise';
+    }
+    return null;
+};
+const preSerializationNonJsonBodyTypeName = (requestBody, activeObjects = new Set()) => {
+    const bodyTypeName = nonJsonBodyTypeName(requestBody);
+    if (bodyTypeName !== null) {
+        return bodyTypeName;
+    }
+    if (typeof requestBody !== 'object' || requestBody === null) {
+        return null;
+    }
+    const objectBody = requestBody;
+    if (typeof objectBody.toJSON === 'function') {
+        return null;
+    }
+    if (activeObjects.has(requestBody)) {
+        return 'circular object';
+    }
+    activeObjects.add(requestBody);
+    try {
+        const values = Array.isArray(requestBody)
+            ? requestBody
+            : Object.values(requestBody);
+        for (const value of values) {
+            const nestedBodyTypeName = preSerializationNonJsonBodyTypeName(value, activeObjects);
+            if (nestedBodyTypeName !== null) {
+                return nestedBodyTypeName;
+            }
+        }
+        return null;
+    }
+    finally {
+        activeObjects.delete(requestBody);
+    }
+};
+const jsonBodyTypeError = (bodyTypeName) => new TypeError(`[createRailsAction] The request body resolved to ${bodyTypeName}, which cannot be JSON serialized correctly. ` +
+    'Return a plain JSON value, null, or undefined instead.');
+const originalJsonBodyValue = (holder, key, rootBody) => {
+    if (key === '') {
+        return rootBody;
+    }
+    if (typeof holder !== 'object' || holder === null) {
+        return undefined;
+    }
+    return holder[key];
+};
+const stringifyJsonBody = (requestBody) => {
+    try {
+        const bodyTypeName = preSerializationNonJsonBodyTypeName(requestBody);
+        if (bodyTypeName !== null) {
+            throw jsonBodyTypeError(bodyTypeName);
+        }
+        const serializedBody = JSON.stringify(requestBody, function replaceJsonBodyValue(key, value) {
+            const originalValue = originalJsonBodyValue(this, key, requestBody);
+            const originalBodyTypeName = nonJsonBodyTypeName(originalValue);
+            if (originalBodyTypeName !== null) {
+                throw jsonBodyTypeError(originalBodyTypeName);
+            }
+            const replacedBodyTypeName = nonJsonBodyTypeName(value);
+            if (replacedBodyTypeName !== null) {
+                throw jsonBodyTypeError(replacedBodyTypeName);
+            }
+            return value;
+        });
+        if (serializedBody === undefined) {
+            throw jsonBodyTypeError('undefined');
+        }
+        return serializedBody;
+    }
+    catch (error) {
+        if (error instanceof TypeError && /BigInt/i.test(error.message)) {
+            throw new TypeError('[createRailsAction] The request body contains a BigInt value, which cannot be JSON serialized correctly. ' +
+                'Convert BigInt values to strings or numbers before returning the body.');
+        }
+        throw error;
+    }
+};
+const mergeHeaders = (...headersList) => {
+    const headers = new Headers();
+    headersList.forEach((headersInit) => {
+        if (headersInit === undefined) {
+            return;
+        }
+        new Headers(headersInit).forEach((value, key) => {
+            headers.set(key, value);
+        });
+    });
+    return headers;
+};
+const buildRailsActionHeaders = (csrfToken, hasJsonBody, ...headersList) => {
+    const headers = mergeHeaders({ Accept: 'application/json' }, ...headersList);
+    if (hasJsonBody) {
+        headers.set('Content-Type', 'application/json');
+    }
+    else {
+        headers.delete('Content-Type');
+    }
+    headers.set('X-CSRF-Token', csrfToken);
+    headers.set('X-Requested-With', 'XMLHttpRequest');
+    return headers;
+};
+const resolvePath = (path, variables) => typeof path === 'function' ? path(variables) : path;
+const resolveHeaders = (headers, variables) => (typeof headers === 'function' ? headers(variables) : headers);
+const hasOwnProperty = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+function callOptionsValue(callOptions, key) {
+    if (typeof callOptions !== 'object' || callOptions === null) {
+        return undefined;
+    }
+    return hasOwnProperty(callOptions, key) ? callOptions[key] : undefined;
+}
+const assertBrowserContext = () => {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        throw new Error('createRailsAction can only be used in browser contexts.');
+    }
+};
+/**
+ * Creates a CSRF-aware JSON caller for a Rails controller action.
+ *
+ * Supply the response generic from the generated Rails response declarations:
+ *
+ * ```ts
+ * type CreateProjectResponse = RailsResponseType<'projects.create'>;
+ * const createProject = createRailsAction<CreateProjectVariables, CreateProjectResponse>({
+ *   path: '/api/projects',
+ * });
+ * ```
+ *
+ * The returned function is directly usable as a TanStack Query `mutationFn`.
+ * It always requests JSON, rejects browser-followed redirects, and resolves 204 or non-JSON success
+ * responses as `null`. Include `null` in `TResponse` when a successful empty response is expected.
+ * A 200 response with `text/html`, such as an unexpected Rails error page, also resolves as `null`.
+ * `options.headers` can override the default `Accept: application/json`; include `null` in `TResponse`
+ * when that custom Accept header may produce a successful non-JSON response.
+ * Omitting `body` sends `variables` as the JSON body verbatim; supply `body` to map or filter fields before
+ * serialization.
+ * Body values that would serialize lossy or outside JSON, including nested `undefined`, `BigInt`, and
+ * non-finite numbers, are rejected before `fetch` runs.
+ * When `variables` only populate `path`, supply `body: () => null` or a mapper to avoid forwarding them.
+ * Return `null` or `undefined` from `body` when the request should not send JSON. DELETE requests never
+ * send a JSON body; identify the resource in the URL instead.
+ */
+export function createRailsAction(options) {
+    const method = (options.method ?? 'POST').toUpperCase();
+    // DELETE body discard is an action configuration problem, so warn at most once per DELETE action factory.
+    let warnedOnDiscardedDeleteBody = method !== 'DELETE' || process.env.NODE_ENV === 'production';
+    let warnedOnImplicitDynamicPathBody = method === 'DELETE' ||
+        typeof options.path !== 'function' ||
+        options.body !== undefined ||
+        process.env.NODE_ENV === 'production';
+    const callRailsAction = async (variables, callOptions = {}) => {
+        // The public conditional type only permits omitted variables when TVariables is undefined.
+        const typedVariables = variables;
+        assertBrowserContext();
+        const resolvedPath = resolvePath(options.path, typedVariables);
+        const requestUrl = resolveSameOriginRequestUrl(resolvedPath);
+        if (requestUrl === null) {
+            throw new Error('createRailsAction can only call same-origin Rails action URLs. ' +
+                'Ensure the path resolves to the same origin as the current page.');
+        }
+        const csrfToken = authenticityToken()?.trim();
+        if (!csrfToken) {
+            throw new Error('createRailsAction requires a <meta name="csrf-token"> tag before submitting. ' +
+                'Add <%= csrf_meta_tags %> to your Rails layout.');
+        }
+        const requestBody = options.body !== undefined ? options.body(typedVariables) : typedVariables;
+        const hasJsonBody = method !== 'DELETE' && requestBody !== undefined && requestBody !== null;
+        const shouldWarnOnDiscardedDeleteBody = !warnedOnDiscardedDeleteBody && requestBody !== undefined && requestBody !== null;
+        const shouldWarnOnImplicitDynamicPathBody = !warnedOnImplicitDynamicPathBody && hasJsonBody;
+        const serializedRequestBody = hasJsonBody ? stringifyJsonBody(requestBody) : undefined;
+        if (shouldWarnOnDiscardedDeleteBody) {
+            warnOnDiscardedDeleteBody(requestBody);
+            warnedOnDiscardedDeleteBody = true;
+        }
+        if (shouldWarnOnImplicitDynamicPathBody) {
+            warnOnImplicitBodyWithDynamicPath();
+            warnedOnImplicitDynamicPathBody = true;
+        }
+        let response;
+        try {
+            response = await fetch(requestUrl, {
+                method,
+                mode: 'same-origin',
+                credentials: 'same-origin',
+                redirect: 'error',
+                signal: callOptionsValue(callOptions, 'signal'),
+                headers: buildRailsActionHeaders(csrfToken, hasJsonBody, resolveHeaders(options.headers, typedVariables), callOptionsValue(callOptions, 'headers')),
+                body: serializedRequestBody,
+            });
+        }
+        catch (fetchError) {
+            warnOnPossibleRedirectFetchError(fetchError);
+            throw fetchError;
+        }
+        if (!response.ok) {
+            // Keep this clone before any error-body reads so callers can still inspect the original response body.
+            let responseBody = null;
+            let bodyReadError;
+            try {
+                responseBody = await parseOptionalJsonBody(response.clone());
+            }
+            catch (error) {
+                if (isAbortError(error)) {
+                    throw error;
+                }
+                bodyReadError = error;
+                responseBody = null;
+            }
+            throw new RailsActionRequestError(response, responseBody, { cause: bodyReadError });
+        }
+        const responseBody = await parseSuccessJsonBody(response);
+        return responseBody;
+    };
+    return callRailsAction;
+}
+//# sourceMappingURL=railsAction.js.map

package/lib/types/index.d.ts

@@ -30,6 +30,8 @@ export type RailsContext = {
     httpAcceptLanguage: string;
     rscPayloadGenerationUrlPath?: string;
     cspNonce?: string;
+    /** Omit or leave undefined to disable; only true is a valid opt-in value. */
+    rscStreamObservability?: true;
 } & ({
     serverSide: false;
 } | {
@@ -320,9 +322,10 @@ export interface ReactOnRails {
     /** @deprecated Use registerStoreGenerators instead */
     registerStore(stores: Record<string, StoreGenerator>): void;
     /**
-     * Allows registration of store generators to be used by multiple React components on one Rails
-     * view. Store generators are functions that take one arg, props, and return a store. Note that
-     * the `setStore` API is different in that it's the actual store hydrated with props.
+     * Allows registration of store generators for legacy or advanced pages where multiple React roots
+     * on one Rails view share a Redux store. Store generators receive props and railsContext, then
+     * return a store. Note that the `setStore` API is different in that it's the actual store hydrated
+     * with props.
      * @param storeGenerators keys are store names, values are the store generators
      */
     registerStoreGenerators(storeGenerators: Record<string, StoreGenerator>): void;
@@ -408,6 +411,11 @@ export interface ReactOnRailsInternal extends ReactOnRails {
      * request.
      */
     clearHydratedStores(): void;
+    /**
+     * Clears registered store generators. Used by internal tests and setup code that must reset global
+     * registration state between runs.
+     */
+    clearStoreGenerators(): void;
     /**
      * @example
      * ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-on-rails",
-  "version": "17.0.0-rc.6",
+  "version": "17.0.0-rc.7",
   "description": "react-on-rails JavaScript for react_on_rails Ruby gem",
   "main": "lib/ReactOnRails.full.js",
   "type": "module",
@@ -29,6 +29,10 @@
     "./pageLifecycle": "./lib/pageLifecycle.js",
     "./createReactOutput": "./lib/createReactOutput.js",
     "./isServerRenderResult": "./lib/isServerRenderResult.js",
+    "./railsAction": {
+      "types": "./lib/railsAction.d.ts",
+      "default": "./lib/railsAction.js"
+    },
     "./reactApis": "./lib/reactApis.cjs",
     "./webpackHelpers": "./lib/webpackHelpers.cjs",
     "./reactHydrateOrRender": "./lib/reactHydrateOrRender.js",