From 89ab1579b006ce874458f789c61c48ebd50f8e06 Mon Sep 17 00:00:00 2001 From: Darren Ethier Date: Mon, 9 Mar 2020 08:24:56 -0400 Subject: [PATCH] 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 --- .../assets/js/base/hooks/index.js | 2 +- ...tem.js => use-store-cart-item-quantity.js} | 20 ++-- .../cart/full-cart/cart-line-item-row.js | 4 +- .../js/settings/shared/settings-init.js | 13 ++ .../assets/js/type-defs/cart.js | 111 ++++++++++++++++++ .../assets/js/type-defs/hooks.js | 3 +- .../assets/js/type-defs/settings.js | 56 +++++++++ 7 files changed, 194 insertions(+), 15 deletions(-) rename plugins/woocommerce-blocks/assets/js/base/hooks/{use-store-cart-item.js => use-store-cart-item-quantity.js} (83%) create mode 100644 plugins/woocommerce-blocks/assets/js/type-defs/settings.js diff --git a/plugins/woocommerce-blocks/assets/js/base/hooks/index.js b/plugins/woocommerce-blocks/assets/js/base/hooks/index.js index 812e1e95d78..2f36d841964 100644 --- a/plugins/woocommerce-blocks/assets/js/base/hooks/index.js +++ b/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'; diff --git a/plugins/woocommerce-blocks/assets/js/base/hooks/use-store-cart-item.js b/plugins/woocommerce-blocks/assets/js/base/hooks/use-store-cart-item-quantity.js similarity index 83% rename from plugins/woocommerce-blocks/assets/js/base/hooks/use-store-cart-item.js rename to plugins/woocommerce-blocks/assets/js/base/hooks/use-store-cart-item-quantity.js index 537a7f42235..09af702e6ec 100644 --- a/plugins/woocommerce-blocks/assets/js/base/hooks/use-store-cart-item.js +++ b/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, }; }; diff --git a/plugins/woocommerce-blocks/assets/js/blocks/cart-checkout/cart/full-cart/cart-line-item-row.js b/plugins/woocommerce-blocks/assets/js/blocks/cart-checkout/cart/full-cart/cart-line-item-row.js index 78712a9ad07..a36acc839d8 100644 --- a/plugins/woocommerce-blocks/assets/js/blocks/cart-checkout/cart/full-cart/cart-line-item-row.js +++ b/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; diff --git a/plugins/woocommerce-blocks/assets/js/settings/shared/settings-init.js b/plugins/woocommerce-blocks/assets/js/settings/shared/settings-init.js index 82a3f26ae4e..af4b8b70d8a 100644 --- a/plugins/woocommerce-blocks/assets/js/settings/shared/settings-init.js +++ b/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, diff --git a/plugins/woocommerce-blocks/assets/js/type-defs/cart.js b/plugins/woocommerce-blocks/assets/js/type-defs/cart.js index 1094569adca..9a24ab16251 100644 --- a/plugins/woocommerce-blocks/assets/js/type-defs/cart.js +++ b/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 * diff --git a/plugins/woocommerce-blocks/assets/js/type-defs/hooks.js b/plugins/woocommerce-blocks/assets/js/type-defs/hooks.js index 4028a7871a8..f70f54eb1f1 100644 --- a/plugins/woocommerce-blocks/assets/js/type-defs/hooks.js +++ b/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 {}; diff --git a/plugins/woocommerce-blocks/assets/js/type-defs/settings.js b/plugins/woocommerce-blocks/assets/js/type-defs/settings.js new file mode 100644 index 00000000000..0c8802ccbfe --- /dev/null +++ b/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} 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 {};