@times-design-system/components-wordpress 1.5.3 → 1.7.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 +38 -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 +25 -3
- 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 +18 -7
- 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 +25 -1
- package/dist/blocks/icon/block.json +10 -0
- package/dist/blocks/icon/edit.js +17 -0
- package/dist/blocks/icon/render.php +19 -8
- 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 +18 -7
- package/dist/blocks/link/block.json +12 -7
- package/dist/blocks/link/edit.js +21 -18
- package/dist/blocks/link/render.php +25 -3
- package/dist/blocks/tab/block.json +10 -0
- package/dist/blocks/tab/edit.js +17 -0
- package/dist/blocks/tab/render.php +18 -7
- 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 +18 -7
- 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 -85
- 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
package/TRANSFORMATION_GUIDE.md
DELETED
|
@@ -1,908 +0,0 @@
|
|
|
1
|
-
# React to WordPress Gutenberg Blocks Transformation Guide
|
|
2
|
-
|
|
3
|
-
This guide documents the process for transforming React components from `@times-design-system/components-react` into WordPress Gutenberg blocks in `@times-design-system/components-wordpress`.
|
|
4
|
-
|
|
5
|
-
## Overview
|
|
6
|
-
|
|
7
|
-
- **Framework**: React-based Gutenberg blocks using `@wordpress/element`
|
|
8
|
-
- **Target**: WordPress 6.0+ with Full Site Editing (FSE) support
|
|
9
|
-
- **Styling**: SCSS from `@times-design-system/theme-scss` with CSS design tokens
|
|
10
|
-
- **Architecture**: Separate implementation (not wrapping React components)
|
|
11
|
-
- **Versioning**: Synchronized with React component package (currently v1.1.0)
|
|
12
|
-
- **Distribution**: NPM package + WordPress plugin
|
|
13
|
-
|
|
14
|
-
---
|
|
15
|
-
|
|
16
|
-
## Directory Structure
|
|
17
|
-
|
|
18
|
-
```
|
|
19
|
-
packages/components-wordpress/
|
|
20
|
-
├── src/
|
|
21
|
-
│ ├── blocks/
|
|
22
|
-
│ │ ├── button/ # Each block gets its own folder
|
|
23
|
-
│ │ │ ├── block.json # Gutenberg block manifest (REQUIRED)
|
|
24
|
-
│ │ │ ├── index.js # Block registration (REQUIRED)
|
|
25
|
-
│ │ │ ├── edit.js # Editor component (REQUIRED)
|
|
26
|
-
│ │ │ ├── save.js # Frontend output component (REQUIRED)
|
|
27
|
-
│ │ │ ├── style.css # Frontend styles
|
|
28
|
-
│ │ │ └── style-editor.css # Editor-only styles
|
|
29
|
-
│ │ ├── text/
|
|
30
|
-
│ │ ├── input/
|
|
31
|
-
│ │ └── ... (other blocks)
|
|
32
|
-
│ ├── utils/
|
|
33
|
-
│ │ └── classBuilder.js # Shared utility functions (BEM className builder)
|
|
34
|
-
│ └── index.js # Main entry point (imports all blocks)
|
|
35
|
-
├── package.json
|
|
36
|
-
├── rollup.config.js
|
|
37
|
-
├── plugin.php # WordPress plugin entry point (auto-generated)
|
|
38
|
-
└── dist/ # Built output
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
---
|
|
42
|
-
|
|
43
|
-
## Step-by-Step Transformation Process
|
|
44
|
-
|
|
45
|
-
### 1. **Analyze the React Component**
|
|
46
|
-
|
|
47
|
-
Before starting, examine the React component in `packages/components-react/src/<ComponentName>/`:
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
cd packages/components-react/src/<ComponentName>
|
|
51
|
-
ls -la
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
Note:
|
|
55
|
-
|
|
56
|
-
- **Props**: Identify all component props and their types
|
|
57
|
-
- **Variants**: List all variant combinations (enum values)
|
|
58
|
-
- **Styling**: Check CSS/SCSS dependencies
|
|
59
|
-
- **External deps**: Note any icon systems, hooks, or utilities used
|
|
60
|
-
|
|
61
|
-
**Example (Button component)**:
|
|
62
|
-
|
|
63
|
-
```
|
|
64
|
-
Props:
|
|
65
|
-
- label (string): Button text
|
|
66
|
-
- intent (enum: primary | secondary | negative)
|
|
67
|
-
- size (enum: small | medium | large)
|
|
68
|
-
- behaviour (enum: hug | full)
|
|
69
|
-
- state (enum: base | hover | pressed | loading | disabled | focus)
|
|
70
|
-
- disabled (boolean)
|
|
71
|
-
- href, target, rel (link attributes)
|
|
72
|
-
- type (button type)
|
|
73
|
-
- iconLeft, iconRight (icon names)
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
### 2. **Create Block Directory Structure**
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
mkdir -p packages/components-wordpress/src/blocks/<component-name>
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
### 3. **Create block.json (Block Manifest)**
|
|
83
|
-
|
|
84
|
-
`block.json` declares the block to WordPress and defines its interface. This is the most critical file.
|
|
85
|
-
|
|
86
|
-
**Template**:
|
|
87
|
-
|
|
88
|
-
```json
|
|
89
|
-
{
|
|
90
|
-
"$schema": "https://schemas.wp.org/trunk/block.json",
|
|
91
|
-
"apiVersion": 3,
|
|
92
|
-
"name": "tds/<block-name>",
|
|
93
|
-
"title": "Block Display Name",
|
|
94
|
-
"category": "common",
|
|
95
|
-
"description": "Brief description",
|
|
96
|
-
"icon": "admin-generic",
|
|
97
|
-
"supports": {
|
|
98
|
-
"html": false,
|
|
99
|
-
"spacing": {
|
|
100
|
-
"margin": true,
|
|
101
|
-
"padding": false
|
|
102
|
-
},
|
|
103
|
-
"align": true,
|
|
104
|
-
"customClassName": true
|
|
105
|
-
},
|
|
106
|
-
"textdomain": "times-design-system",
|
|
107
|
-
"attributes": {
|
|
108
|
-
"prop1": {
|
|
109
|
-
"type": "string|boolean|number|array|object",
|
|
110
|
-
"default": "default-value",
|
|
111
|
-
"description": "Prop description"
|
|
112
|
-
}
|
|
113
|
-
},
|
|
114
|
-
"editorScript": "file:./index.js",
|
|
115
|
-
"editorStyle": "file:./style-editor.css",
|
|
116
|
-
"style": "file:./style.css"
|
|
117
|
-
}
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
**Conversion Rules**:
|
|
121
|
-
|
|
122
|
-
- Each React prop becomes an `attribute`
|
|
123
|
-
- Enum props use `"enum"` array
|
|
124
|
-
- Boolean props use `"type": "boolean"`
|
|
125
|
-
- String/number props use corresponding types
|
|
126
|
-
- Always provide sensible `default` values
|
|
127
|
-
- Add `description` for clarity in block inspector
|
|
128
|
-
|
|
129
|
-
**Example Button block.json**:
|
|
130
|
-
|
|
131
|
-
```json
|
|
132
|
-
{
|
|
133
|
-
"apiVersion": 3,
|
|
134
|
-
"name": "tds/button",
|
|
135
|
-
"title": "Button",
|
|
136
|
-
"attributes": {
|
|
137
|
-
"label": {
|
|
138
|
-
"type": "string",
|
|
139
|
-
"default": "Button label"
|
|
140
|
-
},
|
|
141
|
-
"intent": {
|
|
142
|
-
"type": "string",
|
|
143
|
-
"enum": ["primary", "secondary", "negative"],
|
|
144
|
-
"default": "primary"
|
|
145
|
-
},
|
|
146
|
-
"size": {
|
|
147
|
-
"type": "string",
|
|
148
|
-
"enum": ["small", "medium", "large"],
|
|
149
|
-
"default": "large"
|
|
150
|
-
}
|
|
151
|
-
}
|
|
152
|
-
}
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
### 4. **Create index.js (Block Registration)**
|
|
156
|
-
|
|
157
|
-
This file registers the block with Gutenberg.
|
|
158
|
-
|
|
159
|
-
**Template**:
|
|
160
|
-
|
|
161
|
-
```javascript
|
|
162
|
-
import { registerBlockType } from '@wordpress/blocks';
|
|
163
|
-
import Edit from './edit.js';
|
|
164
|
-
import Save from './save.js';
|
|
165
|
-
import metadata from './block.json';
|
|
166
|
-
|
|
167
|
-
registerBlockType(metadata.name, {
|
|
168
|
-
...metadata,
|
|
169
|
-
edit: Edit,
|
|
170
|
-
save: Save
|
|
171
|
-
});
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
**No customization needed** — this is boilerplate.
|
|
175
|
-
|
|
176
|
-
### 5. **Create edit.js (Editor Component)**
|
|
177
|
-
|
|
178
|
-
The `edit.js` component renders the block in the WordPress editor (what users interact with).
|
|
179
|
-
|
|
180
|
-
**Template Structure**:
|
|
181
|
-
|
|
182
|
-
```javascript
|
|
183
|
-
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
|
|
184
|
-
import {
|
|
185
|
-
PanelBody,
|
|
186
|
-
SelectControl,
|
|
187
|
-
TextControl,
|
|
188
|
-
ToggleControl
|
|
189
|
-
} from '@wordpress/components';
|
|
190
|
-
import { buildButtonClass } from '../../utils/classBuilder.js';
|
|
191
|
-
import './style-editor.css';
|
|
192
|
-
|
|
193
|
-
export default function Edit({ attributes, setAttributes }) {
|
|
194
|
-
const { prop1, prop2, prop3 } = attributes;
|
|
195
|
-
|
|
196
|
-
const blockProps = useBlockProps({
|
|
197
|
-
className: 'tds-<component>-wrapper'
|
|
198
|
-
});
|
|
199
|
-
|
|
200
|
-
return (
|
|
201
|
-
<>
|
|
202
|
-
<div {...blockProps}>{/* Preview of component */}</div>
|
|
203
|
-
|
|
204
|
-
<InspectorControls>
|
|
205
|
-
<PanelBody title="Component Settings">
|
|
206
|
-
{/* Inspector controls for editing props */}
|
|
207
|
-
</PanelBody>
|
|
208
|
-
</InspectorControls>
|
|
209
|
-
</>
|
|
210
|
-
);
|
|
211
|
-
}
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
**Key Points**:
|
|
215
|
-
|
|
216
|
-
- Always use `useBlockProps()` from `@wordpress/block-editor`
|
|
217
|
-
- Use `InspectorControls` to expose editable properties
|
|
218
|
-
- Use WordPress components for controls: `TextControl`, `SelectControl`, `ToggleControl`, `PanelBody`
|
|
219
|
-
- Call `setAttributes({ propName: newValue })` to update block state
|
|
220
|
-
- Import shared utilities like `classBuilder.js` for consistent styling
|
|
221
|
-
|
|
222
|
-
**Example Edit Component (Button)**:
|
|
223
|
-
|
|
224
|
-
```javascript
|
|
225
|
-
<SelectControl
|
|
226
|
-
label="Intent (Style)"
|
|
227
|
-
value={intent}
|
|
228
|
-
options={[
|
|
229
|
-
{ label: 'Primary', value: 'primary' },
|
|
230
|
-
{ label: 'Secondary', value: 'secondary' },
|
|
231
|
-
{ label: 'Negative', value: 'negative' }
|
|
232
|
-
]}
|
|
233
|
-
onChange={(value) => setAttributes({ intent: value })}
|
|
234
|
-
/>
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
### 6. **Create save.js (Frontend Output)**
|
|
238
|
-
|
|
239
|
-
The `save.js` component defines what gets stored/rendered on the website frontend.
|
|
240
|
-
|
|
241
|
-
**Template**:
|
|
242
|
-
|
|
243
|
-
```javascript
|
|
244
|
-
import { useBlockProps } from '@wordpress/block-editor';
|
|
245
|
-
import { buildButtonClass } from '../../utils/classBuilder.js';
|
|
246
|
-
|
|
247
|
-
export default function Save({ attributes }) {
|
|
248
|
-
const { prop1, prop2, prop3 } = attributes;
|
|
249
|
-
|
|
250
|
-
const blockProps = useBlockProps.save({
|
|
251
|
-
className: 'tds-<component>-wrapper'
|
|
252
|
-
});
|
|
253
|
-
|
|
254
|
-
return <div {...blockProps}>{/* HTML structure rendered on frontend */}</div>;
|
|
255
|
-
}
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
**Key Points**:
|
|
259
|
-
|
|
260
|
-
- Must be deterministic (same input = same output always)
|
|
261
|
-
- Always use `useBlockProps.save()`
|
|
262
|
-
- Return valid HTML that matches React component's render output
|
|
263
|
-
- No event handlers or dynamic behavior (it's static HTML)
|
|
264
|
-
- Can be PHP or JavaScript-rendered depending on config
|
|
265
|
-
|
|
266
|
-
### 7. **Create CSS Files — Full Parity with React**
|
|
267
|
-
|
|
268
|
-
#### `style.css` (Frontend Styles) — Critical for Feature Parity
|
|
269
|
-
|
|
270
|
-
The WordPress block's `style.css` **must mirror the React component's styles exactly**. This ensures visual and behavioral consistency across all implementations.
|
|
271
|
-
|
|
272
|
-
**Process**:
|
|
273
|
-
|
|
274
|
-
1. **Copy React component styles** from `packages/components-react/src/<ComponentName>/<ComponentName>.scss`
|
|
275
|
-
2. **Map all className modifiers** to CSS selectors (e.g., React `className="tds-button--size-small"` → CSS `.tds-button--size-small { ... }`)
|
|
276
|
-
3. **Preserve all CSS custom properties** for design tokens
|
|
277
|
-
4. **Include all state handlers**: hover, focus-visible, active, disabled
|
|
278
|
-
5. **Include all variants**: intent (primary, secondary, negative), size (small, medium, large), behaviour (full, hug)
|
|
279
|
-
|
|
280
|
-
**Key Principles**:
|
|
281
|
-
|
|
282
|
-
- Use **resolved design token values** for ALL properties: actual hex colors (e.g., `#005c8a`), pixel sizes (e.g., `8px`), and font names (e.g., `Roboto`)
|
|
283
|
-
- Follow BEM naming: `.tds-<component>`, `.tds-<component>--<modifier>`
|
|
284
|
-
- Include transitions for smooth state changes (usually `0.15s ease`)
|
|
285
|
-
- Focus rings should use concrete colors (e.g., `#737373`) with box-shadow pseudo-element
|
|
286
|
-
- Disabled states need opacity reduction and cursor change
|
|
287
|
-
- All pseudo-classes (`:hover`, `:focus-visible`, `:active`, `:disabled`) must match React behavior
|
|
288
|
-
|
|
289
|
-
**Example Structure** (from Button component):
|
|
290
|
-
|
|
291
|
-
```css
|
|
292
|
-
.tds-button {
|
|
293
|
-
--tds-button-bg: var(--interactive-primary-fill-default);
|
|
294
|
-
--tds-button-fg: var(--interactive-primary-text-default);
|
|
295
|
-
--tds-button-border: var(--interactive-primary-border-default);
|
|
296
|
-
|
|
297
|
-
display: flex;
|
|
298
|
-
align-items: center;
|
|
299
|
-
gap: var(--spacing-03);
|
|
300
|
-
border: 1px solid var(--tds-button-border);
|
|
301
|
-
background-color: var(--tds-button-bg);
|
|
302
|
-
color: var(--tds-button-fg);
|
|
303
|
-
font-family: Roboto;
|
|
304
|
-
font-weight: 500;
|
|
305
|
-
transition: 0.15s ease;
|
|
306
|
-
cursor: pointer;
|
|
307
|
-
}
|
|
308
|
-
|
|
309
|
-
/* Intent variants */
|
|
310
|
-
.tds-button--intent-primary {
|
|
311
|
-
--tds-button-bg: var(--interactive-primary-fill-default);
|
|
312
|
-
--tds-button-fg: var(--interactive-primary-text-default);
|
|
313
|
-
}
|
|
314
|
-
|
|
315
|
-
.tds-button--intent-secondary {
|
|
316
|
-
--tds-button-bg: var(--interactive-secondary-fill-default);
|
|
317
|
-
--tds-button-fg: var(--interactive-secondary-text-default);
|
|
318
|
-
}
|
|
319
|
-
|
|
320
|
-
/* Size variants — RESOLVED values */
|
|
321
|
-
.tds-button--size-small {
|
|
322
|
-
min-height: 40px;
|
|
323
|
-
padding: 4px 8px;
|
|
324
|
-
font-size: 1.4rem;
|
|
325
|
-
}
|
|
326
|
-
|
|
327
|
-
.tds-button--size-medium {
|
|
328
|
-
min-height: 48px;
|
|
329
|
-
padding: 8px 12px;
|
|
330
|
-
font-size: 1.6rem;
|
|
331
|
-
}
|
|
332
|
-
|
|
333
|
-
.tds-button--size-large {
|
|
334
|
-
min-height: 64px;
|
|
335
|
-
padding: 12px 20px;
|
|
336
|
-
font-size: 1.8rem;
|
|
337
|
-
}
|
|
338
|
-
|
|
339
|
-
/* State handlers */
|
|
340
|
-
.tds-button:hover:not(:disabled) {
|
|
341
|
-
background-color: var(--interactive-primary-fill-hover);
|
|
342
|
-
border-color: var(--interactive-primary-border-hover);
|
|
343
|
-
}
|
|
344
|
-
|
|
345
|
-
.tds-button:focus-visible {
|
|
346
|
-
outline: none;
|
|
347
|
-
}
|
|
348
|
-
|
|
349
|
-
.tds-button:focus-visible::after {
|
|
350
|
-
content: '';
|
|
351
|
-
position: absolute;
|
|
352
|
-
inset: calc(var(--spacing-03) * -1);
|
|
353
|
-
border: var(--spacing-01) solid var(--focus-border);
|
|
354
|
-
pointer-events: none;
|
|
355
|
-
}
|
|
356
|
-
|
|
357
|
-
.tds-button:disabled {
|
|
358
|
-
background-color: var(--interactive-disabled-b);
|
|
359
|
-
color: var(--text-disabled);
|
|
360
|
-
cursor: not-allowed;
|
|
361
|
-
opacity: 0.5;
|
|
362
|
-
}
|
|
363
|
-
|
|
364
|
-
/* Behaviour variants */
|
|
365
|
-
.tds-button--behaviour-full {
|
|
366
|
-
width: 100%;
|
|
367
|
-
}
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
**Validation Checklist**:
|
|
371
|
-
|
|
372
|
-
✓ All CSS custom properties match design tokens
|
|
373
|
-
✓ BEM naming is consistent (no underscores, only hyphens)
|
|
374
|
-
✓ All variant combinations present (intent × size × behaviour)
|
|
375
|
-
✓ State handlers for hover, focus, active, disabled
|
|
376
|
-
✓ Line count similar to React component (indicates parity)
|
|
377
|
-
✓ Transitions preserved
|
|
378
|
-
✓ No hardcoded hex colors (all use CSS variables)
|
|
379
|
-
|
|
380
|
-
#### `style-editor.css` (Editor Styles) — Optional
|
|
381
|
-
|
|
382
|
-
- Only loaded in WordPress editor
|
|
383
|
-
- Can override styles for better editing experience
|
|
384
|
-
- Optional — only add if editor preview differs significantly from frontend
|
|
385
|
-
- Example: Adjust padding/margins for better visual feedback in editor
|
|
386
|
-
- Example: Add borders to clarify block boundaries during editing
|
|
387
|
-
|
|
388
|
-
#### CSS Variables and theme-scss Integration
|
|
389
|
-
|
|
390
|
-
**IMPORTANT**: WordPress blocks use **resolved design token values** — actual hex colors, pixel measurements, and font definitions are compiled directly into the CSS. This means blocks are completely self-contained and do not depend on CSS custom properties from theme-scss.
|
|
391
|
-
|
|
392
|
-
**Key Approach**:
|
|
393
|
-
|
|
394
|
-
```
|
|
395
|
-
Design Tokens (theme-scss)
|
|
396
|
-
↓
|
|
397
|
-
Resolved to concrete values
|
|
398
|
-
↓
|
|
399
|
-
Hardcoded into WordPress block CSS
|
|
400
|
-
↓
|
|
401
|
-
No runtime CSS variable dependencies needed
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
**Why Resolved Values**:
|
|
405
|
-
|
|
406
|
-
- Blocks work reliably in any WordPress theme context
|
|
407
|
-
- No need for theme-scss CSS variables to be loaded
|
|
408
|
-
- Consistent appearance across installations
|
|
409
|
-
- Simpler debugging (actual colors/sizes visible in DevTools)
|
|
410
|
-
|
|
411
|
-
**Value Reference**:
|
|
412
|
-
|
|
413
|
-
| Value Type | Examples | Notes |
|
|
414
|
-
| ----------------- | ----------------------------------------------- | ------------------------------------- |
|
|
415
|
-
| **Colors (hex)** | `#005c8a`, `#ffffff`, `#737373` | All interactive colors use hex values |
|
|
416
|
-
| **Spacing (px)** | `4px`, `8px`, `12px`, `16px`, `24px` | All spacing uses pixel units |
|
|
417
|
-
| **Typography** | `-apple-system, BlinkMacSystemFont, "Segoe UI"` | System fonts specified directly |
|
|
418
|
-
| **Font weight** | `400`, `500`, `700` | Numeric weight values |
|
|
419
|
-
| **Font size** | `0.75rem`, `1rem`, `1.125rem` | REMs for scalability |
|
|
420
|
-
| **Border radius** | `0`, `2px`, `4px`, `9999px` | Explicit pixel or full values |
|
|
421
|
-
|
|
422
|
-
**Example Block CSS** (resolved values):
|
|
423
|
-
|
|
424
|
-
```css
|
|
425
|
-
.tds-button {
|
|
426
|
-
/* NO CSS variables — all values are concrete */
|
|
427
|
-
--tds-button-bg: #005c8a; /* Direct hex, not var(--color-*) */
|
|
428
|
-
--tds-button-fg: #ffffff; /* No fallbacks needed */
|
|
429
|
-
|
|
430
|
-
gap: 4px; /* Direct pixel, not var(--spacing-03) */
|
|
431
|
-
padding: 8px 12px; /* Resolved from design tokens */
|
|
432
|
-
|
|
433
|
-
font-family: Roboto;
|
|
434
|
-
font-weight: 500; /* Direct numeric value */
|
|
435
|
-
font-size: 1.6rem; /* Direct resolved size from theme-scss */
|
|
436
|
-
}
|
|
437
|
-
```
|
|
438
|
-
|
|
439
|
-
**See Also**: [SCSS_VARIABLES_REFERENCE.md](./SCSS_VARIABLES_REFERENCE.md) for complete mapping of all resolved values used across all blocks.
|
|
440
|
-
|
|
441
|
-
### 8. **Create/Update Utility Functions**
|
|
442
|
-
|
|
443
|
-
Shared utilities go in `packages/components-wordpress/src/utils/`.
|
|
444
|
-
|
|
445
|
-
**classBuilder.js** (example):
|
|
446
|
-
|
|
447
|
-
```javascript
|
|
448
|
-
export function buildButtonClass({
|
|
449
|
-
intent = 'primary',
|
|
450
|
-
size = 'large',
|
|
451
|
-
behaviour = 'hug',
|
|
452
|
-
state = 'base',
|
|
453
|
-
disabled = false
|
|
454
|
-
}) {
|
|
455
|
-
const classes = [
|
|
456
|
-
'tds-button',
|
|
457
|
-
`tds-button--intent-${intent}`,
|
|
458
|
-
`tds-button--size-${size}`,
|
|
459
|
-
`tds-button--behaviour-${behaviour}`,
|
|
460
|
-
`tds-button--state-${state}`
|
|
461
|
-
];
|
|
462
|
-
|
|
463
|
-
if (disabled) {
|
|
464
|
-
classes.push('tds-button--disabled');
|
|
465
|
-
}
|
|
466
|
-
|
|
467
|
-
return classes.join(' ');
|
|
468
|
-
}
|
|
469
|
-
```
|
|
470
|
-
|
|
471
|
-
**When to add utilities**:
|
|
472
|
-
|
|
473
|
-
- Repeated className building logic
|
|
474
|
-
- Common prop validation
|
|
475
|
-
- Shared component behavior
|
|
476
|
-
- BEM convention helpers
|
|
477
|
-
|
|
478
|
-
### 9. **Register Block in Main index.js**
|
|
479
|
-
|
|
480
|
-
Add block import to `src/index.js`:
|
|
481
|
-
|
|
482
|
-
```javascript
|
|
483
|
-
// Already existing
|
|
484
|
-
import './blocks/button/index.js';
|
|
485
|
-
|
|
486
|
-
// Add new block
|
|
487
|
-
import './blocks/<new-component>/index.js';
|
|
488
|
-
```
|
|
489
|
-
|
|
490
|
-
### 10. **Build and Verify**
|
|
491
|
-
|
|
492
|
-
**After completing all files**:
|
|
493
|
-
|
|
494
|
-
```bash
|
|
495
|
-
# Build the package
|
|
496
|
-
cd packages/components-wordpress
|
|
497
|
-
npm run build
|
|
498
|
-
|
|
499
|
-
# Verify block appears in dist/ with all styles
|
|
500
|
-
ls dist/blocks/<new-component>/
|
|
501
|
-
# Expected: block.json, index.js, edit.js, save.js, render.php, style.css, style-editor.css
|
|
502
|
-
|
|
503
|
-
# Check line count of compiled style.css (should be substantial)
|
|
504
|
-
wc -l dist/blocks/<new-component>/style.css
|
|
505
|
-
```
|
|
506
|
-
|
|
507
|
-
**Build verification checklist**:
|
|
508
|
-
|
|
509
|
-
✓ `dist/blocks/<new-component>/render.php` exists (server-side rendering)
|
|
510
|
-
✓ `dist/blocks/<new-component>/style.css` contains all styles (50+ lines for complex components)
|
|
511
|
-
✓ `block.json` has `"render": "file:./render.php"` reference
|
|
512
|
-
✓ No TypeScript/build errors
|
|
513
|
-
✓ Block registrations all successful
|
|
514
|
-
✓ CSS custom properties properly compiled
|
|
515
|
-
|
|
516
|
-
---
|
|
517
|
-
|
|
518
|
-
## Prop-to-Attribute Conversion Reference
|
|
519
|
-
|
|
520
|
-
| React Prop Type | Block Attribute | Example | Notes |
|
|
521
|
-
| ------------------- | ------------------- | ------------------- | -------------------------------------- |
|
|
522
|
-
| `string` | `"type": "string"` | `label: "Button"` | Simple text |
|
|
523
|
-
| `boolean` | `"type": "boolean"` | `disabled: true` | Toggle controls |
|
|
524
|
-
| `enum` (union type) | `"enum": [...]` | `intent: "primary"` | SelectControl in inspector |
|
|
525
|
-
| `number` | `"type": "number"` | `size: 16` | NumberControl |
|
|
526
|
-
| `Object` | `"type": "object"` | Complex data | Use JSON serialization |
|
|
527
|
-
| `Array` | `"type": "array"` | Multiple values | Use JSON serialization |
|
|
528
|
-
| Event handler | ❌ Not supported | `onClick` | Blocks don't support handlers directly |
|
|
529
|
-
|
|
530
|
-
---
|
|
531
|
-
|
|
532
|
-
## Inspector Controls Reference
|
|
533
|
-
|
|
534
|
-
Common WordPress components for the block inspector:
|
|
535
|
-
|
|
536
|
-
```javascript
|
|
537
|
-
import {
|
|
538
|
-
TextControl, // Text input
|
|
539
|
-
NumberControl, // Number input
|
|
540
|
-
SelectControl, // Dropdown
|
|
541
|
-
ToggleControl, // On/Off switch
|
|
542
|
-
CheckboxControl, // Checkbox
|
|
543
|
-
PanelBody, // Collapsible panel
|
|
544
|
-
ColorPalette, // Color picker
|
|
545
|
-
RangeControl, // Slider
|
|
546
|
-
ButtonGroup // Button group
|
|
547
|
-
} from '@wordpress/components';
|
|
548
|
-
```
|
|
549
|
-
|
|
550
|
-
**Example**:
|
|
551
|
-
|
|
552
|
-
```javascript
|
|
553
|
-
<TextControl
|
|
554
|
-
label="Button Label"
|
|
555
|
-
value={label}
|
|
556
|
-
onChange={(value) => setAttributes({ label: value })}
|
|
557
|
-
placeholder="Enter button text"
|
|
558
|
-
/>
|
|
559
|
-
|
|
560
|
-
<SelectControl
|
|
561
|
-
label="Button Size"
|
|
562
|
-
value={size}
|
|
563
|
-
options={[
|
|
564
|
-
{ label: 'Small', value: 'small' },
|
|
565
|
-
{ label: 'Medium', value: 'medium' },
|
|
566
|
-
{ label: 'Large', value: 'large' },
|
|
567
|
-
]}
|
|
568
|
-
onChange={(value) => setAttributes({ size: value })}
|
|
569
|
-
/>
|
|
570
|
-
|
|
571
|
-
<ToggleControl
|
|
572
|
-
label="Disabled"
|
|
573
|
-
checked={disabled}
|
|
574
|
-
onChange={(value) => setAttributes({ disabled: value })}
|
|
575
|
-
/>
|
|
576
|
-
```
|
|
577
|
-
|
|
578
|
-
---
|
|
579
|
-
|
|
580
|
-
## Styling Best Practices
|
|
581
|
-
|
|
582
|
-
### 1. **Class Naming Convention** (BEM)
|
|
583
|
-
|
|
584
|
-
Follow Block Element Modifier pattern:
|
|
585
|
-
|
|
586
|
-
- Block: `.tds-button`
|
|
587
|
-
- Element: `.tds-button__label`
|
|
588
|
-
- Modifier: `.tds-button--primary`, `.tds-button--large`
|
|
589
|
-
|
|
590
|
-
### 2. **Reference Design Tokens**
|
|
591
|
-
|
|
592
|
-
Use CSS custom properties from `theme-scss`:
|
|
593
|
-
|
|
594
|
-
```css
|
|
595
|
-
.tds-button {
|
|
596
|
-
color: var(--color-text-primary);
|
|
597
|
-
background-color: var(--color-bg-primary);
|
|
598
|
-
font-family: var(--typography-font-family-body);
|
|
599
|
-
border-radius: var(--spacing-radius-md);
|
|
600
|
-
}
|
|
601
|
-
```
|
|
602
|
-
|
|
603
|
-
### 3. **Avoid Inline Styles**
|
|
604
|
-
|
|
605
|
-
Don't set styles in edit.js:
|
|
606
|
-
|
|
607
|
-
```javascript
|
|
608
|
-
// ❌ Don't do this
|
|
609
|
-
<div style={{ color: 'red' }}>...</div>
|
|
610
|
-
|
|
611
|
-
// ✅ Do this instead
|
|
612
|
-
<div className="tds-button--error">...</div>
|
|
613
|
-
```
|
|
614
|
-
|
|
615
|
-
### 4. **Support Block Spacing Settings**
|
|
616
|
-
|
|
617
|
-
Enable margin and padding controls in block.json:
|
|
618
|
-
|
|
619
|
-
```json
|
|
620
|
-
"supports": {
|
|
621
|
-
"spacing": {
|
|
622
|
-
"margin": true,
|
|
623
|
-
"padding": false
|
|
624
|
-
}
|
|
625
|
-
}
|
|
626
|
-
```
|
|
627
|
-
|
|
628
|
-
---
|
|
629
|
-
|
|
630
|
-
## Build and Plugin Generation
|
|
631
|
-
|
|
632
|
-
### Local Development
|
|
633
|
-
|
|
634
|
-
```bash
|
|
635
|
-
# Install dependencies
|
|
636
|
-
cd packages/components-wordpress
|
|
637
|
-
npm install
|
|
638
|
-
|
|
639
|
-
# Development with watch
|
|
640
|
-
npm run dev
|
|
641
|
-
|
|
642
|
-
# Build once
|
|
643
|
-
npm run build
|
|
644
|
-
```
|
|
645
|
-
|
|
646
|
-
### Plugin Distribution
|
|
647
|
-
|
|
648
|
-
The `build:plugin` script generates a WordPress plugin structure:
|
|
649
|
-
|
|
650
|
-
```
|
|
651
|
-
dist/
|
|
652
|
-
├── plugin.php # WordPress plugin entry point
|
|
653
|
-
├── block.json # Root plugin metadata
|
|
654
|
-
└── blocks/
|
|
655
|
-
├── button/
|
|
656
|
-
│ └── ... (compiled block files)
|
|
657
|
-
└── ... (other blocks)
|
|
658
|
-
```
|
|
659
|
-
|
|
660
|
-
**Plugin Headers (generated in plugin.php)**:
|
|
661
|
-
|
|
662
|
-
```php
|
|
663
|
-
<?php
|
|
664
|
-
/**
|
|
665
|
-
* Plugin Name: Times Design System Blocks
|
|
666
|
-
* Description: Gutenberg blocks for Times Design System
|
|
667
|
-
* Version: 1.1.0
|
|
668
|
-
* Text Domain: times-design-system
|
|
669
|
-
* Domain Path: /languages
|
|
670
|
-
* Requires at least: 6.0
|
|
671
|
-
* Requires PHP: 7.4
|
|
672
|
-
*/
|
|
673
|
-
```
|
|
674
|
-
|
|
675
|
-
---
|
|
676
|
-
|
|
677
|
-
## Common Patterns
|
|
678
|
-
|
|
679
|
-
### Pattern 1: Conditional Rendering
|
|
680
|
-
|
|
681
|
-
```javascript
|
|
682
|
-
// In edit.js
|
|
683
|
-
{
|
|
684
|
-
href ? (
|
|
685
|
-
<a href={href} className={className}>
|
|
686
|
-
{label}
|
|
687
|
-
</a>
|
|
688
|
-
) : (
|
|
689
|
-
<button className={className}>{label}</button>
|
|
690
|
-
);
|
|
691
|
-
}
|
|
692
|
-
```
|
|
693
|
-
|
|
694
|
-
### Pattern 2: State Variants
|
|
695
|
-
|
|
696
|
-
Use modifier classes instead of state props:
|
|
697
|
-
|
|
698
|
-
```javascript
|
|
699
|
-
const classes = buildButtonClass({
|
|
700
|
-
intent,
|
|
701
|
-
size,
|
|
702
|
-
disabled, // Adds .tds-button--disabled class
|
|
703
|
-
state // Adds .tds-button--state-{value} class
|
|
704
|
-
});
|
|
705
|
-
```
|
|
706
|
-
|
|
707
|
-
### Pattern 3: Icon Integration
|
|
708
|
-
|
|
709
|
-
Icons should be referenced by name (string), not imported:
|
|
710
|
-
|
|
711
|
-
```javascript
|
|
712
|
-
// Instead of importing an Icon component:
|
|
713
|
-
// ❌ import { PlusIcon } from './icons'
|
|
714
|
-
|
|
715
|
-
// Use a string reference:
|
|
716
|
-
// ✅ iconName: "plus" → render via CSS or font icon system
|
|
717
|
-
```
|
|
718
|
-
|
|
719
|
-
### Pattern 4: Accessibility
|
|
720
|
-
|
|
721
|
-
Always include ARIA attributes:
|
|
722
|
-
|
|
723
|
-
```javascript
|
|
724
|
-
<button aria-label={ariaLabel} disabled={disabled} type={type}>
|
|
725
|
-
{label}
|
|
726
|
-
</button>
|
|
727
|
-
```
|
|
728
|
-
|
|
729
|
-
---
|
|
730
|
-
|
|
731
|
-
## Checklist for Each New Block
|
|
732
|
-
|
|
733
|
-
- [ ] Created `src/blocks/<component-name>/` directory
|
|
734
|
-
- [ ] Created `block.json` with all props as attributes
|
|
735
|
-
- [ ] Created `index.js` for block registration
|
|
736
|
-
- [ ] Created `edit.js` with inspector controls
|
|
737
|
-
- [ ] Created `save.js` with frontend HTML output
|
|
738
|
-
- [ ] Created `style.css` with component styling
|
|
739
|
-
- [ ] Created `style-editor.css` if needed for editor preview
|
|
740
|
-
- [ ] Added block import to `src/index.js`
|
|
741
|
-
- [ ] Tested block renders in editor
|
|
742
|
-
- [ ] Tested block saves and displays correctly
|
|
743
|
-
- [ ] Verified styling with `@times-design-system/theme-scss` tokens
|
|
744
|
-
- [ ] Added utility functions to `src/utils/` if needed
|
|
745
|
-
- [ ] Updated this guide if adding new patterns
|
|
746
|
-
|
|
747
|
-
---
|
|
748
|
-
|
|
749
|
-
## Component Transformation Order
|
|
750
|
-
|
|
751
|
-
Suggested order for consistent, dependency-aware transformation:
|
|
752
|
-
|
|
753
|
-
1. **Button** (done ✓) — Foundation, no dependencies
|
|
754
|
-
2. **Text** — Basic typography, minimal props
|
|
755
|
-
3. **Divider** — Simple layout component
|
|
756
|
-
4. **Input** — Form component
|
|
757
|
-
5. **Link** — Extends button logic
|
|
758
|
-
6. **IconButton** — Builds on button pattern
|
|
759
|
-
7. **Chip** — Multi-prop component
|
|
760
|
-
8. **Flag** — Badge/status component
|
|
761
|
-
9. **Toast** — Notification component
|
|
762
|
-
10. **AdContainer** — Container component
|
|
763
|
-
|
|
764
|
-
---
|
|
765
|
-
|
|
766
|
-
## Testing & Validation Checklist
|
|
767
|
-
|
|
768
|
-
### Pre-Build Testing
|
|
769
|
-
|
|
770
|
-
- [ ] **Styling Parity**: Run visual comparison of React component vs WordPress block
|
|
771
|
-
- Open React component in Storybook: `packages/components-react/src/<ComponentName>`
|
|
772
|
-
- Compare all variants side-by-side (intent, size, behaviour)
|
|
773
|
-
- Verify colors match exactly (should be identical CSS custom properties)
|
|
774
|
-
- Check spacing and padding are correct
|
|
775
|
-
- Test state transitions (hover, focus, active, disabled)
|
|
776
|
-
|
|
777
|
-
- [ ] **CSS Validation**:
|
|
778
|
-
- Line count check: `wc -l src/blocks/<component>/style.css` — should be substantial (50+ for complex components like Button/Link, 20+ for simple components)
|
|
779
|
-
- Compare to React component: `wc -l packages/components-react/src/<ComponentName>/<ComponentName>.scss`
|
|
780
|
-
- Should be similar complexity (±20% acceptable difference)
|
|
781
|
-
- No hardcoded hex colors: `grep -E '#[0-9a-fA-F]{6}' src/blocks/<component>/style.css` — should be zero results (all colors use CSS variables)
|
|
782
|
-
- Validate JSON: `npm run test`
|
|
783
|
-
|
|
784
|
-
- [ ] **Render Callback Testing**:
|
|
785
|
-
- Verify `render.php` exists for server-side pattern rendering
|
|
786
|
-
- Test in WordPress patterns: create pattern with block variants
|
|
787
|
-
- Confirm HTML output matches `save.js` structure exactly
|
|
788
|
-
- Test with different attribute combinations in patterns
|
|
789
|
-
|
|
790
|
-
### Post-Build Testing
|
|
791
|
-
|
|
792
|
-
```bash
|
|
793
|
-
# Navigate to packages/components-wordpress
|
|
794
|
-
cd packages/components-wordpress
|
|
795
|
-
|
|
796
|
-
# Run build
|
|
797
|
-
npm run build
|
|
798
|
-
|
|
799
|
-
# Verify compiled styles
|
|
800
|
-
wc -l dist/blocks/<component>/style.css # Check line count (should match src/)
|
|
801
|
-
grep -c 'tds-<component>--' dist/blocks/<component>/style.css # Count modifiers
|
|
802
|
-
|
|
803
|
-
# Verify render.php exists
|
|
804
|
-
ls dist/blocks/<component>/render.php
|
|
805
|
-
```
|
|
806
|
-
|
|
807
|
-
- [ ] **Compiled Output**:
|
|
808
|
-
- All variant CSS is present in `dist/blocks/<component>/style.css`
|
|
809
|
-
- `render.php` file exists and is copied to dist
|
|
810
|
-
- `block.json` contains `"render": "file:./render.php"`
|
|
811
|
-
|
|
812
|
-
- [ ] **WordPress Installation Testing**:
|
|
813
|
-
1. Build package: `npm run build`
|
|
814
|
-
2. Copy `dist/` to WordPress installation
|
|
815
|
-
3. Activate plugin or install NPM package
|
|
816
|
-
4. Add block to page in editor
|
|
817
|
-
5. Test each variant combination:
|
|
818
|
-
- Different intents (primary, secondary, negative)
|
|
819
|
-
- Different sizes (small, medium, large)
|
|
820
|
-
- Different states (hover by mouse, focus by keyboard, active by click, disabled)
|
|
821
|
-
6. Test in patterns (server-side rendering):
|
|
822
|
-
- Create pattern with block variants
|
|
823
|
-
- Confirm HTML renders correctly before editor JS loads
|
|
824
|
-
- Verify CSS loads properly
|
|
825
|
-
7. Test responsive breakpoints (if applicable):
|
|
826
|
-
- Resize browser window
|
|
827
|
-
- Verify layout adapts correctly
|
|
828
|
-
8. Test accessibility:
|
|
829
|
-
- Keyboard navigation through interactive elements
|
|
830
|
-
- Screen reader announcements
|
|
831
|
-
- Focus ring visibility
|
|
832
|
-
|
|
833
|
-
### Styling Feature Parity Validation
|
|
834
|
-
|
|
835
|
-
For components with variants (Button, Link, Chip, etc.), verify complete coverage:
|
|
836
|
-
|
|
837
|
-
```
|
|
838
|
-
Component: Button
|
|
839
|
-
Intents: primary ✓, secondary ✓, negative ✓
|
|
840
|
-
Sizes: small ✓, medium ✓, large ✓
|
|
841
|
-
Behaviour: hug ✓, full ✓
|
|
842
|
-
States: base ✓, hover ✓, focus ✓, active ✓, disabled ✓
|
|
843
|
-
CSS Classes: .tds-button--intent-primary ✓, .tds-button--size-small ✓, etc.
|
|
844
|
-
```
|
|
845
|
-
|
|
846
|
-
- [ ] All intent variants styled (must match React exactly)
|
|
847
|
-
- [ ] All size variants styled (must match React exactly)
|
|
848
|
-
- [ ] All behaviour variants styled (must match React exactly)
|
|
849
|
-
- [ ] All state handlers present (hover, focus-visible, active, disabled)
|
|
850
|
-
- [ ] CSS custom properties for all tokens (colors, spacing, typography)
|
|
851
|
-
- [ ] Focus rings use consistent `var(--focus-border)`
|
|
852
|
-
- [ ] Transitions preserved from React component
|
|
853
|
-
- [ ] No visual regressions compared to React
|
|
854
|
-
|
|
855
|
-
---
|
|
856
|
-
|
|
857
|
-
## Debugging & Troubleshooting
|
|
858
|
-
|
|
859
|
-
### Block not appearing in Gutenberg?
|
|
860
|
-
|
|
861
|
-
1. Check `block.json` has `name: "tds/..."`
|
|
862
|
-
2. Verify `edit.js` and `save.js` are exported as default
|
|
863
|
-
3. Check console for JavaScript errors
|
|
864
|
-
4. Rebuild: `npm run build`
|
|
865
|
-
|
|
866
|
-
### Styles not loading?
|
|
867
|
-
|
|
868
|
-
1. Verify CSS files in `block.json` point to correct paths
|
|
869
|
-
2. Check class names match SCSS in `theme-scss`
|
|
870
|
-
3. Ensure theme-scss is installed: `npm install @times-design-system/theme-scss`
|
|
871
|
-
4. **Styling gap**: Compare `style.css` line count to React component — if significantly lower, styles may be incomplete
|
|
872
|
-
- Check for all variant modifiers: grep `.tds-<component>--` src/blocks/<component>/style.css
|
|
873
|
-
- Verify state handlers (hover, focus, active, disabled) are present
|
|
874
|
-
- Copy missing styles from React component
|
|
875
|
-
|
|
876
|
-
### Attributes not saving?
|
|
877
|
-
|
|
878
|
-
1. Verify attribute names match in `block.json`, `edit.js`, and `save.js`
|
|
879
|
-
2. Ensure `setAttributes({ key: value })` is called correctly
|
|
880
|
-
3. Check attribute types match intended use
|
|
881
|
-
|
|
882
|
-
### Block doesn't render in patterns?
|
|
883
|
-
|
|
884
|
-
1. Verify `render.php` exists in block directory
|
|
885
|
-
2. Check `block.json` has `"render": "file:./render.php"` reference
|
|
886
|
-
3. Rebuild with `npm run build` to copy render.php to dist/
|
|
887
|
-
4. Verify render.php HTML structure matches save.js exactly
|
|
888
|
-
5. Test in WordPress patterns (not just editor)
|
|
889
|
-
|
|
890
|
-
---
|
|
891
|
-
|
|
892
|
-
## References
|
|
893
|
-
|
|
894
|
-
- [WordPress Blocks Documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/)
|
|
895
|
-
- [Gutenberg Block API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/)
|
|
896
|
-
- [WordPress Components](https://github.com/WordPress/gutenberg/tree/trunk/packages/components)
|
|
897
|
-
- [BEM Naming Convention](http://getbem.com/)
|
|
898
|
-
- [Times Design System Tokens](../../packages/tokens/README.md)
|
|
899
|
-
|
|
900
|
-
---
|
|
901
|
-
|
|
902
|
-
## Version History
|
|
903
|
-
|
|
904
|
-
- **v1.1.0** (May 2026): Initial WordPress block transformation guide
|
|
905
|
-
- Button block reference implementation
|
|
906
|
-
- Class builder utilities
|
|
907
|
-
- Inspector controls patterns
|
|
908
|
-
- Build and plugin generation setup
|