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

package/TRANSFORMATION_GUIDE.md

@@ -0,0 +1,635 @@
+# React to WordPress Gutenberg Blocks Transformation Guide
+
+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`.
+
+## Overview
+
+- **Framework**: React-based Gutenberg blocks using `@wordpress/element`
+- **Target**: WordPress 6.0+ with Full Site Editing (FSE) support
+- **Styling**: SCSS from `@times-design-system/theme-scss` with CSS design tokens
+- **Architecture**: Separate implementation (not wrapping React components)
+- **Versioning**: Synchronized with React component package (currently v1.1.0)
+- **Distribution**: NPM package + WordPress plugin
+
+---
+
+## Directory Structure
+
+```
+packages/components-wordpress/
+├── src/
+│   ├── blocks/
+│   │   ├── button/          # Each block gets its own folder
+│   │   │   ├── block.json   # Gutenberg block manifest (REQUIRED)
+│   │   │   ├── index.js     # Block registration (REQUIRED)
+│   │   │   ├── edit.js      # Editor component (REQUIRED)
+│   │   │   ├── save.js      # Frontend output component (REQUIRED)
+│   │   │   ├── style.css    # Frontend styles
+│   │   │   └── style-editor.css # Editor-only styles
+│   │   ├── text/
+│   │   ├── input/
+│   │   └── ... (other blocks)
+│   ├── utils/
+│   │   └── classBuilder.js  # Shared utility functions (BEM className builder)
+│   └── index.js             # Main entry point (imports all blocks)
+├── package.json
+├── rollup.config.js
+├── plugin.php               # WordPress plugin entry point (auto-generated)
+└── dist/                    # Built output
+```
+
+---
+
+## Step-by-Step Transformation Process
+
+### 1. **Analyze the React Component**
+
+Before starting, examine the React component in `packages/components-react/src/<ComponentName>/`:
+
+```bash
+cd packages/components-react/src/<ComponentName>
+ls -la
+```
+
+Note:
+
+- **Props**: Identify all component props and their types
+- **Variants**: List all variant combinations (enum values)
+- **Styling**: Check CSS/SCSS dependencies
+- **External deps**: Note any icon systems, hooks, or utilities used
+
+**Example (Button component)**:
+
+```
+Props:
+  - label (string): Button text
+  - intent (enum: primary | secondary | negative)
+  - size (enum: small | medium | large)
+  - behaviour (enum: hug | full)
+  - state (enum: base | hover | pressed | loading | disabled | focus)
+  - disabled (boolean)
+  - href, target, rel (link attributes)
+  - type (button type)
+  - iconLeft, iconRight (icon names)
+```
+
+### 2. **Create Block Directory Structure**
+
+```bash
+mkdir -p packages/components-wordpress/src/blocks/<component-name>
+```
+
+### 3. **Create block.json (Block Manifest)**
+
+`block.json` declares the block to WordPress and defines its interface. This is the most critical file.
+
+**Template**:
+
+```json
+{
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 3,
+  "name": "times/<block-name>",
+  "title": "Block Display Name",
+  "category": "common",
+  "description": "Brief description",
+  "icon": "admin-generic",
+  "supports": {
+    "html": false,
+    "spacing": {
+      "margin": true,
+      "padding": false
+    },
+    "align": true,
+    "customClassName": true
+  },
+  "textdomain": "times-design-system",
+  "attributes": {
+    "prop1": {
+      "type": "string|boolean|number|array|object",
+      "default": "default-value",
+      "description": "Prop description"
+    }
+  },
+  "editorScript": "file:./index.js",
+  "editorStyle": "file:./style-editor.css",
+  "style": "file:./style.css"
+}
+```
+
+**Conversion Rules**:
+
+- Each React prop becomes an `attribute`
+- Enum props use `"enum"` array
+- Boolean props use `"type": "boolean"`
+- String/number props use corresponding types
+- Always provide sensible `default` values
+- Add `description` for clarity in block inspector
+
+**Example Button block.json**:
+
+```json
+{
+  "apiVersion": 3,
+  "name": "times/button",
+  "title": "Button",
+  "attributes": {
+    "label": {
+      "type": "string",
+      "default": "Button label"
+    },
+    "intent": {
+      "type": "string",
+      "enum": ["primary", "secondary", "negative"],
+      "default": "primary"
+    },
+    "size": {
+      "type": "string",
+      "enum": ["small", "medium", "large"],
+      "default": "large"
+    }
+  }
+}
+```
+
+### 4. **Create index.js (Block Registration)**
+
+This file registers the block with Gutenberg.
+
+**Template**:
+
+```javascript
+import { registerBlockType } from '@wordpress/blocks';
+import Edit from './edit.js';
+import Save from './save.js';
+import metadata from './block.json';
+
+registerBlockType(metadata.name, {
+  ...metadata,
+  edit: Edit,
+  save: Save
+});
+```
+
+**No customization needed** — this is boilerplate.
+
+### 5. **Create edit.js (Editor Component)**
+
+The `edit.js` component renders the block in the WordPress editor (what users interact with).
+
+**Template Structure**:
+
+```javascript
+import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
+import {
+  PanelBody,
+  SelectControl,
+  TextControl,
+  ToggleControl
+} from '@wordpress/components';
+import { buildButtonClass } from '../../utils/classBuilder.js';
+import './style-editor.css';
+
+export default function Edit({ attributes, setAttributes }) {
+  const { prop1, prop2, prop3 } = attributes;
+
+  const blockProps = useBlockProps({
+    className: 'tds-<component>-wrapper'
+  });
+
+  return (
+    <>
+      <div {...blockProps}>{/* Preview of component */}</div>
+
+      <InspectorControls>
+        <PanelBody title="Component Settings">
+          {/* Inspector controls for editing props */}
+        </PanelBody>
+      </InspectorControls>
+    </>
+  );
+}
+```
+
+**Key Points**:
+
+- Always use `useBlockProps()` from `@wordpress/block-editor`
+- Use `InspectorControls` to expose editable properties
+- Use WordPress components for controls: `TextControl`, `SelectControl`, `ToggleControl`, `PanelBody`
+- Call `setAttributes({ propName: newValue })` to update block state
+- Import shared utilities like `classBuilder.js` for consistent styling
+
+**Example Edit Component (Button)**:
+
+```javascript
+<SelectControl
+  label="Intent (Style)"
+  value={intent}
+  options={[
+    { label: 'Primary', value: 'primary' },
+    { label: 'Secondary', value: 'secondary' },
+    { label: 'Negative', value: 'negative' }
+  ]}
+  onChange={(value) => setAttributes({ intent: value })}
+/>
+```
+
+### 6. **Create save.js (Frontend Output)**
+
+The `save.js` component defines what gets stored/rendered on the website frontend.
+
+**Template**:
+
+```javascript
+import { useBlockProps } from '@wordpress/block-editor';
+import { buildButtonClass } from '../../utils/classBuilder.js';
+
+export default function Save({ attributes }) {
+  const { prop1, prop2, prop3 } = attributes;
+
+  const blockProps = useBlockProps.save({
+    className: 'tds-<component>-wrapper'
+  });
+
+  return <div {...blockProps}>{/* HTML structure rendered on frontend */}</div>;
+}
+```
+
+**Key Points**:
+
+- Must be deterministic (same input = same output always)
+- Always use `useBlockProps.save()`
+- Return valid HTML that matches React component's render output
+- No event handlers or dynamic behavior (it's static HTML)
+- Can be PHP or JavaScript-rendered depending on config
+
+### 7. **Create CSS Files**
+
+#### `style.css` (Frontend Styles)
+
+- Imported on both editor and frontend
+- Contains production CSS for the component
+- References SCSS classes from `theme-scss` package
+- Use CSS variables for tokens
+
+**Template**:
+
+```css
+.tds-<component > -wrapper {
+  /* Component wrapper styles */
+}
+
+.tds-<component > {
+  /* Component styles - mostly inherited from theme-scss */
+}
+
+.tds-<component > --full {
+  width: 100%;
+}
+```
+
+#### `style-editor.css` (Editor Styles)
+
+- Only loaded in WordPress editor
+- Can override styles for better editing experience
+- Optional — only add if editor preview differs significantly from frontend
+
+### 8. **Create/Update Utility Functions**
+
+Shared utilities go in `packages/components-wordpress/src/utils/`.
+
+**classBuilder.js** (example):
+
+```javascript
+export function buildButtonClass({
+  intent = 'primary',
+  size = 'large',
+  behaviour = 'hug',
+  state = 'base',
+  disabled = false
+}) {
+  const classes = [
+    'tds-button',
+    `tds-button--intent-${intent}`,
+    `tds-button--size-${size}`,
+    `tds-button--behaviour-${behaviour}`,
+    `tds-button--state-${state}`
+  ];
+
+  if (disabled) {
+    classes.push('tds-button--disabled');
+  }
+
+  return classes.join(' ');
+}
+```
+
+**When to add utilities**:
+
+- Repeated className building logic
+- Common prop validation
+- Shared component behavior
+- BEM convention helpers
+
+### 9. **Register Block in Main index.js**
+
+Add block import to `src/index.js`:
+
+```javascript
+// Already existing
+import './blocks/button/index.js';
+
+// Add new block
+import './blocks/<new-component>/index.js';
+```
+
+---
+
+## Prop-to-Attribute Conversion Reference
+
+| React Prop Type     | Block Attribute     | Example             | Notes                                  |
+| ------------------- | ------------------- | ------------------- | -------------------------------------- |
+| `string`            | `"type": "string"`  | `label: "Button"`   | Simple text                            |
+| `boolean`           | `"type": "boolean"` | `disabled: true`    | Toggle controls                        |
+| `enum` (union type) | `"enum": [...]`     | `intent: "primary"` | SelectControl in inspector             |
+| `number`            | `"type": "number"`  | `size: 16`          | NumberControl                          |
+| `Object`            | `"type": "object"`  | Complex data        | Use JSON serialization                 |
+| `Array`             | `"type": "array"`   | Multiple values     | Use JSON serialization                 |
+| Event handler       | ❌ Not supported    | `onClick`           | Blocks don't support handlers directly |
+
+---
+
+## Inspector Controls Reference
+
+Common WordPress components for the block inspector:
+
+```javascript
+import {
+  TextControl, // Text input
+  NumberControl, // Number input
+  SelectControl, // Dropdown
+  ToggleControl, // On/Off switch
+  CheckboxControl, // Checkbox
+  PanelBody, // Collapsible panel
+  ColorPalette, // Color picker
+  RangeControl, // Slider
+  ButtonGroup // Button group
+} from '@wordpress/components';
+```
+
+**Example**:
+
+```javascript
+<TextControl
+  label="Button Label"
+  value={label}
+  onChange={(value) => setAttributes({ label: value })}
+  placeholder="Enter button text"
+/>
+
+<SelectControl
+  label="Button Size"
+  value={size}
+  options={[
+    { label: 'Small', value: 'small' },
+    { label: 'Medium', value: 'medium' },
+    { label: 'Large', value: 'large' },
+  ]}
+  onChange={(value) => setAttributes({ size: value })}
+/>
+
+<ToggleControl
+  label="Disabled"
+  checked={disabled}
+  onChange={(value) => setAttributes({ disabled: value })}
+/>
+```
+
+---
+
+## Styling Best Practices
+
+### 1. **Class Naming Convention** (BEM)
+
+Follow Block Element Modifier pattern:
+
+- Block: `.tds-button`
+- Element: `.tds-button__label`
+- Modifier: `.tds-button--primary`, `.tds-button--large`
+
+### 2. **Reference Design Tokens**
+
+Use CSS custom properties from `theme-scss`:
+
+```css
+.tds-button {
+  color: var(--color-text-primary);
+  background-color: var(--color-bg-primary);
+  font-family: var(--typography-font-family-body);
+  border-radius: var(--spacing-radius-md);
+}
+```
+
+### 3. **Avoid Inline Styles**
+
+Don't set styles in edit.js:
+
+```javascript
+// ❌ Don't do this
+<div style={{ color: 'red' }}>...</div>
+
+// ✅ Do this instead
+<div className="tds-button--error">...</div>
+```
+
+### 4. **Support Block Spacing Settings**
+
+Enable margin and padding controls in block.json:
+
+```json
+"supports": {
+  "spacing": {
+    "margin": true,
+    "padding": false
+  }
+}
+```
+
+---
+
+## Build and Plugin Generation
+
+### Local Development
+
+```bash
+# Install dependencies
+cd packages/components-wordpress
+npm install
+
+# Development with watch
+npm run dev
+
+# Build once
+npm run build
+```
+
+### Plugin Distribution
+
+The `build:plugin` script generates a WordPress plugin structure:
+
+```
+dist/
+├── plugin.php          # WordPress plugin entry point
+├── block.json          # Root plugin metadata
+└── blocks/
+    ├── button/
+    │   └── ... (compiled block files)
+    └── ... (other blocks)
+```
+
+**Plugin Headers (generated in plugin.php)**:
+
+```php
+<?php
+/**
+ * Plugin Name: Times Design System Blocks
+ * Description: Gutenberg blocks for Times Design System
+ * Version: 1.1.0
+ * Text Domain: times-design-system
+ * Domain Path: /languages
+ * Requires at least: 6.0
+ * Requires PHP: 7.4
+ */
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Conditional Rendering
+
+```javascript
+// In edit.js
+{
+  href ? (
+    <a href={href} className={className}>
+      {label}
+    </a>
+  ) : (
+    <button className={className}>{label}</button>
+  );
+}
+```
+
+### Pattern 2: State Variants
+
+Use modifier classes instead of state props:
+
+```javascript
+const classes = buildButtonClass({
+  intent,
+  size,
+  disabled, // Adds .tds-button--disabled class
+  state // Adds .tds-button--state-{value} class
+});
+```
+
+### Pattern 3: Icon Integration
+
+Icons should be referenced by name (string), not imported:
+
+```javascript
+// Instead of importing an Icon component:
+// ❌ import { PlusIcon } from './icons'
+
+// Use a string reference:
+// ✅ iconName: "plus" → render via CSS or font icon system
+```
+
+### Pattern 4: Accessibility
+
+Always include ARIA attributes:
+
+```javascript
+<button aria-label={ariaLabel} disabled={disabled} type={type}>
+  {label}
+</button>
+```
+
+---
+
+## Checklist for Each New Block
+
+- [ ] Created `src/blocks/<component-name>/` directory
+- [ ] Created `block.json` with all props as attributes
+- [ ] Created `index.js` for block registration
+- [ ] Created `edit.js` with inspector controls
+- [ ] Created `save.js` with frontend HTML output
+- [ ] Created `style.css` with component styling
+- [ ] Created `style-editor.css` if needed for editor preview
+- [ ] Added block import to `src/index.js`
+- [ ] Tested block renders in editor
+- [ ] Tested block saves and displays correctly
+- [ ] Verified styling with `@times-design-system/theme-scss` tokens
+- [ ] Added utility functions to `src/utils/` if needed
+- [ ] Updated this guide if adding new patterns
+
+---
+
+## Component Transformation Order
+
+Suggested order for consistent, dependency-aware transformation:
+
+1. **Button** (done ✓) — Foundation, no dependencies
+2. **Text** — Basic typography, minimal props
+3. **Divider** — Simple layout component
+4. **Input** — Form component
+5. **Link** — Extends button logic
+6. **IconButton** — Builds on button pattern
+7. **Chip** — Multi-prop component
+8. **Flag** — Badge/status component
+9. **Toast** — Notification component
+10. **AdContainer** — Container component
+
+---
+
+## Debugging & Troubleshooting
+
+### Block not appearing in Gutenberg?
+
+1. Check `block.json` has `name: "times/..."`
+2. Verify `edit.js` and `save.js` are exported as default
+3. Check console for JavaScript errors
+4. Rebuild: `npm run build`
+
+### Styles not loading?
+
+1. Verify CSS files in `block.json` point to correct paths
+2. Check class names match SCSS in `theme-scss`
+3. Ensure theme-scss is installed: `npm install @times-design-system/theme-scss`
+
+### Attributes not saving?
+
+1. Verify attribute names match in `block.json`, `edit.js`, and `save.js`
+2. Ensure `setAttributes({ key: value })` is called correctly
+3. Check attribute types match intended use
+
+---
+
+## References
+
+- [WordPress Blocks Documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/)
+- [Gutenberg Block API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/)
+- [WordPress Components](https://github.com/WordPress/gutenberg/tree/trunk/packages/components)
+- [BEM Naming Convention](http://getbem.com/)
+- [Times Design System Tokens](../../packages/tokens/README.md)
+
+---
+
+## Version History
+
+- **v1.1.0** (May 2026): Initial WordPress block transformation guide
+  - Button block reference implementation
+  - Class builder utilities
+  - Inspector controls patterns
+  - Build and plugin generation setup

package/block.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 3,
+  "name": "times/design-system-blocks",
+  "title": "Times Design System Blocks",
+  "category": "times-design-system",
+  "description": "A collection of Gutenberg blocks built with Times Design System components",
+  "textdomain": "times-design-system",
+  "version": "1.1.0"
+}

package/dist/block.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 3,
+  "name": "times/design-system-blocks",
+  "title": "Times Design System Blocks",
+  "category": "times-design-system",
+  "description": "A collection of Gutenberg blocks built with Times Design System components",
+  "textdomain": "times-design-system",
+  "version": "1.1.0"
+}

package/dist/blocks/ad-container/block.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 3,
+  "name": "times/ad-container",
+  "title": "Ad Container",
+  "category": "common",
+  "description": "Advertising container placeholder",
+  "icon": "image",
+  "supports": {
+    "html": false,
+    "spacing": {
+      "margin": true,
+      "padding": true
+    }
+  },
+  "attributes": {
+    "type": {
+      "type": "string",
+      "default": "inline",
+      "enum": ["header", "inline"]
+    },
+    "slotID": {
+      "type": "string",
+      "default": ""
+    }
+  },
+  "example": {}
+}