@atlaskit/reactions 21.4.0 → 21.6.0

package/dist/types/types/reaction.d.ts

@@ -0,0 +1,82 @@
+/// <reference types="react" />
+import { User } from './User';
+/**
+ * Collection of reactions as object (key is unique id from containerAri and ari combined)
+ */
+export declare type Reactions = Record<string, ReactionSummary[]>;
+/**
+ * MetaData for Reaction object
+ */
+export interface ReactionSummary {
+    /**
+     * Reaction Asset id in the container
+     */
+    ari: string;
+    /**
+     * the container for reactions/ari in the page
+     */
+    containerAri: string;
+    /**
+     * unique Atlassian identifier for an emoji
+     */
+    emojiId: string;
+    /**
+     * Number of selected count for the emoji
+     */
+    count: number;
+    /**
+     * Has the current user selected the emoji or not
+     */
+    reacted: boolean;
+    /**
+     * Users collection
+     */
+    users?: User[];
+    /**
+     * @deprecated Legacy content Not in use anymore
+     */
+    optimisticallyUpdated?: boolean;
+}
+/**
+ * Event handler for when the user clicks on the reaction
+ * @param id give id for the emoji
+ * @param event selected mouse event proerties
+ */
+export declare type ReactionClick = (id: string, event: React.MouseEvent<HTMLButtonElement>) => void;
+/**
+ * Event handler for when the user hovers with the mouse on the reaction
+ * @param reaction reaction object
+ * @param event (Optional) custom DOM event handler callback
+ */
+export declare type ReactionMouseEnter = (reaction: ReactionSummary, event?: React.MouseEvent<any>) => void;
+/**
+ * Condition of the reaction when gets loaded from the store
+ */
+export declare enum ReactionStatus {
+    ready = "READY",
+    loading = "LOADING",
+    error = "ERROR",
+    notLoaded = "NOT_LOADED"
+}
+/**
+ * state in which the reaction is at
+ */
+export declare type ReactionsState = ReactionsNotLoaded | ReactionsLoading | ReactionsReadyState | ReactionsError;
+export declare type ReactionsReadyState = {
+    readonly status: ReactionStatus.ready;
+    readonly reactions: ReactionSummary[];
+};
+export declare type ReactionsLoading = {
+    readonly status: ReactionStatus.loading;
+};
+export declare type ReactionsError = {
+    readonly status: ReactionStatus.error;
+    readonly message: string;
+};
+export declare type ReactionsNotLoaded = {
+    readonly status: ReactionStatus.notLoaded;
+};
+/**
+ * Source where the emoji selected from ("quickSelector" -> default list, "emojiPicker" -> custom emoji list)
+ */
+export declare type ReactionSource = 'quickSelector' | 'emojiPicker';

package/dist/types/types/store.d.ts

@@ -0,0 +1,63 @@
+import { CreateUIAnalyticsEvent } from '@atlaskit/analytics-next';
+import { Actions } from './Actions';
+import { ReactionsState } from './reaction';
+/**
+ * Callback event when changes apply to the main store
+ * @param state latest store state
+ */
+export declare type OnChangeCallback = (state: State) => void;
+/**
+ * Map of state props
+ */
+export interface StoreProps {
+    /**
+     * Get current state of the stor
+     */
+    getState: () => State;
+    /**
+     * Register a callbsack event on change to the store instance state data
+     * @param callback event to register
+     * @deprecated initially implemented by the MemoryReactionsStore class and kept. This will be removed in a future release
+     */
+    onChange: (callback: OnChangeCallback) => void;
+    /**
+     * Deregister any callback event on changes to the store instance state data
+     * @param callback event to de-register
+     * @deprecated initially implemented by the MemoryReactionsStore class and kept. This will be removed in a future release
+     */
+    removeOnChangeListener: (callback: OnChangeCallback) => void;
+    /**
+     * Add Atlaskit analytics events to different operations in the store
+     * @param createAnalyticsEvent analytics event trigger
+     * @deprecated initially implemented by the MemoryReactionsStore class and kept. This will be removed in a future release
+     */
+    setCreateAnalyticsEvent?: (createAnalyticsEvent: CreateUIAnalyticsEvent) => void;
+}
+/**
+ * General Interface for a reaction store
+ */
+export interface Store extends Actions, StoreProps {
+}
+/**
+ * the "store" prop option to the connected view and picker components
+ */
+export declare type StorePropInput = Store | Promise<Store>;
+/**
+ * store main structure
+ */
+export declare type State = {
+    /**
+     * collection of the different reactions (key => unique reaction id , value => state of the reaction)
+     */
+    reactions: {
+        [key: string]: ReactionsState;
+    };
+    /**
+     * custom animation for given emojis as true|false (key => unique reaction id, value => collection of emojiIds and true|false to apply custom animation)
+     */
+    flash: {
+        [key: string]: {
+            [emojiId: string]: boolean;
+        };
+    };
+};

