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

package/dist/execution-context.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Execution Context
+ *
+ * Runtime execution context for capability execution
+ *
+ * @module @pwfabric/runtime/execution-context
+ */
+import type { CapabilityId, FabricId, ManifestationId, ExecutionContext, ExecutionLogger, ExecutionResult, Timestamp } from '@pwfabric/contracts';
+/**
+ * Console-based execution logger
+ */
+export declare class ConsoleExecutionLogger implements ExecutionLogger {
+    private readonly traceId;
+    private readonly spanId;
+    constructor(traceId: string, spanId: string);
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * No-op logger for silent execution
+ */
+export declare class NoOpExecutionLogger implements ExecutionLogger {
+    debug(_message: string, _data?: Record<string, unknown>): void;
+    info(_message: string, _data?: Record<string, unknown>): void;
+    warn(_message: string, _data?: Record<string, unknown>): void;
+    error(_message: string, _data?: Record<string, unknown>): void;
+}
+/**
+ * Invocation handler type for resolving capability execution
+ */
+export type InvocationHandler = <TInput, TOutput>(capabilityId: CapabilityId, input: TInput) => Promise<ExecutionResult<TOutput>>;
+/**
+ * Runtime execution context options
+ */
+export interface RuntimeExecutionContextOptions {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    fabricId: FabricId;
+    manifestationId?: ManifestationId;
+    timeout?: number;
+    data?: Record<string, unknown>;
+    logger?: ExecutionLogger;
+    invoker: InvocationHandler;
+}
+/**
+ * Runtime execution context implementation
+ */
+export declare class RuntimeExecutionContext implements ExecutionContext {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly fabricId: FabricId;
+    readonly manifestationId?: ManifestationId;
+    readonly startedAt: Timestamp;
+    readonly timeout?: number;
+    readonly data: Record<string, unknown>;
+    readonly logger: ExecutionLogger;
+    private readonly invoker;
+    constructor(options: RuntimeExecutionContextOptions);
+    invoke<TInput, TOutput>(capabilityId: CapabilityId, input: TInput): Promise<ExecutionResult<TOutput>>;
+    child(spanId: string): ExecutionContext;
+}
+/**
+ * Generate a unique trace ID
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a unique span ID
+ */
+export declare function generateSpanId(): string;
+/**
+ * Options for creating an execution context
+ */
+export interface CreateExecutionContextOptions {
+    fabricId: FabricId;
+    manifestationId?: ManifestationId;
+    timeout?: number;
+    data?: Record<string, unknown>;
+    silent?: boolean;
+    invoker: InvocationHandler;
+}
+/**
+ * Create a new execution context
+ */
+export declare function createExecutionContext(options: CreateExecutionContextOptions): RuntimeExecutionContext;

package/dist/execution-context.js

@@ -0,0 +1,146 @@
+/**
+ * Execution Context
+ *
+ * Runtime execution context for capability execution
+ *
+ * @module @pwfabric/runtime/execution-context
+ */
+// ============================================================
+// LOGGER IMPLEMENTATION
+// ============================================================
+/**
+ * Console-based execution logger
+ */
+export class ConsoleExecutionLogger {
+    traceId;
+    spanId;
+    constructor(traceId, spanId) {
+        this.traceId = traceId;
+        this.spanId = spanId;
+    }
+    debug(message, data) {
+        console.debug(`[${this.traceId}:${this.spanId}] DEBUG: ${message}`, data || '');
+    }
+    info(message, data) {
+        console.info(`[${this.traceId}:${this.spanId}] INFO: ${message}`, data || '');
+    }
+    warn(message, data) {
+        console.warn(`[${this.traceId}:${this.spanId}] WARN: ${message}`, data || '');
+    }
+    error(message, data) {
+        console.error(`[${this.traceId}:${this.spanId}] ERROR: ${message}`, data || '');
+    }
+}
+/**
+ * No-op logger for silent execution
+ */
+export class NoOpExecutionLogger {
+    debug(_message, _data) {
+        // No-op
+    }
+    info(_message, _data) {
+        // No-op
+    }
+    warn(_message, _data) {
+        // No-op
+    }
+    error(_message, _data) {
+        // No-op
+    }
+}
+/**
+ * Runtime execution context implementation
+ */
+export class RuntimeExecutionContext {
+    traceId;
+    spanId;
+    parentSpanId;
+    fabricId;
+    manifestationId;
+    startedAt;
+    timeout;
+    data;
+    logger;
+    invoker;
+    constructor(options) {
+        this.traceId = options.traceId;
+        this.spanId = options.spanId;
+        if (options.parentSpanId !== undefined) {
+            this.parentSpanId = options.parentSpanId;
+        }
+        this.fabricId = options.fabricId;
+        if (options.manifestationId !== undefined) {
+            this.manifestationId = options.manifestationId;
+        }
+        this.startedAt = Date.now();
+        if (options.timeout !== undefined) {
+            this.timeout = options.timeout;
+        }
+        this.data = options.data ?? {};
+        this.logger = options.logger ?? new ConsoleExecutionLogger(this.traceId, this.spanId);
+        this.invoker = options.invoker;
+    }
+    invoke(capabilityId, input) {
+        return this.invoker(capabilityId, input);
+    }
+    child(spanId) {
+        const childOptions = {
+            traceId: this.traceId,
+            spanId,
+            parentSpanId: this.spanId,
+            fabricId: this.fabricId,
+            invoker: this.invoker,
+            data: { ...this.data },
+            logger: new ConsoleExecutionLogger(this.traceId, spanId),
+        };
+        if (this.manifestationId !== undefined) {
+            childOptions.manifestationId = this.manifestationId;
+        }
+        if (this.timeout !== undefined) {
+            childOptions.timeout = this.timeout;
+        }
+        return new RuntimeExecutionContext(childOptions);
+    }
+}
+// ============================================================
+// CONTEXT FACTORY
+// ============================================================
+/**
+ * Generate a unique trace ID
+ */
+export function generateTraceId() {
+    return `trace_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+/**
+ * Generate a unique span ID
+ */
+export function generateSpanId() {
+    return `span_${Math.random().toString(36).substr(2, 9)}`;
+}
+/**
+ * Create a new execution context
+ */
+export function createExecutionContext(options) {
+    const traceId = generateTraceId();
+    const spanId = generateSpanId();
+    const contextOptions = {
+        traceId,
+        spanId,
+        fabricId: options.fabricId,
+        invoker: options.invoker,
+        logger: options.silent
+            ? new NoOpExecutionLogger()
+            : new ConsoleExecutionLogger(traceId, spanId),
+    };
+    if (options.manifestationId) {
+        contextOptions.manifestationId = options.manifestationId;
+    }
+    if (options.timeout) {
+        contextOptions.timeout = options.timeout;
+    }
+    if (options.data) {
+        contextOptions.data = options.data;
+    }
+    return new RuntimeExecutionContext(contextOptions);
+}
+//# sourceMappingURL=execution-context.js.map

package/dist/execution-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-context.js","sourceRoot":"","sources":["../src/execution-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Execution Context\n *\n * Runtime execution context for capability execution\n *\n * @module @pwfabric/runtime/execution-context\n */\n\nimport type {\n  CapabilityId,\n  FabricId,\n  ManifestationId,\n  ExecutionContext,\n  ExecutionLogger,\n  ExecutionResult,\n  Timestamp,\n} from '@pwfabric/contracts'\n\n// ============================================================\n// LOGGER IMPLEMENTATION\n// ============================================================\n\n/**\n * Console-based execution logger\n */\nexport class ConsoleExecutionLogger implements ExecutionLogger {\n  constructor(\n    private readonly traceId: string,\n    private readonly spanId: string\n  ) {}\n\n  debug(message: string, data?: Record<string, unknown>): void {\n    console.debug(`[${this.traceId}:${this.spanId}] DEBUG: ${message}`, data || '')\n  }\n\n  info(message: string, data?: Record<string, unknown>): void {\n    console.info(`[${this.traceId}:${this.spanId}] INFO: ${message}`, data || '')\n  }\n\n  warn(message: string, data?: Record<string, unknown>): void {\n    console.warn(`[${this.traceId}:${this.spanId}] WARN: ${message}`, data || '')\n  }\n\n  error(message: string, data?: Record<string, unknown>): void {\n    console.error(`[${this.traceId}:${this.spanId}] ERROR: ${message}`, data || '')\n  }\n}\n\n/**\n * No-op logger for silent execution\n */\nexport class NoOpExecutionLogger implements ExecutionLogger {\n  debug(_message: string, _data?: Record<string, unknown>): void {\n    // No-op\n  }\n  info(_message: string, _data?: Record<string, unknown>): void {\n    // No-op\n  }\n  warn(_message: string, _data?: Record<string, unknown>): void {\n    // No-op\n  }\n  error(_message: string, _data?: Record<string, unknown>): void {\n    // No-op\n  }\n}\n\n// ============================================================\n// EXECUTION CONTEXT IMPLEMENTATION\n// ============================================================\n\n/**\n * Invocation handler type for resolving capability execution\n */\nexport type InvocationHandler = <TInput, TOutput>(\n  capabilityId: CapabilityId,\n  input: TInput\n) => Promise<ExecutionResult<TOutput>>\n\n/**\n * Runtime execution context options\n */\nexport interface RuntimeExecutionContextOptions {\n  traceId: string\n  spanId: string\n  parentSpanId?: string\n  fabricId: FabricId\n  manifestationId?: ManifestationId\n  timeout?: number\n  data?: Record<string, unknown>\n  logger?: ExecutionLogger\n  invoker: InvocationHandler\n}\n\n/**\n * Runtime execution context implementation\n */\nexport class RuntimeExecutionContext implements ExecutionContext {\n  readonly traceId: string\n  readonly spanId: string\n  readonly parentSpanId?: string\n  readonly fabricId: FabricId\n  readonly manifestationId?: ManifestationId\n  readonly startedAt: Timestamp\n  readonly timeout?: number\n  readonly data: Record<string, unknown>\n  readonly logger: ExecutionLogger\n\n  private readonly invoker: InvocationHandler\n\n  constructor(options: RuntimeExecutionContextOptions) {\n    this.traceId = options.traceId\n    this.spanId = options.spanId\n    if (options.parentSpanId !== undefined) {\n      this.parentSpanId = options.parentSpanId\n    }\n    this.fabricId = options.fabricId\n    if (options.manifestationId !== undefined) {\n      this.manifestationId = options.manifestationId\n    }\n    this.startedAt = Date.now()\n    if (options.timeout !== undefined) {\n      this.timeout = options.timeout\n    }\n    this.data = options.data ?? {}\n    this.logger = options.logger ?? new ConsoleExecutionLogger(this.traceId, this.spanId)\n    this.invoker = options.invoker\n  }\n\n  invoke<TInput, TOutput>(\n    capabilityId: CapabilityId,\n    input: TInput\n  ): Promise<ExecutionResult<TOutput>> {\n    return this.invoker(capabilityId, input)\n  }\n\n  child(spanId: string): ExecutionContext {\n    const childOptions: RuntimeExecutionContextOptions = {\n      traceId: this.traceId,\n      spanId,\n      parentSpanId: this.spanId,\n      fabricId: this.fabricId,\n      invoker: this.invoker,\n      data: { ...this.data },\n      logger: new ConsoleExecutionLogger(this.traceId, spanId),\n    }\n    if (this.manifestationId !== undefined) {\n      childOptions.manifestationId = this.manifestationId\n    }\n    if (this.timeout !== undefined) {\n      childOptions.timeout = this.timeout\n    }\n    return new RuntimeExecutionContext(childOptions)\n  }\n}\n\n// ============================================================\n// CONTEXT FACTORY\n// ============================================================\n\n/**\n * Generate a unique trace ID\n */\nexport function generateTraceId(): string {\n  return `trace_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`\n}\n\n/**\n * Generate a unique span ID\n */\nexport function generateSpanId(): string {\n  return `span_${Math.random().toString(36).substr(2, 9)}`\n}\n\n/**\n * Options for creating an execution context\n */\nexport interface CreateExecutionContextOptions {\n  fabricId: FabricId\n  manifestationId?: ManifestationId\n  timeout?: number\n  data?: Record<string, unknown>\n  silent?: boolean\n  invoker: InvocationHandler\n}\n\n/**\n * Create a new execution context\n */\nexport function createExecutionContext(\n  options: CreateExecutionContextOptions\n): RuntimeExecutionContext {\n  const traceId = generateTraceId()\n  const spanId = generateSpanId()\n\n  const contextOptions: RuntimeExecutionContextOptions = {\n    traceId,\n    spanId,\n    fabricId: options.fabricId,\n    invoker: options.invoker,\n    logger: options.silent\n      ? new NoOpExecutionLogger()\n      : new ConsoleExecutionLogger(traceId, spanId),\n  }\n\n  if (options.manifestationId) {\n    contextOptions.manifestationId = options.manifestationId\n  }\n  if (options.timeout) {\n    contextOptions.timeout = options.timeout\n  }\n  if (options.data) {\n    contextOptions.data = options.data\n  }\n\n  return new RuntimeExecutionContext(contextOptions)\n}\n"]}

package/dist/executor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Task executor for PWFabric runtime
+ */
+import { type Result } from '@pwfabric/core';
+import { type RuntimeContext } from './context.js';
+/**
+ * Task definition
+ */
+export interface Task<TInput, TOutput> {
+    name: string;
+    execute: (input: TInput, ctx: RuntimeContext) => Promise<TOutput>;
+}
+/**
+ * Executor options
+ */
+export interface ExecutorOptions {
+    timeout?: number;
+    retries?: number;
+}
+/**
+ * Execute a task with the given input
+ */
+export declare function executeTask<TInput, TOutput>(task: Task<TInput, TOutput>, input: TInput, options?: ExecutorOptions): Promise<Result<TOutput, Error>>;
+/**
+ * Create a task definition
+ */
+export declare function defineTask<TInput, TOutput>(name: string, execute: (input: TInput, ctx: RuntimeContext) => Promise<TOutput>): Task<TInput, TOutput>;

package/dist/executor.js

@@ -0,0 +1,33 @@
+/**
+ * Task executor for PWFabric runtime
+ */
+import { ok, err } from '@pwfabric/core';
+import { createContext } from './context.js';
+/**
+ * Execute a task with the given input
+ */
+export async function executeTask(task, input, options = {}) {
+    const ctx = createContext(task.name);
+    const { timeout = 30000 } = options;
+    ctx.logger.info(`Starting task: ${task.name}`);
+    try {
+        const result = await Promise.race([
+            task.execute(input, ctx),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Task ${task.name} timed out after ${timeout}ms`)), timeout)),
+        ]);
+        ctx.logger.info(`Task ${task.name} completed successfully`);
+        return ok(result);
+    }
+    catch (error) {
+        const err_ = error instanceof Error ? error : new Error(String(error));
+        ctx.logger.error(`Task ${task.name} failed`, { error: err_.message });
+        return err(err_);
+    }
+}
+/**
+ * Create a task definition
+ */
+export function defineTask(name, execute) {
+    return { name, execute };
+}
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAe,EAAE,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAuB,aAAa,EAAE,MAAM,cAAc,CAAA;AAkBjE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAA2B,EAC3B,KAAa,EACb,UAA2B,EAAE;IAE7B,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACpC,MAAM,EAAE,OAAO,GAAG,KAAK,EAAE,GAAG,OAAO,CAAA;IAEnC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;IAE9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAChC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;YACxB,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CACR,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC,IAAI,oBAAoB,OAAO,IAAI,CAAC,CAAC,EACzE,OAAO,CACR,CACF;SACF,CAAC,CAAA;QAEF,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,yBAAyB,CAAC,CAAA;QAC3D,OAAO,EAAE,CAAC,MAAM,CAAC,CAAA;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QACtE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,IAAI,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;QACrE,OAAO,GAAG,CAAC,IAAI,CAAC,CAAA;IAClB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,OAAiE;IAEjE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;AAC1B,CAAC","sourcesContent":["/**\n * Task executor for PWFabric runtime\n */\n\nimport { type Result, ok, err } from '@pwfabric/core'\nimport { type RuntimeContext, createContext } from './context.js'\n\n/**\n * Task definition\n */\nexport interface Task<TInput, TOutput> {\n  name: string\n  execute: (input: TInput, ctx: RuntimeContext) => Promise<TOutput>\n}\n\n/**\n * Executor options\n */\nexport interface ExecutorOptions {\n  timeout?: number\n  retries?: number\n}\n\n/**\n * Execute a task with the given input\n */\nexport async function executeTask<TInput, TOutput>(\n  task: Task<TInput, TOutput>,\n  input: TInput,\n  options: ExecutorOptions = {}\n): Promise<Result<TOutput, Error>> {\n  const ctx = createContext(task.name)\n  const { timeout = 30000 } = options\n\n  ctx.logger.info(`Starting task: ${task.name}`)\n\n  try {\n    const result = await Promise.race([\n      task.execute(input, ctx),\n      new Promise<never>((_, reject) =>\n        setTimeout(\n          () => reject(new Error(`Task ${task.name} timed out after ${timeout}ms`)),\n          timeout\n        )\n      ),\n    ])\n\n    ctx.logger.info(`Task ${task.name} completed successfully`)\n    return ok(result)\n  } catch (error) {\n    const err_ = error instanceof Error ? error : new Error(String(error))\n    ctx.logger.error(`Task ${task.name} failed`, { error: err_.message })\n    return err(err_)\n  }\n}\n\n/**\n * Create a task definition\n */\nexport function defineTask<TInput, TOutput>(\n  name: string,\n  execute: (input: TInput, ctx: RuntimeContext) => Promise<TOutput>\n): Task<TInput, TOutput> {\n  return { name, execute }\n}\n"]}

