noboarding 0.1.0-alpha

package/src/types.ts

@@ -0,0 +1,242 @@
+import type React from 'react';
+
+// Screen component types
+export type ScreenType = 'noboard_screen' | 'custom_screen';
+
+// Screen configuration from remote
+export interface ScreenConfig {
+  id: string;
+  type: ScreenType;
+  props: Record<string, any>;
+  // For noboard_screen type — the element tree from the AI builder
+  elements?: ElementNode[];
+  // For custom_screen type — name of the developer-registered component
+  custom_component_name?: string;
+}
+
+// ─── Element Tree Types (matches dashboard primitives) ───
+
+export type ElementType =
+  // Containers (have children)
+  | 'vstack'
+  | 'hstack'
+  | 'zstack'
+  | 'scrollview'
+  // Content (leaf elements)
+  | 'text'
+  | 'image'
+  | 'video'
+  | 'lottie'
+  | 'icon'
+  | 'input'
+  | 'spacer'
+  | 'divider';
+
+export interface ElementNode {
+  id: string;
+  type: ElementType;
+  style: ElementStyle;
+  props: Record<string, any>;
+  children?: ElementNode[];
+  position?: ElementPosition;
+  action?: ElementAction;
+  actions?: ElementAction[];       // multi-action support (runs all in sequence)
+  visibleWhen?: { group: string; hasSelection: boolean };
+  conditions?: ElementConditions;  // variable-based show/hide
+}
+
+// ─── Condition & Variable Types ───
+
+export type ComparisonOperator = 'equals' | 'not_equals' | 'greater_than' | 'less_than' | 'contains' | 'in' | 'is_empty' | 'is_not_empty';
+
+export interface Condition {
+  variable?: string;
+  operator?: ComparisonOperator;
+  value?: any;
+  all?: Condition[];    // AND — all must be true
+  any?: Condition[];    // OR — at least one must be true
+  not?: Condition;      // NOT — negate
+}
+
+export interface ElementConditions {
+  show_if?: Condition;
+}
+
+export interface ConditionalDestination {
+  if: Condition;
+  then: string;
+  else?: string | ConditionalDestination;
+}
+
+export interface ConditionalRoutes {
+  routes: Array<{ condition: Condition; destination: string }>;
+  default: string;
+}
+
+// ─── Element Action ───
+
+export interface ElementAction {
+  type: 'tap' | 'navigate' | 'link' | 'toggle' | 'dismiss' | 'set_variable';
+  destination?: string | ConditionalDestination | ConditionalRoutes; // screen ID, URL, or conditional
+  group?: string; // selection group name for single-select toggles
+  variable?: string; // for set_variable: variable name to set
+  value?: any;       // for set_variable: value to assign
+}
+
+export interface ElementPosition {
+  type?: 'relative' | 'absolute';
+  top?: number;
+  left?: number;
+  right?: number;
+  bottom?: number;
+  centerX?: boolean;
+  centerY?: boolean;
+  zIndex?: number;
+}
+
+export interface ElementStyle {
+  // Layout
+  flex?: number;
+  flexDirection?: 'row' | 'column';
+  justifyContent?: 'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly';
+  alignItems?: 'flex-start' | 'center' | 'flex-end' | 'stretch';
+  alignSelf?: 'flex-start' | 'center' | 'flex-end' | 'stretch';
+  gap?: number;
+  flexWrap?: 'wrap' | 'nowrap';
+  overflow?: 'visible' | 'hidden' | 'scroll';
+
+  // Spacing
+  padding?: number;
+  paddingTop?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  paddingRight?: number;
+  marginTop?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+  marginRight?: number;
+
+  // Size
+  width?: number | string;
+  height?: number | string;
+  maxWidth?: number;
+  minHeight?: number | string;
+
+  // Visual
+  backgroundColor?: string;
+  backgroundGradient?: {
+    type: 'linear' | 'radial';
+    angle?: number;
+    colors: Array<{ color: string; position: number }>;
+  };
+  opacity?: number;
+  borderRadius?: number;
+  borderWidth?: number;
+  borderColor?: string;
+  borderBottomWidth?: number;
+  borderBottomColor?: string;
+
+  // Shadow
+  shadowColor?: string;
+  shadowOpacity?: number;
+  shadowRadius?: number;
+  shadowOffsetX?: number;
+  shadowOffsetY?: number;
+
+  // Text
+  color?: string;
+  fontSize?: number;
+  fontWeight?: string;
+  textAlign?: 'left' | 'center' | 'right' | 'justify';
+  lineHeight?: number;
+  letterSpacing?: number;
+  textTransform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize';
+  textDecorationLine?: 'none' | 'underline' | 'line-through';
+}
+
+// Onboarding configuration from API
+export interface OnboardingConfig {
+  version: string;
+  screens: ScreenConfig[];
+}
+
+// Experiment/A/B test variant
+export interface Experiment {
+  id: string;
+  name: string;
+  variants: Variant[];
+}
+
+export interface Variant {
+  variant_id: string;
+  weight: number;
+  name: string;
+  screens: ScreenConfig[];
+}
+
+// Analytics event
+export interface AnalyticsEvent {
+  event: string;
+  user_id: string;
+  session_id: string;
+  timestamp: number;
+  properties?: Record<string, any>;
+}
+
+// API response types
+export interface GetConfigResponse {
+  config: OnboardingConfig;
+  version: string;
+  experiments: Experiment[];
+  organization_id: string;
+}
+
+export interface TrackEventsResponse {
+  success: boolean;
+  inserted: number;
+}
+
+export interface AssignVariantResponse {
+  variant_id: string;
+  variant_config: {
+    screens: ScreenConfig[];
+  };
+  cached: boolean;
+}
+
+// Component props
+export interface BaseComponentProps {
+  id: string;
+  analytics: Analytics;
+  onNext: (data?: Record<string, any>) => void;
+  onSkip?: () => void;
+}
+
+// Analytics class interface
+export interface Analytics {
+  track(eventName: string, properties?: Record<string, any>): void;
+  flush(): Promise<void>;
+}
+
+// Props interface for developer-registered custom screen components
+export interface CustomScreenProps {
+  analytics: {
+    track: (event: string, properties?: Record<string, any>) => void;
+  };
+  onNext: () => void;
+  onSkip?: () => void;
+  preview?: boolean;
+  data?: Record<string, any>;
+  onDataUpdate?: (data: Record<string, any>) => void;
+}
+
+// Main SDK props
+export interface OnboardingFlowProps {
+  apiKey: string;
+  onComplete: (data?: Record<string, any>) => void;
+  onSkip?: () => void;
+  baseUrl?: string;
+  initialVariables?: Record<string, any>; // seed the variable store
+  customComponents?: Record<string, React.ComponentType<CustomScreenProps>>;
+  onUserIdGenerated?: (userId: string) => void; // Called when user ID is generated for analytics
+}

