@pushframe/sdk 0.1.5 → 0.1.8

package/src/components/ButtonComponent.tsx

@@ -0,0 +1,87 @@
+import React from 'react';
+import { TouchableOpacity, Text, StyleSheet, ActivityIndicator } from 'react-native';
+import type { PushframeComponentProps } from '../registry';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+
+export interface ButtonProps {
+  label?: string;
+  variant?: ButtonVariant;
+  disabled?: boolean;
+  loading?: boolean;
+  onPress?: () => void;
+}
+
+export function ButtonComponent({ props }: PushframeComponentProps<ButtonProps>) {
+  const { label = 'Button', variant = 'primary', disabled = false, loading = false, onPress } = props;
+
+  return (
+    <TouchableOpacity
+      style={[
+        styles.base,
+        variant === 'secondary' && styles.secondary,
+        variant === 'ghost' && styles.ghost,
+        (disabled || loading) && styles.disabled,
+      ]}
+      onPress={onPress}
+      disabled={disabled || loading}
+      activeOpacity={0.8}
+    >
+      {loading ? (
+        <ActivityIndicator
+          size="small"
+          color={variant === 'primary' ? '#ffffff' : '#2563eb'}
+        />
+      ) : (
+        <Text
+          style={[
+            styles.label,
+            variant === 'secondary' && styles.labelSecondary,
+            variant === 'ghost' && styles.labelGhost,
+            (disabled || loading) && styles.labelDisabled,
+          ]}
+        >
+          {label}
+        </Text>
+      )}
+    </TouchableOpacity>
+  );
+}
+
+const styles = StyleSheet.create({
+  base: {
+    backgroundColor: '#2563eb',
+    paddingVertical: 12,
+    paddingHorizontal: 24,
+    borderRadius: 8,
+    alignItems: 'center',
+    justifyContent: 'center',
+    minHeight: 44,
+  },
+  secondary: {
+    backgroundColor: 'transparent',
+    borderWidth: 1.5,
+    borderColor: '#2563eb',
+  },
+  ghost: {
+    backgroundColor: 'transparent',
+    borderWidth: 0,
+  },
+  disabled: {
+    opacity: 0.4,
+  },
+  label: {
+    color: '#ffffff',
+    fontSize: 16,
+    fontWeight: '600',
+  },
+  labelSecondary: {
+    color: '#2563eb',
+  },
+  labelGhost: {
+    color: '#2563eb',
+  },
+  labelDisabled: {
+    opacity: 0.6,
+  },
+});

package/src/components/FlatListComponent.tsx

@@ -0,0 +1,86 @@
+import React from 'react';
+import { FlatList, View } from 'react-native';
+import type { ReactElement } from 'react';
+import type { PushframeComponentProps } from '../registry';
+
+export interface FlatListProps {
+  /**
+   * Array of data items to render. Typically bound from context via
+   * { "$bind": "path.to.array" }. Each item is available as `item` and
+   * the index as `index` inside the item template (first child node).
+   */
+  data?: Record<string, unknown>[];
+  /**
+   * Name of the field on each item to use as the React key.
+   * @default "id"
+   */
+  keyExtractor?: string;
+  horizontal?: boolean;
+  numColumns?: number;
+  padding?: number;
+  paddingTop?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  paddingRight?: number;
+  backgroundColor?: string;
+  flex?: number;
+  showsScrollIndicator?: boolean;
+  /** Height of the separator between items (vertical lists only). */
+  itemSeparatorHeight?: number;
+}
+
+export function FlatListComponent({
+  props,
+  rawChildren,
+  renderChild,
+}: PushframeComponentProps<FlatListProps>) {
+  const {
+    data = [],
+    keyExtractor = 'id',
+    horizontal = false,
+    numColumns = 1,
+    padding,
+    paddingTop,
+    paddingBottom,
+    paddingLeft,
+    paddingRight,
+    backgroundColor,
+    flex,
+    showsScrollIndicator = true,
+    itemSeparatorHeight = 0,
+  } = props;
+
+  // The first child node is used as the item template.
+  const itemTemplate = rawChildren?.[0];
+
+  return (
+    <FlatList
+      data={data}
+      horizontal={horizontal}
+      numColumns={horizontal ? 1 : numColumns}
+      showsHorizontalScrollIndicator={horizontal ? showsScrollIndicator : false}
+      showsVerticalScrollIndicator={!horizontal ? showsScrollIndicator : false}
+      keyExtractor={(item, index) =>
+        String((item as Record<string, unknown>)[keyExtractor] ?? index)
+      }
+      renderItem={({ item, index }) => {
+        if (!itemTemplate || !renderChild) return null;
+        return renderChild(itemTemplate, { item, index }) as ReactElement | null;
+      }}
+      ItemSeparatorComponent={
+        itemSeparatorHeight > 0
+          ? () => <View style={{ height: itemSeparatorHeight }} />
+          : undefined
+      }
+      style={[
+        padding !== undefined && { padding },
+        paddingTop !== undefined && { paddingTop },
+        paddingBottom !== undefined && { paddingBottom },
+        paddingLeft !== undefined && { paddingLeft },
+        paddingRight !== undefined && { paddingRight },
+        backgroundColor !== undefined && { backgroundColor },
+        flex !== undefined && { flex },
+      ]}
+    />
+  );
+}

