@omnikit-js/ui 0.5.0 → 0.5.2

package/README.md

@@ -1,17 +1,18 @@
 # @omnikit-js/ui
 
-A comprehensive SaaS billing component for Next.js applications with Stripe integration. Built with React Server Components support and a beautiful UI.
+A comprehensive SaaS billing component for Next.js applications with Stripe integration. Built with React Server Components support and Tailwind CSS v4.
 
 ## Features
 
 - 🚀 **Server Components Support** - Optimized for Next.js App Router
 - 💳 **Stripe Integration** - Complete payment processing and subscription management
-- 🎨 **Beautiful UI** - Built with Tailwind CSS and Radix UI
+- 🎨 **Beautiful UI** - Built with Tailwind CSS v4 and Radix UI
 - 📊 **Usage Tracking** - Monitor and display resource usage
 - 🔄 **Subscription Management** - Handle upgrades, downgrades, and cancellations
 - 💰 **Payment Methods** - Add, remove, and manage multiple payment methods
 - 📜 **Billing History** - View and download past invoices
 - 🔐 **Secure** - Server-side API key handling
+- 🎯 **No Style Conflicts** - Prefixed CSS option to avoid conflicts with your app
 
 ## Installation
 
@@ -19,58 +20,100 @@ A comprehensive SaaS billing component for Next.js applications with Stripe inte
 npm install @omnikit-js/ui
 ```
 
-### Simple Setup - No Tailwind Required!
+## Usage
 
-Just import the component's CSS file in your app:
+### Option 1: Standard CSS (For Apps Without Tailwind)
 
-**Option 1: In your `app/globals.css` or main CSS file:**
-```css
-@import '@omnikit-js/ui/styles.css';
-```
+If your app doesn't use Tailwind CSS or you want to use the component's default styles:
+
+```javascript
+// Import the CSS in your app's entry point (e.g., _app.tsx or layout.tsx)
+import '@omnikit-js/ui/dist/styles.css'
+
+// Use the component
+import { Billing } from '@omnikit-js/ui'
 
-**Option 2: In your layout file:**
-```tsx
-import '@omnikit-js/ui/styles.css';
+export default function BillingPage() {
+  return (
+    <Billing 
+      userId="user_123"
+      apiUrl="https://your-api.com"
+      apiKey="your-api-key"
+    />
+  )
+}
 ```
 
-**That's it!** The component includes all necessary styles and works without requiring Tailwind CSS configuration.
+### Option 2: Prefixed CSS (Recommended for Apps With Existing Tailwind)
 
-## Prerequisites
+To avoid conflicts with your app's existing Tailwind styles, use the prefixed version:
 
-1. A Stripe account with API keys
-2. A billing API backend (compatible with the expected endpoints)
-3. Next.js 13+ with App Router
+```javascript
+// Import the prefixed CSS instead
+import '@omnikit-js/ui/dist/styles.prefixed.css'
 
-## Usage
+// Use the component
+import { Billing } from '@omnikit-js/ui'
+
+export default function BillingPage() {
+  return (
+    <Billing 
+      userId="user_123"
+      apiUrl="https://your-api.com"
+      apiKey="your-api-key"
+    />
+  )
+}
+```
 
-### Basic Usage
+**Note:** The prefixed version uses `tw-` prefix for all Tailwind classes internally, preventing conflicts with your app's styles.
 
-```jsx
-import { Billing } from '@omnikit-js/ui';
+### Next.js App Router Example
+
+```javascript
+// app/billing/page.tsx
+import '@omnikit-js/ui/dist/styles.prefixed.css'
+import { Billing } from '@omnikit-js/ui'
 
 export default function BillingPage() {
   return (
-    <div className="max-w-7xl mx-auto p-6">
-      <Billing userId="user-123" />
-    </div>
-  );
+    <main className="container mx-auto p-4">
+      <h1 className="text-2xl font-bold mb-6">Billing & Subscription</h1>
+      <Billing 
+        userId="user_123"
+        apiUrl={process.env.NEXT_PUBLIC_API_URL}
+        apiKey={process.env.API_KEY}
+      />
+    </main>
+  )
 }
 ```
 
-### Advanced Usage with Custom Configuration
+### Next.js Pages Router Example
 
-```jsx
-import { Billing } from '@omnikit-js/ui';
+```javascript
+// pages/_app.tsx
+import '@omnikit-js/ui/dist/styles.prefixed.css'
+import type { AppProps } from 'next/app'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />
+}
+
+// pages/billing.tsx
+import { Billing } from '@omnikit-js/ui'
 
 export default function BillingPage() {
   return (
-    <Billing 
-      userId="user-123"
-      apiUrl="https://api.yourdomain.com"
-      apiKey={process.env.API_KEY}
-      projectId="project-456"
-    />
-  );
+    <div className="container mx-auto p-4">
+      <h1 className="text-2xl font-bold mb-6">Billing & Subscription</h1>
+      <Billing 
+        userId="user_123"
+        apiUrl={process.env.NEXT_PUBLIC_API_URL}
+        apiKey={process.env.API_KEY}
+      />
+    </div>
+  )
 }
 ```
 
