@hoddy-ui/core 1.1.0 → 1.1.2

package/README.md

@@ -1,331 +1,1113 @@
 # @hoddy-ui/core
 
-Hoddy UI is a versatile UI component and theming library for React Native and Expo. It follows the Hoddy UI design guidelines, which are a tweak of Material Design. The library provides a collection of reusable components and a customizable theming system to simplify and accelerate the development of mobile applications.
+**The complete UI component library for React Native and Expo applications**
 
-## Installation
+A comprehensive, production-ready UI component library that follows Material Design principles with a modern twist. Built with TypeScript and optimized for React Native and Expo applications.
 
-To install Hoddy UI, use npm or yarn:
+## ✨ Features
 
-**npm:**
+- 🎨 **20+ Production-Ready Components** - From basic buttons to complex forms
+- 🌗 **Dark Mode Support** - Automatic theme switching with system preference detection
+- 🔧 **TypeScript First** - Full type safety and IntelliSense support
+- ⚡ **Performance Optimized** - Minimal bundle size with tree shaking
+- 🎯 **Accessibility Ready** - WCAG compliant components
+- 🔌 **Highly Customizable** - Extensive theming and configuration options
+- 📱 **Cross Platform** - Works seamlessly on iOS and Android
 
-```sh
+## 📦 Installation
+
+```bash
 npm install @hoddy-ui/core
+# or
+yarn add @hoddy-ui/core
 ```
 
-**yarn:**
+### Peer Dependencies
 
-```sh
-yarn add @hoddy-ui/core
+Install the required peer dependencies:
+
+```bash
+npm install @expo/vector-icons @react-native-async-storage/async-storage @react-navigation/native expo-navigation-bar expo-system-ui react-native-safe-area-context react-native-size-matters
 ```
 
-Hoddy UI has the following peer dependencies, make sure to install them as well:
+Or with yarn:
 
-```json
-"@expo/vector-icons": "^13.0.0",
-"@react-native-async-storage/async-storage": "^1.18.1",
-"@react-navigation/native": "^6.1.6",
-"expo-navigation-bar": "^2.1.1",
-"expo-system-ui": "^2.2.1",
-"react": "^18.2.0",
-"react-native": "^0.71.8",
-"react-native-safe-area-context": "^4.5.3",
-"react-native-size-matters": "^0.4.0"
+```bash
+yarn add @expo/vector-icons @react-native-async-storage/async-storage @react-navigation/native expo-navigation-bar expo-system-ui react-native-safe-area-context react-native-size-matters
 ```
 
-## Enabling dark mode
+## 🚀 Quick Start
 
-To take advantage of the dark mode feature, add the UIProvider component to the root of your app
+### Basic Setup
 
-```javascript
-import { UIThemeProvider } from "hoddy-ui/core";
+1. **Initialize the library** (optional but recommended):
 
