@pushframe/sdk 0.1.4 → 0.1.8

package/src/overlays/ToastHost.tsx

@@ -0,0 +1,147 @@
+import React, {
+  forwardRef,
+  useImperativeHandle,
+  useState,
+  useEffect,
+  useRef,
+  useCallback,
+} from 'react';
+import { View, Text, StyleSheet, Animated } from 'react-native';
+import type { ToastPayload } from '../context/PushFrameContext';
+
+// ---------------------------------------------------------------------------
+// Imperative handle
+// ---------------------------------------------------------------------------
+
+export interface ToastHostHandle {
+  show(payload: ToastPayload): void;
+}
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+interface ToastState {
+  id: number;
+  message: string;
+  duration: number;
+  type: ToastPayload['type'];
+}
+
+// ---------------------------------------------------------------------------
+// Style helpers
+// ---------------------------------------------------------------------------
+
+const TYPE_COLORS: Record<NonNullable<ToastPayload['type']>, string> = {
+  success: '#22c55e',
+  error: '#ef4444',
+  info: '#3b82f6',
+  warning: '#f59e0b',
+};
+
+// ---------------------------------------------------------------------------
+// ToastHost
+// ---------------------------------------------------------------------------
+
+/**
+ * Rendered by PushFrameProvider at the root level.
+ * Exposes an imperative `show()` handle for displaying toast messages.
+ * Zero third-party dependencies — built with Animated API.
+ */
+export const ToastHost = forwardRef<ToastHostHandle>(function ToastHost(_props, ref) {
+  const [toast, setToast] = useState<ToastState | null>(null);
+  const opacity = useRef(new Animated.Value(0)).current;
+  const idRef = useRef(0);
+
+  const hide = useCallback(() => {
+    Animated.timing(opacity, {
+      toValue: 0,
+      duration: 200,
+      useNativeDriver: true,
+    }).start(() => {
+      setToast(null);
+    });
+  }, [opacity]);
+
+  useEffect(() => {
+    if (!toast) return;
+
+    // Fade in
+    Animated.timing(opacity, {
+      toValue: 1,
+      duration: 200,
+      useNativeDriver: true,
+    }).start();
+
+    // Auto-dismiss after duration
+    const timer = setTimeout(() => {
+      hide();
+    }, toast.duration);
+
+    return () => {
+      clearTimeout(timer);
+    };
+  }, [toast, opacity, hide]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      show(payload: ToastPayload) {
+        idRef.current += 1;
+        setToast({
+          id: idRef.current,
+          message: payload.message,
+          duration: payload.duration ?? 3000,
+          type: payload.type ?? 'info',
+        });
+        // Reset opacity for new toast
+        opacity.setValue(0);
+      },
+    }),
+    [opacity],
+  );
+
+  if (!toast) return null;
+
+  const backgroundColor = TYPE_COLORS[toast.type ?? 'info'] ?? TYPE_COLORS.info;
+
+  return (
+    <View style={styles.container} pointerEvents="none">
+      <Animated.View style={[styles.toast, { backgroundColor, opacity }]}>
+        <Text style={styles.message}>{toast.message}</Text>
+      </Animated.View>
+    </View>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'absolute',
+    bottom: 60,
+    left: 16,
+    right: 16,
+    alignItems: 'center',
+    zIndex: 9999,
+  },
+  toast: {
+    paddingVertical: 12,
+    paddingHorizontal: 20,
+    borderRadius: 8,
+    maxWidth: 400,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.2,
+    shadowRadius: 4,
+    elevation: 6,
+  },
+  message: {
+    color: '#fff',
+    fontSize: 14,
+    fontWeight: '500',
+    textAlign: 'center',
+  },
+});

