feat(ContentList)(BasicCard): add gravity icon (#1246)

Author: aeksandla

memory-bank/activeContext.md

@@ -13,14 +13,25 @@ The Page Constructor library is currently focused on providing a comprehensive s
 
 Recent development has focused on:
 
-1. **Button Component Enhancement**: Added support for icons through the `img` prop
+1. **Gravity Icons Integration** (Commits a72c3f3 and 8a8aa02):
+
+   - **New Icon Component**: Created universal component `src/components/Icon/Icon.tsx` for working with icons
+   - **Gravity UI Icons Support**: Integration with `@gravity-ui/icons` library for using ready-made icons
+   - **New GravityIconProps Type**: Added type for gravity icons configuration with color support ('brand' | 'text-color')
+   - **BasicCard Update**: Added support for `gravityIcon` prop in BasicCard component
+   - **ContentList Update**: Added support for gravity icons in content lists
+   - **IconWrapper Update**: Extended support for gravity icons in IconWrapper component
+   - **Schema Validation**: Added validation for GravityIconProps in BasicCard and Content schemas
+   - **Storybook Examples**: Added new stories to demonstrate gravity icons
+
+2. **Button Component Enhancement**: Added support for icons through the `img` prop
 
    - Support for Gravity UI icons (React components)
    - Support for custom SVG strings
    - Configurable icon positioning (left/right)
    - Configurable icon size
 
-2. **HeaderBlock Enhancements**: Significant updates to HeaderBlock with new functionality:
+3. **HeaderBlock Enhancements**: Significant updates to HeaderBlock with new functionality:
 
    - **New Content Properties**: Added `additionalInfo`, `overtitle`, and `status` for richer content structure
    - **Custom Rendering**: Added `renderTitle` function prop for custom title rendering
@@ -33,18 +44,26 @@ Recent development has focused on:
    - **Component Architecture**: Refactored background rendering into separate `Background` and `FullWidthBackground` components
    - **Props Refactoring**: Renamed `containerFluidClassName` to `contentWrapperClassName` for better clarity
 
-3. **Card Component Standardization**: Updated BasicCard, LayoutItem, BackgroundCard, and ImageCard with consistent patterns:
+4. **Text Size Enhancement**: Updated `textSize` constant in `src/schema/validators/common.ts`:
+
+   - **Previous values**: `['s', 'm', 'l']`
+   - **Current values**: `['xs', 's', 'sm', 'm', 'l']`
+   - Added new smaller sizes: `'xs'` (extra small) and `'sm'` (small-medium)
+   - This affects all components that use text sizing: Links, FileLinkProps, TitleProps, and various blocks
+   - Updated TypeScript type `TextSize` to include new values
+
+5. **Card Component Standardization**: Updated BasicCard, LayoutItem, BackgroundCard, and ImageCard with consistent patterns:
 
    - Standardized `controlPosition` prop for flexible control placement ('content' vs 'footer')
    - Enhanced accessibility with `useUniqId()` for proper ARIA labeling
    - Consistent size defaults (size='s') across all card components
    - Unified theme support using `getThemedValue` utility
    - Improved integration with the Content sub-block
 
-4. **Accessibility Improvements**: Enhanced ARIA attributes and ID management across card components
-5. **Control Positioning**: New flexible control positioning system allowing buttons/links in footer area
-6. **Performance Optimization**: Reducing bundle size and improving rendering performance
-7. **Documentation**: Expanding Storybook examples and documentation
+6. **Accessibility Improvements**: Enhanced ARIA attributes and ID management across card components
+7. **Control Positioning**: New flexible control positioning system allowing buttons/links in footer area
+8. **Performance Optimization**: Reducing bundle size and improving rendering performance
+9. **Documentation**: Expanding Storybook examples and documentation
 
 ## Active Decisions and Considerations
 
@@ -129,8 +148,9 @@ The following areas are being considered for future development:
 ### Documentation Updates
 
 - Created detailed documentation of card component updates in [`cardComponentUpdates.md`](cardComponentUpdates.md)
-- Updated system patterns to reflect new card architecture
-- Enhanced progress tracking to include sub-block component improvements
+- Created comprehensive documentation of Gravity Icons integration in [`gravityIconsIntegration.md`](gravityIconsIntegration.md)
+- Updated system patterns to reflect new card architecture and icon system
+- Enhanced progress tracking to include sub-block component improvements and icon system enhancements
 
 ### Challenges
 

memory-bank/gravityIconsIntegration.md

@@ -0,0 +1,310 @@
+# Gravity Icons Integration
+
+## Overview
+
+Commits a72c3f3 and 8a8aa02 added full support for Gravity UI Icons in Page Constructor, creating a hybrid icon system that supports both traditional images and vector icons from the @gravity-ui/icons library.
+
+## Key Changes
+
+### New Components
+
+#### Icon Component (`src/components/Icon/Icon.tsx`)
+
+Universal component for working with icons:
+
+```typescript
+type Props = {
+  gravityIcon?: GravityIconProps;
+  icon?: ImageProps;
+  className?: string;
+} & Pick<ImageComponentProps, 'containerClassName'> &
+  QAProps;
+```
+
+**Functionality:**
+
+- Support for Gravity UI icons via `gravityIcon` prop
+- Support for traditional images via `icon` prop
+- Automatic icon type detection
+- Integration with theming through CSS variables
+
+#### Icon Styles (`src/components/Icon/Icon.scss`)
+
+Styles for icon color theming:
+
+```scss
+&_color {
+  &_brand {
+    color: var(--g-color-base-brand) !important;
+  }
+  &_text-color {
+    // as in nearest text
+  }
+}
+```
+
+### Type System Updates
+
+#### GravityIconProps Type
+
+New type in `src/models/constructor-items/common.ts`:
+
+```typescript
+export type GravityIconProps =
+  | string
+  | {
+      name: keyof typeof icons;
+      color: 'brand' | 'text-color';
+    };
+```
+
+**Supported formats:**
+
+- String: `"ChartColumn"` (uses 'brand' color by default)
+- Object: `{name: "ChartColumn", color: "text-color"}` (with color configuration)
+
+### Component Updates
+
+#### BasicCard Enhancement
+
+Added support for `gravityIcon` prop:
+
+```typescript
+interface BasicCardProps {
+  // ... existing props
+  gravityIcon?: ThemeSupporting<GravityIconProps>;
+}
+```
+
+**Integration with IconWrapper:**
+
+```typescript
+<IconWrapper
+    icon={themedIcon ? {value: themedIcon, position: iconPosition} : undefined}
+    gravityIcon={
+        themedGravityIcon
+            ? {value: themedGravityIcon, position: iconPosition}
+            : undefined
+    }
+    className={b('wrapper')}
+    size={size}
+>
+```
+
+#### ContentList Enhancement
+
+Updated to support Gravity icons in list items:
+
+```typescript
+interface ContentItemProps {
+  title?: string;
+  text?: string;
+  icon?: ThemeSupporting<ImageProps | SVGIcon>;
+  gravityIcon?: ThemeSupporting<GravityIconProps>;
+}
+```
+
+**ContentListItemIcon updated:**
+
+- Support for both `icon` and `gravityIcon` props
+- Priority given to `gravityIcon` if both are present
+- Uses new universal `Icon` component
+
+#### IconWrapper Enhancement
+
+Extended support for Gravity icons:
+
+```typescript
+interface IconWrapperProps {
+  icon?: PositionedIcon;
+  gravityIcon?: PositionedGravityIcon;
+  size?: 's' | 'm' | 'l';
+}
+```
+
+**New interface:**
+
+```typescript
+interface PositionedGravityIcon {
+  value: GravityIconProps;
+  position?: IconPosition;
+}
+```
+
+### Schema Validation
+
+#### Common Validators (`src/schema/validators/common.ts`)
+
+Added validation for GravityIconProps:
+
+```typescript
+export const GravityIconProps = {
+  oneOf: [
+    {
+      type: 'string',
+    },
+    {
+      type: 'object',
+      additionalProperties: false,
+      required: ['name'],
+      properties: {
+        name: {
+          type: 'string',
+        },
+        color: {
+          type: 'string',
+          enum: ['brand', 'text-color'],
+        },
+      },
+    },
+  ],
+};
+```
+
+#### BasicCard Schema (`src/sub-blocks/BasicCard/schema.ts`)
+
+Added support for `gravityIcon` in schema:
+
+```typescript
+export const BasicCard = {
+  // ... existing properties
+  properties: {
+    // ... existing properties
+    gravityIcon: GravityIconProps,
+  },
+};
+```
+
+#### Content Schema (`src/sub-blocks/Content/schema.ts`)
+
+Added support in Content elements:
+
+```typescript
+export const ContentItem = {
+  properties: {
+    // ... existing properties
+    gravityIcon: withTheme(GravityIconProps),
+  },
+};
+```
+
+### Storybook Integration
+
+#### BasicCard Stories
+
+Added new `GravityIcons` story with examples:
+
+```json
+"gravityIcons": [
+    {
+        "text": "Icon in content list",
+        "list": [
+            {
+                "gravityIcon": "ChartColumn",
+                "title": "Brand icon color",
+                "text": "Nisi ut aliquip ex ea commodo consequat."
+            },
+            {
+                "gravityIcon": {
+                    "name": "ChartColumn",
+                    "color": "text-color"
+                },
+                "title": "Text icon color",
+                "text": "Nisi ut aliquip ex ea commodo consequat."
+            }
+        ]
+    }
+]
+```
+
+## Technical Implementation
+
+### Icon Resolution Logic
+
+1. **Gravity Icon Priority**: If `gravityIcon` is present, it is used
+2. **Fallback to Image**: If `gravityIcon` is absent, `icon` is used
+3. **Color Application**: Color is applied through CSS classes and variables
+4. **Theme Integration**: Support for `getThemedValue` for theming
+
+### CSS Integration
+
+Icons are integrated with Gravity UI CSS variable system:
+
+- `--g-color-base-brand` for brand color
+- Text color inheritance for `text-color`
+
+### Backward Compatibility
+
+- All existing `icon` props continue to work
+- New `gravityIcon` props are optional
+- Components automatically detect icon type
+- Validation schemas support both formats
+
+## Usage Examples
+
+### Simple String Format
+
+```json
+{
+  "gravityIcon": "ChartColumn"
+}
+```
+
+### Object Format with Color
+
+```json
+{
+  "gravityIcon": {
+    "name": "ChartColumn",
+    "color": "text-color"
+  }
+}
+```
+
+### In BasicCard
+
+```json
+{
+  "gravityIcon": "ChartColumn",
+  "iconPosition": "left",
+  "text": "Card with Gravity icon",
+  "buttons": [
+    {
+      "text": "Action",
+      "theme": "action",
+      "url": "#"
+    }
+  ]
+}
+```
+
+### In ContentList
+
+```json
+{
+  "list": [
+    {
+      "gravityIcon": "ChartColumn",
+      "title": "List item with icon",
+      "text": "Description text"
+    }
+  ]
+}
+```
+
+## Benefits
+
+1. **Consistency**: Unified icon style through Gravity UI
+2. **Performance**: Vector icons instead of raster images
+3. **Theming**: Automatic color theme support
+4. **Scalability**: Icons scale without quality loss
+5. **Maintenance**: Centralized icon management through library
+6. **Backward Compatibility**: Existing code continues to work
+
+## Future Considerations
+
+1. **Icon Library Expansion**: Ability to add custom icons
+2. **Animation Support**: Support for animated icons
+3. **Size Variants**: Additional icon sizes
+4. **Accessibility**: Improved icon accessibility
+5. **Performance Optimization**: Tree-shaking of unused icons