@graphcommerce/docs 3.1.4

package/content/getting-started/header.md

@@ -0,0 +1,224 @@
+---
+menu: 3. Build a custom header
+metaTitle: Build a custom header
+---
+
+> **Developer preview**  
+> This is a developer preview of GraphCommerce. The documentation will be
+> updated as GraphCommerce introduces
+> [new features and refines existing functionality](https://github.com/ho-nl/m2-pwa/releases).
+
+# Build a custom header in GraphCommerce
+
+Previously, you created a GraphCommerce app and started building your custom
+storefront with GraphCommerce. You're now ready to build a custom header for
+your app.
+
+In this tutorial, you'll accomplish a series of tasks to add some specific
+functionality to your app. Your final app will be simple, but you'll learn where
+to find resources to build more complex features on your own.
+
+### After you've finished this tutorial, you'll have accomplished the following:
+
+- Edited the layout component to remove components
+- Add a simplified search Icon button
+- Make a local copy of the MenuFab component and update its imports
+- Change the Menu component's styling to a fullscreen overlay
+
+### Requirements
+
+You've familiarized yourself with
+[React ↗](https://reactjs.org/docs/getting-started.html),
+[Next.js ↗](https://nextjs.org/docs/getting-started), and
+[Mui ↗](https://mui.com/getting-started/installation/). GraphCommerce is a
+frontend React framework that uses Next.js for server-side rendering.
+
+---
+
+<figure>
+
+https://user-images.githubusercontent.com/1251986/154978614-8d2eaee1-d64b-4bae-a7d7-cfee2e9175d3.mp4
+
+<video width="100%" controls autoPlay loop muted>
+<source src="https://user-images.githubusercontent.com/1251986/154978614-8d2eaee1-d64b-4bae-a7d7-cfee2e9175d3.mp4" type="video/mp4"/>
+</video>
+
+  <figcaption>Before customization of the header</figcaption>
+</figure>
+
+<figure>
+
+https://user-images.githubusercontent.com/1251986/154979091-89c72d68-c62f-451c-af49-6f36f3fa6609.mp4
+
+<video width="100%" controls autoPlay loop muted>
+<source src="https://user-images.githubusercontent.com/1251986/154979091-89c72d68-c62f-451c-af49-6f36f3fa6609.mp4" type="video/mp4"/>
+</video>
+
+  <figcaption>After customization of the header</figcaption>
+</figure>
+
+### Move and justify the logo
+
+- In /components/Layout/LayoutFull.tsx, move `<Logo />` after
+  `<DesktopNavBar>...</DesktopNavBar>`
+- Wrap the `<Logo />` component in a `<Box>` component:
+
+```tsx
+<Box
+  sx={{
+    display: 'flex',
+    justifyContent: 'center',
+    flexGrow: 1,
+    pointerEvents: 'none',
+  }}
+>
+  <Logo />
+</Box>
+```
+
+- Add the import of 'Box' to the list of the `'@mui/material'` imports at the
+  top of the file
+- Save the file to see your changes updated in real-time
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/v0jqud" />
+ <figcaption>Reorder components</figcaption>
+</figure>
+
+### Remove DesktopNavBar
+
+- In /components/Layout/LayoutFull.tsx, remove the
+  `<DesktopNavBar>...</DesktopNavBar>` component.
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/S1BIyc" />
+ <figcaption>Remove navigation</figcaption>
+</figure>
+
+### Replace Search input with Search Fab
+
+- In /components/Layout/LayoutFull.tsx, replace
+  `<SearchButton onClick={onSearchStart} label=' ' />` with:
+
+```tsx
+<PageLink href='/search' passHref>
+  <Fab aria-label={t`Search`} size='large' color='inherit'>
+    <IconSvg src={iconSearch} size='large' />
+  </Fab>
+</PageLink>
+```
+
+- Add `iconSearch` to the existing imports from `'@graphcommerce/next-ui'` at
+  the top of the file
+
+### Remove Customer Service Fab
+
+- In /components/Layout/LayoutFull.tsx, remove the Customer Service floating
+  action button by removing it completely:
+
+```tsx
+<PageLink href='/service' passHref>
+  <Fab aria-label={t`Account`} size='large' color='inherit'>
+    <IconSvg src={iconCustomerService} size='large' />
+  </Fab>
+</PageLink>
+```
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/7eadNI" />
+ <figcaption>Replace search input with Search Fab, remove Customer Service Fab</figcaption>
+</figure>
+
+### Make a local copy of the MenuFab component
+
+- In /components/Layout/LayoutFull.tsx, remove `MenuFab` from the
+  `'@graphcommerce/next-ui'` import
+- Add `import { MenuFab } from './MenuFab'` to the list of imports at the top of
+  the file
+
+- Make a copy of /node_modules/@graphcommerce/next-ui/LayoutParts/MenuFab.tsx
+  and move it to the directory /components/Layout/MenuFab.tsx
+- In /components/Layout/MenuFab.tsx, change
+  `const MotionDiv = styled(m.div)({})` to:
+  ```ts
+  const MotionDiv = styled('div')({})
+  ```
+- Remove the `style={{...}}` prop from both the `<MotionDiv>` components to
+  remove the Fab scroll animation
+- Remove `const { opacity, scale, shadowOpacity } = useFabAnimation()`
+
+- Update all imports:
+
+```tsx
+import {
+  extendableComponent,
+  responsiveVal,
+  iconClose,
+  iconMenu,
+  IconSvg,
+} from '@graphcommerce/next-ui'
+import { styled, Box, Fab, Menu, ListItem, Divider, alpha } from '@mui/material'
+import { useRouter } from 'next/router'
+import React, { useEffect } from 'react'
+```
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/O1iBQ4" />
+ <figcaption>Local copy of the MenuFab component with Fab scroll animation removed</figcaption>
+</figure>
+
+### Change the Menu component's styling
+
+- In /components/Layout/MenuFab.tsx, change the `<Menu>` component's PaperProps
+  prop to:
+
+```tsx
+PaperProps={{
+  sx: (theme) => ({
+    width: '100vw',
+    height: '100vh',
+    maxWidth: '100vw',
+    maxHeight: '100vh',
+    backgroundColor: alpha(theme.palette.text.primary, 0.95),
+    color: theme.palette.background.paper,
+    display: 'flex',
+    justifyContent: 'center',
+    alignItems: 'center',
+    borderRadius: 0,
+    '& svg': {
+      color: theme.palette.background.paper,
+    },
+  }),
+}}
+```
+
+- Remove the `<Menu>` component's prop 'disableScrollLock`
+- Add a two props to the `<Menu>` component:
+
+```tsx
+marginThreshold={0}
+TransitionComponent={Fade}
+```
+
+- Add the import of 'Fade' to the list of the `'@mui/material'` imports at the
+  top of the file
+- Remove the search component by removing:
+
+```tsx
+  search ? (
+    <ListItem key='search' dense sx={{ mb: '6px', borderColor: 'red' }}>
+      {search}
+    </ListItem>
+  ) : null,
+```
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/RyXlBV" />
+ <figcaption>Menu component with custom styling</figcaption>
+</figure>
+
+## Next steps
+
+- Learn how to [build pages](../getting-started/pages.md) in GraphCommerce
+- Learn more about creating
+  [styled components with the styled() utility](../framework/theming.md)

package/content/getting-started/pages.md

@@ -0,0 +1,290 @@
+---
+menu: 4. Build pages
+metaTitle: Build pages
+---
+
+> **Developer preview**  
+> This is a developer preview of GraphCommerce. The documentation will be
+> updated as GraphCommerce introduces
+> [new features and refines existing functionality](https://github.com/ho-nl/m2-pwa/releases).
+
+# Build pages in GraphCommerce
+
+Previously, you created a custom storefront and started customizing your
+storefront in GraphCommerce. You're now ready to build pages in your
+GraphCommerce app.
+
+In this tutorial, you'll accomplish a series of tasks to add some specific
+functionality to your custom storefront. The result will be simple, but you'll
+learn where to find resources to build more complex features on your own.
+
+## What you'll learn
+
+- Create a new route
+- Add the page GraphQL queries required to render the layout (header, footer)
+- Use getStaticProps to fetch GraphCMS data
+- Use getStaticPaths to provide a list of all URLs to pre-render
+
+### Requirements
+
+You've familiarized yourself with
+[React ↗](https://reactjs.org/docs/getting-started.html),
+[Next.js ↗](https://nextjs.org/docs/getting-started), and
+[Mui ↗](https://mui.com/getting-started/installation/). GraphCommerce is a
+frontend React framework that uses Next.js for server-side rendering.
+
+---
+
+### Create the route
+
+- Create a new file, /about/about-us.tsx:
+
+```tsx
+export default function AboutUs() {
+  return <>About Us</>
+}
+```
+
+- Visit the page: http://localhost:3000/about/about-us
+
+### Add GraphQL query
+
+- In /about/about-us.tsx, replace the previous code with the following:
+
+```tsx
+import { PageOptions } from '@graphcommerce/framer-next-pages'
+import { StoreConfigDocument } from '@graphcommerce/magento-store'
+import { GetStaticProps } from '@graphcommerce/next-ui'
+import { Container } from '@mui/material'
+import { GetStaticPaths } from 'next'
+import { LayoutFull, LayoutFullProps } from '../../components'
+import {
+  DefaultPageDocument,
+  DefaultPageQuery,
+} from '../../graphql/DefaultPage.gql'
+import { PagesStaticPathsDocument } from '../../graphql/PagesStaticPaths.gql'
+import {
+  graphqlSsrClient,
+  graphqlSharedClient,
+} from '../../lib/graphql/graphqlSsrClient'
+
+type Props = DefaultPageQuery
+type RouteProps = { url: string }
+type GetPageStaticPaths = GetStaticPaths<RouteProps>
+type GetPageStaticProps = GetStaticProps<LayoutFullProps, Props, RouteProps>
+
+function AboutUs() {
+  return <Container>About Us</Container>
+}
+
+AboutUs.pageOptions = {
+  Layout: LayoutFull,
+} as PageOptions
+
+export default AboutUs
+
+export const getStaticProps: GetPageStaticProps = async (context) => {
+  const { locale } = context
+  const client = graphqlSharedClient(locale)
+  const staticClient = graphqlSsrClient(locale)
+
+  const conf = client.query({ query: StoreConfigDocument })
+  const page = staticClient.query({
+    query: DefaultPageDocument,
+    variables: {
+      url: '',
+      rootCategory: (await conf).data.storeConfig?.root_category_uid ?? '',
+    },
+  })
+  // if (!(await page).data.pages?.[0]) return { notFound: true }
+  return {
+    props: {
+      ...(await page).data,
+      apolloState: await conf.then(() => client.cache.extract()),
+    },
+    revalidate: 60 * 20,
+  }
+}
+```
+
+- Visiting http://localhost:3000/about/about-us will output:
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/xdI9be" />
+  <figcaption>Page with page layout (header, footer)</figcaption>
+</figure>
+
+```tsx
+// Example from /graphql/DefaultPage.graphql (DefaultPageDocument)
+
+query DefaultPage($url: String!, $rootCategory: String!) {
+  ...MenuQueryFragment
+  ...FooterQueryFragment
+  ...PageContentQueryFragment
+}
+```
+
+In the `getStaticProps` function, the query `StoreConfigDocument` is used to
+fetch information about the Magento storeview. Then, the query
+`DefaultPageDocument` is used to fetch the data required to render the menu,
+footer and page content.
+
+In this example, the URL variable is empty. As a result, the
+`...PageContentQueryFragment` will have no result when trying to fetch a
+GraphCMS page with URL `''`.
+
+The function `getStaticProps` is used to fetch data, meaning content is rendered
+on the server. Review the page's source code and search for `About Us` to
+validate that this string (currently hard-coded) is part of the source code.
+
+### Add GraphCMS content to the page
+
+- Login to GraphCMS, navigate to Content and add a new Page entry with URL:
+  about/about-us
+- In /about/about-us.tsx, make the following change to `getStaticProps`:
+
+```tsx
+const page = staticClient.query({
+  query: DefaultPageDocument,
+  variables: {
+    url: 'about/about-us',
+    rootCategory: (await conf).data.storeConfig?.root_category_uid ?? '',
+  },
+})
+```
+
+And replace the previous AboutUs function with the following:
+
+```tsx
+function AboutUs({ pages }: Props) {
+  const title = pages?.[0].title ?? ''
+
+  return <Container>{title}</Container>
+}
+```
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/PIOjzB" />
+  <figcaption>Fetch page content from GraphCMS</figcaption>
+</figure>
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/XKo4ut" />
+  <figcaption>GraphCMS entry</figcaption>
+</figure>
+
+### Add pre-rendering with getStaticPaths
+
+- Rename `/about/about-us.tsx` to `/about/[url].tsx`
+- In /about/[url].tsx, replace the getStaticProps function with the following:
+
+```tsx
+export const getStaticPaths: GetPageStaticPaths = (context) => ({
+  paths: [],
+  fallback: 'blocking',
+})
+
+export const getStaticProps: GetPageStaticProps = async (context) => {
+  const { locale, params } = context
+  const client = graphqlSharedClient(locale)
+  const staticClient = graphqlSsrClient(locale)
+
+  const conf = client.query({ query: StoreConfigDocument })
+  const page = staticClient.query({
+    query: DefaultPageDocument,
+    variables: {
+      url: `about/${params?.url}`,
+      rootCategory: (await conf).data.storeConfig?.root_category_uid ?? '',
+    },
+  })
+  // if (!(await page).data.pages?.[0]) return { notFound: true }
+  return {
+    props: {
+      ...(await page).data,
+      apolloState: await conf.then(() => client.cache.extract()),
+    },
+    revalidate: 60 * 20,
+  }
+}
+```
+
+By renaming the file to `/about/[url].tsx`, all routes starting with /about/
+will be handled by the file (dynamic routing). Pages that have dynamic routes
+need a list of paths to be statically generated.
+
+All paths specified by a function called `getStaticPaths` will be statically
+pre-rendered at build-time.
+
+In the example above, the array with paths is empty. The required getStaticPaths
+function is there, but no URLs are pre-rendered. Because getStaticPaths has the
+option `fallback: 'blocking'`, the paths that have not been pre-rendered at
+built-time will not result in a 404:
+
+> From the
+> [getStaticPaths API reference ↗](https://nextjs.org/docs/api-reference/data-fetching/get-static-paths):
+> If fallback is 'blocking', new paths not returned by getStaticPaths will wait
+> for the HTML to be generated, identical to SSR (hence why blocking), and then
+> be cached for future requests so it only happens once per path.
+
+### Pre-render all /about/ pages from GraphCMS
+
+- In /about/[url].tsx, replace the getStaticPaths function with the following:
+
+```tsx
+export const getStaticPaths: GetPageStaticPaths = async (context) => {
+  const { locales = [] } = context
+  // if (process.env.NODE_ENV === 'development') return { paths: [], fallback: 'blocking' }
+
+  const path = async (locale: string) => {
+    const client = graphqlSharedClient(locale)
+    const { data } = await client.query({
+      query: PagesStaticPathsDocument,
+      variables: {
+        first: 10,
+        urlStartsWith: 'about',
+      },
+    })
+    return data.pages.map((page) => ({
+      params: { url: page.url.split('/').slice(1)[0] },
+      locale,
+    }))
+  }
+  const paths = (await Promise.all(locales.map(path))).flat(1)
+  // console.log(paths)
+  return { paths, fallback: 'blocking' }
+}
+```
+
+The PagesStaticPathsDocument query is used to fetch all pages from GraphCMS that
+have a URL starting with 'about'. The locale options from the context object are
+used to create an array:
+
+```txt
+// Terminal output for console.log(paths), upon refreshing the page
+
+[
+  { params: { url: 'about-us' }, locale: 'en-us' },
+  { params: { url: 'about-us' }, locale: 'nl' },
+  { params: { url: 'about-us' }, locale: 'fr-be' },
+  { params: { url: 'about-us' }, locale: 'nl-be' },
+  { params: { url: 'about-us' }, locale: 'en-gb' },
+  { params: { url: 'about-us' }, locale: 'en-ca' },
+]
+```
+
+## Build your local environment
+
+You can test the static build process by running it locally:
+
+- `cd /examples/magento-graphcms/` Navigate to the project directory
+- `yarn build` Start static build process
+
+<figure>
+ <img src="https://cdn-std.droplr.net/files/acc_857465/AAOnX2" />
+  <figcaption>Successful pre-render of the about/about-us page</figcaption>
+</figure>
+
+## Next steps
+
+- Learn how to
+  [build a custom GraphCMS component](../getting-started/graphcms-component.md)