feat: Consistent and sensible layout_config (#922)

* feat: Consistent and sensible layout_config

* [docgen] Update doc/telescope.txt
skip-checks: true

* [WIP]: Thu 17 Jun 2021 03:36:44 PM EDT

* [WIP]: Thu 17 Jun 2021 03:38:11 PM EDT

* layout_default -> layout_defaults

* remove options from bug repot

* Conni2461 suggestions: part 1

* [docgen] Update doc/telescope.txt
skip-checks: true

* Conni2461 suggestions: part 2

* [docgen] Update doc/telescope.txt
skip-checks: true

* Linting

* Improve deprecation checks

- Move `layout_defaults` handling to `deprecated.lua`
- Check for "layout keys" outside of `layout_config` on `setup`

* fixup: Just add a few more words

Co-authored-by: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com>
Co-authored-by: Github Actions <actions@github>

2 files changed, 348 insertions, 81 deletions

diff --git a/doc/telescope.txt b/doc/telescope.txt
index ebb0e04..d2ed4ec 100644
--- a/doc/telescope.txt
+++ b/doc/telescope.txt
@@ -19,13 +19,27 @@ telescope.setup({opts})                                    *telescope.setup()*
 
     Valid keys for {opts.defaults}
 
+                                                *telescope.defaults.border*
+    border: ~
+        Boolean defining if borders are added to Telescope windows.
+
+        Default: true
+
+                                      *telescope.defaults.default_mappings*
+    default_mappings: ~
+        Not recommended to use except for advanced users.
+
+        Will allow you to completely remove all of telescope's default maps
+        and use your own.
+
+
                                  *telescope.defaults.dynamic_preview_title*
     dynamic_preview_title: ~
-          Will change the title of the preview window dynamically, where it
-          is supported. Means the preview window will for example show the
-          full filename.
+        Will change the title of the preview window dynamically, where it
+        is supported. Means the preview window will for example show the
+        full filename.
 
-          Default: false
+        Default: false
 
 
                                           *telescope.defaults.entry_prefix*
@@ -34,6 +48,94 @@ telescope.setup({opts})                                    *telescope.setup()*
 
         Default: '  '
 
+                                         *telescope.defaults.layout_config*
+    layout_config: ~
+        Determines the default configuration values for layout strategies.
+        See |telescope.layout| for details of the configurations options for
+        each strategy.
+
+        Allows setting defaults for all strategies as top level options and
+        for overriding for specific options.
+        For example, the default values below set the default width to 80% of
+        the screen width for all strategies except 'center', which has width
+        of 50% of the screen width.
+
+        Default: {
+          center = {
+            preview_cutoff = 40
+          },
+          height = 0.9,
+          horizontal = {
+            preview_cutoff = 120,
+            prompt_position = "bottom"
+          },
+          vertical = {
+            preview_cutoff = 40
+          },
+          width = 0.8
+        }
+
+
+                                       *telescope.defaults.layout_strategy*
+    layout_strategy: ~
+        Determines the default layout of Telescope pickers.
+        See |telescope.layout| for details of the available strategies.
+
+        Default: 'horizontal'
+
+                                              *telescope.defaults.mappings*
+    mappings: ~
+        Your mappings to override telescope's default mappings.
+
+        Format is:
+        {
+          mode = { ..keys }
+        }
+
+        where {mode} is the one character letter for a mode
+        ('i' for insert, 'n' for normal).
+
+        For example:
+
+        mappings = {
+          i = {
+            ["<esc>"] = require('telescope.actions').close,
+          },
+        }
+
+
+        To disable a keymap, put [map] = false
+          So, to not map "<C-n>", just put
+
+            ...,
+            ["<C-n>"] = false,
+            ...,
+
+          Into your config.
+
+
+        otherwise, just set the mapping to the function that you want it to be.
+
+            ...,
+            ["<C-i>"] = require('telescope.actions').select_default,
+            ...,
+
+        If the function you want is part of `telescope.actions`, then you can simply give a string.
+          For example, the previous option is equivalent to:
+
+            ...,
+            ["<C-i>"] = "select_default",
+            ...,
+
+        You can also add other mappings using tables with `type = "command"`.
+          For example:
+
+            ...,
+            ["jj"] = { "<esc>", type = "command" },
+            ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
+            ...,
+
+
                                          *telescope.defaults.prompt_prefix*
     prompt_prefix: ~
         Will be shown in front of the prompt.
@@ -478,7 +580,7 @@ require("telescope").setup {
       mappings = {
         i = {
           ["<c-d>"] = require("telescope.actions").delete_buffer,
-          -- or right hand side can also be a the name of the action as string
+          -- or right hand side can also be the name of the action as string
           ["<c-d>"] = "delete_buffer",
         },
         n = {
@@ -1119,6 +1221,52 @@ action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker(
 
 
 ================================================================================
+                                                             *telescope.resolve*
+
+Provides "resolver functions" to allow more customisable inputs for options.
+
+resolver.resolve_height()                          *resolver.resolve_height()*
+    Converts input to a function that returns the height. The input must take
+    one of four forms:
+    1. 0 <= number < 1
+       This means total height as a percentage.
+    2. 1 <= number
+       This means total height as a fixed number.
+    3. function
+       Must have signature: function(self, max_columns, max_lines): number
+    4. table of the form: {padding = `foo`}
+       where `foo` has one of the previous three forms.
+       The height is then set to be the remaining space after padding. For
+       example, if the window has height 50, and the input is {padding = 5}, 
+       the height returned will be `40 = 50 - 2*5`
+
+    The returned function will have signature: function(self, max_columns,
+    max_lines): number
+
+
+
+resolver.resolve_width()                            *resolver.resolve_width()*
+    Converts input to a function that returns the width. The input must take
+    one of four forms:
+    1. 0 <= number < 1
+       This means total width as a percentage.
+    2. 1 <= number
+       This means total width as a fixed number.
+    3. function
+       Must have signature: function(self, max_columns, max_lines): number
+    4. table of the form: {padding = `foo`}
+       where `foo` has one of the previous three forms.
+       The width is then set to be the remaining space after padding. For
+       example, if the window has width 100, and the input is {padding = 5}, 
+       the width returned will be `90 = 100 - 2*5`
+
+    The returned function will have signature: function(self, max_columns,
+    max_lines): number
+
+
+
+
+================================================================================
                                                           *telescope.previewers*
 
 Provides a Previewer table that has to be implemented by each previewer. To
@@ -1450,7 +1598,7 @@ Layout strategies are different functions to position telescope.
 
 All layout strategies are functions with the following signature:
 
-  function(picker, columns, lines)
+  function(picker, columns, lines, layout_config)
     -- Do some calculations here...
     return {
       preview = preview_configuration
@@ -1460,99 +1608,167 @@ All layout strategies are functions with the following signature:
   end
 
   Parameters: ~
-    - picker  : A Picker object. (docs coming soon)
-    - columns : number Columns in the vim window
-    - lines   : number Lines in the vim window
+    - picker        : A Picker object. (docs coming soon)
+    - columns       : (number) Columns in the vim window
+    - lines         : (number) Lines in the vim window
+    - layout_config : (table) The configuration values specific to the picker.
 
 
-TODO: I would like to make these link to `telescope.layout_strategies.*`, but
-it's not yet possible.
+This means you can create your own layout strategy if you want! Just be aware
+for now that we may change some APIs or interfaces, so they may break if you
+create your own.
 
-Available layout strategies include:
-  - horizontal:
-    - See |layout_strategies.horizontal|
+A good method for creating your own would be to copy one of the strategies that
+most resembles what you want from
+"./lua/telescope/pickers/layout_strategies.lua" in the telescope repo.
 
-  - vertical:
-    - See |layout_strategies.vertical|
-
-  - 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
-
-  - scroll_speed:
-    - Change the scrolling speed of the previewer
 
 layout_strategies.horizontal()                *layout_strategies.horizontal()*
-    Horizontal previewer
-
-      +-------------+--------------+
-      |             |              |
-      |   Results   |              |
-      |             |    Preview   |
-      |             |              |
-      +-------------|              |
-      |   Prompt    |              |
-      +-------------+--------------+
-
+    Horizontal layout has two columns, one for the preview and one for the
+    prompt and results.
+
+    ┌──────────────────────────────────────────────────┐
+    │                                                  │
+    │    ┌───────────────────┐┌───────────────────┐    │
+    │    │                   ││                   │    │
+    │    │                   ││                   │    │
+    │    │                   ││                   │    │
+    │    │      Results      ││                   │    │
+    │    │                   ││      Preview      │    │
+    │    │                   ││                   │    │
+    │    │                   ││                   │    │
+    │    └───────────────────┘│                   │    │
+    │    ┌───────────────────┐│                   │    │
+    │    │      Prompt       ││                   │    │
+    │    └───────────────────┘└───────────────────┘    │
+    │                                                  │
+    └──────────────────────────────────────────────────┘
+
+    `picker.layout_config` shared options:
+      - height:
+        - How tall to make Telescope's entire layout
+        - See |resolver.resolve_height()|
+      - mirror: Flip the location of the results/prompt and preview windows
+      - scroll_speed: The number of lines to scroll through the previewer
+      - width:
+        - How wide to make Telescope's entire layout
+        - See |resolver.resolve_width()|
+
+    `picker.layout_config` unique options:
+      - preview_cutoff: When columns are less than this value, the preview will be disabled
+      - preview_width:
+        - Change the width of Telescope's preview window
+        - See |resolver.resolve_width()|
+      - prompt_position:
+        - Where to place prompt window.
+        - Available Values: 'bottom', 'top'
 
 
 layout_strategies.center()                        *layout_strategies.center()*
-    Centered layout wih smaller default sizes (I think)
+    Centered layout with a combined block of the prompt and results aligned to
+    the middle of the screen. The preview window is then placed in the
+    remaining space above. Particularly useful for creating dropdown menus (see
+    |telescope.themes| and |themes.get_dropdown()|`).
+
+    ┌──────────────────────────────────────────────────┐
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Preview                |    │
+    │    |                 Preview                |    │
+    │    └────────────────────────────────────────┘    │
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Prompt                 |    │
+    │    ├────────────────────────────────────────┤    │
+    │    |                 Result                 |    │
+    │    |                 Result                 |    │
+    │    └────────────────────────────────────────┘    │
+    │                                                  │
+    │                                                  │
+    │                                                  │
+    │                                                  │
+    └──────────────────────────────────────────────────┘
+
+    `picker.layout_config` shared options:
+      - height:
+        - How tall to make Telescope's entire layout
+        - See |resolver.resolve_height()|
+      - mirror: Flip the location of the results/prompt and preview windows
+      - scroll_speed: The number of lines to scroll through the previewer
+      - width:
+        - How wide to make Telescope's entire layout
+        - See |resolver.resolve_width()|
+
+    `picker.layout_config` unique options:
+      - preview_cutoff: When lines are less than this value, the preview will be disabled
 
-       +--------------+
-       |    Preview   |
-       +--------------+
-       |    Prompt    |
-       +--------------+
-       |    Result    |
-       |    Result    |
-       |    Result    |
-       +--------------+
 
+layout_strategies.vertical()                    *layout_strategies.vertical()*
+    Vertical layout stacks the items on top of each other. Particularly useful
+    with thinner windows.
+
+    ┌──────────────────────────────────────────────────┐
+    │                                                  │
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Preview                |    │
+    │    |                 Preview                |    │
+    │    |                 Preview                |    │
+    │    └────────────────────────────────────────┘    │
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Result                 |    │
+    │    |                 Result                 |    │
+    │    └────────────────────────────────────────┘    │
+    │    ┌────────────────────────────────────────┐    │
+    │    |                 Prompt                 |    │
+    │    └────────────────────────────────────────┘    │
+    │                                                  │
+    └──────────────────────────────────────────────────┘
+
+    `picker.layout_config` shared options:
+      - height:
+        - How tall to make Telescope's entire layout
+        - See |resolver.resolve_height()|
+      - mirror: Flip the location of the results/prompt and preview windows
+      - scroll_speed: The number of lines to scroll through the previewer
+      - width:
+        - How wide to make Telescope's entire layout
+        - See |resolver.resolve_width()|
+
+    `picker.layout_config` unique options:
+      - preview_cutoff: When lines are less than this value, the preview will be disabled
+      - preview_height:
+        - Change the height of Telescope's preview window
+        - See |resolver.resolve_height()|
+      - prompt_position:
+        - (unimplemented, but we plan on supporting)
 
 
-layout_strategies.vertical()                    *layout_strategies.vertical()*
-    Vertical perviewer stacks the items on top of each other.
+layout_strategies.flex()                            *layout_strategies.flex()*
+    Flex layout swaps between `horizontal` and `vertical` strategies based on
+    the window width
+     - Supports |layout_strategies.vertical| or |layout_strategies.horizontal|
+       features
 
-       +-----------------+
-       |    Previewer    |
-       |    Previewer    |
-       |    Previewer    |
-       +-----------------+
-       |     Result      |
-       |     Result      |
-       |     Result      |
-       +-----------------+
-       |     Prompt      |
-       +-----------------+
 
+    `picker.layout_config` shared options:
+      - height:
+        - How tall to make Telescope's entire layout
+        - See |resolver.resolve_height()|
+      - mirror: Flip the location of the results/prompt and preview windows
+      - scroll_speed: The number of lines to scroll through the previewer
+      - width:
+        - How wide to make Telescope's entire layout
+        - See |resolver.resolve_width()|
 
+    `picker.layout_config` unique options:
+      - flip_columns: The number of columns required to move to horizontal mode
+      - flip_lines: The number of lines required to move to horizontal mode
+      - horizontal: Options to pass when switching to horizontal layout
+      - vertical: Options to pass when switching to vertical layout
 
-layout_strategies.flex()                            *layout_strategies.flex()*
-    Swap between `horizontal` and `vertical` strategies based on the window
-    width
-     - Supports `vertical` or `horizontal` features
 
-    Uses:
-     - flip_columns
-     - flip_lines
+layout_strategies.bottom_pane()              *layout_strategies.bottom_pane()*
+    Bottom pane can be used to create layouts similar to "ivy".
+
+    For an easy ivy configuration, see |themes.get_ivy()|
 
 
 
diff --git a/doc/telescope_changelog.txt b/doc/telescope_changelog.txt
new file mode 100644
index 0000000..5b255f7
--- /dev/null
+++ b/doc/telescope_changelog.txt
@@ -0,0 +1,51 @@
+================================================================================
+                                                         *telescope.changelog*
+
+# Changelog
+
+                                                     *telescope.changelog-922*
+
+Date: May 17, 2021
+PR: https://github.com/nvim-telescope/telescope.nvim/pull/922
+
+This is one of our largest breaking changes thus far, so I (TJ) am adding some
+information here so that you can more easily update (without having to track
+down the commit, etc.).
+
+The goal of these breaking changes is to greatly simplify the way
+configuration for layouts happen. This should make it much easier to configure
+each picker, layout_strategy, and more. Please report any bugs or behavior
+that is broken / confusing upstream and we can try and make the configuration
+better.
+
+|telescope.setup()| has changed `layout_defaults` -> `layout_config`.
+    This makes it so that the setup and the pickers share the same key,
+    otherwise it is too confusing which key is for which.
+
+
+`picker:find()` now has different values available for configuring the UI.
+    All configuration for the layout must be passed in the key:
+        `layout_config`.
+
+    Previously, these keys were passed via `picker:find(opts)`, but should be
+    passed via `opts.layout_config` now.
+        - {height}
+        - {width}
+        - {prompt_position}
+        - {preview_cutoff}
+
+    These keys are removed:
+        - {results_height}: This key is no longer valid. Instead, use `height`
+          and the corresponding `preview_*` options for the layout strategy to
+          get the correct results height. This simplifies the configuration
+          for many of the existing strategies.
+
+        - {results_width}: This key actually never did anything. It was
+          leftover from some hacking that I had attempted before. Instead you
+          should be using something like the `preview_width` configuration
+          option for |layout_strategies.horizontal()|
+
+    You should get error messages when you try and use any of the above keys now.
+
+
+ vim:tw=78:ts=8:ft=help:norl: