[WIP] docs: provide TS version of code snippets

jest.eslint.config.js

@@ -9,10 +9,11 @@ module.exports = {
     '.yarn',
     '.cache',
     'build/',
+    'code-examples/',
+    'compiled-data/',
+    'generated/',
     'dist/',
     'public/',
-    'generated',
-    'compiled-data',
   ],
   testMatch: ['<rootDir>/**/*.js', '<rootDir>/**/*.ts', '<rootDir>/**/*.tsx'],
   watchPlugins: [

lint-staged.config.js

@@ -1,5 +1,3 @@
-const micromatch = require('micromatch');
-
 module.exports = {
   '*.md': ['prettier --write --parser markdown'],
   '*.yaml': ['prettier --write --parser yaml'],
@@ -9,7 +7,7 @@ module.exports = {
   '*.ctp.graphql': () => 'yarn generate-types:ctp',
   '*.settings.graphql': () => 'yarn generate-types:settings',
   '*.proxy.graphql': () => 'yarn generate-types:proxy',
-  '*.js': [
+  '!(website)/**/*.js': [
     'prettier --write',
     // NOTE: apparently if you pass some argument that is not a flag AFTER the `reporters`
     // flag, jest does not seem correctly parse the arguments.
@@ -21,7 +19,7 @@ module.exports = {
     // For that reason, we move the `--onlyChanged` flag next to it.
     'yarn lint:js --reporters=jest-silent-reporter --onlyChanged',
   ],
-  '!(cypress)/**/*.{ts,tsx}': [
+  '!(cypress|website)/**/*.{ts,tsx}': [
     'prettier --write',
     // NOTE: apparently if you pass some argument that is not a flag AFTER the `reporters`
     // flag, jest does not seem correctly parse the arguments.
@@ -48,6 +46,7 @@ module.exports = {
     'yarn lint:js --reporters=jest-silent-reporter --onlyChanged',
     () => 'yarn typecheck:cypress',
   ],
+  'website/**/*.{js,ts,tsx}': ['prettier --write'],
   '*.css': [
     'prettier --write --parser css',
     // NOTE: apparently if you pass some argument that is not a flag AFTER the `reporters`

website/gatsby-config.js

@@ -1,4 +1,7 @@
 const colorPresets = require('@commercetools-docs/gatsby-theme-docs/color-presets');
+const {
+  configureThemeWithAddOns,
+} = require('@commercetools-docs/gatsby-theme-docs/configure-theme');
 
 module.exports = {
   // https://www.gatsbyjs.com/docs/reference/release-notes/v2.28/#feature-flags-in-gatsby-configjs
@@ -19,21 +22,19 @@ module.exports = {
   },
   plugins: [
     // Docs theme
-    {
-      resolve: '@commercetools-docs/gatsby-theme-docs',
-      options: {
-        websiteKey: 'custom-applications',
-        colorPreset: colorPresets.merchantCenterDeveloperDocs.key,
-        beta: false,
-        excludeFromSearchIndex: false,
-        gaTrackingId: 'UA-38285631-3',
-        globalNotification: {
-          notificationType: 'info',
-          content:
-            'This is the new documentation of Custom Applications. You can still visit the [legacy documentation](https://docs.commercetools.com/custom-applications/legacy) during the [migration](/migrating-from-project-level-custom-applications) from Project-level Custom Applications.',
-        },
-        overrideDefaultConfigurationData: ['**/top-*'],
+    ...configureThemeWithAddOns({
+      websiteKey: 'custom-applications',
+      colorPreset: colorPresets.merchantCenterDeveloperDocs.key,
+      beta: false,
+      excludeFromSearchIndex: false,
+      gaTrackingId: 'UA-38285631-3',
+      globalNotification: {
+        notificationType: 'info',
+        content:
+          'This is the new documentation of Custom Applications. You can still visit the [legacy documentation](https://docs.commercetools.com/custom-applications/legacy) during the [migration](/migrating-from-project-level-custom-applications) from Project-level Custom Applications.',
       },
-    },
+      overrideDefaultConfigurationData: ['**/top-*'],
+      addOns: ['@commercetools-docs/gatsby-theme-code-examples'],
+    }),
   ],
 };

website/package.json

@@ -11,7 +11,8 @@
     "generate-icons": "svgr -d src/icons/generated -- src/icons/svg && prettier --write '**/generated/*.js'"
   },
   "dependencies": {
-    "@commercetools-docs/gatsby-theme-docs": "18.6.0",
+    "@commercetools-docs/gatsby-theme-code-examples": "19.2.0",
+    "@commercetools-docs/gatsby-theme-docs": "19.1.0",
     "@commercetools-docs/ui-kit": "18.6.0",
     "@commercetools-uikit/card": "^15.0.0",
     "@commercetools-uikit/spacings-inline": "^15.0.0",

website/src/@commercetools-docs/gatsby-theme-docs/overrides/.gitignore

@@ -0,0 +1 @@
+addon-components.js

website/src/@commercetools-docs/gatsby-theme-docs/overrides/addon-components.js

@@ -0,0 +1,8 @@
+/* eslint-disable prettier/prettier */
+/* eslint import/no-anonymous-default-export: [2, {"allowObject": true}] */
+/* THIS IS AN AUTOGENERATED FILE, DO NOT EDIT DIRECTLY */
+import * as components0 from '@commercetools-docs/gatsby-theme-code-examples/shortcodes';
+
+export default {
+  ...components0,
+};

website/src/@commercetools-docs/gatsby-theme-docs/overrides/markdown-components.js

@@ -1,9 +1,11 @@
 import { BetaFlag } from '@commercetools-docs/gatsby-theme-docs';
 import Playground from '../../../components/playground';
+import addonComponents from './addon-components';
 
 const markdownComponents = {
   Playground,
   BetaFlag,
+  ...addonComponents,
 };
 
 export default markdownComponents;

website/src/code-examples/api-reference/application-config/environment-prop.jsx

@@ -0,0 +1,8 @@
+import { useApplicationContext } from '@commercetools-frontend/application-shell-connectors';
+
+const MyComponent = () => {
+  const applicationName = useApplicationContext(
+    (context) => context.environment.applicationName
+  );
+  return <div>{`Welcome to the application ${applicationName}!`}</div>;
+};

website/src/code-examples/api-reference/application-config/environment-prop.tsx

@@ -0,0 +1,8 @@
+import { useApplicationContext } from '@commercetools-frontend/application-shell-connectors';
+
+const MyComponent = () => {
+  const applicationName = useApplicationContext(
+    (context) => context.environment.applicationName
+  );
+  return <div>{`Welcome to the application ${applicationName}!`}</div>;
+};

website/src/code-examples/api-reference/application-config/runtime-application-environment.jsx

@@ -0,0 +1,6 @@
+const EntryPoint = () => (
+  <ApplicationShell
+    environment={window.app}
+    // other props
+  />
+);

website/src/code-examples/api-reference/application-config/runtime-application-environment.tsx

@@ -0,0 +1,10 @@
+import type { ApplicationWindow } from '@commercetools-frontend/constants';
+
+declare let window: ApplicationWindow;
+
+const EntryPoint = () => (
+  <ApplicationShell
+    environment={window.app}
+    // other props
+  />
+);

website/src/code-examples/api-reference/commercetools-frontend-actions-global/handle-action-error-instance.jsx

@@ -0,0 +1,8 @@
+class CustomError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CustomError';
+  }
+}
+const error = new CustomError('error');
+dispatch(handleActionError(error)); // dispatch method from Redux store

website/src/code-examples/api-reference/commercetools-frontend-actions-global/handle-action-error-instance.tsx

@@ -0,0 +1,8 @@
+class CustomError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CustomError';
+  }
+}
+const error = new CustomError('error');
+dispatch(handleActionError(error)); // dispatch method from Redux store

website/src/code-examples/api-reference/commercetools-frontend-actions-global/handle-action-error.jsx

@@ -0,0 +1,15 @@
+import { STATUS_CODES } from '@commercetools-frontend/constants';
+const error = {
+  statusCode: STATUS_CODES.FORBIDDEN, // statusCode: 403
+  body: {
+    message: 'This is an error',
+    errors: [
+      {
+        message: 'This is an error', // this message will be displayed as notification text
+        code: 'Invalid',
+      },
+    ],
+  },
+};
+// ...
+dispatch(handleActionError(error)); // dispatch method from Redux store

website/src/code-examples/api-reference/commercetools-frontend-actions-global/handle-action-error.tsx

@@ -0,0 +1,35 @@
+import { STATUS_CODES } from '@commercetools-frontend/constants';
+
+type TStatusCode = typeof STATUS_CODES[keyof typeof STATUS_CODES];
+
+type TAppNotificationApiError<ExtraFields extends {} = {}> = {
+  message: string;
+  /** @deprecated Use `extensions.code` */
+  code?: string;
+  extensions?: {
+    code?: string;
+  };
+} & ExtraFields;
+
+type TActionError = {
+  statusCode: TStatusCode;
+  body: {
+    message: string;
+    errors?: TAppNotificationApiError | TAppNotificationApiError[];
+  };
+};
+
+const error: TActionError = {
+  statusCode: STATUS_CODES.FORBIDDEN, // statusCode: 403
+  body: {
+    message: 'This is an error',
+    errors: [
+      {
+        message: 'This is an error', // this message will be displayed as notification text
+        code: 'Invalid',
+      },
+    ],
+  },
+};
+// ...
+dispatch(handleActionError(error)); // dispatch method from Redux store

website/src/code-examples/api-reference/commercetools-frontend-actions-global/handle-multiple-action-error.jsx

@@ -0,0 +1,18 @@
+const error = {
+  // ...
+  body: {
+    // ...
+    errors: [
+      {
+        message:
+          "This is the first error", // displayed as the notification text
+        code: "Invalid",
+      },
+      {
+        message:
+          "This is the second error", // also displayed as the notification text
+        code: "Invalid",
+      },
+    ],
+  },
+}

website/src/code-examples/api-reference/commercetools-frontend-actions-global/handle-multiple-action-error.tsx

@@ -0,0 +1,37 @@
+import { STATUS_CODES } from '@commercetools-frontend/constants';
+
+type TStatusCode = typeof STATUS_CODES[keyof typeof STATUS_CODES];
+
+type TAppNotificationApiError<ExtraFields extends {} = {}> = {
+  message: string;
+  /** @deprecated Use `extensions.code` */
+  code?: string;
+  extensions?: {
+    code?: string;
+  };
+} & ExtraFields;
+
+type TActionError = {
+  statusCode: TStatusCode;
+  body: {
+    message: string;
+    errors?: TAppNotificationApiError | TAppNotificationApiError[];
+  };
+};
+
+const error: TActionError = {
+  // ...
+  body: {
+    // ...
+    errors: [
+      {
+        message: 'This is the first error', // displayed as the notification text
+        code: 'Invalid',
+      },
+      {
+        message: 'This is the second error', // also displayed as the notification text
+        code: 'Invalid',
+      },
+    ],
+  },
+};

website/src/code-examples/api-reference/commercetools-frontend-actions-global/show-api-error-notification.jsx

@@ -0,0 +1,11 @@
+const errors = [
+  {
+    message: "A duplicate value '\"Test channel\"' exists for field 'key'.",
+    code: 'DuplicateField',
+    extensions: {
+      code: 'DuplicateField',
+    },
+  },
+];
+// ...
+dispatch(showApiErrorNotification({ errors })); // dispatch method from Redux store

website/src/code-examples/api-reference/commercetools-frontend-actions-global/show-api-error-notification.tsx

@@ -0,0 +1,20 @@
+type TAppNotificationApiError<ExtraFields extends {} = {}> = {
+  message: string;
+  /** @deprecated Use `extensions.code` */
+  code?: string;
+  extensions?: {
+    code?: string;
+  };
+} & ExtraFields;
+
+const errors: TAppNotificationApiError[] = [
+  {
+    message: "A duplicate value '\"Test channel\"' exists for field 'key'.",
+    code: 'DuplicateField',
+    extensions: {
+      code: 'DuplicateField',
+    },
+  },
+];
+// ...
+// dispatch(showApiErrorNotification({ errors })); // dispatch method from Redux store

website/src/code-examples/api-reference/commercetools-frontend-actions-global/show-notification.jsx

@@ -0,0 +1,7 @@
+import {
+  DOMAINS,
+  NOTIFICATION_KINDS_SIDE,
+} from '@commercetools-frontend/constants';
+
+const kind = NOTIFICATION_KINDS_SIDE.success;
+const domain = DOMAINS.SIDE;

website/src/code-examples/api-reference/commercetools-frontend-actions-global/show-notification.tsx

@@ -0,0 +1,7 @@
+import {
+  DOMAINS,
+  NOTIFICATION_KINDS_SIDE,
+} from '@commercetools-frontend/constants';
+
+const kind = NOTIFICATION_KINDS_SIDE.success;
+const domain = DOMAINS.SIDE;

website/src/code-examples/api-reference/commercetools-frontend-actions-global/use-hide-all-page-notifications.jsx

@@ -0,0 +1,4 @@
+import { useHideAllPageNotifications } from '@commercetools-frontend/actions-global';
+
+const hideAllPageNotifications = useHideAllPageNotifications();
+hideAllPageNotifications();

website/src/code-examples/api-reference/commercetools-frontend-actions-global/use-hide-all-page-notifications.tsx

@@ -0,0 +1,4 @@
+import { useHideAllPageNotifications } from '@commercetools-frontend/actions-global';
+
+const hideAllPageNotifications = useHideAllPageNotifications();
+hideAllPageNotifications();

website/src/code-examples/api-reference/commercetools-frontend-actions-global/use-on-action-error.jsx

@@ -0,0 +1,18 @@
+import { STATUS_CODES } from '@commercetools-frontend/constants';
+import { useOnActionError } from '@commercetools-frontend/actions-global';
+
+const error = {
+  statusCode: STATUS_CODES.FORBIDDEN, // statusCode: 403
+  body: {
+    message: "This is an error",
+    errors: [
+      {
+        message:
+          "This is an error",
+        code: "Invalid",
+      },
+    ],
+  },
+}
+const onActionError = useOnActionError();
+onActionError(error)