@bydata/react-supertabs 1.2.5 → 1.2.6

package/Readme.md

@@ -0,0 +1,322 @@
+# SuperTabs
+
+`SuperTabs` is a production-ready React navigation library for managing parent tabs and nested sub-tabs in complex applications.
+
+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`.
+
+```jsx
+import { TabProvider } from "components/SuperTabs/TabContext";
+import { alertService } from "super-notifier";
+
+<TabProvider
+  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>;
+```
+
+Render tabs in header:
+
+```jsx
+import SuperTabs from "components/SuperTabs/SuperTabs";
+
+<header>
+  <SuperTabs />
+</header>;
+```
+
+---
+
+## 2) `TabProvider` props
+
+### Required
+
+- `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
+}
+```
+
+### 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
+{
+  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
+{
+  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>;
+```
+
+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(row) {
+  openSuperTabOnRowClick({
+    tab: {
+      id: row.id,
+      name: row.name,
+      url: `/app/recruiter/f-${row.id}`,
+    },
+    isSubTab: true, // defaults to true
+  });
+}
+```
+
+---
+
+## 5) Tab object notes
+
+Common fields:
+
+- `id`
+- `url`
+- one of `name` / `title`
+
+Optional:
+
+- `showAvatar`, `firstName`, `lastName`, `imgSrc` or `img_url`
+- `tooltip` for hover text; falls back to tab title/name when empty
+- `isExternal`
+- any extra metadata your module uses
+
+```js
+{
+  id: 100,
+  url: "/app/profile/100",
+  tooltip: "Profile: John Doe",
+  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(
+  (customButtonData) => {
+    // customButtonData is passed when using customAddButtons
+    openSuperTabOnRowClick({
+      tab: {
+        id: 123,
+        name: "New Funnel",
+        url: "/app/recruiter/f-123",
+      },
+      isSubTab: true,
+    });
+  },
+  [openSuperTabOnRowClick],
+);
+
+useEffect(() => {
+  const unsub = emitter.emit("bindCallback", {
+    id: 2, // same parent module id from SITE_PAGES
+    callback: handleTabAddBtn,
+  });
+  return unsub;
+}, [handleTabAddBtn]);
+```
+
+---
+
+## 7) Close cleanup event
+
+```jsx
+import { useEffect } from "react";
+import { emitter } from "components/SuperTabs/SuperTabs";
+
+useEffect(() => {
+  const unsub = emitter.subscribe(
+    "superTabClose",
+    ({ appId, isSubTab, tab }) => {
+      if (appId === 2 && isSubTab) {
+        // cleanup here
+      }
+    },
+  );
+  return unsub;
+}, []);
+```
+
+---
+
+## 8) Not Available page
+
+```jsx
+import NotAvailable from "components/SuperTabs/NotAvailable";
+
+<NotAvailable subTabName="Profile" />;
+```
+
+---
+
+## 9) Keep-alive (optional)
+
+Use shared keep-alive utility:
+
+```jsx
+import { withKeepAlive } from "components/KeepAlive";
+
+const Component = () => <div>Component</div>;
+export default withKeepAlive(Component, 2); // module id
+```
+
+Cleanup keep-alive cache on parent tab close:
+
+```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", ({ appId, isSubTab }) => {
+    if (appId && !isSubTab) {
+      drop(appId);
+    }
+  });
+  return unsub;
+}, [drop]);
+```
+
+---
+
+## 10) Styling note
+
+Home tab logo can be styled with `.brand-logo`.

package/dist/SuperTabs.js

@@ -56,6 +56,13 @@ var tooltipStyles = {
   backgroundColor: 'var(--tab-background-overlay, #272B32)',
   color: 'var(--tab-text-normal, #BDC3CC)'
 };
+var getTooltipContent = function getTooltipContent(item, fallbackTitle) {
+  var customTooltip = item === null || item === void 0 ? void 0 : item.tooltip;
+  if (typeof customTooltip === 'string' && customTooltip.trim()) {
+    return customTooltip.trim();
+  }
+  return fallbackTitle;
+};
 var filterSubTabs = function filterSubTabs(subTabs) {
   // const subTabsInList = [];
   var subTabsInNavbar = [];
@@ -884,7 +891,7 @@ var SuperTabs = function SuperTabs(_ref) {
           className: 'child-tabs-wrapper tab-' + tab.id + (showSubTabs ? ' expanded' : '')
           // (isActive ? ' active' : '')
         }, /*#__PURE__*/_react["default"].createElement(_reactHoverText["default"], {
-          content: tab.title,
+          content: getTooltipContent(tab, tab.title),
           delay: 500,
           followCursor: true,
           placement: "bottom",
@@ -1002,7 +1009,7 @@ var SuperTabs = function SuperTabs(_ref) {
         isDragDisabled: isMobileScreen
       }, function (provided, snapshot) {
         return /*#__PURE__*/_react["default"].createElement(_reactHoverText["default"], {
-          content: tab.title,
+          content: getTooltipContent(tab, tab.title),
           delay: 500,
           followCursor: true,
           placement: "bottom",
@@ -1186,7 +1193,7 @@ var SubTab = exports.SubTab = function SubTab(_ref0) {
     index: subIndex
   }, function (subprovided, snapshot) {
     return /*#__PURE__*/_react["default"].createElement(_reactHoverText["default"], {
-      content: title,
+      content: getTooltipContent(subTab, title),
       delay: 500,
       followCursor: true,
       show: showTooltip,

package/package.json

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

package/README.md

@@ -1,262 +0,0 @@
-# React 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
-------
-
-```bash
-npm install @bydata/react-supertabs
-```
-
-### 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
-
-```
-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,
-}]
-
-// 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.
-
-import { TabProvider } from '@bydata/react-supertabs';
-<TabProvider
-    SITE_PREFIX={SITE_PREFIX}
-    SITE_PAGES={SITE_PAGES}
-    homeUrl="/app"
-    getTabs={getTabs}
-    handleOpenTab={handleOpenTab}
-    handleCloseTab={handleCloseTab}
-    handleReorderTabs={handleReorderTabs}
-    alertService={alertService}
->
-    <Main />
-</TabProvider>
-```
-
->**Render the component within the App's header**
-```
-import { SuperTabs, useTabContext } from '@bydata/react-supertabs';
-
-<header>
-    <SuperTabs />
-</header>
-```
-
->**Wrap the hyperlink as follows:**
-
-Each tab should contain all the necessary information to be stored.
-
-Mandatory Fields:
--   `id`
--   `name`
--   `url`
-
-For Avatar:
--   `showAvatar` must be set to `true`
--   The following fields must be provided:
-    -   `firstName`
-    -   `lastName`
-    -   `imgSrc`
-
-```
-// Tab object Examples
-
-{
-    id: 1,
-    name: 'title',
-    url: '/recruiter/f-1`
-}
-
-{
-    id: 100,
-    url: '/profile/100`
-    firstName: 'John',
-    lastName: 'Doe',
-    showAvatar: true,
-    imgSrc: img_url,
-    department,
-    designation,
-    department_id,
-}
-```
-```
-import { SuperLink } from '@bydata/react-supertabs';
-<SuperLink tab={page} isSubTab={false}>
-    {page.title}
-</SuperLink>
-```
-
-OR
-
-```
-import { useTabContext } from '@bydata/react-supertabs';
-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 });
-}
-```
-
->**Bind the callback for the plus button to each module during the initial render.**
-
-If a module requires a plus button for adding a new tab, you can include the following:
-```
-import { emitter, useTabContext } from '@bydata/react-supertabs';
-
-const { openSuperTabOnRowClick } = useTabContext();
-
-const handleTabAddBtn = useCallback(() => {
-    openSuperTabOnRowClick({
-        tab: {
-            id: 123,
-            name: `New Funnel`,
-            url: `/recruiter/f-${123}`,
-        },
-        isSubTab: true,
-    });
-}, [openSuperTabOnRowClick]);
-
-useEffect(() => {
-    const unsub = emitter.emit("bindCallback", {
-        id: 2, // Same id provided for this module in navigation.js
-        callback: handleTabAddBtn,
-    });
-    return unsub;
-}, [handleTabAddBtn]);
-```
-
-> Note: The logo of the home tab can be updated by targeting the `brand-logo` class.
-
------
-
-#### Advanced
-
->**Cleanup**
-
-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 '@bydata/react-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;
-}, []);
-```
-
->**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 '@bydata/react-supertabs';
-
-<NotAvailable  subTabName='Profile' />
-```
-
->**Keep Alive  (Experimental)**
-
-```
-import { withKeepAlive } from '@bydata/react-supertabs';
-
-// Same id provided for this module in navigation.js
-export  default  withKeepAlive(Component, Unique ID);
-
-Eg.
-const  Component  = () => {
-	return <div>Component</div>
-}
-
-export  default  withKeepAlive(Component, 2);
-```
-Keep Alive Cleanup
-```
-// This can be incorporated into a component that is always rendered, such as the header.
-
-import { useAliveScope, emitter } from '@bydata/react-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;
-}, []);
-```