back + tests + doc

Author: dvlpp

demo/app/Sharp/Authors/Commands/VisitFacebookProfileCommand.php

@@ -20,7 +20,7 @@ public function buildCommandConfig(): void
 
     public function execute(mixed $instanceId, array $data = []): array
     {
-        return $this->link('https://facebook.com');
+        return $this->link('https://facebook.com', targetBlank: true);
     }
 
     public function authorizeFor(mixed $instanceId): bool

docs/guide/commands.md

@@ -169,18 +169,18 @@ Here is the full list of available methods:
 
 ### Command return types
 
-Finally, let's review the return possibilities: after a Command has been executed, the code must return something to tell to the front what to do next. There are height of them:
+Finally, let's review the return possibilities: after a Command has been executed, the code must return something to tell to the front what to do next. There are eight of them:
 
-- `return $this->info('some text', reload: true)`: displays the entered text in a modal. The second argument, optional (default is `false`), is a boolean to also mark Sharp to reload the page.
+- `return $this->info(string $message, bool $reload = false)`: displays the entered text in a modal. The second argument allows reloading the page first.
 - `return $this->reload()`: reload the current page (with context).
-- `return $this->refresh(1)`*: refresh only the instance with an id on `1`. We can pass an id array also to refresh more than one instance.
-- `return $this->view('view.name', ['some'=>'params'])`: display a view right in Sharp; useful for page previews.
-- `return $this->html('...')`: display an HTML content.
-- `return $this->link('/path/to/redirect')`: redirect to the given path.
-- `return $this->download('path', 'diskName')`: the browser will download the specified file.
-- `return $this->streamDownload('path', 'name')`: the browser will stream the specified file.
-
-\* `refresh()` is only useful in an Entity List case (in a Dashboard or a Show Page, it will be treated as a `reload()`). In order to make it work properly, you have to slightly adapt the `getListData()` of your Entity List implementation, making use of `$this->queryParams->specificIds()`:
+- `return $this->refresh(mixed $ids)`*: refresh only instance(s) with an id in `$ids`, which can be either a single id or an array.
+- `return $this->view(string $bladeView, array $params = [])`: display a view right in Sharp; useful for page previews.
+- `return $this->html(string $htmlContent)`: display an HTML content.
+- `return $this->link(string $link, bool $targetBlank = false)`: redirect to the given path. The second argument, optional (default is `false`), is a boolean to open the link in a new tab.
+- `return $this->download(string $filePath, ?string $fileName = null, ?string $diskName = null)`: the browser will download the specified file.
+- `return $this->streamDownload(string $fileContent, string $fileName)`: the browser will stream the specified file.
+
+\* `refresh()` is only useful in an Entity List case (in a Dashboard or a Show Page, it will be treated as a `reload()`). To make it work properly, you have to slightly adapt the `getListData()` of your Entity List implementation, making use of `$this->queryParams->specificIds()`:
 
 ```php
 class OrderList extends SharpEntityList

src/Data/Commands/CommandResponseData.php

@@ -8,7 +8,7 @@
 
 // download & streamDownload actions returns the file directly in the response
 #[LiteralTypeScriptType(
-    '{ action: "'.CommandAction::Link->value.'", link: string } | '.
+    '{ action: "'.CommandAction::Link->value.'", link: string, targetBlank: boolean } | '.
     '{ action: "'.CommandAction::Info->value.'", message: string, reload: boolean } | '.
     '{ action: "'.CommandAction::Refresh->value.'", items?: Array<{ [key: string]: any }> } | '.
     '{ action: "'.CommandAction::Reload->value.'" } | '.

src/EntityList/Commands/Command.php

@@ -44,11 +44,12 @@ protected function info(string $message, bool $reload = false): array
         ];
     }
 
-    protected function link(string $link): array
+    protected function link(string $link, bool $targetBlank = false): array
     {
         return [
             'action' => CommandAction::Link->value,
             'link' => $link,
+            'targetBlank' => $targetBlank,
         ];
     }
 

src/EntityList/Commands/EntityState.php

@@ -46,7 +46,7 @@ protected function streamDownload(string $fileContent, string $fileName): array
         throw new SharpInvalidConfigException('StreamDownload return type is not supported for a state.');
     }
 
-    protected function link(string $link): array
+    protected function link(string $link, bool $targetBlank = false): array
     {
         throw new SharpInvalidConfigException('Link return type is not supported for a state.');
     }

tests/Http/Api/Commands/ApiEntityListEntityCommandControllerTest.php

@@ -211,6 +211,68 @@ public function getListData(): array|\Illuminate\Contracts\Support\Arrayable
         ]);
 });
 
+it('allows to call an link entity command', function () {
+    fakeListFor('person', new class() extends PersonList
+    {
+        protected function getEntityCommands(): ?array
+        {
+            return [
+                'cmd' => new class() extends EntityCommand
+                {
+                    public function label(): ?string
+                    {
+                        return 'entity';
+                    }
+
+                    public function execute(array $data = []): array
+                    {
+                        return $this->link('https://sharp.code16.fr');
+                    }
+                },
+            ];
+        }
+    });
+
+    $this->postJson(route('code16.sharp.api.list.command.entity', ['person', 'cmd']))
+        ->assertOk()
+        ->assertJson([
+            'action' => 'link',
+            'link' => 'https://sharp.code16.fr',
+            'targetBlank' => false,
+        ]);
+});
+
+it('allows to call an link + targetBlank entity command', function () {
+    fakeListFor('person', new class() extends PersonList
+    {
+        protected function getEntityCommands(): ?array
+        {
+            return [
+                'cmd' => new class() extends EntityCommand
+                {
+                    public function label(): ?string
+                    {
+                        return 'entity';
+                    }
+
+                    public function execute(array $data = []): array
+                    {
+                        return $this->link('https://sharp.code16.fr', targetBlank: true);
+                    }
+                },
+            ];
+        }
+    });
+
+    $this->postJson(route('code16.sharp.api.list.command.entity', ['person', 'cmd']))
+        ->assertOk()
+        ->assertJson([
+            'action' => 'link',
+            'link' => 'https://sharp.code16.fr',
+            'targetBlank' => true,
+        ]);
+});
+
 it('allows to call a form entity command and it handles 422', function () {
     fakeListFor('person', new class() extends PersonList
     {