react-multi-tab 1.0.0

package/README.md

@@ -0,0 +1,190 @@
+# react-multi-tab
+
+A headless, accessible, router-agnostic, and fully type-safe multi-tab component library for React.
+
+[![npm version](https://img.shields.io/npm/v/react-multi-tab.svg)](https://npmjs.org/package/react-multi-tab)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Agnostic & Pluggable:** Works independently of any bundler or router. Includes adapters for memory, URL Search Params, and `react-router-dom`.
+- **Headless & Accessible:** Follows the WAI-ARIA Tabs pattern. Complete keyboard navigation (`Arrow keys`, `Home`, `End`) out of the box. You control the styling.
+- **TypeScript Generics:** Fully type-safe context, components, and hooks. Never use `any` again.
+- **State Preservation:** Keeps tab content mounted when inactive (via `hidden` attribute) to preserve form states and scroll positions.
+
+## 🚀 Performance & Developer Experience (DX)
+
+We have built the core state-management of `react-multi-tab` to meet the highest performance and Developer Experience (DX) standards.
+
+### 1. `useSyncExternalStore` (The Performance Boost)
+We stripped the large object out of React Context and replaced it with a custom Vanilla JS store (`createMultiTabStore`). 
+By utilizing React 18's `useSyncExternalStore`, components like `useTabData` now strictly subscribe to only the data they care about.
+
+> **Why it matters:** Typing in an input field inside a specific tab will **NO LONGER** trigger a re-render across the entire Tab system. Only the component that called `useTabData` for that specific tab will update!
+
+### 2. `TabInstanceContext` (The DX Boost)
+Developers no longer need to manually pass down the cryptic `instanceId` to every page component.
+Because `<TabPanels />` implicitly wraps your components with `<TabContent>`, it invisibly provides the context to all descendants.
+
+```tsx
+// Inside any page (e.g., A-Page.tsx)
+const [data, setData] = useTabData<APageData>(); // Boom! Magic.
+```
+> `useTabData` automatically finds its own tab's context. If no context is found, it safely falls back to the globally active tab.
+
+### 3. Built for Redux/Zustand Users
+For teams that prefer keeping form data in a global Redux slice instead of our internal data store, we introduced the `useTabInstanceId()` hook.
+```tsx
+import { useTabInstanceId } from 'react-multi-tab';
+
+function MyReduxPage() {
+  const tabId = useTabInstanceId(); // Seamlessly gets the ID!
+  
+  const handleChange = () => {
+    dispatch(updateFormSlice({ tabId, data: '...' }));
+  }
+}
+```
+
+### 4. Smart Tab History
+When a tab is closed, the library remembers the exact history of your active tabs and gracefully falls back to the **previously active** tab instead of abruptly jumping to the end of the list. Exactly like VS Code!
+
+## Installation
+
+```bash
+npm install react-multi-tab
+# or
+yarn add react-multi-tab
+```
+
+## Basic Usage
+
+Here is a full example showing how to build a tabbed layout using the vanilla URL `searchParamsAdapter` and the new explicit page registry.
+
+### 1. Define Your Pages & Registry
+
+Create your page components and register them explicitly.
+
+```tsx
+// src/registry.ts
+import { createPageRegistry, useTabData } from 'react-multi-tab';
+
+interface DashboardData { filter?: string; }
+
+function Dashboard({ instanceId }: { instanceId: string }) {
+  // 100% Type-safe!
+  const [data, setData] = useTabData<DashboardData>();
+  
+  return (
+    <div>
+      <h2>Dashboard</h2>
+      <p>Filter: {data.filter ?? 'None'}</p>
+      <button onClick={() => setData({ filter: 'Active' })}>Set Filter</button>
+    </div>
+  );
+}
+
+function Settings() {
+  return <h2>Settings</h2>;
+}
+
+// Create a bundler-agnostic registry
+export const registry = createPageRegistry([
+  { id: 'dashboard', label: 'Dashboard', component: Dashboard },
+  { id: 'settings', label: 'Settings', component: Settings },
+]);
+```
+
+### 2. Wrap with Provider & Build the Layout
+
+Use the provided headless components to build your accessible tab interface. They include all necessary ARIA attributes and keyboard events.
+
+```tsx
+// src/App.tsx
+import { 
+  MultiTabProvider, 
+  searchParamsAdapter,
+  TabList, 
+  TabTrigger, 
+  TabCloseButton, 
+  TabPanels,
+  useMultiTab
+} from 'react-multi-tab';
+import { registry } from './registry';
+
+function MainLayout() {
+  const { tabs, openTab } = useMultiTab();
+
+  return (
+    <div style={{ display: 'flex' }}>
+      {/* Sidebar / Menu */}
+      <nav style={{ width: 200 }}>
+        <button onClick={() => openTab('dashboard')}>Open Dashboard</button>
+        <button onClick={() => openTab('settings')}>Open Settings</button>
+      </nav>
+
+      <div style={{ flex: 1 }}>
+        {/* Accessible Tab List */}
+        <TabList aria-label="My Application Tabs">
+          {tabs.map((tab) => (
+            <TabTrigger key={tab.instanceId} instanceId={tab.instanceId}>
+              {tab.label}
+              <TabCloseButton instanceId={tab.instanceId} />
+            </TabTrigger>
+          ))}
+        </TabList>
+
+        {/* Renders all active and hidden tab panels */}
+        <TabPanels />
+      </div>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <MultiTabProvider 
+      registry={registry}
+      adapter={searchParamsAdapter()} // Syncs active tabs to the browser URL
+    >
+      <MainLayout />
+    </MultiTabProvider>
+  );
+}
+```
+
+## Running the Playground
+
+You can easily test the components locally using the built-in Playground!
+
+1. Go to the project root directory.
+2. Run the playground command:
+```bash
+yarn run dev:demo
+```
+3. Open `http://localhost:3000` to interact with the demo.
+
+## Advanced Features
+
+### React Router Integration
+
+If you want to sync your tab state with React Router, you can use the optional adapter.
+
+```tsx
+import { MultiTabProvider } from 'react-multi-tab';
+import { useReactRouterAdapter } from 'react-multi-tab/adapters/react-router';
+
+function App() {
+  const routerAdapter = useReactRouterAdapter();
+
+  return (
+    <MultiTabProvider registry={registry} adapter={routerAdapter}>
+      <MainLayout />
+    </MultiTabProvider>
+  );
+}
+```
+
+## License
+
+MIT © Arif GEVENCİ

package/dist/adapters/react-router.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+var react = require('react');
+var reactRouterDom = require('react-router-dom');
+
+// src/adapters/react-router.ts
+function useReactRouterAdapter(options) {
+  const [, setSearchParams] = reactRouterDom.useSearchParams();
+  const setParamsRef = react.useRef(setSearchParams);
+  setParamsRef.current = setSearchParams;
+  const tabsKey = options?.tabsParam ?? "tabs";
+  const activeKey = options?.activeParam ?? "active";
+  return react.useMemo(
+    () => ({
+      read() {
+        const params = new URLSearchParams(window.location.search);
+        const tabsStr = params.get(tabsKey);
+        const activeTab = params.get(activeKey);
+        if (!tabsStr) return null;
+        return { tabs: tabsStr.split(",").filter(Boolean), activeTab };
+      },
+      write(tabs, activeTabId) {
+        const newParams = {};
+        if (tabs.length > 0) {
+          newParams[tabsKey] = tabs.map((t) => t.instanceId).join(",");
+          if (activeTabId) newParams[activeKey] = activeTabId;
+        }
+        setParamsRef.current(newParams, { replace: true });
+      },
+      subscribe(callback) {
+        window.addEventListener("popstate", callback);
+        return () => window.removeEventListener("popstate", callback);
+      }
+    }),
+    [tabsKey, activeKey]
+  );
+}
+
+exports.useReactRouterAdapter = useReactRouterAdapter;
+//# sourceMappingURL=react-router.cjs.map
+//# sourceMappingURL=react-router.cjs.map

package/dist/adapters/react-router.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/react-router.ts"],"names":["useSearchParams","useRef","useMemo"],"mappings":";;;;;;AAgCO,SAAS,sBACd,OAAA,EACY;AACZ,EAAA,MAAM,GAAG,eAAe,CAAA,GAAIA,8BAAA,EAAgB;AAG5C,EAAA,MAAM,YAAA,GAAeC,aAAO,eAAe,CAAA;AAC3C,EAAA,YAAA,CAAa,OAAA,GAAU,eAAA;AAEvB,EAAA,MAAM,OAAA,GAAU,SAAS,SAAA,IAAa,MAAA;AACtC,EAAA,MAAM,SAAA,GAAY,SAAS,WAAA,IAAe,QAAA;AAE1C,EAAA,OAAOC,aAAA;AAAA,IACL,OAAO;AAAA,MACL,IAAA,GAAO;AACL,QAAA,MAAM,MAAA,GAAS,IAAI,eAAA,CAAgB,MAAA,CAAO,SAAS,MAAM,CAAA;AACzD,QAAA,MAAM,OAAA,GAAU,MAAA,CAAO,GAAA,CAAI,OAAO,CAAA;AAClC,QAAA,MAAM,SAAA,GAAY,MAAA,CAAO,GAAA,CAAI,SAAS,CAAA;AAEtC,QAAA,IAAI,CAAC,SAAS,OAAO,IAAA;AACrB,QAAA,OAAO,EAAE,MAAM,OAAA,CAAQ,KAAA,CAAM,GAAG,CAAA,CAAE,MAAA,CAAO,OAAO,CAAA,EAAG,SAAA,EAAU;AAAA,MAC/D,CAAA;AAAA,MAEA,KAAA,CAAM,MAAqB,WAAA,EAA4B;AACrD,QAAA,MAAM,YAAoC,EAAC;AAC3C,QAAA,IAAI,IAAA,CAAK,SAAS,CAAA,EAAG;AACnB,UAAA,SAAA,CAAU,OAAO,CAAA,GAAI,IAAA,CAAK,GAAA,CAAI,CAAC,MAAM,CAAA,CAAE,UAAU,CAAA,CAAE,IAAA,CAAK,GAAG,CAAA;AAC3D,UAAA,IAAI,WAAA,EAAa,SAAA,CAAU,SAAS,CAAA,GAAI,WAAA;AAAA,QAC1C;AACA,QAAA,YAAA,CAAa,OAAA,CAAQ,SAAA,EAAW,EAAE,OAAA,EAAS,MAAM,CAAA;AAAA,MACnD,CAAA;AAAA,MAEA,UAAU,QAAA,EAAsB;AAC9B,QAAA,MAAA,CAAO,gBAAA,CAAiB,YAAY,QAAQ,CAAA;AAC5C,QAAA,OAAO,MAAM,MAAA,CAAO,mBAAA,CAAoB,UAAA,EAAY,QAAQ,CAAA;AAAA,MAC9D;AAAA,KACF,CAAA;AAAA,IACA,CAAC,SAAS,SAAS;AAAA,GACrB;AACF","file":"react-router.cjs","sourcesContent":["import { useMemo, useRef } from \"react\";\nimport { useSearchParams } from \"react-router-dom\";\nimport type { TabInstance, URLAdapter } from \"../types\";\n\n/** Options for {@link useReactRouterAdapter}. */\nexport interface ReactRouterAdapterOptions {\n  /** Query-string key for tab instance IDs. @default \"tabs\" */\n  tabsParam?: string;\n  /** Query-string key for the active tab. @default \"active\" */\n  activeParam?: string;\n}\n\n/**\n * React Router v6+ adapter (hook).\n *\n * Must be called **inside** a `<BrowserRouter>` or equivalent.\n * Returns a stable {@link URLAdapter} reference.\n *\n * @example\n * ```tsx\n * import { useReactRouterAdapter } from 'react-multi-tab/adapters/react-router';\n *\n * function App() {\n *   const adapter = useReactRouterAdapter();\n *   return (\n *     <MultiTabProvider adapter={adapter} registry={registry}>\n *       ...\n *     </MultiTabProvider>\n *   );\n * }\n * ```\n */\nexport function useReactRouterAdapter(\n  options?: ReactRouterAdapterOptions\n): URLAdapter {\n  const [, setSearchParams] = useSearchParams();\n\n  // Keep a stable ref so the adapter object identity doesn't change.\n  const setParamsRef = useRef(setSearchParams);\n  setParamsRef.current = setSearchParams;\n\n  const tabsKey = options?.tabsParam ?? \"tabs\";\n  const activeKey = options?.activeParam ?? \"active\";\n\n  return useMemo<URLAdapter>(\n    () => ({\n      read() {\n        const params = new URLSearchParams(window.location.search);\n        const tabsStr = params.get(tabsKey);\n        const activeTab = params.get(activeKey);\n\n        if (!tabsStr) return null;\n        return { tabs: tabsStr.split(\",\").filter(Boolean), activeTab };\n      },\n\n      write(tabs: TabInstance[], activeTabId: string | null) {\n        const newParams: Record<string, string> = {};\n        if (tabs.length > 0) {\n          newParams[tabsKey] = tabs.map((t) => t.instanceId).join(\",\");\n          if (activeTabId) newParams[activeKey] = activeTabId;\n        }\n        setParamsRef.current(newParams, { replace: true });\n      },\n\n      subscribe(callback: () => void) {\n        window.addEventListener(\"popstate\", callback);\n        return () => window.removeEventListener(\"popstate\", callback);\n      },\n    }),\n    [tabsKey, activeKey]\n  );\n}\n"]}

