@hubspot/ui-extensions 0.12.3 → 0.13.0

package/dist/internal/hook-utils.js

@@ -1,5 +1,5 @@
-import { createContext, useContext } from 'react';
-const MocksContext = createContext(null);
+import { createContext, useContext, useRef } from 'react';
+const ReactRenderMocksContext = createContext(null);
 /**
  * Creates a mock-aware hook function that can be used to mock the original hook function.
  * The mock-aware hook function will return the mocked hook function if a mock is found, otherwise it will return the original hook function.
@@ -10,29 +10,28 @@ const MocksContext = createContext(null);
  */
 export const createMockAwareHook = (hookName, originalHookFunction) => {
     const useWrapper = (...args) => {
-        const mocks = useMocksContext();
-        if (!mocks) {
+        const mocksContext = useMocksContext();
+        if (!mocksContext) {
             // If no mocks are provided, call the original hook function
             return originalHookFunction(...args);
         }
-        // When a mock is provided by the testing utilities (via <MocksContextProvider>), return the mocked hook function
+        const { mocks } = mocksContext;
         const mockHook = mocks[hookName];
         if (!mockHook) {
             throw new Error(`Illegal State: Mock for hook ${hookName} not found.`);
         }
-        // Call the mocked hook function with the same arguments as the original hook function and return the result
         return mockHook(...args);
     };
     return useWrapper;
 };
 /**
  * A hook that provides access to the Mocks context.
- * Returns the mocks object if inside a MocksContextProvider, otherwise returns null.
+ * Returns the mocks context value if inside a MocksContextProvider, otherwise returns null.
  *
- * @returns The mocks object or null if not in a test environment.
+ * @returns The mocks context value or null if not in a test environment.
  */
 export function useMocksContext() {
-    return useContext(MocksContext);
+    return useContext(ReactRenderMocksContext);
 }
 /**
  * A React component that provides the Mocks context that can be used to provide mocks to the mock-aware hook functions.
@@ -40,4 +39,19 @@ export function useMocksContext() {
  * @param children The children to render.
  * @returns The children wrapped in the Mocks context provider.
  */
-export const MocksContextProvider = MocksContext.Provider;
+export const MocksContextProvider = ReactRenderMocksContext.Provider;
+/**
+ * Stabilizes a value's reference identity across re-renders using deep
+ * comparison via JSON.stringify.
+ */
+export function useStableValue(value) {
+    const stableRef = useRef({
+        key: JSON.stringify(value),
+        value,
+    });
+    const key = JSON.stringify(value);
+    if (key !== stableRef.current.key) {
+        stableRef.current = { key, value };
+    }
+    return stableRef.current.value;
+}

package/dist/pages/components/index.d.ts

@@ -0,0 +1 @@
+export * from './page-routes.ts';

package/dist/pages/components/index.js

@@ -0,0 +1 @@
+export * from "./page-routes.js";

package/dist/{shared/types/pages → pages}/components/page-routes.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType, ReactNode } from 'react';
-import type { EmptyProps } from '../../shared.ts';
+import type { EmptyProps } from '../../shared/types/shared.ts';
 /**
  * The props type for the layout component of [PageRoutes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes).
  */
