# @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:

npm install react react-dom clsx tailwind-merge lucide-react

🚀 Quick Start

1. Setup App Meta Provider

// App.tsx
import { AppMetaProvider } from '@tmj/ui';

function App() {
  return (
    <AppMetaProvider>
      <MyPage />
    </AppMetaProvider>
  );
}

2. Use Layout Components

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

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

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

// 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

// 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

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