Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## Unreleased

- Add an **Icon only** position: the label is visually hidden but kept for screen readers, and edited from a required sidebar field
- Fix icon-only editor selection so clicking the button keeps `core/button` selected (Icon panel and required screen-reader label stay available)
- Mark icons rendered inside buttons as decorative (`aria-hidden="true"`)

## 1.0.0 - 2026-10-15

- Initial release
18 changes: 16 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Extend the WordPress **core Button** block (`core/button`) with optional icons,

- **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
- **Icon position**: Display the icon to the left or right of the label, or show the icon only (label kept for screen readers)
- **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
Expand Down Expand Up @@ -42,7 +42,8 @@ composer require beapi/blockparty-button-icon
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
4. Choose **Left**, **Right** or **Icon only** for icon position
- With **Icon only**, the label is hidden in the canvas and on the front end; fill the required **Label (screen readers)** field in the sidebar
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

Expand All @@ -67,6 +68,8 @@ The first block type in the filtered list is used when the editor creates a new

- 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
- Icons inside buttons get `aria-hidden="true"`: the text label always provides the accessible name
- **Icon only** buttons keep the label in the markup and hide it visually (`.blockparty-button-icon--only .wp-block-button__label`), so links and buttons keep an accessible name

## Generated markup example

Expand All @@ -79,6 +82,17 @@ The first block type in the filtered list is used when the editor creates a new
</div>
```

Icon only:

```html
<div class="wp-block-button blockparty-button-icon blockparty-button-icon--only">
<a class="wp-block-button__link wp-element-button" href="#">
<span class="wp-block-icon" aria-hidden="true">…</span>
<span class="wp-block-button__label">Next slide</span>
</a>
</div>
```

## Development

### Prerequisites
Expand Down
33 changes: 31 additions & 2 deletions classes/IconBlockRenderer.php
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@
namespace Blockparty\ButtonIcon;

/**
* Converts core/icon wrappers so markup stays valid inside button links.
* Converts core/icon wrappers so markup stays valid inside button links
* and marks them as decorative.
*/
class IconBlockRenderer {

Expand Down Expand Up @@ -102,7 +103,35 @@ public function render_icon_as_span( string $block_content, array $block ): stri
return $block_content;
}

return self::convert_icon_wrapper_to_span( $block_content );
return self::hide_icon_from_assistive_technologies(
self::convert_icon_wrapper_to_span( $block_content )
);
}

/**
* Marks the icon wrapper as decorative (aria-hidden="true").
*
* Inside a button the text label always provides the accessible name, even
* when it is visually hidden (icon only). An icon aria-label would otherwise
* be announced in addition to the label.
*
* @param string $html Rendered icon block HTML.
* @return string HTML with aria-hidden on the icon wrapper when applicable.
*/
public static function hide_icon_from_assistive_technologies( string $html ): string {
$processor = new \WP_HTML_Tag_Processor( $html );

if ( ! $processor->next_tag( array( 'class_name' => 'wp-block-icon' ) ) ) {
return $html;
}

if ( 'true' === $processor->get_attribute( 'aria-hidden' ) ) {
return $html;
}

$processor->set_attribute( 'aria-hidden', 'true' );

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Régression sur les boutons v1.0.0 sans libellé

Ce filtre tourne au rendu, donc sur tout le contenu déjà publié, sans réenregistrement. Un bouton v1.0.0 avec icône + libellé vide + aria-label sur l'icône (le seul moyen de faire une icône seule avant cette PR) devient un lien sans nom accessible.

Suggestion : ne poser aria-hidden que si le libellé a du texte. Le plus simple est probablement de le faire dans leave_button_with_icon_context() (le filtre render_block_core/button), où tu as le HTML complet du bouton : tu vérifies que .wp-block-button__label n'est pas vide (par exemple avec trim( wp_strip_all_tags( … ) ) sur le contenu du span, ou avec WP_HTML_Processor), puis tu poses aria-hidden sur .wp-block-icon. Sinon, tu laisses l'icône telle quelle. Ça règle aussi le cas « icône seule + libellé vide » (point 3 de la review).

Un test PHPUnit sur ce cas serait bienvenu.


Generated by Claude Code


return $processor->get_updated_html();
}

/**
Expand Down
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"translation-revision-date":"2026-10-15 22:34+0200","generator":"WP-CLI\/2.11.0","source":"build\/index.js","domain":"messages","locale_data":{"messages":{"":{"domain":"messages","lang":"fr_FR","plural-forms":"nplurals=2; plural=(n != 1);"},"Remove icon":["Retirer l\u2019ic\u00f4ne"],"Icon":["Ic\u00f4ne"],"Show icon":["Afficher l\u2019ic\u00f4ne"],"Icon position":["Position de l\u2019ic\u00f4ne"],"Left":["Gauche"],"Right":["Droite"],"Replace Icon":["Remplacer l\u2019ic\u00f4ne"],"Mark as nofollow":["Marquer en nofollow"],"Button text":["Texte du bouton"],"Add text\u2026":["Ajouter du texte\u2026"],"Link":["Lien"]}}}
{"translation-revision-date":"2026-10-15 22:34+0200","generator":"WP-CLI\/2.12.0","source":"build\/index.js","domain":"messages","locale_data":{"messages":{"":{"domain":"messages","lang":"fr_FR","plural-forms":"nplurals=2; plural=(n != 1);"},"Remove icon":["Retirer l\u2019ic\u00f4ne"],"Icon":["Ic\u00f4ne"],"Show icon":["Afficher l\u2019ic\u00f4ne"],"Icon position":["Position de l\u2019ic\u00f4ne"],"Left":["Gauche"],"Right":["Droite"],"Replace Icon":["Remplacer l\u2019ic\u00f4ne"],"Mark as nofollow":["Marquer en nofollow"],"Button text":["Texte du bouton"],"Add text\u2026":["Ajouter du texte\u2026"],"Link":["Lien"],"Icon only":["Ic\u00f4ne seule"],"Label (screen readers)":["Libell\u00e9 (lecteurs d\u2019\u00e9cran)"],"Required. Hidden on screen, announced by assistive technologies.":["Obligatoire. Masqu\u00e9 \u00e0 l\u2019\u00e9cran, annonc\u00e9 par les technologies d\u2019assistance."],"A label is required for an icon-only button to be accessible.":["Un libell\u00e9 est obligatoire pour qu\u2019un bouton ic\u00f4ne seule soit accessible."]}}}
Binary file modified languages/blockparty-button-icon-fr_FR.mo
Binary file not shown.
16 changes: 16 additions & 0 deletions languages/blockparty-button-icon-fr_FR.po
Original file line number Diff line number Diff line change
Expand Up @@ -74,3 +74,19 @@ msgstr "Ajouter du texte…"
#: build/index.js:1
msgid "Link"
msgstr "Lien"

#: build/index.js:1
msgid "Icon only"
msgstr "Icône seule"

#: build/index.js:1
msgid "Label (screen readers)"
msgstr "Libellé (lecteurs d’écran)"

#: build/index.js:1
msgid "Required. Hidden on screen, announced by assistive technologies."
msgstr "Obligatoire. Masqué à l’écran, annoncé par les technologies d’assistance."

#: build/index.js:1
msgid "A label is required for an icon-only button to be accessible."
msgstr "Un libellé est obligatoire pour qu’un bouton icône seule soit accessible."
20 changes: 18 additions & 2 deletions languages/blockparty-button-icon.pot
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ msgstr ""
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"POT-Creation-Date: 2026-10-15T20:12:02+00:00\n"
"POT-Creation-Date: 2026-11-18T18:31:44+00:00\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"X-Generator: WP-CLI 2.11.0\n"
"X-Generator: WP-CLI 2.12.0\n"
"X-Domain: blockparty-button-icon\n"

#. Plugin Name of the plugin
Expand Down Expand Up @@ -58,6 +58,22 @@ msgstr ""
msgid "Right"
msgstr ""

#: build/index.js:1
msgid "Icon only"
msgstr ""

#: build/index.js:1
msgid "Label (screen readers)"
msgstr ""

#: build/index.js:1
msgid "Required. Hidden on screen, announced by assistive technologies."
msgstr ""

#: build/index.js:1
msgid "A label is required for an icon-only button to be accessible."
msgstr ""

#: build/index.js:1
msgid "Replace Icon"
msgstr ""
Expand Down
2 changes: 1 addition & 1 deletion readme.txt
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Blockparty Button Icon enhances the WordPress core Button block (`core/button`)

* Extends the core Button block (no new block name)
* Optional icon via inner blocks (defaults to `core/icon`)
* Icon position: left or right
* Icon position: left, right or icon only (label kept for screen readers)
* Horizontal block gap for icon ↔ label spacing
* Valid HTML inside links (`span` wrapper for icons on the front end)
* Filter `blockparty_button_icon_allowed_icon_blocks` to allow other icon block types
Expand Down
4 changes: 4 additions & 0 deletions src/editor.scss
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@
flex-direction: row-reverse;
}

&.blockparty-button-icon--only .block-editor-block-list__block {
pointer-events: none;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ça corrige bien le point Bugbot 👍. Effets de bord à garder en tête :

  • l'icône interne n'est plus sélectionnable à la souris, seulement par la vue en liste ou au clavier ;
  • son inspecteur expose toujours un aria-label qui est maintenant ignoré au front, dans toutes les positions, à cause du aria-hidden. Un contributeur peut le remplir sans effet.

On pourrait ajouter un texte d'aide, ou masquer ce champ via un filtre editor.BlockEdit quand le core/icon a pour parent un core/button avec hasIcon. Pense aussi à répondre au thread Bugbot et à le résoudre.


Generated by Claude Code

}

.wp-block-icon {
display: inline-flex;
flex-shrink: 0;
Expand Down
61 changes: 60 additions & 1 deletion src/extend-core-button/button-icon-controls.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,27 @@ import {
Button,
ToolbarButton,
ToolbarGroup,
Notice,
PanelBody,
TextControl,
ToggleControl,
// eslint-disable-next-line @wordpress/no-unsafe-wp-apis -- ToggleGroupControl is not yet a stable export in @wordpress/components.
__experimentalToggleGroupControl as ToggleGroupControl,
// eslint-disable-next-line @wordpress/no-unsafe-wp-apis
__experimentalToggleGroupControlOption as ToggleGroupControlOption,
} from '@wordpress/components';
import { ICON_POSITION_LEFT, ICON_POSITION_RIGHT } from './constants';
import {
ICON_POSITION_LEFT,
ICON_POSITION_ONLY,
ICON_POSITION_RIGHT,
} from './constants';
import IconToolbarSvg from './icon-toolbar-svg';
import { getInnerIconClientId } from './get-inner-icon-client-id';
import { openIconInserterForBlock } from './open-icon-inserter';
import {
getButtonLabelPlainText,
plainTextToButtonLabel,
} from './button-label-plain-text';

/**
* Toolbar and inspector controls for button icons.
Expand All @@ -25,6 +35,7 @@ import { openIconInserterForBlock } from './open-icon-inserter';
* @param {string} props.iconPosition Icon position relative to label.
* @param {boolean} props.hasIconBlock Whether core/icon is available.
* @param {string} props.clientId Button block client id.
* @param {string} [props.text] Button label (rich-text HTML).
* @param {( attributes: Object ) => void} props.setAttributes Attribute updater.
* @return {Element} Controls fragment.
*/
Expand All @@ -33,12 +44,16 @@ export default function ButtonIconControls( {
iconPosition,
hasIconBlock,
clientId,
text,
setAttributes,
} ) {
const iconClientId = useSelect(
( select ) => getInnerIconClientId( select, clientId ),
[ clientId ]
);
const isIconOnly = hasIcon && iconPosition === ICON_POSITION_ONLY;
const plainLabel = getButtonLabelPlainText( text );
const isLabelMissing = isIconOnly && '' === plainLabel.trim();

return (
<>
Expand Down Expand Up @@ -105,7 +120,51 @@ export default function ButtonIconControls( {
'blockparty-button-icon'
) }
/>
<ToggleGroupControlOption
value={ ICON_POSITION_ONLY }
label={ __(
'Icon only',
'blockparty-button-icon'
) }
/>
</ToggleGroupControl>
{ isIconOnly && (
<>
<TextControl
label={ __(
'Label (screen readers)',
'blockparty-button-icon'
) }
help={ __(
'Required. Hidden on screen, announced by assistive technologies.',
'blockparty-button-icon'
) }
value={ plainLabel }
required
aria-invalid={ isLabelMissing }
__next40pxDefaultSize
__nextHasNoMarginBottom
onChange={ ( value ) => {
setAttributes( {
text: plainTextToButtonLabel(

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note : chaque frappe remplace text par du texte brut échappé. Toute la mise en forme existante est donc perdue dès la première modification (gras, italique, mais surtout un <span lang="en">, qui compte pour le RGAA 8.7). Ça se comprend vu le besoin, mais il faudrait au moins le documenter (README) pour que ce ne soit pas une surprise quand on repasse en gauche ou droite.


Generated by Claude Code

value
),
} );
} }
/>
{ isLabelMissing && (
<Notice

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

La notice signale l'erreur mais n'empêche pas d'enregistrer. Si on veut une vraie contrainte, on peut passer par lockPostSaving( 'blockparty-button-icon-label' ) / unlockPostSaving de core/editor, avec une clé unique par clientId. Attention dans ce cas à l'éditeur de site, où core/editor se comporte différemment.

Ce n'est pas bloquant pour moi si on ajoute le fallback PHP (pas de aria-hidden quand le libellé est vide) : au pire, l'aria-label de l'icône prend le relais.


Generated by Claude Code

status="error"
isDismissible={ false }
>
{ __(
'A label is required for an icon-only button to be accessible.',
'blockparty-button-icon'
) }
</Notice>
) }
</>
) }
<Button
variant="secondary"
__next40pxDefaultSize
Expand Down
34 changes: 34 additions & 0 deletions src/extend-core-button/button-label-plain-text.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
/**
* Converts the button rich-text label to plain text (for a TextControl).
*
* Uses DOMParser so the markup is parsed in an inert document (no script or
* resource loading).
*
* @param {string|undefined} html Rich-text HTML.
* @return {string} Plain text.
*/
export function getButtonLabelPlainText( html ) {
if ( ! html ) {
return '';
}

const doc = new window.DOMParser().parseFromString(
`<body>${ html }</body>`,
'text/html'
);

return doc.body.textContent || '';
}

/**
* Escapes plain text so it can be stored in the rich-text `text` attribute.
*
* @param {string} text Plain text typed by the editor.
* @return {string} HTML-safe text.
*/
export function plainTextToButtonLabel( text ) {
return ( text || '' )
.replace( /&/g, '&amp;' )
.replace( /</g, '&lt;' )
.replace( />/g, '&gt;' );
}
2 changes: 2 additions & 0 deletions src/extend-core-button/constants.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ export const BUTTON_LABEL_CLASS_NAME = 'wp-block-button__label';

export const ICON_POSITION_LEFT = 'left';
export const ICON_POSITION_RIGHT = 'right';
/** Icon only: label is kept for screen readers but visually hidden. */
export const ICON_POSITION_ONLY = 'only';

export const BUTTON_ICON_ATTRIBUTES = {
hasIcon: {
Expand Down
3 changes: 2 additions & 1 deletion src/extend-core-button/edit-with-icon-toolbar.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,12 @@
* Routes core/button to the icon-aware edit UI or the core edit with toolbar.
*
* @param {Object} props Block edit props.
* @param {Function} OriginalEdit Core button edit component.

Check warning on line 10 in src/extend-core-button/edit-with-icon-toolbar.jsx

View workflow job for this annotation

GitHub Actions / Lint JS and CSS

Prefer a more specific type to `Function`
* @return {Element} Edit element.
*/
export default function EditWithIconToolbar( props, OriginalEdit ) {
const { attributes, setAttributes, clientId } = props;
const { hasIcon, iconPosition } = attributes;
const { hasIcon, iconPosition, text } = attributes;
const hasIconBlock = getRegisteredIconBlocks().length > 0;

return (
Expand All @@ -30,6 +30,7 @@
iconPosition={ iconPosition }
hasIconBlock={ hasIconBlock }
clientId={ clientId }
text={ text }
setAttributes={ setAttributes }
/>
<OriginalEdit { ...props } />
Expand Down
Loading
Loading