@kawaiininja/layouts 1.0.3 → 1.0.5

package/README.md

@@ -2,108 +2,187 @@
 
 High-performance, premium mobile-first layouts for the Onyx Framework. Designed with a focus on fluid gestures, modularity, and state-of-the-art aesthetics.
 
+[**📖 Read the Full Developer Guide**](./GUIDE.md) | [**🎨 Explore Examples**](./examples/)
+
+---
+
 ## ✨ Features
 
-- **Gesture-Driven Navigation**: Horizontal tab swiping and vertical pull-to-refresh logic.
-- **Radial Quick Actions**: Long-press navigation keys to trigger a radial menu for rapid access to actions.
-- **Dynamic Headers**: Auto-updating header titles based on navigation state, with support for custom actions.
-- **Modular Drawers**: Easily integrate side menus and custom bottom sheets/panels.
-- **Integrated Theme Support**: Built-in dark/light mode toggle with persistence and system-wide CSS variable injection.
-- **Hardware Back Button Support**: Sophisticated history management for closing overlays and panels seamlessly on mobile devices.
+### 🖐️ Gesture-Driven Navigation (Fluid Flow)
+
+- **Horizontal Tab Swiping**: Seamlessly transition between sub-tabs with natural swipe gestures. Built on a custom gesture engine for zero-lag response.
+- **Vertical Pull-to-Refresh**: Per-tab or global refresh logic with integrated spring physics and haptic feedback support.
+- **Smart History management**: Integrated hardware back-button handling. Pressing "Back" on Android or using back gestures will close drawers and panels before navigating away from the page.
+
+### 🔘 Radial Quick Actions (Long-Press)
+
+- **Zero-Friction Access**: Long-press any navigation rail item to reveal a radial selection menu.
+- **Directional Selection**: Swipe towards an action item to select and execute it instantly without lifting your finger.
+- **Programmable Logic**: Quick actions can trigger internal state changes, external redirects, or open custom layout drawers.
+
+### 🖼️ Modular Layout Engine
+
+- **Dynamic Headers**: Auto-syncing header titles with current navigation state. Supports custom right-aligned actions (buttons, icons, etc.).
+- **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.
+
+### 🎨 Design System & Theme
+
+- **Premium Glassmorphism**: High-quality backdrop blurs and subtle gradients for a modern, high-end feel.
+- **Integrated Theme Support**: Robust dark/light mode toggle with local storage persistence and system-aware defaults.
+
+---
 
 ## 🚀 Installation
 
 ```bash
-npm install @onyx/layouts
+npm install @kawaiininja/layouts
 ```
 
 Note: This package requires `framer-motion`, `lucide-react`, and `react` >= 18.0.0.
 
+---
+
 ## 📦 Usage
 
+### Basic Example
+
 ```jsx
-import { OnyxMobileLayout } from "@onyx/layouts";
-import { Home, Settings, PenTool, RefreshCw } from "lucide-react";
+import { OnyxMobileLayout } from "@kawaiininja/layouts";
+import { Home, Search, Bell, User, PenTool, Grid } from "lucide-react";
 
-const MyLayout = () => {
+const MyApp = () => {
   const tabs = [
     {
       id: "home",
-      icon: Home,
       label: "Home",
-      navTitle: "My Feed",
-      subTabs: [{ label: "Overview", icon: Grid, view: MyViewComponent }],
+      icon: Home,
+      navTitle: "Activity Feed",
+      subTabs: [
+        { label: "Inbox", icon: Grid, view: () => <div>Your Messages</div> },
+      ],
       quickActions: [
         {
+          label: "New Post",
           icon: PenTool,
-          label: "Create",
-          onClick: ({ openDrawer }) => openDrawer("editor"),
+          onClick: ({ openDrawer }) => openDrawer("post_editor"),
         },
       ],
-      onRefresh: () => fetchData(),
-      isRefreshing: loadingState,
     },
   ];
 
   return (
     <OnyxMobileLayout
       tabs={tabs}
-      user={{ name: "Alex", handle: "@alex", avatar: "url" }}
+      user={{
+        name: "Alex Designer",
+        handle: "@alex_ui",
+        avatar: "https://example.com/avatar.png",
+      }}
       drawers={{
-        editor: MyEditorPanel,
+        post_editor: PostEditorPanel,
       }}
     />
   );
 };
 ```
 
