v5: Icon Sets/Groups + UI Update

[mike-sheppard]

Summary

• Add support for Icon Sets/Grouping (also multi-location) (closes Feature Request: Add the posibillty to set a directory in the ACF Field Settings #32)
• Update grouped picker ui
• Full a11y rewrite using native <dialog> with focus trap and arrow-key nav, plus fixes for the Enter-key opening the picker (closes [BUG] Hit ENTER key anywhere in the admin page opens an icon picker #34)
• Tooling swapped to Mago + Oxfmt + Oxlint, PHPStan raised 5 → 10, new code-quality CI workflow + extra tests.

Related

• Closes Feature Request: Add the posibillty to set a directory in the ACF Field Settings #32
• Closes [BUG] Hit ENTER key anywhere in the admin page opens an icon picker #34

Issue

• Large + varied sets of icons were all grouped together making it difficult to organise without name prefixes
• Single-directory icon source forced teams with multiple icon sets to merge them on disk (Feature Request: Add the posibillty to set a directory in the ACF Field Settings #32).
• Pressing Enter anywhere in WP admin opened the picker because the trigger button defaulted to type="submit" ([BUG] Hit ENTER key anywhere in the admin page opens an icon picker #34).
• Picker popup had significant a11y gaps: no focus trap, no Escape, list items not
  keyboard-focusable.
• get_svg_icon_uri() returned theme-relative URLs even when icons were stored elsewhere, silently 404'd.

Solution

• Multiple icon locations: filter accepts a list of { path, url, name?, key? }; each renders as a named group in the picker. 'group_by_subdir' => true exposes subfolders as groups automatically.
• Per-field allowed_groups setting: restricts a field to a chosen subset of groups.
• Native <dialog> rewrite: focus trap, Escape, focus restoration, ARIA come for free; manual a11y JS deleted. Icon tiles are real <button>s with arrow-key grid navigation.
• type="button" on all buttons: fixes [BUG] Hit ENTER key anywhere in the admin page opens an icon picker #34.
• get_svg_icon_uri() bug fix: now resolves the matching location's URL.

Impact

• Back-compatible PHP/JS API: single-location filter still works, $plugin->svgs unchanged,
  acfSvgIconPicker.svgs still localized (new groups added alongside).
• DOM hooks changed: .acf-svg-icon-picker__popup-overlay and <li data-svg> are gone, replaced by <dialog class="acf-svg-icon-picker__popup"> and <button class="acf-svg-icon-picker__option">. CSS targeting the old hooks needs updating.
• Browser baseline: native <dialog> requires Chrome 37+, Firefox 98+, Safari 15.4+ (all
  2022+).
• Contributor tooling swap: PHPCS/ESLint/Stylelint replaced by Mago + Oxfmt + Oxlint. PHPStan raised from level 5 → 10. New code-quality.yml workflow.

Usage Changes

// Multiple groups
add_filter('acf_svg_icon_picker_custom_location', fn () => [
    [ 'name' => 'Brand', 'key' => 'brand', 'path' => …, 'url' => … ],
    [ 'name' => 'UI',                      'path' => …, 'url' => … ],
]);

// Auto-grouping by subdir
add_filter('acf_svg_icon_picker_custom_location', fn () => [
    'path' => …, 'url' => …, 'group_by_subdir' => true,
]);

// Per-field allowlist
$fields->addField('industry_icon', 'svg_icon_picker', [
    'allowed_groups' => ['nucleo', 'ui'],
]);

Testing

All PHPUnit tests pass (10+ new). Coverage includes: multi-location groups, slug collisions, empty-location skip, single-location (pre 4.4 style), subdir mode, helper path/URI resolution, and per-field allowlist. PHPStan level 10 clean.

Picker UI behaviours (focus trap, Escape, arrow nav) are inherited from native <dialog>, manual
smoke-test recommended in review.

Preview

New ACF Field Option

Updated Picker UI

Filtered Groups

Missing State

[Copilot]

Pull request overview

This PR introduces icon set grouping (including multi-location and subdirectory-driven grouping) to the ACF SVG Icon Picker, rewrites the picker UI around native <dialog> for improved accessibility/keyboard navigation, and updates contributor tooling/CI to enforce formatting and stricter static analysis.

Changes:

• Add multi-location icon sources with group metadata + per-field allowed_groups filtering, and fix helper URL resolution for custom locations.
• Rewrite the picker UI to use native <dialog>, button-based icon tiles, and arrow-key grid navigation; ensure buttons use type="button" to avoid unintended form submits.
• Replace/upgrade dev tooling (Mago + Oxfmt + Oxlint), raise PHPStan level, and add a code-quality GitHub Actions workflow.

Reviewed changes

Copilot reviewed 16 out of 20 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
acf-svg-icon-picker.php	Adds shared location normalization + location-aware URI/path resolution helpers (including group_by_subdir).
class-acf-field-svg-icon-picker.php	Implements groups/multi-location collection and exposes $groups; adds per-field allowed_groups setting and localizes groups to JS.
resources/scripts/input.js	Replaces jQuery picker logic with vanilla JS and native <dialog>, adds arrow-key navigation and per-field group filtering.
resources/views/acf-field.php	Updates field markup for type="button", improves escaping, and passes allowed-groups allowlist via data-allowed-groups.
resources/styles/input.css	Updates styling for <dialog> UI, responsive grid tiles, group headings, and improved focus/RTL handling via CSS custom properties and logical props.
tests/bootstrap.php	Formatting adjustments to match new tooling/style.
tests/TestPlugin.php	Adds/updates tests for multi-location groups, collisions, empty dir skipping, subdir grouping, helper resolution, and per-field allowlist.
README.md	Documents multi-location groups, subdir grouping, per-field allowlist, and new dev workflows.
CHANGELOG.md	Adds Keep-a-Changelog formatted history and documents v4.4.0 changes.
composer.json	Adds PHP >=8.1 requirement and swaps formatting tooling to Mago; updates scripts accordingly.
composer.lock	Updates locked dependencies for new tooling / stricter CI.
phpstan.neon	Raises PHPStan level and updates excluded paths.
mago.toml	Configures Mago formatting (same-line braces) and sources/excludes.
package.json	Adds Oxfmt/Oxlint scripts and devDependencies for JS/CSS/JSON formatting & JS linting.
package-lock.json	Locks Oxfmt/Oxlint dependency tree.
.github/workflows/code-quality.yml	Adds CI workflow for PHPStan, Mago format check, Oxfmt format check, and Oxlint.
.oxfmtrc.json	Configures Oxfmt formatting and ignore patterns.
.gitignore	Adds node_modules and .DS_Store.
.phpcs.xml.dist	Removes legacy PHPCS configuration (tooling replaced).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 20 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 28 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 28 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 28 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Levdbas]

Hey @mike-sheppard , I will give this a spin later this week to see if everything is working as intended!

[Levdbas]

Hey @mike-sheppard , I will give this a spin later this week to see if everything is working as intended!

Sup @mike-sheppard!

My promised week became month. To make up for it, did a good testing and added a POT file and Dutch translations.

But amazing work. Love the new UI. Didn't test the new icon set feature yet though.

btw, I ran into an issue on what I assume was caused by Bedrock where the acf_field class was not available yet. So I moved the require inside the hook. That fixed the issue. See this commit

[mike-sheppard]

hey sorry for the delay @Levdbas, thanks for testing + tweaking. I'll take a look early next week + test again + merge it all hopefully 🤞

[Copilot]

Pull request overview

Copilot reviewed 24 out of 31 changed files in this pull request and generated 3 comments.