package/src/variableUtils.ts

@@ -0,0 +1,133 @@
+import { Condition, ComparisonOperator, ConditionalDestination, ConditionalRoutes } from './types';
+
+/**
+ * Resolve {variable_name} placeholders in a template string.
+ * Unknown variables resolve to empty string.
+ */
+export function resolveTemplate(
+  template: string,
+  variables: Record<string, any>
+): string {
+  if (!template || !template.includes('{')) return template;
+  return template.replace(/\{(\w+(?:\.\w+)*)\}/g, (_match, varName) => {
+    // Support dot notation: "user.name" → variables["user.name"] or variables.user?.name
+    let value = variables[varName];
+    if (value === undefined && varName.includes('.')) {
+      const parts = varName.split('.');
+      value = variables[parts[0]];
+      for (let i = 1; i < parts.length && value != null; i++) {
+        value = value[parts[i]];
+      }
+    }
+    if (value === undefined || value === null) return '';
+    return String(value);
+  });
+}
+
+/**
+ * Evaluate a single comparison against the variable store.
+ */
+function evaluateComparison(
+  variableName: string,
+  operator: ComparisonOperator,
+  conditionValue: any,
+  variables: Record<string, any>
+): boolean {
+  const actual = variables[variableName];
+
+  switch (operator) {
+    case 'equals':
+      return actual === conditionValue;
+    case 'not_equals':
+      return actual !== conditionValue;
+    case 'greater_than':
+      return typeof actual === 'number' && actual > conditionValue;
+    case 'less_than':
+      return typeof actual === 'number' && actual < conditionValue;
+    case 'contains':
+      if (typeof actual === 'string') return actual.includes(conditionValue);
+      if (Array.isArray(actual)) return actual.includes(conditionValue);
+      return false;
+    case 'in':
+      return Array.isArray(conditionValue) && conditionValue.includes(actual);
+    case 'is_empty':
+      return actual === undefined || actual === null || actual === '' ||
+        (Array.isArray(actual) && actual.length === 0);
+    case 'is_not_empty':
+      return actual !== undefined && actual !== null && actual !== '' &&
+        !(Array.isArray(actual) && actual.length === 0);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Recursively evaluate a Condition tree against the variable store.
+ * Supports: single comparison, all (AND), any (OR), not (negation).
+ * Returns true if no valid condition structure (default: show element).
+ */
+export function evaluateCondition(
+  condition: Condition,
+  variables: Record<string, any>
+): boolean {
+  if (!condition) return true;
+
+  // AND logic
+  if (condition.all) {
+    return condition.all.every(c => evaluateCondition(c, variables));
+  }
+
+  // OR logic
+  if (condition.any) {
+    return condition.any.some(c => evaluateCondition(c, variables));
+  }
+
+  // Negation
+  if (condition.not) {
+    return !evaluateCondition(condition.not, variables);
+  }
+
+  // Single comparison
+  if (condition.variable && condition.operator) {
+    return evaluateComparison(condition.variable, condition.operator, condition.value, variables);
+  }
+
+  // No valid condition structure — default to true
+  return true;
+}
+
+/**
+ * Resolve a destination (plain string or conditional) to a concrete screen ID.
+ * Returns the string destination or undefined.
+ */
+export function resolveDestination(
+  destination: string | ConditionalDestination | ConditionalRoutes | undefined,
+  variables: Record<string, any>
+): string | undefined {
+  if (!destination) return undefined;
+
+  // Plain string — backward compatible
+  if (typeof destination === 'string') return destination;
+
+  // Routes array (multi-path)
+  if ('routes' in destination) {
+    const routes = destination as ConditionalRoutes;
+    for (const route of routes.routes) {
+      if (evaluateCondition(route.condition, variables)) {
+        return route.destination;
+      }
+    }
+    return routes.default;
+  }
+
+  // If/then/else
+  const cond = destination as ConditionalDestination;
+  if (evaluateCondition(cond.if, variables)) {
+    return cond.then;
+  }
+  if (cond.else) {
+    if (typeof cond.else === 'string') return cond.else;
+    return resolveDestination(cond.else, variables);
+  }
+  return 'next'; // fallback
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "commonjs",
+    "lib": ["ES2017"],
+    "jsx": "react-native",
+    "declaration": true,
+    "outDir": "./lib",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "lib", "**/*.spec.ts"]
+}