@@ -96,6 +139,58 @@ export default function ClientBillingPage({ customerData, pricingData, paymentMe
 }
 ```
 
+## Resolving Style Conflicts
+
+If you experience style conflicts, especially with progress bars or grid layouts:
+
+### Progress Bar Color Conflicts
+
+Override the progress bar styles in your global CSS:
+
+```css
+/* Force specific progress bar colors */
+.omnikit-progress-fill {
+  background-color: #3b82f6 !important;
+}
+
+/* Or for dark mode */
+@media (prefers-color-scheme: dark) {
+  .omnikit-progress-fill {
+    background-color: #60a5fa !important;
+  }
+}
+```
+
+### Grid Layout Conflicts
+
+Wrap the component in a scoped container to isolate styles:
+
+```css
+/* Create an isolation container */
+.billing-wrapper {
+  /* Reset conflicting styles */
+  all: initial;
+  font-family: inherit;
+  color: inherit;
+}
+
+.billing-wrapper * {
+  box-sizing: border-box;
+}
+
+/* Fix specific grid issues */
+.billing-wrapper .omnikit-pricing-grid {
+  display: grid !important;
+  gap: 1rem !important;
+}
+```
+
+```javascript
+<div className="billing-wrapper">
+  <Billing userId="user_123" />
+</div>
+```
+
 ## Component Props
 
 ### Billing (Server Component)
@@ -117,7 +212,7 @@ export default function ClientBillingPage({ customerData, pricingData, paymentMe
 | apiUrl | string | The API base URL |
 | apiKey | string | The API key for authentication |
 
-### Environment Variables
+## Environment Variables
 
 Create a `.env.local` file in your Next.js project:
 
@@ -146,43 +241,44 @@ The component expects the following API endpoints:
 - `POST /billing/payment-methods/:id/default` - Set default payment method
 - `DELETE /billing/payment-methods/:id` - Delete payment method
 
-## Features
+## Troubleshooting
 
-### Subscription Management
-- View current subscription details
-- Upgrade/downgrade plans
-- Cancel subscriptions
-- View billing history
-
-### Payment Methods
-- Add new payment methods with Stripe
-- Set default payment method
-- Remove payment methods
-- Secure card information handling
-
-### Usage Tracking
-- Real-time usage metrics
-- Progress bars for plan limits
-- Usage history and analytics
-
-### Responsive Design
-- Mobile-friendly interface
-- Clean, modern UI
-- Accessible components
-
-## Styling
-
-The component uses Tailwind CSS classes and is designed to work with your existing Tailwind configuration. Make sure your project includes the component's styles by adding this to your `tailwind.config.js`:
-
-```js
-module.exports = {
-  content: [
-    // ... your other content paths
-    "./node_modules/@omnikit-js/ui/**/*.{js,ts,jsx,tsx}",
-  ],
-  // ... rest of your config
-}
-```
+### Common Issues and Solutions
+
+1. **Progress bar showing wrong color**
+   - Use the prefixed CSS version
+   - Override `.omnikit-progress-fill` with `!important`
+
+2. **Grid layout breaking on pricing page**
+   - Check for global grid styles in your app
+   - Use the isolation container approach shown above
+   - Ensure no conflicting CSS Grid properties
+
+3. **Modal z-index conflicts**
+   - Component modals use `z-50` (z-index: 50)
+   - Adjust your app's z-index scale if needed
+
+4. **Font inconsistencies**
+   - The component inherits font-family
+   - Set font on a parent element
+
+5. **Styles not loading**
+   - Ensure you're importing the CSS file
+   - Check the correct path: `@omnikit-js/ui/dist/styles.css` or `@omnikit-js/ui/dist/styles.prefixed.css`
+
+## Version History
+
+- **0.5.1** - Tailwind CSS v4 support with prefix option
+- **0.3.5** - Previous version with Tailwind CSS v3
+
+## Browser Support
+
+Requires modern browsers:
+- Safari 16.4+
+- Chrome 111+
+- Firefox 128+
+
+For older browser support, use version 0.3.5.
 
 ## TypeScript