@scalably/ui 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Scalably
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,8 @@
 # Scalably UI Component Library
 
+![npm version](https://img.shields.io/npm/v/@scalably/ui)
+![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.
 
 ## 🚀 Features
@@ -20,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() {
@@ -55,28 +50,40 @@ export default function App() {
 }
 ```
 
-### 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:
@@ -145,13 +152,11 @@ 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>
 
-// ❌ Avoid - mixing prefixed and non-prefixed classes
-<div className="p-4"> {/* This won't conflict */}
-  <Button>Button with ui-* classes</Button>
+// ✅ Your global styles won't break the components
+<div className="p-4 bg-red-500">
+  <Button>Isolated Button</Button>
 </div>
 ```
 
@@ -222,14 +227,14 @@ Visit our Storybook documentation for:
 
 ### Colors
 
-- **Primary**: `#36499B` - Main brand color for primary actions
-- **Secondary**: `#F2F6FC` - Light background colors with multiple levels
-- **Success**: `#22BC4D` - Green for positive actions and success states
-- **Warning**: `#FF7A00` - Orange for caution and in-progress states
-- **Info**: `#2772F0` - Blue for informational content
-- **Error**: `#EA3540` - Red for destructive actions and errors
-- **Inactive**: `#777E90` - Gray for inactive or completed states
-- **Disabled**: `#B2BBC7` - Light gray for disabled elements
+- **Primary**: `#36499B` – Main brand color for primary actions (`sui-bg-primary`, `sui-text-primary`)
+- **Secondary**: `#F2F6FC` – Light background colors (`sui-bg-secondary`, `sui-text-secondary`)
+- **Success**: `#22BC4D` – Positive actions and success states (`sui-bg-success`, `sui-text-success`)
+- **Warning**: `#FF7A00` – Caution and in-progress states (`sui-bg-warning`, `sui-text-warning`)
+- **Info**: `#2772F0` – Informational content (`sui-bg-info`, `sui-text-info`)
+- **Error**: `#EA3540` – Destructive actions and errors (`sui-bg-error`, `sui-text-error`)
+- **Inactive**: `#777E90` – Inactive or completed states (`sui-text-inactive`, `sui-border-inactive`)
+- **Disabled**: `#B2BBC7` – Disabled elements (`sui-text-disabled`, `sui-border-disabled`)
 
 ### Typography
 
@@ -243,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