@forge/react 11.16.2-next.1-experimental-49a346a → 11.16.2-next.1-experimental-ad10820

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @forge/react
 
-## 11.16.2-next.1-experimental-49a346a
+## 11.16.2-next.1-experimental-ad10820
 
 ### Minor Changes
 
@@ -20,7 +20,7 @@
 - Updated dependencies [f7f06c8]
 - Updated dependencies [dba5074]
 - Updated dependencies [fc55c83]
-  - @forge/bridge@5.17.0-next.6-experimental-49a346a
+  - @forge/bridge@5.17.0-next.6-experimental-ad10820
 
 ## 11.16.2-next.1
 

package/out/router/components/Route.d.ts

@@ -1,7 +1,20 @@
 import { ForgeChildren } from '../../types';
 export interface RouteProps {
+    /**
+     * The URL path pattern to match against the current location. Supports static segments, dynamic parameters (e.g. :id), and a catch-all wildcard (*).
+     * @type string
+     */
     path: string;
+    /**
+     * The content to render when the path matches the current location.
+     * @type ForgeElement
+     */
     children: ForgeChildren;
 }
+/**
+ * Route conditionally renders its children when the current URL path matches its path prop. It must be used within a Router component.
+ *
+ * @see [Route](https://developer.atlassian.com/platform/forge/ui-kit/components/router/#route) in UI Kit documentation for more information
+ */
 export declare const Route: ({ path, children }: RouteProps) => import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=Route.d.ts.map

package/out/router/components/Route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Route.d.ts","sourceRoot":"","sources":["../../../src/router/components/Route.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,eAAO,MAAM,KAAK,uBAAwB,UAAU,mDAoBnD,CAAC"}
+{"version":3,"file":"Route.d.ts","sourceRoot":"","sources":["../../../src/router/components/Route.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,uBAAwB,UAAU,mDAoBnD,CAAC"}

package/out/router/components/Route.js

@@ -6,6 +6,11 @@ const react_1 = require("react");
 const RouterContext_1 = require("./RouterContext");
 const ParamsContext_1 = require("./ParamsContext");
 const matchPath_1 = require("../utils/matchPath");
+/**
+ * Route conditionally renders its children when the current URL path matches its path prop. It must be used within a Router component.
+ *
+ * @see [Route](https://developer.atlassian.com/platform/forge/ui-kit/components/router/#route) in UI Kit documentation for more information
+ */
 const Route = ({ path, children }) => {
     const context = (0, react_1.useContext)(RouterContext_1.RouterContext);
     if (!context) {

package/out/router/components/Router.d.ts

@@ -1,7 +1,19 @@
 import { ForgeChildren, ForgeNode } from '../../types';
 export interface RouterProps {
+    /**
+     * @type Route
+     * The child elements to render within the router. Typically contains one or more Route components.
+     */
     children: ForgeChildren;
-    fallback?: ForgeNode;
+    /**
+     * A fallback value to render when no Route child has a path matching the current path.
+     */
+    fallback?: ForgeNode | null;
 }
+/**
+ * Router provides client-side routing by allowing content to be rendered based on the current URL path.
+ *
+ * @see [Router](https://developer.atlassian.com/platform/forge/ui-kit/components/router/) in UI Kit documentation for more information
+ */
 export declare const Router: ({ children, fallback }: RouterProps) => import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=Router.d.ts.map

package/out/router/components/Router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../../src/router/components/Router.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,eAAO,MAAM,MAAM,2BAAmC,WAAW,4CA0ChE,CAAC"}
+{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../../src/router/components/Router.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAevD,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAC7B;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,2BAAmC,WAAW,4CAiEhE,CAAC"}

package/out/router/components/Router.js

@@ -5,6 +5,18 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const bridge_1 = require("@forge/bridge");
 const RouterContext_1 = require("./RouterContext");
+const components_1 = require("../../components");
+const Fallback = ({ hasMatchedRouteRef, fallback }) => {
+    if (hasMatchedRouteRef.current) {
+        return null;
+    }
+    return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: fallback });
+};
+/**
+ * Router provides client-side routing by allowing content to be rendered based on the current URL path.
+ *
+ * @see [Router](https://developer.atlassian.com/platform/forge/ui-kit/components/router/) in UI Kit documentation for more information
+ */
 const Router = ({ children, fallback = null }) => {
     const [history, setHistory] = (0, react_1.useState)(null);
     const [location, setLocation] = (0, react_1.useState)(null);
@@ -35,9 +47,12 @@ const Router = ({ children, fallback = null }) => {
         }
         return { history, location, hasMatchedRouteRef };
     }, [history, location]);
-    if (error || !routerContext) {
-        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: fallback });
+    if (error) {
+        return ((0, jsx_runtime_1.jsx)(components_1.SectionMessage, { appearance: "error", children: (0, jsx_runtime_1.jsx)(components_1.Text, { children: error.message }) }));
+    }
+    if (!routerContext) {
+        return ((0, jsx_runtime_1.jsx)(components_1.SectionMessage, { appearance: "error", children: (0, jsx_runtime_1.jsxs)(components_1.Text, { children: ["History is not defined. Check the list of", ' ', (0, jsx_runtime_1.jsx)(components_1.Link, { href: "https://developer.atlassian.com/platform/forge/ui-kit/components/router/#supported-modules", children: "supported modules" }), ' ', "for Router"] }) }));
     }
