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

package/dist/render/keyframes-css.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Surface keyframe registry CSS generation (arbitrary `@keyframes`).
+ *
+ * The runtime ships a fixed set of `pw-*` keyframes in `SURFACE_BASE_CSS`
+ * (pulse / fade-in / marquee / slide-up / slide-down / scale-in / spin /
+ * bounce / spring-in), so `block.style.animation` could only reference those. A surface can
+ * now declare arbitrary named keyframes via `appearance.config.keyframes`
+ * (name → keyframe body); this module emits one `@keyframes <name>{<body>}` per
+ * entry so a block can drive custom motion offline.
+ *
+ * Each name is PREFIXED with `pw-kf-` to avoid colliding with host-page or
+ * runtime-shipped keyframes — so a surface declaring `{ wiggle: '…' }` makes the
+ * animation available as `pw-kf-wiggle`, and a block references it via
+ * `block.style.animation: 'pw-kf-wiggle 0.4s ease'`.
+ *
+ * The keyframe BODY passes through untouched (authors supply standard
+ * `@keyframes` selector blocks, e.g. `0%{…}50%{…}100%{…}`). An empty/absent
+ * registry emits zero bytes. The existing `prefers-reduced-motion` gate in
+ * `SURFACE_BASE_CSS` neutralises these animations for users who opt out (it
+ * matches by animation, not by keyframe name), so no extra gating is needed
+ * here.
+ *
+ * @module @pwfabric/runtime/render/keyframes-css
+ */
+/**
+ * Build the surface keyframe CSS from the appearance `keyframes` registry
+ * (name → keyframe body). Emits `@keyframes pw-kf-<name>{<body>}` for each
+ * entry. Entries with an empty name or empty body are skipped. Returns '' when
+ * the registry is empty/undefined (zero bytes emitted).
+ */
+export declare function buildKeyframesCss(keyframes: Readonly<Record<string, string>> | undefined): string;

package/dist/render/keyframes-css.js

@@ -0,0 +1,44 @@
+/**
+ * Surface keyframe registry CSS generation (arbitrary `@keyframes`).
+ *
+ * The runtime ships a fixed set of `pw-*` keyframes in `SURFACE_BASE_CSS`
+ * (pulse / fade-in / marquee / slide-up / slide-down / scale-in / spin /
+ * bounce / spring-in), so `block.style.animation` could only reference those. A surface can
+ * now declare arbitrary named keyframes via `appearance.config.keyframes`
+ * (name → keyframe body); this module emits one `@keyframes <name>{<body>}` per
+ * entry so a block can drive custom motion offline.
+ *
+ * Each name is PREFIXED with `pw-kf-` to avoid colliding with host-page or
+ * runtime-shipped keyframes — so a surface declaring `{ wiggle: '…' }` makes the
+ * animation available as `pw-kf-wiggle`, and a block references it via
+ * `block.style.animation: 'pw-kf-wiggle 0.4s ease'`.
+ *
+ * The keyframe BODY passes through untouched (authors supply standard
+ * `@keyframes` selector blocks, e.g. `0%{…}50%{…}100%{…}`). An empty/absent
+ * registry emits zero bytes. The existing `prefers-reduced-motion` gate in
+ * `SURFACE_BASE_CSS` neutralises these animations for users who opt out (it
+ * matches by animation, not by keyframe name), so no extra gating is needed
+ * here.
+ *
+ * @module @pwfabric/runtime/render/keyframes-css
+ */
+/** Prefix applied to every surface-declared keyframe name (collision guard). */
+const KEYFRAME_PREFIX = 'pw-kf-';
+/**
+ * Build the surface keyframe CSS from the appearance `keyframes` registry
+ * (name → keyframe body). Emits `@keyframes pw-kf-<name>{<body>}` for each
+ * entry. Entries with an empty name or empty body are skipped. Returns '' when
+ * the registry is empty/undefined (zero bytes emitted).
+ */
+export function buildKeyframesCss(keyframes) {
+    if (!keyframes)
+        return '';
+    let css = '';
+    for (const [name, body] of Object.entries(keyframes)) {
+        if (!name || typeof body !== 'string' || body.trim().length === 0)
+            continue;
+        css += `@keyframes ${KEYFRAME_PREFIX}${name}{${body}}`;
+    }
+    return css;
+}
+//# sourceMappingURL=keyframes-css.js.map

