[JEWEL-938] Split SelectableLazyColumn into Single/Multi APIs and add initial selected keys support

[nebojsa-vuksic]

Summary

This PR splits Jewel SelectableLazyColumn into explicit single-selection and multi-selection APIs (SingleSelectionLazyColumn, MultiSelectionLazyColumn) and adds support for initial selected keys during state creation, while preserving legacy API behavior and
compatibility.

Dependency

This PR depends on #3446 and should be merged only after that PR lands. Until then, the PR stays in draft mode.

Changes

• Added SingleSelectionLazyColumn and MultiSelectionLazyColumn as new composable entry points.
• Added dedicated typed states: SingleSelectionLazyListState and MultiSelectionLazyListState.
• Added typed remember APIs:
  • rememberSingleSelectionLazyListState(initialSelectedKey = ...)
  • rememberMultiSelectionLazyListState(initialSelectedKeys = ...)
• Extended SelectableLazyListState with selectionMode and initialSelectedKeys metadata used in legacy compatibility scenarios.
• Kept legacy SelectableLazyColumn/rememberSelectableLazyListState APIs for source and binary compatibility and marked migration path with deprecations.
• Deprecated 2-arg rememberSelectableLazyListState(firstVisibleItemIndex, firstVisibleItemScrollOffset) and directed users to the 4-arg overload.
• Preserved legacy contract: if both are provided and mismatch, explicit selectionMode parameter wins over state.selectionMode.
• Added mismatch warnings for legacy selection mode/state inconsistencies, with no runtime exceptions.
• Kept first composition callback behavior stable: initial preselected keys do not trigger onSelectedIndexesChange.
• Added tests for typed APIs and legacy compatibility edge cases.

Edge cases and behavior details

• Legacy mismatch: selectionMode = SelectionMode.Single with legacy state containing multiple selected keys.
  • Warning is logged.
  • Existing initial selection is shown as-is until interaction.
  • Interaction follows explicit selectionMode = SelectionMode.Single.
• Legacy mismatch: selectionMode = SelectionMode.None with legacy state already containing selected keys.
  • Warning is logged.
  • Existing keys are preserved initially.
  • New selection through interaction is suppressed by SelectionMode.None semantics.
• Legacy remember normalization:
  • SelectionMode.None drops all initial keys.
  • SelectionMode.Single keeps first key from list order.
  • SelectionMode.Multiple keeps all keys, deduplicated in insertion order.
• Multi-selection keyboard edge case:
  • Non-contiguous selection (e.g., 1 and 3), then Shift+Down, correctly adds next item while preserving existing picks.

Why new APIs and why keep old ones

• New APIs provide explicit single/multi selection entry points and prevent passing arbitrary modes through the new surface.
• Legacy APIs are retained to avoid source/binary breakage for existing consumers and to enable gradual migration.
• Deprecations guide users toward the new APIs without forcing immediate breakage.

Release notes

New features

• [JEWEL-938] Added SingleSelectionLazyColumn and MultiSelectionLazyColumn with dedicated typed state and remember APIs.
• [JEWEL-938] Added initial selection support for new/legacy state creation (initialSelectedKey/initialSelectedKeys).

Bug fixes

• [JEWEL-938] Fixed multi-selection edge-case behavior for non-contiguous selection extension with keyboard range actions.

Deprecated API

• [JEWEL-938] Deprecated legacy SelectableLazyColumn entry points in favor of explicit single/multi APIs while preserving
  compatibility overloads.
• [JEWEL-938] Deprecated legacy 2-arg rememberSelectableLazyListState(...); use the 4-arg overload.

[nebojsa-vuksic]

The rememberSelectableLazyListState 2-args function is depricated

fun rememberSelectableLazyListState(
    initialFirstVisibleItemIndex: Int = 0,
    initialFirstVisibleItemScrollOffset: Int = 0,
)

in favor of rememberSelectableLazyListState 4-args function:

public fun rememberSingleSelectionLazyListState(
    initialFirstVisibleItemIndex: Int = 0,
    initialFirstVisibleItemScrollOffset: Int = 0,
    initialSelectedKey: Any? = null,
)

[DanielSouzaBertoldi]

Great work! 🚀

[DanielSouzaBertoldi]

We should discuss about how long can a method/class stay deprecated. I get we want to maintain source compat in this case, but in the release notes/deprecation message we could be a bit more precise with when are we expecting to fully hide this API for good

[nebojsa-vuksic]

Far point! As far as I know IntelliJ keeps API deprecated for at least two releases. I'm also fine with this approach :) @rock3r @DanielSouzaBertoldi What do you think if we state that we are planning to delete this in 26.3 release?