@times-design-system/components-wordpress 1.2.2-alpha.0 → 1.2.2-alpha.1

package/BLOCK_CREATION_CHECKLIST.md

@@ -16,7 +16,8 @@ Use this checklist when creating each new WordPress block from a React component
 - [ ] Created `block.json` manifest
 - [ ] Created `index.js` registration file
 - [ ] Created `edit.js` editor component
-- [ ] Created `save.js` frontend component
+- [ ] Created `save.js` frontend component (static output only, no event handlers)
+- [ ] Created `render.php` server-side rendering callback
 - [ ] Created `style.css` frontend styles
 - [ ] Created `style-editor.css` (if needed)
 
@@ -24,6 +25,7 @@ Use this checklist when creating each new WordPress block from a React component
 
 - [ ] Set `name` to `tds/<component-name>`
 - [ ] Set descriptive `title`
+- [ ] Added `"render": "file:./render.php"` for server-side rendering
 - [ ] Added all React props as `attributes`
 - [ ] Set appropriate `type` for each attribute
 - [ ] Added `enum` arrays for variant props
@@ -45,10 +47,25 @@ Use this checklist when creating each new WordPress block from a React component
 
 ## 5. save.js
 
-- [ ] Used `useBlockProps.save()`
-- [ ] Returned valid, deterministic HTML
-- [ ] Output matches React component structure
-- [ ] No event handlers or dynamic behavior
+- [ ] Used `useBlockProps.save()` (no event handlers or state)
+- [ ] Output structure matches what `render.php` outputs
+- [ ] No dynamic behavior or client-side logic
+- [ ] Included proper ARIA attributes
+
+## 5b. render.php
+
+- [ ] Created PHP file that mirrors `save.js` output
+- [ ] Used `sanitize_*()` and `esc_*()` functions for all attributes
+- [ ] Used `get_block_wrapper_attributes()` for wrapper
+- [ ] Used `wp_kses_post()` for any rich content
+- [ ] Conditionally rendered elements based on attributes
+- [ ] Added proper PHPDoc header with @package taghavior
+
+## 6b. Pattern Testing
+
+- [ ] Verified block renders in patterns (server-side rendering)
+- [ ] Tested block with various attribute combinations in patterns
+- [ ] Confirmed HTML output in pattern matches `render.php` structure
 - [ ] Included proper ARIA attributes
 
 ## 6. Styling
@@ -111,15 +128,21 @@ Track which components have been transformed:
 
 ## Quick Reference: Prop Type → Block Attribute
 
-```
-React Type          → Block.json Type & Example
+Issue: Block doesn't render in patterns
+
+**Solution**: Verify `render.php` exists and is referenced in `block.json` with `"render": "file:./render.php"`. Render callbacks provide server-side rendering for patterns.
+
+### Issue: Block appears but styles are missing in patterns
+
+**Solution**: Ensure theme/plugin enqueues block CSS with `wp_enqueue_style()` on both frontend and editor
 ─────────────────────────────────────────────────
-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)
-```
+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)
+
+````
 
 ---
 
@@ -157,4 +180,4 @@ npm run build
 
 # Validate JSON
 npm run test