+---
+
 ## 🛠️ Configuration API
 
-### OnyxMobileLayoutProps
-
-| Prop           | Type                        | Description                                             |
-| :------------- | :-------------------------- | :------------------------------------------------------ |
-| `tabs`         | `TabConfig[]`               | Array of main navigation tabs (right rail).             |
-| `user`         | `UserConfig`                | User profile data for the side drawer.                  |
-| `drawers`      | `Record<string, Component>` | Dictionary of custom panels/bottom sheets.              |
-| `drawerItems`  | `DrawerItemConfig[]`        | Custom links for the main side drawer.                  |
-| `onSignOut`    | `() => void`                | Callback triggered when the sign-out button is clicked. |
-| `onRefresh`    | `() => void`                | (Global) Callback for pull-to-refresh.                  |
-| `isRefreshing` | `boolean`                   | (Global) Refreshing state.                              |
-| `initialTab`   | `string`                    | ID of the tab to show on mount (default: 'home').       |
-
-### TabConfig
-
-| Field          | Type                  | Description                                       |
-| :------------- | :-------------------- | :------------------------------------------------ |
-| `id`           | `string`              | Unique identifier for navigation.                 |
-| `icon`         | `LucideIcon`          | Icon for the navigation rail.                     |
-| `label`        | `string`              | Label for the navigation rail.                    |
-| `navTitle`     | `string`              | (Optional) Title shown in the header when active. |
-| `subTabs`      | `SubTabConfig[]`      | Array of nested horizontal tabs.                  |
-| `quickActions` | `QuickActionConfig[]` | Actions triggered by long-press on the nav key.   |
-| `onRefresh`    | `() => void`          | Tab-specific refresh callback.                    |
-| `isRefreshing` | `boolean`             | Tab-specific refresh state.                       |
-
-### QuickActionConfig / DrawerItemConfig
-
-Quick actions and Drawer items support an `onClick` callback that receives a context object:
-
-```typescript
-onClick: ({ openDrawer: (id: string) => void }) => void
-```
+### `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).              |
+
+### `TabConfig`
 
-## 🎨 Theme Variables
+| 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.                                                 |
 
-The layout relies on the following CSS variables for its design system:
+### `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. |
+
+### `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 }`. |
+
+---
+
+## 🌊 Gesture Interactions Guide
+
+### 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.
+
+### 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.
+
+---
+
+## 🎨 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) */
+  --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;
+}
+```
 
-- `--bg-main`: Page background
-- `--bg-surface`: Header/Tab background
-- `--bg-elevated`: Drawer/Overlay background
-- `--color-accent`: Highlight/Active color
-- `--text-primary`: Main text
-- `--text-muted`: Secondary text
-- `--color-border-subtle`: Borders and dividers
+---
 
 ## ⚖️ License
 

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,17 +3,21 @@ export interface SubTabConfig {
     label: string;
     icon: ComponentType<any>;
     view: ComponentType<any>;
+    path?: string;
 }
 export interface QuickActionConfig {
     label: string;
     icon: ComponentType<any>;
-    onClick?: () => void;
+    onClick?: (ctx: {
+        openDrawer: (id: string) => void;
+    }) => void;
 }
 export interface TabConfig {
     id: string;
     label: string;
     icon: ComponentType<any>;
     navTitle?: string;
+    path?: string;
     subTabs: SubTabConfig[];
     quickActions: QuickActionConfig[];
     rightAction?: ReactNode;
@@ -25,7 +29,9 @@ export interface DrawerItemConfig {
     icon: any;
     targetTab?: string;
     targetSubTab?: string;
-    onClick?: () => void;
+    onClick?: (ctx: {
+        openDrawer: (id: string) => void;
+    }) => void;
 }
 export interface UserConfig {
     name: string;
@@ -46,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.3",
+    "version": "1.0.5",
     "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",