@userflow-tech/react-native 0.1.0

package/src/content/StepButton.tsx

@@ -0,0 +1,70 @@
+import { interpolateSessionData } from '@userflow-tech/core';
+import type {
+  FlowActionFragment,
+  FlowButtonFragment,
+  ThemeFragment,
+} from '@userflow-tech/protocol';
+import * as React from 'react';
+import type { TextStyle } from 'react-native';
+import { Platform, Pressable, StyleSheet, Text } from 'react-native';
+
+import { isPrimaryButtonAppearance } from './buttonAppearance';
+import { resolveStepButtonChrome, stepButtonContainerStyle } from './resolveStepButtonChrome';
+
+export interface StepButtonProps {
+  button: FlowButtonFragment;
+  theme: ThemeFragment;
+  sessionData: { name: string; value: string | string[] }[];
+  onActions: (actions: FlowActionFragment[]) => void;
+}
+
+export function StepButton({
+  button,
+  theme,
+  sessionData,
+  onActions,
+}: StepButtonProps): React.ReactElement {
+  const label = interpolateSessionData(button.text, sessionData);
+  const isPrimary = isPrimaryButtonAppearance(button.appearance);
+  const chrome = resolveStepButtonChrome(theme, isPrimary);
+
+  return (
+    <Pressable
+      testID={`userflow-button-${button.cvid}`}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      onPress={() => onActions(button.actions)}
+      style={({ pressed }) => [
+        styles.button,
+        stepButtonContainerStyle(chrome),
+        { opacity: pressed ? 0.88 : 1 },
+      ]}
+    >
+      <Text
+        style={[
+          styles.label,
+          {
+            color: chrome.fontColor,
+            fontFamily: theme.fontFamily || undefined,
+            fontSize: chrome.fontSize,
+            lineHeight: chrome.lineHeight,
+            fontWeight: chrome.fontWeight,
+            ...(Platform.OS === 'android' ? { includeFontPadding: false } : null),
+          } satisfies TextStyle,
+        ]}
+      >
+        {label}
+      </Text>
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  button: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  label: {
+    textAlign: 'center',
+  },
+});

package/src/content/buttonAppearance.ts

@@ -0,0 +1,11 @@
+/**
+ * Web parity: DEFAULT / default map to secondary (`--default`); PRIMARY
+ * (and banner-primary) use the filled primary CTA treatment.
+ *
+ * @see userflow/web/app/util/flow-formatting.tsx `formatButtonClassName`
+ */
+export function isPrimaryButtonAppearance(appearance: string | null | undefined): boolean {
+  if (!appearance) return false;
+  const normalized = appearance.toLowerCase();
+  return normalized === 'primary' || normalized === 'banner-primary';
+}

package/src/content/deserialize.ts

@@ -0,0 +1,147 @@
+import type {
+  AttributeElement,
+  LookupAttribute,
+  ParagraphElement,
+  PlaintextDoc,
+  PlaintextElement,
+  PlaintextText,
+  RichContentDoc,
+} from './types';
+
+export function emptyParagraph(text = ''): ParagraphElement {
+  return {
+    type: 'paragraph',
+    children: [{ text }],
+  };
+}
+
+export function emptyRichContentDoc(text = ''): RichContentDoc {
+  return {
+    type: 'rich2',
+    children: [emptyParagraph(text)],
+  };
+}
+
+export function emptyPlaintextDoc(text = ''): PlaintextDoc {
+  return {
+    type: 'plaintext2',
+    children: [
+      {
+        type: 'plaintext',
+        children: [{ text }],
+      },
+    ],
+  };
+}
+
+/**
+ * Parse a wire `content` string into a rich2 doc.
+ * Invalid JSON / wrong type returns an empty doc (never throws) so a bad step
+ * cannot crash the host app.
+ */
+export function deserializeRichContentDoc(input: string | null | undefined): RichContentDoc {
+  if (!input) return emptyRichContentDoc();
+  try {
+    const doc = JSON.parse(input) as { type?: string };
+    if (doc?.type === 'rich2') {
+      return doc as RichContentDoc;
+    }
+  } catch {
+    // fall through
+  }
+  return emptyRichContentDoc();
+}
+
+export function deserializePlaintextDoc(input: string | null | undefined): PlaintextDoc {
+  if (!input) return emptyPlaintextDoc();
+  try {
+    const doc = JSON.parse(input) as { type?: string };
+    if (doc?.type === 'plaintext2') {
+      return doc as PlaintextDoc;
+    }
+  } catch {
+    // fall through
+  }
+  return emptyPlaintextDoc();
+}
+
+export function isText(node: unknown): node is { text: string } {
+  return (
+    typeof node === 'object' &&
+    node !== null &&
+    typeof (node as { text?: unknown }).text === 'string'
+  );
+}
+
+export function isElement(node: unknown): node is { type: string; children: unknown[] } {
+  return (
+    typeof node === 'object' &&
+    node !== null &&
+    Array.isArray((node as { children?: unknown }).children) &&
+    typeof (node as { text?: unknown }).text !== 'string'
+  );
+}
+
+export function getAttributeNodeValue(
+  node: AttributeElement,
+  lookupAttribute: LookupAttribute | undefined,
+): string | null {
+  if (!lookupAttribute) return null;
+  const fqn = node.attributeName;
+  if (typeof fqn === 'string') {
+    const value = lookupAttribute(fqn) || node.fallback;
+    if (typeof value === 'string') return value;
+  }
+  return null;
+}
+
+/** Walk a plaintext2 doc (or string) into a plain string, resolving attribute nodes. */
+export function stringifyPlaintextDoc(
+  doc: PlaintextDoc | string | null | undefined,
+  { lookupAttribute }: { lookupAttribute?: LookupAttribute } = {},
+): string {
+  if (!doc) return '';
+  if (typeof doc === 'string') {
+    doc = deserializePlaintextDoc(doc);
+  }
+
+  const out: string[] = [];
+
+  function walk(node: PlaintextElement | PlaintextText): void {
+    if (isText(node)) {
+      if (node.text) out.push(node.text);
+      return;
+    }
+    if (node.type === 'attribute') {
+      const value = getAttributeNodeValue(node, lookupAttribute);
+      if (value) out.push(value);
+      return;
+    }
+    for (const child of node.children ?? []) {
+      if (child) walk(child);
+    }
+  }
+
+  for (const child of doc.children ?? []) {
+    if (child) walk(child);
+  }
+  return out.join('');
+}
+
+export function traverseTreeDoc(
+  root: { children: unknown[] } | unknown[],
+  callback: (node: unknown, idx: number) => void,
+): void {
+  function walk(node: unknown, idx: number): void {
+    callback(node, idx);
+    if (isElement(node)) {
+      for (const [i, child] of (node.children ?? []).entries()) {
+        if (child) walk(child, i);
+      }
+    }
+  }
+  const children = Array.isArray(root) ? root : root.children;
+  for (const [i, child] of (children ?? []).entries()) {
+    if (child) walk(child, i);
+  }
+}

package/src/content/imageLayout.ts

@@ -0,0 +1,29 @@
+import type { DimensionValue } from 'react-native';
+
+import type { ImageElement } from './types';
+
+export type ImageFrame = {
+  /** Width applied to a wrapping View (percent / fill are reliable here). */
+  wrapperWidth: DimensionValue;
+  aspectRatio: number | undefined;
+};
+
+/**
+ * Resolve image frame sizing for RN: percentage and fill widths belong on a
+ * wrapping View; the Image itself stretches to 100% of that wrapper.
+ */
+export function resolveImageFrame(node: ImageElement): ImageFrame {
+  let wrapperWidth: DimensionValue = '100%';
+  if (node.widthMode === 'px' && node.displayWidth != null) {
+    wrapperWidth = node.displayWidth;
+  } else if (node.widthMode === 'percent' && node.displayWidth != null) {
+    wrapperWidth = `${node.displayWidth}%`;
+  }
+
+  const aspectRatio =
+    node.width != null && node.height != null && node.width > 0
+      ? node.width / node.height
+      : undefined;
+
+  return { wrapperWidth, aspectRatio };
+}

