init with kirby, vue and pagedjs interactive

public/kirby/src/Option/Option.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Kirby\Option;
+
+use Kirby\Cms\ModelWithContent;
+use Kirby\Toolkit\I18n;
+
+/**
+ * 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 string|array $text;
+
+	public function __construct(
+		public string|int|float|null $value,
+		public bool $disabled = false,
+		public string|null $icon = null,
+		public string|array|null $info = null,
+		string|array|null $text = null
+	) {
+		$this->text = $text ?? ['en' => $this->value];
+	}
+
+	public static function factory(string|int|float|array|null $props): static
+	{
+		if (is_array($props) === false) {
+			$props = ['value' => $props];
+		}
+
+		// Normalize info to be an array
+		if (isset($props['info']) === true) {
+			$props['info'] = match (true) {
+				is_array($props['info']) => $props['info'],
+				$props['info'] === null,
+				$props['info'] === false => null,
+				default                  => ['en' => $props['info']]
+			};
+		}
+
+		// Normalize text to be an array
+		if (isset($props['text']) === true) {
+			$props['text'] = match (true) {
+				is_array($props['text']) => $props['text'],
+				$props['text'] === null,
+				$props['text'] === false => null,
+				default                  => ['en' => $props['text']]
+			};
+		}
+
+		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
+	{
+		$info = I18n::translate($this->info, $this->info);
+		$text = I18n::translate($this->text, $this->text);
+
+		return [
+			'disabled' => $this->disabled,
+			'icon'     => $this->icon,
+			'info'     => $info ? $model->toSafeString($info) : $info,
+			'text'     => $text ? $model->toSafeString($text) : $text,
+			'value'    => $this->value
+		];
+	}
+}

public/kirby/src/Option/Options.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace Kirby\Option;
+
+use Kirby\Cms\Collection;
+use Kirby\Cms\ModelWithContent;
+use Kirby\Toolkit\A;
+
+/**
+ * Collection of possible options 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
+ *
+ * @extends \Kirby\Cms\Collection<\Kirby\Option\Option>
+ */
+class Options extends Collection
+{
+	public function __construct(array $objects = [])
+	{
+		foreach ($objects as $object) {
+			$this->__set($object->value, $object);
+		}
+	}
+
+	/**
+	 * The Kirby Collection class only shows the key to
+	 * avoid huge trees when dumping, but for the options
+	 * collections this is really not useful
+	 *
+	 * @codeCoverageIgnore
+	 */
+	public function __debugInfo(): array
+	{
+		return A::map($this->data, fn ($item) => (array)$item);
+	}
+
+	public static function factory(array $items = []): static
+	{
+		$collection = new static();
+
+		foreach ($items as $key => $option) {
+			// convert an associative value => text array into props;
+			// 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
+	{
+		$options = [];
+
+		foreach ($this->data as $key => $option) {
+			$options[$key] = $option->render($model);
+		}
+
+		return array_values($options);
+	}
+}

public/kirby/src/Option/OptionsApi.php

@@ -0,0 +1,157 @@
+<?php
+
+namespace Kirby\Option;
+
+use Kirby\Cms\ModelWithContent;
+use Kirby\Cms\Nest;
+use Kirby\Content\Field;
+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 string|null $icon = null,
+		public string|null $info = 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,
+			icon : $props['icon'] ?? null,
+			info : $props['info'] ?? 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
+	 *
+	 * @param bool $safeMode Whether to escape special HTML characters in
+	 *                       the option text for safe output in the Panel;
+	 *                       only set to `false` if the text is later escaped!
+	 */
+	public function resolve(ModelWithContent $model, bool $safeMode = true): 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 convert from JSON to array
+		$data = $this->load($model);
+
+		// @codeCoverageIgnoreStart
+		if ($data === null) {
+			throw new NotFoundException(
+				message: 'Options could not be loaded from API: ' . $model->toSafeString($this->url)
+			);
+		}
+		// @codeCoverageIgnoreEnd
+
+		// turn data into Nest so that it can be queried
+		// or field methods applied to the data
+		$data = Nest::create($data);
+
+		// optionally query a substructure inside the data array
+		$data    = Query::factory($this->query)->resolve($data);
+		$options = [];
+
+		// create options by resolving text and value query strings
+		// for each item from the data
+		foreach ($data as $key => $item) {
+			// convert simple `key: value` API data
+			if (is_string($item) === true) {
+				$item = new Field(null, $key, $item);
+			}
+
+			$safeMethod = $safeMode === true ? 'toSafeString' : 'toString';
+
+			$options[] = [
+				// value is always a raw string
+				'value' => $model->toString($this->value, ['item' => $item]),
+				// text is only a raw string when using {< >}
+				// or when the safe mode is explicitly disabled (select field)
+				'text'  => $model->$safeMethod($this->text, ['item' => $item]),
+				// additional data
+				'icon'  => $this->icon !== null ? $model->toString($this->icon, ['item' => $item]) : null,
+				'info'  => $this->info !== null ? $model->$safeMethod($this->info, ['item' => $item]) : null
+			];
+		}
+
+		// create Options object and render this subsequently
+		return $this->options = Options::factory($options);
+	}
+}

public/kirby/src/Option/OptionsProvider.php

@@ -0,0 +1,38 @@
+<?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);
+	}
+
+	/**
+	 * Dynamically determines the actual options and resolves
+	 * them to the correct text-value entries
+	 *
+	 * @param bool $safeMode Whether to escape special HTML characters in
+	 *                       the option text for safe output in the Panel;
+	 *                       only set to `false` if the text is later escaped!
+	 */
+	abstract public function resolve(ModelWithContent $model, bool $safeMode = true): Options;
+}

public/kirby/src/Option/OptionsQuery.php

@@ -0,0 +1,196 @@
+<?php
+
+namespace Kirby\Option;
+
+use Kirby\Cms\Block;
+use Kirby\Cms\File;
+use Kirby\Cms\ModelWithContent;
+use Kirby\Cms\Page;
+use Kirby\Cms\StructureObject;
+use Kirby\Cms\User;
+use Kirby\Content\Field;
+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,
+		public string|null $icon = null,
+		public string|null $info = 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,
+			icon : $props['icon'] ?? null,
+			info : $props['info'] ?? 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
+	 *
+	 * @param bool $safeMode Whether to escape special HTML characters in
+	 *                       the option text for safe output in the Panel;
+	 *                       only set to `false` if the text is later escaped!
+	 */
+	public function resolve(ModelWithContent $model, bool $safeMode = true): 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) {
+			$type = is_object($result) === true ? $result::class : gettype($result);
+
+			throw new InvalidArgumentException(
+				message: 'Invalid query result data: ' . $type
+			);
+		}
+
+		// create options array
+		$options = $result->toArray(function ($item) use ($model, $safeMode) {
+			// 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 using {< >}
+			// or when the safe mode is explicitly disabled (select field)
+			$safeMethod = $safeMode === true ? 'toSafeString' : 'toString';
+			$text = $model->$safeMethod($this->text ?? $text, $data);
+
+			// additional data
+			$icon = $this->icon !== null ? $model->toString($this->icon, $data) : null;
+			$info = $this->info !== null ? $model->$safeMethod($this->info, $data) : null;
+
+			return compact('text', 'value', 'icon', 'info');
+		});
+
+		return $this->options = Options::factory($options);
+	}
+}