@hubspot/ui-extensions 0.12.3 → 0.12.4

package/dist/experimental/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 />');
+        });
+    });
+});

package/dist/experimental/pages/hooks.d.ts

@@ -0,0 +1,8 @@
+import type { MatchedPageRoute } from './types.ts';
+/**
+ * The hook that provides the current page route to the component.
+ *
+ * @returns The current page route.
+ * @experimental This hook is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
+ */
+export declare const usePageRoute: () => MatchedPageRoute;

package/dist/experimental/pages/hooks.js

@@ -0,0 +1,15 @@
+import { useContext } from 'react';
+import { AppPageRouteContext } from "./internal/app-page-route-context.js";
+/**
+ * The hook that provides the current page route to the component.
+ *
+ * @returns The current page route.
+ * @experimental This hook is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates.
+ */
+export const usePageRoute = () => {
+    const matchedPageRoute = useContext(AppPageRouteContext);
+    if (!matchedPageRoute) {
+        throw new Error('usePageRoute must be used within a <PageRouter> component produced by createPageRouter');
+    }
+    return matchedPageRoute;
+};

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

@@ -1,4 +1,6 @@
+export * from './components/index.ts';
+export * from './create-page-router.tsx';
+export * from './hooks.ts';
+export type * from './types.ts';
 export type * from '../../shared/types/pages/components/index.ts';
-export type * from '../../shared/types/pages/app-pages-types.ts';
-export declare const PageRoutes: import("../../shared/types/pages/components/page-routes.ts").PageRoutesComponent, usePageRoute: import("../../shared/types/pages/app-pages-types.ts").UsePageRouteHook, createPageRouter: import("../../shared/types/pages/app-pages-types.ts").CreatePageRouterFunction;
-export { PageLink } from '../../shared/remoteComponents.tsx';
+export { PageBreadcrumbs, PageHeader, PageLink, PageTitle, } from '../../shared/remoteComponents.tsx';

package/dist/experimental/pages/index.js

@@ -1,3 +1,4 @@
-import { getWorkerGlobals } from "../../internal/global-utils.js";
-export const { PageRoutes, usePageRoute, createPageRouter } = getWorkerGlobals().hsWorkerAPI;
-export { PageLink } from "../../shared/remoteComponents.js";
+export * from "./components/index.js";
+export * from "./create-page-router.js";
+export * from "./hooks.js";
+export { PageBreadcrumbs, PageHeader, PageLink, PageTitle, } from "../../shared/remoteComponents.js";

package/dist/experimental/pages/internal/app-page-route-context.d.ts

@@ -0,0 +1,16 @@
+import type { MatchedPageRoute } from '../types.ts';
+export declare const AppPageRouteContext: import("react").Context<MatchedPageRoute | null>;
+interface AppPageRouteProviderProps {
+    children: React.ReactNode;
+    pageRoute: MatchedPageRoute;
+}
+/**
+ * The provider that provides the current page route to the component.
+ * This component is used internally by the produced page router components.
+ *
+ * @param children - The children to render.
+ * @param pageRoute - The current page route.
+ * @returns The provider.
+ */
+export declare const AppPageRouteProvider: ({ children, pageRoute, }: AppPageRouteProviderProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/experimental/pages/internal/app-page-route-context.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext } from 'react';
+export const AppPageRouteContext = createContext(null);
+/**
+ * The provider that provides the current page route to the component.
+ * This component is used internally by the produced page router components.
+ *
+ * @param children - The children to render.
+ * @param pageRoute - The current page route.
+ * @returns The provider.
+ */
+export const AppPageRouteProvider = ({ children, pageRoute, }) => (_jsx(AppPageRouteContext.Provider, { value: pageRoute, children: children }));

package/dist/experimental/pages/internal/convert-page-routes-react-elements.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+import { type RoutesNode } from './page-router-internal-types.ts';
+/**
+ * Converts a react node to a routes node by recursively converting the react node.
+ *
+ * @param reactNode - The react node to convert.
+ * @returns The converted routes node.
+ */
+export declare const convertReactPageRoutesElement: (reactNode: ReactNode) => RoutesNode;

