Playground/blueprint preview

.distignore

@@ -1,10 +1,13 @@
+# Directories
 /.git
 /.github
-/.wordpress-org
 /node_modules
 /src
 /tests
+# Keep .wordpress-org/blueprints in release tags so Playground git:directory
+# installs (and WordPress.org Live Preview) can bootstrap the demo.
 
+# Configuration files
 .distignore
 .editorconfig
 .eslintrc
@@ -13,15 +16,25 @@
 .plugin-data
 .stylelintrc
 .wp-env.json
-CHANGELOG.md
+grumphp.yml
+phpcs.xml.dist
+phpunit.xml.dist
+
+# Dependency management
 composer.json
 composer.lock
-grumphp.yml
-LICENSE.md
 package.json
 package-lock.json
-phpcs.xml.dist
-phpunit.xml.dist
+
+# Documentation
+CHANGELOG.md
+LICENSE.md
 README.md
+
+# Development files
 webpack.config.js
 yarn.lock
+*.log
+*.map
+.DS_Store
+

.gitattributes

@@ -1,10 +1,9 @@
 /.git export-ignore
 /.github export-ignore
-/.wordpress-org export-ignore
 /src/ export-ignore -diff
-/vendor/ export-ignore -diff
 /node_modules export-ignore
 /tests export-ignore
+# Keep .wordpress-org/blueprints and vendor/ available for Playground git:directory installs.
 
 /.distignore export-ignore
 /.editorconfig export-ignore

.wordpress-org/blueprints/blueprint.json

