@tirth_jasoliya/ui 1.0.0

package/README.md

@@ -0,0 +1,240 @@
+```markdown
+# @tirth_jasoliya/ui
+
+> ✨ A complete, type-safe UI component library featuring elegant layouts, data displays, and utility components. Built with TypeScript, Tailwind CSS, and React.
+
+---
+
+## 🌟 Features
+
+- **Layout System**: Pre-built, composable layout components (`AppContainer`, `AppHeader`, `AppContent`, `AppFooter`)
+- **Type Safety**: Fully typed components with intelligent prop completion
+- **Context-Aware**: Built-in app meta management for titles, breadcrumbs, and actions
+- **Utility-First**: Includes helpful utilities like `GeneralHelper` for formatting and UI helpers
+- **Customizable**: Themeable and extensible with Tailwind CSS
+
+---
+
+## 📦 Installation
+
+```bash
+# Using npm
+npm install @tirth_jasoliya/ui
+
+# Using yarn
+yarn add @tirth_jasoliya/ui
+
+# Using pnpm
+pnpm add @tirth_jasoliya/ui
+```
+
+**Peer Dependencies**:
+```bash
+npm install react react-dom clsx tailwind-merge lucide-react
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Setup App Meta Provider
+
+```tsx
+// App.tsx
+import { AppMetaProvider } from '@tmj/ui';
+
+function App() {
+  return (
+    <AppMetaProvider>
+      <MyPage />
+    </AppMetaProvider>
+  );
+}
+```
+
+### 2. Use Layout Components
+
+```tsx
+import {
+  AppContainer,
+  AppHeader,
+  AppContent,
+  AppFooter
+} from '@tmj/ui';
+
+function DashboardPage() {
+  return (
+    <AppContainer>
+      <AppHeader />
+      <AppContent>
+        <h1>Dashboard Content</h1>
+      </AppContent>
+      <AppFooter />
+    </AppContainer>
+  );
+}
+```
+
+### 3. Manage Page Metadata
+
+```tsx
+import { usePageTemplate } from '@tmj/ui/hooks';
+
+function ProductPage() {
+  usePageTemplate({
+    title: 'Product Details',
+    breadcrumbs: [
+      { label: 'Home', href: '/' },
+      { label: 'Products', href: '/products' },
+      { label: 'Current Product' }
+    ],
+    primaryActions: <Button>Edit Product</Button>
+  });
+
+  return <div>...</div>;
+}
+```
+
+---
+
+## 🧩 Core Components
+
+### Layout System
+
+| Component       | Description |
+|-----------------|-------------|
+| `AppContainer`  | Root layout container with spacing and padding controls |
+| `AppHeader`     | Top navigation bar with title, breadcrumbs, and actions |
+| `AppContent`    | Flexible content area with multiple layout modes |
+| `AppFooter`     | Bottom bar with secondary actions and pagination |
+
+### Utility Components
+
+```tsx
+import { GeneralHelper } from '@tmj/ui';
+
+// Format currency
+const price = GeneralHelper.formatINR(1500, { compact: true }); // ₹1.5K
+
+// Status badge
+<GeneralHelper.StatusBadge status="active" variant="outline" />
+
+// Copy to clipboard
+<GeneralHelper.CopyToClipboard text="Copy me!" />
+```
+
+---
+
+## 🛠️ Advanced Usage
+
+### Custom Route Types
+
+```tsx
+// lib/app-meta.ts
+import { createAppMetaContext } from '@tmj/ui/context/app-meta';
+
+type AppRoutes = '/' | '/dashboard' | '/products/:id';
+
+const { AppMetaProvider, useAppMeta } = createAppMetaContext<AppRoutes>();
+
+export { AppMetaProvider, useAppMeta };
+```
+
+### Theming
+
+```tsx
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          DEFAULT: 'var(--color-primary)',
+          light: 'var(--color-primary-light)',
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 📚 API Reference
+
+### AppMeta Context
+
+| Hook/Component | Description |
+|---------------|-------------|
+| `AppMetaProvider` | Provides context for page metadata |
+| `useAppMeta()` | Access and update app metadata |
+| `usePageTemplate()` | Hook to set page metadata |
+
+### GeneralHelper Utilities
+
+| Method | Description |
+|--------|-------------|
+| `formatINR()` | Format numbers as Indian Rupees |
+| `formatDate()` | Date formatting utilities |
+| `toProperCase()` | String case conversion |
+| `StatusBadge` | Configurable status indicator |
+| `CopyToClipboard` | Clipboard copy component |
+
+---
+
+## 🎨 Design Philosophy
+
+1. **Consistent**: Unified design language across components
+2. **Composable**: Mix and match layout components as needed
+3. **Type-Safe**: Full TypeScript support with intelligent hints
+4. **Performant**: Optimized for fast rendering and updates
+5. **Accessible**: Built with WAI-ARIA standards
+
+---
+
+## 🛣️ Roadmap
+
+- [x] Core layout components
+- [x] App meta management system
+- [x] Data table component
+- [x] Data template component
+- [] Form components
+- [x] Dark mode support
+- [] Component playground
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please open an issue to discuss your ideas or submit a PR.
+
+---
+
+## 📄 License
+
+MIT © [Tirth Jasoliya](https://github.com/tirth-jasoliya)
+```
+
+This README features:
+
+1. Clear, visually appealing structure with emoji headers
+2. Complete installation instructions
+3. Quick start guide with code examples
+4. Component API reference
+5. Advanced usage patterns
+6. Design philosophy and roadmap
+7. Consistent with your router package's style
+
+The documentation highlights:
+- The layout system first (your core feature)
+- Type safety as a key benefit
+- Practical examples for common use cases
+- Easy integration instructions
+- Future plans to set expectations
+
+You can further customize it with:
+- Screenshots of components
+- Live demo links
+- More detailed code examples
+- Theming documentation
+- Contribution guidelines