@checkmate-monitor/frontend-api 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @checkmate-monitor/frontend-api
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+  - @checkmate-monitor/common@0.1.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@checkmate-monitor/frontend-api",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
+  "dependencies": {
+    "@checkmate-monitor/common": "workspace:*",
+    "@orpc/client": "^1.13.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.5",
+    "@types/react": "^18.0.0",
+    "typescript": "^5.0.0",
+    "@checkmate-monitor/tsconfig": "workspace:*",
+    "@checkmate-monitor/scripts": "workspace:*"
+  }
+}

package/src/api-context.ts

@@ -0,0 +1,53 @@
+import React, { createContext, useContext, ReactNode } from "react";
+import { ApiRef } from "./api-ref";
+
+export type ApiRegistry = Map<string, unknown>;
+
+const ApiContext = createContext<ApiRegistry | undefined>(undefined);
+
+export class ApiRegistryBuilder {
+  private registry: ApiRegistry = new Map();
+
+  register<T>(ref: ApiRef<T>, impl: T) {
+    this.registry.set(ref.id, impl);
+    return this;
+  }
+
+  registerFactory<T>(ref: ApiRef<T>, factory: (registry: ApiRegistry) => T) {
+    const impl = factory(this.registry);
+    this.registry.set(ref.id, impl);
+    return this;
+  }
+
+  build() {
+    return this.registry;
+  }
+}
+
+export const ApiProvider = ({
+  registry,
+  children,
+}: {
+  registry: ApiRegistry;
+  children: ReactNode;
+}) => {
+  return React.createElement(
+    ApiContext.Provider,
+    { value: registry },
+    children
+  );
+};
+
+export function useApi<T>(ref: ApiRef<T>): T {
+  const registry = useContext(ApiContext);
+  if (!registry) {
+    throw new Error("useApi must be used within an ApiProvider");
+  }
+
+  const output = registry.get(ref.id);
+  if (!output) {
+    throw new Error(`No implementation found for API '${ref.id}'`);
+  }
+
+  return output as T;
+}

package/src/api-ref.ts

@@ -0,0 +1,15 @@
+export type ApiRef<T> = {
+  id: string;
+  T: T;
+  toString(): string;
+};
+
+export function createApiRef<T>(id: string): ApiRef<T> {
+  return {
+    id,
+    T: undefined as T,
+    toString() {
+      return `ApiRef(${id})`;
+    },
+  };
+}

package/src/components/ExtensionSlot.tsx

@@ -0,0 +1,46 @@
+import { pluginRegistry } from "../plugin-registry";
+import type { SlotContext } from "../plugin";
+import type { SlotDefinition } from "../slots";
+
+/**
+ * Type-safe props for ExtensionSlot.
+ * Extracts the context type from the slot definition itself,
+ * ensuring the context matches what the slot expects.
+ */
+type ExtensionSlotProps<TSlot extends SlotDefinition<unknown>> =
+  SlotContext<TSlot> extends undefined
+    ? { slot: TSlot; context?: undefined }
+    : { slot: TSlot; context: SlotContext<TSlot> };
+
+/**
+ * Renders all extensions registered for the given slot.
+ *
+ * @example
+ * ```tsx
+ * // Slot with context - context is required and type-checked
+ * <ExtensionSlot slot={SystemDetailsSlot} context={{ system }} />
+ *
+ * // Slot without context
+ * <ExtensionSlot slot={NavbarSlot} />
+ * ```
+ */
+export function ExtensionSlot<TSlot extends SlotDefinition<unknown>>({
+  slot,
+  context,
+}: ExtensionSlotProps<TSlot>) {
+  const extensions = pluginRegistry.getExtensions(slot.id);
+
+  if (extensions.length === 0) {
+    return <></>;
+  }
+
+  return (
+    <>
+      {extensions.map((ext) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const Component = ext.component as React.ComponentType<any>;
+        return <Component key={ext.id} {...(context ?? {})} />;
+      })}
+    </>
+  );
+}

package/src/core-apis.ts

