Minga.Editing.Completion (Minga v0.1.0)

Pure data structure for managing LSP completion state.

Holds the list of completion items returned by a language server, tracks the selected index, and filters items as the user continues typing. All functions are pure transformations with no side effects.

Lifecycle

new/2 — create from parsed LSP completion items and a trigger position
filter/2 — narrow the visible items as the user types more characters
move_up/1 / move_down/1 — navigate the selection
selected_item/1 — get the currently highlighted item
accept/1 — returns the text/edit to insert for the selected item

Summary

Types

item()

A parsed completion item.

item_kind()

LSP CompletionItemKind as an atom.

t()

text_edit()

A text edit to apply when accepting a completion.

Functions

accept(completion)

Returns the insert text and optional text edit for the selected item.

active?(completion)

Returns true if there are any filtered items to show.

count(completion)

Returns the count of currently filtered items.

filter(completion, prefix)

Filters completion items by the text typed since the trigger position.

kind_label(atom)

Returns a single-character kind indicator for rendering.

move_down(c)

Moves the selection down one item, wrapping at the bottom.

move_up(c)

Moves the selection up one item, wrapping at the top.

new(items, trigger_position)

Creates a new completion state from a list of parsed items and the cursor position where completion was triggered.

parse_item(raw)

Parses a single LSP CompletionItem map into an item() struct.

parse_response(items)

Parses an LSP completion response into a list of item() maps.

selected_item(completion)

Returns the currently selected item, or nil if no items.

update_selected_documentation(completion, doc_text)

Updates the documentation for the currently selected item.

visible_items(completion)

Returns {visible_items, selected_offset} for rendering.

Types

item()

@type item() :: %{
  label: String.t(),
  kind: item_kind(),
  insert_text: String.t(),
  filter_text: String.t(),
  detail: String.t(),
  documentation: String.t(),
  sort_text: String.t(),
  text_edit: text_edit() | nil,
  raw: map() | nil
}

A parsed completion item.

item_kind()

@type item_kind() ::
  :text
  | :method
  | :function
  | :constructor
  | :field
  | :variable
  | :class
  | :interface
  | :module
  | :property
  | :unit
  | :value
  | :enum
  | :keyword
  | :snippet
  | :color
  | :file
  | :reference
  | :folder
  | :enum_member
  | :constant
  | :struct
  | :event
  | :operator
  | :type_parameter

LSP CompletionItemKind as an atom.

t()

@type t() :: %Minga.Editing.Completion{
  filter_text: String.t(),
  filtered: [item()],
  items: [item()],
  last_resolved_index: integer(),
  max_visible: pos_integer(),
  resolve_timer: reference() | nil,
  selected: non_neg_integer(),
  trigger_position: {non_neg_integer(), non_neg_integer()}
}

text_edit()

@type text_edit() :: %{
  range: %{
    start_line: non_neg_integer(),
    start_col: non_neg_integer(),
    end_line: non_neg_integer(),
    end_col: non_neg_integer()
  },
  new_text: String.t()
}

A text edit to apply when accepting a completion.

Functions

accept(completion)

@spec accept(t()) :: {:insert_text, String.t()} | {:text_edit, text_edit()} | nil

Returns the insert text and optional text edit for the selected item.

If the item has a text_edit, returns {:text_edit, edit}. Otherwise returns {:insert_text, text}.

active?(completion)

@spec active?(t()) :: boolean()

Returns true if there are any filtered items to show.

count(completion)

@spec count(t()) :: non_neg_integer()

Returns the count of currently filtered items.

filter(completion, prefix)

@spec filter(t(), String.t()) :: t()

Filters completion items by the text typed since the trigger position.

Items whose filter_text starts with prefix (case-insensitive) are kept. Resets selection to the top.

kind_label(atom)

@spec kind_label(item_kind()) :: String.t()

Returns a single-character kind indicator for rendering.

move_down(c)

@spec move_down(t()) :: t()

Moves the selection down one item, wrapping at the bottom.

move_up(c)

@spec move_up(t()) :: t()

Moves the selection up one item, wrapping at the top.

new(items, trigger_position)

@spec new(
  [item()],
  {non_neg_integer(), non_neg_integer()}
) :: t()

Creates a new completion state from a list of parsed items and the cursor position where completion was triggered.

parse_item(raw)

@spec parse_item(map()) :: item()

Parses a single LSP CompletionItem map into an item() struct.

parse_response(items)

@spec parse_response(map() | [map()] | nil) :: [item()]

Parses an LSP completion response into a list of item() maps.

Handles both CompletionList (%{"items" => [...]}) and bare CompletionItem[] response formats.

selected_item(completion)

@spec selected_item(t()) :: item() | nil

Returns the currently selected item, or nil if no items.

update_selected_documentation(completion, doc_text)

@spec update_selected_documentation(t(), String.t()) :: t()

Updates the documentation for the currently selected item.

Called when a completionItem/resolve response arrives with the full documentation text.

visible_items(completion)

@spec visible_items(t()) :: {[item()], non_neg_integer()}

Returns {visible_items, selected_offset} for rendering.

visible_items is a window of at most max_visible items centered around the selection. selected_offset is the index of the selected item within that window.