Merge branch 'feature/presets'

Author: arraypress

README.md

@@ -25,6 +25,7 @@ wherever the screen happens to be.
 * Group fields into tabs or collapsible sections
 * Sit two short fields on one line with `'width' => 'half'`
 * Take an amount with its currency symbol inside the control
+* Fill a select from a named preset — roles, timezones, countries — with one string
 * Fold a repeater's rows away, each titled by one of its own fields
 * Reorder a repeater by dragging its handle, or from the keyboard
 * Refuse a value that fails a rule — required, email, url, your own callable — and say why
@@ -107,7 +108,7 @@ Date, time and colour
 : `date` `time` `datetime` `color` `gradient` `date_range` `time_range`
 
 Choice
-: `select` `enhanced_select` `select_multiple` `checkbox` `toggle` `radio` `checkbox_group` `button_group` `card_choice`
+: `select` `enhanced_select` `select_multiple` `checkbox` `toggle` `radio` `checkbox_group` `button_group` `card_choice` `country` `currency`
 
 Relational — one search endpoint behind all of them
 : `post` `page` `user` `taxonomy` `ajax` `tags`
@@ -124,6 +125,38 @@ Layout and display
 Purpose-built
 : `license` `email_editor` `action_button`
 
+## Options from a preset
+
+The lists every settings screen ends up needing — the site's roles, its
+timezones, its page templates — are presets, and a select asks for one by
+name rather than building it again:
+
+```php
+use ArrayPress\FieldKit\FieldSet;
+use ArrayPress\FieldKit\Context\OptionContext;
+
+$set = new FieldSet(
+	[
+		'notify_role' => [ 'type' => 'select', 'label' => __( 'Notify', 'my-plugin' ), 'options' => 'roles' ],
+		'timezone'    => [ 'type' => 'select', 'label' => __( 'Timezone', 'my-plugin' ), 'options' => 'timezones' ],
+		'country'     => [ 'type' => 'country', 'label' => __( 'Country', 'my-plugin' ), 'continents' => true ],
+		'currency'    => [ 'type' => 'currency', 'label' => __( 'Currency', 'my-plugin' ) ],
+	],
+	new OptionContext( 'my_plugin' ),
+	'my_plugin'
+);
+```
+
+The built-ins are `roles`, `post_types`, `taxonomies`, `pages`, `timezones`,
+`image_sizes`, `page_templates`, `cron_schedules`, `countries` and
+`currencies`. The last two draw on `arraypress/wp-countries` and
+`arraypress/wp-money`; the `country` and `currency` types use them by default.
+
+A preset is resolved when the field renders, not when it is declared, and its
+options pass through the `field_kit_preset_options` filter. Register your own
+with `Presets::register( 'products', fn() => $options )` and any field can say
+`'options' => 'products'`.
+
 ## Requirements
 
 * PHP 8.3 or later

composer.json

@@ -11,14 +11,18 @@
     }
   ],
   "require": {
-    "php": ">=8.3"
+    "php": ">=8.3",
+    "arraypress/wp-countries": "^1.0"
   },
   "require-dev": {
     "phpcompatibility/phpcompatibility-wp": "^2.1",
     "phpunit/phpunit": "^12.0",
     "squizlabs/php_codesniffer": "^3.13.5",
     "wp-coding-standards/wpcs": "^3.4"
   },
+  "suggest": {
+    "arraypress/wp-money": "Supplies the currencies preset and the options of the currency field type."
+  },
   "autoload": {
     "psr-4": {
       "ArrayPress\\FieldKit\\": "src/"
@@ -29,7 +33,8 @@
       "ArrayPress\\FieldKit\\Tests\\": "tests/"
     },
     "exclude-from-classmap": [
-      "/tests/bootstrap.php"
+      "/tests/bootstrap.php",
+      "/tests/stubs/"
     ]
   },
   "scripts": {

src/Field.php

@@ -13,6 +13,7 @@
 namespace ArrayPress\FieldKit;
 
 use ArrayPress\FieldKit\Contracts\FieldType;
+use ArrayPress\FieldKit\Support\Presets;
 
 /**
  * A single field, normalized once and then read-only.
@@ -429,13 +430,24 @@ public function placeholder(): string {
 	 * Choice options as value => label.
 	 *
 	 * Accepts a callable so options can be resolved at render time rather
-	 * than at registration, which is what dynamic sources need.
+	 * than at registration, which is what dynamic sources need. Accepts a
+	 * name, too -- `'options' => 'roles'` -- which is a preset, built in or
+	 * registered by the consumer, and resolved the same way.
+	 *
+	 * The name is checked before the callable, because a string is a
+	 * callable too whenever a function of that name exists: a preset called
+	 * `pages` must not turn into a call to some plugin's `pages()`. A
+	 * function name that is not a preset still works as it always did.
 	 *
 	 * @return array<string, string>
 	 */
 	public function options(): array {
 		$options = $this->get( 'options', [] );
 
+		if ( is_string( $options ) && '' !== $options && ( Presets::has( $options ) || ! is_callable( $options ) ) ) {
+			return Presets::options( $options, $this );
+		}
+
 		if ( is_callable( $options ) ) {
 			$options = $options( $this );
 		}

src/Registry.php

@@ -62,6 +62,8 @@ final class Registry {
 		'radio'           => Types\RadioType::class,
 		'checkbox_group'  => Types\CheckboxGroupType::class,
 		'button_group'    => Types\ButtonGroupType::class,
+		'country'         => Types\CountryType::class,
+		'currency'        => Types\CurrencyType::class,
 
 		// Media.
 		'image'           => Types\ImageType::class,