@@ -1,6 +1,6 @@
 {
 	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
-	"landingPage": "/wp-admin/",
+	"landingPage": "/blockparty-button-icon-demo/",
 	"preferredVersions": {
 		"php": "8.1",
 		"wp": "latest"
@@ -11,8 +11,8 @@
 			"pluginData": {
 				"resource": "git:directory",
 				"url": "https://github.com/BeAPI/blockparty-button-icon",
-				"ref": "1.0.0",
-				"refType": "tag"
+				"ref": "playground/blueprint-preview",
+				"refType": "branch"
 			},
 			"options": {
 				"activate": true,
@@ -23,6 +23,14 @@
 			"step": "login",
 			"username": "admin",
 			"password": "password"
+		},
+		{
+			"step": "runPHP",
+			"code": "<?php\nrequire_once 'wordpress/wp-load.php';\n$dir = WP_CONTENT_DIR . '/mu-plugins';\nif ( ! is_dir( $dir ) ) {\n\twp_mkdir_p( $dir );\n}\n$file = $dir . '/blockparty-button-icon-playground-kses.php';\n$mu_plugin = <<<'MUPLUGIN_EOF'\n<?php\n/**\n * WordPress Playground: extend KSES for Blockparty Button Icon demo markup.\n */\nadd_filter( 'wp_kses_allowed_html', function( $tags, $context ) {\n\tif ( 'post' !== $context ) {\n\t\treturn $tags;\n\t}\n\n\tif ( ! isset( $tags['div'] ) ) {\n\t\t$tags['div'] = array();\n\t}\n\t$tags['div']['style']       = true;\n\t$tags['div']['aria-hidden'] = true;\n\t$tags['div']['class']       = true;\n\n\tif ( ! isset( $tags['span'] ) ) {\n\t\t$tags['span'] = array();\n\t}\n\t$tags['span']['class'] = true;\n\n\tif ( ! isset( $tags['a'] ) ) {\n\t\t$tags['a'] = array();\n\t}\n\t$tags['a']['href']      = true;\n\t$tags['a']['class']     = true;\n\t$tags['a']['target']    = true;\n\t$tags['a']['rel']       = true;\n\t$tags['a']['data-type'] = true;\n\t$tags['a']['data-id']   = true;\n\n\treturn $tags;\n}, 10, 2 );\nMUPLUGIN_EOF;\nfile_put_contents( $file, $mu_plugin );\necho file_exists( $file ) ? 'mu-plugin installed' : 'mu-plugin failed';\n"
+		},
+		{
+			"step": "runPHP",
+			"code": "<?php\nrequire_once 'wordpress/wp-load.php';\n$page_content = <<<'BLOCKPARTY_BUTTON_ICON_MARKUP_EOF'\n<!-- wp:paragraph -->\n<p>This page demonstrates the <strong>Blockparty Button Icon</strong> extension for the core Button block. Icons use the native <code>core/icon</code> block inside the link, with left or right placement.</p>\n<!-- /wp:paragraph -->\n\n<!-- wp:spacer {\"height\":\"var:preset|spacing|40\"} -->\n<div style=\"height:var(--wp--preset--spacing--40)\" aria-hidden=\"true\" class=\"wp-block-spacer\"></div>\n<!-- /wp:spacer -->\n\n<!-- wp:buttons -->\n<div class=\"wp-block-buttons\"><!-- wp:button {\"hasIcon\":true,\"iconPosition\":\"left\",\"text\":\"Explore features\",\"url\":\"#\"} -->\n<div class=\"wp-block-button blockparty-button-icon blockparty-button-icon--left\"><a class=\"wp-block-button__link wp-element-button\" href=\"#\"><!-- wp:icon {\"icon\":\"core/shadow\"} /--><span class=\"wp-block-button__label\">Explore features</span></a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"className\":\"is-style-outline\",\"hasIcon\":true,\"iconPosition\":\"left\",\"text\":\"Learn more\",\"url\":\"#\"} -->\n<div class=\"wp-block-button is-style-outline blockparty-button-icon blockparty-button-icon--left\"><a class=\"wp-block-button__link wp-element-button\" href=\"#\"><!-- wp:icon {\"icon\":\"core/caution\"} /--><span class=\"wp-block-button__label\">Learn more</span></a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"hasIcon\":true,\"iconPosition\":\"right\",\"text\":\"Read documentation\",\"url\":\"https://github.com/BeAPI/blockparty-button-icon\"} -->\n<div class=\"wp-block-button blockparty-button-icon blockparty-button-icon--right\"><a class=\"wp-block-button__link wp-element-button\" href=\"https://github.com/BeAPI/blockparty-button-icon\"><!-- wp:icon {\"icon\":\"core/rss\"} /--><span class=\"wp-block-button__label\">Read documentation</span></a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"className\":\"is-style-outline\",\"hasIcon\":true,\"iconPosition\":\"right\",\"text\":\"Continue\",\"url\":\"#\"} -->\n<div class=\"wp-block-button is-style-outline blockparty-button-icon blockparty-button-icon--right\"><a class=\"wp-block-button__link wp-element-button\" href=\"#\"><!-- wp:icon {\"icon\":\"core/arrow-right\"} /--><span class=\"wp-block-button__label\">Continue</span></a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->\n\n<!-- wp:spacer {\"height\":\"var:preset|spacing|40\"} -->\n<div style=\"height:var(--wp--preset--spacing--40)\" aria-hidden=\"true\" class=\"wp-block-spacer\"></div>\n<!-- /wp:spacer -->\n\n<!-- wp:paragraph {\"fontSize\":\"small\"} -->\n<p class=\"has-small-font-size\">Edit any button in the block editor and use the Icon controls to toggle the icon, change its position, or adjust horizontal block gap.</p>\n<!-- /wp:paragraph -->\nBLOCKPARTY_BUTTON_ICON_MARKUP_EOF;\n\n$page_id = wp_insert_post(\n\tarray(\n\t\t'post_title'   => 'Blockparty Button Icon',\n\t\t'post_name'    => 'blockparty-button-icon-demo',\n\t\t'post_content' => $page_content,\n\t\t'post_status'  => 'publish',\n\t\t'post_type'    => 'page',\n\t)\n);\necho 'Page created with ID: ' . $page_id;\n?>\n"
 		}
 	]
 }

README.md