package/dist/forms/form-entity-bridge.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Form → Entity Declarative Bridge
+ *
+ * Attaches a form-to-entity bridge to the SurfaceEventBus.
+ * When a specified form emits 'form:submit', writes to the data source the
+ * binding names — our own store or anyone else's endpoint.
+ *
+ * Requires `platform/entities` capability (platform/input retired;
+ * form submissions now flow exclusively through entity_records).
+ *
+ * @module @pwfabric/runtime/forms/form-entity-bridge
+ */
+import type { SurfaceEventBus } from '@pwfabric/contracts';
+import type { EntityMutationResult, EntityOperationError } from '../entity/types.js';
+export type { Unsubscribe } from '@pwfabric/contracts';
+export interface FormEntityBridgeConfig {
+    /** The form block ID to listen for. */
+    formId: string;
+    /**
+     * The DATA SOURCE this form writes to.
+     *
+     * It used to be `entityType` — a platform model — which is why "why can we
+     * not POST to our own endpoint?" was a question with no answer: the form's
+     * only expressible destination was our store. A source has an address, and
+     * our store's address is one of them.
+     *
+     * The read half already worked this way; this is the write half catching up.
+     */
+    sourceId: string;
+    /** How to write. Defaults to POST — the only shape a form has ever had. */
+    method?: 'POST' | 'PUT' | 'PATCH';
+    /**
+     * Optional mapping from form values to entity data.
+     * If omitted, form values are passed as-is.
+     */
+    mapping?: (values: Record<string, unknown>) => Record<string, unknown>;
+    /** Called on successful entity creation. */
+    onSuccess?: (result: EntityMutationResult & {
+        success: true;
+    }) => void;
+    /** Called when entity creation fails. */
+    onError?: (error: EntityOperationError) => void;
+    /**
+     * Optional path to navigate to after success.
+     * Uses window.location.assign (client-side only).
+     */
+    successRedirect?: string;
+    /**
+     * Surface-state keys the bridge drives across the create lifecycle, so the
+     * UI reflects the REAL API result (not an optimistic onSubmitAction):
+     * `loading` true while the create is in flight, then `success` OR `error`.
+     * Each is a boolean set via setState; gate blocks with if:{{state.<key>}}.
+     */
+    statusKeys?: {
+        loading?: string;
+        success?: string;
+        error?: string;
+        /**
+         * Where the writer's OWN WORDS go on failure — the server's status and
+         * message, or the validation sentence naming the fields. Cleared (`''`)
+         * when an attempt starts and on success, so a toast bound to it never
+         * shows yesterday's refusal. Without it a page can only say "it failed"
+         * and has to invent why.
+         */
+        message?: string;
+    };
+}
+/**
+ * Where a form's submission is actually sent.
+ *
+ * One method, because a form has one job. The host decides what a source id
+ * means — the entity facade for a platform-backed source, an HTTP call for a
+ * rest one — which is what lets the same declaration serve both without the
+ * bridge knowing the difference.
+ */
+export interface FormWriter {
+    write(sourceId: string, values: Record<string, unknown>, method: 'POST' | 'PUT' | 'PATCH'): Promise<EntityMutationResult>;
+}
+/**
+ * Attaches a form-to-entity bridge to the SurfaceEventBus.
+ * When the specified form emits 'form:submit', writes to the source the
+ * binding names.
+ *
+ * Requires `platform/entities` capability active (platform/input retired).
+ *
+ * @returns Unsubscribe function — call on surface unmount.
+ */
+export declare function attachFormEntityBridge(bus: SurfaceEventBus, writer: FormWriter, config: FormEntityBridgeConfig, 
+/**
+ * Completes what the form block gathered before it is mapped and written —
+ * the host adds the named controls `FormData` cannot see (a control drawn
+ * from buttons has no native field; see forms/named-control-values).
+ */
+completeValues?: (formId: string, values: Record<string, unknown>) => Record<string, unknown>): () => void;

