@cdmbase/wiki-browser 12.0.18-alpha.5

package/lib/templates/content/docs/feature-api/feature-browser/routes-menu.md

@@ -0,0 +1,110 @@
+---
+meta:
+    title: Routes and Menus
+    description: Routes and Menus
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Routes and Menus...
+headers:
+    Cache-Control: no-cache
+---
+
+## Routes and Menu
+
+Both `routes` and `menu` are depend on the `routeConfig` provided to `Feature`.
+
+Menu have extends `Feature's routeConfiguration` such as name, icon, locale, hideInMenu, hideChildrenInMenu and other configuration, so that it is easier to generate menus in one place.
+
+Check how [routing](./routing.md) works before checking the menu.
+
+### Menu
+
+The data format it as follows.
+
+```js
+export interface IMenuDataItem {
+    /**
+     * @name submenu
+     */
+    children?: IMenuDataItem[];
+    /**
+     * @name Hide child nodes in the menu
+     */
+    hideChildrenInMenu?: boolean;
+    /**
+     * @name hideSelf and children in menu
+     */
+    hideInMenu?: boolean;
+    /**
+     * @name Icon of the menu
+     */
+    icon?: React.ReactNode;
+    /**
+     * @name Internationalization key for custom menus
+     */
+    locale?: string | false;
+    /**
+     * @name The name of the menu
+     */
+    name?: string;
+    /**
+     * @name is used to calibrate the selected value, default is path
+     */
+    key?: string;
+    /**
+     * @name disable menu option
+     */
+    disabled?: boolean;
+    /**
+     * @name path
+     */
+    path?: string;
+    /**
+     * @name custom parent node
+     * @description When this node is selected, the node of parentKeys is also selected
+     */
+    parentKeys?: string[];
+    /**
+     * @name hides itself and elevates child nodes to its level
+     */
+    flatMenu?: boolean;
+
+    /**
+     * @name position of the Menu
+     * @enum `IMenuPosition`
+     */
+    position?: IMenuPosition;
+
+
+    /**
+     * @name permissions to determine whether to render menu or not
+     */
+    authority?: string[];
+
+    /**
+     * @name priority of the menu to display in the order. Lower values shows first.
+     */
+    priority?: number;
+
+    [key: string]: any;
+}
+
+export enum IMenuPosition {
+    LOGO = 'LOGO',
+    UPPER = 'UPPER',
+    MIDDLE = 'MIDDLE',
+    LOWER = 'LOWER',
+    BOTTOM = 'BOTTOM',
+}
+
+```
+
+A layout can be designed to render the menus based on it.
+
+### Position of menu
+
+Menu position is provided with `position`. The layout is when rendering the menu able to seperate the menu based on the position where it customized to render.
+
+### Customize the content of the menu
+
+With `menuItemRedner`, `subMenuItemRender`, `title`, `logo`, `menuHeaderRender` you can customize the menu style very easily. If you are really not satisfied, you can use `menuRender` to fully customize it.

package/lib/templates/content/docs/feature-api/feature-browser/routing-convention.md

