@salesforce/retail-react-app 1.0.0-preview.0

package/jest.config.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2022, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+const path = require('path')
+const base = require('@salesforce/pwa-kit-dev/configs/jest/jest.config.js')
+
+module.exports = {
+    ...base,
+    moduleNameMapper: {
+        ...base.moduleNameMapper,
+        '^react$': '<rootDir>/node_modules/react/index.js',
+        '^react-router-dom(.*)$': '<rootDir>/node_modules/react-router-dom/index.js',
+        '^@salesforce\/retail-react-app(.*)$': '<rootDir>$1',
+        '^@tanstack/react-query$':
+            '<rootDir>/node_modules/@tanstack/react-query/build/lib/index.js',
+        '^is-what$': '<rootDir>/node_modules/is-what/dist/cjs/index.cjs',
+        '^copy-anything$': '<rootDir>/node_modules/copy-anything/dist/cjs/index.cjs'
+    },
+    setupFilesAfterEnv: [path.join(__dirname, 'jest-setup.js')],
+    collectCoverageFrom: [
+        'app/**/*.{js,jsx}',
+        'non-pwa/**/*.{js,jsx}',
+        'worker/**/*.{js,jsx}',
+        'scripts/generator/*.{js,jsx}',
+        '!app/pages/test-container/**/*.{js,jsx}',
+        '!app/utils/test-utils.js',
+        '!app/mocks/*.js',
+        '!app/main.jsx',
+        '!app/loader.js',
+        '!app/ssr.js',
+        '!app/static/**',
+        '!app/theme/**',
+        '!node_modules/**'
+    ],
+    //@TODO: Revert this threshold back to original numbers stattements: 80, branches: 72, functions: 78, lines: 83
+    coverageThreshold: {
+        global: {
+            statements: 73,
+            branches: 60,
+            functions: 65,
+            lines: 74
+        }
+    },
+    // Increase to: 6 x default timeout of 5 seconds
+    ...(process.env.CI ? {testTimeout: 30000} : {})
+}

package/jsconfig.json

