@scalably/ui 0.2.0 → 0.2.2

package/README.md

@@ -1,7 +1,6 @@
 # Scalably UI Component Library
 
 ![npm version](https://img.shields.io/npm/v/@scalably/ui)
-![build status](https://github.com/quangnle/scalably-components/actions/workflows/pr-checks.yml/badge.svg?branch=main)
 ![license](https://img.shields.io/npm/l/@scalably/ui)
 
 A modern, accessible, and fully isolated React component library built with TypeScript and Tailwind CSS. Designed to work seamlessly across multiple projects without style conflicts.
@@ -24,19 +23,11 @@ npm install @scalably/ui
 
 ## 🎨 Usage
 
-### 1. Import the CSS
+### 1. Use Components (Styles Auto-Injected)
 
-Add the component library styles to your main entry point:
+The `ScalablyUIProvider` automatically injects styles into `document.head`, so you don't need to manually import CSS. This ensures styles work correctly in portals (modals, tooltips, etc.). No wrapper or scope class is required—just wrap your app once.
 
 ```tsx
-// In your main.tsx, App.tsx, or index.tsx
-import "@scalably/ui/styles";
-```
-
-### 2. Use Components
-
-```tsx
-import "@scalably/ui/styles";
 import { ScalablyUIProvider, Form, FormField, Input, Button, ToastContainer, Toast } from "@scalably/ui";
 
 export default function App() {
@@ -59,30 +50,40 @@ export default function App() {
 }
 ```
 
-Note: Toasts in this library are intentionally declarative. Render a `Toast` inside a `ToastContainer` when you want it visible (e.g., based on component state). This avoids hidden globals and keeps UI state predictable. If you prefer an imperative API, you can wrap your own tiny helper around local state to toggle a `Toast` component.
-
-### 3. Add the provider once (recommended)
+### 2. Optional: Manual CSS Import
 
-Instead of adding the `sui-scope` class manually, wrap your app with the provider:
+If you prefer to import CSS manually (e.g., for better control or SSR optimization), you can disable automatic injection:
 
 ```tsx
+// In your main.tsx, App.tsx, or index.tsx
 import "@scalably/ui/styles";
 import { ScalablyUIProvider } from "@scalably/ui";
 
 export default function App() {
-  return <ScalablyUIProvider>{/* your app */}</ScalablyUIProvider>;
+  return (
+    <ScalablyUIProvider injectStyles={false}>
+      {/* your app */}
+    </ScalablyUIProvider>
+  );
 }
 ```
 
-Optional no extra DOM element:
+### 3. Portal Support
+
+Styles automatically work in portaled components (modals, tooltips, popovers, etc.) because:
+- Styles are injected globally into `document.head`
+- CSS variables propagate to all elements
+- No parent selector dependencies
 
 ```tsx
-<ScalablyUIProvider asChild>
-  <main>{/* your app */}</main>
-  {/* merges the scope onto <main> */}
-</ScalablyUIProvider>
+// Tooltips, modals, and other portaled components work automatically
+<Tooltip content="This works in portals!" portal>
+  <Button>Hover me</Button>
+</Tooltip>
 ```
 
+Note: Toasts in this library are intentionally declarative. Render a `Toast` inside a `ToastContainer` when you want it visible (e.g., based on component state). This avoids hidden globals and keeps UI state predictable. If you prefer an imperative API, you can wrap your own tiny helper around local state to toggle a `Toast` component.
+
 ### 4. React import guidance
 
 If you reference the React namespace (e.g., `React.useState`, `React.forwardRef`, `React.SVGProps`) add an explicit import to avoid UMD global errors:
@@ -151,12 +152,10 @@ All components use prefixed Tailwind classes (`sui-*`) to ensure complete style
 
 ```tsx
 // ✅ Correct - components are properly isolated
-<div className="sui-scope">
-  <Button>Isolated Button</Button>
-</div>
+<Button>Isolated Button</Button>
 
 // ✅ Your global styles won't break the components
-<div className="p-4 bg-red-500"> {/* These global classes won't affect the button's styles */}
+<div className="p-4 bg-red-500">
   <Button>Isolated Button</Button>
 </div>
 ```
@@ -249,10 +248,12 @@ Visit our Storybook documentation for:
 
 The library uses a custom Tailwind configuration with:
 
-- **Prefix**: `sui-` for all utility classes
-- **Important**: `.sui-scope` for style isolation
+- **Prefix**: `sui-` for all utility classes (provides style isolation)
+- **Global Styles**: Automatically injected via `ScalablyUIProvider`
+- **CSS Variables**: Design tokens available globally for theming
 - **Custom Colors**: Brand-specific color palette
 - **Custom Shadows**: Soft, medium, and strong shadow variants
+- **Portal Support**: Styles work in portaled components (modals, tooltips, etc.)
 
 ### Build Configuration