package/src/components/ImageComponent.tsx

@@ -0,0 +1,70 @@
+import React from 'react';
+import { Image, StyleSheet, View, Text } from 'react-native';
+import type { PushframeComponentProps } from '../registry';
+
+export type ImageResizeMode = 'cover' | 'contain' | 'stretch' | 'center';
+
+export interface ImageProps {
+  src?: string;
+  alt?: string;
+  width?: number;
+  height?: number;
+  resizeMode?: ImageResizeMode;
+  borderRadius?: number;
+}
+
+export function ImageComponent({ props }: PushframeComponentProps<ImageProps>) {
+  const {
+    src,
+    alt = '',
+    width,
+    height = 200,
+    resizeMode = 'cover',
+    borderRadius,
+  } = props;
+
+  if (!src) {
+    return (
+      <View
+        style={[
+          styles.placeholder,
+          width !== undefined && { width },
+          { height },
+          borderRadius !== undefined && { borderRadius },
+        ]}
+      >
+        <Text style={styles.placeholderText}>{alt || 'No image'}</Text>
+      </View>
+    );
+  }
+
+  return (
+    <Image
+      source={{ uri: src }}
+      accessibilityLabel={alt}
+      resizeMode={resizeMode}
+      style={[
+        styles.image,
+        width !== undefined && { width },
+        { height },
+        borderRadius !== undefined && { borderRadius },
+      ]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  image: {
+    width: '100%',
+  },
+  placeholder: {
+    width: '100%',
+    backgroundColor: '#e5e7eb',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  placeholderText: {
+    color: '#9ca3af',
+    fontSize: 14,
+  },
+});

package/src/components/PushFrameComponent.tsx

@@ -0,0 +1,221 @@
+import React, { useCallback, useEffect, useState } from 'react';
+import type { ReactNode, ReactElement } from 'react';
+import { usePushFrameContext } from '../context/PushFrameContext';
+import type { SchemaNode, ToastPayload, BottomSheetPayload } from '../context/PushFrameContext';
+import { RecursiveRenderer } from '../renderer/RecursiveRenderer';
+
+// ---------------------------------------------------------------------------
+// Shared slot props (used by both Screen and Component)
+// ---------------------------------------------------------------------------
+
+export interface PushFrameSlotProps {
+  /** ID of the screen/component to fetch from the delivery service. */
+  id: string;
+  /**
+   * Data context local to this slot. Merged with the Provider context;
+   * local keys win on conflict.
+   */
+  context?: Record<string, unknown>;
+  /**
+   * External loading signal from the host app. When true, loading UI is shown
+   * even if the schema has already been fetched.
+   */
+  isLoading?: boolean;
+  /**
+   * Loading UI shown while isLoading=true OR schema is being fetched.
+   * Falls back to Provider-level loadingComponent.
+   */
+  loadingComponent?: ReactNode;
+  /**
+   * Fallback UI shown on fetch error or unresolvable component type.
+   * Falls back to Provider-level fallbackComponent.
+   */
+  fallbackComponent?: ReactNode;
+  /**
+   * Slot-level action handler. Return true to stop the action from bubbling
+   * to the Provider-level onAction.
+   */
+  onAction?: (action: string, payload?: Record<string, unknown>) => boolean | void;
+}
+
+// ---------------------------------------------------------------------------
+// Schema fetch
+// ---------------------------------------------------------------------------
+
+async function fetchSchema(
+  baseUrl: string,
+  apiKey: string,
+  path: string,
+): Promise<SchemaNode> {
+  const url = new URL(path, baseUrl + '/').toString();
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    Authorization: `Bearer ${apiKey}`,
+    'x-project-key': apiKey,
+  };
+
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    throw new Error(`[PushFrame] HTTP ${res.status} fetching "${path}"`);
+  }
+
+  const envelope = (await res.json()) as { schema?: SchemaNode } & SchemaNode;
+  return envelope.schema ?? envelope;
+}
+
+// ---------------------------------------------------------------------------
+// PushFrameComponent
+// ---------------------------------------------------------------------------
+
+interface PushFrameComponentInternalProps extends PushFrameSlotProps {
+  /** Resource type — determines which delivery endpoint to hit. */
+  resourceType: 'screens' | 'components';
+  /** When true, wraps the rendered output with flex:1 (used by Screen). */
+  fullscreen?: boolean;
+}
+
+function PushFrameComponentInternal({
+  id,
+  resourceType,
+  context: slotContext,
+  isLoading: externalLoading,
+  loadingComponent: slotLoading,
+  fallbackComponent: slotFallback,
+  onAction: slotOnAction,
+  fullscreen,
+}: PushFrameComponentInternalProps) {
+  const {
+    apiKey,
+    baseUrl,
+    appVersion,
+    globalContext,
+    registry,
+    loadingComponent: providerLoading,
+    fallbackComponent: providerFallback,
+    onAction: providerOnAction,
+    onError,
+    showToast,
+    showBottomSheet,
+    dismissBottomSheet,
+  } = usePushFrameContext();
+
+  const [schema, setSchema] = useState<SchemaNode | null>(null);
+  const [fetchError, setFetchError] = useState<Error | null>(null);
+  const [isFetching, setIsFetching] = useState(true);
+
+  // Build fetch path: {resourceType}/{id}/{appVersion} — "null" when not set
+  const fetchPath = `${resourceType}/${encodeURIComponent(id)}/${encodeURIComponent(appVersion ?? 'null')}`;
+
+  // Merged data context: provider → slot (local wins)
+  const mergedContext = slotContext ? { ...globalContext, ...slotContext } : globalContext;
+
+  // Resolved UI components with fallback precedence
+  const loadingUI = slotLoading !== undefined ? slotLoading : providerLoading;
+  const fallbackUI = slotFallback !== undefined ? slotFallback : providerFallback;
+
+  // Fetch schema
+  useEffect(() => {
+    let cancelled = false;
+    setSchema(null);
+    setFetchError(null);
+    setIsFetching(true);
+
+    fetchSchema(baseUrl, apiKey, fetchPath)
+      .then((s) => {
+        if (!cancelled) {
+          setSchema(s);
+          setIsFetching(false);
+        }
+      })
+      .catch((err: unknown) => {
+        if (!cancelled) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setFetchError(error);
+          setIsFetching(false);
+          onError?.(error);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [fetchPath, baseUrl, apiKey, onError]);
+
+  // Dispatch action — handles built-ins, then bubbles via slot → provider
+  const dispatchAction = useCallback(
+    (action: string, payload?: Record<string, unknown>) => {
+      // Built-in actions — never bubble to host app
+      if (action === 'show-toast') {
+        showToast(payload as unknown as ToastPayload);
+        return;
+      }
+      if (action === 'show-bottom-sheet') {
+        showBottomSheet(payload as unknown as BottomSheetPayload);
+        return;
+      }
+      if (action === 'dismiss-bottom-sheet') {
+        dismissBottomSheet();
+        return;
+      }
+      if (action === 'scroll-to') {
+        // scroll-to is handled by the ScrollView primitive via ref; no bubbling needed
+        return;
+      }
+
+      // Bubble: slot onAction first; if it returns true, stop
+      const stopped = slotOnAction?.(action, payload);
+      if (stopped) return;
+
+      // Provider onAction
+      providerOnAction?.(action, payload);
+    },
+    [showToast, showBottomSheet, dismissBottomSheet, slotOnAction, providerOnAction],
+  );
+
+  // Loading state: external flag OR schema not yet fetched
+  const isShowingLoader = externalLoading || isFetching;
+
+  if (isShowingLoader) {
+    return (loadingUI as ReactElement | null) ?? null;
+  }
+
+  if (fetchError || !schema) {
+    return (fallbackUI as ReactElement | null) ?? null;
+  }
+
+  const rendered = (
+    <RecursiveRenderer
+      node={schema}
+      context={mergedContext}
+      registry={registry}
+      dispatchAction={dispatchAction}
+      fallbackComponent={fallbackUI}
+    />
+  );
+
+  if (fullscreen) {
+    // PushFrame.Screen wraps with flex:1
+    return <>{rendered}</>;
+  }
+
+  return rendered;
+}
+
+// ---------------------------------------------------------------------------
+// Public PushFrameComponent
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetches a component schema from GET /components/:id[/:appVersion] on the
+ * delivery service and renders it inline using RecursiveRenderer.
+ *
+ * Context is merged: Provider context → slot context (local wins).
+ * Actions bubble: slot onAction → Provider onAction.
+ * Built-in actions (show-toast, show-bottom-sheet, etc.) are handled internally.
+ */
+export function PushFrameComponent(props: PushFrameSlotProps) {
+  return <PushFrameComponentInternal {...props} resourceType="components" />;
+}
+
+// Re-export internal for Screen to use
+export { PushFrameComponentInternal };

package/src/components/PushFrameProvider.tsx

@@ -0,0 +1,177 @@
+import React, { useCallback, useMemo, useRef } from 'react';
+import type { ReactNode } from 'react';
+import { PushFrameContext } from '../context/PushFrameContext';
+import type {
+  PushFrameContextValue,
+  ToastPayload,
+  BottomSheetPayload,
+  SchemaNode,
+} from '../context/PushFrameContext';
+import { ComponentRegistry } from '../registry/ComponentRegistry';
+import { ToastHost } from '../overlays/ToastHost';
+import type { ToastHostHandle } from '../overlays/ToastHost';
+import { BottomSheetHost } from '../overlays/BottomSheetHost';
+import type { BottomSheetHostHandle } from '../overlays/BottomSheetHost';
+import { RecursiveRenderer } from '../renderer/RecursiveRenderer';
+
+const DEFAULT_BASE_URL = 'https://api.pushframe.io';
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+export interface PushFrameProviderProps {
+  /** Pushframe API key — sent as Authorization header on all fetches. */
+  apiKey: string;
+  /**
+   * Runtime data context. Screens/Components bind to this via {{expressions}}.
+   * Merged at the Provider level; slot-level context wins on conflict.
+   */
+  context?: Record<string, unknown>;
+  /**
+   * Base URL of the Pushframe delivery service.
+   * Defaults to the production endpoint: https://api.pushframe.io
+   */
+  baseUrl?: string;
+  /**
+   * Semver string appended to fetch paths for schema version targeting.
+   * e.g. "1.2.3" → GET /screens/home/1.2.3
+   * When not provided, "null" is sent as the appVersion in the URL.
+   */
+  appVersion?: string;
+  /**
+   * Developer-registered native components merged into the ComponentRegistry.
+   * Built-in types cannot be overridden — conflicting keys are warned and skipped.
+   */
+  components?: Record<string, React.ComponentType<unknown>>;
+  /** Default loading UI shown while schema is fetching or isLoading=true. */
+  loadingComponent?: ReactNode;
+  /** Default fallback UI shown on fetch error or unknown component type. */
+  fallbackComponent?: ReactNode;
+  /**
+   * Global action handler. Receives actions that are not handled as built-ins
+   * and were not stopped by a slot-level onAction.
+   */
+  onAction?: (action: string, payload?: Record<string, unknown>) => void;
+  /** Called whenever a fetch or render error occurs. */
+  onError?: (error: Error) => void;
+  children: ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// PushFrameProvider
+// ---------------------------------------------------------------------------
+
+/**
+ * Root provider for the PushFrame SDK.
+ *
+ * Wrap your app (or a subtree) in this provider. All PushFrame.Screen and
+ * PushFrame.Component slots inside will fetch their schemas from the delivery
+ * service and render them using the shared ComponentRegistry and context.
+ *
+ * Also renders the ToastHost and BottomSheetHost overlay hosts at root level
+ * so any component in the tree can trigger them via built-in actions.
+ */
+export function PushFrameProvider({
+  apiKey,
+  context = {},
+  baseUrl = DEFAULT_BASE_URL,
+  appVersion,
+  components,
+  loadingComponent,
+  fallbackComponent,
+  onAction,
+  onError,
+  children,
+}: PushFrameProviderProps) {
+  // Registry — created once (components prop should be stable)
+  const registry = useMemo(
+    () => new ComponentRegistry(components),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  // Overlay refs
+  const toastRef = useRef<ToastHostHandle>(null);
+  const bottomSheetRef = useRef<BottomSheetHostHandle>(null);
+
+  const showToast = useCallback((payload: ToastPayload) => {
+    toastRef.current?.show(payload);
+  }, []);
+
+  const showBottomSheet = useCallback((payload: BottomSheetPayload) => {
+    bottomSheetRef.current?.show(payload);
+  }, []);
+
+  const dismissBottomSheet = useCallback(() => {
+    bottomSheetRef.current?.dismiss();
+  }, []);
+
+  // renderContent for BottomSheetHost — renders a schema node with the Provider's registry
+  const renderBottomSheetContent = useCallback(
+    (schema: SchemaNode, sheetContext?: Record<string, unknown>) => {
+      const mergedContext = sheetContext ? { ...context, ...sheetContext } : context;
+      // No-op dispatchAction for bottom sheet content (actions bubble via onAction)
+      const dispatchAction = (action: string, payload?: Record<string, unknown>) => {
+        if (action === 'dismiss-bottom-sheet') {
+          dismissBottomSheet();
+          return;
+        }
+        if (action === 'show-toast') {
+          showToast(payload as unknown as ToastPayload);
+          return;
+        }
+        onAction?.(action, payload);
+      };
+      return (
+        <RecursiveRenderer
+          node={schema}
+          context={mergedContext}
+          registry={registry}
+          dispatchAction={dispatchAction}
+          fallbackComponent={fallbackComponent}
+        />
+      );
+    },
+    [context, registry, fallbackComponent, onAction, dismissBottomSheet, showToast],
+  );
+
+  const contextValue = useMemo<PushFrameContextValue>(
+    () => ({
+      apiKey,
+      baseUrl,
+      appVersion,
+      globalContext: context,
+      registry,
+      loadingComponent,
+      fallbackComponent,
+      onAction,
+      onError,
+      showToast,
+      showBottomSheet,
+      dismissBottomSheet,
+    }),
+    [
+      apiKey,
+      baseUrl,
+      appVersion,
+      context,
+      registry,
+      loadingComponent,
+      fallbackComponent,
+      onAction,
+      onError,
+      showToast,
+      showBottomSheet,
+      dismissBottomSheet,
+    ],
+  );
+
+  return (
+    <PushFrameContext.Provider value={contextValue}>
+      {children}
+      <ToastHost ref={toastRef} />
+      <BottomSheetHost ref={bottomSheetRef} renderContent={renderBottomSheetContent} />
+    </PushFrameContext.Provider>
+  );
+}

package/src/components/PushFrameScreen.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import { PushFrameComponentInternal } from './PushFrameComponent';
+import type { PushFrameSlotProps } from './PushFrameComponent';
+
+/**
+ * Fetches a screen schema from GET /screens/:id[/:appVersion] on the delivery
+ * service and renders it with flex:1 sizing (full-page layout).
+ *
+ * Identical to PushFrame.Component in behaviour, but:
+ * - Fetches from /screens/:id instead of /components/:id
+ * - Applies flex:1 to its container so it fills the available space
+ *
+ * Context is merged: Provider context → slot context (local wins).
+ * Actions bubble: slot onAction → Provider onAction.
+ * Built-in actions (show-toast, show-bottom-sheet, etc.) are handled internally.
+ */
+export function PushFrameScreen(props: PushFrameSlotProps) {
+  return (
+    <View style={styles.container}>
+      <PushFrameComponentInternal {...props} resourceType="screens" fullscreen />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});