Followup for useStoreCartItem work (change hook name and improve typedefs) (https://github.com/woocommerce/woocommerce-blocks/pull/1900)

* add typedefs for CartItem

* remove cartItem from StoreCartItem typedef

* Implement new typedef and fix defaults as well as returned object.

Now that `cartItem` is only used internally, the default set on the state only has to be the properties required internally in the hook.

* add typedefs for shared settings and implement typedef comments.

* change hook name

plugins/woocommerce-blocks/assets/js/base/hooks/index.js

@@ -2,7 +2,7 @@ export * from './use-query-state';
 export * from './use-shallow-equal';
 export * from './use-store-cart';
 export * from './use-store-cart-coupons';
-export * from './use-store-cart-item';
+export * from './use-store-cart-item-quantity';
 export * from './use-store-products';
 export * from './use-store-notices';
 export * from './use-collection';

plugins/woocommerce-blocks/assets/js/base/hooks/use-store-cart-item-quantity.js

@@ -1,5 +1,3 @@
-/** @typedef { import('@woocommerce/type-defs/hooks').StoreCartItem } StoreCartItem */
-
 /**
  * External dependencies
  */
@@ -13,6 +11,11 @@ import { useDebounce } from 'use-debounce';
  */
 import { useStoreCart } from './use-store-cart';
 
+/**
+ * @typedef {import('@woocommerce/type-defs/hooks').StoreCartItemQuantity} StoreCartItemQuantity
+ * @typedef {import('@woocommerce/type-defs/cart').CartItem} CartItem
+ */
+
 /**
  * This is a custom hook for loading the Store API /cart/ endpoint and
  * actions for removing or changing item quantity.
@@ -20,18 +23,16 @@ import { useStoreCart } from './use-store-cart';
  * @see https://github.com/woocommerce/woocommerce-gutenberg-products-block/tree/master/src/RestApi/StoreApi
  *
  * @param {string} cartItemKey Key for a cart item.
- * @return {StoreCartItem} An object exposing data and actions relating to cart items.
+ * @return {StoreCartItemQuantity} An object exposing data and actions relating to cart items.
  */
-export const useStoreCartItem = ( cartItemKey ) => {
+export const useStoreCartItemQuantity = ( cartItemKey ) => {
 	const { cartItems, cartIsLoading } = useStoreCart();
+	/**
+	 * @type {[CartItem, function( CartItem ):undefined]}
+	 */
 	const [ cartItem, setCartItem ] = useState( {
 		key: '',
-		isLoading: true,
-		cartData: {},
 		quantity: 0,
-		isPending: false,
-		changeQuantity: () => void null,
-		removeItem: () => void null,
 	} );
 	// Store quantity in hook state. This is used to keep the UI
 	// updated while server request is updated.
@@ -78,6 +79,5 @@ export const useStoreCartItem = ( cartItemKey ) => {
 		changeQuantity,
 		removeItem,
 		isLoading: cartIsLoading,
-		cartItem,
 	};
 };

plugins/woocommerce-blocks/assets/js/blocks/cart-checkout/cart/full-cart/cart-line-item-row.js

@@ -7,7 +7,7 @@ import PropTypes from 'prop-types';
 import QuantitySelector from '@woocommerce/base-components/quantity-selector';
 import FormattedMonetaryAmount from '@woocommerce/base-components/formatted-monetary-amount';
 import { getCurrency, formatPrice } from '@woocommerce/base-utils';
-import { useStoreCartItem } from '@woocommerce/base-hooks';
+import { useStoreCartItemQuantity } from '@woocommerce/base-hooks';
 import { Icon, trash } from '@woocommerce/icons';
 
 /**
@@ -36,7 +36,7 @@ const CartLineItemRow = ( { lineItem = {} } ) => {
 		changeQuantity,
 		removeItem,
 		isPending: itemQuantityDisabled,
-	} = useStoreCartItem( key );
+	} = useStoreCartItemQuantity( key );
 
 	const currency = getCurrency();
 	const regularPrice = parseInt( prices.regular_price, 10 ) * quantity;

plugins/woocommerce-blocks/assets/js/settings/shared/settings-init.js

@@ -1,3 +1,6 @@
+/**
+ * @type {import("@woocommerce/type-defs/settings").WooCommerceSharedSettings}
+ */
 const defaults = {
 	adminUrl: '',
 	countries: [],
@@ -21,19 +24,29 @@ const defaults = {
 	wcAssetUrl: '',
 };
 
+// @ts-ignore wcSettings is window global
 const globalSharedSettings = typeof wcSettings === 'object' ? wcSettings : {};
 
 // Use defaults or global settings, depending on what is set.
+/**
+ * @type {import("@woocommerce/type-defs/settings").WooCommerceSharedSettings}
+ */
 const allSettings = {
 	...defaults,
 	...globalSharedSettings,
 };
 
+/**
+ * @type {import("@woocommerce/type-defs/settings").WooCommerceSiteCurrency}
+ */
 allSettings.currency = {
 	...defaults.currency,
 	...allSettings.currency,
 };
 
+/**
+ * @type {import("@woocommerce/type-defs/settings").WooCommerceSiteLocale}
+ */
 allSettings.locale = {
 	...defaults.locale,
 	...allSettings.locale,

plugins/woocommerce-blocks/assets/js/type-defs/cart.js

@@ -45,6 +45,117 @@
  * @property {string} email      The email for the billing address
  */
 
+/**
+ * @typedef {Object} CartItemImage
+ *
+ * @property {number} id        Image id.
+ * @property {string} src       Full size image URL.
+ * @property {string} thumbnail Thumbnail URL.
+ * @property {string} srcset    Thumbnail srcset for responsive image.
+ * @property {string} sizes     Thumbnail sizes for responsive images.
+ * @property {string} name      Image name.
+ * @property {string} alt       Image alternative text.
+ */
+
+/**
+ * @typedef {Object} CartItemVariation
+ *
+ * @property {string} attribute Variation attribute name.
+ * @property {string} value     Variation attribute value.
+ */
+
+/**
+ * @typedef {Object} CartItemTotals
+ *
+ * @property {string} currency_code               The ISO code for the currency.
+ * @property {number} currency_minor_unit         The precision (decimal
+ *                                                places).
+ * @property {string} currency_symbol             The symbol for the currency
+ *                                                (eg '$')
+ * @property {string} currency_prefix             Price prefix for the currency
+ *                                                which can be used to format
+ *                                                returned prices.
+ * @property {string} currency_suffix             Price suffix for the currency
+ *                                                which can be used to format
+ *                                                returned prices.
+ * @property {string} currency_decimal_separator  The string used for the
+ *                                                decimal separator.
+ * @property {string} currency_thousand_separator The string used for the
+ *                                                thousands separator.
+ * @property {string} line_subtotal               Line subtotal (the price of
+ *                                                the product before coupon
+ *                                                discounts have been applied).
+ * @property {string} line_subtotal_tax           Line subtotal tax.
+ * @property {string} line_total                  Line total (the price of the
+ *                                                product after coupon
+ *                                                discounts have been applied).
+ * @property {string} line_total_tax              Line total tax.
+ */
+
+/**
+ * @typedef {Object} CartItemPrices
+ *
+ * @property {string} currency_code               The ISO code for the currency.
+ * @property {number} currency_minor_unit         The precision (decimal
+ *                                                places).
+ * @property {string} currency_symbol             The symbol for the currency
+ *                                                (eg '$')
+ * @property {string} currency_prefix             Price prefix for the currency
+ *                                                which can be used to format
+ *                                                returned prices.
+ * @property {string} currency_suffix             Price suffix for the currency
+ *                                                which can be used to format
+ *                                                returned prices.
+ * @property {string} currency_decimal_separator  The string used for the
+ *                                                decimal separator.
+ * @property {string} currency_thousand_separator The string used for the
+ *                                                thousands separator.
+ * @property {string} price                       Current product price.
+ * @property {string} regular_price               Regular product price.
+ * @property {string} sale_price                  Sale product price, if
+ *                                                applicable.
+ * @property {Object} price_range                 Price range, if applicable.
+ * @property {string} price_range.min_amount      Price min amount in range.
+ * @property {string} price_range.max_amount      Price max amount in range.
+ *
+ */
+
+/**
+ * @typedef {Object} CartItem
+ *
+ * @property {string}              key                 Unique identifier for the
+ *                                                     item within the cart.
+ * @property {number}              id                  The cart item product or
+ *                                                     variation id.
+ * @property {number}              quantity            The quantity of this item
+ *                                                     in the cart.
+ * @property {string}              name                Product name.
+ * @property {string}              summary             A short summary (or
+ *                                                     excerpt from the full
+ *                                                     description).
+ * @property {string}              short_description   Product short description
+ *                                                     in HTML format.
+ * @property {string}              sku                 Stock keeping unit, if
+ *                                                     applicable.
+ * @property {number|null}         low_stock_remaining Quantity left in stock if
+ *                                                     stock is low, or null if
+ *                                                     not applicable.
+ * @property {boolean}             sold_individually   If true, only one item of
+ *                                                     this product is allowed
+ *                                                     for purchase in a single
+ *                                                     order.
+ * @property {string}              permalink           Product URL.
+ * @property {CartItemImage[]}     images              List of images attached
+ *                                                     to the cart item
+ *                                                     product/variation.
+ * @property {CartItemVariation[]} variation           Chosen attributes (for
+ *                                                     variations).
+ * @property {CartItemTotals}      totals              Item total amounts
+ *                                                     provided using the
+ *                                                     smallest unit of the
+ *                                                     currency.
+ */
+
 /**
  * @typedef {Object} CartData
  *

plugins/woocommerce-blocks/assets/js/type-defs/hooks.js

@@ -29,7 +29,7 @@
  */
 
 /**
- * @typedef {Object} StoreCartItem
+ * @typedef {Object} StoreCartItemQuantity
  *
  * @property {boolean}  isLoading       True when cart items are being
  *                                      loaded.
@@ -38,7 +38,6 @@
  * @property {Function} changeQuantity  Callback for changing quantity of item
  *                                      in cart.
  * @property {Function} removeItem      Callback for removing a cart item.
- * @property {Object}   cartItem        The cartItem retrieved.
  */
 
 export {};

plugins/woocommerce-blocks/assets/js/type-defs/settings.js

@@ -0,0 +1,56 @@
+/**
+ * @typedef {Object} WooCommerceSiteCurrency
+ *
+ * @property {string} code               The ISO code for the currency.
+ * @property {number} precision          The precision (decimal places).
+ * @property {string} symbol             The symbol for the currency (eg '$')
+ * @property {string} symbolPosition     The position for the symbol ('left',
+ *                                       or 'right')
+ * @property {string} decimalSeparator   The string used for the decimal
+ *                                       separator.
+ * @property {string} thousandSeparator The string used for the thousands
+ *                                       separator.
+ * @property {string} priceFormat        The format string use for displaying
+ *                                       an amount in this currency.
+ */
+
+/**
+ * @typedef {Object} WooCommerceSiteLocale
+ *
+ * @property {string}        siteLocale    The locale string for the current
+ *                                         site.
+ * @property {string}        userLocale    The locale string for the current
+ *                                         user.
+ * @property {Array<string>} weekdaysShort An array of short weekday strings
+ *                                         in the current user's locale.
+ */
+
+/**
+ * @typedef {Object} WooCommerceSharedSettings
+ *
+ * @property {string}                  adminUrl         The url for the current
+ *                                                      site's dashboard.
+ * @property {Object}                  countries        An object of countries
+ *                                                      where the keys are
+ *                                                      Country codes and values
+ *                                                      are country names
+ *                                                      localized for the site's
+ *                                                      current language.
+ * @property {WooCommerceSiteCurrency} currency         The current site
+ *                                                      currency object.
+ * @property {string}                  defaultDateRange The default date range
+ *                                                      query string to use.
+ * @property {WooCommerceSiteLocale}   locale           Locale information for
+ *                                                      the site.
+ * @property {Object}                  orderStatuses    An object of order
+ *                                                      statuses indexed by
+ *                                                      status key and localized
+ *                                                      status value.
+ * @property {string}                  siteTitle        The current title of the
+ *                                                      site.
+ * @property {string}                  wcAssetUrl       The url to the assets
+ *                                                      directory for the
+ *                                                      WooCommerce plugin.
+ */
+
+export {};