*artio.txt*	a minimal, nature-infused file picker for neovim using ui2

==============================================================================

FEATURES                                                      *artio-features*

Requires Neovim `>= 0.12`

- Lightweight picker window built on Neovim's ui2
- Prompt + list UI components - minimal and focused
- Fuzzy filtering using matchfuzzy (built-in)
- Optional icon support for common filetypes through mini.icons
  (https://github.com/echasnovski/mini.nvim)
- No heavy dependencies - pure Lua

UI2

artio requires ui2 to be enabled.

an example of how to set this up is:

>lua
  require("vim._core.ui2").enable({ enable = true, msg = {
    target = "msg",
  } })
<

INSTALLATION

`vim.pack`

>lua
  vim.pack.add({{ src = "https://github.com/comfysage/artio.nvim" }})
<

`lazy.nvim`

>lua
  {
    "comfysage/artio.nvim", lazy = false,
  }
<

==============================================================================

CONFIGURATION                                                   *artio-config*

Options ~

options that change default behavior of the picker.

>lua
  {
    opts = {
      preselect = true, -- whether to preselect the first match
      bottom = true, -- whether to draw the prompt at the bottom
      shrink = true, -- whether the window should shrink to fit the matches
      promptprefix = "", -- prefix for the prompt
      prompt_title = true, -- whether to draw the prompt title
      pointer = "", -- pointer for the selected match
      marker = "│", -- prefix for marked items
      infolist = { "list" }, -- index: [1] list: (4/5)
      use_icons = true, -- requires mini.icons
    },
  }
<

Window Options ~

some less used options for the picker window and its render logic.

>lua
  {
    win = {
      height = 12,
      hidestatusline = false, -- works best with laststatus=3
    },
  }
<

Mappings ~

these override the default mappings for any picker.
these map keys to actions. its allowed to use multiple keys for the same
action.

NOTE: if you override the mappings, make sure to provide keys for all actions

>lua
  {
    mappings = {
      ["<down>"] = "down",
      ["<up>"] = "up",
      ["<cr>"] = "accept",
      ["<esc>"] = "cancel",
      ["<tab>"] = "mark",
      ["<c-l>"] = "togglepreview",
      ["<c-q>"] = "setqflist",
      ["<m-q>"] = "setqflistmark",
    },
  }
<

Setup ~

after setting up artio with your options there are some additional things to
setup.

Keymaps for artio are set using the |<Plug>| interface. These bindings are set
by the api and can be rebound by the user to specific keybindings.

By default there are <Plug> bindings for all builtins. |artio-builtins|

Example ~

>lua
  require('artio').setup({})

  -- override built-in ui select with artio
  vim.ui.select = require("artio").select

  vim.keymap.set("n", "<leader><leader>", "<Plug>(artio-files)")
  vim.keymap.set("n", "<leader>fg", "<Plug>(artio-grep)")

  -- smart file picker
  vim.keymap.set("n", "<leader>ff", "<Plug>(artio-smart)")

  -- general built-in pickers
  vim.keymap.set("n", "<leader>fh", "<Plug>(artio-helptags)")
  vim.keymap.set("n", "<leader>fb", "<Plug>(artio-buffers)")
  vim.keymap.set("n", "<leader>f/", "<Plug>(artio-buffergrep)")
  vim.keymap.set("n", "<leader>fo", "<Plug>(artio-oldfiles)")
<

==============================================================================

API                                                                *artio-api*

artio.pick({opts})                                              *artio.pick()*

  create a new picker |artio.Picker| and start it.

  >lua
    artio.pick({
      items = { 'a', 'b', 'c' },
      fn = artio.sorter,
    })
  <

artio.generic({items}, {props})                              *artio.generic()*

  creates a generic picker from the given items and props.
  uses the default |artio.sorter| function.

                                                              *artio.select()*
artio.select({items}, {opts}, {on_choice}, {start_opts?})

  the |vim.ui.select| interface implemented for artio.
  adds an optional `{start_opts?}` argument that accepts artio specific
  options.

artio.resume()                                                *artio.resume()*

  resume the last closed picker. does not work across neovim
  restarts/sessions.

  Plug: `<Plug>(artio-resume)`.

API-PICKER                                                  *artio-api-picker*

*artio.Picker*
  a picker is a special table that holds the state of the picker.
  the current active picker is stored in
  `require('artio.picker').active_picker`.

  Fields: ~
    - {items}           (`artio.Picker.item[]|string[]`)
                        array of |artio.Picker.item| or strings. an array of
                        strings will be converted to items.
    - {fn}              (`artio.Picker.sorter`)
                        an instance of |artio.Picker.sorter|.
    - {on_close}        (`fun(text: string, idx: integer)`)
                        callback function for when the picker closes (after
                        accepting a match). gets the `item.text` field as the
                        first argument and the item id as the second.
    - {get_items}?      (`fun(input: string): artio.Picker.item[]`)
    - {format_item}?    (`fun(item: any): string`)
    - {preview_item}?   (`fun(item: any): {buf?:integer, pos?:[integer,integer], pos_end?:[integer,integer]}`)
    - {get_icon}?       (`fun(item: artio.Picker.item): string, string`)
    - {hl_item}?        (`fun(item: artio.Picker.item): artio.Picker.hl[]`)
    - {on_quit}?        (`fun()`)
                        callback function for when the picker closes before
                        choosing a match.
    - {prompt}?         (`string`)
                        text before prompt prefix. can be disabled with
                        `config.opts.prompt_title = false`.
    - {defaulttext}?    (`string`)
                        start input for picker.
    - {prompttext}?     (`string`)
                        defaults to prompt title combined with prompt prefix.
    - {opts}?           (`artio.config.opts`)
                        picker options combined with the user config.
    - {win}?            (`artio.config.win`)
                        picker window options combined with the user config.
    - {actions}?        (`table<string, artio.Picker.action>`)
                        picker specific actions.
    - {mappings}?       (`table<string, string>`)
                        mappings from the user config.

API-SORTER                                                  *artio-api-sorter*

*artio.Picker.sorter*
   a function that takes an array of |artio.Picker.item| and an input string
   and returns a table of matches |artio.Picker.matches|.

*artio.Picker.matches*
  a table where each key is the id of the item and each value is of
  |artio.Picker.match|.

*artio.Picker.match*

  Fields: ~
    - {1}       (`integer`)
                id of the item
    - {2}       (`any`)
                array of ' matching ' hls. these correspond to chars of the
                `item.text` field. this is based on the output of
                |matchfuzzypos|.
    - {3}       (`integer`)
                the score of the match.

*artio.Picker.item*

  Fields: ~
    - {id}      (`integer`)
    - {v}       (`any`)
    - {text}    (`string`)

artio.sorter({items}, {input})                                *artio.sorter()*

  the default sorter provides support for pattern matching. a `/.../` match at
  the start of the input will limit the fuzzy sorter to items matching the
  pattern. if you want to use `/.../` in your fuzzy matches, make sure to
  escape it by starting the input with an empty space (` /.../`). fuzzy
  sorting will be done on the input with the pattern removed.

API-BUILTINS

artio builtins are for general editor use. they are accessible through
`require('artio.builtins')`.

builtins.builtins()                                           *artio-builtins*

  list of all builtins.

  Plug: `<Plug>(artio-builtins)`.

builtins.files()                                                 *artio-files*

  list all files within the current directory.

  Plug: `<Plug>(artio-files)`.

builtins.grep()                                                   *artio-grep*

  grep in the current directory.
  runs `rg` if available; uses `grep` as a fallback.

  Plug: `<Plug>(artio-grep)`.

builtins.oldfiles()                                           *artio-oldfiles*

  list all files in |v:oldfiles|; recently accessed files in neovim. these are
  stored in |shada| memory.

  Plug: `<Plug>(artio-oldfiles)`.

builtins.buffergrep()                                       *artio-buffergrep*

  grep in the current buffer. uses the default sorter to match lines.

  Plug: `<Plug>(artio-buffergrep)`.

builtins.helptags()                                           *artio-helptags*

  list all help tags. behaves like |:help|.

  Plug: `<Plug>(artio-helptags)`.

builtins.buffers()                                             *artio-buffers*

  list all open buffers. behaves like |:buffers|.

  Plug: `<Plug>(artio-buffers)`.

builtins.smart()                                                 *artio-smart*

  uses the regular files picker as a base
  - boosts items in the bufferlist
  - proportionally boosts items that match closely to the current file in
    proximity within the filesystem

  Plug: `<Plug>(artio-smart)`.

builtins.colorschemes()                                   *artio-colorschemes*

  list all colorschemes by finding all `colors/*.{vim,lua}` files in the
  runtime.

  Plug: `<Plug>(artio-colorschemes)`.

builtins.highlights()                                       *artio-highlights*

  list all highlights. behaves like |:highlight|.

  Plug: `<Plug>(artio-highlights)`.

builtins.diagnostics({buffer})                             *artio-diagnostics*

  list all diagnostics. uses diagnostics from |vim.diagnostic.get()|.
  uses all diagnostics in the workspace if no buffer is specified.

  Plug: `<Plug>(artio-diagnostics)`.

builtins.diagnostics_buffer({buffer})               *artio-diagnostics-buffer*

  list all diagnostics for the given buffer. uses diagnostics from
  |vim.diagnostic.get()|. uses the current buffer if no buffer is specified.

  Plug: `<Plug>(artio-diagnostics-buffer)`.

builtins.keymaps()                                             *artio-keymaps*

  list all keymaps. uses formatted data from |nvim_get_keymap()|.

  Plug: `<Plug>(artio-keymaps)`.

builtins.commands()                                           *artio-commands*

  list all user commands. uses formatted data from |nvim_get_commands()|.

  Plug: `<Plug>(artio-commands)`.

builtins.quickfix()                                           *artio-quickfix*

  show current quickfix list. allows previewing items and updating the list.

  Plug: `<Plug>(artio-quickfix)`.

 vim:tw=78:ts=8:noet:ft=help:norl: