Merge pull request #12 from BeAPI/release/1.1.0

Release 1.1.0

Author: firestar300

.distignore

@@ -21,5 +21,7 @@ phpcs.xml.dist
 phpunit.xml.dist
 psalm.xml.dist
 README.md
+CHANGELOG.md
+CONTRIBUTING.md
 webpack.config.js
 yarn.lock

.gitattributes

@@ -9,3 +9,4 @@
 /phpcs.xml.dist export-ignore
 /psalm.xml export-ignore
 /README.md export-ignore
+/CONTRIBUTING.md export-ignore

.gitignore

@@ -1,3 +1,3 @@
 /vendor/
 /node_modules/
-/assets/build/
+/build/

.plugin-data

@@ -1,4 +1,4 @@
 {
-	"version": "1.0.6",
+	"version": "1.1.0",
 	"slug": "beapi-acf-palette"
 }

.wp-env.json

@@ -0,0 +1,5 @@
+{
+	"plugins": [
+		"."
+	]
+}

CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+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]
+
+Nothing yet.
+
+## [1.1.0] - 2026-01-12
+
+### Added
+
+- New "Color Source" field setting to choose between three sources in theme.json:
+  - `settings.color.palette` (default): Standard WordPress color palette
+  - `custom.color`: Custom color definitions with slug as key and hex value (must be at root level)
+  - `both`: Combines both settings and custom colors (custom takes priority on conflicts)
+- Automatic name generation from slugs for custom colors
+  - Example: `environnement-400` → "Environnement 400"
+  - Example: `services-publics-900` → "Services Publics 900"
+- Dynamic reloading of Include/Exclude color options via AJAX when source changes
+- AJAX endpoint `acf_palette_get_colors` for fetching colors based on selected source
+
+### Changed
+
+- Simplified Return Format options: removed "Label" option
+  - **Slug**: Returns only the color slug (e.g., `"primary-orange"`)
+  - **Hex Color**: Returns only the hex value (e.g., `"#FF6745"`)
+  - **Both (Array)**: Returns array with `name`, `slug`, and `color`
+- Updated Array format structure for consistency:
+  - Before: `['value' => '...', 'label' => '...', 'color' => '...']`
+  - After: `['name' => '...', 'slug' => '...', 'color' => '...']`
+- Split color retrieval logic into separate methods (`get_settings_colors()`, `get_custom_colors()`, `get_both_colors()`)
+- Changed color source field layout from horizontal to vertical for better readability
+- Updated `get_theme_colors()` method to accept a `$source` parameter
+- All field methods now support the `color_source` parameter
+
+### Fixed
+
+- Fixed AJAX handler to use proper capability checks and custom nonce validation
+- Fixed custom colors retrieval to correctly read from root-level `custom.color` in theme.json
+- Improved security with `acf_palette_nonce` instead of generic `acf_nonce`
+
+### Technical
+
+- Added `get_settings_colors()` private method for `settings.color.palette`
+- Added `get_custom_colors()` private method for `custom.color`
+- Added `get_both_colors()` private method for combining both sources
+- Added `format_slug_to_name()` helper method for slug-to-name conversion
+- Added `ajax_get_colors()` method to handle AJAX requests
+- Added JavaScript AJAX handler in `editor.js` to reload color options dynamically
+- Added `updateSelectOptions()` JavaScript function to refresh Select2 dropdowns
+- Added `wp_localize_script()` for passing AJAX URL and nonce to JavaScript
+- Removed debug logs (`console.log` and `error_log`) from production code
+
+## [1.0.6] - 2025-11-28
+
+### Fixed
+
+- Updated export-ignore list in `.gitattributes` for cleaner releases
+
+## [1.0.5] - 2025-11-28
+
+### Changed
+
+- Updated PHP version requirement to 8.3
+
+### Fixed
+
+- Fixed potential undefined array key warnings
+
+## [1.0.4] - 2025-11-27
+
+### Changed
+
+- Updated plugin metadata and autoloader configuration
+
+## [1.0.3] - 2025-11-27
+
+### Added
+
+- Added autoload configuration
+
+## [1.0.2] - 2025-11-27
+
+### Fixed
+
+- Updated package metadata in `composer.json`
+
+## [1.0.1] - 2025-11-27
+
+### Added
+
+- Automated release workflow setup
+- Added `composer.lock` file
+
+### Changed
+
+- Removed Node.js build step from workflow
+- Removed obsolete workflow configurations
+- Set first radio option as selected by default
+
+## [1.0.0] - 2025-08-08
+
+### Added
+
+- Initial release of ACF Color Palette plugin
+- Custom ACF field type "Theme Color" for selecting colors from theme.json
+- Support for `settings.color.palette` colors from theme.json
+- Color preview with color circle and hex code
+- Select2 integration for searchable dropdown
+- Field settings:
+  - Allow Null: Option to allow no color selection
+  - Default Value: Set a default color
+  - Color Filter Method: Choose between "Exclude" or "Include" colors
+  - Exclude Colors: Exclude specific colors from selection
+  - Include Colors: Only include specific colors
+  - Return Format: Value (Slug), Hex Color, Label, or Array
+- Return format options:
+  - Value: Returns color slug
+  - Hex: Returns hex color code
+  - Label: Returns color name
+  - Array: Returns complete color data
+- Support for multiple theme.json file locations
+- Color filtering based on inclusion/exclusion rules
+- Automatic color selection (first color or "No color" if null allowed)

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Local Dev
+
+## Installation
+
+```shell
+# Composer installation
+composer install -o
+./vendor/bin/psalm-plugin enable humanmade/psalm-plugin-wordpress
+
+# Add playwright locally
+npx playwright install --with-deps
+
+# Install dependencies
+npm install
+
+# Env start, this will launch the environment with the PHP version specified into `.wp-env.json` and latest version of WordPress.
+npm run env:start
+
+# Install and activate ACF pro, for example :
+npm run wp-cli -- wp plugin install --activate https://composer.beapi.fr/dist/wpengine/advanced-custom-fields-pro/wpengine-advanced-custom-fields-pro-6.2.7.zip
+```
+
+## Créer une nouvelle fonctionnalité ou un correctif
+
+À partir de la branche `develop` à jour, créez votre branche `feature/<topic>` si c'est une nouvelle fonctionnalité ou `fix/<topic>` si c'est un correctif.
+
+## Merger votre fonctionnalité ou correctif
+
+Créez une Pull Request de votre branche vers `main`.
+
+## Créer une nouvelle branche de release
+
+Une fois votre branche mergée sur `main`, créez une nouvelle branche `release/X.X.X` (X.X.X correspondant à la nouvelle version de votre release).
+
+Modifiez les fichiers `.plugin-data` et `beapi-acf-palette.php` pour mettre à jour la version.
+
+```plain
+{
+ "version": "1.0.6",
+ "slug": "beapi-acf-palette"
+}
+```
+
+```php
+/*
+Version: 1.0.6
+*/
+
+define( 'BEAPI_ACF_PALETTE_VERSION', '1.0.6' );
+```
+
+Committez et poussez votre branche.
+
+## Déployer une nouvelle release
+
+Créez une Pull Request de votre branche `release/X.X.X` vers `main` et une autre Pull Request vers `develop`.
+
+Une fois validée et mergée, un nouveau tag sera créé. Il faudra ensuite lancer la commande Satis pour mettre à jour <https://composer.beapi.fr/>.

