@kuckit/sdk-react 1.0.0

package/dist/index.js

@@ -0,0 +1,700 @@
+import { Fragment, createContext, createElement, useContext } from "react";
+
+//#region src/define-module.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)
+*   },
+* })
+* ```
+*/
+function defineKuckitClientModule(mod) {
+	return mod;
+}
+
+//#endregion
+//#region src/registry.ts
+/**
+* Registry for module-provided routes
+*
+* Collects route definitions during module loading and provides
+* methods to build a TanStack Router route tree.
+*/
+var RouteRegistry = class {
+	routes = /* @__PURE__ */ new Map();
+	frozen = false;
+	/**
+	* Register a route definition
+	* @throws Error if registry is frozen or route ID already exists
+	*/
+	add(route) {
+		if (this.frozen) throw new Error(`RouteRegistry is frozen. Cannot add route "${route.id}" after finalization.`);
+		if (this.routes.has(route.id)) throw new Error(`Route with ID "${route.id}" is already registered.`);
+		this.routes.set(route.id, route);
+	}
+	/**
+	* Get all registered routes
+	*/
+	getAll() {
+		return Array.from(this.routes.values());
+	}
+	/**
+	* Get a route by ID
+	*/
+	get(id) {
+		return this.routes.get(id);
+	}
+	/**
+	* Check if a route is registered
+	*/
+	has(id) {
+		return this.routes.has(id);
+	}
+	/**
+	* Get routes grouped by parent ID
+	*/
+	getByParent(parentId = "__root__") {
+		return this.getAll().filter((r) => (r.parentRouteId ?? "__root__") === parentId);
+	}
+	/**
+	* Freeze the registry to prevent further modifications
+	*/
+	freeze() {
+		this.frozen = true;
+	}
+	/**
+	* Check if registry is frozen
+	*/
+	isFrozen() {
+		return this.frozen;
+	}
+	/**
+	* Get the number of registered routes
+	*/
+	get size() {
+		return this.routes.size;
+	}
+	/**
+	* Clear all routes (only works if not frozen)
+	*/
+	clear() {
+		if (this.frozen) throw new Error("RouteRegistry is frozen. Cannot clear routes.");
+		this.routes.clear();
+	}
+};
+/**
+* Registry for module-provided navigation items
+*
+* Collects nav items during module loading and provides
+* methods to build navigation menus.
+*/
+var NavRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	frozen = false;
+	/**
+	* Register a navigation item
+	* @throws Error if registry is frozen or item ID already exists
+	*/
+	add(item) {
+		if (this.frozen) throw new Error(`NavRegistry is frozen. Cannot add item "${item.id}" after finalization.`);
+		if (this.items.has(item.id)) throw new Error(`Navigation item with ID "${item.id}" is already registered.`);
+		this.items.set(item.id, item);
+	}
+	/**
+	* Get all registered navigation items, sorted by order
+	*/
+	getAll() {
+		return Array.from(this.items.values()).sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+	}
+	/**
+	* Get a navigation item by ID
+	*/
+	get(id) {
+		return this.items.get(id);
+	}
+	/**
+	* Check if a nav item is registered
+	*/
+	has(id) {
+		return this.items.has(id);
+	}
+	/**
+	* Get top-level navigation items (no parent)
+	*/
+	getTopLevel() {
+		return this.getAll().filter((item) => !item.parentId);
+	}
+	/**
+	* Get nav items that should appear in main navigation
+	* (items with showInMainNav === true)
+	*/
+	getMainNavItems() {
+		return this.getAll().filter((item) => !item.parentId && item.showInMainNav === true);
+	}
+	/**
+	* Get module nav items (not in main nav)
+	* (items without showInMainNav or showInMainNav === false)
+	*/
+	getModuleNavItems() {
+		return this.getAll().filter((item) => !item.parentId && item.showInMainNav !== true);
+	}
+	/**
+	* Get child navigation items for a parent
+	*/
+	getChildren(parentId) {
+		return this.getAll().filter((item) => item.parentId === parentId);
+	}
+	/**
+	* Build a hierarchical navigation tree
+	*/
+	buildTree() {
+		return this.getTopLevel().map((item) => this.buildTreeItem(item));
+	}
+	buildTreeItem(item) {
+		const children = this.getChildren(item.id);
+		return {
+			...item,
+			children: children.length > 0 ? children.map((c) => this.buildTreeItem(c)) : void 0
+		};
+	}
+	/**
+	* Freeze the registry to prevent further modifications
+	*/
+	freeze() {
+		this.frozen = true;
+	}
+	/**
+	* Check if registry is frozen
+	*/
+	isFrozen() {
+		return this.frozen;
+	}
+	/**
+	* Get the number of registered items
+	*/
+	get size() {
+		return this.items.size;
+	}
+	/**
+	* Clear all items (only works if not frozen)
+	*/
+	clear() {
+		if (this.frozen) throw new Error("NavRegistry is frozen. Cannot clear items.");
+		this.items.clear();
+	}
+};
+/**
+* Registry for module-provided slot components
+*
+* Collects components registered to named slots during module loading
+* and provides methods to retrieve them for rendering.
+*/
+var SlotRegistry = class {
+	slots = /* @__PURE__ */ new Map();
+	frozen = false;
+	/**
+	* Register a component into a named slot
+	* @throws Error if registry is frozen
+	*/
+	add(slotName, component, moduleId, options) {
+		if (this.frozen) throw new Error(`SlotRegistry is frozen. Cannot add to slot "${slotName}" after finalization.`);
+		const registration = {
+			slotName,
+			component,
+			moduleId,
+			order: options?.order ?? 100,
+			props: options?.props
+		};
+		const existing = this.slots.get(slotName);
+		if (existing) existing.push(registration);
+		else this.slots.set(slotName, [registration]);
+	}
+	/**
+	* Get all components registered to a slot, sorted by order
+	*/
+	getSlot(name) {
+		return [...this.slots.get(name) ?? []].sort((a, b) => a.order - b.order);
+	}
+	/**
+	* Check if a slot has any components registered
+	*/
+	hasSlot(name) {
+		const registrations = this.slots.get(name);
+		return registrations !== void 0 && registrations.length > 0;
+	}
+	/**
+	* Get all slot names that have components registered
+	*/
+	getSlotNames() {
+		return Array.from(this.slots.keys());
+	}
+	/**
+	* Get total number of registered components across all slots
+	*/
+	get size() {
+		let count = 0;
+		for (const registrations of this.slots.values()) count += registrations.length;
+		return count;
+	}
+	/**
+	* Freeze the registry to prevent further modifications
+	*/
+	freeze() {
+		this.frozen = true;
+	}
+	/**
+	* Check if registry is frozen
+	*/
+	isFrozen() {
+		return this.frozen;
+	}
+	/**
+	* Clear all slots (only works if not frozen)
+	*/
+	clear() {
+		if (this.frozen) throw new Error("SlotRegistry is frozen. Cannot clear slots.");
+		this.slots.clear();
+	}
+};
+/**
+* Context for navigation registry
+*/
+const NavContext = createContext(null);
+function KuckitNavProvider({ registry, children }) {
+	return createElement(NavContext.Provider, { value: registry }, children);
+}
+/**
+* Hook to access navigation items
+*/
+function useKuckitNav() {
+	const ctx = useContext(NavContext);
+	if (!ctx) throw new Error("useKuckitNav must be used within a KuckitNavProvider");
+	return ctx;
+}
+/**
+* Hook to get sorted navigation items
+*/
+function useNavItems() {
+	return useKuckitNav().getAll();
+}
+/**
+* Hook to get hierarchical navigation tree
+*/
+function useNavTree() {
+	return useKuckitNav().buildTree();
+}
+/**
+* Create a component registry for storing named components
+*/
+function createComponentRegistry() {
+	const components = /* @__PURE__ */ new Map();
+	return {
+		register: (name, component) => {
+			if (components.has(name)) console.warn(`Component "${name}" is already registered. Overwriting.`);
+			components.set(name, component);
+		},
+		get: (name) => components.get(name),
+		has: (name) => components.has(name),
+		getAll: () => new Map(components)
+	};
+}
+/**
+* Validates that a capability string matches expected patterns
+*/
+const isValidCapability = (cap) => {
+	if ([
+		"nav.item",
+		"settings.page",
+		"dashboard.widget",
+		"api.webhook",
+		"api.public",
+		"slot.provider"
+	].includes(cap)) return true;
+	if (cap.startsWith("custom.") && cap.length > 7) return true;
+	return false;
+};
+/**
+* Registry for loaded Kuckit client modules
+*
+* Tracks all loaded modules and their capabilities for querying.
+*/
+var ClientModuleRegistry = class {
+	modules = /* @__PURE__ */ new Map();
+	frozen = false;
+	/**
+	* Register a loaded module
+	* @throws Error if registry is frozen or module ID already exists
+	*/
+	register(module) {
+		if (this.frozen) throw new Error(`ClientModuleRegistry is frozen. Cannot register module "${module.id}" after finalization.`);
+		if (this.modules.has(module.id)) throw new Error(`Module with ID "${module.id}" is already registered.`);
+		const capabilities = module.capabilities ?? [];
+		for (const cap of capabilities) if (!isValidCapability(cap)) throw new Error(`Invalid capability "${cap}" in module "${module.id}". Capabilities must be built-in (nav.item, settings.page, etc.) or custom.* prefixed.`);
+		this.modules.set(module.id, {
+			id: module.id,
+			displayName: module.displayName,
+			description: module.description,
+			version: module.version,
+			capabilities
+		});
+	}
+	/**
+	* Get all registered modules
+	*/
+	getAll() {
+		return Array.from(this.modules.values());
+	}
+	/**
+	* Get a module by ID
+	*/
+	getById(id) {
+		return this.modules.get(id);
+	}
+	/**
+	* Check if a module is registered
+	*/
+	has(id) {
+		return this.modules.has(id);
+	}
+	/**
+	* Get all modules that have a specific capability
+	*/
+	getWithCapability(capability) {
+		return this.getAll().filter((mod) => mod.capabilities.includes(capability));
+	}
+	/**
+	* Check if a specific module has a capability
+	*/
+	hasCapability(moduleId, capability) {
+		const module = this.modules.get(moduleId);
+		return module ? module.capabilities.includes(capability) : false;
+	}
+	/**
+	* Get all unique capabilities across all modules
+	*/
+	getAllCapabilities() {
+		const caps = /* @__PURE__ */ new Set();
+		for (const mod of this.modules.values()) for (const cap of mod.capabilities) caps.add(cap);
+		return Array.from(caps);
+	}
+	/**
+	* Freeze the registry to prevent further modifications
+	*/
+	freeze() {
+		this.frozen = true;
+	}
+	/**
+	* Check if registry is frozen
+	*/
+	isFrozen() {
+		return this.frozen;
+	}
+	/**
+	* Get the number of registered modules
+	*/
+	get size() {
+		return this.modules.size;
+	}
+	/**
+	* Clear all modules (only works if not frozen)
+	*/
+	clear() {
+		if (this.frozen) throw new Error("ClientModuleRegistry is frozen. Cannot clear modules.");
+		this.modules.clear();
+	}
+};
+let globalClientRegistry = null;
+/**
+* Get the global client module registry
+* Creates one if it doesn't exist
+*/
+function getClientModuleRegistry() {
+	if (!globalClientRegistry) globalClientRegistry = new ClientModuleRegistry();
+	return globalClientRegistry;
+}
+/**
+* Get all client modules that have a specific capability
+* Convenience function that uses the global registry
+*/
+function getClientModulesWithCapability(capability) {
+	return getClientModuleRegistry().getWithCapability(capability);
+}
+/**
+* Reset the global client registry (mainly for testing)
+*/
+function resetClientModuleRegistry() {
+	globalClientRegistry = null;
+}
+/**
+* Factory function to create fresh registries
+*/
+function createRegistries() {
+	return {
+		routeRegistry: new RouteRegistry(),
+		navRegistry: new NavRegistry(),
+		componentRegistry: createComponentRegistry(),
+		slotRegistry: new SlotRegistry(),
+		moduleRegistry: new ClientModuleRegistry()
+	};
+}
+
+//#endregion
+//#region src/loader.ts
+/**
+* Validates that a module has the correct shape
+*/
+const validateModule = (candidate, source) => {
+	if (!candidate || typeof candidate !== "object") throw new Error(`Invalid Kuckit client module from "${source}": expected an object with module definition`);
+	const mod = candidate;
+	if (!mod.id || typeof mod.id !== "string") throw new Error(`Invalid Kuckit client module from "${source}": missing or invalid 'id' property`);
+	if (mod.register !== void 0 && typeof mod.register !== "function") throw new Error(`Invalid Kuckit client module from "${source}": 'register' must be a function`);
+	if (mod.onUnload !== void 0 && typeof mod.onUnload !== "function") throw new Error(`Invalid Kuckit client module from "${source}": 'onUnload' must be a function`);
+	return mod;
+};
+/**
+* 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')
+* ```
+*/
+const loadKuckitClientModules = async (opts) => {
+	const { orpc, queryClient, env, modules, onRegisterComponent, onRegisterRoute, onRegisterNavItem, onRegisterSlot, onComplete } = opts;
+	const loadedModules = [];
+	const routeRegistry = new RouteRegistry();
+	const navRegistry = new NavRegistry();
+	const componentRegistry = createComponentRegistry();
+	const slotRegistry = new SlotRegistry();
+	const moduleRegistry = getClientModuleRegistry();
+	for (const spec of modules) {
+		if (spec.disabled) continue;
+		let validated;
+		let source;
+		if (spec.module) {
+			validated = validateModule(spec.module, spec.module.id ?? "direct-module");
+			source = "direct";
+		} else if (spec.package) {
+			let imported;
+			try {
+				imported = await import(
+					/* @vite-ignore */
+					spec.package
+);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				throw new Error(`Failed to import client module "${spec.package}": ${message}`);
+			}
+			validated = validateModule(imported.kuckitClientModule ?? imported.default, spec.package);
+			source = "package";
+		} else throw new Error("ClientModuleSpec must have either \"module\" or \"package\" property");
+		moduleRegistry.register(validated);
+		loadedModules.push({
+			...validated,
+			_source: source
+		});
+	}
+	for (const mod of loadedModules) if (mod.register) {
+		const ctx = {
+			orpc,
+			queryClient,
+			env,
+			registerComponent: (name, component) => {
+				componentRegistry.register(name, component);
+				onRegisterComponent?.(name, component);
+			},
+			addRoute: (route) => {
+				routeRegistry.add(route);
+				onRegisterRoute?.(route);
+			},
+			addNavItem: (item) => {
+				navRegistry.add(item);
+				onRegisterNavItem?.(item);
+			},
+			registerSlot: (slotName, component, options) => {
+				slotRegistry.add(slotName, component, mod.id, options);
+				onRegisterSlot?.(slotName, component, mod.id, options);
+			}
+		};
+		try {
+			await mod.register(ctx);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`Client module "${mod.id}" register() failed: ${message}`);
+		}
+	}
+	routeRegistry.freeze();
+	navRegistry.freeze();
+	slotRegistry.freeze();
+	const result = {
+		modules: loadedModules,
+		routeRegistry,
+		navRegistry,
+		componentRegistry,
+		slotRegistry,
+		moduleRegistry
+	};
+	if (onComplete) await onComplete(result);
+	return result;
+};
+/**
+* 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()
+* ```
+*/
+const createClientModuleUnloadHandler = (modules) => {
+	return async () => {
+		for (const mod of [...modules].reverse()) if (mod.onUnload) try {
+			await mod.onUnload();
+		} catch (error) {
+			console.error(`Client module "${mod.id}" onUnload() failed:`, error);
+		}
+	};
+};
+
+//#endregion
+//#region src/slots.ts
+/**
+* Context for slot registry
+*/
+const SlotContext = createContext(null);
+function KuckitSlotProvider({ registry, children }) {
+	return createElement(SlotContext.Provider, { value: registry }, children);
+}
+/**
+* Hook to access the slot registry
+*/
+function useSlotRegistry() {
+	const ctx = useContext(SlotContext);
+	if (!ctx) throw new Error("useSlotRegistry must be used within a KuckitSlotProvider");
+	return ctx;
+}
+/**
+* Hook to get components registered to a specific slot
+*/
+function useSlot(name) {
+	return useSlotRegistry().getSlot(name);
+}
+/**
+* Hook to check if a slot has any components
+*/
+function useHasSlot(name) {
+	return useSlotRegistry().hasSlot(name);
+}
+/**
+* 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" />
+* ```
+*/
+function KuckitSlot({ name, fallback, wrapperClassName, wrapperTag, slotProps }) {
+	const ctx = useContext(SlotContext);
+	if (!ctx) return fallback ?? null;
+	const registrations = ctx.getSlot(name);
+	if (registrations.length === 0) return fallback ?? null;
+	const rendered = registrations.map((reg, index) => {
+		const Component = reg.component;
+		const combinedProps = {
+			...reg.props,
+			...slotProps
+		};
+		return createElement(Component, {
+			key: `${reg.moduleId}-${index}`,
+			...combinedProps
+		});
+	});
+	if (wrapperTag) return createElement(wrapperTag, { className: wrapperClassName }, rendered);
+	if (wrapperClassName) return createElement("div", { className: wrapperClassName }, rendered);
+	return createElement(Fragment, null, rendered);
+}
+
+//#endregion
+//#region src/rpc-context.ts
+/**
+* Context for RPC client access
+*/
+const RpcContext = createContext(null);
+function KuckitRpcProvider({ client, children }) {
+	return createElement(RpcContext.Provider, { value: client }, children);
+}
+/**
+* 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' })
+* }
+* ```
+*/
+function useRpc() {
+	const ctx = useContext(RpcContext);
+	if (!ctx) throw new Error("useRpc must be used within a KuckitRpcProvider");
+	return ctx;
+}
+/**
+* Hook to check if RPC client is available
+*/
+function useHasRpc() {
+	return useContext(RpcContext) !== null;
+}
+
+//#endregion
+export { ClientModuleRegistry, KuckitNavProvider, KuckitRpcProvider, KuckitSlot, KuckitSlotProvider, NavRegistry, RouteRegistry, SlotRegistry, createClientModuleUnloadHandler, createComponentRegistry, createRegistries, defineKuckitClientModule, getClientModuleRegistry, getClientModulesWithCapability, loadKuckitClientModules, resetClientModuleRegistry, useHasRpc, useHasSlot, useKuckitNav, useNavItems, useNavTree, useRpc, useSlot, useSlotRegistry };