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

package/dist/render/BehaviorSurfaceProvider.js

@@ -0,0 +1,185 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * BehaviorSurfaceProvider
+ *
+ * React provider that wraps a surface render session with a
+ * stable `SurfaceEventBus` instance and the real `surfaceId`.
+ *
+ * When `entityFormBindings` are supplied and an EntityFacade
+ * is available via EntityFacadeContext, automatically attaches form→entity
+ * bridges on mount and tears them down on unmount.
+ *
+ * All block children receive both values via context so they can emit events
+ * that carry a meaningful surface ID without prop-drilling.
+ *
+ * Lifecycle:
+ * - Emits `surface:load` on mount
+ * - Emits `surface:unload` on unmount
+ * - Re-creates the bus (and re-emits lifecycle events) when `surfaceId` changes
+ *
+ * @module @pwfabric/runtime/render/BehaviorSurfaceProvider
+ */
+import * as React from 'react';
+import { SURFACE_EVENTS } from '@pwfabric/contracts';
+import { SurfaceEventContext } from './surface-event-context.js';
+import { SurfaceIdContext } from './surface-id-context.js';
+import { createSurfaceEventBus } from './surface-event-bus.js';
+import { useEntityFacade } from './entity-facade-context.js';
+import { useOptionalDataService } from '../data/DataCapabilityProvider.js';
+import { useSurfaceData } from './surface-data-context.js';
+import { attachFormEntityBridge } from '../forms/form-entity-bridge.js';
+import { resolveFormWriteTarget, toFormWriteError } from '../forms/form-write-target.js';
+import { completeNamedControlValues } from '../forms/named-control-values.js';
+/**
+ * Wraps a surface render tree with a scoped `SurfaceEventBus` and `surfaceId`.
+ *
+ * Place this as the outermost wrapper inside `SurfaceRenderer` so every block
+ * in the tree can call `useSurfaceEvents()` and `useSurfaceId()`.
+ */
+export function BehaviorSurfaceProvider({ surfaceId, children, entityFormBindings, dataSources, onEvent, blocks, }) {
+    // Canonical event path: the renderer's handler is subscribed to the global `*`
+    // wildcard. Every block emits through the bus (useSurfaceEvents) → this handler
+    // dispatches declarative actions (setState/refresh) + forwards to the host.
+    // A ref keeps the subscription stable while always calling the latest handler.
+    const onEventRef = React.useRef(onEvent);
+    onEventRef.current = onEvent;
+    // Re-create the bus when surfaceId changes so sibling surfaces stay isolated.
+    //
+    // The `*` subscription is attached HERE, at construction, rather than in an
+    // effect. `bus.emit` is synchronous and unbuffered: an event emitted while
+    // `handlers.get('*')` is empty is dropped and never replayed. React runs
+    // effects CHILD-FIRST, so a subscription owned by this provider would attach
+    // only after every block's own mount effect had already run — meaning any
+    // block that emits from its mount effect had its event silently swallowed,
+    // deterministically. The same gap opened, more narrowly, for interactions
+    // landing between a commit and its passive-effect flush, which is what made
+    // `dispatch-actions.dom` / `entity-list-reactive-repro.dom` flaky.
+    //
+    // Subscribing during render is safe here because the bus is constructed in
+    // this same factory: nothing outside observes it before we return, so there
+    // is no external mutation and re-running the factory yields an independent
+    // bus. No explicit teardown is needed either — the handler is reachable only
+    // through the bus, so a discarded bus takes its listener with it.
+    const bus = React.useMemo(() => {
+        const created = createSurfaceEventBus();
+        created.on('*', (event) => onEventRef.current?.(event));
+        return created;
+    }, [surfaceId]);
+    React.useEffect(() => {
+        bus.emit({ type: SURFACE_EVENTS.SURFACE_LOAD, surfaceId, timestamp: Date.now() });
+        return () => {
+            bus.emit({ type: SURFACE_EVENTS.SURFACE_UNLOAD, surfaceId, timestamp: Date.now() });
+        };
+    }, [bus, surfaceId]);
+    // auto-wire form→entity bridges when EntityFacade is available.
+    //
+    // Attached during render, for the same reason the `*` handler above is: a
+    // bridge that subscribes from an effect is not listening yet while the blocks
+    // it serves are already interactive, and `bus.emit` drops what nobody is
+    // listening for. A form submitted in that window lost its create outright —
+    // the residual flake in `entity-list-reactive-repro.dom` after the `*` fix,
+    // where the wildcard handler saw `form:submit` but the bridge never did.
+    //
+    // Previous bridges are torn down before new ones attach, so re-running this
+    // (deps change, or a StrictMode double render) never stacks duplicates.
+    const entityFacade = useEntityFacade();
+    // OPTIONAL, because this provider also mounts on the behaviours-only path
+    // where no data machinery exists. A form pointed at a rest source there has
+    // nowhere to write, and says so, rather than the whole surface failing to
+    // render.
+    const dataService = useOptionalDataService();
+    // What the page has bound RIGHT NOW, read at write time through a ref so a
+    // fresh fetch never re-attaches the bridges. Null outside the data-bound
+    // path, where no record can have loaded and every write is a create.
+    const surfaceData = useSurfaceData();
+    const surfaceDataRef = React.useRef(surfaceData);
+    surfaceDataRef.current = surfaceData;
+    /**
+     * THE ONE PLACE THAT KNOWS WHAT A SOURCE ID MEANS.
+     *
+     * The bridge does not, deliberately — that is what lets one declaration
+     * serve our own store and a third party's endpoint without the form knowing
+     * which it is talking to.
+     *
+     * THE VERB FOLLOWS THE RECORD. A binding that says `PATCH` can only update
+     * a record the source has loaded; with none loaded the honest write is a
+     * create. Otherwise a Profile form would PATCH the collection path, the API
+     * would answer 404 "Route not found", and the visitor would read "check the
+     * highlighted fields".
+     */
+    const writer = React.useMemo(() => {
+        const byId = new Map((dataSources ?? []).map((s) => [s.id, s]));
+        return {
+            async write(sourceId, values, method) {
+                const source = byId.get(sourceId);
+                const target = resolveFormWriteTarget(method, surfaceDataRef.current?.[sourceId]);
+                if (source?.kind === 'entity' && source.entityType && entityFacade) {
+                    const entityType = source.entityType;
+                    return target.recordId
+                        ? entityFacade.store.update(entityType, target.recordId, values)
+                        : entityFacade.store.create(entityType, values);
+                }
+                if (!source) {
+                    return {
+                        success: false,
+                        error: {
+                            type: 'not_found',
+                            message: `This form writes to "${sourceId}", which this page does not declare.`,
+                        },
+                    };
+                }
+                if (!dataService) {
+                    return {
+                        success: false,
+                        error: {
+                            type: 'connector',
+                            message: `This form writes to "${sourceId}", but this page has no data layer to write through.`,
+                        },
+                    };
+                }
+                const res = await dataService.fetchData(sourceId, {
+                    method: target.method,
+                    body: values,
+                    ...(target.recordId !== undefined ? { recordId: target.recordId } : {}),
+                });
+                if (!res.success)
+                    return { success: false, error: toFormWriteError(res.error) };
+                const written = res.data;
+                const id = written && typeof written === 'object' ? written['id'] : undefined;
+                return {
+                    success: true,
+                    data: (written ?? {}),
+                    id: (typeof id === 'string' || typeof id === 'number' ? String(id) : target.recordId ?? sourceId),
+                };
+            },
+        };
+    }, [dataSources, entityFacade, dataService]);
+    // Read at submit time through a ref, like the bound data, so a re-render
+    // never re-attaches the bridges.
+    const blocksRef = React.useRef(blocks);
+    blocksRef.current = blocks;
+    const completeValues = React.useCallback((formId, values) => {
+        const tree = blocksRef.current;
+        const state = surfaceDataRef.current?.['state'];
+        if (!tree || !state || typeof state !== 'object')
+            return values;
+        return completeNamedControlValues(tree, formId, values, state);
+    }, []);
+    const bridgeUnsubsRef = React.useRef([]);
+    React.useMemo(() => {
+        bridgeUnsubsRef.current.forEach((u) => u());
+        bridgeUnsubsRef.current = entityFormBindings?.length
+            ? entityFormBindings.map((cfg) => attachFormEntityBridge(bus, writer, cfg, completeValues))
+            : [];
+    }, [writer, bus, entityFormBindings, completeValues]);
+    // Detach on unmount. Keyed on nothing so it runs once per mount; the memo
+    // above owns teardown for every other transition.
+    React.useEffect(() => {
+        return () => {
+            bridgeUnsubsRef.current.forEach((u) => u());
+            bridgeUnsubsRef.current = [];
+        };
+    }, []);
+    return (_jsx(SurfaceEventContext.Provider, { value: bus, children: _jsx(SurfaceIdContext.Provider, { value: surfaceId, children: children }) }));
+}
+//# sourceMappingURL=BehaviorSurfaceProvider.js.map