package/dist/experimental/pages/internal/convert-page-routes-react-elements.js

@@ -0,0 +1,138 @@
+import { Fragment, isValidElement, Children as ReactChildren, } from 'react';
+import { PageRoutes, } from "../components/page-routes.js";
+import { RouteNodeType, } from "./page-router-internal-types.js";
+const isReactPageRoutesElement = (reactRouteNode) => {
+    return isValidElement(reactRouteNode) && reactRouteNode.type === PageRoutes;
+};
+const isReactRouteElement = (reactNode) => isValidElement(reactNode) && reactNode.type === PageRoutes.Route;
+const isReactIndexRouteElement = (reactNode) => isValidElement(reactNode) && reactNode.type === PageRoutes.IndexRoute;
+const isReactAnyRouteElement = (reactNode) => isValidElement(reactNode) && reactNode.type === PageRoutes.AnyRoute;
+const isReactFragmentElement = (reactRouteNode) => isValidElement(reactRouteNode) && reactRouteNode.type === Fragment;
+/**
+ * Describes a React node by producing a string representation of the React node.
+ *
+ * @param reactNode - The react node to describe.
+ * @returns The description of the react node.
+ */
+const describeReactNode = (reactNode) => {
+    if (reactNode == null) {
+        return String(reactNode);
+    }
+    if (typeof reactNode !== 'object') {
+        return JSON.stringify(reactNode);
+    }
+    if (isValidElement(reactNode)) {
+        const elementType = reactNode.type;
+        const name = typeof elementType === 'string'
+            ? elementType
+            : typeof elementType === 'function'
+                ? elementType.displayName ||
+                    elementType.name ||
+                    'Unknown'
+                : 'Unknown';
+        return `<${name} />`;
+    }
+    return JSON.stringify(reactNode);
+};
+class InvalidRoutesReactNodeError extends Error {
+    constructor(reactNode) {
+        super(`Invalid React node for page routes: ${describeReactNode(reactNode)}`);
+    }
+}
+const addRoute = (parentNode, childNode) => {
+    if (!parentNode.children) {
+        parentNode.children = [];
+    }
+    parentNode.children.push(childNode);
+};
+/**
+ * Converts a routes element to a routes node by recursively converting the routes children.
+ *
+ * @param reactRoutesElement - The routes element to convert.
+ * @returns The converted routes node.
+ */
+function convertReactRoutesElement(reactRoutesElement) {
+    const { path, layoutComponent, children } = reactRoutesElement.props;
+    const routesNode = {
+        type: RouteNodeType.Routes,
+        path,
+        layoutComponent,
+        children: null,
+    };
+    convertChildrenReactRouteElements(routesNode, children);
+    return routesNode;
+}
+/**
+ * Converts the children of a routes element to a routes node by recursively converting the children.
+ *
+ * @param parentNode - The parent node to add the children to.
+ * @param children - The children to convert.
+ * @returns void.
+ */
+function convertChildrenReactRouteElements(parentNode, children) {
+    ReactChildren.forEach(children, (child) => {
+        if (child == null || typeof child === 'boolean') {
+            return;
+        }
+        if (isReactPageRoutesElement(child)) {
+            const routesNode = convertReactRoutesElement(child);
+            addRoute(parentNode, routesNode);
+        }
+        else if (isReactRouteElement(child)) {
+            const { path, component, id } = child.props;
+            const routeNode = {
+                type: RouteNodeType.Path,
+                path,
+                component,
+                id,
+            };
+            addRoute(parentNode, routeNode);
+        }
+        else if (isReactIndexRouteElement(child)) {
+            const { component, id } = child.props;
+            const routeNode = {
+                type: RouteNodeType.Path,
+                path: '/',
+                component,
+                id,
+            };
+            addRoute(parentNode, routeNode);
+        }
+        else if (isReactAnyRouteElement(child)) {
+            const { component, id } = child.props;
+            const routeNode = {
+                type: RouteNodeType.Path,
+                path: '*',
+                component,
+                id,
+            };
+            addRoute(parentNode, routeNode);
+        }
+        else if (isReactFragmentElement(child)) {
+            convertChildrenReactRouteElements(parentNode, child.props.children);
+        }
+        else {
+            throw new InvalidRoutesReactNodeError(child);
+        }
+    });
+}
+/**
+ * Converts a react node to a routes node by recursively converting the react node.
+ *
+ * @param reactNode - The react node to convert.
+ * @returns The converted routes node.
+ */
+export const convertReactPageRoutesElement = (reactNode) => {
+    if (isReactPageRoutesElement(reactNode)) {
+        return convertReactRoutesElement(reactNode);
+    }
+    if (isReactFragmentElement(reactNode)) {
+        const rootNode = {
+            type: RouteNodeType.Routes,
+            children: null,
+        };
+        convertChildrenReactRouteElements(rootNode, reactNode.props.children);
+        return rootNode;
+    }
+    throw new InvalidRoutesReactNodeError(reactNode);
+};

