feat(pickers): fully customizable layout (#2572)

doc/telescope.txt

@@ -146,6 +146,13 @@ telescope.setup({opts})                                    *telescope.setup()*
 
         Default: 'horizontal'
 
+                                         *telescope.defaults.create_layout*
+    create_layout: ~
+        Configure the layout of Telescope pickers.
+        See |telescope.pickers.layout| for details.
+
+        Default: 'nil'
+
                                          *telescope.defaults.layout_config*
     layout_config: ~
         Determines the default configuration values for layout strategies.
@@ -1947,6 +1954,155 @@ ordered from the lowest priority to the highest priority.
 <
 
 
+================================================================================
+LAYOUT                                                *telescope.pickers.layout*
+
+The telescope pickers layout can be configured using the
+|telescope.defaults.create_layout| option.
+
+Parameters: ~
+  - picker : A Picker object.
+
+Return: ~
+  - layout : instance of `TelescopeLayout` class.
+
+Example: ~
+>
+local Layout = require "telescope.pickers.layout"
+
+require("telescope").setup {
+  create_layout = function(picker)
+    local function create_window(enter, width, height, row, col, title)
+      local bufnr = vim.api.nvim_create_buf(false, true)
+      local winid = vim.api.nvim_open_win(bufnr, enter, {
+        style = "minimal",
+        relative = "editor",
+        width = width,
+        height = height,
+        row = row,
+        col = col,
+        border = "single",
+        title = title,
+      })
+
+      vim.wo[winid].winhighlight = "Normal:Normal"
+
+      return Layout.Window {
+        bufnr = bufnr,
+        winid = winid,
+      }
+    end
+
+    local function destory_window(window)
+      if window then
+        if vim.api.nvim_win_is_valid(window.winid) then
+          vim.api.nvim_win_close(window.winid, true)
+        end
+        if vim.api.nvim_buf_is_valid(window.bufnr) then
+          vim.api.nvim_buf_delete(window.bufnr, { force = true })
+        end
+      end
+    end
+
+    local layout = Layout {
+      picker = picker,
+      mount = function(self)
+        self.results = create_window(false, 40, 20, 0, 0, "Results")
+        self.preview = create_window(false, 40, 23, 0, 42, "Preview")
+        self.prompt = create_window(true, 40, 1, 22, 0, "Prompt")
+      end,
+      unmount = function(self)
+        destory_window(self.results)
+        destory_window(self.preview)
+        destory_window(self.prompt)
+      end,
+      update = function(self) end,
+    }
+
+    return layout
+  end,
+}
+<
+
+TelescopeWindowBorder.config                    *TelescopeWindowBorder.config*
+
+
+    Fields: ~
+        {bufnr}        (integer)
+        {winid}        (integer|nil)
+        {change_title} (nil|function)  (self: TelescopeWindowBorder, title:
+                                       string, pos?:
+                                       "NW"|"N"|"NE"|"SW"|"S"|"SE"):nil
+
+
+TelescopeWindowBorder                                  *TelescopeWindowBorder*
+
+
+    Fields: ~
+        {bufnr} (integer|nil)
+        {winid} (integer|nil)
+
+
+TelescopeWindow.config                                *TelescopeWindow.config*
+
+
+    Fields: ~
+        {bufnr}  (integer)
+        {winid}  (integer|nil)
+        {border} (TelescopeWindowBorder.config|nil)
+
+
+TelescopeWindow                                              *TelescopeWindow*
+
+
+    Fields: ~
+        {border} (TelescopeWindowBorder)
+        {bufnr}  (integer)
+        {winid}  (integer)
+
+
+TelescopeLayout.config                                *TelescopeLayout.config*
+
+
+    Fields: ~
+        {mount}   (function)             (self: TelescopeLayout):nil
+        {unmount} (function)             (self: TelescopeLayout):nil
+        {update}  (function)             (self: TelescopeLayout):nil
+        {prompt}  (TelescopeWindow|nil)
+        {results} (TelescopeWindow|nil)
+        {preview} (TelescopeWindow|nil)
+
+
+TelescopeLayout                                              *TelescopeLayout*
+
+
+    Fields: ~
+        {prompt}  (TelescopeWindow)
+        {results} (TelescopeWindow)
+        {preview} (TelescopeWindow|nil)
+
+
+Layout:mount()                              *telescope.pickers.layout:mount()*
+    Create the layout. This needs to ensure the required properties are
+    populated.
+
+
+
+Layout:unmount()                          *telescope.pickers.layout:unmount()*
+    Destroy the layout. This is responsible for performing clean-up, for
+    example:
+     - deleting buffers
+     - closing windows
+     - clearing autocmds
+
+
+
+Layout:update()                            *telescope.pickers.layout:update()*
+    Refresh the layout. This is called when, for example, vim is resized.
+
+
+
+
 ================================================================================
 LAYOUT                                                        *telescope.layout*