Add FAQ entry about tab completion in prompts

docs/contrib.md

@@ -32,8 +32,17 @@ Some of the most popular and actively maintained are listed below:
 | [Cloup](https://github.com/janluke/cloup)               | Adds option groups, constraints, command aliases, help themes, suggestions and more. | ![GitHub stars](https://img.shields.io/github/stars/janluke/cloup?label=%20&style=flat-square)         | ![Last commit](https://img.shields.io/github/last-commit/janluke/cloup?label=%20&style=flat-square)         |
 | [Click Extra](https://github.com/kdeldycke/click-extra) | Cloup + colorful `--help`, `--config`, `--show-params`, `--verbosity` options, etc.  | ![GitHub stars](https://img.shields.io/github/stars/kdeldycke/click-extra?label=%20&style=flat-square) | ![Last commit](https://img.shields.io/github/last-commit/kdeldycke/click-extra?label=%20&style=flat-square) |
 
+## Interactive input libraries
+
+Click reads a prompt with the built-in {func}`input` and embeds no line editor of its own. If you need fancy features like completion of arbitrary values, selection menus or fuzzy search you need to replace {func}`click.prompt` with a third-party library. The projects below are popular and actively maintained:
+
+| Project                                                                   | Description                                                                | Popularity                                                                                                            | Activity                                                                                                                   |
+|---------------------------------------------------------------------------|----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
+| [Textual](https://github.com/Textualize/textual)                          | Build terminal and web user interfaces with a Python API.                  | ![GitHub stars](https://img.shields.io/github/stars/Textualize/textual?label=%20&style=flat-square)                   | ![Last commit](https://img.shields.io/github/last-commit/Textualize/textual?label=%20&style=flat-square)                   |
+| [prompt-toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) | Build interactive command lines with completion, history and key bindings. | ![GitHub stars](https://img.shields.io/github/stars/prompt-toolkit/python-prompt-toolkit?label=%20&style=flat-square) | ![Last commit](https://img.shields.io/github/last-commit/prompt-toolkit/python-prompt-toolkit?label=%20&style=flat-square) |
+
 ```{note}
-To make it into the list above, a project:
+To make it into any of the lists above, a project:
 
 - must be actively maintained (at least one commit in the last year)
 - must have a reasonable number of stars (at least 20)

docs/faqs.md

@@ -105,6 +105,60 @@ You can set the `EDITOR` in your environment with its appropriate flags:
 
 For an editor with no such flag, a workaround is to point `EDITOR` at a small wrapper script that opens the editor and blocks until it exits.
 
+### Tab completion during interactive prompts
+
+A command asks for a file path while it runs:
+
+```python
+import click
+
+
+@click.command()
+def convert():
+    source = click.prompt("File to convert", type=click.Path(exists=True))
+    click.echo(f"Converting {source}")
+```
+
+Pressing {kbd}`Tab` while typing the answer inserts a tab character instead of completing the path:
+
+```console
+$ convert
+File to convert: Doc<TAB>
+Error: Path 'Doc\t' does not exist.
+```
+
+This is not a bug in Click. Tab completion of the command line belongs to the shell: the shell asks the program for candidates through Click's completion mode, before any command code runs. A prompt works the other way around. The program already runs and reads the line itself, so Click never sees the {kbd}`Tab` key.
+
+{func}`~click.prompt` reads that line with the built-in {func}`input`, and Click passes the whole prompt text to it as-is. This is where Python's {mod}`readline` module takes over, but nothing binds {kbd}`Tab` to completion by default.
+
+#### Answer
+
+Bind {kbd}`Tab` in `readline` and the prompt completes paths with no other change:
+
+```python
+import readline
+
+if "libedit" in (readline.__doc__ or ""):
+    readline.parse_and_bind("bind ^I rl_complete")
+else:
+    readline.parse_and_bind("tab: complete")
+```
+
+See the {mod}`readline` documentation for the binding syntax, for the two libraries it can be built on, and for writing a completer of your own. The module is Unix-only, so the import fails on Windows.
+
+Readline completes file names. It knows nothing about the parameter, so it cannot complete other values, such as the choices of a {class}`~click.Choice` parameter. Click embeds no line editor of its own: for completion of such values at a prompt, use one of the [interactive input libraries](contrib.md#interactive-input-libraries).
+
+When the value does not have to be asked while the command runs, another option is to take it out of the prompt and put it on the command line, as an argument or an option:
+
+```python
+@click.command()
+@click.argument("source", type=click.Path(exists=True))
+def convert(source):
+    click.echo(f"Converting {source}")
+```
+
+The shell completes paths there natively and Click's completion mode takes part in it (as described in [Shell Completion](shell-completion.md)).
+
 (custom-completions-show-the-full-value)=
 ### Custom completions show the full value