getlotui 0.1.0 → 0.1.2

package/ENHANCED_INPUTS.md

@@ -0,0 +1,141 @@
+# Enhanced Input Components
+
+## Overview
+We've significantly enhanced the CrossUI input system with modern, production-ready components featuring animations, icons, and multiple input types.
+
+## New Components
+
+### 1. **OTPInput Component** 🔐
+A premium one-time password input component with:
+- **Auto-focus**: Automatically focuses the first input
+- **Smooth animations**: Scale animations on input
+- **Auto-advance**: Moves to next field automatically
+- **Backspace handling**: Smart navigation on delete
+- **Secure mode**: Optional password masking
+- **Customizable length**: Support for 4, 6, or any digit length
+- **Multiple variants**: default, filled, error, success
+- **Multiple sizes**: sm, md, lg
+- **Completion callback**: Triggers when all digits are entered
+
+**Usage:**
+```tsx
+<OTPInput
+  length={6}
+  value={otp}
+  onChange={setOtp}
+  onComplete={(code) => Alert.alert("Complete!", code)}
+  size="md"
+  variant="default"
+/>
+```
+
+### 2. **Enhanced Input Component** ✨
+Upgraded the existing Input with:
+- **Left/Right Icons**: Support for Ionicons on both sides
+- **Focus Animations**: Smooth border color transitions
+- **Helper Text**: Additional guidance below input
+- **Improved Shadows**: Dynamic shadows based on focus state
+- **Icon Callbacks**: Clickable right icons (e.g., clear button)
+- **Better Visual Hierarchy**: Enhanced border widths and colors
+
+**New Props:**
+- `leftIcon`: Icon name from Ionicons
+- `rightIcon`: Icon name from Ionicons
+- `onRightIconPress`: Callback for right icon press
+- `helperText`: Helper text displayed below input
+
+**Usage:**
+```tsx
+<Input
+  label="Email"
+  placeholder="john@example.com"
+  leftIcon="mail-outline"
+  rightIcon="close-circle"
+  onRightIconPress={() => setValue("")}
+  helperText="We'll never share your email"
+/>
+```
+
+## Enhanced JSON Configurations
+
+### Input Variants
+Added new style variants to `input.json`:
+- **filled**: Light background, no border
+- **outlined**: Transparent background, visible border
+- **underlined**: Transparent background, bottom border only
+- **focused**: Enhanced border width (2px) for better visibility
+- **error**: Improved border width (1.5px)
+
+### OTP Input Configuration
+New `otp-input.json` with:
+- **Variants**: default, filled, error, success
+- **Sizes**: sm (40x48), md (50x56), lg (60x64)
+- **Defaults**: 6-digit length, 12px gap between boxes
+
+## Visual Improvements
+
+### Animations
+1. **Focus Animation**: Border color smoothly transitions to primary color
+2. **OTP Scale Animation**: Each box scales on input for tactile feedback
+3. **Icon Color Transition**: Icons change color on focus
+
+### Shadows
+- **Default State**: Subtle shadow (opacity: 0.05, radius: 4)
+- **Focused State**: Enhanced shadow (opacity: 0.15, radius: 8, primary color)
+- **OTP Boxes**: Individual shadows with focus enhancement
+
+### Typography & Spacing
+- **Helper Text**: 13px, subtle color
+- **Error Text**: 13px, danger color, with icon
+- **Labels**: 14px, semibold, consistent spacing
+- **Icon Sizing**: Responsive to input size (16-24px)
+
+## Demo Features in App.tsx
+
+The playground now showcases:
+1. **OTP Input Section**:
+   - 6-digit verification code
+   - 4-digit secure PIN with masking
+   
+2. **Enhanced Inputs Section**:
+   - Email with mail icon
+   - Password with lock icon
+   - Search with clear button
+   - Phone with call icon
+   - Location with navigation icon
+   - Multiline bio with helper text
+   - Error state with alert icon
+
+## File Structure
+
+```
+packages/
+├── core/
+│   └── components/
+│       ├── input.json (enhanced)
+│       └── otp-input.json (new)
+└── expo/
+    └── src/
+        └── components/
+            ├── Input.tsx (enhanced)
+            └── OTPInput.tsx (new)
+```
+
+## Best Practices
+
+1. **Use helper text** for additional context
+2. **Add icons** for better visual hierarchy
+3. **Implement clear buttons** for better UX
+4. **Use OTP input** for verification codes
+5. **Leverage animations** for premium feel
+6. **Maintain consistent spacing** with design tokens
+
+## Next Steps
+
+Potential enhancements:
+- Floating label inputs
+- Input masks (phone, credit card)
+- Autocomplete support
+- Voice input integration
+- Custom keyboard types
+- Input groups/compound inputs

