@se-studio/project-build 1.0.85 → 1.0.87
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md
CHANGED
package/package.json
CHANGED
|
@@ -77,6 +77,64 @@ const sizes = calculateVisualSizes(1, { laptop: 0.5 });
|
|
|
77
77
|
| 2 cols in 12 on laptop, half on mobile | `(0.5, { laptop: 2/12 })` |
|
|
78
78
|
| Small icon (~96px) | `(0.25)` |
|
|
79
79
|
|
|
80
|
+
### CMS Width & Position (`widthPercent`, `horizontalPosition`)
|
|
81
|
+
|
|
82
|
+
Visuals in Contentful can have a `widthPercent` (e.g. 50%) and `horizontalPosition` (Left / Middle / Right). These control how wide the visual renders on laptop+ and where it aligns within its container. **How these fields are applied depends on the component rendering the visual.**
|
|
83
|
+
|
|
84
|
+
**Key principle**: The `Visual` component is a "fill my container" renderer — it does **not** apply width constraints itself. Width and position are always the responsibility of the wrapping component.
|
|
85
|
+
|
|
86
|
+
#### Which components handle it automatically
|
|
87
|
+
|
|
88
|
+
* **`VisualComponent`** (framework, `@/framework/VisualComponent`): Handles `widthPercent` and `horizontalPosition` in both embedded and non-embedded modes. Also adjusts `visualSizes` so the browser fetches an appropriately sized image.
|
|
89
|
+
* **`ResponsiveVisual`** (core-ui): Wraps the `Visual` in a div that applies `--image-width` and horizontal positioning. Components using `ResponsiveVisual` get this for free.
|
|
90
|
+
|
|
91
|
+
#### Custom components using `Visual` directly
|
|
92
|
+
|
|
93
|
+
If your component renders `Visual` directly and the visual may have a `widthPercent`, you must handle it yourself:
|
|
94
|
+
|
|
95
|
+
1. **Wrap in a positioning div** using helpers from `core-ui`:
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
import { getVisualWidthPercent } from '@se-studio/core-data-types';
|
|
99
|
+
import {
|
|
100
|
+
calculateHorizontalPositionClassName,
|
|
101
|
+
calculateImageWidthStyleVariable,
|
|
102
|
+
calculateVisualSizes,
|
|
103
|
+
Visual,
|
|
104
|
+
cn,
|
|
105
|
+
} from '@se-studio/core-ui';
|
|
106
|
+
|
|
107
|
+
const imageWidthStyle = calculateImageWidthStyleVariable(visual);
|
|
108
|
+
const imageHorizontalPosition = imageWidthStyle
|
|
109
|
+
? calculateHorizontalPositionClassName(visual)
|
|
110
|
+
: undefined;
|
|
111
|
+
|
|
112
|
+
<div
|
|
113
|
+
className={cn(
|
|
114
|
+
'w-full',
|
|
115
|
+
imageHorizontalPosition,
|
|
116
|
+
imageWidthStyle && 'laptop:w-(--image-width)',
|
|
117
|
+
)}
|
|
118
|
+
style={imageWidthStyle}
|
|
119
|
+
>
|
|
120
|
+
<Visual visual={visual} visualSizes={visualSizes} />
|
|
121
|
+
</div>
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
2. **Factor width into `visualSizes`** so the browser doesn't over-fetch:
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
const widthPercent = getVisualWidthPercent(visual);
|
|
128
|
+
const laptopRatio = widthPercent ? widthPercent / 100 : undefined;
|
|
129
|
+
const visualSizes = laptopRatio
|
|
130
|
+
? calculateVisualSizes(1, { laptop: laptopRatio })
|
|
131
|
+
: calculateVisualSizes(1);
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
#### Collections with multiple visuals
|
|
135
|
+
|
|
136
|
+
Collections like `SeparatedVisualsCollection` may interpret `widthPercent` differently — as relative proportions between visuals rather than absolute percentages. The collection controls the layout and passes the computed slot width to `visualSizes`. Don't apply the standard wrapper pattern blindly in collections; match `visualSizes` to the actual rendered slot width.
|
|
137
|
+
|
|
80
138
|
### LCP Optimization (`calculateImagePriority`)
|
|
81
139
|
|
|
82
140
|
For the Hero component (or whatever is at the top of the page), you must prioritize the image load to improve LCP (Largest Contentful Paint).
|