package/dist/render/keyframes-css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyframes-css.js","sourceRoot":"","sources":["../../src/render/keyframes-css.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,gFAAgF;AAChF,MAAM,eAAe,GAAG,QAAQ,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAuD;IAEvD,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAA;IACzB,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,SAAQ;QAC3E,GAAG,IAAI,cAAc,eAAe,GAAG,IAAI,IAAI,IAAI,GAAG,CAAA;IACxD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC","sourcesContent":["/**\n * Surface keyframe registry CSS generation (arbitrary `@keyframes`).\n *\n * The runtime ships a fixed set of `pw-*` keyframes in `SURFACE_BASE_CSS`\n * (pulse / fade-in / marquee / slide-up / slide-down / scale-in / spin /\n * bounce / spring-in), so `block.style.animation` could only reference those. A surface can\n * now declare arbitrary named keyframes via `appearance.config.keyframes`\n * (name → keyframe body); this module emits one `@keyframes <name>{<body>}` per\n * entry so a block can drive custom motion offline.\n *\n * Each name is PREFIXED with `pw-kf-` to avoid colliding with host-page or\n * runtime-shipped keyframes — so a surface declaring `{ wiggle: '…' }` makes the\n * animation available as `pw-kf-wiggle`, and a block references it via\n * `block.style.animation: 'pw-kf-wiggle 0.4s ease'`.\n *\n * The keyframe BODY passes through untouched (authors supply standard\n * `@keyframes` selector blocks, e.g. `0%{…}50%{…}100%{…}`). An empty/absent\n * registry emits zero bytes. The existing `prefers-reduced-motion` gate in\n * `SURFACE_BASE_CSS` neutralises these animations for users who opt out (it\n * matches by animation, not by keyframe name), so no extra gating is needed\n * here.\n *\n * @module @pwfabric/runtime/render/keyframes-css\n */\n\n/** Prefix applied to every surface-declared keyframe name (collision guard). */\nconst KEYFRAME_PREFIX = 'pw-kf-'\n\n/**\n * Build the surface keyframe CSS from the appearance `keyframes` registry\n * (name → keyframe body). Emits `@keyframes pw-kf-<name>{<body>}` for each\n * entry. Entries with an empty name or empty body are skipped. Returns '' when\n * the registry is empty/undefined (zero bytes emitted).\n */\nexport function buildKeyframesCss(\n  keyframes: Readonly<Record<string, string>> | undefined\n): string {\n  if (!keyframes) return ''\n  let css = ''\n  for (const [name, body] of Object.entries(keyframes)) {\n    if (!name || typeof body !== 'string' || body.trim().length === 0) continue\n    css += `@keyframes ${KEYFRAME_PREFIX}${name}{${body}}`\n  }\n  return css\n}\n"]}

package/dist/render/query-state.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveQueryState<T>(query: T, state: Readonly<Record<string, unknown>>): T;
+/** True when any string inside the query carries an expression. */
+export declare function queryHasState(query: unknown): boolean;

package/dist/render/query-state.js

