@kuckit/sdk-react 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,668 @@
+import { ComponentType, JSX, ReactNode } from "react";
+import { QueryClient } from "@tanstack/react-query";
+
+//#region src/types.d.ts
+
+/**
+ * Built-in capability types for common module features
+ */
+type BuiltInCapability = 'nav.item' | 'settings.page' | 'dashboard.widget' | 'api.webhook' | 'api.public' | 'slot.provider';
+/**
+ * Module capability type - built-in or custom
+ * Custom capabilities must be prefixed with 'custom.'
+ */
+type ModuleCapability = BuiltInCapability | `custom.${string}`;
+/**
+ * Module metadata for discovery and documentation
+ */
+interface KuckitClientModuleMeta {
+  /** Unique identifier, e.g., 'kuckit.users' or 'acme.billing' */
+  id: string;
+  /** Human-readable name */
+  displayName?: string;
+  /** Module description */
+  description?: string;
+  /** Module version */
+  version?: string;
+  /** Capabilities this module provides */
+  capabilities?: ModuleCapability[];
+}
+/**
+ * Metadata for a route definition
+ */
+interface RouteMeta {
+  /** Page title for document head */
+  title?: string;
+  /** Icon identifier (e.g., 'credit-card', 'users') */
+  icon?: string;
+  /** Whether this route requires authentication */
+  requiresAuth?: boolean;
+  /** Custom metadata */
+  [key: string]: unknown;
+}
+/**
+ * Route definition for module-provided routes
+ */
+interface RouteDefinition {
+  /** Unique route identifier */
+  id: string;
+  /**
+   * URL path for the route.
+   *
+   * The path convention determines where the route is rendered:
+   * - `/some-path` → Root level route (outside dashboard, no layout wrapper)
+   * - `/dashboard/some-path` → Dashboard route (wrapped in dashboard layout)
+   *
+   * Root-level routes are public by default. Use `meta.requiresAuth: true`
+   * to require authentication for root routes.
+   *
+   * @example '/cli/activate' // Root level, no dashboard wrapper
+   * @example '/dashboard/settings/profile' // Dashboard route with layout
+   */
+  path: string;
+  /** React component to render for this route */
+  component: ComponentType<unknown>;
+  /** Parent route ID (defaults to '__root__' if not specified) */
+  parentRouteId?: string;
+  /** Route metadata */
+  meta?: RouteMeta;
+}
+/**
+ * Navigation item for sidebar/header menus
+ */
+interface NavItem {
+  /** Unique identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Navigation path */
+  path: string;
+  /** Icon identifier (lucide-react icon name, e.g., 'credit-card', 'users') */
+  icon?: string;
+  /** Sort order (lower = higher priority) */
+  order?: number;
+  /** Parent nav item ID for nested navigation */
+  parentId?: string;
+  /** If true, show in main nav instead of "Modules" section */
+  showInMainNav?: boolean;
+  /** Badge text (e.g., "New", "Beta") */
+  badge?: string;
+}
+/**
+ * Options for slot registration
+ */
+interface SlotOptions {
+  /** Sort order (lower = higher priority, default: 100) */
+  order?: number;
+  /** Props to pass to the component */
+  props?: Record<string, unknown>;
+}
+/**
+ * Internal representation of a registered slot component
+ */
+interface SlotRegistration {
+  /** The slot name this component is registered to */
+  slotName: string;
+  /** The component to render */
+  component: ComponentType<unknown>;
+  /** Module that registered this component */
+  moduleId: string;
+  /** Sort order (lower = higher priority) */
+  order: number;
+  /** Props to pass to the component */
+  props?: Record<string, unknown>;
+}
+/**
+ * Context passed to client module hooks
+ */
+interface KuckitClientModuleContext {
+  /** oRPC client instance */
+  orpc: unknown;
+  /** TanStack Query client */
+  queryClient: QueryClient;
+  /** Environment name (development, production, etc.) */
+  env: string;
+  /** Register a component for use in the application */
+  registerComponent: (name: string, component: ComponentType<unknown>) => void;
+  /** Register a route that will be injected into the router */
+  addRoute: (route: RouteDefinition) => void;
+  /** Register a navigation item for sidebar/header menus */
+  addNavItem: (item: NavItem) => void;
+  /** Register a component into a named slot */
+  registerSlot: (slotName: string, component: ComponentType<unknown>, options?: SlotOptions) => void;
+}
+/**
+ * Client module lifecycle hooks
+ */
+interface KuckitClientModuleHooks {
+  /**
+   * Called when the module is registered
+   * Use this to register components, initialize state, etc.
+   */
+  register?(ctx: KuckitClientModuleContext): void | Promise<void>;
+  /**
+   * Called when the module is unloaded (optional)
+   * Use this for cleanup
+   */
+  onUnload?(): void | Promise<void>;
+}
+/**
+ * Complete client module definition combining metadata and hooks
+ */
+interface KuckitClientModuleDefinition extends KuckitClientModuleMeta, KuckitClientModuleHooks {}
+/**
+ * Client module specification in application config
+ *
+ * You can specify a module in two ways:
+ * 1. `module`: Direct reference to a module definition (preferred in monorepos)
+ * 2. `package`: NPM package path for dynamic import (for published packages)
+ */
+interface ClientModuleSpec {
+  /** Direct module definition (preferred in monorepos for better type safety) */
+  module?: KuckitClientModuleDefinition;
+  /** NPM package path for dynamic import, e.g., '@acme/billing-module/client' */
+  package?: string;
+  /** Whether to skip this module */
+  disabled?: boolean;
+}
+/**
+ * Internal type for loaded modules
+ */
+interface LoadedClientModule extends KuckitClientModuleDefinition {
+  _source: 'direct' | 'package';
+}
+//#endregion
+//#region src/define-module.d.ts
+/**
+ * Helper function to define a client module with type safety
+ *
+ * @example
+ * ```ts
+ * export const kuckitClientModule = defineKuckitClientModule({
+ *   id: 'acme.billing',
+ *   displayName: 'Billing',
+ *   version: '1.0.0',
+ *
+ *   register(ctx) {
+ *     ctx.registerComponent('BillingDashboard', BillingDashboard)
+ *     ctx.registerComponent('InvoiceList', InvoiceList)
+ *   },
+ * })
+ * ```
+ */
+declare function defineKuckitClientModule<T extends KuckitClientModuleDefinition>(mod: T): T;
+//#endregion
+//#region src/registry.d.ts
+/**
+ * Registry for module-provided routes
+ *
+ * Collects route definitions during module loading and provides
+ * methods to build a TanStack Router route tree.
+ */
+declare class RouteRegistry {
+  private routes;
+  private frozen;
+  /**
+   * Register a route definition
+   * @throws Error if registry is frozen or route ID already exists
+   */
+  add(route: RouteDefinition): void;
+  /**
+   * Get all registered routes
+   */
+  getAll(): RouteDefinition[];
+  /**
+   * Get a route by ID
+   */
+  get(id: string): RouteDefinition | undefined;
+  /**
+   * Check if a route is registered
+   */
+  has(id: string): boolean;
+  /**
+   * Get routes grouped by parent ID
+   */
+  getByParent(parentId?: string): RouteDefinition[];
+  /**
+   * Freeze the registry to prevent further modifications
+   */
+  freeze(): void;
+  /**
+   * Check if registry is frozen
+   */
+  isFrozen(): boolean;
+  /**
+   * Get the number of registered routes
+   */
+  get size(): number;
+  /**
+   * Clear all routes (only works if not frozen)
+   */
+  clear(): void;
+}
+/**
+ * Registry for module-provided navigation items
+ *
+ * Collects nav items during module loading and provides
+ * methods to build navigation menus.
+ */
+declare class NavRegistry {
+  private items;
+  private frozen;
+  /**
+   * Register a navigation item
+   * @throws Error if registry is frozen or item ID already exists
+   */
+  add(item: NavItem): void;
+  /**
+   * Get all registered navigation items, sorted by order
+   */
+  getAll(): NavItem[];
+  /**
+   * Get a navigation item by ID
+   */
+  get(id: string): NavItem | undefined;
+  /**
+   * Check if a nav item is registered
+   */
+  has(id: string): boolean;
+  /**
+   * Get top-level navigation items (no parent)
+   */
+  getTopLevel(): NavItem[];
+  /**
+   * Get nav items that should appear in main navigation
+   * (items with showInMainNav === true)
+   */
+  getMainNavItems(): NavItem[];
+  /**
+   * Get module nav items (not in main nav)
+   * (items without showInMainNav or showInMainNav === false)
+   */
+  getModuleNavItems(): NavItem[];
+  /**
+   * Get child navigation items for a parent
+   */
+  getChildren(parentId: string): NavItem[];
+  /**
+   * Build a hierarchical navigation tree
+   */
+  buildTree(): NavTreeItem[];
+  private buildTreeItem;
+  /**
+   * Freeze the registry to prevent further modifications
+   */
+  freeze(): void;
+  /**
+   * Check if registry is frozen
+   */
+  isFrozen(): boolean;
+  /**
+   * Get the number of registered items
+   */
+  get size(): number;
+  /**
+   * Clear all items (only works if not frozen)
+   */
+  clear(): void;
+}
+/**
+ * Registry for module-provided slot components
+ *
+ * Collects components registered to named slots during module loading
+ * and provides methods to retrieve them for rendering.
+ */
+declare class SlotRegistry {
+  private slots;
+  private frozen;
+  /**
+   * Register a component into a named slot
+   * @throws Error if registry is frozen
+   */
+  add(slotName: string, component: ComponentType<unknown>, moduleId: string, options?: SlotOptions): void;
+  /**
+   * Get all components registered to a slot, sorted by order
+   */
+  getSlot(name: string): SlotRegistration[];
+  /**
+   * Check if a slot has any components registered
+   */
+  hasSlot(name: string): boolean;
+  /**
+   * Get all slot names that have components registered
+   */
+  getSlotNames(): string[];
+  /**
+   * Get total number of registered components across all slots
+   */
+  get size(): number;
+  /**
+   * Freeze the registry to prevent further modifications
+   */
+  freeze(): void;
+  /**
+   * Check if registry is frozen
+   */
+  isFrozen(): boolean;
+  /**
+   * Clear all slots (only works if not frozen)
+   */
+  clear(): void;
+}
+/**
+ * Hierarchical navigation tree item
+ */
+interface NavTreeItem extends NavItem {
+  children?: NavTreeItem[];
+}
+/**
+ * Provider component for Kuckit navigation
+ */
+interface KuckitNavProviderProps {
+  registry: NavRegistry;
+  children: ReactNode;
+}
+declare function KuckitNavProvider({
+  registry,
+  children
+}: KuckitNavProviderProps): ReactNode;
+/**
+ * Hook to access navigation items
+ */
+declare function useKuckitNav(): NavRegistry;
+/**
+ * Hook to get sorted navigation items
+ */
+declare function useNavItems(): NavItem[];
+/**
+ * Hook to get hierarchical navigation tree
+ */
+declare function useNavTree(): NavTreeItem[];
+/**
+ * Create a component registry for storing named components
+ */
+declare function createComponentRegistry(): ComponentRegistry;
+interface ComponentRegistry {
+  register: (name: string, component: ComponentType<unknown>) => void;
+  get: (name: string) => ComponentType<unknown> | undefined;
+  has: (name: string) => boolean;
+  getAll: () => Map<string, ComponentType<unknown>>;
+}
+/**
+ * Information about a loaded client module
+ */
+interface LoadedClientModuleInfo {
+  /** Module unique identifier */
+  id: string;
+  /** Human-readable name */
+  displayName?: string;
+  /** Module description */
+  description?: string;
+  /** Module version */
+  version?: string;
+  /** Capabilities this module provides */
+  capabilities: ModuleCapability[];
+}
+/**
+ * Registry for loaded Kuckit client modules
+ *
+ * Tracks all loaded modules and their capabilities for querying.
+ */
+declare class ClientModuleRegistry {
+  private modules;
+  private frozen;
+  /**
+   * Register a loaded module
+   * @throws Error if registry is frozen or module ID already exists
+   */
+  register(module: KuckitClientModuleDefinition): void;
+  /**
+   * Get all registered modules
+   */
+  getAll(): LoadedClientModuleInfo[];
+  /**
+   * Get a module by ID
+   */
+  getById(id: string): LoadedClientModuleInfo | undefined;
+  /**
+   * Check if a module is registered
+   */
+  has(id: string): boolean;
+  /**
+   * Get all modules that have a specific capability
+   */
+  getWithCapability(capability: ModuleCapability): LoadedClientModuleInfo[];
+  /**
+   * Check if a specific module has a capability
+   */
+  hasCapability(moduleId: string, capability: ModuleCapability): boolean;
+  /**
+   * Get all unique capabilities across all modules
+   */
+  getAllCapabilities(): ModuleCapability[];
+  /**
+   * Freeze the registry to prevent further modifications
+   */
+  freeze(): void;
+  /**
+   * Check if registry is frozen
+   */
+  isFrozen(): boolean;
+  /**
+   * Get the number of registered modules
+   */
+  get size(): number;
+  /**
+   * Clear all modules (only works if not frozen)
+   */
+  clear(): void;
+}
+/**
+ * Get the global client module registry
+ * Creates one if it doesn't exist
+ */
+declare function getClientModuleRegistry(): ClientModuleRegistry;
+/**
+ * Get all client modules that have a specific capability
+ * Convenience function that uses the global registry
+ */
+declare function getClientModulesWithCapability(capability: ModuleCapability): LoadedClientModuleInfo[];
+/**
+ * Reset the global client registry (mainly for testing)
+ */
+declare function resetClientModuleRegistry(): void;
+/**
+ * Factory function to create fresh registries
+ */
+declare function createRegistries(): {
+  routeRegistry: RouteRegistry;
+  navRegistry: NavRegistry;
+  componentRegistry: ComponentRegistry;
+  slotRegistry: SlotRegistry;
+  moduleRegistry: ClientModuleRegistry;
+};
+//#endregion
+//#region src/loader.d.ts
+interface LoadClientModulesOptions {
+  /** oRPC client instance */
+  orpc: unknown;
+  /** TanStack Query client */
+  queryClient: QueryClient;
+  /** Environment name (development, production, etc.) */
+  env: string;
+  /** List of client modules to load */
+  modules: ClientModuleSpec[];
+  /** Callback when a component is registered (deprecated, use result.componentRegistry) */
+  onRegisterComponent?: (name: string, component: ComponentType<unknown>) => void;
+  /** Callback when a route is registered (deprecated, use result.routeRegistry) */
+  onRegisterRoute?: (route: RouteDefinition) => void;
+  /** Callback when a nav item is registered (deprecated, use result.navRegistry) */
+  onRegisterNavItem?: (item: NavItem) => void;
+  /** Callback when a slot component is registered (deprecated, use result.slotRegistry) */
+  onRegisterSlot?: (slotName: string, component: ComponentType<unknown>, moduleId: string, options?: SlotOptions) => void;
+  /** Hook called when all modules are loaded */
+  onComplete?: (result: LoadClientModulesResult) => void | Promise<void>;
+}
+/**
+ * Result of loading client modules
+ */
+interface LoadClientModulesResult {
+  /** All successfully loaded modules */
+  modules: LoadedClientModule[];
+  /** Registry containing all registered routes */
+  routeRegistry: RouteRegistry;
+  /** Registry containing all navigation items */
+  navRegistry: NavRegistry;
+  /** Registry containing all registered components */
+  componentRegistry: ComponentRegistry;
+  /** Registry containing all slot registrations */
+  slotRegistry: SlotRegistry;
+  /** Registry containing module info and capabilities */
+  moduleRegistry: ClientModuleRegistry;
+}
+/**
+ * Load and initialize Kuckit client modules
+ *
+ * This function orchestrates the client module loading lifecycle:
+ *
+ * 1. **Import Phase**: Dynamic import each module package (or use direct reference)
+ * 2. **Register Phase**: Run register() hooks with context (routes, nav, components, slots)
+ * 3. **Finalize Phase**: Freeze registries and call onComplete
+ *
+ * @example
+ * ```tsx
+ * const { modules, routeRegistry, navRegistry, slotRegistry, moduleRegistry } = await loadKuckitClientModules({
+ *   orpc,
+ *   queryClient,
+ *   env: 'production',
+ *   modules: [
+ *     { package: '@acme/billing-module/client' },
+ *     { module: myLocalModule },
+ *   ],
+ * })
+ *
+ * // Use routeRegistry to build TanStack Router routes
+ * const moduleRoutes = routeRegistry.getAll()
+ *
+ * // Use navRegistry for sidebar navigation
+ * const navItems = navRegistry.getAll()
+ *
+ * // Use slotRegistry with KuckitSlot component
+ * <KuckitSlot name="dashboard.widgets" />
+ *
+ * // Query modules by capability
+ * const navModules = moduleRegistry.getWithCapability('nav.item')
+ * ```
+ */
+declare const loadKuckitClientModules: (opts: LoadClientModulesOptions) => Promise<LoadClientModulesResult>;
+/**
+ * Create an unload handler for loaded client modules
+ *
+ * Returns a function that calls onUnload() on all modules in reverse order.
+ *
+ * @example
+ * ```ts
+ * const unload = createClientModuleUnloadHandler(loadedModules)
+ *
+ * // When cleaning up (e.g., HMR, route unmount)
+ * await unload()
+ * ```
+ */
+declare const createClientModuleUnloadHandler: (modules: LoadedClientModule[]) => (() => Promise<void>);
+//#endregion
+//#region src/slots.d.ts
+/**
+ * Provider component for Kuckit slots
+ */
+interface KuckitSlotProviderProps {
+  registry: SlotRegistry;
+  children: ReactNode;
+}
+declare function KuckitSlotProvider({
+  registry,
+  children
+}: KuckitSlotProviderProps): ReactNode;
+/**
+ * Hook to access the slot registry
+ */
+declare function useSlotRegistry(): SlotRegistry;
+/**
+ * Hook to get components registered to a specific slot
+ */
+declare function useSlot(name: string): SlotRegistration[];
+/**
+ * Hook to check if a slot has any components
+ */
+declare function useHasSlot(name: string): boolean;
+/**
+ * Props for the KuckitSlot component
+ */
+interface KuckitSlotProps {
+  /** The name of the slot to render */
+  name: string;
+  /** Content to show when no components are registered */
+  fallback?: ReactNode;
+  /** CSS class name for the wrapper element */
+  wrapperClassName?: string;
+  /** Tag name for the wrapper element (default: none, renders fragments) */
+  wrapperTag?: keyof JSX.IntrinsicElements;
+  /** Additional props to pass to all slot components */
+  slotProps?: Record<string, unknown>;
+}
+/**
+ * Component that renders all components registered to a named slot
+ *
+ * @example
+ * ```tsx
+ * // In host app layout
+ * <KuckitSlot name="dashboard.widgets" />
+ *
+ * // With fallback
+ * <KuckitSlot name="settings.tabs" fallback={<EmptyState />} />
+ *
+ * // With wrapper
+ * <KuckitSlot name="nav.items" wrapperTag="nav" wrapperClassName="flex gap-2" />
+ * ```
+ */
+declare function KuckitSlot({
+  name,
+  fallback,
+  wrapperClassName,
+  wrapperTag,
+  slotProps
+}: KuckitSlotProps): ReactNode;
+//#endregion
+//#region src/rpc-context.d.ts
+/**
+ * Provider component for Kuckit RPC client
+ */
+interface KuckitRpcProviderProps {
+  /** The oRPC client instance */
+  client: unknown;
+  children: ReactNode;
+}
+declare function KuckitRpcProvider({
+  client,
+  children
+}: KuckitRpcProviderProps): ReactNode;
+/**
+ * Hook to access the RPC client
+ *
+ * @example
+ * ```tsx
+ * import { useRpc } from '@kuckit/sdk-react'
+ * import type { AppRouterClient } from '@kuckit/api/routers/index'
+ *
+ * function MyComponent() {
+ *   const rpc = useRpc<AppRouterClient>()
+ *   const result = await rpc.myRouter.myProcedure({ input: 'value' })
+ * }
+ * ```
+ */
+declare function useRpc<T = unknown>(): T;
+/**
+ * Hook to check if RPC client is available
+ */
+declare function useHasRpc(): boolean;
+//#endregion
+export { type BuiltInCapability, ClientModuleRegistry, type ClientModuleSpec, type ComponentRegistry, type KuckitClientModuleContext, type KuckitClientModuleDefinition, type KuckitClientModuleHooks, type KuckitClientModuleMeta, KuckitNavProvider, KuckitRpcProvider, type KuckitRpcProviderProps, KuckitSlot, type KuckitSlotProps, KuckitSlotProvider, type KuckitSlotProviderProps, type LoadClientModulesOptions, type LoadClientModulesResult, type LoadedClientModule, type LoadedClientModuleInfo, type ModuleCapability, type NavItem, NavRegistry, type NavTreeItem, type RouteDefinition, type RouteMeta, RouteRegistry, type SlotOptions, type SlotRegistration, SlotRegistry, createClientModuleUnloadHandler, createComponentRegistry, createRegistries, defineKuckitClientModule, getClientModuleRegistry, getClientModulesWithCapability, loadKuckitClientModules, resetClientModuleRegistry, useHasRpc, useHasSlot, useKuckitNav, useNavItems, useNavTree, useRpc, useSlot, useSlotRegistry };