@@ -0,0 +1,124 @@
+---
+meta:
+    title: Routing Convention
+    description: Routing Convention
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Routing Convention...
+headers:
+    Cache-Control: no-cache
+---
+
+## Component layout
+
+`compute.tsx` is used for saving all the routes related configuration. And it is get imported in `module.tsx`.
+
+```
+├── src
+│   ├── assets
+│   │   └── images
+│   │       ├── bank_account_helper.png
+│   │       ├── paypal_logo.png
+│   │       └── stripe_logo.png
+│   ├── contianers
+│   │   ├── Billing
+│   │   │   ├── Billing.tsx
+│   ├── compute.tsx
+│   ├── constants
+│   ├── index.tsx
+│   ├── module.tsx
+
+```
+
+compute.tsx
+
+```js
+export const basePath = '/o/:orgName/usermenu';
+export const modulePath = `${basePath}/billing`;
+const billingPageStore = [
+    // this would define the parent menu position of the billing menus
+    {
+        key: 'user-menu',
+        name: 'User Menu',
+        tab: 'User Menu',
+        path: basePath,
+        position: IMenuPosition.BOTTOM,
+        exact: false,
+    },
+    // this would define the submenu's parent of Billing
+    {
+        key: 'billing',
+        name: 'Billing',
+        tab: 'Billing',
+        path: modulePath,
+        auth: true,
+        exact: false,
+        authority: [IPreDefineBillingPermissions.viewSubscriptions],
+        component: React.lazy(() => import('./components/billing-tab')),
+    },
+    {
+        name: 'Home',
+        key: 'home',
+        tab: 'Home',
+        auth: true,
+        path: `${modulePath}/home`,
+        component: Home,
+        authority: [IPreDefineBillingPermissions.viewSubscriptions],
+    },
+];
+
+// add the `key` that you want to use in `routeConfig`
+const selectedRoutes = ['billing', 'home', 'user-menu'];
+const filteredBillingRoutes: IMappedData[] = getFilteredRoutes(billingPageStore, selectedRoutes);
+
+export const filteredRoutes: IMappedData[] = [...filteredBillingRoutes];
+```
+
+module.tsx
+
+```js
+import { Feature } from '@common-stack/client-react';
+import { filteredRoutes } from './compute';
+
+export const repository = new Feature({
+  routeConfig: filteredRoutes,
+  ...
+});
+
+```
+
+### Routing Security
+
+If the routes need a login user, set `auth: true`.
+
+example
+
+```js
+    {
+        name: 'Home',
+        key: 'home',
+        tab: 'Home',
+        auth: true,
+        ...
+    },
+```
+
+Under the hood it uses `authWrapper` set in the `Feature.authWrapper`.
+
+### Routing permissions
+
+If permssions are configured in the backend, you can restrict the URL based on the permission by setting `authority`.
+
+example
+
+```js
+
+    {
+        key: 'billing',
+        name: 'Billing',
+        ...
+        authority: [IPreDefineBillingPermissions.viewSubscriptions],
+        component: React.lazy(() => import('./components/billing-tab')),
+    },
+
+```

package/lib/templates/content/docs/feature-api/feature-browser/routing.md

@@ -0,0 +1,338 @@
+---
+meta:
+    title: Routing
+    description: Routing
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Routing...
+headers:
+    Cache-Control: no-cache
+---
+
+## Routing
+
+In Feature, application are single-page applications, and the page address jumps are done on the browser side, and the server will not be re-requested to html, and html is only loaded once when the application is initialized. All pages are compossed of different components. The switching of pages is actually the switching of different components. You only need to associate different routing paths with corresponding components in the confiugration.
+
+## Configuring Routing
+
+Configure through `routeConfig` in the configuration file, the format is an array of routing information.
+
+Example:
+
+```js
+const genRoutes = [
+    {
+        ['/ghost']: { component: Component },
+        ['/pepper']: { component: Component, exact: false },
+        ['/pepper/ginger']: { component: Component, exact: true },
+        ['/pepper/:type']: { component: Component, exact: false },
+        ['/pepper/:type/scoville']: { component: Component, exact: false },
+    },
+];
+
+const connector = new Feature({ routeConfig: genRoutes });
+```
+
+### path
+
+- Type: `string`
+
+`path` Only two placeholder configurations are supported, the first is `:` in the, and the second is in the form of `*` wildcards, which can only appear at the end of the routing string.
+
+### component
+
+- Type: `string`
+
+Configure the React component.
+
+### sub routes
+
+Configure sub-routes by based on the path. In order to have a sub route the parent path should have `exact: false`.
+
+Example:
+
+If you need a subroute to `/ginger` under `pepper`, the parent route `/pepper` should have `exact: false` and the sub-route should be prepend with parent path like `/peper/ginger`
+
+```js
+    const genRoutes = [
+        {
+            ['/pepper']: { component: Component, exact: false },
+            ['/pepper/ginger']: { component: Component, exact: true },
+    ];
+
+```
+
+This will result into
+
+```js
+const connectorRoutes = connector.getConfiguredRoutes();
+/** connectorRoutes = [
+                    {
+                path: '/pepper',
+                component: Component,
+                exact: false,
+                routes: [
+                    {
+                        path: '/pepper/ginger',
+                        component: Component,
+                        exact: true,
+                    },
+                ],
+            },
+    ]
+    **/
+```
+
+### redirect
+
+- Type `string`
+  Configure routing jumps.
+
+for example:
+
+```
+    const genRoutes = [
+        {
+            ['/']: { redirect: '/list' },
+            ['/list']: { component: Component, exact: true },
+    ];
+
+    const connector = new Feature({ routeConfig: genRoutes });
+```
+
+### wrappers
+
+- Type `string[]`
+  wrappers is HOC.
+
+For example, you can run validation check for a specific route.
+
+```js
+    const genRoutes = [
+        {
+            ['/user']: {
+              component: 'user',
+              wrappers: [ (props) => validationComp ]
+               },
+            ['/list']: { component: Component, exact: true },
+    ];
+
+```
+
+### title
+
+- Type: `string`
+  Configure the title of the route.
+
+## Route component parameters
+
+Feature uses `react-router@5` as a routing component. You can use all the routing hooks supported by `react-router@5`.
+
+Since `routeConfig` is a wrapper of `react-router@5`, it supprots all [Route Config](https://v5.reactrouter.com/web/example/route-config)
+
+Read react-router docs
+
+- [exact](https://v5.reactrouter.com/web/api/Route/exact-bool)
+- [strict](https://v5.reactrouter.com/web/api/Route/strict-bool)
+- [location](https://v5.reactrouter.com/web/api/Route/location-object)
+- [query params](https://v5.reactrouter.com/web/example/query-parameters)
+
+As well all of react-router@5 APIs are supproted.
+
+### Routing Dynamic Parameters
+
+```js
+const genRoutes = [
+    {
+        ['/pepper']: { component: Component, exact: false },
+        ['/pepper/:type']: { component: Component, exact: false },
+        ['/pepper/:type/scoville']: { component: ScovilleComponent, exact: true },
+    },
+];
+
+const connector = new Feature({ routeConfig: genRoutes });
+```
+
+Component
+
+```js
+import { useParams } from 'react-router';
+
+const ScovilleComponent = () => {
+    const params = useParams();
+}
+/**
+ for route `/pepper/lime/scoville`
+ //params
+ {
+   "type": "lime"
+ }
+
+```
+
+### generatePath
+
+Sometimes in a component we need to redirect. The generatePath function can be used to generate URLs to the routes.
+
+```js
+import { generatePath, useHistory } from 'react-router';
+
+const ROUTES = {
+    dashboard: '/o/:orgName/dashboard',
+};
+
+const onOrgSelection = (orgName: string) => {
+    const route = generatePath(ROUTES.dashboard, { orgName: 'test' });
+    // Will return `/o/test/dashboard`
+    history.push(route);
+};
+```
+
+## A realistic app may have Routes configured as below.
+
+Example:
+
+```js
+const orgRoutes = {
+    ['/']: { exact: true, component: MyComponent },
+    ['/login']: { exact: true, component: MyComponent },
+    ['/callback']: { exact: true, component: MyComponent },
+    ['/:orgName/usermenu/logout']: { exact: true, component: MyComponent },
+    ['/:orgName/usermenu/profile']: { exact: true, component: MyComponent },
+    ['/reset-password']: { exact: true, component: MyComponent },
+    ['/:orgName/usermenu/account/']: { exact: false, component: MyComponent },
+    ['/:orgName/usermenu/account']: { exact: false, component: MyComponent },
+    ['/:orgName/usermenu/account-settings']: { exact: true, component: MyComponent },
+    ['/:orgName/teams/view/:teamName']: { exact: false, component: MyComponent },
+    ['/:orgName/teams']: { exact: true, component: MyComponent },
+    ['/:orgName/invitation']: { exact: true, component: MyComponent },
+    ['/:orgName/members']: { exact: false, component: MyComponent },
+    ['/:orgName/dashboard']: { exact: true, component: MyComponent },
+    ['/:orgName/registries']: { exact: true, component: MyComponent },
+    ['/:orgName']: { exact: false, component: MyComponent },
+};
+```
+
+Under the hood it will generates to below `Object` before passing it to the `react-router-config` function.
+
+```js
+const reactRouterConfig = [
+    {
+        _pathPrefix: '',
+        component: [Function],
+        exact: true,
+        path: '/authenticate-popup',
+        position: 'MIDDLE',
+    },
+    {
+        _pathPrefix: '',
+        component: [Function],
+        exact: true,
+        path: '/callback',
+        position: 'MIDDLE',
+    },
+    {
+        _pathPrefix: '',
+        component: [Function],
+        exact: true,
+        path: '/reset-password',
+        position: 'MIDDLE',
+    },
+    {
+        _pathPrefix: '',
+        component: [Function],
+        exact: false,
+        name: 'rootSlash',
+        path: '/',
+        position: 'MIDDLE',
+        routes: [
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: false,
+                path: '/',
+                position: 'MIDDLE',
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: true,
+                path: '/:orgName/dashboard',
+                position: 'MIDDLE',
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: true,
+                path: '/:orgName/invitation',
+                position: 'MIDDLE',
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: false,
+                path: '/:orgName/members',
+                position: 'MIDDLE',
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: true,
+                path: '/:orgName/registries',
+                position: 'MIDDLE',
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: true,
+                path: '/:orgName/teams',
+                position: 'MIDDLE',
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: false,
+                path: '/:orgName/teams/view/:teamName',
+                position: 'MIDDLE',
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: false,
+                path: '/:orgName/usermenu/account',
+                position: 'MIDDLE',
+                routes: [
+                    {
+                        _pathPrefix: '/',
+                        component: [Function],
+                        exact: false,
+                        path: '/:orgName/usermenu/account/',
+                        position: 'MIDDLE',
+                    },
+                ],
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: true,
+                path: '/:orgName/usermenu/account-settings',
+                position: 'MIDDLE',
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: true,
+                path: '/:orgName/usermenu/logout',
+                position: 'MIDDLE',
+            },
+            {
+                _pathPrefix: '/',
+                component: [Function],
+                exact: true,
+                path: '/:orgName/usermenu/profile',
+                position: 'MIDDLE',
+            },
+        ],
+    },
+];
+```

package/lib/templates/content/docs/feature-api/feature-mobile/auth-permissions.md

@@ -0,0 +1,20 @@
+---
+meta:
+    title: Auth and Permissions
+    description: Auth and Permissions
+date: '2023-06-02T00:00:00'
+updated: '2024-06-02T00:00:00'
+excerpt: Auth and Permissions...
+headers:
+    Cache-Control: no-cache
+---
+
+## Auth and Permissions
+
+We have recently introduced the support of authentication wrapper to react navigation wrapper. The auth wrapper takes the two arguments One is the Component it self and other is the Unauthenticated Component, it validates if user is authenticated, if yes then it renders the component otherwise it checks if Unauthenticated component is passed then it renders that else it redirect to login
+
+<img width="744" alt="Screenshot 2022-11-28 at 1 39 51 AM" src="https://user-images.githubusercontent.com/30002668/204158578-873ac3b9-792b-4ef8-a130-8c87228af06d.png"/>
+
+In order to setup auth permission to route object you need to set property `auth: true`, you can also pass unauthenticated component as shown below
+
+<img width="941" alt="Screenshot 2022-11-28 at 2 10 32 AM" src="https://user-images.githubusercontent.com/30002668/204159871-49c03aa1-6ff3-4c5e-b6da-01bd307a20b3.png"/>