package/src/content/migrateFlowBlocks.ts

@@ -0,0 +1,39 @@
+import { isElement, traverseTreeDoc } from './deserialize';
+import type { ButtonElement, RichContentDoc } from './types';
+
+/**
+ * Append a trailing button-group for any step buttons missing from the doc
+ * (legacy flows stored buttons only on the step fragment). Questions are skipped
+ * in Phase 3 MVP.
+ */
+export function migrateFlowBlocksIntoContent(
+  doc: RichContentDoc,
+  { buttons }: { buttons?: { cvid: string }[] } = {},
+): RichContentDoc {
+  const buttonCvids = new Set<string>();
+  traverseTreeDoc(doc, (node) => {
+    if (isElement(node) && node.type === 'button') {
+      buttonCvids.add((node as ButtonElement).cvid);
+    }
+  });
+
+  if (!buttons?.length) return doc;
+
+  const missingButtons = buttons.filter((button) => !buttonCvids.has(button.cvid));
+  if (missingButtons.length === 0) return doc;
+
+  return {
+    ...doc,
+    children: [
+      ...doc.children,
+      {
+        type: 'button-group',
+        children: missingButtons.map((button) => ({
+          type: 'button' as const,
+          cvid: button.cvid,
+          children: [{ text: '' as const }],
+        })),
+      },
+    ],
+  };
+}

package/src/content/openSafeUrl.ts

