@stone-js/use-react 0.2.0 → 0.3.1

package/dist/index.js

@@ -1,11 +1,11 @@
-import { isNotEmpty, isEmpty, InitializationError, isMetaClassModule, isMetaFactoryModule, isFunctionModule, isObjectLikeModule, isFunction, mergeBlueprints, stoneBlueprint, classDecoratorLegacyWrapper, setMetadata, methodDecoratorLegacyWrapper, addMetadata, LIFECYCLE_HOOK_KEY, hasMetadata, getMetadata, isMatchedAdapter, Logger, addBlueprint } from '@stone-js/core';
+import { isNotEmpty, isEmpty, InitializationError, isMetaClassModule, isMetaFactoryModule, isObjectLikeModule, isFunction, isFunctionModule, classDecoratorLegacyWrapper, setMetadata, methodDecoratorLegacyWrapper, addMetadata, LIFECYCLE_HOOK_KEY, hasMetadata, getMetadata, isMatchedAdapter, mergeBlueprints, stoneBlueprint, Logger, addBlueprint } from '@stone-js/core';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { renderToString } from 'react-dom/server';
-import { createContext, StrictMode, useState, useEffect, useContext } from 'react';
-import { createRoot, hydrateRoot } from 'react-dom/client';
+import { createContext, StrictMode, useContext, useMemo, useState, useEffect } from 'react';
+import { hydrateRoot, createRoot } from 'react-dom/client';
 import { Config } from '@stone-js/config';
 import { GET, NODE_CONSOLE_PLATFORM, Router, RouteEvent } from '@stone-js/router';
-import { OutgoingHttpResponse, RedirectResponse, MetaStaticFileMiddleware, MetaCompressionMiddleware } from '@stone-js/http-core';
+import { RedirectResponse, OutgoingHttpResponse, MetaCompressionMiddleware, MetaStaticFileMiddleware } from '@stone-js/http-core';
 
 /**
   * Stone DOM Attribute.
@@ -912,167 +912,6 @@ class UseReactServiceProvider {
  */
 const MetaUseReactServiceProvider = { module: UseReactServiceProvider, isClass: true };
 
