Merge branch 'main' into l12

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Feature request
+    url: https://github.com/laravel/prompts/pulls
+    about: 'For ideas or feature requests, send in a pull request'
   - name: Support Questions & Other
     url: https://laravel.com/docs/contributions#support-questions
     about: 'This repository is only for reporting bugs. If you have a question or need help using the library, click:'

.github/SECURITY.md

@@ -15,7 +15,7 @@ If you discover a security vulnerability within Laravel, please send an email to
 ```
 -----BEGIN PGP PUBLIC KEY BLOCK-----
 Version: OpenPGP v2.0.8
-Comment: https://sela.io/pgp/
+Comment: Report Security Vulnerabilities to [email protected]
 
 xsFNBFugFSQBEACxEKhIY9IoJzcouVTIYKJfWFGvwFgbRjQWBiH3QdHId5vCrbWo
 s2l+4Rv03gMG+yHLJ3rWElnNdRaNdQv59+lShrZF7Bvu7Zvc0mMNmFOM/mQ/K2Lt

CHANGELOG.md

@@ -1,6 +1,51 @@
 # Release Notes
 
-## [Unreleased](https://github.com/laravel/prompts/compare/v0.1.18...main)
+## [Unreleased](https://github.com/laravel/prompts/compare/v0.2.1...main)
+
+## [v0.2.1](https://github.com/laravel/prompts/compare/v0.2.0...v0.2.1) - 2024-09-19
+
+* [ BugFix ] Handle Failed Terminal Read Gracefully by [@ProjektGopher](https://github.com/ProjektGopher) in https://github.com/laravel/prompts/pull/164
+* Update `dev-main` branch alias to `0.2.x-dev` by [@crynobone](https://github.com/crynobone) in https://github.com/laravel/prompts/pull/166
+
+## [v0.2.0](https://github.com/laravel/prompts/compare/v0.1.25...v0.2.0) - 2024-09-11
+
+* Adding "Clear" Function For Cleaning The Terminal by [@TarsisioXavier](https://github.com/TarsisioXavier) in https://github.com/laravel/prompts/pull/160
+* Extract Looping Mechanisms by [@ProjektGopher](https://github.com/ProjektGopher) in https://github.com/laravel/prompts/pull/162
+
+## [v0.1.25](https://github.com/laravel/prompts/compare/v0.1.24...v0.1.25) - 2024-08-12
+
+* Add transformation support by [@emenkens](https://github.com/emenkens) in https://github.com/laravel/prompts/pull/156
+* Fix textarea helper method signature. by [@samrap](https://github.com/samrap) in https://github.com/laravel/prompts/pull/159
+
+## [v0.1.24](https://github.com/laravel/prompts/compare/v0.1.23...v0.1.24) - 2024-06-17
+
+* Allow re-rendering during progress callback by [@jessarcher](https://github.com/jessarcher) in https://github.com/laravel/prompts/pull/155
+
+## [v0.1.23](https://github.com/laravel/prompts/compare/v0.1.22...v0.1.23) - 2024-05-27
+
+* Ignore PHPstan error by [@jessarcher](https://github.com/jessarcher) in https://github.com/laravel/prompts/pull/149
+* Allow selecting all options in a `multiselect` by [@duncanmcclean](https://github.com/duncanmcclean) in https://github.com/laravel/prompts/pull/147
+
+## [v0.1.22](https://github.com/laravel/prompts/compare/v0.1.21...v0.1.22) - 2024-05-10
+
+* fix(helper): ensure helpers can't be redeclared by [@NickSdot](https://github.com/NickSdot) in https://github.com/laravel/prompts/pull/146
+
+## [v0.1.21](https://github.com/laravel/prompts/compare/v0.1.20...v0.1.21) - 2024-04-30
+
+* Add description to composer.json by [@edwinvdpol](https://github.com/edwinvdpol) in https://github.com/laravel/prompts/pull/139
+* Add ability to specify character in pad function by [@ProjektGopher](https://github.com/ProjektGopher) in https://github.com/laravel/prompts/pull/141
+* Adds support for additional keys by [@ProjektGopher](https://github.com/ProjektGopher) in https://github.com/laravel/prompts/pull/140
+* Extract string handling methods from DrawsBoxes trait by [@ProjektGopher](https://github.com/ProjektGopher) in https://github.com/laravel/prompts/pull/142
+
+## [v0.1.20](https://github.com/laravel/prompts/compare/v0.1.19...v0.1.20) - 2024-04-18
+
+* Fix for up/down arrows + cursor position when textarea content contains multi-byte strings by [@joetannenbaum](https://github.com/joetannenbaum) in https://github.com/laravel/prompts/pull/137
+
+## [v0.1.19](https://github.com/laravel/prompts/compare/v0.1.18...v0.1.19) - 2024-04-16
+
+* Fix `multisearch` array handling by [@jessarcher](https://github.com/jessarcher) in https://github.com/laravel/prompts/pull/132
+* Adds Reversible Forms to Prompts by [@lukeraymonddowning](https://github.com/lukeraymonddowning) in https://github.com/laravel/prompts/pull/118
+* Fix type error in suggest with collection by [@macocci7](https://github.com/macocci7) in https://github.com/laravel/prompts/pull/134
 
 ## [v0.1.18](https://github.com/laravel/prompts/compare/v0.1.17...v0.1.18) - 2024-04-04
 

composer.json

@@ -1,6 +1,7 @@
 {
     "name": "laravel/prompts",
     "type": "library",
+    "description": "Add beautiful and user-friendly forms to your command-line applications.",
     "license": "MIT",
     "autoload": {
         "psr-4": {
@@ -41,7 +42,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-main": "0.1.x-dev"
+            "dev-main": "0.2.x-dev"
         }
     },
     "prefer-stable": true,

phpunit.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.2/phpunit.xsd" bootstrap="vendor/autoload.php" colors="true" backupStaticProperties="true">
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.2/phpunit.xsd" bootstrap="vendor/autoload.php" colors="true" backupStaticProperties="true" failOnWarning="true">
   <testsuites>
     <testsuite name="Test Suite">
       <directory suffix="Test.php">./tests</directory>

playground/clear.php

@@ -0,0 +1,19 @@
+<?php
+
+use function Laravel\Prompts\clear;
+use function Laravel\Prompts\note;
+use function Laravel\Prompts\pause;
+
+require __DIR__.'/../vendor/autoload.php';
+
+note('This will disappear.');
+
+pause('Press [Enter] to continue.');
+
+clear();
+
+note('This will also disappear.');
+
+pause('Press [Enter] to continue.');
+
+clear();

playground/text.php

@@ -13,6 +13,7 @@
         default => null,
     },
     hint: 'We will never share your email address with anyone else.',
+    transform: fn ($value) => strtolower($value),
 );
 
 var_dump($email);

playground/textarea.php

@@ -4,11 +4,11 @@
 
 require __DIR__.'/../vendor/autoload.php';
 
-$email = textarea(
+$story = textarea(
     label: 'Tell me a story',
     placeholder: 'Weave me a tale',
 );
 
-var_dump($email);
+var_dump($story);
 
 echo str_repeat(PHP_EOL, 5);

src/Clear.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Laravel\Prompts;
+
+class Clear extends Prompt
+{
+    /**
+     * Clear the terminal.
+     */
+    public function prompt(): bool
+    {
+        // Fill the previous newline count so subsequent prompts won't add padding.
+        static::output()->write(PHP_EOL.PHP_EOL);
+
+        $this->writeDirectly($this->renderTheme());
+
+        return true;
+    }
+
+    /**
+     * Clear the terminal.
+     */
+    public function display(): void
+    {
+        $this->prompt();
+    }
+
+    /**
+     * Get the value of the prompt.
+     */
+    public function value(): bool
+    {
+        return true;
+    }
+}

src/Concerns/FakesInputOutput.php

@@ -29,13 +29,30 @@ public static function fake(array $keys = []): void
         $mock->shouldReceive('lines')->byDefault()->andReturn(24);
         $mock->shouldReceive('initDimensions')->byDefault();
 
-        foreach ($keys as $key) {
+        static::fakeKeyPresses($keys, function (string $key) use ($mock): void {
             $mock->shouldReceive('read')->once()->andReturn($key);
-        }
+        });
 
         static::$terminal = $mock;
 
-        self::setOutput(new BufferedConsoleOutput());
+        self::setOutput(new BufferedConsoleOutput);
+    }
+
+    /**
+     * Implementation of the looping mechanism for simulating key presses.
+     *
+     * By ignoring the `$callable` parameter which contains the default logic
+     * for simulating fake key presses, we can use a custom implementation
+     * to emit key presses instead, allowing us to use different inputs.
+     *
+     * @param  array<string>  $keys
+     * @param  callable(string $key): void  $callable
+     */
+    public static function fakeKeyPresses(array $keys, callable $callable): void
+    {
+        foreach ($keys as $key) {
+            $callable($key);
+        }
     }
 
     /**

src/Concerns/Termwind.php

@@ -11,7 +11,7 @@ trait Termwind
 {
     protected function termwind(string $html)
     {
-        renderUsing($output = new BufferedConsoleOutput());
+        renderUsing($output = new BufferedConsoleOutput);
 
         render($html);
 

src/Concerns/Themes.php

@@ -3,6 +3,7 @@
 namespace Laravel\Prompts\Concerns;
 
 use InvalidArgumentException;
+use Laravel\Prompts\Clear;
 use Laravel\Prompts\ConfirmPrompt;
 use Laravel\Prompts\MultiSearchPrompt;
 use Laravel\Prompts\MultiSelectPrompt;
@@ -17,6 +18,7 @@
 use Laravel\Prompts\Table;
 use Laravel\Prompts\TextareaPrompt;
 use Laravel\Prompts\TextPrompt;
+use Laravel\Prompts\Themes\Default\ClearRenderer;
 use Laravel\Prompts\Themes\Default\ConfirmPromptRenderer;
 use Laravel\Prompts\Themes\Default\MultiSearchPromptRenderer;
 use Laravel\Prompts\Themes\Default\MultiSelectPromptRenderer;
@@ -60,6 +62,7 @@ trait Themes
             Note::class => NoteRenderer::class,
             Table::class => TableRenderer::class,
             Progress::class => ProgressRenderer::class,
+            Clear::class => ClearRenderer::class,
         ],
     ];
 

src/Concerns/TypedValue.php

@@ -27,8 +27,10 @@ protected function trackTypedValue(string $default = '', bool $submit = true, ?c
             $this->cursorPosition = mb_strlen($this->typedValue);
         }
 
-        $this->on('key', function ($key) use ($submit, $ignore, $allowNewLine) {
-            if ($key[0] === "\e" || in_array($key, [Key::CTRL_B, Key::CTRL_F, Key::CTRL_A, Key::CTRL_E])) {
+        $this->on('key', function (string $key) use ($submit, $ignore, $allowNewLine): void {
+            if ($key !== '' &&
+                ($key[0] === "\e" || in_array($key, [Key::CTRL_B, Key::CTRL_F, Key::CTRL_A, Key::CTRL_E]))
+            ) {
                 if ($ignore !== null && $ignore($key)) {
                     return;
                 }

src/ConfirmPrompt.php

@@ -2,6 +2,8 @@
 
 namespace Laravel\Prompts;
 
+use Closure;
+
 class ConfirmPrompt extends Prompt
 {
     /**
@@ -20,6 +22,7 @@ public function __construct(
         public bool|string $required = false,
         public mixed $validate = null,
         public string $hint = '',
+        public ?Closure $transform = null,
     ) {
         $this->confirmed = $default;
 

src/FormBuilder.php

@@ -78,23 +78,23 @@ public function submit(): array
     /**
      * Prompt the user for text input.
      */
-    public function text(string $label, string $placeholder = '', string $default = '', bool|string $required = false, mixed $validate = null, string $hint = '', ?string $name = null): self
+    public function text(string $label, string $placeholder = '', string $default = '', bool|string $required = false, mixed $validate = null, string $hint = '', ?string $name = null, ?Closure $transform = null): self
     {
         return $this->runPrompt(text(...), get_defined_vars());
     }
 
     /**
      * Prompt the user for multiline text input.
      */
-    public function textarea(string $label, string $placeholder = '', string $default = '', bool|string $required = false, ?Closure $validate = null, string $hint = '', int $rows = 5, ?string $name = null): self
+    public function textarea(string $label, string $placeholder = '', string $default = '', bool|string $required = false, ?Closure $validate = null, string $hint = '', int $rows = 5, ?string $name = null, ?Closure $transform = null): self
     {
         return $this->runPrompt(textarea(...), get_defined_vars());
     }
 
     /**
      * Prompt the user for input, hiding the value.
      */
-    public function password(string $label, string $placeholder = '', bool|string $required = false, mixed $validate = null, string $hint = '', ?string $name = null): self
+    public function password(string $label, string $placeholder = '', bool|string $required = false, mixed $validate = null, string $hint = '', ?string $name = null, ?Closure $transform = null): self
     {
         return $this->runPrompt(password(...), get_defined_vars());
     }
@@ -105,7 +105,7 @@ public function password(string $label, string $placeholder = '', bool|string $r
      * @param  array<int|string, string>|Collection<int|string, string>  $options
      * @param  true|string  $required
      */
-    public function select(string $label, array|Collection $options, int|string|null $default = null, int $scroll = 5, mixed $validate = null, string $hint = '', bool|string $required = true, ?string $name = null): self
+    public function select(string $label, array|Collection $options, int|string|null $default = null, int $scroll = 5, mixed $validate = null, string $hint = '', bool|string $required = true, ?string $name = null, ?Closure $transform = null): self
     {
         return $this->runPrompt(select(...), get_defined_vars());
     }
@@ -116,15 +116,15 @@ public function select(string $label, array|Collection $options, int|string|null
      * @param  array<int|string, string>|Collection<int|string, string>  $options
      * @param  array<int|string>|Collection<int, int|string>  $default
      */
-    public function multiselect(string $label, array|Collection $options, array|Collection $default = [], int $scroll = 5, bool|string $required = false, mixed $validate = null, string $hint = 'Use the space bar to select options.', ?string $name = null): self
+    public function multiselect(string $label, array|Collection $options, array|Collection $default = [], int $scroll = 5, bool|string $required = false, mixed $validate = null, string $hint = 'Use the space bar to select options.', ?string $name = null, ?Closure $transform = null): self
     {
         return $this->runPrompt(multiselect(...), get_defined_vars());
     }
 
     /**
      * Prompt the user to confirm an action.
      */
-    public function confirm(string $label, bool $default = true, string $yes = 'Yes', string $no = 'No', bool|string $required = false, mixed $validate = null, string $hint = '', ?string $name = null): self
+    public function confirm(string $label, bool $default = true, string $yes = 'Yes', string $no = 'No', bool|string $required = false, mixed $validate = null, string $hint = '', ?string $name = null, ?Closure $transform = null): self
     {
         return $this->runPrompt(confirm(...), get_defined_vars());
     }
@@ -142,7 +142,7 @@ public function pause(string $message = 'Press enter to continue...', ?string $n
      *
      * @param  array<string>|Collection<int, string>|Closure(string): array<string>  $options
      */
-    public function suggest(string $label, array|Collection|Closure $options, string $placeholder = '', string $default = '', int $scroll = 5, bool|string $required = false, mixed $validate = null, string $hint = '', ?string $name = null): self
+    public function suggest(string $label, array|Collection|Closure $options, string $placeholder = '', string $default = '', int $scroll = 5, bool|string $required = false, mixed $validate = null, string $hint = '', ?string $name = null, ?Closure $transform = null): self
     {
         return $this->runPrompt(suggest(...), get_defined_vars());
     }
@@ -153,7 +153,7 @@ public function suggest(string $label, array|Collection|Closure $options, string
      * @param  Closure(string): array<int|string, string>  $options
      * @param  true|string  $required
      */
-    public function search(string $label, Closure $options, string $placeholder = '', int $scroll = 5, mixed $validate = null, string $hint = '', bool|string $required = true, ?string $name = null): self
+    public function search(string $label, Closure $options, string $placeholder = '', int $scroll = 5, mixed $validate = null, string $hint = '', bool|string $required = true, ?string $name = null, ?Closure $transform = null): self
     {
         return $this->runPrompt(search(...), get_defined_vars());
     }
@@ -163,7 +163,7 @@ public function search(string $label, Closure $options, string $placeholder = ''
      *
      * @param  Closure(string): array<int|string, string>  $options
      */
-    public function multisearch(string $label, Closure $options, string $placeholder = '', int $scroll = 5, bool|string $required = false, mixed $validate = null, string $hint = 'Use the space bar to select options.', ?string $name = null): self
+    public function multisearch(string $label, Closure $options, string $placeholder = '', int $scroll = 5, bool|string $required = false, mixed $validate = null, string $hint = 'Use the space bar to select options.', ?string $name = null, ?Closure $transform = null): self
     {
         return $this->runPrompt(multisearch(...), get_defined_vars());
     }

src/Key.php

@@ -6,8 +6,12 @@ class Key
 {
     const UP = "\e[A";
 
+    const SHIFT_UP = "\e[1;2A";
+
     const DOWN = "\e[B";
 
+    const SHIFT_DOWN = "\e[1;2B";
+
     const RIGHT = "\e[C";
 
     const LEFT = "\e[D";
@@ -20,6 +24,8 @@ class Key
 
     const LEFT_ARROW = "\eOD";
 
+    const ESCAPE = "\e";
+
     const DELETE = "\e[3~";
 
     const BACKSPACE = "\177";