@@ -0,0 +1,70 @@
+/**
+ * resolveQueryState — substitute `{{state.x}}` (and any expression) inside a
+ * data-source `query` object before it reaches the connector.
+ *
+ * Without it state would be interpolated ONLY in REST `endpoint` strings and
+ * connector/entity sources would pass `source.query` to the engine raw, so a
+ * pagination block writing `state.page` and a segmented-control writing
+ * `state.severity` could never reach `query.pagination.offset` or
+ * `query.filter.value`. This walks the query deeply and resolves every string
+ * that contains `{{ }}`.
+ *
+ * A string that is EXACTLY one expression (`"{{state.page}}"`) resolves to
+ * the raw value (number stays number, array stays array) so
+ * `pagination.limit: "{{state.pageSize}}"` yields a number, not "20".
+ * Mixed strings (`"prefix-{{state.x}}"`) resolve to a string.
+ */
+import { createExpressionContext, evaluate, interpolate } from '../surface/expression.js';
+const WHOLE = /^\s*\{\{\s*([^{}]+?)\s*\}\}\s*$/;
+export function resolveQueryState(query, state) {
+    const ctx = createExpressionContext({ state });
+    const walk = (v) => {
+        if (typeof v === 'string') {
+            if (!v.includes('{{'))
+                return v;
+            const whole = WHOLE.exec(v);
+            if (whole && whole[1] !== undefined) {
+                const r = evaluate(whole[1], ctx);
+                if (!r.success)
+                    return undefined;
+                // An "All" segment and an empty search box both write '' (or null) into
+                // state. Read literally that is `field eq ''`, which matches no row —
+                // the control that was meant to WIDEN the list emptied it. A whole
+                // expression resolving to nothing is no constraint, so the key drops.
+                // A literal '' written into the query by an author is untouched: only
+                // an expression can resolve away.
+                if (r.value === '' || r.value === null)
+                    return undefined;
+                return r.value;
+            }
+            const r = interpolate(v, ctx);
+            return r.success ? r.value : v;
+        }
+        if (Array.isArray(v))
+            return v.map(walk);
+        if (v && typeof v === 'object') {
+            const out = {};
+            for (const [k, val] of Object.entries(v)) {
+                const w = walk(val);
+                // an unresolved whole-expression drops the key so the connector sees
+                // "no constraint", not `undefined` as a literal filter value
+                if (w !== undefined)
+                    out[k] = w;
+            }
+            return out;
+        }
+        return v;
+    };
+    return walk(query);
+}
+/** True when any string inside the query carries an expression. */
+export function queryHasState(query) {
+    if (typeof query === 'string')
+        return query.includes('{{');
+    if (Array.isArray(query))
+        return query.some(queryHasState);
+    if (query && typeof query === 'object')
+        return Object.values(query).some(queryHasState);
+    return false;
+}
+//# sourceMappingURL=query-state.js.map

