->roles($context) to limit available roles

config/api/routes/roles.php

@@ -8,13 +8,9 @@
 		'pattern' => 'roles',
 		'method'  => 'GET',
 		'action'  => function () {
-			$kirby = $this->kirby();
-
-			return match ($kirby->request()->get('canBe')) {
-				'changed' => $kirby->roles()->canBeChanged(),
-				'created' => $kirby->roles()->canBeCreated(),
-				default   => $kirby->roles()
-			};
+			$kirby   = $this->kirby();
+			$context = $kirby->request()->get('canBe');
+			return $kirby->roles($context);
 		}
 	],
 	[

src/Cms/App.php

@@ -1301,10 +1301,22 @@ public function response(): Responder
 
 	/**
 	 * Returns all user roles
+	 *
+	 * @param string|null $context User action context for which the roles are used (create, change)
 	 */
-	public function roles(): Roles
+	public function roles(string|null $context = null): Roles
 	{
-		return $this->roles ??= Roles::load($this->root('roles'));
+		$roles = $this->roles ??= Roles::load($this->root('roles'));
+
+		// filter roles based on the user action context
+		// as user permissions and/or options can restrict these further
+		$roles = match ($context) {
+			'create', 'created' => $roles->canBeCreated(),
+			'change', 'changed' => $roles->canBeChanged(),
+			default             => $roles
+		};
+
+		return $roles;
 	}
 
 	/**

src/Cms/User.php

@@ -574,14 +574,15 @@ public function role(): Role
 	}
 
 	/**
-	 * Returns all available roles
-	 * for this user, that can be selected
-	 * by the authenticated user
+	 * Returns all available roles for this user,
+	 * that can be selected by the authenticated user
+	 *
+	 * @param string|null $context User action context for which the roles are used (create, change)
 	 */
-	public function roles(): Roles
+	public function roles(string|null $context = null): Roles
 	{
 		$kirby = $this->kirby();
-		$roles = $kirby->roles();
+		$roles = $kirby->roles($context);
 
 		// a collection with just the one role of the user
 		$myRole = $roles->filter('id', $this->role()->id());

tests/Cms/App/AppTest.php

@@ -767,6 +767,72 @@ public function testRolesFromFixtures()
 		$this->assertInstanceOf(Roles::class, $app->roles());
 	}
 
+	/**
+	 * @covers ::roles
+	 */
+	public function testRolesWithUserActionContext()
+	{
+		$app = new App([
+			'user'  => '[email protected]',
+			'users' => [
+				[
+					'email' => '[email protected]',
+					'role'  => 'editor'
+				]
+			],
+			'blueprints' => [
+				'users/admin' => [
+					'name' => 'admin'
+				],
+				'users/editor' => [
+					'name' => 'editor'
+				],
+				'users/client' => [
+					'name' => 'client'
+				]
+			]
+		]);
+
+		$this->assertCount(3, $app->roles());
+		$this->assertCount(2, $app->roles('create'));
+		$this->assertCount(0, $app->roles('change')); // TODO: change once `User::roles()` and `UserPermissions::canChangeRole()` have been improved/fixed
+
+		Blueprint::$loaded = [];
+
+		$app = new App([
+			'user'  => '[email protected]',
+			'users' => [
+				[
+					'email' => '[email protected]',
+					'role'  => 'editor'
+				]
+			],
+			'blueprints' => [
+				'users/admin' => [
+					'name' => 'admin'
+				],
+				'users/editor' => [
+					'name' => 'editor'
+				],
+				'users/client' => [
+					'name'    => 'client',
+					'options' => [
+						'create' => [
+							'editor' => false
+						],
+						'changeRole' => [
+							'editor' => false
+						]
+					]
+				],
+			]
+		]);
+
+		$this->assertCount(3, $app->roles());
+		$this->assertCount(1, $app->roles('create'));
+		$this->assertCount(0, $app->roles('change')); // TODO: change once `User::roles()` and `UserPermissions::canChangeRole()` have been improved/fixed
+	}
+
 	// TODO: debug is not working properly
 	// public function testEmail()
 	// {