stream-chat-react-native-core 9.12.1 → 9.13.0

package/src/ai-components/generative-ui/AIUIComponentDefinition.ts

@@ -0,0 +1,163 @@
+import { isRecord } from './AIUIHelpers';
+
+/** A JSON Schema, as a component's parameters are described to the agent. */
+export type AIUIJSONSchema = Record<string, unknown>;
+
+/** Something the agent fills in for a component. */
+export type AIUIParameter = {
+  /** Whether the agent must fill it in. */
+  isRequired: boolean;
+  /** The name the agent fills it in by, such as `title`. */
+  name: string;
+  /** What it holds, as a JSON Schema, such as `AIUIParameterType.string`. */
+  type: AIUIJSONSchema;
+  /** What it is, for the agent. */
+  description?: string;
+};
+
+/** Something a component reports when the person uses it, such as tapping a place. */
+export type AIUIComponentEvent = {
+  /** When it happens, for the agent. */
+  description: string;
+  /** The name it is reported by, such as `ask_about`. */
+  name: string;
+  /** What it carries, in order. */
+  parameters: AIUIParameter[];
+};
+
+/**
+ * An app's component as the agent knows it: its name, what it shows, what the agent fills in
+ * and what it reports. It is portable JSON, the same on every platform, so one description
+ * (such as a `UIComponents.json` shared with the iOS and Android apps) serves them all.
+ */
+export type AIUIComponentDefinition = {
+  /** What it shows and when to use it, for the agent. */
+  description: string;
+  /** What it reports when the person uses it. */
+  events: AIUIComponentEvent[];
+  /** The name the agent places it by, such as `place_card`. */
+  name: string;
+  /**
+   * What the agent fills in, in order: a format such as OpenUI Lang passes arguments by
+   * position.
+   */
+  parameters: AIUIParameter[];
+};
+
+/** The types a parameter commonly has, as JSON Schemas. */
+export const AIUIParameterType = {
+  /** A list of values of one type. */
+  array: (items: AIUIJSONSchema): AIUIJSONSchema => ({ items, type: 'array' }),
+  boolean: { type: 'boolean' } as AIUIJSONSchema,
+  /** A day, such as `2026-11-14`. */
+  date: { format: 'date', type: 'string' } as AIUIJSONSchema,
+  /** A moment, such as `2026-11-14T09:30:00Z`. */
+  dateTime: { format: 'date-time', type: 'string' } as AIUIJSONSchema,
+  /** One of a fixed set of strings. */
+  enumeration: (values: string[]): AIUIJSONSchema => ({ enum: values, type: 'string' }),
+  integer: { type: 'integer' } as AIUIJSONSchema,
+  number: { type: 'number' } as AIUIJSONSchema,
+  /** An object with named fields, in order. */
+  object: (fields: AIUIParameter[]): AIUIJSONSchema => aiUIObjectSchema(fields),
+  string: { type: 'string' } as AIUIJSONSchema,
+  /** A link, such as an image's. */
+  url: { format: 'uri', type: 'string' } as AIUIJSONSchema,
+};
+
+/** A parameter the agent must fill in. */
+export const requiredAIUIParameter = (
+  name: string,
+  type: AIUIJSONSchema,
+  description?: string,
+): AIUIParameter => ({ description, isRequired: true, name, type });
+
+/** A parameter the agent may leave out. */
+export const optionalAIUIParameter = (
+  name: string,
+  type: AIUIJSONSchema,
+  description?: string,
+): AIUIParameter => ({ description, isRequired: false, name, type });
+
+// The key that keeps the order of an object's fields, which JSON objects don't have.
+const ORDER_KEY = 'x-order';
+
+const strings = (value: unknown) =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+
+/** Parameters as a JSON Schema object, the way a tool's are described, keeping their order. */
+export const aiUIObjectSchema = (parameters: AIUIParameter[]): AIUIJSONSchema => ({
+  [ORDER_KEY]: parameters.map(({ name }) => name),
+  properties: Object.fromEntries(
+    parameters.map(({ description, name, type }) => [
+      name,
+      description === undefined ? type : { ...type, description },
+    ]),
+  ),
+  required: parameters.filter(({ isRequired }) => isRequired).map(({ name }) => name),
+  type: 'object',
+});
+
+/** The fields of a JSON Schema object, in the order it keeps, then by name. */
+export const aiUIParametersOf = (schema: unknown): AIUIParameter[] => {
+  if (!isRecord(schema)) return [];
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const required = new Set(strings(schema.required));
+  const ordered = strings(schema[ORDER_KEY]).filter((name) => name in properties);
+  const rest = Object.keys(properties)
+    .filter((name) => !ordered.includes(name))
+    .sort();
+  return [...ordered, ...rest].flatMap((name) => {
+    const field = properties[name];
+    if (!isRecord(field)) return [];
+    const { description, ...type } = field;
+    return [
+      {
+        description: typeof description === 'string' ? description : undefined,
+        isRequired: required.has(name),
+        name,
+        type,
+      },
+    ];
+  });
+};
+
+/**
+ * Reads a component's portable JSON, such as one entry of a `UIComponents.json`, or returns
+ * `undefined` for one without a name.
+ */
+export const parseAIUIComponentDefinition = (
+  json: unknown,
+): AIUIComponentDefinition | undefined => {
+  if (!isRecord(json) || typeof json.name !== 'string' || json.name === '') {
+    return undefined;
+  }
+  const events = Array.isArray(json.events) ? json.events : [];
+  return {
+    description: typeof json.description === 'string' ? json.description : '',
+    events: events.flatMap((event) =>
+      isRecord(event) && typeof event.name === 'string'
+        ? [
+            {
+              description: typeof event.description === 'string' ? event.description : '',
+              name: event.name,
+              parameters: aiUIParametersOf(event.parameters),
+            },
+          ]
+        : [],
+    ),
+    name: json.name,
+    parameters: aiUIParametersOf(json.parameters),
+  };
+};
+
+/** A component's portable JSON, as `parseAIUIComponentDefinition` reads it back. */
+export const aiUIComponentDefinitionJSON = (definition: AIUIComponentDefinition) => ({
+  description: definition.description,
+  events: definition.events.map(({ description, name, parameters }) => ({
+    description,
+    name,
+    ...(parameters.length ? { parameters: aiUIObjectSchema(parameters) } : {}),
+  })),
+  name: definition.name,
+  parameters: aiUIObjectSchema(definition.parameters),
+});

