@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
|
@@ -1,385 +0,0 @@
|
|
|
1
|
-
# Block Creation Checklist
|
|
2
|
-
|
|
3
|
-
**🚀 Quick Start:** Run `npm run block:status` to see transformation progress, then `npm run block:create -- ComponentName` for guidance on any component.
|
|
4
|
-
|
|
5
|
-
Use this checklist when creating each new WordPress block from a React component.
|
|
6
|
-
|
|
7
|
-
## 1. Analysis
|
|
8
|
-
|
|
9
|
-
- [ ] Reviewed React component in `packages/components-react/src/<ComponentName>/`
|
|
10
|
-
- [ ] Listed all props and their types
|
|
11
|
-
- [ ] Identified variant combinations (enums)
|
|
12
|
-
- [ ] Checked for external dependencies (icons, utilities)
|
|
13
|
-
- [ ] Noted any special styling requirements
|
|
14
|
-
|
|
15
|
-
## 2. Setup
|
|
16
|
-
|
|
17
|
-
- [ ] Created directory: `src/blocks/<component-name>/`
|
|
18
|
-
- [ ] Created `block.json` manifest
|
|
19
|
-
- [ ] Created `index.js` registration file
|
|
20
|
-
- [ ] Created `edit.js` editor component
|
|
21
|
-
- [ ] Created `save.js` frontend component (static output only, no event handlers)
|
|
22
|
-
- [ ] Created `render.php` server-side rendering callback
|
|
23
|
-
- [ ] Created `style.css` frontend styles
|
|
24
|
-
- [ ] Created `style-editor.css` (if needed)
|
|
25
|
-
|
|
26
|
-
## 3. block.json
|
|
27
|
-
|
|
28
|
-
- [ ] Set `name` to `tds/<component-name>`
|
|
29
|
-
- [ ] Set descriptive `title`
|
|
30
|
-
- [ ] Added `"render": "file:./render.php"` for server-side rendering
|
|
31
|
-
- [ ] Added all React props as `attributes`
|
|
32
|
-
- [ ] Set appropriate `type` for each attribute
|
|
33
|
-
- [ ] Added `enum` arrays for variant props
|
|
34
|
-
- [ ] Set sensible `default` values
|
|
35
|
-
- [ ] Added clear `description` for each attribute
|
|
36
|
-
- [ ] Configured `supports` object (spacing, align, etc.)
|
|
37
|
-
|
|
38
|
-
## 4. edit.js
|
|
39
|
-
|
|
40
|
-
- [ ] Imported `useBlockProps` from `@wordpress/block-editor`
|
|
41
|
-
- [ ] Imported `InspectorControls` from `@wordpress/block-editor`
|
|
42
|
-
- [ ] Imported appropriate components from `@wordpress/components`
|
|
43
|
-
- [ ] Used `buildButtonClass` or similar utility from `src/utils/`
|
|
44
|
-
- [ ] Added `InspectorControls` with `PanelBody`
|
|
45
|
-
- [ ] Created control for each attribute
|
|
46
|
-
- [ ] Called `setAttributes()` for each control
|
|
47
|
-
- [ ] Rendered preview of component in editor
|
|
48
|
-
- [ ] Added editor styles import
|
|
49
|
-
|
|
50
|
-
## 5. save.js
|
|
51
|
-
|
|
52
|
-
- [ ] Used `useBlockProps.save()` (no event handlers or state)
|
|
53
|
-
- [ ] Output structure matches what `render.php` outputs
|
|
54
|
-
- [ ] No dynamic behavior or client-side logic
|
|
55
|
-
- [ ] Included proper ARIA attributes
|
|
56
|
-
|
|
57
|
-
## 5b. render.php
|
|
58
|
-
|
|
59
|
-
- [ ] Created PHP file that mirrors `save.js` output
|
|
60
|
-
- [ ] Used `sanitize_*()` and `esc_*()` functions for all attributes
|
|
61
|
-
- [ ] Used `get_block_wrapper_attributes()` for wrapper
|
|
62
|
-
- [ ] Used `wp_kses_post()` for any rich content
|
|
63
|
-
- [ ] Conditionally rendered elements based on attributes
|
|
64
|
-
- [ ] Added proper PHPDoc header with @package taghavior
|
|
65
|
-
|
|
66
|
-
## 6b. Pattern Testing
|
|
67
|
-
|
|
68
|
-
- [ ] Verified block renders in patterns (server-side rendering)
|
|
69
|
-
- [ ] Tested block with various attribute combinations in patterns
|
|
70
|
-
- [ ] Confirmed HTML output in pattern matches `render.php` structure
|
|
71
|
-
- [ ] Included proper ARIA attributes
|
|
72
|
-
|
|
73
|
-
## 6. Styling — Full Parity with React Components
|
|
74
|
-
|
|
75
|
-
### 6a. Copy Styles from React Component
|
|
76
|
-
|
|
77
|
-
- [ ] Located React component styles in `packages/components-react/src/<ComponentName>/<ComponentName>.scss` or `.css`
|
|
78
|
-
- [ ] Identified all style segments: base styles, variant modifiers, state handlers (hover, focus, active, disabled)
|
|
79
|
-
- [ ] Copied complete CSS from React component to WordPress `style.css`
|
|
80
|
-
- [ ] **CRITICAL**: All CSS custom properties (design tokens) are preserved — NO hardcoded values
|
|
81
|
-
- [ ] Followed BEM naming: `.tds-<component>`, `.tds-<component>--modifier` (intent variants, size variants, behaviour variants)
|
|
82
|
-
- [ ] Ensured state handlers (hover, focus, active, disabled) are included
|
|
83
|
-
- [ ] Verified transitions and animations are preserved
|
|
84
|
-
|
|
85
|
-
### 6b. Resolved Design Token Values
|
|
86
|
-
|
|
87
|
-
WordPress blocks use **resolved design token values** — actual hex colors, pixel sizes, and font definitions compiled directly into CSS. This makes blocks completely self-contained.
|
|
88
|
-
|
|
89
|
-
**Conversion Process**:
|
|
90
|
-
|
|
91
|
-
For each CSS property in the React component:
|
|
92
|
-
|
|
93
|
-
1. Identify the design token it references (e.g., `--spacing-05`, `--interactive-primary-fill-default`)
|
|
94
|
-
2. Look up the resolved value in [SCSS_VARIABLES_REFERENCE.md](./SCSS_VARIABLES_REFERENCE.md)
|
|
95
|
-
3. Replace the variable with the actual value:
|
|
96
|
-
- `gap: var(--spacing-03)` → `gap: 4px`
|
|
97
|
-
- `background: var(--interactive-primary-fill-default)` → `background: #005c8a`
|
|
98
|
-
- `font-family: var(--fontFamily040)` → `font-family: Roboto`
|
|
99
|
-
- `font-size: var(--fontSize030)` → `font-size: 1.6rem` (always use rem units from theme-scss)
|
|
100
|
-
|
|
101
|
-
**Checklist**:
|
|
102
|
-
|
|
103
|
-
- [ ] All hex color values are used directly (e.g., `#005c8a`, never `var(--color-*)`)
|
|
104
|
-
- [ ] All spacing uses pixel values (e.g., `8px`, never `var(--spacing-05)`)
|
|
105
|
-
- [ ] All typography uses concrete values (font-family, font-weight, font-size all explicit)
|
|
106
|
-
- [ ] Border radius values are hardcoded (e.g., `4px`, `9999px`)
|
|
107
|
-
- [ ] No CSS custom property fallbacks (e.g., no `var(--spacing-05, 8px)`)
|
|
108
|
-
- [ ] Blocks work in any WordPress theme (no theme-scss dependency needed)
|
|
109
|
-
- [ ] All color values from design tokens are accurate
|
|
110
|
-
|
|
111
|
-
**Reference**: See `SCSS_VARIABLES_REFERENCE.md` for the complete value mapping
|
|
112
|
-
|
|
113
|
-
### 6c. Variant Coverage
|
|
114
|
-
|
|
115
|
-
- [ ] **Intent variants**: primary, secondary, negative (if applicable) with unique color tokens
|
|
116
|
-
- [ ] **Size variants**: small, medium, large (if applicable) with appropriate padding/font-size
|
|
117
|
-
- [ ] **Behaviour variants**: full width, hug content, etc.
|
|
118
|
-
- [ ] **State handlers**: hover, active, focus-visible with box-shadow rings, disabled with opacity/color changes
|
|
119
|
-
- [ ] **Channel/toggle states**: for components like Chip (on/off states with different colors)
|
|
120
|
-
|
|
121
|
-
### 6d. Testing & Validation
|
|
122
|
-
|
|
123
|
-
- [ ] Tested styles on editor and frontend
|
|
124
|
-
- [ ] Verified all variant combinations render correctly with proper colors/sizing
|
|
125
|
-
- [ ] Checked focus/hover/active states work as expected
|
|
126
|
-
- [ ] Tested disabled state (proper cursor, opacity, color changes)
|
|
127
|
-
- [ ] Tested responsive breakpoints if applicable
|
|
128
|
-
- [ ] Added `style-editor.css` for editor-specific overrides (only if needed)
|
|
129
|
-
- [ ] Confirmed line count of `style.css` is comparable to React component (similar complexity = similar coverage)
|
|
130
|
-
- [ ] Visual comparison: side-by-side React vs WordPress block in patterns/editor to confirm parity
|
|
131
|
-
|
|
132
|
-
## 7. Utilities
|
|
133
|
-
|
|
134
|
-
- [ ] Created helper functions in `src/utils/` (if needed)
|
|
135
|
-
- [ ] Added `classBuilder` for className generation (if complex)
|
|
136
|
-
- [ ] Documented utility functions with JSDoc
|
|
137
|
-
|
|
138
|
-
## 8. Integration
|
|
139
|
-
|
|
140
|
-
- [ ] Added block import to `src/index.js`
|
|
141
|
-
- [ ] Updated `src/utils/classBuilder.js` with new utilities
|
|
142
|
-
- [ ] Verified block appears in Gutenberg inserter
|
|
143
|
-
- [ ] Tested all attribute controls in block inspector
|
|
144
|
-
- [ ] Verified block saves correctly
|
|
145
|
-
- [ ] Tested frontend rendering
|
|
146
|
-
|
|
147
|
-
## 9. Quality Assurance
|
|
148
|
-
|
|
149
|
-
- [ ] No console errors or warnings
|
|
150
|
-
- [ ] Accessibility tested (keyboard nav, screen readers)
|
|
151
|
-
- [ ] Mobile-responsive layout tested
|
|
152
|
-
- [ ] Dark mode compatibility (if applicable)
|
|
153
|
-
- [ ] Block HTML validates without errors
|
|
154
|
-
- [ ] Tested with different content lengths
|
|
155
|
-
|
|
156
|
-
## 10. Tests (Auto-Generated)
|
|
157
|
-
|
|
158
|
-
Tests are **automatically generated** when you create a block with `npm run block:create`:
|
|
159
|
-
|
|
160
|
-
- [ ] Test file created: `__tests__/blocks/<component-name>.test.js`
|
|
161
|
-
- [ ] Test file runs without errors: `npm test`
|
|
162
|
-
- [ ] Review generated test template
|
|
163
|
-
- [ ] Update component rendering in test
|
|
164
|
-
- [ ] Add variant tests based on component props
|
|
165
|
-
- [ ] Add attribute tests based on block.json attributes
|
|
166
|
-
- [ ] Run tests: `npm test` — all tests pass
|
|
167
|
-
- [ ] Add tests for edge cases and state combinations
|
|
168
|
-
|
|
169
|
-
### Test File Structure
|
|
170
|
-
|
|
171
|
-
Generated test files include templates for:
|
|
172
|
-
|
|
173
|
-
- **Basic Rendering** — Component renders with wrapper and element classes
|
|
174
|
-
- **Attribute Handling** — Empty/missing attributes handled gracefully
|
|
175
|
-
- **Variants** — Intent, size, behaviour variants render correctly
|
|
176
|
-
- **Accessibility** — ARIA attributes, semantic HTML tested
|
|
177
|
-
- **State** — Disabled, channel, toggle states render correctly
|
|
178
|
-
- **Multiple Attributes** — Combinations of attributes work together
|
|
179
|
-
|
|
180
|
-
### Test Generation Options
|
|
181
|
-
|
|
182
|
-
Auto-generation happens during block creation:
|
|
183
|
-
|
|
184
|
-
```bash
|
|
185
|
-
# Create block → generates block files AND test file
|
|
186
|
-
npm run block:create -- DialogBox
|
|
187
|
-
|
|
188
|
-
# Create test file only (if needed)
|
|
189
|
-
npm run block:test -- DialogBox
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
### Customizing Generated Tests
|
|
193
|
-
|
|
194
|
-
Templates generate based on component type:
|
|
195
|
-
|
|
196
|
-
- **Button-like** (Button, IconButton, Flag, Toast): intent/size/disabled variants
|
|
197
|
-
- **Text-like** (Text, InputHelperMessage): typography/semantic element variants
|
|
198
|
-
- **Basic** (Divider, AdContainer): minimal template for custom implementation
|
|
199
|
-
|
|
200
|
-
## 11. Documentation
|
|
201
|
-
|
|
202
|
-
- [ ] Updated this checklist
|
|
203
|
-
- [ ] Added block to component list in TRANSFORMATION_GUIDE.md
|
|
204
|
-
- [ ] Documented any special handling or considerations
|
|
205
|
-
- [ ] Added block to component inventory
|
|
206
|
-
|
|
207
|
-
---
|
|
208
|
-
|
|
209
|
-
## Component Transformation Order
|
|
210
|
-
|
|
211
|
-
Track which components have been transformed:
|
|
212
|
-
|
|
213
|
-
- [x] Button (Reference implementation, with tests)
|
|
214
|
-
- [x] Text (with tests)
|
|
215
|
-
- [x] Divider (with tests)
|
|
216
|
-
- [x] Input (with tests)
|
|
217
|
-
- [x] Link (with tests)
|
|
218
|
-
- [x] IconButton (with tests)
|
|
219
|
-
- [x] Chip (with tests)
|
|
220
|
-
- [x] Flag (with tests)
|
|
221
|
-
- [x] Toast (with tests)
|
|
222
|
-
- [x] AdContainer (with tests)
|
|
223
|
-
- [x] DialogBox (with tests)
|
|
224
|
-
- [x] Icon (with tests)
|
|
225
|
-
- [x] InputHelperMessage (with tests)
|
|
226
|
-
- [x] Tab (with tests)
|
|
227
|
-
- [x] TabGroup (with tests)
|
|
228
|
-
|
|
229
|
-
**Status: 15/15 blocks transformed** ✅
|
|
230
|
-
**Test Coverage: 450 tests, 100% pass rate** ✅
|
|
231
|
-
|
|
232
|
-
---
|
|
233
|
-
|
|
234
|
-
## Using the Block Creation Script
|
|
235
|
-
|
|
236
|
-
The block creation system provides automated scaffolding and guidance:
|
|
237
|
-
|
|
238
|
-
### Commands
|
|
239
|
-
|
|
240
|
-
```bash
|
|
241
|
-
# Check transformation status (all components)
|
|
242
|
-
npm run block:status
|
|
243
|
-
|
|
244
|
-
# List pending components ready for transformation
|
|
245
|
-
npm run block:list
|
|
246
|
-
|
|
247
|
-
# Get guidance checklist for a component (read-only)
|
|
248
|
-
npm run block:checklist -- ComponentName
|
|
249
|
-
npm run block:checklist:all
|
|
250
|
-
|
|
251
|
-
# Create block files AND test file automatically
|
|
252
|
-
npm run block:create -- ComponentName
|
|
253
|
-
npm run block:create:all
|
|
254
|
-
|
|
255
|
-
# Generate test file only (if needed)
|
|
256
|
-
npm run block:test -- ComponentName
|
|
257
|
-
|
|
258
|
-
# Show help
|
|
259
|
-
npm run block:create -- --help
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
### Workflow: Create Block + Auto-Generated Tests
|
|
263
|
-
|
|
264
|
-
When you run `npm run block:create -- DialogBox`, the script:
|
|
265
|
-
|
|
266
|
-
1. ✅ Creates `src/blocks/dialog-box/` directory
|
|
267
|
-
2. ✅ Generates `block.json` (config)
|
|
268
|
-
3. ✅ Generates `index.js` (registration)
|
|
269
|
-
4. ✅ Generates `edit.js` (editor UI)
|
|
270
|
-
5. ✅ Generates `save.js` (static output)
|
|
271
|
-
6. ✅ Generates `render.php` (server rendering)
|
|
272
|
-
7. ✅ Generates `style.css` (styles)
|
|
273
|
-
8. ✅ **Generates `__tests__/blocks/dialog-box.test.js`** (tests)
|
|
274
|
-
9. Shows implementation checklist
|
|
275
|
-
|
|
276
|
-
All files include TODO comments and are ready for customization.
|
|
277
|
-
|
|
278
|
-
### Current Transformation Status
|
|
279
|
-
|
|
280
|
-
```
|
|
281
|
-
✅ Transformed (15): Button, Text, Link, Input, Chip, Divider, Flag,
|
|
282
|
-
IconButton, Toast, AdContainer, DialogBox, Icon,
|
|
283
|
-
InputHelperMessage, Tab, TabGroup
|
|
284
|
-
|
|
285
|
-
📊 Test Coverage:
|
|
286
|
-
- 450 total tests across 15 blocks
|
|
287
|
-
- 20 test files (15 blocks + 5 infrastructure/integration)
|
|
288
|
-
- 100% pass rate
|
|
289
|
-
- Auto-generated test templates for each block
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
---
|
|
293
|
-
|
|
294
|
-
Issue: Block doesn't render in patterns
|
|
295
|
-
|
|
296
|
-
**Solution**: Verify `render.php` exists and is referenced in `block.json` with `"render": "file:./render.php"`. Render callbacks provide server-side rendering for patterns.
|
|
297
|
-
|
|
298
|
-
### Issue: Block appears but styles are missing in patterns
|
|
299
|
-
|
|
300
|
-
**Solution**: Ensure theme/plugin enqueues block CSS with `wp_enqueue_style()` on both frontend and editor
|
|
301
|
-
─────────────────────────────────────────────────
|
|
302
|
-
string → "type": "string", "default": ""
|
|
303
|
-
boolean → "type": "boolean", "default": false
|
|
304
|
-
enum (union) → "enum": ["a", "b"], "default": "a"
|
|
305
|
-
number → "type": "number", "default": 0
|
|
306
|
-
Event handler → Not supported (use editor preview only)
|
|
307
|
-
|
|
308
|
-
````
|
|
309
|
-
|
|
310
|
-
---
|
|
311
|
-
|
|
312
|
-
## Common Issues & Solutions
|
|
313
|
-
|
|
314
|
-
### Issue: Block doesn't appear in inserter
|
|
315
|
-
|
|
316
|
-
**Solution**: Verify `block.json` has `name: "tds/..."` and `index.js` imports block registration
|
|
317
|
-
|
|
318
|
-
### Issue: Attributes not persisting
|
|
319
|
-
|
|
320
|
-
**Solution**: Check attribute names match exactly in `block.json`, `edit.js`, `save.js`
|
|
321
|
-
|
|
322
|
-
### Issue: Styles not loading
|
|
323
|
-
|
|
324
|
-
**Solution**: Verify CSS paths in `block.json` and ensure theme-scss is in dependencies
|
|
325
|
-
|
|
326
|
-
### Issue: Styles incomplete or missing variants
|
|
327
|
-
|
|
328
|
-
**Solution**: Compare `style.css` line count to React component to identify gaps
|
|
329
|
-
```bash
|
|
330
|
-
# Check line count
|
|
331
|
-
wc -l src/blocks/<component>/style.css
|
|
332
|
-
wc -l packages/components-react/src/<ComponentName>/<ComponentName>.scss
|
|
333
|
-
|
|
334
|
-
# If WordPress component is <50% of React component, styles are incomplete
|
|
335
|
-
# Copy missing variant modifiers from React component:
|
|
336
|
-
grep 'tds-<component>--' packages/components-react/src/<ComponentName>/<ComponentName>.scss
|
|
337
|
-
# Ensure all variants are in WordPress style.css
|
|
338
|
-
```
|
|
339
|
-
|
|
340
|
-
**Typical missing patterns**:
|
|
341
|
-
- Intent variant modifiers (primary, secondary, negative)
|
|
342
|
-
- Size variant modifiers (small, medium, large)
|
|
343
|
-
- State handlers (hover, focus-visible, active, disabled)
|
|
344
|
-
- Focus ring styling with ::after pseudo-element
|
|
345
|
-
- Behaviour modifiers (full, hug)
|
|
346
|
-
|
|
347
|
-
### Issue: Block styles differ from React component
|
|
348
|
-
|
|
349
|
-
**Solution**: Use visual regression testing
|
|
350
|
-
1. Open React component in Storybook
|
|
351
|
-
2. Render WordPress block in editor side-by-side
|
|
352
|
-
3. Compare colors, spacing, typography for each variant
|
|
353
|
-
4. Verify all CSS custom properties use `var(--token-name)` format
|
|
354
|
-
5. Copy any missing styles from React component
|
|
355
|
-
|
|
356
|
-
### Issue: Inspector controls not working
|
|
357
|
-
|
|
358
|
-
**Solution**: Verify `setAttributes()` is called with correct attribute name and value
|
|
359
|
-
|
|
360
|
-
### Issue: Block renders in editor but not in patterns
|
|
361
|
-
|
|
362
|
-
**Solution**: Verify server-side render callback is properly configured
|
|
363
|
-
1. Check `render.php` exists in block directory
|
|
364
|
-
2. Verify `block.json` contains `"render": "file:./render.php"`
|
|
365
|
-
3. Rebuild: `npm run build` (copies render.php to dist/)
|
|
366
|
-
4. Verify render.php HTML structure matches save.js exactly
|
|
367
|
-
5. Test render.php independently in WordPress patterns
|
|
368
|
-
|
|
369
|
-
---
|
|
370
|
-
|
|
371
|
-
## Helpful Commands
|
|
372
|
-
|
|
373
|
-
```bash
|
|
374
|
-
# Create new block scaffold
|
|
375
|
-
./scripts/create-block.sh <component-name>
|
|
376
|
-
|
|
377
|
-
# Build for development
|
|
378
|
-
npm run dev
|
|
379
|
-
|
|
380
|
-
# Build for production
|
|
381
|
-
npm run build
|
|
382
|
-
|
|
383
|
-
# Validate JSON
|
|
384
|
-
npm run test
|
|
385
|
-
````
|