-/**
- * Utility function to define an adapter error page.
- *
- * @param module - The adapter error page module.
- * @param options - Optional adapter error page options.
- * @returns The UseReactBlueprint.
- */
-function defineAdapterErrorPage(module, options) {
-    const error = options?.error ?? 'default';
-    const adapterErrorPages = Object.fromEntries([error].flat().map((err) => [
-        err,
-        {
-            ...options,
-            module,
-            error: err,
-            isFactory: options?.isClass !== true
-        }
-    ]));
-    return {
-        stone: {
-            useReact: {
-                adapterErrorPages
-            }
-        }
-    };
-}
-
-/**
- * Default blueprint for a React-based Stone.js application.
- *
- * - Defines middleware, lifecycle hooks, and the default HTML template path.
- */
-const internalUseReactBlueprint = {
-    stone: {
-        useReact: {},
-        services: [MetaReactRuntime],
-        providers: [MetaUseReactServiceProvider]
-    }
-};
-
-/**
- * Defines a Stone React app using a factory-based or class-based main handler.
- *
- * @param moduleOrOptions - A factory function or class constructor for the main page.
- * @param optionsOrBlueprints - Optional application-level configuration.
- * @param maybeBlueprints - Additional blueprints to merge.
- * @returns A fully merged Stone blueprint.
- */
-function defineStoneReactApp(moduleOrOptions = {}, optionsOrBlueprints, maybeBlueprints) {
-    let module;
-    let options = {};
-    let blueprints = [];
-    // Pattern: defineStoneReactApp(handler, options?, blueprints?)
-    if (isFunctionModule(moduleOrOptions)) {
-        module = moduleOrOptions;
-        if (isObjectLikeModule(optionsOrBlueprints)) {
-            options = optionsOrBlueprints;
-            blueprints = Array.isArray(maybeBlueprints) ? maybeBlueprints : [];
-        }
-    }
-    else if (isObjectLikeModule(moduleOrOptions)) { // Pattern: defineStoneReactApp(options, blueprints?)
-        options = moduleOrOptions;
-        blueprints = Array.isArray(optionsOrBlueprints) ? optionsOrBlueprints : [];
-    }
-    const stonePart = {
-        ...options,
-        useReact: {
-            ...options.useReact
-        }
-    };
-    if (isNotEmpty(module)) {
-        stonePart.useReact.componentEventHandler = {
-            module,
-            isComponent: true,
-            isClass: options.isClass,
-            isFactory: options.isClass !== true
-        };
-    }
-    return mergeBlueprints(stoneBlueprint, internalUseReactBlueprint, ...blueprints, { stone: stonePart });
-}
-
-/**
- * Utility function to define a page.
- *
- * @param module - The EventHandler module.
- * @param options - Page definition options.
- * @returns The UseReactBlueprint.
- */
-function definePage(module, options) {
-    return {
-        stone: {
-            router: {
-                definitions: [
-                    {
-                        ...options,
-                        method: GET,
-                        methods: [],
-                        children: undefined,
-                        handler: {
-                            module,
-                            isComponent: true,
-                            layout: options?.layout,
-                            isClass: options?.isClass,
-                            isFactory: options?.isClass !== true
-                        }
-                    }
-                ]
-            }
-        }
-    };
-}
-/**
- * Utility function to define a page layout.
- *
- * @param module - The layout module.
- * @param options - Optional page layout definition options.
- * @returns The UseReactBlueprint.
- */
-function definePageLayout(module, options) {
-    const name = options?.name ?? 'default';
-    return {
-        stone: {
-            useReact: {
-                layout: {
-                    [name]: {
-                        module,
-                        isClass: options?.isClass,
-                        isFactory: options?.isClass !== true
-                    }
-                }
-            }
-        }
-    };
-}
-/**
- * Utility function to define an error page.
- *
- * @param module - The layout module.
- * @param options - Optional page layout definition options.
- * @returns The UseReactBlueprint.
- */
-function defineErrorPage(module, options) {
-    const error = options?.error ?? 'default';
-    const errorPages = Object.fromEntries([error].flat().map((err) => [
-        err,
-        {
-            ...options,
-            module,
-            error: err,
-            isFactory: options?.isClass !== true
-        }
-    ]));
-    return {
-        stone: {
-            useReact: {
-                errorPages
-            }
-        }
-    };
-}
-
 /**
  * Constants are defined here to prevent Circular dependency between modules
  * This pattern must be applied to all Stone libraries or third party libraries.
@@ -1147,37 +986,24 @@ const ErrorPage = (options) => {
 };
 
 /**
- * A class decorator for defining a class as a React Page route action.
- * Uses the `Match` decorator internally to register the route with the HTTP `GET` method.
- *
- * @param options - Configuration options for the route definition, excluding the `methods` property.
- * @returns A method decorator to be applied to a class method.
+ * Hook decorator to mark a method as a lifecycle hook
+ * And automatically add it to the global lifecycle hook registry.
  *
  * @example
  * ```typescript
- * import { Page } from '@stone-js/use-react';
- *
- * @Page('/user-profile')
- * class UserPage {
- *   handle({ event }): Record<string, string> {
- *     return { name: 'Jane Doe' };
- *   }
- *
- *   render({ data }) {
- *     return <h1>User name: {data.name}</h1>;
- *   }
+ * class MyClass {
+ *    // ...
+ *    @Hook('onPreparingPage')
+ *    onPreparingPage () {}
  * }
  * ```
+ *
+ * @param name - The name of the lifecycle hook.
+ * @returns A class decorator function that sets the metadata using the provided options.
  */