package/dist/forms/form-entity-bridge.js

@@ -0,0 +1,96 @@
+/**
+ * Form → Entity Declarative Bridge
+ *
+ * Attaches a form-to-entity bridge to the SurfaceEventBus.
+ * When a specified form emits 'form:submit', writes to the data source the
+ * binding names — our own store or anyone else's endpoint.
+ *
+ * Requires `platform/entities` capability (platform/input retired;
+ * form submissions now flow exclusively through entity_records).
+ *
+ * @module @pwfabric/runtime/forms/form-entity-bridge
+ */
+/**
+ * Attaches a form-to-entity bridge to the SurfaceEventBus.
+ * When the specified form emits 'form:submit', writes to the source the
+ * binding names.
+ *
+ * Requires `platform/entities` capability active (platform/input retired).
+ *
+ * @returns Unsubscribe function — call on surface unmount.
+ */
+export function attachFormEntityBridge(bus, writer, config, 
+/**
+ * Completes what the form block gathered before it is mapped and written —
+ * the host adds the named controls `FormData` cannot see (a control drawn
+ * from buttons has no native field; see forms/named-control-values).
+ */
+completeValues) {
+    // Drive a surface-state boolean via setState on the bus → handleEvent
+    // (DataBoundInner) applies it. Lets the UI reflect the REAL create lifecycle.
+    const sk = config.statusKeys;
+    const setState = (surfaceId, blockId, key, value) => {
+        bus.emit({
+            type: 'capability:form-status',
+            surfaceId,
+            ...(blockId ? { blockId } : {}),
+            payload: { action: { type: 'setState', key, value } },
+            timestamp: Date.now(),
+        });
+    };
+    return bus.on('form:submit', async (descriptor) => {
+        // Only handle events for the configured form
+        if (descriptor.blockId !== config.formId)
+            return;
+        const gathered = descriptor.payload?.values ?? {};
+        const rawValues = completeValues ? completeValues(config.formId, gathered) : gathered;
+        const mapped = config.mapping ? config.mapping(rawValues) : rawValues;
+        // Lifecycle start: loading on, clear any prior success/error so the UI is
+        // accurate for THIS attempt.
+        if (sk?.loading)
+            setState(descriptor.surfaceId, descriptor.blockId, sk.loading, true);
+        if (sk?.success)
+            setState(descriptor.surfaceId, descriptor.blockId, sk.success, false);
+        if (sk?.error)
+            setState(descriptor.surfaceId, descriptor.blockId, sk.error, false);
+        if (sk?.message)
+            setState(descriptor.surfaceId, descriptor.blockId, sk.message, '');
+        const result = await writer.write(config.sourceId, mapped, config.method ?? 'POST');
+        // Loading off regardless of outcome.
+        if (sk?.loading)
+            setState(descriptor.surfaceId, descriptor.blockId, sk.loading, false);
+        if (result.success) {
+            config.onSuccess?.(result);
+            // Success is bound to the API result (not optimistic).
+            if (sk?.success)
+                setState(descriptor.surfaceId, descriptor.blockId, sk.success, true);
+            // Reactive read half: re-fetch data sources so an entity-backed list
+            // (dataSource kind:'entity') reflects the just-created record.
+            bus.emit({
+                type: 'entity:created',
+                surfaceId: descriptor.surfaceId,
+                ...(descriptor.blockId ? { blockId: descriptor.blockId } : {}),
+                // Keyed by the SOURCE, because that is what a reader re-fetches. It
+                // used to be the entity type, which only a platform-backed list could
+                // match.
+                payload: { action: { type: 'refreshAll' }, sourceId: config.sourceId },
+                timestamp: Date.now(),
+            });
+            if (config.successRedirect) {
+                // Client-side navigation — safe to call in browser context
+                if (typeof window !== 'undefined') {
+                    window.location.assign(config.successRedirect);
+                }
+            }
+        }
+        else {
+            config.onError?.(result.error);
+            // Failure is bound to the API result — and so are its words.
+            if (sk?.error)
+                setState(descriptor.surfaceId, descriptor.blockId, sk.error, true);
+            if (sk?.message)
+                setState(descriptor.surfaceId, descriptor.blockId, sk.message, result.error.message);
+        }
+    });
+}
+//# sourceMappingURL=form-entity-bridge.js.map

