@bydata/react-supertabs 1.1.9 → 1.2.0

package/dist/Readme.md

@@ -1,258 +1,320 @@
-
 # SuperTabs
 
-**SuperTabs** is a powerful and user-friendly tab management component. It enables seamless navigation by opening modules as tabs, with support for sub-tabs, smooth transitions. An experimental _keep-alive_ feature ensures components stay active across tab switches for enhanced usability.
-
-### SuperTabs Features
-------
--   **Tab-based Navigation**: Open modules as tabs for an intuitive and efficient navigation experience.
--   **Sub-Tabs Support**: Create nested sub-tabs within a main tab for hierarchical organization.
--   **Smooth Transitions**: Enjoy a polished user experience with fluid tab-switching animations.
--   **Keep-Alive (Experimental)**: Maintain the state of components across tab switches for seamless interaction (experimental feature).
-
-### Installation and usage
-------
-
-#### Basic
-
->**Import TabProvider and wrap it around the main wrapper**
-
- - This is needed to access useTabContext.
- - Make sure to pass `SITE_PREFIX` and `SITE_PAGES` (From Navigation.js)
- - `homeUrl` is optional and defaults to "/"
- - `persistTabsAfterLogin` is optional and defaults to "false"
-    - Used to preserve tab state upon login.
- - `entityIdentifierKey` is optional and defaults to 'organization_id',
-    - Used to identify the organization / client id
- - `preventHomeRedirect` is optional and defaults to false,
-    - This will open a menu on click of home button instead of redirecting 
- - `handleOpenTab` async function to open the tab in backend
-    - expects the following keys in return
-    - { status: 1, tabId, children: undefined }
- - `handleCloseTab` async function to open the tab in backend
-    - expects the following keys in return
-    - { status: 1, current_tab_id: 123 }
- - `handleReorderTabs` async function to open the tab in backend
-    - { status: 1 }
- - `getTabs` async function to open the tab in backend async () => { },
-    - expects the following keys in return
-    - { status: 1, tabs: [], current_tab: {} || null, hasNoTabs }
-    - hasNoTabs = user for whom there are no tabs open
- - `getUserDetails` function which return the user details from user token
- - `hasPrivilege` function which checks if the user has the privilege passed in function param
- - `alertService` An object containing different methods for displaying toast alerts.
-    - can call success, warning, error, info, alert methods.
-    - super-notifier - NPM package can be used here
-    - https://www.npmjs.com/package/super-notifier
+`SuperTabs` is a production-ready React navigation library for managing parent tabs and nested sub-tabs in complex applications.
 
-```
-Eg. 
-const SITE_PREFIX = 'teamLink_'
-const API_BASE_URL = 'https://api.teamlink.com/data_stream'
-const SITE_PAGES = [{
-	title:  "Organization",
-	url:  "/app/organization",
-	privilege:  "ORGANIZATION",
-	id:  1,
-},
-{
-	title:  "Recruiter",
-	url:  "/app/recruiter/f-home",
-	privilege:  "RECRUITER",
-	showAddButton:  true,
-    customAddButtons: [
-      {
-        name: "Data Grid",
-        id: 1,
-      },
-      {
-        name: "Trend Master",
-        id: 2,
-      }
-    ],
-	containsSubTabs:  true,
-	id:  2,
-}]
+It provides a robust tab lifecycle with route integration, privilege-aware module access, and extensible UI controls for module-level workflows.
+
+### Highlights
+
+- Parent tab and sub-tab navigation with URL synchronization
+- Drag-and-drop tab reordering
+- Configurable module actions (`showAddButton` and `customAddButtons`)
+- Pluggable handlers for open, close, reorder, and fetch operations
+
+---
+
+## 1) Setup
+
+Wrap your app with `TabProvider`.
 
-// showAddButton - can be added if the module needs plus button.
-// containsSubTabs - can be added if the tab includes sub tabs.
-// customAddButtons - These buttons will be added in the sub tab list. Clicking on the button will trigger the binded callback with object as param.
+```jsx
+import { TabProvider } from "components/SuperTabs/TabContext";
+import { alertService } from "super-notifier";
 
