Skip to content

Commit 7978f71

Browse files
NikitaCGNikitaCG
authored
fix: sass version and add memory bank for sub-blocks (#1225)
1 parent 61aaec3 commit 7978f71

File tree

24 files changed

+4784
-387
lines changed

24 files changed

+4784
-387
lines changed

‎memory-bank/storybookComponents.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -76,17 +76,17 @@ The following component in the src/Indents directory has Storybook stories:
7676

7777
The following sub-blocks in the src/sub-blocks directory have Storybook stories:
7878

79-
1. **BackgroundCard**: A sub-block for displaying content with a background.
80-
2. **BasicCard**: A simple card sub-block for displaying content.
81-
3. **Content**: A sub-block for displaying content in a structured format.
82-
4. **Divider**: A sub-block for creating visual dividers between content.
83-
5. **HubspotForm**: A sub-block for integrating Hubspot forms.
84-
6. **ImageCard**: A sub-block for displaying images with card-like styling.
85-
7. **LayoutItem**: A sub-block for creating layout structures.
86-
8. **MediaCard**: A sub-block for displaying media content in a card format.
87-
9. **PriceCard**: A sub-block for displaying pricing information.
88-
10. **PriceDetailed**: A sub-block for displaying detailed pricing information.
89-
11. **Quote**: A sub-block for displaying quotations.
79+
1. **BackgroundCard**: A sub-block for displaying content with a background. ✅ [Usage documented](usage/backgroundCard.md)
80+
2. **BasicCard**: A simple card sub-block for displaying content. ✅ [Usage documented](usage/basicCard.md)
81+
3. **Content**: A sub-block for displaying content in a structured format. ✅ [Usage documented](usage/content.md)
82+
4. **Divider**: A sub-block for creating visual dividers between content. ✅ [Usage documented](usage/divider.md)
83+
5. **HubspotForm**: A sub-block for integrating Hubspot forms. ✅ [Usage documented](usage/hubspotForm.md)
84+
6. **ImageCard**: A sub-block for displaying images with card-like styling. ✅ [Usage documented](usage/imageCard.md)
85+
7. **LayoutItem**: A sub-block for creating layout structures. ✅ [Usage documented](usage/layoutItem.md)
86+
8. **MediaCard**: A sub-block for displaying media content in a card format. ✅ [Usage documented](usage/mediaCard.md)
87+
9. **PriceCard**: A sub-block for displaying pricing information. ✅ [Usage documented](usage/priceCard.md)
88+
10. **PriceDetailed**: A sub-block for displaying detailed pricing information (deprecated). ✅ [Usage documented](usage/priceDetailed.md)
89+
11. **Quote**: A sub-block for displaying quotations. ✅ [Usage documented](usage/quote.md)
9090

9191
### Containers
9292

‎memory-bank/usage/backgroundCard.md‎

Lines changed: 361 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,361 @@
1+
# BackgroundCard Sub-block Usage
2+
3+
This document outlines how the BackgroundCard sub-block is used across blocks, sub-blocks, and components in the page-constructor project.
4+
5+
## Overview
6+
7+
The BackgroundCard sub-block is a versatile component that displays content with a background image or color. It provides a visually appealing way to present information with title, text, additional information, links, buttons, and content lists. The component supports theming options, border styles, and various padding configurations, making it adaptable for different design requirements.
8+
9+
## Usage Graph
10+
11+
```mermaid
12+
graph TD
13+
%% Main Component
14+
BackgroundCard[BackgroundCard Sub-block]
15+
16+
%% Blocks that use BackgroundCard
17+
CardLayout[CardLayout Block]
18+
19+
%% Usage relationships
20+
CardLayout --> BackgroundCard
21+
22+
%% Style classes
23+
style BackgroundCard fill:#f9d77e,stroke:#f9bc02,stroke-width:2px,color:#000
24+
style CardLayout fill:#c6def1,stroke:#2274a5,stroke-width:1px,color:#000
25+
```
26+
27+
## Component Details
28+
29+
### BackgroundCard Sub-block
30+
31+
- **File**: `src/sub-blocks/BackgroundCard/BackgroundCard.tsx`
32+
- **Description**: Displays content with a background image or color, supporting various content elements and theming options.
33+
- **Props**:
34+
- `title`: Card title (required)
35+
- `text`: Card description with YFM support (required)
36+
- `url`: URL that opens when clicking the card
37+
- `urlTitle`: Accessible title for the URL
38+
- `border`: Border style - 'line', 'shadow', or 'none'
39+
- `background`: Background image with theme support
40+
- `backgroundColor`: Background color
41+
- `paddingBottom`: Space between the text and the bottom of the card - 's', 'm', 'l', or 'xl'
42+
- `additionalInfo`: Additional information text with YFM support
43+
- `theme`: Content theme - 'default', 'dark', or 'light'
44+
- `links`: Array of link objects
45+
- `buttons`: Array of button objects
46+
- `analyticsEvents`: Analytics events to track
47+
- `controlPosition`: Position of controls (links and buttons) - 'content' or 'footer'
48+
- `list`: Array of content list items
49+
50+
## Usage Patterns
51+
52+
> **Note**: In the code examples below, `b()` is a utility function used throughout the page-constructor project for BEM (Block Element Modifier) class naming. It generates CSS class names following the BEM methodology, making the code more maintainable and consistent.
53+
54+
### In Blocks
55+
56+
#### CardLayout Block
57+
58+
- **File**: `src/blocks/CardLayout/CardLayout.tsx`
59+
- **Usage**: Used as a child component within the CardLayout block to display cards with background images or colors.
60+
- **Implementation**:
61+
```tsx
62+
<CardLayout title={title} description={description} colSizes={colSizes}>
63+
<BackgroundCard
64+
title="Tell a story and build a narrative"
65+
text="We are all storytellers. Stories are a powerful way to communicate ideas and share information."
66+
background={{
67+
light: {
68+
src: '/path/to/light-image.png',
69+
alt: 'Background image',
70+
disableCompress: true,
71+
},
72+
dark: {
73+
src: '/path/to/dark-image.png',
74+
alt: 'Background image',
75+
},
76+
}}
77+
/>
78+
{/* Other cards */}
79+
</CardLayout>
80+
```
81+
82+
## Component Structure
83+
84+
The BackgroundCard component is composed of several key parts:
85+
86+
1. **CardBase**: Provides the base card functionality including border styles and URL handling
87+
2. **BackgroundImage**: Renders the background image with theme support
88+
3. **Content**: Displays the card content including title, text, additional info, links, buttons, and content list
89+
90+
### Internal Structure
91+
92+
```tsx
93+
<CardBase
94+
className={b({padding: paddingBottom, theme: cardTheme})}
95+
contentClassName={b('content')}
96+
url={url}
97+
border={borderType}
98+
analyticsEvents={analyticsEvents}
99+
urlTitle={urlTitle}
100+
>
101+
<CardBase.Content>
102+
<BackgroundImage
103+
className={b('image')}
104+
{...getThemedValue(background, theme)}
105+
style={{backgroundColor}}
106+
/>
107+
<Content
108+
titleId={titleId}
109+
title={title}
110+
text={text}
111+
additionalInfo={additionalInfo}
112+
size="s"
113+
theme={cardTheme}
114+
links={links}
115+
buttons={buttons}
116+
list={list}
117+
colSizes={{all: 12, md: 12}}
118+
controlPosition={areControlsInFooter ? 'bottom' : 'default'}
119+
/>
120+
</CardBase.Content>
121+
</CardBase>
122+
```
123+
124+
## Theming Support
125+
126+
The BackgroundCard component supports theming through the `theme` prop:
127+
128+
### Default Theme
129+
130+
- Uses standard text colors
131+
- Default background and border styles
132+
133+
### Dark Theme
134+
135+
- Uses light text colors on dark backgrounds
136+
- Suitable for dark backgrounds or images
137+
- Applied via `.background-card_theme_dark` class
138+
139+
### Light Theme
140+
141+
- Uses dark text colors on light backgrounds
142+
- Suitable for light backgrounds or images
143+
- Applied via `.background-card_theme_light` class
144+
145+
## Background Handling
146+
147+
The component supports flexible background input:
148+
149+
### Background Image
150+
151+
```tsx
152+
// Themed background image
153+
background: {
154+
light: {
155+
src: "/path/to/light-image.png",
156+
alt: "Background image",
157+
disableCompress: true
158+
},
159+
dark: {
160+
src: "/path/to/dark-image.png",
161+
alt: "Background image"
162+
}
163+
}
164+
```
165+
166+
### Background Color
167+
168+
```tsx
169+
// Background color
170+
backgroundColor: '#7ccea0';
171+
```
172+
173+
## Padding Options
174+
175+
The component supports different padding bottom values:
176+
177+
- `s`: Small padding
178+
- `m`: Medium padding
179+
- `l`: Large padding
180+
- `xl`: Extra large padding
181+
182+
## Control Position
183+
184+
The component supports two positions for controls (links and buttons):
185+
186+
- `content`: Controls are placed within the content area
187+
- `footer`: Controls are placed at the bottom of the card (only works when paddingBottom is not set)
188+
189+
## Integration with Theme System
190+
191+
The BackgroundCard component integrates with the page-constructor theme system:
192+
193+
1. **Theme Processing**: Uses `getThemedValue()` utility to resolve themed backgrounds
194+
2. **Image Processing**: Uses `BackgroundImage` component to handle background images
195+
3. **Content Theming**: Passes theme to the Content component for consistent styling
196+
4. **Theme Context**: Respects the global theme context for consistent styling
197+
198+
## Best Practices
199+
200+
1. **Background Selection**: Choose appropriate background images or colors that provide good contrast with the text.
201+
202+
2. **Content Structure**: Provide meaningful titles and descriptions for accessibility.
203+
204+
3. **Theme Selection**:
205+
206+
- Use `default` theme for standard cards
207+
- Use `dark` theme for cards with dark backgrounds
208+
- Use `light` theme for cards with light backgrounds
209+
210+
4. **Border Usage**:
211+
212+
- Use `line` border for subtle separation
213+
- Use `shadow` border for elevated appearance
214+
- Use `none` border for seamless integration
215+
216+
5. **Padding Selection**:
217+
218+
- Use appropriate padding based on content length and design requirements
219+
- Consider using larger padding for cards with more content
220+
221+
6. **Control Position**:
222+
- Use `content` position for standard layout
223+
- Use `footer` position for cards where controls should be aligned at the bottom
224+
225+
## Example Usage
226+
227+
### Basic BackgroundCard
228+
229+
```tsx
230+
<BackgroundCard
231+
title="Lorem ipsum"
232+
text="**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
233+
additionalInfo="Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur."
234+
/>
235+
```
236+
237+
### With Background Image
238+
239+
```tsx
240+
<BackgroundCard
241+
title="Lorem ipsum"
242+
text="**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
243+
background={{
244+
light: {
245+
src: '/path/to/light-image.png',
246+
alt: 'Background image',
247+
disableCompress: true,
248+
},
249+
dark: {
250+
src: '/path/to/dark-image.png',
251+
alt: 'Background image',
252+
},
253+
}}
254+
/>
255+
```
256+
257+
### With Links and Buttons
258+
259+
```tsx
260+
<BackgroundCard
261+
title="Lorem ipsum"
262+
text="**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
263+
links={[
264+
{
265+
url: 'https://example.com',
266+
text: 'Link',
267+
theme: 'normal',
268+
arrow: true,
269+
},
270+
]}
271+
buttons={[
272+
{
273+
text: 'Button',
274+
theme: 'action',
275+
url: 'https://example.com',
276+
},
277+
{
278+
text: 'Button',
279+
theme: 'outlined',
280+
url: 'https://example.com',
281+
},
282+
]}
283+
/>
284+
```
285+
286+
### With Content List
287+
288+
```tsx
289+
<BackgroundCard
290+
title="Lorem ipsum"
291+
text="**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
292+
list={[
293+
{
294+
icon: {
295+
light: '/path/to/icon-light.svg',
296+
dark: '/path/to/icon-dark.svg',
297+
},
298+
title: 'Lorem ipsum',
299+
text: '**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation.',
300+
},
301+
{
302+
icon: {
303+
light: '/path/to/icon-light.svg',
304+
dark: '/path/to/icon-dark.svg',
305+
},
306+
text: '**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation.',
307+
},
308+
]}
309+
/>
310+
```
311+
312+
### With Dark Theme and Background Color
313+
314+
```tsx
315+
<BackgroundCard
316+
title="Lorem ipsum"
317+
text="**Ut enim ad minim veniam** [quis nostrud](https://example.com) exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
318+
backgroundColor="#7ccea0"
319+
theme="dark"
320+
buttons={[
321+
{
322+
text: 'Button',
323+
theme: 'normal-contrast',
324+
url: 'https://example.com',
325+
},
326+
{
327+
text: 'Button',
328+
theme: 'outlined-contrast',
329+
url: 'https://example.com',
330+
},
331+
]}
332+
/>
333+
```
334+
335+
## Storybook Documentation
336+
337+
The BackgroundCard component includes Storybook stories demonstrating:
338+
339+
- Default card display
340+
- Various content configurations (with/without links, buttons, content list)
341+
- Different background options (image, color)
342+
- Padding variations
343+
- Theme variations
344+
- Border styles
345+
- URL handling
346+
- Control positioning
347+
348+
Stories are located in `src/sub-blocks/BackgroundCard/__stories__/BackgroundCard.stories.tsx` with example data in `data.json`.
349+
350+
## Testing
351+
352+
The BackgroundCard component includes comprehensive visual tests covering:
353+
354+
- Default rendering with various content configurations
355+
- Background image and color rendering
356+
- Theme application
357+
- Border styles
358+
- Padding variations
359+
- Control positioning
360+
361+
Test files are located in `src/sub-blocks/BackgroundCard/__tests__/BackgroundCard.visual.test.tsx`.

0 commit comments

Comments
 (0)