@ikonai/sdk-react-ui 0.0.28 → 0.0.31

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@ikonai/sdk-react-ui",
-  "version": "0.0.28",
+  "version": "0.0.31",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
+  "sideEffects": false,
   "exports": {
     ".": {
       "import": "./index.js",

package/renderer/index.d.ts

@@ -1,4 +1,6 @@
-export { UiRenderer, type UiRendererProps } from './ui-renderer';
+export { UiRenderer, type UiRendererProps, renderChildren } from './ui-renderer';
 export { UiComponentRegistry, createComponentLibrary, } from './component-library';
 export { useUiStore } from './use-ui-store';
+export { useUiNode } from './use-ui-node';
+export { useRootView } from './use-root-view';
 export type { UiComponentRenderer, UiComponentLibrary, UiNode, UiRenderContext, UiComponentRendererProps, ParsedUiUpdate, UiSnapshot, UiFullSnapshot, UiDiffSnapshot, UiNodeDiff, TextDelta, UiNodeProps, UiUpdateType, UiStoreSnapshot, UiOptimisticPatchState, } from './types';

package/renderer/types.d.ts

@@ -1,22 +1,43 @@
-import { UIPayload } from '../../../../shared/generated/src/index.ts';
-import { UiNode } from '../../../sdk-ui/src/index.ts';
+import { UIPayload } from '../../../../shared/protocol/src/index.ts';
+import { HandlerCache, UiNode, UiStreamStore } from '../../../sdk-ui/src/index.ts';
 import { IkonClient, IkonVideoPlayback } from '../../../sdk/src/index.ts';
 import { ComponentType, ReactNode } from 'react';
 export { type UiUpdateType, type UiNodeProps, type UiNode, type UiNodeDiff, type UiSnapshot, type UiFullSnapshot, type UiDiffSnapshot, type UiSnapshotMetadata, type UiOptimisticPatchMetadata, type UiOptimisticReconcileMetadata, type TextDelta, type ParsedUiUpdate, type UiStoreSnapshot, type UiOptimisticPatchState, } from '../../../sdk-ui/src/index.ts';
+/**
+ * Context for rendering UI nodes.
+ * Provides access to payloads, action dispatch, and rendering utilities.
+ */
 export interface UiRenderContext {
+    /** Get a payload by key */
     getPayload(key: string): UIPayload | undefined;
+    /** Render child nodes (for backward compatibility) */
     renderChildren(nodes: readonly UiNode[]): ReactNode;
+    /** Render a view by ID */
     renderView(viewId: string): ReactNode;
+    /** Dispatch an action with optional payload */
     dispatchAction(actionId: string, payload?: unknown): void;
+    /** The Ikon client instance */
     client?: IkonClient;
+    /** Video playback API */
     video?: IkonVideoPlayback;
+    /** The store instance for per-node subscriptions */
+    store: UiStreamStore;
+    /** The component library for resolving renderers */
+    library: UiComponentLibrary;
+    /** Handler cache for stable event handlers */
+    handlerCache: HandlerCache;
 }
+/**
+ * Props passed to component renderers.
+ * New pattern: nodeId + store for granular updates.
+ */
 export interface UiComponentRendererProps {
-    readonly node: UiNode;
+    /** The node ID to render */
+    readonly nodeId: string;
+    /** The rendering context */
     readonly context: UiRenderContext;
-    readonly children: readonly ReactNode[];
+    /** CSS class name from styleIds */
     readonly className?: string;
-    readonly styleIds: readonly string[];
 }
 export type UiComponentRenderer = ComponentType<UiComponentRendererProps>;
 export interface UiComponentLibrary {

package/renderer/ui-renderer.d.ts

@@ -1,7 +1,14 @@
 import { IkonClient, IkonVideoPlayback } from '../../../sdk/src/index.ts';
 import { UiStreamStore } from '../../../sdk-ui/src/index.ts';
 import { ReactNode } from 'react';
-import { UiComponentLibrary } from './types';
+import { UiComponentLibrary, UiNode, UiRenderContext } from './types';
+/**
+ * Render children nodes by their IDs.
+ * Used by component renderers to render their children.
+ * Note: This creates new JSX elements each call. For better performance,
+ * renderers should use context.renderChildren within useMemo.
+ */
+export declare function renderChildren(childNodes: readonly UiNode[], context: UiRenderContext): ReactNode;
 export interface UiRendererProps {
     readonly store: UiStreamStore;
     readonly library: UiComponentLibrary;
@@ -11,4 +18,4 @@ export interface UiRendererProps {
     readonly client?: IkonClient;
     readonly video?: IkonVideoPlayback;
 }
-export declare function UiRenderer({ store, library, viewId, emptyFallback, onAction, client, video }: UiRendererProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null;
+export declare const UiRenderer: import('react').NamedExoticComponent<UiRendererProps>;

package/renderer/use-root-view.d.ts

@@ -0,0 +1,13 @@
+import { UiStreamStore } from '../../../sdk-ui/src/index.ts';
+interface RootViewState {
+    rootViewId: string | undefined;
+    rootNodeId: string | undefined;
+}
+/**
+ * Hook that only re-renders when the root view structure changes.
+ * Unlike useUiStore, this does NOT re-render on every node change.
+ * This is critical for performance - the UiRenderer should only re-render
+ * when the root view changes, not when individual nodes update.
+ */
+export declare function useRootView(store: UiStreamStore, viewId?: string): RootViewState;
+export {};

package/renderer/use-ui-node.d.ts

@@ -0,0 +1,11 @@
+import { UiStreamStore } from '../../../sdk-ui/src/index.ts';
+import { UiNode } from './types';
+/**
+ * Hook for subscribing to a specific node in the UI store.
+ * Only re-renders when this specific node changes, not when other nodes change.
+ *
+ * @param store - The UiStreamStore instance
+ * @param nodeId - The ID of the node to subscribe to
+ * @returns The UiNode or undefined if not found
+ */
+export declare function useUiNode(store: UiStreamStore, nodeId: string): UiNode | undefined;

package/surface.d.ts

@@ -1,4 +1,4 @@
-import { UIStreamCategories } from '../../../shared/generated/src/index.ts';
+import { UIStreamCategories } from '../../../shared/protocol/src/index.ts';
 import { UiStreamStore } from '../../sdk-ui/src/index.ts';
 import { UiComponentLibrary } from './renderer';
 import { IkonClient, IkonVideoPlayback } from '../../sdk/src/index.ts';
@@ -13,9 +13,8 @@ export interface IkonUiSurfaceProps {
     stores: ReadonlyMap<string, IkonUiStoreEntry>;
     library: UiComponentLibrary;
     category?: IkonUiCategory;
-    version?: number;
     onAction?: (actionId: string, payload?: string) => void;
     client?: IkonClient;
     video?: IkonVideoPlayback;
 }
-export declare function IkonUiSurface({ stores, library, category, version, onAction, client, video }: IkonUiSurfaceProps): import("react/jsx-runtime").JSX.Element | null;
+export declare const IkonUiSurface: import('react').NamedExoticComponent<IkonUiSurfaceProps>;

package/use-ikon-ui-stores.d.ts

@@ -0,0 +1,10 @@
+import { IkonUi } from './ikon-ui';
+import { IkonUiStoreEntry } from './surface';
+/**
+ * Hook that subscribes to IkonUi store changes.
+ * Triggers re-renders when:
+ * - Stores are added/removed
+ * - A store transitions from empty to having valid data (rootViewId + views)
+ * Does NOT re-render on every node update within stores.
+ */
+export declare function useIkonUiStores(ikonUi: IkonUi | null | undefined): ReadonlyMap<string, IkonUiStoreEntry> | undefined;