@rezi-ui/core 0.1.0-alpha.1

package/dist/app/widgetRenderer.d.ts

@@ -0,0 +1,238 @@
+/**
+ * packages/core/src/app/widgetRenderer.ts — Widget tree renderer with focus and event routing.
+ *
+ * Why: Handles the "view mode" rendering path where users return VNode trees
+ * from a view function. Orchestrates the full widget pipeline: tree commit,
+ * layout computation, focus management, event routing, input editing, and
+ * drawlist rendering.
+ *
+ * Responsibilities:
+ *   - Commit VNode tree (reconciliation, instance ID allocation)
+ *   - Compute layout for viewport
+ *   - Manage focus state (traversal, pending changes)
+ *   - Route engine events to widgets (keyboard/mouse -> actions)
+ *   - Handle input widget editing (text/key/paste events)
+ *   - Render committed tree to drawlist
+ *
+ * v2 Cursor Protocol:
+ *   - When useV2Cursor is enabled, uses DrawlistBuilderV2
+ *   - Emits SET_CURSOR for focused Input widgets with proper position
+ *
+ * @see docs/guide/runtime-and-layout.md
+ * @see docs/guide/lifecycle-and-updates.md
+ */
+import type { CursorShape } from "../abi.js";
+import type { RuntimeBackend } from "../backend.js";
+import { type DrawlistBuilderV1, type DrawlistBuilderV2 } from "../drawlist/index.js";
+import type { ZrevEvent } from "../events.js";
+import type { ViewFn } from "../index.js";
+import { type RoutedAction } from "../runtime/router.js";
+import type { Theme } from "../theme/theme.js";
+/** Callbacks for render lifecycle tracking (used by app to set inRender flag). */
+export type WidgetRendererHooks = Readonly<{
+    enterRender: () => void;
+    exitRender: () => void;
+}>;
+/** Terminal viewport dimensions in columns and rows. */
+export type Viewport = Readonly<{
+    cols: number;
+    rows: number;
+}>;
+/**
+ * Result of submitting a widget render frame.
+ * On success, inFlight resolves when backend acknowledges the frame.
+ */
+export type WidgetRenderSubmitResult = Readonly<{
+    ok: true;
+    inFlight: Promise<void>;
+}> | Readonly<{
+    ok: false;
+    code: "ZRUI_USER_CODE_THROW" | "ZRUI_DRAWLIST_BUILD_ERROR" | "ZRUI_BACKEND_ERROR" | "ZRUI_DUPLICATE_KEY" | "ZRUI_DUPLICATE_ID" | "ZRUI_INVALID_PROPS";
+    detail: string;
+}>;
+export type WidgetRenderPlan = Readonly<{
+    /** Re-run view + commit (required when state or view outputs changed). */
+    commit: boolean;
+    /** Recompute layout explicitly (e.g. viewport resize). */
+    layout: boolean;
+    /**
+     * Allow commit-time layout stability checks.
+     * When true, the renderer may still relayout even if `layout` is false.
+     */
+    checkLayoutStability: boolean;
+}>;
+/**
+ * Outcome of routing an engine event through the widget tree.
+ * needsRender indicates if focus/pressed state changed (requires re-render).
+ * action is emitted when a pressable widget is activated.
+ */
+export type WidgetRoutingOutcome = Readonly<{
+    needsRender: boolean;
+    action?: RoutedAction;
+}>;
+/**
+ * Renderer for widget view mode.
+ *
+ * Maintains committed tree, layout, focus state, and input widget state
+ * across frames. Routes engine events to produce UI actions.
+ *
+ * @typeParam S - Application state type
+ */
+export declare class WidgetRenderer<S> {
+    private readonly backend;
+    private readonly builder;
+    private readonly useV2Cursor;
+    private readonly cursorShape;
+    private readonly cursorBlink;
+    private readonly requestRender;
+    private readonly requestView;
+    private committedRoot;
+    private layoutTree;
+    private focusState;
+    private focusList;
+    private baseFocusList;
+    private enabledById;
+    private baseEnabledById;
+    private pressableIds;
+    private pressedId;
+    private pressedVirtualList;
+    private traps;
+    private readonly allocator;
+    private readonly compositeRegistry;
+    private inputById;
+    private readonly inputCursorByInstanceId;
+    private readonly inputWorkingValueByInstanceId;
+    private readonly virtualListStore;
+    private readonly tableStore;
+    private readonly treeStore;
+    private readonly loadedTreeChildrenByTreeId;
+    private readonly treeLoadTokenByTreeAndKey;
+    private nextTreeLoadToken;
+    private readonly virtualListById;
+    private readonly buttonById;
+    private readonly tableById;
+    private readonly treeById;
+    private readonly dropdownById;
+    private readonly selectById;
+    private readonly checkboxById;
+    private readonly radioGroupById;
+    private readonly commandPaletteById;
+    private readonly filePickerById;
+    private readonly fileTreeExplorerById;
+    private readonly splitPaneById;
+    private readonly codeEditorById;
+    private readonly diffViewerById;
+    private readonly toolApprovalDialogById;
+    private readonly logsConsoleById;
+    private rectById;
+    private splitPaneChildRectsById;
+    private toastContainers;
+    private toastActionByFocusId;
+    private toastFocusableActionIds;
+    private readonly commandPaletteItemsById;
+    private readonly commandPaletteLoadingById;
+    private readonly commandPaletteFetchTokenById;
+    private readonly commandPaletteLastQueryById;
+    private readonly commandPaletteLastSourcesRefById;
+    private readonly toolApprovalFocusedActionById;
+    private readonly diffViewerFocusedHunkById;
+    private readonly diffViewerExpandedHunksById;
+    private readonly logsConsoleLastGTimeById;
+    private hadRoutingWidgets;
+    private readonly tableRenderCacheById;
+    private readonly logsConsoleRenderCacheById;
+    private readonly diffRenderCacheById;
+    private readonly codeEditorRenderCacheById;
+    private splitPaneDrag;
+    private readonly layerRegistry;
+    private layerStack;
+    private closeOnEscapeByLayerId;
+    private closeOnBackdropByLayerId;
+    private onCloseByLayerId;
+    private dropdownStack;
+    private readonly dropdownSelectedIndexById;
+    private readonly _metadataCollector;
+    private readonly _pooledRectByInstanceId;
+    private readonly _pooledLayoutSigByInstanceId;
+    private readonly _pooledNextLayoutSigByInstanceId;
+    private readonly _pooledRectById;
+    private readonly _pooledSplitPaneChildRectsById;
+    private _layoutMeasureCache;
+    private readonly _pooledCloseOnEscape;
+    private readonly _pooledCloseOnBackdrop;
+    private readonly _pooledOnClose;
+    private readonly _pooledToastActionByFocusId;
+    private readonly _pooledLayoutStack;
+    private readonly _pooledRuntimeStack;
+    private readonly _pooledDropdownStack;
+    private readonly _pooledToastContainers;
+    private readonly _pooledToastFocusableActionIds;
+    private readonly _pooledPrevTreeIds;
+    private readonly _pooledPrevDropdownIds;
+    private readonly _pooledPrevTreeStoreIds;
+    private readonly _pooledPrevCommandPaletteIds;
+    private readonly _pooledPrevToolApprovalDialogIds;
+    private readonly _pooledPrevDiffViewerIds;
+    private readonly _pooledPrevLogsConsoleIds;
+    constructor(opts: Readonly<{
+        backend: RuntimeBackend;
+        builder?: DrawlistBuilderV1 | DrawlistBuilderV2;
+        maxDrawlistBytes?: number;
+        drawlistValidateParams?: boolean;
+        drawlistReuseOutputBuffer?: boolean;
+        drawlistEncodedStringCacheCap?: number;
+        /** Called when composite widgets invalidate (useState/useEffect). */
+        requestRender?: () => void;
+        /** Called when composite widgets require a new view/commit pass. */
+        requestView?: () => void;
+        /** Enable v2 cursor protocol for native cursor support */
+        useV2Cursor?: boolean;
+        /** Cursor shape for focused inputs (default: bar) */
+        cursorShape?: CursorShape;
+        /** Whether cursor should blink (default: true) */
+        cursorBlink?: boolean;
+    }>);
+    /**
+     * Get the currently focused widget ID.
+     *
+     * @returns Focused widget ID or null if nothing focused
+     */
+    getFocusedId(): string | null;
+    /**
+     * Determine whether a key event should bypass the keybinding system.
+     *
+     * Why: When dropdowns or modal overlays are active, widgets must be able to
+     * consume Escape to close/deny/exit without being preempted by global
+     * keybindings (e.g., "Escape => menu").
+     */
+    shouldBypassKeybindings(event: ZrevEvent): boolean;
+    /**
+     * Route an engine event through the widget tree.
+     *
+     * Handles focus traversal (Tab/Shift+Tab), mouse interactions,
+     * keyboard activation (Enter/Space), and input widget editing.
+     *
+     * @param event - Engine event from ZREV parsing
+     * @returns Routing outcome with render flag and optional action
+     */
+    routeEngineEvent(event: ZrevEvent): WidgetRoutingOutcome;
+    /**
+     * Execute view function, commit tree, compute layout, and render to drawlist.
+     *
+     * Pipeline:
+     *   1. Call viewFn(snapshot) to get VNode tree
+     *   2. Commit VNode tree (reconciliation, instance allocation)
+     *   3. Compute layout for viewport dimensions
+     *   4. Finalize focus state for committed tree
+     *   5. Render tree to drawlist
+     *   6. Submit drawlist to backend
+     *
+     * @param viewFn - User view function returning VNode tree
+     * @param snapshot - Current application state (read-only)
+     * @param viewport - Terminal dimensions
+     * @param hooks - Lifecycle hooks for render tracking
+     * @returns Success with in-flight promise, or error with code/detail
+     */
+    submitFrame(viewFn: ViewFn<S>, snapshot: Readonly<S>, viewport: Viewport, theme: Theme, hooks: WidgetRendererHooks, plan?: WidgetRenderPlan): WidgetRenderSubmitResult;
+}
+//# sourceMappingURL=widgetRenderer.d.ts.map

package/dist/app/widgetRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widgetRenderer.d.ts","sourceRoot":"","sources":["../../src/app/widgetRenderer.ts"],"names":[],"mappings":"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"}