package/src/primitives/ActivityIndicator.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import { ActivityIndicator as RNActivityIndicator } from 'react-native';
+import type { ActivityIndicatorProps as RNActivityIndicatorProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameActivityIndicatorProps extends RNActivityIndicatorProps {
+  if?: string;
+  actions?: Action[];
+}
+
+/**
+ * Thin wrapper over React Native ActivityIndicator.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+export function ActivityIndicator({
+  if: _if,
+  actions: _actions,
+  ...rest
+}: PushFrameActivityIndicatorProps) {
+  return <RNActivityIndicator {...rest} />;
+}

package/src/primitives/FlatList.tsx

@@ -0,0 +1,49 @@
+import React from 'react';
+import { FlatList as RNFlatList } from 'react-native';
+import type { FlatListProps as RNFlatListProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameFlatListProps<T = unknown>
+  extends Omit<RNFlatListProps<T>, 'data' | 'horizontal'> {
+  if?: string;
+  actions?: Action[];
+  /**
+   * Resolved array of items. Populated by RecursiveRenderer from the
+   * `items` binding expression on the schema node.
+   */
+  items?: T[];
+  /**
+   * "vertical" (default) or "horizontal". Maps to RN `horizontal` boolean.
+   */
+  direction?: 'vertical' | 'horizontal';
+  /**
+   * Number of columns for grid layouts. Forwarded directly to RN FlatList.
+   */
+  numColumns?: number;
+}
+
+/**
+ * Thin wrapper over React Native FlatList.
+ * RecursiveRenderer handles this type specially — it resolves `items` from
+ * a binding expression and constructs the `renderItem` per-item context.
+ *
+ * This component maps Pushframe props to RN FlatList props and strips
+ * Pushframe-specific props before forwarding.
+ */
+export function FlatList<T = unknown>({
+  if: _if,
+  actions: _actions,
+  items,
+  direction,
+  numColumns,
+  ...rest
+}: PushFrameFlatListProps<T>) {
+  return (
+    <RNFlatList<T>
+      data={items}
+      horizontal={direction === 'horizontal'}
+      numColumns={numColumns}
+      {...rest}
+    />
+  );
+}

package/src/primitives/Image.tsx

@@ -0,0 +1,26 @@
+import React from 'react';
+import { Image as RNImage } from 'react-native';
+import type { ImageProps as RNImageProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameImageProps extends Omit<RNImageProps, 'source'> {
+  if?: string;
+  actions?: Action[];
+  /**
+   * URI string for the image source. Maps to RN `source={{ uri: src }}`.
+   * Takes precedence over the base `source` prop.
+   */
+  src?: string;
+  /** Pass-through for cases where a static require() source is needed. */
+  source?: RNImageProps['source'];
+}
+
+/**
+ * Thin wrapper over React Native Image.
+ * `src` maps to `source={{ uri: src }}`.
+ * Strips `if`, `actions`, `src` before forwarding to RN.
+ */
+export function Image({ if: _if, actions: _actions, src, source, ...rest }: PushFrameImageProps) {
+  const resolvedSource = src ? { uri: src } : source ?? { uri: '' };
+  return <RNImage source={resolvedSource} {...rest} />;
+}

package/src/primitives/KeyboardAvoidingView.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import { KeyboardAvoidingView as RNKeyboardAvoidingView } from 'react-native';
+import type { KeyboardAvoidingViewProps as RNKeyboardAvoidingViewProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameKeyboardAvoidingViewProps extends RNKeyboardAvoidingViewProps {
+  if?: string;
+  actions?: Action[];
+}
+
+/**
+ * Thin wrapper over React Native KeyboardAvoidingView.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+export function KeyboardAvoidingView({
+  if: _if,
+  actions: _actions,
+  ...rest
+}: PushFrameKeyboardAvoidingViewProps) {
+  return <RNKeyboardAvoidingView {...rest} />;
+}

package/src/primitives/Modal.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { Modal as RNModal } from 'react-native';
+import type { ModalProps as RNModalProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameModalProps extends RNModalProps {
+  if?: string;
+  actions?: Action[];
+}
+
+/**
+ * Thin wrapper over React Native Modal.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+export function Modal({ if: _if, actions: _actions, ...rest }: PushFrameModalProps) {
+  return <RNModal {...rest} />;
+}

package/src/primitives/Pressable.tsx

@@ -0,0 +1,19 @@
+import React from 'react';
+import { Pressable as RNPressable } from 'react-native';
+import type { PressableProps as RNPressableProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFramePressableProps extends RNPressableProps {
+  if?: string;
+  actions?: Action[];
+}
+
+/**
+ * Thin wrapper over React Native Pressable.
+ * Actions with trigger "onPress" and "onLongPress" are wired by RecursiveRenderer
+ * and forwarded through as standard RN props.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+export function Pressable({ if: _if, actions: _actions, ...rest }: PushFramePressableProps) {
+  return <RNPressable {...rest} />;
+}

package/src/primitives/SafeAreaView.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import type { ViewProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameSafeAreaViewProps extends ViewProps {
+  if?: string;
+  actions?: Action[];
+  /**
+   * Edges to apply safe-area insets on.
+   * Forwarded to react-native-safe-area-context's SafeAreaView when available.
+   * Example: ['top', 'bottom']
+   */
+  edges?: string[];
+}
+
+// Prefer react-native-safe-area-context (standard Expo dependency) when available;
+// fall back to RN core SafeAreaView otherwise.
+// Both are typed to accept `edges` so the prop flows through without stripping;
+// the RN core fallback will silently ignore the unknown prop at runtime.
+let NativeSafeAreaView: React.ComponentType<ViewProps & { edges?: string[] }>;
+
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  NativeSafeAreaView = (require('react-native-safe-area-context') as {
+    SafeAreaView: React.ComponentType<ViewProps & { edges?: string[] }>;
+  }).SafeAreaView;
+} catch {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  NativeSafeAreaView = (require('react-native') as {
+    SafeAreaView: React.ComponentType<ViewProps & { edges?: string[] }>;
+  }).SafeAreaView;
+}
+
+/**
+ * Thin wrapper over SafeAreaView.
+ * Uses react-native-safe-area-context when available, RN core otherwise.
+ * Strips `if`, `actions` before forwarding; passes `edges` through to
+ * react-native-safe-area-context (ignored gracefully in the RN core fallback).
+ */
+export function SafeAreaView({ if: _if, actions: _actions, ...rest }: PushFrameSafeAreaViewProps) {
+  return <NativeSafeAreaView {...rest} />;
+}