package/docs/0-intro.tsx

@@ -6,27 +6,53 @@ import {
   code,
   AtlassianInternalWarning,
 } from '@atlaskit/docs';
+import SectionMessage from '@atlaskit/section-message';
 
-import ReactionsExample from '../examples/00-picker-and-reactions';
-
-const ReactionsSource = require('!!raw-loader!../examples/00-picker-and-reactions');
-
-const ReactionsProps = require('!!extract-react-types-loader!../examples/examples-utils/ReactionsExampleWrapper');
+import ReactionsExample from '../examples/01-connected-reactions-view';
 
 export default md`
   ${(<AtlassianInternalWarning />)}
 
   The main purpose of the Reactions component is to provide users the ability to react to pieces of content.
+  It includes support for adding/view/remove a reaction from a specified emoji provider object.
+
+  The key components to use are:
+  1. [connectedReactionPicker](/packages/elements/reactions/docs/connected-reaction-picker)
+  1. [connectedReactionsView](/packages/elements/reactions/docs/connected-reactions-view)
+
+  The key types to use are:
+  1. [ReactionsStore](/packages/elements/reactions/docs/reactions-store)
+  1. [ReactionServiceClient](/packages/elements/reactions/docs/reaction-service-client)
+  1. [EmojiResource](https://atlaskit.atlassian.com/packages/elements/emoji/docs/resourced-emoji)
 
   ## Usage
 
-  Import the component in your React app as follows:
+  For each of these components, first import the following in your React app as follows:
 
   ${code`
