Update Composer packages

kirby/src/Option/Option.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace Kirby\Option;
+
+use Kirby\Blueprint\Factory;
+use Kirby\Blueprint\NodeIcon;
+use Kirby\Blueprint\NodeText;
+use Kirby\Cms\ModelWithContent;
+
+/**
+ * Option for select fields, radio fields, etc
+ *
+ * @package   Kirby Option
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class Option
+{
+	public function __construct(
+		public float|int|string|null $value,
+		public bool $disabled = false,
+		public NodeIcon|null $icon = null,
+		public NodeText|null $info = null,
+		public NodeText|null $text = null
+	) {
+		$this->text ??= new NodeText(['en' => $this->value]);
+	}
+
+	public static function factory(float|int|string|null|array $props): static
+	{
+		if (is_array($props) === false) {
+			$props = ['value' => $props];
+		}
+
+		$props = Factory::apply($props, [
+			'icon' => NodeIcon::class,
+			'info' => NodeText::class,
+			'text' => NodeText::class
+		]);
+
+		return new static(...$props);
+	}
+
+	public function id(): string|int|float
+	{
+		return $this->value ?? '';
+	}
+
+	/**
+	 * Renders all data for the option
+	 */
+	public function render(ModelWithContent $model): array
+	{
+		return [
+			'disabled' => $this->disabled,
+			'icon'     => $this->icon?->render($model),
+			'info'     => $this->info?->render($model),
+			'text'     => $this->text?->render($model),
+			'value'    => $this->value
+		];
+	}
+}

kirby/src/Option/Options.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Kirby\Option;
+
+use Kirby\Blueprint\Collection;
+use Kirby\Cms\ModelWithContent;
+
+/**
+ * Options
+ *
+ * @package   Kirby Option
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class Options extends Collection
+{
+	public const TYPE = Option::class;
+
+	public function __construct(array $objects = [])
+	{
+		foreach ($objects as $object) {
+			$this->__set($object->value, $object);
+		}
+	}
+
+	public static function factory(array $items = []): static
+	{
+		$collection = new static();
+
+		foreach ($items as $key => $option) {
+			// skip if option is already an array of option props
+			if (
+				is_array($option) === false ||
+				array_key_exists('value', $option) === false
+			) {
+				$option = match (true) {
+					is_string($key) => ['value' => $key, 'text' => $option],
+					default         => ['value' => $option]
+				};
+			}
+
+			$option = Option::factory($option);
+			$collection->__set($option->id(), $option);
+		}
+
+		return $collection;
+	}
+
+	public function render(ModelWithContent $model): array
+	{
+		return array_values(parent::render($model));
+	}
+}

kirby/src/Option/OptionsApi.php

@@ -0,0 +1,127 @@
+<?php
+
+namespace Kirby\Option;
+
+use Kirby\Cms\ModelWithContent;
+use Kirby\Cms\Nest;
+use Kirby\Data\Json;
+use Kirby\Exception\NotFoundException;
+use Kirby\Http\Remote;
+use Kirby\Http\Url;
+use Kirby\Query\Query;
+
+/**
+ * Options fetched from any REST API
+ * or local file with valid JSON data.
+ *
+ * @package   Kirby Option
+ * @author    Bastian Allgeier <bastian@getkirby.com>,
+ * 			  Nico Hoffmann <nico@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class OptionsApi extends OptionsProvider
+{
+	public function __construct(
+		public string $url,
+		public string|null $query = null,
+		public string|null $text = null,
+		public string|null $value = null
+	) {
+	}
+
+	public function defaults(): static
+	{
+		$this->text  ??= '{{ item.value }}';
+		$this->value ??= '{{ item.key }}';
+		return $this;
+	}
+
+	public static function factory(string|array $props): static
+	{
+		if (is_string($props) === true) {
+			return new static(url: $props);
+		}
+
+		return new static(
+			url: $props['url'],
+			query: $props['query'] ?? $props['fetch'] ?? null,
+			text: $props['text'] ?? null,
+			value: $props['value'] ?? null
+		);
+	}
+
+	/**
+	 * Loads the API content from a remote URL
+	 * or local file (or from cache)
+	 */
+	public function load(ModelWithContent $model): array|null
+	{
+		// resolve query templates in $this->url string
+		$url = $model->toSafeString($this->url);
+
+		// URL, request via cURL
+		if (Url::isAbsolute($url) === true) {
+			return Remote::get($url)->json();
+		}
+
+		// local file
+		return Json::read($url);
+	}
+
+	public static function polyfill(array|string $props = []): array
+	{
+		if (is_string($props) === true) {
+			return ['url' => $props];
+		}
+
+		if ($query = $props['fetch'] ?? null) {
+			$props['query'] ??= $query;
+			unset($props['fetch']);
+		}
+
+		return $props;
+	}
+
+	/**
+	 * Creates the actual options by loading
+	 * data from the API and resolving it to
+	 * the correct text-value entries
+	 */
+	public function resolve(ModelWithContent $model): Options
+	{
+		// use cached options if present
+		// @codeCoverageIgnoreStart
+		if ($this->options !== null) {
+			return $this->options;
+		}
+		// @codeCoverageIgnoreEnd
+
+		// apply property defaults
+		$this->defaults();
+
+		// load data from URL and narrow down to queried part
+		$data = $this->load($model);
+
+		if ($data === null) {
+			throw new NotFoundException('Options could not be loaded from API: ' . $model->toSafeString($this->url));
+		}
+
+		// turn data into Nest so that it can be queried
+		$data = Nest::create($data);
+		$data = Query::factory($this->query)->resolve($data);
+
+		// create options by resolving text and value query strings
+		// for each item from the data
+		$options = $data->toArray(fn ($item) => [
+			// value is always a raw string
+			'value' => $model->toString($this->value, ['item' => $item]),
+			// text is only a raw string when using {< >}
+			'text' => $model->toSafeString($this->text, ['item' => $item]),
+		]);
+
+		// create Options object and render this subsequently
+		return $this->options = Options::factory($options);
+	}
+}

