feat(api): Add API to start finder from a specified root item group

doc/API.md

@@ -1,5 +1,34 @@
 # Lua API
 
+## Options for Finding Items
+
+The `require('legendary').find()` function also takes a table of options. The accepted options are:
+
+| Table Key | Type (see below for type definitions) | Description |
+| --------- | ---- | ----------- |
+| `itemgroup` | `string` | Find items only within the specified `ItemGroup` |
+| `filters`   | `LegendaryItemFilter[]` | Filter functions used to filter items |
+| `select_prompt` | `string` | Override the prompt title from your config for this instance |
+| `formatter` | `LegendaryItemFormatter` | Override the item formatter from your config for this instance |
+
+### Types
+
+```lua
+---@alias LegendaryItemFilter fun(item:LegendaryItem, context: LegendaryEditorContext):boolean
+
+---@alias LegendaryItemFormatter fun(items:LegendaryItem[],mode:string):string[]
+
+---@alias LegendaryItem Keymap|Command|Augroup|Autocmd|Function|ItemGroup
+
+---@class LegendaryEditorContext
+---@field buf integer
+---@field buftype string
+---@field filetype string
+---@field mode string
+---@field cursor_pos integer[] { row, col }
+---@field marks integer[]|nil
+```
+
 You can also manually bind new items after you've already called `require('legendary').setup()`.
 This can be useful for things like binding language-specific keyaps in the LSP `on_attach` function.
 
@@ -104,6 +133,16 @@ require('legendary').find({
 })
 ```
 
+## Find Items From a Specific Item Group
+
+To search `legendary.nvim` items only from a specific [item group](./table_structures/KEYMAPS.md#item-groups),
+you can pass the group's name via the `itemgroup` option:
+
+```lua
+-- find only LSP-related items
+require('legendary').find({ itemgroup = 'LSP' })
+```
+
 ## Repeat Last Item
 
 You can repeat the previous item selected from `legendary.nvim`'s finder. By default, it only executes the item

doc/FILTERS.md

@@ -1,6 +1,7 @@
 # Built-in Filters
 
-The `require('legendary.filters')` module provides the following filters
+A filter is just a function with the signature `fun(item): bool`, but the
+`require('legendary.filters')` module provides the following built-in filters
 for convenience:
 
 ```lua

doc/table_structures/COMMANDS.md

@@ -109,7 +109,7 @@ local commands = {
 }
 ```
 
-## Item groups
+## Item Groups
 
 You can also organize keymaps, commands, and functions into groups that will show up
 in the finder UI like a folder, selecting it will then trigger another finder for items

doc/table_structures/FUNCTIONS.md

@@ -39,7 +39,7 @@ You can also pass options via the `opts` property:
 - `buffer` option (a buffer handle, or `0` for current buffer), which will
   make the function visible only in the specified buffer.
 
-## Item groups
+## Item Groups
 
 You can also organize keymaps, commands, and functions into groups that will show up
 in the finder UI like a folder, selecting it will then trigger another finder for items

doc/table_structures/KEYMAPS.md

@@ -167,7 +167,7 @@ local keymaps = {
 }
 ```
 
-## Item groups
+## Item Groups
 
 You can also organize keymaps, commands, and functions into groups that will show up
 in the finder UI like a folder, selecting it will then trigger another finder for items

lua/legendary/data/itemlist.lua

@@ -48,7 +48,7 @@ function ItemList:add(items)
         group.icon = group.icon or item.icon
         group.description = group.description or item.description
       else
-        self.itemgroup_refs[item.name] = item
+        self.itemgroup_refs[item:id()] = item
         table.insert(self.items, item)
       end
       self.sorted = false
@@ -66,6 +66,17 @@ function ItemList:add(items)
   end
 end
 
+---Get an ItemGroup by ID/name.
+---@param id string
+---@return ItemGroup|nil
+function ItemList:get_item_group(id)
+  if not id or type(id) ~= 'string' or #id == 0 then
+    return nil
+  end
+
+  return self.itemgroup_refs[id]
+end
+
 ---@alias LegendaryItemFilter fun(item:LegendaryItem, context: LegendaryEditorContext):boolean
 
 ---Filter the ItemList. Returns a *new* ItemList,

lua/legendary/ui/init.lua

@@ -12,6 +12,7 @@ local Log = require('legendary.log')
 local M = {}
 
 ---@class LegendaryFindOpts
+---@field itemgroup string Find items in this item group only
 ---@field filters LegendaryItemFilter[]
 ---@field select_prompt string|fun():string
 ---@field formatter LegendaryItemFormatter
@@ -27,6 +28,16 @@ local function select_inner(opts, context, itemlist)
     Log.trace('Launching select UI')
   end
 
+  -- if no itemlist passed
+  if itemlist == nil then
+    -- if an item group is specified, use that
+    local itemgroup = State.items:get_item_group(opts.itemgroup)
+    if itemgroup then
+      itemlist = itemgroup.items
+    end
+  end
+
+  -- finally, use full item list if no other lists are specified
   itemlist = itemlist or State.items
   opts = opts or {}