@app-studio/web 0.9.31 → 0.9.33

package/docs/components/Icon.mdx

@@ -0,0 +1,438 @@
+# Icon
+
+A comprehensive collection of SVG icons with consistent styling, customizable colors, sizes, and orientations. All icons are optimized for accessibility and performance, with support for filled and outlined variants.
+
+### **Import**
+  ```tsx
+  import * as Icon from '@app-studio/web';
+  // Or import specific icons
+  import {
+    UploadIcon,
+    DownloadIcon,
+    EditIcon,
+    DeleteIcon,
+    CloseIcon,
+    CheckIcon
+  } from '@app-studio/web';
+  ```
+
+### **Basic Usage**
+```tsx
+import React from 'react';
+import { UploadIcon, EditIcon, DeleteIcon } from '@app-studio/web';
+import { Horizontal } from 'app-studio';
+
+export const BasicIcons = () => (
+  <Horizontal gap={16}>
+    <UploadIcon widthHeight={24} />
+    <EditIcon widthHeight={24} />
+    <DeleteIcon widthHeight={24} />
+  </Horizontal>
+);
+```
+
+### **Icon Sizes**
+```tsx
+import React from 'react';
+import { StarIcon } from '@app-studio/web';
+import { Horizontal } from 'app-studio';
+
+export const IconSizes = () => (
+  <Horizontal gap={16} alignItems="center">
+    <StarIcon widthHeight={16} />
+    <StarIcon widthHeight={24} />
+    <StarIcon widthHeight={32} />
+    <StarIcon widthHeight={48} />
+    <StarIcon widthHeight={64} />
+  </Horizontal>
+);
+```
+
+### **Icon Colors**
+```tsx
+import React from 'react';
+import { HeartIcon } from '@app-studio/web';
+import { Horizontal } from 'app-studio';
+
+export const IconColors = () => (
+  <Horizontal gap={16}>
+    <HeartIcon widthHeight={32} color="color.red.500" />
+    <HeartIcon widthHeight={32} color="color.blue.500" />
+    <HeartIcon widthHeight={32} color="color.green.500" />
+    <HeartIcon widthHeight={32} color="color.purple.500" />
+    <HeartIcon widthHeight={32} color="color.orange.500" />
+  </Horizontal>
+);
+```
+
+### **Filled vs Outlined**
+```tsx
+import React from 'react';
+import { StarIcon, HeartIcon, BookmarkIcon } from '@app-studio/web';
+import { Horizontal, Vertical, Text } from 'app-studio';
+
+export const IconVariants = () => (
+  <Vertical gap={16}>
+    <Text>Filled Icons</Text>
+    <Horizontal gap={16}>
+      <StarIcon widthHeight={32} filled={true} color="color.yellow.500" />
+      <HeartIcon widthHeight={32} filled={true} color="color.red.500" />
+      <BookmarkIcon widthHeight={32} filled={true} color="color.blue.500" />
+    </Horizontal>
+
+    <Text>Outlined Icons</Text>
+    <Horizontal gap={16}>
+      <StarIcon widthHeight={32} filled={false} color="color.yellow.500" />
+      <HeartIcon widthHeight={32} filled={false} color="color.red.500" />
+      <BookmarkIcon widthHeight={32} filled={false} color="color.blue.500" />
+    </Horizontal>
+  </Vertical>
+);
+```
+
+### **Icon Orientations**
+```tsx
+import React from 'react';
+import { ArrowIcon } from '@app-studio/web';
+import { Horizontal, Text } from 'app-studio';
+
+export const IconOrientations = () => (
+  <Horizontal gap={24} alignItems="center">
+    <div>
+      <Text fontSize={12}>Up</Text>
+      <ArrowIcon widthHeight={32} orientation="up" />
+    </div>
+    <div>
+      <Text fontSize={12}>Right</Text>
+      <ArrowIcon widthHeight={32} orientation="right" />
+    </div>
+    <div>
+      <Text fontSize={12}>Down</Text>
+      <ArrowIcon widthHeight={32} orientation="down" />
+    </div>
+    <div>
+      <Text fontSize={12}>Left</Text>
+      <ArrowIcon widthHeight={32} orientation="left" />
+    </div>
+  </Horizontal>
+);
+```
+
+### **Available Icons**
+
+The icon library includes a comprehensive set of icons organized by category:
+
+**Navigation & Actions:**
+- `ArrowIcon` - Directional arrows with orientation support
+- `ChevronIcon` - Chevron arrows for dropdowns and navigation
+- `CloseIcon` - Close/X icon for modals and dismissible elements
+- `MenuIcon` - Hamburger menu icon
+- `BackIcon` - Back navigation arrow
+- `ForwardIcon` - Forward navigation arrow
+
+**File & Media:**
+- `UploadIcon` - File upload indicator
+- `DownloadIcon` - File download indicator
+- `ImageIcon` - Image file representation
+- `VideoIcon` - Video file representation
+- `FileIcon` - Generic file representation
+- `FolderIcon` - Folder/directory representation
+- `AttachmentIcon` - File attachment indicator
+
+**User Interface:**
+- `EditIcon` - Edit/pencil icon for editing actions
+- `DeleteIcon` / `DustBinIcon` - Delete/trash actions
+- `CopyIcon` - Copy to clipboard actions
+- `SearchIcon` - Search functionality
+- `FilterIcon` - Filter/sort functionality
+- `SettingsIcon` - Settings and configuration
+- `InfoIcon` - Information and help
+- `WarningIcon` - Warning and alert states
+- `ErrorIcon` - Error states
+- `CheckIcon` - Success and confirmation
+- `PlusIcon` - Add/create actions
+- `MinusIcon` - Remove/subtract actions
+
+**Social & Communication:**
+- `FacebookIcon` - Facebook social media
+- `XIcon` - X (Twitter) social media
+- `MessageIcon` - Chat and messaging
+- `MailIcon` - Email communication
+- `PhoneIcon` - Phone and calling
+- `ShareIcon` - Share functionality
+
+**Media Controls:**
+- `PlayIcon` - Play media content
+- `PauseIcon` - Pause media content
+- `StopIcon` - Stop media content
+- `VolumeIcon` - Audio volume control
+- `MuteIcon` - Mute audio
+
+**Status & Indicators:**
+- `LoadingSpinnerIcon` - Loading and progress states
+- `StarIcon` - Ratings and favorites
+- `HeartIcon` - Likes and favorites
+- `BookmarkIcon` - Bookmarks and saved items
+- `BellIcon` - Notifications
+- `BadgeIcon` - Status badges
+
+### **Icon Usage in Components**
+```tsx
+import React from 'react';
+import { Button } from '@app-studio/web';
+import { EditIcon, DeleteIcon, SaveIcon } from '@app-studio/web';
+import { Horizontal } from 'app-studio';
+
+export const IconButtons = () => (
+  <Horizontal gap={12}>
+    <Button
+      icon={<EditIcon widthHeight={16} />}
+      variant="outline"
+    >
+      Edit
+    </Button>
+    <Button
+      icon={<DeleteIcon widthHeight={16} />}
+      variant="outline"
+      colorScheme="theme.error"
+    >
+      Delete
+    </Button>
+    <Button
+      icon={<SaveIcon widthHeight={16} />}
+      variant="filled"
+      colorScheme="theme.primary"
+    >
+      Save
+    </Button>
+  </Horizontal>
+);
+```
+
+### **Custom Icon Styling**
+```tsx
+import React from 'react';
+import { StarIcon } from '@app-studio/web';
+import { View } from 'app-studio';
+
+export const CustomStyledIcon = () => (
+  <View>
+    <StarIcon
+      widthHeight={48}
+      color="color.yellow.400"
+      filled={true}
+      style={{
+        filter: 'drop-shadow(0 2px 4px rgba(0,0,0,0.2))',
+        transition: 'transform 0.2s ease',
+      }}
+      onMouseEnter={(e) => {
+        e.currentTarget.style.transform = 'scale(1.1)';
+      }}
+      onMouseLeave={(e) => {
+        e.currentTarget.style.transform = 'scale(1)';
+      }}
+    />
+  </View>
+);
+```
+
+### **Props**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| widthHeight | number | 24 | Size of the icon in pixels (sets both width and height) |
+| color | string | 'currentColor' | Color of the icon (supports theme colors) |
+| filled | boolean | varies by icon | Whether the icon should be filled or outlined |
+| strokeWidth | number | 1-2 | Stroke width for outlined icons |
+| orientation | `'left' \| 'right' \| 'up' \| 'down'` | 'up' | Orientation/rotation of the icon |
+| transform | string | undefined | Custom CSS transform property |
+
+### **IconWrapper Props**
+
+All icons inherit from the base `IconWrapper` component which extends `ViewProps`:
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| className | string | CSS class name for styling |
+| style | CSSProperties | Inline styles |
+| onClick | function | Click event handler |
+| onMouseEnter | function | Mouse enter event handler |
+| onMouseLeave | function | Mouse leave event handler |
+| aria-label | string | Accessibility label |
+| role | string | ARIA role |
+
+### **Responsive Icons**
+```tsx
+import React from 'react';
+import { MenuIcon } from '@app-studio/web';
+import { useBreakpoint } from 'app-studio';
+
+export const ResponsiveIcon = () => {
+  const { isMobile, isTablet, isDesktop } = useBreakpoint();
+
+  const iconSize = isMobile ? 20 : isTablet ? 24 : 28;
+
+  return (
+    <MenuIcon
+      widthHeight={iconSize}
+      color="color.gray.700"
+    />
+  );
+};
+```
+
+### **Icon with Tooltip**
+```tsx
+import React from 'react';
+import { Tooltip } from '@app-studio/web';
+import { InfoIcon } from '@app-studio/web';
+
+export const IconWithTooltip = () => (
+  <Tooltip content="This provides additional information">
+    <InfoIcon
+      widthHeight={20}
+      color="color.blue.500"
+      style={{ cursor: 'help' }}
+    />
+  </Tooltip>
+);
+```
+
+### **Animated Icons**
+```tsx
+import React, { useState } from 'react';
+import { HeartIcon } from '@app-studio/web';
+import { View } from 'app-studio';
+
+export const AnimatedIcon = () => {
+  const [isLiked, setIsLiked] = useState(false);
+
+  return (
+    <View
+      onClick={() => setIsLiked(!isLiked)}
+      style={{ cursor: 'pointer' }}
+    >
+      <HeartIcon
+        widthHeight={32}
+        color={isLiked ? 'color.red.500' : 'color.gray.400'}
+        filled={isLiked}
+        style={{
+          transition: 'all 0.2s ease',
+          transform: isLiked ? 'scale(1.2)' : 'scale(1)',
+        }}
+      />
+    </View>
+  );
+};
+```
+
+### **Icon Grid Display**
+```tsx
+import React from 'react';
+import * as Icons from '@app-studio/web';
+import { View, Text } from 'app-studio';
+
+export const IconGrid = () => {
+  const iconNames = Object.keys(Icons).filter(name =>
+    name.endsWith('Icon') && name !== 'IconWrapper'
+  );
+
+  return (
+    <View
+      display="grid"
+      gridTemplateColumns="repeat(auto-fill, minmax(120px, 1fr))"
+      gap={16}
+    >
+      {iconNames.map((iconName) => {
+        const IconComponent = Icons[iconName as keyof typeof Icons];
+        return (
+          <View
+            key={iconName}
+            padding={12}
+            border="1px solid"
+            borderColor="color.gray.200"
+            borderRadius={8}
+            textAlign="center"
+          >
+            <IconComponent widthHeight={24} color="color.gray.700" />
+            <Text fontSize={10} marginTop={4}>
+              {iconName}
+            </Text>
+          </View>
+        );
+      })}
+    </View>
+  );
+};
+```
+
+### **Best Practices**
+
+**Sizing:**
+- Use consistent icon sizes within the same context
+- Standard sizes: 16px (small), 20px (medium), 24px (large), 32px+ (extra large)
+- Consider touch targets for interactive icons (minimum 44px)
+
+**Colors:**
+- Use semantic colors for status icons (red for errors, green for success)
+- Maintain sufficient contrast for accessibility
+- Use theme colors for consistency across your application
+
+**Accessibility:**
+- Provide `aria-label` for standalone icons
+- Use `role="img"` for decorative icons
+- Ensure icons are not the only way to convey information
+
+**Performance:**
+- Icons are SVG-based for crisp rendering at any size
+- Import only the icons you need to reduce bundle size
+- Consider icon sprites for large applications
+
+### **Customization**
+
+**Creating Custom Icons:**
+```tsx
+import React from 'react';
+import { IconWrapper, IconProps } from '@app-studio/web';
+
+export const CustomIcon: React.FC<IconProps> = ({
+  widthHeight = 24,
+  color = 'currentColor',
+  filled = true,
+  ...props
+}) => (
+  <IconWrapper widthHeight={widthHeight} color={color} {...props}>
+    <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
+      <path
+        d="M12 2L2 7v10c0 5.55 3.84 9.74 9 11 5.16-1.26 9-5.45 9-11V7l-10-5z"
+        fill={filled ? color : 'none'}
+        stroke={filled ? 'none' : color}
+        strokeWidth={filled ? 0 : 2}
+      />
+    </svg>
+  </IconWrapper>
+);
+```
+
+### **Integration Examples**
+
+**With Navigation:**
+```tsx
+import React from 'react';
+import { NavigationMenu } from '@app-studio/web';
+import { HomeIcon, UserIcon, SettingsIcon } from '@app-studio/web';
+
+export const IconNavigation = () => (
+  <NavigationMenu>
+    <NavigationMenu.Item icon={<HomeIcon widthHeight={20} />}>
+      Home
+    </NavigationMenu.Item>
+    <NavigationMenu.Item icon={<UserIcon widthHeight={20} />}>
+      Profile
+    </NavigationMenu.Item>
+    <NavigationMenu.Item icon={<SettingsIcon widthHeight={20} />}>
+      Settings
+    </NavigationMenu.Item>
+  </NavigationMenu>
+);
+```