package/dist/forms/form-entity-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-entity-bridge.js","sourceRoot":"","sources":["../../src/forms/form-entity-bridge.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Form → Entity Declarative Bridge\n *\n * Attaches a form-to-entity bridge to the SurfaceEventBus.\n * When a specified form emits 'form:submit', writes to the data source the\n * binding names — our own store or anyone else's endpoint.\n *\n * Requires `platform/entities` capability (platform/input retired;\n * form submissions now flow exclusively through entity_records).\n *\n * @module @pwfabric/runtime/forms/form-entity-bridge\n */\n\nimport type { SurfaceEventBus } from '@pwfabric/contracts'\nimport type { EntityMutationResult, EntityOperationError } from '../entity/types.js'\n\n// Re-export Unsubscribe from contracts for convenience\nexport type { Unsubscribe } from '@pwfabric/contracts'\n\nexport interface FormEntityBridgeConfig {\n  /** The form block ID to listen for. */\n  formId: string\n  /**\n   * The DATA SOURCE this form writes to.\n   *\n   * It used to be `entityType` — a platform model — which is why \"why can we\n   * not POST to our own endpoint?\" was a question with no answer: the form's\n   * only expressible destination was our store. A source has an address, and\n   * our store's address is one of them.\n   *\n   * The read half already worked this way; this is the write half catching up.\n   */\n  sourceId: string\n  /** How to write. Defaults to POST — the only shape a form has ever had. */\n  method?: 'POST' | 'PUT' | 'PATCH'\n  /**\n   * Optional mapping from form values to entity data.\n   * If omitted, form values are passed as-is.\n   */\n  mapping?: (values: Record<string, unknown>) => Record<string, unknown>\n  /** Called on successful entity creation. */\n  onSuccess?: (result: EntityMutationResult & { success: true }) => void\n  /** Called when entity creation fails. */\n  onError?: (error: EntityOperationError) => void\n  /**\n   * Optional path to navigate to after success.\n   * Uses window.location.assign (client-side only).\n   */\n  successRedirect?: string\n  /**\n   * Surface-state keys the bridge drives across the create lifecycle, so the\n   * UI reflects the REAL API result (not an optimistic onSubmitAction):\n   * `loading` true while the create is in flight, then `success` OR `error`.\n   * Each is a boolean set via setState; gate blocks with if:{{state.<key>}}.\n   */\n  statusKeys?: {\n    loading?: string\n    success?: string\n    error?: string\n    /**\n     * Where the writer's OWN WORDS go on failure — the server's status and\n     * message, or the validation sentence naming the fields. Cleared (`''`)\n     * when an attempt starts and on success, so a toast bound to it never\n     * shows yesterday's refusal. Without it a page can only say \"it failed\"\n     * and has to invent why.\n     */\n    message?: string\n  }\n}\n\n/**\n * Where a form's submission is actually sent.\n *\n * One method, because a form has one job. The host decides what a source id\n * means — the entity facade for a platform-backed source, an HTTP call for a\n * rest one — which is what lets the same declaration serve both without the\n * bridge knowing the difference.\n */\nexport interface FormWriter {\n  write(\n    sourceId: string,\n    values: Record<string, unknown>,\n    method: 'POST' | 'PUT' | 'PATCH'\n  ): Promise<EntityMutationResult>\n}\n\n/**\n * Attaches a form-to-entity bridge to the SurfaceEventBus.\n * When the specified form emits 'form:submit', writes to the source the\n * binding names.\n *\n * Requires `platform/entities` capability active (platform/input retired).\n *\n * @returns Unsubscribe function — call on surface unmount.\n */\nexport function attachFormEntityBridge(\n  bus: SurfaceEventBus,\n  writer: FormWriter,\n  config: FormEntityBridgeConfig,\n  /**\n   * Completes what the form block gathered before it is mapped and written —\n   * the host adds the named controls `FormData` cannot see (a control drawn\n   * from buttons has no native field; see forms/named-control-values).\n   */\n  completeValues?: (formId: string, values: Record<string, unknown>) => Record<string, unknown>\n): () => void {\n  // Drive a surface-state boolean via setState on the bus → handleEvent\n  // (DataBoundInner) applies it. Lets the UI reflect the REAL create lifecycle.\n  const sk = config.statusKeys\n  const setState = (surfaceId: string, blockId: string | undefined, key: string, value: unknown): void => {\n    bus.emit({\n      type: 'capability:form-status',\n      surfaceId,\n      ...(blockId ? { blockId } : {}),\n      payload: { action: { type: 'setState', key, value } },\n      timestamp: Date.now(),\n    })\n  }\n\n  return bus.on('form:submit', async (descriptor) => {\n    // Only handle events for the configured form\n    if (descriptor.blockId !== config.formId) return\n\n    const gathered = (descriptor.payload?.values as Record<string, unknown>) ?? {}\n    const rawValues = completeValues ? completeValues(config.formId, gathered) : gathered\n    const mapped = config.mapping ? config.mapping(rawValues) : rawValues\n\n    // Lifecycle start: loading on, clear any prior success/error so the UI is\n    // accurate for THIS attempt.\n    if (sk?.loading) setState(descriptor.surfaceId, descriptor.blockId, sk.loading, true)\n    if (sk?.success) setState(descriptor.surfaceId, descriptor.blockId, sk.success, false)\n    if (sk?.error) setState(descriptor.surfaceId, descriptor.blockId, sk.error, false)\n    if (sk?.message) setState(descriptor.surfaceId, descriptor.blockId, sk.message, '')\n\n    const result = await writer.write(config.sourceId, mapped, config.method ?? 'POST')\n\n    // Loading off regardless of outcome.\n    if (sk?.loading) setState(descriptor.surfaceId, descriptor.blockId, sk.loading, false)\n\n    if (result.success) {\n      config.onSuccess?.(result)\n      // Success is bound to the API result (not optimistic).\n      if (sk?.success) setState(descriptor.surfaceId, descriptor.blockId, sk.success, true)\n      // Reactive read half: re-fetch data sources so an entity-backed list\n      // (dataSource kind:'entity') reflects the just-created record.\n      bus.emit({\n        type: 'entity:created',\n        surfaceId: descriptor.surfaceId,\n        ...(descriptor.blockId ? { blockId: descriptor.blockId } : {}),\n        // Keyed by the SOURCE, because that is what a reader re-fetches. It\n        // used to be the entity type, which only a platform-backed list could\n        // match.\n        payload: { action: { type: 'refreshAll' }, sourceId: config.sourceId },\n        timestamp: Date.now(),\n      })\n      if (config.successRedirect) {\n        // Client-side navigation — safe to call in browser context\n        if (typeof window !== 'undefined') {\n          window.location.assign(config.successRedirect)\n        }\n      }\n    } else {\n      config.onError?.(result.error)\n      // Failure is bound to the API result — and so are its words.\n      if (sk?.error) setState(descriptor.surfaceId, descriptor.blockId, sk.error, true)\n      if (sk?.message) setState(descriptor.surfaceId, descriptor.blockId, sk.message, result.error.message)\n    }\n  })\n}\n"]}