-    return (0, jsx_runtime_1.jsx)(RouterContext_1.RouterContext.Provider, { value: routerContext, children: children });
+    return ((0, jsx_runtime_1.jsxs)(RouterContext_1.RouterContext.Provider, { value: routerContext, children: [children, (0, jsx_runtime_1.jsx)(Fallback, { hasMatchedRouteRef: hasMatchedRouteRef, fallback: fallback })] }));
 };
 exports.Router = Router;

package/out/router/components/__test__/Router.test.js

@@ -59,6 +59,13 @@ describe('Router', () => {
         expect(forgeDoc).toHaveProperty('children[0].children[0].props.text', 'First');
         expect(forgeDoc?.children).toHaveLength(1);
     });
+    it('renders fallback when no Route matches', async () => {
+        mockCreateHistory.mockImplementation(async () => (0, test_utils_1.createMockHistory)('/unknown'));
+        await reconcilerTestRenderer_1.default.create((0, jsx_runtime_1.jsxs)(Router_1.Router, { fallback: (0, jsx_runtime_1.jsx)(__1.Text, { children: "No match" }), children: [(0, jsx_runtime_1.jsx)(Route_1.Route, { path: "/", children: (0, jsx_runtime_1.jsx)(__1.Text, { children: "Home" }) }), (0, jsx_runtime_1.jsx)(Route_1.Route, { path: "/settings", children: (0, jsx_runtime_1.jsx)(__1.Text, { children: "Settings" }) })] }));
+        const forgeDoc = (0, testUtils_1.getLastBridgeCallForgeDoc)(bridgeCalls);
+        expect(forgeDoc).toHaveProperty('children[0].type', 'Text');
+        expect(forgeDoc).toHaveProperty('children[0].children[0].props.text', 'No match');
+    });
     it('renders the catchall Route when no other route matches', async () => {
         mockCreateHistory.mockImplementation(async () => (0, test_utils_1.createMockHistory)('/unknown'));
         await reconcilerTestRenderer_1.default.create((0, jsx_runtime_1.jsxs)(Router_1.Router, { children: [(0, jsx_runtime_1.jsx)(Route_1.Route, { path: "/", children: (0, jsx_runtime_1.jsx)(__1.Text, { children: "Home" }) }), (0, jsx_runtime_1.jsx)(Route_1.Route, { path: "*", children: (0, jsx_runtime_1.jsx)(__1.Text, { children: "Not Found" }) })] }));

package/out/router/hooks/useLocation.d.ts

@@ -1,3 +1,9 @@
 import type { Location } from 'history';
+/**
+ * This hook returns the current location object, which contains information about the current URL. It updates automatically when the user navigates to a different route.
+ * It must be used within a Router component.
+ *
+ * @see [useLocation](https://developer.atlassian.com/platform/forge/ui-kit/hooks/use-location/) in UI Kit documentation for more information
+ */
 export declare const useLocation: () => Location;
 //# sourceMappingURL=useLocation.d.ts.map

package/out/router/hooks/useLocation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLocation.d.ts","sourceRoot":"","sources":["../../../src/router/hooks/useLocation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,eAAO,MAAM,WAAW,QAAO,QAQ9B,CAAC"}
+{"version":3,"file":"useLocation.d.ts","sourceRoot":"","sources":["../../../src/router/hooks/useLocation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAO,QAQ9B,CAAC"}

package/out/router/hooks/useLocation.js

@@ -3,6 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useLocation = void 0;
 const react_1 = require("react");
 const RouterContext_1 = require("../components/RouterContext");
+/**
+ * This hook returns the current location object, which contains information about the current URL. It updates automatically when the user navigates to a different route.
+ * It must be used within a Router component.
+ *
+ * @see [useLocation](https://developer.atlassian.com/platform/forge/ui-kit/hooks/use-location/) in UI Kit documentation for more information
+ */
 const useLocation = () => {
     const context = (0, react_1.useContext)(RouterContext_1.RouterContext);
     if (!context) {

package/out/router/hooks/useNavigate.d.ts

@@ -1,6 +1,11 @@
 interface NavigateOptions {
     replace?: boolean;
 }
+/**
+ * This hook returns a function that lets you programmatically navigate to different routes in your app. It must be used within a Router component.
+ *
+ * @see [useNavigate](https://developer.atlassian.com/platform/forge/ui-kit/hooks/use-navigate/) in UI Kit documentation for more information
+ */
 export declare const useNavigate: () => (to: string | number, options?: NavigateOptions) => void;
 export {};
 //# sourceMappingURL=useNavigate.d.ts.map

package/out/router/hooks/useNavigate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useNavigate.d.ts","sourceRoot":"","sources":["../../../src/router/hooks/useNavigate.ts"],"names":[],"mappings":"AAGA,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAwBD,eAAO,MAAM,WAAW,aAUf,MAAM,GAAG,MAAM,YAAY,eAAe,SAkBlD,CAAC"}
+{"version":3,"file":"useNavigate.d.ts","sourceRoot":"","sources":["../../../src/router/hooks/useNavigate.ts"],"names":[],"mappings":"AAGA,UAAU,eAAe;IAIvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAwBD;;;;GAIG;AACH,eAAO,MAAM,WAAW,aAUf,MAAM,GAAG,MAAM,YAAY,eAAe,SAkBlD,CAAC"}

package/out/router/hooks/useNavigate.js

@@ -21,6 +21,11 @@ const resolvePath = (currentPathname, to) => {
     }
     return '/' + resolved.join('/');
 };
+/**
+ * This hook returns a function that lets you programmatically navigate to different routes in your app. It must be used within a Router component.
+ *
+ * @see [useNavigate](https://developer.atlassian.com/platform/forge/ui-kit/hooks/use-navigate/) in UI Kit documentation for more information
+ */
 const useNavigate = () => {
     const context = (0, react_1.useContext)(RouterContext_1.RouterContext);
     if (!context) {

package/out/router/hooks/useParams.d.ts

@@ -1,2 +1,8 @@
+/**
+ * This hook returns an object containing the dynamic parameters extracted from the current URL, as defined by the matching Route component's path prop.
+ * It must be used within a Route component.
+ *
+ * @see [useParams](https://developer.atlassian.com/platform/forge/ui-kit/hooks/use-params/) in UI Kit documentation for more information
+ */
 export declare const useParams: () => Record<string, string>;
 //# sourceMappingURL=useParams.d.ts.map

package/out/router/hooks/useParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useParams.d.ts","sourceRoot":"","sources":["../../../src/router/hooks/useParams.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,SAAS,QAAO,OAAO,MAAM,EAAE,MAAM,CAMjD,CAAC"}
+{"version":3,"file":"useParams.d.ts","sourceRoot":"","sources":["../../../src/router/hooks/useParams.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,eAAO,MAAM,SAAS,QAAO,OAAO,MAAM,EAAE,MAAM,CAMjD,CAAC"}

package/out/router/hooks/useParams.js

@@ -3,6 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useParams = void 0;
 const react_1 = require("react");
 const ParamsContext_1 = require("../components/ParamsContext");
+/**
+ * This hook returns an object containing the dynamic parameters extracted from the current URL, as defined by the matching Route component's path prop.
+ * It must be used within a Route component.
+ *
+ * @see [useParams](https://developer.atlassian.com/platform/forge/ui-kit/hooks/use-params/) in UI Kit documentation for more information
+ */
 const useParams = () => {
     const context = (0, react_1.useContext)(ParamsContext_1.ParamsContext);
     if (context === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forge/react",
-  "version": "11.16.2-next.1-experimental-49a346a",
+  "version": "11.16.2-next.1-experimental-ad10820",
   "description": "Forge React reconciler",
   "author": "Atlassian",
   "license": "SEE LICENSE IN LICENSE.txt",
@@ -36,7 +36,7 @@
     "@atlaskit/adf-schema": "^48.0.0",
     "@atlaskit/adf-utils": "^19.19.0",
     "@atlaskit/forge-react-types": "^1.3.0",
-    "@forge/bridge": "^5.17.0-next.6-experimental-49a346a",
+    "@forge/bridge": "^5.17.0-next.6-experimental-ad10820",
     "@forge/egress": "^2.3.2",
     "@forge/i18n": "0.0.7",
     "@types/react": "^18.2.64",