@idealyst/components 1.0.41 → 1.0.44

package/CLAUDE.md

@@ -5,7 +5,7 @@ This file provides comprehensive component documentation for LLMs working with t
 ## Library Overview
 
 @idealyst/components is a cross-platform React/React Native component library with:
-- 11 core components organized into 5 categories
+- 13 core components organized into 6 categories
 - Theme-based styling with Unistyles
 - Intent-based color system (primary, neutral, success, error, warning)
 - Cross-platform compatibility (React & React Native)
@@ -34,6 +34,10 @@ This file provides comprehensive component documentation for LLMs working with t
 ### Utility Components
 - **Icon**: Icon display (`name`, `size`, `color`, `intent`)
 
+### Overlay Components
+- **Dialog**: Modal dialog (`open`, `onOpenChange`, `title`, `size="small|medium|large"`, `variant="default"`, `showCloseButton`, `closeOnBackdropClick`, `closeOnEscapeKey`)
+- **Popover**: Contextual overlay (`open`, `onOpenChange`, `anchor`, `placement="top|bottom|left|right"`, `offset`, `closeOnClickOutside`, `closeOnEscapeKey`, `showArrow`)
+
 ## Intent System
 
 All components use a consistent intent-based color system:
@@ -73,6 +77,54 @@ All components use a consistent intent-based color system:
 </Card>
 ```
 
+### Dialog Usage
+```tsx
+const [dialogOpen, setDialogOpen] = useState(false);
+
+<Dialog
+  open={dialogOpen}
+  onOpenChange={setDialogOpen}
+  title="Confirm Action"
+  size="medium"
+>
+  <View spacing="md">
+    <Text>Are you sure you want to proceed?</Text>
+    <View style={{ flexDirection: 'row', gap: 8 }}>
+      <Button variant="outlined" onPress={() => setDialogOpen(false)}>
+        Cancel
+      </Button>
+      <Button variant="contained" intent="primary" onPress={handleConfirm}>
+        Confirm
+      </Button>
+    </View>
+  </View>
+</Dialog>
+```
+
+### Popover Usage
+```tsx
+const [popoverOpen, setPopoverOpen] = useState(false);
+const buttonRef = useRef<HTMLDivElement>(null);
+
+<div ref={buttonRef} style={{ display: 'inline-block' }}>
+  <Button onPress={() => setPopoverOpen(true)}>
+    Show Menu
+  </Button>
+</div>
+<Popover
+  open={popoverOpen}
+  onOpenChange={setPopoverOpen}
+  anchor={buttonRef}
+  placement="bottom-start"
+  showArrow
+>
+  <View spacing="sm">
+    <Button variant="text" onPress={handleAction}>Action 1</Button>
+    <Button variant="text" onPress={handleAction}>Action 2</Button>
+  </View>
+</Popover>
+```
+
 ## Styling Guidelines
 
 1. **Use variants over manual styles** - Components provide semantic variants
@@ -85,13 +137,13 @@ All components use a consistent intent-based color system:
 
 ```tsx
 // Individual imports (recommended)
-import { Button, Text, View } from '@idealyst/components';
+import { Button, Text, View, Dialog, Popover } from '@idealyst/components';
 
 // Documentation access
 import { componentDocs, getComponentDocs } from '@idealyst/components/docs';
 
 // Examples
