Export createExternalRouteRef and set id

Co-authored-by: Fredrik Adelöw <freben@gmail.com>
Co-authored-by: blam<ben@blam.sh>
Co-authored-by: Patrik Oldsberg <poldsberg@gmail.com>

docs/plugins/composability.md

@@ -248,7 +248,7 @@ might be linking to, allowing the app to decide the final target. If the
 declare an `ExternalRouteRef` similar to this:
 
 ```ts
-const headerLinkRouteRef = createExternalRouteRef();
+const headerLinkRouteRef = createExternalRouteRef({ id: 'header-link' });
 ```
 
 ### Binding External Routes in the App

packages/core-api/src/app/App.test.tsx

@@ -28,7 +28,7 @@ import { generateBoundRoutes, PrivateAppImpl } from './App';
 
 describe('generateBoundRoutes', () => {
   it('runs happy path', () => {
-    const external = { myRoute: createExternalRouteRef() };
+    const external = { myRoute: createExternalRouteRef({ id: '1' }) };
     const ref = createRouteRef({ path: '', title: '' });
     const result = generateBoundRoutes(({ bind }) => {
       bind(external, { myRoute: ref });
@@ -38,7 +38,7 @@ describe('generateBoundRoutes', () => {
   });
 
   it('throws on unknown keys', () => {
-    const external = { myRoute: createExternalRouteRef() };
+    const external = { myRoute: createExternalRouteRef({ id: '2' }) };
     const ref = createRouteRef({ path: '', title: '' });
     expect(() =>
       generateBoundRoutes(({ bind }) => {
@@ -51,7 +51,7 @@ describe('generateBoundRoutes', () => {
 describe('Integration Test', () => {
   const plugin1RouteRef = createRouteRef({ path: '/blah1', title: '' });
   const plugin2RouteRef = createRouteRef({ path: '/blah2', title: '' });
-  const externalRouteRef = createExternalRouteRef();
+  const externalRouteRef = createExternalRouteRef({ id: '3' });
 
   const plugin1 = createPlugin({
     id: 'blob',
@@ -77,7 +77,7 @@ describe('Integration Test', () => {
         Promise.resolve((_: PropsWithChildren<{ path?: string }>) => {
           // eslint-disable-next-line react-hooks/rules-of-hooks
           const routeRefFunction = useRouteRef(externalRouteRef);
-          return <div>Our Route Is: {routeRefFunction({})}</div>;
+          return <div>Our Route Is: {routeRefFunction()}</div>;
         }),
       mountPoint: plugin1RouteRef,
     }),

packages/core-api/src/routing/RouteRef.ts

@@ -65,13 +65,22 @@ export function createRouteRef<
 }
 
 export class ExternalRouteRef {
-  private constructor() {}
-
-  toString() {
-    return `externalRouteRef{}`;
+  private constructor(id: string) {
+    this.toString = () => `externalRouteRef{${id}}`;
   }
 }
 
-export function createExternalRouteRef(): ExternalRouteRef {
-  return new ((ExternalRouteRef as unknown) as { new (): ExternalRouteRef })();
+export type ExternalRouteRefOptions = {
+  /**
+   * An identifier for this route, used to identify it in error messages
+   */
+  id: string;
+};
+
+export function createExternalRouteRef(
+  options: ExternalRouteRefOptions,
+): ExternalRouteRef {
+  return new ((ExternalRouteRef as unknown) as {
+    new (id: string): ExternalRouteRef;
+  })(options.id);
 }

packages/core-api/src/routing/hooks.test.tsx

@@ -59,9 +59,9 @@ const ref2 = createRouteRef(mockConfig({ path: '/wat2' }));
 const ref3 = createRouteRef(mockConfig({ path: '/wat3' }));
 const ref4 = createRouteRef(mockConfig({ path: '/wat4' }));
 const ref5 = createRouteRef(mockConfig({ path: '/wat5' }));
-const eRefA = createExternalRouteRef();
-const eRefB = createExternalRouteRef();
-const eRefC = createExternalRouteRef();
+const eRefA = createExternalRouteRef({ id: '1' });
+const eRefB = createExternalRouteRef({ id: '2' });
+const eRefC = createExternalRouteRef({ id: '3' });
 
 const MockRouteSource = <T extends { [name in string]: string }>(props: {
   path?: string;

packages/core-api/src/routing/hooks.tsx

@@ -111,7 +111,7 @@ class RouteResolver {
 
 const RoutingContext = createContext<RouteResolver | undefined>(undefined);
 
-export function useRouteRef<Params extends { [param in string]: string }>(
+export function useRouteRef<Params extends { [param in string]: string } = {}>(
   routeRef: RouteRef<Params> | ExternalRouteRef,
 ): RouteFunc<Params> {
   const sourceLocation = useLocation();

packages/core-api/src/routing/index.ts

@@ -21,6 +21,6 @@ export type {
   MutableRouteRef,
 } from './types';
 export { FlatRoutes } from './FlatRoutes';
-export { createRouteRef } from './RouteRef';
+export { createRouteRef, createExternalRouteRef } from './RouteRef';
 export type { RouteRefConfig } from './RouteRef';
 export { useRouteRef } from './hooks';