README.md

@@ -15,43 +15,45 @@ Un nouveau type de champ ACF qui récupère automatiquement les couleurs défini
    - Le champ affichera automatiquement toutes les couleurs définies dans `wp-content/themes/[theme]/theme.json`
 
 2. **Options du champ**
+   - **Color Source** : Choisir la source des couleurs
+     - `Settings Palette` : Uniquement `settings.color.palette`
+     - `Custom Colors` : Uniquement `custom.color`
+     - `Both` : Combine les deux sources (settings + custom)
    - **Allow Null** : Permet de ne pas sélectionner de couleur
    - **Default Value** : Valeur par défaut
    - **Color Filter Method** : Choisir entre exclure ou inclure des couleurs
    - **Exclude Colors** : Permet d'exclure certaines couleurs de la sélection
    - **Include Colors** : Permet de n'inclure que certaines couleurs spécifiques
-   - **Return Format** : Format de retour (Value, Label, ou Array)
+   - **Return Format** : Format de retour (Slug, Hex Color, ou Both)
 
 3. **Formats de retour**
-   - **Value (Slug)** : Retourne le slug de la couleur (ex: `primary-orange`)
+   - **Slug** : Retourne le slug de la couleur (ex: `primary-orange`)
    - **Hex Color** : Retourne la valeur hexadécimale (ex: `#FF6745`)