@@ -0,0 +1,30 @@
+import { Linking } from 'react-native';
+
+const ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);
+
+/**
+ * Returns true when `url` uses an allowlisted scheme suitable for opening
+ * from flow content (http(s), mailto, tel). Rejects javascript:, file:,
+ * custom schemes, and unparseable strings.
+ */
+export function isSafeUrl(url: string | null | undefined): boolean {
+  if (!url) return false;
+  const trimmed = url.trim();
+  if (!trimmed) return false;
+  try {
+    const parsed = new URL(trimmed);
+    return ALLOWED_PROTOCOLS.has(parsed.protocol);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Opens `url` via Linking when the scheme is allowlisted.
+ * @returns whether the URL was opened
+ */
+export async function openSafeUrl(url: string | null | undefined): Promise<boolean> {
+  if (!isSafeUrl(url) || !url) return false;
+  await Linking.openURL(url.trim());
+  return true;
+}

package/src/content/resolveStepButtonChrome.ts

@@ -0,0 +1,122 @@
+import type { ThemeFragment } from '@userflow-tech/protocol';
+import type { TextStyle, ViewStyle } from 'react-native';
+
+export interface StepButtonChrome {
+  backgroundColor: string;
+  fontColor: string;
+  borderColor: string;
+  borderWidth: number;
+  borderRadius: number;
+  minWidth: number;
+  buttonHeight: number;
+  fontSize: number;
+  lineHeight: number;
+  paddingHorizontal: number;
+  paddingVertical: number;
+  fontWeight: TextStyle['fontWeight'];
+}
+
+function readNumber(theme: ThemeFragment, key: string, fallback: number): number {
+  const value = theme[key];
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const parsed = parseFloat(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+}
+
+function readString(theme: ThemeFragment, key: string, fallback: string): string {
+  const value = theme[key];
+  return typeof value === 'string' && value.length > 0 ? value : fallback;
+}
+
+function firstString(theme: ThemeFragment, keys: string[], fallback: string): string {
+  for (const key of keys) {
+    const value = theme[key];
+    if (typeof value === 'string' && value.length > 0) return value;
+  }
+  return fallback;
+}
+
+/**
+ * Web bubble button chrome (`userflowjs-bubble-button--primary` /
+ * `--default`) with the same theme default chains as `fillThemeDefaults` in
+ * userflowjs/util/themes.ts.
+ */
+export function resolveStepButtonChrome(
+  theme: ThemeFragment,
+  isPrimary: boolean,
+): StepButtonChrome {
+  const widgetBackground = firstString(
+    theme,
+    ['widgetBackgroundColor', 'brandBackgroundColor', 'defaultButtonBackgroundColor'],
+    '#1a57e6',
+  );
+  const widgetForeground = firstString(
+    theme,
+    ['widgetForegroundColor', 'brandForegroundColor', 'defaultButtonFontColor'],
+    '#ffffff',
+  );
+  const mainBackground = firstString(theme, ['mainBackgroundColor', 'backgroundColor'], '#ffffff');
+
+  const fontSize = theme.fontSize > 0 ? theme.fontSize : 16;
+  // Backend theme default is 24px (`themes.line_height`).
+  const lineHeight = readNumber(theme, 'lineHeight', 24);
+  const buttonHeight = readNumber(theme, 'buttonHeight', 32);
+  const borderRadius = readNumber(theme, 'buttonBorderRadius', 8);
+  const minWidth = readNumber(theme, 'buttonMinWidth', 0);
+  const fontWeightBold = readNumber(theme, 'fontWeightBold', 600);
+
+  let backgroundColor: string;
+  let fontColor: string;
+  let borderColor: string;
+  let borderWidth: number;
+  let fontWeight: number;
+
+  if (isPrimary) {
+    backgroundColor = readString(theme, 'primaryButtonBackgroundColor', widgetBackground);
+    fontColor = readString(theme, 'primaryButtonFontColor', widgetForeground);
+    borderColor = readString(theme, 'primaryButtonBorderColor', backgroundColor);
+    borderWidth = Math.max(0, readNumber(theme, 'primaryButtonBorderWidth', 0));
+    fontWeight = readNumber(theme, 'primaryButtonFontWeight', fontWeightBold);
+  } else {
+    backgroundColor = readString(theme, 'defaultButtonBackgroundColor', mainBackground);
+    fontColor = readString(theme, 'defaultButtonFontColor', widgetBackground);
+    borderColor = readString(theme, 'defaultButtonBorderColor', fontColor);
+    borderWidth = Math.max(0, readNumber(theme, 'defaultButtonBorderWidth', 1));
+    fontWeight = readNumber(theme, 'defaultButtonFontWeight', fontWeightBold);
+  }
+
+  const paddingVertical = Math.max(0, (buttonHeight - lineHeight) / 2 - borderWidth);
+  const paddingHorizontal = fontSize;
+
+  return {
+    backgroundColor,
+    fontColor,
+    borderColor,
+    borderWidth,
+    borderRadius,
+    minWidth,
+    buttonHeight,
+    fontSize,
+    lineHeight,
+    paddingHorizontal,
+    paddingVertical,
+    fontWeight: String(fontWeight) as TextStyle['fontWeight'],
+  };
+}
+
+export function stepButtonContainerStyle(chrome: StepButtonChrome): ViewStyle {
+  return {
+    backgroundColor: chrome.backgroundColor,
+    borderColor: chrome.borderColor,
+    borderWidth: chrome.borderWidth,
+    borderRadius: chrome.borderRadius,
+    minHeight: chrome.buttonHeight,
+    paddingHorizontal: chrome.paddingHorizontal,
+    paddingTop: chrome.paddingVertical,
+    paddingBottom: chrome.paddingVertical,
+    ...(chrome.minWidth > 0 ? { minWidth: chrome.minWidth } : {}),
+  };
+}

package/src/content/themeColor.ts

@@ -0,0 +1,98 @@
+/**
+ * Color helpers for TreeDoc chrome that mirrors userflowjs bubble-frame.styl.
+ * Assumes 1rem = 16px when mapping web padding tokens to RN.
+ */
+
+/** mirrors userflowjs bubble-frame.styl blockquote border alpha */
+export const WEB_QUOTE_BORDER_ALPHA = 0.15;
+
+/** mirrors userflowjs bubble-frame.styl code background alpha */
+export const WEB_CODE_BG_ALPHA = 0.05;
+
+/** mirrors $padding-2 / $padding-4 / $padding-8 / $padding-16 (1rem = 16px) */
+export const WEB_PADDING_2 = 2;
+export const WEB_PADDING_4 = 4;
+export const WEB_PADDING_8 = 8;
+export const WEB_PADDING_16 = 16;
+
+/**
+ * Matches `styles.root.gap` in RichContentRenderer. Quote/code `marginBottom`
+ * is reduced by this so gap + margin ≈ web’s `$padding-16` (16px).
+ */
+export const ROOT_CONTENT_GAP = 8;
+
+/** mirrors calc(var(--userflow-font-size) * 0.875) */
+export const WEB_CODE_FONT_SCALE = 0.875;
+
+/** mirrors calc(var(--userflow-font-size) * 0.25) */
+export const WEB_CODE_RADIUS_SCALE = 0.25;
+
+/** mirrors var(--userflow-line-height, 24px) */
+export const WEB_LINE_HEIGHT_FALLBACK = 24;
+
+/** Neutral gray when the theme color cannot be parsed (avoids black chrome on light text). */
+const FALLBACK_FG = { r: 127, g: 127, b: 127 };
+
+export type Rgb = { r: number; g: number; b: number };
+
+function clampByte(n: number): number {
+  if (Number.isNaN(n)) return 0;
+  return Math.max(0, Math.min(255, Math.round(n)));
+}
+
+/** Exported for tests — parse theme color strings into RGB. */
+export function parseThemeRgb(color: string | null | undefined): Rgb | null {
+  if (color == null || typeof color !== 'string') return null;
+  const trimmed = color.trim();
+
+  const short = /^#([0-9a-fA-F]{3})$/.exec(trimmed);
+  if (short?.[1]) {
+    const chars = short[1].split('');
+    return {
+      r: parseInt((chars[0] ?? '0') + (chars[0] ?? '0'), 16),
+      g: parseInt((chars[1] ?? '0') + (chars[1] ?? '0'), 16),
+      b: parseInt((chars[2] ?? '0') + (chars[2] ?? '0'), 16),
+    };
+  }
+
+  // #RRGGBB or #RRGGBBAA (alpha ignored — caller supplies opacity)
+  const long = /^#([0-9a-fA-F]{6})([0-9a-fA-F]{2})?$/.exec(trimmed);
+  if (long?.[1]) {
+    const hex = long[1];
+    return {
+      r: parseInt(hex.slice(0, 2), 16),
+      g: parseInt(hex.slice(2, 4), 16),
+      b: parseInt(hex.slice(4, 6), 16),
+    };
+  }
+
+  const rgb = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)/i.exec(trimmed);
+  if (rgb) {
+    return {
+      r: clampByte(Number(rgb[1])),
+      g: clampByte(Number(rgb[2])),
+      b: clampByte(Number(rgb[3])),
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Convert a theme color to `rgba(r,g,b,a)`.
+ * Supports `#RGB`, `#RRGGBB`, `#RRGGBBAA`, `rgb()`, and `rgba()`.
+ * Falls back to neutral gray when the color cannot be parsed.
+ */
+export function foregroundAlpha(color: string | null | undefined, alpha: number): string {
+  const rgb = parseThemeRgb(color) ?? FALLBACK_FG;
+  return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${alpha})`;
+}
+
+/**
+ * Extra margin below quote/code so that with {@link ROOT_CONTENT_GAP} the
+ * visual spacing matches web `margin-bottom: $padding-16`.
+ */
+export function blockMarginBelow(isLast: boolean): number {
+  if (isLast) return 0;
+  return Math.max(0, WEB_PADDING_16 - ROOT_CONTENT_GAP);
+}