-```
+````

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

@@ -13,6 +13,7 @@
       "padding": true
     }
   },
+  "render": "file:./render.php",
   "attributes": {
     "type": {
       "type": "string",

package/dist/blocks/ad-container/render.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * Ad Container Block Render Callback
+ * 
+ * Renders the Ad Container block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$type = isset($attributes['type']) ? sanitize_text_field($attributes['type']) : '';
+$slot_id = isset($attributes['slotID']) ? sanitize_text_field($attributes['slotID']) : '';
+
+$class_name = 'tds-ad-container';
+if ($type) {
+	$class_name .= ' tds-ad-container--' . sanitize_html_class($type);
+}
+
+$wrapper_attrs = get_block_wrapper_attributes(['class' => $class_name]);
+?>
+
+<div 
+	<?php echo wp_kses_post($wrapper_attrs); ?>
+	<?php echo $slot_id ? 'data-slot-id="' . esc_attr($slot_id) . '"' : ''; ?>
+></div>

package/dist/blocks/button/block.json

@@ -16,6 +16,7 @@
     "customClassName": true
   },
   "textdomain": "times-design-system",
+  "render": "file:./render.php",
   "attributes": {
     "label": {
       "type": "string",

package/dist/blocks/button/render.php

@@ -0,0 +1,71 @@
+<?php
+/**
+ * Button Block Render Callback
+ * 
+ * Renders the Button block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$label = isset($attributes['label']) ? sanitize_text_field($attributes['label']) : 'Button label';
+$intent = isset($attributes['intent']) ? sanitize_text_field($attributes['intent']) : 'primary';
+$size = isset($attributes['size']) ? sanitize_text_field($attributes['size']) : 'large';
+$behaviour = isset($attributes['behaviour']) ? sanitize_text_field($attributes['behaviour']) : 'hug';
+$state = isset($attributes['state']) ? sanitize_text_field($attributes['state']) : 'base';
+$disabled = isset($attributes['disabled']) ? (bool) $attributes['disabled'] : false;
+$href = isset($attributes['href']) ? esc_url($attributes['href']) : '';
+$target = isset($attributes['target']) ? sanitize_text_field($attributes['target']) : '';
+$rel = isset($attributes['rel']) ? sanitize_text_field($attributes['rel']) : '';
+$type = isset($attributes['type']) ? sanitize_text_field($attributes['type']) : 'button';
+$aria_label = isset($attributes['ariaLabel']) ? sanitize_text_field($attributes['ariaLabel']) : '';
+
+// Build button classes
+$classes = ['tds-button'];
+$classes[] = 'tds-button--intent-' . $intent;
+$classes[] = 'tds-button--size-' . $size;
+$classes[] = 'tds-button--behaviour-' . $behaviour;
+$classes[] = 'tds-button--state-' . $state;
+if ($disabled) {
+	$classes[] = 'tds-button--disabled';
+}
+
+$button_class = implode(' ', $classes);
+$element_tag = $href ? 'a' : 'button';
+$wrapper_attrs = get_block_wrapper_attributes(['class' => 'tds-button-wrapper']);
+?>
+
+<div <?php echo wp_kses_post($wrapper_attrs); ?>>
+	<?php
+	if ($element_tag === 'a') {
+		?>
+		<a 
+			class="<?php echo esc_attr($button_class); ?>"
+			href="<?php echo esc_attr($href); ?>"
+			<?php echo $target ? 'target="' . esc_attr($target) . '"' : ''; ?>
+			<?php echo $rel ? 'rel="' . esc_attr($rel) . '"' : ''; ?>
+			<?php echo $aria_label ? 'aria-label="' . esc_attr($aria_label) . '"' : ''; ?>
+		>
+			<span class="tds-button__label-container">
+				<span class="tds-button__label"><?php echo wp_kses_post($label); ?></span>
+			</span>
+		</a>
+		<?php
+	} else {
+		?>
+		<button 
+			class="<?php echo esc_attr($button_class); ?>"
+			<?php echo $disabled ? 'disabled' : ''; ?>
+			type="<?php echo esc_attr($type); ?>"
+			<?php echo $aria_label ? 'aria-label="' . esc_attr($aria_label) . '"' : ''; ?>
+		>
+			<span class="tds-button__label-container">
+				<span class="tds-button__label"><?php echo wp_kses_post($label); ?></span>
+			</span>
+		</button>
+		<?php
+	}
+	?>
+</div>

package/dist/blocks/chip/block.json

@@ -12,6 +12,7 @@
       "margin": true
     }
   },
+  "render": "file:./render.php",
   "attributes": {
     "content": {
       "type": "string",

package/dist/blocks/chip/render.php

@@ -0,0 +1,40 @@
+<?php
+/**
+ * Chip Block Render Callback
+ * 
+ * Renders the Chip block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$content_text = isset($attributes['content']) ? wp_kses_post($attributes['content']) : '';
+$intent = isset($attributes['intent']) ? sanitize_text_field($attributes['intent']) : '';
+$size = isset($attributes['size']) ? sanitize_text_field($attributes['size']) : '';
+$state = isset($attributes['state']) ? sanitize_text_field($attributes['state']) : '';
+$channel = isset($attributes['channel']) ? (bool) $attributes['channel'] : false;
+$toggle = isset($attributes['toggle']) ? (bool) $attributes['toggle'] : false;
+$aria_label = isset($attributes['ariaLabel']) ? sanitize_text_field($attributes['ariaLabel']) : '';
+
+$classes = ['tds-chip'];
+$classes[] = 'tds-chip--intent-' . $intent;
+$classes[] = 'tds-chip--size-' . $size;
+$classes[] = 'tds-chip--state-' . $state;
+if ($channel) {
+	$classes[] = 'tds-chip--channel';
+}
+if ($toggle) {
+	$classes[] = 'tds-chip--toggle';
+}
+
+$wrapper_attrs = get_block_wrapper_attributes(['class' => implode(' ', $classes)]);
+?>
+
+<button 
+	<?php echo wp_kses_post($wrapper_attrs); ?>
+	<?php echo $aria_label ? 'aria-label="' . esc_attr($aria_label) . '"' : ''; ?>
+>
+	<span class="tds-chip__content"><?php echo wp_kses_post($content_text); ?></span>
+</button>

package/dist/blocks/divider/block.json

@@ -13,6 +13,7 @@
     },
     "align": ["wide", "full"]
   },
+  "render": "file:./render.php",
   "attributes": {
     "isDashed": {
       "type": "boolean",

package/dist/blocks/divider/render.php

@@ -0,0 +1,31 @@
+<?php
+/**
+ * Divider Block Render Callback
+ * 
+ * Renders the Divider block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$is_dashed = isset($attributes['isDashed']) ? (bool) $attributes['isDashed'] : false;
+$is_vertical = isset($attributes['isVertical']) ? (bool) $attributes['isVertical'] : false;
+$padding = isset($attributes['padding']) ? (bool) $attributes['padding'] : false;
+
+$classes = ['tds-divider'];
+if ($is_dashed) {
+	$classes[] = 'tds-divider--dashed';
+}
+if ($is_vertical) {
+	$classes[] = 'tds-divider--vertical';
+}
+if ($padding) {
+	$classes[] = 'tds-divider--padding';
+}
+
+$wrapper_attrs = get_block_wrapper_attributes(['class' => implode(' ', $classes)]);
+?>
+
+<div <?php echo wp_kses_post($wrapper_attrs); ?>></div>

package/dist/blocks/flag/block.json

@@ -12,6 +12,7 @@
       "margin": true
     }
   },
+  "render": "file:./render.php",
   "attributes": {
     "label": {
       "type": "string",

package/dist/blocks/flag/render.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * Flag Block Render Callback
+ * 
+ * Renders the Flag block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$label = isset($attributes['label']) ? sanitize_text_field($attributes['label']) : '';
+$content_text = isset($attributes['content']) ? wp_kses_post($attributes['content']) : '';
+$intent = isset($attributes['intent']) ? sanitize_text_field($attributes['intent']) : '';
+$size = isset($attributes['size']) ? sanitize_text_field($attributes['size']) : '';
+$aria_label = isset($attributes['ariaLabel']) ? sanitize_text_field($attributes['ariaLabel']) : '';
+
+$classes = ['tds-flag'];
+$classes[] = 'tds-flag--intent-' . $intent;
+$classes[] = 'tds-flag--size-' . $size;
+
+$wrapper_attrs = get_block_wrapper_attributes(['class' => implode(' ', $classes)]);
+?>
+
+<div 
+	<?php echo wp_kses_post($wrapper_attrs); ?>
+	<?php echo $aria_label ? 'aria-label="' . esc_attr($aria_label) . '"' : ''; ?>
+>
+	<?php if ($label) : ?>
+		<div class="tds-flag__label"><?php echo wp_kses_post($label); ?></div>
+	<?php endif; ?>
+	<div class="tds-flag__content"><?php echo wp_kses_post($content_text); ?></div>
+</div>

package/dist/blocks/icon-button/block.json

@@ -12,6 +12,7 @@
       "margin": true
     }
   },
+  "render": "file:./render.php",
   "attributes": {
     "iconName": {
       "type": "string",

package/dist/blocks/icon-button/render.php

@@ -0,0 +1,46 @@
+<?php
+/**
+ * Icon Button Block Render Callback
+ * 
+ * Renders the Icon Button block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$icon_name = isset($attributes['iconName']) ? sanitize_text_field($attributes['iconName']) : '';
+$round = isset($attributes['round']) ? (bool) $attributes['round'] : false;
+$href = isset($attributes['href']) ? esc_url($attributes['href']) : '';
+$target = isset($attributes['target']) ? sanitize_text_field($attributes['target']) : '';
+$rel = isset($attributes['rel']) ? sanitize_text_field($attributes['rel']) : '';
+$aria_label = isset($attributes['ariaLabel']) ? sanitize_text_field($attributes['ariaLabel']) : '';
+
+$classes = ['tds-icon-button'];
+if ($round) {
+	$classes[] = 'tds-icon-button--round';
+}
+
+$element_tag = $href ? 'a' : 'button';
+$wrapper_attrs = get_block_wrapper_attributes(['class' => implode(' ', $classes)]);
+?>
+
+<?php if ($element_tag === 'a') : ?>
+	<a 
+		<?php echo wp_kses_post($wrapper_attrs); ?>
+		href="<?php echo esc_attr($href); ?>"
+		<?php echo $target ? 'target="' . esc_attr($target) . '"' : ''; ?>
+		<?php echo $rel ? 'rel="' . esc_attr($rel) . '"' : ''; ?>
+		<?php echo $aria_label ? 'aria-label="' . esc_attr($aria_label) . '"' : ''; ?>
+	>
+		<span class="tds-icon-button__icon"><?php echo wp_kses_post($icon_name); ?></span>
+	</a>
+<?php else : ?>
+	<button 
+		<?php echo wp_kses_post($wrapper_attrs); ?>
+		<?php echo $aria_label ? 'aria-label="' . esc_attr($aria_label) . '"' : ''; ?>
+	>
+		<span class="tds-icon-button__icon"><?php echo wp_kses_post($icon_name); ?></span>
+	</button>
+<?php endif; ?>

package/dist/blocks/input/block.json

@@ -12,6 +12,7 @@
       "margin": true
     }
   },
+  "render": "file:./render.php",
   "attributes": {
     "label": {
       "type": "string",

package/dist/blocks/input/render.php

@@ -0,0 +1,39 @@
+<?php
+/**
+ * Input Block Render Callback
+ * 
+ * Renders the Input block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$label = isset($attributes['label']) ? sanitize_text_field($attributes['label']) : '';
+$placeholder = isset($attributes['placeholder']) ? sanitize_text_field($attributes['placeholder']) : '';
+$type = isset($attributes['type']) ? sanitize_text_field($attributes['type']) : 'text';
+$disabled = isset($attributes['disabled']) ? (bool) $attributes['disabled'] : false;
+$required = isset($attributes['required']) ? (bool) $attributes['required'] : false;
+$name = isset($attributes['name']) ? sanitize_text_field($attributes['name']) : '';
+$id = isset($attributes['id']) ? sanitize_text_field($attributes['id']) : '';
+
+$wrapper_attrs = get_block_wrapper_attributes();
+?>
+
+<div <?php echo wp_kses_post($wrapper_attrs); ?>>
+	<?php if ($label) : ?>
+		<label for="<?php echo esc_attr($id); ?>" class="tds-input__label">
+			<?php echo wp_kses_post($label); ?>
+		</label>
+	<?php endif; ?>
+	<input 
+		type="<?php echo esc_attr($type); ?>"
+		<?php echo $placeholder ? 'placeholder="' . esc_attr($placeholder) . '"' : ''; ?>
+		<?php echo $disabled ? 'disabled' : ''; ?>
+		<?php echo $required ? 'required' : ''; ?>
+		<?php echo $name ? 'name="' . esc_attr($name) . '"' : ''; ?>
+		<?php echo $id ? 'id="' . esc_attr($id) . '"' : ''; ?>
+		class="tds-input"
+	/>
+</div>

package/dist/blocks/link/block.json

@@ -12,6 +12,7 @@
       "margin": true
     }
   },
+  "render": "file:./render.php",
   "attributes": {
     "href": {
       "type": "string",

package/dist/blocks/link/render.php

@@ -0,0 +1,44 @@
+<?php
+/**
+ * Link Block Render Callback
+ * 
+ * Renders the Link block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$href = isset($attributes['href']) ? esc_url($attributes['href']) : '';
+$content_text = isset($attributes['content']) ? wp_kses_post($attributes['content']) : '';
+$intent = isset($attributes['intent']) ? sanitize_text_field($attributes['intent']) : '';
+$sentiment = isset($attributes['sentiment']) ? sanitize_text_field($attributes['sentiment']) : '';
+$size = isset($attributes['size']) ? sanitize_text_field($attributes['size']) : '';
+$state = isset($attributes['state']) ? sanitize_text_field($attributes['state']) : '';
+$inline = isset($attributes['inline']) ? (bool) $attributes['inline'] : true;
+$aria_label = isset($attributes['ariaLabel']) ? sanitize_text_field($attributes['ariaLabel']) : '';
+$target = isset($attributes['target']) ? sanitize_text_field($attributes['target']) : '_self';
+$rel = isset($attributes['rel']) ? sanitize_text_field($attributes['rel']) : '';
+
+$classes = ['tds-link'];
+$classes[] = 'tds-link--intent-' . $intent;
+$classes[] = 'tds-link--sentiment-' . $sentiment;
+$classes[] = 'tds-link--size-' . $size;
+$classes[] = 'tds-link--state-' . $state;
+if (!$inline) {
+	$classes[] = 'tds-link--block';
+}
+
+$wrapper_attrs = get_block_wrapper_attributes(['class' => implode(' ', $classes)]);
+?>
+
+<a 
+	<?php echo wp_kses_post($wrapper_attrs); ?>
+	href="<?php echo esc_attr($href); ?>"
+	<?php echo $aria_label ? 'aria-label="' . esc_attr($aria_label) . '"' : ''; ?>
+	<?php echo ($target !== '_self') ? 'target="' . esc_attr($target) . '"' : ''; ?>
+	<?php echo $rel ? 'rel="' . esc_attr($rel) . '"' : ''; ?>
+>
+	<span class="tds-link__content"><?php echo wp_kses_post($content_text); ?></span>
+</a>

package/dist/blocks/text/block.json

@@ -13,6 +13,7 @@
       "padding": false
     }
   },
+  "render": "file:./render.php",
   "attributes": {
     "as": {
       "type": "string",

package/dist/blocks/text/render.php

@@ -0,0 +1,26 @@
+<?php
+/**
+ * Text Block Render Callback
+ * 
+ * Renders the Text typography block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$as = isset($attributes['as']) ? sanitize_text_field($attributes['as']) : 'p';
+$typography_style = isset($attributes['typographyStyle']) ? sanitize_text_field($attributes['typographyStyle']) : '';
+$text_content = isset($attributes['content']) ? wp_kses_post($attributes['content']) : '';
+
+$tag_name = in_array($as, ['p', 'span', 'h1', 'h2', 'h3', 'h4', 'h5'], true) ? $as : 'p';
+$class_name = 'tds-text';
+if ($typography_style) {
+	$class_name .= ' tds-text--' . sanitize_html_class($typography_style);
+}
+
+$wrapper_attrs = get_block_wrapper_attributes(['class' => $class_name]);
+?>
+
+<?php echo wp_sprintf('<%s %s>%s</%s>', $tag_name, wp_kses_post($wrapper_attrs), wp_kses_post($text_content), $tag_name); ?>

package/dist/blocks/toast/block.json

@@ -12,6 +12,7 @@
       "margin": true
     }
   },
+  "render": "file:./render.php",
   "attributes": {
     "label": {
       "type": "string",

package/dist/blocks/toast/render.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Toast Block Render Callback
+ * 
+ * Renders the Toast notification block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$label = isset($attributes['label']) ? wp_kses_post($attributes['label']) : '';
+$intent = isset($attributes['intent']) ? sanitize_text_field($attributes['intent']) : '';
+$link = isset($attributes['link']) ? esc_url($attributes['link']) : '';
+$link_label = isset($attributes['linkLabel']) ? sanitize_text_field($attributes['linkLabel']) : '';
+$timeout = isset($attributes['timeout']) ? intval($attributes['timeout']) : 0;
+
+$classes = ['tds-toast'];
+$classes[] = 'tds-toast--intent-' . $intent;
+
+$wrapper_attrs = get_block_wrapper_attributes(['class' => implode(' ', $classes)]);
+?>
+
+<div 
+	<?php echo wp_kses_post($wrapper_attrs); ?>
+	role="status"
+	aria-live="polite"
+	<?php echo $timeout ? 'data-timeout="' . esc_attr($timeout) . '"' : ''; ?>
+>
+	<div class="tds-toast__content">
+		<div class="tds-toast__label"><?php echo wp_kses_post($label); ?></div>
+	</div>
+	<?php if ($link && $link_label) : ?>
+		<a href="<?php echo esc_attr($link); ?>" class="tds-toast__link"><?php echo wp_kses_post($link_label); ?></a>
+	<?php endif; ?>
+</div>