@kawaiininja/layouts 1.0.4 → 1.0.6

package/README.md

@@ -1,4 +1,4 @@
-# @onyx/layouts
+# @kawaiininja/layouts
 
 High-performance, premium mobile-first layouts for the Onyx Framework. Designed with a focus on fluid gestures, modularity, and state-of-the-art aesthetics.
 
@@ -26,6 +26,12 @@ High-performance, premium mobile-first layouts for the Onyx Framework. Designed
 - **Flexible Side Drawer**: Fully configurable drawer menu with support for deep-linking (target specific tabs/sub-tabs) and custom action links.
 - **Panel System**: Register any number of custom drawers (Bottom Sheets) that can be triggered from anywhere in the app.
 
+### 🛣️ Integrated Routing Support
+
+- **Full URL Sync**: Sync layout state with `react-router-dom` or any history-based router.
+- **Controlled Navigation**: Pass `activeTab` and `activeSubTab` from your routing hook to drive the UI.
+- **Path Mapping**: Define `path` strings for tabs and sub-tabs to automatically trigger the `onNavigate` callback.
+
 ### 🎨 Design System & Theme
 
 - **Premium Glassmorphism**: High-quality backdrop blurs and subtle gradients for a modern, high-end feel.
@@ -36,7 +42,7 @@ High-performance, premium mobile-first layouts for the Onyx Framework. Designed
 ## 🚀 Installation
 
 ```bash
-npm install @onyx/layouts
+npm install @kawaiininja/layouts
 ```
 
 Note: This package requires `framer-motion`, `lucide-react`, and `react` >= 18.0.0.
@@ -45,42 +51,53 @@ Note: This package requires `framer-motion`, `lucide-react`, and `react` >= 18.0
 
 ## 📦 Usage
 
