Skip to content

feat(Header): add props for elements className #1238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
36 changes: 27 additions & 9 deletions memory-bank/activeContext.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,29 @@ The Page Constructor library is currently focused on providing a comprehensive s

Recent development has focused on:

1. **Card Component Standardization**: Updated BasicCard, LayoutItem, BackgroundCard, and ImageCard with consistent patterns:
1. **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
- **Enhanced Background Support**: New `fullWidthMedia` property for full-width media backgrounds
- **Improved Media Control**: Added `mediaView` and `mediaClassName` for better media customization
- **Layout Customization**: Added `contentWrapperClassName` for custom styling of the content-wrapper element
- **Accessibility Improvements**: Enhanced ARIA support with `useUniqId()` and proper labeling
- **Context Integration**: Better integration with `useWindowWidth` and responsive breakpoints
- **Component Architecture**: Refactored background rendering into separate `Background` and `FullWidthBackground` components

2. **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

2. **Accessibility Improvements**: Enhanced ARIA attributes and ID management across card components
3. **Control Positioning**: New flexible control positioning system allowing buttons/links in footer area
4. **Performance Optimization**: Reducing bundle size and improving rendering performance
5. **Documentation**: Expanding Storybook examples and documentation
3. **Accessibility Improvements**: Enhanced ARIA attributes and ID management across components
4. **Control Positioning**: New flexible control positioning system allowing buttons/links in footer area
5. **Performance Optimization**: Reducing bundle size and improving rendering performance
6. **Documentation**: Expanding Storybook examples and documentation

## Active Decisions and Considerations

Expand All @@ -33,6 +44,8 @@ Recent development has focused on:
- **Component Structure**: The library follows a hierarchical component structure with blocks, sub-blocks, and base components
- **Context Providers**: Multiple context providers manage different aspects of the application (theme, mobile detection, analytics, etc.)
- **Type System**: A comprehensive TypeScript type system ensures type safety and developer experience
- **Responsive Design**: Enhanced integration with window width context and breakpoint constants for better mobile adaptation
- **Component Composition**: Complex blocks like HeaderBlock use internal component composition (Background, FullWidthBackground) for better maintainability

### Block System

Expand Down Expand Up @@ -94,10 +107,15 @@ The following areas are being considered for future development:

### Recent Achievements

1. **Accessibility Enhancement**: Improved ARIA support across card components with proper ID management
2. **Control Positioning Flexibility**: New `controlPosition` prop provides better layout control
3. **Theme Integration**: Consistent theme support using `getThemedValue` utility
4. **Component Consistency**: Standardized patterns across card components improve maintainability
1. **HeaderBlock Enhancement**: Significant improvements to HeaderBlock functionality:

- Improved media control with `mediaClassName` props
- Added layout customization with `contentWrapperClassName` prop

2. **Accessibility Enhancement**: Improved ARIA support across components with proper ID management
3. **Control Positioning Flexibility**: New `controlPosition` prop provides better layout control
4. **Theme Integration**: Consistent theme support using `getThemedValue` utility
5. **Component Consistency**: Standardized patterns across card components improve maintainability

### Documentation Updates

Expand Down
8 changes: 7 additions & 1 deletion memory-bank/progress.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,18 @@ The Page Constructor library is a mature and stable project that provides a comp

The library includes a comprehensive set of blocks for various use cases:

- **Layout Blocks**: Header, ContentLayout, CardLayout
- **Layout Blocks**: Header (with enhanced features), ContentLayout, CardLayout
- **Content Blocks**: Media, Banner, Info, Table, Tabs
- **Interactive Blocks**: Slider, Questions, FoldableList, Form
- **Feature Blocks**: PromoFeatures, ExtendedFeatures, Icons
- **Integration Blocks**: Map, Share, Companies

#### HeaderBlock Enhanced Features

The HeaderBlock has been significantly enhanced with new capabilities:

- **Media Customization**: `mediaView` and `mediaClassName` props for better media control

### Sub-block Components