package/src/ai-components/generative-ui/AIUIDocument.ts

@@ -0,0 +1,77 @@
+import { isRecord, isSameJSON } from './AIUIHelpers';
+
+/**
+ * The format a reply's UI is written in, such as `a2ui` or `openui`. Formats are an open set:
+ * a renderer says which one it reads.
+ */
+export type AIUIFormat = 'a2ui' | 'openui' | (string & {});
+
+/**
+ * The UI an agent wrote for a reply, which shows in place of the reply's text.
+ */
+export type AIUIDocument = {
+  /** The document in its format's own shape: a program's text, or JSON. */
+  content: unknown;
+  /** The format it is written in. */
+  format: AIUIFormat;
+  /** Whether the agent is still writing it. */
+  isStreaming: boolean;
+  /** The format's version, when the agent names one. */
+  version?: string;
+};
+
+/**
+ * A reply's `ai_ui` field as the agents router writes it. An app that reads it from its Stream
+ * messages types it there with `ai_ui?: AIUIDocumentJSON` in its `CustomMessageData`.
+ */
+export type AIUIDocumentJSON = {
+  /** The document in its format's own shape: usually text, such as A2UI's JSON lines. */
+  content: unknown;
+  format: AIUIFormat;
+  /** `streaming` while the agent writes it, then `complete`. */
+  status?: 'streaming' | 'complete' | (string & {});
+  /** The version of the field's own layout; a newer one than this SDK reads shows the text. */
+  v?: number;
+  version?: string;
+};
+
+/** The custom field of a message that holds its document. */
+export const AI_UI_CUSTOM_DATA_KEY = 'ai_ui';
+/** The newest version of the `ai_ui` field this SDK reads. */
+export const AI_UI_SUPPORTED_VERSION = 1;
+
+/**
+ * Reads the document of a message's `ai_ui` field, or returns `undefined` when it carries none
+ * this SDK can read: no format, no content, or a field newer than this SDK, which can lay its
+ * documents out differently. The reply then shows its text.
+ */
+export const parseAIUIDocument = (field: unknown): AIUIDocument | undefined => {
+  if (!isRecord(field)) return undefined;
+  const { content, format, status, v, version } = field;
+  if (typeof format !== 'string' || format === '') return undefined;
+  if (content === undefined || content === null) return undefined;
+  if (typeof v === 'number' && v > AI_UI_SUPPORTED_VERSION) return undefined;
+  return {
+    content,
+    format,
+    isStreaming: status === 'streaming',
+    ...(typeof version === 'string' && version !== '' ? { version } : {}),
+  };
+};
+
+/** The content of a document when it is text, such as an OpenUI program or A2UI's JSON lines. */
+export const aiUIDocumentText = (document: AIUIDocument) =>
+  typeof document.content === 'string' ? document.content : undefined;
+
+/**
+ * Whether two documents are the same, content included. A message is a new object on every
+ * update while a reply streams, so a document is compared by what it holds.
+ */
+export const isSameAIUIDocument = (a: AIUIDocument | undefined, b: AIUIDocument | undefined) =>
+  a === b ||
+  (!!a &&
+    !!b &&
+    a.format === b.format &&
+    a.version === b.version &&
+    a.isStreaming === b.isStreaming &&
+    isSameJSON(a.content, b.content));

