@akinon/projectzero 1.32.0 → 1.33.0

package/app-template/docs/data-fetching/server/widget.md

@@ -0,0 +1,218 @@
+---
+title: Widget
+sidebar_label: Widget
+slug: widget
+custom_edit_url: null
+---
+
+## getWidgetData
+
+This function is used to fetch data for widgets created in Omnitron.
+
+The **getWidgetData** function is imported from `'@akinon/next/data/server'`.
+
+```javascript
+import { getWidgetData } from '@akinon/next/data/server';
+```
+
+The widget data is fetched by defining this function as follow:
+
+```javascript
+const data = await getWidgetData({slug: 'gender-widget-order'});
+```
+
+- `slug`: The slug of the widget to be fetched needs to be provided as a parameter. This parameter is mandatory and should be of type String.
+
+Data returned from the function:
+
+```json
+{
+  "attributes": {
+    "widget_order": [
+      {
+        "value": {
+          "item_slug": "home-stories-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "home-hero-slider-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "countdown-banner-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "home-single-banner-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "home-categories-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "multiple-banner-1-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "new-arrivals-recommendation-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "multiple-banner-2-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "home-quad-category-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "multiple-banner-3-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "price-selector-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "best-sellers-recommendation-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "home-two-banner-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "multiple-banner-4-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "home-size-selector-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "multiple-banner-5-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "home-quad-category-3-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "home-quad-category-2-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "home-quad-category-4-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      },
+      {
+        "value": {
+          "item_slug": "category-seo-recommendation-men"
+        },
+        "kwargs": {
+          "value": {},
+          "data_type": "nested"
+        }
+      }
+    ]
+  },
+  "name": "Men Widget Order",
+  "template": "none",
+  "slug": "men-widget-order"
+}
+```

package/app-template/docs/delete-account.md

@@ -0,0 +1,25 @@
+# Delete Account
+
+To deactivate a user's account, a request is sent to the `useAnonymizeMutation` service. This service provides the user with the option to delete their account.
+
+The **useAnonymizeMutation** function is imported from `@akinon/next/data/client/account` as below:
+
+```js
+import { useAnonymizeMutation } from '@akinon/next/data/client/account';
+```
+
+To use the function, create a variable, call the **useAnonymizeMutation** function, and execute the request. The example below demonstrates when the **Delete My Account** button is clicked, the **deleteUser** function is invoked.
+
+```js
+const [ deleteUser, { isLoading: isDeleting, error: responseError, isError, isSuccess } ] = useAnonymizeMutation();
+
+return (
+  <Button onClick={() => deleteUser()}>
+    {isDeleting ? (
+      <LoaderSpinner />
+    ) : (
+      Delete My Account
+    )}
+  </Button>
+)
+```

package/app-template/docs/deployment.md

@@ -0,0 +1,46 @@
+
+## Deployment
+
+### Required Environment Variables
+
+Before initiating your application's deployment to ACC, it is important to set up the necessary environment variables. Please ensure you have added the following variables to your application before your first deployment:
+
+- **NEXT_PUBLIC_URL**: The website's URL, accessible from the ACC dashboard.
+- **NEXTAUTH_URL**: The website's URL, identical to NEXT_PUBLIC_URL.
+- **NEXTAUTH_SECRET**: A secret string for session encryption, generated from any online tool.
+- **CACHE_SECRET**: A secret string for encrypting Redis cache requests. Generate this using any online tool; without it, Redis cache may not function properly.
+
+### Add Remote Repository
+
+For deploying your application to ACC, the addition of a remote repository is required. Obtain the URL of the remote repository from the ACC dashboard.
+
+Run the following command to add the remote repository:
+
+```bash
+git remote add acc <acc-repository-url>
+```
+
+### Create and Push a Tag
+
+For deploying your application to ACC, create a tag within your repository. Ensure all changes are committed before proceeding.
+
+Run the following command to create a tag:
+
+```bash
+git tag <tag-name>
+```
+
+Then, push the tag to the remote repository:
+
+```bash
+git push acc <tag-name>
+```
+
+### Build Your Application
+
+Navigate to My Applications > {Your Application} > Builds. Click the **Build** button. Enter the tag name created in the previous step and click **Build** button.
+
+
+### Deploy Your Application
+
+Upon successful completion of the build, initiate the deployment by providing the same tag name and clicking the **Deploy** button.

