stream-chat-react-native-core 10.0.0-rc.1 → 10.0.0-rc.2

package/src/store/apis/queries/selectReactionsForMessages.ts

@@ -5,11 +5,14 @@ import { SqliteClient } from '../../SqliteClient';
 import type { Scalar, TableRowJoinedUser } from '../../types';
 
 /**
- * Fetches reactions for a message from the database for messageIds.
- * @param messageIds The message IDs for which reactions are to be fetched.
- * @param limit The limit of how many reactions should be returned.
- * @param filters A ReactionFilter for the reactions we want to fetch. Only type is currently supported.
- * @param sort A sort for reactions to be used when querying. Custom data is currently not supported for sorting.
+ * Fetches the reactions of the given messages. Only the `type` filter and sorting by `created_at`
+ * are supported.
+ *
+ * @param messageIds The IDs of the messages to fetch reactions for.
+ * @param limit Maximum number of reactions to return, or `null` for no limit. Defaults to 25.
+ * @param filters Reaction filters. Only `type` is supported.
+ * @param sort Reaction sort. Only `created_at` is supported.
+ * @returns The reactions joined with their users.
  */
 export const selectReactionsForMessages = async (
   messageIds: string[],

package/src/store/apis/upsertChannels.ts

@@ -21,7 +21,6 @@ export const upsertChannels = async ({
   execute?: boolean;
   isLatestMessagesSet?: boolean;
 }) => {
-  // Update the database only if the query is provided.
   let queries: PreparedQueries[] = [];
 
   const channelIds = channels.map((channel) => channel.channel?.cid);
@@ -42,7 +41,7 @@ export const upsertChannels = async ({
       membership &&
       !members.some((m: ChannelMemberResponse) => m.user?.id === membership.user?.id)
     ) {
-      members.push({ ...membership, user_id: membership.user?.id });
+      members.push({ ...membership, user_id: membership.user?.id ?? membership.user_id });
     }
 
     if (active_live_locations && active_live_locations.length > 0) {

package/src/store/apis/upsertCidsForQuery.ts

@@ -25,7 +25,6 @@ export const upsertCidsForQuery = async ({
   predefinedFilter?: ParsedPredefinedFilterResponse;
   sort?: SortParamRequest[];
 }) => {
-  // Update the database only if the query is provided.
   const cidsString = JSON.stringify(cids);
   const id = convertFilterSortToQuery({ filters, options, sort });
   const predefinedFilterString = predefinedFilter ? JSON.stringify(predefinedFilter) : null;

package/src/store/apis/upsertDraft.ts

@@ -19,7 +19,7 @@ export const upsertDraft = async ({
   const queries: PreparedQueries[] = [];
   const { channel_cid, parent_id, message } = draft;
 
-  // Delete existing draft message if it exists.
+  // Deletes any existing draft of the same channel and parent first.
   const deleteQuery = createDeleteQuery('draft', {
     cid: channel_cid,
     parentId: parent_id,
@@ -27,7 +27,7 @@ export const upsertDraft = async ({
 
   queries.push(deleteQuery);
 
-  // Important: Make sure you create a draft only after a draft message is created.
+  // The draft row references the draft message, so the message is queued first.
   const storableDraftMessage = mapDraftMessageToStorable({ draftMessage: message });
 
   queries.push(createUpsertQuery('draftMessage', storableDraftMessage));
@@ -51,8 +51,7 @@ export const upsertDraft = async ({
   }
 
   if (messagesToUpsert.length > 0) {
-    const query = await upsertMessages({ execute: false, messages: messagesToUpsert });
-    queries.concat(query);
+    queries.push(...(await upsertMessages({ execute: false, messages: messagesToUpsert })));
   }
 
   if (execute) {

package/src/store/constants.ts

@@ -2,10 +2,5 @@ export const DB_NAME = 'stream-chat-react-native';
 export const DB_LOCATION = 'databases';
 export const DB_STATUS_ERROR = 1;
 
-/**
- * Default value for the `maxSyncEventsLimit` prop on `Chat`. Chosen conservatively
- * and below the backend hard cap; tune with performance data. The underlying LLC
- * (`stream-chat`) has no default of its own, this default is implied purely by the
- * RN SDK.
- */
+/** Default for the `maxSyncEventsLimit` prop on `Chat`, below the server's hard cap. */
 export const DEFAULT_MAX_SYNC_EVENTS_LIMIT = 250;

package/src/store/mappers/mapPollToStorable.ts

@@ -33,7 +33,7 @@ export const mapPollToStorable = (poll: PollResponseData): TableRow<'poll'> => {
     allow_user_suggested_options,
     answers_count,
     created_at: mapTimestampToStorable(created_at),
-    created_by: JSON.stringify(created_by), // decouple the users from the actual poll
+    created_by: JSON.stringify(created_by), // stored as JSON to decouple the user from the poll
     created_by_id,
     description,
     enforce_unique_vote,

package/src/store/mappers/mapReadToStorable.ts

@@ -24,7 +24,7 @@ export const mapReadToStorable = ({
     cid,
     lastDeliveredAt: mapTimestampToStorable(last_delivered_at),
     lastDeliveredMessageId: last_delivered_message_id,
-    // `0` is the LLC's epoch sentinel; the column is `INTEGER NOT NULL`.
+    // `0` is the epoch sentinel of `stream-chat`; the column is `INTEGER NOT NULL`.
     lastRead: last_read ?? 0,
     lastReadMessageId: last_read_message_id,
     unreadMessages: unread_messages,

package/src/store/mappers/mapStorableToMember.ts

@@ -41,6 +41,6 @@ export const mapStorableToMember = (
     shadow_banned: Boolean(shadowBanned),
     updated_at: mapStorableToRequiredTimestamp(updatedAt),
     user: mapStorableToUser(user),
-    user_id: userId,
+    user_id: userId ?? user.id,
   };
 };

package/src/store/mappers/mapStorableToPoll.ts

@@ -49,9 +49,8 @@ export const mapStorableToPoll = (pollRow: TableRow<'poll'>): PollResponseData =
     updated_at: mapStorableToRequiredTimestamp(updated_at),
     vote_count,
     vote_counts_by_option: JSON.parse(vote_counts_by_option),
-    // `voting_visibility` is `'anonymous' | 'public'` on the response, and the column is TEXT.
-    // The `?? ''` fallback was never a valid value — it only compiled because the date fields on
-    // this same object literal were already failing and masking it. Default to the API's default.
+    // The column is TEXT, while the response type is `'anonymous' | 'public'`. A missing value
+    // falls back to the API default.
     voting_visibility: (voting_visibility as PollResponseData['voting_visibility']) ?? 'public',
   };
 };

package/src/store/mappers/mapStorableToTimestamp.ts

@@ -2,23 +2,19 @@ import { asTimestampNS } from 'stream-chat';
 import type { TimestampNS } from 'stream-chat';
 
 /**
- * A timestamp on its way *out of* SQLite. The inverse of `mapTimestampToStorable`, and equally
- * conversion-free: the column already holds the unix-nanosecond number every response and event
- * field carries, so it is branded as a `TimestampNS` without being converted.
+ * Brands a stored unix-nanosecond column as a `TimestampNS` without converting it (the inverse of
+ * `mapTimestampToStorable`), and maps SQLite's `null` for an absent timestamp to `undefined`.
  *
- * It exists for the one thing SQLite and the response types disagree about — SQLite says `null`
- * for an absent timestamp, the generated types say `undefined`.
- *
- * Every date column is nullable, so use {@link mapStorableToRequiredTimestamp} for a field the model
- * declares required (`created_at` / `updated_at`). The compiler cannot catch a miss in a mapper whose
- * literal ends with `...JSON.parse(extraData)` — spreading `any` disables the check.
+ * Every date column is nullable, so use {@link mapStorableToRequiredTimestamp} for fields the model
+ * declares required (`created_at`, `updated_at`). The compiler cannot catch a miss in a mapper
+ * whose literal ends with `...JSON.parse(extraData)`, because spreading `any` disables the check.
  */
 export const mapStorableToTimestamp = (timestamp?: number | null): TimestampNS | undefined =>
   timestamp == null ? undefined : asTimestampNS(timestamp);
 
 /**
  * {@link mapStorableToTimestamp} for a field the model declares required: an absent column reads
- * back as the epoch, which every "no timestamp" consumer already treats as nothing having happened.
+ * back as the epoch, which consumers treat as no timestamp.
  */
 export const mapStorableToRequiredTimestamp = (timestamp?: number | null): TimestampNS =>
   mapStorableToTimestamp(timestamp) ?? asTimestampNS(0);

package/src/store/mappers/mapTimestampToStorable.ts

@@ -1,14 +1,9 @@
 /**
- * A timestamp on its way *into* SQLite. Unix nanoseconds in, unix nanoseconds out — every date
- * column is `INTEGER` holding exactly what the API put on the wire, so there is no conversion here.
- * Lossless relative to what JavaScript holds: `JSON.parse` already quantised the value to the
- * nearest double (~256 ns) before SQLite saw it.
+ * Stores a unix-nanosecond timestamp in its `INTEGER` column unchanged, mapping `undefined` to
+ * `null`. Nothing is lost: `JSON.parse` already rounded the value to the nearest double (~256 ns).
  *
- * The only thing this function does is pick `null` over `undefined`, and that choice is
- * load-bearing rather than stylistic: `upsertStatementParts` omits `undefined` values from the
- * column list, so an absent date on an upsert-**update** would silently keep whatever was
- * already stored. Writing an explicit `null` clears it, which is what the previous ISO mapper
- * did by returning `''`.
+ * The `null` matters: `upsertStatementParts` omits `undefined` values from the column list, so an
+ * absent date on an upsert-update would keep the stored value rather than clear it.
  */
 export const mapTimestampToStorable = (timestamp?: number | null): number | null =>
   timestamp ?? null;

package/src/store/schema.ts

@@ -348,10 +348,7 @@ export type Schema = {
   channelQueries: {
     cids: string;
     id: string;
-    /**
-     * The backend-resolved `predefined_filter` metadata this cid order was produced by, as JSON.
-     * Null for a plain `filter_conditions` query.
-     */
+    /** JSON of the server-resolved `predefined_filter` this CID order came from; null otherwise. */
     predefinedFilter?: string | null;
   };
   channels: {

package/src/store/sqlite-utils/createDeleteQuery.ts

@@ -4,13 +4,12 @@ import type { Schema } from '../schema';
 import type { PreparedQueries, TableColumnNames, TableColumnValue } from '../types';
 
 /**
- * Creates a simple delete query for sqlite.
+ * Creates a prepared `DELETE` query. In `whereCondition` an array value matches with `IN`, a key
+ * with an `undefined` value is skipped, and the conditions are joined with AND.
  *
- * @param {string} table Table name
- * @param {Object} whereCondition Where condition for select query.
- *  e.g., { id: 'vishal', cid: ['messaging:id1', 'messaging:id2'] }.
- *  All the conditions will be joined with AND in final query.
- * @returns {string} Final select query
+ * @param table The table name.
+ * @param whereCondition Column values to match, for example `{ id: 'a', cid: ['b', 'c'] }`.
+ * @returns The prepared query as `[sql, params]`.
  */
 
 export const createDeleteQuery = <T extends keyof Schema>(

package/src/store/sqlite-utils/createSelectQuery.ts

@@ -5,14 +5,15 @@ import type { Schema } from '../schema';
 import type { PreparedQueries, TableColumnNames, TableColumnValue } from '../types';
 
 /**
- * Creates a simple select query for sqlite.
+ * Creates a prepared `SELECT` query for `fields` (defaults to `['*']`). In `whereCondition` an
+ * array value matches with `IN`, a key with an `undefined` value is skipped, and the conditions are
+ * joined with AND.
  *
- * @param {string} table Table name
- * @param {Array} fields Array of columns which need to be selected e.g., ['*'] or ['id', 'name']
- * @param {Object} whereCondition Where condition for select query.
- *  e.g., { id: 'vishal', cid: ['messaging:id1', 'messaging:id2'] }.
- *  All the conditions will be joined with AND in final query.
- * @returns {string} Final select query
+ * @param table The table name.
+ * @param fields The columns to select. Defaults to `['*']`.
+ * @param whereCondition Column values to match, for example `{ id: 'a', cid: ['b', 'c'] }`.
+ * @param orderBy Column sort directions, `1` for ascending and `-1` for descending.
+ * @returns The prepared query as `[sql, params]`.
  */
 export const createSelectQuery = <T extends keyof Schema>(
   table: T,

package/src/store/sqlite-utils/createUpdateQuery.ts

@@ -4,14 +4,14 @@ import type { Schema } from '../schema';
 import type { PreparedQueries, TableColumnNames, TableColumnValue, TableRow } from '../types';
 
 /**
- * Creates a simple update query for sqlite.
+ * Creates a prepared `UPDATE OR IGNORE` query that sets the columns in `set`. In `whereCondition`
+ * an array value matches with `IN`, a key with an `undefined` value is skipped, and the conditions
+ * are joined with AND.
  *
- * @param {string} table Table name
- * @param {Object} set Set conditions for update query.
- * @param {Object} whereCondition Where condition for select query.
- *  e.g., { id: 'vishal', cid: ['messaging:id1', 'messaging:id2'] }.
- *  All the conditions will be joined with AND in final query.
- * @returns {string} Final update query for sqlite
+ * @param table The table name.
+ * @param set The column values to write.
+ * @param whereCondition Column values to match, for example `{ id: 'a', cid: ['b', 'c'] }`.
+ * @returns The prepared query as `[sql, params]`.
  */
 export const createUpdateQuery = <T extends keyof Schema>(
   table: T,

package/src/store/sqlite-utils/createUpsertQuery.ts

@@ -2,9 +2,8 @@ import { Schema, tables } from '../schema';
 import type { PreparedQueries, TableColumnNames, TableRow } from '../types';
 
 /**
- * The pieces every upsert statement is built from, shared with
- * {@link import('./createUpsertQueryIfParentExists').createUpsertQueryIfParentExists} so the two
- * forms cannot drift in how they filter columns or resolve conflict keys.
+ * The pieces every upsert statement is built from, shared with `createUpsertQueryIfParentExists` so
+ * both filter columns and resolve conflict keys the same way.
  *
  * @internal
  */
@@ -15,12 +14,9 @@ export const upsertStatementParts = <T extends keyof Schema>(
 ) => {
   const filteredRow: typeof row = {};
 
-  // In case of "DO UPDATE SET", we only want to update the properties which
-  // are provided, and not set undefined properties in database.
-  // E.g., channel date such as `own_capabilities` is only available in response of client.queryChannels or channel.query.
-  // But its not available in `event.channel`. And our mapper functions such as mapChannelToStorable will set fields which are not available as undefined.
-  // So when you execute upsert query for storable value of `event.channel` in `channels` table, it will
-  // unset ownCapabilities field for that channel in `channels` table.
+  // `DO UPDATE SET` only updates the provided properties. Mappers set unavailable fields to
+  // `undefined` (`own_capabilities` is missing from `event.channel`, for example), and writing
+  // those would clear the stored values.
   for (const key in row) {
     if (row[key] !== undefined) {
       filteredRow[key] = row[key];
@@ -49,12 +45,13 @@ export const upsertStatementParts = <T extends keyof Schema>(
 };
 
 /**
- * Creates a simple upsert query for sqlite.
+ * Creates a prepared upsert query. Conflicts are checked on `conflictCheckKeys`, defaulting to the
+ * primary key (https://www.sqlite.org/lang_UPSERT.html). `undefined` row values are left out.
  *
- * @param {string} table Table name
- * @param {Object} row Table row to insert or update.
- * @param {Array} conflictCheckKeys Custom list of columns to check conflicts for - https://www.sqlite.org/lang_UPSERT.html. By default conflicts are checked on primary keys.
- * @returns {string} Final upsert query for sqlite
+ * @param table The table name.
+ * @param row The table row to insert or update.
+ * @param conflictCheckKeys The columns to check conflicts on. Defaults to the primary key.
+ * @returns The prepared query as `[sql, params]`.
  */
 export const createUpsertQuery = <T extends keyof Schema>(
   table: T,

package/src/store/sqlite-utils/createUpsertQueryIfParentExists.ts

@@ -3,9 +3,7 @@ import { upsertStatementParts } from './createUpsertQuery';
 import { Schema } from '../schema';
 import type { PreparedQueries, TableColumnNames, TableRow } from '../types';
 
-/**
- * The row this write depends on - the parent side of a foreign key declared in {@link Schema}.
- */
+/** The row this write depends on: the parent side of a foreign key declared in {@link Schema}. */
 type ParentRow = {
   column: string;
   table: keyof Schema;
@@ -13,31 +11,23 @@ type ParentRow = {
 };
 
 /**
- * An upsert that writes nothing at all when the row it references is absent.
- *
- * Deliberately NOT an option on `createUpsertQuery`: "insert or update" is a contract worth keeping
- * exact, and this is a third thing - "insert or update, or do nothing" - so it says so in its name
- * rather than hiding behind a flag.
- *
- * For the tables whose schema declares a foreign key. Only part of a channel's messages are ever
- * cached, so a child row can genuinely arrive for a parent this database has never held - a reaction
- * on an old message, say. SQLite rejects that child, and since these queries are executed as one
- * batch, the one rejected statement aborts every unrelated write alongside it.
+ * An upsert that writes nothing when the parent row it references is absent. Conflicts are checked
+ * on `conflictCheckKeys`, defaulting to the primary key.
  *
- * Skipping is the honest outcome rather than the lesser evil: these tables mirror what is held
- * locally, so a child with no parent has nothing to hang off, and it comes back on its own once the
- * parent is cached (a message arrives carrying its own reactions).
+ * It is separate from `createUpsertQuery` so that function stays a plain "insert or update". Only
+ * part of a channel's messages is cached, so a child row (a reaction, say) can arrive for a parent
+ * the database never held. SQLite rejects it, and as queries run in one batch, that aborts every
+ * unrelated write alongside it. Skipping it is correct: the child returns with its parent once that
+ * is cached.
  *
- * Expressed as `WHERE EXISTS` inside the statement rather than as a separate probe so it costs no
- * extra round trip and cannot race with the write it guards - and the lookup it does is the same
- * index lookup the foreign key already forces on every insert. SQLite requires that `WHERE` when an
- * `INSERT ... SELECT` is followed by `ON CONFLICT`, so the clause doing the guarding is also what
- * keeps the upsert unambiguous.
+ * The check is a `WHERE EXISTS` inside the statement, so it costs no round trip and cannot race the
+ * write. SQLite requires that `WHERE` when `INSERT ... SELECT` is followed by `ON CONFLICT`.
  *
- * @param table Table name.
- * @param row Table row to insert or update.
+ * @param table The table name.
+ * @param row The table row to insert or update.
  * @param parent The row that must exist for anything to be written.
- * @param conflictCheckKeys Custom list of columns to check conflicts for. Defaults to primary keys.
+ * @param conflictCheckKeys The columns to check conflicts on. Defaults to the primary key.
+ * @returns The prepared query as `[sql, params]`.
  */
 export const createUpsertQueryIfParentExists = <T extends keyof Schema>(
   table: T,

package/src/theme/topologicalResolution.ts

@@ -5,14 +5,16 @@ const isPlainObject = (value: unknown): value is Record<string, unknown> => {
 };
 
 /**
- * Resolves "$token" references in `dictionary` by performing a DFS.
- * deps first, then node - i.e. a topological evaluation.
+ * Resolves `$token` references in `dictionary` depth first, dependencies before the token that uses
+ * them, so declaration order does not matter. Throws on a cycle or an unresolved reference.
+ *
+ * @param dictionary The semantic tokens, whose values may reference other tokens as `$token`.
+ * @returns The dictionary with every reference resolved.
  */
 export const resolveTokensTopologically = <T extends Theme['semantics']>(dictionary: T): T => {
   const resolvedMemo = new Map<string, unknown>();
 
-  // Used purely for cycle detection (even though we do not expect
-  // cycles we want to assert early to make sure we raise an alarm).
+  // Cycle detection: none are expected, but a cycle must fail loudly.
   const visiting = new Set<string>();
 
   const resolveValueDeep = (value: unknown): unknown => {
@@ -31,11 +33,7 @@ export const resolveTokensTopologically = <T extends Theme['semantics']>(diction
     return value;
   };
 
-  /**
-   * This is the topological sort part:
-   * - DFS into dependencies first
-   * - then memoize the current token
-   */
+  /** Resolves a token's dependencies first, then memoizes the token. */
   const dfs = (tokenKeyOrPath: string, originalRef: string): unknown => {
     const cacheKey = tokenKeyOrPath;
 
@@ -50,13 +48,10 @@ export const resolveTokensTopologically = <T extends Theme['semantics']>(diction
     const raw = dictionary[tokenKeyOrPath as keyof Theme['semantics']];
 
     if (raw === undefined) {
-      // is throwing maybe too strict here ?
       throw new Error(`Unresolved reference: "${originalRef}" (missing "${tokenKeyOrPath}")`);
     }
 
-    // resolve dependencies inside `raw` BEFORE finalizing this token
-    // so that we can throw if there's a cycle or the dep graph is not
-    // connected)
+    // Dependencies resolve before the token is memoized, so a cycle or a missing reference throws.
     const fullyResolved = resolveValueDeep(raw);
 
     resolvedMemo.set(cacheKey, fullyResolved);

package/src/types/react-native-compat.ts

@@ -10,20 +10,10 @@ import type {
 } from 'react-native';
 
 /**
- * Portable React Native ref (host instance) types.
- *
- * React Native 0.87 made the Strict TypeScript API the default. Under it the core components are
- * function components rather than classes, so a component type is no longer usable as its own ref
- * type - `useRef<View>(null)` no longer type checks against `<View ref={...} />`. React Native now
- * publishes dedicated instance types (`ViewInstance`, `TextInputInstance`, ...) instead.
- *
- * Those `*Instance` types do not exist on React Native < 0.87 and this SDK supports `>=0.79`, so we
- * cannot import them directly. `React.ComponentRef<typeof X>` resolves to the correct instance type
- * on *both* type generations - it is exactly how React Native itself defines `ViewInstance` and
- * friends internally - so it is the portable spelling and the one to use throughout the SDK.
- *
- * When the SDK's minimum supported React Native reaches 0.87, these aliases can be swapped for the
- * upstream `*Instance` types in a single edit.
+ * Portable React Native ref (host instance) types. From React Native 0.87 the core components are
+ * function components, so a component type cannot double as its ref type, and the `ViewInstance`
+ * family of instance types is absent before 0.87 (the SDK supports `>=0.79`).
+ * `React.ComponentRef<typeof X>` resolves to the right instance type on both.
  */
 
 export type ViewRef = React.ComponentRef<typeof View>;
@@ -33,23 +23,17 @@ export type ScrollViewRef = React.ComponentRef<typeof ScrollView>;
 export type FlatListRef<ItemT = unknown> = React.ComponentRef<typeof FlatList<ItemT>>;
 export type SectionListRef<ItemT = unknown> = React.ComponentRef<typeof SectionList<ItemT>>;
 
-/**
- * `KeyboardEventListener` was dropped from React Native's root type exports in 0.87. It was only ever
- * an alias for a handler taking a `KeyboardEvent`, so we re-declare it here rather than deep importing.
- */
+/** Handler for a `KeyboardEvent`. Declared here because React Native 0.87+ does not export it. */
 export type KeyboardEventListener = (event: KeyboardEvent) => void;
 
 /**
- * `ViewToken` and `ViewabilityConfig` are no longer exported from the `react-native` root under the
- * Strict TypeScript API - `ViewToken` moved to `@react-native/virtualized-lists` (re-exported from
- * the root as `ListViewToken`) and `ViewabilityConfig` is no longer re-exported at all. Both appear
- * in this SDK's public message list surface, and neither spelling exists across the whole `>=0.79`
- * range, so we declare them structurally. The shapes are stable and shared by `FlatList` and
- * `@shopify/flash-list`.
+ * Structural `ViewToken` and `ViewabilityConfig`, which appear in the public message list surface.
+ * The `react-native` root exports them differently across `>=0.79` (under the Strict TypeScript API
+ * `ViewToken` is `ListViewToken` and `ViewabilityConfig` is not exported), and `FlatList` and
+ * `@shopify/flash-list` share the shapes.
  *
- * `index` is deliberately widened to `number | null | undefined`: React Native typed it `number | null`
- * up to 0.86 and `number | undefined` from 0.87, and as consumers of the callback we must accept
- * whichever the running version hands us.
+ * `index` is `number | null | undefined` because React Native types it `number | null` up to 0.86
+ * and `number | undefined` from 0.87.
  */
 export type ViewToken<ItemT = unknown> = {
   index: number | null | undefined;
@@ -60,24 +44,15 @@ export type ViewToken<ItemT = unknown> = {
 };
 
 export type ViewabilityConfig = {
-  /**
-   * Minimum amount of time (in milliseconds) that an item must be physically viewable before the
-   * viewability callback will be fired.
-   */
+  /** Minimum time in milliseconds an item must be viewable before the viewability callback runs. */
   minimumViewTime?: number | undefined;
   /**
-   * Percent of viewport that must be covered for a partially occluded item to count as "viewable",
-   * 0-100. Fully visible items are always considered viewable.
+   * Percent (0-100) of the viewport that must be covered for a partially occluded item to count as
+   * viewable. Fully visible items always count.
    */
   viewAreaCoveragePercentThreshold?: number | undefined;
-  /**
-   * Similar to `viewAreaCoveragePercentThreshold`, but considers the percent of the item that is
-   * visible rather than the fraction of the viewable area it covers.
-   */
+  /** Like `viewAreaCoveragePercentThreshold`, but measured as the percent of the item visible. */
   itemVisiblePercentThreshold?: number | undefined;
-  /**
-   * Nothing is considered viewable until the user scrolls or `recordInteraction` is called after
-   * render.
-   */
+  /** When true, nothing is viewable until the user scrolls or `recordInteraction` is called. */
   waitForInteraction?: boolean | undefined;
 };