spoko-design-system 1.11.0 → 1.11.2
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
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
## [1.11.2](https://github.com/polo-blue/sds/compare/v1.11.1...v1.11.2) (2025-10-30)
|
|
2
|
+
|
|
3
|
+
## [1.11.1](https://github.com/polo-blue/sds/compare/v1.11.0...v1.11.1) (2025-10-30)
|
|
4
|
+
|
|
5
|
+
### Bug Fixes
|
|
6
|
+
|
|
7
|
+
* **ProductEngine:** remove manual quote escaping causing double-encoding ([dfa196d](https://github.com/polo-blue/sds/commit/dfa196d812cd40e1b476bd28d814d2b158449d3c))
|
|
8
|
+
|
|
1
9
|
## [1.11.0](https://github.com/polo-blue/sds/compare/v1.10.0...v1.11.0) (2025-10-30)
|
|
2
10
|
|
|
3
11
|
### Features
|
package/TOOLTIPS.md
ADDED
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
# Tooltip System Documentation
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
SDS includes a complete tooltip system built on [Tippy.js](https://atomiks.github.io/tippyjs/) with custom styling and automatic initialization.
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- 🎨 Custom SDS theme matching design system colors
|
|
10
|
+
- ⚡ Performance-optimized delegation pattern
|
|
11
|
+
- 🔄 Automatic support for Astro View Transitions
|
|
12
|
+
- 🎯 Simple data-attribute API
|
|
13
|
+
- 📦 All dependencies bundled (no need to install tippy.js separately)
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
**Option 1: Automatic initialization (recommended)**
|
|
18
|
+
|
|
19
|
+
Import the complete tooltip system in your layout's script tag:
|
|
20
|
+
|
|
21
|
+
```astro
|
|
22
|
+
---
|
|
23
|
+
// In your BaseLayout.astro or HeadCommon.astro
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
<head>
|
|
27
|
+
<!-- ... other head elements -->
|
|
28
|
+
<script src="/src/scripts/tooltips.ts"></script>
|
|
29
|
+
</head>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
// In your /src/scripts/tooltips.ts
|
|
34
|
+
import 'spoko-design-system/scripts/tooltips';
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**Option 2: Manual initialization**
|
|
38
|
+
|
|
39
|
+
If you need more control:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { initTooltips } from 'spoko-design-system';
|
|
43
|
+
|
|
44
|
+
// Initialize tooltips manually
|
|
45
|
+
initTooltips();
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Usage
|
|
49
|
+
|
|
50
|
+
Add tooltips to any element using the `data-tippy-content` attribute:
|
|
51
|
+
|
|
52
|
+
```astro
|
|
53
|
+
<span data-tippy-content="This is a tooltip">
|
|
54
|
+
Hover over me
|
|
55
|
+
</span>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### With HTML content
|
|
59
|
+
|
|
60
|
+
```astro
|
|
61
|
+
<span data-tippy-content="<strong>Bold text</strong> and <em>italic</em>">
|
|
62
|
+
Rich tooltip
|
|
63
|
+
</span>
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Structured tooltips (like engine codes)
|
|
67
|
+
|
|
68
|
+
The system supports structured tooltips with headers and specs:
|
|
69
|
+
|
|
70
|
+
```astro
|
|
71
|
+
<span
|
|
72
|
+
class="engine-code"
|
|
73
|
+
data-tippy-content={tooltipHTML}
|
|
74
|
+
>
|
|
75
|
+
CAYA
|
|
76
|
+
</span>
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Where `tooltipHTML` can be generated using:
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
import { getEngineTooltipContent } from 'spoko-design-system';
|
|
83
|
+
|
|
84
|
+
const tooltipHTML = getEngineTooltipContent(engine, translations);
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Components with built-in tooltips
|
|
88
|
+
|
|
89
|
+
These SDS components automatically include tooltip functionality:
|
|
90
|
+
|
|
91
|
+
- `<ProductEngine>` - Engine codes with detailed specs
|
|
92
|
+
- `<ProductEngines>` - List of engine codes
|
|
93
|
+
- `<ProductCodes>` - PR codes (when descriptions are available)
|
|
94
|
+
|
|
95
|
+
## Styling
|
|
96
|
+
|
|
97
|
+
The tooltip theme uses SDS design tokens:
|
|
98
|
+
|
|
99
|
+
- Background: `neutral-lightest` (#f3f4f6)
|
|
100
|
+
- Text: `slate-darkest` (#1e293b)
|
|
101
|
+
- Border: `neutral-lighter` (#e5e7eb)
|
|
102
|
+
- Header (engine tooltips): `accent-deepBlue` (#001e50)
|
|
103
|
+
|
|
104
|
+
To customize, override the `.tippy-box[data-theme~='sds']` class in your project.
|
|
105
|
+
|
|
106
|
+
## Dependencies
|
|
107
|
+
|
|
108
|
+
SDS includes `tippy.js` as a dependency, so your project **does not need to install it separately**.
|
|
109
|
+
|
|
110
|
+
If your project already has `tippy.js` installed, you can safely remove it:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
pnpm remove tippy.js
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Technical Details
|
|
117
|
+
|
|
118
|
+
### Delegation Pattern
|
|
119
|
+
|
|
120
|
+
The tooltip system uses Tippy.js's delegation pattern for optimal performance:
|
|
121
|
+
|
|
122
|
+
- Single event listener on `body`
|
|
123
|
+
- Targets all `[data-tippy-content]` elements
|
|
124
|
+
- No need to re-initialize when DOM changes
|
|
125
|
+
- Works with dynamically added content
|
|
126
|
+
|
|
127
|
+
### Astro View Transitions
|
|
128
|
+
|
|
129
|
+
The system automatically re-initializes on Astro page navigation:
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
document.addEventListener('astro:page-load', () => {
|
|
133
|
+
initTooltips();
|
|
134
|
+
});
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Configuration
|
|
138
|
+
|
|
139
|
+
Default configuration (in `src/scripts/tooltips.ts`):
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
{
|
|
143
|
+
target: '[data-tippy-content]',
|
|
144
|
+
allowHTML: true,
|
|
145
|
+
theme: 'sds',
|
|
146
|
+
placement: 'top',
|
|
147
|
+
arrow: true,
|
|
148
|
+
animation: 'shift-away',
|
|
149
|
+
duration: [200, 150],
|
|
150
|
+
maxWidth: 280
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## Troubleshooting
|
|
155
|
+
|
|
156
|
+
### Tooltips not showing
|
|
157
|
+
|
|
158
|
+
1. Verify the script is imported in your layout
|
|
159
|
+
2. Check that elements have `data-tippy-content` attribute
|
|
160
|
+
3. Ensure content is not empty or "undefined"
|
|
161
|
+
4. Check browser console for errors
|
|
162
|
+
|
|
163
|
+
### Double tooltips or conflicts
|
|
164
|
+
|
|
165
|
+
If you see duplicate tooltips:
|
|
166
|
+
|
|
167
|
+
1. Make sure you're only importing the tooltip script once
|
|
168
|
+
2. Don't call `initTooltips()` manually if using auto-initialization
|
|
169
|
+
3. Remove any local tippy.js installations that might conflict
|
|
170
|
+
|
|
171
|
+
### Styling not applied
|
|
172
|
+
|
|
173
|
+
1. Verify SDS theme CSS is imported (included in script import)
|
|
174
|
+
2. Check CSS specificity - SDS uses `!important` for some properties
|
|
175
|
+
3. Ensure your build process handles CSS imports from node_modules
|
|
176
|
+
|
|
177
|
+
## Examples
|
|
178
|
+
|
|
179
|
+
### Basic tooltip
|
|
180
|
+
|
|
181
|
+
```astro
|
|
182
|
+
<button data-tippy-content="Click to save">
|
|
183
|
+
Save
|
|
184
|
+
</button>
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Engine code tooltip
|
|
188
|
+
|
|
189
|
+
```astro
|
|
190
|
+
---
|
|
191
|
+
import { ProductEngine } from 'spoko-design-system';
|
|
192
|
+
|
|
193
|
+
const engine = {
|
|
194
|
+
code: 'CAYA',
|
|
195
|
+
name: '1.6 TDI',
|
|
196
|
+
power: { kw: 55, ps: 75, ps_label: 'PS', label: 'Power' },
|
|
197
|
+
displacement: { value: 1598, label: 'Displacement' },
|
|
198
|
+
euro: { value: 5, label: 'Standard' }
|
|
199
|
+
};
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
<ProductEngine engine={engine} />
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Custom structured tooltip
|
|
206
|
+
|
|
207
|
+
```astro
|
|
208
|
+
<span data-tippy-content={`
|
|
209
|
+
<div class="tooltip-header">
|
|
210
|
+
<strong>Custom Header</strong>
|
|
211
|
+
</div>
|
|
212
|
+
<div class="tooltip-specs">
|
|
213
|
+
<div class="tooltip-row">
|
|
214
|
+
<span class="tooltip-label">Label:</span>
|
|
215
|
+
<span class="tooltip-value">Value</span>
|
|
216
|
+
</div>
|
|
217
|
+
</div>
|
|
218
|
+
`}>
|
|
219
|
+
Custom tooltip
|
|
220
|
+
</span>
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Migration from standalone Tippy.js
|
|
224
|
+
|
|
225
|
+
If migrating from a direct Tippy.js implementation:
|
|
226
|
+
|
|
227
|
+
1. Remove `tippy.js` from package.json
|
|
228
|
+
2. Remove local tooltip initialization code
|
|
229
|
+
3. Import SDS tooltip script: `import 'spoko-design-system/scripts/tooltips'`
|
|
230
|
+
4. Update elements to use `data-tippy-content` instead of manual initialization
|
|
231
|
+
5. Update custom styles to target `.tippy-box[data-theme~='sds']`
|
|
232
|
+
|
|
233
|
+
## Support
|
|
234
|
+
|
|
235
|
+
For issues or feature requests, please open an issue at:
|
|
236
|
+
https://github.com/polo-blue/sds/issues
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spoko-design-system",
|
|
3
|
-
"version": "1.11.
|
|
3
|
+
"version": "1.11.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"private": false,
|
|
6
6
|
"main": "./index.ts",
|
|
@@ -128,7 +128,7 @@
|
|
|
128
128
|
"@vitejs/plugin-vue": "^6.0.1",
|
|
129
129
|
"@vue/compiler-sfc": "^3.5.22",
|
|
130
130
|
"@vue/eslint-config-typescript": "^14.6.0",
|
|
131
|
-
"astro": "^5.15.
|
|
131
|
+
"astro": "^5.15.3",
|
|
132
132
|
"conventional-changelog-conventionalcommits": "^9.1.0",
|
|
133
133
|
"eslint": "^9.38.0",
|
|
134
134
|
"eslint-plugin-astro": "^1.4.0",
|
|
@@ -19,16 +19,9 @@ const { engine, showComma = false, translations = {} } = Astro.props;
|
|
|
19
19
|
|
|
20
20
|
// Generate tooltip content for data attribute
|
|
21
21
|
const tooltipContent = getEngineTooltipContent(engine, translations);
|
|
22
|
-
|
|
23
|
-
// Escape quotes for HTML attribute
|
|
24
|
-
const tooltipContentEscaped = tooltipContent.replace(/"/g, '"');
|
|
25
22
|
---
|
|
26
23
|
|
|
27
|
-
<span
|
|
28
|
-
class="engine-code"
|
|
29
|
-
class:list={[`engine-code-${engine.code}`]}
|
|
30
|
-
data-tippy-content={tooltipContentEscaped}
|
|
31
|
-
>
|
|
24
|
+
<span class="engine-code" class:list={[`engine-code-${engine.code}`]} data-tippy-content={tooltipContent}>
|
|
32
25
|
{engine.code}{showComma && ','}
|
|
33
26
|
</span>
|
|
34
27
|
|
|
@@ -204,6 +204,7 @@ When using data from the API, pass the `pr_codes` array directly:
|
|
|
204
204
|
|
|
205
205
|
## Notes
|
|
206
206
|
|
|
207
|
+
- **Tooltip setup required**: Import `'spoko-design-system/scripts/tooltips'` once in your layout (see [Tooltips documentation](/core/tooltips))
|
|
207
208
|
- Hover over any PR code to see its full description
|
|
208
209
|
- Colors are based on semantic variant categories, not hardcoded per code
|
|
209
210
|
- Combined codes are displayed as `CODE+CODE` with each code colored independently
|
|
@@ -25,18 +25,28 @@ Display a single engine code with tooltip showing detailed engine information.
|
|
|
25
25
|
import { ProductEngine } from 'spoko-design-system'
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
**2. Initialize tooltips
|
|
28
|
+
**2. Initialize tooltips (one-time setup):**
|
|
29
|
+
|
|
30
|
+
Create a tooltip script in your project:
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
// src/scripts/tooltips.ts
|
|
34
|
+
import 'spoko-design-system/scripts/tooltips';
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Then import it in your layout's `<head>`:
|
|
29
38
|
|
|
30
39
|
```astro
|
|
31
40
|
---
|
|
32
|
-
// In your layout file (e.g.,
|
|
41
|
+
// In your layout file (e.g., HeadCommon.astro)
|
|
33
42
|
---
|
|
34
|
-
<
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
</script>
|
|
43
|
+
<head>
|
|
44
|
+
<script src="/src/scripts/tooltips.ts"></script>
|
|
45
|
+
</head>
|
|
38
46
|
```
|
|
39
47
|
|
|
48
|
+
See [Tooltips documentation](/core/tooltips) for details.
|
|
49
|
+
|
|
40
50
|
### Basic Usage (New API Structure):
|
|
41
51
|
|
|
42
52
|
<div class="component-preview">
|
|
@@ -47,7 +57,7 @@ import { ProductEngine } from 'spoko-design-system'
|
|
|
47
57
|
serie: { value: "EA189", label: "Seria silnika" },
|
|
48
58
|
power: { kw: 55, ps: 75, ps_label: "KM", label: "Moc" },
|
|
49
59
|
displacement: { value: 1598, label: "Pojemność" },
|
|
50
|
-
euro: { value: 5, label: "Norma
|
|
60
|
+
euro: { value: 5, label: "Norma" }
|
|
51
61
|
}} />
|
|
52
62
|
<ProductEngine engine={{
|
|
53
63
|
code: "CAYB",
|
|
@@ -55,7 +65,7 @@ import { ProductEngine } from 'spoko-design-system'
|
|
|
55
65
|
serie: { value: "EA189", label: "Seria silnika" },
|
|
56
66
|
power: { kw: 66, ps: 90, ps_label: "KM", label: "Moc" },
|
|
57
67
|
displacement: { value: 1598, label: "Pojemność" },
|
|
58
|
-
euro: { value: 5, label: "Norma
|
|
68
|
+
euro: { value: 5, label: "Norma" }
|
|
59
69
|
}} />
|
|
60
70
|
</div>
|
|
61
71
|
</div>
|
|
@@ -95,7 +105,7 @@ Engine codes for special editions are automatically color-coded:
|
|
|
95
105
|
name: "1.4 TSI",
|
|
96
106
|
power: { kw: 132, ps: 180, ps_label: "KM", label: "Moc" },
|
|
97
107
|
displacement: { value: 1390, label: "Pojemność" },
|
|
98
|
-
euro: { value: 5, label: "Norma
|
|
108
|
+
euro: { value: 5, label: "Norma " }
|
|
99
109
|
}} />
|
|
100
110
|
</div>
|
|
101
111
|
<div class="flex flex-col gap-1">
|
|
@@ -105,7 +115,7 @@ Engine codes for special editions are automatically color-coded:
|
|
|
105
115
|
name: "1.6 TDI",
|
|
106
116
|
power: { kw: 165, ps: 220, ps_label: "KM", label: "Moc" },
|
|
107
117
|
displacement: { value: 1598, label: "Pojemność" },
|
|
108
|
-
euro: { value: 6, label: "Norma
|
|
118
|
+
euro: { value: 6, label: "Norma " }
|
|
109
119
|
}} />
|
|
110
120
|
</div>
|
|
111
121
|
<div class="flex flex-col gap-1">
|
|
@@ -115,7 +125,7 @@ Engine codes for special editions are automatically color-coded:
|
|
|
115
125
|
name: "1.0 TSI",
|
|
116
126
|
power: { kw: 70, ps: 95, ps_label: "KM", label: "Moc" },
|
|
117
127
|
displacement: { value: 999, label: "Pojemność" },
|
|
118
|
-
euro: { value: 6, label: "Norma
|
|
128
|
+
euro: { value: 6, label: "Norma " }
|
|
119
129
|
}} />
|
|
120
130
|
</div>
|
|
121
131
|
</div>
|
|
@@ -128,7 +138,7 @@ Engine codes for special editions are automatically color-coded:
|
|
|
128
138
|
name: '1.4 TSI',
|
|
129
139
|
power: { kw: 132, ps: 180, ps_label: 'KM', label: 'Moc' },
|
|
130
140
|
displacement: { value: 1390, label: 'Pojemność' },
|
|
131
|
-
euro: { value: 5, label: 'Norma
|
|
141
|
+
euro: { value: 5, label: 'Norma ' }
|
|
132
142
|
}} />
|
|
133
143
|
|
|
134
144
|
<!-- WRC Engine - Blue -->
|
|
@@ -137,7 +147,7 @@ Engine codes for special editions are automatically color-coded:
|
|
|
137
147
|
name: '1.6 TDI',
|
|
138
148
|
power: { kw: 165, ps: 220, ps_label: 'KM', label: 'Moc' },
|
|
139
149
|
displacement: { value: 1598, label: 'Pojemność' },
|
|
140
|
-
euro: { value: 6, label: 'Norma
|
|
150
|
+
euro: { value: 6, label: 'Norma ' }
|
|
141
151
|
}} />
|
|
142
152
|
```
|
|
143
153
|
|
|
@@ -163,7 +173,7 @@ import { ProductEngines } from 'spoko-design-system'
|
|
|
163
173
|
serie: { value: "EA189", label: "Seria silnika" },
|
|
164
174
|
power: { kw: 55, ps: 75, ps_label: "KM", label: "Moc" },
|
|
165
175
|
displacement: { value: 1598, label: "Pojemność" },
|
|
166
|
-
euro: { value: 5, label: "Norma
|
|
176
|
+
euro: { value: 5, label: "Norma " }
|
|
167
177
|
},
|
|
168
178
|
{
|
|
169
179
|
id: 14,
|
|
@@ -172,7 +182,7 @@ import { ProductEngines } from 'spoko-design-system'
|
|
|
172
182
|
serie: { value: "EA189", label: "Seria silnika" },
|
|
173
183
|
power: { kw: 66, ps: 90, ps_label: "KM", label: "Moc" },
|
|
174
184
|
displacement: { value: 1598, label: "Pojemność" },
|
|
175
|
-
euro: { value: 5, label: "Norma
|
|
185
|
+
euro: { value: 5, label: "Norma " }
|
|
176
186
|
},
|
|
177
187
|
{
|
|
178
188
|
id: 15,
|
|
@@ -181,7 +191,7 @@ import { ProductEngines } from 'spoko-design-system'
|
|
|
181
191
|
serie: { value: "EA189", label: "Seria silnika" },
|
|
182
192
|
power: { kw: 77, ps: 105, ps_label: "KM", label: "Moc" },
|
|
183
193
|
displacement: { value: 1598, label: "Pojemność" },
|
|
184
|
-
euro: { value: 5, label: "Norma
|
|
194
|
+
euro: { value: 5, label: "Norma " }
|
|
185
195
|
},
|
|
186
196
|
]} />
|
|
187
197
|
</div>
|
|
@@ -200,7 +210,7 @@ import { ProductEngines } from 'spoko-design-system';
|
|
|
200
210
|
serie: { value: 'EA189', label: 'Seria silnika' },
|
|
201
211
|
power: { kw: 55, ps: 75, ps_label: 'KM', label: 'Moc' },
|
|
202
212
|
displacement: { value: 1598, label: 'Pojemność' },
|
|
203
|
-
euro: { value: 5, label: 'Norma
|
|
213
|
+
euro: { value: 5, label: 'Norma ' }
|
|
204
214
|
},
|
|
205
215
|
{
|
|
206
216
|
id: 14,
|
|
@@ -209,7 +219,7 @@ import { ProductEngines } from 'spoko-design-system';
|
|
|
209
219
|
serie: { value: 'EA189', label: 'Seria silnika' },
|
|
210
220
|
power: { kw: 66, ps: 90, ps_label: 'KM', label: 'Moc' },
|
|
211
221
|
displacement: { value: 1598, label: 'Pojemność' },
|
|
212
|
-
euro: { value: 5, label: 'Norma
|
|
222
|
+
euro: { value: 5, label: 'Norma ' }
|
|
213
223
|
}
|
|
214
224
|
]} />
|
|
215
225
|
```
|
|
@@ -271,7 +281,7 @@ When using data from the API, pass the `part_engines` array directly. The compon
|
|
|
271
281
|
"euro": {
|
|
272
282
|
"value": 5,
|
|
273
283
|
"formatted": "Norma Euro 5",
|
|
274
|
-
"label": "Norma
|
|
284
|
+
"label": "Norma "
|
|
275
285
|
}
|
|
276
286
|
},
|
|
277
287
|
{
|
|
@@ -313,7 +323,7 @@ When using data from the API, pass the `part_engines` array directly. The compon
|
|
|
313
323
|
"euro": {
|
|
314
324
|
"value": 5,
|
|
315
325
|
"formatted": "Norma Euro 5",
|
|
316
|
-
"label": "Norma
|
|
326
|
+
"label": "Norma "
|
|
317
327
|
}
|
|
318
328
|
}
|
|
319
329
|
]
|
|
@@ -385,7 +395,7 @@ Special engine codes are automatically color-coded:
|
|
|
385
395
|
|
|
386
396
|
## Notes
|
|
387
397
|
|
|
388
|
-
- **Setup required**:
|
|
398
|
+
- **Setup required**: Import `'spoko-design-system/scripts/tooltips'` once in your layout (see [Tooltips docs](/core/tooltips))
|
|
389
399
|
- Hover over any engine code to see full specifications in a detailed tooltip
|
|
390
400
|
- Tooltips use Tippy.js delegation pattern (one global handler for all tooltips)
|
|
391
401
|
- **Performance**: No client-side hydration needed - pure Astro components
|
|
@@ -403,12 +413,6 @@ Special engine codes are automatically color-coded:
|
|
|
403
413
|
If upgrading from the old Vue version:
|
|
404
414
|
|
|
405
415
|
1. **Remove `client:load`** directive from all ProductEngine/ProductEngines usage
|
|
406
|
-
2. **
|
|
407
|
-
```astro
|
|
408
|
-
<script>
|
|
409
|
-
import { initTooltips } from 'spoko-design-system';
|
|
410
|
-
initTooltips();
|
|
411
|
-
</script>
|
|
412
|
-
```
|
|
416
|
+
2. **Set up tooltips** in your layout (see [Tooltips documentation](/core/tooltips))
|
|
413
417
|
3. **Update imports** to use Astro components (automatically handled by package exports)
|
|
414
418
|
4. **No other changes needed** - props and API structure remain the same
|
|
@@ -0,0 +1,491 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Tooltips"
|
|
3
|
+
layout: "../../layouts/MainLayout.astro"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Tooltips
|
|
7
|
+
|
|
8
|
+
A complete tooltip system built on [Tippy.js](https://atomiks.github.io/tippyjs/) with custom SDS styling and automatic initialization.
|
|
9
|
+
|
|
10
|
+
## Features
|
|
11
|
+
|
|
12
|
+
- 🎨 **Custom SDS Theme** - Matches design system colors
|
|
13
|
+
- ⚡ **Performance Optimized** - Delegation pattern handles thousands of tooltips efficiently
|
|
14
|
+
- 🔄 **Astro View Transitions** - Automatic re-initialization on navigation
|
|
15
|
+
- 🎯 **Simple API** - Just add a data attribute
|
|
16
|
+
- 📦 **Bundled** - No need to install tippy.js separately in your project
|
|
17
|
+
- 🔍 **SEO Friendly** - Content rendered in HTML, enhanced progressively
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
### Step 1: Create a tooltip initialization script
|
|
22
|
+
|
|
23
|
+
In your project, create a script file (e.g., `src/scripts/tooltips.ts`):
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
// src/scripts/tooltips.ts
|
|
27
|
+
import 'spoko-design-system/scripts/tooltips';
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
That's it! This single import includes:
|
|
31
|
+
- ✅ Tippy.js library
|
|
32
|
+
- ✅ Base Tippy.js CSS
|
|
33
|
+
- ✅ SDS custom theme CSS
|
|
34
|
+
- ✅ Auto-initialization logic
|
|
35
|
+
- ✅ Astro View Transitions support
|
|
36
|
+
|
|
37
|
+
### Step 2: Import in your layout
|
|
38
|
+
|
|
39
|
+
Add the script to your main layout's `<head>`:
|
|
40
|
+
|
|
41
|
+
```astro
|
|
42
|
+
---
|
|
43
|
+
// src/layouts/BaseLayout.astro or HeadCommon.astro
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
<head>
|
|
47
|
+
<!-- ... other head elements -->
|
|
48
|
+
<script src="/src/scripts/tooltips.ts"></script>
|
|
49
|
+
</head>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Usage
|
|
53
|
+
|
|
54
|
+
### Basic Tooltip
|
|
55
|
+
|
|
56
|
+
Add the `data-tippy-content` attribute to any element:
|
|
57
|
+
|
|
58
|
+
<div class="component-preview">
|
|
59
|
+
<div class="bg-white p-6 w-full">
|
|
60
|
+
<button
|
|
61
|
+
class="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
|
|
62
|
+
data-tippy-content="This is a basic tooltip">
|
|
63
|
+
Hover over me
|
|
64
|
+
</button>
|
|
65
|
+
</div>
|
|
66
|
+
</div>
|
|
67
|
+
|
|
68
|
+
```astro
|
|
69
|
+
<button data-tippy-content="This is a basic tooltip">
|
|
70
|
+
Hover over me
|
|
71
|
+
</button>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### HTML Content
|
|
75
|
+
|
|
76
|
+
Tooltips support HTML content:
|
|
77
|
+
|
|
78
|
+
<div class="component-preview">
|
|
79
|
+
<div class="bg-white p-6 w-full">
|
|
80
|
+
<span
|
|
81
|
+
class="underline decoration-dotted cursor-help"
|
|
82
|
+
data-tippy-content="<strong>Bold text</strong> and <em>italic text</em>">
|
|
83
|
+
HTML tooltip
|
|
84
|
+
</span>
|
|
85
|
+
</div>
|
|
86
|
+
</div>
|
|
87
|
+
|
|
88
|
+
```astro
|
|
89
|
+
<span data-tippy-content="<strong>Bold text</strong> and <em>italic text</em>">
|
|
90
|
+
HTML tooltip
|
|
91
|
+
</span>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Structured Tooltips
|
|
95
|
+
|
|
96
|
+
For complex tooltips with headers and multiple sections:
|
|
97
|
+
|
|
98
|
+
<div class="component-preview">
|
|
99
|
+
<div class="bg-white p-6 w-full">
|
|
100
|
+
<span
|
|
101
|
+
class="underline decoration-dotted cursor-help text-blue-600"
|
|
102
|
+
data-tippy-content='<div class="tooltip-header"><strong>Product Details</strong></div><div class="tooltip-specs"><div class="tooltip-row"><span class="tooltip-label">SKU:</span><span class="tooltip-value">12345</span></div><div class="tooltip-row"><span class="tooltip-label">Weight:</span><span class="tooltip-value">2.5 kg</span></div></div>'>
|
|
103
|
+
Product Info
|
|
104
|
+
</span>
|
|
105
|
+
</div>
|
|
106
|
+
</div>
|
|
107
|
+
|
|
108
|
+
```astro
|
|
109
|
+
<span data-tippy-content={`
|
|
110
|
+
<div class="tooltip-header">
|
|
111
|
+
<strong>Product Details</strong>
|
|
112
|
+
</div>
|
|
113
|
+
<div class="tooltip-specs">
|
|
114
|
+
<div class="tooltip-row">
|
|
115
|
+
<span class="tooltip-label">SKU:</span>
|
|
116
|
+
<span class="tooltip-value">12345</span>
|
|
117
|
+
</div>
|
|
118
|
+
<div class="tooltip-row">
|
|
119
|
+
<span class="tooltip-label">Weight:</span>
|
|
120
|
+
<span class="tooltip-value">2.5 kg</span>
|
|
121
|
+
</div>
|
|
122
|
+
</div>
|
|
123
|
+
`}>
|
|
124
|
+
Product Info
|
|
125
|
+
</span>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Components with Built-in Tooltips
|
|
129
|
+
|
|
130
|
+
These SDS components automatically include tooltips:
|
|
131
|
+
|
|
132
|
+
### ProductEngine & ProductEngines
|
|
133
|
+
|
|
134
|
+
Engine codes with detailed specification tooltips:
|
|
135
|
+
|
|
136
|
+
```astro
|
|
137
|
+
import { ProductEngines } from 'spoko-design-system';
|
|
138
|
+
|
|
139
|
+
<ProductEngines engines={product.part_engines} />
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
See [ProductEngine documentation](/components/product-engine) for details.
|
|
143
|
+
|
|
144
|
+
### ProductCodes
|
|
145
|
+
|
|
146
|
+
PR codes with description tooltips (when available):
|
|
147
|
+
|
|
148
|
+
```astro
|
|
149
|
+
import { ProductCodes } from 'spoko-design-system';
|
|
150
|
+
|
|
151
|
+
<ProductCodes prcodes={product.pr_codes} isPdp={true} />
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## Styling
|
|
155
|
+
|
|
156
|
+
### SDS Theme
|
|
157
|
+
|
|
158
|
+
The default SDS theme uses these design tokens:
|
|
159
|
+
|
|
160
|
+
| Property | Value | Token |
|
|
161
|
+
|----------|-------|-------|
|
|
162
|
+
| Background | `#f3f4f6` | `neutral-lightest` |
|
|
163
|
+
| Text Color | `#1e293b` | `slate-darkest` |
|
|
164
|
+
| Border | `#e5e7eb` | `neutral-lighter` |
|
|
165
|
+
| Header Background | `#001e50` | `accent-deepBlue` |
|
|
166
|
+
| Max Width | `280px` | - |
|
|
167
|
+
| Border Radius | `0.5rem` | - |
|
|
168
|
+
|
|
169
|
+
### Custom Styling
|
|
170
|
+
|
|
171
|
+
To customize the tooltip appearance, override these CSS classes:
|
|
172
|
+
|
|
173
|
+
```css
|
|
174
|
+
/* Main tooltip box */
|
|
175
|
+
.tippy-box[data-theme~='sds'] {
|
|
176
|
+
background-color: your-color !important;
|
|
177
|
+
color: your-text-color !important;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/* Tooltip content area */
|
|
181
|
+
.tippy-box[data-theme~='sds'] .tippy-content {
|
|
182
|
+
padding: 0.5rem 0.75rem;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/* Structured tooltip header */
|
|
186
|
+
.tippy-box[data-theme~='sds'] .tooltip-header {
|
|
187
|
+
background-color: your-header-color;
|
|
188
|
+
color: white;
|
|
189
|
+
padding: 0.375rem 0.5rem;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/* Tooltip specs rows */
|
|
193
|
+
.tippy-box[data-theme~='sds'] .tooltip-row {
|
|
194
|
+
display: flex;
|
|
195
|
+
justify-content: space-between;
|
|
196
|
+
padding: 0.25rem 0;
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Available CSS Classes
|
|
201
|
+
|
|
202
|
+
For structured tooltips:
|
|
203
|
+
|
|
204
|
+
| Class | Purpose |
|
|
205
|
+
|-------|---------|
|
|
206
|
+
| `.tooltip-header` | Dark blue header section |
|
|
207
|
+
| `.tooltip-specs` | Container for specification rows |
|
|
208
|
+
| `.tooltip-row` | Single specification row |
|
|
209
|
+
| `.tooltip-label` | Left-aligned label text |
|
|
210
|
+
| `.tooltip-value` | Right-aligned value text |
|
|
211
|
+
|
|
212
|
+
## Configuration
|
|
213
|
+
|
|
214
|
+
The tooltip system uses these default settings:
|
|
215
|
+
|
|
216
|
+
```ts
|
|
217
|
+
{
|
|
218
|
+
target: '[data-tippy-content]', // Target selector
|
|
219
|
+
allowHTML: true, // Allow HTML in content
|
|
220
|
+
theme: 'sds', // SDS custom theme
|
|
221
|
+
placement: 'top', // Default placement
|
|
222
|
+
arrow: true, // Show arrow
|
|
223
|
+
animation: 'shift-away', // Animation style
|
|
224
|
+
duration: [200, 150], // [show, hide] duration (ms)
|
|
225
|
+
maxWidth: 280, // Maximum width (px)
|
|
226
|
+
}
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
To customize, you can create your own initialization:
|
|
230
|
+
|
|
231
|
+
```ts
|
|
232
|
+
// src/scripts/custom-tooltips.ts
|
|
233
|
+
import { delegate } from 'tippy.js';
|
|
234
|
+
import 'tippy.js/dist/tippy.css';
|
|
235
|
+
import 'spoko-design-system/styles/tippy-theme.css';
|
|
236
|
+
|
|
237
|
+
export function initCustomTooltips() {
|
|
238
|
+
delegate('body', {
|
|
239
|
+
target: '[data-tippy-content]',
|
|
240
|
+
allowHTML: true,
|
|
241
|
+
theme: 'sds',
|
|
242
|
+
placement: 'bottom', // Changed from 'top'
|
|
243
|
+
maxWidth: 400, // Wider tooltips
|
|
244
|
+
// ... other options
|
|
245
|
+
});
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
// Initialize
|
|
249
|
+
if (typeof document !== 'undefined') {
|
|
250
|
+
document.addEventListener('astro:page-load', () => {
|
|
251
|
+
initCustomTooltips();
|
|
252
|
+
});
|
|
253
|
+
}
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## Technical Details
|
|
257
|
+
|
|
258
|
+
### Delegation Pattern
|
|
259
|
+
|
|
260
|
+
The tooltip system uses Tippy.js's delegation pattern:
|
|
261
|
+
|
|
262
|
+
- **Single event listener** on `body` handles all tooltips
|
|
263
|
+
- **No re-initialization needed** when DOM changes
|
|
264
|
+
- **Efficient memory usage** - scales to thousands of tooltips
|
|
265
|
+
- **Dynamic content support** - works with client-side rendering
|
|
266
|
+
|
|
267
|
+
### How It Works
|
|
268
|
+
|
|
269
|
+
1. One global event listener watches for mouseenter/focus on `[data-tippy-content]` elements
|
|
270
|
+
2. Tooltip instance created on-demand when user hovers
|
|
271
|
+
3. Instance destroyed when tooltip hides
|
|
272
|
+
4. No memory leaks from orphaned instances
|
|
273
|
+
|
|
274
|
+
### Astro View Transitions
|
|
275
|
+
|
|
276
|
+
The system automatically handles Astro's View Transitions:
|
|
277
|
+
|
|
278
|
+
```ts
|
|
279
|
+
document.addEventListener('astro:page-load', () => {
|
|
280
|
+
initTooltips();
|
|
281
|
+
});
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
This ensures tooltips work correctly after client-side navigation.
|
|
285
|
+
|
|
286
|
+
## API Reference
|
|
287
|
+
|
|
288
|
+
### initTooltips()
|
|
289
|
+
|
|
290
|
+
Initializes the global tooltip delegation.
|
|
291
|
+
|
|
292
|
+
**Import:**
|
|
293
|
+
```ts
|
|
294
|
+
import { initTooltips } from 'spoko-design-system';
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
**Usage:**
|
|
298
|
+
```ts
|
|
299
|
+
initTooltips();
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
**Note:** Usually not needed if you import `'spoko-design-system/scripts/tooltips'` which auto-initializes.
|
|
303
|
+
|
|
304
|
+
### getEngineTooltipContent()
|
|
305
|
+
|
|
306
|
+
Generates HTML content for engine tooltips.
|
|
307
|
+
|
|
308
|
+
**Import:**
|
|
309
|
+
```ts
|
|
310
|
+
import { getEngineTooltipContent } from 'spoko-design-system';
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
**Usage:**
|
|
314
|
+
```ts
|
|
315
|
+
const tooltipHTML = getEngineTooltipContent(engine, translations);
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
**Parameters:**
|
|
319
|
+
|
|
320
|
+
| Parameter | Type | Required | Description |
|
|
321
|
+
|-----------|------|----------|-------------|
|
|
322
|
+
| `engine` | `Engine` | Yes | Engine object with nested structure |
|
|
323
|
+
| `translations` | `EngineTranslations` | No | Optional translation overrides |
|
|
324
|
+
|
|
325
|
+
**Returns:** HTML string for tooltip content
|
|
326
|
+
|
|
327
|
+
See [ProductEngine documentation](/components/product-engine) for `Engine` interface details.
|
|
328
|
+
|
|
329
|
+
## Dependencies
|
|
330
|
+
|
|
331
|
+
SDS includes `tippy.js` as a dependency. **Your project does not need to install it separately.**
|
|
332
|
+
|
|
333
|
+
If you have `tippy.js` in your project's `package.json`, you can safely remove it:
|
|
334
|
+
|
|
335
|
+
```bash
|
|
336
|
+
pnpm remove tippy.js
|
|
337
|
+
# or
|
|
338
|
+
npm uninstall tippy.js
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
## Troubleshooting
|
|
342
|
+
|
|
343
|
+
### Tooltips not showing
|
|
344
|
+
|
|
345
|
+
**Check these items:**
|
|
346
|
+
|
|
347
|
+
1. ✅ Script imported in layout: `<script src="/src/scripts/tooltips.ts"></script>`
|
|
348
|
+
2. ✅ Elements have `data-tippy-content` attribute
|
|
349
|
+
3. ✅ Content is not empty or "undefined"
|
|
350
|
+
4. ✅ Hard refresh browser (Ctrl+Shift+R) to clear cache
|
|
351
|
+
|
|
352
|
+
### Double tooltips or conflicts
|
|
353
|
+
|
|
354
|
+
If you see duplicate tooltips:
|
|
355
|
+
|
|
356
|
+
1. Only import the tooltip script **once** in your layout
|
|
357
|
+
2. Don't call `initTooltips()` manually if using auto-initialization
|
|
358
|
+
3. Remove any local `tippy.js` installations that might conflict
|
|
359
|
+
|
|
360
|
+
### Tooltips not working after navigation
|
|
361
|
+
|
|
362
|
+
If tooltips break after Astro View Transitions:
|
|
363
|
+
|
|
364
|
+
1. Verify `astro:page-load` event listener is registered (included in SDS script)
|
|
365
|
+
2. Check browser console for errors
|
|
366
|
+
3. Make sure View Transitions are properly configured in Astro
|
|
367
|
+
|
|
368
|
+
### Styling not applied
|
|
369
|
+
|
|
370
|
+
1. Verify SDS theme CSS is imported (included in SDS tooltip script)
|
|
371
|
+
2. Check CSS specificity - SDS uses `!important` for some properties
|
|
372
|
+
3. Ensure your build process handles CSS imports from `node_modules`
|
|
373
|
+
|
|
374
|
+
### Performance issues
|
|
375
|
+
|
|
376
|
+
If you have thousands of tooltips and notice lag:
|
|
377
|
+
|
|
378
|
+
1. The delegation pattern should handle this efficiently
|
|
379
|
+
2. Check if you're calling `initTooltips()` multiple times
|
|
380
|
+
3. Consider lazy-loading tooltip-heavy sections
|
|
381
|
+
|
|
382
|
+
## Browser Support
|
|
383
|
+
|
|
384
|
+
Tooltips work in all modern browsers:
|
|
385
|
+
|
|
386
|
+
- ✅ Chrome/Edge (latest)
|
|
387
|
+
- ✅ Firefox (latest)
|
|
388
|
+
- ✅ Safari (latest)
|
|
389
|
+
- ✅ Mobile browsers (iOS Safari, Chrome Android)
|
|
390
|
+
|
|
391
|
+
**Note:** Requires JavaScript. Content is still visible if JS is disabled (progressive enhancement).
|
|
392
|
+
|
|
393
|
+
## Examples
|
|
394
|
+
|
|
395
|
+
### Product Specification
|
|
396
|
+
|
|
397
|
+
```astro
|
|
398
|
+
<dl>
|
|
399
|
+
<dt>Weight</dt>
|
|
400
|
+
<dd>
|
|
401
|
+
<span data-tippy-content="Includes packaging">
|
|
402
|
+
2.5 kg
|
|
403
|
+
</span>
|
|
404
|
+
</dd>
|
|
405
|
+
</dl>
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### Help Icons
|
|
409
|
+
|
|
410
|
+
```astro
|
|
411
|
+
<label>
|
|
412
|
+
Email
|
|
413
|
+
<span
|
|
414
|
+
class="inline-block ml-1 text-gray-400 cursor-help"
|
|
415
|
+
data-tippy-content="We'll never share your email">
|
|
416
|
+
ⓘ
|
|
417
|
+
</span>
|
|
418
|
+
</label>
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
### Technical Terms
|
|
422
|
+
|
|
423
|
+
```astro
|
|
424
|
+
<p>
|
|
425
|
+
The part fits all
|
|
426
|
+
<abbr
|
|
427
|
+
data-tippy-content="Volkswagen Aktiengesellschaft Group"
|
|
428
|
+
class="cursor-help underline decoration-dotted">
|
|
429
|
+
VAG
|
|
430
|
+
</abbr>
|
|
431
|
+
vehicles from 2009-2014.
|
|
432
|
+
</p>
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
## Best Practices
|
|
436
|
+
|
|
437
|
+
### ✅ Do
|
|
438
|
+
|
|
439
|
+
- Use semantic HTML with tooltips as enhancement
|
|
440
|
+
- Keep tooltip content concise (< 50 words)
|
|
441
|
+
- Use structured tooltips for multiple data points
|
|
442
|
+
- Include proper ARIA labels when needed
|
|
443
|
+
- Test on mobile devices
|
|
444
|
+
|
|
445
|
+
### ❌ Don't
|
|
446
|
+
|
|
447
|
+
- Put critical information only in tooltips
|
|
448
|
+
- Use tooltips for large blocks of text
|
|
449
|
+
- Nest interactive elements inside tooltips
|
|
450
|
+
- Use tooltips on disabled elements
|
|
451
|
+
- Initialize tooltips multiple times
|
|
452
|
+
|
|
453
|
+
## Migration
|
|
454
|
+
|
|
455
|
+
### From Direct Tippy.js
|
|
456
|
+
|
|
457
|
+
If migrating from a direct Tippy.js implementation:
|
|
458
|
+
|
|
459
|
+
1. **Remove** `tippy.js` from your `package.json`
|
|
460
|
+
2. **Remove** local tooltip initialization code
|
|
461
|
+
3. **Add** SDS tooltip script import
|
|
462
|
+
4. **Update** elements to use `data-tippy-content`
|
|
463
|
+
5. **Update** custom styles to target `.tippy-box[data-theme~='sds']`
|
|
464
|
+
|
|
465
|
+
### From Old SDS Setup
|
|
466
|
+
|
|
467
|
+
If you had the old setup with manual initialization:
|
|
468
|
+
|
|
469
|
+
**Old way (remove this):**
|
|
470
|
+
```astro
|
|
471
|
+
<script>
|
|
472
|
+
import { initTooltips } from 'spoko-design-system';
|
|
473
|
+
initTooltips();
|
|
474
|
+
</script>
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
**New way (use this):**
|
|
478
|
+
```astro
|
|
479
|
+
<script src="/src/scripts/tooltips.ts"></script>
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
```ts
|
|
483
|
+
// src/scripts/tooltips.ts
|
|
484
|
+
import 'spoko-design-system/scripts/tooltips';
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
## Related Documentation
|
|
488
|
+
|
|
489
|
+
- [ProductEngine Component](/components/product-engine) - Engine codes with tooltips
|
|
490
|
+
- [ProductCodes Component](/components/pr-code) - PR codes with tooltips
|
|
491
|
+
- [Tippy.js Documentation](https://atomiks.github.io/tippyjs/) - Underlying library
|