-   - **Label** : Retourne le nom de la couleur (ex: `Primaire orange`)
-   - **Array** : Retourne un tableau avec `value`, `label` et `color`
+   - **Both (Array)** : Retourne un tableau avec `name`, `slug` et `color`
 
 #### Exemple d'utilisation en PHP
 
 ```php
-// Récupérer le slug (si configuré en "Value (Slug)")
+// Récupérer le slug (si configuré en "Slug")
 $color_slug = get_field('my_color_field');
+// 'primary-orange'
 
 // Récupérer la valeur hexadécimale (si configuré en "Hex Color")
 $color_hex = get_field('my_color_field');
+// '#FF6745'
 echo "background-color: {$color_hex};";
 
-// Récupérer le nom (si configuré en "Label")
-$color_name = get_field('my_color_field');
-
-// Récupérer toutes les informations (si configuré en "Array")
+// Récupérer toutes les informations (si configuré en "Both (Array)")
 $color_data = get_field('my_color_field');
 // $color_data = [
-//     'value' => 'primary-orange',
-//     'label' => 'Primaire orange',
+//     'name'  => 'Primaire orange',
+//     'slug'  => 'primary-orange',
 //     'color' => '#FF6745'
 // ];
 
-// Utilisation directe en CSS avec le format Array
-$color_hex = $color_data['color'];
-echo "background-color: {$color_hex};";
+// Utilisation avec le format Array
+echo "background-color: {$color_data['color']};";
+echo "Title: {$color_data['name']}";
 ```
 
 #### Méthodes de filtrage des couleurs
@@ -63,9 +65,11 @@ Le champ offre deux méthodes pour filtrer les couleurs disponibles :
 
 Ces options sont mutuellement exclusives et s'affichent conditionnellement selon la méthode choisie.
 
-#### Structure attendue du theme.json
+#### Sources de couleurs disponibles
+
+Le plugin peut récupérer les couleurs depuis trois sources différentes dans le `theme.json` :
 
-Le plugin s'attend à trouver les couleurs dans :
+##### 1. Settings Palette (par défaut)
 
 ```json
 {
@@ -83,6 +87,64 @@ Le plugin s'attend à trouver les couleurs dans :
 }
 ```
 
+##### 2. Custom Colors
+
+```json
+{
+  "$schema": "https://schemas.wp.org/trunk/theme.json",
+  "version": 3,
+  "custom": {
+    "color": {
+      "environnement-400": "#c9dcba",
+      "environnement-900": "#395f0f",
+      "entreprises-400": "#c1bcff",
+      "entreprises-900": "#001cb7"
+    }
+  },
+  "settings": {
+    // ... autres paramètres
+  }
+}
+```
+
+Les couleurs custom utilisent une structure simplifiée où le slug est la clé et la couleur hex est la valeur. Le nom lisible est généré automatiquement à partir du slug :
+
+- `environnement-400` → "Environnement 400"
+- `services-publics-900` → "Services Publics 900"
+
+##### 3. Both (Settings + Custom)
+
+Combine les couleurs des deux sources. Si un slug existe dans les deux sources, la version de `custom.color` sera prioritaire.
+
+```json
+{
+  "settings": {
+    "color": {
+      "palette": [
+        {
+          "name": "Primaire",
+          "slug": "primary",
+          "color": "#FF6745"
+        }
+      ]
+    }
+  },
+  "custom": {
+    "color": {
+      "environnement-400": "#c9dcba",
+      "entreprises-400": "#c1bcff"
+    }
+  }
+}
+```
+
+**Résultat avec "Both" :** Les 3 couleurs seront disponibles (`primary`, `environnement-400`, `entreprises-400`)
+
+**Note :** Pour les couleurs custom, le nom est automatiquement généré à partir du slug. Par exemple :
+
+- `environnement-400` devient "Environnement 400"
+- `services-publics-900` devient "Services Publics 900"
+
 ## Installation
 
 1. Copier le plugin dans `wp-content/plugins/beapi-acf-palette/`