package/dist/forms/form-write-target.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Form write target — WHICH verb, WHICH record, and what a refusal means.
+ *
+ * A form binding says how it wants to write (`method: 'PATCH'`), but a PATCH
+ * has to name a record and the page only knows one from what its source
+ * loaded. When nothing loaded there is nothing to patch; the honest write is a
+ * create. Otherwise a Profile form would send `PATCH /records/Attendee` — the
+ * collection, no id — the API would answer 404 "Route not found", and the
+ * page would report it as a field-validation problem with no field
+ * highlighted.
+ *
+ * Two pure functions, so the rule is testable without a DOM and the same
+ * answer serves the in-process facade and the HTTP path alike.
+ *
+ * @module @pwfabric/runtime/forms/form-write-target
+ */
+import type { DataFetchError } from '../data/types.js';
+import type { EntityOperationError } from '../entity/types.js';
+export type FormWriteMethod = 'POST' | 'PUT' | 'PATCH';
+export interface FormWriteTarget {
+    readonly method: FormWriteMethod;
+    /** Present only for an update — the id of the record the source has loaded. */
+    readonly recordId?: string;
+}
+export declare function resolveFormWriteTarget(method: FormWriteMethod, bound: unknown): FormWriteTarget;
+/**
+ * Translate a data-layer refusal into what the form should say.
+ *
+ * "Check the highlighted fields" is reserved for a 400 that names fields.
+ * Anything else is the server refusing, and the server's own status and
+ * words are the message — a 404 on the collection path is a routing fact,
+ * not a problem with what the visitor typed.
+ */
+export declare function toFormWriteError(err: DataFetchError): EntityOperationError;