package/README.md

@@ -1,78 +1,159 @@
-# Getting Started with GetLotUI
+# 🛸 GetLotUI
+
+> **The Unified, Token-Driven Design System for Every Platform.**
+
+GetLotUI is a high-performance, platform-agnostic design system built on a **"Token-First"** architecture. It allows developers to define design intent once and deploy it across **Web**, **Expo (React Native)**, and **Flutter** with pixel-perfect consistency.
+ 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
+[![pnpm](https://img.shields.io/badge/maintained%20with-pnpm-cc00ff.svg)](https://pnpm.io/)
+ 
+---
+
+## 🤔 Why GetLotUI?
+
+Maintaining a consistent design system across Web and Mobile is notoriously difficult. Developers often end up duplicating styles in CSS, React Native Stylesheets, and Dart, leading to **brand drift** and maintenance nightmares.
+
+**GetLotUI solves this by:**
+1. **Centralizing Truth**: Every color, font size, and spacing unit lives in a single JSON source.
+2. **Native Performance**: No runtime translation layers. We generate native code for each platform.
+3. **Developer Experience**: Use a familiar CLI to "add" components just like shadcn/ui.
+
+---
+
+## 🎨 Design Philosophy
+
+- **Atomic Tokens**: Every design decision is a token.
+- **Contract over Implementation**: Define *what* a component does before deciding *how* it's rendered.
+- **Copy-Paste (Source-First)**: Components are copied into your repo. You own the code. No complex library dependencies.
+
+---
+ 
+## ✨ Features
+
+- **🌐 Cross-Platform by Design**: First-class support for Web, Expo, and Flutter.
+- **💎 Token-Driven Logic**: Change a color in your JSON tokens and watch it update across JS, Dart, and CSS.
+- **🛠️ Powerful CLI**: Scaffold components and initialize projects with a single command.
+- **📦 Monorepo powered by PNPM**: Seamlessly link core logic with platform implementations.
+- **📖 Live Documentation**: Built-in Next.js documentation site generated from your components.
+
+---
+
+## 📐 Architecture
+
+GetLotUI separates **Design Intent** from **Platform Implementation**. This ensures that your brand identity remains consistent even if you change your tech stack.
+
+```mermaid
+graph TD
+    A[Core Tokens JSON/TS] --> B(CLI Engine)
+    B --> C[Web Styles]
+    B --> D[Expo Components]
+    B --> E[Flutter Widgets]
+    
+    subgraph "Design Logic"
+    A
+    end
+    
+    subgraph "Output Adapters"
+    C
+    D
+    E
+    end
+```
 
-GetLotUI is a component scaffolding tool that copies customizable, source-code components directly into your project. It is designed to work seamlessly with Expo and React Native applications.
+### The Layered Model
 
-## Prerequisites
+| Layer | Responsibility | Technology | Output |
+| :--- | :--- | :--- | :--- |
+| **01. Token Layer** | Colors, Spacing, Typography | JSON / TypeScript | Design Variables |
+| **02. Contract Layer** | Component Interfaces & Logic | TypeScript Interfaces | Prop Definitions |
+| **03. Render Layer** | Platform-specific Views | React Native / Swift / Dart | The Visual UI |
 
-- **Node.js** (v18 or higher)
-- An existing **Expo** project (managed or bare workflow)
+---
 
-## Installation
+## 🧩 Available Components
 
-You don't need to install GetLotUI globally. You can use it directly via `npx`.
+Scaffold these instantly using `npx getlotui add <name>`:
 
-However, if you prefer to install it as a dev dependency in your project:
+| Component | Expo | Flutter | Web |
+| :--- | :---: | :---: | :---: |
+| **Button** | ✅ | ✅ | ✅ |
+| **Input** | ✅ | ✅ | ✅ |
+| **Toast** | ✅ | 🚧 | ✅ |
+| **Badge** | ✅ | 🚧 | ✅ |
+| **Avatar** | ✅ | 🚧 | ✅ |
+| **Card** | ✅ | ✅ | ✅ |
+| **Dropdown** | ✅ | 🚧 | ✅ |
 
-```bash
-pnpm add -D getlotui
-# or
-npm install -D getlotui
-# or
-yarn add -D getlotui
-```
+---
 
-## Initialization
+## 📁 Repository Structure
 
-Run the `init` command to set up GetLotUI in your project. This will create a `getlotui.config.json` file in your root directory.
+### 📦 Packages (`/packages`)
+- **`@getlotui/core`**: The brain. Contains tokens, design system logic, and shared types.
+- **`@getlotui/cli`**: The developer's Swiss Army knife. Used to manage the design system.
+- **`@getlotui/expo`**: React Native (Expo) implementation of the GetLotUI components.
+- **`@getlotui/flutter`**: Flutter implementation using Dart tokens.
+- **`@getlotui/web`**: Web implementation (Tailwind CSS and React).
 
-```bash
-npx getlotui init
-```
+### 🧪 Apps (`/apps`)
+- **`documentation`**: The official Next.js documentation website.
+- **`expo-playground`**: Sandbox for testing Expo components.
+- **`flutter-playground`**: Sandbox for testing Flutter components.
 
-The CLI will:
-1. Detect your project type (e.g., Expo).
-2. Create `getlotui.config.json` with default settings:
+---
 
-```json
-{
-  "adapter": "expo",
-  "componentsDir": "components/ui"
-}
-```
+## 🚀 Getting Started
 
-## Adding Components
+### 1. Prerequisites
+Ensure you have [Node 20+](https://nodejs.org/) and [pnpm](https://pnpm.io/) installed.
+
+```bash
+npm install -g pnpm
+```
 
-Once initialized, you can add components to your project. Use the `add` command followed by the component name.
+### 2. Installation
+Install dependencies for all workspaces:
 
 ```bash
-npx getlotui add button
-npx getlotui add input
+pnpm install
 ```
 
-This will:
-1. Download/Copy the component source code to your configured `componentsDir` (default: `components/ui`).
-2. Add any necessary utility files (if applicable in future updates).
+### 3. Development
+- **Run Docs**: `pnpm --filter documentation dev`
+- **Run Expo Sandbox**: `pnpm --filter expo-playground start`
+- **Run Flutter Sandbox**: `cd apps/flutter-playground && flutter run`
+
+---
 
-Now you can import and use the component in your app:
+## 🛠️ CLI Usage
 
-```tsx
-import { Button } from '@/components/ui/Button';
+The GetLotUI CLI allows you to easily integrate the design system into any project.
 
-export default function App() {
-  return (
-    <Button title="Click Me" onPress={() => console.log('Pressed')} variant="primary" />
-  );
-}
+### Initialize a project
+Automatically detects your framework (Expo, Flutter, or Web) and sets up the configuration.
+```bash
+npx getlotui init
+```
+
+### Add a component
+Fetch a pre-styled component from the GetLotUI library.
+```bash
+npx getlotui add button
+npx getlotui add card
 ```
 
-## Customization
+---
 
-Since GetLotUI copies the **source code** into your project, you have full control.
-- Open `components/ui/Button.tsx`.
-- Modify styles, props, or behavior to match your design system.
-- No vendor lock-in; it's your code now!
+## ⚙️ Road Map
+- [x] Expo Implementation
+- [x] CLI Foundation
+- [x] Flutter Support (Beta)
+- [ ] Web Components (Alpha)
+- [ ] Figma to Token Sync
+- [ ] Automated Visual Regression Testing
 
-## Troubleshooting
+---
 
-- **"getlotui.config.json not found"**: Run `npx getlotui init` first.
-- **"Component already exists"**: The CLI won't overwrite existing files to prevent data loss. Rename your existing file or delete it if you want to replace it.
+## 📜 License
+MIT © 2026 GetLotUI Team. Built with ❤️ for the community.