package/dist/render/query-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-state.js","sourceRoot":"","sources":["../../src/render/query-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,uBAAuB,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAEzF,MAAM,KAAK,GAAG,iCAAiC,CAAA;AAE/C,MAAM,UAAU,iBAAiB,CAAI,KAAQ,EAAE,KAAwC;IACrF,MAAM,GAAG,GAAG,uBAAuB,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;IAC9C,MAAM,IAAI,GAAG,CAAC,CAAU,EAAW,EAAE;QACnC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAA;YAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAC3B,IAAI,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;gBACpC,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;gBACjC,IAAI,CAAC,CAAC,CAAC,OAAO;oBAAE,OAAO,SAAS,CAAA;gBAChC,wEAAwE;gBACxE,sEAAsE;gBACtE,mEAAmE;gBACnE,sEAAsE;gBACtE,sEAAsE;gBACtE,kCAAkC;gBAClC,IAAI,CAAC,CAAC,KAAK,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI;oBAAE,OAAO,SAAS,CAAA;gBACxD,OAAO,CAAC,CAAC,KAAK,CAAA;YAChB,CAAC;YACD,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;YAC7B,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAChC,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACxC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC/B,MAAM,GAAG,GAA4B,EAAE,CAAA;YACvC,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,EAAE,CAAC;gBACpE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;gBACnB,qEAAqE;gBACrE,6DAA6D;gBAC7D,IAAI,CAAC,KAAK,SAAS;oBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;YACjC,CAAC;YACD,OAAO,GAAG,CAAA;QACZ,CAAC;QACD,OAAO,CAAC,CAAA;IACV,CAAC,CAAA;IACD,OAAO,IAAI,CAAC,KAAK,CAAM,CAAA;AACzB,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IAC1D,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAgC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IAClH,OAAO,KAAK,CAAA;AACd,CAAC","sourcesContent":["/**\n * resolveQueryState — substitute `{{state.x}}` (and any expression) inside a\n * data-source `query` object before it reaches the connector.\n *\n * Without it state would be interpolated ONLY in REST `endpoint` strings and\n * connector/entity sources would pass `source.query` to the engine raw, so a\n * pagination block writing `state.page` and a segmented-control writing\n * `state.severity` could never reach `query.pagination.offset` or\n * `query.filter.value`. This walks the query deeply and resolves every string\n * that contains `{{ }}`.\n *\n * A string that is EXACTLY one expression (`\"{{state.page}}\"`) resolves to\n * the raw value (number stays number, array stays array) so\n * `pagination.limit: \"{{state.pageSize}}\"` yields a number, not \"20\".\n * Mixed strings (`\"prefix-{{state.x}}\"`) resolve to a string.\n */\nimport { createExpressionContext, evaluate, interpolate } from '../surface/expression.js'\n\nconst WHOLE = /^\\s*\\{\\{\\s*([^{}]+?)\\s*\\}\\}\\s*$/\n\nexport function resolveQueryState<T>(query: T, state: Readonly<Record<string, unknown>>): T {\n  const ctx = createExpressionContext({ state })\n  const walk = (v: unknown): unknown => {\n    if (typeof v === 'string') {\n      if (!v.includes('{{')) return v\n      const whole = WHOLE.exec(v)\n      if (whole && whole[1] !== undefined) {\n        const r = evaluate(whole[1], ctx)\n        if (!r.success) return undefined\n        // An \"All\" segment and an empty search box both write '' (or null) into\n        // state. Read literally that is `field eq ''`, which matches no row —\n        // the control that was meant to WIDEN the list emptied it. A whole\n        // expression resolving to nothing is no constraint, so the key drops.\n        // A literal '' written into the query by an author is untouched: only\n        // an expression can resolve away.\n        if (r.value === '' || r.value === null) return undefined\n        return r.value\n      }\n      const r = interpolate(v, ctx)\n      return r.success ? r.value : v\n    }\n    if (Array.isArray(v)) return v.map(walk)\n    if (v && typeof v === 'object') {\n      const out: Record<string, unknown> = {}\n      for (const [k, val] of Object.entries(v as Record<string, unknown>)) {\n        const w = walk(val)\n        // an unresolved whole-expression drops the key so the connector sees\n        // \"no constraint\", not `undefined` as a literal filter value\n        if (w !== undefined) out[k] = w\n      }\n      return out\n    }\n    return v\n  }\n  return walk(query) as T\n}\n\n/** True when any string inside the query carries an expression. */\nexport function queryHasState(query: unknown): boolean {\n  if (typeof query === 'string') return query.includes('{{')\n  if (Array.isArray(query)) return query.some(queryHasState)\n  if (query && typeof query === 'object') return Object.values(query as Record<string, unknown>).some(queryHasState)\n  return false\n}\n"]}

package/dist/render/renderer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Surface Renderer
+ *
+ * Phase 2A.1: Main Surface-to-React rendering component
+ *
+ * @module @pwfabric/runtime/render/renderer
+ */
+import * as React from 'react';
+import type { Block } from '@pwfabric/core';
+import type { SurfaceRendererProps, BlockComponentRegistry, CapabilityProvider, ImageAdapter } from './types.js';
+/**
+ * SurfaceRenderer component
+ *
+ * Renders a surface definition to React components. surface
+ * definitions come from the pack-derived registry (the host's installed
+ * blocks and receipts) rather than hardcoded starter exports.
+ */
+export declare function SurfaceRenderer({ surface, capabilities, theme, projectTheme, projectDarkTheme, basePath, onEvent, components: customComponents, className, viewport: viewportProp, gap, padding, imageAdapter, entityFacade, connections, renderBlockWrapper, interactionMode, }: SurfaceRendererProps): React.ReactElement;
+/**
+ * Standalone block renderer
+ *
+ * Renders a single block without a surface wrapper.
+ */
+export declare function BlockRenderer({ block, capabilities, theme: _theme, basePath, onEvent, components: customComponents, imageAdapter, }: {
+    block: Block;
+    capabilities?: CapabilityProvider[];
+    theme?: 'light' | 'dark';
+    basePath?: string;
+    onEvent?: SurfaceRendererProps['onEvent'];
+    components?: Partial<BlockComponentRegistry>;
+    imageAdapter?: ImageAdapter;
+}): React.ReactElement;
+/**
+ * Get all block IDs from a surface
+ */
+export declare function getBlockIds(blocks: readonly Block[]): string[];
+/**
+ * Find a block by ID in a surface
+ */
+export declare function findBlockById(blocks: readonly Block[], id: string): Block | undefined;
+/**
+ * Update a block by ID in a surface
+ */
+export declare function updateBlockById(blocks: readonly Block[], id: string, updates: Partial<Block>): Block[];