-import { ButtonExamples } from '@idealyst/components/examples';
+import { ButtonExamples, DialogExamples, PopoverExamples } from '@idealyst/components/examples';
 ```
 
 ## Key Props Reference
@@ -144,9 +196,11 @@ src/Badge/README.md
 src/Button/README.md
 src/Card/README.md
 src/Checkbox/README.md
+src/Dialog/README.md
 src/Divider/README.md
 src/Icon/README.md
 src/Input/README.md
+src/Popover/README.md
 src/Screen/README.md
 src/Text/README.md
 src/View/README.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/components",
-  "version": "1.0.41",
+  "version": "1.0.44",
   "description": "Shared component library for React and React Native",
   "documentation": "https://github.com/your-username/idealyst-framework/tree/main/packages/components#readme",
   "main": "src/index.ts",
@@ -40,7 +40,7 @@
     "publish:npm": "npm publish"
   },
   "peerDependencies": {
-    "@idealyst/theme": "^1.0.41",
+    "@idealyst/theme": "^1.0.44",
     "@mdi/js": "^7.4.47",
     "@mdi/react": "^1.6.1",
     "@react-native-vector-icons/common": "^12.0.1",

package/src/Dialog/Dialog.native.tsx

@@ -0,0 +1,91 @@
+import React, { useEffect } from 'react';
+import { Modal, View, Text, TouchableOpacity, TouchableWithoutFeedback, BackHandler } from 'react-native';
+import { DialogProps } from './types';
+import { dialogStyles } from './Dialog.styles';
+
+const Dialog: React.FC<DialogProps> = ({
+  open,
+  onOpenChange,
+  title,
+  children,
+  size = 'medium',
+  variant = 'default',
+  showCloseButton = true,
+  closeOnBackdropClick = true,
+  animationType = 'fade',
+  style,
+  testID,
+}) => {
+  // Handle Android back button
+  useEffect(() => {
+    if (!open) return;
+
+    const handleBackPress = () => {
+      onOpenChange(false);
+      return true; // Prevent default back behavior
+    };
+
+    const backHandler = BackHandler.addEventListener('hardwareBackPress', handleBackPress);
+    return () => backHandler.remove();
+  }, [open, onOpenChange]);
+
+  const handleBackdropPress = () => {
+    if (closeOnBackdropClick) {
+      onOpenChange(false);
+    }
+  };
+
+  const handleClosePress = () => {
+    onOpenChange(false);
+  };
+
+  // Apply variants
+  dialogStyles.useVariants({
+    size,
+    variant,
+  });
+
+  return (
+    <Modal
+      visible={open}
+      transparent
+      animationType={animationType}
+      onRequestClose={() => onOpenChange(false)}
+      statusBarTranslucent
+      testID={testID}
+    >
+      <TouchableWithoutFeedback onPress={handleBackdropPress}>
+        <View style={dialogStyles.backdrop}>
+          <TouchableWithoutFeedback onPress={(e) => e.stopPropagation()}>
+            <View style={[dialogStyles.container, style]}>
+              {(title || showCloseButton) && (
+                <View style={dialogStyles.header}>
+                  {title && (
+                    <Text style={dialogStyles.title}>
+                      {title}
+                    </Text>
+                  )}
+                  {showCloseButton && (
+                    <TouchableOpacity
+                      style={dialogStyles.closeButton}
+                      onPress={handleClosePress}
+                      accessibilityLabel="Close dialog"
+                      accessibilityRole="button"
+                    >
+                      <Text style={dialogStyles.closeButtonText}>×</Text>
+                    </TouchableOpacity>
+                  )}
+                </View>
+              )}
+              <View style={dialogStyles.content}>
+                {children}
+              </View>
+            </View>
+          </TouchableWithoutFeedback>
+        </View>
+      </TouchableWithoutFeedback>
+    </Modal>
+  );
+};
+
+export default Dialog;

package/src/Dialog/Dialog.styles.tsx

@@ -0,0 +1,148 @@
+import { StyleSheet } from 'react-native-unistyles';
+
+export const dialogStyles = StyleSheet.create((theme) => ({
+  backdrop: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: 'rgba(0, 0, 0, 0.5)',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    zIndex: 1000,
+    
+    // Web-specific styles
+    _web: {
+      position: 'fixed',
+      transition: 'opacity 150ms ease-out',
+    },
+  },
+  
+  container: {
+    backgroundColor: theme.colors?.background?.primary || '#ffffff',
+    borderRadius: theme.borderRadius?.lg || 12,
+    shadowColor: '#000',
+    shadowOffset: {
+      width: 0,
+      height: 10,
+    },
+    shadowOpacity: 0.25,
+    shadowRadius: 20,
+    elevation: 10,
+    maxHeight: '90%',
+    
+    variants: {
+      size: {
+        small: {
+          width: '90%',
+          maxWidth: 400,
+        },
+        medium: {
+          width: '90%',
+          maxWidth: 600,
+        },
+        large: {
+          width: '90%',
+          maxWidth: 800,
+        },
+        fullscreen: {
+          width: '100%',
+          height: '100%',
+          borderRadius: 0,
+          maxHeight: '100%',
+        },
+      },
+      variant: {
+        default: {},
+        alert: {
+          borderTopWidth: 4,
+          borderTopColor: theme.colors?.border?.primary || '#e5e7eb',
+        },
+        confirmation: {
+          borderTopWidth: 4,
+          borderTopColor: theme.colors?.border?.primary || '#e5e7eb',
+        },
+      },
+    },
+    
+    // Web-specific styles
+    _web: {
+      position: 'relative',
+      display: 'flex',
+      flexDirection: 'column',
+      overflow: 'auto',
+      boxShadow: '0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)',
+      transition: 'opacity 150ms ease-out, transform 150ms ease-out',
+      transformOrigin: 'center center',
+    },
+  },
+  
+  header: {
+    borderBottomWidth: 1,
+    borderBottomColor: theme.colors?.border?.primary || '#e5e7eb',
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    
+    _web: {
+      borderBottomStyle: 'solid',
+    },
+  },
+  
+  title: {
+    marginLeft: theme.spacing?.lg || 12,
+    fontSize: 18,
+    paddingVertical: theme.spacing.md,
+    fontWeight: '600',
+    color: theme.colors?.text?.primary || '#111827',
+    flex: 1,
+
+    _web: {
+      paddingVertical: theme.spacing.xs,
+    }
+  },
+  
+  closeButton: {
+    width: 32,
+    height: 32,
+    marginRight: theme.spacing?.md || 12,
+    borderRadius: 16,
+    backgroundColor: 'transparent',
+    border: 'none',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    cursor: 'pointer',
+    
+    _web: {
+      _hover: {
+        backgroundColor: theme.colors?.background?.secondary || '#f3f4f6',
+      },
+    },
+  },
+  
+  closeButtonText: {
+    fontSize: 18,
+    color: theme.colors?.text?.secondary || '#6b7280',
+    fontWeight: '500',
+  },
+  
+  content: {
+    padding: theme.spacing?.lg || 16,
+    
+    _web: {
+      overflow: 'visible',
+      maxHeight: 'none',
+    },
+  },
+  
+  // Native-specific modal styles
+  modal: {
+    margin: 0,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+}));

package/src/Dialog/Dialog.web.tsx

@@ -0,0 +1,170 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { getWebProps } from 'react-native-unistyles/web';
+import { DialogProps } from './types';
+import { dialogStyles } from './Dialog.styles';
+import Icon from '../Icon';
+
+
+const Dialog: React.FC<DialogProps> = ({
+  open,
+  onOpenChange,
+  title,
+  children,
+  size = 'medium',
+  variant = 'default',
+  showCloseButton = true,
+  closeOnBackdropClick = true,
+  closeOnEscapeKey = true,
+  style,
+  testID,
+}) => {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const previousActiveElementRef = useRef<HTMLElement | null>(null);
+  const [isVisible, setIsVisible] = useState(false);
+  const [shouldRender, setShouldRender] = useState(false);
+
+  // Handle mounting/unmounting with animation
+  useEffect(() => {
+    if (open && !shouldRender) {
+      // Opening sequence
+      setShouldRender(true);
+      // Use double requestAnimationFrame to ensure the DOM has fully rendered
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          setIsVisible(true);
+        });
+      });
+    } else if (!open && shouldRender) {
+      // Closing sequence
+      setIsVisible(false);
+      // Wait for transition to complete before unmounting
+      const timer = setTimeout(() => {
+        setShouldRender(false);
+      }, 150); // Match transition duration
+      return () => clearTimeout(timer);
+    }
+  }, [open, shouldRender]);
+
+  // Handle escape key
+  useEffect(() => {
+    if (!open || !closeOnEscapeKey) return;
+
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        onOpenChange(false);
+      }
+    };
+
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [open, closeOnEscapeKey, onOpenChange]);
+
+  // Handle focus management
+  useEffect(() => {
+    if (open) {
+      // Store the currently focused element
+      previousActiveElementRef.current = document.activeElement as HTMLElement;
+      
+      // Focus the dialog
+      setTimeout(() => {
+        dialogRef.current?.focus();
+      }, 0);
+    } else {
+      // Restore focus to the previously focused element
+      if (previousActiveElementRef.current) {
+        previousActiveElementRef.current.focus();
+      }
+    }
+  }, [open]);
+
+  // Prevent body scroll when dialog is open
+  useEffect(() => {
+    if (open) {
+      const originalStyle = window.getComputedStyle(document.body).overflow;
+      document.body.style.overflow = 'hidden';
+      return () => {
+        document.body.style.overflow = originalStyle;
+      };
+    }
+  }, [open]);
+
+  if (!shouldRender) return null;
+
+  const handleBackdropClick = (event: React.MouseEvent) => {
+    if (closeOnBackdropClick && event.target === event.currentTarget) {
+      onOpenChange(false);
+    }
+  };
+
+  const handleCloseClick = () => {
+    onOpenChange(false);
+  };
+
+  // Apply variants
+  dialogStyles.useVariants({
+    size,
+    variant,
+  });
+
+  const backdropProps = getWebProps([
+    dialogStyles.backdrop,
+    { opacity: isVisible ? 1 : 0 }
+  ]);
+  const containerProps = getWebProps([
+    dialogStyles.container, 
+    style,
+    isVisible 
+      ? { opacity: 1, transform: 'scale(1) translateY(0px)' }
+      : { opacity: 0, transform: 'scale(0.96) translateY(-4px)' }
+  ]);
+  const headerProps = getWebProps([dialogStyles.header]);
+  const titleProps = getWebProps([dialogStyles.title]);
+  const closeButtonProps = getWebProps([dialogStyles.closeButton]);
+  const contentProps = getWebProps([dialogStyles.content]);
+
+  const dialogContent = (
+    <div
+      {...backdropProps}
+      onClick={handleBackdropClick}
+      data-testid={testID}
+    >
+      <div
+        {...containerProps}
+        ref={dialogRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={title ? 'dialog-title' : undefined}
+        tabIndex={-1}
+        onClick={(e) => e.stopPropagation()}
+      >
+        {(title || showCloseButton) && (
+          <div {...headerProps}>
+            {title && (
+              <h2 {...titleProps} id="dialog-title">
+                {title}
+              </h2>
+            )}
+            {showCloseButton && (
+              <button
+                {...closeButtonProps}
+                onClick={handleCloseClick}
+                aria-label="Close dialog"
+                type="button"
+              >
+                <Icon name="close" />
+              </button>
+            )}
+          </div>
+        )}
+        <div {...contentProps}>
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+
+  return createPortal(dialogContent, document.body);
+};
+
+export default Dialog;