@@ -0,0 +1,13 @@
+// for development convenience, this file helps IDE's find relative paths prefixed with
+// the self-reference (to this package) 'retail-react-app'
+
+// jsconfig.json
+{
+    "compilerOptions": {
+        "target": "ES6",
+        "baseUrl": "./",
+        "paths": {
+            "retail-react-app/*": ["./*"]
+        }
+    }
+}

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@salesforce/retail-react-app",
+  "version": "1.0.0-preview.0",
+  "license": "See license in LICENSE",
+  "author": "cc-pwa-kit@salesforce.com",
+  "ccExtensibility": {
+    "extendable": [
+      "@salesforce/retail-react-app"
+    ]
+  },
+  "scripts": {
+    "analyze-build": "cross-env MOBIFY_ANALYZE=true npm run build",
+    "build": "npm run build-translations && pwa-kit-dev build",
+    "build-translations": "npm run extract-default-translations && npm run compile-translations",
+    "compile-translations": "formatjs compile-folder --ast translations translations/compiled",
+    "compile-translations:pseudo": "formatjs compile --ast translations/en-US.json --out-file translations/compiled/en-XA.json --pseudo-locale en-XA",
+    "extract-default-translations": "node ./scripts/extract-default-messages.js en-US",
+    "format": "pwa-kit-dev format \"**/*.{js,jsx}\"",
+    "lint": "pwa-kit-dev lint \"**/*.{js,jsx}\"",
+    "lint:fix": "npm run lint -- --fix",
+    "push": "npm run build && pwa-kit-dev push",
+    "save-credentials": "pwa-kit-dev save-credentials",
+    "start": "cross-env NODE_ICU_DATA=node_modules/full-icu pwa-kit-dev start",
+    "start:inspect": "npm run start -- --inspect",
+    "start:pseudolocale": "npm run extract-default-translations && npm run compile-translations:pseudo && cross-env USE_PSEUDOLOCALE=true npm run start",
+    "tail-logs": "pwa-kit-dev tail-logs",
+    "test": "pwa-kit-dev test",
+    "test:lighthouse": "cross-env NODE_ENV=production lhci autorun --config=tests/lighthouserc.js",
+    "test:max-file-size": "npm run build && bundlesize"
+  },
+  "browserslist": [
+    "iOS >= 9.0",
+    "Android >= 4.4.4",
+    "last 4 ChromeAndroid versions"
+  ],
+  "dependencies": {
+    "@chakra-ui/icons": "^2.0.19",
+    "@chakra-ui/react": "^2.6.0",
+    "@chakra-ui/skip-nav": "^2.0.15",
+    "@chakra-ui/system": "^2.5.6",
+    "@emotion/react": "^11.10.6",
+    "@emotion/styled": "^11.10.6",
+    "@formatjs/cli": "^6.0.4",
+    "@lhci/cli": "^0.11.0",
+    "@loadable/component": "^5.15.3",
+    "@peculiar/webcrypto": "^1.4.2",
+    "@salesforce/commerce-sdk-react": "1.0.0-preview.0",
+    "@salesforce/pwa-kit-dev": "3.0.0-preview.0",
+    "@salesforce/pwa-kit-react-sdk": "3.0.0-preview.0",
+    "@salesforce/pwa-kit-runtime": "3.0.0-preview.0",
+    "@tanstack/react-query": "^4.0.10",
+    "@tanstack/react-query-devtools": "^4.29.1",
+    "@testing-library/dom": "^9.0.1",
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/user-event": "^14.4.3",
+    "base64-arraybuffer": "^0.2.0",
+    "bundlesize2": "^0.0.31",
+    "card-validator": "^8.1.1",
+    "cross-env": "^5.2.1",
+    "focus-visible": "^5.2.0",
+    "framer-motion": "^10.12.9",
+    "full-icu": "^1.5.0",
+    "helmet": "^4.6.0",
+    "jest-fetch-mock": "^2.1.2",
+    "js-cookie": "^3.0.1",
+    "jsonwebtoken": "^9.0.0",
+    "jwt-decode": "^3.1.2",
+    "lodash": "^4.17.21",
+    "msw": "^1.2.1",
+    "nanoid": "^3.3.4",
+    "njwt": "^1.2.0",
+    "prop-types": "^15.8.1",
+    "query-string": "^7.1.3",
+    "raf": "^3.4.1",
+    "randomstring": "^1.2.3",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-helmet": "^6.1.0",
+    "react-hook-form": "^7.43.9",
+    "react-intl": "^5.25.1",
+    "react-router-dom": "^5.3.4"
+  },
+  "devDependencies": {
+    "cross-env": "^5.2.1"
+  },
+  "engines": {
+    "node": "^16.11.0 || ^18.0.0",
+    "npm": "^8.0.0 || ^9.0.0"
+  },
+  "bundlesize": [
+    {
+      "path": "build/main.js",
+      "maxSize": "42 kB"
+    },
+    {
+      "path": "build/vendor.js",
+      "maxSize": "320 kB"
+    }
+  ],
+  "overrides": {
+    "nwsapi": "2.2.2"
+  },
+  "gitHead": "a9f820893b7714244a0af509a5aefecc1344153c"
+}

package/scripts/extract-default-messages.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/*
+ * Copyright (c) 2023, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+/* eslint @typescript-eslint/no-var-requires: "off" */
+
+/**
+ * This script will extract messages from base template and extended app and output all translations in the extended app
+ * If a file is overridden, it won't extract messages from that file in the base template
+ */
+const {exec} = require('child_process')
+const fs = require('fs')
+const path = require('path')
+const packagePath = path.join(process.cwd(), 'package.json')
+const pkgJSON = JSON.parse(fs.readFileSync(packagePath))
+const locale = process.argv[2]
+
+const getAllFilesByExtensions = (dirPath, arrayOfFiles = [], extensions = []) => {
+    const files = fs.readdirSync(dirPath)
+
+    files.forEach(function (file) {
+        if (fs.statSync(path.join(dirPath, file)).isDirectory()) {
+            arrayOfFiles = getAllFilesByExtensions(
+                path.join(dirPath, file),
+                arrayOfFiles,
+                extensions
+            )
+        } else {
+            arrayOfFiles.push(path.join(dirPath, file))
+        }
+    })
+    if (extensions.length) {
+        return arrayOfFiles.filter((filePath) => {
+            const getExtension = path.extname(filePath).replace('.', '')
+            return extensions.includes(getExtension)
+        })
+    }
+
+    return arrayOfFiles
+}
+
+try {
+    const overridesDir = pkgJSON.ccExtensibility?.overridesDir
+    if (!overridesDir) {
+        const command = `formatjs extract "app/**/*.{js,jsx,ts,tsx}" --out-file translations/${locale}.json --id-interpolation-pattern [sha512:contenthash:base64:6]`
+        exec(command, (err) => {
+            if (err) {
+                console.error(err)
+            }
+        })
+    } else {
+        const overridesPath = path.join(process.cwd(), pkgJSON.ccExtensibility?.overridesDir)
+        // get all the files in extended app
+        const files = getAllFilesByExtensions(
+            path.join(overridesPath, 'app'),
+            [],
+            ['js', 'jsx', 'ts', 'tsx']
+        )
+        // get the file names that are overridden in base template
+        const overriddenFiles = files
+            .map((path) => {
+                const replacedPath = path.replace(
+                    overridesDir,
+                    `node_modules/${pkgJSON.ccExtensibility?.extends}`
+                )
+                // check if this file does exist in base template
+                const isFileExist = fs.existsSync(replacedPath)
+                return isFileExist ? replacedPath : ''
+            })
+            .filter(Boolean)
+        // rename the files needs to ignore to have .ignore extensions so it won't be recognized by formatjs
+        overriddenFiles.forEach((filePath) => {
+            fs.rename(filePath, `${filePath}.ignore`, (err) => err && console.error(err))
+        })
+
+        const extractCommand = `formatjs extract "./node_modules/${pkgJSON.ccExtensibility?.extends}/app/**/*.{js,jsx,ts,tsx}" "${pkgJSON.ccExtensibility?.overridesDir}/app/**/*.{js,jsx,ts,tsx}" --out-file translations/${locale}.json --id-interpolation-pattern [sha512:contenthash:base64:6]`
+        exec(extractCommand, (err) => {
+            if (err) {
+                console.error(err)
+            }
+            // restore file names
+            overriddenFiles.forEach((filePath) => {
+                fs.rename(`${filePath}.ignore`, filePath, (err) => err && console.error(err))
+            })
+        })
+    }
+} catch (error) {
+    console.error(error)
+}

