@graphcommerce/docs 8.1.0-canary.3 → 8.1.0-canary.5

package/CHANGELOG.md

@@ -1,8 +1,63 @@
 # Change Log
 
-## 8.1.0-canary.3
+## 8.1.0-canary.5
 
-## 8.1.0-canary.2
+## 8.0.6-canary.4
+
+## 8.0.6-canary.3
+
+## 8.0.6-canary.2
+
+## 8.0.6-canary.1
+
+## 8.0.6-canary.0
+
+### Patch Changes
+
+- [#2196](https://github.com/graphcommerce-org/graphcommerce/pull/2196) [`84c50e4`](https://github.com/graphcommerce-org/graphcommerce/commit/84c50e49a1a7f154d4a8f4045c37e773e20283ad) - Allow Lingui to use linguiLocale with country identifiers like `en-us`, it would always load `en` in this case. Introced a new `useLocale` hook to use the correct locale string to use in Intl methods.
+  ([@paales](https://github.com/paales))
+
+## 8.0.5
+
+## 8.0.5-canary.10
+
+## 8.0.5-canary.9
+
+## 8.0.5-canary.8
+
+## 8.0.5-canary.7
+
+## 8.0.5-canary.6
+
+## 8.0.5-canary.5
+
+## 8.0.5-canary.4
+
+## 8.0.5-canary.3
+
+## 8.0.5-canary.2
+
+## 8.0.5-canary.1
+
+## 8.0.5-canary.0
+
+## 8.0.4
+
+## 8.0.4-canary.1
+
+## 8.0.4-canary.0
+
+## 8.0.3
+
+## 8.0.3-canary.6
+
+## 8.0.3-canary.5
+
+## 8.0.3-canary.4
+
+## 8.0.3-canary.3
+
+## 8.0.3-canary.2
 
 ## 8.0.3-canary.1
 

package/framework/config.md

@@ -1,4 +1,12 @@
 <!-- Automatically generated from Config.graphqls -->
+### DatalayerConfig
+
+GoogleDatalayerConfig to allow enabling certain aspects of the datalayer
+
+#### coreWebVitals: boolean
+
+Enable core web vitals tracking for GraphCommerce
+
 # GraphCommerce configuration system
 
 Global GraphCommerce configuration can be configured in your `graphcommerce.config.js` file
@@ -58,7 +66,7 @@ Examples:
 
 You can export configuration by running `yarn graphcommerce export-config`
 
-## Extending the configuration in your  project
+## Extending the configuration in your project
 
 Create a graphql/Config.graphqls file in your project and extend the GraphCommerceConfig, GraphCommerceStorefrontConfig inputs to add configuration.
 
@@ -159,6 +167,8 @@ customer requires email confirmation.
 This value should match Magento 2's configuration value for
 `customer/create_account/confirm` and should be removed once we can query
 
+#### dataLayer: [DatalayerConfig](#DatalayerConfig)
+
 #### debug: [GraphCommerceDebugConfig](#GraphCommerceDebugConfig)
 
 Debug configuration for GraphCommerce
@@ -334,7 +344,9 @@ All storefront configuration for the project
 
 #### locale: string (required)
 
-Must be a locale string https://www.unicode.org/reports/tr35/tr35-59/tr35.html#Identifiers
+Must be a [locale string](https://www.unicode.org/reports/tr35/tr35-59/tr35.html#Identifiers) for automatic redirects to work.
+
+This value can be used as a sub-path identifier only, make sure linguiLocale is configured for each URL.
 
 #### magentoStoreCode: string (required)
 
@@ -390,7 +402,9 @@ Add a gcms-locales header to make sure queries return in a certain language, can
 
 #### linguiLocale: string
 
-Specify a custom locale for to load translations.
+Specify a custom locale for to load translations. Must be lowercase valid locale.
+
+This value is also used for the Intl.
 
 ### MagentoConfigurableVariantValues
 

package/framework/plugins-react.md

@@ -1,7 +1,7 @@
 # Plugins GraphCommerce
 
-GraphCommerce's plugin system allows you to extend GraphCommerce's built-in
-components or functions with your own logic.
+GraphCommerce's plugin system allows you to extend or replace GraphCommerce's
+built-in components or functions with your own logic.
 
 - No runtime overhead: The plugin system is fully implemented in webpack and
 - Easy plugin creation: Configuration should happen in the plugin file, not a
@@ -13,10 +13,11 @@ components or functions with your own logic.
 A plugin is a way to modify React Components or a Function by wrapping them,
 without having to modify the code directly.
 
-For the M2 people: Think of around plugins, but without configuration files and
-no performance penalty.
+> For the M2 people: Think of around plugins, but without configuration files
+> and no performance penalty.
 
-GraphCommerce has two kinds of plugins, React Component plugins and Function
+GraphCommerce has three kinds of plugins, component plugins, function plugins
+and replacement plugins.
 
 React Component plugins, which can be used to:
 
@@ -33,103 +34,117 @@ Function plugins, which can be used to:
 - Modify the arguments of a function
 - Skip calling the original function conditionally
 
-## How do I write a React Component plugin?
+Replacement plugins, which can be used to:
+
+- Replace any export with your own implementation
+- Replace an internal component used by another internal component with your own
+  implementation.
+
+## How do I write a component plugin?
 
 In this example we're going to add some text to list items, just like the text
 ‘BY GC’ that can seen in the demo on
 [category pages](https://graphcommerce.vercel.app/en/women/business).
 
-1. Create a new file in `/plugins/ProductListItemByGC.tsx` with the following
-   contents:
-
-   ```tsx
-   import type { ProductListItem } from '@graphcommerce/magento-product'
-   import type { ReactPlugin } from '@graphcommerce/next-config'
-   import { Typography } from '@mui/material'
-
-   export const component = 'ProductListItem' // Component to extend, required
-   export const exported = '@graphcommerce/magento-product' // Location where the component is exported, required
-
-   const ListPlugin: ReactPlugin<typeof ProductListItem> = (props) => {
-     // Prev in this case is ProductListItem, you should be able to see this if you log it.
-     const { Prev, ...rest } = props
-     return (
-       <Prev
-         {...rest}
-         subTitle={
-           <Typography component='span' variant='caption'>
-             Plugin!
-           </Typography>
-         }
-       />
-     )
-   }
-   export const Plugin = ListPlugin // An export with the name Plugin, required
-   ```
-
-2. Trigger the 'interceptor generation' so GraphCommerce knows of the existence
-   of your plugin. To enable: Modify the page that you expect the plugin to
-   occur on. In this case modify `pages/[...url].tsx` by adding a few linebreaks
-   and save the file
-
-   If everything went as expected you should see `Plugin!` below the product
-   name. If that doesn't work try restarting the dev server.
-
-3. Happy programming!
-
-4. You can enable debug mode in your graphcommerce.config.js:
-
-   ```js
-   const config = {
-     debug: {
-       pluginStatus: true,
-     },
-   }
-   ```
+Create a new file in `/plugins/MyProductListItemPlugin.tsx` with the following
+contents:
 
-## How does it work?
+```tsx
+import type { ProductListItemProps } from '@graphcommerce/magento-product'
+import type { PluginConfig, PluginProps } from '@graphcommerce/next-config'
+import { Typography } from '@mui/material'
+
+export const config: PluginConfig = {
+  type: 'component',
+  module: '@graphcommerce/magento-product',
+}
+
+// Exported name should be the same as the function you want to create a plugin for
+export const ProductListItem = (props: PluginProps<ProductListItemProps>) => {
+  // Prev in this case is ProductListItem, you should be able to see this if you log it.
+  // Prev needs to be rendered and {...rest} always needs to be passed.
+  const { Prev, ...rest } = props
+  return (
+    <Prev
+      {...rest}
+      subTitle={
+        <Typography component='span' variant='caption'>
+          Plugin!
+        </Typography>
+      }
+    />
+  )
+}
+```
+
+## How do I write a function plugin?
+
+Create a new file in `/plugins/myFunctionPlugin.tsx` with the following
+contents:
+
+```tsx
+import type { graphqlConfig as graphqlConfigType } from '@graphcommerce/graphql'
+import type { FunctionPlugin, PluginConfig } from '@graphcommerce/next-config'
+import { createStoreLink } from '../link/createStoreLink'
+
+export const config: PluginConfig = {
+  type: 'function',
+  module: '@graphcommerce/graphql',
+}
+
+// Exported name should be the same as the function you want to create a plugin for
+export const graphqlConfig: FunctionPlugin<typeof graphqlConfigType> = (
+  prev,
+  conf,
+) => {
+  const results = prev(conf)
+  return {
+    ...results,
+    links: [...results.links, createStoreLink(conf.storefront.locale)],
+  }
+}
+```
 
-After the creation of the plugin file GraphCommerce will create an interceptor
-file to load you plugin. To see what has happened, open the
-`node_modules/@graphcommerce/magento-product/index.interceptor.tsx` and you
-should see something like:
+## How do I write a replacement plugin?
 
 ```tsx
-export * from '.'
-import { Plugin as AwesomeProductListItem } from '../../examples/magento-graphcms/plugins/AwesomeProductListItem'
-import { ComponentProps } from 'react'
-import { ProductListItem as ProductListItemBase } from '.'
-
-/**
- * Interceptor for `<ProductListItem/>` with these plugins:
- *
- * - `../../examples/magento-graphcms/plugins/AwesomeProductListItem`
- */
-type ProductListItemProps = ComponentProps<typeof ProductListItemBase>
-
-function AwesomeProductListItemInterceptor(props: ProductListItemProps) {
-  return <AwesomeProductListItem {...props} Prev={ProductListItemBase} />
+import { ProductCountProps } from '@graphcommerce/magento-product'
+import { PluginConfig } from '@graphcommerce/next-config'
+
+export const config: PluginConfig = {
+  type: 'replace',
+  module: '@graphcommerce/magento-product',
+}
+
+export function ProductListCount(props: ProductCountProps) {
+  const { total_count } = props
+  return <div>{total_count}</div>
 }
-export const ProductListItem = AwesomeProductListItemInterceptor
 ```
 
-If you read the interceptor file from the bottom up, you see:
+Note: The original component can not be used, because we completely rewrite the
+export. If you want to do this, a component or function plugin is a better
+choice.
 
-- The original `ProductListItem` is replaced with
-  `AwesomeProductListItemInterceptor`
-- `AwesomeProductListItemInterceptor` is a react component which renders
-  `AwesomeProductListItem` with a `Prev` prop.
-- `AwesomeProductListItem` is the plugin you just created.
-- `Prev` is the original `ProductListItem` (renamed to `ProductListItemBase`)
-- `ProductListItemProps` are the props of the original `ProductListItem` and
-  thus your plugin is automatically validated by TypeScript.
+## How do make sure my plugin is applied?
 
-So in conclusion, a plugin is a react component that renders the original
-component with a `Prev` prop. The `Prev` prop is the original component.
+When creating the plugin for the first time you need to restart your dev server
+once. After the first generation of the interceptor file, the file is watched
+and changes will be picked up.
 
-When opening the React debugger you can see the plugin wrapped.
+If everything went as expected you should see your plugin applied correct.
 
-<img width="263" alt="Scherm­afbeelding 2023-03-15 om 12 16 59" src="https://user-images.githubusercontent.com/1244416/225293707-1ce1cd87-108b-4f28-b9ee-0c5d68d9a886.png" />
+## How can I debug to see which plugins are applied?
+
+You can enable debug mode in your graphcommerce.config.js:
+
+```js
+const config = {
+  debug: { pluginStatus: true },
+}
+```
+
+Or use `GC_DEBUG_PLUGIN_STATUS=true` in your environment variables.
 
 ### How are plugins loaded?
 
@@ -141,33 +156,66 @@ Package locations are the root and all packages with `graphcommerce` in the name
 (This means all `@graphcommerce/*` packages and
 `@your-company/graphcommerce-plugin-name`)
 
-The Webpack plugin statically analyses the plugin file to find `component`,
-`exported` and `ifConfig` and extracts that information.
-
-### Possible use cases
+The Webpack plugin statically analyses the plugin files to find any valid
+configuration. This is then used to create the interceptors.
 
-In the examples above we've extended the product list items, but it should also
-work for other things such as:
+### Conditionally include a plugin
 
-- Googletagmanager
-- Googleanalytics
-- Google recaptcha
-- Compare functionality
-- Wishlist functionality?
-- Abstraction between GraphCommerce and Backends? (Magento, BigCommerce,
-  CommerceTools, etc.)
+Provide an ifConfig in the plugin config to conditionally include a plugin if a
+[configuration](./config.md) value is truthy:
 
-### Conditionally include a plugin
+```tsx
+export const config: PluginConfig = {
+  type: 'component',
+  module: '@graphcommerce/magento-product',
+  ifConfig: 'demoMode',
+}
+```
 
-Provide an ifConfig export in the plugin that will only include the plugin if a
-[configuration](./config.md) value is truthy.
+Or checking on a value:
 
 ```tsx
-import type { IfConfig } from '@graphcommerce/next-config'
-export const ifConfig: IfConfig = 'googleAnalytics'
+export const config: PluginConfig<'compareVariant'> = {
+  type: 'component',
+  module: '@graphcommerce/magento-product',
+  ifConfig: ['compareVariant', 'CHECKBOX'],
+}
 ```
 
 ### Plugin loading order
 
-A plugin is injected later than the dependencies of the package. So if a plugin
-is loaded to early, make sure the package has a dependency on the other package.
+The plugin loading order is determined by the order of the dependencies defined
+in the package.json. If the order isn't correct, make sure you've defined the
+correct dependencies in your package.json.
+
+Local plugins are closest to the original component, meaning that package
+specific plugins have already been called before your plugin is called.
+
+## How does it work?
+
+After the creation of the plugin file GraphCommerce will create an 'interceptor'
+for your file.
+
+To see the the created plugin for ProductListItem, '_Go to Definition_'
+(CMD/Ctrl+Click) on `<ProductListItem>` in
+`components/ProductListItems/productListRenderer.tsx`. You should now go to the
+`ProductListItem.interceptor.tsx` file.
+
+In this file the original `ProductListItem` is replaced with
+`PluginDemoProductListItemInterceptor`. The interceptor renders
+`<PluginDemoProductListItemSource />` with a `Prev` prop which is the plugin.
+
+The whole plugin 'chain' is constructed here and eventually ending up on
+`ProductListItemOriginal` which is the original component (but renamed).
+
+### Examples
+
+In the examples above we've extended the product list items, but it should also
+work for other things such as:
+
+- [Update the gallery when a configurable is selected](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/magento-product-configurable/plugins/ConfigurableProductPage/ConfigurableProductPageGallery.tsx)
+- [Insert the Google Recaptcha Script](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/googlerecaptcha/plugins/GrecaptchaGraphQLProvider.tsx)
+- [Activate Google Recaptcha when a form is loaded](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/googlerecaptcha/plugins/GrecaptchaApolloErrorSnackbar.tsx)
+- [Add a compare icon next to the cart icon](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/magento-compare/plugins/AddCompareFabNextToCart.tsx)
+- [Add a compare icon to the ProductListItem](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/magento-compare/plugins/CompareAbleProductListItem.tsx)
+- etc.

package/magento/multi-theme-multi-website.md

@@ -0,0 +1,130 @@
+# Multiple themes/brands with multiple websites
+
+When deciding how to develop multiple themes/brands, there are several
+gradations of customizability.
+
+Deciding on how to approach this is a trade-off between the amount of
+customizability and the amount of code duplication.
+
+## Gradations of modularization/thematization
+
+### Level 1: One codebase, one build. Differences are configured in GraphCommerceStorefrontConfig
+
+- Advantage: Simple, everything is easy to configure in the config.
+- Advantage: Upgrade once
+- Disadvantage: Not tree shakable (very large differences between brands can
+  become problematic)
+
+This requires discipline from the developer that we maintain the 'Single
+responsibility' principle for components. Components that actually serve two
+completely separate functionalities depending on the brand are not desirable.
+
+Create a Config.graphqls in your graphql directory with the following contents:
+
+```graphql
+enum ThemeName {
+  BRAND_1
+  BRAND_2
+}
+
+extend input GraphCommerceStorefrontConfig {
+  themeName: ThemeName!
+}
+```
+
+Applying a different theme based on the store configuration:
+
+```tsx
+// in _app.tsx
+const { themeName } = useStorefrontConfig()
+const theme = useMemo(() => {
+  if (themeName === 'BRAND_1') {
+    const brand1Palette = ...
+    return createThemeWithPalette(brand1Palette)
+  }
+}, [domain])
+```
+
+Applying a different component based on the store configuration:
+
+```tsx
+export function MyComponent() {
+  const { themeName } = useStorefrontConfig()
+
+  if (themeName === 'BRAND_1') return <Brand1Component>
+  return <Brand2Component {...}/>
+}
+```
+
+### Level 2: One codebase, multiple builds. Differences are configured in GraphCommerceConfig
+
+- Advantage: Tree shakable
+- Advantage: Upgrade once
+- Disadvantage: Multiple builds
+- Disadvantage: Multiple deployments
+
+Create a Config.graphqls in your graphql directory with the following contents:
+
+```graphql
+enum ThemeName {
+  BRAND_1
+  BRAND_2
+}
+
+extend input GraphCommerceConfig {
+  themeName: ThemeName!
+}
+```
+
+During deploy you'd have to set the theme that is being build:
+`GC_THEME_NAME=BRAND_1`.
+
+Create a separate theme for each brand:
+
+```tsx
+let theme: Theme
+if (import.meta.graphCommerce.theme === 'BRAND_1') {
+  const brand1Palette = ...
+  theme = createThemeWithPalette(brand1Palette)
+} else if (import.meta.graphCommerce.theme === 'BRAND_2') {
+  const brand2Palette = ...
+  theme = createThemeWithPalette(brand2Palette)
+}
+theme.components = createOverrides(theme) as Components
+
+export { theme }
+```
+
+Replace/Plugin a component based on the theme:
+
+```tsx
+// plugins/BRAND_1/magento-product/Replace.tsx
+export const config: PluginConfig<'themeName'> = {
+  type: 'replace',
+  module: '@graphcommerce/magento-product',
+  ifConfig: ['themeName', 'BRAND_1'],
+}
+
+export function ProductListItem(props: ProductListItemProps) {
+  //...
+}
+```
+
+Now when a new brand is added you can copy-paste the BRAND_1 directory and you
+should be able to modify the components to your liking.
+
+<!--
+### Level 3: Monorepo with one graphcommerce instance, but a separate generic package per brand.
+
+- Advantage: Tree shakable
+- Advantage: Full flexibility
+- Disadvantage: Files are copied per brand.
+- Disadvantage: Upgrades are duplicated
+- Disadvantage: Projects diverge quickly and become hard to maintain.
+
+This requires you to modify all imports of the examples directory, thus making
+upgrades more difficult. GraphCommerce does not offer a flexible solution for
+this.
+
+To achieve this we could: Offer a way to also handle `export * from 'my-brand'`
+in plugins. -->

package/package.json

@@ -2,10 +2,10 @@
   "name": "@graphcommerce/docs",
   "homepage": "https://www.graphcommerce.org/docs",
   "repository": "github:graphcommerce-org/graphcommerce/docs",
-  "version": "8.1.0-canary.3",
+  "version": "8.1.0-canary.5",
   "sideEffects": true,
   "peerDependencies": {
-    "@graphcommerce/prettier-config-pwa": "^8.1.0-canary.3"
+    "@graphcommerce/prettier-config-pwa": "^8.1.0-canary.5"
   },
   "prettier": "@graphcommerce/prettier-config-pwa"
 }

package/upgrading/graphcommerce-8-to-9.md

@@ -0,0 +1,34 @@
+# Upgrading from GraphCommerce 7 to 8
+
+Depending on the amounts of customisations you've made, there are some manual
+steps. Please follow the regular [upgrade steps first](./readme.md).
+
+1. ReactPlugin TypeScript definition is removed.
+
+## 1. ReactPlugin TypeScript definition is removed
+
+The `ReactPlugin` TypeScript definition has been removed and only `PluginProps`
+is available.
+
+Replace
+
+```tsx
+const MyPlugin: ReactPlugin<typeof OriginalComponent> = (props) => {
+  const { Prev, ...rest } = props
+  return <Prev {...rest} />
+}
+export const Plugin = MyPlugin
+```
+
+Now becomes:
+
+```tsx
+const MyPlugin = (props: PluginProps<OriginalComponentProps>) => {
+  const { Prev, ...rest } = props
+  return <Prev {...rest} />
+}
+export const Plugin = MyPlugin
+```
+
+There is a new plugin configuration method by using
+`export config: PluginConfig = {}`.