package/app-template/docs/dynamic-route.md

@@ -0,0 +1,33 @@
+## Dynamic Route
+
+**Some Pages Where Dynamic Route is Used**
+
+-   `/users/email-set-primary/${TOKEN-ID}`
+-   `/users/registration/account-confirm-email/${TOKEN-ID}`
+
+The page **/users/email-set-primary/${TOKEN-ID}** is the page to which a user is directed when they change their email, using the token sent to the new email address. Upon signing in this page, the token value is obtained via params, and the `useChangeEmailVerificationQuery(id.join('/'))` function makes the API call. The user's new email address is updated through the API call.
+
+The page **/users/registration/account-confirm-email/${TOKEN-ID}** is the page to which a user is directed when they become a new member, using the token sent to their email address. Upon signing in this page, the token value is obtained via params, and the `useConfirmEmailVerificationQuery(id.join('/'))` function makes the API call. The verification of the user's email address is completed through the API call.
+
+**How to Use?**
+
+1. Create a folder in the main path of your page structure: 
+
+	`users > registration > acount-confirm-email > [[...id]] > page.tsx`
+
+2. Then, define an enum in `src > routes > index.ts`:
+
+	```typescript
+	enum AUTH_ROUTES {
+		EMAIL_SET_PRIMARY = '/users/email-set-primary/.+',
+		CONFIRM_EMAIL = '/users/registration/account-confirm-email/.+'
+	}
+	```
+
+3. To export the defined **AUTH_ROUTES**, assign the enum to the `ROUTES` variable at the bottom of the page:
+
+	```typescript
+	export  const  ROUTES = {
+		...AUTH_ROUTES
+	};
+	```

package/app-template/docs/icons.md

@@ -0,0 +1,52 @@
+---
+title: Generate Icons
+sidebar_label: Icons
+slug: icons
+custom_edit_url: null
+---
+
+SVG icons to be used in the project are stored under the `src/assets/icons` folder.
+
+```sh
+There are two different methods that can be used for icon usage.
+
+1. Icons can be used by generating an SVG Sprite.
+
+2. Icon fonts can be generated and used by using the VS Code extension developed by the Project Zero Team.
+```
+
+### Steps for Generating an Icon Font 
+
+1. Obtain and install the VS Code extension.
+
+2. Add the SVG icons you want to convert to an icon font under the `src/assets/icons` folder.
+
+3. Inside VS Code, open the command palette screen by using the shortcut `CMD + SHIFT + P` (or `CTRL + SHIFT + P`).
+
+4. In the command palette screen, run the `Generate Icons` command.
+
+5. After running the command, you will find the relevant files starting with `pz-icon` generated under the `src/assets/fonts` folder.
+
+6. Icon can now be used along with its name within the `<Icon>` component to generate the icon font.
+
+## Usage of the Icon Component
+
+Import the Icon component into the file where you want to use it.
+
+```sh
+import { Icon } from '../components';
+```
+
+Call the imported component within your page.
+
+```sh
+<Icon name="akinon" size={34} className="text-red" />
+```
+
+Props that the Icon component accepts:
+
+-   **`name` (string):** The name of the icon you want to use. This prop is mandatory.
+
+-   **`size` (number):** Used to specify the size of the icon. The default value is 18px.
+
+-   **`className` (string):** Used for additional styling for the icon (e.g., color).

package/app-template/docs/localization.md