package/dist/forms/form-write-target.js

@@ -0,0 +1,81 @@
+/**
+ * Form write target — WHICH verb, WHICH record, and what a refusal means.
+ *
+ * A form binding says how it wants to write (`method: 'PATCH'`), but a PATCH
+ * has to name a record and the page only knows one from what its source
+ * loaded. When nothing loaded there is nothing to patch; the honest write is a
+ * create. Otherwise a Profile form would send `PATCH /records/Attendee` — the
+ * collection, no id — the API would answer 404 "Route not found", and the
+ * page would report it as a field-validation problem with no field
+ * highlighted.
+ *
+ * Two pure functions, so the rule is testable without a DOM and the same
+ * answer serves the in-process facade and the HTTP path alike.
+ *
+ * @module @pwfabric/runtime/forms/form-write-target
+ */
+/**
+ * The record a source currently binds, if any.
+ *
+ * A list source binds an array (the platform's record reads always do — see
+ * `LIST_KINDS` in DataBoundSurfaceRenderer); a single-record source may bind
+ * an object. The FIRST row is the record a form on that page edits: a
+ * profile page reads "me", a settings page reads "the one preference row".
+ */
+function boundRecord(bound) {
+    const candidate = Array.isArray(bound) ? bound[0] : bound;
+    return candidate !== null && typeof candidate === 'object' && !Array.isArray(candidate)
+        ? candidate
+        : undefined;
+}
+export function resolveFormWriteTarget(method, bound) {
+    if (method === 'POST')
+        return { method: 'POST' };
+    const id = boundRecord(bound)?.['id'];
+    const recordId = typeof id === 'string' ? id : typeof id === 'number' ? String(id) : undefined;
+    return recordId ? { method, recordId } : { method: 'POST' };
+}
+/**
+ * The field paths a validation refusal names.
+ *
+ * The API answers `VALIDATION_FAILED` with `path: message; path: message`
+ * (the host's app-records API). Read the paths out so a
+ * form can highlight them; keep the whole sentence so the visitor can too.
+ */
+function fieldPathsOf(message) {
+    return message
+        .split(';')
+        .map((part) => part.trim())
+        .filter((part) => part.includes(':'))
+        .map((part) => part.slice(0, part.indexOf(':')).trim())
+        .filter((path) => path.length > 0 && !/\s/.test(path));
+}
+const VALIDATION_CODES = new Set(['VALIDATION_FAILED', 'INVALID_BODY']);
+/**
+ * Translate a data-layer refusal into what the form should say.
+ *
+ * "Check the highlighted fields" is reserved for a 400 that names fields.
+ * Anything else is the server refusing, and the server's own status and
+ * words are the message — a 404 on the collection path is a routing fact,
+ * not a problem with what the visitor typed.
+ */
+export function toFormWriteError(err) {
+    const { status, code, message } = err;
+    if (status === undefined) {
+        return { type: 'connector', message: `Could not reach the server: ${message}` };
+    }
+    if (status === 400 && (code === undefined || VALIDATION_CODES.has(code))) {
+        return {
+            type: 'validation',
+            message: `Check the highlighted fields — ${message}`,
+            details: { status, code, fields: fieldPathsOf(message) },
+        };
+    }
+    const type = status === 404 ? 'not_found' : status === 401 || status === 403 ? 'unauthorized' : 'connector';
+    return {
+        type,
+        message: `The server could not save this record (${status}): ${message}`,
+        details: { status, code },
+    };
+}
+//# sourceMappingURL=form-write-target.js.map