@pushframe/sdk 0.1.4 → 0.1.8

package/src/registry.ts

@@ -0,0 +1,99 @@
+import type { ComponentType, ReactElement, ReactNode } from 'react';
+import type { PushframeNode } from './schema';
+
+/**
+ * Props passed to every Pushframe component.
+ *
+ * `props`        — fully-resolved (all $bind references substituted) props map.
+ * `children`     — pre-rendered child nodes (if any).
+ * `onAction`     — callback for emitting an action event back to the host app.
+ * `rawChildren`  — raw schema child nodes, available for data-driven components
+ *                  (e.g. FlatList) that need to render the same template
+ *                  multiple times with different context.
+ * `renderChild`  — render a schema node with an optional context override that
+ *                  gets merged into the parent context. Use this together with
+ *                  `rawChildren` to implement per-item rendering.
+ */
+export interface PushframeComponentProps<TProps = Record<string, unknown>> {
+  props: TProps;
+  children?: ReactNode;
+  onAction?: (eventName: string, payload: unknown) => void;
+  rawChildren?: readonly PushframeNode[];
+  renderChild?: (
+    node: PushframeNode,
+    contextOverride?: Record<string, unknown>,
+  ) => ReactElement | null;
+}
+
+export type PushframeComponent<TProps = Record<string, unknown>> =
+  ComponentType<PushframeComponentProps<TProps>>;
+
+/**
+ * ComponentRegistry maps a component type string (e.g. "stack") to its
+ * React component implementation.
+ *
+ * Use `createRegistry()` to construct one, then call `register()` to add
+ * custom components on top.
+ */
+export class ComponentRegistry {
+  private readonly components = new Map<string, PushframeComponent>();
+
+  /**
+   * Register a component under the given type string.
+   * Calling register() with an existing type overwrites the previous entry,
+   * allowing host apps to override built-ins.
+   */
+  register<TProps>(
+    type: string,
+    component: PushframeComponent<TProps>,
+  ): this {
+    this.components.set(type, component as PushframeComponent);
+    return this;
+  }
+
+  /**
+   * Look up a component by type string.
+   * Returns undefined if no component is registered for that type.
+   */
+  get(type: string): PushframeComponent | undefined {
+    return this.components.get(type);
+  }
+
+  /**
+   * Returns true if the registry contains an entry for the given type.
+   */
+  has(type: string): boolean {
+    return this.components.has(type);
+  }
+
+  /**
+   * Returns all registered type strings (useful for debugging).
+   */
+  types(): string[] {
+    return Array.from(this.components.keys());
+  }
+}
+
+/**
+ * Build the default registry pre-loaded with all built-in components.
+ */
+export function createDefaultRegistry(): ComponentRegistry {
+  // Lazy-import to keep tree-shaking effective when consumers only need
+  // a subset of built-ins.
+  const { StackComponent } = require('./components/StackComponent');
+  const { TextComponent } = require('./components/TextComponent');
+  const { ButtonComponent } = require('./components/ButtonComponent');
+  const { ImageComponent } = require('./components/ImageComponent');
+  const { ScrollViewComponent } = require('./components/ScrollViewComponent');
+  const { FlatListComponent } = require('./components/FlatListComponent');
+
+  return new ComponentRegistry()
+    .register('stack', StackComponent)
+    // 'screen' is a common server-side root container alias for stack
+    .register('screen', StackComponent)
+    .register('text', TextComponent)
+    .register('button', ButtonComponent)
+    .register('image', ImageComponent)
+    .register('scrollview', ScrollViewComponent)
+    .register('flatlist', FlatListComponent);
+}

package/src/renderer/RecursiveRenderer.tsx