-import { TabProvider } from 'components/SuperTabs/TabContext';
 <TabProvider
-    SITE_PREFIX={SITE_PREFIX}
-    SITE_PAGES={SITE_PAGES}
-    homeUrl="/app"
-    getTabs={getTabs}
-    handleOpenTab={handleOpenTab}
-    handleCloseTab={handleCloseTab}
-    handleReorderTabs={handleReorderTabs}
-    alertService={alertService}
+  SITE_PREFIX={SITE_PREFIX}
+  SITE_PAGES={SITE_PAGES}
+  homeUrl="/app"
+  getUserDetails={getUser}
+  hasPrivilege={(privilege) => checkPrivilege(getUser().privileges, privilege)}
+  getTabs={getTabs}
+  handleOpenTab={handleOpenTab}
+  handleCloseTab={handleCloseTab}
+  handleReorderTabs={handleReorderTabs}
+  isDefaultExpanded={true}
+  alertService={alertService}
 >
-    <Main />
-</TabProvider>
+  <Main />
+</TabProvider>;
 ```
 
->**Render the component within the App's header**
-```
-import { useTabContext } from "components/SuperTabs/TabContext";
+Render tabs in header:
+
+```jsx
+import SuperTabs from "components/SuperTabs/SuperTabs";
 
 <header>
-    <SuperTabs />
-</header>
+  <SuperTabs />
+</header>;
 ```
 
->**Wrap the hyperlink as follows:**
+---
 
-Each tab should contain all the necessary information to be stored.
+## 2) `TabProvider` props
 
-Mandatory Fields:
--   `id`
--   `name`
--   `url`
+### Required
 
-For Avatar:
--   `showAvatar` must be set to `true`
--   The following fields must be provided:
-    -   `firstName`
-    -   `lastName`
-    -   `imgSrc`
+- `SITE_PREFIX: string`
+- `SITE_PAGES: Array<SitePage>`
 
+`SitePage` is typically:
+
+```js
+{
+  id: 2,
+  title: "Recruiter",
+  url: "/app/recruiter/f-home",
+  privilege: "RECRUITER",
+  containsSubTabs: true,
+  showAddButton: true, // boolean or privilege array
+  customAddButtons: [
+    { id: 1, name: "Data Grid", privilege: "RECRUITER" },
+    { id: 2, name: "Trend Master", privilege: "RECRUITER" }
+  ],
+  showInMobile: true,  // optional
+  isExternal: false    // optional
+}
 ```
-// Tab object Examples
 
+### Optional
+
+- `homeUrl` (default: `/`)
+- `entityIdentifierKey` (default: `organization_id`)
+- `persistTabsAfterLogin` (default: `false`)
+- `preventHomeRedirect` (default: `false`)
+  - When `true`, clicking home opens module menu instead of redirecting.
+- `retainTabsAfterEntityChange` (default: `false`)
+- `shouldRedirectToSubTab` (default: `true`)
+- `isMobileView` (default: `false`)
+- `isDefaultExpanded` (default: `false`)
+- `getUserDetails` (function)
+- `hasPrivilege` (function)
+- `getTabs` (async function)
+- `handleOpenTab` (async function)
+- `handleCloseTab` (async function)
+- `handleReorderTabs` (async function)
+- `alertService` object with optional methods: `success`, `warning`, `error`, `info`, `alert`
+
+---
+
+## 3) API callback contracts
+
+### `getTabs({ payload, controller })`
+
+Expected shape:
+
+```js
 {
-    id: 1,
-    name: 'title',
-    url: '/recruiter/f-1`
+  status: 1,
+  tabs: [],                // flat backend tabs with tab_info
+  current_tab: {} | null,  // current tab from backend
+  hasNoTabs: false         // true when backend has no open tabs
 }
