Update RN Share.share()'s argument types to be more explicit (#44887)

Summary:
Pull Request resolved: #44887

The previous inexact object types and documentation for Share.share()'s arguments have led to confusion in how this library should be used. This diff updates the argument types to be more explicit, and rewrites some of the documentation for clarity.

Changelog:
[General][Breaking] Update `Share.share()`'s argument types to be more explicit.

Differential Revision: D58224906

packages/react-native/Libraries/Share/Share.js

@@ -15,24 +15,23 @@ const processColor = require('../StyleSheet/processColor').default;
 const Platform = require('../Utilities/Platform');
 const invariant = require('invariant');
 
-type Content =
+export type ShareContent =
   | {
       title?: string,
-      message: string,
-      ...
+      url: string,
+      message?: string,
     }
   | {
       title?: string,
-      url: string,
-      ...
+      url?: string,
+      message: string,
     };
-type Options = {
+export type ShareOptions = {
   dialogTitle?: string,
   excludedActivityTypes?: Array<string>,
   tintColor?: string,
   subject?: string,
   anchor?: number,
-  ...
 };
 
 class Share {
@@ -43,21 +42,21 @@ class Share {
    * If the user dismissed the dialog, the Promise will still be resolved with action being `Share.dismissedAction`
    * and all the other keys being undefined.
    *
-   * In Android, Returns a Promise which always be resolved with action being `Share.sharedAction`.
+   * In Android, Returns a Promise which always resolves with action being `Share.sharedAction`.
    *
    * ### Content
    *
-   *  - `message` - a message to share
-   *
    * #### iOS
    *
    *  - `url` - a URL to share
+   *  - `message` - a message to share
    *
-   * At least one of URL and message is required.
+   * At least one of `URL` or `message` is required.
    *
    * #### Android
    *
-   * - `title` - title of the message
+   * - `title` - title of the message (optional)
+   * - `message` - a message to share (often will include a URL).
    *
    * ### Options
    *
@@ -73,16 +72,16 @@ class Share {
    *
    */
   static share(
-    content: Content,
-    options: Options = {},
+    content: ShareContent,
+    options: ShareOptions = {},
   ): Promise<{action: string, activityType: ?string}> {
     invariant(
       typeof content === 'object' && content !== null,
       'Content to share must be a valid object',
     );
     invariant(
       typeof content.url === 'string' || typeof content.message === 'string',
-      'At least one of URL and message is required',
+      'At least one of URL or message is required',
     );
     invariant(
       typeof options === 'object' && options !== null,

packages/react-native/Libraries/__tests__/__snapshots__/public-api-test.js.snap

@@ -7337,29 +7337,28 @@ declare export default typeof NativeShareModule;
 `;
 
 exports[`public API should not change unintentionally Libraries/Share/Share.js 1`] = `
-"type Content =
+"export type ShareContent =
   | {
       title?: string,
-      message: string,
-      ...
+      url: string,
+      message?: string,
     }
   | {
       title?: string,
-      url: string,
-      ...
+      url?: string,
+      message: string,
     };
-type Options = {
+export type ShareOptions = {
   dialogTitle?: string,
   excludedActivityTypes?: Array<string>,
   tintColor?: string,
   subject?: string,
   anchor?: number,
-  ...
 };
 declare class Share {
   static share(
-    content: Content,
-    options: Options
+    content: ShareContent,
+    options: ShareOptions
   ): Promise<{ action: string, activityType: ?string }>;
   static sharedAction: \\"sharedAction\\";
   static dismissedAction: \\"dismissedAction\\";