@@ -0,0 +1,41 @@
+import {
+  PermissionAction,
+  ClientDefinition,
+  InferClient,
+} from "@checkmate-monitor/common";
+import { createApiRef } from "./api-ref";
+
+export interface LoggerApi {
+  info(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+}
+
+export interface FetchApi {
+  fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+  forPlugin(pluginId: string): {
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+  };
+}
+
+export const loggerApiRef = createApiRef<LoggerApi>("core.logger");
+export const fetchApiRef = createApiRef<FetchApi>("core.fetch");
+
+export interface PermissionApi {
+  usePermission(permission: string): { loading: boolean; allowed: boolean };
+  useResourcePermission(
+    resource: string,
+    action: PermissionAction
+  ): { loading: boolean; allowed: boolean };
+  useManagePermission(resource: string): { loading: boolean; allowed: boolean };
+}
+
+export const permissionApiRef = createApiRef<PermissionApi>("core.permission");
+
+export interface RpcApi {
+  client: unknown;
+  forPlugin<T extends ClientDefinition>(def: T): InferClient<T>;
+}
+
+export const rpcApiRef = createApiRef<RpcApi>("core.rpc");

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./api-ref";
+export * from "./api-context";
+export * from "./core-apis";
+export * from "./plugin";
+export * from "./plugin-registry";
+export * from "./components/ExtensionSlot";
+export * from "./utils";
+export * from "./slots";
+export * from "./use-plugin-route";

package/src/plugin-registry.ts

@@ -0,0 +1,245 @@
+import { FrontendPlugin, Extension } from "./plugin";
+
+/**
+ * Listener function for registry changes
+ */
+type RegistryListener = () => void;
+
+/**
+ * Resolved route information for runtime access.
+ */
+interface ResolvedRoute {
+  id: string;
+  path: string;
+  pluginId: string;
+  element?: React.ReactNode;
+  title?: string;
+  permission?: string;
+}
+
+class PluginRegistry {
+  private plugins: FrontendPlugin[] = [];
+  private extensions = new Map<string, Extension[]>();
+  private routeMap = new Map<string, ResolvedRoute>();
+
+  /**
+   * Version counter that increments on every registry change.
+   * Used by React components to trigger re-renders when plugins are added/removed.
+   */
+  private version = 0;
+  private listeners: Set<RegistryListener> = new Set();
+
+  /**
+   * Validate and register routes from a plugin.
+   */
+  private registerRoutes(plugin: FrontendPlugin) {
+    if (!plugin.routes) return;
+
+    const pluginId = plugin.metadata.pluginId;
+
+    for (const route of plugin.routes) {
+      // Validate that route's pluginId matches the frontend plugin
+      if (route.route.pluginId !== pluginId) {
+        console.error(
+          `❌ Route pluginId mismatch: route "${route.route.id}" has pluginId "${route.route.pluginId}" ` +
+            `but plugin is "${pluginId}"`
+        );
+        throw new Error(
+          `Route pluginId "${route.route.pluginId}" doesn't match plugin "${pluginId}"`
+        );
+      }
+
+      const fullPath = `/${route.route.pluginId}${
+        route.route.path.startsWith("/")
+          ? route.route.path
+          : `/${route.route.path}`
+      }`;
+
+      const resolvedRoute: ResolvedRoute = {
+        id: route.route.id,
+        path: fullPath,
+        pluginId: route.route.pluginId,
+        element: route.element,
+        title: route.title,
+        permission: route.permission?.id,
+      };
+
+      // Add to route map for resolution
+      this.routeMap.set(route.route.id, resolvedRoute);
+    }
+  }
+
+  /**
+   * Unregister routes from a plugin.
+   */
+  private unregisterRoutes(plugin: FrontendPlugin) {
+    if (!plugin.routes) return;
+
+    for (const route of plugin.routes) {
+      this.routeMap.delete(route.route.id);
+    }
+  }
+
+  register(plugin: FrontendPlugin) {
+    const pluginId = plugin.metadata.pluginId;
+
+    // Avoid duplicate registration
+    if (this.plugins.some((p) => p.metadata.pluginId === pluginId)) {
+      console.warn(`⚠️ Plugin ${pluginId} already registered`);
+      return;
+    }
+
+    console.log(`🔌 Registering frontend plugin: ${pluginId}`);
+    this.plugins.push(plugin);
+
+    if (plugin.extensions) {
+      for (const extension of plugin.extensions) {
+        if (!this.extensions.has(extension.slot.id)) {
+          this.extensions.set(extension.slot.id, []);
+        }
+        this.extensions.get(extension.slot.id)!.push(extension);
+      }
+    }
+
+    this.registerRoutes(plugin);
+    this.incrementVersion();
+  }
+
+  /**
+   * Unregister a plugin by ID.
+   * Removes the plugin and all its extensions from the registry.
+   */
+  unregister(pluginId: string): boolean {
+    const pluginIndex = this.plugins.findIndex(
+      (p) => p.metadata.pluginId === pluginId
+    );
+    if (pluginIndex === -1) {
+      console.warn(`⚠️ Plugin ${pluginId} not found for unregistration`);
+      return false;
+    }
+
+    const plugin = this.plugins[pluginIndex];
+    console.log(`🔌 Unregistering frontend plugin: ${pluginId}`);
+
+    // Remove plugin from list
+    this.plugins.splice(pluginIndex, 1);
+
+    // Remove extensions
+    if (plugin.extensions) {
+      for (const extension of plugin.extensions) {
+        const slotExtensions = this.extensions.get(extension.slot.id);
+        if (slotExtensions) {
+          const extIndex = slotExtensions.findIndex(
+            (e) => e.id === extension.id
+          );
+          if (extIndex !== -1) {
+            slotExtensions.splice(extIndex, 1);
+          }
+        }
+      }
+    }
+
+    this.unregisterRoutes(plugin);
+    this.incrementVersion();
+    return true;
+  }
+
+  /**
+   * Check if a plugin is registered.
+   */
+  hasPlugin(pluginId: string): boolean {
+    return this.plugins.some((p) => p.metadata.pluginId === pluginId);
+  }
+
+  getPlugins() {
+    return this.plugins;
+  }
+
+  getExtensions(slotId: string): Extension[] {
+    return this.extensions.get(slotId) || [];
+  }
+
+  /**
+   * Get all routes for rendering in the router.
+   */
+  getAllRoutes() {
+    return this.plugins.flatMap((plugin) => {
+      return (plugin.routes || []).map((route) => {
+        const fullPath = `/${route.route.pluginId}${
+          route.route.path.startsWith("/")
+            ? route.route.path
+            : `/${route.route.path}`
+        }`;
+
+        return {
+          path: fullPath,
+          element: route.element,
+          title: route.title,
+          permission: route.permission?.id,
+        };
+      });
+    });
+  }
+
+  /**
+   * Resolve a route by its ID to get the full path.
+   *
+   * @param routeId - Route ID in format "{pluginId}.{routeName}"
+   * @param params - Optional path parameters to substitute
+   * @returns The resolved full path, or undefined if not found
+   */
+  resolveRoute(
+    routeId: string,
+    params?: Record<string, string>
+  ): string | undefined {
+    const route = this.routeMap.get(routeId);
+    if (!route) {
+      console.warn(`⚠️ Route "${routeId}" not found in registry`);
+      return undefined;
+    }
+
+    if (!params) {
+      return route.path;
+    }
+
+    // Substitute path parameters
+    let result = route.path;
+    for (const [key, value] of Object.entries(params)) {
+      result = result.replace(`:${key}`, value);
+    }
+    return result;
+  }
+
+  /**
+   * Get the current version number.
+   * Increments on every register/unregister.
+   */
+  getVersion(): number {
+    return this.version;
+  }
+
+  /**
+   * Subscribe to registry changes.
+   * Returns an unsubscribe function.
+   */
+  subscribe(listener: RegistryListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private incrementVersion() {
+    this.version++;
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+
+  reset() {
+    this.plugins = [];
+    this.extensions.clear();
+    this.routeMap.clear();
+    this.incrementVersion();
+  }
+}
+
+export const pluginRegistry = new PluginRegistry();

package/src/plugin.ts

@@ -0,0 +1,75 @@
+import React from "react";
+import { ApiRef } from "./api-ref";
+import type { SlotDefinition } from "./slots";
+import type {
+  RouteDefinition,
+  PluginMetadata,
+  Permission,
+} from "@checkmate-monitor/common";
+
+/**
+ * Extract the context type from a SlotDefinition
+ */
+export type SlotContext<T> = T extends SlotDefinition<infer C> ? C : never;
+
+/**
+ * Type-safe extension that infers component props from the slot definition.
+ */
+export interface Extension<
+  TSlot extends SlotDefinition<unknown> = SlotDefinition<unknown>
+> {
+  id: string;
+  slot: TSlot;
+  component: React.ComponentType<SlotContext<TSlot>>;
+}
+
+/**
+ * Helper to create a type-safe extension from a slot definition.
+ * This ensures the component props match the slot's expected context.
+ */
+export function createSlotExtension<TSlot extends SlotDefinition<unknown>>(
+  slot: TSlot,
+  extension: Omit<Extension<TSlot>, "slot">
+): Extension<TSlot> {
+  return {
+    ...extension,
+    slot,
+  };
+}
+
+/**
+ * Route configuration for a frontend plugin.
+ * Uses RouteDefinition from the plugin's common package.
+ */
+export interface PluginRoute {
+  /** Route definition from common package */
+  route: RouteDefinition;
+
+  /** React element to render */
+  element?: React.ReactNode;
+
+  /** Page title */
+  title?: string;
+
+  /** Permission required to access this route (use permission object from common package) */
+  permission?: Permission;
+}
+
+/**
+ * Frontend plugin configuration.
+ * Uses PluginMetadata from the common package for consistent plugin identification.
+ */
+export interface FrontendPlugin {
+  /** Plugin metadata from the common package (contains pluginId) */
+  metadata: PluginMetadata;
+  extensions?: Extension[];
+  apis?: {
+    ref: ApiRef<unknown>;
+    factory: (deps: { get: <T>(ref: ApiRef<T>) => T }) => unknown;
+  }[];
+  routes?: PluginRoute[];
+}
+
+export function createFrontendPlugin(plugin: FrontendPlugin): FrontendPlugin {
+  return plugin;
+}

package/src/slots.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { createSlot, SlotDefinition } from "./slots";
+import { pluginRegistry } from "./plugin-registry";
+import { createFrontendPlugin } from "./plugin";
+
+describe("createSlot", () => {
+  test("creates a slot definition with the correct id", () => {
+    const slot = createSlot("test.slot.id");
+    expect(slot.id).toBe("test.slot.id");
+  });
+
+  test("creates a slot definition with typed context", () => {
+    interface MyContext {
+      userId: string;
+      label: string;
+    }
+
+    const slot = createSlot<MyContext>("typed.slot");
+    expect(slot.id).toBe("typed.slot");
+
+    // Type check: slot._contextType should be assignable to MyContext
+    // This is a compile-time check, at runtime _contextType is undefined
+    const contextType: MyContext | undefined = slot._contextType;
+    expect(contextType).toBeUndefined();
+  });
+
+  test("creates slot with undefined context type by default", () => {
+    const slot = createSlot("simple.slot");
+    expect(slot.id).toBe("simple.slot");
+    expect(slot._contextType).toBeUndefined();
+  });
+});
+
+describe("Cross-Plugin Slot Usage", () => {
+  // Simulate: PluginA exposes a slot from its common package
+  const PluginASlot = createSlot<{ message: string }>("plugin-a.custom.slot");
+
+  // Simulate: PluginB creates an extension for PluginA's slot
+  const MockComponent = () => null;
+
+  beforeEach(() => {
+    pluginRegistry.reset();
+  });
+
+  afterEach(() => {
+    pluginRegistry.reset();
+  });
+
+  test("PluginB can register an extension to PluginA's exported slot", () => {
+    // PluginA would typically define its slot in its -common package
+    // e.g., export const PluginASlot = createSlot<...>("plugin-a.custom.slot")
+
+    // PluginB imports and uses the slot:
+    const pluginB = createFrontendPlugin({
+      metadata: { pluginId: "plugin-b" },
+      extensions: [
+        {
+          id: "plugin-b.extension-for-plugin-a",
+          slot: PluginASlot, // Using the SlotDefinition directly
+          component: MockComponent,
+        },
+      ],
+    });
+
+    pluginRegistry.register(pluginB);
+
+    // Verify the extension is registered to the correct slot
+    const extensions = pluginRegistry.getExtensions(PluginASlot.id);
+    expect(extensions).toHaveLength(1);
+    expect(extensions[0].id).toBe("plugin-b.extension-for-plugin-a");
+    expect(extensions[0].component).toBe(MockComponent);
+  });
+
+  test("multiple plugins can register extensions to the same slot", () => {
+    const MockComponentB = () => null;
+    const MockComponentC = () => null;
+
+    const pluginB = createFrontendPlugin({
+      metadata: { pluginId: "plugin-b" },
+      extensions: [
+        {
+          id: "plugin-b.extension",
+          slot: PluginASlot,
+          component: MockComponentB,
+        },
+      ],
+    });
+
+    const pluginC = createFrontendPlugin({
+      metadata: { pluginId: "plugin-c" },
+      extensions: [
+        {
+          id: "plugin-c.extension",
+          slot: PluginASlot,
+          component: MockComponentC,
+        },
+      ],
+    });
+
+    pluginRegistry.register(pluginB);
+    pluginRegistry.register(pluginC);
+
+    const extensions = pluginRegistry.getExtensions(PluginASlot.id);
+    expect(extensions).toHaveLength(2);
+    expect(extensions.map((e) => e.id)).toContain("plugin-b.extension");
+    expect(extensions.map((e) => e.id)).toContain("plugin-c.extension");
+  });
+
+  test("extensions are removed when plugin is unregistered", () => {
+    const pluginB = createFrontendPlugin({
+      metadata: { pluginId: "plugin-b" },
+      extensions: [
+        {
+          id: "plugin-b.extension",
+          slot: PluginASlot,
+          component: MockComponent,
+        },
+      ],
+    });
+
+    pluginRegistry.register(pluginB);
+    expect(pluginRegistry.getExtensions(PluginASlot.id)).toHaveLength(1);
+
+    pluginRegistry.unregister("plugin-b");
+    expect(pluginRegistry.getExtensions(PluginASlot.id)).toHaveLength(0);
+  });
+
+  test("slot id property is readonly and consistent", () => {
+    const slot1 = createSlot("consistent.slot");
+    const slot2 = createSlot("consistent.slot");
+
+    // Same id string creates equivalent slot references
+    expect(slot1.id).toBe(slot2.id);
+
+    // Extensions registered to either slot.id will be in the same collection
+    const pluginB = createFrontendPlugin({
+      metadata: { pluginId: "plugin-b" },
+      extensions: [
+        {
+          id: "plugin-b.ext1",
+          slot: slot1,
+          component: MockComponent,
+        },
+      ],
+    });
+
+    const pluginC = createFrontendPlugin({
+      metadata: { pluginId: "plugin-c" },
+      extensions: [
+        {
+          id: "plugin-c.ext2",
+          slot: slot2,
+          component: MockComponent,
+        },
+      ],
+    });
+
+    pluginRegistry.register(pluginB);
+    pluginRegistry.register(pluginC);
+
+    // Both extensions should be in the same slot
+    expect(pluginRegistry.getExtensions(slot1.id)).toHaveLength(2);
+    expect(pluginRegistry.getExtensions(slot2.id)).toHaveLength(2);
+  });
+});
+
+describe("SlotDefinition type safety", () => {
+  test("slot context type is preserved as phantom type", () => {
+    interface SystemContext {
+      systemId: string;
+      systemName: string;
+    }
+
+    const slot: SlotDefinition<SystemContext> =
+      createSlot<SystemContext>("system.details");
+
+    // The id is accessible
+    expect(slot.id).toBe("system.details");
+
+    // Type assertion to verify the phantom type is correct
+    // This is a compile-time check - the actual value is undefined
+    type ExtractedContext = NonNullable<typeof slot._contextType>;
+    const _typeCheck: ExtractedContext = { systemId: "1", systemName: "Test" };
+    expect(_typeCheck).toBeDefined();
+  });
+
+  test("createSlot with object context type", () => {
+    const slot = createSlot<{ count: number; items: string[] }>("complex.slot");
+    expect(slot.id).toBe("complex.slot");
+  });
+
+  test("createSlot without context type defaults to undefined", () => {
+    const slot = createSlot("no-context.slot");
+
+    // Type should be SlotDefinition<undefined>
+    // When NonNullable is applied to undefined, it becomes never
+    // This is just a compile-time type verification
+    expect(slot.id).toBe("no-context.slot");
+  });
+});

package/src/slots.ts

@@ -0,0 +1,48 @@
+/**
+ * A type-safe slot definition that can be exported from plugin common packages.
+ * The context type parameter defines what props extensions will receive.
+ */
+export interface SlotDefinition<TContext = undefined> {
+  /** Unique slot identifier, recommended format: "plugin-name.area.purpose" */
+  readonly id: string;
+  /** Phantom type for context type inference - do not use directly */
+  readonly _contextType?: TContext;
+}
+
+/**
+ * Creates a type-safe slot definition that can be exported from any package.
+ *
+ * @example
+ * // In @checkmate-monitor/catalog-common
+ * export const SystemDetailsSlot = createSlot<{ systemId: string }>(
+ *   "catalog.system.details"
+ * );
+ *
+ * // In your frontend plugin
+ * extensions: [{
+ *   id: "my-plugin.system-details",
+ *   slot: SystemDetailsSlot,
+ *   component: MySystemDetailsExtension, // Receives { systemId: string }
+ * }]
+ *
+ * @param id - Unique slot identifier
+ * @returns A slot definition that can be used for type-safe extension registration
+ */
+export function createSlot<TContext = undefined>(
+  id: string
+): SlotDefinition<TContext> {
+  return { id } as SlotDefinition<TContext>;
+}
+
+/**
+ * Core layout slots - no context required
+ */
+export const DashboardSlot = createSlot("dashboard");
+export const NavbarSlot = createSlot("core.layout.navbar");
+export const NavbarMainSlot = createSlot("core.layout.navbar.main");
+export const UserMenuItemsSlot = createSlot(
+  "core.layout.navbar.user-menu.items"
+);
+export const UserMenuItemsBottomSlot = createSlot(
+  "core.layout.navbar.user-menu.items.bottom"
+);

package/src/use-plugin-route.ts

@@ -0,0 +1,65 @@
+import { useCallback } from "react";
+import type { RouteDefinition } from "@checkmate-monitor/common";
+import { resolveRoute } from "@checkmate-monitor/common";
+import { pluginRegistry } from "./plugin-registry";
+
+/**
+ * React hook for resolving plugin routes to full paths.
+ *
+ * Can resolve routes in two ways:
+ * 1. Using a RouteDefinition object from a plugin's routes (type-safe, recommended)
+ * 2. Using a route ID string (for cross-plugin resolution)
+ *
+ * @example Using RouteDefinition (recommended)
+ * ```tsx
+ * import { maintenanceRoutes } from "@checkmate-monitor/maintenance-common";
+ *
+ * const MyComponent = () => {
+ *   const getRoute = usePluginRoute();
+ *
+ *   return (
+ *     <Link to={getRoute(maintenanceRoutes.routes.config)}>Config</Link>
+ *   );
+ * };
+ * ```
+ *
+ * @example With path parameters
+ * ```tsx
+ * const getRoute = usePluginRoute();
+ *
+ * // For a route like "/detail/:id"
+ * const detailPath = getRoute(maintenanceRoutes.routes.detail, { id: "123" });
+ * // Returns: "/maintenance/detail/123"
+ * ```
+ *
+ * @example Using route ID string (cross-plugin)
+ * ```tsx
+ * const path = getRoute("maintenance.config");
+ * ```
+ */
+export function usePluginRoute(): {
+  <TParams extends string>(
+    route: RouteDefinition<TParams>,
+    params?: TParams extends never ? never : Record<TParams, string>
+  ): string;
+  (routeId: string, params?: Record<string, string>): string | undefined;
+} {
+  return useCallback(
+    (
+      routeOrId: RouteDefinition | string,
+      params?: Record<string, string>
+    ): string | undefined => {
+      if (typeof routeOrId === "string") {
+        // Resolve by route ID through registry
+        return pluginRegistry.resolveRoute(routeOrId, params);
+      }
+      // Resolve using route definition directly
+      // Cast needed because overload signatures hide implementation details
+      if (params) {
+        return resolveRoute(routeOrId as RouteDefinition<string>, params);
+      }
+      return resolveRoute(routeOrId as RouteDefinition<never>);
+    },
+    []
+  ) as ReturnType<typeof usePluginRoute>;
+}

package/src/utils.tsx

@@ -0,0 +1,16 @@
+import React, { Suspense, ComponentType } from "react";
+
+export function wrapInSuspense<P extends object>(
+  Component: ComponentType<P>,
+  fallback: React.ReactNode = <div>Loading...</div>
+): React.FC<P> {
+  const WrappedComponent: React.FC<P> = (props) => (
+    <Suspense fallback={fallback}>
+      <Component {...props} />
+    </Suspense>
+  );
+  WrappedComponent.displayName = `Suspense(${
+    Component.displayName || Component.name || "Component"
+  })`;
+  return WrappedComponent;
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkmate-monitor/tsconfig/frontend.json",
+  "include": [
+    "src"
+  ]
+}