@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.
Files changed (175) hide show
  1. package/dist/blocks/ad-container/block.json +10 -0
  2. package/dist/blocks/ad-container/edit.js +17 -1
  3. package/dist/blocks/ad-container/render.php +14 -0
  4. package/dist/blocks/button/block.json +19 -5
  5. package/dist/blocks/button/edit.js +33 -15
  6. package/dist/blocks/button/render.php +24 -2
  7. package/dist/blocks/button/style.css +63 -0
  8. package/dist/blocks/chip/block.json +12 -7
  9. package/dist/blocks/chip/edit.js +20 -17
  10. package/dist/blocks/chip/render.php +14 -2
  11. package/dist/blocks/dialog-box/block.json +10 -0
  12. package/dist/blocks/dialog-box/edit.js +17 -0
  13. package/dist/blocks/dialog-box/render.php +16 -4
  14. package/dist/blocks/divider/block.json +10 -0
  15. package/dist/blocks/divider/edit.js +18 -2
  16. package/dist/blocks/divider/render.php +14 -1
  17. package/dist/blocks/flag/block.json +10 -0
  18. package/dist/blocks/flag/edit.js +27 -2
  19. package/dist/blocks/flag/render.php +14 -0
  20. package/dist/blocks/icon/block.json +10 -0
  21. package/dist/blocks/icon/edit.js +17 -0
  22. package/dist/blocks/icon/render.php +16 -4
  23. package/dist/blocks/icon-button/block.json +15 -0
  24. package/dist/blocks/icon-button/edit.js +33 -1
  25. package/dist/blocks/icon-button/render.php +19 -0
  26. package/dist/blocks/icon-button/style.css +37 -3
  27. package/dist/blocks/input/block.json +10 -0
  28. package/dist/blocks/input/edit.js +27 -1
  29. package/dist/blocks/input/render.php +17 -1
  30. package/dist/blocks/input-helper-message/block.json +10 -0
  31. package/dist/blocks/input-helper-message/edit.js +17 -0
  32. package/dist/blocks/input-helper-message/render.php +16 -4
  33. package/dist/blocks/link/block.json +12 -7
  34. package/dist/blocks/link/edit.js +21 -18
  35. package/dist/blocks/link/render.php +14 -2
  36. package/dist/blocks/tab/block.json +10 -0
  37. package/dist/blocks/tab/edit.js +17 -0
  38. package/dist/blocks/tab/render.php +16 -4
  39. package/dist/blocks/tab-group/block.json +10 -0
  40. package/dist/blocks/tab-group/edit.js +17 -0
  41. package/dist/blocks/tab-group/render.php +16 -4
  42. package/dist/blocks/text/block.json +10 -0
  43. package/dist/blocks/text/edit.js +18 -2
  44. package/dist/blocks/text/render.php +14 -1
  45. package/dist/blocks/toast/block.json +10 -0
  46. package/dist/blocks/toast/edit.js +18 -1
  47. package/dist/blocks/toast/render.php +14 -0
  48. package/dist/index.cjs +389 -148
  49. package/dist/index.cjs.map +1 -1
  50. package/dist/index.js +389 -148
  51. package/dist/index.js.map +1 -1
  52. package/dist/utils/DATA_ATTRIBUTES_USAGE.md +377 -0
  53. package/dist/utils/sanitize-data-attributes.php +109 -0
  54. package/package.json +9 -3
  55. package/BLOCK_CREATION_CHECKLIST.md +0 -385
  56. package/BUILD.md +0 -411
  57. package/CHANGELOG.md +0 -81
  58. package/SCSS_VARIABLES_REFERENCE.md +0 -316
  59. package/STYLING_SYNC_GUIDE.md +0 -306
  60. package/TESTING.md +0 -152
  61. package/TRANSFORMATION_GUIDE.md +0 -908
  62. package/dist/blocks/button/style-resolved.css +0 -153
  63. package/lib/wordpress.js +0 -7
  64. package/rollup.config.js +0 -75
  65. package/scripts/build-plugin.cjs +0 -121
  66. package/scripts/create-block.sh +0 -141
  67. package/scripts/create-wordpress-block-tests.cjs +0 -438
  68. package/scripts/create-wordpress-block.cjs +0 -681
  69. package/src/blocks/ad-container/block.json +0 -29
  70. package/src/blocks/ad-container/edit.js +0 -42
  71. package/src/blocks/ad-container/index.js +0 -10
  72. package/src/blocks/ad-container/render.php +0 -27
  73. package/src/blocks/ad-container/save.js +0 -16
  74. package/src/blocks/ad-container/style-editor.css +0 -4
  75. package/src/blocks/ad-container/style.css +0 -30
  76. package/src/blocks/button/block.json +0 -90
  77. package/src/blocks/button/edit.js +0 -187
  78. package/src/blocks/button/index.js +0 -11
  79. package/src/blocks/button/render.php +0 -71
  80. package/src/blocks/button/save.js +0 -52
  81. package/src/blocks/button/style-editor.css +0 -15
  82. package/src/blocks/button/style-resolved.css +0 -153
  83. package/src/blocks/button/style.css +0 -157
  84. package/src/blocks/chip/block.json +0 -58
  85. package/src/blocks/chip/edit.js +0 -113
  86. package/src/blocks/chip/index.js +0 -10
  87. package/src/blocks/chip/render.php +0 -40
  88. package/src/blocks/chip/save.js +0 -36
  89. package/src/blocks/chip/style-editor.css +0 -5
  90. package/src/blocks/chip/style.css +0 -87
  91. package/src/blocks/dialog-box/block.json +0 -24
  92. package/src/blocks/dialog-box/edit.js +0 -41
  93. package/src/blocks/dialog-box/index.js +0 -17
  94. package/src/blocks/dialog-box/render.php +0 -24
  95. package/src/blocks/dialog-box/save.js +0 -23
  96. package/src/blocks/dialog-box/style.css +0 -23
  97. package/src/blocks/divider/block.json +0 -32
  98. package/src/blocks/divider/edit.js +0 -42
  99. package/src/blocks/divider/index.js +0 -10
  100. package/src/blocks/divider/render.php +0 -31
  101. package/src/blocks/divider/save.js +0 -18
  102. package/src/blocks/divider/style-editor.css +0 -4
  103. package/src/blocks/divider/style.css +0 -37
  104. package/src/blocks/flag/block.json +0 -49
  105. package/src/blocks/flag/edit.js +0 -82
  106. package/src/blocks/flag/index.js +0 -10
  107. package/src/blocks/flag/render.php +0 -34
  108. package/src/blocks/flag/save.js +0 -25
  109. package/src/blocks/flag/style-editor.css +0 -5
  110. package/src/blocks/flag/style.css +0 -54
  111. package/src/blocks/icon/block.json +0 -24
  112. package/src/blocks/icon/edit.js +0 -41
  113. package/src/blocks/icon/index.js +0 -17
  114. package/src/blocks/icon/render.php +0 -24
  115. package/src/blocks/icon/save.js +0 -23
  116. package/src/blocks/icon/style.css +0 -23
  117. package/src/blocks/icon-button/block.json +0 -44
  118. package/src/blocks/icon-button/edit.js +0 -82
  119. package/src/blocks/icon-button/index.js +0 -10
  120. package/src/blocks/icon-button/render.php +0 -46
  121. package/src/blocks/icon-button/save.js +0 -29
  122. package/src/blocks/icon-button/style-editor.css +0 -5
  123. package/src/blocks/icon-button/style.css +0 -31
  124. package/src/blocks/input/block.json +0 -48
  125. package/src/blocks/input/edit.js +0 -78
  126. package/src/blocks/input/index.js +0 -10
  127. package/src/blocks/input/render.php +0 -39
  128. package/src/blocks/input/save.js +0 -27
  129. package/src/blocks/input/style-editor.css +0 -8
  130. package/src/blocks/input/style.css +0 -53
  131. package/src/blocks/input-helper-message/block.json +0 -24
  132. package/src/blocks/input-helper-message/edit.js +0 -42
  133. package/src/blocks/input-helper-message/index.js +0 -17
  134. package/src/blocks/input-helper-message/render.php +0 -24
  135. package/src/blocks/input-helper-message/save.js +0 -23
  136. package/src/blocks/input-helper-message/style.css +0 -23
  137. package/src/blocks/link/block.json +0 -72
  138. package/src/blocks/link/edit.js +0 -151
  139. package/src/blocks/link/index.js +0 -10
  140. package/src/blocks/link/render.php +0 -44
  141. package/src/blocks/link/save.js +0 -46
  142. package/src/blocks/link/style-editor.css +0 -5
  143. package/src/blocks/link/style.css +0 -119
  144. package/src/blocks/tab/block.json +0 -24
  145. package/src/blocks/tab/edit.js +0 -41
  146. package/src/blocks/tab/index.js +0 -17
  147. package/src/blocks/tab/render.php +0 -24
  148. package/src/blocks/tab/save.js +0 -23
  149. package/src/blocks/tab/style.css +0 -23
  150. package/src/blocks/tab-group/block.json +0 -24
  151. package/src/blocks/tab-group/edit.js +0 -41
  152. package/src/blocks/tab-group/index.js +0 -17
  153. package/src/blocks/tab-group/render.php +0 -24
  154. package/src/blocks/tab-group/save.js +0 -23
  155. package/src/blocks/tab-group/style.css +0 -23
  156. package/src/blocks/text/block.json +0 -33
  157. package/src/blocks/text/edit.js +0 -56
  158. package/src/blocks/text/index.js +0 -10
  159. package/src/blocks/text/render.php +0 -26
  160. package/src/blocks/text/save.js +0 -18
  161. package/src/blocks/text/style-editor.css +0 -4
  162. package/src/blocks/text/style.css +0 -7
  163. package/src/blocks/toast/block.json +0 -40
  164. package/src/blocks/toast/edit.js +0 -85
  165. package/src/blocks/toast/index.js +0 -10
  166. package/src/blocks/toast/render.php +0 -37
  167. package/src/blocks/toast/save.js +0 -29
  168. package/src/blocks/toast/style-editor.css +0 -4
  169. package/src/blocks/toast/style.css +0 -67
  170. package/src/index.js +0 -16
  171. package/src/utils/classBuilder.js +0 -53
  172. package/tsconfig.json +0 -116
  173. package/vitest.config.js +0 -28
  174. package/vitest.config.ts +0 -28
  175. package/vitest.setup.ts +0 -129
@@ -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