package/src/primitives/ScrollView.tsx

@@ -0,0 +1,21 @@
+import React, { forwardRef } from 'react';
+import { ScrollView as RNScrollView } from 'react-native';
+import type { ScrollViewProps as RNScrollViewProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameScrollViewProps extends RNScrollViewProps {
+  if?: string;
+  actions?: Action[];
+}
+
+/**
+ * Thin wrapper over React Native ScrollView.
+ * Forwards ref to support programmatic scrolling (e.g. scroll-to action).
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+export const ScrollView = forwardRef<RNScrollView, PushFrameScrollViewProps>(function ScrollView(
+  { if: _if, actions: _actions, ...rest },
+  ref,
+) {
+  return <RNScrollView ref={ref} {...rest} />;
+});

package/src/primitives/StatusBar.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { StatusBar as RNStatusBar } from 'react-native';
+import type { StatusBarProps as RNStatusBarProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameStatusBarProps extends RNStatusBarProps {
+  if?: string;
+  actions?: Action[];
+}
+
+/**
+ * Thin wrapper over React Native StatusBar.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+export function StatusBar({ if: _if, actions: _actions, ...rest }: PushFrameStatusBarProps) {
+  return <RNStatusBar {...rest} />;
+}

package/src/primitives/Switch.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { Switch as RNSwitch } from 'react-native';
+import type { SwitchProps as RNSwitchProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameSwitchProps extends Omit<RNSwitchProps, 'onValueChange' | 'onChange'> {
+  if?: string;
+  actions?: Action[];
+  /**
+   * Schema trigger "onChange" — wired by RecursiveRenderer.
+   * Mapped to RN `onValueChange` by this component.
+   */
+  onChange?: (value: boolean) => void;
+}
+
+/**
+ * Thin wrapper over React Native Switch.
+ * Maps Pushframe schema trigger to RN event prop:
+ *   onChange → onValueChange
+ * Strips `if`, `actions`, `onChange` before forwarding to RN.
+ */
+export function Switch({ if: _if, actions: _actions, onChange, ...rest }: PushFrameSwitchProps) {
+  return <RNSwitch onValueChange={onChange} {...rest} />;
+}

