feat: layout horizontal and vertical can now be mirrored (#548)

See documentation for more info

3 files changed, 74 insertions, 12 deletions

diff --git a/README.md b/README.md
index ebc93aa..9ebcfaf 100644
--- a/README.md
+++ b/README.md
@@ -147,7 +147,12 @@ require('telescope').setup{
     sorting_strategy = "descending",
     layout_strategy = "horizontal",
     layout_defaults = {
-      -- TODO add builtin options.
+      horizontal = {
+        mirror = false,
+      },
+      vertical = {
+        mirror = false,
+      },
     },
     file_sorter =  require'telescope.sorters'.get_fuzzy_file,
     file_ignore_patterns = {},
@@ -199,7 +204,7 @@ EOF
 | `sorting_strategy`     | Where first selection should be located.              | descending/ascending       |
 | `layout_strategy`      | How the telescope is drawn.                           | [supported layouts](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts) |
 | `winblend`             | How transparent is the telescope window should be.    | NUM                        |
-| `layout_defaults`      | Layout specific configuration ........ TODO           | TODO                       |
+| `layout_defaults`      | Extra settings for fine-tuning how your layout looks  | [supported settings](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts#layout-defaults) |
 | `width`                | TODO                                                  | NUM                        |
 | `preview_cutoff`       | TODO                                                  | NUM                        |
 | `results_height`       | TODO                                                  | NUM                        |
diff --git a/doc/telescope.txt b/doc/telescope.txt
index c9a999c..bdd5f8f 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -236,7 +236,8 @@ All layout strategies are functions with the following signature: >
         - columns : number Columns in the vim window
         - lines   : number Lines in the vim window
 
-TODO: I would like to make these link to `telescope.layout_strategies.*`, but it's not yet possible.
+TODO: I would like to make these link to `telescope.layout_strategies.*`,
+but it's not yet possible.
 
 Available layout strategies include:
   horizontal:
@@ -248,6 +249,24 @@ Available layout strategies include:
   flex:
   - See |layout_strategies.flex|
 
+Available tweaks to the settings in layout defaults include
+(can be applied to horizontal and vertical layouts):
+  mirror (default is `false`):
+  - Flip the view of the current layout:
+    - If using horizontal: if `true`, swaps the location of the
+      results/prompt window and preview window
+    - If using vertical: if `true`, swaps the location of the results and
+      prompt windows
+
+  width_padding:
+  - How many cells to pad the width of Telescope's layout window
+
+  height_padding:
+  - How many cells to pad the height of Telescope's layout window
+
+  preview_width:
+  - Change the width of Telescope's preview window
+
 
 layout_strategies.center()                        *layout_strategies.center()*
 
diff --git a/lua/telescope/pickers/layout_strategies.lua b/lua/telescope/pickers/layout_strategies.lua
index 382d9a6..16919de 100644
--- a/lua/telescope/pickers/layout_strategies.lua
+++ b/lua/telescope/pickers/layout_strategies.lua
@@ -21,7 +21,8 @@
 ---         - columns : number Columns in the vim window
 ---         - lines   : number Lines in the vim window
 ---
---- TODO: I would like to make these link to `telescope.layout_strategies.*`, but it's not yet possible.
+--- TODO: I would like to make these link to `telescope.layout_strategies.*`,
+--- but it's not yet possible.
 ---
 --- Available layout strategies include:
 ---   horizontal:
@@ -33,6 +34,24 @@
 ---   flex:
 ---   - See |layout_strategies.flex|
 ---
+--- Available tweaks to the settings in layout defaults include
+--- (can be applied to horizontal and vertical layouts):
+---   mirror (default is `false`):
+---   - Flip the view of the current layout:
+---     - If using horizontal: if `true`, swaps the location of the
+---       results/prompt window and preview window
+---     - If using vertical: if `true`, swaps the location of the results and
+---       prompt windows
+---
+---   width_padding:
+---   - How many cells to pad the width of Telescope's layout window
+---
+---   height_padding:
+---   - How many cells to pad the height of Telescope's layout window
+---
+---   preview_width:
+---   - Change the width of Telescope's preview window
+---
 ---@brief ]]
 
 local config = require('telescope.config')
@@ -76,6 +95,7 @@ layout_strategies.horizontal = function(self, max_columns, max_lines)
     width_padding = "How many cells to pad the width",
     height_padding = "How many cells to pad the height",
     preview_width = "(Resolvable): Determine preview width",
+    mirror = "Flip the location of the results/prompt and preview windows",
   })
 
   local initial_options = self:_get_initial_window_options()
@@ -133,9 +153,16 @@ layout_strategies.horizontal = function(self, max_columns, max_lines)
     preview.height = 0
   end
 
-  results.col = width_padding
-  prompt.col = width_padding
-  preview.col = results.col + results.width + 2
+  -- Default value is false, to use the normal horizontal layout
+  if not layout_config.mirror then
+    results.col = width_padding
+    prompt.col = width_padding
+    preview.col = results.col + results.width + 2
+  else
+    preview.col = width_padding
+    prompt.col = preview.col + preview.width + 2
+    results.col = preview.col + preview.width + 2
+  end
 
   preview.line = height_padding
   if self.window.prompt_position == "top" then
@@ -229,9 +256,14 @@ end
 ---    +-----------------+
 ---
 layout_strategies.vertical = function(self, max_columns, max_lines)
-  local layout_config = self.layout_config or {}
-  local initial_options = self:_get_initial_window_options()
+  local layout_config = validate_layout_config(self.layout_config or {}, {
+    width_padding = "How many cells to pad the width",
+    height_padding = "How many cells to pad the height",
+    preview_height = "(Resolvable): Determine preview height",
+    mirror = "Flip the locations of the results and prompt windows",
+  })
 
+  local initial_options = self:_get_initial_window_options()
   local preview = initial_options.preview
   local results = initial_options.results
   local prompt = initial_options.prompt
@@ -272,9 +304,15 @@ layout_strategies.vertical = function(self, max_columns, max_lines)
   results.col, preview.col, prompt.col = width_padding, width_padding, width_padding
 
   if self.previewer then
-    preview.line = height_padding
-    results.line = preview.line + preview.height + 2
-    prompt.line = results.line + results.height + 2
+    if not layout_config.mirror then
+      preview.line = height_padding
+      results.line = preview.line + preview.height + 2
+      prompt.line = results.line + results.height + 2
+    else
+      prompt.line = height_padding
+      results.line = prompt.line + prompt.height + 2
+      preview.line = results.line + results.height + 2
+    end
   else
     results.line = height_padding
     prompt.line = results.line + results.height + 2