feat: New Tab and Tabs classes for blueprints

Author: bastianallgeier

config/api/models/FileBlueprint.php

@@ -9,7 +9,7 @@
 	'fields' => [
 		'name'    => fn (FileBlueprint $blueprint) => $blueprint->name(),
 		'options' => fn (FileBlueprint $blueprint) => $blueprint->options(),
-		'tabs'    => fn (FileBlueprint $blueprint) => $blueprint->tabs(),
+		'tabs'    => fn (FileBlueprint $blueprint) => array_values($blueprint->tabs()->toArray()),
 		'title'   => fn (FileBlueprint $blueprint) => $blueprint->title(),
 	],
 	'type'  => FileBlueprint::class,

config/api/models/PageBlueprint.php

@@ -12,7 +12,7 @@
 		'options' => fn (PageBlueprint $blueprint) => $blueprint->options(),
 		'preview' => fn (PageBlueprint $blueprint) => $blueprint->preview(),
 		'status'  => fn (PageBlueprint $blueprint) => $blueprint->status(),
-		'tabs'    => fn (PageBlueprint $blueprint) => $blueprint->tabs(),
+		'tabs'    => fn (PageBlueprint $blueprint) => array_values($blueprint->tabs()->toArray()),
 		'title'   => fn (PageBlueprint $blueprint) => $blueprint->title(),
 	],
 	'type'  => PageBlueprint::class,

config/api/models/SiteBlueprint.php

@@ -9,7 +9,7 @@
 	'fields' => [
 		'name'    => fn (SiteBlueprint $blueprint) => $blueprint->name(),
 		'options' => fn (SiteBlueprint $blueprint) => $blueprint->options(),
-		'tabs'    => fn (SiteBlueprint $blueprint) => $blueprint->tabs(),
+		'tabs'    => fn (SiteBlueprint $blueprint) => array_values($blueprint->tabs()->toArray()),
 		'title'   => fn (SiteBlueprint $blueprint) => $blueprint->title(),
 	],
 	'type'  => SiteBlueprint::class,

config/api/models/UserBlueprint.php

@@ -9,7 +9,7 @@
 	'fields' => [
 		'name'    => fn (UserBlueprint $blueprint) => $blueprint->name(),
 		'options' => fn (UserBlueprint $blueprint) => $blueprint->options(),
-		'tabs'    => fn (UserBlueprint $blueprint) => $blueprint->tabs(),
+		'tabs'    => fn (UserBlueprint $blueprint) => array_values($blueprint->tabs()->toArray()),
 		'title'   => fn (UserBlueprint $blueprint) => $blueprint->title(),
 	],
 	'type'  => UserBlueprint::class,

panel/src/components/Navigation/ModelTabs.test.ts

@@ -5,14 +5,11 @@ import ModelTabs from "./ModelTabs.vue";
 const tabs = [
 	{
 		name: "main",
-		columns: [
-			{ fields: { headline: { type: "text" } } },
-			{ fields: { Text: { type: "textarea" } } }
-		]
+		fields: ["headline", "Text"]
 	},
 	{
 		name: "meta",
-		columns: [{ fields: { seo: { type: "text" } } }]
+		fields: ["seo"]
 	}
 ];
 
