@pushframe/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,458 @@
+import * as React from 'react';
+import React__default, { ReactNode, ReactElement } from 'react';
+import * as react_native from 'react-native';
+import { TextProps, ViewProps, ImageProps, PressableProps, TextInputProps, FlatListProps, ModalProps, ActivityIndicatorProps, SwitchProps, KeyboardAvoidingViewProps, StatusBarProps, ScrollViewProps, ScrollView as ScrollView$1 } from 'react-native';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+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__default.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;
+}
+/**
+ * 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.
+ */
+declare function PushFrameProvider({ apiKey, context, baseUrl, appVersion, components, loadingComponent, fallbackComponent, onAction, onError, children, }: PushFrameProviderProps): react_jsx_runtime.JSX.Element;
+
+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;
+}
+/**
+ * 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.
+ */
+declare function PushFrameComponent(props: PushFrameSlotProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * 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.
+ */
+declare function PushFrameScreen(props: PushFrameSlotProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * 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.
+ */
+declare class ComponentRegistry {
+    private readonly components;
+    constructor(developerComponents?: Record<string, React__default.ComponentType<unknown>>);
+    /**
+     * Resolve a type string to its React component.
+     * Returns null if no component is registered for the type.
+     */
+    resolve(type: string): React__default.ComponentType<Record<string, unknown>> | null;
+    /**
+     * Returns all registered type strings (useful for debugging).
+     */
+    types(): string[];
+}
+
+interface SchemaNode {
+    type: string;
+    props?: Record<string, unknown>;
+    children?: SchemaNode[];
+    actions?: Action[];
+    if?: string;
+}
+interface FlatListSchemaNode extends SchemaNode {
+    type: 'flatlist';
+    renderItem: SchemaNode;
+}
+interface Action {
+    trigger: string;
+    action: string;
+    payload?: Record<string, unknown>;
+}
+interface ToastPayload {
+    message: string;
+    duration?: number;
+    type?: 'success' | 'error' | 'info' | 'warning';
+}
+interface BottomSheetPayload {
+    schema: SchemaNode;
+    context?: Record<string, unknown>;
+}
+interface ScrollToPayload {
+    x?: number;
+    y?: number;
+    animated?: boolean;
+}
+interface PushFrameContextValue {
+    apiKey: string;
+    baseUrl: string;
+    appVersion?: string;
+    globalContext: Record<string, unknown>;
+    registry: ComponentRegistry;
+    loadingComponent?: React__default.ReactNode;
+    fallbackComponent?: React__default.ReactNode;
+    onAction?: (action: string, payload?: Record<string, unknown>) => void;
+    onError?: (error: Error) => void;
+    showToast: (payload: ToastPayload) => void;
+    showBottomSheet: (payload: BottomSheetPayload) => void;
+    dismissBottomSheet: () => void;
+}
+declare const PushFrameContext: React__default.Context<PushFrameContextValue | null>;
+declare function usePushFrameContext(): PushFrameContextValue;
+
+interface PushFrameTextProps extends TextProps {
+    /** Pushframe: hidden by RecursiveRenderer before component renders. */
+    if?: string;
+    /** Pushframe: converted to handlers by RecursiveRenderer before component renders. */
+    actions?: Action[];
+    /**
+     * Text content via binding. If provided, takes precedence over children.
+     * Pushframe-specific — resolved to a string by the time the component renders.
+     */
+    value?: string;
+}
+/**
+ * Thin wrapper over React Native Text.
+ * Strips `if`, `actions` before forwarding to RN.
+ * `value` takes precedence over `children` when both are present.
+ */
+declare function Text({ if: _if, actions: _actions, value, children, ...rest }: PushFrameTextProps): react_jsx_runtime.JSX.Element;
+
+interface PushFrameViewProps extends ViewProps {
+    if?: string;
+    actions?: Action[];
+}
+/**
+ * Thin wrapper over React Native View.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+declare function View({ if: _if, actions: _actions, ...rest }: PushFrameViewProps): react_jsx_runtime.JSX.Element;
+
+interface PushFrameImageProps extends Omit<ImageProps, '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?: ImageProps['source'];
+}
+/**
+ * Thin wrapper over React Native Image.
+ * `src` maps to `source={{ uri: src }}`.
+ * Strips `if`, `actions`, `src` before forwarding to RN.
+ */
+declare function Image({ if: _if, actions: _actions, src, source, ...rest }: PushFrameImageProps): react_jsx_runtime.JSX.Element;
+
+interface PushFramePressableProps extends PressableProps {
+    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.
+ */
+declare function Pressable({ if: _if, actions: _actions, ...rest }: PushFramePressableProps): react_jsx_runtime.JSX.Element;
+
+interface PushFrameTextInputProps extends Omit<TextInputProps, '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.
+ */
+declare function TextInput({ if: _if, actions: _actions, onChange, onSubmit, ...rest }: PushFrameTextInputProps): react_jsx_runtime.JSX.Element;
+
+interface PushFrameFlatListProps<T = unknown> extends Omit<FlatListProps<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.
+ */
+declare function FlatList<T = unknown>({ if: _if, actions: _actions, items, direction, numColumns, ...rest }: PushFrameFlatListProps<T>): react_jsx_runtime.JSX.Element;
+
+interface PushFrameModalProps extends ModalProps {
+    if?: string;
+    actions?: Action[];
+}
+/**
+ * Thin wrapper over React Native Modal.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+declare function Modal({ if: _if, actions: _actions, ...rest }: PushFrameModalProps): react_jsx_runtime.JSX.Element;
+
+interface PushFrameActivityIndicatorProps extends ActivityIndicatorProps {
+    if?: string;
+    actions?: Action[];
+}
+/**
+ * Thin wrapper over React Native ActivityIndicator.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+declare function ActivityIndicator({ if: _if, actions: _actions, ...rest }: PushFrameActivityIndicatorProps): react_jsx_runtime.JSX.Element;
+
+interface PushFrameSwitchProps extends Omit<SwitchProps, '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.
+ */
+declare function Switch({ if: _if, actions: _actions, onChange, ...rest }: PushFrameSwitchProps): react_jsx_runtime.JSX.Element;
+
+interface PushFrameKeyboardAvoidingViewProps extends KeyboardAvoidingViewProps {
+    if?: string;
+    actions?: Action[];
+}
+/**
+ * Thin wrapper over React Native KeyboardAvoidingView.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+declare function KeyboardAvoidingView({ if: _if, actions: _actions, ...rest }: PushFrameKeyboardAvoidingViewProps): react_jsx_runtime.JSX.Element;
+
+interface PushFrameSafeAreaViewProps extends ViewProps {
+    if?: string;
+    actions?: Action[];
+}
+/**
+ * Thin wrapper over SafeAreaView.
+ * Uses react-native-safe-area-context when available, RN core otherwise.
+ * Strips `if`, `actions` before forwarding to the underlying component.
+ */
+declare function SafeAreaView({ if: _if, actions: _actions, ...rest }: PushFrameSafeAreaViewProps): react_jsx_runtime.JSX.Element;
+
+interface PushFrameStatusBarProps extends StatusBarProps {
+    if?: string;
+    actions?: Action[];
+}
+/**
+ * Thin wrapper over React Native StatusBar.
+ * Strips `if`, `actions` before forwarding to RN.
+ */
+declare function StatusBar({ if: _if, actions: _actions, ...rest }: PushFrameStatusBarProps): react_jsx_runtime.JSX.Element;
+
+interface DispatchAction {
+    (actionName: string, payload?: Record<string, unknown>): void;
+}
+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__default.ReactNode;
+}
+/**
+ * Stateless recursive renderer. Evaluates schema nodes and produces React elements.
+ *
+ * - Evaluates `if` expression; returns null when falsy
+ * - Handles FlatList nodes with per-item context injection
+ * - Resolves all prop bindings against current context
+ * - Wires actions to component event handler props
+ * - Looks up component in registry; renders fallback or null when not found
+ * - Recurses into children
+ */
+declare function RecursiveRenderer({ node, context, registry, dispatchAction, fallbackComponent, }: RecursiveRendererProps): ReactElement | null;
+
+/**
+ * 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
+ */
+/**
+ * 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
+ */
+declare function resolveValue(value: unknown, context: Record<string, unknown>): unknown;
+/**
+ * Resolve all values in a props map against the context.
+ * Recursively resolves nested objects and arrays.
+ */
+declare function resolveProps(props: Record<string, unknown> | undefined, context: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Recursively resolve binding expressions in a value (including nested objects/arrays).
+ */
+declare function resolveDeep(value: unknown, context: Record<string, unknown>): unknown;
+
+/**
+ * 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 the node always renders.
+ */
+declare function evaluateIf(ifExpr: string | undefined, context: Record<string, unknown>): boolean;
+
+interface PushFrameScrollViewProps extends ScrollViewProps {
+    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.
+ */
+declare const ScrollView: React__default.ForwardRefExoticComponent<PushFrameScrollViewProps & React__default.RefAttributes<ScrollView$1>>;
+
+/**
+ * The PushFrame namespace. Import this as the single entry-point for the SDK.
+ *
+ * Slot components:
+ * - PushFrame.Provider  — wraps the app, initialises registry and context
+ * - PushFrame.Screen    — full-page slot (fetches /screens/:name, applies flex:1)
+ * - PushFrame.Component — inline slot (fetches /components/:name)
+ *
+ * Primitives (used internally by RecursiveRenderer, available for direct use):
+ * - PushFrame.Text, PushFrame.View, PushFrame.ScrollView, PushFrame.Image
+ * - PushFrame.Pressable, PushFrame.TextInput, PushFrame.FlatList
+ * - PushFrame.Modal, PushFrame.ActivityIndicator, PushFrame.Switch
+ * - PushFrame.KeyboardAvoidingView, PushFrame.SafeAreaView, PushFrame.StatusBar
+ */
+declare const PushFrame: {
+    readonly Provider: typeof PushFrameProvider;
+    readonly Screen: typeof PushFrameScreen;
+    readonly Component: typeof PushFrameComponent;
+    readonly Text: typeof Text;
+    readonly View: typeof View;
+    readonly ScrollView: React.ForwardRefExoticComponent<PushFrameScrollViewProps & React.RefAttributes<react_native.ScrollView>>;
+    readonly Image: typeof Image;
+    readonly Pressable: typeof Pressable;
+    readonly TextInput: typeof TextInput;
+    readonly FlatList: typeof FlatList;
+    readonly Modal: typeof Modal;
+    readonly ActivityIndicator: typeof ActivityIndicator;
+    readonly Switch: typeof Switch;
+    readonly KeyboardAvoidingView: typeof KeyboardAvoidingView;
+    readonly SafeAreaView: typeof SafeAreaView;
+    readonly StatusBar: typeof StatusBar;
+};
+
+export { type Action, ActivityIndicator, type BottomSheetPayload, ComponentRegistry, type DispatchAction, FlatList, type FlatListSchemaNode, Image, KeyboardAvoidingView, Modal, Pressable, PushFrame, type PushFrameActivityIndicatorProps, PushFrameComponent, PushFrameContext, type PushFrameContextValue, type PushFrameFlatListProps, type PushFrameImageProps, type PushFrameKeyboardAvoidingViewProps, type PushFrameModalProps, type PushFramePressableProps, PushFrameProvider, type PushFrameProviderProps, type PushFrameSafeAreaViewProps, PushFrameScreen, type PushFrameScrollViewProps, type PushFrameSlotProps, type PushFrameStatusBarProps, type PushFrameSwitchProps, type PushFrameTextInputProps, type PushFrameTextProps, type PushFrameViewProps, RecursiveRenderer, type RecursiveRendererProps, SafeAreaView, type SchemaNode, type ScrollToPayload, ScrollView, StatusBar, Switch, Text, TextInput, type ToastPayload, View, evaluateIf, resolveDeep, resolveProps, resolveValue, usePushFrameContext };