@digia-engage/core 2.0.3 → 2.2.0

package/src/DigiaProvider.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
 import {
     Animated,
     Dimensions,
@@ -17,6 +17,18 @@ import { digiaAnchorRegistry, type AnchorLayout } from './digiaAnchorRegistry';
 import { digiaActionHandler, type ActionCallbacks } from './actionHandler';
 import type { DismissReason } from './types';
 import type { Action, SpotlightConfig, SpotlightStep, TooltipConfig, TooltipStep } from './templateTypes';
+import { interpolateVariables, type VariableMap } from './interpolate';
+
+// ─── Variable context ─────────────────────────────────────────────────────────
+// Provides the active campaign's variable map to all descendant components.
+// Avoids threading `variables` through every prop chain.
+
+const VariableContext = createContext<VariableMap | undefined>(undefined);
+
+function TextWithVariables({ children, ...props }: Omit<React.ComponentProps<typeof Text>, 'children'> & { children: string }) {
+    const variables = useContext(VariableContext);
+    return <Text {...props}>{interpolateVariables(children, variables)}</Text>;
+}
 
 // ─── @floating-ui/core platform adapter ──────────────────────────────────────
 
@@ -184,9 +196,9 @@ function ActionButton({
             onPress={onPress}
             style={[s.button, isPrimary && { backgroundColor: btnPrimaryBg }]}
         >
-            <Text style={{ color: isPrimary ? btnPrimaryText : btnGhostText, fontSize: 13, fontWeight: '600', fontFamily }}>
+            <TextWithVariables style={{ color: isPrimary ? btnPrimaryText : btnGhostText, fontSize: 13, fontWeight: '600', fontFamily }}>
                 {action.label}
-            </Text>
+            </TextWithVariables>
         </Pressable>
     );
 }
@@ -221,10 +233,20 @@ function TooltipOverlay({
     useEffect(() => {
         setLayout(null);
         setFloatPos(null);
-        return digiaAnchorRegistry.subscribe(step.anchorKey, (l) => {
+        let skipCached = false;
+        const unsub = digiaAnchorRegistry.subscribe(step.anchorKey, (l) => {
+            if (!skipCached) return;
+            const { width: screenW, height: screenH } = Dimensions.get('window');
+            if (l.pageY + l.height <= 0 || l.pageY >= screenH || l.pageX + l.width <= 0 || l.pageX >= screenW) {
+                digiaGuideController.cancel(request.payloadId);
+                return;
+            }
             setLayout(l);
         });
-    }, [step.anchorKey]);
+        skipCached = true;
+        digiaAnchorRegistry.remeasure(step.anchorKey);
+        return unsub;
+    }, [step.anchorKey]); // eslint-disable-line react-hooks/exhaustive-deps
 
     useEffect(() => {
         if (!layout || !floatingSize) return;
@@ -317,104 +339,110 @@ function TooltipOverlay({
     }, [config.outsideTapBehavior, next, dismiss]);
 
     return (
-        <Modal transparent statusBarTranslucent animationType="none" visible>
-            <Animated.View style={[StyleSheet.absoluteFill, { opacity: opacityAnim }]}>
-                {/* Full-screen backdrop: blocks all touches (scroll, tap) */}
-                <Pressable style={StyleSheet.absoluteFill} onPress={handleBackdropPress} />
-                {floatPos ? (
-                    // Bubble as Pressable so tapping the bubble body also advances
-                    <Pressable
-                        onLayout={(e) => {
-                            const { width, height } = e.nativeEvent.layout;
-                            if (floatingSize?.w !== width || floatingSize?.h !== height) {
-                                setFloatingSize({ w: width, h: height });
-                            }
-                        }}
-                        onPress={handleBackdropPress}
-                        style={[
-                            s.tooltipBubble,
-                            {
-                                left: floatPos.x,
-                                top: floatPos.y,
-                                width: tooltipW,
-                                backgroundColor: step.backgroundColor,
-                                borderRadius: step.cornerRadius,
-                                borderWidth: step.borderWidth,
-                                borderColor: step.borderColor,
-                                padding: step.padding,
-                            },
-                            step.shadow && s.shadow,
-                        ]}
-                    >
-                        {showArrow && (
-                            <GuideArrow
-                                placement={resolvedPlacement}
-                                color={step.arrowColor ?? step.backgroundColor}
-                                borderColor={step.arrowBorderColor ?? step.borderColor}
-                                size={arrowSize}
-                                arrowOffset={arrowOffset}
-                            />
-                        )}
-                        <Text style={{ color: step.titleColor, fontSize: step.titleSize, fontWeight: step.titleWeight, fontFamily }}>
-                            {step.title}
-                        </Text>
-                        {!!step.body && (
-                            <Text style={{ marginTop: 4, color: step.bodyColor, fontSize: step.bodySize, fontFamily }}>
-                                {step.body}
-                            </Text>
-                        )}
-                        <View style={s.actionRow}>
-                            {step.actions.map((action, i) => (
-                                <ActionButton
-                                    key={i}
-                                    action={action}
-                                    btnPrimaryBg={step.buttonPrimaryBackgroundColor}
-                                    btnPrimaryText={step.buttonPrimaryTextColor}
-                                    btnGhostText={step.buttonGhostTextColor}
-                                    onPress={() => {
-                                        const isMultiStep = config.steps.length > 1;
-                                        const isLastStep = stepIndex === config.steps.length - 1;
-                                        const actionUrl = 'url' in action ? (action as { url: string }).url : undefined;
-                                        request.onExperienceEvent({ type: 'clicked', stepIndex, stepTotal: config.steps.length, anchorKey: step.anchorKey, displayStyle: 'tooltip', ctaLabel: action.label, actionType: action.type, actionUrl });
-                                        if (isMultiStep) {
-                                            request.onExperienceEvent({ type: 'step_clicked', stepIndex, stepTotal: config.steps.length, anchorKey: step.anchorKey, displayStyle: 'tooltip', ctaLabel: action.label, actionType: action.type, actionUrl });
-                                        }
-                                        if (isMultiStep && isLastStep && action.type !== 'back') {
-                                            request.onExperienceEvent({ type: 'completed', stepIndex, stepTotal: config.steps.length, anchorKey: step.anchorKey, displayStyle: 'tooltip' });
-                                        }
-                                        void digiaActionHandler.execute(action, {
-                                            campaign_id: request.payloadId,
-                                            campaign_key: request.campaignKey,
-                                            campaign_type: 'guide',
-                                            source: { kind: 'button', button_label: action.label },
-                                            step_index: stepIndex,
-                                            step_total: config.steps.length,
-                                        }, actionCallbacks());
-                                    }}
-                                />
-                            ))}
-                        </View>
-                    </Pressable>
-                ) : (
-                    // Off-screen measurement pass to determine bubble size before positioning.
-                    <View
-                        pointerEvents="none"
-                        onLayout={(e) => setFloatingSize({ w: e.nativeEvent.layout.width, h: e.nativeEvent.layout.height })}
-                        style={[s.tooltipBubble, { left: -9999, top: -9999, width: tooltipW, padding: step.padding }]}
-                    >
-                        <Text style={{ fontSize: step.titleSize, fontFamily }}>{step.title}</Text>
-                        {!!step.body && <Text style={{ fontSize: step.bodySize, fontFamily }}>{step.body}</Text>}
-                        <View style={s.actionRow}>
-                            {step.actions.map((a, i) => (
-                                <View key={i} style={s.button}>
-                                    <Text style={{ fontSize: 13, fontFamily }}>{a.label}</Text>
+        <VariableContext.Provider value={request.variables}>
+            <Modal transparent statusBarTranslucent animationType="none" visible>
+                {/* pointerEvents="box-none": container passes touches through; only children intercept.
+                    This prevents the invisible measurement pass from blocking the screen. */}
+                <Animated.View style={[StyleSheet.absoluteFill, { opacity: opacityAnim }]} pointerEvents="box-none">
+                    {floatPos ? (
+                        <>
+                            {/* Full-screen backdrop: blocks all touches once bubble is positioned */}
+                            <Pressable style={StyleSheet.absoluteFill} onPress={handleBackdropPress} />
+                            {/* Bubble as Pressable so tapping the bubble body also advances */}
+                            <Pressable
+                                onLayout={(e) => {
+                                    const { width, height } = e.nativeEvent.layout;
+                                    if (floatingSize?.w !== width || floatingSize?.h !== height) {
+                                        setFloatingSize({ w: width, h: height });
+                                    }
+                                }}
+                                onPress={handleBackdropPress}
+                                style={[
+                                    s.tooltipBubble,
+                                    {
+                                        left: floatPos.x,
+                                        top: floatPos.y,
+                                        width: tooltipW,
+                                        backgroundColor: step.backgroundColor,
+                                        borderRadius: step.cornerRadius,
+                                        borderWidth: step.borderWidth,
+                                        borderColor: step.borderColor,
+                                        padding: step.padding,
+                                    },
+                                    step.shadow && s.shadow,
+                                ]}
+                            >
+                                {showArrow && (
+                                    <GuideArrow
+                                        placement={resolvedPlacement}
+                                        color={step.arrowColor ?? step.backgroundColor}
+                                        borderColor={step.arrowBorderColor ?? step.borderColor}
+                                        size={arrowSize}
+                                        arrowOffset={arrowOffset}
+                                    />
+                                )}
+                                <TextWithVariables style={{ color: step.titleColor, fontSize: step.titleSize, fontWeight: step.titleWeight, fontFamily }}>
+                                    {step.title}
+                                </TextWithVariables>
+                                {!!step.body && (
+                                    <TextWithVariables style={{ marginTop: 4, color: step.bodyColor, fontSize: step.bodySize, fontFamily }}>
+                                        {step.body}
+                                    </TextWithVariables>
+                                )}
+                                <View style={s.actionRow}>
+                                    {step.actions.map((action, i) => (
+                                        <ActionButton
+                                            key={i}
+                                            action={action}
+                                            btnPrimaryBg={step.buttonPrimaryBackgroundColor}
+                                            btnPrimaryText={step.buttonPrimaryTextColor}
+                                            btnGhostText={step.buttonGhostTextColor}
+                                            onPress={() => {
+                                                const isMultiStep = config.steps.length > 1;
+                                                const isLastStep = stepIndex === config.steps.length - 1;
+                                                const actionUrl = 'url' in action ? (action as { url: string }).url : undefined;
+                                                request.onExperienceEvent({ type: 'clicked', stepIndex, stepTotal: config.steps.length, anchorKey: step.anchorKey, displayStyle: 'tooltip', ctaLabel: action.label, actionType: action.type, actionUrl });
+                                                if (isMultiStep) {
+                                                    request.onExperienceEvent({ type: 'step_clicked', stepIndex, stepTotal: config.steps.length, anchorKey: step.anchorKey, displayStyle: 'tooltip', ctaLabel: action.label, actionType: action.type, actionUrl });
+                                                }
+                                                if (isMultiStep && isLastStep && action.type !== 'back') {
+                                                    request.onExperienceEvent({ type: 'completed', stepIndex, stepTotal: config.steps.length, anchorKey: step.anchorKey, displayStyle: 'tooltip' });
+                                                }
+                                                void digiaActionHandler.execute(action, {
+                                                    campaign_id: request.payloadId,
+                                                    campaign_key: request.campaignKey,
+                                                    campaign_type: 'guide',
+                                                    source: { kind: 'button', button_label: action.label },
+                                                    step_index: stepIndex,
+                                                    step_total: config.steps.length,
+                                                }, actionCallbacks());
+                                            }}
+                                        />
+                                    ))}
                                 </View>
-                            ))}
+                            </Pressable>
+                        </>
+                    ) : (
+                        // Off-screen measurement pass to determine bubble size before positioning.
+                        <View
+                            pointerEvents="none"
+                            onLayout={(e) => setFloatingSize({ w: e.nativeEvent.layout.width, h: e.nativeEvent.layout.height })}
+                            style={[s.tooltipBubble, { left: -9999, top: -9999, width: tooltipW, padding: step.padding }]}
+                        >
+                            <TextWithVariables style={{ fontSize: step.titleSize, fontFamily }}>{step.title}</TextWithVariables>
+                            {!!step.body && <TextWithVariables style={{ fontSize: step.bodySize, fontFamily }}>{step.body}</TextWithVariables>}
+                            <View style={s.actionRow}>
+                                {step.actions.map((a, i) => (
+                                    <View key={i} style={s.button}>
+                                        <TextWithVariables style={{ fontSize: 13, fontFamily }}>{a.label}</TextWithVariables>
+                                    </View>
+                                ))}
+                            </View>
                         </View>
-                    </View>
-                )}
-            </Animated.View>
-        </Modal>
+                    )}
+                </Animated.View>
+            </Modal>
+        </VariableContext.Provider>
     );
 }
 
@@ -505,12 +533,12 @@ function SpotlightCallout({
                 onLayout={(e) => setFloatingSize({ w: e.nativeEvent.layout.width, h: e.nativeEvent.layout.height })}
                 style={[calloutStyle, { position: 'absolute', left: -9999, top: -9999 }]}
             >
-                <Text style={{ fontSize: step.titleSize, fontFamily }}>{step.title}</Text>
-                {!!step.body && <Text style={{ marginTop: 4, fontSize: step.bodySize, fontFamily }}>{step.body}</Text>}
+                <TextWithVariables style={{ fontSize: step.titleSize, fontFamily }}>{step.title}</TextWithVariables>
+                {!!step.body && <TextWithVariables style={{ marginTop: 4, fontSize: step.bodySize, fontFamily }}>{step.body}</TextWithVariables>}
                 <View style={s.actionRow}>
                     {step.actions.map((a, i) => (
                         <View key={i} style={s.button}>
-                            <Text style={{ fontSize: 13, fontFamily }}>{a.label}</Text>
+                            <TextWithVariables style={{ fontSize: 13, fontFamily }}>{a.label}</TextWithVariables>
                         </View>
                     ))}
                 </View>
@@ -535,13 +563,13 @@ function SpotlightCallout({
                     arrowOffset={arrowOffset}
                 />
             )}
-            <Text style={{ color: step.titleColor, fontSize: step.titleSize, fontWeight: step.titleWeight, fontFamily }}>
+            <TextWithVariables style={{ color: step.titleColor, fontSize: step.titleSize, fontWeight: step.titleWeight, fontFamily }}>
                 {step.title}
-            </Text>
+            </TextWithVariables>
             {!!step.body && (
-                <Text style={{ marginTop: 4, color: step.bodyColor, fontSize: step.bodySize, fontFamily }}>
+                <TextWithVariables style={{ marginTop: 4, color: step.bodyColor, fontSize: step.bodySize, fontFamily }}>
                     {step.body}
-                </Text>
+                </TextWithVariables>
             )}
             <View style={s.actionRow}>
                 {step.actions.map((action, i) => (
@@ -575,10 +603,20 @@ function SpotlightOverlay({
 
     useEffect(() => {
         setLayout(null);
-        return digiaAnchorRegistry.subscribe(step.anchorKey, (l) => {
+        let skipCached = false;
+        const unsub = digiaAnchorRegistry.subscribe(step.anchorKey, (l) => {
+            if (!skipCached) return;
+            const { width: screenW, height: screenH } = Dimensions.get('window');
+            if (l.pageY + l.height <= 0 || l.pageY >= screenH || l.pageX + l.width <= 0 || l.pageX >= screenW) {
+                digiaGuideController.cancel(request.payloadId);
+                return;
+            }
             setLayout(l);
         });
-    }, [step.anchorKey]);
+        skipCached = true;
+        digiaAnchorRegistry.remeasure(step.anchorKey);
+        return unsub;
+    }, [step.anchorKey]); // eslint-disable-line react-hooks/exhaustive-deps
 
     useEffect(() => {
         if (layout && pendingFadeIn.current) {
@@ -676,42 +714,44 @@ function SpotlightOverlay({
         : '';
 
     return (
-        <Modal transparent statusBarTranslucent animationType="none" visible>
-            <Animated.View style={[StyleSheet.absoluteFill, { opacity: opacityAnim }]} pointerEvents="box-none">
-                {layout && (
-                    <>
-                        <Svg
-                            width={screenW}
-                            height={screenH}
-                            style={StyleSheet.absoluteFill}
-                            pointerEvents="none"
-                        >
-                            <Path
-                                fillRule="evenodd"
-                                d={`${screenPath} ${cutoutPath}`}
-                                fill={step.overlayColor}
-                                fillOpacity={step.overlayOpacity}
-                            />
-                            {step.highlightGlowWidth > 0 && (
+        <VariableContext.Provider value={request.variables}>
+            <Modal transparent statusBarTranslucent animationType="none" visible>
+                <Animated.View style={[StyleSheet.absoluteFill, { opacity: opacityAnim }]} pointerEvents="box-none">
+                    {layout && (
+                        <>
+                            <Svg
+                                width={screenW}
+                                height={screenH}
+                                style={StyleSheet.absoluteFill}
+                                pointerEvents="none"
+                            >
                                 <Path
-                                    d={cutoutPath}
-                                    fill="none"
-                                    stroke={step.highlightGlowColor}
-                                    strokeWidth={step.highlightGlowWidth}
+                                    fillRule="evenodd"
+                                    d={`${screenPath} ${cutoutPath}`}
+                                    fill={step.overlayColor}
+                                    fillOpacity={step.overlayOpacity}
                                 />
-                            )}
-                        </Svg>
-                        {/* Backdrop with configurable outside-tap behaviour */}
-                        <Pressable style={StyleSheet.absoluteFill} onPress={handleBackdropPress} />
-                        <SpotlightCallout
-                            step={step}
-                            layout={layout}
-                            onActionPress={handleActionPress}
-                        />
-                    </>
-                )}
-            </Animated.View>
-        </Modal>
+                                {step.highlightGlowWidth > 0 && (
+                                    <Path
+                                        d={cutoutPath}
+                                        fill="none"
+                                        stroke={step.highlightGlowColor}
+                                        strokeWidth={step.highlightGlowWidth}
+                                    />
+                                )}
+                            </Svg>
+                            {/* Backdrop with configurable outside-tap behaviour */}
+                            <Pressable style={StyleSheet.absoluteFill} onPress={handleBackdropPress} />
+                            <SpotlightCallout
+                                step={step}
+                                layout={layout}
+                                onActionPress={handleActionPress}
+                            />
+                        </>
+                    )}
+                </Animated.View>
+            </Modal>
+        </VariableContext.Provider>
     );
 }
 
@@ -773,4 +813,4 @@ const s = StyleSheet.create({
         borderRadius: 8,
         paddingHorizontal: 12,
     },
-});
+});

package/src/digiaAnchorRegistry.ts

@@ -1,8 +1,10 @@
 type AnchorLayout = { pageX: number; pageY: number; width: number; height: number }
 type Listener = (layout: AnchorLayout) => void
+type MeasureCallback = () => void
 
 const _layouts = new Map<string, AnchorLayout>()
 const _listeners = new Map<string, Listener>()
+const _measureCallbacks = new Map<string, MeasureCallback>()
 
 const setLayout = (key: string, layout: AnchorLayout) => {
     _layouts.set(key, layout)
@@ -21,7 +23,20 @@ const subscribe = (key: string, listener: Listener): () => void => {
 const remove = (key: string) => {
     _layouts.delete(key)
     _listeners.delete(key)
+    _measureCallbacks.delete(key)
+}
+
+const registerMeasure = (key: string, cb: MeasureCallback) => {
+    _measureCallbacks.set(key, cb)
+}
+
+const unregisterMeasure = (key: string, cb: MeasureCallback) => {
+    if (_measureCallbacks.get(key) === cb) _measureCallbacks.delete(key)
+}
+
+const remeasure = (key: string) => {
+    _measureCallbacks.get(key)?.()
 }
 
 export type { AnchorLayout }
-export const digiaAnchorRegistry = { setLayout, getLayout, subscribe, remove }
+export const digiaAnchorRegistry = { setLayout, getLayout, subscribe, remove, registerMeasure, unregisterMeasure, remeasure }

package/src/interpolate.ts

@@ -0,0 +1,44 @@
+export type VariableMap = Record<string, string>;
+
+const PLACEHOLDER_PATTERN = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+
+export function interpolateVariables(
+    text: string,
+    variables: VariableMap | undefined,
+): string {
+    if (!variables) return text;
+    return text.replace(PLACEHOLDER_PATTERN, (match, name: string) => {
+        const value = variables[name];
+        return value === undefined ? '' : value;
+    });
+}
+
+export function parseVariableMap(raw: unknown): VariableMap | undefined {
+    const source = parseVariableSource(raw);
+    if (!source) return undefined;
+
+    const variables: VariableMap = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+        if (typeof value === 'string') variables[key] = value;
+        else if (typeof value === 'number' || typeof value === 'boolean') variables[key] = String(value);
+    }
+    return Object.keys(variables).length > 0 ? variables : undefined;
+}
+
+function parseVariableSource(raw: unknown): Record<string, unknown> | undefined {
+    if (!raw) return undefined;
+    if (typeof raw === 'string') {
+        try {
+            const parsed = JSON.parse(raw);
+            return isPlainObject(parsed) ? parsed : undefined;
+        } catch {
+            return undefined;
+        }
+    }
+    return isPlainObject(raw) ? raw : undefined;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}