@times-design-system/components-wordpress 1.5.2 → 1.6.0
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/dist/blocks/ad-container/block.json +10 -0
- package/dist/blocks/ad-container/edit.js +17 -1
- package/dist/blocks/ad-container/render.php +14 -0
- package/dist/blocks/button/block.json +19 -5
- package/dist/blocks/button/edit.js +33 -15
- package/dist/blocks/button/render.php +24 -2
- package/dist/blocks/button/style.css +63 -0
- package/dist/blocks/chip/block.json +12 -7
- package/dist/blocks/chip/edit.js +20 -17
- package/dist/blocks/chip/render.php +14 -2
- package/dist/blocks/dialog-box/block.json +10 -0
- package/dist/blocks/dialog-box/edit.js +17 -0
- package/dist/blocks/dialog-box/render.php +16 -4
- package/dist/blocks/divider/block.json +10 -0
- package/dist/blocks/divider/edit.js +18 -2
- package/dist/blocks/divider/render.php +14 -1
- package/dist/blocks/flag/block.json +10 -0
- package/dist/blocks/flag/edit.js +27 -2
- package/dist/blocks/flag/render.php +14 -0
- package/dist/blocks/icon/block.json +10 -0
- package/dist/blocks/icon/edit.js +17 -0
- package/dist/blocks/icon/render.php +16 -4
- package/dist/blocks/icon-button/block.json +15 -0
- package/dist/blocks/icon-button/edit.js +33 -1
- package/dist/blocks/icon-button/render.php +19 -0
- package/dist/blocks/icon-button/style.css +37 -3
- package/dist/blocks/input/block.json +10 -0
- package/dist/blocks/input/edit.js +27 -1
- package/dist/blocks/input/render.php +17 -1
- package/dist/blocks/input-helper-message/block.json +10 -0
- package/dist/blocks/input-helper-message/edit.js +17 -0
- package/dist/blocks/input-helper-message/render.php +16 -4
- package/dist/blocks/link/block.json +12 -7
- package/dist/blocks/link/edit.js +21 -18
- package/dist/blocks/link/render.php +14 -2
- package/dist/blocks/tab/block.json +10 -0
- package/dist/blocks/tab/edit.js +17 -0
- package/dist/blocks/tab/render.php +16 -4
- package/dist/blocks/tab-group/block.json +10 -0
- package/dist/blocks/tab-group/edit.js +17 -0
- package/dist/blocks/tab-group/render.php +16 -4
- package/dist/blocks/text/block.json +10 -0
- package/dist/blocks/text/edit.js +18 -2
- package/dist/blocks/text/render.php +14 -1
- package/dist/blocks/toast/block.json +10 -0
- package/dist/blocks/toast/edit.js +18 -1
- package/dist/blocks/toast/render.php +14 -0
- package/dist/index.cjs +389 -148
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +389 -148
- package/dist/index.js.map +1 -1
- package/dist/utils/DATA_ATTRIBUTES_USAGE.md +377 -0
- package/dist/utils/sanitize-data-attributes.php +109 -0
- package/package.json +9 -3
- package/BLOCK_CREATION_CHECKLIST.md +0 -385
- package/BUILD.md +0 -411
- package/CHANGELOG.md +0 -81
- package/SCSS_VARIABLES_REFERENCE.md +0 -316
- package/STYLING_SYNC_GUIDE.md +0 -306
- package/TESTING.md +0 -152
- package/TRANSFORMATION_GUIDE.md +0 -908
- package/dist/blocks/button/style-resolved.css +0 -153
- package/lib/wordpress.js +0 -7
- package/rollup.config.js +0 -75
- package/scripts/build-plugin.cjs +0 -121
- package/scripts/create-block.sh +0 -141
- package/scripts/create-wordpress-block-tests.cjs +0 -438
- package/scripts/create-wordpress-block.cjs +0 -681
- package/src/blocks/ad-container/block.json +0 -29
- package/src/blocks/ad-container/edit.js +0 -42
- package/src/blocks/ad-container/index.js +0 -10
- package/src/blocks/ad-container/render.php +0 -27
- package/src/blocks/ad-container/save.js +0 -16
- package/src/blocks/ad-container/style-editor.css +0 -4
- package/src/blocks/ad-container/style.css +0 -30
- package/src/blocks/button/block.json +0 -90
- package/src/blocks/button/edit.js +0 -187
- package/src/blocks/button/index.js +0 -11
- package/src/blocks/button/render.php +0 -71
- package/src/blocks/button/save.js +0 -52
- package/src/blocks/button/style-editor.css +0 -15
- package/src/blocks/button/style-resolved.css +0 -153
- package/src/blocks/button/style.css +0 -157
- package/src/blocks/chip/block.json +0 -58
- package/src/blocks/chip/edit.js +0 -113
- package/src/blocks/chip/index.js +0 -10
- package/src/blocks/chip/render.php +0 -40
- package/src/blocks/chip/save.js +0 -36
- package/src/blocks/chip/style-editor.css +0 -5
- package/src/blocks/chip/style.css +0 -87
- package/src/blocks/dialog-box/block.json +0 -24
- package/src/blocks/dialog-box/edit.js +0 -41
- package/src/blocks/dialog-box/index.js +0 -17
- package/src/blocks/dialog-box/render.php +0 -24
- package/src/blocks/dialog-box/save.js +0 -23
- package/src/blocks/dialog-box/style.css +0 -23
- package/src/blocks/divider/block.json +0 -32
- package/src/blocks/divider/edit.js +0 -42
- package/src/blocks/divider/index.js +0 -10
- package/src/blocks/divider/render.php +0 -31
- package/src/blocks/divider/save.js +0 -18
- package/src/blocks/divider/style-editor.css +0 -4
- package/src/blocks/divider/style.css +0 -37
- package/src/blocks/flag/block.json +0 -49
- package/src/blocks/flag/edit.js +0 -82
- package/src/blocks/flag/index.js +0 -10
- package/src/blocks/flag/render.php +0 -34
- package/src/blocks/flag/save.js +0 -25
- package/src/blocks/flag/style-editor.css +0 -5
- package/src/blocks/flag/style.css +0 -54
- package/src/blocks/icon/block.json +0 -24
- package/src/blocks/icon/edit.js +0 -41
- package/src/blocks/icon/index.js +0 -17
- package/src/blocks/icon/render.php +0 -24
- package/src/blocks/icon/save.js +0 -23
- package/src/blocks/icon/style.css +0 -23
- package/src/blocks/icon-button/block.json +0 -44
- package/src/blocks/icon-button/edit.js +0 -82
- package/src/blocks/icon-button/index.js +0 -10
- package/src/blocks/icon-button/render.php +0 -46
- package/src/blocks/icon-button/save.js +0 -29
- package/src/blocks/icon-button/style-editor.css +0 -5
- package/src/blocks/icon-button/style.css +0 -31
- package/src/blocks/input/block.json +0 -48
- package/src/blocks/input/edit.js +0 -78
- package/src/blocks/input/index.js +0 -10
- package/src/blocks/input/render.php +0 -39
- package/src/blocks/input/save.js +0 -27
- package/src/blocks/input/style-editor.css +0 -8
- package/src/blocks/input/style.css +0 -53
- package/src/blocks/input-helper-message/block.json +0 -24
- package/src/blocks/input-helper-message/edit.js +0 -42
- package/src/blocks/input-helper-message/index.js +0 -17
- package/src/blocks/input-helper-message/render.php +0 -24
- package/src/blocks/input-helper-message/save.js +0 -23
- package/src/blocks/input-helper-message/style.css +0 -23
- package/src/blocks/link/block.json +0 -72
- package/src/blocks/link/edit.js +0 -151
- package/src/blocks/link/index.js +0 -10
- package/src/blocks/link/render.php +0 -44
- package/src/blocks/link/save.js +0 -46
- package/src/blocks/link/style-editor.css +0 -5
- package/src/blocks/link/style.css +0 -119
- package/src/blocks/tab/block.json +0 -24
- package/src/blocks/tab/edit.js +0 -41
- package/src/blocks/tab/index.js +0 -17
- package/src/blocks/tab/render.php +0 -24
- package/src/blocks/tab/save.js +0 -23
- package/src/blocks/tab/style.css +0 -23
- package/src/blocks/tab-group/block.json +0 -24
- package/src/blocks/tab-group/edit.js +0 -41
- package/src/blocks/tab-group/index.js +0 -17
- package/src/blocks/tab-group/render.php +0 -24
- package/src/blocks/tab-group/save.js +0 -23
- package/src/blocks/tab-group/style.css +0 -23
- package/src/blocks/text/block.json +0 -33
- package/src/blocks/text/edit.js +0 -56
- package/src/blocks/text/index.js +0 -10
- package/src/blocks/text/render.php +0 -26
- package/src/blocks/text/save.js +0 -18
- package/src/blocks/text/style-editor.css +0 -4
- package/src/blocks/text/style.css +0 -7
- package/src/blocks/toast/block.json +0 -40
- package/src/blocks/toast/edit.js +0 -85
- package/src/blocks/toast/index.js +0 -10
- package/src/blocks/toast/render.php +0 -37
- package/src/blocks/toast/save.js +0 -29
- package/src/blocks/toast/style-editor.css +0 -4
- package/src/blocks/toast/style.css +0 -67
- package/src/index.js +0 -16
- package/src/utils/classBuilder.js +0 -53
- package/tsconfig.json +0 -116
- package/vitest.config.js +0 -28
- package/vitest.config.ts +0 -28
- package/vitest.setup.ts +0 -129
|
@@ -0,0 +1,377 @@
|
|
|
1
|
+
# Data Attributes Extension Guide
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
WordPress blocks in the Times Design System support custom `data-*` attributes and custom CSS classes for extensibility. This allows client implementations to add tracking, analytics, custom JavaScript hooks, testing selectors, and other data without modifying core block code.
|
|
6
|
+
|
|
7
|
+
## How It Works
|
|
8
|
+
|
|
9
|
+
### 1. Define Allowed Attributes (Server-Side)
|
|
10
|
+
|
|
11
|
+
Each block filters which `data-*` attributes are permitted. Clients define these in their theme or plugin:
|
|
12
|
+
|
|
13
|
+
**Example: Allow tracking attributes on buttons**
|
|
14
|
+
|
|
15
|
+
```php
|
|
16
|
+
// In your theme's functions.php or plugin file:
|
|
17
|
+
|
|
18
|
+
add_filter('tds_button_allowed_data_attributes', function($allowed, $attributes) {
|
|
19
|
+
return array_merge($allowed, [
|
|
20
|
+
'data-track-event',
|
|
21
|
+
'data-analytics-id',
|
|
22
|
+
'data-segment-user',
|
|
23
|
+
'data-gtag'
|
|
24
|
+
]);
|
|
25
|
+
}, 10, 2);
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**Why the allowlist?**
|
|
29
|
+
|
|
30
|
+
- ✅ Security: Prevents injection of arbitrary attributes
|
|
31
|
+
- ✅ Control: Server explicitly approves which attributes render
|
|
32
|
+
- ✅ Auditing: Easy to see what custom attributes are in use
|
|
33
|
+
- ✅ Namespace: `data-*` attributes are HTML-standard for metadata
|
|
34
|
+
|
|
35
|
+
### 2. Set Attributes in Gutenberg Block Editor
|
|
36
|
+
|
|
37
|
+
In the block inspector or via programmatic block creation:
|
|
38
|
+
|
|
39
|
+
**Via Gutenberg block editor:**
|
|
40
|
+
|
|
41
|
+
1. Add the block to your page
|
|
42
|
+
2. In the block inspector, configure standard attributes (label, intent, size, etc.)
|
|
43
|
+
3. Custom `dataAttributes` object is typically set programmatically or via block templates
|
|
44
|
+
|
|
45
|
+
**Via JavaScript:**
|
|
46
|
+
|
|
47
|
+
```javascript
|
|
48
|
+
// Set block attributes including dataAttributes
|
|
49
|
+
wp.blocks.createBlock('tds/button', {
|
|
50
|
+
label: 'Click me',
|
|
51
|
+
intent: 'primary',
|
|
52
|
+
dataAttributes: {
|
|
53
|
+
'data-track-event': 'button-click',
|
|
54
|
+
'data-analytics-id': 'button-123',
|
|
55
|
+
'data-gtag': 'event_button'
|
|
56
|
+
}
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
**Via PHP block template:**
|
|
61
|
+
|
|
62
|
+
```php
|
|
63
|
+
<!-- wp:tds/button {
|
|
64
|
+
"label": "Submit Form",
|
|
65
|
+
"intent": "primary",
|
|
66
|
+
"dataAttributes": {
|
|
67
|
+
"data-track-event": "form-submit",
|
|
68
|
+
"data-segment-user": "user-456"
|
|
69
|
+
}
|
|
70
|
+
} /-->
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 3. Output in Rendered HTML
|
|
74
|
+
|
|
75
|
+
The sanitized attributes render as HTML data attributes:
|
|
76
|
+
|
|
77
|
+
**Example output:**
|
|
78
|
+
|
|
79
|
+
```html
|
|
80
|
+
<button
|
|
81
|
+
class="tds-button tds-button--intent-primary tds-button--size-large"
|
|
82
|
+
data-track-event="button-click"
|
|
83
|
+
data-analytics-id="button-123"
|
|
84
|
+
data-gtag="event_button"
|
|
85
|
+
>
|
|
86
|
+
Click me
|
|
87
|
+
</button>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Allowed Attributes by Block
|
|
93
|
+
|
|
94
|
+
### Button Block
|
|
95
|
+
|
|
96
|
+
Filter: `tds_button_allowed_data_attributes`
|
|
97
|
+
|
|
98
|
+
Common use cases:
|
|
99
|
+
|
|
100
|
+
```php
|
|
101
|
+
'data-track-event' // Event tracking (analytics)
|
|
102
|
+
'data-analytics-id' // Unique identifier for this button
|
|
103
|
+
'data-segment-user' // Segment.io user identifier
|
|
104
|
+
'data-gtag' // Google Tag Manager
|
|
105
|
+
'data-qa-id' // QA testing selector
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Link Block
|
|
109
|
+
|
|
110
|
+
Filter: `tds_link_allowed_data_attributes`
|
|
111
|
+
|
|
112
|
+
Common use cases:
|
|
113
|
+
|
|
114
|
+
```php
|
|
115
|
+
'data-track-click' // Click tracking
|
|
116
|
+
'data-outbound' // Mark as external link
|
|
117
|
+
'data-campaign-id' // Marketing campaign ID
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Chip Block
|
|
121
|
+
|
|
122
|
+
Filter: `tds_chip_allowed_data_attributes`
|
|
123
|
+
|
|
124
|
+
Common use cases:
|
|
125
|
+
|
|
126
|
+
```php
|
|
127
|
+
'data-tag-id' // Tag/chip identifier
|
|
128
|
+
'data-category' // Categorization
|
|
129
|
+
'data-filter-group' // Filter group name
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Input Block
|
|
133
|
+
|
|
134
|
+
Filter: `tds_input_allowed_data_attributes`
|
|
135
|
+
|
|
136
|
+
Common use cases:
|
|
137
|
+
|
|
138
|
+
```php
|
|
139
|
+
'data-field-name' // Form field identifier
|
|
140
|
+
'data-validation-rule' // Custom validation
|
|
141
|
+
'data-form-id' // Parent form identifier
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Other Blocks
|
|
145
|
+
|
|
146
|
+
Each block follows the same pattern:
|
|
147
|
+
|
|
148
|
+
```
|
|
149
|
+
Filter: tds_{block_name}_allowed_data_attributes
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## Implementation Checklist
|
|
155
|
+
|
|
156
|
+
**For block developers adding new blocks:**
|
|
157
|
+
|
|
158
|
+
- [ ] Add `classes` string attribute to `block.json`
|
|
159
|
+
- [ ] Add `dataAttributes` object attribute to `block.json`
|
|
160
|
+
- [ ] In `render.php`, require the shared utility at the top
|
|
161
|
+
- [ ] Call `tds_sanitize_data_attributes()` to validate attributes
|
|
162
|
+
- [ ] Output sanitized attributes to main HTML element
|
|
163
|
+
- [ ] Test allowlist filter blocks disallowed attributes
|
|
164
|
+
|
|
165
|
+
**For theme/plugin developers using blocks:**
|
|
166
|
+
|
|
167
|
+
- [ ] Register allowed data attributes via filter hook
|
|
168
|
+
- [ ] Use `wp.blocks.createBlock()` or block templates to set attributes
|
|
169
|
+
- [ ] Access attributes in JavaScript using `data-*` selectors
|
|
170
|
+
- [ ] Test that attributes are rendering as expected
|
|
171
|
+
- [ ] Document which data attributes your theme/plugin uses
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Security Notes
|
|
176
|
+
|
|
177
|
+
✅ **What's protected:**
|
|
178
|
+
|
|
179
|
+
- Only `data-*` attributes can be added (prevents XSS via event handlers like `onclick`)
|
|
180
|
+
- Maximum 10 attributes per block (prevents DoS via attribute bloat)
|
|
181
|
+
- Maximum 200 characters per value (prevents excessively large attribute values)
|
|
182
|
+
- Values are sanitized with `sanitize_text_field()` (removes HTML markup)
|
|
183
|
+
- Allowlist filter ensures only approved attributes render (whitelist > blacklist)
|
|
184
|
+
|
|
185
|
+
❌ **What's not allowed:**
|
|
186
|
+
|
|
187
|
+
- `onclick`, `onload`, or other event handlers
|
|
188
|
+
- `href`, `src`, `action` or other behavioral attributes
|
|
189
|
+
- `id`, `class`, `style` (use `classes` and block spacing supports instead)
|
|
190
|
+
- Any attribute not explicitly allowlisted
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## Examples
|
|
195
|
+
|
|
196
|
+
### Analytics Tracking
|
|
197
|
+
|
|
198
|
+
```php
|
|
199
|
+
// In functions.php:
|
|
200
|
+
add_filter('tds_button_allowed_data_attributes', function($allowed) {
|
|
201
|
+
return array_merge($allowed, [
|
|
202
|
+
'data-analytics-event',
|
|
203
|
+
'data-analytics-label',
|
|
204
|
+
'data-analytics-category'
|
|
205
|
+
]);
|
|
206
|
+
});
|
|
207
|
+
|
|
208
|
+
// In block template:
|
|
209
|
+
<!-- wp:tds/button {
|
|
210
|
+
"label": "Download Report",
|
|
211
|
+
"dataAttributes": {
|
|
212
|
+
"data-analytics-event": "download",
|
|
213
|
+
"data-analytics-label": "q2-report",
|
|
214
|
+
"data-analytics-category": "reporting"
|
|
215
|
+
}
|
|
216
|
+
} /-->
|
|
217
|
+
|
|
218
|
+
// Output:
|
|
219
|
+
<button
|
|
220
|
+
data-analytics-event="download"
|
|
221
|
+
data-analytics-label="q2-report"
|
|
222
|
+
data-analytics-category="reporting"
|
|
223
|
+
>
|
|
224
|
+
Download Report
|
|
225
|
+
</button>
|
|
226
|
+
|
|
227
|
+
// JavaScript:
|
|
228
|
+
document.addEventListener('click', (e) => {
|
|
229
|
+
if (e.target.hasAttribute('data-analytics-event')) {
|
|
230
|
+
const event = e.target.getAttribute('data-analytics-event');
|
|
231
|
+
// Send to analytics service
|
|
232
|
+
gtag('event', event, {
|
|
233
|
+
label: e.target.getAttribute('data-analytics-label'),
|
|
234
|
+
category: e.target.getAttribute('data-analytics-category')
|
|
235
|
+
});
|
|
236
|
+
}
|
|
237
|
+
});
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### QA Testing Selectors
|
|
241
|
+
|
|
242
|
+
```php
|
|
243
|
+
// In functions.php:
|
|
244
|
+
add_filter('tds_button_allowed_data_attributes', function($allowed) {
|
|
245
|
+
return array_merge($allowed, ['data-qa-id']);
|
|
246
|
+
});
|
|
247
|
+
|
|
248
|
+
// In block template:
|
|
249
|
+
<!-- wp:tds/button {
|
|
250
|
+
"label": "Sign Up",
|
|
251
|
+
"dataAttributes": {
|
|
252
|
+
"data-qa-id": "signup-button"
|
|
253
|
+
}
|
|
254
|
+
} /-->
|
|
255
|
+
|
|
256
|
+
// In test code:
|
|
257
|
+
const signupButton = cy.get('[data-qa-id="signup-button"]');
|
|
258
|
+
signupButton.should('be.visible').click();
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### Custom CSS Classes
|
|
262
|
+
|
|
263
|
+
```php
|
|
264
|
+
// In block template:
|
|
265
|
+
<!-- wp:tds/button {
|
|
266
|
+
"label": "Click Me",
|
|
267
|
+
"classes": "my-custom-class dark-mode margin-bottom-large"
|
|
268
|
+
} /-->
|
|
269
|
+
|
|
270
|
+
// Output:
|
|
271
|
+
<button class="tds-button my-custom-class dark-mode margin-bottom-large">
|
|
272
|
+
Click Me
|
|
273
|
+
</button>
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Troubleshooting
|
|
279
|
+
|
|
280
|
+
**Q: My data attributes aren't rendering**
|
|
281
|
+
A: Check that your filter is returning an array with the attribute names. Example:
|
|
282
|
+
|
|
283
|
+
```php
|
|
284
|
+
// ✗ Wrong
|
|
285
|
+
return 'data-track-event';
|
|
286
|
+
|
|
287
|
+
// ✓ Correct
|
|
288
|
+
return array_merge($allowed, ['data-track-event']);
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
**Q: I'm getting truncated values**
|
|
292
|
+
A: Values are limited to 200 characters. Reduce the value or split across multiple attributes:
|
|
293
|
+
|
|
294
|
+
```php
|
|
295
|
+
// This will be truncated to 200 chars:
|
|
296
|
+
'data-description' => 'This is a very long description...'
|
|
297
|
+
|
|
298
|
+
// Better: use shorter value
|
|
299
|
+
'data-id' => 'desc-123'
|
|
300
|
+
'data-type' => 'description'
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
**Q: Can I use camelCase or uppercase in attribute names?**
|
|
304
|
+
A: Yes! The pattern `/^data-[a-z0-9_-]+$/i` allows:
|
|
305
|
+
|
|
306
|
+
```php
|
|
307
|
+
'data-trackEvent' // ✓ camelCase
|
|
308
|
+
'data-ANALYTICS_ID' // ✓ UPPERCASE with underscores
|
|
309
|
+
'data-track-event' // ✓ kebab-case
|
|
310
|
+
'data_track_event' // ✗ Not allowed (underscore at start)
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
**Q: My custom classes aren't applying**
|
|
314
|
+
A: Ensure classes are separated by spaces and contain valid CSS class characters. Each class is validated with `sanitize_html_class()`.
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## API Reference
|
|
319
|
+
|
|
320
|
+
### `tds_sanitize_data_attributes()`
|
|
321
|
+
|
|
322
|
+
```php
|
|
323
|
+
tds_sanitize_data_attributes(
|
|
324
|
+
array $data_attributes,
|
|
325
|
+
string $block_name,
|
|
326
|
+
array $attributes = []
|
|
327
|
+
): array
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
**Parameters:**
|
|
331
|
+
|
|
332
|
+
- `$data_attributes` - Raw data attributes object from block
|
|
333
|
+
- `$block_name` - Block name without 'tds/' prefix (e.g., 'button')
|
|
334
|
+
- `$attributes` - Full block attributes (for filter context)
|
|
335
|
+
|
|
336
|
+
**Returns:** Sanitized and validated data attributes array
|
|
337
|
+
|
|
338
|
+
**Filter Hook:**
|
|
339
|
+
|
|
340
|
+
```php
|
|
341
|
+
apply_filters(
|
|
342
|
+
"tds_{$block_name}_allowed_data_attributes",
|
|
343
|
+
[], // array of allowed attribute names
|
|
344
|
+
$attributes
|
|
345
|
+
)
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
**Example:**
|
|
349
|
+
|
|
350
|
+
```php
|
|
351
|
+
// Register allowed attributes
|
|
352
|
+
add_filter('tds_button_allowed_data_attributes', function($allowed, $attributes) {
|
|
353
|
+
// Only allow tracking attributes
|
|
354
|
+
return ['data-track-event', 'data-analytics-id'];
|
|
355
|
+
}, 10, 2);
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
360
|
+
## Best Practices
|
|
361
|
+
|
|
362
|
+
✅ **DO:**
|
|
363
|
+
|
|
364
|
+
- Use descriptive attribute names: `data-track-event`, not `data-x`
|
|
365
|
+
- Document your allowed attributes in code comments
|
|
366
|
+
- Validate attribute values in JavaScript (they're user input)
|
|
367
|
+
- Use filters for all configuration
|
|
368
|
+
- Keep attribute values short and simple
|
|
369
|
+
- Use kebab-case for attribute names (e.g., `data-track-event`)
|
|
370
|
+
|
|
371
|
+
❌ **DON'T:**
|
|
372
|
+
|
|
373
|
+
- Try to work around the allowlist (it's for security)
|
|
374
|
+
- Store large amounts of data in attributes (use `data-*` for small metadata only)
|
|
375
|
+
- Rely on undocumented attribute names
|
|
376
|
+
- Assume filters are active without checking filter registry
|
|
377
|
+
- Use prohibited attributes like `onclick`, `href`, `src`
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
<?php
|
|
2
|
+
/**
|
|
3
|
+
* Data Attributes Sanitization Utility
|
|
4
|
+
*
|
|
5
|
+
* Provides shared sanitization logic for block data-* attributes.
|
|
6
|
+
* Ensures consistent security and validation across all blocks.
|
|
7
|
+
*
|
|
8
|
+
* @package TimesDesignSystem\ComponentsWordPress
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Sanitize and validate custom data-* attributes
|
|
13
|
+
*
|
|
14
|
+
* Applies a whitelist filter to determine which data-* attributes are allowed,
|
|
15
|
+
* then validates and sanitizes each attribute before output.
|
|
16
|
+
*
|
|
17
|
+
* @param array $data_attributes Raw data attributes from block attributes
|
|
18
|
+
* @param string $block_name Block name without 'tds/' prefix (e.g., 'button', 'chip')
|
|
19
|
+
* @param array $attributes Full block attributes array (for filter context)
|
|
20
|
+
*
|
|
21
|
+
* @return array Sanitized and validated data attributes ready for HTML output
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* // In render.php:
|
|
25
|
+
* $sanitized_data_attributes = tds_sanitize_data_attributes(
|
|
26
|
+
* $attributes['dataAttributes'] ?? [],
|
|
27
|
+
* 'button',
|
|
28
|
+
* $attributes
|
|
29
|
+
* );
|
|
30
|
+
*
|
|
31
|
+
* $data_attrs_html = '';
|
|
32
|
+
* foreach ($sanitized_data_attributes as $key => $value) {
|
|
33
|
+
* $data_attrs_html .= ' ' . esc_attr($key) . '="' . esc_attr($value) . '"';
|
|
34
|
+
* }
|
|
35
|
+
*
|
|
36
|
+
* // Then in HTML:
|
|
37
|
+
* // <button <?php echo $data_attrs_html; ?>>...</button>
|
|
38
|
+
*/
|
|
39
|
+
function tds_sanitize_data_attributes($data_attributes, $block_name, $attributes = []) {
|
|
40
|
+
// Validate inputs
|
|
41
|
+
if (!is_array($data_attributes)) {
|
|
42
|
+
return [];
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
if (!is_string($block_name)) {
|
|
46
|
+
return [];
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
if (!is_array($attributes)) {
|
|
50
|
+
$attributes = [];
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// Get allowed data attribute keys from filter
|
|
54
|
+
$allowed_data_attribute_keys = apply_filters(
|
|
55
|
+
"tds_{$block_name}_allowed_data_attributes",
|
|
56
|
+
[],
|
|
57
|
+
$attributes
|
|
58
|
+
);
|
|
59
|
+
|
|
60
|
+
// Ensure it's an array
|
|
61
|
+
if (!is_array($allowed_data_attribute_keys)) {
|
|
62
|
+
$allowed_data_attribute_keys = [];
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
// Limits for DoS prevention
|
|
66
|
+
$max_data_attributes = 10;
|
|
67
|
+
$max_data_value_length = 200;
|
|
68
|
+
$sanitized_data_attributes = [];
|
|
69
|
+
|
|
70
|
+
// Regex for valid data attribute names: data-*, case-insensitive, allows numbers/hyphens/underscores
|
|
71
|
+
$valid_data_attr_pattern = '/^data-[a-z0-9_-]+$/i';
|
|
72
|
+
|
|
73
|
+
foreach ($data_attributes as $key => $value) {
|
|
74
|
+
// Enforce maximum attribute count
|
|
75
|
+
if (count($sanitized_data_attributes) >= $max_data_attributes) {
|
|
76
|
+
break;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// Validate key and value are scalar types
|
|
80
|
+
if (!is_string($key) || !is_scalar($value)) {
|
|
81
|
+
continue;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// Must start with 'data-'
|
|
85
|
+
if (strpos($key, 'data-') !== 0) {
|
|
86
|
+
continue;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// Must match valid data attribute pattern
|
|
90
|
+
if (!preg_match($valid_data_attr_pattern, $key)) {
|
|
91
|
+
continue;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
// Must be in allowed list (set via filter)
|
|
95
|
+
if (!in_array($key, $allowed_data_attribute_keys, true)) {
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// Sanitize and truncate value
|
|
100
|
+
$sanitized_value = sanitize_text_field((string) $value);
|
|
101
|
+
if (strlen($sanitized_value) > $max_data_value_length) {
|
|
102
|
+
$sanitized_value = substr($sanitized_value, 0, $max_data_value_length);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
$sanitized_data_attributes[$key] = $sanitized_value;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
return $sanitized_data_attributes;
|
|
109
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@times-design-system/components-wordpress",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.6.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Times Design System Gutenberg blocks for WordPress Full Site Editing",
|
|
6
6
|
"keywords": [
|
|
@@ -54,11 +54,17 @@
|
|
|
54
54
|
"url": "https://github.com/newsuk/times-design-system/issues"
|
|
55
55
|
},
|
|
56
56
|
"homepage": "https://github.com/newsuk/times-design-system#readme",
|
|
57
|
+
"files": [
|
|
58
|
+
"dist/",
|
|
59
|
+
"plugin.php",
|
|
60
|
+
"block.json",
|
|
61
|
+
"README.md"
|
|
62
|
+
],
|
|
57
63
|
"publishConfig": {
|
|
58
64
|
"access": "public"
|
|
59
65
|
},
|
|
60
66
|
"dependencies": {
|
|
61
|
-
"@times-design-system/theme-scss": "^2.
|
|
67
|
+
"@times-design-system/theme-scss": "^2.5.1",
|
|
62
68
|
"@wordpress/block-editor": "^12.0.0",
|
|
63
69
|
"@wordpress/blocks": "^12.0.0",
|
|
64
70
|
"@wordpress/components": "^25.0.0",
|
|
@@ -87,5 +93,5 @@
|
|
|
87
93
|
"typescript": "^5.0.0",
|
|
88
94
|
"vitest": "^1.0.4"
|
|
89
95
|
},
|
|
90
|
-
"gitHead": "
|
|
96
|
+
"gitHead": "96aae79e15100c0ddf7ce0e9defa5283c2d35803"
|
|
91
97
|
}
|