+```
+
+### `handleOpenTab(payload[, controller])`
+
+Expected shape:
 
+```js
 {
-    id: 100,
-    url: '/profile/100`
-    firstName: 'John',
-    lastName: 'Doe',
-    showAvatar: true,
-    imgSrc: img_url,
-    department,
-    designation,
-    department_id,
+  status: 1,
+  tabId: 123,
+  children: [] // optional child tabs
 }
 ```
+
+### `handleCloseTab(tabId)`
+
+Expected shape:
+
+```js
+{
+  status: 1,
+  current_tab_id: 456 // optional
+}
 ```
+
+### `handleReorderTabs(payload)`
+
+Expected shape:
+
+```js
+{
+  status: 1;
+}
+```
+
+---
+
+## 4) Opening tabs
+
+### Option 1: `SuperLink`
+
+```jsx
 import SuperLink from "components/SuperTabs/SuperLink";
+
 <SuperLink tab={page} isSubTab={false}>
-    {page.title}
-</SuperLink>
+  {page.title}
+</SuperLink>;
 ```
 
-OR
+Open external links:
 
+```jsx
+<SuperLink tab={{ ...page, isExternal: true }} isSubTab={false} isExternal>
+  {page.title}
+</SuperLink>
 ```
+
+### Option 2: `openSuperTabOnRowClick`
+
+```jsx
 import { useTabContext } from "components/SuperTabs/TabContext";
+
 const { openSuperTabOnRowClick } = useTabContext();
 
