user status: Sync server-data types with server behavior; rework model

As mentioned in some comments, the server-data types and comments
are based on my empirical observations reported in
  https://chat.zulip.org/#narrow/stream/412-api-documentation/topic/Emoji.20statuses.20in.20zulip.2Eyaml/near/1322329
; those should eventually make it into the server API doc.

Author: chrisbobbe

src/account-info/AccountDetails.js

@@ -67,7 +67,7 @@ export default function AccountDetails(props: Props): Node {
         />
         <ZulipText style={[styles.largerText, styles.halfMarginRight]} text={user.full_name} />
       </View>
-      {userStatusText !== undefined && (
+      {userStatusText !== null && (
         <ZulipText style={[styles.largerText, componentStyles.statusText]} text={userStatusText} />
       )}
       {!isSelf && (

src/api/eventTypes.js

@@ -10,7 +10,14 @@
  * @flow strict-local
  */
 
-import type { Message, MutedUser, Stream, UserId, UserPresence } from './modelTypes';
+import type {
+  Message,
+  MutedUser,
+  Stream,
+  UserId,
+  UserPresence,
+  UserStatusUpdate,
+} from './modelTypes';
 import type { RealmDataForUpdate } from './realmDataTypes';
 
 export class EventTypes {
@@ -101,25 +108,19 @@ export type PresenceEvent = $ReadOnly<{|
 |}>;
 
 /**
- * Updates the user status for a user
+ * New value for a user's chosen availability and/or text/emoji status
  *
- * @prop [away] - update user's away status:
- *       - `true` the user is away regardless of presence
- *       - `false` remove the away status, now use presence
- * @prop [status_text] - if present:
- *       - empty string clears the user's status text
- *       - any string sets user's status to that
- *
- * Not providing a property means 'leave this value unchanged'
+ * https://zulip.com/api/get-events#user_status
  *
  * See InitialDataUserStatus for the corresponding initial data.
  */
 export type UserStatusEvent = $ReadOnly<{|
   ...EventCommon,
   type: typeof EventTypes.user_status,
   user_id: UserId,
-  away?: boolean,
-  status_text?: string,
+
+  // How the status is updated from the old value.
+  ...UserStatusUpdate,
 |}>;
 
 type StreamListEvent = $ReadOnly<{|

src/api/initialDataTypes.js

@@ -1,5 +1,6 @@
 /* @flow strict-local */
 
+import type { UserStatusUpdate } from './modelTypes';
 import type {
   CrossRealmBot,
   MutedTopicTuple,
@@ -497,6 +498,13 @@ export type InitialDataUpdateMessageFlags = $ReadOnly<{|
   |}>,
 |}>;
 
+/**
+ * Users' chosen availability and text/emoji statuses.
+ *
+ * See UserStatusEvent for the event that carries updates to this data.
+ */
+// TODO(?): Find out if servers ignore any users (e.g., deactivated ones) when
+//   assembling this.
 export type InitialDataUserStatus = $ReadOnly<{|
   /**
    * Older servers (through at least 1.9.1) don't send this.
@@ -511,16 +519,24 @@ export type InitialDataUserStatus = $ReadOnly<{|
    */
   // TODO(server-1.9.1): Make required.
   user_status?: $ReadOnly<{|
+    // How the status has changed relative to the following "zero" value:
+    //
+    // {
+    //   away: false,
+    //   status_text: '',
+    //   emoji_name: '',
+    //   reaction_type: '',
+    //   emoji_code: '',
+    // };
+    //
+    // (For how we represent that zero value as a UserStatus in our model,
+    // see `kUserStatusZero`.)
+    //
+    // If no change, servers may omit the record for that user entirely.
+    //
     // Keys are UserId encoded as strings (just because JS objects are
     // string-keyed).
-    [userId: string]: $ReadOnly<{|
-      // TODO: add status emoji properties
-      // TODO: Comment on what these mean (if doc not fixed):
-      //   https://chat.zulip.org/#narrow/stream/412-api-documentation/topic/Emoji.20statuses.20in.20zulip.2Eyaml/near/1322329
-
-      away?: true,
-      status_text?: string,
-    |}>,
+    [userId: string]: UserStatusUpdate,
   |}>,
 |}>;
 

src/api/modelTypes.js

@@ -211,6 +211,32 @@ export type UserGroup = $ReadOnly<{|
   name: string,
 |}>;
 
+/**
+ * The server's representation of the diff between two user-status records.
+ *
+ * A value is mentioned only when it's changed.
+ *
+ * N.B., emoji statuses are new in 5.0 (feature level 86), so they'll never
+ * be present before then. But "unchanged" is still appropriate semantics
+ * and will lead to correct behavior.
+ *
+ * For the strings, the empty string means that component of the user's
+ * status is unset.
+ */
+// TODO(server-5.0): Simplify jsdoc.
+// TODO(docs): All this is observed empirically; update the doc. See
+//   https://chat.zulip.org/#narrow/stream/412-api-documentation/topic/Emoji.20statuses.20in.20zulip.2Eyaml/near/1322329
+export type UserStatusUpdate = $ReadOnly<{|
+  away?: boolean,
+  status_text?: string,
+
+  // These three properties point to an emoji in the same way the same-named
+  // properties point to an emoji in the Reaction type; see there.
+  emoji_name?: string,
+  emoji_code?: string,
+  reaction_type?: ReactionType | '', // eslint-disable-line no-use-before-define
+|}>;
+
 /** See ClientPresence, and the doc linked there. */
 export type PresenceStatus = 'active' | 'idle' | 'offline';
 

src/api/users/updateUserStatus.js

@@ -9,8 +9,6 @@ type UserStatusParams = {|
 
 // TODO: Take a partial UserStatus object from our user-status model.
 //   Partial because servers allow updating just part of the status in a
-//   request, and it's nice to let callers do that. First need to make
-//   missing/`undefined` stop being meaningful representations in any of
-//   UserStatus's keys.
+//   request, and it's nice to let callers do that.
 export default (auth: Auth, params: UserStatusParams): Promise<ApiResponseSuccess> =>
   apiPost(auth, 'users/me/status', params);

src/reduxTypes.js

@@ -10,7 +10,7 @@
 import type Immutable from 'immutable';
 import type { InputSelector } from 'reselect';
 
-import type { Account, Outbox } from './types';
+import type { Account, Outbox, ReactionType } from './types';
 import type { Action, DispatchableWithoutAccountAction } from './actionTypes';
 import type {
   Topic,
@@ -383,18 +383,24 @@ export type TypingState = $ReadOnly<{|
 export type UserGroupsState = $ReadOnlyArray<UserGroup>;
 
 /**
- * Specifies user status related properties
- * @prop away - present if we are to override user's presence status
- *   * This is the "user status" / "unavailable" feature added in early 2019.
- *     (At time of writing, there are no docs to link to.)
- * @prop status_text - a string representing information the user decided to
- *   manually set as their 'current status'
+ * A user's chosen availability and text/emoji statuses.
  */
-// TODO: fix types, implementation, and jsdoc:
-//   https://chat.zulip.org/#narrow/stream/412-api-documentation/topic/Emoji.20statuses.20in.20zulip.2Eyaml/near/1322329
 export type UserStatus = $ReadOnly<{|
-  away?: true,
-  status_text?: string,
+  // true/false: User unavailable/available.
+  away: boolean,
+
+  // "foo": User's status text is "foo".
+  // null: User's status text is unset.
+  status_text: string | null,
+
+  // null: User's status emoji is unset.
+  status_emoji: null | {|
+    // These three properties point to an emoji in the same way the same-named
+    // properties point to an emoji in the Reaction type; see there.
+    +emoji_name: string,
+    +reaction_type: ReactionType,
+    +emoji_code: string,
+  |},
 |}>;
 
 export type UserStatusState = Immutable.Map<UserId, UserStatus>;

src/user-status/UserStatusScreen.js

@@ -38,11 +38,11 @@ export default function UserStatusScreen(props: Props): Node {
   const auth = useSelector(getAuth);
   const userStatusText = useSelector(getSelfUserStatusText);
 
-  const [statusText, setStatusText] = useState<string | void>(userStatusText);
+  const [statusText, setStatusText] = useState<string | null>(userStatusText);
   const _ = useContext(TranslationContext);
 
   const sendToServer = useCallback(
-    (_statusText: string | void) => {
+    (_statusText: string | null) => {
       api.updateUserStatus(auth, { status_text: _statusText ?? '' });
       NavigationService.dispatch(navigateBack());
     },
@@ -54,7 +54,7 @@ export default function UserStatusScreen(props: Props): Node {
   }, [statusText, sendToServer]);
 
   const handlePressClear = useCallback(() => {
-    setStatusText(undefined);
+    setStatusText(null);
     sendToServer('');
   }, [sendToServer]);