package/src/primitives/Text.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import { Text as RNText } from 'react-native';
+import type { TextProps as RNTextProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameTextProps extends RNTextProps {
+  /** Pushframe: hidden by RecursiveRenderer before component renders. */
+  if?: string;
+  /** Pushframe: converted to handlers by RecursiveRenderer before component renders. */
+  actions?: Action[];
+  /**
+   * Text content. Takes precedence over `children`.
+   * Pushframe schema convention: use `value`.
+   */
+  value?: string;
+  /**
+   * Alias for `value`. The transformer outputs the Craft editor's `content`
+   * field here. `value` takes precedence when both are present.
+   */
+  content?: string;
+}
+
+/**
+ * Thin wrapper over React Native Text.
+ * Strips `if`, `actions`, `content` before forwarding to RN.
+ * Display priority: value > content > children (children remain in rest).
+ */
+export function Text({
+  if: _if,
+  actions: _actions,
+  value,
+  content,
+  ...rest
+}: PushFrameTextProps) {
+  // When value or content is provided it takes precedence over JSX children
+  // (which are part of rest via RNTextProps inheritance).
+  const textContent = value !== undefined ? value : content;
+  if (textContent !== undefined) {
+    return <RNText {...rest}>{textContent}</RNText>;
+  }
+  // No explicit text content — forward rest as-is (includes any children prop)
+  return <RNText {...rest} />;
+}

package/src/primitives/TextInput.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { TextInput as RNTextInput } from 'react-native';
+import type { TextInputProps as RNTextInputProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameTextInputProps extends Omit<RNTextInputProps, 'onChange'> {
+  if?: string;
+  actions?: Action[];
+  /**
+   * Schema trigger "onChange" — wired by RecursiveRenderer.
+   * Mapped to RN `onChangeText` by this component.
+   */
+  onChange?: (text: string) => void;
+  /**
+   * Schema trigger "onSubmit" — wired by RecursiveRenderer.
+   * Mapped to RN `onSubmitEditing` by this component.
+   */
+  onSubmit?: () => void;
+}
+
+/**
+ * Thin wrapper over React Native TextInput.
+ * Maps Pushframe schema triggers to RN event props:
+ *   onChange → onChangeText
+ *   onSubmit → onSubmitEditing
+ * Strips `if`, `actions`, `onChange`, `onSubmit` before forwarding to RN.
+ */
+export function TextInput({
+  if: _if,
+  actions: _actions,
+  onChange,
+  onSubmit,
+  ...rest
+}: PushFrameTextInputProps) {
+  return (
+    <RNTextInput
+      onChangeText={onChange}
+      onSubmitEditing={onSubmit ? () => onSubmit() : undefined}
+      {...rest}
+    />
+  );
+}

package/src/primitives/View.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { View as RNView } from 'react-native';
+import type { ViewProps as RNViewProps } from 'react-native';
+import type { Action } from '../context/PushFrameContext';
+
+export interface PushFrameViewProps extends RNViewProps {
+  if?: string;
+  actions?: Action[];
+}
+
+/**
+ * Thin wrapper over React Native View.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+export function View({ if: _if, actions: _actions, ...rest }: PushFrameViewProps) {
+  return <RNView {...rest} />;
+}

package/src/primitives/index.ts

@@ -0,0 +1,38 @@
+export { Text } from './Text';
+export type { PushFrameTextProps } from './Text';
+
+export { View } from './View';
+export type { PushFrameViewProps } from './View';
+
+export { ScrollView } from './ScrollView';
+export type { PushFrameScrollViewProps } from './ScrollView';
+
+export { Image } from './Image';
+export type { PushFrameImageProps } from './Image';
+
+export { Pressable } from './Pressable';
+export type { PushFramePressableProps } from './Pressable';
+
+export { TextInput } from './TextInput';
+export type { PushFrameTextInputProps } from './TextInput';
+
+export { FlatList } from './FlatList';
+export type { PushFrameFlatListProps } from './FlatList';
+
+export { Modal } from './Modal';
+export type { PushFrameModalProps } from './Modal';
+
+export { ActivityIndicator } from './ActivityIndicator';
+export type { PushFrameActivityIndicatorProps } from './ActivityIndicator';
+
+export { Switch } from './Switch';
+export type { PushFrameSwitchProps } from './Switch';
+
+export { KeyboardAvoidingView } from './KeyboardAvoidingView';
+export type { PushFrameKeyboardAvoidingViewProps } from './KeyboardAvoidingView';
+
+export { SafeAreaView } from './SafeAreaView';
+export type { PushFrameSafeAreaViewProps } from './SafeAreaView';
+
+export { StatusBar } from './StatusBar';
+export type { PushFrameStatusBarProps } from './StatusBar';

package/src/registry/ComponentRegistry.ts

@@ -0,0 +1,99 @@
+import type React from 'react';
+import { Text } from '../primitives/Text';
+import { View } from '../primitives/View';
+import { ScrollView } from '../primitives/ScrollView';
+import { Image } from '../primitives/Image';
+import { Pressable } from '../primitives/Pressable';
+import { TextInput } from '../primitives/TextInput';
+import { FlatList } from '../primitives/FlatList';
+import { Modal } from '../primitives/Modal';
+import { ActivityIndicator } from '../primitives/ActivityIndicator';
+import { Switch } from '../primitives/Switch';
+import { KeyboardAvoidingView } from '../primitives/KeyboardAvoidingView';
+import { SafeAreaView } from '../primitives/SafeAreaView';
+import { StatusBar } from '../primitives/StatusBar';
+
+// ---------------------------------------------------------------------------
+// Built-in type → component mappings (cannot be overridden)
+// ---------------------------------------------------------------------------
+
+const BUILT_IN_TYPES: ReadonlySet<string> = new Set([
+  'text',
+  'view',
+  'scrollview',
+  'image',
+  'pressable',
+  'textinput',
+  'flatlist',
+  'modal',
+  'activityindicator',
+  'switch',
+  'keyboardavoidingview',
+  'safeareaview',
+  'statusbar',
+]);
+
+const BUILT_IN_COMPONENTS: ReadonlyMap<string, React.ComponentType<Record<string, unknown>>> =
+  new Map([
+    ['text', Text as React.ComponentType<Record<string, unknown>>],
+    ['view', View as React.ComponentType<Record<string, unknown>>],
+    ['scrollview', ScrollView as React.ComponentType<Record<string, unknown>>],
+    ['image', Image as React.ComponentType<Record<string, unknown>>],
+    ['pressable', Pressable as React.ComponentType<Record<string, unknown>>],
+    ['textinput', TextInput as React.ComponentType<Record<string, unknown>>],
+    ['flatlist', FlatList as unknown as React.ComponentType<Record<string, unknown>>],
+    ['modal', Modal as React.ComponentType<Record<string, unknown>>],
+    ['activityindicator', ActivityIndicator as React.ComponentType<Record<string, unknown>>],
+    ['switch', Switch as React.ComponentType<Record<string, unknown>>],
+    ['keyboardavoidingview', KeyboardAvoidingView as React.ComponentType<Record<string, unknown>>],
+    ['safeareaview', SafeAreaView as React.ComponentType<Record<string, unknown>>],
+    ['statusbar', StatusBar as React.ComponentType<Record<string, unknown>>],
+  ]);
+
+// ---------------------------------------------------------------------------
+// ComponentRegistry
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps component type strings to React components.
+ *
+ * Built-ins are always present and cannot be overridden.
+ * Developer-registered components are merged on top for non-conflicting types.
+ */
+export class ComponentRegistry {
+  private readonly components: Map<string, React.ComponentType<Record<string, unknown>>>;
+
+  constructor(developerComponents?: Record<string, React.ComponentType<unknown>>) {
+    // Start with built-ins
+    this.components = new Map(BUILT_IN_COMPONENTS);
+
+    // Merge developer components, skipping any that conflict with built-ins
+    if (developerComponents) {
+      for (const [type, component] of Object.entries(developerComponents)) {
+        if (BUILT_IN_TYPES.has(type)) {
+          console.warn(
+            `[PushFrame] ComponentRegistry: "${type}" is a built-in type and cannot be overridden. ` +
+              `Registration skipped.`,
+          );
+          continue;
+        }
+        this.components.set(type, component as React.ComponentType<Record<string, unknown>>);
+      }
+    }
+  }
+
+  /**
+   * Resolve a type string to its React component.
+   * Returns null if no component is registered for the type.
+   */
+  resolve(type: string): React.ComponentType<Record<string, unknown>> | null {
+    return this.components.get(type) ?? null;
+  }
+
+  /**
+   * Returns all registered type strings (useful for debugging).
+   */
+  types(): string[] {
+    return Array.from(this.components.keys());
+  }
+}