@times-design-system/components-wordpress 0.4.0 → 0.7.2-alpha.2

package/BLOCK_CREATION_CHECKLIST.md

@@ -0,0 +1,160 @@
+# Block Creation Checklist
+
+Use this checklist when creating each new WordPress block from a React component.
+
+## 1. Analysis
+
+- [ ] Reviewed React component in `packages/components-react/src/<ComponentName>/`
+- [ ] Listed all props and their types
+- [ ] Identified variant combinations (enums)
+- [ ] Checked for external dependencies (icons, utilities)
+- [ ] Noted any special styling requirements
+
+## 2. Setup
+
+- [ ] Created directory: `src/blocks/<component-name>/`
+- [ ] Created `block.json` manifest
+- [ ] Created `index.js` registration file
+- [ ] Created `edit.js` editor component
+- [ ] Created `save.js` frontend component
+- [ ] Created `style.css` frontend styles
+- [ ] Created `style-editor.css` (if needed)
+
+## 3. block.json
+
+- [ ] Set `name` to `times/<component-name>`
+- [ ] Set descriptive `title`
+- [ ] Added all React props as `attributes`
+- [ ] Set appropriate `type` for each attribute
+- [ ] Added `enum` arrays for variant props
+- [ ] Set sensible `default` values
+- [ ] Added clear `description` for each attribute
+- [ ] Configured `supports` object (spacing, align, etc.)
+
+## 4. edit.js
+
+- [ ] Imported `useBlockProps` from `@wordpress/block-editor`
+- [ ] Imported `InspectorControls` from `@wordpress/block-editor`
+- [ ] Imported appropriate components from `@wordpress/components`
+- [ ] Used `buildButtonClass` or similar utility from `src/utils/`
+- [ ] Added `InspectorControls` with `PanelBody`
+- [ ] Created control for each attribute
+- [ ] Called `setAttributes()` for each control
+- [ ] Rendered preview of component in editor
+- [ ] Added editor styles import
+
+## 5. save.js
+
+- [ ] Used `useBlockProps.save()`
+- [ ] Returned valid, deterministic HTML
+- [ ] Output matches React component structure
+- [ ] No event handlers or dynamic behavior
+- [ ] Included proper ARIA attributes
+
+## 6. Styling
+
+- [ ] Updated `style.css` with component styles
+- [ ] Used CSS custom properties for design tokens
+- [ ] Followed BEM naming: `.tds-<component>`, `.tds-<component>--modifier`
+- [ ] Tested styles on editor and frontend
+- [ ] Added `style-editor.css` for editor-specific overrides (if needed)
+
+## 7. Utilities
+
+- [ ] Created helper functions in `src/utils/` (if needed)
+- [ ] Added `classBuilder` for className generation (if complex)
+- [ ] Documented utility functions with JSDoc
+
+## 8. Integration
+
+- [ ] Added block import to `src/index.js`
+- [ ] Updated `src/utils/classBuilder.js` with new utilities
+- [ ] Verified block appears in Gutenberg inserter
+- [ ] Tested all attribute controls in block inspector
+- [ ] Verified block saves correctly
+- [ ] Tested frontend rendering
+
+## 9. Quality Assurance
+
+- [ ] No console errors or warnings
+- [ ] Accessibility tested (keyboard nav, screen readers)
+- [ ] Mobile-responsive layout tested
+- [ ] Dark mode compatibility (if applicable)
+- [ ] Block HTML validates without errors
+- [ ] Tested with different content lengths
+
+## 10. Documentation
+
+- [ ] Updated this checklist
+- [ ] Added block to component list in TRANSFORMATION_GUIDE.md
+- [ ] Documented any special handling or considerations
+- [ ] Added block to component inventory
+
+---
+
+## Component Transformation Order
+
+Track which components have been transformed:
+
+- [x] Button (Reference implementation)
+- [x] Text
+- [x] Divider
+- [x] Input
+- [x] Link
+- [x] IconButton
+- [x] Chip
+- [x] Flag
+- [x] Toast
+- [x] AdContainer
+
+---
+
+## Quick Reference: Prop Type → Block Attribute
+
+```
+React Type          → Block.json Type & Example
+─────────────────────────────────────────────────
+string              → "type": "string", "default": ""
+boolean             → "type": "boolean", "default": false
+enum (union)        → "enum": ["a", "b"], "default": "a"
+number              → "type": "number", "default": 0
+Event handler       → Not supported (use editor preview only)
+```
+
+---
+
+## Common Issues & Solutions
+
+### Issue: Block doesn't appear in inserter
+
+**Solution**: Verify `block.json` has `name: "times/..."` and `index.js` imports block registration
+
+### Issue: Attributes not persisting
+
+**Solution**: Check attribute names match exactly in `block.json`, `edit.js`, `save.js`
+
+### Issue: Styles not loading
+
+**Solution**: Verify CSS paths in `block.json` and ensure theme-scss is in dependencies
+
+### Issue: Inspector controls not working
+
+**Solution**: Verify `setAttributes()` is called with correct attribute name and value
+
+---
+
+## Helpful Commands
+
+```bash
+# Create new block scaffold
+./scripts/create-block.sh <component-name>
+
+# Build for development
+npm run dev
+
+# Build for production
+npm run build
+
+# Validate JSON
+npm run test
+```

