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>

lua/telescope/config/resolve.lua

@@ -1,3 +1,8 @@
+---@tag telescope.resolve
+
+---@brief [[
+--- Provides "resolver functions" to allow more customisable inputs for options.
+---@brief ]]
 
 --[[
 
@@ -40,7 +45,7 @@ height =
 
     3. function(picker, columns, lines)
         -> returns one of the above options
-        return max.min(110, max_rows * .5)
+        return math.min(110, max_rows * .5)
 
         if columns > 120 then
             return 110
@@ -88,46 +93,80 @@ That's the next step to scrolling.
 local get_default = require('telescope.utils').get_default
 
 local resolver = {}
+local _resolve_map = {}
 
-local _resolve_map = {
-  -- Booleans
-  [function(val) return val == false end] = function(selector, val)
-    return function(...)
-      return val
-    end
-  end,
-
-  -- Percentages
-  [function(val) return type(val) == 'number' and val >= 0 and val < 1 end] = function(selector, val)
-    return function(...)
-      local selected = select(selector, ...)
-      return math.floor(val * selected)
-    end
-  end,
-
-  -- Numbers
-  [function(val) return type(val) == 'number' and val >= 1 end] = function(selector, val)
-    return function(...)
-      local selected = select(selector, ...)
-      return math.min(val, selected)
-    end
-  end,
-
-
-  -- Tables TODO:
-  -- ... {70, max}
-
-
-  -- function:
-  --    Function must have same signature as get_window_layout
-  --        function(self, max_columns, max_lines): number
-  --
-  --    Resulting number is used for this configuration value.
-  [function(val) return type(val) == 'function' end] = function(selector, val)
+-- Booleans
+_resolve_map[function(val) return val == false end] = function(_, val)
+  return function(...)
     return val
-  end,
-}
+  end
+end
 
+-- Percentages
+_resolve_map[function(val) return type(val) == 'number' and val >= 0 and val < 1 end] = function(selector, val)
+  return function(...)
+    local selected = select(selector, ...)
+    return math.floor(val * selected)
+  end
+end
+
+-- Numbers
+_resolve_map[function(val) return type(val) == 'number' and val >= 1 end] = function(selector, val)
+  return function(...)
+    local selected = select(selector, ...)
+    return math.min(val, selected)
+  end
+end
+
+-- Tables TODO:
+-- ... {70, max}
+
+-- function:
+--    Function must have same signature as get_window_layout
+--        function(self, max_columns, max_lines): number
+--
+--    Resulting number is used for this configuration value.
+_resolve_map[function(val) return type(val) == 'function' end] = function(_, val)
+  return val
+end
+
+-- Add padding option
+_resolve_map[function(val) return type(val) == 'table' and val['padding'] ~= nil end] = function(selector, val)
+  local resolve_pad = function(value)
+    for k, v in pairs(_resolve_map) do
+      if k(value) then
+        return v(selector, value)
+      end
+    end
+
+    error('invalid configuration option for padding:' .. tostring(value))
+  end
+
+  return function(...)
+    local selected = select(selector, ...)
+    local padding = resolve_pad(val['padding'])
+    return math.floor(selected - 2 * padding(...))
+  end
+end
+
+
+--- Converts input to a function that returns the height.
+--- The input must take one of four forms:
+--- 1. 0 <= number < 1 <br>
+---     This means total height as a percentage.
+--- 2. 1 <= number <br>
+---     This means total height as a fixed number.
+--- 3. function <br>
+---     Must have signature:
+---       function(self, max_columns, max_lines): number
+--- 4. table of the form: {padding = `foo`} <br>
+---     where `foo` has one of the previous three forms. <br>
+---     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_height = function(val)
   for k, v in pairs(_resolve_map) do
     if k(val) then
@@ -138,6 +177,23 @@ resolver.resolve_height = function(val)
   error('invalid configuration option for height:' .. tostring(val))
 end
 
+--- Converts input to a function that returns the width.
+--- The input must take one of four forms:
+--- 1. 0 <= number < 1 <br>
+---     This means total width as a percentage.
+--- 2. 1 <= number <br>
+---     This means total width as a fixed number.
+--- 3. function <br>
+---     Must have signature:
+---       function(self, max_columns, max_lines): number
+--- 4. table of the form: {padding = `foo`} <br>
+---     where `foo` has one of the previous three forms. <br>
+---     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
 resolver.resolve_width = function(val)
   for k, v in pairs(_resolve_map) do
     if k(val) then
@@ -148,8 +204,8 @@ resolver.resolve_width = function(val)
   error('invalid configuration option for width:' .. tostring(val))
 end
 
---- Win option always returns a table with preview, results, and prompt.
---- It handles many different ways. Some examples are as follows:
+-- Win option always returns a table with preview, results, and prompt.
+-- It handles many different ways. Some examples are as follows:
 --
 -- -- Disable
 -- borderschars = false