@graphcommerce/docs 6.2.0-canary.9 → 6.2.0-canary.90

package/CHANGELOG.md

@@ -1,5 +1,195 @@
 # Change Log
 
+## 6.2.0-canary.90
+
+### Patch Changes
+
+- [#2034](https://github.com/graphcommerce-org/graphcommerce/pull/2034) [`6fca47484`](https://github.com/graphcommerce-org/graphcommerce/commit/6fca474847fe52f004a6ac0abbd88492512b46ad) - Pre-resolve the customFetch in mesh config ([@paales](https://github.com/paales))
+
+## 6.2.0-canary.89
+
+## 6.2.0-canary.88
+
+## 6.2.0-canary.87
+
+### Patch Changes
+
+- [#2022](https://github.com/graphcommerce-org/graphcommerce/pull/2022) [`0495db84d`](https://github.com/graphcommerce-org/graphcommerce/commit/0495db84d1d450750bd74b94a379b4e7764a5753) - add documentation for the GraphCommerceStorefrontConfig gallery option. ([@carlocarels90](https://github.com/carlocarels90))
+
+## 6.2.0-canary.86
+
+## 6.2.0-canary.85
+
+## 6.2.0-canary.84
+
+## 6.2.0-canary.83
+
+## 6.2.0-canary.82
+
+## 6.2.0-canary.81
+
+## 6.2.0-canary.80
+
+## 6.2.0-canary.79
+
+## 6.2.0-canary.78
+
+## 6.2.0-canary.77
+
+## 6.2.0-canary.76
+
+## 6.2.0-canary.75
+
+## 6.2.0-canary.74
+
+## 6.2.0-canary.73
+
+### Patch Changes
+
+- [#1978](https://github.com/graphcommerce-org/graphcommerce/pull/1978) [`0c91ac1f7`](https://github.com/graphcommerce-org/graphcommerce/commit/0c91ac1f70f58dec418e945fc4a6a8c6732cc21e) - When a user selects a variant, it will switch the values on the configurable page with the values of the configured variant. Enabling options here will allow switching of those variants. ([@carlocarels90](https://github.com/carlocarels90))
+
+## 6.2.0-canary.72
+
+## 6.2.0-canary.71
+
+## 6.2.0-canary.70
+
+## 6.2.0-canary.69
+
+## 6.2.0-canary.68
+
+## 6.2.0-canary.67
+
+## 6.2.0-canary.66
+
+## 6.2.0-canary.65
+
+## 6.2.0-canary.64
+
+## 6.2.0-canary.63
+
+## 6.2.0-canary.62
+
+## 6.2.0-canary.61
+
+## 6.2.0-canary.60
+
+## 6.2.0-canary.59
+
+## 6.2.0-canary.58
+
+## 6.2.0-canary.57
+
+## 6.2.0-canary.56
+
+## 6.2.0-canary.55
+
+## 6.2.0-canary.54
+
+## 6.2.0-canary.53
+
+## 6.2.0-canary.52
+
+## 6.2.0-canary.51
+
+### Patch Changes
+
+- [`2f479c830`](https://github.com/graphcommerce-org/graphcommerce/commit/2f479c830e84137b739d83bc6dd1e36a6e299e3a) - Added advise about URL suffixes ([@paales](https://github.com/paales))
+
+## 6.2.0-canary.50
+
+## 6.2.0-canary.49
+
+### Patch Changes
+
+- [#1959](https://github.com/graphcommerce-org/graphcommerce/pull/1959) [`d0809b132`](https://github.com/graphcommerce-org/graphcommerce/commit/d0809b132a0e4cbdfeb86164f6c16a89ebecd987) - Added support for default values in the Config.graphqls files for the documentation ([@JoshuaS98](https://github.com/JoshuaS98))
+
+## 6.2.0-canary.48
+
+## 6.2.0-canary.47
+
+## 6.2.0-canary.46
+
+## 6.2.0-canary.45
+
+## 6.2.0-canary.44
+
+## 6.2.0-canary.43
+
+## 6.2.0-canary.42
+
+## 6.2.0-canary.41
+
+## 6.2.0-canary.40
+
+## 6.2.0-canary.39
+
+### Patch Changes
+
+- [#1957](https://github.com/graphcommerce-org/graphcommerce/pull/1957) [`cb3c82163`](https://github.com/graphcommerce-org/graphcommerce/commit/cb3c82163c32768f977b85c21b029ead354847af) - Docs were directly applied to the config.md which is autogenerated ([@paales](https://github.com/paales))
+
+## 6.2.0-canary.38
+
+## 6.2.0-canary.37
+
+## 6.2.0-canary.36
+
+## 6.2.0-canary.35
+
+## 6.2.0-canary.34
+
+## 6.2.0-canary.33
+
+## 6.2.0-canary.32
+
+## 6.2.0-canary.31
+
+## 6.2.0-canary.30
+
+## 6.2.0-canary.29
+
+## 6.2.0-canary.28
+
+## 6.2.0-canary.27
+
+## 6.2.0-canary.26
+
+## 6.2.0-canary.25
+
+## 6.2.0-canary.24
+
+## 6.2.0-canary.23
+
+## 6.2.0-canary.22
+
+## 6.2.0-canary.21
+
+## 6.2.0-canary.20
+
+## 6.2.0-canary.19
+
+## 6.2.0-canary.18
+
+### Patch Changes
+
+- [#1933](https://github.com/graphcommerce-org/graphcommerce/pull/1933) [`e644887a7`](https://github.com/graphcommerce-org/graphcommerce/commit/e644887a75a3801a8b0dcf39558f56110a51d774) - Updated ReCAPTCHA docs ([@bramvanderholst](https://github.com/bramvanderholst))
+
+## 6.2.0-canary.17
+
+## 6.2.0-canary.16
+
+## 6.2.0-canary.15
+
+## 6.2.0-canary.14
+
+## 6.2.0-canary.13
+
+## 6.2.0-canary.12
+
+## 6.2.0-canary.11
+
+## 6.2.0-canary.10
+
 ## 6.2.0-canary.9
 
 ## 6.2.0-canary.8

package/framework/config.md

@@ -115,10 +115,29 @@ When Magento's StoreConfig adds this value, this can be replaced.
 
 Use compare functionality
 
-#### `compareVariant: [CompareVariant](#CompareVariant)`
+#### `compareVariant: [CompareVariant](#CompareVariant) (default: ICON)`
 
-By default the compare feature is denoted with a 'compare icon' (2 arrows facing one another).
-This may be fine for experienced users, but for more clarity it's also possible to present the compare feature as a checkbox accompanied by the 'Compare' label
+By default the compare feature is denoted with a 'compare ICON' (2 arrows facing one another).
+This may be fine for experienced users, but for more clarity it's also possible to present the compare feature as a CHECKBOX accompanied by the 'Compare' label
+
+#### `configurableVariantForSimple: Boolean (default: [object Object])`
+
+If a simple product is part of a Configurable product page, should the simple product be
+rendered as a configured option of the configurable product page?
+
+How does this work:
+
+When the `products(filters: { url_key: { eq: 'simple-product' } }) { ... }` query is ran,
+Magento also returns the Simple product and the Configurable product the simple belongs to.
+
+If that is the case we render the configurable product page instead of the simple product page but
+the options to select the simple product are pre-selected.
+
+#### `configurableVariantValues: [MagentoConfigurableVariantValues](#MagentoConfigurableVariantValues) (default: [object Object])`
+
+When a user selects a variant, it will switch the values on the configurable page with the values of the configured variant.
+
+Enabling options here will allow switching of those variants.
 
 #### `customerRequireEmailConfirmation: Boolean`
 
@@ -132,7 +151,7 @@ This value should match Magento 2's configuration value for
 
 Debug configuration for GraphCommerce
 
-#### `demoMode: Boolean`
+#### `demoMode: Boolean (default: true)`
 
 Enables some demo specific code that is probably not useful for a project:
 
@@ -150,9 +169,13 @@ To override the value for a specific locale, configure in i18n config.
 
 #### `googleRecaptchaKey: String`
 
-Google reCAPTCHA key, get from https://developers.google.com/recaptcha/docs/v3
+Google reCAPTCHA site key.
+When using reCAPTCHA, this value is required, even if you are configuring different values for each locale.
 
-This value is required even if you are configuring different values for each locale.
+Get a site key and a secret key from https://developers.google.com/recaptcha/docs/v3
+
+The secret key should be added in the Magento admin panel (Stores > Configuration > Security > Google ReCAPTCHA Storefront > reCAPTCHA v3 Invisible)
+ReCAPTCHA can then be enabled/disabled for the different forms, separately (Stores > Configuration > Security > Google ReCAPTCHA Storefront > Storefront)
 
 #### `googleTagmanagerId: String`
 
@@ -160,6 +183,10 @@ The Google Tagmanager ID to be used on the site.
 
 This value is required even if you are configuring different values for each locale.
 
+#### `hygraphProjectId: String`
+
+Hygraph Project ID. **Only used for migrations.**
+
 #### `hygraphWriteAccessEndpoint: String`
 
 Content API. **Only used for migrations.**
@@ -187,6 +214,12 @@ Project settings -> API Access -> Permanent Auth Tokens
   - Delete existing components
   - Update remote sources
   - Delete remote sources
+  - Read existing environments
+  - Read public content views
+  - Create public content views
+  - Update public content views
+  - Delete public content views
+  - Can see schema view
 
 ```
 GC_HYGRAPH_WRITE_ACCESS_ENDPOINT="https://...hygraph.com/v2/..."
@@ -210,6 +243,12 @@ Limit the static generation of SSG when building
 
 To enable next.js' preview mode, configure the secret you'd like to use.
 
+#### `productFiltersLayout: [ProductFiltersLayout](#ProductFiltersLayout) (default: DEFAULT)`
+
+Layout how the filters are rendered.
+DEFAULT: Will be rendered as horzontal chips on desktop and mobile
+SIDEBAR: Will be rendered as a sidebar on desktop and horizontal chips on mobile
+
 #### `productFiltersPro: Boolean`
 
 Product filters with better UI for mobile and desktop.
@@ -325,4 +364,23 @@ 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.
+
+### MagentoConfigurableVariantValues
+
+Options to configure which values will be replaced when a variant is selected on the product page.
+
+#### `content: Boolean`
+
+Use the name, description, short description and meta data from the configured variant
+
+#### `gallery: Boolean`
+
+This option enables the automatic update of product gallery images on the product page when a variant is selected,
+provided that the gallery images for the selected variant differ from the currently displayed images.
+
+#### `url: Boolean`
+
+When a variant is selected the URL of the product will be changed in the address bar.
+
+This only happens when the actual variant is can be accessed by the URL.

package/framework/favicon.md

@@ -35,6 +35,20 @@ to simplify the process of making correct favicons.
  <figcaption>Favicon sketch template</figcaption>
 </figure>
 
+## Open Graph preview image
+
+The Open Graph image is automaticly set for product and category pages if
+possible. For product pages the first gallary image will be used and for
+category pages the image uploaded to the `Category Image` attribute. If these
+images are not availale or on any of the other other pages a preview image will
+not be added unless added as `ogImage` prop to the `PageMeta`, `, CategoryMeta`
+or `ProductPageMeta` components.
+
+It is possible to enable a fallback image per route by setting the
+`ogImageUseFallback` prop to `true` on either the `PageMeta`, `, CategoryMeta`
+or `ProductPageMeta` components. The image used as fallback can be found at
+`/public/open-graph-image.jpg`
+
 ## Next steps
 
 - Lear more about [Static file serving](../framework/static-file-serving.md)

package/hygraph/cli.md

@@ -0,0 +1,63 @@
+---
+menu: Hygraph cli
+---
+
+# Hygraph migrate cli
+
+It is possible to upgrade your Hygraph schema using the Graphcommerce Hygraph
+CLI: `yarn graphcommerce hygraph-migrate`
+
+This is a tool that automatically modifies your Hygraph schema without having to
+add models, components field and enumerations manually.
+
+Please note that:
+
+- All migrations are backwards compatible with previous versions of
+  GraphCommerce. This means that after running a migration, older versions of
+  GraphCommerce will still work (unless specified otherwise)
+
+- There is no rollback functionality in the Hygraph migrate cli. Please create a
+  copy of the project to test te migration on first. Once you run a migration,
+  you can't undo these schema changes with the CLI. You will be required
+  rollback the from the UI yourself.
+
+### Steps
+
+The following steps are needed to utilize this tool:
+
+1. Create a Hygraph migration token
+   1. Open your Hygraph project. Go to: Project settings > Permanent auth tokens
+   2. Click 'Add token' and give it a name, something like 'GraphCommerce Write
+      Access Token' and keep stage on 'Published'.
+   3. Under 'Management API', click 'Yes, Initialize defaults'
+   4. Click 'Edit Permissions' and enable: 'Update' and 'Delete' permissions for
+      'models', 'enumerations', 'fields', 'components' and 'sources':
+      - Update existing models
+      - Delete existing models
+      - Update existing fields
+      - Delete existing fields
+      - Update existing enumerations
+      - Delete existing enumerations
+      - Update existing components
+      - Delete existing components
+      - Update remote sources
+      - Delete remote sources
+      - Read existing environments
+      - Read public content views
+      - Create public content views
+      - Update public content views
+      - Delete public content views
+      - Can see schema view
+   5. Add this new token to your env file: `GC_HYGRAPH_WRITE_ACCESS_TOKEN=""`
+2. Add the Content API key to your env file like this:
+   1. Open your Hygraph project. Go to: Project settings -> API Access
+   2. Copy the Content API URL and add to your env file:
+      `GC_HYGRAPH_WRITE_ACCESS_ENDPOINT=""`
+3. Add your hygraphProjectId to your env file like this:
+   1. Copy the project ID from the URL when logged in
+      `https://app.hygraph.com/PROJECT_ID_IS_HERE/master`
+   2. Add the project ID to your env file: `GC_HYGRAPH_PROJECT_ID=””`
+4. Run `yarn graphcommerce hygraph-migrate`
+5. Select the migration you want to run and press enter.
+6. The migrations should now be applied, check your Hygraph Schema if changes
+   are made.

package/{framework/graphcms.md → hygraph/readme.md}

@@ -1,5 +1,5 @@
 ---
-menu: Hygraph
+menu: Overview
 ---
 
 # Hygraph
@@ -66,3 +66,4 @@ Is used to add a`RowProduct (variant:Grid)` and a
 
 - Learn how to
   [build a custom Hygraph component](../getting-started/graphcms-component.md)
+  - Learn how to [upgrade your Hygraph schema](./upgrading.md)

package/magento/configurable-products.md

@@ -0,0 +1,95 @@
+---
+menu: Configurable Products
+---
+
+# Configurable Products
+
+Example:
+[Simple product (with pre-selection)](https://graphcommerce.vercel.app/p/matriarch-s-edges-size-4-6y-gc-469-sock-6y)
+
+GraphCommerce enables various ways to manage the display of data from
+configurable products in Magento. This flexibility allows you to choose dynamic
+updates for the following data:
+
+- **Content:** Name, description, short description, and meta-data from the
+  selected variant.
+- **Gallery:** Automatically updates product gallery images on the product page
+  when a variant is chosen, provided the gallery images for the selected variant
+  differ from the currently displayed ones.
+- **URL:** The product URL changes in the address bar when a variant is
+  selected, but this only happens when the actual variant can be accessed via
+  the URL.
+
+## Enabling this Feature
+
+To enable this feature, add the **configurableVariantValues** section to your
+`graphcommerce.config.js` file and activate the desired options.
+
+```
+const config = {
+  ...
+
+  configurableVariantValues: {
+    url: true,
+    gallery: true,
+    content: true,
+  },
+
+  configurableVariantForSimple: true,
+}
+```
+
+### GraphCommerceConfig
+
+- #### `configurableVariantForSimple: Boolean`
+
+  Determines whether a simple product should appear as a Configurable Product
+  with pre-selected options or as the default Simple Product.
+
+  **How does this work:**
+
+  When the `products(filters: { url_key: { eq: 'simple-product' } }) { ... }`
+  query is ran, Magento also returns the Simple product and the Configurable
+  product the simple belongs to.
+
+  If that is the case we render the Configurable Product page instead of the
+  Simple Product page but the options to select the Simple Product are
+  pre-selected.
+
+- #### `configurableVariantValues`
+
+  Options to configure which values will be replaced when a variant is selected
+  on the product page.
+
+  - #### `content: Boolean`
+
+    **Description:** Use the name, description, short description and meta data
+    from the configured variant
+
+  - #### `gallery: Boolean`
+
+    **Description:** This option enables the automatic update of product gallery
+    images on the product page when a variant is selected, provided that the
+    gallery images for the selected variant differ from the currently displayed
+    images.
+
+  - #### `url: Boolean`
+
+    **Description:** When a variant is selected the URL of the product will be
+    changed in the address bar.
+
+    **Note:** This only occurs when the actual variant can be accessed through
+    the URL.
+
+## Magento configuration
+
+### How should a Magento administrator configure the configurable and simple products to use this?
+
+To make use of this features the Visibility of your product should be set to
+**Catalog** or **Catalog, Search**. Or else the data is not accessible.
+
+> `Catalog -> Products -> [product] -> Visibility: [Catalog / Catalog, Search]`
+
+## Next steps
+
+- [Overview](./readme)

package/magento/readme.md

@@ -50,6 +50,20 @@ For Magento Open Source:
 For Adobe Commerce:
 `Stores -> Attributes -> Customer Address -> street -> Lines Count`
 
+### Remove URL suffixes from products and categorories (optional)
+
+GraphCommerce does not support URL suffixes, because Next.js can not handle urls
+ending in `.html`. When migrating from an existing shop, GraphCommerce will
+automatically redirect to the suffix-less URL. However, GraphCommerce will need
+to do an additional query to Magento to find the route.
+
+If you are starting out from a new project, we recommend to remove the URL
+suffixes from products and categories.
+
+Remove the URL suffixes from products and categories. (default is `.html`)
+`Stores -> Configuration -> Catalog -> Catalog -> Search Engine Optimization -> Product URL Suffix`
+`Stores -> Configuration -> Catalog -> Catalog -> Search Engine Optimization -> Category URL Suffix`
+
 ## Optional packages
 
 - [Store Pickup / MSI](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/magento-cart-pickup)

package/package.json

@@ -2,10 +2,10 @@
   "name": "@graphcommerce/docs",
   "homepage": "https://www.graphcommerce.org/docs",
   "repository": "github:graphcommerce-org/graphcommerce/docs",
-  "version": "6.2.0-canary.9",
+  "version": "6.2.0-canary.90",
   "sideEffects": true,
   "devDependencies": {
-    "@graphcommerce/prettier-config-pwa": "6.2.0-canary.9"
+    "@graphcommerce/prettier-config-pwa": "6.2.0-canary.90"
   },
   "prettier": "@graphcommerce/prettier-config-pwa"
 }

package/roadmap.md

@@ -15,9 +15,8 @@ The following overview contains the status of items on the GraphCommerce roadmap
 
 ## In progress
 
-- [ ] Algolia implementation
-- [ ] Dynamic Row based content
-- [ ] Product compare functionality
+- [ ] Better authorization handling
+- [ ] Hygraph schema migrations
 - [ ] Edge runtime for GraphQL Mesh and Streaming SSR rendering
 - [ ] Global store messages
 
@@ -25,6 +24,9 @@ The following overview contains the status of items on the GraphCommerce roadmap
 
 [See all releases](https://github.com/graphcommerce-org/graphcommerce/releases?q=prerelease%3Afalse+&expanded=true)
 
+- [x] [Algolia Search (beta)](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/algolia-search)
+- [x] [Dynamic Rows (beta)](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/hygraph-dynamic-rows)
+- [x] [Product compare](https://github.com/graphcommerce-org/graphcommerce/blob/main/packages/magento-compare/Config.graphqls)
 - [x] Google Tagmanager 4 datalayer implementation
       [docs ↗](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/googleanalytics)
 - [x] Paypal Express payment service

package/upgrading/graphcommerce-6-to-7.md

@@ -0,0 +1,96 @@
+# Upgrading from GraphCommerce 6 to 7
+
+Depending on the amounts of customisations you've made, there are some manual
+steps. Please follow the regular [upgrade steps first](./readme.md).
+
+1. [Add `fetchPolicy: cache-first` to LayoutDocument](#add-cache-first-fetchpolicy-to-layoutdocument)
+2. [Use thew new `hygraphPageContent` function instead of DefaultPageQuery](#use-the-new-hygraphpagecontent-function-instead-of-defaultpagequery)
+3. [Translation file updates](#translation-file-updates)
+4. [All @graphql-mesh/\* should be set to latest](#all-graphql-mesh-should-be-set-to-latest)
+5. [Upgrading your Hygraph schema](#upgrading-your-hygraph-schema)
+
+## Add `fetchPolicy: cache-first` to LayoutDocument queries
+
+🟠 Only required if you've added custom pages
+
+All occurences of LayoutDocument should get a `fetchPolicy: 'cache-first'`
+option.
+
+```tsx
+// Find all occurences of
+staticClient.query({ query: LayoutDocument })
+
+// Replace with
+staticClient.query({ query: LayoutDocument, fetchPolicy: 'cache-first' })
+```
+
+## Use the new `hygraphPageContent` function instead of DefaultPageQuery
+
+🟠 Only required if you've added custom pages
+
+The `DefaultPageDocument` is removed in favor of the new `hygraphPageContent`
+query. This function handles caching better and allows for (currently in beta)
+DynamicRows feature.
+
+```tsx
+// DefaultPageDocument
+const page = staticClient.query({
+  query: DefaultPageDocument,
+  variables: { url: `blog/${urlKey}` },
+})
+
+// Becomes hygraphPageContent
+const page = hygraphPageContent(staticClient, `blog/${urlKey}`)
+```
+
+## Translation file updates
+
+🟠 Only required if you've added custom translations
+
+All locales files now require a `msgid` comment. All translations need to have a
+`#. js-lingui-explicit-id` comment added. This could be done with a
+find-and-replace:
+
+Find (including the empty line)
+
+```
+
+msgid
+```
+
+Replace with (including the empty line)
+
+```
+
+#. js-lingui-explicit-id
+msgid
+```
+
+To validate your translations run `yarn lingui` to extract everything.
+
+## All @graphql-mesh/\* should be set to latest.
+
+🟠 Only required if you've added custom @graphql-mesh/\* packages
+
+All @graphql-mesh packages are using a 0.x.x versioning schema. This means that
+each minor change is considered a major change by yarn. This causes lots of
+issues with version mismatches. Since `@graphql-mesh` isn't making any major
+breaking before releasing 1.x this is the safest course of action for now. Once
+1.x is released we'll switch to "^1.0.0" as a version constraint.
+
+In your package.json
+
+```json
+// Replace
+    "@graphql-mesh/json-schema": "^0.37.6",
+    "@graphql-mesh/transform-filter-schema": "^0.15.8",
+
+// With
+    "@graphql-mesh/json-schema": "latest",
+    "@graphql-mesh/transform-filter-schema": "latest",
+```
+
+## Upgrading your Hygraph schema
+
+Upgrade your Hygraph schema with the [Hygraph migration cli](../hygraph/cli.md).
+Select `graphcommerce6to7` as version.

package/upgrading/readme.md

@@ -107,6 +107,7 @@ find . -type f -name '*.rej' -delete
 After resolving the diff issues, manually process upgrade instructions:
 
 - [Upgrading to GraphCommerce 5 to 6](../upgrading/graphcommerce-5-to-6.md)
+- [Upgrading to GraphCommerce 6 to 7](../upgrading/graphcommerce-6-to-7.md)
 
 Run and validate your local environment: