hazo_ui 2.6.1 → 2.6.3

package/README.md

@@ -65,6 +65,104 @@ Tailwind v4 uses JIT compilation and only generates CSS for classes found in sca
 
 ---
 
+## Color Configuration
+
+hazo_ui provides a centralized configuration system for customizing button and header colors across all components. You can set colors globally using `set_hazo_ui_config()` or override them per-component using props.
+
+### Global Configuration
+
+Set default colors for all components in your app:
+
+```tsx
+import { set_hazo_ui_config } from 'hazo_ui';
+
+// Set custom colors globally (typically in your app's entry point)
+set_hazo_ui_config({
+  // Dialog headers
+  header_background_color: '#1e3a8a',
+  header_text_color: '#ffffff',
+
+  // Submit/Apply buttons
+  submit_button_background_color: '#10b981',
+  submit_button_text_color: '#ffffff',
+
+  // Cancel buttons
+  cancel_button_border_color: '#6b7280',
+  cancel_button_text_color: '#374151',
+
+  // Clear/Delete buttons
+  clear_button_border_color: '#ef4444',
+  clear_button_text_color: '#ef4444',
+});
+```
+
+### Per-Component Override
+
+Override colors for individual component instances using props:
+
+```tsx
+<HazoUiMultiFilterDialog
+  availableFields={fields}
+  onFilterChange={handleFilterChange}
+  // Color overrides (these take precedence over global config)
+  headerBackgroundColor="#7c3aed"
+  headerTextColor="#ffffff"
+  submitButtonBackgroundColor="#f59e0b"
+  submitButtonTextColor="#ffffff"
+  cancelButtonBorderColor="#ec4899"
+  cancelButtonTextColor="#ec4899"
+/>
+```
+
+### Available Color Properties
+
+**HazoUiConfig Interface:**
+```tsx
+interface HazoUiConfig {
+  // Dialog Header Colors
+  header_background_color?: string;
+  header_text_color?: string;
+
+  // Submit/Action Button Colors
+  submit_button_background_color?: string;
+  submit_button_text_color?: string;
+  submit_button_hover_color?: string;
+
+  // Cancel Button Colors
+  cancel_button_background_color?: string;
+  cancel_button_text_color?: string;
+  cancel_button_border_color?: string;
+  cancel_button_hover_color?: string;
+
+  // Clear/Delete Button Colors
+  clear_button_background_color?: string;
+  clear_button_text_color?: string;
+  clear_button_border_color?: string;
+  clear_button_hover_color?: string;
+}
+```
+
+### Configuration Functions
+
+**`set_hazo_ui_config(config: Partial<HazoUiConfig>)`**
+- Merges provided config with existing global config
+- Accepts partial config (you can set only the colors you want to customize)
+
+**`get_hazo_ui_config(): Readonly<HazoUiConfig>`**
+- Returns the current global configuration (read-only)
+
+**`reset_hazo_ui_config()`**
+- Resets all colors to default (undefined, using theme defaults)
+
+### Components Supporting Color Configuration
+
+The following components support both global config and prop-level color overrides:
+- `HazoUiDialog` - via `headerBackgroundColor`, `headerTextColor`, `accentColor` props
+- `HazoUiMultiFilterDialog` - via header/submit/cancel/clear color props
+- `HazoUiMultiSortDialog` - via header/submit/cancel/clear color props
+
+---
+
 ## Components
 
 ### Component Overview
@@ -1707,6 +1805,27 @@ function CustomHeightExample() {
 
 A flexible, standardized dialog component with customizable animations, sizes, and theming. Built on Radix UI Dialog primitives with a consistent header/body/footer layout.
 
+### Two Usage Patterns
+
+HazoUiDialog offers two approaches depending on your needs:
+
+1. **Props-based API (HazoUiDialog)** - For simple confirmations, alerts, and standard forms with predefined header/body/footer layout
+2. **Compositional API (Primitives)** - For complex layouts with custom headers, tabs, avatars, and full layout control
+
+#### When to Use Each Approach
+
+**Use HazoUiDialog (props-based) when:**
+- You need a standard confirmation dialog
+- Your content fits a simple header/body/footer layout
+- You want quick implementation with minimal code
+- Examples: confirmations, alerts, simple forms
+
+**Use Compositional API (primitives) when:**
+- You need custom headers with avatars, icons, or complex layouts
+- Your dialog has tabs or multi-section content
+- You want full control over the dialog structure
+- Examples: client details with tabs, complex forms, custom workflows
+
 #### Features
 
 - **Flexible Sizing**: 5 size presets from small (400px) to full-width (98vw), plus custom sizing
@@ -1759,8 +1878,13 @@ interface HazoUiDialogProps {
   openAnimation?: AnimationPreset | string;  // default: "zoom"
   closeAnimation?: AnimationPreset | string; // default: "zoom"
 
-  // Color Customization
+  // Variant (preset color theme)
+  variant?: DialogVariant;               // default: "default"
+  splitHeader?: boolean;                 // default: true - When true, title/description get separate bg rows; false = single bg, italic description
+
+  // Color Customization (overrides variant preset if both provided)
   headerBackgroundColor?: string;
+  descriptionBackgroundColor?: string;
   headerTextColor?: string;
   bodyBackgroundColor?: string;
   footerBackgroundColor?: string;
@@ -1780,11 +1904,14 @@ interface HazoUiDialogProps {
   showCloseButton?: boolean;           // default: true
 }
 
+type DialogVariant = 'default' | 'info' | 'success' | 'warning' | 'danger';
 type AnimationPreset = 'zoom' | 'slide' | 'fade' | 'bounce' | 'scale-up' | 'flip' | 'slide-left' | 'slide-right' | 'slide-top' | 'none';
 type ButtonVariant = "default" | "destructive" | "outline" | "secondary" | "ghost" | "link";
 ```
 
-#### Basic Usage
+#### Pattern 1: Basic Usage (Props-based API)
+
+For simple dialogs with standard layout:
 
 ```tsx
 import { HazoUiDialog } from 'hazo_ui';
@@ -1819,6 +1946,170 @@ function ConfirmDialog() {
 }
 ```
 
+#### Pattern 2: Compositional API (Complex Layouts)
+
+For dialogs with custom headers, tabs, or complex layouts:
+
+```tsx
+import {
+  HazoUiDialogRoot,
+  HazoUiDialogContent,
+  HazoUiDialogHeader,
+  HazoUiDialogTitle,
+  HazoUiDialogDescription,
+  HazoUiDialogFooter,
+} from 'hazo_ui';
+import { useState } from 'react';
+import { User } from 'lucide-react';
+
+function ClientDetailsDialog() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [activeTab, setActiveTab] = useState('personal');
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>
+        Open Client Details
+      </button>
+
+      <HazoUiDialogRoot open={isOpen} onOpenChange={setIsOpen}>
+        <HazoUiDialogContent className="sm:max-w-2xl w-[90vw] h-[80vh] flex flex-col p-0">
+          {/* Custom Header with Avatar */}
+          <HazoUiDialogHeader className="bg-navbar text-navbar-foreground p-6 rounded-t-lg">
+            <div className="flex items-center gap-3">
+              <div className="w-12 h-12 rounded-full bg-primary/20 flex items-center justify-center">
+                <User className="h-6 w-6 text-primary-foreground" />
+              </div>
+              <div>
+                <HazoUiDialogTitle className="text-white text-left">
+                  John Doe
+                </HazoUiDialogTitle>
+                <HazoUiDialogDescription className="text-white/80 text-left">
+                  john.doe@example.com
+                </HazoUiDialogDescription>
+              </div>
+            </div>
+          </HazoUiDialogHeader>
+
+          {/* Tabs Navigation */}
+          <div className="border-b px-6">
+            <div className="flex gap-4">
+              <button
+                onClick={() => setActiveTab('personal')}
+                className={`py-3 px-1 text-sm font-medium border-b-2 ${
+                  activeTab === 'personal'
+                    ? 'border-primary text-primary'
+                    : 'border-transparent text-muted-foreground'
+                }`}
+              >
+                Personal
+              </button>
+              <button
+                onClick={() => setActiveTab('address')}
+                className={`py-3 px-1 text-sm font-medium border-b-2 ${
+                  activeTab === 'address'
+                    ? 'border-primary text-primary'
+                    : 'border-transparent text-muted-foreground'
+                }`}
+              >
+                Address
+              </button>
+              <button
+                onClick={() => setActiveTab('contact')}
+                className={`py-3 px-1 text-sm font-medium border-b-2 ${
+                  activeTab === 'contact'
+                    ? 'border-primary text-primary'
+                    : 'border-transparent text-muted-foreground'
+                }`}
+              >
+                Contact
+              </button>
+            </div>
+          </div>
+
+          {/* Scrollable Tab Content */}
+          <div className="flex-1 overflow-y-auto p-6">
+            {activeTab === 'personal' && (
+              <div className="space-y-4">
+                <div>
+                  <label className="text-sm font-medium">Full Name</label>
+                  <input
+                    type="text"
+                    className="w-full px-3 py-2 border rounded-md mt-1"
+                  />
+                </div>
+                {/* More personal fields */}
+              </div>
+            )}
+            {activeTab === 'address' && (
+              <div className="space-y-4">
+                {/* Address fields */}
+              </div>
+            )}
+            {activeTab === 'contact' && (
+              <div className="space-y-4">
+                {/* Contact fields */}
+              </div>
+            )}
+          </div>
+
+          {/* Footer */}
+          <HazoUiDialogFooter className="p-6 border-t">
+            <button
+              onClick={() => setIsOpen(false)}
+              className="px-4 py-2 border rounded-md hover:bg-accent"
+            >
+              Cancel
+            </button>
+            <button
+              onClick={() => setIsOpen(false)}
+              className="px-4 py-2 bg-primary text-primary-foreground rounded-md"
+            >
+              Save Changes
+            </button>
+          </HazoUiDialogFooter>
+        </HazoUiDialogContent>
+      </HazoUiDialogRoot>
+    </>
+  );
+}
+```
+
+**Available Compositional Components:**
+
+```tsx
+import {
+  HazoUiDialogRoot,        // Root dialog container (replaces Dialog)
+  HazoUiDialogTrigger,     // Trigger button (optional)
+  HazoUiDialogContent,     // Dialog content wrapper
+  HazoUiDialogHeader,      // Header section
+  HazoUiDialogTitle,       // Title text
+  HazoUiDialogDescription, // Description text
+  HazoUiDialogFooter,      // Footer section
+  HazoUiDialogPortal,      // Portal wrapper
+  HazoUiDialogOverlay,     // Backdrop overlay
+  HazoUiDialogClose,       // Close button
+} from 'hazo_ui';
+```
+
+**Key Differences:**
+
+| Feature | Props-based API | Compositional API |
+|---------|----------------|-------------------|
+| **Layout** | Predefined header/body/footer | Build your own structure |
+| **Configuration** | Via props | Via component composition |
+| **Complexity** | Simple, quick | Flexible, powerful |
+| **Best for** | Confirmations, alerts | Tabs, avatars, custom layouts |
+| **Code** | Minimal | More verbose |
+
+**Compositional API Tips:**
+
+- Use `flex flex-col` on `HazoUiDialogContent` for layouts with headers/footers
+- Set `p-0` on `HazoUiDialogContent` and add padding to individual sections
+- Use `overflow-y-auto` on the scrollable content area
+- Apply `bg-navbar text-navbar-foreground` for dark headers
+- Use `border-t` on footer for visual separation
+
 #### Action Button States and Custom Footers
 
 The dialog supports enhanced action buttons with loading states, icons, and fully custom footers for complex UX scenarios.
@@ -2146,75 +2437,69 @@ function ProgressDialog() {
 />
 ```
 
-#### Themed Dialogs
+#### Themed Dialogs (Variant Prop)
+
+Use the `variant` prop to apply preset color themes with a single prop instead of specifying individual colors. Available variants: `info`, `success`, `warning`, `danger`.
+
+Each variant auto-applies: header background tint, header text color, border color, accent color, tinted overlay, and (for `danger`) destructive button variant.
+
+**Override chain:** Individual prop > Variant preset > Global config. You can use a variant and still override specific colors via props.
 
-**Success Theme**
 ```tsx
-<HazoUiDialog
-  title="✓ Success"
-  description="Operation completed successfully"
-  actionButtonText="Done"
-  showCancelButton={false}
-  borderColor="rgb(34, 197, 94)"
-  headerBackgroundColor="rgb(220, 252, 231)"
-  headerTextColor="rgb(22, 101, 52)"
-  accentColor="rgb(34, 197, 94)"
-  overlayClassName="bg-green-950/50"
-  {...props}
->
+// Success variant
+<HazoUiDialog variant="success" title="✓ Success" actionButtonText="Done" showCancelButton={false} {...props}>
   <p>Your changes have been saved.</p>
 </HazoUiDialog>
-```
 
-**Warning Theme**
-```tsx
-<HazoUiDialog
-  title="⚠ Warning"
-  description="Please review before proceeding"
-  actionButtonText="I Understand"
-  borderColor="rgb(234, 179, 8)"
-  headerBackgroundColor="rgb(254, 249, 195)"
-  headerTextColor="rgb(113, 63, 18)"
-  accentColor="rgb(234, 179, 8)"
-  overlayClassName="bg-yellow-950/50"
-  {...props}
->
+// Warning variant
+<HazoUiDialog variant="warning" title="⚠ Warning" actionButtonText="I Understand" {...props}>
   <p>You have unsaved changes that will be lost.</p>
 </HazoUiDialog>
+
+// Danger variant (auto-sets destructive button)
+<HazoUiDialog variant="danger" title="⛔ Delete" actionButtonText="Delete Permanently" {...props}>
+  <p>All data will be permanently deleted.</p>
+</HazoUiDialog>
+
+// Info variant
+<HazoUiDialog variant="info" title="ℹ Information" actionButtonText="Got It" showCancelButton={false} {...props}>
+  <p>New features are now available.</p>
+</HazoUiDialog>
 ```
 
-**Danger Theme**
+##### Split Header vs Merged Header
+
+By default (`splitHeader={true}`), variant dialogs render the title and description as two separate rows with different background intensities. Set `splitHeader={false}` for a single header background with the description as italic subtext.
+
 ```tsx
-<HazoUiDialog
-  title="⛔ Destructive Action"
-  description="This cannot be undone"
-  actionButtonText="Delete Permanently"
-  actionButtonVariant="destructive"
-  borderColor="rgb(239, 68, 68)"
-  headerBackgroundColor="rgb(254, 226, 226)"
-  headerTextColor="rgb(127, 29, 29)"
-  overlayClassName="bg-red-950/50"
-  {...props}
->
-  <p>All data will be permanently deleted.</p>
+// Split header (default) - two background rows
+<HazoUiDialog variant="info" splitHeader={true} title="Title" description="Description" {...props}>
+  <p>Title row has stronger blue, description row has lighter blue.</p>
+</HazoUiDialog>
+
+// Merged header - single background, italic description
+<HazoUiDialog variant="danger" splitHeader={false} title="Delete" description="This is permanent." {...props}>
+  <p>One red header background with italic description text.</p>
 </HazoUiDialog>
 ```
 
-**Info Theme**
+##### Overriding Variant Colors
+
 ```tsx
+// Use info variant but override header to purple
 <HazoUiDialog
-  title="ℹ Information"
-  description="Learn more about this feature"
-  actionButtonText="Got It"
-  showCancelButton={false}
-  borderColor="rgb(59, 130, 246)"
-  headerBackgroundColor="rgb(219, 234, 254)"
-  headerTextColor="rgb(30, 58, 138)"
-  accentColor="rgb(59, 130, 246)"
-  overlayClassName="bg-blue-950/50"
+  variant="info"
+  headerBackgroundColor="rgb(243, 232, 255)"
+  headerTextColor="rgb(88, 28, 135)"
+  title="Custom Header"
   {...props}
 >
-  <p>New features are now available.</p>
+  <p>Blue border/accent from variant, purple header from props.</p>
+</HazoUiDialog>
+
+// Danger variant with non-destructive button override
+<HazoUiDialog variant="danger" actionButtonVariant="default" title="Acknowledge" {...props}>
+  <p>Red colors from variant, default button from prop override.</p>
 </HazoUiDialog>
 ```