Recently updated sub-block components with enhanced consistency:
Expand Down
34 changes: 34 additions & 0 deletions memory-bank/systemPatterns.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,40 @@ Blocks are composed of smaller components and sub-blocks:
└───────────────────────────────┘
```

### HeaderBlock Architecture

HeaderBlock follows an enhanced architectural pattern with component composition:

```
┌─────────────────────────────────────┐
│ HeaderBlock │
├─────────────────────────────────────┤
│ • useUniqId() for accessibility │
│ • useWindowWidth() for responsive │
│ • Theme support via getThemedValue │
│ • Component composition pattern │
├─────────────────────────────────────┤
│ Background Components │
│ • Background (media backgrounds) │
│ • FullWidthBackground (full width) │
├─────────────────────────────────────┤
│ Content Structure │
│ • overtitle (above title) │
│ • title with custom rendering │
│ • description and additionalInfo │
│ • status element support │
│ • buttons with ARIA labeling │
└─────────────────────────────────────┘
```

Key HeaderBlock patterns:

- **Component Composition**: Separate Background and FullWidthBackground components
- **Enhanced Content**: Support for overtitle, additionalInfo, status, and custom title rendering
- **Responsive Integration**: useWindowWidth hook and BREAKPOINTS constants
- **Media Flexibility**: mediaView and mediaClassName for customization
- **Accessibility**: Proper ARIA labeling with titleId for button descriptions

### Card Component Architecture

Card components follow a consistent architectural pattern:
Expand Down
10 changes: 8 additions & 2 deletions memory-bank/techContext.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,8 @@
- **Sub-blocks**: Components used within blocks (Cards, Quotes, etc.)
- **Components**: Basic UI elements (Button, Link, Image, etc.)
- **Grid**: Responsive layout system
- **Context**: React context providers for various features
- **Utils**: Utility functions and helpers
- **Context**: React context providers for various features (including WindowWidthContext for responsive design)
- **Utils**: Utility functions and helpers (including responsive breakpoint constants)

### Server-Side

Expand All @@ -81,6 +81,12 @@
- **iframe**: Isolated environment for rendering pages
- **Messaging**: Communication between editor and preview

## Recent Technical Enhancements

### HeaderBlock Technical Improvements

- **Type Safety**: Extended TypeScript interfaces with new properties (`mediaClassName`, `gridClassName`)

## Technical Constraints

1. **Browser Compatibility**:
Expand Down
237 changes: 237 additions & 0 deletions memory-bank/usage/headerBlock.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,237 @@
# HeaderBlock Usage Documentation

## Overview

HeaderBlock is a versatile layout block that serves as the main header section of a page. It has been significantly enhanced with new content structure options, improved accessibility, and better responsive design integration.

## Enhanced Properties

### Content Structure

#### `overtitle`

- **Type**: `string | JSX.Element`
- **Description**: Text or JSX element displayed above the main title
- **Usage**: For category labels, breadcrumb-like navigation, or contextual information

```json
{
"type": "header-block",
"overtitle": "Product Category",
"title": "Main Product Title"
}
```

#### `additionalInfo`

- **Type**: `string`
- **Description**: Additional information displayed after the description
- **Content Type**: YFM (Yandex Flavored Markdown)
- **Usage**: For supplementary details, disclaimers, or extended descriptions

```json
{
"type": "header-block",
"title": "Product Title",
"description": "Main product description",
"additionalInfo": "**Note**: Additional details about the product"
}
```

#### `status`

- **Type**: `JSX.Element`
- **Description**: Status element displayed next to the title
- **Usage**: For badges, labels, or status indicators

### Custom Rendering

#### `renderTitle`

- **Type**: `(title: string) => React.ReactNode`
- **Description**: Function for custom title rendering
- **Usage**: When you need custom title formatting or additional elements within the title

### Media Enhancements

#### `mediaView`

- **Type**: `'full' | 'fit'`
- **Default**: `'full'`
- **Description**: Controls how media content is displayed
- **Usage**:
- `'full'`: Media fills the available space
- `'fit'`: Media maintains aspect ratio within bounds

#### `mediaClassName`

- **Type**: `string`
- **Description**: Additional CSS class for media elements
- **Usage**: For custom styling of media content

#### `contentWrapperClassName`

- **Type**: `string`
- **Description**: Additional CSS class for the content-wrapper element
- **Usage**: For custom styling of the content wrapper that contains the header layout

### Background Enhancements

#### `fullWidthMedia`

- **Type**: `boolean`
- **Description**: Allows media backgrounds to extend to full viewport width
- **Usage**: For immersive background experiences

```json
{
"type": "header-block",
"title": "Immersive Header",
"background": {
"image": "background.jpg",
"fullWidthMedia": true
}
}
```

## Technical Implementation

### Component Architecture

The HeaderBlock now uses a component composition pattern:

```
HeaderBlock
├── Background (for media backgrounds)
├── FullWidthBackground (for full-width backgrounds)
└── Content Structure
├── overtitle
├── title (with custom rendering support)
├── description
├── additionalInfo
└── buttons
```

### Responsive Design

- **WindowWidth Integration**: Uses `useWindowWidth` hook for responsive behavior
- **Breakpoint Constants**: Leverages `BREAKPOINTS` constants for consistent responsive design
- **Mobile Adaptation**: Enhanced mobile experience with conditional media rendering

### Accessibility Features

- **Unique IDs**: Uses `useUniqId()` hook for proper ARIA labeling
- **ARIA Relationships**: Buttons are properly associated with titles using `aria-describedby`
- **Screen Reader Support**: Improved content structure for better screen reader navigation

### Background Components

#### Background Component

- Handles media backgrounds with video and image support
- Mobile-responsive media rendering
- Parallax support (disabled by default)

#### FullWidthBackground Component

- Renders full-width background colors
- Used when `fullWidth` or `fullWidthMedia` is enabled

## Usage Examples

### Basic Enhanced Header

```json
{
"type": "header-block",
"overtitle": "New Release",
"title": "Product Launch 2024",
"description": "Introducing our latest innovation",
"additionalInfo": "Available in **limited quantities**",
"buttons": [
{
"text": "Learn More",
"url": "/product",
"theme": "action"
}
]
}
```

### Header with Full-Width Media Background

```json
{
"type": "header-block",
"title": "Immersive Experience",
"description": "Full-width background showcase",
"background": {
"image": {
"src": "hero-background.jpg",
"alt": "Hero background"
},
"fullWidthMedia": true,
"color": "#1a1a1a"
},
"theme": "dark"
}
```

### Header with Custom Media View

```json
{
"type": "header-block",
"title": "Product Showcase",
"description": "Featured product display",
"image": {
"src": "product-image.jpg",
"alt": "Product showcase"
},
"mediaView": "fit",
"mediaClassName": "custom-media-style"
}
```

## Migration Notes

### New Properties

- All new properties are optional and backward compatible
- Existing HeaderBlock configurations will continue to work unchanged

### Enhanced Features

- Improved accessibility is automatically applied
- Responsive design enhancements are enabled by default
- Background rendering improvements are transparent to existing usage

### Deprecated Properties

- Some legacy properties may be deprecated in future versions
- Check the schema for current property status

## Best Practices

1. **Content Hierarchy**: Use `overtitle` for contextual information, `title` for main heading, `description` for primary details, and `additionalInfo` for supplementary content

2. **Accessibility**: Always provide meaningful `alt` text for images and ensure proper content structure

3. **Responsive Design**: Test headers across different screen sizes, especially when using custom media configurations

4. **Performance**: Use appropriate image sizes and formats for background media

5. **Theme Consistency**: Ensure theme settings work well with background colors and media content

## Schema Reference

The HeaderBlock schema includes all enhanced properties with proper validation:

- `overtitle`: String or JSX content type
- `additionalInfo`: YFM content with textarea input
- `mediaView`: Enum with 'full' and 'fit' options
- `fullWidthMedia`: Boolean for background configuration
- `renderTitle`: Function prop (not in schema, runtime only)
- `status`: JSX element (not in schema, runtime only)
- `mediaClassName`: String for custom styling
- `contentWrapperClassName`: String for custom styling (not in schema, runtime only)
Loading