@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/render/DataBoundSurfaceRenderer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Data-Bound Surface Renderer
+ *
+ * Wrapper component that resolves dataSources, state, and {{expression}} props
+ * before passing concrete values to the existing SurfaceRenderer.
+ *
+ * Architecture (post-refactor):
+ *   Surface JSON (dataSources + state + {{expr}} in props)
+ *     -> DataBoundSurfaceRenderer
+ *       -> DataCapabilityProvider (creates DataService instance)
+ *         -> DataBoundInner
+ *           -> useSurfaceData: maps SurfaceDataSourceDefinition → DataSourceDefinition,
+ *              registers with DataService, fetches via DataService, manages React state
+ *     -> SurfaceRenderer (unchanged)
+ *       -> Block components (unchanged)
+ *
+ * Backward compatible: if no dataSources, passes through with zero overhead.
+ *
+ * @module @pwfabric/runtime/render/DataBoundSurfaceRenderer
+ */
+import * as React from 'react';
+import type { DataBoundSurfaceRendererProps, SurfaceAction } from './data-binding-types.js';
+import type { RenderableSurface } from './types.js';
+import type { Block } from '@pwfabric/core';
+/**
+ * The actions a block's `action` prop names, in order.
+ *
+ * One action or a list of them (`[setState step, setState stepError '']`) —
+ * a wizard's "Next" has to move the step AND clear the previous step's error
+ * in one click. Anything that is not a surface action (a form's `action` is
+ * its submit URL string) names none.
+ */
+export declare function blockActionsOf(value: unknown): readonly SurfaceAction[];
+/**
+ * Does this surface need the data-bound path — state, expression resolution,
+ * the action dispatcher — or can it go straight to SurfaceRenderer?
+ *
+ * ONE ANSWER FOR EVERY HOST. The renderer's own passthrough check and embed's
+ * `needsDataBoundRenderer` used to disagree: embed counted `initialState`, the
+ * renderer did not. So a wizard page carrying nothing but `initialState` and
+ * buttons with `action` props reached the renderer, fell into the passthrough,
+ * and there `visibleWhen` was never evaluated, `repeat` never expanded and no
+ * `action` was ever dispatched — the buttons were dead. A block `action` alone
+ * needs the path too: it is dispatched nowhere else. So does a block
+ * `visibleWhen`/`if`/`repeat` (see blockTreeHasCondition).
+ *
+ * Host-provided behaviors are a prop, not part of the surface, and are
+ * checked by the renderer on top of this.
+ */
+export declare function surfaceNeedsDataBinding(surface: {
+    readonly blocks?: readonly Block[];
+    readonly capabilities?: RenderableSurface['capabilities'];
+}): boolean;
+/**
+ * Normalize a stored behavior trigger string to canonical colon form.
+ * - Already has `:` → return lowercased/trimmed as-is
+ * - Has `.` → replace first `.` with `:`
+ * - Otherwise → return trimmed lowercased (best-effort; won't match well-formed events)
+ */
+export declare function canonicalizeEventType(raw: string): string;
+export declare function isSurfaceAction(value: unknown): value is SurfaceAction;
+/**
+ * Guard the `navigate` action against XSS: only http(s) absolute URLs and
+ * relative/anchor URLs may be navigated to. A scheme like `javascript:`,
+ * `data:`, or `vbscript:` is rejected so a stored behavior cannot execute
+ * script in a published-surface visitor's context. Control characters are
+ * stripped first to defeat `java\tscript:`-style scheme smuggling.
+ */
+export declare function isSafeNavigateUrl(url: unknown): url is string;
+/**
+ * Data-bound surface renderer.
+ *
+ * If nothing on the surface is dynamic (see surfaceNeedsDataBinding), renders
+ * SurfaceRenderer directly (zero overhead).
+ * Otherwise, wraps with DataCapabilityProvider for DataService context, then
+ * fetches data, manages state, resolves expressions, and intercepts events.
+ */
+export declare function DataBoundSurfaceRenderer(props: DataBoundSurfaceRendererProps): React.ReactElement;