package/tests/lighthouserc.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2021, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+module.exports = {
+    // The different Lighthouse CI configuration options:
+    // https://github.com/GoogleChrome/lighthouse-ci/blob/master/docs/configuration.md
+    ci: {
+        collect: {
+            startServerCommand: 'npm run start',
+            //NOTE: Adjust the key pages URLs that you find important to your website.
+            url: [
+                'http://localhost:3000/',
+                'http://localhost:3000/global/en-GB/category/womens',
+                'http://localhost:3000/global/en-GB/product/25493613M',
+                'http://localhost:3000/global/en-GB/search?q=suit'
+            ],
+            startServerReadyPattern: 'First build complete',
+            startServerReadyTimeout: 90000
+        },
+        upload: {
+            target: 'temporary-public-storage'
+        },
+        assert: {
+            aggregationMethod: 'median',
+            assertions: {
+                // NOTE: Adjust the scores accordingly as the performance is improved
+                'categories:performance': ['error', {minScore: 0.3}],
+                'categories:pwa': ['error', {minScore: 0.9}],
+                'categories:seo': ['error', {minScore: 0.85}],
+                'categories:accessibility': ['error', {minScore: 0.88}]
+            }
+        }
+    }
+}

package/translations/README.md

@@ -0,0 +1,127 @@
+# Translations
+
+Most of the files in this folder are generated by `react-intl` **CLI tool**:
+
+- `<root>/translations/en-US.json` <- output of _extracting_ the default messages, which you can send to your translators.
+- `<root>/translations/[locale].json` <- the files that your translators make for the other locales
+- `<root>/translations/compiled/[locale].json` <- output of _compiling_ the messages into AST format
+  - Compiling helps improve the performance because it allows `react-intl` to skip the parsing step
+
+Several **npm scripts** are available to you that make it easier to use the CLI tool. See `package.json` for more details.
+
+- To **extract the default messages**, run `npm run extract-default-translations` to have all the default messages extracted into a json file. By default, en-US.json is the file that's generated. If you wish to extract your messages into a different json file, simply update the script by replacing `en-US` with your desired locale.
+- To **compile the translations** from all the locales, run `npm run compile-translations`.
+- To run **both an extract and compile**, run `npm run build-translations`.
+
+## Formatting Messages
+
+For all the hardcoded translations in your site, write them...
+
+- _inline_ in the components, so it’s easier to see where in the page or component that they get used in
+- and in the _default/fallback locale_ (for example, in English)
+
+For example, in your React component, you can add formatted messages like `intl.formatMessage({defaultMessage: '...'})` or `<FormattedMessage defaultMessage="..." />`
+
+### Adding Message Id
+
+At the minimum, only defaultMessage is the required parameter. The message id is optional. If you don’t specify it, the id is auto-generated for you.
+
+## Testing with a Pseudo Locale
+
+To check whether you’ve wrapped all the hardcoded strings with either `intl.formatMessage()` or `<FormattedMessage />` , there’s a quick way to test that by running `npm run start:pseudolocale`. It runs your local dev server with the locale forced to the pseudo locale.
+
+Loading the site in your browser, you can quickly see that those messages that have been formatted would look like this: `[!! Ṕŕíííṿâćććẏ ṔṔṔŏĺíííćẏ !!]`
+
+# Localization
+
+Since the Retail React App supports **multiple sites** feature, this means each site can have its own localization setup. In each site, 
+the default locale, supported locales, and currency settings are defined in a site object in `config/sites.js` under `ll0n`.
+
+The locale ids `l10n.supportedLocales[n].id` follow the format supported by OCAPI and Commerce API: `<language code>-<country code>` as defined in this InfoCenter topic: [OCAPI localization 21.8](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/OCAPI/current/usage/Localization.html).
+
+The currency code in `l10n.supportedCurrencies` and `l10n.supportedLocales[n].preferredCurrency` follow the ISO 4217 standard.
+
+**Important**: The supported locale settings `l10n.supportedLocales` must match the locale settings for your B2C Commerce instance. For more information about configuring locales on a B2C Commerce instance, see this InfoCenter topic: [Configure Site Locales](https://documentation.b2c.commercecloud.salesforce.com/DOC2/topic/com.demandware.dochelp/content/b2c_commerce/topics/admin/b2c_configuring_site_locales.html).
+
+Here’s an example of locale configuration in sites configuration:
+
+```js
+// config/sites.js
+modules.exports = [
+   {
+      id: 'site-id', 
+      l10n: {
+         supportedCurrencies: ['GBP', 'EUR', 'CNY', 'JPY'],
+         defaultCurrency: 'GBP',
+         supportedLocales: [
+            {
+               id: 'de-DE',
+               preferredCurrency: 'EUR'
+            },
+            {
+               id: 'en-GB',
+               preferredCurrency: 'GBP'
+            },
+            {
+               id: 'es-MX',
+               preferredCurrency: 'MXN'
+            },
+            // other locales
+         ],
+         defaultLocale: 'en-GB'
+      }
+   }
+]
+```
+
+## How to Add a New Locale
+
+The process for adding a new locale is as follows:
+
+1. Create/enable the new locale in Business Manager of your B2C Commerce instance
+2. Enable the locale's currency too in Business Manager
+3. Add the new locale and its currency to your targeted site in `config/sites.js`
+4. If the new locale is also going to be the locale of your inline default messages:
+    - Update those default messages to be in that locale's language
+    - Run `npm run extract-default-translations` to extract the new translations
+    - Send the extracted translations to your translation team
+5. Place the files you receive from your translation team into the `<root>/translations/` folder
+6. Run `npm run compile-translations`
+
+## Tips
+
+Here are a few useful things to know for developers.
+
+### User-Preferred Locales vs. App-Supported Locales
+
+How a locale gets chosen depends on whether there’s a match found between 2 sets of locales. On a high level, it looks like this:
+
+1. Get the app-supported locales, which are defined in each site object in `config/sites.js` (under `l10n.supportedLocales` of your targeted site).
+2. Get the user-preferred locales, which are what the visitors prefer to see. The developer is responsible for fully implementing them in their own projects within the special `_app` component.
+3. If there’s a match between these 2 sets of locales, then the app would use it as the target locale.
+4. Otherwise, the app would fall back to the locale of the inline `defaultMessage`s. 
+
+### How to Detect the Active Locale
+
+- Within component render, `useLocale` hook is available to you: `const locale = useLocale()`
+- Within a page’s `getProps` you can call utility function `resolveLocaleFromUrl` like this:
+
+```js
+ProductDetail.getProps = async ({res, params, location, api}) => {
+    const locale = resolveLocaleFromUrl(`${location.pathname}${location.search}`)
+    ...
+}
+```
+
+### Dynamic Loading of the Translation Files
+
+Using dynamic import, regardless of how many locales the app supports, it would load only one locale at a time.
+
+Initially, on app load, the translated messages are part of the server-rendered html. Afterwards on the client side, when dynamically changing the locale, the app would download the JSON file associated with that locale.
+
+- Each locale is a separate JSON file in the bundle. And it’s served with a 1-year cache header.
+- When a new bundle is deployed, you must download the JSON files again.
+
+### Link Component
+
+The generated project comes with its own `Link` component. It automatically inserts the locale in the URLs for you.