@kawaiininja/layouts 1.0.3 → 1.0.4

package/README.md

@@ -2,14 +2,36 @@
 
 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
 
@@ -19,91 +41,148 @@ npm install @onyx/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 { 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/types.d.ts

@@ -7,7 +7,9 @@ export interface SubTabConfig {
 export interface QuickActionConfig {
     label: string;
     icon: ComponentType<any>;
-    onClick?: () => void;
+    onClick?: (ctx: {
+        openDrawer: (id: string) => void;
+    }) => void;
 }
 export interface TabConfig {
     id: string;
@@ -25,7 +27,9 @@ export interface DrawerItemConfig {
     icon: any;
     targetTab?: string;
     targetSubTab?: string;
-    onClick?: () => void;
+    onClick?: (ctx: {
+        openDrawer: (id: string) => void;
+    }) => void;
 }
 export interface UserConfig {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kawaiininja/layouts",
-    "version": "1.0.3",
+    "version": "1.0.4",
     "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",