strapi-plugin-navigation 2.0.12 → 2.1.0-beta.2

package/README.md

@@ -36,6 +36,22 @@ Strapi Navigation Plugin provides a website navigation / menu builder feature fo
 - Tree (nested)
 - RFR (ready for handling by Redux First Router)
 
+### Table of Contents
+1. [✨ Features](#-features)
+2. [⏳ Installation](#-installation)
+3. [🖐 Requirements](#-requirements)
+4. [🔧 Basic Configuration](#-configuration)
+   - [Settings page](#in-v203-and-newer)
+   - [Plugin file](#in-v202-and-older--default-configuration-state-for-v203-and-newer)
+5. [🔧 GraphQL Configuration](#-gql-configuration)
+6. [🌍 i18n Internationalization](#-i18n-internationalization)
+7. [🕸️ Public API specification](#%EF%B8%8F-public-api-specification)
+   - [REST API](#rest-api) 
+   - [GraphQL API](#graphql-api)
+8. [💬 FAQ](#-faq)
+10. [🤝 Contributing](#-contributing)
+11. [👨‍💻 Community support](#-community-support)
+
 ## ✨ Features
 
 - **Navigation Public API:** Simple and ready for use API endpoint for consuming the navigation structure you've created
@@ -43,6 +59,8 @@ Strapi Navigation Plugin provides a website navigation / menu builder feature fo
 - **Any Content Type relation:** Navigation can by linked to any of your Content Types by default. Simply, you're controlling it and also limiting available content types by configuration props
 - **Different types of navigation items:** Create navigation with items linked to internal types, to external links or wrapper elements to keep structure clean 
 - **Multiple navigations:** Create as many Navigation containers as you want, setup them and use in the consumer application
+- **Light / Dark mode compatible:** By design we're supporting Strapi ☀️ Light / 🌙 Dark modes 
+- **Webhooks integration:** Changes to navigation will trigger 'entry.update' or 'entry.create' webhook events. 
 - **Customizable:** Possibility to customize the options like: available Content Types, Maximum level for "attach to menu", Additional fields (audience)
 - **[Audit log](https://github.com/VirtusLab/strapi-molecules/tree/master/packages/strapi-plugin-audit-log):** integration with Strapi Molecules Audit Log plugin that provides changes track record
 
@@ -53,13 +71,23 @@ Strapi Navigation Plugin provides a website navigation / menu builder feature fo
 
 ## ⏳ Installation
 
+### Via Strapi Markerplace
+
+As a ✅ **verified** plugin by Strapi team we're available on the [**Strapi Marketplace**](https://market.strapi.io/plugins/strapi-plugin-navigation) as well as **In-App Marketplace** where you can follow the installation instructions.
+
+<div style="margin: 20px 0" align="center">
+  <img style="width: 100%; height: auto;" src="public/assets/marketplace.png" alt="Strapi In-App Marketplace" />
+</div>
+
+### Via command line
+
 It's recommended to use **yarn** to install this plugin within your Strapi project. [You can install yarn with these docs](https://yarnpkg.com/lang/en/docs/install/).
 
 ```bash
 yarn add strapi-plugin-navigation@latest
 ```
 
-After successful installation you've to build a fresh package that includes  plugin UI. To archive that simply use:
+After successful installation you've to re-build your Strapi instance. To archive that simply use:
 
 ```bash
 yarn build
@@ -74,7 +102,15 @@ yarn develop --watch-admin
 
 The **UI Navigation** plugin should appear in the **Plugins** section of Strapi sidebar after you run app again.
 
-Enjoy 🎉
+You can manage your multiple navigation containers by going to the **Navigation** section of the **Content Manager**.
+
+<div style="margin: 20px 0" align="center">
+  <img style="width: 100%; height: auto;" src="public/assets/content-manager.png" alt="Strapi In-App Marketplace" />
+</div>
+
+As a next step you must configure your the plugin by the way you want to. See [**Configuration**](#🔧-configuration) section.
+
+All done. Enjoy 🎉
 
 ## 🖐 Requirements
 
@@ -82,7 +118,7 @@ Complete installation requirements are exact same as for Strapi itself and can b
 
 **Supported Strapi versions**:
 
-- Strapi v4.1.5 (recently tested)
+- Strapi v4.1.11 (recently tested)
 - Strapi v4.x
 
 > This plugin is designed for **Strapi v4** and is not working with v3.x. To get version for **Strapi v3** install version [v1.x](https://github.com/VirtusLab-Open-Source/strapi-plugin-navigation/tree/strapi-v3).
@@ -91,9 +127,17 @@ Complete installation requirements are exact same as for Strapi itself and can b
 
 ## 🔧 Configuration
 
+To start your journey with **Navigation plugin** you must first setup it using the dedicated Settings page (`v2.0.3` and newer) or for any version, put your configuration in `config/plugins.js`. Anyway we're recommending the click-through option where your configuration is going to be properly validated.
+
 ### In `v2.0.3` and newer
 
-Version `2.0.3` introduces the intuitive **Settings** page which you can easily access via `Strapi Settings -> Section: Navigation Plugin -> Configuration`. On the dedicated page, you will be able to set up all crucial properties which drive the plugin and customize each individual collection for which **Navigation plugin** should be enabled.
+Version `2.0.3` introduces the intuitive **Settings** page which you can easily access via `Strapi Settings -> Section: Navigation Plugin -> Configuration`. 
+
+On the dedicated page, you will be able to set up all crucial properties which drive the plugin and customize each individual collection for which **Navigation plugin** should be enabled.
+
+<div style="margin: 20px 0" align="center">
+  <img style="width: 100%; height: auto;" src="public/assets/configuration.png" alt="Plugin configuration" />
+</div>
 
 > *Note*
 > The default configuration for your plugin is fetched from `config/plugins.js` or, if the file is not there, directly from the plugin itself. If you would like to customize the default state to which you might revert, please follow the next section.
@@ -129,6 +173,7 @@ Config for this plugin is stored as a part of the `config/plugins.js` or `config
 - `contentTypes` - UIDs of related content types
 - `contentTypesNameFields` - Definition of content type title fields like `'api::<collection name>.<content type name>': ['field_name_1', 'field_name_2']`, if not set titles are pulled from fields like `['title', 'subject', 'name']`. **TIP** - Proper content type uid you can find in the URL of Content Manager where you're managing relevant entities like: `admin/content-manager/collectionType/< THE UID HERE >?page=1&pageSize=10&sort=Title:ASC&plugins[i18n][locale]=en`
 - `gql` - If you're using GraphQL that's the right place to put all necessary settings. More **[ here ](#gql-configuration)**
+- `i18nEnabled` - should you want to manage multi-locale content via navigation set this value `Enabled`. More **[ here ](#i18n-internationalization)**
 
 ## 🔧 GQL Configuration
 Using navigation with GraphQL requires both plugins to be installed and working. You can find installation guide for GraphQL plugin **[here](https://docs.strapi.io/developer-docs/latest/plugins/graphql.html#graphql)**.  To properly configure GQL to work with navigation you should provide `gql` prop. This should contain union types that will be used to define GQL response format for your data while fetching:
@@ -159,6 +204,38 @@ gql: {
 ```
 where `Page` and `UploadFile` are your type names for the **Content Types** you're referring by navigation items relations. 
 
+## 🌍 i18n Internationalization
+
+### Settings
+
+This feature is **opt-in**.
+
+In order to use this functionality setting **default locale** is required. (See: Settings -> Internationalization)
+
+Once feature is enabled a restart is required. On server startup missing navigations for other locales will be created. From then you can manage navigation's localizations just like before.
+
+If you want go back to _pre-i18n_ way you can disable it in settings. Already created navigations will not be removed unless you make a choice for plugin to do so(this will require a restart).
+
+If your newly created navigation localization is empty you can copy contents of one version's to the empty one. If related item is localized and locale version exists localization will be used as a related item. Otherwise plugin will fallback to an original item.
+
+### Rendering
+
+Shape of the rendered navigation will not change. Querying stays almost the same. To query for specific locale version just add `locale` query param. For example:
+
+```https://yourdomain.cool/api/navigation/render/1?locale=fr```
+
+or
+
+```https://yourdomain.cool/api/navigation/render/main-navigation?locale=fr```
+
+If `locale` is not specified whatever version used to be at id `1` will be returned.
+
+Of course if you know that `fr` version is present at id `2` you can just query for that.
+
+### GraphQL
+
+If feature is enabled GQL render navigation query is expanded to handle `locale` param(it will work the same as regular requests). Checkout schema provided by GraphQL plugin.
+
 ## 👤 RBAC
 Plugin provides granular permissions based on Strapi RBAC functionality.
 
@@ -169,7 +246,7 @@ For any role different than **Super Admin**, to access the **Navigation panel**
 ## Base Navigation Item model
 
 ### Flat
-```
+```json
 {
     "id": 1,
     "title": "News",
@@ -182,13 +259,13 @@ For any role different than **Super Admin**, to access the **Navigation panel**
     "master": 1, // Navigation 'id'
     "createdAt": "2020-09-29T13:29:19.086Z",
     "updatedAt": "2020-09-29T13:29:19.128Z",
-    "related": [ <Content Type model > ],
+    "related": {/*<Content Type model >*/ },
     "audience": []
 }
 ```
 
 ### Tree
-```
+```json
 {
     "title": "News",
     "menuAttached": true,
@@ -198,7 +275,7 @@ For any role different than **Super Admin**, to access the **Navigation panel**
     "slug": "benefits",
     "external": false,
     "related": {
-        <Content Type model >
+        // <Content Type model >
     },
     "items": [
         {
@@ -209,13 +286,13 @@ For any role different than **Super Admin**, to access the **Navigation panel**
             "uiRouterKey": "generic",
             "external": true
         },
-        < Tree Navigation Item models >
+       //  < Tree Navigation Item models >
     ]
 }
 ```
 
 ### RFR
-```
+```json
 {
     "id": "News",
     "title": "News",
@@ -234,33 +311,41 @@ For any role different than **Super Admin**, to access the **Navigation panel**
 
 ## 🕸️ Public API specification
 
-### Query Params 
+Plugin supports both **REST API** and **GraphQL API** exposed by Strapi.
+
+**Query Params**
 
-- `type` - Enum value representing structure type of returned navigation 
+- `navigationIdOrSlug` - ID or slug for which your navigation structure is generated like for REST API:
 
-    **Example URL**: `https://localhost:1337/api/navigation/render/1?type=FLAT`
+  > `https://localhost:1337/api/navigation/render/1`
+  > `https://localhost:1337/api/navigation/render/main-menu`
 
-- `menu` - Boolean value for querying only navigation items that are attached to menu should be rendered eg.
+- `type` - Enum value representing structure type of returned navigation:
+  > `https://localhost:1337/api/navigation/render/1?type=FLAT`
 
-    **Example URL**: `https://localhost:1337/api/navigation/render/1?menu=true`
+- `menu` (`menuOnly` for GQL) - Boolean value for querying only navigation items that are attached to menu should be rendered eg.
+  > `https://localhost:1337/api/navigation/render/1?menu=true`
 
-- `path` - String value for querying navigation items by its path 
+- `path` - String value for querying navigation items by its path:
+  > `https://localhost:1337/api/navigation/render/1?path=/home/about-us`
 
-    **Example URL**: `https://localhost:1337/api/navigation/render/1?path=/home/about-us`
+### REST API
 
-### Render
+> **Important!**
+> Version `v2.0.13` introduced breaking change!
+> All responses have changed their structure. Related field will now be of type ContentType instead of Array\<ContentType\>
 
-`GET <host>/api/navigation/render/<idOrSlug>?type=<type>`
+`GET <host>/api/navigation/render/<navigationIdOrSlug>?type=<type>`
 
-Return a rendered navigation structure depends on passed type (`tree`, `rfr` or nothing to render as `flat/raw`).
+Return a rendered navigation structure depends on passed type (`TREE`, `RFR` or nothing to render as `FLAT`).
 
-*Note: The ID of navigation by default is `1`, that's for future extensions and multi-navigation feature.*
+> The ID of navigation by default is `1`, if you've got defined multiple navigations you must work with their IDs or Slugs to fetch.
 
 **Example URL**: `https://localhost:1337/api/navigation/render/1`
 
 **Example response body**
 
-```
+```json
 [
     {
         "id": 1,
@@ -274,22 +359,22 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
         "master": 1,
         "created_at": "2020-09-29T13:29:19.086Z",
         "updated_at": "2020-09-29T13:29:19.128Z",
-        "related": [{
+        "related": {
             "__contentType": "Page",
             "id": 1,
             "title": "News",
-            ...
-        }]
+            // ...
+        }
     },
-    ...
+    // ...
 ]
 ```
 
-**Example URL**: `https://localhost:1337/api/navigation/render/1?type=tree`
+**Example URL**: `https://localhost:1337/api/navigation/render/1?type=TREE`
 
 **Example response body**
 
-```
+```json
 [
     {
         "title": "News",
@@ -303,7 +388,7 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
             "__contentType": "Page",
             "id": 1,
             "title": "News",
-            ...
+            // ...
         },
         "items": [
             {
@@ -314,18 +399,18 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
                 "uiRouterKey": "generic",
                 "external": true
             },
-            ...
+            // ...
         ]
     },
-    ...
+    // ...
 ]
 ```
 
-**Example URL**: `https://localhost:1337/api/navigation/render/1?type=rfr`
+**Example URL**: `https://localhost:1337/api/navigation/render/1?type=RFR`
 
 **Example response body**
 
-```
+```json
 {
     "pages": {
         "News": {
@@ -370,7 +455,7 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
             "parent": "Community",
             "menuAttached": false
         },
-        ...
+        // ...
     },
     "nav": {
         "root": [
@@ -389,7 +474,7 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
                 "type": "external",
                 "url": "http://example.com"
             },
-            ...
+            // ...
         ],
         "Community": [
             {
@@ -397,10 +482,113 @@ Return a rendered navigation structure depends on passed type (`tree`, `rfr` or
                 "type": "internal",
                 "page": "Highlights"
             },
-            ...
+            // ...
         ],
-        ...
+        // ...
+    }
+}
+```
+
+### GraphQL API
+
+Same as [**REST API**](#rest-api) returns a rendered navigation structure depends on passed type (`TREE`, `RFR` or nothing to render as `FLAT`).
+
+**Example request**
+
+```graphql
+query {
+  renderNavigation(
+    navigationIdOrSlug: "main-navigation"
+    type: TREE
+    menuOnly: false
+  ) {
+    id
+    title
+    path
+    related {
+      id
+      attributes {
+        __typename
+
+        ... on Page {
+          Title
+        }
+
+        ... on WithFlowType {
+          Name
+        }
+      }
     }
+    items {
+      id
+      title
+      path
+      related {
+        id
+        attributes {
+          __typename
+
+          ... on Page {
+            Title
+          }
+
+          ... on WithFlowType {
+            Name
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Example response**
+
+```json
+{
+  "data": {
+    "renderNavigation": [
+      {
+        "id": 8,
+        "title": "Test page",
+        "path": "/test-path",
+        "related": {
+          "id": 3,
+          "attributes": {
+            "__typename": "WithFlowType",
+            "Name": "Test"
+          }
+        },
+        "items": [
+          {
+            "id": 11,
+            "title": "Nested",
+            "path": "/test-path/nested-one",
+            "related": {
+              "id": 1,
+              "attributes": {
+                  "__typename": "Page",
+                "Title": "Eg. Page title"
+              }
+            }
+          }
+        ]
+      },
+      {
+        "id": 10,
+        "title": "Another page",
+        "path": "/another",
+        "related": {
+          "id": 2,
+          "attributes": {
+            "__typename": "Page",
+            "Title": "dfdfdf"
+          }
+        },
+        "items": []
+      }
+    ]
+  }
 }
 ```
 
@@ -416,13 +604,22 @@ For single types a global name of this content type will be used as a template n
 
 Live example of plugin usage can be found in the [VirtusLab Strapi Examples](https://github.com/VirtusLab/strapi-examples/tree/master/strapi-plugin-navigation) repository.
 
-## 💬 Q&A
+## 💬 FAQ
 
-### Content Types
+### GraphQL tricks
 
-**Q:** I've recognized **Navigation Item** and **Navigation** collection types in the Collections sidebar section, but they are not working properly. What should I do?
+**Q:** I would like to use GraphQL schemas but I'm not getting renderNavigation query or even proper types as Navigation, NavigationItem etc. What should I do?
 
-**A:** As an authors of the plugin we're not supporting any editing of mentioned content types via built-in Strapi Content Manager. Plugin delivers highly customized & extended functionality which might be covered only by dedicated editor UI accessible via **Plugins Section > UI Navigation**. Only issues that has been recognized there, are in the scope of support we've providing.
+**A:** **A:** There is a one trick you might try. Strapi by default is ordering plugins by the way which takes `strapi-plugin-graphql` to initialize earlier than other plugins so types might not be injected. If you don't have it yet, please create `config/plugins.js` file and put there following lines (put `graphql` at the end):
+
+```js
+module.exports = {
+  'navigation': { enabled: true },
+  'graphql': { enabled: true },
+};
+```
+
+If you already got it, make sure that `navigation` plugin is inserted before `graphql`. That should do the job.
 
 ## 🤝 Contributing
 
@@ -437,6 +634,28 @@ Live example of plugin usage can be found in the [VirtusLab Strapi Examples](htt
 
 Feel free to fork and make a Pull Request to this plugin project. All the input is warmly welcome!
 
+- Clone repository
+
+    ```
+    git clone git@github.com:VirtusLab-Open-Source/strapi-plugin-navigation.git
+    ```
+
+- Create a soft link in your strapi project to plugin build folder
+
+    ```sh
+    ln -s <...>/strapi-plugin-navigation/build <...>/strapi-project/src/plugins/navigation 
+    ```
+
+- Run build command 
+
+    ```ts
+    // Watch for file changes
+    yarn develop
+
+    // or run build without nodemon
+    yarn build:dev
+    ```
+
 ## 👨‍💻 Community support
 
 For general help using Strapi, please refer to [the official Strapi documentation](https://strapi.io/documentation/). For additional help, you can use one of these channels to ask a question:

package/admin/src/components/Alert/styles.d.ts

@@ -0,0 +1,2 @@
+export const PermanentAlert: any;
+//# sourceMappingURL=styles.d.ts.map

package/admin/src/components/Alert/styles.js

@@ -1,8 +1,14 @@
-import styled from 'styled-components';
-import { Alert } from '@strapi/design-system/Alert';
-
-export const PermanentAlert = styled(Alert)`
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermanentAlert = void 0;
+const styled_components_1 = __importDefault(require("styled-components"));
+const Alert_1 = require("@strapi/design-system/Alert");
+exports.PermanentAlert = (0, styled_components_1.default)(Alert_1.Alert) `
  button {
      display: none;
  }
 `;
+//# sourceMappingURL=styles.js.map

package/admin/src/components/CollapseButton/index.d.ts

@@ -0,0 +1,7 @@
+export default CollapseButton;
+declare function CollapseButton({ toggle, collapsed, itemsCount }: {
+    toggle: any;
+    collapsed: any;
+    itemsCount: any;
+}): JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/admin/src/components/CollapseButton/index.js

@@ -1,11 +1,15 @@
-import React from 'react';
-import styled from 'styled-components'
-import { Flex } from '@strapi/design-system/Flex';
-import { Typography } from '@strapi/design-system/Typography';
-import { Icon } from '@strapi/design-system/Icon';
-import { CarretUp, CarretDown } from '@strapi/icons';
-
-const Wrapper = styled.div`
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = __importDefault(require("react"));
+const styled_components_1 = __importDefault(require("styled-components"));
+const Flex_1 = require("@strapi/design-system/Flex");
+const Typography_1 = require("@strapi/design-system/Typography");
+const Icon_1 = require("@strapi/design-system/Icon");
+const icons_1 = require("@strapi/icons");
+const Wrapper = styled_components_1.default.div `
 	border-radius: 50%;
 	background: #DCDCE4;
 	width: 25px;
@@ -15,17 +19,12 @@ const Wrapper = styled.div`
 	align-items: center;
 	margin-right: 8px;
 `;
-
-const CollapseButton = ({ toggle, collapsed, itemsCount }) => (
-	<Flex justifyContent='space-between' alignItems='center' onClick={toggle} cursor="pointer" style={{ marginRight: '16px' }}>
-		<Wrapper>
-			{ collapsed ?
-				<Icon as={CarretDown} width='7px' height='4px' /> :
-				<Icon as={CarretUp} width='7px' height='4px' />
-			}
-		</Wrapper>
-		<Typography variant="pi">{itemsCount} nested items</Typography>
-	</Flex >
-);
-
-export default CollapseButton;
+const CollapseButton = ({ toggle, collapsed, itemsCount }) => (react_1.default.createElement(Flex_1.Flex, { justifyContent: 'space-between', alignItems: 'center', onClick: toggle, cursor: "pointer", style: { marginRight: '16px' } },
+    react_1.default.createElement(Wrapper, null, collapsed ?
+        react_1.default.createElement(Icon_1.Icon, { as: icons_1.CarretDown, width: '7px', height: '4px' }) :
+        react_1.default.createElement(Icon_1.Icon, { as: icons_1.CarretUp, width: '7px', height: '4px' })),
+    react_1.default.createElement(Typography_1.Typography, { variant: "pi" },
+        itemsCount,
+        " nested items")));
+exports.default = CollapseButton;
+//# sourceMappingURL=index.js.map

package/admin/src/components/ConfirmationDialog/index.d.ts

@@ -0,0 +1,28 @@
+export default ConfirmationDialog;
+declare function ConfirmationDialog({ isVisible, isActionAsync, children, onConfirm, onCancel, header, labelCancel, labelConfirm, iconConfirm, mainIcon }: {
+    isVisible?: boolean | undefined;
+    isActionAsync?: boolean | undefined;
+    children: any;
+    onConfirm: any;
+    onCancel: any;
+    header: any;
+    labelCancel: any;
+    labelConfirm: any;
+    iconConfirm: any;
+    mainIcon?: JSX.Element | undefined;
+}): JSX.Element;
+declare namespace ConfirmationDialog {
+    namespace propTypes {
+        const isVisible: PropTypes.Requireable<boolean>;
+        const isActionAsync: PropTypes.Requireable<boolean>;
+        const children: PropTypes.Requireable<any>;
+        const header: PropTypes.Requireable<string>;
+        const labelCancel: PropTypes.Requireable<string>;
+        const labelConfirm: PropTypes.Requireable<string>;
+        const iconConfirm: PropTypes.Requireable<object>;
+        const onConfirm: PropTypes.Validator<(...args: any[]) => any>;
+        const onCancel: PropTypes.Validator<(...args: any[]) => any>;
+    }
+}
+import PropTypes from "prop-types";
+//# sourceMappingURL=index.d.ts.map