Merge pull request #1392 from magento-research/jimothy/gh-1389_merge-…

…master-to-develop

Merge master to develop

magento-compatibility.js

@@ -4,6 +4,6 @@
 
 // PWA Studio version -> Magento version.
 module.exports = {
-    '>2.0.0': '2.3.1',
+    '>2.0.0': '>=2.3.1',
     '2.0.0': '2.3.0'
 };

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magento/pwa-studio",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "private": true,
   "workspaces": [
     "packages/graphql-cli-validate-magento-pwa-queries",

packages/peregrine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magento/peregrine",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "publishConfig": {
     "access": "public"
   },

packages/peregrine/src/hooks/useApolloContext.js

@@ -1,4 +1,10 @@
 import { useContext } from 'react';
 import { ApolloContext } from 'react-apollo/ApolloContext';
 
+/**
+ * A function that provides access to the [Apollo client]{@link https://www.apollographql.com/docs/react/api/apollo-client} API.
+ *
+ * @return {ApolloClient} The Apollo client for this application
+ * @kind function
+ */
 export const useApolloContext = () => useContext(ApolloContext);

packages/peregrine/src/hooks/useDropdown.js

@@ -2,6 +2,13 @@ import { useCallback, useRef, useState } from 'react';
 
 import { useEventListener } from './useEventListener';
 
+/**
+ * A React Hook for adding dropdown-related logic.
+ *
+ * @kind function
+ *
+ * @return {Dropdown} An object containing functions and values to add dropdown logic
+ */
 export const useDropdown = () => {
     const elementRef = useRef(null);
     const [expanded, setExpanded] = useState(false);
@@ -16,6 +23,15 @@ export const useDropdown = () => {
     // add listener to document, as an effect
     useEventListener(document, 'mousedown', maybeCollapse);
 
+    /**
+     * The object returned contains the pieces needed to add the dropdown logic to your components
+     *
+     * @typedef Dropdown
+     * @type {Object}
+     * @property {Ref} elementRef - A [ref]{@link https://reactjs.org/docs/refs-and-the-dom.html} object for attaching to React elements
+     * @property {Boolean} expanded - The value of the `expanded` state
+     * @property {Function} setExpanded - [State Hook]{@link https://reactjs.org/docs/hooks-state.html} function for setting the expanded state
+     */
     return {
         elementRef,
         expanded,

packages/peregrine/src/hooks/useQuery.js

@@ -3,13 +3,29 @@ import { useCallback, useMemo } from 'react';
 import { useApolloContext } from './useApolloContext';
 import { useQueryResult } from './useQueryResult';
 
+/**
+ * A [React Hook]{@link https://reactjs.org/docs/hooks-intro.html} that provides
+ * access to query results data and an API object for running the query and
+ * managing a query result state object.
+ *
+ * @kind function
+ *
+ * @param {DocumentNode} query A GraphQL document containing a query to send to the server. See {@link https://github.com/apollographql/graphql-tag graphql-tag}
+ *
+ * @return {Object[]} An array with two entries containing the following content: [{@link ../useQueryResult#queryresultstate--object QueryResultState}, {@link API}]
+ */
 export const useQuery = query => {
     const apolloClient = useApolloContext();
     const [queryResultState, queryResultApi] = useQueryResult();
     const { receiveResponse } = queryResultApi;
 
-    // define a callback that performs a query
-    // either as an effect or in response to user interaction
+    /**
+     * A callback function that performs a query either as an effect or in response to user interaction.
+     *
+     * @function API.runQuery
+     *
+     * @param {DocumentNode} query A GraphQL document
+     */
     const runQuery = useCallback(
         async ({ variables }) => {
             const payload = await apolloClient.query({ query, variables });
@@ -18,7 +34,16 @@ export const useQuery = query => {
         [apolloClient, query, receiveResponse]
     );
 
-    // this object should never change
+    /**
+     * The API for managing the query.
+     * Use this API to run queries and get the resulting state values and query data.
+     *
+     * In addition to the {@link API.runQuery runQuery()} function,
+     * this object also contains the API methods from the {@link ../useQueryResult#api--object  useQueryResult hook}.
+     *
+     * @typedef API
+     * @type Object
+     */
     const api = useMemo(
         () => ({
             ...queryResultApi,

packages/peregrine/src/hooks/useQueryResult.js

@@ -35,9 +35,36 @@ const reducer = (state, { payload, type }) => {
     }
 };
 
+/**
+ * A [React Hook]{@link https://reactjs.org/docs/hooks-intro.html} that contains
+ * logic for handling a query result.
+ * It returns the state of the query result and an API object for managing that
+ * state object.
+ *
+ * @typedef useQueryResult
+ * @kind function
+ *
+ * @return {Object[]} An array with two entries containing the following content: [ {@link QueryResultState}, {@link API}]
+ */
 export const useQueryResult = () => {
+    /**
+     * A function for dispatching actions specific to this module.
+     * This is similar to the [dispatch() function in Redux]{@link https://redux.js.org/api/store#dispatch}
+     *
+     * @function API.dispatch
+     *
+     * @param {QueryResultState} state The current state
+     * @param {QueryResultAction} action A QueryResultAction object
+     */
     const [state, dispatch] = useReducer(reducer, initialState);
 
+    /**
+     * Set the state data
+     *
+     * @function API.setData
+     *
+     * @param {Object} data The updated state data
+     */
     const setData = useCallback(
         payload => {
             dispatch({
@@ -48,6 +75,13 @@ export const useQueryResult = () => {
         [dispatch]
     );
 
+    /**
+     * Set the error state
+     *
+     * @function API.setError
+     *
+     * @param {Object} errorData The error data for the state
+     */
     const setError = useCallback(
         payload => {
             dispatch({
@@ -58,6 +92,13 @@ export const useQueryResult = () => {
         [dispatch]
     );
 
+    /**
+     * Set the loading state
+     *
+     * @function API.setLoading
+     *
+     * @param {Boolean} isLoading New value for the loading state
+     */
     const setLoading = useCallback(
         payload => {
             dispatch({
@@ -68,6 +109,13 @@ export const useQueryResult = () => {
         [dispatch]
     );
 
+    /**
+     * Updates the state using the response payload.
+     *
+     * @function API.receiveResponse
+     *
+     * @param {Object} payload The query response payload
+     */
     const receiveResponse = useCallback(
         payload => {
             dispatch({
@@ -78,6 +126,11 @@ export const useQueryResult = () => {
         [dispatch]
     );
 
+    /**
+     * Resets the state to its initial value.
+     *
+     * @function API.resetState
+     */
     const resetState = useCallback(
         payload => {
             dispatch({
@@ -88,7 +141,14 @@ export const useQueryResult = () => {
         [dispatch]
     );
 
-    // this object should never change
+    /**
+     * The API for managing the query results state.
+     * Use this API to update the various parts of the query result state.
+     *
+     * This object should never change.
+     * @typedef API
+     * @type Object
+     */
     const api = useMemo(
         () => ({
             dispatch,
@@ -103,3 +163,26 @@ export const useQueryResult = () => {
 
     return [state, api];
 };
+
+// Misc. type definitions
+
+/**
+ * The current state of a query result.
+ *
+ * @typedef QueryResultState
+ * @type Object
+ *
+ * @property {Object} data The query data or null if it is not available.
+ * @property {Object} error Error object that is set when there is an error getting the query.
+ * @property {Boolean} loading True if the query is still being loaded. False otherwise.
+ */
+
+/**
+ * An Action object similar to a [Redux Action]{@link https://redux.js.org/basics/actions}.
+ *
+ * @typedef QueryResultAction
+ * @type Object
+ *
+ * @property {Object} payload The data payload for an action
+ * @property {String} type The type of action associated with this object
+ */

packages/peregrine/src/hooks/useSearchParam.js

@@ -6,6 +6,18 @@ const getSearchParam = (parameter = '', location = window.location) => {
     return params.get(parameter) || '';
 };
 
+/**
+ * A [React Hook]{@link https://reactjs.org/docs/hooks-intro.html} that gets
+ * a search parameter from a URL and calls a provided setter function with
+ * the corresponding value.
+ *
+ * @kind function
+ *
+ * @param {Object} props An object containing the location, parameter, and setter function.
+ * @param {String} props.location The URL location to search in
+ * @param {String} props.parameter The parameter to search for
+ * @param {Function} props.setValue A setter function that is passed the parameter value found in the URL
+ */
 export const useSearchParam = props => {
     const { location, parameter, setValue } = props;
     const value = getSearchParam(parameter, location);

packages/pwa-buildpack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magento/pwa-buildpack",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "publishConfig": {
     "access": "public"
   },
@@ -34,7 +34,7 @@
     "@babel/plugin-transform-react-jsx": "~7.3.0",
     "@magento/directive-parser": "~0.1.6",
     "@magento/express-sharp": "~2.1.1-newdeps.1",
-    "@magento/upward-js": "~2.1.0",
+    "@magento/upward-js": "~2.2.0",
     "ajv": "~6.9.2",
     "apicache": "~1.4.0",
     "babel-loader": "~8.0.5",

packages/upward-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magento/upward-js",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Implementation of the UPWARD spec as a NodeJS server",
   "main": "./lib/index.js",
   "bin": {
@@ -49,7 +49,7 @@
     "shrink-ray-current": "~4.0.0"
   },
   "devDependencies": {
-    "@magento/upward-spec": "~2.1.0",
+    "@magento/upward-spec": "~2.2.0",
     "express": "~4.16.4",
     "supertest": "~3.4.2"
   },

packages/upward-spec/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magento/upward-spec",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "UPWARD specification, guide, and test suite.",
   "main": "./suite/index.js",
   "bin": {

packages/venia-concept/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magento/venia-concept",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "publishConfig": {
     "access": "public"
   },
@@ -36,7 +36,7 @@
   "homepage": "https://github.com/magento-research/pwa-studio/tree/master/packages/venia-concept#readme",
   "dependencies": {
     "@babel/runtime": "~7.4.2",
-    "@magento/peregrine": "~2.1.0",
+    "@magento/peregrine": "~3.0.0",
     "apollo-boost": "~0.1.28",
     "apollo-cache-inmemory": "~1.4.3",
     "apollo-cache-persist": "~0.1.1",
@@ -71,8 +71,8 @@
     "@babel/plugin-transform-react-jsx": "~7.3.0",
     "@babel/plugin-transform-runtime": "~7.4.4",
     "@babel/preset-env": "~7.3.4",
-    "@magento/pwa-buildpack": "~2.1.0",
-    "@magento/upward-js": "~2.1.0",
+    "@magento/pwa-buildpack": "~3.0.0",
+    "@magento/upward-js": "~2.2.0",
     "@storybook/react": "~4.1.13",
     "babel-core": "~7.0.0-bridge.0",
     "babel-jest": "~24.1.0",

packages/venia-concept/src/components/SearchBar/__tests__/__snapshots__/suggestedProduct.spec.js.snap

@@ -7,6 +7,7 @@ Array [
   >
     <img
       alt="Product Name"
+      className="thumbnail"
     />
   </span>,
   <span

packages/venia-concept/src/components/SearchBar/suggestedProduct.css

@@ -12,6 +12,11 @@
     justify-content: center;
 }
 
+.thumbnail {
+    max-height: 75px;
+    max-width: 60px;
+}
+
 .name {
     word-break: break-word;
 }

packages/venia-concept/src/components/SearchBar/suggestedProduct.js

@@ -26,7 +26,8 @@ class SuggestedProduct extends Component {
             root: string,
             image: string,
             name: string,
-            price: string
+            price: string,
+            thumbnail: string
         })
     };
 
@@ -49,6 +50,7 @@ class SuggestedProduct extends Component {
                 <span className={classes.image}>
                     <img
                         alt={name}
+                        className={classes.thumbnail}
                         src={resourceUrl(small_image, {
                             type: 'image-product',
                             width: 60

pwa-devdocs/_drafts/useEventListener/index.md

@@ -0,0 +1,10 @@
+---
+title: useEventListener
+---
+
+<!--
+The reference doc content is generated automatically from the source code.
+To update this section, update the doc blocks in the source code
+-->
+
+{% include auto-generated/peregrine/src/hooks/useEventListener.md %}