enh: TextInterface mnemonic

Author: e3rd

docs/Settings.md

@@ -60,7 +60,7 @@ The difference when using such configuration file.
 
 ### Inheritance
 
-The individual setting items are inherited, while the descendants have the higher priority.
+The individual setting items are inherited, while the descendants have the higher priority. Ex. `TuiSettings` works as a default for `TextSettings` and `TextualSettings`.
 
 ```mermaid
 graph LR
@@ -70,7 +70,7 @@ TextualSettings --> TuiSettings
 TextSettings --> TuiSettings
 ```
 
-Ex. this config file sets the `UiSettings` item [`mnemonic`][mininterface.settings.UiSettings.mnemonic] to None for `TuiSettings` and more specifically to False for `TextSettings`.
+Ex. this config file sets the `UiSettings` item [`mnemonic`][mininterface.settings.UiSettings.mnemonic] to `None` for `TuiSettings` and more specifically to `False` for `TextSettings`.
 
 ```yaml
 mininterface:
@@ -99,5 +99,17 @@ For the different interfaces, the value varies this way:
         show_root_full_path: false
 
 ::: mininterface.settings.GuiSettings
+    options:
+        show_root_full_path: false
+
+::: mininterface.settings.TuiSettings
+    options:
+        show_root_full_path: false
+
+::: mininterface.settings.TextualSettings
+    options:
+        show_root_full_path: false
+
+::: mininterface.settings.TextSettings
     options:
         show_root_full_path: false

mininterface/_mininterface/adaptor.py

@@ -40,31 +40,34 @@ def run_dialog(self, form: TagDict, title: str = "", submit: bool | str = True)
         Setups the facet._fetch_from_adaptor.
         """
         self.facet._fetch_from_adaptor(form)
+        if self.settings.mnemonic is not False:
+            self._determine_mnemonic(form, self.settings.mnemonic is True)
 
+    def _determine_mnemonic(self, form: TagDict, also_nones=False):
+        """ also_nones – Also determine those tags when Tag.mnemonic=None. """
         # Determine mnemonic
-        if self.settings.mnemonic is not False:
-            used_mnemonic = set()
-            to_be_determined: list[Tag] = []
-            for tag in flatten(form):
-                if tag.mnemonic is False:
-                    continue
-                if isinstance(tag.mnemonic, str):
-                    used_mnemonic.add(tag.mnemonic)
-                    tag._mnemonic = tag.mnemonic
-                elif self.settings.mnemonic or tag.mnemonic:
-                    # .settings.mnemonic=None + tag.mnemonic=True OR
-                    # .settings.mnemonic=True + tag.mnemonic=None
-                    to_be_determined.append(tag)
-
-            # Find free mnemonic for Tag
-            for tag in to_be_determined:
-                # try every char in label
-                # then, if no free letter, give a random letter
-                for c in chain((c.lower() for c in tag.label if c.isalpha()), ascii_lowercase):
-                    if c not in used_mnemonic:
-                        used_mnemonic.add(c)
-                        tag._mnemonic = c
-                        break
+        used_mnemonic = set()
+        to_be_determined: list[Tag] = []
+        for tag in flatten(form):
+            if tag.mnemonic is False:
+                continue
+            if isinstance(tag.mnemonic, str):
+                used_mnemonic.add(tag.mnemonic)
+                tag._mnemonic = tag.mnemonic
+            elif also_nones or tag.mnemonic:
+                # .settings.mnemonic=None + tag.mnemonic=True OR
+                # .settings.mnemonic=True + tag.mnemonic=None
+                to_be_determined.append(tag)
+
+        # Find free mnemonic for Tag
+        for tag in to_be_determined:
+            # try every char in label
+            # then, if no free letter, give a random letter
+            for c in chain((c.lower() for c in tag.label if c.isalpha()), ascii_lowercase):
+                if c not in used_mnemonic:
+                    used_mnemonic.add(c)
+                    tag._mnemonic = c
+                    break
 
     def submit_done(self) -> bool:
         if action := self.post_submit_action:

mininterface/_text_interface/adaptor.py

@@ -94,6 +94,11 @@ def _get_tag_val(self, val: Tag | dict):
             case dict() as d:
                 return f"... ({len(d)}×)"
 
+    def _get_tag_mnemonic(self, val: Tag | dict):
+        if isinstance(val, Tag) and val._mnemonic:
+            return f"[{val._mnemonic}] "
+        return ""
+
     def run_dialog(self, form: TagDict, title: str = "", submit: bool | str = True) -> TagDict:
         """ Let the user edit the form_dict values in a GUI window.
         On abrupt window close, the program exits.
@@ -121,7 +126,7 @@ def _run_dialog(self, form: TagDict, title: str = "", submit: bool | str = True)
             if single:
                 key = next(iter(form))
             else:
-                index = self._choose([f"{key}{self._get_tag_val(val)}" for key,
+                index = self._choose([f"{self._get_tag_mnemonic(val)}{key}{self._get_tag_val(val)}" for key,
                                       val in form.items()], append_ok=True)
                 key = list(form)[index]
 
@@ -155,7 +160,10 @@ def _choose(self, items: list, title=None, append_ok=False, multiple: bool = Fal
         kwargs = {}
         if not multiple:
             if len(items) < 10:
-                it = [f"[{i+1}] {item}" for i, item in enumerate(items)]
+                # use number as shorcuts when no shortcuts are given `[c]`
+                it = [item if item.startswith("[")  # field already starts with a shortcut, ex. `[f] foo`
+                      else f"[{i+1}] {item}"  # add a number shorctu, ex. `[1] foo`
+                      for i, item in enumerate(items)]
             else:
                 kwargs = {"show_search_hint": True}
 
@@ -187,3 +195,8 @@ def _choose(self, items: list, title=None, append_ok=False, multiple: bool = Fal
                     raise Submit
                 index -= 1
         return index
+
+    def _determine_mnemonic(self, form: TagDict, also_nones=False):
+        if self.settings.mnemonic_over_number is False:
+            return
+        super()._determine_mnemonic(form, also_nones=also_nones and self.settings.mnemonic_over_number is True)

mininterface/_textual_interface/textual_app.py

@@ -1,3 +1,4 @@
+import asyncio
 from typing import TYPE_CHECKING
 from textual import events
 from textual.app import App

mininterface/_textual_interface/widgets.py

@@ -32,6 +32,19 @@ def get_ui_value(self):
         else:
             return self.value
 
+    # NOTE, Tag.mnemonic is unfortunately not supported
+    # because terminal key sending is a mess.
+    # In some terminals (gnome-terminal, terminator), alt+f sends ctrl+right
+    # (yeah, alt+f should go word forward, but this is awfaul)
+    # and hitting alt will trigger an escape sequence while escape is mapped to exit the app.
+    # I failed setting a timeout to work around this. Not taking account the different Win behaviour.
+    # This should really be handled by a lower level, ex. prompt_toolkit seem to have better handling than textual.
+    # def on_key(self, event: events.Key) -> None:
+    #     return
+    #     if event.key == "alt+" + self.tag._mnemonic:
+    #         self.focus()
+    #         event.stop()
+
 
 class TagWidgetWithInput(TagWidget):
     """Base class for widgets that contain an input element"""

mininterface/settings.py

@@ -58,17 +58,65 @@ class TextualSettings(TuiSettings):
 
 @dataclass
 class TextSettings(TuiSettings):
-    ...
+    mnemonic_over_number: Optional[bool] = None
+    """ Even when mnemonic can be determined, use rather number as a shortcut.
+
+    By default if `None`, determine those with `Tag(mnemonic=char|True)`:
+
+    ```bash
+    >     ok
+    [1] foo1: ×
+    [2] foo2: ×
+    [g] foo3: ×
+    ```
+
+    If `True`, determine also those having `Tag(mnemonic=None)`:
+
+    ```bash
+    >     ok
+    [f] foo1: ×
+    [o] foo2: ×
+    [g] foo3: ×
+    ```
+
+    If `False`, we prefer numbers:
+
+    ```bash
+    >     ok
+    [1] foo1: ×
+    [2] foo2: ×
+    [3] foo3: ×
+    ```
+
+    The original code:
+
+    ```python
+    from dataclasses import dataclass
+    from typing import Annotated
+    from mininterface import Tag, run
+    from mininterface.settings import MininterfaceSettings, TextSettings
+
+
+    @dataclass
+    class Env:
+        foo1: bool = False
+        foo2: bool = False
+        foo3: Annotated[bool, Tag(mnemonic="g")] = False
+
+
+    m = run(Env, settings=MininterfaceSettings(text=TextSettings(mnemonic_over_number=True)))
+    m.form()
+    quit()
+    ```
+    """
 
 
 @dataclass
 class WebSettings(TextualSettings):
+    # This is ready and working and waiting for the demand.
     ...
 
 
-# NOTE elaborate in the docs when more examples exist
-# TuiSettings works as a default for TextSettings and TextualSettings
-
 @dataclass
 class MininterfaceSettings:
     ui: UiSettings = field(default_factory=UiSettings)