-function App() {
+```tsx
+import { initialize } from "@hoddy-ui/core";
+
+initialize({
+  // Custom font family
+  fontFamily: "Inter-Regular",
+
+  // Google Maps API key for Locator component
+  googleMapApiKey: "your-google-maps-api-key",
+
+  // Edge-to-edge display (affects Android navigation bar styling)
+  edgeToEdge: false,
+
+  // Custom colors
+  colors: {
+    primary: {
+      main: "#6366f1",
+      light: "#818cf8",
+      dark: "#4f46e5",
+    },
+  },
+});
+```
+
+2. **Wrap your app with the theme provider**:
+
+```tsx
+import React from "react";
+import { UIThemeProvider } from "@hoddy-ui/core";
+import App from "./App";
+
+export default function Root() {
   return (
     <UIThemeProvider>
-      <Component />
+      <App />
     </UIThemeProvider>
   );
 }
 ```
 
-## Usage
-
-Here's a quick example of how to use Hoddy UI in your React Native or Expo project:
+3. **Start using components**:
 
-```javascript
+```tsx
 import React from "react";
 import { View } from "react-native";
-import { Button, Typography } from "@hoddy-ui/core";
+import {
+  Typography,
+  Button,
+  TextField,
+  Animator,
+  useColors,
+  useFadeAnimation,
+} from "@hoddy-ui/core";
+
+export default function HomeScreen() {
+  const colors = useColors();
 
-const HomeScreen = () => {
   return (
-    <View>
-      <Typography>Welcome to Hoddy UI!</Typography>
-      <Button title="Click me" onPress={() => console.log("Button pressed!")} />
+    <View style={{ padding: 20, backgroundColor: colors.white[1] }}>
+      <Animator type="fade" duration={1000}>
+        <Typography variant="h4" color="primary" gutterBottom={20}>
+          Welcome to Hoddy UI!
+        </Typography>
+      </Animator>
+
+      <Animator type="slide" direction="up" delay={200}>
+        <TextField
+          label="Email Address"
+          variant="outlined"
+          keyboardType="email-address"
+          gutterBottom={16}
+        />
+      </Animator>
+
+      <Animator type="grow" delay={400}>
+        <Button
+          title="Get Started"
+          variant="contained"
+          color="primary"
+          onPress={() => console.log("Button pressed!")}
+        />
+      </Animator>
     </View>
   );
-};
+}
+```
+
+## ⚙️ Configuration
+
+### Global Configuration
+
+Use the `initialize` function to configure the library globally:
+
+```tsx
+import { initialize } from "@hoddy-ui/core";
 
-export default HomeScreen;
+initialize({
+  // Font family for all typography components
+  fontFamily?: string;
+
+  // Google Maps API key for Locator component
+  googleMapApiKey?: string;
+
+  // Edge-to-edge display (skips Android navigation bar styling)
+  edgeToEdge?: boolean;
+
+  // Custom color overrides
+  colors?: {
+    primary?: { main: string; light?: string; dark?: string };
+    secondary?: { main: string; light?: string; dark?: string };
+    // ... and more
+  };
+});
 ```
 
-## Components
+### Theme Configuration
 
-Hoddy UI provides the following components for building your UI:
+The theme system automatically detects system preferences and can be controlled programmatically:
 
-- [AdaptiveStatusBar](#adaptivestatusbar)
-- [Avatar](#avatar)
-- [AlertX](#alertx)
-- [Button](#button)
-- [FlashMessage](#flashmessage)
-- [FormWrapper](#formwrapper)
-- [Grid](#grid)
-- [GridItem](#griditem)
-- [IconButton](#iconbutton)
-- [LinkButton](#linkbutton)
-- [List](#list)
-- [ListItem](#listitem)
-- [ListItemText](#listitemtext)
-- [Locator](#locator)
-- [Popup](#popup)
-- [SafeAreaView](#safeareaview)
-- [Spinner](#spinner)
-- [TextField](#textfield)
-- [TextField2](#textfield2)
-- [Typography](#typography)
+```tsx
+import { useTheme } from "@hoddy-ui/core";
 
-## Component API Reference
+function ThemeToggle() {
+  const { themeState, themeDispatch } = useTheme();
 
-### AdaptiveStatusBar
+  const toggleTheme = () => {
+    themeDispatch({
+      type: themeState.mode === "dark" ? "light" : "dark",
+    });
+  };
 
-A component that adapts the status bar color based on the theme.
+  return (
+    <Button
+      title={`Switch to ${themeState.mode === "dark" ? "Light" : "Dark"} Mode`}
+      onPress={toggleTheme}
+    />
+  );
+}
+```
 
-**Props:**
+## 🎨 Theming System
 
-| Prop            | Type   | Default         | Description                                                                               |
-| --------------- | ------ | --------------- | ----------------------------------------------------------------------------------------- |
-| barStyle        | string | "light-content" | The style of the status bar. Possible values: "default", "light-content", "dark-content". |
-| backgroundColor | string | Theme-dependent | The background color of the status bar.                                                   |
+### Using Hooks
 
-Example usage:
+Access theme colors and state throughout your app:
 
-```jsx
-import { AdaptiveStatusBar } from "@hoddy-ui/core";
+```tsx
+import { useColors, useTheme } from "@hoddy-ui/core";
+
+function MyComponent() {
+  const colors = useColors();
+  const theme = useTheme();
 
-const App = () => {
   return (
-    <>
-      <AdaptiveStatusBar />
-      {/* Rest of the app */}
-    </>
+    <View
+      style={{
+        backgroundColor: colors.white[1],
+        borderColor: colors.primary.main,
+      }}
+    >
+      <Typography color={theme === "dark" ? "white" : "dark"}>
+        Current theme: {theme}
+      </Typography>
+    </View>
   );
+}
+```
+
+### Color Palette
+
+The library includes a comprehensive color system:
+
+```tsx
+const colors = {
+  // Primary colors
+  primary: { main: "#007AFF", light: "#5AC8FA", dark: "#0051D5" },
+  secondary: { main: "#FF3B30", light: "#FF6B6B", dark: "#D70015" },
+
+  // Neutral colors
+  white: ["#FFFFFF", "#F8F9FA", "#E9ECEF"],
+  black: ["#000000", "#212529", "#495057"],
+
+  // Semantic colors
+  success: { main: "#28A745", light: "#34CE57", dark: "#1E7E34" },
+  error: { main: "#DC3545", light: "#E74C3C", dark: "#C82333" },
+  warning: { main: "#FFC107", light: "#FFD54F", dark: "#FF8F00" },
+
+  // Utility colors
+  textPrimary: { main: "#212529" },
+  textSecondary: { main: "#6C757D" },
+  divider: { main: "#DEE2E6" },
 };
 ```
 
-### Avatar
+## 🧩 Components
 
-A component for displaying user avatars.
+### Layout & Structure
 
-**Props:**
+- **`SafeAreaView`** - Safe area wrapper for different devices
+- **`Grid`** & **`GridItem`** - Flexible grid layout system
+- **`FormWrapper`** - Form container with validation support
 
-| Prop    | Type    | Default | Description                           |
-| ------- | ------- | ------- | ------------------------------------- |
-| image   | number  | -       | The source of the avatar image.       |
-| size    | number  | 40      | The size of the avatar in pixels.     |
-| rounded | boolean | false   | Whether the avatar should be rounded. |
+### Navigation & Status
 
-### AlertX
+- **`AdaptiveStatusBar`** - Theme-aware status bar
+- Navigation utilities via hooks
 
-A customizable alert component.
+### Typography
 
-**Props:**
+- **`Typography`** - Comprehensive text component with variants (h1-h6, body1-body2, caption)
 
-| Prop    | Type   | Default   | Description                                                                       |
-| ------- | ------ | --------- | --------------------------------------------------------------------------------- |
-| title   | string | -         | The title of the alert.                                                           |
-| message | string | -         | The message/content of the alert.                                                 |
-| type    | string | "default" | The type of the alert. Possible values: "default", "success", "error", "warning". |
+### Form Components
 
-### Button
+- **`TextField`** - Material Design text input with variants
+- **`TextField2`** - Alternative text field design
+- **`Locator`** - Location picker with Google Maps integration
 
-A customizable button component.
+### Interactive Elements
 
-**Props:**
+- **`Button`** - Primary action buttons with variants
+- **`IconButton`** - Icon-only buttons
+- **`LinkButton`** - Text-based link buttons
 
-| Prop    | Type     | Default | Description                                |
-| ------- | -------- | ------- | ------------------------------------------ |
-| title   | string   | -       | The text to display on the button.         |
-| onPress | function | -       | The function to be called on button press. |
+### Feedback & Communication
 
-### FlashMessage
+- **`FlashMessage`** - Toast notifications and alerts
+- **`AlertX`** - Customizable alert dialogs
+- **`Spinner`** - Loading indicators
 
-A component for displaying flash messages.
+### Data Display
 
-**Props:**
+- **`Avatar`** - User profile images and placeholders
+- **`List`**, **`ListItem`**, **`ListItemText`** - List components
 
-| Prop     | Type    | Default   | Description                                                                               |
-| -------- | ------- | --------- | ----------------------------------------------------------------------------------------- |
-| message  | string  | -         | The message/content of the flash message.                                                 |
-| type     | string  | "default" | The type of the flash message. Possible values: "default", "success", "error", "warning". |
-| duration | number  | 3000      | The duration in milliseconds that the flash message should be displayed.                  |
-| autoHide | boolean | true      | Whether the flash message should auto-hide after the specified duration.                  |
+### Overlays & Modals
 
-### FormWrapper
+- **`Popup`** - Modal dialogs and bottom sheets
 
-A wrapper component for form fields.
+### Animation
 
-**Props:**
+- **`Animator`** - Layout animations and transitions
 
-| Prop     | Type | Default | Description                               |
-| -------- | ---- | ------- | ----------------------------------------- |
-| children | node | -       | The form fields/components to be wrapped. |
+## 📖 Component API Reference
 
-### Grid
+### Typography
 
-A flexible grid component for arranging child elements.
+A versatile text component supporting multiple variants and styling options.
 
 **Props:**
 
-| Prop       | Type   | Default | Description                                    |
-| ---------- | ------ | ------- | ---------------------------------------------- |
-| children   | node   | -       | The child elements to be rendered in the grid. |
-| numColumns | number | 2       | The number of columns in the grid.             |
-| spacing    | number | 10      | The spacing between grid items in pixels.      |
+| Prop           | Type                                                                              | Default   | Description                   |
+| -------------- | --------------------------------------------------------------------------------- | --------- | ----------------------------- |
+| `variant`      | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "body1" \| "body2" \| "caption"` | `"body1"` | Text style variant            |
+| `color`        | `string`                                                                          | `"dark"`  | Text color from theme palette |
+| `align`        | `"left" \| "center" \| "right"`                                                   | `"left"`  | Text alignment                |
+| `gutterBottom` | `number`                                                                          | `0`       | Bottom margin in pixels       |
+| `fontWeight`   | `number`                                                                          | `400`     | Font weight                   |
+| `textCase`     | `"uppercase" \| "lowercase" \| "capitalize"`                                      | `null`    | Text transformation           |
+
+**Example:**
+
+```tsx
+<Typography variant="h4" color="primary" gutterBottom={20}>
+  Welcome to Hoddy UI
+</Typography>
+```
 
-### GridItem
+### Button
 
-A component representing an item in the Grid component.
+A comprehensive button component with multiple variants and states.
 
 **Props:**
 
-| Prop     | Type | Default | Description                   |
-| -------- | ---- | ------- | ----------------------------- |
-| children | node | -       | The content of the grid item. |
+| Prop       | Type                                  | Default       | Description                |
+| ---------- | ------------------------------------- | ------------- | -------------------------- |
+| `title`    | `string`                              | -             | Button text                |
+| `variant`  | `"contained" \| "outlined" \| "text"` | `"contained"` | Button variant             |
+| `color`    | `string`                              | `"primary"`   | Button color from theme    |
+| `size`     | `"small" \| "medium" \| "large"`      | `"medium"`    | Button size                |
+| `disabled` | `boolean`                             | `false`       | Disabled state             |
+| `loading`  | `boolean`                             | `false`       | Loading state with spinner |
+| `onPress`  | `() => void`                          | -             | Press handler              |
+| `start`    | `ReactNode`                           | -             | Leading icon/element       |
+| `end`      | `ReactNode`                           | -             | Trailing icon/element      |
+
+**Example:**
+
+```tsx
+<Button
+  title="Submit"
+  variant="contained"
+  color="primary"
+  loading={isLoading}
+  onPress={handleSubmit}
+/>
+```
 
 ### IconButton
 
-A button component with an icon.
+A button component that displays only an icon.
 
 **Props:**
 
-| Prop    | Type     | Default | Description                                |
-| ------- | -------- | ------- | ------------------------------------------ |
-| icon    | string   | -       | The name of the icon to display.           |
-| onPress | function | -       | The function to be called on button press. |
+| Prop              | Type                  | Default      | Description               |
+| ----------------- | --------------------- | ------------ | ------------------------- |
+| `icon`            | `string`              | -            | Icon name                 |
+| `iconType`        | `"material" \| "ion"` | `"material"` | Icon library to use       |
+| `size`            | `number`              | `24`         | Icon size in pixels       |
+| `color`           | `string`              | `"dark"`     | Icon color from theme     |
+| `bg`              | `boolean`             | `false`      | Show background circle    |
+| `elevation`       | `number`              | `0`          | Shadow elevation          |
+| `disabled`        | `boolean`             | `false`      | Disabled state            |
+| `onPress`         | `() => void`          | -            | Press handler             |
+| `style`           | `ViewStyle`           | `{}`         | Icon style overrides      |
+| `containerStyles` | `ViewStyle`           | `{}`         | Container style overrides |
+
+**Example:**
+
+```tsx
+<IconButton
+  icon="star"
+  iconType="ion"
+  size={28}
+  color="primary"
+  bg={true}
+  elevation={2}
+  onPress={() => console.log("Starred!")}
+/>
+```
 
 ### LinkButton
 
-A button component that navigates to a specified URL.
+A text-based button component for navigation or secondary actions.
 
 **Props:**
 
-| Prop  | Type   | Default | Description                             |
-| ----- | ------ | ------- | --------------------------------------- |
-| title | string | -       | The text to display on the button.      |
-| url   | string | -       | The URL to navigate to on button press. |
+| Prop         | Type         | Default  | Description           |
+| ------------ | ------------ | -------- | --------------------- |
+| `title`      | `string`     | -        | Button text           |
+| `color`      | `string`     | `"blue"` | Text color from theme |
+| `fontSize`   | `number`     | `12`     | Font size             |
+| `fontWeight` | `string`     | `"400"`  | Font weight           |
+| `disabled`   | `boolean`    | `false`  | Disabled state        |
+| `onPress`    | `() => void` | -        | Press handler         |
+| `style`      | `TextStyle`  | `{}`     | Text style overrides  |
+
+**Example:**
+
+```tsx
+<LinkButton
+  title="Forgot Password?"
+  color="primary"
+  fontSize={14}
+  onPress={() => navigation.navigate("ForgotPassword")}
+/>
+```
 
-### List
+### TextField
 
-A component for rendering lists.
+A Material Design text input component with comprehensive features.
 
 **Props:**
 
-| Prop     | Type | Default | Description                    |
-| -------- | ---- | ------- | ------------------------------ |
-| children | node | -       | The list items to be rendered. |
+| Prop           | Type                                   | Default      | Description           |
+| -------------- | -------------------------------------- | ------------ | --------------------- |
+| `label`        | `string`                               | -            | Input label           |
+| `variant`      | `"outlined" \| "filled" \| "standard"` | `"outlined"` | Input variant         |
+| `value`        | `string`                               | -            | Input value           |
+| `onChangeText` | `(text: string) => void`               | -            | Change handler        |
+| `placeholder`  | `string`                               | -            | Placeholder text      |
+| `error`        | `boolean`                              | `false`      | Error state           |
+| `helperText`   | `string`                               | -            | Helper/error text     |
+| `disabled`     | `boolean`                              | `false`      | Disabled state        |
+| `multiline`    | `boolean`                              | `false`      | Multiline input       |
+| `start`        | `ReactNode`                            | -            | Leading icon/element  |
+| `end`          | `ReactNode`                            | -            | Trailing icon/element |
+
+**Example:**
+
+```tsx
+<TextField
+  label="Email Address"
+  variant="outlined"
+  value={email}
+  onChangeText={setEmail}
+  keyboardType="email-address"
+  error={!!emailError}
+  helperText={emailError}
+/>
+```
 
-### ListItem
+### Locator
 
-A component representing an item in the List component.
+A location picker component with Google Maps integration.
 
 **Props:**
 
-| Prop     | Type | Default | Description                   |
-| -------- | ---- | ------- | ----------------------------- |
-| children | node | -       | The content of the list item. |
+| Prop                 | Type                               | Default       | Description                |
+| -------------------- | ---------------------------------- | ------------- | -------------------------- |
+| `onLocationSelected` | `(location: LocationType) => void` | -             | Location selection handler |
+| `label`              | `string`                           | -             | Input label                |
+| `variant`            | `"contained" \| "outlined"`        | `"contained"` | Input variant              |
+| `location`           | `LocationType`                     | -             | Current location           |
+| `country`            | `string`                           | `"ng"`        | Country code for search    |
+| `error`              | `boolean`                          | `false`       | Error state                |
+
+**Example:**
+
+```tsx
+<Locator
+  label="Select Location"
+  onLocationSelected={(location) => setSelectedLocation(location)}
+  country="us"
+/>
+```
 
-### ListItemText
+### SafeAreaView
 
-A component representing the text content of a ListItem.
+A safe area wrapper component that handles device-specific safe areas.
 
 **Props:**
 
-| Prop     | Type | Default | Description              |
-| -------- | ---- | ------- | ------------------------ |
-| children | node | -       | The text to be rendered. |
+| Prop       | Type        | Default | Description               |
+| ---------- | ----------- | ------- | ------------------------- |
+| `children` | `ReactNode` | -       | Child components          |
+| `style`    | `ViewStyle` | `{}`    | Container style overrides |
 
-### Locator
+**Example:**
 
-A component for displaying a location marker on a map.
+```tsx
+<SafeAreaView style={{ backgroundColor: "white" }}>
+  <YourContent />
+</SafeAreaView>
+```
+
+### AdaptiveStatusBar
+
+A status bar component that automatically adapts to the current theme.
 
 **Props:**
 
-| Prop      | Type   | Default | Description                    |
-| --------- | ------ | ------- | ------------------------------ |
-| latitude  | number | -       | The latitude of the location.  |
-| longitude | number | -       | The longitude of the location. |
+| Prop          | Type      | Default | Description                           |
+| ------------- | --------- | ------- | ------------------------------------- |
+| `translucent` | `boolean` | `false` | Whether the status bar is translucent |
 
-### Popup
+**Example:**
 
-A customizable popup component.
+```tsx
+<AdaptiveStatusBar translucent={true} />
+```
+
+### AlertX
+
+A customizable alert component for displaying important messages.
 
 **Props:**
 
-| Prop    | Type     | Default | Description                                         |
-| ------- | -------- | ------- | --------------------------------------------------- |
-| title   | string   | -       | The title of the popup.                             |
-| onClose | function | -       | The function to be called when the popup is closed. |
+| Prop           | Type                                          | Default       | Description               |
+| -------------- | --------------------------------------------- | ------------- | ------------------------- |
+| `type`         | `"info" \| "warning" \| "success" \| "error"` | `"info"`      | Alert type                |
+| `variant`      | `"contained" \| "outlined"`                   | `"contained"` | Alert variant             |
+| `title`        | `string`                                      | -             | Alert title               |
+| `body`         | `string`                                      | -             | Alert message             |
+| `gutterBottom` | `number`                                      | `0`           | Bottom margin in pixels   |
+| `style`        | `ViewStyle`                                   | `{}`          | Container style overrides |
+
+**Example:**
+
+```tsx
+<AlertX
+  type="success"
+  title="Success!"
+  body="Your profile has been updated successfully."
+  gutterBottom={20}
+/>
+```
 
-### SafeAreaView
+### Avatar
 
-A component that renders content within the safe area boundaries of the device.
+A component for displaying user avatars with support for images, labels, or default icons.
 
 **Props:**
 
-| Prop     | Type | Default | Description                 |
-| -------- | ---- | ------- | --------------------------- |
-| children | node | -       | The content to be rendered. |
+| Prop      | Type                        | Default       | Description                 |
+| --------- | --------------------------- | ------------- | --------------------------- |
+| `source`  | `ImageSourcePropType`       | -             | Image source                |
+| `label`   | `string`                    | -             | Text label (first letter)   |
+| `size`    | `number`                    | `48`          | Avatar size in pixels       |
+| `color`   | `string`                    | `"dark"`      | Background color from theme |
+| `variant` | `"contained" \| "outlined"` | `"contained"` | Avatar variant              |
+| `style`   | `ViewStyle`                 | `{}`          | Container style overrides   |
+
+**Example:**
+
+```tsx
+<Avatar
+  source={{ uri: 'https://example.com/avatar.jpg' }}
+  size={64}
+/>
+
+<Avatar
+  label="John Doe"
+  color="primary"
+  size={48}
+/>
+```
 
-### Spinner
+### Grid & GridItem
+
+Flexible grid layout components for organizing content.
+
+**Grid Props:**
+
+| Prop       | Type        | Default | Description               |
+| ---------- | ----------- | ------- | ------------------------- |
+| `children` | `ReactNode` | -       | GridItem components       |
+| `spacing`  | `number`    | `1`     | Spacing between items     |
+| `style`    | `ViewStyle` | `{}`    | Container style overrides |
+
+**GridItem Props:**
+
+| Prop         | Type                                     | Default | Description               |
+| ------------ | ---------------------------------------- | ------- | ------------------------- |
+| `children`   | `ReactNode`                              | -       | Item content              |
+| `col`        | `number`                                 | `2`     | Number of columns to span |
+| `alignItems` | `"center" \| "flex-start" \| "flex-end"` | -       | Item alignment            |
+| `spacing`    | `number`                                 | `1`     | Item spacing              |
+| `style`      | `ViewStyle`                              | `{}`    | Item style overrides      |
+
+**Example:**
+
+```tsx
+<Grid spacing={2}>
+  <GridItem col={2}>
+    <Typography>Full width item</Typography>
+  </GridItem>
+  <GridItem col={4} alignItems="center">
+    <Typography>Quarter width item</Typography>
+  </GridItem>
+  <GridItem col={4}>
+    <Typography>Another quarter width</Typography>
+  </GridItem>
+</Grid>
+```
 
-A component for displaying a loading spinner.
+### FormWrapper
+
+A wrapper component that provides keyboard handling and scrolling for forms.
 
 **Props:**
 
-| Prop  | Type   | Default         | Description                                                 |
-| ----- | ------ | --------------- | ----------------------------------------------------------- |
-| size  | string | "small"         | The size of the spinner. Possible values: "small", "large". |
-| color | string | Theme-dependent | The color of the spinner.                                   |
+| Prop                     | Type                            | Default            | Description                 |
+| ------------------------ | ------------------------------- | ------------------ | --------------------------- |
+| `children`               | `ReactNode`                     | -                  | Form content                |
+| `mode`                   | `"scroll" \| "static"`          | `"scroll"`         | Wrapper mode                |
+| `behavior`               | `KeyboardAvoidingView` behavior | Platform-dependent | Keyboard avoidance behavior |
+| `keyboardVerticalOffset` | `number`                        | `10`               | Keyboard offset             |
+| `contentContainerStyle`  | `ViewStyle`                     | `{}`               | ScrollView content style    |
+| `style`                  | `ViewStyle`                     | `{}`               | Container style             |
+| `onScroll`               | `(event) => void`               | -                  | Scroll event handler        |
+
+**Example:**
+
+```tsx
+<FormWrapper mode="scroll" keyboardVerticalOffset={20}>
+  <TextField label="Name" />
+  <TextField label="Email" />
+  <Button title="Submit" />
+</FormWrapper>
+```
 
-### TextField
+### List, ListItem & ListItemText
+
+Components for displaying structured lists of data.
+
+**List Props:**
+
+| Prop       | Type        | Default | Description               |
+| ---------- | ----------- | ------- | ------------------------- |
+| `children` | `ReactNode` | -       | ListItem components       |
+| `style`    | `ViewStyle` | `{}`    | Container style overrides |
+
+**ListItem Props:**
+
+| Prop       | Type         | Default | Description               |
+| ---------- | ------------ | ------- | ------------------------- |
+| `children` | `ReactNode`  | -       | Item content              |
+| `link`     | `boolean`    | `false` | Show arrow indicator      |
+| `divider`  | `boolean`    | `false` | Show bottom border        |
+| `onPress`  | `() => void` | -       | Press handler             |
+| `index`    | `number`     | `1`     | Item index for animations |
+| `style`    | `ViewStyle`  | `{}`    | Item style overrides      |
+
+**ListItemText Props:**
+
+| Prop             | Type              | Default | Description               |
+| ---------------- | ----------------- | ------- | ------------------------- |
+| `primary`        | `string`          | -       | Primary text              |
+| `secondary`      | `string`          | -       | Secondary text            |
+| `divider`        | `boolean`         | `false` | Show bottom border        |
+| `primaryProps`   | `TypographyProps` | `{}`    | Primary text props        |
+| `secondaryProps` | `TypographyProps` | `{}`    | Secondary text props      |
+| `style`          | `ViewStyle`       | `{}`    | Container style overrides |
+
+**Example:**
+
+```tsx
+<List>
+  <ListItem link onPress={() => navigate("Profile")}>
+    <ListItemText primary="Profile Settings" secondary="Manage your account" />
+  </ListItem>
+  <ListItem divider>
+    <ListItemText primary="Notifications" />
+  </ListItem>
+</List>
+```
+
+### Popup
 
-A component for text input.
+A modal component for overlays, dialogs, and bottom sheets.
 
 **Props:**
 
-| Prop        | Type   | Default | Description                         |
-| ----------- | ------ | ------- | ----------------------------------- |
-| label       | string | -       | The label for the text input.       |
-| placeholder | string | -       | The placeholder text for the input. |
+| Prop                     | Type                | Default | Description               |
+| ------------------------ | ------------------- | ------- | ------------------------- |
+| `open`                   | `boolean`           | -       | Whether popup is visible  |
+| `onClose`                | `() => void`        | -       | Close handler             |
+| `title`                  | `string`            | -       | Popup title               |
+| `children`               | `ReactNode`         | -       | Popup content             |
+| `sheet`                  | `boolean \| number` | `false` | Bottom sheet mode/height  |
+| `bare`                   | `boolean`           | `false` | Hide header and padding   |
+| `keyboardVerticalOffset` | `number`            | -       | Keyboard avoidance offset |
+| `style`                  | `ViewStyle`         | `{}`    | Container style overrides |
+
+**Example:**
+
+```tsx
+<Popup
+  open={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Confirm Action"
+  sheet={400}
+>
+  <Typography>Are you sure you want to delete this item?</Typography>
+  <Button title="Delete" color="error" />
+  <Button title="Cancel" variant="outlined" />
+</Popup>
+```
 
-### TextField2
+### Spinner
 
-Another component for text input.
+A loading indicator component with customizable appearance.
 
 **Props:**
 
-| Prop        | Type   | Default | Description                         |
-| ----------- | ------ | ------- | ----------------------------------- |
-| label       | string | -       | The label for the text input.       |
-| placeholder | string | -       | The placeholder text for the input. |
+| Prop         | Type                 | Default     | Description               |
+| ------------ | -------------------- | ----------- | ------------------------- |
+| `size`       | `"small" \| "large"` | `"large"`   | Spinner size              |
+| `color`      | `string`             | `"primary"` | Spinner color from theme  |
+| `label`      | `string`             | -           | Loading text              |
+| `fullscreen` | `boolean`            | `false`     | Cover entire screen       |
+| `style`      | `ViewStyle`          | `{}`        | Container style overrides |
 
-### Typography
+**Example:**
+
+```tsx
+<Spinner size="large" color="primary" label="Loading..." fullscreen={true} />
+```
+
+### Animator
+
+A unified component that provides a single interface for all animation types with generic props.
+
+**Features:**
+
+- **Single Component**: One component handles all animation types
+- **Generic Props**: Consistent prop naming across all animations (e.g., `closeAfter` instead of animation-specific names)
+- **Modular Hooks**: Animation logic is separated into individual custom hooks
+- **Type Safety**: Full TypeScript support with proper typing
+- **Performance**: Only the specified animation runs, others are not loaded
+
+**Generic Props:**
+
+All animation types support these generic props:
+
+| Prop         | Type                                                                        | Default | Description                                                   |
+| ------------ | --------------------------------------------------------------------------- | ------- | ------------------------------------------------------------- |
+| `type`       | `"fade" \| "grow" \| "slide" \| "blink" \| "float" \| "roll" \| "thrownup"` | -       | Animation type                                                |
+| `duration`   | `number`                                                                    | `500`   | Animation duration in milliseconds                            |
+| `delay`      | `number`                                                                    | `0`     | Delay before animation starts                                 |
+| `closeAfter` | `number \| null`                                                            | `null`  | Time after which the exit animation starts (null for no exit) |
+| `style`      | `ViewStyle`                                                                 | `{}`    | Additional styles for the animated view                       |
+
+**Animation-Specific Props:**
+
+**Slide Animation:**
+
+- `direction`: `"up" \| "down" \| "left" \| "right"`
+- `initialValue`: Custom initial position value
+
+**Grow Animation:**
+
+- `initialScale`: Starting scale (default: 0)
+
+**Blink Animation:**
+
+- `blinkDuration`: Duration of one blink cycle
+- `minOpacity`: Minimum opacity value
+- `maxOpacity`: Maximum opacity value
+
+**Float Animation:**
+
+- `closeDuration`: Duration of exit animation
+- `floatDistance`: Distance to float up/down
+- `floatDuration`: Duration of one float cycle
+
+**Roll Animation:**
+
+- `initialTranslateY`: Initial vertical position
+- `initialRotate`: Initial rotation value
+
+**Examples:**
+
+```tsx
+// Fade animation
+<Animator type="fade" duration={1000} closeAfter={3000}>
+  <Text>This will fade in and out</Text>
+</Animator>
+
+// Slide animation
+<Animator type="slide" direction="up" duration={800} closeAfter={2000}>
+  <View>This will slide up from bottom</View>
+</Animator>
+
+// Grow animation
+<Animator type="grow" initialScale={0.5} duration={600}>
+  <Button>This will grow from 50% scale</Button>
+</Animator>
+
+// Blink animation (continuous)
+<Animator type="blink" blinkDuration={1000} minOpacity={0.3}>
+  <Icon>This will blink continuously</Icon>
+</Animator>
 
-A component for displaying text with different styles.
+// Float animation
+<Animator type="float" floatDistance={20} floatDuration={2000} closeAfter={5000}>
+  <View>This will float up and down</View>
+</Animator>
+
+// Roll animation
+<Animator type="roll" initialRotate="45deg" duration={800}>
+  <Image>This will roll and rotate</Image>
+</Animator>
+
+// Thrown up animation
+<Animator type="thrownup" delay={500} closeAfter={4000}>
+  <Notification>This will spring up from bottom</Notification>
+</Animator>
+```
+
+**Available Animation Types:**
+
+1. **fade**: Simple fade in/out
+2. **grow**: Scale-based growth animation
+3. **slide**: Directional slide animations
+4. **blink**: Continuous opacity blinking
+5. **float**: Floating up/down motion with fade
+6. **roll**: Combined rotation and translation
+7. **thrownup**: Spring-based upward animation
+
+**Using Animation Hooks Directly:**
+
+You can also use the animation hooks directly for custom implementations:
+
+```tsx
+import { useFadeAnimation, useSlideAnimation } from "@hoddy-ui/core";
+
+const MyComponent = () => {
+  const { animatedStyle } = useFadeAnimation({
+    duration: 800,
+    closeAfter: 2000,
+  });
+
+  return (
+    <Animated.View style={animatedStyle}>
+      <Text>Custom animated content</Text>
+    </Animated.View>
+  );
+};
+```
+
+**Migration from Old Components:**
+
+Replace old individual animation components:
+
+```tsx
+// Old way
+<AnimatedFade fadeOutAfter={2000}>
+  <Text>Content</Text>
+</AnimatedFade>
+
+// New way
+<Animator type="fade" closeAfter={2000}>
+  <Text>Content</Text>
+</Animator>
+```
+
+### FlashMessage
+
+Display toast notifications and alerts.
 
 **Props:**
 
-| Prop     | Type   | Default | Description                                                                                          |
-| -------- | ------ | ------- | ---------------------------------------------------------------------------------------------------- |
-| variant  | string | "body"  | The style variant of the text. Possible values: "heading", "title", "subheading", "body", "caption". |
-| children | node   | -       | The text content to be rendered.                                                                     |
+| Prop       | Type                                          | Default  | Description            |
+| ---------- | --------------------------------------------- | -------- | ---------------------- |
+| `message`  | `string`                                      | -        | Message text           |
+| `type`     | `"success" \| "error" \| "warning" \| "info"` | `"info"` | Message type           |
+| `duration` | `number`                                      | `3000`   | Display duration in ms |
+| `position` | `"top" \| "bottom"`                           | `"top"`  | Message position       |
+
+**Usage:**
+
+```tsx
+import { showMessage } from "@hoddy-ui/core";
+
+// Show a success message
+showMessage({
+  message: "Profile updated successfully!",
+  type: "success",
+});
+```
+
+## 🔧 Hooks
+
+### useColors
+
+Access the current theme's color palette:
+
+```tsx
+import { useColors } from "@hoddy-ui/core";
+
+function MyComponent() {
+  const colors = useColors();
+
+  return (
+    <View style={{ backgroundColor: colors.primary.main }}>
+      {/* Component content */}
+    </View>
+  );
+}
+```
+
+### useTheme
+
+Access and control the current theme:
+
+```tsx
+import { useTheme } from "@hoddy-ui/core";
+
+function ThemeAwareComponent() {
+  const { themeState, themeDispatch } = useTheme();
+
+  const toggleTheme = () => {
+    themeDispatch({
+      type: themeState.mode === "dark" ? "light" : "dark",
+    });
+  };
+
+  return <Button title="Toggle Theme" onPress={toggleTheme} />;
+}
+```
+
+### useNavScreenOptions
+
+Get theme-aware navigation screen options:
+
+```tsx
+import { useNavScreenOptions } from "@hoddy-ui/core";
+
+function MyScreen() {
+  const screenOptions = useNavScreenOptions("stack");
+
+  // Use with React Navigation
+  return (
+    <Stack.Screen name="Home" component={HomeScreen} options={screenOptions} />
+  );
+}
+```
+
+### Animation Hooks
+
+Access animation logic directly for custom implementations:
+
+#### useFadeAnimation
+
+```tsx
+import { useFadeAnimation } from "@hoddy-ui/core";
+
+function FadeComponent() {
+  const { animatedStyle } = useFadeAnimation({
+    duration: 800,
+    closeAfter: 2000,
+  });
+
+  return (
+    <Animated.View style={animatedStyle}>
+      <Text>This will fade in and out</Text>
+    </Animated.View>
+  );
+}
+```
+
+#### useSlideAnimation
+
+```tsx
+import { useSlideAnimation } from "@hoddy-ui/core";
+
+function SlideComponent() {
+  const { animatedStyle } = useSlideAnimation({
+    direction: "up",
+    duration: 600,
+    initialValue: 100,
+  });
+
+  return (
+    <Animated.View style={animatedStyle}>
+      <Text>This will slide up</Text>
+    </Animated.View>
+  );
+}
+```
+
+#### useGrowAnimation
+
+```tsx
+import { useGrowAnimation } from "@hoddy-ui/core";
+
+function GrowComponent() {
+  const { animatedStyle } = useGrowAnimation({
+    duration: 500,
+    initialScale: 0.5,
+  });
+
+  return (
+    <Animated.View style={animatedStyle}>
+      <Text>This will grow from 50% scale</Text>
+    </Animated.View>
+  );
+}
+```
+
+#### Other Animation Hooks
+
+- `useBlinkAnimation` - For continuous blinking effects
+- `useFloatAnimation` - For floating up/down motion
+- `useRollAnimation` - For rotation and translation effects
+- `useThrownUpAnimation` - For spring-based upward animations
+
+All animation hooks accept similar configuration objects with properties like `duration`, `delay`, and animation-specific options.
+
+## 🎯 Advanced Usage
+
+### Custom Theme Provider
+
+Create your own theme provider with custom configurations:
+
+```tsx
+import { UIThemeProvider, initialize } from "@hoddy-ui/core";
+
+// Initialize with custom configuration
+initialize({
+  fontFamily: "CustomFont-Regular",
+  colors: {
+    primary: { main: "#FF6B6B" },
+    secondary: { main: "#4ECDC4" },
+  },
+});
+
+function App() {
+  return (
+    <UIThemeProvider>
+      <YourAppContent />
+    </UIThemeProvider>
+  );
+}
+```
+
+### Form Validation Example
+
+```tsx
+import React, { useState } from "react";
+import { View } from "react-native";
+import { TextField, Button, FormWrapper } from "@hoddy-ui/core";
+
+function LoginForm() {
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [errors, setErrors] = useState({});
+
+  const validate = () => {
+    const newErrors = {};
+    if (!email) newErrors.email = "Email is required";
+    if (!password) newErrors.password = "Password is required";
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  };
+
+  const handleSubmit = () => {
+    if (validate()) {
+      // Handle form submission
+    }
+  };
+
+  return (
+    <FormWrapper>
+      <TextField
+        label="Email"
+        value={email}
+        onChangeText={setEmail}
+        error={!!errors.email}
+        helperText={errors.email}
+        keyboardType="email-address"
+      />
+
+      <TextField
+        label="Password"
+        value={password}
+        onChangeText={setPassword}
+        error={!!errors.password}
+        helperText={errors.password}
+        secureTextEntry
+      />
+
+      <Button
+        title="Login"
+        onPress={handleSubmit}
+        variant="contained"
+        color="primary"
+      />
+    </FormWrapper>
+  );
+}
+```
+
+## 📱 Platform Compatibility
+
+- **React Native**: ≥ 0.71.8
+- **Expo**: SDK 48+
+- **iOS**: 11.0+
+- **Android**: API 21+ (Android 5.0)
+- **TypeScript**: ≥ 5.0.4
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## 📄 License
+
+MIT © [Hoddy Inc](https://github.com/kinghoddy)
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/kinghoddy/hoddy-ui)
+- [npm Package](https://www.npmjs.com/package/@hoddy-ui/core)
+- [Issues & Support](https://github.com/kinghoddy/hoddy-ui/issues)
+
+---
+
+**Need help?** [Open an issue](https://github.com/kinghoddy/hoddy-ui/issues) or check out our [examples](../../test/hoddyui).