hacktoolkit · YosefAshenafi · Nov 18, 2025
diff --git a/README.md b/README.md
@@ -1,2 +1,128 @@
-# expo-htk
-A set of utilities, services, models, reusable design patterns for Expo (a React Native framework/toolkit).
+# Expo HTK - Hacktoolkit for Expo
+
+Complete utilities, services, components, and reusable design patterns for Expo/React Native applications.
+
+## Quick Overview
+
+Expo HTK is a comprehensive toolkit providing pre-built features, utilities, and components for accelerating Expo/React Native development. Pick and use what you need for your project.
+
+**What's Included:**
+- **Features**: App settings, theme system, device info
+- **Components**: Reusable UI components (dialogs, etc.)
+- **Utilities**: Helper functions (string, enum, observer, react, theme)
+- **State**: Type-safe state management
+- **Storage**: Platform-aware adapters (MMKV, localStorage)
+
+## Quick Start
+
+This is a toolkit meant to be integrated into your Expo project. Copy or reference the modules you need.
+
+```typescript
+// Example: Using App Settings
+import { createAppSettings } from '@htk/features/appSettings';
+
+const { useAppSettings, updateAppSetting } = createAppSettings({
+    darkMode: false,
+    fontSize: 16
+  });
+```
+
+**Full examples and detailed setup instructions are in the documentation below.**
+
+## Documentation
+
+### Features
+- **[App Settings](features/appSettings/README.md)** - Settings management system with UI
+- **[Theme System](features/theme/README.md)** - Light/dark mode with system detection
+- **[Expo Features](features/expo/README.md)** - Device info and Expo integrations
+
+### Components
+- **[Components Overview](components/README.md)** - Reusable UI components
+  - **[Dialog Components](components/Dialogs/README.md)** - Modal dialogs
+    - **[Confirm Dialog](components/Dialogs/Confirm/README.md)** - Confirmation dialogs
+
+### Core Systems
+- **[State Management](states/README.md)** - Jotai-based state with persistence
+- **[Storage Adapters](storages/README.md)** - Platform-aware storage
+  - **[MMKV](storages/mmkv/README.md)** - Fast mobile storage
+  - **[localStorage](storages/localStorage/README.md)** - Web storage
+- **[Type Definitions](types/README.md)** - Shared TypeScript types
+
+### Utilities
+- **[Utilities Overview](utils/README.md)** - Helper functions
+  - **[String Utils](utils/string/README.md)** - Text formatting
+  - **[Enum Utils](utils/enum/README.md)** - Enum helpers
+  - **[Observer Pattern](utils/observer/README.md)** - Event system
+  - **[React Utils](utils/react/README.md)** - Context builder
+  - **[Theme Utils](utils/theme/README.md)** - Styling helpers
+
+## Architecture
+
+```typescript
+expo-htk/
+├── features/         # Complete feature implementations
+├── components/       # Reusable UI components
+├── states/          # State management
+├── storages/        # Storage adapters
+├── types/           # TypeScript definitions
+├── utils/           # Utility functions
+└── README.md        # This file
+```
+
+## Technology Stack
+
+### Core
+- React Native
+- Expo
+- TypeScript
+
+### State & Storage
+- Jotai (state management)
+- react-native-mmkv (mobile storage)
+- localStorage (web storage)
+
+### UI & Styling
+- react-native-ui-lib
+- @react-navigation/native
+
+### Other
+- rollbar-react-native (error tracking)
+- mapbox (geolocation)
+- humanize-plus (number formatting)
+
+## Getting Started
+
+1. **Explore the Documentation** - Browse the feature and utility docs above
+2. **Choose What You Need** - Pick the modules relevant to your app
+3. **Set Up Features** - Initialize and configure using the feature READMEs
+4. **Integrate Components** - Use pre-built UI components in your screens
+5. **Extend as Needed** - Create custom components following the guidelines
+
+## Contributing
+
+When adding new features or components:
+
+1. Follow the established patterns and conventions
+2. Create comprehensive documentation
+3. Include usage examples
+4. Write tests
+5. Ensure TypeScript support
+6. Support theming and customization
+
+See individual module documentation for specific guidelines.
+
+## License
+
+MIT License - Copyright 2024 Hacktoolkit
+
+## Support & Resources
+
+- [Expo Documentation](https://docs.expo.dev)
+- [React Native Docs](https://reactnative.dev)
+- [Jotai](https://jotai.org)
+- [react-native-ui-lib](https://wix.github.io/react-native-ui-lib/)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+
+---
+
+For detailed information about any feature or utility, see the documentation links above.
diff --git a/components/Dialogs/Confirm/README.md b/components/Dialogs/Confirm/README.md
@@ -0,0 +1,177 @@
+# Confirm Dialog Component
+
+## Overview
+The Confirm Dialog is a reusable, context-based dialog component for displaying confirmation messages with customizable button layouts. It provides a flexible system for requesting user confirmation with support for both horizontal and vertical button arrangements.
+
+## Location
+`components/Dialogs/Confirm/`
+
+## Purpose
+This component handles confirmation prompts in the application, allowing developers to:
+- Display modal dialogs with custom messages
+- Configure button labels dynamically
+- Support different button layout strategies (horizontal/vertical)
+- Manage dialog state through React Context
+- Provide consistent UI/UX for confirmation workflows
+
+## Components Included
+
+### Core Files
+
+ File Purpose 
+---------------
+ `index.tsx` Main Confirm component export and API 
+ `context.ts` React Context for managing dialog state 
+ `Root.tsx` Root container that renders the dialog 
+ `Title.tsx` Dialog title component 
+ `HorizontalButtons.tsx` Horizontal button layout variant 
+ `VerticalButtons.tsx` Vertical button layout variant 
+
+## Architecture
+
+### Context-Based State Management
+The component uses React Context to manage:
+- Dialog visibility state
+- Button configuration
+- Dialog title and message
+- Action callbacks
+
+### Component Hierarchy
+```typescript
+Confirm (Provider)
+├── Root (Container)
+│ ├── Title
+│ └── Buttons (Layout Strategy)
+│ ├── HorizontalButtons
+│ └── VerticalButtons
+```
+
+## Usage
+
+### Basic Setup
+```typescript
+import { Confirm } from '@htk/components';
+
+// Wrap your app or screen with the provider
+export function MyApp() {
+  return (
+    <Confirm>
+      <MainScreen />
+    </Confirm>
+  );
+}
+```
+
+### Triggering a Confirmation
+```typescript
+import { useConfirm } from '@htk/components';
+
+export function MyComponent() {
+  const { confirm } = useConfirm();
+
+  const handleDelete = () => {
+    confirm({
+        title: 'Delete Item?',
+        message: 'This action cannot be undone.',
+        buttons: [
+          { label: 'Cancel', onPress: () => {} },
+          { label: 'Delete', onPress: handleConfirmedDelete }
+        ]
+    });
+};
+
+return <Button onPress={handleDelete} />;
+
+}
+```
+
+## Props & API
+
+### Confirm Component
+The root provider component - wraps the application or screen section that needs confirmation dialogs.
+
+```typescript
+interface ConfirmProps {
+  children: ReactNode;
+
+}
+```
+
+### Button Configuration
+```typescript
+interface ConfirmButton {
+  label: string;
+  onPress: () => void;
+  variant?: 'primary' 'secondary' 'destructive';
+
+}
+```
+
+### useConfirm Hook
+```typescript
+const { confirm } = useConfirm();
+
+function confirm(config: {
+    title: string;
+    message: string;
+    buttons: ConfirmButton[];
+    layout?: 'horizontal' 'vertical'; // defaults to horizontal
+  }): void
+```
+
+## Button Layouts
+
+### Horizontal Layout (Default)
+Best for 2-3 buttons on wider screens. Buttons arranged in a row.
+
+```typescript
+buttons: [
+  { label: 'Cancel', onPress: () => {} },
+  { label: 'Confirm', onPress: () => {} }
+]
+// Renders: [Cancel] [Confirm]
+```
+
+### Vertical Layout
+Better for longer button labels or mobile screens. Buttons stacked vertically.
+
+```typescript
+confirm({
+    title: 'Confirm Action',
+    buttons: [...],
+    layout: 'vertical'
+  });
+```
+
+## Styling
+The component uses `react-native-ui-lib` for styling and integrates with the app's theme system. Styles are applied through the theme context and can be customized via the theme configuration.
+
+## Related Components
+- **Dialogs Folder**: [`../README.md`](../README.md) - Other dialog types and patterns
+- **Components**: [`../../README.md`](../../README.md) - Component development guidelines
+
+## Key Features
+- Context-based state management (no prop drilling)
+- Flexible button configurations
+- Multiple layout strategies
+- Theme-aware styling
+- TypeScript support with full type safety
+- Accessible dialog implementation
+
+## Common Use Cases
+1. **Delete Confirmations** - Confirm before removing items
+2. **Action Warnings** - Warn users about irreversible actions
+3. **Data Loss Prevention** - Ask before discarding changes
+4. **Destructive Operations** - Confirm critical operations
+
+## Best Practices
+- Keep titles concise and action-focused
+- Use clear, actionable button labels
+- Consider the user's context when deciding layout
+- Always provide a way to cancel the action
+- Use appropriate button variants for the action severity
+
+## Notes
+- The Confirm component should be placed high in the component tree to wrap all sections that might trigger confirmations
+- Multiple `Confirm` providers can be used for different dialog systems if needed
+- Button callbacks handle the actual action logic and dialog dismissal