@@ -30,7 +27,7 @@ describe("ModelTabs.vue", () => {
 	});
 
 	describe("withBadges", () => {
-		it("counts the changed fields of all columns of a tab", () => {
+		it("counts the changed fields of a tab", () => {
 			expect(badges({ headline: "a", seo: "b" })).toStrictEqual([
 				{ text: 1 },
 				{ text: 1 }

panel/src/components/Navigation/ModelTabs.vue

@@ -25,14 +25,8 @@ export default {
 			const changes = Object.keys(this.diff);
 
 			return this.tabs.map((tab) => {
-				// collect all fields per tab
-				const fields = [];
-
-				for (const column in tab.columns) {
-					for (const field in tab.columns[column].fields) {
-						fields.push(field);
-					}
-				}
+				// all field names of the tab
+				const fields = tab.fields ?? [];
 
 				// get count of changed fields in this tab
 				const changesInTab = fields.filter((field) =>

src/Blueprint/Blueprint.php

@@ -52,7 +52,9 @@ class Blueprint
 
 	// Cache for sections created from `section` fields
 	protected array $sections = [];
-	protected array $tabs = [];
+
+	// Collected tabs, see `tabs()`
+	protected Tabs|null $tabs = null;
 
 	/**
 	 * Magic getter/caller for any blueprint prop
@@ -88,13 +90,11 @@ public function __construct(array $props)
 
 		// convert all shortcuts and normalize the props
 		$normalizer = new Normalizer(
-			model: $this->model,
 			props: $props
 		);
 
 		$this->fields = $normalizer->fields();
 		$this->props  = $normalizer->props();
-		$this->tabs   = $normalizer->tabs();
 	}
 
 	/**
@@ -461,23 +461,30 @@ public function sections(): array
 	}
 
 	/**
-	 * Returns a single tab by name
+	 * Returns a single tab by name or the
+	 * first tab if no name is given
 	 */
-	public function tab(string|null $name = null): array|null
+	public function tab(string|null $name = null): Tab|null
 	{
+		$tabs = $this->tabs();
+
 		if ($name === null) {
-			return A::first($this->tabs);
+			return $tabs->first();
 		}
 
-		return $this->tabs[$name] ?? null;
+		return $tabs->get($name);
 	}
 
 	/**
-	 * Returns all tabs
+	 * Creates and caches the collection of all tabs
+	 * from the normalized tab props
 	 */
-	public function tabs(): array
+	public function tabs(): Tabs
 	{
-		return array_values($this->tabs);
+		return $this->tabs ??= new Tabs(
+			tabs: $this->props['tabs'] ?? [],
+			model: $this->model
+		);
 	}
 
 	/**
@@ -493,6 +500,9 @@ public function title(): string
 	 */
 	public function toArray(): array
 	{
-		return $this->props;
+		return [
+			...$this->props,
+			'tabs' => $this->tabs()->toArray()
+		];
 	}
 }

src/Blueprint/Normalizer.php

@@ -2,7 +2,6 @@
 
 namespace Kirby\Blueprint;
 
-use Kirby\Cms\ModelWithContent;
 use Kirby\Exception\InvalidArgumentException;
 use Kirby\Form\Field;
 use Kirby\Toolkit\A;
@@ -36,10 +35,8 @@ class Normalizer
 	// Collected blueprint props
 	protected array $props;
 
-	public function __construct(
-		protected ModelWithContent $model,
-		array $props
-	) {
+	public function __construct(array $props)
+	{
 		$this->props = $this->normalize($props);
 	}
 
@@ -488,7 +485,6 @@ protected function normalizeTabs(mixed $tabs): array
 				'columns' => $this->normalizeColumns($tabName, $tabProps['columns'] ?? []),
 				'icon'    => $tabProps['icon']  ?? null,
 				'label'   => $this->i18n($tabProps['label'] ?? Str::label($tabName)),
-				'link'    => $this->model->panel()->url(true) . '/?tab=' . $tabName,
 				'name'    => $tabName,
 			];
 		}

src/Blueprint/Tab.php

@@ -0,0 +1,161 @@
+<?php
+
+namespace Kirby\Blueprint;
+
+use Kirby\Cms\ModelWithContent;
+use Kirby\Form\Fields;
+use Kirby\Toolkit\I18n;
+use Kirby\Toolkit\Str;
+
+/**
+ * Represents a single tab of a blueprint. Tabs are
+ * the top level of the blueprint layout. They hold
+ * columns, which hold fields.
+ *
+ * @copyright Bastian Allgeier
+ * @license   https://getkirby.com/license
+ * @since     6.0.0
+ */
+class Tab
+{
+	public function __construct(
+		protected ModelWithContent $model,
+		protected string $name,
+		protected array $columns = [],
+		protected string|null $icon = null,
+		protected array|string|null $label = null,
+		protected array $props = []
+	) {
+	}
+
+	/**
+	 * Returns all normalized columns of the tab.
+	 *
+	 * If a `Fields` collection is passed, the blueprint field
+	 * definitions of each column are replaced by the resolved
+	 * field props for the Panel.
+	 */
+	public function columns(Fields|null $fields = null): array
+	{
+		if ($fields === null) {
+			return $this->columns;
+		}
+
+		$columns = $this->columns;
+
+		foreach ($columns as $key => $column) {
+			$names = array_map(
+				'strtolower',
+				array_keys($column['fields'] ?? [])
+			);
+
+			// only resolve the props of the fields in this tab,
+			// as that can be expensive for list fields
+			$columns[$key]['fields'] = $fields
+				->filter(fn ($field) => in_array($field->name(), $names, true))
+				->toProps();
+		}
+
+		return $columns;
+	}
+
+	/**
+	 * Returns a flat list of the lowercase names of all
+	 * fields in the tab. The Panel uses this list to count
+	 * the unsaved changes per tab.
+	 */
+	public function fieldNames(): array
+	{
+		$names = [];
+
+		foreach ($this->columns as $column) {
+			foreach (array_keys($column['fields'] ?? []) as $name) {
+				$names[] = Str::lower($name);
+			}
+		}
+
+		return $names;
+	}
+
+	/**
+	 * Returns the icon of the tab
+	 */
+	public function icon(): string|null
+	{
+		return $this->icon;
+	}
+
+	/**
+	 * Returns the translated label of the tab and
+	 * falls back to an automatic label
+	 */
+	public function label(): string
+	{
+		$label = I18n::translate($this->label, $this->label);
+
+		if (is_string($label) === true) {
+			return $label;
+		}
+
+		return Str::label($this->name);
+	}
+
+	/**
+	 * Returns the Panel link to the tab
+	 */
+	public function link(): string
+	{
+		return $this->model->panel()->url(true) . '/?tab=' . $this->name;
+	}
+
+	/**
+	 * Returns the parent model
+	 */
+	public function model(): ModelWithContent
+	{
+		return $this->model;
+	}
+
+	/**
+	 * Returns the name of the tab
+	 */
+	public function name(): string
+	{
+		return $this->name;
+	}
+
+	/**
+	 * Returns the reduced props for the Panel tab bar.
+	 * The columns are not included here, as the tab bar
+	 * only needs to render a button per tab.
+	 */
+	public function toButtonProps(): array
+	{
+		return [
+			'fields' => $this->fieldNames(),
+			'icon'   => $this->icon(),
+			'label'  => $this->label(),
+			'link'   => $this->link(),
+			'name'   => $this->name(),
+		];
+	}
+
+	/**
+	 * Converts the tab to a plain array with all
+	 * columns and fields.
+	 *
+	 * If a `Fields` collection is passed, the columns
+	 * carry the resolved field props for the Panel.
+	 */
+	public function toViewProps(Fields|null $fields = null): array
+	{
+		return [
+			...$this->props,
+			'columns' => $this->columns($fields),
+			'icon'    => $this->icon(),
+			'label'   => $this->label(),
+			'link'    => $this->link(),
+			'name'    => $this->name(),
+		];
+	}
+}