package/dist/render/BehaviorSurfaceProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BehaviorSurfaceProvider.js","sourceRoot":"","sources":["../../src/render/BehaviorSurfaceProvider.tsx"],"names":[],"mappings":"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"}

package/dist/render/BlockErrorBoundary.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Block Error Boundary
+ *
+ * React class component that isolates block-level render crashes.
+ * If a single block throws during render, only that block shows
+ * a fallback UI — the rest of the surface stays intact.
+ *
+ * @module @pwfabric/runtime/render/BlockErrorBoundary
+ */
+import * as React from 'react';
+interface BlockErrorBoundaryProps {
+    readonly blockId: string;
+    readonly blockType: string;
+    readonly children: React.ReactNode;
+}
+interface BlockErrorBoundaryState {
+    readonly hasError: boolean;
+    readonly error: Error | null;
+}
+export declare class BlockErrorBoundary extends React.Component<BlockErrorBoundaryProps, BlockErrorBoundaryState> {
+    constructor(props: BlockErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): BlockErrorBoundaryState;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    render(): React.ReactNode;
+}
+export {};
+//# sourceMappingURL=BlockErrorBoundary.d.ts.map

package/dist/render/BlockErrorBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockErrorBoundary.d.ts","sourceRoot":"","sources":["../../src/render/BlockErrorBoundary.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,UAAU,uBAAuB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CACnC;AAED,UAAU,uBAAuB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CAC7B;AAED,qBAAa,kBAAmB,SAAQ,KAAK,CAAC,SAAS,CACrD,uBAAuB,EACvB,uBAAuB,CACxB;gBACa,KAAK,EAAE,uBAAuB;IAK1C,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,uBAAuB;IAI7D,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,IAAI;IAQ5D,MAAM,IAAI,KAAK,CAAC,SAAS;CAyBnC"}