package/dist/adapters/react-router.d.cts

@@ -0,0 +1,33 @@
+import { U as URLAdapter } from '../types-Df_5I7eH.cjs';
+import 'react';
+
+/** Options for {@link useReactRouterAdapter}. */
+interface ReactRouterAdapterOptions {
+    /** Query-string key for tab instance IDs. @default "tabs" */
+    tabsParam?: string;
+    /** Query-string key for the active tab. @default "active" */
+    activeParam?: string;
+}
+/**
+ * React Router v6+ adapter (hook).
+ *
+ * Must be called **inside** a `<BrowserRouter>` or equivalent.
+ * Returns a stable {@link URLAdapter} reference.
+ *
+ * @example
+ * ```tsx
+ * import { useReactRouterAdapter } from 'react-multi-tab/adapters/react-router';
+ *
+ * function App() {
+ *   const adapter = useReactRouterAdapter();
+ *   return (
+ *     <MultiTabProvider adapter={adapter} registry={registry}>
+ *       ...
+ *     </MultiTabProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function useReactRouterAdapter(options?: ReactRouterAdapterOptions): URLAdapter;
+
+export { type ReactRouterAdapterOptions, useReactRouterAdapter };

package/dist/adapters/react-router.d.ts

@@ -0,0 +1,33 @@
+import { U as URLAdapter } from '../types-Df_5I7eH.js';
+import 'react';
+
+/** Options for {@link useReactRouterAdapter}. */
+interface ReactRouterAdapterOptions {
+    /** Query-string key for tab instance IDs. @default "tabs" */
+    tabsParam?: string;
+    /** Query-string key for the active tab. @default "active" */
+    activeParam?: string;
+}
+/**
+ * React Router v6+ adapter (hook).
+ *
+ * Must be called **inside** a `<BrowserRouter>` or equivalent.
+ * Returns a stable {@link URLAdapter} reference.
+ *
+ * @example
+ * ```tsx
+ * import { useReactRouterAdapter } from 'react-multi-tab/adapters/react-router';
+ *
+ * function App() {
+ *   const adapter = useReactRouterAdapter();
+ *   return (
+ *     <MultiTabProvider adapter={adapter} registry={registry}>
+ *       ...
+ *     </MultiTabProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function useReactRouterAdapter(options?: ReactRouterAdapterOptions): URLAdapter;
+
+export { type ReactRouterAdapterOptions, useReactRouterAdapter };

package/dist/adapters/react-router.mjs

@@ -0,0 +1,39 @@
+import { useRef, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+// src/adapters/react-router.ts
+function useReactRouterAdapter(options) {
+  const [, setSearchParams] = useSearchParams();
+  const setParamsRef = useRef(setSearchParams);
+  setParamsRef.current = setSearchParams;
+  const tabsKey = options?.tabsParam ?? "tabs";
+  const activeKey = options?.activeParam ?? "active";
+  return useMemo(
+    () => ({
+      read() {
+        const params = new URLSearchParams(window.location.search);
+        const tabsStr = params.get(tabsKey);
+        const activeTab = params.get(activeKey);
+        if (!tabsStr) return null;
+        return { tabs: tabsStr.split(",").filter(Boolean), activeTab };
+      },
+      write(tabs, activeTabId) {
+        const newParams = {};
+        if (tabs.length > 0) {
+          newParams[tabsKey] = tabs.map((t) => t.instanceId).join(",");
+          if (activeTabId) newParams[activeKey] = activeTabId;
+        }
+        setParamsRef.current(newParams, { replace: true });
+      },
+      subscribe(callback) {
+        window.addEventListener("popstate", callback);
+        return () => window.removeEventListener("popstate", callback);
+      }
+    }),
+    [tabsKey, activeKey]
+  );
+}
+
+export { useReactRouterAdapter };
+//# sourceMappingURL=react-router.mjs.map
+//# sourceMappingURL=react-router.mjs.map

package/dist/adapters/react-router.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/react-router.ts"],"names":[],"mappings":";;;;AAgCO,SAAS,sBACd,OAAA,EACY;AACZ,EAAA,MAAM,GAAG,eAAe,CAAA,GAAI,eAAA,EAAgB;AAG5C,EAAA,MAAM,YAAA,GAAe,OAAO,eAAe,CAAA;AAC3C,EAAA,YAAA,CAAa,OAAA,GAAU,eAAA;AAEvB,EAAA,MAAM,OAAA,GAAU,SAAS,SAAA,IAAa,MAAA;AACtC,EAAA,MAAM,SAAA,GAAY,SAAS,WAAA,IAAe,QAAA;AAE1C,EAAA,OAAO,OAAA;AAAA,IACL,OAAO;AAAA,MACL,IAAA,GAAO;AACL,QAAA,MAAM,MAAA,GAAS,IAAI,eAAA,CAAgB,MAAA,CAAO,SAAS,MAAM,CAAA;AACzD,QAAA,MAAM,OAAA,GAAU,MAAA,CAAO,GAAA,CAAI,OAAO,CAAA;AAClC,QAAA,MAAM,SAAA,GAAY,MAAA,CAAO,GAAA,CAAI,SAAS,CAAA;AAEtC,QAAA,IAAI,CAAC,SAAS,OAAO,IAAA;AACrB,QAAA,OAAO,EAAE,MAAM,OAAA,CAAQ,KAAA,CAAM,GAAG,CAAA,CAAE,MAAA,CAAO,OAAO,CAAA,EAAG,SAAA,EAAU;AAAA,MAC/D,CAAA;AAAA,MAEA,KAAA,CAAM,MAAqB,WAAA,EAA4B;AACrD,QAAA,MAAM,YAAoC,EAAC;AAC3C,QAAA,IAAI,IAAA,CAAK,SAAS,CAAA,EAAG;AACnB,UAAA,SAAA,CAAU,OAAO,CAAA,GAAI,IAAA,CAAK,GAAA,CAAI,CAAC,MAAM,CAAA,CAAE,UAAU,CAAA,CAAE,IAAA,CAAK,GAAG,CAAA;AAC3D,UAAA,IAAI,WAAA,EAAa,SAAA,CAAU,SAAS,CAAA,GAAI,WAAA;AAAA,QAC1C;AACA,QAAA,YAAA,CAAa,OAAA,CAAQ,SAAA,EAAW,EAAE,OAAA,EAAS,MAAM,CAAA;AAAA,MACnD,CAAA;AAAA,MAEA,UAAU,QAAA,EAAsB;AAC9B,QAAA,MAAA,CAAO,gBAAA,CAAiB,YAAY,QAAQ,CAAA;AAC5C,QAAA,OAAO,MAAM,MAAA,CAAO,mBAAA,CAAoB,UAAA,EAAY,QAAQ,CAAA;AAAA,MAC9D;AAAA,KACF,CAAA;AAAA,IACA,CAAC,SAAS,SAAS;AAAA,GACrB;AACF","file":"react-router.mjs","sourcesContent":["import { useMemo, useRef } from \"react\";\nimport { useSearchParams } from \"react-router-dom\";\nimport type { TabInstance, URLAdapter } from \"../types\";\n\n/** Options for {@link useReactRouterAdapter}. */\nexport interface ReactRouterAdapterOptions {\n  /** Query-string key for tab instance IDs. @default \"tabs\" */\n  tabsParam?: string;\n  /** Query-string key for the active tab. @default \"active\" */\n  activeParam?: string;\n}\n\n/**\n * React Router v6+ adapter (hook).\n *\n * Must be called **inside** a `<BrowserRouter>` or equivalent.\n * Returns a stable {@link URLAdapter} reference.\n *\n * @example\n * ```tsx\n * import { useReactRouterAdapter } from 'react-multi-tab/adapters/react-router';\n *\n * function App() {\n *   const adapter = useReactRouterAdapter();\n *   return (\n *     <MultiTabProvider adapter={adapter} registry={registry}>\n *       ...\n *     </MultiTabProvider>\n *   );\n * }\n * ```\n */\nexport function useReactRouterAdapter(\n  options?: ReactRouterAdapterOptions\n): URLAdapter {\n  const [, setSearchParams] = useSearchParams();\n\n  // Keep a stable ref so the adapter object identity doesn't change.\n  const setParamsRef = useRef(setSearchParams);\n  setParamsRef.current = setSearchParams;\n\n  const tabsKey = options?.tabsParam ?? \"tabs\";\n  const activeKey = options?.activeParam ?? \"active\";\n\n  return useMemo<URLAdapter>(\n    () => ({\n      read() {\n        const params = new URLSearchParams(window.location.search);\n        const tabsStr = params.get(tabsKey);\n        const activeTab = params.get(activeKey);\n\n        if (!tabsStr) return null;\n        return { tabs: tabsStr.split(\",\").filter(Boolean), activeTab };\n      },\n\n      write(tabs: TabInstance[], activeTabId: string | null) {\n        const newParams: Record<string, string> = {};\n        if (tabs.length > 0) {\n          newParams[tabsKey] = tabs.map((t) => t.instanceId).join(\",\");\n          if (activeTabId) newParams[activeKey] = activeTabId;\n        }\n        setParamsRef.current(newParams, { replace: true });\n      },\n\n      subscribe(callback: () => void) {\n        window.addEventListener(\"popstate\", callback);\n        return () => window.removeEventListener(\"popstate\", callback);\n      },\n    }),\n    [tabsKey, activeKey]\n  );\n}\n"]}