-  import { ReactionStore, ConnectedReactionsView } from '@atlaskit/reactions';
-  import { EmojiResource } from '@atlaskit/emoji/resource';
-
-  const emojiProvider = new EmojiResource({
+  import { ReactionStore, ConnectedReactionsView, State, MemoryReactionsStore, ReactionServiceClient } from '@atlaskit/reactions';
+  import { EmojiResource, EmojiResourceConfig } from '@atlaskit/emoji/resource';
+
+  // Config object for the emoji resource
+  const config: EmojiResourceConfig = {
+    singleEmojiApi: {
+      getUrl: (emojiId: string) => 'https://emoji-example/emoji/site-id/emojiId',
+      securityProvider: () => ({
+        headers: {
+          'User-Context': '{{token}}',
+          Authorization: 'Bearer {{token}}',
+        },
+      })
+    },
+    optimisticImageApi: {
+      getUrl: (emojiId: string) => 'https://emoji-example/emoji/site-id/emojiId/path',
+      securityProvider: () => ({
+        headers: {
+          'User-Context': '{{token}}',
+          Authorization: 'Bearer {{token}}',
+        },
+      })
+    },
     providers: [
       {
         url: 'https://emoji-example/emoji/standard',
@@ -35,46 +61,111 @@ export default md`
         url: 'https://emoji-example/emoji/site-id/site',
         securityProvider: () => ({
           headers: {
-            Authorization: 'Bearer token',
+            Authorization: 'Bearer {{token}}',
           },
         }),
       },
-    ],
+    ]
+  };
+
+  const apiConfig = {
+    baseUrl: 'http://www.example.org',
+    // optional, generate token from asap, check \`pf-emoji-service\` for more info
+    authHeader: 'Bearer token',
+  };
+
+  // Create a client object fetching the reactions data from the specified url
+  const client = new ReactionServiceClient(apiConfig.baseUrl, apiConfig.authHeader);
+
+  // Define the initial state object
+  const intialState: State = {
+    reactions: {},
+    flash: {}
+  };
+
+  // Define the store object that will handle all the reactions data (get/set/remove) and the API calls to the server
+  const store = new MemoryReactionsStore(client, intialState, {
+    subproduct: 'atlaskit',
   });
 
-  const demoAri = 'ari:cloud:owner:demo-cloud-id:item/1';
+  // Define an emoji resource object instance that will be passed as prop to the ConnectedReactionsView component
+  const emojiResource = new EmojiResource(config); //See warning below
+
+  /**
+   * fetch from all the providers in the config object and cache the results (see EmojiResource for more info).
+   * Note: this is a one time fetch, so if you want to fetch from the same providers again, you need to create a new EmojiResource instance. Furhermore, you'll need to handle for a failed fetch and retry requests if your app logic requires this.
+   */
+  emojiResource.fetchEmojiProvider();
+
+  // Retrieve your ari and containerAri values from the server
+  const ari = 'ari:cloud:owner:demo-cloud-id:item/1';
   const containerAri = 'ari:cloud:owner:demo-cloud-id:container/1';
 
+
+  // Render the component in your React app
   ReactDOM.render(
-    <ReactionStore url="https://reactions-service">
-      <ConnectedReactionsView
-        containerAri={containerAri}
-        ari={demoAri}
-        emojiProvider={Promise.resolve(emojiProvider)}
-      />
-    </ReactionStore>,
+    <ConnectedReactionsView
+      store={store}
+      containerAri={containerAri}
+      ari={demoAri}
+      emojiProvider={Promise.resolve(emojiResource)}
+    />
     container,
-  );
   };`}
 
+  ${(
+    <>
+      <br />
+      <SectionMessage
+        appearance="warning"
+        title="There should be only one instance of EmojiResource in your application"
+      >
+        <p>
+          Make sure EmojiResource is initialised only once to avoid performance
+          issues using useMemo.
+        </p>
+      </SectionMessage>
+      <br />
+      <SectionMessage appearance="information">
+        <p>EmojiResource object implements the EmojiProvider interface.</p>
+        <a
+          href="https://atlaskit.atlassian.com/packages/elements/emoji/docs/emoji-provider"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          See here for information on EmojiProvider.
+        </a>
+      </SectionMessage>
+    </>
+  )}
+
   ### Note:
 
   Don't forget to add polyfills for fetch, ES6 & ES7 to your product build if you want to target older browsers.
   We recommend the use of [babel-preset-env](https://babeljs.io/docs/plugins/preset-env/) & [babel-polyfill](https://babeljs.io/docs/usage/polyfill/)
 
-  Key navigation can be bound to \`selectNext\` (e.g. down arrow),
-  \`selectPrevious\` (e.g. up arrow), and \`chooseCurrentSelection\`
-  (e.g. enter and tab).
+  ### Example:
 
   ${(
     <Example
       packageName="@atlaskit/reactions"
       Component={ReactionsExample}
       title="Picker and Reactions"
-      source={ReactionsSource}
+      source={require('!!raw-loader!../examples/01-connected-reactions-view')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Reactions Props"
+      props={require('!!extract-react-types-loader!../extract-react-type/Reactions')}
     />
   )}
 
-  ${(<Props props={ReactionsProps} />)}
 
-`;
+  ${(
+    <Props
+      heading="Reaction Props"
+      props={require('!!extract-react-types-loader!../extract-react-type/Reaction')}
+    />
+  )}`;

package/docs/1-connected-reaction-picker.tsx

@@ -0,0 +1,133 @@
+import React from 'react';
+import { md, Example, code, Props } from '@atlaskit/docs';
+import SectionMessage from '@atlaskit/section-message';
+
+import ConnectedReactionPickerExample from '../examples/00-connected-reaction-picker';
+
+export default md`
+
+  The ConnectedReactionPicker component renders the Reaction picker custom selector to add a new reaction to the content displayed.
+
+  ## Usage
+
+  Import the component in your React app as follows:
+
+  ${code`
+  import { ReactionStore, ConnectedReactionPicker, State, MemoryReactionsStore, ReactionServiceClient } from '@atlaskit/reactions';
+  import { EmojiResource, EmojiResourceConfig } from '@atlaskit/emoji/resource';
+
+  // Config object for the emoji resource
+  const config: EmojiResourceConfig = {
+    singleEmojiApi: {
+      getUrl: (emojiId: string) => 'https://emoji-example/emoji/site-id/emojiId',
+      securityProvider: () => ({
+        headers: {
+          'User-Context': '{{token}}',
+          Authorization: 'Bearer {{token}}',
+        },
+      })
+    },
+    optimisticImageApi: {
+      getUrl: (emojiId: string) => 'https://emoji-example/emoji/site-id/emojiId/path',
+      securityProvider: () => ({
+        headers: {
+          'User-Context': '{{token}}',
+          Authorization: 'Bearer {{token}}',
+        },
+      })
+    },
+    providers: [
+      {
+        url: 'https://emoji-example/emoji/standard',
+      },
+      {
+        url: 'https://emoji-example/emoji/site-id/site',
+        securityProvider: () => ({
+          headers: {
+            Authorization: 'Bearer {{token}}',
+          },
+        }),
+      },
+    ]
+  };
+
+  const apiConfig = {
+    baseUrl: 'http://www.example.org',
+    // optional, generate token from asap, check \`pf-emoji-service\` for more info
+    authHeader: 'Bearer token',
+  };
+
+  // Create a client object fetching the reactions data from the specified url
+  const client = new ReactionServiceClient(apiConfig.baseUrl, apiConfig.authHeader);
+
+  // Define the initial state object
+  const intialState: State = {
+    reactions: {},
+    flash: {}
+  };
+
+  // Define the store object that will handle all the reactions data (get/set/remove) and the API calls to the server
+  const store = new MemoryReactionsStore(client, intialState, {
+    subproduct: 'atlaskit',
+  });
+
+
+  // Define an emoji resource object instance (EmojiResource implements the EmojiProvider interface) that will be passed as prop to the ConnectedReactionPicker component
+  const emojiResource = new EmojiResource(config); //See warning below
+
+  /**
+   * fetch from all the providers in the config object and cache the results (see EmojiResource for more info).
+   * Note: this is a one time fetch, so if you want to fetch from the same providers again, you need to create a new EmojiResource instance. Furhermore, you'll need to handle for a failed fetch and retry requests if your app logic requires this.
+   */
+  emojiResource.fetchEmojiProvider();
+
+  // Retrieve your ari and containerAri values from the server
+  const ari = 'ari:cloud:owner:demo-cloud-id:item/1';
+  const containerAri = 'ari:cloud:owner:demo-cloud-id:container/1';
+
+  const emojiProvider = new EmojiResource(config);
+  const emojiId = { shortName: ':grimacing:', id: '1f603' };
+
+
+  ReactDOM.render(
+    <ConnectedReactionPicker
+    store={store}
+    containerAri={containerAri}
+    ari={demoAri}
+    emojiProvider={Promise.resolve(emojiResource)}
+    />
+  );`}
+
+  ${(
+    <>
+      <br />
+      <SectionMessage
+        appearance="warning"
+        title="There should be only one instance of EmojiResource in your application"
+      >
+        <p>
+          Make sure EmojiResource is initialised only once to avoid performance
+          issues using useMemo.
+        </p>
+      </SectionMessage>
+    </>
+  )}
+
+  ### Example:
+
+  ${(
+    <Example
+      packageName="@atlaskit/reactions"
+      Component={ConnectedReactionPickerExample}
+      title="Connected Reactions Picker"
+      source={require('!!raw-loader!../examples/00-connected-reaction-picker')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="ConnectedReactionPicker Props"
+      props={require('!!extract-react-types-loader!../extract-react-type/ConnectedReactionPicker')}
+    />
+  )}
+`;

package/docs/2-connected-reactions-view.tsx

@@ -0,0 +1,130 @@
+import React from 'react';
+import { md, Example, code, Props } from '@atlaskit/docs';
+import SectionMessage from '@atlaskit/section-message';
+
+import ConnectedReactionsViewExample from '../examples/01-connected-reactions-view';
+
+export default md`
+
+  The ConnectedReactionsView component renders all existing reactions for given post/comment/etc.. as well as the [ConnectedReactionPicker](/packages/elements/reactions/docs/connected-reaction-picker) to add more reactions.
+
+  ## Usage
+
+  Import the component in your React app as follows:
+
+  ${code`
+  import { ReactionStore, ConnectedReactionsView, State, MemoryReactionsStore, ReactionServiceClient } from '@atlaskit/reactions';
+  import { EmojiResource, EmojiResourceConfig } from '@atlaskit/emoji/resource';
+
+  // Config object for the emoji resource
+  const config: EmojiResourceConfig = {
+    singleEmojiApi: {
+      getUrl: (emojiId: string) => 'https://emoji-example/emoji/site-id/emojiId',
+      securityProvider: () => ({
+        headers: {
+          'User-Context': '{{token}}',
+          Authorization: 'Bearer {{token}}',
+        },
+      })
+    },
+    optimisticImageApi: {
+      getUrl: (emojiId: string) => 'https://emoji-example/emoji/site-id/emojiId/path',
+      securityProvider: () => ({
+        headers: {
+          'User-Context': '{{token}}',
+          Authorization: 'Bearer {{token}}',
+        },
+      })
+    },
+    providers: [
+      {
+        url: 'https://emoji-example/emoji/standard',
+      },
+      {
+        url: 'https://emoji-example/emoji/site-id/site',
+        securityProvider: () => ({
+          headers: {
+            Authorization: 'Bearer {{token}}',
+          },
+        }),
+      },
+    ]
+  };
+
+  const apiConfig = {
+    baseUrl: 'http://www.example.org',
+    // optional, generate token from asap, check \`pf-emoji-service\` for more info
+    authHeader: 'Bearer token',
+  };
+
+  // Create a client object fetching the reactions data from the specified url
+  const client = new ReactionServiceClient(apiConfig.baseUrl, apiConfig.authHeader);
+
+  // Define the initial state object
+  const intialState: State = {
+    reactions: {},
+    flash: {}
+  };
+
+  // Define the store object that will handle all the reactions data (get/set/remove) and the API calls to the server
+  const store = new MemoryReactionsStore(client, intialState, {
+    subproduct: 'atlaskit',
+  });
+
+  // Define an emoji resource object instance (EmojiResource implements the EmojiProvider interface) that will be passed as prop to the ConnectedReactionsView component
+  const emojiResource = new EmojiResource(config); //See warning below
+
+  /**
+   * fetch from all the providers in the config object and cache the results (see EmojiResource for more info).
+   * Note: this is a one time fetch, so if you want to fetch from the same providers again, you need to create a new EmojiResource instance. Furhermore, you'll need to handle for a failed fetch and retry requests if your app logic requires this.
+   */
+  emojiResource.fetchEmojiProvider();
+
+  // Retrieve your ari and containerAri values from the server
+  const ari = 'ari:cloud:owner:demo-cloud-id:item/1';
+  const containerAri = 'ari:cloud:owner:demo-cloud-id:container/1';
+
+  const emojiProvider = new EmojiResource(config);
+
+  // Render the component in your React app
+  ReactDOM.render(
+    <ConnectedReactionsView
+      store={store}
+      containerAri={containerAri}
+      ari={demoAri}
+      emojiProvider={Promise.resolve(emojiResource)}
+    />
+    container,
+  };`}
+
+  ${(
+    <>
+      <br />
+      <SectionMessage
+        appearance="warning"
+        title="There should be only one instance of EmojiResource in your application"
+      >
+        <p>
+          Make sure EmojiResource is initialised only once to avoid performance
+          issues using useMemo.
+        </p>
+      </SectionMessage>
+    </>
+  )}
+
+  ${(
+    <Example
+      packageName="@atlaskit/reactions"
+      Component={ConnectedReactionsViewExample}
+      title="Connected Reactions View"
+      source={require('!!raw-loader!../examples/01-connected-reactions-view')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="ConnectedReactionsView type"
+      props={require('!!extract-react-types-loader!../extract-react-type/ConnectedReactionsView')}
+    />
+  )}
+`;

package/docs/3-reactions-store.tsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import { md, code, Props } from '@atlaskit/docs';
+import SectionMessage from '@atlaskit/section-message';
+
+export default md`
+
+  The ReactionsStore is one of the key interfaces that encapsulates all logic needed to maintain internal state of the reaction elements (get latest state and onChange callback events), including different types of Actions required to perform on the store (getReactions, toggleReaction on/off, adding a new reaciton, getting detailed reaction upon hovering the emoji icon).
+  It serves as one of the key props passed to the connected HoC used in Reactions: (\`ConnectedReactionPicker\` and \`ConnectedReactions\`).
+
+  ${(
+    <>
+      <br />
+      <SectionMessage appearance="information" title="">
+        You can instantiate an instance of the ReactionsStore object using the
+        built in <strong>MemoryReactionsStore</strong> class object that
+        contains all logic required to communicate with the store. It provides
+        all the methods to interact with the store and the API calls to the
+        server, including logging
+        <a
+          target="_blank"
+          rel="noopener noreferrer"
+          href="https://developer.atlassian.com/platform/ufo/"
+        >
+          UFO
+        </a>
+        .
+        <br />
+      </SectionMessage>
+    </>
+  )}
+
+  ## Usage
+
+  ${code`
+  import { MemoryReactionsStore, State, ReactionServiceClient } from '@atlaskit/reactions';
+
+  const apiConfig = {
+    baseUrl: 'http://www.example.org',
+    // optional, generate token from asap, check \`pf-emoji-service\` for more info
+    authHeader: 'Bearer token',
+  };
+
+  // Create a client object fetching the reactions data from the specified url
+  const client = new ReactionServiceClient(apiConfig.baseUrl, apiConfig.authHeader);
+
+  // Define the initial state object
+  const intialState: State = {
+    reactions: {},
+    flash: {}
+  };
+
+  // Define the store object that will handle all the reactions data (get/set/remove) and the API calls to the server
+  const store = new MemoryReactionsStore(client, intialState, {
+    subproduct: 'atlaskit',
+  });
+`}
+
+  ${(
+    <Props
+      heading="Store Type"
+      props={require('!!extract-react-types-loader!../extract-react-type/reactionsStore')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Actions type"
+      props={require('!!extract-react-types-loader!../extract-react-type/actions')}
+    />
+  )}
+`;