kirby/src/Option/OptionsProvider.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Kirby\Option;
+
+use Kirby\Cms\ModelWithContent;
+
+/**
+ * Abstract class as base for dynamic options
+ * providers like OptionsApi and OptionsQuery
+ *
+ * @package   Kirby Option
+ * @author    Nico Hoffmann <nico@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+abstract class OptionsProvider
+{
+	public Options|null $options = null;
+
+	/**
+	 * Returns options as array
+	 */
+	public function render(ModelWithContent $model)
+	{
+		return $this->resolve($model)->render($model);
+	}
+
+	abstract public function resolve(ModelWithContent $model): Options;
+}

kirby/src/Option/OptionsQuery.php

@@ -0,0 +1,179 @@
+<?php
+
+namespace Kirby\Option;
+
+use Kirby\Cms\Block;
+use Kirby\Cms\Field;
+use Kirby\Cms\File;
+use Kirby\Cms\ModelWithContent;
+use Kirby\Cms\Page;
+use Kirby\Cms\StructureObject;
+use Kirby\Cms\User;
+use Kirby\Exception\InvalidArgumentException;
+use Kirby\Toolkit\Collection;
+use Kirby\Toolkit\Obj;
+
+/**
+ * Options derrived from running a query against
+ * pages, files, users or structures to create
+ * options out of them.
+ *
+ * @package   Kirby Option
+ * @author    Bastian Allgeier <bastian@getkirby.com>,
+ * 			  Nico Hoffmann <nico@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class OptionsQuery extends OptionsProvider
+{
+	public function __construct(
+		public string $query,
+		public string|null $text = null,
+		public string|null $value = null
+	) {
+	}
+
+	protected function collection(array $array): Collection
+	{
+		foreach ($array as $key => $value) {
+			if (is_scalar($value) === true) {
+				$array[$key] = new Obj([
+					'key'   => new Field(null, 'key', $key),
+					'value' => new Field(null, 'value', $value),
+				]);
+			}
+		}
+
+		return new Collection($array);
+	}
+
+	public static function factory(string|array $props): static
+	{
+		if (is_string($props) === true) {
+			return new static(query: $props);
+		}
+
+		return new static(
+			query: $props['query'] ?? $props['fetch'],
+			text: $props['text'] ?? null,
+			value: $props['value'] ?? null
+		);
+	}
+
+	/**
+	 * Returns defaults for the following based on item type:
+	 * [query entry alias, default text query, default value query]
+	 */
+	protected function itemToDefaults(array|object $item): array
+	{
+		return match (true) {
+			is_array($item),
+			$item instanceof Obj => [
+				'arrayItem',
+				'{{ item.value }}',
+				'{{ item.value }}'
+			],
+
+			$item instanceof StructureObject => [
+				'structureItem',
+				'{{ item.title }}',
+				'{{ item.id }}'
+			],
+
+			$item instanceof Block => [
+				'block',
+				'{{ block.type }}: {{ block.id }}',
+				'{{ block.id }}'
+			],
+
+			$item instanceof Page => [
+				'page',
+				'{{ page.title }}',
+				'{{ page.id }}'
+			],
+
+			$item instanceof File => [
+				'file',
+				'{{ file.filename }}',
+				'{{ file.id }}'
+			],
+
+			$item instanceof User => [
+				'user',
+				'{{ user.username }}',
+				'{{ user.email }}'
+			],
+
+			default => [
+				'item',
+				'{{ item.value }}',
+				'{{ item.value }}'
+			]
+		};
+	}
+
+	public static function polyfill(array|string $props = []): array
+	{
+		if (is_string($props) === true) {
+			return ['query' => $props];
+		}
+
+		if ($query = $props['fetch'] ?? null) {
+			$props['query'] ??= $query;
+			unset($props['fetch']);
+		}
+
+		return $props;
+	}
+
+	/**
+	 * Creates the actual options by running
+	 * the query on the model and resolving it to
+	 * the correct text-value entries
+	 */
+	public function resolve(ModelWithContent $model): Options
+	{
+		// use cached options if present
+		// @codeCoverageIgnoreStart
+		if ($this->options !== null) {
+			return $this->options;
+		}
+		// @codeCoverageIgnoreEnd
+
+		// run query
+		$result = $model->query($this->query);
+
+		// the query already returned an options collection
+		if ($result instanceof Options) {
+			return $result;
+		}
+
+		// convert result to a collection
+		if (is_array($result) === true) {
+			$result = $this->collection($result);
+		}
+
+		if ($result instanceof Collection === false) {
+			throw new InvalidArgumentException('Invalid query result data: ' . get_class($result));
+		}
+
+		// create options array
+		$options = $result->toArray(function ($item) use ($model) {
+			// get defaults based on item type
+			[$alias, $text, $value] = $this->itemToDefaults($item);
+			$data = ['item' => $item, $alias => $item];
+
+			// value is always a raw string
+			$value = $model->toString($this->value ?? $value, $data);
+
+			// text is only a raw string when HTML prop
+			// is explicitly set to true
+			$text = $model->toSafeString($this->text ?? $text, $data);
+
+			return compact('text', 'value');
+		});
+
+		return $this->options = Options::factory($options);
+	}
+}