@pushframe/sdk 0.1.5 → 0.1.9

package/src/schema.ts

@@ -0,0 +1,132 @@
+/**
+ * Pushframe Schema — typed definitions for screen definitions.
+ *
+ * A screen is described as a tree of PushframeNode objects.
+ * Props can be static values OR data-bindings via { "$bind": "path.to.value" }.
+ * Conditions gate whether a node renders at all.
+ * Actions declare event handlers; the host app is responsible for handling them.
+ */
+
+// ---------------------------------------------------------------------------
+// Primitive schema version
+// ---------------------------------------------------------------------------
+
+export const SCHEMA_VERSION = '1.0' as const;
+export type SchemaVersion = typeof SCHEMA_VERSION;
+
+// ---------------------------------------------------------------------------
+// Data binding
+// ---------------------------------------------------------------------------
+
+/**
+ * A binding reference to a value in the runtime context.
+ * e.g. { "$bind": "user.firstName" }
+ */
+export interface Binding {
+  readonly $bind: string;
+}
+
+export function isBinding(value: unknown): value is Binding {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '$bind' in value &&
+    typeof (value as Record<string, unknown>)['$bind'] === 'string'
+  );
+}
+
+/**
+ * A prop value is either a static primitive / object, or a binding.
+ */
+export type PropValue =
+  | string
+  | number
+  | boolean
+  | null
+  | Binding
+  | PropValue[]
+  | { [key: string]: PropValue };
+
+export type PropsMap = Record<string, PropValue>;
+
+// ---------------------------------------------------------------------------
+// Conditions
+// ---------------------------------------------------------------------------
+
+/**
+ * A condition gates whether a node should render.
+ *
+ * Supported operators:
+ *   equals     — strict equality (===)
+ *   notEquals  — strict inequality (!==)
+ *   truthy     — if the resolved value is truthy (no `value` needed)
+ *   falsy      — if the resolved value is falsy  (no `value` needed)
+ */
+export type ConditionOperator = 'equals' | 'notEquals' | 'truthy' | 'falsy';
+
+export interface Condition {
+  /** The binding (or static value) to test. */
+  readonly if: Binding | PropValue;
+  /** Comparison operator. Defaults to "truthy" when omitted. */
+  readonly operator?: ConditionOperator;
+  /**
+   * The right-hand side value to compare against.
+   * Required for `equals` / `notEquals`; ignored for `truthy` / `falsy`.
+   */
+  readonly equals?: PropValue;
+}
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+/** Navigate to another screen by ID. */
+export interface NavigateAction {
+  readonly type: 'navigate';
+  readonly screen: string;
+  readonly params?: Record<string, PropValue>;
+}
+
+/** Emit a named custom event. The host app decides what to do with it. */
+export interface CustomAction {
+  readonly type: 'custom';
+  readonly event: string;
+  readonly payload?: Record<string, PropValue>;
+}
+
+export type PushframeAction = NavigateAction | CustomAction;
+
+export type ActionsMap = Record<string, PushframeAction>;
+
+// ---------------------------------------------------------------------------
+// Node
+// ---------------------------------------------------------------------------
+
+/**
+ * A single node in the UI tree.
+ *
+ * `type` maps to a registered component (e.g. "stack", "text", "button", "image").
+ * `props` are passed (after binding resolution) directly to the component.
+ * `children` are rendered recursively.
+ * `conditions` — when present, node is skipped if the condition evaluates to false.
+ * `actions` — event handler definitions; passed to the component as resolved callbacks.
+ */
+export interface PushframeNode {
+  readonly type: string;
+  readonly props?: PropsMap;
+  readonly children?: readonly PushframeNode[];
+  readonly conditions?: Condition;
+  readonly actions?: ActionsMap;
+}
+
+// ---------------------------------------------------------------------------
+// Screen definition
+// ---------------------------------------------------------------------------
+
+export interface ScreenDefinition {
+  readonly schemaVersion: SchemaVersion;
+  readonly id: string;
+  readonly root: PushframeNode;
+  /** Optional display name — used for debugging / logging. */
+  readonly name?: string;
+}