@qwickapps/react-framework 1.5.12 → 1.5.13

package/src/components/blocks/OptionSelector.tsx

@@ -0,0 +1,459 @@
+'use client';
+
+/**
+ * OptionSelector - Universal option selection component with visual modes
+ *
+ * Features:
+ * - Multiple display modes (text, color swatches, images)
+ * - Multiple variants (buttons, dropdown, grid)
+ * - Visual disabled state for unavailable options
+ * - Tooltips for unavailable items
+ * - Selected state highlighting
+ * - Responsive layouts (horizontal, vertical, wrap)
+ * - Theme-compliant styling with CSS custom properties
+ * - Full serialization support
+ *
+ * @example
+ * // Text mode (sizes, quantities, etc.)
+ * <OptionSelector
+ *   options={[
+ *     { id: 's', label: 'S', available: true },
+ *     { id: 'm', label: 'M', available: true },
+ *   ]}
+ *   displayMode="text"
+ * />
+ *
+ * @example
+ * // Color mode (color selection)
+ * <OptionSelector
+ *   options={[
+ *     { id: 'red', label: 'Red', hexValue: '#FF0000', available: true },
+ *     { id: 'blue', label: 'Blue', hexValue: '#0000FF', available: true },
+ *   ]}
+ *   displayMode="color"
+ * />
+ *
+ * @example
+ * // Image mode (pattern selection)
+ * <OptionSelector
+ *   options={[
+ *     { id: 'pattern1', label: 'Stripes', imageUrl: '/patterns/stripes.jpg', available: true },
+ *   ]}
+ *   displayMode="image"
+ * />
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { useCallback } from 'react';
+import { Box, Button, Select, MenuItem, FormControl, InputLabel, Tooltip } from '@mui/material';
+import CheckIcon from '@mui/icons-material/Check';
+import { createSerializableView, SerializableComponent } from '../shared/createSerializableView';
+import { ViewProps } from '../shared/viewProps';
+
+export interface SelectOption {
+  /** Unique identifier */
+  id: string;
+
+  /** Display label */
+  label: string;
+
+  /** Whether this option is available for selection */
+  available: boolean;
+
+  /** Optional price adjustment */
+  price?: number;
+
+  /** Hex color value (for color display mode) */
+  hexValue?: string;
+
+  /** Image URL (for image or color display mode) */
+  imageUrl?: string;
+}
+
+export interface OptionSelectorProps extends ViewProps {
+  /** Array of available options */
+  options: SelectOption[];
+
+  /** Currently selected option ID */
+  selectedOption?: string;
+
+  /** Callback when option is selected */
+  onOptionSelect?: (optionId: string) => void;
+
+  /** Display mode */
+  displayMode?: 'text' | 'color' | 'image';
+
+  /** Display variant */
+  variant?: 'buttons' | 'dropdown' | 'grid';
+
+  /** Layout direction (for buttons variant) */
+  layout?: 'horizontal' | 'vertical' | 'wrap';
+
+  /** Visual size (for color/image modes) */
+  visualSize?: 'small' | 'medium' | 'large';
+
+  /** Show label below visual (for color/image modes) */
+  showLabel?: boolean;
+
+  /** Disable all selections */
+  disabled?: boolean;
+
+  /** Label for the selector */
+  label?: string;
+
+  /** Data source for dynamic loading */
+  dataSource?: string;
+
+  /** Data binding configuration */
+  bindingOptions?: Record<string, unknown>;
+}
+
+// View component
+function OptionSelectorView({
+  options = [],
+  selectedOption,
+  onOptionSelect,
+  displayMode = 'text',
+  variant = 'grid',
+  layout = 'wrap',
+  visualSize = 'medium',
+  showLabel = false,
+  disabled = false,
+  label = 'Select Option',
+  dataSource,
+  bindingOptions,
+  ...restProps
+}: OptionSelectorProps) {
+  const handleOptionClick = useCallback((optionId: string, available: boolean) => {
+    if (!disabled && available && onOptionSelect) {
+      onOptionSelect(optionId);
+    }
+  }, [disabled, onOptionSelect]);
+
+  const handleDropdownChange = useCallback((event: any) => {
+    if (onOptionSelect) {
+      onOptionSelect(event.target.value);
+    }
+  }, [onOptionSelect]);
+
+  // Get visual size in pixels
+  const getSizePixels = () => {
+    if (displayMode === 'text') return 48;
+    switch (visualSize) {
+      case 'small': return 32;
+      case 'large': return 56;
+      case 'medium':
+      default: return 44;
+    }
+  };
+
+  const sizeInPx = getSizePixels();
+
+  // Render nothing if no options
+  if (!options || options.length === 0) {
+    return null;
+  }
+
+  // Dropdown variant
+  if (variant === 'dropdown') {
+    return (
+      <FormControl
+        fullWidth
+        disabled={disabled}
+        {...restProps}
+        sx={{
+          '& .MuiOutlinedInput-root': {
+            '& fieldset': {
+              borderColor: 'var(--theme-border-main)',
+            },
+            '&:hover fieldset': {
+              borderColor: 'var(--theme-border-emphasis)',
+            },
+            '&.Mui-focused fieldset': {
+              borderColor: 'var(--theme-primary)',
+            },
+          },
+          '& .MuiInputLabel-root': {
+            color: 'var(--theme-text-secondary)',
+            '&.Mui-focused': {
+              color: 'var(--theme-primary)',
+            },
+          },
+        }}
+      >
+        <InputLabel>{label}</InputLabel>
+        <Select
+          value={selectedOption || ''}
+          onChange={handleDropdownChange}
+          label={label}
+          sx={{
+            backgroundColor: 'var(--theme-surface)',
+            color: 'var(--theme-text-primary)',
+          }}
+        >
+          {options.map((option) => (
+            <MenuItem
+              key={option.id}
+              value={option.id}
+              disabled={!option.available}
+              sx={{
+                color: option.available ? 'var(--theme-text-primary)' : 'var(--theme-text-disabled)',
+              }}
+            >
+              {displayMode === 'color' && option.hexValue && (
+                <Box
+                  sx={{
+                    width: 20,
+                    height: 20,
+                    mr: 1,
+                    borderRadius: '50%',
+                    backgroundColor: option.hexValue,
+                    border: '1px solid var(--theme-border-main)',
+                    backgroundImage: option.imageUrl ? `url(${option.imageUrl})` : undefined,
+                    backgroundSize: 'cover',
+                  }}
+                />
+              )}
+              {option.label}
+              {!option.available && ' (Out of stock)'}
+              {option.price && option.price !== 0 && ` (+$${(option.price / 100).toFixed(2)})`}
+            </MenuItem>
+          ))}
+        </Select>
+      </FormControl>
+    );
+  }
+
+  // Buttons/Grid variant with visual modes
+  const getLayoutStyles = () => {
+    if (variant === 'grid') {
+      const minWidth = displayMode === 'text' ? 60 : sizeInPx + 16;
+      return {
+        display: 'grid',
+        gridTemplateColumns: `repeat(auto-fill, minmax(${minWidth}px, 1fr))`,
+        gap: displayMode === 'text' ? 1 : 2,
+      };
+    }
+
+    return {
+      display: 'flex',
+      flexDirection: layout === 'vertical' ? 'column' : 'row',
+      flexWrap: layout === 'wrap' ? 'wrap' : 'nowrap',
+      gap: 1,
+    };
+  };
+
+  return (
+    <Box {...restProps}>
+      {label && (
+        <Box
+          component="label"
+          sx={{
+            display: 'block',
+            mb: 1,
+            fontSize: '0.875rem',
+            fontWeight: 500,
+            color: 'var(--theme-text-primary)',
+          }}
+        >
+          {label}
+        </Box>
+      )}
+
+      <Box sx={getLayoutStyles()}>
+        {options.map((option) => {
+          const isSelected = selectedOption === option.id;
+          const isAvailable = option.available;
+
+          // Text mode - render as buttons
+          if (displayMode === 'text') {
+            const button = (
+              <Button
+                key={option.id}
+                onClick={() => handleOptionClick(option.id, isAvailable)}
+                disabled={disabled || !isAvailable}
+                variant={isSelected ? 'contained' : 'outlined'}
+                sx={{
+                  minWidth: variant === 'grid' ? '60px' : '80px',
+                  height: `${sizeInPx}px`,
+                  borderRadius: 'var(--theme-border-radius-small)',
+                  textTransform: 'uppercase',
+                  fontWeight: 600,
+                  fontSize: '0.875rem',
+                  backgroundColor: isSelected ? 'var(--theme-primary)' : 'var(--theme-surface)',
+                  color: isSelected ? 'var(--theme-text-on-primary)' : 'var(--theme-text-primary)',
+                  borderColor: isSelected ? 'var(--theme-primary)' : 'var(--theme-border-main)',
+                  borderWidth: '2px',
+                  borderStyle: 'solid',
+                  '&.Mui-disabled': {
+                    backgroundColor: 'var(--theme-surface-variant)',
+                    color: 'var(--theme-text-disabled)',
+                    borderColor: 'var(--theme-border-light)',
+                    opacity: 0.5,
+                    textDecoration: 'line-through',
+                  },
+                  '&:hover:not(.Mui-disabled)': {
+                    backgroundColor: !isSelected ? 'var(--theme-surface-variant)' : undefined,
+                    borderColor: !isSelected ? 'var(--theme-border-emphasis)' : undefined,
+                    boxShadow: 'var(--theme-elevation-1)',
+                  },
+                  transition: 'all 0.2s ease-in-out',
+                }}
+              >
+                {option.label}
+              </Button>
+            );
+
+            return !isAvailable ? (
+              <Tooltip
+                key={option.id}
+                title="Not available"
+                arrow
+                sx={{
+                  '& .MuiTooltip-tooltip': {
+                    backgroundColor: 'var(--theme-surface)',
+                    color: 'var(--theme-text-primary)',
+                    border: '1px solid var(--theme-border-main)',
+                    boxShadow: 'var(--theme-elevation-2)',
+                  },
+                  '& .MuiTooltip-arrow': {
+                    color: 'var(--theme-surface)',
+                  },
+                }}
+              >
+                <span>{button}</span>
+              </Tooltip>
+            ) : button;
+          }
+
+          // Color/Image mode - render as visual swatches
+          const swatchContent = (
+            <Box
+              key={option.id}
+              onClick={() => handleOptionClick(option.id, isAvailable)}
+              sx={{
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                gap: 0.5,
+                cursor: disabled || !isAvailable ? 'not-allowed' : 'pointer',
+                opacity: disabled || !isAvailable ? 0.5 : 1,
+              }}
+            >
+              <Box
+                sx={{
+                  position: 'relative',
+                  width: sizeInPx,
+                  height: sizeInPx,
+                  borderRadius: displayMode === 'color' ? '50%' : 'var(--theme-border-radius-small)',
+                  backgroundColor: option.hexValue || 'var(--theme-surface-variant)',
+                  backgroundImage: option.imageUrl ? `url(${option.imageUrl})` : undefined,
+                  backgroundSize: 'cover',
+                  backgroundPosition: 'center',
+                  border: '2px solid',
+                  borderColor: isSelected ? 'var(--theme-primary)' : 'var(--theme-border-main)',
+                  boxShadow: isSelected ? 'var(--theme-elevation-2)' : 'none',
+                  transition: 'all 0.2s ease-in-out',
+                  ...(isAvailable && !disabled && !isSelected && {
+                    '&:hover': {
+                      borderColor: 'var(--theme-border-emphasis)',
+                      boxShadow: 'var(--theme-elevation-1)',
+                      transform: 'scale(1.05)',
+                    },
+                  }),
+                  ...(!isAvailable && {
+                    '&::after': {
+                      content: '""',
+                      position: 'absolute',
+                      top: '50%',
+                      left: '10%',
+                      right: '10%',
+                      height: '2px',
+                      backgroundColor: 'var(--theme-border-emphasis)',
+                      transform: 'translateY(-50%) rotate(-45deg)',
+                    },
+                  }),
+                }}
+              >
+                {isSelected && (
+                  <Box
+                    sx={{
+                      position: 'absolute',
+                      top: '50%',
+                      left: '50%',
+                      transform: 'translate(-50%, -50%)',
+                      display: 'flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      width: '100%',
+                      height: '100%',
+                      borderRadius: 'inherit',
+                      backgroundColor: 'rgba(0, 0, 0, 0.3)',
+                    }}
+                  >
+                    <CheckIcon
+                      sx={{
+                        color: 'white',
+                        fontSize: sizeInPx * 0.5,
+                        filter: 'drop-shadow(0 1px 2px rgba(0,0,0,0.5))',
+                      }}
+                    />
+                  </Box>
+                )}
+              </Box>
+
+              {showLabel && (
+                <Box
+                  sx={{
+                    fontSize: '0.75rem',
+                    color: 'var(--theme-text-secondary)',
+                    textAlign: 'center',
+                    maxWidth: sizeInPx + 16,
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    whiteSpace: 'nowrap',
+                  }}
+                >
+                  {option.label}
+                </Box>
+              )}
+            </Box>
+          );
+
+          return (
+            <Tooltip
+              key={option.id}
+              title={!isAvailable ? 'Not available' : option.label}
+              arrow
+              sx={{
+                '& .MuiTooltip-tooltip': {
+                  backgroundColor: 'var(--theme-surface)',
+                  color: 'var(--theme-text-primary)',
+                  border: '1px solid var(--theme-border-main)',
+                  boxShadow: 'var(--theme-elevation-2)',
+                },
+                '& .MuiTooltip-arrow': {
+                  color: 'var(--theme-surface)',
+                },
+              }}
+            >
+              {swatchContent}
+            </Tooltip>
+          );
+        })}
+      </Box>
+    </Box>
+  );
+}
+
+// Create the serializable component
+export const OptionSelector: SerializableComponent<OptionSelectorProps> =
+  createSerializableView<OptionSelectorProps>({
+    tagName: 'OptionSelector',
+    version: '1.0.0',
+    role: 'view',
+    View: OptionSelectorView,
+  });
+
+export default OptionSelector;