-const Page = (path, options = {}) => {
-    return classDecoratorLegacyWrapper((target, context) => {
-        setMetadata(context, REACT_PAGE_KEY, {
-            ...options,
-            path,
-            method: GET,
-            methods: [],
-            handler: { isClass: true, isComponent: true, layout: options.layout, module: target }
-        });
+const Hook = (name) => {
+    return methodDecoratorLegacyWrapper((_target, context) => {
+        addMetadata(context, LIFECYCLE_HOOK_KEY, { name, method: context.name });
     });
 };
 
@@ -1206,24 +1032,31 @@ const PageLayout = (options) => {
 };
 
 /**
- * Hook decorator to mark a method as a lifecycle hook
- * And automatically add it to the global lifecycle hook registry.
+ * Decorator to create a snapshot of the current data.
+ *
+ * @param name - The name of the snapshot.
+ * @returns A method decorator.
  *
  * @example
  * ```typescript
- * class MyClass {
- *    // ...
- *    @Hook('onPreparingPage')
- *    onPreparingPage () {}
+ * import { Service } from '@stone-js/core';
+ * import { Snapshot } from '@stone-js/use-react';
+ *
+ * @Service({ alias: 'userService' })
+ * class UserService {
+ *   @Snapshot()
+ *   showProfile() {
+ *     return { name: 'John Doe' };
+ *   }
  * }
  * ```
- *
- * @param name - The name of the lifecycle hook.
- * @returns A class decorator function that sets the metadata using the provided options.
  */
-const Hook = (name) => {
-    return methodDecoratorLegacyWrapper((_target, context) => {
-        addMetadata(context, LIFECYCLE_HOOK_KEY, { name, method: context.name });
+const Snapshot = (name) => {
+    return methodDecoratorLegacyWrapper((target, context) => {
+        return async function (...args) {
+            name = name ?? `${String(Object.getPrototypeOf(this).constructor.name)}.${String(context.name)}`;
+            return await ReactRuntime.instance?.snapshot(name, () => target.apply(this, args));
+        };
     });
 };
 
@@ -1257,33 +1090,74 @@ const PageStatus = (statusCode = 200, headers = {}) => {
 };
 
 /**
- * Decorator to create a snapshot of the current data.
+ * A class decorator for defining a class as a React Page route action.
+ * Uses the `Match` decorator internally to register the route with the HTTP `GET` method.
  *
- * @param name - The name of the snapshot.
- * @returns A method decorator.
+ * @param options - Configuration options for the route definition, excluding the `methods` property.
+ * @returns A method decorator to be applied to a class method.
  *
  * @example
  * ```typescript
- * import { Service } from '@stone-js/core';
- * import { Snapshot } from '@stone-js/use-react';
+ * import { Page } from '@stone-js/use-react';
  *
- * @Service({ alias: 'userService' })
- * class UserService {
- *   @Snapshot()
- *   showProfile() {
- *     return { name: 'John Doe' };
+ * @Page('/user-profile')
+ * class UserPage {
+ *   handle({ event }): Record<string, string> {
+ *     return { name: 'Jane Doe' };
+ *   }
+ *
+ *   render({ data }) {
+ *     return <h1>User name: {data.name}</h1>;
  *   }
  * }
  * ```
  */
-const Snapshot = (name) => {
-    return methodDecoratorLegacyWrapper((target, context) => {
-        return async function (...args) {
-            name = name ?? `${String(Object.getPrototypeOf(this).constructor.name)}.${String(context.name)}`;
-            return await ReactRuntime.instance?.snapshot(name, () => target.apply(this, args));
-        };
+const Page = (path, options = {}) => {
+    return classDecoratorLegacyWrapper((target, context) => {
+        setMetadata(context, REACT_PAGE_KEY, {
+            ...options,
+            path,
+            method: GET,
+            methods: [],
+            handler: { isClass: true, isComponent: true, layout: options.layout, module: target }
+        });
+    });
+};
+
+/**
+ * Sets the error handler for the React adapter and registers error pages.
+ *
+ * @param errorHandler - The error handler to set for the React adapter.
+ * @param context - The blueprint context containing modules and blueprint.
+ * @returns The updated blueprint context with the error handler and error pages set.
+ */
+function setUseReactAdapterErrorHandler(errorHandler, context) {
+    context
+        .blueprint
+        .set('stone.adapter.errorHandlers.default', { module: errorHandler, isClass: true });
+    context
+        .modules
+        .filter(module => hasMetadata(module, REACT_ADAPTER_ERROR_PAGE_KEY))
+        .forEach(module => {
+        const { error, layout, adapterAlias, platform } = getMetadata(module, REACT_ADAPTER_ERROR_PAGE_KEY, { error: 'default' });
+        if (isMatchedAdapter(context.blueprint, platform, adapterAlias)) {
+            Array(error).flat().forEach(name => {
+                context
+                    .blueprint
+                    .set(`stone.useReact.adapterErrorPages.${name}`, { isClass: true, layout, module });
+            });
+        }
     });
-};
+    // Process both eager and lazy loaded error pages
+    Object
+        .keys(context.blueprint.get('stone.useReact.adapterErrorPages', {}))
+        .forEach((name) => {
+        context
+            .blueprint
+            .set(`stone.adapter.errorHandlers.${name}`, { module: errorHandler, isClass: true });
+    });
+    return context;
+}
 
 /**
  * Blueprint middleware to dynamically set lifecycle hooks for react.
@@ -1417,38 +1291,164 @@ async function SetUseReactEventHandlerMiddleware(context, next) {
 }
 
 /**
- * Sets the error handler for the React adapter and registers error pages.
+ * Default blueprint for a React-based Stone.js application.
  *
- * @param errorHandler - The error handler to set for the React adapter.
- * @param context - The blueprint context containing modules and blueprint.
- * @returns The updated blueprint context with the error handler and error pages set.
+ * - Defines middleware, lifecycle hooks, and the default HTML template path.
  */
-function setUseReactAdapterErrorHandler(errorHandler, context) {
-    context
-        .blueprint
-        .set('stone.adapter.errorHandlers.default', { module: errorHandler, isClass: true });
-    context
-        .modules
-        .filter(module => hasMetadata(module, REACT_ADAPTER_ERROR_PAGE_KEY))
-        .forEach(module => {
-        const { error, layout, adapterAlias, platform } = getMetadata(module, REACT_ADAPTER_ERROR_PAGE_KEY, { error: 'default' });
-        if (isMatchedAdapter(context.blueprint, platform, adapterAlias)) {
-            Array(error).flat().forEach(name => {
-                context
-                    .blueprint
-                    .set(`stone.useReact.adapterErrorPages.${name}`, { isClass: true, layout, module });
-            });
+const internalUseReactBlueprint = {
+    stone: {
+        useReact: {},
+        services: [MetaReactRuntime],
+        providers: [MetaUseReactServiceProvider]
+    }
+};
+
+/**
+ * Utility function to define an adapter error page.
+ *
+ * @param module - The adapter error page module.
+ * @param options - Optional adapter error page options.
+ * @returns The UseReactBlueprint.
+ */
+function defineAdapterErrorPage(module, options) {
+    const error = options?.error ?? 'default';
+    const adapterErrorPages = Object.fromEntries([error].flat().map((err) => [
+        err,
+        {
+            ...options,
+            module,
+            error: err,
+            isFactory: options?.isClass !== true
         }
-    });
-    // Process both eager and lazy loaded error pages
-    Object
-        .keys(context.blueprint.get('stone.useReact.adapterErrorPages', {}))
-        .forEach((name) => {
-        context
-            .blueprint
-            .set(`stone.adapter.errorHandlers.${name}`, { module: errorHandler, isClass: true });
-    });
-    return context;
+    ]));
+    return {
+        stone: {
+            useReact: {
+                adapterErrorPages
+            }
+        }
+    };
+}
+
+/**
+ * Defines a Stone React app using a factory-based or class-based main handler.
+ *
+ * @param moduleOrOptions - A factory function or class constructor for the main page.
+ * @param optionsOrBlueprints - Optional application-level configuration.
+ * @param maybeBlueprints - Additional blueprints to merge.
+ * @returns A fully merged Stone blueprint.
+ */
+function defineStoneReactApp(moduleOrOptions = {}, optionsOrBlueprints, maybeBlueprints) {
+    let module;
+    let options = {};
+    let blueprints = [];
+    // Pattern: defineStoneReactApp(handler, options?, blueprints?)
+    if (isFunctionModule(moduleOrOptions)) {
+        module = moduleOrOptions;
+        if (isObjectLikeModule(optionsOrBlueprints)) {
+            options = optionsOrBlueprints;
+            blueprints = Array.isArray(maybeBlueprints) ? maybeBlueprints : [];
+        }
+    }
+    else if (isObjectLikeModule(moduleOrOptions)) { // Pattern: defineStoneReactApp(options, blueprints?)
+        options = moduleOrOptions;
+        blueprints = Array.isArray(optionsOrBlueprints) ? optionsOrBlueprints : [];
+    }
+    const stonePart = {
+        ...options,
+        useReact: {
+            ...options.useReact
+        }
+    };
+    if (isNotEmpty(module)) {
+        stonePart.useReact.componentEventHandler = {
+            module,
+            isComponent: true,
+            isClass: options.isClass,
+            isFactory: options.isClass !== true
+        };
+    }
+    return mergeBlueprints(stoneBlueprint, internalUseReactBlueprint, ...blueprints, { stone: stonePart });
+}
+
+/**
+ * Utility function to define a page.
+ *
+ * @param module - The EventHandler module.
+ * @param options - Page definition options.
+ * @returns The UseReactBlueprint.
+ */
+function definePage(module, options) {
+    return {
+        stone: {
+            router: {
+                definitions: [
+                    {
+                        ...options,
+                        method: GET,
+                        methods: [],
+                        children: undefined,
+                        handler: {
+                            module,
+                            isComponent: true,
+                            layout: options?.layout,
+                            isClass: options?.isClass,
+                            isFactory: options?.isClass !== true
+                        }
+                    }
+                ]
+            }
+        }
+    };
+}
+/**
+ * Utility function to define a page layout.
+ *
+ * @param module - The layout module.
+ * @param options - Optional page layout definition options.
+ * @returns The UseReactBlueprint.
+ */
+function definePageLayout(module, options) {
+    const name = options?.name ?? 'default';
+    return {
+        stone: {
+            useReact: {
+                layout: {
+                    [name]: {
+                        module,
+                        isClass: options?.isClass,
+                        isFactory: options?.isClass !== true
+                    }
+                }
+            }
+        }
+    };
+}
+/**
+ * Utility function to define an error page.
+ *
+ * @param module - The layout module.
+ * @param options - Optional page layout definition options.
+ * @returns The UseReactBlueprint.
+ */
+function defineErrorPage(module, options) {
+    const error = options?.error ?? 'default';
+    const errorPages = Object.fromEntries([error].flat().map((err) => [
+        err,
+        {
+            ...options,
+            module,
+            error: err,
+            isFactory: options?.isClass !== true
+        }
+    ]));
+    return {
+        stone: {
+            useReact: {
+                errorPages
+            }
+        }
+    };
 }
 
 /**
@@ -1624,6 +1624,47 @@ const StoneClient = ({ children }) => {
     return isClient() ? jsx(Fragment, { children: children }) : jsx(Fragment, {});
 };
 
+/**
+ * Internal link component using Stone.js router.
+ */
+const StoneLink = ({ to, href, noRel, external, children, ariaCurrentValue = 'page', selectedClass = 'selected', ...rest }) => {
+    const isExternal = external === true;
+    const shouldHandleNav = !isExternal && isNotEmpty(to);
+    const router = useContext(StoneContext).container.resolve(Router);
+    const path = useMemo(() => {
+        return isObjectLikeModule(to) ? router.generate(to) : to ?? href ?? '#';
+    }, [to, href, router]);
+    const [currentRoute, setCurrentRoute] = useState(router.getCurrentRoute());
+    const selectedClassName = currentRoute?.path === path ? selectedClass : undefined;
+    const elemClassName = [rest.className, selectedClassName].filter(Boolean).join(' ').trim();
+    const handleClick = (event) => {
+        rest.onClick?.(event);
+        if (event.defaultPrevented || isExternal)
+            return;
+        event.preventDefault();
+        isNotEmpty(to) && router.navigate(to);
+    };
+    if (isEmpty(to) && isEmpty(href)) {
+        Logger.warn('StoneLink: missing "to" or "href"');
+    }
+    useEffect(() => {
+        const routerEventHandler = (event) => {
+            setCurrentRoute(event.get('route'));
+        };
+        router.on(RouteEvent.ROUTED, routerEventHandler);
+        return () => {
+            router.off(RouteEvent.ROUTED, routerEventHandler);
+        };
+    }, [router]);
+    return (
+    // eslint-disable-next-line react/jsx-no-target-blank
+    jsx("a", { ...rest, href: path, className: elemClassName, target: isExternal ? '_blank' : rest.target, "aria-current": isNotEmpty(selectedClassName) ? ariaCurrentValue : undefined, rel: noRel === true
+            ? undefined
+            : isExternal
+                ? 'noopener noreferrer'
+                : rest.rel, onClick: shouldHandleNav ? handleClick : rest.onClick, children: children }));
+};
+
 /**
  * A dynamic rendering component that updates its content based on a global event.
  *
@@ -1636,7 +1677,7 @@ const StoneClient = ({ children }) => {
  * @param options - The options to create the Stone Outlet.
  * @returns The Stone Outlet component.
  */
-const StoneOutlet = ({ children }) => {
+const StoneOutlet = ({ children, ...rest }) => {
     const [currentView, setCurrentView] = useState(children);
     useEffect(() => {
         const eventName = STONE_PAGE_EVENT_OUTLET;
@@ -1648,44 +1689,7 @@ const StoneOutlet = ({ children }) => {
         window.addEventListener(eventName, handleEvent);
         return () => window.removeEventListener(eventName, handleEvent);
     }, []);
-    return jsx("div", { "data-stone-outlet": 'true', children: currentView });
-};
-
-/**
- * Internal link component using Stone.js router.
- */
-const InternalLink = ({ to, href, noRel, children, className, defaultNav, selectedClass = 'selected', ariaCurrentValue = 'page', rel = 'noopener noreferrer' }) => {
-    const router = useContext(StoneContext).container.resolve(Router);
-    const path = isObjectLikeModule(to) ? router.generate(to) : to ?? href;
-    const [currentRoute, setCurrentRoute] = useState(router.getCurrentRoute());
-    const selectedClassName = currentRoute?.path === path ? selectedClass : undefined;
-    const elemClassName = [className, selectedClassName].filter(Boolean).join(' ').trim();
-    const handleClick = (event) => {
-        event.preventDefault();
-        router.navigate(to ?? '');
-    };
-    useEffect(() => {
-        const routerEventHandler = (event) => {
-            setCurrentRoute(event.get('route'));
-        };
-        router.on(RouteEvent.ROUTED, routerEventHandler);
-        return () => {
-            router.off(RouteEvent.ROUTED, routerEventHandler);
-        };
-    }, [router]);
-    return defaultNav === true
-        ? (jsx("a", { href: path, className: elemClassName, "aria-current": ariaCurrentValue, rel: noRel !== undefined ? undefined : rel, children: children }))
-        : (jsx("button", { onClick: handleClick, className: elemClassName, "aria-current": ariaCurrentValue, rel: noRel !== undefined ? undefined : rel, children: children }));
-};
-/**
- * External link component rendering a regular <a> tag.
- */
-const ExternalLink = ({ to, href, noRel, target, children, className, ariaCurrentValue = 'page', rel = 'noopener noreferrer' }) => (jsx("a", { target: target, className: className, "aria-current": ariaCurrentValue, rel: noRel !== undefined ? undefined : rel, href: typeof to === 'string' ? to : href, children: children }));
-/**
- * Main StoneLink component delegating to internal or external versions.
- */
-const StoneLink = (props) => {
-    return props.external === true ? jsx(ExternalLink, { ...props }) : jsx(InternalLink, { ...props });
+    return jsx("div", { ...rest, "data-stone-outlet": 'true', children: currentView });
 };
 
 /**