@rocapine/react-native-onboarding-ui 1.32.0 → 1.34.0

package/src/UI/Pages/ComposableScreen/elements/ImageElement.tsx

@@ -1,11 +1,22 @@
 import React from "react";
 import { z } from "zod";
-import { Image, View } from "react-native";
+import { Image as RNImage, View } from "react-native";
+import { SvgUri } from "react-native-svg";
 import { BaseBoxProps, BaseBoxPropsSchema } from "./BaseBoxProps";
 import { UIElement } from "../types";
 import { RenderContext, buildShadowStyle, dim } from "./shared";
 import { GradientBox } from "./GradientBox";
 
+// expo-image decodes webp/avif reliably across platforms (RN's built-in Image is
+// flaky for webp on iOS). Optional peer dep — fall back to RN Image when absent,
+// mirroring GradientBox's expo-linear-gradient handling.
+let ExpoImage: React.ComponentType<any> | null = null;
+try {
+  ExpoImage = require("expo-image").Image;
+} catch {
+  // expo-image not installed — RN Image fallback below
+}
+
 export type ImageElementProps = BaseBoxProps & {
   url: string;
   aspectRatio?: number;
@@ -18,6 +29,39 @@ export const ImageElementPropsSchema = BaseBoxPropsSchema.extend({
   resizeMode: z.enum(["cover", "contain", "stretch", "center"]).optional(),
 });
 
+type ResizeMode = "cover" | "contain" | "stretch" | "center";
+
+// RN resizeMode → expo-image contentFit.
+const CONTENT_FIT: Record<ResizeMode, "cover" | "contain" | "fill" | "none"> = {
+  cover: "cover",
+  contain: "contain",
+  stretch: "fill",
+  center: "none",
+};
+
+// RN resizeMode → SVG preserveAspectRatio (SvgUri has no resizeMode).
+const SVG_ASPECT: Record<ResizeMode, string> = {
+  cover: "xMidYMid slice",
+  contain: "xMidYMid meet",
+  center: "xMidYMid meet",
+  stretch: "none",
+};
+
+// SVGs need react-native-svg's SvgUri — RN/expo Image can't decode SVG XML. Auto
+// -detected by file extension (query-string / hash tolerant) so existing payloads
+// with `.svg` URLs just work, no schema change.
+const isSvgUrl = (url: string): boolean =>
+  url.split(/[?#]/)[0].toLowerCase().endsWith(".svg");
+
+// Pick expo-image when installed (better webp/avif), else RN Image. resizeMode
+// passes through unchanged on RN; maps to contentFit on expo-image.
+const renderRaster = (url: string, resizeMode: ResizeMode | undefined, style: any): React.ReactElement =>
+  ExpoImage ? (
+    <ExpoImage source={url} contentFit={CONTENT_FIT[resizeMode ?? "cover"]} style={style} />
+  ) : (
+    <RNImage source={{ uri: url }} resizeMode={resizeMode} style={style} />
+  );
+
 type ImageUIElement = Extract<UIElement, { type: "Image" }>;
 
 type Props = {
@@ -27,6 +71,7 @@ type Props = {
 
 export const ImageElementComponent = ({ element }: Props): React.ReactElement => {
   const p = element.props;
+  const isSvg = isSvgUrl(p.url);
   const hasShadow = p.shadowColor != null || p.elevation != null;
   // iOS clips shadows when overflow:hidden, so a shadow-bearing Image needs a
   // wrapper View carrying the shadow (no overflow clip) and the Image inside
@@ -58,17 +103,21 @@ export const ImageElementComponent = ({ element }: Props): React.ReactElement =>
       paddingVertical: p.paddingVertical,
       ...(shadowStyle ?? {}),
     };
-    const innerImage = (
-      <Image
-        source={{ uri: p.url }}
-        resizeMode={p.resizeMode}
-        style={{
-          width: "100%",
-          height: "100%",
-          borderRadius: p.borderRadius,
-          overflow: (p.overflow ?? "hidden") as any,
-        }}
+    // Inner content fills the wrapper (which carries layout + corner clip).
+    const innerImage = isSvg ? (
+      <SvgUri
+        uri={p.url}
+        width="100%"
+        height="100%"
+        preserveAspectRatio={SVG_ASPECT[p.resizeMode ?? "contain"]}
       />
+    ) : (
+      renderRaster(p.url, p.resizeMode, {
+        width: "100%",
+        height: "100%",
+        borderRadius: p.borderRadius,
+        overflow: (p.overflow ?? "hidden") as any,
+      })
     );
     if (p.backgroundGradient) {
       return (
@@ -80,35 +129,46 @@ export const ImageElementComponent = ({ element }: Props): React.ReactElement =>
     return <View style={wrapperStyle as any}>{innerImage}</View>;
   }
 
-  return (
-    <Image
-      source={{ uri: p.url }}
-      resizeMode={p.resizeMode}
-      style={({
-        flex: p.flex,
-        flexShrink: p.flexShrink,
-        flexGrow: p.flexGrow,
-        alignSelf: p.alignSelf,
-        aspectRatio: p.aspectRatio,
-        width: dim(p.width),
-        height: dim(p.height),
-        minWidth: p.minWidth,
-        maxWidth: p.maxWidth,
-        minHeight: p.minHeight,
-        maxHeight: p.maxHeight,
-        backgroundColor: p.backgroundColor,
-        overflow: p.overflow,
-        borderRadius: p.borderRadius,
-        borderWidth: p.borderWidth,
-        borderColor: p.borderColor,
-        opacity: p.opacity,
-        margin: p.margin,
-        marginHorizontal: p.marginHorizontal,
-        marginVertical: p.marginVertical,
-        padding: p.padding,
-        paddingHorizontal: p.paddingHorizontal,
-        paddingVertical: p.paddingVertical,
-      }) as any}
-    />
-  );
+  const simpleStyle = {
+    flex: p.flex,
+    flexShrink: p.flexShrink,
+    flexGrow: p.flexGrow,
+    alignSelf: p.alignSelf,
+    aspectRatio: p.aspectRatio,
+    width: dim(p.width),
+    height: dim(p.height),
+    minWidth: p.minWidth,
+    maxWidth: p.maxWidth,
+    minHeight: p.minHeight,
+    maxHeight: p.maxHeight,
+    backgroundColor: p.backgroundColor,
+    overflow: p.overflow,
+    borderRadius: p.borderRadius,
+    borderWidth: p.borderWidth,
+    borderColor: p.borderColor,
+    opacity: p.opacity,
+    margin: p.margin,
+    marginHorizontal: p.marginHorizontal,
+    marginVertical: p.marginVertical,
+    padding: p.padding,
+    paddingHorizontal: p.paddingHorizontal,
+    paddingVertical: p.paddingVertical,
+  } as any;
+
+  // SvgUri can't carry the full RN layout style itself, so wrap it in a View that
+  // does, and let the SVG fill it.
+  if (isSvg) {
+    return (
+      <View style={simpleStyle}>
+        <SvgUri
+          uri={p.url}
+          width="100%"
+          height="100%"
+          preserveAspectRatio={SVG_ASPECT[p.resizeMode ?? "contain"]}
+        />
+      </View>
+    );
+  }
+
+  return renderRaster(p.url, p.resizeMode, simpleStyle);
 };

package/src/UI/Pages/ComposableScreen/elements/RichTextElement.tsx

@@ -0,0 +1,188 @@
+import React from "react";
+import { z } from "zod";
+import { evaluateCondition } from "@rocapine/react-native-onboarding";
+import { BaseBoxProps, BaseBoxPropsSchema } from "./BaseBoxProps";
+import { UIElement } from "../types";
+import { RenderContext, dim, interpolate, RichTextStyleContext, InheritedTextStyle } from "./shared";
+import { GradientBox } from "./GradientBox";
+
+// Mirror of the headless RichTextElement schema. Kept in lockstep with
+// packages/onboarding/src/steps/ComposableScreen/elements/RichTextElement.ts —
+// TS won't catch drift because this re-declares its own type.
+export type RichTextElementProps = BaseBoxProps & {
+  gap?: number;
+  alignItems?: "flex-start" | "center" | "flex-end" | "baseline" | "stretch";
+  justifyContent?: "flex-start" | "center" | "flex-end" | "space-between" | "space-around";
+  flexWrap?: "wrap" | "nowrap";
+  fontSize?: number;
+  fontWeight?: string;
+  fontFamily?: string | "inherit";
+  fontStyle?: "normal" | "italic";
+  color?: string;
+  textAlign?: "left" | "center" | "right";
+  letterSpacing?: number;
+  lineHeight?: number;
+};
+
+export const RichTextElementPropsSchema = BaseBoxPropsSchema.extend({
+  gap: z.number().optional(),
+  alignItems: z.enum(["flex-start", "center", "flex-end", "baseline", "stretch"]).optional(),
+  justifyContent: z.enum(["flex-start", "center", "flex-end", "space-between", "space-around"]).optional(),
+  flexWrap: z.enum(["wrap", "nowrap"]).optional(),
+  fontSize: z.number().optional(),
+  fontWeight: z.string().optional(),
+  fontFamily: z.string().optional(),
+  fontStyle: z.enum(["normal", "italic"]).optional(),
+  color: z.string().optional(),
+  textAlign: z.enum(["left", "center", "right"]).optional(),
+  letterSpacing: z.number().optional(),
+  lineHeight: z.number().optional(),
+});
+
+type RichTextUIElement = Extract<UIElement, { type: "RichText" }>;
+type TextChild = Extract<UIElement, { type: "Text" }>;
+
+type Props = {
+  element: RichTextUIElement;
+  ctx: RenderContext;
+  parentType?: "XStack" | "YStack" | "ZStack" | "RichText" | "XScroll";
+};
+
+// `textAlign` aligns text *inside* a Text box, but RichText splits each word into
+// its own shrink-wrapped flex item, so textAlign is a no-op on the row. The row's
+// horizontal distribution is governed by `justifyContent` — map textAlign onto it
+// (explicit `justifyContent` still wins) so authors get the alignment they expect.
+const ALIGN_TO_JUSTIFY = {
+  left: "flex-start",
+  center: "center",
+  right: "flex-end",
+} as const;
+
+// A plain-text child (no box styling, no motion) is split into one flex item per
+// word so the row wraps word-by-word like real text — the chip pattern from
+// host apps (parseTitleWithChips). A child carrying box styling (backgroundColor
+// / borderRadius / border / padding) or motion is a "chip" and stays atomic so
+// its box renders as a single rounded unit.
+const isFlowingText = (child: TextChild): boolean => {
+  const p = child.props;
+  return (
+    typeof p.content === "string" &&
+    p.backgroundColor == null &&
+    p.backgroundGradient == null &&
+    p.borderRadius == null &&
+    p.borderWidth == null &&
+    p.padding == null &&
+    p.paddingHorizontal == null &&
+    p.paddingVertical == null &&
+    // margin / explicit size would be applied to *every* word if split, so a
+    // child carrying any of them is treated as an atomic chip too.
+    p.margin == null &&
+    p.marginHorizontal == null &&
+    p.marginVertical == null &&
+    p.width == null &&
+    p.height == null &&
+    p.minWidth == null &&
+    p.maxWidth == null &&
+    p.minHeight == null &&
+    p.maxHeight == null &&
+    p.animation == null &&
+    p.transform == null
+  );
+};
+
+/**
+ * Wrapping flex row of child `Text` elements. Plain-text children are split into
+ * per-word flex items so text wraps word-by-word (like a paragraph); box-styled
+ * children render as atomic "chips" (padded/rounded/rotated pills) that honor
+ * their own box props, `renderWhen`, `expression`, and motion. The result is a
+ * title where chips sit inline with naturally-wrapping words.
+ *
+ * The container's text-style props are published via `RichTextStyleContext` so
+ * every child `Text` inherits them as defaults (child overrides win).
+ */
+export const RichTextElementComponent = ({ element, ctx, parentType }: Props): React.ReactElement => {
+  const p = element.props;
+
+  const inheritedTextStyle: InheritedTextStyle = {
+    fontSize: p.fontSize,
+    fontWeight: p.fontWeight,
+    fontFamily: p.fontFamily,
+    fontStyle: p.fontStyle,
+    color: p.color,
+    textAlign: p.textAlign,
+    letterSpacing: p.letterSpacing,
+    lineHeight: p.lineHeight,
+  };
+
+  // Expand children into the actual flex items to render: split flowing text into
+  // words, keep chips whole. renderWhen is evaluated once per source child here
+  // (flowing-text words then render unconditionally); chips keep their renderWhen
+  // and are gated by renderElement.
+  const flatVars = Object.fromEntries(
+    Object.entries(ctx.variables).map(([k, v]) => [k, v?.value])
+  );
+  const expanded: UIElement[] = [];
+  for (const child of element.children) {
+    if (child.renderWhen && !evaluateCondition(child.renderWhen, flatVars)) continue;
+
+    if (isFlowingText(child)) {
+      const raw = child.props.content as string;
+      const text = child.props.mode === "expression" ? interpolate(raw, ctx.variables) : raw;
+      const tokens = text.split(/(\s+)/).filter((t) => t.length > 0);
+      tokens.forEach((tok, i) => {
+        expanded.push({
+          ...child,
+          id: `${child.id}-w${i}`,
+          renderWhen: undefined,
+          // mode dropped (undefined): content is already interpolated above, and
+          // undefined is truer to the schema than the non-enum "plain".
+          props: { ...child.props, content: tok, mode: undefined },
+        });
+      });
+    } else {
+      // Chip: renderWhen already passed above; null it so renderElement doesn't
+      // re-evaluate the same condition (symmetry with the word path).
+      expanded.push({ ...child, renderWhen: undefined });
+    }
+  }
+
+  return (
+    <GradientBox
+      gradient={p.backgroundGradient}
+      style={{
+        flexDirection: "row",
+        flexWrap: p.flexWrap ?? "wrap",
+        gap: p.gap,
+        alignItems: p.alignItems ?? "center",
+        justifyContent:
+          p.justifyContent ?? (p.textAlign ? ALIGN_TO_JUSTIFY[p.textAlign] : "center"),
+        flex: p.flex,
+        flexShrink: p.flexShrink ?? (parentType === "XStack" ? 1 : undefined),
+        flexGrow: p.flexGrow,
+        alignSelf: p.alignSelf,
+        width: dim(p.width),
+        height: dim(p.height),
+        minWidth: p.minWidth,
+        maxWidth: p.maxWidth,
+        minHeight: p.minHeight,
+        maxHeight: p.maxHeight,
+        padding: p.padding,
+        paddingHorizontal: p.paddingHorizontal,
+        paddingVertical: p.paddingVertical,
+        margin: p.margin,
+        marginHorizontal: p.marginHorizontal,
+        marginVertical: p.marginVertical,
+        backgroundColor: p.backgroundGradient ? undefined : p.backgroundColor,
+        borderWidth: p.borderWidth,
+        borderRadius: p.borderRadius,
+        borderColor: p.borderColor,
+        overflow: p.overflow,
+        opacity: p.opacity,
+      }}
+    >
+      <RichTextStyleContext.Provider value={inheritedTextStyle}>
+        {ctx.renderChildren(expanded, "RichText")}
+      </RichTextStyleContext.Provider>
+    </GradientBox>
+  );
+};

package/src/UI/Pages/ComposableScreen/elements/ScrollViewElement.tsx

@@ -23,6 +23,8 @@ export type ScrollViewElementProps = BaseBoxProps & {
   contentInset?: ScrollViewContentInset;
   contentContainerPadding?: number;
   keyboardShouldPersistTaps?: "always" | "never" | "handled";
+  alignItems?: "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
+  justifyContent?: "flex-start" | "center" | "flex-end" | "space-between" | "space-around";
 };
 
 const ContentInsetSchema = z.object({
@@ -42,6 +44,8 @@ export const ScrollViewElementPropsSchema = BaseBoxPropsSchema.extend({
   contentInset: ContentInsetSchema.optional(),
   contentContainerPadding: z.number().min(0).optional(),
   keyboardShouldPersistTaps: z.enum(["always", "never", "handled"]).optional(),
+  alignItems: z.enum(["flex-start", "center", "flex-end", "stretch", "baseline"]).optional(),
+  justifyContent: z.enum(["flex-start", "center", "flex-end", "space-between", "space-around"]).optional(),
 });
 
 type ScrollViewUIElement = Extract<UIElement, { type: "ScrollView" }>;
@@ -81,8 +85,17 @@ export const ScrollViewElementComponent = ({ element, ctx }: Props): React.React
     opacity: p.opacity,
   };
 
+  // Horizontal: children must keep their intrinsic width and overflow so the row
+  // can scroll — so NO flexGrow (which would pin the content to the viewport
+  // width) and children render with parentType "XScroll" (row layout, no
+  // flexShrink default). Vertical keeps flexGrow:1 so a short payload still fills
+  // the scroll viewport. alignItems/justifyContent let authors control cross-axis
+  // alignment + distribution along the scroll axis.
   const contentContainerStyle = {
-    flexGrow: 1,
+    flexDirection: horizontal ? ("row" as const) : ("column" as const),
+    flexGrow: horizontal ? undefined : 1,
+    alignItems: p.alignItems,
+    justifyContent: p.justifyContent,
     padding: p.contentContainerPadding,
   };
 
@@ -99,7 +112,7 @@ export const ScrollViewElementComponent = ({ element, ctx }: Props): React.React
       style={hasGradient ? { flex: 1 } : containerStyle}
       contentContainerStyle={contentContainerStyle}
     >
-      {ctx.renderChildren(element.children, horizontal ? "XStack" : "YStack")}
+      {ctx.renderChildren(element.children, horizontal ? "XScroll" : "YStack")}
     </ScrollView>
   );
 

package/src/UI/Pages/ComposableScreen/elements/StackElement.tsx

@@ -24,7 +24,7 @@ type StackUIElement = Extract<UIElement, { type: "YStack" | "XStack" }>;
 type Props = {
   element: StackUIElement;
   ctx: RenderContext;
-  parentType?: "XStack" | "YStack" | "ZStack";
+  parentType?: "XStack" | "YStack" | "ZStack" | "RichText" | "XScroll";
 };
 
 export const StackElementComponent = ({ element, ctx, parentType }: Props): React.ReactElement => {

package/src/UI/Pages/ComposableScreen/elements/TextElement.tsx

@@ -4,7 +4,7 @@ import { Text } from "react-native";
 import { useResolvedFontStyle } from "@rocapine/react-native-onboarding";
 import { BaseBoxProps, BaseBoxPropsSchema } from "./BaseBoxProps";
 import { UIElement } from "../types";
-import { RenderContext, interpolate, dim, resolveInheritedFontFamily } from "./shared";
+import { RenderContext, interpolate, dim, resolveInheritedFontFamily, RichTextStyleContext } from "./shared";
 import { GradientBox } from "./GradientBox";
 
 export type TextSpan = {
@@ -118,12 +118,22 @@ type TextUIElement = Extract<UIElement, { type: "Text" }>;
 type Props = {
   element: TextUIElement;
   ctx: RenderContext;
-  parentType?: "XStack" | "YStack" | "ZStack";
+  parentType?: "XStack" | "YStack" | "ZStack" | "RichText" | "XScroll";
 };
 
 export const TextElementComponent = ({ element, ctx, parentType }: Props): React.ReactElement => {
   const { theme, variables } = ctx;
   const p = element.props;
+  // Text-style defaults inherited from a parent `RichText` container (empty when
+  // this Text isn't inside one). Element props always win over inherited values.
+  const inherited = React.useContext(RichTextStyleContext);
+  const fontSize = p.fontSize ?? inherited.fontSize;
+  const fontWeight = p.fontWeight ?? inherited.fontWeight;
+  const fontStyle = p.fontStyle ?? inherited.fontStyle;
+  const color = p.color ?? inherited.color;
+  const textAlign = p.textAlign ?? inherited.textAlign;
+  const letterSpacing = p.letterSpacing ?? inherited.letterSpacing;
+  const lineHeight = p.lineHeight ?? inherited.lineHeight;
   const isExpression = p.mode === "expression";
   const content: string | TextSpan[] = Array.isArray(p.content)
     ? isExpression
@@ -133,10 +143,10 @@ export const TextElementComponent = ({ element, ctx, parentType }: Props): React
       ? interpolate(p.content, variables)
       : p.content;
   const inheritedFontFamily = resolveInheritedFontFamily(
-    p.fontFamily,
+    p.fontFamily ?? inherited.fontFamily,
     theme.typography.defaultFontFamily
   );
-  const resolvedFont = useResolvedFontStyle(inheritedFontFamily, p.fontWeight);
+  const resolvedFont = useResolvedFontStyle(inheritedFontFamily, fontWeight);
 
   const textNode = (
     <Text
@@ -151,14 +161,14 @@ export const TextElementComponent = ({ element, ctx, parentType }: Props): React
         maxWidth: p.backgroundGradient ? undefined : p.maxWidth,
         minHeight: p.backgroundGradient ? undefined : p.minHeight,
         maxHeight: p.backgroundGradient ? undefined : p.maxHeight,
-        fontSize: p.fontSize,
-        fontWeight: resolvedFont.resolvedToVariant ? undefined : (p.fontWeight as any),
+        fontSize,
+        fontWeight: resolvedFont.resolvedToVariant ? undefined : (fontWeight as any),
         fontFamily: resolvedFont.fontFamily,
-        fontStyle: p.fontStyle,
-        color: p.color ?? theme.colors.text.primary,
-        textAlign: p.textAlign,
-        letterSpacing: p.letterSpacing,
-        lineHeight: p.lineHeight,
+        fontStyle,
+        color: color ?? theme.colors.text.primary,
+        textAlign,
+        letterSpacing,
+        lineHeight,
         backgroundColor: p.backgroundGradient ? undefined : p.backgroundColor,
         padding: p.backgroundGradient ? undefined : p.padding,
         paddingHorizontal: p.backgroundGradient ? undefined : p.paddingHorizontal,

package/src/UI/Pages/ComposableScreen/elements/renderElement.tsx

@@ -5,6 +5,7 @@ import { BaseBoxProps } from "./BaseBoxProps";
 import { RenderContext } from "./shared";
 import { StackElementComponent } from "./StackElement";
 import { TextElementComponent } from "./TextElement";
+import { RichTextElementComponent } from "./RichTextElement";
 import { ImageElementComponent } from "./ImageElement";
 import { LottieElementComponent } from "./LottieElement";
 import { RiveElementRenderer } from "./RiveElement";
@@ -27,7 +28,7 @@ import { AnimatedBox } from "./AnimatedBox";
 export const renderElement = (
   element: UIElement,
   ctx: RenderContext,
-  parentType?: "XStack" | "YStack" | "ZStack"
+  parentType?: "XStack" | "YStack" | "ZStack" | "RichText" | "XScroll"
 ): React.ReactNode => {
   if (element.renderWhen) {
     const flatVars = Object.fromEntries(
@@ -47,6 +48,10 @@ export const renderElement = (
     return <TextElementComponent key={element.id} element={element} ctx={ctx} parentType={parentType} />;
   }
 
+  if (element.type === "RichText") {
+    return <RichTextElementComponent key={element.id} element={element} ctx={ctx} parentType={parentType} />;
+  }
+
   if (element.type === "Image") {
     return <ImageElementComponent key={element.id} element={element} ctx={ctx} />;
   }

package/src/UI/Pages/ComposableScreen/elements/shared.ts

@@ -11,9 +11,27 @@ export type RenderContext = {
   setVariable: (key: string, entry: ComposableVariableEntry) => void;
   onContinue: () => void;
   customActions: CustomActions;
-  renderChildren: (elements: UIElement[], parentType: "XStack" | "YStack" | "ZStack") => React.ReactNode;
+  renderChildren: (elements: UIElement[], parentType: "XStack" | "YStack" | "ZStack" | "RichText" | "XScroll") => React.ReactNode;
 };
 
+// Text-style defaults a `RichText` container hands down to its child `Text`
+// elements. A `<View>` doesn't propagate text style to nested `<Text>`, so the
+// RichText renderer publishes these via context and `TextElementComponent`
+// merges them under its own props (child always wins). Empty default ({}) means
+// Text elements outside a RichText behave unchanged.
+export type InheritedTextStyle = {
+  fontSize?: number;
+  fontWeight?: string;
+  fontFamily?: string | "inherit";
+  fontStyle?: "normal" | "italic";
+  color?: string;
+  textAlign?: "left" | "center" | "right";
+  letterSpacing?: number;
+  lineHeight?: number;
+};
+
+export const RichTextStyleContext = React.createContext<InheritedTextStyle>({});
+
 export const interpolate = (template: string, variables: Record<string, ComposableVariableEntry>): string =>
   template.replace(/\{\{([^}]+?)\}\}/g, (_, key) => variables[key]?.label ?? variables[key]?.value ?? "");
 

package/src/UI/Pages/ComposableScreen/types.ts

@@ -10,6 +10,7 @@ import {
 import { CustomPayloadSchema } from "../types";
 import { type StackElementProps, StackElementPropsSchema } from "./elements/StackElement";
 import { type TextElementProps, TextElementPropsSchema } from "./elements/TextElement";
+import { type RichTextElementProps, RichTextElementPropsSchema } from "./elements/RichTextElement";
 import { type ImageElementProps, ImageElementPropsSchema } from "./elements/ImageElement";
 import { type LottieElementProps, LottieElementPropsSchema } from "./elements/LottieElement";
 import { type RiveElementProps, RiveElementPropsSchema } from "./elements/RiveElement";
@@ -37,6 +38,7 @@ export type { BaseBoxProps } from "./elements/BaseBoxProps";
 export { BaseBoxPropsSchema } from "./elements/BaseBoxProps";
 export type { StackElementProps } from "./elements/StackElement";
 export type { TextElementProps } from "./elements/TextElement";
+export type { RichTextElementProps } from "./elements/RichTextElement";
 export type { ImageElementProps } from "./elements/ImageElement";
 export type { LottieElementProps } from "./elements/LottieElement";
 export type { RiveElementProps } from "./elements/RiveElement";
@@ -76,6 +78,14 @@ export type UIElement =
       type: "Text";
       props: TextElementProps;
     }
+  | {
+      id: string;
+      name?: string;
+      renderWhen?: LeafCondition | ConditionGroup;
+      type: "RichText";
+      props: RichTextElementProps;
+      children: Array<Extract<UIElement, { type: "Text" }>>;
+    }
   | {
       id: string;
       name?: string;
@@ -201,6 +211,17 @@ export type UIElement =
       props: ProgressIndicatorElementProps;
     };
 
+// The `Text` variant, extracted so `RichText` can restrict its children to
+// Text-only (children: z.array(TextUIElementSchema)) while the union references
+// the same object.
+const TextUIElementSchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  renderWhen: z.union([LeafConditionSchema, ConditionGroupSchema]).optional(),
+  type: z.literal("Text"),
+  props: TextElementPropsSchema,
+});
+
 export const UIElementSchema: z.ZodType<UIElement> = z.lazy(() =>
   z.union([
     z.object({
@@ -211,12 +232,14 @@ export const UIElementSchema: z.ZodType<UIElement> = z.lazy(() =>
       props: StackElementPropsSchema,
       children: z.array(UIElementSchema),
     }),
+    TextUIElementSchema,
     z.object({
       id: z.string(),
       name: z.string().optional(),
       renderWhen: z.union([LeafConditionSchema, ConditionGroupSchema]).optional(),
-      type: z.literal("Text"),
-      props: TextElementPropsSchema,
+      type: z.literal("RichText"),
+      props: RichTextElementPropsSchema,
+      children: z.array(TextUIElementSchema),
     }),
     z.object({
       id: z.string(),