@hubspot/ui-extensions 0.12.3 → 0.13.0

package/dist/pages/hooks.d.ts

@@ -0,0 +1,7 @@
+import type { MatchedPageRoute } from './types.ts';
+/**
+ * The hook that provides the current page route to the component.
+ *
+ * @returns The current page route.
+ */
+export declare const usePageRoute: () => MatchedPageRoute;

package/dist/pages/hooks.js

@@ -0,0 +1,14 @@
+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.
+ */
+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/pages/index.d.ts

@@ -0,0 +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 { PageBreadcrumbs, PageHeader, PageLink, PageTitle, } from '../shared/remoteComponents.tsx';

package/dist/pages/index.js

@@ -0,0 +1,4 @@
+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/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/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/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/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/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/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/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>;

package/dist/pages/internal/trie-router.js

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+const WILDCARD = '*';
+const normalizePath = (path) => `/${path.replace(/\/+/g, '/').replace(/\/$/, '').replace(/^\//, '')}`;
+const splitSegments = (normalizedPath) => normalizedPath === '/' ? [] : normalizedPath.slice(1).split('/');
+const isParamSegment = (segment) => segment.startsWith(':');
+const getParamNameForSegment = (segment) => segment.slice(1);
+const safeDecodeURIComponent = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+/**
+ * Recursively searches the trie for an existing route that would conflict
+ * with the given segments. Returns the conflicting pattern, or null.
+ */
+const findConflictingPattern = (node, segmentIndex, segments) => {
+    if (segmentIndex === segments.length) {
+        return node.pattern ?? null;
+    }
+    const segment = segments[segmentIndex];
+    if (isParamSegment(segment)) {
+        const { paramChildren } = node;
+        if (paramChildren) {
+            for (const paramChild of Object.values(paramChildren)) {
+                const result = findConflictingPattern(paramChild, segmentIndex + 1, segments);
+                if (result)
+                    return result;
+            }
+        }
+    }
+    else if (segment === WILDCARD) {
+        return node.children?.[WILDCARD]?.pattern ?? null;
+    }
+    else {
+        const childNode = node.children?.[segment];
+        if (childNode) {
+            const result = findConflictingPattern(childNode, segmentIndex + 1, segments);
+            if (result)
+                return result;
+        }
+    }
+    return null;
+};
+/**
+ * Recursively walks the trie to find a route matching the given segments.
+ * Tries static children, then param children, then wildcard (priority order).
+ */
+const findMatchingRoute = (node, params, segments, segmentIndex) => {
+    if (segmentIndex === segments.length) {
+        // Only terminal nodes have data assigned
+        if ('data' in node) {
+            return {
+                data: node.data,
+                params,
+            };
+        }
+        return null;
+    }
+    const segment = segments[segmentIndex];
+    // Try matches in priority order: static > param > wildcard
+    const childNode = node.children?.[segment];
+    if (childNode) {
+        const result = findMatchingRoute(childNode, params, segments, segmentIndex + 1);
+        if (result)
+            return result;
+    }
+    const { paramChildren } = node;
+    if (paramChildren) {
+        for (const [paramName, paramChild] of Object.entries(paramChildren)) {
+            const result = findMatchingRoute(paramChild, { ...params, [paramName]: safeDecodeURIComponent(segment) }, segments, segmentIndex + 1);
+            if (result)
+                return result;
+        }
+    }
+    const wildcardNode = node.children?.[WILDCARD];
+    if (wildcardNode && 'data' in wildcardNode) {
+        return {
+            data: wildcardNode.data,
+            params: {
+                ...params,
+                [WILDCARD]: segments.slice(segmentIndex).join('/'),
+            },
+        };
+    }
+    return null;
+};
+/**
+ * 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 const createTrieRouter = () => {
+    const rootNode = {};
+    return {
+        matchPath: (path) => {
+            const normalizedPath = normalizePath(path);
+            const segments = splitSegments(normalizedPath);
+            return findMatchingRoute(rootNode, {}, segments, 0);
+        },
+        addRoute: (path, data) => {
+            const normalizedPath = normalizePath(path);
+            const segments = splitSegments(normalizedPath);
+            // Validate the route before we start adding it to the trie to avoid adding invalid routes
+            for (let i = 0; i < segments.length; i++) {
+                const segment = segments[i];
+                if (segment === WILDCARD && i !== segments.length - 1) {
+                    throw new Error(`Wildcard must be the last segment in route: ${normalizedPath}`);
+                }
+                if (isParamSegment(segment) && getParamNameForSegment(segment) === '') {
+                    throw new Error(`Invalid route "${normalizedPath}": param segment at position ${i} has an empty name`);
+                }
+            }
+            const conflictingPattern = findConflictingPattern(rootNode, 0, segments);
+            if (conflictingPattern) {
+                throw new Error(`Route conflict: "${normalizedPath}" conflicts with existing route "${conflictingPattern}"`);
+            }
+            // Add the route to the trie
+            let current = rootNode;
+            for (const segment of segments) {
+                if (isParamSegment(segment)) {
+                    current = (current.paramChildren ??= {})[getParamNameForSegment(segment)] ??= {};
+                }
+                else {
+                    current = (current.children ??= {})[segment] ??= {};
+                }
+            }
+            current.data = data;
+            current.pattern = normalizedPath;
+        },
+    };
+};

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

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