-function handleRowClick(e) {
-    const tab = { id: e.id, name: e.name, url: `/recruiter/f-${e.id}` };
-    // isSubTab defaults to true
-    openSuperTabOnRowClick({ tab, isSubTab });
+function handleRowClick(row) {
+  openSuperTabOnRowClick({
+    tab: {
+      id: row.id,
+      name: row.name,
+      url: `/app/recruiter/f-${row.id}`,
+    },
+    isSubTab: true, // defaults to true
+  });
 }
 ```
 
->**Bind the callback for the plus button to each module during the initial render.**
+---
+
+## 5) Tab object notes
+
+Common fields:
+
+- `id`
+- `url`
+- one of `name` / `title`
 
-If a module requires a plus button for adding a new tab, you can include the following:
+Optional:
+
+- `showAvatar`, `firstName`, `lastName`, `imgSrc` or `img_url`
+- `isExternal`
+- any extra metadata your module uses
+
+```js
+{
+  id: 100,
+  url: "/app/profile/100",
+  firstName: "John",
+  lastName: "Doe",
+  showAvatar: true,
+  imgSrc: "https://cdn.example.com/u100.png"
+}
 ```
+
+---
+
+## 6) Add button callbacks
+
+Bind module add callbacks using emitter:
+
+```jsx
+import { useCallback, useEffect } from "react";
 import { emitter } from "components/SuperTabs/SuperTabs";
 import { useTabContext } from "components/SuperTabs/TabContext";
 
 const { openSuperTabOnRowClick } = useTabContext();
 
-const handleTabAddBtn = useCallback(() => {
+const handleTabAddBtn = useCallback(
+  (customButtonData) => {
+    // customButtonData is passed when using customAddButtons
     openSuperTabOnRowClick({
-        tab: {
-            id: 123,
-            name: `New Funnel`,
-            url: `/recruiter/f-${123}`,
-        },
-        isSubTab: true,
+      tab: {
+        id: 123,
+        name: "New Funnel",
+        url: "/app/recruiter/f-123",
+      },
+      isSubTab: true,
     });
-}, [openSuperTabOnRowClick]);
+  },
+  [openSuperTabOnRowClick],
+);
 
 useEffect(() => {
-    const unsub = emitter.emit("bindCallback", {
-        id: 2, // Same id provided for this module in navigation.js
-        callback: handleTabAddBtn,
-    });
-    return unsub;
+  const unsub = emitter.emit("bindCallback", {
+    id: 2, // same parent module id from SITE_PAGES
+    callback: handleTabAddBtn,
+  });
+  return unsub;
 }, [handleTabAddBtn]);
 ```
 
-> Note: The logo of the home tab can be updated by targeting the `brand-logo` class.
-
------
-
-#### Advanced
+---
 
->**Cleanup**
+## 7) Close cleanup event
 
-When a tab is closed, it may be necessary to clean up some data. The `superTabClose` event can be utilized for this purpose.
-
-```
-import { emitter } from  'components/SuperTabs/SuperTabs';
+```jsx
+import { useEffect } from "react";
+import { emitter } from "components/SuperTabs/SuperTabs";
 
 useEffect(() => {
-	const  unsub  =  emitter.subscribe('superTabClose', ({ appId, isSubTab, tab }) => {
-		// Same id provided for this module in navigation.js
-		if (appId === 2 && isSubTab) {
-			// handle clean up here
-		}
-	})
-	return unsub;
+  const unsub = emitter.subscribe(
+    "superTabClose",
+    ({ appId, isSubTab, tab }) => {
+      if (appId === 2 && isSubTab) {
+        // cleanup here
+      }
+    },
+  );
+  return unsub;
 }, []);
 ```
 
->**Not Available page**
-- If a profile is deleted, the tab will remain open. To address this, we can display a "Page Not Available" message.
+---
 
-```
-import  NotAvailable  from  'components/SuperTabs/NotAvailable';
+## 8) Not Available page
 
-<NotAvailable  subTabName='Profile' />
+```jsx
+import NotAvailable from "components/SuperTabs/NotAvailable";
+
+<NotAvailable subTabName="Profile" />;
 ```
 
->**Keep Alive  (Experimental)**
+---
 
-```
-import { withKeepAlive } from  "components/SuperTabs/KeepAlive";
+## 9) Keep-alive (optional)
 
-// Same id provided for this module in navigation.js
-export  default  withKeepAlive(Component, Unique ID);
+Use shared keep-alive utility:
 
-Eg.
-const  Component  = () => {
-	return <div>Component</div>
-}
+```jsx
+import { withKeepAlive } from "components/KeepAlive";
 
-export  default  withKeepAlive(Component, 2);
-```
-Keep Alive Cleanup
+const Component = () => <div>Component</div>;
+export default withKeepAlive(Component, 2); // module id
 ```
-// This can be incorporated into a component that is always rendered, such as the header.
 
-import { useAliveScope } from  "components/SuperTabs/KeepAlive";
-import  { emitter } from  "components/SuperTabs/SuperTabs";
+Cleanup keep-alive cache on parent tab close:
 
-const { drop } =  useAliveScope();
+```jsx
+import { useEffect } from "react";
+import { useAliveScope } from "components/KeepAlive";
+import { emitter } from "components/SuperTabs/SuperTabs";
+
+const { drop } = useAliveScope();
 
 useEffect(() => {
-	const unsub = emitter.subscribe('superTabClose', (e) => {
-		const { appId, isSubTab } =  e;
-		if (appId && !isSubTab) {
-			// drop the cache of the tab
-			drop(appId);
-		}
-	})
-	return unsub;
-}, []);
-```
+  const unsub = emitter.subscribe("superTabClose", ({ appId, isSubTab }) => {
+    if (appId && !isSubTab) {
+      drop(appId);
+    }
+  });
+  return unsub;
+}, [drop]);
+```
+
+---
+
+## 10) Styling note
+
+Home tab logo can be styled with `.brand-logo`.

package/dist/TabContext.js

@@ -252,8 +252,8 @@ function TabProvider(_ref9) {
     subTabWrapperWidth = _useState12[0],
     setSubTabWrapperWidth = _useState12[1];
   var _useState13 = (0, _react.useState)(function () {
-      var _getUserDetails;
-      return ((_getUserDetails = getUserDetails()) === null || _getUserDetails === void 0 ? void 0 : _getUserDetails[entityIdentifierKey]) || null;
+      var _getUserDetails$entit, _getUserDetails;
+      return (_getUserDetails$entit = (_getUserDetails = getUserDetails()) === null || _getUserDetails === void 0 ? void 0 : _getUserDetails[entityIdentifierKey]) !== null && _getUserDetails$entit !== void 0 ? _getUserDetails$entit : null;
     }),
     _useState14 = _slicedToArray(_useState13, 2),
     currentEntityId = _useState14[0],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bydata/react-supertabs",
-  "version": "1.1.9",
+  "version": "1.2.0",
   "description": "A customizable React super tabs component.",
   "main": "dist/index.js",
   "module": "dist/index.js",