@@ -0,0 +1,242 @@
+import React from 'react';
+import type { ReactElement } from 'react';
+import type { SchemaNode, FlatListSchemaNode, Action } from '../context/PushFrameContext';
+import type { ComponentRegistry } from '../registry/ComponentRegistry';
+import { resolveProps, resolveDeep, resolveValue } from './bindingResolver';
+import { evaluateIf } from './conditionalEvaluator';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DispatchAction {
+  (actionName: string, payload?: Record<string, unknown>): void;
+}
+
+export interface RecursiveRendererProps {
+  node: SchemaNode;
+  /** Current merged data context for binding resolution. */
+  context: Record<string, unknown>;
+  registry: ComponentRegistry;
+  /** Handles all actions — built-ins and host-app bubbling. Provided by the slot component. */
+  dispatchAction: DispatchAction;
+  /** Shown when a component type is not found in the registry. */
+  fallbackComponent?: React.ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// Action wiring helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Group an actions array by trigger name and produce a prop map where each
+ * trigger key maps to a callback that fires all actions for that trigger.
+ */
+function buildActionProps(
+  actions: Action[],
+  context: Record<string, unknown>,
+  dispatchAction: DispatchAction,
+): Record<string, (...args: unknown[]) => void> {
+  // Group by trigger
+  const grouped = new Map<string, Action[]>();
+  for (const action of actions) {
+    const existing = grouped.get(action.trigger);
+    if (existing) {
+      existing.push(action);
+    } else {
+      grouped.set(action.trigger, [action]);
+    }
+  }
+
+  const result: Record<string, (...args: unknown[]) => void> = {};
+  for (const [trigger, triggerActions] of grouped) {
+    result[trigger] = (..._args: unknown[]) => {
+      for (const action of triggerActions) {
+        const resolvedPayload =
+          action.payload !== undefined
+            ? (resolveDeep(action.payload, context) as Record<string, unknown>)
+            : undefined;
+        dispatchAction(action.action, resolvedPayload);
+      }
+    };
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// FlatList special handling
+// ---------------------------------------------------------------------------
+
+function renderFlatListNode(
+  node: FlatListSchemaNode,
+  context: Record<string, unknown>,
+  registry: ComponentRegistry,
+  dispatchAction: DispatchAction,
+  fallbackComponent: React.ReactNode,
+): ReactElement | null {
+  // Resolve all props including the data/items binding
+  const resolvedProps = resolveProps(node.props, context);
+
+  // Build action props for the FlatList container itself
+  const actionProps = node.actions ? buildActionProps(node.actions, context, dispatchAction) : {};
+
+  // Support both `data` (transformer output) and `items` (legacy) for the array source.
+  // Extract and resolve; the primitive receives it as `items`.
+  const {
+    data: resolvedData,
+    items: resolvedItems,
+    keyExtractor: keyExtractorExpr,
+    direction,
+    numColumns,
+    visible: _visible,
+    _propValues: _pv,
+    ...restProps
+  } = resolvedProps;
+
+  const items = Array.isArray(resolvedData)
+    ? (resolvedData as unknown[])
+    : Array.isArray(resolvedItems)
+      ? (resolvedItems as unknown[])
+      : [];
+
+  // Build a keyExtractor function if specified in schema
+  let keyExtractorFn: ((item: unknown, index: number) => string) | undefined;
+  if (typeof keyExtractorExpr === 'string') {
+    const extractorExpr = keyExtractorExpr;
+    keyExtractorFn = (item: unknown, index: number) => {
+      const itemContext = { ...context, item, index };
+      const resolved = resolveValue(extractorExpr, itemContext);
+      return resolved !== undefined && resolved !== null ? String(resolved) : String(index);
+    };
+  }
+
+  // itemTemplate: per-item context merges { item, index } into current context
+  const renderItemFn = ({ item, index }: { item: unknown; index: number }): ReactElement | null => {
+    const itemContext = { ...context, item, index };
+    return (
+      <RecursiveRenderer
+        node={node.itemTemplate}
+        context={itemContext}
+        registry={registry}
+        dispatchAction={dispatchAction}
+        fallbackComponent={fallbackComponent}
+        key={keyExtractorFn ? keyExtractorFn(item, index) : index}
+      />
+    );
+  };
+
+  const FlatListComponent = registry.resolve('flatlist');
+  if (!FlatListComponent) {
+    console.warn('[PushFrame] RecursiveRenderer: "flatlist" not found in registry.');
+    return fallbackComponent ? (fallbackComponent as ReactElement) : null;
+  }
+
+  return React.createElement(FlatListComponent, {
+    ...restProps,
+    ...actionProps,
+    items,
+    direction,
+    numColumns,
+    keyExtractor: keyExtractorFn,
+    renderItem: renderItemFn,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// RecursiveRenderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Stateless recursive renderer. Evaluates schema nodes and produces React elements.
+ *
+ * - Evaluates `if` expression (string or non-string); returns null when falsy
+ * - Handles `visible` prop: returns null when visible resolves to false
+ * - Handles FlatList nodes with per-item context injection via `itemTemplate`
+ * - Supports `data` (transformer) and `items` (legacy) as FlatList data source
+ * - Resolves all prop bindings against current context
+ * - Merges `_propValues` into child context (custom component prop injection)
+ * - Wires actions to component event handler props
+ * - Looks up component in registry; renders fallback or null when not found
+ * - Recurses into children
+ */
+export function RecursiveRenderer({
+  node,
+  context,
+  registry,
+  dispatchAction,
+  fallbackComponent,
+}: RecursiveRendererProps): ReactElement | null {
+  // 1. Evaluate conditional — skip entire subtree if falsy
+  if (!evaluateIf(node.if, context)) {
+    return null;
+  }
+
+  // 2. FlatList special case
+  if (node.type === 'flatlist') {
+    return renderFlatListNode(
+      node as FlatListSchemaNode,
+      context,
+      registry,
+      dispatchAction,
+      fallbackComponent,
+    );
+  }
+
+  // 3. Resolve props
+  const resolvedProps = resolveProps(node.props, context);
+
+  // 4. Handle `visible` prop — transformer sets visible:false when a node is hidden.
+  //    A missing or true value means visible; anything falsy hides the node.
+  if (resolvedProps.visible !== undefined && !resolvedProps.visible) {
+    return null;
+  }
+
+  // 5. Extract SDK-internal props that must not be forwarded to RN components.
+  //    `_propValues` carries custom-component instance overrides → merge into
+  //    child context so nested bindings resolve against them.
+  const {
+    visible: _visible,
+    _propValues: propValuesRaw,
+    ...propsToForward
+  } = resolvedProps;
+
+  const propValues = propValuesRaw as Record<string, unknown> | undefined;
+  const childContext =
+    propValues && Object.keys(propValues).length > 0
+      ? { ...context, ...propValues }
+      : context;
+
+  // 6. Wire actions → inject as trigger-named props
+  const actionProps = node.actions ? buildActionProps(node.actions, context, dispatchAction) : {};
+
+  // 7. Resolve component from registry
+  const Component = registry.resolve(node.type);
+  if (!Component) {
+    console.warn(
+      `[PushFrame] RecursiveRenderer: Unknown component type "${node.type}". ` +
+        `Registered types: ${registry.types().join(', ')}`,
+    );
+    return fallbackComponent ? (fallbackComponent as ReactElement) : null;
+  }
+
+  // 8. Render children recursively (using childContext for _propValues injection)
+  const children =
+    node.children && node.children.length > 0
+      ? node.children.map((child, index) => (
+          <RecursiveRenderer
+            key={`${child.type}-${index}`}
+            node={child}
+            context={childContext}
+            registry={registry}
+            dispatchAction={dispatchAction}
+            fallbackComponent={fallbackComponent}
+          />
+        ))
+      : undefined;
+
+  return React.createElement(Component, {
+    ...propsToForward,
+    ...actionProps,
+    children,
+  });
+}

package/src/renderer/bindingResolver.ts

@@ -0,0 +1,94 @@
+/**
+ * Binding resolver for PushFrame {{expression}} syntax.
+ *
+ * Rules:
+ * - A value that is entirely "{{expr}}" resolves to the bound value (any type)
+ * - A value with inline bindings "Hello {{user.name}}" resolves to a string
+ * - Unresolved paths return undefined — never throws
+ * - Non-string values are returned as-is
+ */
+
+const FULL_BINDING_RE = /^\{\{(.+)\}\}$/;
+const INLINE_BINDING_RE = /\{\{([^}]+)\}\}/g;
+
+/**
+ * Evaluate a binding expression string against the provided context.
+ * Uses Function constructor for safe, sandboxed expression evaluation.
+ * Returns undefined on any error.
+ */
+function evaluateExpression(expr: string, context: Record<string, unknown>): unknown {
+  try {
+    const keys = Object.keys(context);
+    const values = keys.map((k) => context[k]);
+    // eslint-disable-next-line no-new-func
+    const fn = new Function(...keys, `"use strict"; try { return (${expr}); } catch(e) { return undefined; }`) as (
+      ...args: unknown[]
+    ) => unknown;
+    return fn(...values);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve a single prop value against context.
+ *
+ * - String values: check for full binding "{{expr}}" or inline bindings "Hello {{name}}"
+ * - Non-string values: returned as-is
+ */
+export function resolveValue(value: unknown, context: Record<string, unknown>): unknown {
+  if (typeof value !== 'string') {
+    return value;
+  }
+
+  // Full binding: entire string is "{{expr}}" — return the actual resolved value
+  const fullMatch = FULL_BINDING_RE.exec(value);
+  if (fullMatch?.[1] !== undefined) {
+    return evaluateExpression(fullMatch[1].trim(), context);
+  }
+
+  // Inline binding: replace each "{{expr}}" occurrence within the string
+  if (INLINE_BINDING_RE.test(value)) {
+    INLINE_BINDING_RE.lastIndex = 0;
+    return value.replace(INLINE_BINDING_RE, (_, expr: string) => {
+      const resolved = evaluateExpression(expr.trim(), context);
+      return resolved !== undefined && resolved !== null ? String(resolved) : '';
+    });
+  }
+
+  // No bindings — return as-is
+  return value;
+}
+
+/**
+ * Resolve all values in a props map against the context.
+ * Recursively resolves nested objects and arrays.
+ */
+export function resolveProps(
+  props: Record<string, unknown> | undefined,
+  context: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!props) return {};
+  const resolved: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(props)) {
+    resolved[key] = resolveDeep(value, context);
+  }
+  return resolved;
+}
+
+/**
+ * Recursively resolve binding expressions in a value (including nested objects/arrays).
+ */
+export function resolveDeep(value: unknown, context: Record<string, unknown>): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveDeep(item, context));
+  }
+  if (typeof value === 'object' && value !== null) {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      result[k] = resolveDeep(v, context);
+    }
+    return result;
+  }
+  return resolveValue(value, context);
+}

package/src/renderer/conditionalEvaluator.ts

@@ -0,0 +1,29 @@
+import { resolveValue } from './bindingResolver';
+
+/**
+ * Evaluate the `if` expression of a SchemaNode against the current context.
+ *
+ * Returns true  → node should render
+ * Returns false → node (and its entire subtree) should be skipped
+ *
+ * Falsy values: false, null, undefined, 0, "" all hide the node.
+ * When `ifExpr` is undefined/null the node always renders.
+ *
+ * Accepts `unknown` to match the transformer's `if?: unknown` output:
+ *   - String values are resolved as {{}} binding expressions
+ *   - Non-string values (boolean, number, null) are coerced directly
+ */
+export function evaluateIf(
+  ifExpr: unknown,
+  context: Record<string, unknown>,
+): boolean {
+  if (ifExpr === undefined || ifExpr === null) return true;
+
+  // Non-string: treat the value itself as the condition (e.g. `if: false`)
+  if (typeof ifExpr !== 'string') return Boolean(ifExpr);
+
+  const resolved = resolveValue(ifExpr, context);
+
+  // Standard falsy check — any falsy value hides the node
+  return Boolean(resolved);
+}

package/src/renderer.tsx

@@ -0,0 +1,124 @@
+import React from 'react';
+import type { ReactElement } from 'react';
+import type { PushframeNode, ActionsMap } from './schema';
+import type { ComponentRegistry } from './registry';
+import type { PushframeContext } from './bindings';
+import { resolveProps } from './bindings';
+import { evaluateCondition } from './conditions';
+import type { PushframeAction } from './schema';
+
+/**
+ * Called by the host app whenever an action is triggered.
+ * `eventName` is the prop key (e.g. "onPress").
+ * `action` is the resolved action descriptor from the schema.
+ */
+export type ActionHandler = (eventName: string, action: PushframeAction) => void;
+
+interface RenderNodeOptions {
+  node: PushframeNode;
+  context: PushframeContext;
+  registry: ComponentRegistry;
+  onAction?: ActionHandler;
+  /** Key to help React reconcile siblings. */
+  key?: string;
+}
+
+/**
+ * Recursively render a single PushframeNode.
+ *
+ * Returns null when:
+ *  - The node's condition evaluates to false
+ *  - The node's type is not found in the registry
+ */
+export function renderNode({
+  node,
+  context,
+  registry,
+  onAction,
+  key,
+}: RenderNodeOptions): ReactElement | null {
+  // 1. Evaluate conditions — skip if false.
+  if (!evaluateCondition(node.conditions, context)) {
+    return null;
+  }
+
+  // 2. Look up the component.
+  const Component = registry.get(node.type);
+  if (!Component) {
+    console.warn(
+      `[Pushframe] No component registered for type "${node.type}". ` +
+        `Registered types: ${registry.types().join(', ')}`,
+    );
+    return null;
+  }
+
+  // 3. Resolve props.
+  const resolvedProps = resolveProps(node.props, context);
+
+  // 4. Build action callbacks and merge into props.
+  if (node.actions) {
+    mergeActionCallbacks(resolvedProps, node.actions, onAction);
+  }
+
+  // 5. Render children recursively.
+  const childOptions = onAction
+    ? { context, registry, onAction }
+    : { context, registry };
+
+  const children =
+    node.children && node.children.length > 0
+      ? node.children.map((child, index) =>
+          renderNode({
+            node: child,
+            key: `${child.type}-${index}`,
+            ...childOptions,
+          }),
+        )
+      : undefined;
+
+  // Helper for data-driven components (e.g. FlatList) to render a template
+  // node multiple times with different context (e.g. one render per list item).
+  const renderChild = (
+    childNode: PushframeNode,
+    contextOverride?: Record<string, unknown>,
+  ) =>
+    renderNode({
+      node: childNode,
+      context: contextOverride ? { ...context, ...contextOverride } : context,
+      registry,
+      onAction,
+    });
+
+  // 6. Build component props — only include onAction when defined
+  //    (required by exactOptionalPropertyTypes).
+  const componentProps = {
+    props: resolvedProps as Record<string, unknown>,
+    children,
+    rawChildren: node.children,
+    renderChild,
+  };
+
+  return React.createElement(Component, { key, ...componentProps });
+}
+
+/**
+ * For each entry in the actions map, inject a callback function into resolvedProps
+ * so the component can call e.g. `props.onPress()` without coupling to the schema.
+ */
+function mergeActionCallbacks(
+  resolvedProps: Record<string, unknown>,
+  actions: ActionsMap,
+  onAction?: ActionHandler,
+): void {
+  for (const [eventName, action] of Object.entries(actions)) {
+    resolvedProps[eventName] = () => {
+      if (onAction) {
+        onAction(eventName, action);
+      } else {
+        console.warn(
+          `[Pushframe] Action "${eventName}" fired but no onAction handler was provided.`,
+        );
+      }
+    };
+  }
+}