markora-ui 0.1.0

package/README.md

@@ -0,0 +1,497 @@
+# ✨ Markora UI - Premium React Component Library
+
+A production-ready React and Next.js UI library featuring beautifully crafted components, advanced templates, and a modern design system built with TypeScript, Tailwind CSS, and React.
+
+[![npm version](https://img.shields.io/npm/v/markora-ui.svg)](https://www.npmjs.com/package/markora-ui)
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-18.2%2B%20%7C%2019.0%2B-blue)](https://reactjs.org)
+
+---
+
+## 🎯 Why Markora UI?
+
+- **60+ Professional Components** - Production-ready instead of disconnected snippets
+- **Fully Type-Safe** - Complete TypeScript support with IntelliSense
+- **Accessibility First** - WCAG 2.1 compliant, keyboard navigation built-in
+- **Theme System** - Light & dark mode with customizable design tokens
+- **Zero Runtime** - Tailwind CSS based, styles ship as CSS only
+- **Tree-Shakeable** - Import only what you need, optimize bundle size
+- **Interactive Docs** - Live component showcase with copy-paste code
+- **Built for Teams** - Works seamlessly with React, Next.js, and modern tooling
+
+---
+
+## 📦 Installation
+
+### Prerequisites
+- React 18.2+ or 19.0+
+- Tailwind CSS 3.0+
+- Node.js 16+
+
+### Quick Install
+
+```bash
+npm install markora-ui
+# or
+yarn add markora-ui
+# or
+pnpm add markora-ui
+```
+
+---
+
+## 🚀 Getting Started
+
+### Step 1: Configure Tailwind CSS
+
+If you haven't already, set up Tailwind CSS:
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+### Step 2: Update `tailwind.config.ts`
+
+Include Aether UI in your Tailwind config:
+
+```typescript
+import type { Config } from 'tailwindcss';
+
+export default {
+  content: [
+    './index.html',
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/markora-ui/**/*.{js,mjs,ts,mts}',
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+} satisfies Config;
+```
+
+### Step 3: Import Styles
+
+In your app's entry point:
+
+```typescript
+import 'aether-ui/styles.css';
+```
+
+### Step 4: Start Using Components
+
+```typescript
+import { Button, Card, CardContent, CardHeader, CardTitle } from 'aether-ui';
+
+export default function App() {
+  return (
+    <div className="p-8">
+      <Card>
+        <CardHeader>
+          <CardTitle>Welcome to Markora UI</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <Button variant="primary" size="lg">
+            Get Started
+          </Button>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+```
+
+---
+
+## 📚 Component Library
+
+### Form Components (16)
+- **Input** - Text, email, password inputs with validation
+- **InputField** - Labeled input with helper text and error states
+- **Textarea** - Multi-line text input
+- **TextareaField** - Textarea with labels and validation
+- **Select** - Single and multi-select dropdowns
+- **Combobox** - Searchable select component
+- **Checkbox** - Standalone and groups
+- **Radio** - Radio button groups
+- **FileUpload** - File upload component
+- **Switch** - Toggle switches
+- **DatePicker** - Calendar date selection
+- **InputGroup** - Grouped inputs with addons
+- **NumberInput** - Number input with increment/decrement
+- **InputOTP** - One-time password inputs
+- **NativeSelect** - Native select element
+- **SegmentedControl** - Segmented control component
+
+### Button Components (5)
+- **Button** - Primary, secondary, outline, destructive, ghost variants
+- **IconButton** - Compact button for icons only
+- **ButtonGroup** - Group related buttons
+- **MarkoriButton** - Premium styled button variant
+- **ActionBar** - Toolbar for grouped actions
+
+### Data Display (15)
+- **Table** - Basic data table
+- **DataTable** - Advanced table with sorting/filtering
+- **Card** - Container with header, content, footer
+- **Badge** - Labels and status indicators
+- **Stat** - Metric display with trends
+- **Rating** - Star rating component
+- **Avatar** - User profile pictures
+- **AvatarGroup** - Multiple avatars grouped
+- **Progress** - Progress bars
+- **ProgressCircle** - Circular progress indicator
+- **Timeline** - Event timeline
+- **Pagination** - Page navigation
+- **Divider** - Visual separator
+- **Typography** - Text styles and variants
+- **Chart** - Data visualization (bar, line, area)
+
+### Navigation (8)
+- **Tabs** - Tab navigation
+- **Breadcrumb** - Breadcrumb navigation
+- **Navigation** - Navigation menu
+- **NavigationMenu** - Complex navigation structures
+- **Sidebar** - Collapsible sidebar
+- **Menubar** - Menu bar component
+- **Dock** - Floating dock navigation
+- **TreeView** - Hierarchical tree navigation
+
+### Overlay Components (8)
+- **Dialog** - Modal dialog
+- **Sheet** - Drawer/slide-out dialog
+- **Popover** - Floating popover
+- **Tooltip** - Tooltip with placements
+- **DropdownMenu** - Dropdown menu
+- **ContextMenu** - Right-click context menu
+- **HoverCard** - Hover reveal card
+- **Modal** - Modal dialog variant
+
+### Feedback (6)
+- **Toast** - Toast notifications (via Sonner)
+- **Callout** - Alert callout boxes
+- **Banner** - Top/bottom banners
+- **AlertDialog** - Alert dialogs
+- **Skeleton** - Loading skeleton
+- **Spinner** - Loading spinner
+
+### Special Components (12+)
+- **Accordion** - Collapsible sections
+- **Carousel** - Image carousel
+- **Clipboard** - Copy to clipboard
+- **Collapsible** - Collapsible content
+- **Command** - Command palette
+- **EmptyState** - Empty state UI
+- **Label** - Form labels
+- **Kbd** - Keyboard key display
+- **Marquee** - Scrolling marquee
+- **Separator** - Visual separator
+- **Slider** - Range slider
+- **ScrollArea** - Scrollable container
+
+### Premium Effects (8+)
+- **BorderBeam** - Animated border beam
+- **Meteors** - Meteor rain effect
+- **OrbitingCircles** - Orbiting circles animation
+- **SpotlightCard** - Spotlight hover effect
+- **BackgroundGradient** - Gradient backgrounds
+- **CelestialPulse** - Pulsing celestial effect
+- **GradientText** - Gradient text
+- **HolographicDataDeck** - Holographic data display
+
+### Templates & Layouts (5+)
+- **PricingCard** - Pricing tier cards
+- **FeatureCard** - Feature showcase cards
+- **ProductShowcaseCarousel** - Product showcase
+- **InteractiveOrbNavigation** - Interactive orb nav
+- **SocialPulseWidget** - Social metrics widget
+
+---
+
+## 💡 Usage Examples
+
+### Basic Form
+
+```typescript
+import { InputField, Select, Button } from 'markora-ui';
+import { useState } from 'react';
+
+export default function ContactForm() {
+  const [email, setEmail] = useState('');
+  
+  return (
+    <form className="space-y-4 max-w-md">
+      <InputField
+        label="Email Address"
+        type="email"
+        placeholder="you@example.com"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        hint="We'll never share your email"
+      />
+      <Select
+        label="Subject"
+        options={[
+          { label: 'Support', value: 'support' },
+          { label: 'Sales', value: 'sales' },
+          { label: 'General', value: 'general' },
+        ]}
+      />
+      <Button fullWidth variant="primary">
+        Submit
+      </Button>
+    </form>
+  );
+}
+```
+
+### With Next.js 14+
+
+```typescript
+// app/layout.tsx
+import 'markora-ui/styles.css';
+import { ThemeProvider } from 'markora-ui';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <ThemeProvider>{children}</ThemeProvider>
+      </body>
+    </html>
+  );
+}
+
+// app/page.tsx
+'use client';
+
+import { Button, Card, CardContent, CardHeader, CardTitle } from 'aether-ui';
+
+export default function Page() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Launch faster</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button variant="primary">Ship with Markora UI</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+### Dark Mode
+
+```typescript
+import { ThemeProvider, ThemeToggle, Button } from 'markora-ui';
+
+export default function App() {
+  return (
+    <ThemeProvider defaultTheme="light" storageKey="theme">
+      <div className="p-8">
+        <ThemeToggle />
+        <Button>Hello World</Button>
+      </div>
+    </ThemeProvider>
+  );
+}
+```
+
+### Custom Styling
+
+All components support Tailwind classes:
+
+```typescript
+<Button 
+  variant="primary"
+  className="shadow-lg hover:shadow-xl transition-shadow duration-300"
+>
+  Enhanced Button
+</Button>
+```
+
+---
+
+## 🎨 Theming
+
+### Available Theme Variables
+
+```css
+--background        /* Page background */
+--foreground        /* Text foreground */
+--card              /* Card background */
+--card-foreground   /* Card text */
+--primary           /* Primary accent */
+--primary-foreground
+--secondary         /* Secondary accent */
+--secondary-foreground
+--destructive       /* Danger state */
+--destructive-foreground
+--muted             /* Muted text */
+--muted-foreground
+--accent            /* Accent color */
+--accent-foreground
+--border            /* Border color */
+```
+
+### Light & Dark Mode
+
+The library automatically supports system preferences. Override with:
+
+```typescript
+<ThemeProvider attribute="class" defaultTheme="dark" storageKey="app-theme">
+  {children}
+</ThemeProvider>
+```
+
+---
+
+## 📖 Interactive Docs
+
+Run the development server to explore all components:
+
+```bash
+npm run dev
+```
+
+Navigate to `http://localhost:5173` to see:
+- Live component previews
+- Editable examples
+- Copy-paste code snippets
+- All variants for each component
+
+---
+
+## 🔧 Advanced Usage
+
+### Extending Components
+
+```typescript
+import { Button, type ButtonProps } from 'markora-ui';
+
+interface CustomButtonProps extends ButtonProps {
+  analytics?: string;
+}
+
+export function CustomButton({ analytics, ...props }: CustomButtonProps) {
+  return (
+    <Button 
+      {...props}
+      onClick={(e) => {
+        // Track analytics
+        console.log('Clicked:', analytics);
+        props.onClick?.(e);
+      }}
+    />
+  );
+}
+```
+
+### With CSS Modules
+
+```typescript
+import styles from './page.module.css';
+import { Button } from 'markora-ui';
+
+export default function Page() {
+  return (
+    <Button variant="primary" className={styles.button}>
+      Styled Button
+    </Button>
+  );
+}
+```
+
+---
+
+## 📦 Bundle Size
+
+Minified and tree-shaken:
+
+| Format | Size | Gzipped |
+|--------|------|---------|
+| ESM | ~45KB | ~12KB |
+| CJS | ~48KB | ~13KB |
+| CSS | ~8KB | ~2KB |
+
+<details>
+<summary><strong>Size breakdown by category</strong></summary>
+
+- Form Components: ~8KB
+- Buttons: ~2KB
+- Data Display: ~12KB
+- Navigation: ~6KB
+- Overlays: ~8KB
+- Effects & Templates: ~9KB
+
+</details>
+
+---
+
+## ✅ Browser Support
+
+| Browser | Minimum Version |
+|---------|-----------------|
+| Chrome | Latest |
+| Firefox | Latest |
+| Safari | 13+ |
+| Edge | Latest |
+| iOS Safari | 13+ |
+| Android Chrome | 81+ |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start dev server
+npm run dev
+
+# Build for production
+npm run build
+
+# Run tests
+npm run test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+---
+
+## 📄 License
+
+MIT © 2024 Markora UI
+
+---
+
+## 🙋 Support & Community
+
+- 📖 [Full Documentation](https://markora-ui.dev)
+- 🐛 [Report Issues](https://github.com/yourusername/markora-ui/issues)
+- 💬 [Discussions](https://github.com/yourusername/markora-ui/discussions)
+- 📧 Email: support@markora-ui.dev
+- 🐦 Twitter: [@markora_ui](https://twitter.com/markora_ui)
+
+---
+
+## 🎉 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and breaking changes.
+
+---
+
+**Made with ❤️ by the Markora UI Team**