mud_server.admin_tui.keybindings
================================

.. py:module:: mud_server.admin_tui.keybindings

.. autoapi-nested-parse::

   User-configurable keybindings for the Admin TUI.

   This module defines a small configuration layer for Textual keybindings so
   users can customize navigation without editing source code. It supports:
   - A default keybinding set (Tab, hjkl, Space select, etc.)
   - Optional JSON overrides via a config file
   - Safe fallback to defaults if the file is missing or invalid

   Design Goals:
   - Keep the format simple (JSON)
   - Merge overrides on top of defaults
   - Validate and normalize key strings
   - Avoid crashing the TUI if config is malformed



Attributes
----------

.. autoapisummary::

   mud_server.admin_tui.keybindings.logger
   mud_server.admin_tui.keybindings.DEFAULT_KEYBINDINGS
   mud_server.admin_tui.keybindings.ENV_KEYBINDINGS_PATH
   mud_server.admin_tui.keybindings.DEFAULT_KEYBINDINGS_PATH


Classes
-------

.. autoapisummary::

   mud_server.admin_tui.keybindings.KeyBindings


Module Contents
---------------

.. py:data:: logger

.. py:data:: DEFAULT_KEYBINDINGS
   :type:  dict[str, list[str]]

.. py:data:: ENV_KEYBINDINGS_PATH
   :value: 'MUD_TUI_KEYBINDINGS_PATH'


.. py:data:: DEFAULT_KEYBINDINGS_PATH

.. py:class:: KeyBindings

   Immutable keybindings container.

   .. attribute:: bindings

      Mapping of action -> list of keys (Textual key syntax).


   .. py:attribute:: bindings
      :type:  dict[str, list[str]]


   .. py:method:: get_keys(action)

      Return the list of keys for an action, defaulting to empty list.



   .. py:method:: load(path = None)
      :classmethod:


      Load keybindings from JSON, merged with defaults.

      Priority:
          1. Explicit path argument (if provided)
          2. ENV_KEYBINDINGS_PATH
          3. DEFAULT_KEYBINDINGS_PATH

      The JSON file can be either:
          { "bindings": { "next_tab": ["tab"] } }
      or:
          { "next_tab": ["tab"] }

      Invalid or missing files fall back to defaults.