@@ -72,44 +72,11 @@ export interface PageRoutesProps {
  *
  * See [PageRoutes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes) for more information.
  *
- * @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
  */
-export interface PageRoutesComponent {
-    (props: PageRoutesProps): null;
-    /**
-     * Used as a descriptor for an index (i.e., "/") route.
-     *
-     * Example usage:
-     *
-     * ```tsx
-     * <PageRoutes.IndexRoute component={HomePage} />
-     * ```
-     *
-     * @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
-     */
-    IndexRoute: (props: IndexRouteProps) => null;
-    /**
-     * Used as a descriptor for a route with a path pattern.
-     *
-     * Example usage:
-     *
-     * ```tsx
-     * <PageRoutes.Route path="/docs" component={DocsPage} />
-     * ```
-     * @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
-     */
-    Route: (props: RouteProps) => null;
-    /**
-     * Used as a descriptor for a route that matches any path.
-     *
-     * Example usage:
-     *
-     * ```tsx
-     * <PageRoutes.AnyRoute component={NotFoundPage} />
-     * ```
-     *
-     * @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
-     */
-    AnyRoute: (props: AnyRouteProps) => null;
+export declare function PageRoutes(__props: PageRoutesProps): null;
+export declare namespace PageRoutes {
+    var IndexRoute: (__props: IndexRouteProps) => null;
+    var Route: (__props: RouteProps) => null;
+    var AnyRoute: (__props: AnyRouteProps) => null;
 }
 export {};

package/dist/pages/components/page-routes.js

@@ -0,0 +1,62 @@
+class PageRoutesRenderError extends Error {
+    constructor(componentName) {
+        super(`<${componentName}> should not be rendered directly. Use createPageRouter instead.`);
+    }
+}
+/**
+ * Used as a descriptor for a collection of page routes.
+ *
+ * Example usage:
+ *
+ * ```tsx
+ * const PageRouter = createPageRouter(<PageRoutes>
+ *   <PageRoutes.IndexRoute component={HomePage} />
+ *   <PageRoutes.Route path="/docs" component={DocsPage} />
+ *   <PageRoutes.AnyRoute component={NotFoundPage} />
+ * </PageRoutes>);
+ * ```
+ *
+ * See [PageRoutes](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/ui-components/app-page-components/page-routes#pageroutes) for more information.
+ *
+ */
+export function PageRoutes(__props) {
+    throw new PageRoutesRenderError('PageRoutes');
+}
+/**
+ * Used as a descriptor for an index (i.e., "/") route.
+ *
+ * Example usage:
+ *
+ * ```tsx
+ * <PageRoutes.IndexRoute component={HomePage} />
+ * ```
+ *
+ */
+PageRoutes.IndexRoute = function IndexRoute(__props) {
+    throw new PageRoutesRenderError('PageRoutes.IndexRoute');
+};
+/**
+ * Used as a descriptor for a route with a path pattern.
+ *
+ * Example usage:
+ *
+ * ```tsx
+ * <PageRoutes.Route path="/docs" component={DocsPage} />
+ * ```
+ */
+PageRoutes.Route = function Route(__props) {
+    throw new PageRoutesRenderError('PageRoutes.Route');
+};
+/**
+ * Used as a descriptor for a route that matches any path.
+ *
+ * Example usage:
+ *
+ * ```tsx
+ * <PageRoutes.AnyRoute component={NotFoundPage} />
+ * ```
+ *
+ */
+PageRoutes.AnyRoute = function AnyRoute(__props) {
+    throw new PageRoutesRenderError('PageRoutes.AnyRoute');
+};

package/dist/pages/create-page-router.d.ts

@@ -0,0 +1,33 @@
+import { type ReactElement } from 'react';
+import type { ReactFragmentProps } from '../shared/types/index.ts';
+import type { PageRoutesProps } from './components/page-routes.ts';
+import type { PageRouterComponent } from './types.ts';
+/**
+ * The function type for [createPageRouter](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/app-pages/reference#createpagerouter).
+ *
+ * Example usage:
+ *
+ * ```tsx
+ * const PageRouter = createPageRouter(
+ *   <PageRoutes layoutComponent={AppLayout}>
+ *     <PageRoutes.IndexRoute component={HomePage} id="home" />
+ *     <PageRoutes.Route path="/docs" component={DocsPage} />
+ *     <PageRoutes path="/customers" layoutComponent={CustomersLayout}>
+ *       <PageRoutes.IndexRoute component={ListCustomersPage} />
+ *       <PageRoutes.Route path="/:customerId" component={ViewCustomerPage} />
+ *     </PageRoutes>
+ *     <PageRoutes.AnyRoute component={NotFoundPage} />
+ *   </PageRoutes>
+ * );
+ *
+ * function AppPages() {
+ *   return <PageRouter />;
+ * }
+ *
+ * hubspot.extend<"pages">(() => <AppPages />);
+ * ```
+ *
+ * @param routes The routes to render.
+ * @returns The page router component.
+ */
+export declare const createPageRouter: (reactPageRoutesElement: ReactElement<PageRoutesProps> | ReactElement<ReactFragmentProps>) => PageRouterComponent;

package/dist/pages/create-page-router.js

@@ -0,0 +1,121 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { EmptyState, Text } from "../shared/remoteComponents.js";
+import { AppPageRouteProvider } from "./internal/app-page-route-context.js";
+import { convertReactPageRoutesElement } from "./internal/convert-page-routes-react-elements.js";
+import { RouteNodeType, } from "./internal/page-router-internal-types.js";
+import { createTrieRouter } from "./internal/trie-router.js";
+import { useAppPageLocation } from "./internal/useAppPageLocation.js";
+/**
+ * Adds the routes to the trie router.
+ *
+ * @param trieRouter - The trie router to add the routes to.
+ * @param seenRouteIds - The set of route ids that have already been seen.
+ * @param routeNode - The node to add the routes to.
+ * @param parentPath - The path to the parent node.
+ * @param parentLayouts - The layouts to apply to the node.
+ */
+const addRoutes = (trieRouter, seenRouteIds, routeNode, parentPath, parentLayouts) => {
+    if (routeNode.type === RouteNodeType.Routes) {
+        const prefix = parentPath + (routeNode.path ?? '');
+        const layouts = routeNode.layoutComponent
+            ? [...parentLayouts, routeNode.layoutComponent]
+            : parentLayouts;
+        if (routeNode.children) {
+            for (const childRouteNode of routeNode.children) {
+                addRoutes(trieRouter, seenRouteIds, childRouteNode /* routeNode */, prefix /* parentPath */, layouts /* parentLayouts */);
+            }
+        }
+    }
+    else {
+        const fullPath = parentPath + routeNode.path;
+        if (routeNode.id !== undefined) {
+            if (seenRouteIds.has(routeNode.id)) {
+                throw new Error(`Duplicate route id: "${routeNode.id}"`);
+            }
+            seenRouteIds.add(routeNode.id);
+        }
+        trieRouter.addRoute(fullPath, {
+            component: routeNode.component,
+            layouts: parentLayouts,
+            id: routeNode.id,
+        });
+    }
+};
+/**
+ * The function type for [createPageRouter](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensibility/app-pages/reference#createpagerouter).
+ *
+ * Example usage:
+ *
+ * ```tsx
+ * const PageRouter = createPageRouter(
+ *   <PageRoutes layoutComponent={AppLayout}>
+ *     <PageRoutes.IndexRoute component={HomePage} id="home" />
+ *     <PageRoutes.Route path="/docs" component={DocsPage} />
+ *     <PageRoutes path="/customers" layoutComponent={CustomersLayout}>
+ *       <PageRoutes.IndexRoute component={ListCustomersPage} />
+ *       <PageRoutes.Route path="/:customerId" component={ViewCustomerPage} />
+ *     </PageRoutes>
+ *     <PageRoutes.AnyRoute component={NotFoundPage} />
+ *   </PageRoutes>
+ * );
+ *
+ * function AppPages() {
+ *   return <PageRouter />;
+ * }
+ *
+ * hubspot.extend<"pages">(() => <AppPages />);
+ * ```
+ *
+ * @param routes The routes to render.
+ * @returns The page router component.
+ */
+export const createPageRouter = (reactPageRoutesElement) => {
+    // Convert the React element to a route node and add them to a trie router.
+    const rootRouteNode = convertReactPageRoutesElement(reactPageRoutesElement);
+    const trieRouter = createTrieRouter();
+    const seenRouteIds = new Set();
+    addRoutes(trieRouter, seenRouteIds, rootRouteNode /* routeNode */, '' /* parentPath */, [] /* parentLayouts */);
+    // Now create the PageRouter component that uses the trie router to match the current app page location.
+    // The component will render the content of the matched route.
+    // The component will also provide the matched app page route to the content of the matched route.
+    const PageRouter = () => {
+        const appPageLocation = useAppPageLocation();
+        const { path: appPagePath, params: appPageParams } = appPageLocation;
+        const matchedRoute = useMemo(() => {
+            return trieRouter.matchPath(appPagePath);
+        }, [appPagePath]);
+        const matchedAppPageRoute = useMemo(() => {
+            return matchedRoute
+                ? {
+                    routeId: matchedRoute.data.id,
+                    path: appPagePath,
+                    params: {
+                        ...matchedRoute.params,
+                        ...appPageParams,
+                    },
+                }
+                : {
+                    path: appPagePath,
+                    params: appPageParams,
+                };
+        }, [matchedRoute, appPagePath, appPageParams]);
+        const routeData = matchedRoute?.data;
+        const content = useMemo(() => {
+            if (!routeData) {
+                // TODO: Localize the title and body text.
+                return (_jsx(EmptyState, { title: "Page not found", layout: "vertical", reverseOrder: true, children: _jsx(Text, { children: "This app page does not exist." }) }));
+            }
+            const Component = routeData.component;
+            let node = _jsx(Component, {});
+            // Wrap the route component with any ancestor layout components found in the route tree.
+            for (let i = routeData.layouts.length - 1; i >= 0; i--) {
+                const Layout = routeData.layouts[i];
+                node = _jsx(Layout, { children: node });
+            }
+            return node;
+        }, [routeData]);
+        return (_jsx(AppPageRouteProvider, { pageRoute: matchedAppPageRoute, children: content }));
+    };
+    return PageRouter;
+};

package/dist/pages/create-page-router.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pages/create-page-router.test.js

@@ -0,0 +1,296 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { describe, expect, it } from 'vitest';
+import { Box, Text } from "../index.js";
+import { createRenderer } from "../testing/index.js";
+import { PageRoutes } from "./components/page-routes.js";
+import { createPageRouter } from "./create-page-router.js";
+import { usePageRoute } from "./hooks.js";
+const HomePage = () => _jsx(Text, { testId: "page", children: "home" });
+const DocsPage = () => _jsx(Text, { testId: "page", children: "docs" });
+const SupportIndexPage = () => _jsx(Text, { testId: "page", children: "support-index" });
+const ContactUsPage = () => _jsx(Text, { testId: "page", children: "contact-us" });
+const FAQPage = () => _jsx(Text, { testId: "page", children: "faq" });
+const NotFoundPage = () => _jsx(Text, { testId: "page", children: "not-found-custom" });
+const RouteInfoDisplay = () => {
+    const { routeId, path, params } = usePageRoute();
+    return (_jsxs(_Fragment, { children: [_jsx(Text, { testId: "route-id", children: routeId ?? '' }), _jsx(Text, { testId: "route-path", children: path }), _jsx(Text, { testId: "route-params", children: JSON.stringify(params) })] }));
+};
+const ContactDetailsPage = () => (_jsxs(_Fragment, { children: [_jsx(Text, { testId: "page", children: "contact-details" }), _jsx(RouteInfoDisplay, {})] }));
+describe('createPageRouter', () => {
+    describe('basic routing', () => {
+        it('renders the index route at the default location', () => {
+            const { render, findByTestId } = createRenderer('home');
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(PageRoutes.Route, { path: "/docs", component: DocsPage })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('home');
+        });
+        it('renders a named route when path matches', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({ path: '/docs', params: {} });
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(PageRoutes.Route, { path: "/docs", component: DocsPage })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('docs');
+        });
+        it('shows "Page not found" when no route matches', () => {
+            const { mocks, render, find } = createRenderer('home');
+            mocks.setPageLocation({ path: '/unknown', params: {} });
+            const PageRouter = createPageRouter(_jsx(PageRoutes, { children: _jsx(PageRoutes.IndexRoute, { component: HomePage }) }));
+            render(_jsx(PageRouter, {}));
+            expect(find(Text, (node) => node.text === 'This app page does not exist.')).toBeTruthy();
+        });
+    });
+    describe('route exclusivity', () => {
+        it('renders only the index route and not other routes at the default location', () => {
+            const { render, findAll, findByTestId, maybeFind } = createRenderer('home');
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(PageRoutes.Route, { path: "/docs", component: DocsPage }), _jsx(PageRoutes.Route, { path: "/support", component: SupportIndexPage })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findAll(Text, { testId: 'page' })).toHaveLength(1);
+            expect(findByTestId(Text, 'page').text).toEqual('home');
+            expect(maybeFind(Text, (node) => node.text === 'docs')).toBeNull();
+            expect(maybeFind(Text, (node) => node.text === 'support-index')).toBeNull();
+        });
+        it('renders only the matched named route and not the index or other routes', () => {
+            const { mocks, render, findAll, findByTestId, maybeFind } = createRenderer('home');
+            mocks.setPageLocation({ path: '/docs', params: {} });
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(PageRoutes.Route, { path: "/docs", component: DocsPage }), _jsx(PageRoutes.Route, { path: "/support", component: SupportIndexPage })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findAll(Text, { testId: 'page' })).toHaveLength(1);
+            expect(findByTestId(Text, 'page').text).toEqual('docs');
+            expect(maybeFind(Text, (node) => node.text === 'home')).toBeNull();
+            expect(maybeFind(Text, (node) => node.text === 'support-index')).toBeNull();
+        });
+        it('renders only the matched nested route and not sibling or parent-level routes', () => {
+            const { mocks, render, findAll, findByTestId, maybeFind } = createRenderer('home');
+            mocks.setPageLocation({ path: '/support/faq', params: {} });
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsxs(PageRoutes, { path: "/support", children: [_jsx(PageRoutes.IndexRoute, { component: SupportIndexPage }), _jsx(PageRoutes.Route, { path: "/contact-us", component: ContactUsPage }), _jsx(PageRoutes.Route, { path: "/faq", component: FAQPage })] })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findAll(Text, { testId: 'page' })).toHaveLength(1);
+            expect(findByTestId(Text, 'page').text).toEqual('faq');
+            expect(maybeFind(Text, (node) => node.text === 'home')).toBeNull();
+            expect(maybeFind(Text, (node) => node.text === 'support-index')).toBeNull();
+            expect(maybeFind(Text, (node) => node.text === 'contact-us')).toBeNull();
+        });
+        it('renders only one route at a time when location changes', () => {
+            const { mocks, render, findAll, findByTestId, maybeFind } = createRenderer('home');
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(PageRoutes.Route, { path: "/docs", component: DocsPage }), _jsx(PageRoutes.Route, { path: "/support", component: SupportIndexPage })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findAll(Text, { testId: 'page' })).toHaveLength(1);
+            expect(findByTestId(Text, 'page').text).toEqual('home');
+            expect(maybeFind(Text, (node) => node.text === 'docs')).toBeNull();
+            mocks.setPageLocation({ path: '/docs', params: {} });
+            expect(findAll(Text, { testId: 'page' })).toHaveLength(1);
+            expect(findByTestId(Text, 'page').text).toEqual('docs');
+            expect(maybeFind(Text, (node) => node.text === 'home')).toBeNull();
+            mocks.setPageLocation({ path: '/support', params: {} });
+            expect(findAll(Text, { testId: 'page' })).toHaveLength(1);
+            expect(findByTestId(Text, 'page').text).toEqual('support-index');
+            expect(maybeFind(Text, (node) => node.text === 'docs')).toBeNull();
+        });
+    });
+    describe('nested routes', () => {
+        const createNestedRouter = () => createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsxs(PageRoutes, { path: "/support", children: [_jsx(PageRoutes.IndexRoute, { component: SupportIndexPage }), _jsx(PageRoutes.Route, { path: "/contact-us", component: ContactUsPage }), _jsx(PageRoutes.Route, { path: "/faq", component: FAQPage })] })] }));
+        it('renders nested index route', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({ path: '/support', params: {} });
+            const PageRouter = createNestedRouter();
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('support-index');
+        });
+        it('renders nested named route', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({ path: '/support/contact-us', params: {} });
+            const PageRouter = createNestedRouter();
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('contact-us');
+        });
+        it('renders a different nested named route', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({ path: '/support/faq', params: {} });
+            const PageRouter = createNestedRouter();
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('faq');
+        });
+    });
+    describe('path parameters', () => {
+        it('extracts path params from the route pattern', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({ path: '/contacts/abc-123', params: {} });
+            const PageRouter = createPageRouter(_jsx(PageRoutes, { children: _jsx(PageRoutes.Route, { path: "/contacts/:contactId", component: ContactDetailsPage }) }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('contact-details');
+            expect(findByTestId(Text, 'route-params').text).toEqual('{"contactId":"abc-123"}');
+        });
+        it('merges path params with appPageLocation params', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({
+                path: '/contacts/abc-123',
+                params: { tab: 'activity' },
+            });
+            const PageRouter = createPageRouter(_jsx(PageRoutes, { children: _jsx(PageRoutes.Route, { path: "/contacts/:contactId", component: ContactDetailsPage }) }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'route-params').text).toEqual('{"contactId":"abc-123","tab":"activity"}');
+        });
+        it('gives appPageLocation params precedence over path params on conflict', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({
+                path: '/contacts/from-path',
+                params: { contactId: 'from-query' },
+            });
+            const PageRouter = createPageRouter(_jsx(PageRoutes, { children: _jsx(PageRoutes.Route, { path: "/contacts/:contactId", component: ContactDetailsPage }) }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'route-params').text).toEqual('{"contactId":"from-query"}');
+        });
+    });
+    describe('layout components', () => {
+        it('wraps matched route content in the layout component', () => {
+            const { render, findByTestId } = createRenderer('home');
+            const AppLayout = ({ children }) => (_jsx(Box, { testId: "layout-app", children: children }));
+            const PageRouter = createPageRouter(_jsx(PageRoutes, { layoutComponent: AppLayout, children: _jsx(PageRoutes.IndexRoute, { component: HomePage }) }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Box, 'layout-app')).toBeTruthy();
+            expect(findByTestId(Text, 'page').text).toEqual('home');
+        });
+        it('nests layout components from outer to inner', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            const OuterLayout = ({ children }) => (_jsx(Box, { testId: "layout-outer", children: children }));
+            const InnerLayout = ({ children }) => (_jsx(Box, { testId: "layout-inner", children: children }));
+            mocks.setPageLocation({ path: '/section/page-a', params: {} });
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { layoutComponent: OuterLayout, children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(PageRoutes, { path: "/section", layoutComponent: InnerLayout, children: _jsx(PageRoutes.Route, { path: "/page-a", component: DocsPage }) })] }));
+            render(_jsx(PageRouter, {}));
+            const outerLayout = findByTestId(Box, 'layout-outer');
+            const innerLayout = outerLayout.find(Box, { testId: 'layout-inner' });
+            expect(outerLayout).toBeTruthy();
+            expect(innerLayout).toBeTruthy();
+            expect(findByTestId(Text, 'page').text).toEqual('docs');
+        });
+    });
+    describe('catch-all and wildcard routes', () => {
+        it('renders AnyRoute for unmatched paths', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({ path: '/does-not-exist', params: {} });
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(PageRoutes.Route, { path: "/docs", component: DocsPage }), _jsx(PageRoutes.AnyRoute, { component: NotFoundPage })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('not-found-custom');
+        });
+        it('renders the wildcard route and captures the remaining path', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({
+                path: '/files/documents/report.pdf',
+                params: {},
+            });
+            const WildcardDisplay = () => {
+                const { params } = usePageRoute();
+                return (_jsxs(_Fragment, { children: [_jsx(Text, { testId: "page", children: "file-browser" }), _jsx(Text, { testId: "wildcard", children: params['*'] })] }));
+            };
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(PageRoutes.Route, { path: "/files/*", component: WildcardDisplay })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('file-browser');
+            expect(findByTestId(Text, 'wildcard').text).toEqual('documents/report.pdf');
+        });
+    });
+    describe('route IDs', () => {
+        it('provides routeId via usePageRoute when route has an id', () => {
+            const { render, findByTestId } = createRenderer('home');
+            const PageWithRouteInfo = () => _jsx(RouteInfoDisplay, {});
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { id: "home", component: PageWithRouteInfo }), _jsx(PageRoutes.Route, { id: "docs", path: "/docs", component: PageWithRouteInfo })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'route-id').text).toEqual('home');
+        });
+        it('provides the correct routeId for a named route', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({ path: '/docs', params: {} });
+            const PageWithRouteInfo = () => _jsx(RouteInfoDisplay, {});
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { id: "home", component: PageWithRouteInfo }), _jsx(PageRoutes.Route, { id: "docs", path: "/docs", component: PageWithRouteInfo })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'route-id').text).toEqual('docs');
+        });
+        it('throws on duplicate route IDs', () => {
+            expect(() => createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { id: "same-id", component: HomePage }), _jsx(PageRoutes.Route, { id: "same-id", path: "/other", component: DocsPage })] }))).toThrowError('Duplicate route id: "same-id"');
+        });
+    });
+    describe('location reactivity', () => {
+        it('re-renders with new content when location changes after mount', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(PageRoutes.Route, { path: "/docs", component: DocsPage }), _jsx(PageRoutes.Route, { path: "/support", component: SupportIndexPage })] }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('home');
+            mocks.setPageLocation({ path: '/docs', params: {} });
+            expect(findByTestId(Text, 'page').text).toEqual('docs');
+            mocks.setPageLocation({ path: '/support', params: {} });
+            expect(findByTestId(Text, 'page').text).toEqual('support-index');
+        });
+        it('updates route params when location params change', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            const PageRouter = createPageRouter(_jsx(PageRoutes, { children: _jsx(PageRoutes.Route, { path: "/contacts/:contactId", component: ContactDetailsPage }) }));
+            mocks.setPageLocation({ path: '/contacts/111', params: {} });
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'route-params').text).toEqual('{"contactId":"111"}');
+            mocks.setPageLocation({ path: '/contacts/222', params: {} });
+            expect(findByTestId(Text, 'route-params').text).toEqual('{"contactId":"222"}');
+        });
+        it('transitions from a matched route to "Page not found"', () => {
+            const { mocks, render, findByTestId, find } = createRenderer('home');
+            const PageRouter = createPageRouter(_jsx(PageRoutes, { children: _jsx(PageRoutes.IndexRoute, { component: HomePage }) }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('home');
+            mocks.setPageLocation({ path: '/missing', params: {} });
+            expect(find(Text, (node) => node.text === 'This app page does not exist.')).toBeTruthy();
+        });
+    });
+    describe('conditional routes', () => {
+        it('excludes a route when condition is false', () => {
+            const { mocks, render, find } = createRenderer('home');
+            mocks.setPageLocation({ path: '/docs', params: {} });
+            const docsEnabled = false;
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), docsEnabled && (_jsx(PageRoutes.Route, { path: "/docs", component: DocsPage }))] }));
+            render(_jsx(PageRouter, {}));
+            expect(find(Text, (node) => node.text === 'This app page does not exist.')).toBeTruthy();
+        });
+        it('includes a route when condition is true', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({ path: '/docs', params: {} });
+            const docsEnabled = true;
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), docsEnabled && (_jsx(PageRoutes.Route, { path: "/docs", component: DocsPage }))] }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('docs');
+        });
+        it('handles null children', () => {
+            const { render, findByTestId } = createRenderer('home');
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), null] }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('home');
+        });
+        it('skips conditional nested routes when falsy', () => {
+            const { mocks, render, find } = createRenderer('home');
+            mocks.setPageLocation({ path: '/support', params: {} });
+            const supportEnabled = false;
+            const PageRouter = createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), supportEnabled && (_jsxs(PageRoutes, { path: "/support", children: [_jsx(PageRoutes.IndexRoute, { component: SupportIndexPage }), _jsx(PageRoutes.Route, { path: "/contact-us", component: ContactUsPage })] }))] }));
+            render(_jsx(PageRouter, {}));
+            expect(find(Text, (node) => node.text === 'This app page does not exist.')).toBeTruthy();
+        });
+        it('supports routes generated from an array via .map()', () => {
+            const { mocks, render, findByTestId } = createRenderer('home');
+            mocks.setPageLocation({ path: '/support', params: {} });
+            const rootPages = {
+                '/': HomePage,
+                '/docs': DocsPage,
+                '/support': SupportIndexPage,
+            };
+            const PageRouter = createPageRouter(_jsx(PageRoutes, { children: Object.entries(rootPages).map(([path, PageComponent]) => (_jsx(PageRoutes.Route, { path: path, component: PageComponent }, path))) }));
+            render(_jsx(PageRouter, {}));
+            expect(findByTestId(Text, 'page').text).toEqual('support-index');
+        });
+    });
+    describe('invalid routes', () => {
+        it('throws for an invalid top-level element', () => {
+            expect(() => createPageRouter(_jsx("div", {}))).toThrowError('Invalid React node for page routes: <div />');
+        });
+        it('throws for an invalid child element', () => {
+            expect(() => createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx("span", {})] }))).toThrowError('Invalid React node for page routes: <span />');
+        });
+        it('throws for a named component child', () => {
+            const Sidebar = () => _jsx("div", { children: "sidebar" });
+            expect(() => createPageRouter(_jsxs(PageRoutes, { children: [_jsx(PageRoutes.IndexRoute, { component: HomePage }), _jsx(Sidebar, {})] }))).toThrowError('Invalid React node for page routes: <Sidebar />');
+        });
+    });
+});