-### Basic Example
+### Integrated with React Router
 
 ```jsx
-import { OnyxMobileLayout } from "@onyx/layouts";
-import { Home, Search, Bell, User, PenTool, Grid } from "lucide-react";
+import { OnyxMobileLayout } from "@kawaiininja/layouts";
+import { BrowserRouter, useNavigate, useLocation } from "react-router-dom";
+import { Home, Grid, PenTool } from "lucide-react";
+
+const App = () => {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const currentPath = location.pathname;
 
-const MyApp = () => {
   const tabs = [
     {
       id: "home",
       label: "Home",
       icon: Home,
-      navTitle: "Activity Feed",
+      path: "/home",
       subTabs: [
-        { label: "Inbox", icon: Grid, view: () => <div>Your Messages</div> },
+        {
+          label: "Feed",
+          icon: Grid,
+          path: "feed",
+          view: () => <div>Main Feed</div>,
+        },
       ],
       quickActions: [
         {
           label: "New Post",
           icon: PenTool,
-          onClick: ({ openDrawer }) => openDrawer("post_editor"),
+          onClick: ({ openDrawer }) => openDrawer("editor"),
         },
       ],
     },
   ];
 
+  // Derive active states from URL
+  const activeTabId = tabs.find((t) => currentPath.startsWith(t.path))?.id;
+
   return (
     <OnyxMobileLayout
       tabs={tabs}
-      user={{
-        name: "Alex Designer",
-        handle: "@alex_ui",
-        avatar: "https://example.com/avatar.png",
-      }}
+      user={{ name: "Alex", handle: "@alex", avatar: "..." }}
+      activeTab={activeTabId}
+      onNavigate={(path) => navigate(path)}
       drawers={{
-        post_editor: PostEditorPanel,
+        editor: MyEditorPanel,
       }}
     />
   );
@@ -93,51 +110,54 @@ const MyApp = () => {
 
 ### `OnyxMobileLayoutProps`
 
-| Prop           | Type                        | Description                                                                   |
-| :------------- | :-------------------------- | :---------------------------------------------------------------------------- |
-| `tabs`         | `TabConfig[]`               | **Required**. The main navigation stack (Rails on the right).                 |
-| `user`         | `UserConfig`                | **Required**. Data for the side drawer's profile section.                     |
-| `drawers`      | `Record<string, Component>` | Dictionary of custom panel components. Keys are used as IDs for `openDrawer`. |
-| `drawerItems`  | `DrawerItemConfig[]`        | Custom links for the side menu. If empty, defaults to first tab's subtabs.    |
-| `onSignOut`    | `() => void`                | Triggered when the "Sign Out" button in the drawer is clicked.                |
-| `onRefresh`    | `() => void`                | Global pull-to-refresh handler. Overridden if a tab has its own `onRefresh`.  |
-| `isRefreshing` | `boolean`                   | Global refresh state.                                                         |
-| `initialTab`   | `string`                    | The ID of the tab to show initially. Default: `home`.                         |
-| `rightAction`  | `ReactNode`                 | Global action element shown in the header (e.g., Settings icon).              |
+| Prop           | Type                        | Description                                                   |
+| :------------- | :-------------------------- | :------------------------------------------------------------ |
+| `tabs`         | `TabConfig[]`               | **Required**. The main navigation stack (Rails on the right). |
+| `user`         | `UserConfig`                | **Required**. Data for the side drawer's profile section.     |
+| `drawers`      | `Record<string, Component>` | Dictionary of custom panel components.                        |
+| `activeTab`    | `string`                    | Controlled ID of the active tab.                              |
+| `activeSubTab` | `string`                    | Controlled label of the active sub-tab.                       |
+| `onNavigate`   | `(path: string) => void`    | Triggered on path-based navigation (Rails, Tabs, Drawers).    |
+| `drawerItems`  | `DrawerItemConfig[]`        | Custom links for the side menu.                               |
+| `onSignOut`    | `() => void`                | Triggered when the "Sign Out" button is clicked.              |
+| `onRefresh`    | `() => void`                | Global pull-to-refresh handler.                               |
+| `isRefreshing` | `boolean`                   | Global refresh state.                                         |
+| `initialTab`   | `string`                    | Default: `home`.                                              |
+| `rightAction`  | `ReactNode`                 | Global header action element.                                 |
 
 ### `TabConfig`
 
-| Field          | Type                  | Description                                                                 |
-| :------------- | :-------------------- | :-------------------------------------------------------------------------- |
-| `id`           | `string`              | Unique identifier used for internal routing.                                |
-| `label`        | `string`              | Text label shown in the Rail.                                               |
-| `icon`         | `LucideIcon`          | Icon shown in the Rail.                                                     |
-| `navTitle`     | `string`              | Optional. Text shown in the top header when this tab is active.             |
-| `subTabs`      | `SubTabConfig[]`      | Horizontal navigation nested under this tab.                                |
-| `quickActions` | `QuickActionConfig[]` | Radial menu items triggered by long-press.                                  |
-| `onRefresh`    | `() => void`          | Tab-specific refresh handler. If provided, disables the global `onRefresh`. |
-| `isRefreshing` | `boolean`             | Tab-specific loading state.                                                 |
-| `rightAction`  | `ReactNode`           | Tab-specific header action.                                                 |
+| Field          | Type                  | Description                     |
+| :------------- | :-------------------- | :------------------------------ |
+| `id`           | `string`              | Unique identifier.              |
+| `label`        | `string`              | Rail label.                     |
+| `icon`         | `LucideIcon`          | Rail icon.                      |
+| `path`         | `string`              | Absolute base path for routing. |
+| `navTitle`     | `string`              | Optional header title.          |
+| `subTabs`      | `SubTabConfig[]`      | Nested horizontal navigation.   |
+| `quickActions` | `QuickActionConfig[]` | Radial menu items.              |
+| `onRefresh`    | `() => void`          | Tab-specific refresh handler.   |
+| `isRefreshing` | `boolean`             | Tab-specific loading state.     |
+| `rightAction`  | `ReactNode`           | Tab-specific header action.     |
 
 ### `SubTabConfig`
 
-| Field   | Type         | Description                                          |
-| :------ | :----------- | :--------------------------------------------------- |
-| `label` | `string`     | Text shown in the horizontal pill.                   |
-| `icon`  | `LucideIcon` | Icon next to the label.                              |
-| `view`  | `Component`  | The component to render when this sub-tab is active. |
+| Field   | Type         | Description                            |
+| :------ | :----------- | :------------------------------------- |
+| `label` | `string`     | Pill label.                            |
+| `icon`  | `LucideIcon` | Pill icon.                             |
+| `path`  | `string`     | Relative or absolute path for routing. |
+| `view`  | `Component`  | The component to render.               |
 
 ### `QuickActionConfig` & `DrawerItemConfig`
 
-Both configurations share an `onClick` context provider:
-
-| Prop           | Type            | Description                                                               |
-| :------------- | :-------------- | :------------------------------------------------------------------------ |
-| `label`        | `string`        | Item text.                                                                |
-| `icon`         | `LucideIcon`    | Item icon.                                                                |
-| `targetTab`    | `string`        | (Drawer only) Target Tab ID for navigation.                               |
-| `targetSubTab` | `string`        | (Drawer only) Target Sub-tab Label for deep-linking.                      |
-| `onClick`      | `(ctx) => void` | Custom callback. Context contains `{ openDrawer: (id: string) => void }`. |
+| Prop           | Type            | Description                                      |
+| :------------- | :-------------- | :----------------------------------------------- |
+| `label`        | `string`        | Item text.                                       |
+| `icon`         | `LucideIcon`    | Item icon.                                       |
+| `targetTab`    | `string`        | Target Tab ID for navigation.                    |
+| `targetSubTab` | `string`        | Target Sub-tab Label for deep-linking.           |
+| `onClick`      | `(ctx) => void` | Context: `{ openDrawer: (id: string) => void }`. |
 
 ---
 
@@ -145,39 +165,28 @@ Both configurations share an `onClick` context provider:
 
 ### Pull-to-Refresh
 
-To enable the refresh indicator, simply provide an `onRefresh` callback. The indicator will appear when the user pulls down from the top of the scroll container.
-
 - **Threshold**: 60px pull triggers the refresh.
-- **State Control**: Use `isRefreshing` to let the layout know when the operation is complete.
+- **Implementation**: Provide `onRefresh` and sync `isRefreshing`.
 
 ### Quick Action Menu (Radial Selection)
 
-1. **Trigger**: Press and hold any item in the right navigation rail for 400ms.
-2. **Selection**: While holding, move your finger up or down. The selection indicator will follow.
-3. **Execution**: Release your finger to execute the highlighted action.
+1. **Trigger**: Long-press (400ms) any Navigation Rail item.
+2. **Selection**: Drag towards an action to highlight.
+3. **Execution**: Release to trigger.
 
 ---
 
 ## 🎨 Design System (CSS Tokens)
 
-The layout is highly skinable using CSS variables. Override these in your root CSS:
-
 ```css
 :root {
-  /* Backgrounds */
-  --bg-main: 0, 0, 0; /* Pure black */
-  --bg-surface: 18, 18, 18; /* Elevate surface */
-  --bg-elevated: 28, 28, 28; /* Drawer/Menus */
-
-  /* Brand */
-  --color-accent: 99, 102, 241; /* Primary brand color (Indigo) */
+  --bg-main: 0, 0, 0;
+  --bg-surface: 18, 18, 18;
+  --bg-elevated: 28, 28, 28;
+  --color-accent: 99, 102, 241;
   --color-secondary: 236, 72, 153;
-
-  /* Text */
   --text-primary: 255, 255, 255;
   --text-muted: 156, 163, 175;
-
-  /* Borders */
   --color-border-subtle: 255, 255, 255, 0.1;
 }
 ```

package/dist/MobileLayout.js

@@ -103,17 +103,43 @@ function useRailNavScroll(active, navKeys) {
     };
 }
 // --- Main Layout Component ---
-const OnyxMobileLayoutBase = ({ tabs, user, drawers = {}, onSignOut, onRefresh, isRefreshing: externalRefreshing, rightAction, initialTab = "home", drawerItems = [], }) => {
-    const [activeTab, setActiveTab] = useState(initialTab);
+const OnyxMobileLayoutBase = ({ tabs, user, drawers = {}, onSignOut, onRefresh, isRefreshing: externalRefreshing, rightAction, initialTab = "home", activeTab: externalActiveTab, activeSubTab: externalActiveSubTab, onNavigate, drawerItems = [], }) => {
+    const [internalActiveTab, setInternalActiveTab] = useState(initialTab);
+    const activeTab = externalActiveTab || internalActiveTab;
     const [isOpen, setIsOpen] = useState(false);
     const [isDragging, setIsDragging] = useState(false);
     const [activeDrawer, setActiveDrawer] = useState(null);
     const [pullY, setPullY] = useState(0);
     const [internalRefreshing, setInternalRefreshing] = useState(false);
     const currentTabConfig = tabs.find((t) => t.id === activeTab);
-    const isRefreshing = currentTabConfig?.isRefreshing ?? externalRefreshing ?? internalRefreshing;
     const subTabs = currentTabConfig?.subTabs || [];
-    const [subTab, setSubTab] = useState(subTabs[0]?.label || "");
+    const [internalSubTab, setInternalSubTab] = useState(subTabs[0]?.label || "");
+    const subTab = externalActiveSubTab || internalSubTab;
+    const navigateTo = (tabId, subTabLabel) => {
+        if (tabId)
+            setInternalActiveTab(tabId);
+        if (subTabLabel)
+            setInternalSubTab(subTabLabel);
+        if (onNavigate) {
+            const targetTab = tabs.find((t) => t.id === (tabId || activeTab));
+            let path = targetTab?.path || "";
+            if (subTabLabel) {
+                const st = targetTab?.subTabs.find((s) => s.label === subTabLabel);
+                if (st?.path) {
+                    if (st.path.startsWith("/")) {
+                        path = st.path;
+                    }
+                    else {
+                        const base = path.endsWith("/") ? path : path + "/";
+                        path = base + st.path;
+                    }
+                }
+            }
+            if (path)
+                onNavigate(path);
+        }
+    };
+    const isRefreshing = currentTabConfig?.isRefreshing ?? externalRefreshing ?? internalRefreshing;
     const navKeys = useMemo(() => tabs.map((t) => t.id), [tabs]);
     const { scrollContainerRef, activeHeight, activeOffset, registerButtonRef } = useRailNavScroll(activeTab, navKeys);
     const DRAWER_WIDTH = 220;
@@ -165,8 +191,8 @@ const OnyxMobileLayoutBase = ({ tabs, user, drawers = {}, onSignOut, onRefresh,
     useEffect(() => {
         if (currentTabConfig && currentTabConfig.subTabs.length > 0) {
             const isValid = currentTabConfig.subTabs.some((st) => st.label === subTab);
-            if (!isValid)
-                setSubTab(currentTabConfig.subTabs[0].label);
+            if (!isValid && currentTabConfig.subTabs.length > 0)
+                navigateTo(undefined, currentTabConfig.subTabs[0].label);
         }
     }, [activeTab, tabs, subTab, currentTabConfig]);
     const [[prevActive, direction], setDir] = useState([activeTab, 0]);
@@ -210,10 +236,7 @@ const OnyxMobileLayoutBase = ({ tabs, user, drawers = {}, onSignOut, onRefresh,
                         targetTab: tabs[0].id,
                         targetSubTab: st.label,
                     }))).map((item) => (_jsxs("button", { onClick: () => {
-                        if (item.targetTab)
-                            setActiveTab(item.targetTab);
-                        if (item.targetSubTab)
-                            setSubTab(item.targetSubTab);
+                        navigateTo(item.targetTab, item.targetSubTab);
                         if (item.onClick)
                             item.onClick({
                                 openDrawer: (id) => setActiveDrawer(id),
@@ -280,9 +303,9 @@ const OnyxMobileLayoutBase = ({ tabs, user, drawers = {}, onSignOut, onRefresh,
             if (Math.abs(lastDxRef.current) > 50) {
                 const idx = subTabs.findIndex((t) => t.label === subTab);
                 if (lastDxRef.current < 0 && idx < subTabs.length - 1)
-                    setSubTab(subTabs[idx + 1].label);
+                    navigateTo(undefined, subTabs[idx + 1].label);
                 else if (lastDxRef.current > 0 && idx > 0)
-                    setSubTab(subTabs[idx - 1].label);
+                    navigateTo(undefined, subTabs[idx - 1].label);
             }
         }
         if (isVerticalPull.current) {
@@ -365,7 +388,7 @@ const OnyxMobileLayoutBase = ({ tabs, user, drawers = {}, onSignOut, onRefresh,
             setQuickMenu((prev) => ({ ...prev, visible: false, selectedIndex: -1 }));
         }
         else {
-            setActiveTab(tabId);
+            navigateTo(tabId);
         }
     };
     const currentTranslate = isDragging ? renderDragX : isOpen ? DRAWER_WIDTH : 0;
@@ -377,7 +400,7 @@ const OnyxMobileLayoutBase = ({ tabs, user, drawers = {}, onSignOut, onRefresh,
                         ? "none"
                         : "transform 0.3s cubic-bezier(0.32, 0.72, 0, 1), border-radius 0.3s",
                     overflow: "hidden",
-                }, children: [isOpen && !isDragging && (_jsx("div", { className: "absolute inset-0 z-50 bg-black/20", onClick: () => setIsOpen(false) })), _jsxs("div", { className: "flex-1 flex flex-col h-full mr-12 relative bg-[rgb(var(--bg-main))]", children: [_jsx(Header, { title: currentTabConfig?.navTitle || currentTabConfig?.label || "App", onMenuClick: () => setIsOpen(!isOpen), rightAction: currentTabConfig?.rightAction || rightAction }), _jsx(HorizontalTabs, { tabs: subTabs, active: subTab, onChange: setSubTab }), _jsxs("main", { ref: mainScrollRef, className: "flex-1 overflow-y-auto no-scrollbar overscroll-contain relative mr-4", children: [_jsx("div", { className: "absolute top-0 left-0 right-0 flex justify-center items-center pointer-events-none z-0", style: {
+                }, children: [isOpen && !isDragging && (_jsx("div", { className: "absolute inset-0 z-50 bg-black/20", onClick: () => setIsOpen(false) })), _jsxs("div", { className: "flex-1 flex flex-col h-full mr-12 relative bg-[rgb(var(--bg-main))]", children: [_jsx(Header, { title: currentTabConfig?.navTitle || currentTabConfig?.label || "App", onMenuClick: () => setIsOpen(!isOpen), rightAction: currentTabConfig?.rightAction || rightAction }), _jsx(HorizontalTabs, { tabs: subTabs, active: subTab, onChange: (label) => navigateTo(undefined, label) }), _jsxs("main", { ref: mainScrollRef, className: "flex-1 overflow-y-auto no-scrollbar overscroll-contain relative mr-4", children: [_jsx("div", { className: "absolute top-0 left-0 right-0 flex justify-center items-center pointer-events-none z-0", style: {
                                             height: `${pullY}px`,
                                             opacity: Math.min(pullY / 40, 1),
                                         }, children: _jsx("div", { className: `p-2 bg-[rgb(var(--bg-surface))] rounded-full shadow-md border border-[rgb(var(--color-border-subtle))] ${isRefreshing

package/dist/types.d.ts

@@ -3,6 +3,7 @@ export interface SubTabConfig {
     label: string;
     icon: ComponentType<any>;
     view: ComponentType<any>;
+    path?: string;
 }
 export interface QuickActionConfig {
     label: string;
@@ -16,6 +17,7 @@ export interface TabConfig {
     label: string;
     icon: ComponentType<any>;
     navTitle?: string;
+    path?: string;
     subTabs: SubTabConfig[];
     quickActions: QuickActionConfig[];
     rightAction?: ReactNode;
@@ -50,5 +52,8 @@ export interface OnyxMobileLayoutProps {
     isRefreshing?: boolean;
     rightAction?: ReactNode;
     initialTab?: string;
+    activeTab?: string;
+    activeSubTab?: string;
+    onNavigate?: (path: string) => void;
     drawerItems?: DrawerItemConfig[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kawaiininja/layouts",
-    "version": "1.0.4",
+    "version": "1.0.6",
     "description": "High-performance, premium mobile-first layouts for the Onyx Framework, featuring gesture-driven navigation, radial quick actions, and integrated theme support.",
     "main": "dist/index.js",
     "module": "dist/index.js",
@@ -26,13 +26,13 @@
     "license": "MIT",
     "repository": {
         "type": "git",
-        "url": "https://github.com/kawaiininja/onyx-framework.git",
+        "url": "https://github.com/4kawaiininja/onyx-framework.git",
         "directory": "layouts"
     },
     "bugs": {
-        "url": "https://github.com/kawaiininja/onyx-framework/issues"
+        "url": "https://github.com/4kawaiininja/onyx-framework/issues"
     },
-    "homepage": "https://github.com/kawaiininja/onyx-framework#readme",
+    "homepage": "https://github.com/4kawaiininja/onyx-framework/blob/main/layouts/README.md",
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",