@stone-js/use-react 0.2.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Stone.js
+Copyright © 2026 Stone Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/l/@stone-js/use-react)](https://opensource.org/licenses/MIT)
 [![npm](https://img.shields.io/npm/v/@stone-js/use-react)](https://www.npmjs.com/package/@stone-js/use-react)
 [![npm](https://img.shields.io/npm/dm/@stone-js/use-react)](https://www.npmjs.com/package/@stone-js/use-react)
-![Maintenance](https://img.shields.io/maintenance/yes/2025)
+![Maintenance](https://img.shields.io/maintenance/yes/2026)
 [![Build Status](https://github.com/stone-foundation/stone-js-use-react/actions/workflows/main.yml/badge.svg)](https://github.com/stone-foundation/stone-js-use-react/actions/workflows/main.yml)
 [![Publish Package to npmjs](https://github.com/stone-foundation/stone-js-use-react/actions/workflows/release.yml/badge.svg)](https://github.com/stone-foundation/stone-js-use-react/actions/workflows/release.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-use-react&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-use-react)

package/dist/browser.js

@@ -1,17 +1,11 @@
-import { createContext, StrictMode, useContext, useState, useEffect } from 'react';
-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, mergeBlueprints, stoneBlueprint, Logger, classDecoratorLegacyWrapper, setMetadata, methodDecoratorLegacyWrapper, addMetadata, LIFECYCLE_HOOK_KEY, hasMetadata, getMetadata, isMatchedAdapter, addBlueprint } from '@stone-js/core';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { renderToString } from 'react-dom/server';
-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, NAVIGATION_EVENT, Router, RouteEvent } from '@stone-js/router';
-import { OutgoingBrowserResponse, RedirectBrowserResponse } from '@stone-js/browser-core';
-
-/**
- * Stone context.
- * Usefull to pass data to the components.
- */
-const StoneContext = createContext({});
+import { RedirectBrowserResponse, OutgoingBrowserResponse } from '@stone-js/browser-core';
 
 /**
   * Stone DOM Attribute.
@@ -246,6 +240,12 @@ const STONE_SNAPSHOT = '__STONE_SNAPSHOT__';
  */
 const STONE_PAGE_EVENT_OUTLET = 'stone:inject:react-page:outlet';
 
+/**
+ * Stone context.
+ * Usefull to pass data to the components.
+ */
+const StoneContext = createContext({});
+
 /**
  * Provides a scoped `StoneContext` for its children within a strict mode.
  *
@@ -912,33 +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.
  *
@@ -993,6 +966,33 @@ function defineStoneReactApp(moduleOrOptions = {}, optionsOrBlueprints, maybeBlu
     return mergeBlueprints(stoneBlueprint, internalUseReactBlueprint, ...blueprints, { stone: stonePart });
 }
 
+/**
+ * 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
+            }
+        }
+    };
+}
+
 /**
  * Utility function to define a page.
  *
@@ -1073,6 +1073,73 @@ function defineErrorPage(module, options) {
     };
 }
 
+/**
+ * Class representing an UseReactBrowserErrorHandler.
+ *
+ * Adapter level error handler for React applications.
+ */
+class UseReactBrowserErrorHandler {
+    logger;
+    blueprint;
+    /**
+     * Create an UseReactBrowserErrorHandler.
+     *
+     * @param options - UseReactBrowserErrorHandler options.
+     */
+    constructor({ blueprint }) {
+        this.blueprint = blueprint;
+        this.logger = Logger.getInstance();
+    }
+    /**
+     * Handle an error.
+     *
+     * @param error - The error to handle.
+     * @param context - The context of the adapter.
+     * @returns The raw response.
+     */
+    async handle(error, context) {
+        this.logger.error(error.message, { error });
+        return context
+            .rawResponseBuilder
+            .add('render', async () => await this.renderError(error, context));
+    }
+    /**
+     * Get the error body.
+     *
+     * @param error - The error to handle.
+     * @returns The error body.
+     */
+    async renderError(error, context) {
+        const app = await buildAdapterErrorComponent(this.blueprint, context, error.statusCode ?? 500, error);
+        // Render the component
+        renderReactApp(app, this.blueprint);
+    }
+}
+
+/**
+ * Create an UseReact response.
+ *
+ * @param options - The options for creating the response.
+ * @returns The React response.
+ */
+const reactResponse = (options) => {
+    if (isNotEmpty(options) &&
+        (isNotEmpty(options.url) ||
+            (isNotEmpty(options.content) && isNotEmpty(options.content.redirect)))) {
+        return reactRedirectResponse(options);
+    }
+    return OutgoingBrowserResponse.create(options);
+};
+/**
+ * Create an UseReact redirect response.
+ *
+ * @param options - The options for creating the response.
+ * @returns The React redirect response.
+ */
+const reactRedirectResponse = (options) => {
+    return RedirectBrowserResponse.create({ statusCode: 302, ...options });
+};
+
 /**
  * Constants are defined here to prevent Circular dependency between modules
  * This pattern must be applied to all Stone libraries or third party libraries.
@@ -1285,65 +1352,6 @@ const Snapshot = (name) => {
     });
 };
 
-/**
- * Create an UseReact response.
- *
- * @param options - The options for creating the response.
- * @returns The React response.
- */
-const reactResponse = (options) => {
-    if (isNotEmpty(options) &&
-        (isNotEmpty(options.url) ||
-            (isNotEmpty(options.content) && isNotEmpty(options.content.redirect)))) {
-        return reactRedirectResponse(options);
-    }
-    return OutgoingBrowserResponse.create(options);
-};
-/**
- * Create an UseReact redirect response.
- *
- * @param options - The options for creating the response.
- * @returns The React redirect response.
- */
-const reactRedirectResponse = (options) => {
-    return RedirectBrowserResponse.create({ statusCode: 302, ...options });
-};
-
-/**
- * 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.
  *
@@ -1476,46 +1484,38 @@ async function SetUseReactEventHandlerMiddleware(context, next) {
 }
 
 /**
- * Class representing an UseReactBrowserErrorHandler.
+ * Sets the error handler for the React adapter and registers error pages.
  *
- * Adapter level error handler for React applications.
+ * @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.
  */
-class UseReactBrowserErrorHandler {
-    logger;
-    blueprint;
-    /**
-     * Create an UseReactBrowserErrorHandler.
-     *
-     * @param options - UseReactBrowserErrorHandler options.
-     */
-    constructor({ blueprint }) {
-        this.blueprint = blueprint;
-        this.logger = Logger.getInstance();
-    }
-    /**
-     * Handle an error.
-     *
-     * @param error - The error to handle.
-     * @param context - The context of the adapter.
-     * @returns The raw response.
-     */
-    async handle(error, context) {
-        this.logger.error(error.message, { error });
-        return context
-            .rawResponseBuilder
-            .add('render', async () => await this.renderError(error, context));
-    }
-    /**
-     * Get the error body.
-     *
-     * @param error - The error to handle.
-     * @returns The error body.
-     */
-    async renderError(error, context) {
-        const app = await buildAdapterErrorComponent(this.blueprint, context, error.statusCode ?? 500, error);
-        // Render the component
-        renderReactApp(app, this.blueprint);
-    }
+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;
 }
 
 /**
@@ -1715,16 +1715,26 @@ const StoneClient = ({ children }) => {
 /**
  * Internal link component using Stone.js router.
  */
-const InternalLink = ({ to, href, noRel, children, className, defaultNav, selectedClass = 'selected', ariaCurrentValue = 'page', rel = 'noopener noreferrer' }) => {
+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 = isObjectLikeModule(to) ? router.generate(to) : to ?? href;
+    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 = [className, selectedClassName].filter(Boolean).join(' ').trim();
+    const elemClassName = [rest.className, selectedClassName].filter(Boolean).join(' ').trim();
     const handleClick = (event) => {
+        rest.onClick?.(event);
+        if (event.defaultPrevented || isExternal)
+            return;
         event.preventDefault();
-        router.navigate(to ?? '');
+        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'));
@@ -1734,19 +1744,13 @@ const InternalLink = ({ to, href, noRel, children, className, defaultNav, select
             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 (
+    // 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 }));
 };
 
 /**
@@ -1761,7 +1765,7 @@ const StoneLink = (props) => {
  * @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;
@@ -1773,7 +1777,7 @@ const StoneOutlet = ({ children }) => {
         window.addEventListener(eventName, handleEvent);
         return () => window.removeEventListener(eventName, handleEvent);
     }, []);
-    return jsx("div", { "data-stone-outlet": 'true', children: currentView });
+    return jsx("div", { ...rest, "data-stone-outlet": 'true', children: currentView });
 };
 
 /**