@@ -0,0 +1,204 @@
+---
+title: Localization
+sidebar_label: Localization
+slug: localization
+custom_edit_url: null
+---
+
+Project Zero Next supports multiple languages and currencies, and all the necessary settings for language and currency management can be found within the settings.js file.
+
+## Locales
+
+### Adding a New Locale
+
+To add a new locale to the project, follow these steps:
+
+1.  Open the settings.js file.
+2.  Locate the **localization** section.
+3.  Inside the **locales** array, add a new object with the following properties:
+
+| Property | Description |
+| --- | --- |
+| label | A label that can be displayed on any page of the website. |
+| value | The lowercase locale value in ISO 639-1 format or including the country code in ISO 3166-1 alpha-2 format. |
+| localePath | Name of the locale's JSON translation file. For example, if the value is "en," the file should be placed in the public/locales/en directory. |
+| apiValue | The value of the locale defined in Commerce. |
+| rtl | A boolean value that specifies whether it is right-to-left, like Arabic. |
+
+Here's an example of adding a new locale:
+
+```javascript
+localization: {
+  locales: [
+    {
+      label: 'EN',
+      value: 'en',
+      localePath: 'en',
+      apiValue: 'en-us',
+      rtl: false,
+    },
+  ],
+}
+```
+
+### Default Locale
+
+The default locale for the project can be specified by using the **defaultLocaleValue** in the settings.js file. This value should match the "value" of one of the defined locales.
+
+### Setting a Locale
+
+To set a locale in the project, the **setLocale** method available in the useLocalization hook can be used. This method will automatically change the URL to reflect the selected locale.
+
+Example of using **setLocale**:
+
+```javascript
+const { setLocale } = useLocalization();
+
+setLocale('en-us');
+```
+
+### Disabling Redirection to Default Locale
+
+In some cases, like displaying a landing page on example.com/ while using the ShowAllLocales strategy, users are automatically redirected to URLs containing the default locale (e.g., example.com/en). To disable this redirection, set **redirectToDefaultLocale** to false in the settings.js file:
+
+```javascript
+localization: {
+  redirectToDefaultLocale: false,
+}
+```
+
+## Currencies
+
+### Adding a New Currency
+
+To add a new currency to the project, follow these steps:
+
+1.  Open the settings.js file.
+2.  Locate the **currencies** section.
+3.  Inside the **currencies** array, add a new object with the following properties:
+    -   **label**: The label for the currency (e.g., 'USD').
+    -   **code**: The code for the currency (e.g., 'usd').
+
+Here's an example of adding a new currency:
+
+```javascript
+currencies: [
+  {
+    label: 'USD',
+    code: 'usd',
+  },
+]
+```
+
+### Default Currency
+
+The default currency in the project can be specified by using the **defaultCurrencyCode** in the settings.js file. This code must match the "code" of one of the defined currencies.
+
+### Determining Active Currency
+
+The **getActiveCurrencyCode** function's default behavior is to retrieve the active currency code from a cookie named `pz-currency`. Users can customize this function to obtain the currency code from different sources, such as headers or the URL. If the return value doesn't match any currency code in the `currencies` array, the default currency code will be used.
+
+Here's an example:
+
+```javascript
+getActiveCurrencyCode: ({ req, locale, defaultCurrencyCode }) => {
+  const [, countryCode] = locale.split('-');
+
+  if (countryCode === 'ae') {
+    return 'aed';
+  } else if (countryCode === 'qa') {
+    return 'qar';
+  }
+
+  return defaultCurrencyCode;
+}
+```
+
+### Setting a Currency
+
+To set a currency in the project, the **setCurrency** method available in the useLocalization hook can be used.
+
+Important: If the currency is linked to the locale by using `getActiveCurrencyCode` function in the settings, you need to use `setLocale` instead of this.
+
+Example of using **setCurrency**:
+
+```javascript
+const { setCurrency } = useLocalization();
+
+setCurrency('usd');
+```
+
+Important: Basket will be cleared when the currency is changed. Both of `setCurrency` and `setLocale` methods will clear the basket automatically.
+
+## URL Strategy
+
+Project Zero Next supports multiple URL structures to cater to different requirements. Users can set the URL strategy using the **localeUrlStrategy** value in settings.js.
+
+Example of setting the URL strategy:
+
+```javascript
+localization: {
+  localeUrlStrategy: LocaleUrlStrategy.ShowAllLocales,
+}
+```
+
+The available values for **localeUrlStrategy** are:
+
+-   LocaleUrlStrategy.HideDefaultLocale
+-   LocaleUrlStrategy.HideAllLocales
+-   LocaleUrlStrategy.ShowAllLocales
+
+LocaleUrlStrategy.HideDefaultLocale:
+
+-   For English (en): "/women"
+-   For Turkish (tr): "/tr/women"
+
+LocaleUrlStrategy.ShowAllLocales:
+
+-   For English (en): "/en/women"
+-   For Turkish (tr): "/tr/women"
+
+LocaleUrlStrategy.HideAllLocales:
+
+-   For English (en): "/women"
+-   For Turkish (tr): "/women"
+
+> **Note:** The "HideAllLocales" option is not recommended for SEO purposes.
+
+## Translations
+
+Translations can be managed by adding key-value pairs to JSON files located under the public/locales directory. For example, if the English (en) locale is used, translation files can be stored in public/locales/en/account.json.
+
+## Localization in Components
+
+### Client Components
+
+The **useLocalization** hook provides all the necessary properties for localization in client components. To make use of translations in the client components, use the "**t**" function as shown in the example below:
+
+```javascript
+import { useLocalization } from '@akinon/next/hooks';
+
+const {
+  t,
+  currencies,
+  currency,
+  defaultCurrencyCode,
+  locales,
+  locale,
+  defaultLocaleValue,
+  localeUrlStrategy,
+  setLocale,
+} = useLocalization();
+
+const translatedText = t('account.change_email.header.title');
+```
+
+### Server Components
+
+For server components, the "**t**" function can be imported from the following path to access translations:
+
+```javascript
+import { t } from '@akinon/next/utils/server-translation';
+
+const translatedText = t('account.change_email.header.title');
+```