package/dist/experimental/pages/internal/page-router-internal-types.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { EmptyProps } from '../../../shared/types/shared.ts';
+import type { PageRoutesLayoutComponent } from '../components/page-routes.ts';
+export interface PageRoutesLayoutProps {
+    children: ReactNode;
+}
+export declare enum RouteNodeType {
+    Routes = "routes",
+    Path = "path"
+}
+/**
+ * An intermediate representation of the page routes before being added to the trie router.
+ */
+export interface RoutesNode {
+    type: RouteNodeType.Routes;
+    path?: string;
+    layoutComponent?: PageRoutesLayoutComponent;
+    children: RouteNode[] | null;
+}
+/**
+ * An intermediate representation of a route before being added to the trie router.
+ */
+export interface RoutePathNode {
+    type: RouteNodeType.Path;
+    path: string;
+    component: ComponentType<EmptyProps>;
+    id?: string;
+}
+/**
+ * An intermediate representation of a route descriptor node that is used to populate an app page router.
+ */
+export type RouteNode = RoutesNode | RoutePathNode;
+/**
+ * The data for a page route.
+ */
+export interface PageRouteData {
+    component: ComponentType<EmptyProps>;
+    layouts: PageRoutesLayoutComponent[];
+    id?: string;
+}

package/dist/experimental/pages/internal/page-router-internal-types.js

@@ -0,0 +1,5 @@
+export var RouteNodeType;
+(function (RouteNodeType) {
+    RouteNodeType["Routes"] = "routes";
+    RouteNodeType["Path"] = "path";
+})(RouteNodeType || (RouteNodeType = {}));

package/dist/experimental/pages/internal/trie-router.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Trie-based URL router. Routes are split into path segments and are stored in a prefix tree for
+ * O(number-of-path-segments) lookup. When multiple route types match, priority is: static > param > wildcard.
+ */
+export interface MatchedRoute<TRouteData> {
+    data: TRouteData;
+    params: Record<string, string>;
+}
+/**
+ * The TrieRouter interface defines the methods for matching and adding routes to the router.
+ */
+export interface TrieRouter<TRouteData> {
+    /**
+     * Matches a path to a route and returns the route data and parameters
+     */
+    matchPath: (path: string) => MatchedRoute<TRouteData> | null;
+    /**
+     * Adds a route to the router
+     */
+    addRoute: (path: string, data: TRouteData) => void;
+}
+/**
+ * Creates a new TrieRouter instance. After creation, routes can be added to the router using the addRoute method.
+ * Routes can be matched using the matchPath method.
+ *
+ * The order that routes are added does not matter. The router will always match the longest possible route.
+ *
+ * @param TRouteData - The type of the route data that can be associated with each added route
+ * @returns A TrieRouter instance
+ */
+export declare const createTrieRouter: <TRouteData = unknown>() => TrieRouter<TRouteData>;