package/src/components/blocks/index.ts

@@ -22,6 +22,8 @@ export { default as Section } from './Section';
 export { default as Image } from './Image';
 export { default as Text } from './Text';
 export { default as ProductCard } from './ProductCard';
+export { default as ImageGallery } from './ImageGallery';
+export { default as OptionSelector } from './OptionSelector';
 export { default as FeatureCard } from './FeatureCard';
 export { default as CardListGrid } from './CardListGrid';
 
@@ -37,5 +39,7 @@ export type { SectionProps } from './Section';
 export type { ImageProps } from './Image';
 export type { TextProps } from './Text';
 export type { ProductCardProps, Product, ProductCardAction } from './ProductCard';
+export type { ImageGalleryProps, GalleryImage } from './ImageGallery';
+export type { OptionSelectorProps, SelectOption } from './OptionSelector';
 export type { FeatureCardProps, FeatureItem, FeatureCardAction } from './FeatureCard';
 export type { CardListGridProps } from './CardListGrid';

package/src/schemas/ImageGallerySchema.ts

@@ -0,0 +1,148 @@
+/**
+ * Schema for ImageGallery component - Image gallery with multiple view variants
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { IsBoolean, IsOptional, IsString, IsNumber, IsIn, IsArray, ValidateNested } from 'class-validator';
+import { Type } from 'class-transformer';
+import 'reflect-metadata';
+import { Editor, Field, Schema, FieldType, DataType } from '@qwickapps/schema';
+import { ViewSchema } from './ViewSchema';
+
+// Product image interface
+export class GalleryImageModel {
+  @Field({ dataType: DataType.STRING })
+  @IsString()
+  url!: string;
+
+  @Field({ dataType: DataType.STRING })
+  @IsString()
+  alt!: string;
+
+  @Field({ dataType: DataType.STRING })
+  @IsOptional()
+  @IsString()
+  thumbnail?: string;
+}
+
+// Gallery variants
+export type GalleryVariant = 'thumbnails' | 'carousel' | 'grid';
+
+// Thumbnail positions
+export type ThumbnailPosition = 'left' | 'bottom' | 'right';
+
+@Schema('ImageGallery', '1.0.0')
+export class ImageGalleryModel extends ViewSchema {
+  @Field({ dataType: DataType.ARRAY })
+  @Editor({
+    field_type: FieldType.ARRAY,
+    label: 'Product Images',
+    description: 'Array of product images to display in the gallery',
+  })
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => GalleryImageModel)
+  images!: GalleryImageModel[];
+
+  @Field({ dataType: DataType.STRING })
+  @Editor({
+    field_type: FieldType.TEXT,
+    label: 'Product Name',
+    description: 'Product name for accessibility',
+    placeholder: 'Premium Cotton T-Shirt'
+  })
+  @IsString()
+  productName!: string;
+
+  @Field({ defaultValue: 'thumbnails', dataType: DataType.STRING })
+  @Editor({
+    field_type: FieldType.SELECT,
+    label: 'Gallery Variant',
+    description: 'Display variant for the gallery',
+    validation: {
+      options: [
+        { label: 'Thumbnails', value: 'thumbnails' },
+        { label: 'Carousel', value: 'carousel' },
+        { label: 'Grid', value: 'grid' }
+      ]
+    }
+  })
+  @IsOptional()
+  @IsString()
+  @IsIn(['thumbnails', 'carousel', 'grid'])
+  variant?: GalleryVariant;
+
+  @Field({ defaultValue: 'left', dataType: DataType.STRING })
+  @Editor({
+    field_type: FieldType.SELECT,
+    label: 'Thumbnail Position',
+    description: 'Position of thumbnails (only for thumbnails variant)',
+    validation: {
+      options: [
+        { label: 'Left', value: 'left' },
+        { label: 'Bottom', value: 'bottom' },
+        { label: 'Right', value: 'right' }
+      ]
+    }
+  })
+  @IsOptional()
+  @IsString()
+  @IsIn(['left', 'bottom', 'right'])
+  thumbnailPosition?: ThumbnailPosition;
+
+  @Field({ defaultValue: '1', dataType: DataType.STRING })
+  @Editor({
+    field_type: FieldType.TEXT,
+    label: 'Aspect Ratio',
+    description: 'Aspect ratio for main image (e.g., "1", "4/3", "16/9")',
+    placeholder: '1'
+  })
+  @IsOptional()
+  @IsString()
+  aspectRatio?: string;
+
+  @Field({ defaultValue: true, dataType: DataType.BOOLEAN })
+  @Editor({
+    field_type: FieldType.BOOLEAN,
+    label: 'Show Zoom',
+    description: 'Enable zoom functionality for images'
+  })
+  @IsOptional()
+  @IsBoolean()
+  showZoom?: boolean;
+
+  @Field({ dataType: DataType.NUMBER })
+  @Editor({
+    field_type: FieldType.NUMBER,
+    label: 'Max Images',
+    description: 'Maximum number of images to display (leave empty for all)',
+    placeholder: '8'
+  })
+  @IsOptional()
+  @IsNumber()
+  maxImages?: number;
+
+  @Field({ dataType: DataType.STRING })
+  @Editor({
+    field_type: FieldType.TEXT,
+    label: 'Data Source',
+    description: 'Data source for dynamic image loading',
+    placeholder: 'product-images'
+  })
+  @IsOptional()
+  @IsString()
+  dataSource?: string;
+
+  @Field({ dataType: DataType.OBJECT })
+  @Editor({
+    field_type: FieldType.TEXTAREA,
+    label: 'Binding Options',
+    description: 'Data binding configuration (JSON format)',
+    placeholder: '{ "filter": {}, "sort": {} }'
+  })
+  @IsOptional()
+  bindingOptions?: Record<string, unknown>;
+}
+
+export default ImageGalleryModel;