package/app-template/docs/logging.md

@@ -0,0 +1,48 @@
+# Log Documentation
+
+## Import logger interface
+
+```typescript
+import logger from '@akinon/next/utils/log';
+```
+
+## Available Log Levels
+
+- trace
+- debug
+- info
+- warn
+- error
+- fatal
+
+## Set Environment Variables for Debug Levels in Console
+
+#### For development mode `yarn dev`
+``LOG_LEVEL_DEV=trace``
+
+#### For production mode `yarn start`
+``LOG_LEVEL=error``
+
+## Function Signature
+
+```typescript
+debug(message: string, payload: any): void;
+```
+
+## Example usage
+
+```typescript
+import logger from '@akinon/next/utils/log';
+
+const payload = {
+  id: 1,
+  username: 'akinon'
+};
+
+logger.debug('Logged user', payload);
+```
+---
+
+**Important note: Setting levels lower than the "info" level (for example, debug and trace) in the production environment may cause significant performance problems. Please do not use levels such as debug and trace for a long time.**
+
+**Using a logger in client-side codes (for example, in client components) writes the log to the browser's console. Please make sure you are not logging sensitive content on the client-side.**

package/app-template/docs/plugins.md

@@ -0,0 +1,76 @@
+---
+title: Plugins
+sidebar_label: Plugins
+slug: plugins
+custom_edit_url: null
+---
+
+To access and manage plugins for your Project Zero CLI, run the following command:
+
+```css
+npx projectzero --plugins
+``` 
+
+The plugins selected from this list will be added to the project and ready for use. The plugins can be removed from the project by unchecking it from the same list.
+
+### Plugin List
+
+1. Masterpass
+2. Basket Gift Pack
+3. Checkout Gift Pack
+4. Checkout Providers
+5. OTP
+6. Redirection Payment
+7. Click & Collect
+
+## Installation
+
+1. To install plugins, run the following command in the console:
+
+    ```css
+    npx projectzero --plugins
+    ```
+
+2. Select the plugins desire to install from the list provided.
+
+### Masterpass
+
+The Masterpass plugin enables users to make payments with their Masterpass-registered cards on the payment page. With this plugin, operations such as listing Masterpass-registered cards, adding new cards, and removing cards can be performed.
+
+[Click here for details](https://bitbucket.org/akinonteam/pz-masterpass/src/main/)
+
+### Basket Gift Pack
+
+This plugin allows for the addition of gift pack and gift note or just a gift note for products on the basket page.
+
+[Click here for details](https://bitbucket.org/akinonteam/pz-basket-gift-pack/src/main/)
+
+### Checkout Gift Pack
+
+Used to enable the gift pack option for products on the payment page.
+
+[Click here for details](https://bitbucket.org/akinonteam/pz-checkout-gift-pack/src/main/)
+
+### Checkout Providers
+
+This plugin is used to add payment methods to the checkout process.
+
+[Click here for details](https://bitbucket.org/akinonteam/pz_checkout_providers/src/master/)
+
+### OTP
+
+This application provides SMS verification (OTP) support for desired actions such as registration and updating profile information.
+
+[Click here for details](https://bitbucket.org/akinonteam/pz_otp/src/master/)
+
+### Redirection Payment
+
+Used to enable any payment option with a redirection type on the payment page.
+
+[Click here for details](https://bitbucket.org/akinonteam/pz-redirection-payment/src/main/)
+
+### Click & Collect
+
+This plugin enables the "Click & Collect" in-store pickup option.
+
+[Click here for details](https://bitbucket.org/akinonteam/pz-click-collect/src/main/)