@@ -0,0 +1,134 @@
+[![Be API Github Banner](.github/banner-github.png)](https://beapi.fr)
+
+[![Test with WordPress Playground](https://img.shields.io/badge/Test%20with-WordPress%20Playground-0073aa?style=for-the-badge&logo=wordpress&logoColor=white)](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/BeAPI/blockparty-button-icon/refs/heads/playground/blueprint-preview/.wordpress-org/blueprints/blueprint.json)
+
+# Blockparty Button Icon
+
+Extend the WordPress **core Button** block (`core/button`) with optional icons, placement controls, and spacing between icon and label.
+
+## Features
+
+- **Core block extension**: No new block name — editors keep using the familiar Button block
+- **Optional icon**: Insert an icon as an inner block (defaults to `core/icon` on WordPress 7.0+)
+- **Icon position**: Display the icon to the left or right of the label
+- **Block gap**: Control horizontal spacing between icon and text via block spacing settings
+- **Valid markup**: Icons render inside links with a `span` wrapper on the front end (phrasing content)
+- **Extensible**: Filter which icon block types may be inserted into a button
+
+## Requirements
+
+- WordPress 7.0 or higher
+- PHP 8.1 or higher
+- Gutenberg block editor
+
+## Installation
+
+### Manual installation
+
+1. Download the plugin files
+2. Upload the `blockparty-button-icon` folder to `/wp-content/plugins/`
+3. Activate the plugin through the **Plugins** screen in WordPress
+
+### Composer installation
+
+```bash
+composer require beapi/blockparty-button-icon
+```
+
+## Usage
+
+### Enable an icon on a button
+
+1. Add or select a **Button** block in the editor
+2. Open the block **Styles** panel (sidebar)
+3. Turn on **Show icon**
+4. Choose **Left** or **Right** for icon position
+5. Use the block toolbar **Icon** control to pick or replace the icon
+6. Adjust **Block spacing → Block gap** (horizontal) to change the space between icon and label
+
+### Allowed icon blocks
+
+By default, only `core/icon` is allowed inside the button link.
+
+Customize the list with the `blockparty_button_icon_allowed_icon_blocks` filter:
+
+```php
+add_filter(
+	'blockparty_button_icon_allowed_icon_blocks',
+	static function (): array {
+		return array( 'core/icon', 'blockparty/icon' );
+	}
+);
+```
+
+The first block type in the filtered list is used when the editor creates a new icon inner block.
+
+## Accessibility
+
+- Button label text is wrapped in `<span class="wp-block-button__label">` when an icon is present, keeping a clear text node for assistive technologies
+- On the front end, `core/icon` outer wrappers are output as `span` elements when rendered inside button links
+
+## Generated markup example
+
+```html
+<div class="wp-block-button blockparty-button-icon blockparty-button-icon--left">
+	<a class="wp-block-button__link wp-element-button" href="#" style="gap:var(--wp--preset--spacing--20)">
+		<span class="wp-block-icon" aria-hidden="true">…</span>
+		<span class="wp-block-button__label">Get started</span>
+	</a>
+</div>
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 24.18+ and npm 11.16+ (see `package.json` `engines`)
+- Composer 2.x
+
+### Build
+
+```bash
+composer install
+npm install
+npm run build
+```
+
+### Watch mode
+
+```bash
+npm start
+```
+
+### Linting
+
+```bash
+composer cs
+npm run lint:js src
+npm run lint:css -- "src/**/*.scss"
+```
+
+### WordPress Playground blueprint
+
+The [Playground blueprint](.wordpress-org/blueprints/blueprint.json) installs the plugin from the `playground/blueprint-preview` branch, which includes built assets and Composer `vendor/` for demos. Update that branch after releases when you change the public demo.
+
+### Internationalization
+
+```bash
+npm run make-pot
+npm run make-json
+```
+
+## Support
+
+For bug reports and feature requests, use the [GitHub issues](https://github.com/BeAPI/blockparty-button-icon/issues) page.
+
+## Changelog
+
+See [readme.txt](readme.txt) and [CHANGELOG.md](CHANGELOG.md) for version history.
+
+Developed with ❤️ by [Be API](https://beapi.fr)
+
+## License
+
+GPL-2.0-or-later

build/index.asset.php

@@ -0,0 +1,16 @@
+<?php return array(
+	'dependencies' => array(
+		'react-jsx-runtime',
+		'wp-block-editor',
+		'wp-blocks',
+		'wp-components',
+		'wp-data',
+		'wp-element',
+		'wp-hooks',
+		'wp-i18n',
+		'wp-keycodes',
+		'wp-primitives',
+		'wp-url'
+	),
+	'version' => 'ff595fb21b7020ff3bb6'
+);