NAME

Selkie::Widget::ListView - Scrollable single-select list of strings

SYNOPSIS

use Selkie::Widget::ListView;
use Selkie::Sizing;

my $list = Selkie::Widget::ListView.new(sizing => Sizing.flex);
$list.set-items(<Alpha Beta Gamma Delta>);

$list.on-select.tap:   -> $name { say "cursor on: $name" };
$list.on-activate.tap: -> $name { say "selected: $name" };
$list.on-key('d', -> $ { delete-item });

DESCRIPTION

A vertical list of string entries with a cursor. Arrow keys (and PageUp/PageDown/Home/End/mouse wheel) move the cursor; Enter activates. The selected item is always fully visible; the list auto-scrolls as the cursor moves.

Two Supplies:

• on-select — fires whenever the cursor moves. Use for "show details of highlighted"

• on-activate — fires when the user presses Enter. Use for "open this item"

Across set-items calls, cursor position is preserved by label when possible. If the previously-selected string is still in the new list, the cursor follows it. Otherwise the cursor index is clamped to bounds. Only resets to 0 when the list becomes empty.

Includes a scrollbar on the right edge when items exceed the viewport.

EXAMPLES

Store-driven list

$app.store.subscribe-with-callback(
    'file-list',
    -> $s { ($s.get-in('files') // []).map(*<name>).List },
    -> @items { $list.set-items(@items) },     # cursor preserved by value
    $list,
);

$list.on-activate.tap: -> $name {
    $app.store.dispatch('files/open', :$name);
};

SEE ALSO

• Selkie::Widget::CardList — same pattern for variable-height cards

• Selkie::Widget::RadioGroup — similar UI but for one-of-many selection

method items

method items() returns List

The current items as a List.

method cursor

method cursor() returns UInt

Index of the cursor (the highlighted row). Always 0 when the list is empty.

method selected

method selected() returns Str

The string at the cursor, or the Str type object when empty.

method on-select

method on-select() returns Supply

Supply that emits the selected string whenever the cursor moves (Up / Down / mouse click / select-index). Fires once on set-items if the new list is non-empty.

method on-activate

method on-activate() returns Supply

Supply that emits the selected string when the user activates a row (Enter, Space, double-click). on-select fires for cursor movement; on-activate only fires for explicit activation.

method set-items

method set-items(
    @new-items
) returns Mu

Replace the items. The cursor tracks the previously-selected string if it's still present in the new list (so a list refresh doesn't jump the user back to row 0); otherwise clamps to the new bounds. Emits on on-select when the resulting list is non-empty.

method select-index

method select-index(
    Int $idx where { ... }
) returns Mu

Move the cursor to $idx (clamped to the last item) and emit on on-select. No-op when the list is empty.