@scalably/ui 0.2.0 → 0.2.1

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
 

package/dist/index.d.cts

@@ -3,7 +3,6 @@ import { ReactNode } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ClassValue } from 'clsx';
 import * as date_fns from 'date-fns';
 export { addMonths, endOfMonth, isSameDay, startOfMonth } from 'date-fns';
 
@@ -142,7 +141,7 @@ interface StatusBadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "
 declare const StatusBadge: react.ForwardRefExoticComponent<StatusBadgeProps & react.RefAttributes<HTMLSpanElement>>;
 
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "link" | "text" | "outline" | "destructive" | "secondary" | null | undefined;
+    variant?: "link" | "text" | "outline" | "default" | "destructive" | "secondary" | null | undefined;
     size?: "icon" | "md" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type ButtonVariant = VariantProps<typeof buttonVariants>["variant"];
@@ -750,6 +749,13 @@ interface FileUploadProps {
      * This runs after internal type/size validation.
      */
     onValidateFile?: (file: File) => FileUploadError | null | undefined;
+    /** Enable video thumbnail capture UI via modal when a video file is selected. */
+    enableVideoThumbnail?: boolean;
+    /**
+     * Called when a thumbnail is captured from the selected video's current frame.
+     * Provides the Blob (image/jpeg) and a data URL for immediate preview.
+     */
+    onThumbnailCapture?: (thumbnail: Blob, dataUrl: string, file: FileUploadFile) => void;
 }
 /**
  * File upload component with drag-and-drop, validation, previews, and accessibility support.
@@ -1569,29 +1575,55 @@ declare const ViewToggle: React.FC<ViewToggleProps>;
 
 interface ScalablyUIProviderProps {
     children: React.ReactNode;
+    /**
+     * @deprecated `className` is no longer needed. Styles are applied globally.
+     */
     className?: string;
     /**
-     * When true, merges the scope class onto the single child instead of adding an extra wrapper div.
+     * @deprecated `asChild` is no longer needed. Styles are applied globally.
      */
     asChild?: boolean;
+    /**
+     * When true, automatically injects the component library styles into document.head.
+     * This ensures styles work in portals (modals, tooltips, etc.) without requiring
+     * manual CSS imports. Defaults to true.
+     */
+    injectStyles?: boolean;
 }
 /**
  * ScalablyUIProvider
  *
- * Adds the required `sui-scope` wrapper so prefixed Tailwind styles apply.
+ * Provides the Scalably UI component library context and automatically injects styles.
+ * All classes are globally prefixed (`sui-*`), so no wrapper element is required.
+ *
+ * Features:
+ * - Automatically injects CSS into document.head (prevents double-injection)
+ * - Works with SSR (only injects on client-side)
+ * - Ensures styles are available for portaled components
+ * - Maintains style isolation via 'sui-' prefix
  *
  * Usage:
+ * ```tsx
  * <ScalablyUIProvider>
  *   <App />
  * </ScalablyUIProvider>
+ * ```
  *
- * Or to avoid an extra DOM node:
- * <ScalablyUIProvider asChild>
- *   <main />
+ * To disable automatic style injection (if you import CSS manually):
+ * ```tsx
+ * <ScalablyUIProvider injectStyles={false}>
+ *   <App />
  * </ScalablyUIProvider>
+ * ```
  */
 declare const ScalablyUIProvider: React.FC<ScalablyUIProviderProps>;
 
+/**
+ * Type for class values accepted by clsx
+ */
+type ClassValue = ClassArray | ClassDictionary | string | number | bigint | null | boolean | undefined;
+type ClassDictionary = Record<string, unknown>;
+type ClassArray = ClassValue[];
 /**
  * Utility function to merge Tailwind CSS classes intelligently
  * Combines clsx for conditional classes and tailwind-merge for conflict resolution

package/dist/index.d.ts

@@ -3,7 +3,6 @@ import { ReactNode } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ClassValue } from 'clsx';
 import * as date_fns from 'date-fns';
 export { addMonths, endOfMonth, isSameDay, startOfMonth } from 'date-fns';
 
@@ -142,7 +141,7 @@ interface StatusBadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "
 declare const StatusBadge: react.ForwardRefExoticComponent<StatusBadgeProps & react.RefAttributes<HTMLSpanElement>>;
 
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "link" | "text" | "outline" | "destructive" | "secondary" | null | undefined;
+    variant?: "link" | "text" | "outline" | "default" | "destructive" | "secondary" | null | undefined;
     size?: "icon" | "md" | "lg" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 type ButtonVariant = VariantProps<typeof buttonVariants>["variant"];
@@ -750,6 +749,13 @@ interface FileUploadProps {
      * This runs after internal type/size validation.
      */
     onValidateFile?: (file: File) => FileUploadError | null | undefined;
+    /** Enable video thumbnail capture UI via modal when a video file is selected. */
+    enableVideoThumbnail?: boolean;
+    /**
+     * Called when a thumbnail is captured from the selected video's current frame.
+     * Provides the Blob (image/jpeg) and a data URL for immediate preview.
+     */
+    onThumbnailCapture?: (thumbnail: Blob, dataUrl: string, file: FileUploadFile) => void;
 }
 /**
  * File upload component with drag-and-drop, validation, previews, and accessibility support.
@@ -1569,29 +1575,55 @@ declare const ViewToggle: React.FC<ViewToggleProps>;
 
 interface ScalablyUIProviderProps {
     children: React.ReactNode;
+    /**
+     * @deprecated `className` is no longer needed. Styles are applied globally.
+     */
     className?: string;
     /**
-     * When true, merges the scope class onto the single child instead of adding an extra wrapper div.
+     * @deprecated `asChild` is no longer needed. Styles are applied globally.
      */
     asChild?: boolean;
+    /**
+     * When true, automatically injects the component library styles into document.head.
+     * This ensures styles work in portals (modals, tooltips, etc.) without requiring
+     * manual CSS imports. Defaults to true.
+     */
+    injectStyles?: boolean;
 }
 /**
  * ScalablyUIProvider
  *
- * Adds the required `sui-scope` wrapper so prefixed Tailwind styles apply.
+ * Provides the Scalably UI component library context and automatically injects styles.
+ * All classes are globally prefixed (`sui-*`), so no wrapper element is required.
+ *
+ * Features:
+ * - Automatically injects CSS into document.head (prevents double-injection)
+ * - Works with SSR (only injects on client-side)
+ * - Ensures styles are available for portaled components
+ * - Maintains style isolation via 'sui-' prefix
  *
  * Usage:
+ * ```tsx
  * <ScalablyUIProvider>
  *   <App />
  * </ScalablyUIProvider>
+ * ```
  *
- * Or to avoid an extra DOM node:
- * <ScalablyUIProvider asChild>
- *   <main />
+ * To disable automatic style injection (if you import CSS manually):
+ * ```tsx
+ * <ScalablyUIProvider injectStyles={false}>
+ *   <App />
  * </ScalablyUIProvider>
+ * ```
  */
 declare const ScalablyUIProvider: React.FC<ScalablyUIProviderProps>;
 
+/**
+ * Type for class values accepted by clsx
+ */
+type ClassValue = ClassArray | ClassDictionary | string | number | bigint | null | boolean | undefined;
+type ClassDictionary = Record<string, unknown>;
+type ClassArray = ClassValue[];
 /**
  * Utility function to merge Tailwind CSS classes intelligently
  * Combines clsx for conditional classes and tailwind-merge for conflict resolution