@idealyst/components 1.0.53 → 1.0.56

package/src/SVGImage/README.md

@@ -0,0 +1,209 @@
+# SVGImage Component
+
+A cross-platform React/React Native component for rendering SVG images with theme support and consistent styling.
+
+## Overview
+
+The SVGImage component provides a unified way to display SVG images across web and React Native platforms. It supports both imported SVG files (as React components) and remote SVG URLs, with built-in theming and styling capabilities.
+
+## Installation
+
+The SVGImage component is part of the `@idealyst/components` package:
+
+```bash
+yarn add @idealyst/components
+```
+
+For React Native projects, you also need:
+```bash
+yarn add react-native-svg react-native-svg-transformer
+```
+
+## Basic Usage
+
+### Imported SVG Files (Recommended)
+
+```tsx
+import { SVGImage } from '@idealyst/components';
+import MyLogo from './assets/logo.svg';
+
+function MyComponent() {
+  return (
+    <SVGImage 
+      source={MyLogo}
+      width={100}
+      height={50}
+    />
+  );
+}
+```
+
+### Remote SVG URLs
+
+```tsx
+import { SVGImage } from '@idealyst/components';
+
+function MyComponent() {
+  return (
+    <SVGImage 
+      source={{ uri: "https://cdn.jsdelivr.net/npm/simple-icons@v9/icons/react.svg" }}
+      width={60}
+      height={60}
+      color="#61dafb"
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `source` | `string \| { uri: string } \| React.FC<SvgProps>` | **Required** | SVG source - can be imported component, URL string, or URI object |
+| `width` | `number \| string` | `24` | Width of the SVG |
+| `height` | `number \| string` | `24` | Height of the SVG |
+| `size` | `number \| string` | - | Sets both width and height (overrides individual width/height) |
+| `color` | `string` | - | Fill color for the SVG |
+| `intent` | `'primary' \| 'success' \| 'error' \| 'warning' \| 'neutral'` | - | Theme-based color intent |
+| `style` | `ViewStyle` | - | Additional container styles |
+| `testID` | `string` | - | Test identifier |
+
+## Theme Integration
+
+The SVGImage component integrates with the Idealyst theme system:
+
+```tsx
+<SVGImage 
+  source={MyIcon}
+  size={24}
+  intent="primary" // Uses theme's primary color
+/>
+
+<SVGImage 
+  source={MyIcon}
+  size={24}
+  intent="success" // Uses theme's success color
+/>
+```
+
+## Platform Setup
+
+### React Native Setup
+
+1. **Install dependencies:**
+   ```bash
+   yarn add react-native-svg react-native-svg-transformer
+   ```
+
+2. **Configure Metro bundler** (`metro.config.js`):
+   ```javascript
+   const config = {
+     transformer: {
+       babelTransformerPath: require.resolve('react-native-svg-transformer'),
+     },
+     resolver: {
+       sourceExts: ['js', 'jsx', 'ts', 'tsx', 'svg'],
+       assetExts: ['png', 'jpg', 'jpeg', 'gif', 'webp'],
+     },
+   };
+   ```
+
+3. **Add TypeScript declarations** (`types/svg.d.ts`):
+   ```typescript
+   declare module '*.svg' {
+     import React from 'react';
+     import { SvgProps } from 'react-native-svg';
+     const content: React.FC<SvgProps>;
+     export default content;
+   }
+   ```
+
+4. **iOS: Install pods:**
+   ```bash
+   cd ios && pod install
+   ```
+
+### Web Setup
+
+For web projects using Vite, SVG imports work out of the box. Add TypeScript declarations if needed:
+
+```typescript
+// types/svg.d.ts
+declare module '*.svg' {
+  import React from 'react';
+  const content: React.FC<React.SVGProps<SVGSVGElement>>;
+  export default content;
+}
+```
+
+## Examples
+
+### Basic Usage
+```tsx
+import { SVGImage } from '@idealyst/components';
+import LogoIcon from './logo.svg';
+
+<SVGImage source={LogoIcon} size={40} />
+```
+
+### With Theme Colors
+```tsx
+<SVGImage 
+  source={LogoIcon} 
+  size={32}
+  intent="primary"
+/>
+```
+
+### Remote SVG
+```tsx
+<SVGImage 
+  source={{ uri: "https://cdn.jsdelivr.net/npm/simple-icons@v9/icons/typescript.svg" }}
+  width={48}
+  height={48}
+  color="#3178c6"
+/>
+```
+
+### Custom Styling
+```tsx
+<SVGImage 
+  source={LogoIcon}
+  size={60}
+  style={{ 
+    backgroundColor: '#f0f0f0',
+    borderRadius: 8,
+    padding: 8 
+  }}
+/>
+```
+
+## Best Practices
+
+1. **Prefer imported SVGs over URLs** - Better performance and reliability
+2. **Use theme intents** - Ensures consistency with your design system
+3. **Provide dimensions** - Always specify width/height or size
+4. **Test on both platforms** - Verify SVGs render correctly on web and mobile
+5. **Use CDN URLs** - For remote SVGs, use reliable CDNs like jsDelivr
+
+## Limitations
+
+- **React Native**: Local SVG files must be imported as components (not file paths)
+- **Remote URLs**: Some servers may block requests from mobile apps (403 errors)
+- **Coloring**: Works best with single-color SVG icons
+
+## Troubleshooting
+
+### SVGs not showing on React Native
+- Ensure `react-native-svg-transformer` is configured in Metro
+- Check that SVGs are imported as components, not file paths
+- Verify pods are installed on iOS
+
+### Remote SVGs failing
+- Use CDN URLs (e.g., jsDelivr, unpkg) instead of direct server URLs
+- Check browser console for CORS or 403 errors
+- Consider hosting SVGs on your own CDN
+
+### TypeScript errors
+- Add SVG type declarations to your project
+- Ensure `react-native-svg` types are installed

package/src/SVGImage/SVGImage.native.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import { View } from 'react-native';
+import { SvgUri } from 'react-native-svg';
+import { SVGImageProps } from './types';
+import { svgImageStyles } from './SVGImage.styles';
+
+const SVGImage: React.FC<SVGImageProps> = ({
+  source,
+  width,
+  height,
+  size,
+  color,
+  intent,
+  style,
+  testID,
+  ...props
+}) => {
+  // Apply variants using Unistyles 3.0 pattern
+  if (intent) {
+    svgImageStyles.useVariants({
+      intent: intent as 'primary' | 'success' | 'error' | 'warning' | 'neutral',
+    });
+  }
+
+  // Determine dimensions - size takes precedence over individual width/height
+  const finalWidth = size || width || 24;
+  const finalHeight = size || height || 24;
+
+  // Mode 1: Handle React components (imported SVG components)
+  if (typeof source === 'function') {
+    const SvgComponent = source;
+    return (
+      <View style={[svgImageStyles.container, style]} testID={testID} {...props}>
+        <SvgComponent
+          width={finalWidth}
+          height={finalHeight}
+          fill={color}
+          color={color}
+        />
+      </View>
+    );
+  }
+
+  // Mode 2: Handle URI-based SVG loading
+  const sourceUri = typeof source === 'string' ? source : source.uri;
+  
+  return (
+    <View style={[svgImageStyles.container, style]} testID={testID} {...props}>
+      <SvgUri
+        uri={sourceUri}
+        width={finalWidth}
+        height={finalHeight}
+        fill={color}
+        color={color}
+      />
+    </View>
+  );
+};
+
+export default SVGImage;

package/src/SVGImage/SVGImage.styles.tsx

@@ -0,0 +1,70 @@
+import { StyleSheet } from 'react-native-unistyles';
+
+export const svgImageStyles = StyleSheet.create((theme) => ({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    
+    variants: {
+      intent: {
+        primary: {
+          // Use CSS filter for web, tintColor for React Native
+          filter: `brightness(0) saturate(100%) invert(27%) sepia(51%) saturate(2878%) hue-rotate(346deg) brightness(104%) contrast(97%)`,
+        },
+        success: {
+          filter: `brightness(0) saturate(100%) invert(64%) sepia(88%) saturate(3323%) hue-rotate(84deg) brightness(119%) contrast(119%)`,
+        },
+        error: {
+          filter: `brightness(0) saturate(100%) invert(23%) sepia(89%) saturate(7395%) hue-rotate(4deg) brightness(102%) contrast(118%)`,
+        },
+        warning: {
+          filter: `brightness(0) saturate(100%) invert(54%) sepia(98%) saturate(4341%) hue-rotate(21deg) brightness(101%) contrast(101%)`,
+        },
+        neutral: {
+          filter: `brightness(0) saturate(100%) invert(52%) sepia(23%) saturate(3207%) hue-rotate(314deg) brightness(99%) contrast(96%)`,
+        },
+      },
+    },
+    
+    // Web-specific styles
+    _web: {
+      userSelect: 'none',
+    },
+    
+    // Native-specific styles  
+    _native: {
+      variants: {
+        intent: {
+          primary: {
+            tintColor: theme.intents?.primary?.main || '#3b82f6',
+          },
+          success: {
+            tintColor: theme.intents?.success?.main || '#22c55e',
+          },
+          error: {
+            tintColor: theme.intents?.error?.main || '#ef4444',
+          },
+          warning: {
+            tintColor: theme.intents?.warning?.main || '#f59e0b',
+          },
+          neutral: {
+            tintColor: theme.intents?.neutral?.main || '#6b7280',
+          },
+        },
+      },
+    },
+  },
+  
+  image: {
+    // Base image styles
+    _web: {
+      display: 'block',
+      maxWidth: '100%',
+      height: 'auto',
+    },
+    
+    _native: {
+      // Native image styles will be applied via Image component
+    },
+  },
+}));

package/src/SVGImage/SVGImage.web.tsx

@@ -0,0 +1,93 @@
+import React from 'react';
+import { getWebProps } from 'react-native-unistyles/web';
+import { SVGImageProps } from './types';
+import { svgImageStyles } from './SVGImage.styles';
+
+const SVGImage: React.FC<SVGImageProps> = ({
+  source,
+  width,
+  height,
+  size,
+  color,
+  intent,
+  resizeMode = 'contain',
+  style,
+  testID,
+  ...props
+}) => {
+  // Apply variants using Unistyles 3.0 pattern
+  if (intent) {
+    svgImageStyles.useVariants({
+      intent: intent as 'primary' | 'success' | 'error' | 'warning' | 'neutral',
+    });
+  }
+
+  // Determine dimensions - size takes precedence over individual width/height
+  const finalWidth = size || width;
+  const finalHeight = size || height;
+
+  // Handle React components (imported SVG components)
+  if (typeof source === 'function') {
+    const SvgComponent = source;
+    return (
+      <div {...getWebProps([svgImageStyles.container, style])} {...props} data-testid={testID}>
+        <SvgComponent
+          width={finalWidth || 24}
+          height={finalHeight || 24}
+          fill={color || 'currentColor'}
+          color={color || 'currentColor'}
+        />
+      </div>
+    );
+  }
+
+  // Determine source URL
+  const sourceUrl = typeof source === 'string' ? source : source.uri;
+
+  // Create the style array
+  const containerStyleArray = [
+    svgImageStyles.container,
+    style,
+  ];
+
+  const imageStyleArray = [
+    svgImageStyles.image,
+  ];
+
+  // Use getWebProps to generate className and ref for web
+  const containerWebProps = getWebProps(containerStyleArray);
+  const imageWebProps = getWebProps(imageStyleArray);
+
+  // Apply custom color if provided
+  // Convert React Native resize modes to CSS object-fit values
+  const getObjectFit = (mode: 'contain' | 'cover' | 'stretch'): React.CSSProperties['objectFit'] => {
+    switch (mode) {
+      case 'contain': return 'contain';
+      case 'cover': return 'cover';
+      case 'stretch': return 'fill';
+      default: return 'contain';
+    }
+  };
+
+  const imageStyle: React.CSSProperties = {
+    width: finalWidth,
+    height: finalHeight,
+    objectFit: getObjectFit(resizeMode),
+    ...(color && {
+      filter: `brightness(0) saturate(100%) ${color}`,
+    }),
+  };
+
+  return (
+    <div {...containerWebProps} {...props} data-testid={testID}>
+      <img
+        {...imageWebProps}
+        src={sourceUrl}
+        alt="SVG Image"
+        style={imageStyle}
+      />
+    </div>
+  );
+};
+
+export default SVGImage;

package/src/SVGImage/index.native.ts

@@ -0,0 +1,2 @@
+export { default } from './SVGImage.native';
+export * from './types';

package/src/SVGImage/index.ts

@@ -0,0 +1,5 @@
+// Platform-agnostic SVGImage export
+// Metro will resolve to index.native.ts for React Native
+// This file serves as fallback for web environments
+export { default } from './SVGImage.web';
+export * from './types';

package/src/SVGImage/index.web.ts

@@ -0,0 +1,2 @@
+export { default } from './SVGImage.web';
+export * from './types';

package/src/SVGImage/types.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import { ViewProps } from 'react-native';
+import { SvgProps } from 'react-native-svg';
+import { IntentNames } from '../theme';
+
+export interface SVGImageProps extends Omit<ViewProps, 'children'> {
+  source: string | { uri: string } | React.FC<SvgProps>;
+  width?: number | string;
+  height?: number | string;
+  size?: number | string;
+  color?: string;
+  intent?: IntentNames;
+  resizeMode?: 'contain' | 'cover' | 'stretch';
+}

package/src/examples/AllExamples.tsx

@@ -11,6 +11,7 @@ import { DividerExamples } from './DividerExamples';
 import { BadgeExamples } from './BadgeExamples';
 import { AvatarExamples } from './AvatarExamples';
 import { ScreenExamples } from './ScreenExamples';
+import { SVGImageExamples } from './SVGImageExamples';
 import { DialogExamples } from './DialogExamples';
 import { PopoverExamples } from './PopoverExamples';
 import { ThemeExtensionExamples } from './ThemeExtensionExamples';
@@ -63,6 +64,9 @@ export const AllExamples = () => {
       <ScreenExamples />
       <Divider spacing="medium" />
       
+      <SVGImageExamples />
+      <Divider spacing="medium" />
+      
       <DialogExamples />
       <Divider spacing="medium" />
       

package/src/examples/SVGImageExamples.tsx

@@ -0,0 +1,188 @@
+import { Screen, View, SVGImage, Text } from '../index';
+import testLogo from './test-logo.svg';
+
+export const SVGImageExamples = () => {
+  return (
+    <Screen background="primary" padding="lg">
+      <View spacing="none">
+        <Text size="large" weight="bold" align="center">
+          SVG Image Examples
+        </Text>
+        
+        {/* Local SVG File Example */}
+        <View spacing="md">
+          <Text size="medium" weight="semibold">Loading Local SVG File</Text>
+          <Text size="small">
+            Using the test-logo.svg file - works on web, limited support on React Native
+          </Text>
+          <View style={{ flexDirection: 'row', gap: 16, flexWrap: 'wrap', alignItems: 'center' }}>
+            {/* Original size */}
+            <SVGImage 
+              source={testLogo}
+              width={102} 
+              height={30}
+            />
+            
+            {/* Smaller version */}
+            <SVGImage 
+              source={testLogo}
+              width={68} 
+              height={20}
+            />
+            
+            {/* Using size prop */}
+            <SVGImage 
+              source={testLogo}
+              size={40}
+            />
+          </View>
+        </View>
+
+        {/* Intent Colors */}
+        <View spacing="md">
+          <Text size="medium" weight="semibold">Intent Colors</Text>
+          <Text size="small">
+            SVG images with theme-based coloring
+          </Text>
+          <View style={{ flexDirection: 'row', gap: 16, flexWrap: 'wrap', alignItems: 'center' }}>
+            <SVGImage 
+              source={testLogo}
+              width={102} 
+              height={30}
+              intent="primary"
+            />
+            <SVGImage 
+              source={testLogo}
+              width={102} 
+              height={30}
+              intent="success"
+            />
+            <SVGImage 
+              source={testLogo}
+              width={102} 
+              height={30}
+              intent="error"
+            />
+            <SVGImage 
+              source={testLogo}
+              width={102} 
+              height={30}
+              intent="warning"
+            />
+          </View>
+        </View>
+
+        {/* Custom Colors */}
+        <View spacing="md">
+          <Text size="medium" weight="semibold">Custom Colors</Text>
+          <Text size="small">
+            Direct color specification
+          </Text>
+          <View style={{ flexDirection: 'row', gap: 16, flexWrap: 'wrap', alignItems: 'center' }}>
+            <SVGImage 
+              source={testLogo}
+              width={102} 
+              height={30}
+              color="#ff6b6b"
+            />
+            <SVGImage 
+              source={testLogo}
+              width={102} 
+              height={30}
+              color="#4ecdc4"
+            />
+            <SVGImage 
+              source={testLogo}
+              width={102} 
+              height={30}
+              color="#45b7d1"
+            />
+          </View>
+        </View>
+
+        {/* Remote URL Example */}
+        <View spacing="md">
+          <Text size="medium" weight="semibold">Loading from URL</Text>
+          <Text size="small">
+            SVG images loaded from remote URLs (web only for security)
+          </Text>
+          <View style={{ flexDirection: 'row', gap: 16, flexWrap: 'wrap', alignItems: 'center' }}>
+            <SVGImage 
+              source={{ uri: "https://cdn.jsdelivr.net/npm/simple-icons@v9/icons/react.svg" }}
+              width={60} 
+              height={60}
+            />
+            <SVGImage 
+              source={{ uri: "https://cdn.jsdelivr.net/npm/simple-icons@v9/icons/javascript.svg" }}
+              width={60} 
+              height={60}
+              intent="primary"
+            />
+            <SVGImage 
+              source={{ uri: "https://cdn.jsdelivr.net/npm/simple-icons@v9/icons/typescript.svg" }}
+              width={60} 
+              height={60}
+              intent="success"
+            />
+          </View>
+        </View>
+
+        {/* Resize Modes */}
+        <View spacing="md">
+          <Text size="medium" weight="semibold">Resize Modes</Text>
+          <Text size="small">
+            Different ways to fit SVG images in containers
+          </Text>
+          <View style={{ flexDirection: 'row', gap: 16, flexWrap: 'wrap', alignItems: 'center' }}>
+            <View style={{ width: 80, height: 40, backgroundColor: 'rgba(0,0,0,0.1)' }}>
+              <SVGImage 
+                source={testLogo}
+                width="100%" 
+                height="100%"
+                resizeMode="contain"
+              />
+            </View>
+            <View style={{ width: 80, height: 40, backgroundColor: 'rgba(0,0,0,0.1)' }}>
+              <SVGImage 
+                source={testLogo}
+                width="100%" 
+                height="100%"
+                resizeMode="cover"
+              />
+            </View>
+            <View style={{ width: 80, height: 40, backgroundColor: 'rgba(0,0,0,0.1)' }}>
+              <SVGImage 
+                source={testLogo}
+                width="100%" 
+                height="100%"
+                resizeMode="stretch"
+              />
+            </View>
+          </View>
+        </View>
+
+        {/* Usage Tips */}
+        <View spacing="md">
+          <Text size="medium" weight="semibold">Usage Tips</Text>
+          <View spacing="sm">
+            <Text size="small">
+              • <Text weight="semibold">Local files:</Text> Use relative paths for bundled SVG files
+            </Text>
+            <Text size="small">
+              • <Text weight="semibold">Remote URLs:</Text> Use {`{ uri: "https://..." }`} format
+            </Text>
+            <Text size="small">
+              • <Text weight="semibold">React Native:</Text> Local SVGs have limited support - use remote URLs or convert to PNG
+            </Text>
+            <Text size="small">
+              • <Text weight="semibold">Coloring:</Text> Works best with single-color SVG icons
+            </Text>
+            <Text size="small">
+              • <Text weight="semibold">Performance:</Text> Cache remote SVGs for better performance
+            </Text>
+          </View>
+        </View>
+      </View>
+    </Screen>
+  );
+};

package/src/examples/index.ts

@@ -9,6 +9,7 @@ export { DividerExamples } from './DividerExamples';
 export { BadgeExamples } from './BadgeExamples';
 export { AvatarExamples } from './AvatarExamples';
 export { ScreenExamples } from './ScreenExamples';
+export { SVGImageExamples } from './SVGImageExamples';
 export { DialogExamples } from './DialogExamples';
 export { PopoverExamples } from './PopoverExamples';
 export { ThemeExtensionExamples } from './ThemeExtensionExamples';