package/BUILD.md

@@ -0,0 +1,411 @@
+# WordPress Blocks Build Guide
+
+This document explains the build process for the Times Design System WordPress blocks package.
+
+## Overview
+
+The build process transforms source components into a WordPress plugin distribution with the following steps:
+
+1. **Clean** — Remove old builds
+2. **Rollup Bundle** — Compile JavaScript, copy block files
+3. **Plugin Organization** — Arrange files for WordPress
+
+## Build Process
+
+### Step 1: Install Dependencies
+
+```bash
+cd packages/components-wordpress
+npm install
+```
+
+**Required for build**:
+
+- `rollup` — Module bundler
+- `@rollup/plugin-*` — Rollup plugins for various file types
+- `rollup-plugin-copy` — Copy static files
+- `rollup-plugin-postcss` — Process CSS
+- `@babel/*` — JavaScript transpilation
+- `typescript` — TypeScript support
+
+### Step 2: Build
+
+```bash
+npm run build
+```
+
+This runs:
+
+```bash
+npm run clean                 # Remove old dist/
+npm run build:rollup          # Rollup bundling + copy
+npm run build:plugin          # Organize plugin structure
+```
+
+**Output**: `dist/` folder with:
+
+```
+dist/
+├── plugin.php                 # WordPress plugin entry
+├── block.json                 # Root manifest
+├── index.js                   # ES module
+├── index.cjs                  # CommonJS
+├── index.css                  # Compiled styles
+├── blocks/                    # Block files
+│   ├── button/
+│   │   ├── block.json
+│   │   ├── index.js
+│   │   ├── edit.js
+│   │   ├── save.js
+│   │   ├── style.css
+│   │   └── style-editor.css
+│   └── [more blocks]/
+└── utils/
+    └── classBuilder.js
+```
+
+### Step 3: Development Build
+
+```bash
+npm run dev
+```
+
+Watches for changes and rebuilds automatically. Used during development.
+
+## Build Configuration
+
+### rollup.config.js
+
+The main build configuration:
+
+**Input**: `src/index.js`
+
+**Outputs**:
+
+- `dist/index.js` — ES module (for bundlers)
+- `dist/index.cjs` — CommonJS (for Node)
+
+**Plugins**:
+
+1. **resolve** — Resolves node modules
+   - Handles `.js`, `.jsx`, `.ts`, `.tsx`, `.json`
+   - Uses browser resolution
+2. **commonjs** — Converts CommonJS to ES modules
+3. **json** — Allows importing JSON files
+4. **typescript** — Transpiles TypeScript
+   - Outputs type declarations to `dist/`
+5. **postcss** — Processes CSS
+   - Extracts to `dist/index.css`
+   - Minifies CSS
+   - Creates sourcemaps
+6. **babel** — Transpiles JavaScript
+   - Supports ES6+
+   - JSX support
+7. **copy** — Copies static files
+   - `src/blocks/**/*` → `dist/blocks/`
+   - `src/utils/**/*.js` → `dist/utils/`
+   - `src/**/*.css` → `dist/`
+   - `plugin.php` → `dist/plugin.php`
+   - `block.json` → `dist/block.json`
+
+**External Dependencies** (not bundled):
+
+- `@wordpress/blocks`
+- `@wordpress/block-editor`
+- `@wordpress/components`
+- `@wordpress/element`
+
+These are assumed to be available in WordPress.
+
+### scripts/build-plugin.js
+
+Post-build script that:
+
+1. ✅ Verifies plugin structure
+2. ✅ Checks all blocks have required files
+3. ✅ Reports missing utilities
+4. ✅ Displays build summary
+5. ✅ Validates plugin.php exists
+6. ✅ Verifies block.json manifests
+
+## File Structure for Build
+
+```
+src/
+├── index.js                   # Main entry (registers all blocks)
+├── blocks/
+│   ├── button/
+│   │   ├── block.json         # ← Copied to dist/blocks/button/
+│   │   ├── index.js           # ← Copied to dist/blocks/button/
+│   │   ├── edit.js            # ← Copied to dist/blocks/button/
+│   │   ├── save.js            # ← Copied to dist/blocks/button/
+│   │   ├── style.css          # ← Copied to dist/blocks/button/
+│   │   └── style-editor.css   # ← Copied to dist/blocks/button/
+│   └── [more blocks]/
+├── utils/
+│   └── classBuilder.js        # ← Copied to dist/utils/
+└── [other files]
+
+plugin.php                      # ← Copied to dist/
+block.json                      # ← Copied to dist/
+rollup.config.js                # ← Build config (not copied)
+package.json                    # ← Package info (not copied)
+```
+
+## What Gets Bundled vs Copied
+
+### Bundled (by Rollup)
+
+- `src/index.js` → `dist/index.js` and `dist/index.cjs`
+- All JavaScript imports in index.js
+- CSS (extracted to `dist/index.css`)
+
+### Copied (by Rollup copy plugin)
+
+- `src/blocks/**/*` → `dist/blocks/`
+- `src/utils/**/*.js` → `dist/utils/`
+- `plugin.php` → `dist/plugin.php`
+- `block.json` → `dist/block.json`
+
+## Troubleshooting Build
+
+### Error: Cannot find module '@rollup/plugin-\*'
+
+**Solution**: Install missing dependencies
+
+```bash
+npm install --save-dev @rollup/plugin-babel @rollup/plugin-typescript rollup-plugin-copy rollup-plugin-postcss
+```
+
+### Error: Block not found in dist/blocks/
+
+**Check**:
+
+1. Block folder exists in `src/blocks/<block-name>/`
+2. `block.json` exists in block folder
+3. `src/index.js` imports the block: `import './blocks/<block-name>/index.js'`
+4. Run build again: `npm run build`
+
+### Error: "Cannot compile CSS"
+
+**Solution**:
+
+1. Ensure PostCSS is installed: `npm install --save-dev rollup-plugin-postcss`
+2. Check CSS syntax is valid
+3. Clear dist: `npm run clean`
+4. Rebuild: `npm run build`
+
+### dist/blocks/ is empty
+
+**Check**:
+
+1. Rollup config `copy` targets are correct
+2. Block files exist in `src/blocks/`
+3. Rollup is using correct config: `rollup -c`
+4. No permissions issues on dist/ folder
+
+## Distribution
+
+### For WordPress Plugin Users
+
+The contents of `dist/` are ready to distribute:
+
+```bash
+# Zip for distribution
+cd dist
+zip -r times-design-system-blocks.zip .
+
+# Or copy to WordPress
+cp -r dist/* /path/to/wordpress/wp-content/plugins/times-design-system-blocks/
+```
+
+### For NPM Package Users
+
+```bash
+# Build for publishing
+npm run build
+
+# Publish to npm registry
+npm publish
+```
+
+## Development Workflow
+
+### Adding a New Block
+
+1. Create block directory:
+
+   ```bash
+   ./scripts/create-block.sh myblock
+   ```
+
+2. Edit files in `src/blocks/myblock/`:
+   - `block.json` — Add attributes
+   - `edit.js` — Add inspector controls
+   - `save.js` — Add frontend HTML
+   - `style.css` — Add styles
+
+3. Register in `src/index.js`:
+
+   ```javascript
+   import './blocks/myblock/index.js';
+   ```
+
+4. Build and test:
+   ```bash
+   npm run build
+   # Test in WordPress
+   ```
+
+### Modifying Existing Block
+
+1. Edit files in `src/blocks/<block-name>/`
+2. Save changes
+3. If running `npm run dev`, changes auto-rebuild
+4. If not, manually run `npm run build`
+5. Test changes in WordPress
+
+### Testing Before Build
+
+```bash
+# Validate Rollup config
+npx rollup --help
+
+# Test individual file compilation
+npx rollup --input src/index.js --format esm
+
+# Check file sizes
+npm run build && du -sh dist/*
+```
+
+## Performance Tips
+
+### Reduce Bundle Size
+
+1. **Remove unused blocks**:
+   - Comment out imports in `src/index.js`
+   - Rebuild: `npm run build`
+
+2. **Use external dependencies**:
+   - WordPress packages are external (not bundled)
+   - Keep them that way for smaller bundle
+
+3. **Minify CSS**:
+   - PostCSS config already minifies
+   - CSS is extracted to separate file
+
+### Build Speed
+
+1. **Incremental build** (during dev):
+
+   ```bash
+   npm run dev  # Only rebuilds changed files
+   ```
+
+2. **Skip type checking**:
+   - In `rollup.config.js`, set `typescript: false`
+   - Only for development!
+
+3. **Parallel builds**:
+   - Use `npm-run-all` for multiple builds in parallel
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Build WordPress Blocks
+
+on:
+  push:
+    branches: [main]
+    paths: ['packages/components-wordpress/**']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: |
+          cd packages/components-wordpress
+          npm install
+
+      - name: Build
+        run: |
+          cd packages/components-wordpress
+          npm run build
+
+      - name: Verify output
+        run: |
+          test -d packages/components-wordpress/dist/blocks
+          test -f packages/components-wordpress/dist/plugin.php
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: wordpress-blocks
+          path: packages/components-wordpress/dist/
+```
+
+## Debugging
+
+### Enable Verbose Output
+
+```bash
+# Rollup verbose mode
+npx rollup -c --verbose
+
+# Node debug
+DEBUG=* npm run build
+```
+
+### Check Generated Files
+
+```bash
+# List dist structure
+tree dist/
+
+# Check file sizes
+ls -lh dist/**/*
+
+# Verify block.json syntax
+cat dist/blocks/button/block.json | jq .
+```
+
+### Common Issues Checklist
+
+- [ ] All dependencies installed: `npm install`
+- [ ] Rollup config valid: `npx rollup --help`
+- [ ] Source files exist in `src/blocks/`
+- [ ] `block.json` is valid JSON
+- [ ] Imports in `src/index.js` match block folder names
+- [ ] CSS files have valid syntax
+- [ ] No TypeScript errors in `*.ts` files
+- [ ] plugin.php exists in root
+
+---
+
+## Quick Commands Reference
+
+```bash
+npm run clean               # Remove dist/
+npm run build:rollup        # Run Rollup bundler
+npm run build:plugin        # Run plugin organizer
+npm run build               # Full build (clean + rollup + plugin)
+npm run dev                 # Watch mode for development
+npm run test                # Run tests
+npm run prepublishOnly      # Runs before npm publish
+```
+
+---
+
+For more details on WordPress plugin structure, see:
+
+- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
+- [Gutenberg Blocks](https://developer.wordpress.org/block-editor/)
+- [TRANSFORMATION_GUIDE.md](./TRANSFORMATION_GUIDE.md)

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.7.1](https://github.com/newsuk/times-design-system/compare/@times-design-system/components-wordpress@0.7.0...@times-design-system/components-wordpress@0.7.1) (2026-05-26)
+
+**Note:** Version bump only for package @times-design-system/components-wordpress
+
+# [0.7.0](https://github.com/newsuk/times-design-system/compare/@times-design-system/components-wordpress@0.6.0...@times-design-system/components-wordpress@0.7.0) (2026-05-11)
+
+### Features
+
+- **TDS-76:** update theme reconciliation and publish components for … ([#65](https://github.com/newsuk/times-design-system/issues/65)) ([031e63a](https://github.com/newsuk/times-design-system/commit/031e63a9bf39218b1cf4d82bc763cac2f1c60e0a))
+
+# [0.6.0](https://github.com/newsuk/times-design-system/compare/@times-design-system/components-wordpress@0.5.0...@times-design-system/components-wordpress@0.6.0) (2026-04-14)
+
+### Features
+
+- **TDS-74:** beta component development ([#49](https://github.com/newsuk/times-design-system/issues/49)) ([f98ecaa](https://github.com/newsuk/times-design-system/commit/f98ecaad96b12292d0ab4a7fae73328215d3e945))
+
+# [0.5.0](https://github.com/newsuk/times-design-system/compare/@times-design-system/components-wordpress@0.4.0...@times-design-system/components-wordpress@0.5.0) (2026-03-23)
+
+### Features
+
+- **TDS-72:** repo review ([#46](https://github.com/newsuk/times-design-system/issues/46)) ([e46785a](https://github.com/newsuk/times-design-system/commit/e46785a49ab436598e508e9c934df0cea47a24e8))
+
 # 0.4.0 (2026-02-05)
 
 ### Features

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2017, News UK & Ireland Ltd
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.