package/src/ai-components/generative-ui/AIUIEntrance.tsx

@@ -0,0 +1,223 @@
+import React, {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { Platform, type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native';
+import Animated, {
+  Easing,
+  ReduceMotion,
+  useAnimatedStyle,
+  useSharedValue,
+  withDelay,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated';
+
+import { useReduceMotion } from '../voice-visualization/useReduceMotion';
+
+/**
+ * Spaces out the parts of a reply's UI that come in together, so they come in one after another
+ * rather than at once.
+ */
+export class AIUICascade {
+  /** How long after the part before it a part comes in, in seconds. */
+  static readonly step = 0.1;
+  /** The longest a part waits for the parts before it, in seconds. */
+  static readonly longestWait = 0.4;
+
+  private next = 0;
+
+  /** How long a part that comes in at `now`, in seconds, waits for the parts before it. */
+  delay(now = (typeof performance === 'undefined' ? Date.now() : performance.now()) / 1000) {
+    const start = Math.min(Math.max(now, this.next), now + AIUICascade.longestWait);
+    this.next = start + AIUICascade.step;
+    return start - now;
+  }
+}
+
+type AIUIStage = {
+  cascade: AIUICascade;
+  /** Whether what shows now comes in with the part around it, rather than on its own. */
+  isCarried: boolean;
+};
+
+const AIUIStageContext = createContext<AIUIStage | undefined>(undefined);
+
+// A spring with a response of 0.7 and a damping of 0.88. It settles in about as long.
+const SPRING = { dampingRatio: 0.88, duration: 700 };
+// With reduced motion a part only fades, which the system setting would otherwise skip.
+const FADE = {
+  duration: 300,
+  easing: Easing.out(Easing.ease),
+  reduceMotion: ReduceMotion.Never,
+};
+// How far a part rises into place, how small it starts, and how far out of focus.
+const RISE = 16;
+const START_SCALE = 0.97;
+const START_BLUR = 8;
+// A blur only Android 12 and later draws; elsewhere a part comes in without it.
+const CAN_BLUR = Platform.OS === 'android' && Number(Platform.Version) >= 31;
+
+// Shows its content, bringing it in after the cascade's delay when it starts hidden.
+const useEntrance = (
+  startsHidden: boolean,
+  cascade: AIUICascade | undefined,
+  resetKey?: unknown,
+) => {
+  const reduceMotion = useReduceMotion();
+  const [shownFor, setShownFor] = useState(resetKey);
+  const [hasShownState, setHasShown] = useState(!startsHidden);
+  const isReset = !Object.is(shownFor, resetKey);
+  if (isReset) {
+    setShownFor(resetKey);
+    setHasShown(!startsHidden);
+  }
+  const hasShown = isReset ? !startsHidden : hasShownState;
+  const progress = useSharedValue(startsHidden ? 0 : 1);
+  const progressFor = useRef(resetKey);
+  useLayoutEffect(() => {
+    if (Object.is(progressFor.current, resetKey)) return;
+    progressFor.current = resetKey;
+    progress.value = startsHidden ? 0 : 1;
+  });
+  useEffect(() => {
+    if (hasShown) return;
+    const delay = (cascade?.delay() ?? 0) * 1000;
+    progress.value = withDelay(delay, reduceMotion ? withTiming(1, FADE) : withSpring(1, SPRING));
+    setHasShown(true);
+  }, [cascade, hasShown, progress, reduceMotion]);
+  const style = useAnimatedStyle(() => {
+    const shown = Math.min(progress.value, 1);
+    if (reduceMotion) return { opacity: shown };
+    return {
+      opacity: shown,
+      transform: [
+        { translateY: (1 - progress.value) * RISE },
+        { scale: START_SCALE + (1 - START_SCALE) * progress.value },
+      ],
+      // Back in focus as it settles: a blur this small draws nothing.
+      ...(CAN_BLUR ? { filter: [{ blur: Math.max(0, 1 - shown) * START_BLUR }] } : {}),
+    };
+  }, [reduceMotion]);
+  return { hasShown, style };
+};
+
+/**
+ * A reply's generated UI as a whole: it comes in when it first shows while the agent writes it,
+ * and shows at once when it was written before, such as a reply from history.
+ */
+export const AIUIEntranceStage = ({
+  children,
+  isStreaming,
+  resetKey,
+  style,
+}: {
+  children: ReactNode;
+  /** Whether the agent is writing the UI as it first shows. */
+  isStreaming: boolean;
+  /**
+   * Which reply's UI it shows: when it changes, it shows the UI as one mounted for it would, as
+   * when a list reuses it for another reply.
+   */
+  resetKey?: unknown;
+  style?: StyleProp<ViewStyle>;
+}) => {
+  const [held, setHeld] = useState(() => ({
+    cascade: new AIUICascade(),
+    isLive: isStreaming,
+    resetKey,
+  }));
+  let shown = held;
+  if (!Object.is(held.resetKey, resetKey)) {
+    shown = { cascade: new AIUICascade(), isLive: isStreaming, resetKey };
+    setHeld(shown);
+  }
+  const { cascade, isLive } = shown;
+  const { hasShown, style: entrance } = useEntrance(isLive, cascade, resetKey);
+  const stage = useMemo(
+    () => ({ cascade, isCarried: !isLive || !hasShown }),
+    [cascade, hasShown, isLive],
+  );
+  return (
+    <AIUIStageContext.Provider value={stage}>
+      <Animated.View style={[styles.entrance, entrance, style]}>{children}</Animated.View>
+    </AIUIStageContext.Provider>
+  );
+};
+
+/**
+ * Whether a part of a reply's generated UI comes in, as it was when the part mounted: a part
+ * that shows at once, such as one of a reply from history, can show in a plain view.
+ */
+export const useAIUIComesIn = () => {
+  const stage = useContext(AIUIStageContext);
+  const [comesIn] = useState(() => !!stage && !stage.isCarried);
+  return comesIn;
+};
+
+/**
+ * What a part of a reply's generated UI needs to come in when it shows, for a renderer that
+ * animates a view of its own rather than wrap the part in `AIUIEntrance`: the animated `style`
+ * for that view, and `scope`, to wrap what the part shows in, so what shows with it comes in
+ * with it. The same entrance as `AIUIEntrance`'s.
+ */
+export const useAIUIEntrance = () => {
+  const stage = useContext(AIUIStageContext);
+  const { hasShown, style } = useEntrance(!!stage && !stage.isCarried, stage?.cascade);
+  const inner = useMemo(
+    () => stage && { cascade: stage.cascade, isCarried: stage.isCarried || !hasShown },
+    [hasShown, stage],
+  );
+  const scope = useMemo(
+    () => (children: ReactNode) => (
+      <AIUIStageContext.Provider value={inner}>{children}</AIUIStageContext.Provider>
+    ),
+    [inner],
+  );
+  return { scope, style: [styles.entrance, style] };
+};
+
+/**
+ * Brings a part of a reply's generated UI in when it shows, such as when the agent writes it:
+ * the part fades in, rising into place and, on Android 12 and later, coming into focus, after the
+ * parts that came in just before it. What shows together with the reply's UI, or with a part
+ * around it, comes in with that, so a reply written before it showed shows at once. With reduced
+ * motion it only fades.
+ *
+ * Renderers give it to each part they place. Every app component has it.
+ */
+export const AIUIEntrance = ({
+  children,
+  style,
+}: {
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}) => {
+  const comesIn = useAIUIComesIn();
+  return comesIn ? (
+    <EnteringPart style={style}>{children}</EnteringPart>
+  ) : (
+    <View style={[styles.entrance, style]}>{children}</View>
+  );
+};
+
+const EnteringPart = ({
+  children,
+  style,
+}: {
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}) => {
+  const { scope, style: entrance } = useAIUIEntrance();
+  return <Animated.View style={[entrance, style]}>{scope(children)}</Animated.View>;
+};
+
+const styles = StyleSheet.create({
+  entrance: { transformOrigin: 'top' },
+});

package/src/ai-components/generative-ui/AIUIErrorBoundary.tsx

@@ -0,0 +1,39 @@
+import { Component, type ReactNode } from 'react';
+
+type AIUIErrorBoundaryProps = {
+  children: ReactNode;
+  onError: (error: unknown) => void;
+  /** Tries the children again when it changes, such as when what they show changed. */
+  resetKey?: unknown;
+};
+
+type AIUIErrorBoundaryState = { hasError: boolean; resetKey: unknown };
+
+/**
+ * Keeps generated UI that throws while it renders, such as an app's component given what it
+ * didn't expect, from taking what is around it down with it. It shows nothing and says so.
+ */
+export class AIUIErrorBoundary extends Component<AIUIErrorBoundaryProps, AIUIErrorBoundaryState> {
+  state: AIUIErrorBoundaryState = { hasError: false, resetKey: this.props.resetKey };
+
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+
+  static getDerivedStateFromProps(
+    props: AIUIErrorBoundaryProps,
+    state: AIUIErrorBoundaryState,
+  ): Partial<AIUIErrorBoundaryState> | null {
+    return Object.is(props.resetKey, state.resetKey)
+      ? null
+      : { hasError: false, resetKey: props.resetKey };
+  }
+
+  componentDidCatch(error: unknown) {
+    this.props.onError(error);
+  }
+
+  render() {
+    return this.state.hasError ? null : this.props.children;
+  }
+}

package/src/ai-components/generative-ui/AIUIHelpers.ts

@@ -0,0 +1,86 @@
+// What the generated UI layer and its renderers share. Free of React and of any renderer's
+// packages.
+
+/** Whether `value` is a JSON object, rather than an array, `null` or a scalar. */
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Whether two JSON values hold the same. A message is a new object on every update while a reply
+ * streams, so what it carries is compared by value.
+ */
+export const isSameJSON = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a)) {
+    return (
+      Array.isArray(b) &&
+      a.length === b.length &&
+      a.every((item, index) => isSameJSON(item, b[index]))
+    );
+  }
+  if (!isRecord(a) || !isRecord(b)) return false;
+  const keys = Object.keys(a);
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && isSameJSON(a[key], b[key]))
+  );
+};
+
+/** How many bytes `text` takes as UTF-8, as the agent's backend counts it. */
+export const utf8ByteLength = (text: string) => {
+  let bytes = 0;
+  for (let index = 0; index < text.length; index++) {
+    const code = text.charCodeAt(index);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && index + 1 < text.length) {
+      // A surrogate pair is one character of four bytes.
+      bytes += 4;
+      index++;
+    } else bytes += 3;
+  }
+  return bytes;
+};
+
+/**
+ * The type an app's component is placed by in a format's UI, such as `PlaceCard` for
+ * `place_card`: named as A2UI's and OpenUI's own components are.
+ */
+export const aiUITypeName = (name: string) =>
+  name
+    .split(/[_\- ]/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+
+/** `text` as a sentence, ending in a full stop unless it ends otherwise. */
+export const aiUISentence = (text: string) => {
+  const trimmed = text.trim();
+  return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+};
+
+// A link's scheme, then what follows it, with no whitespace in it.
+const LINK = /^([A-Za-z][A-Za-z0-9+.-]*):(\S*)$/;
+
+const hasControlCharacter = (text: string) => {
+  for (let index = 0; index < text.length; index++) {
+    const code = text.charCodeAt(index);
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+};
+
+/**
+ * The scheme of a link from a reply's UI, in lowercase, such as `https`, or `undefined` for text
+ * that isn't one: no scheme, whitespace or control characters in it, or a web link with no host.
+ * React Native's `URL` doesn't refuse what isn't a link, so it is read here.
+ */
+export const aiUILinkScheme = (link: string): string | undefined => {
+  const trimmed = link.trim();
+  const match = hasControlCharacter(trimmed) ? null : LINK.exec(trimmed);
+  if (!match) return undefined;
+  const scheme = match[1].toLowerCase();
+  const rest = match[2];
+  if ((scheme === 'http' || scheme === 'https') && !/^\/\/[^/?#]+/.test(rest)) return undefined;
+  return scheme;
+};