package/dist/render/BlockErrorBoundary.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Block Error Boundary
+ *
+ * React class component that isolates block-level render crashes.
+ * If a single block throws during render, only that block shows
+ * a fallback UI — the rest of the surface stays intact.
+ *
+ * @module @pwfabric/runtime/render/BlockErrorBoundary
+ */
+import * as React from 'react';
+export class BlockErrorBoundary extends React.Component {
+    constructor(props) {
+        super(props);
+        this.state = { hasError: false, error: null };
+    }
+    static getDerivedStateFromError(error) {
+        return { hasError: true, error };
+    }
+    componentDidCatch(error, info) {
+        console.error(`[PWFabric] Block render error: ${this.props.blockType}#${this.props.blockId}`, error, info.componentStack);
+    }
+    render() {
+        if (this.state.hasError) {
+            // Quiet-shape fallback: no visible copy — the earlier card leaked the
+            // raw exception message ("Cannot read properties of undefined…") to end
+            // users in a hardcoded light-red dev box. The error tint + dashed
+            // border signal "this section failed"; the technical message stays in
+            // the title tooltip and in the componentDidCatch console.error above,
+            // and data-block-error keeps it queryable for tests/tooling.
+            return (_jsx("div", { style: {
+                    border: '2px dashed var(--pw-color-error, #ef4444)',
+                    borderRadius: '8px',
+                    backgroundColor: 'color-mix(in srgb, var(--pw-color-error, #ef4444) 8%, transparent)',
+                    minHeight: '32px',
+                }, "data-block-error": this.props.blockId, "data-block-error-type": this.props.blockType, title: this.state.error?.message ?? 'Unknown error' }));
+        }
+        return this.props.children;
+    }
+}
+//# sourceMappingURL=BlockErrorBoundary.js.map

package/dist/render/BlockErrorBoundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockErrorBoundary.js","sourceRoot":"","sources":["../../src/render/BlockErrorBoundary.tsx"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAa9B,MAAM,OAAO,kBAAmB,SAAQ,KAAK,CAAC,SAG7C;IACC,YAAY,KAA8B;QACxC,KAAK,CAAC,KAAK,CAAC,CAAA;QACZ,IAAI,CAAC,KAAK,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAC/C,CAAC;IAED,MAAM,CAAC,wBAAwB,CAAC,KAAY;QAC1C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;IAClC,CAAC;IAEQ,iBAAiB,CAAC,KAAY,EAAE,IAAqB;QAC5D,OAAO,CAAC,KAAK,CACX,kCAAkC,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAC9E,KAAK,EACL,IAAI,CAAC,cAAc,CACpB,CAAA;IACH,CAAC;IAEQ,MAAM;QACb,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;YACxB,sEAAsE;YACtE,wEAAwE;YACxE,kEAAkE;YAClE,sEAAsE;YACtE,sEAAsE;YACtE,6DAA6D;YAC7D,OAAO,CACL,cACE,KAAK,EAAE;oBACL,MAAM,EAAE,2CAA2C;oBACnD,YAAY,EAAE,KAAK;oBACnB,eAAe,EAAE,oEAAoE;oBACrF,SAAS,EAAE,MAAM;iBAClB,sBACiB,IAAI,CAAC,KAAK,CAAC,OAAO,2BACb,IAAI,CAAC,KAAK,CAAC,SAAS,EAC3C,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,IAAI,eAAe,GACnD,CACH,CAAA;QACH,CAAC;QAED,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAA;IAC5B,CAAC;CACF"}

package/dist/render/DataBoundSurfaceRenderer.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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;
+//# sourceMappingURL=DataBoundSurfaceRenderer.d.ts.map

package/dist/render/DataBoundSurfaceRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataBoundSurfaceRenderer.d.ts","sourceRoot":"","sources":["../../src/render/DataBoundSurfaceRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAO9B,OAAO,KAAK,EACV,6BAA6B,EAE7B,aAAa,EAEd,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAGV,iBAAiB,EAElB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAkF3C;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,aAAa,EAAE,CAGvE;AAiCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAA;IAClC,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAA;CAC1D,GAAG,OAAO,CAUV;AA2qBD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKzD;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAWtE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAQ7D;AAMD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,6BAA6B,GAAG,KAAK,CAAC,YAAY,CAqEjG"}