feat: New stats field class

docs: Fix inline docs

Author: bastianallgeier

src/Cms/Core.php

@@ -12,6 +12,7 @@
 use Kirby\Form\Field\BlocksField;
 use Kirby\Form\Field\EntriesField;
 use Kirby\Form\Field\LayoutField;
+use Kirby\Form\Field\StatsField;
 use Kirby\Panel\Ui\FilePreviews\AudioFilePreview;
 use Kirby\Panel\Ui\FilePreviews\ImageFilePreview;
 use Kirby\Panel\Ui\FilePreviews\PdfFilePreview;
@@ -270,6 +271,7 @@ public function fields(): array
 			'range'       => $this->root . '/fields/range.php',
 			'select'      => $this->root . '/fields/select.php',
 			'slug'        => $this->root . '/fields/slug.php',
+			'stats'       => StatsField::class,
 			'structure'   => $this->root . '/fields/structure.php',
 			'tags'        => $this->root . '/fields/tags.php',
 			'tel'         => $this->root . '/fields/tel.php',

src/Form/Field/StatsField.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Kirby\Form\Field;
+
+use Kirby\Form\FieldClass;
+use Kirby\Panel\Ui\Stats;
+
+/**
+ * Stats field
+ *
+ * @package   Kirby Field
+ * @author    Bastian Allgeier <[email protected]>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://getkirby.com/license
+ * @since     5.1.0
+ */
+class StatsField extends FieldClass
+{
+	/**
+	 * Array or query string for reports. Each report needs a `label` and `value` and can have additional `info`, `link`, `icon` and `theme` settings.
+	 */
+	protected array|string $reports;
+
+	/**
+	 * The size of the report cards. Available sizes: `tiny`, `small`, `medium`, `large`
+	 */
+	protected string $size;
+
+	/**
+	 * Cache for the Stats UI component
+	 */
+	protected Stats $stats;
+
+	public function __construct(array $params)
+	{
+		parent::__construct($params);
+
+		$this->reports = $params['reports'] ?? [];
+		$this->size    = $params['size']    ?? 'large';
+	}
+
+	public function hasValue(): bool
+	{
+		return false;
+	}
+
+	public function reports(): array
+	{
+		return $this->stats()->reports();
+	}
+
+	public function size(): string
+	{
+		return $this->stats()->size();
+	}
+
+	public function stats(): Stats
+	{
+		return $this->stats ??= Stats::from(
+			model: $this->model,
+			reports: $this->reports,
+			size: $this->size
+		);
+	}
+
+	public function props(): array
+	{
+		return [
+			...parent::props(),
+			...$this->stats()->props()
+		];
+	}
+}

tests/Form/Field/StatsFieldTest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Kirby\Form\Field;
+
+use Kirby\Panel\Ui\Stats;
+
+class StatsFieldTest extends TestCase
+{
+	public function testDefaultProps(): void
+	{
+		$field = $this->field('stats');
+
+		$this->assertSame('stats', $field->type());
+		$this->assertSame('stats', $field->name());
+		$this->assertSame('Stats', $field->label());
+		$this->assertSame([], $field->reports());
+		$this->assertSame('large', $field->size());
+		$this->assertFalse($field->hasValue());
+		$this->assertInstanceOf(Stats::class, $field->stats());
+
+		$props = $field->props();
+
+		$this->assertSame('Stats', $props['label']);
+		$this->assertSame('stats', $props['name']);
+		$this->assertSame('stats', $props['type']);
+		$this->assertSame([], $props['reports']);
+		$this->assertSame('large', $props['size']);
+	}
+}