refactor: allow binding to a single item or multiple items

src/LumexUI/Components/Listbox/ListboxContext.cs

@@ -4,13 +4,15 @@ namespace LumexUI;
 
 internal class ListboxContext<T>( LumexListbox<T> owner ) : IComponentContext<LumexListbox<T>>
 {
+    private bool _collectingItems;
+
     public LumexListbox<T> Owner { get; } = owner;
     public List<LumexListboxItem<T>> Items { get; } = [];
-    public bool CollectingItems { get; private set; }
+    public SelectionMode SelectionMode { get; set; }
 
     public void Register( LumexListboxItem<T> item )
     {
-        if( CollectingItems )
+        if( _collectingItems )
         {
             Items.Add( item );
         }
@@ -24,11 +26,11 @@ public void Unregister( LumexListboxItem<T> item )
     public void StartCollectingItems()
     {
         Items.Clear();
-        CollectingItems = true;
+        _collectingItems = true;
     }
 
     public void FinishCollectingItems()
     {
-        CollectingItems = false;
+        _collectingItems = false;
     }
 }

src/LumexUI/Components/Listbox/LumexListbox.razor

@@ -1,8 +1,8 @@
 @namespace LumexUI
 @inherits LumexComponentBase
-@typeparam T
+@typeparam TValue
 
-<CascadingValue TValue="ListboxContext<T>" Value="@_context" IsFixed="@true">
+<CascadingValue TValue="ListboxContext<TValue>" Value="@_context" IsFixed="@true">
     @{
         _context.StartCollectingItems();
     }

src/LumexUI/Components/Listbox/LumexListbox.razor.cs

@@ -12,9 +12,9 @@ namespace LumexUI;
 /// <summary>
 /// A component representing a listbox component, used to display a selectable list of items.
 /// </summary>
-/// <typeparam name="T">The type of the values associated with the items in the listbox.</typeparam>
-[CascadingTypeParameter( nameof( T ) )]
-public partial class LumexListbox<T> : LumexComponentBase
+/// <typeparam name="TValue">The type of the values associated with the items in the listbox.</typeparam>
+[CascadingTypeParameter( nameof( TValue ) )]
+public partial class LumexListbox<TValue> : LumexComponentBase
 {
     /// <summary>
     /// Gets or sets content to be rendered inside the listbox.
@@ -43,34 +43,36 @@ public partial class LumexListbox<T> : LumexComponentBase
     [Parameter] public ThemeColor Color { get; set; } = ThemeColor.Default;
 
     /// <summary>
-    /// Gets or sets the selection mode for the listbox, determining how items can be selected.
+    /// Gets or sets the collection of items currently disabled in the listbox.
     /// </summary>
-    /// <remarks>
-    /// The default is <see cref="SelectionMode.None"/>
-    /// </remarks>
-    [Parameter] public SelectionMode SelectionMode { get; set; }
+    [Parameter] public ICollection<TValue?>? DisabledItems { get; set; }
+
+    /// <summary>
+    /// Gets or sets an item currently selected in the listbox.
+    /// </summary>
+    [Parameter] public TValue? Value { get; set; }
 
     /// <summary>
     /// Gets or sets the collection of items currently selected in the listbox.
     /// </summary>
-    [Parameter] public ICollection<T>? SelectedItems { get; set; }
+    [Parameter] public ICollection<TValue?>? Values { get; set; }
 
     /// <summary>
-    /// Gets or sets the callback that is invoked when the selection of items in the listbox changes.
+    /// Gets or sets the callback that is invoked when the selection of item in the listbox changes.
     /// </summary>
-    [Parameter] public EventCallback<ICollection<T>> SelectedItemsChanged { get; set; }
+    [Parameter] public EventCallback<TValue?> ValueChanged { get; set; }
 
     /// <summary>
-    /// Gets or sets the collection of items currently disabled in the listbox.
+    /// Gets or sets the callback that is invoked when the selection of items in the listbox changes.
     /// </summary>
-    [Parameter] public ICollection<T>? DisabledItems { get; set; }
+    [Parameter] public EventCallback<ICollection<TValue?>> ValuesChanged { get; set; }
 
     private readonly static RenderFragment _emptyContent = builder =>
     {
         builder.AddContent( 0, "No items." );
     };
 
-    private readonly ListboxContext<T> _context;
+    private readonly ListboxContext<TValue> _context;
     private readonly RenderFragment _renderItems;
     private readonly RenderFragment _renderEmptyContent;
 
@@ -81,13 +83,39 @@ public partial class LumexListbox<T> : LumexComponentBase
     /// </summary>
     public LumexListbox()
     {
-        _context = new ListboxContext<T>( this );
+        _context = new ListboxContext<TValue>( this );
         _renderItems = RenderItems;
         _renderEmptyContent = RenderEmptyContent;
 
         As = "ul";
     }
 
+    /// <inheritdoc />
+    public override Task SetParametersAsync( ParameterView parameters )
+    {
+        parameters.SetParameterProperties( this );
+
+        if( parameters.TryGetValue<TValue>( nameof( Value ), out var _ ) &&
+            parameters.TryGetValue<ICollection<TValue>>( nameof( Values ), out var _ ) )
+        {
+            throw new InvalidOperationException(
+                $"{GetType()} requires one of {nameof( Value )} or {nameof( Values )}, but both were specified." );
+        }
+
+        // Automatically set the SelectionMode depending on
+        // which of the 2-way bindable parameters are provided.
+        if( parameters.TryGetValue<TValue>( nameof( Value ), out var _ ) )
+        {
+            _context.SelectionMode = SelectionMode.Single;
+        }
+        else if( parameters.TryGetValue<ICollection<TValue>>( nameof( Values ), out var _ ) )
+        {
+            _context.SelectionMode = SelectionMode.Multiple;
+        }
+
+        return base.SetParametersAsync( ParameterView.Empty );
+    }
+
     /// <inheritdoc />
     protected override void OnParametersSet()
     {

src/LumexUI/Components/Listbox/LumexListboxItem.razor

@@ -1,9 +1,9 @@
 @namespace LumexUI
 @inherits LumexComponentBase
-@typeparam T
+@typeparam TValue
 
 @{
-    Context.Register(this);
+    Context?.Register(this);
 }
 
 @code {
@@ -36,7 +36,7 @@
                 <span class="@_slots.Title" data-slot="title">@ChildContent</span>
             }
 
-            @if (Context.Owner.SelectionMode is not SelectionMode.None)
+            @if (Context?.SelectionMode is not SelectionMode.None)
             {
                 <span class="@_slots.SelectedIcon" data-slot="selected-icon">
                     @_renderSelectedIcon

src/LumexUI/Components/Listbox/LumexListboxItem.razor.cs

@@ -2,6 +2,8 @@
 // LumexUI licenses this file to you under the MIT license
 // See the license here https://github.com/LumexUI/lumexui/blob/main/LICENSE
 
+using System.Diagnostics;
+
 using LumexUI.Common;
 using LumexUI.Styles;
 
@@ -13,14 +15,9 @@ namespace LumexUI;
 /// <summary>
 /// A component representing an item within the <see cref="LumexListbox{T}"/>.
 /// </summary>
-/// <typeparam name="T">The type of the value associated with the listbox item.</typeparam>
-public partial class LumexListboxItem<T> : LumexComponentBase, IDisposable
+/// <typeparam name="TValue">The type of the value associated with the listbox item.</typeparam>
+public partial class LumexListboxItem<TValue> : LumexComponentBase, IDisposable
 {
-    /// <summary>
-    /// Gets or sets a unique identifier for the listbox item.
-    /// </summary>
-    [Parameter, EditorRequired] public T Id { get; set; } = default!;
-
     /// <summary>
     /// Gets or sets content to be rendered inside the listbox item.
     /// </summary>
@@ -36,6 +33,11 @@ public partial class LumexListboxItem<T> : LumexComponentBase, IDisposable
     /// </summary>
     [Parameter] public RenderFragment? EndContent { get; set; }
 
+    /// <summary>
+    /// Gets or sets a value representing the listbox item.
+    /// </summary>
+    [Parameter] public TValue? Value { get; set; }
+
     /// <summary>
     /// Gets or sets a description of the listbox item.
     /// </summary>
@@ -67,9 +69,9 @@ public partial class LumexListboxItem<T> : LumexComponentBase, IDisposable
     /// </summary>
     [Parameter] public EventCallback<MouseEventArgs> OnClick { get; set; }
 
-    [CascadingParameter] internal ListboxContext<T> Context { get; set; } = default!;
+    [CascadingParameter] internal ListboxContext<TValue>? Context { get; set; }
 
-    private LumexListbox<T> Listbox => Context.Owner;
+    private LumexListbox<TValue>? Listbox => Context?.Owner;
 
     private readonly RenderFragment _renderSelectedIcon;
 
@@ -90,41 +92,40 @@ public override Task SetParametersAsync( ParameterView parameters )
     {
         parameters.SetParameterProperties( this );
 
-        // Respect the Variant value if provided; otherwise, use the owner's
-        Variant = parameters.TryGetValue<ListboxVariant>( nameof( Variant ), out var variant )
-            ? variant
-            : Context.Owner.Variant;
-
-        // Respect the Color value if provided; otherwise, use the owner's
-        Color = parameters.TryGetValue<ThemeColor>( nameof( Color ), out var color )
-            ? color
-            : Context.Owner.Color;
+        if( Listbox is not null )
+        {
+            // Respect the Variant value if provided; otherwise, use the owner's
+            Variant = parameters.TryGetValue<ListboxVariant>( nameof( Variant ), out var variant )
+                ? variant
+                : Listbox.Variant;
+
+            // Respect the Color value if provided; otherwise, use the owner's
+            Color = parameters.TryGetValue<ThemeColor>( nameof( Color ), out var color )
+                ? color
+                : Listbox.Color;
+        }
 
         return base.SetParametersAsync( ParameterView.Empty );
     }
 
     /// <inheritdoc />
     protected override void OnInitialized()
     {
-        ContextNullException.ThrowIfNull( Context, nameof( LumexListboxItem<T> ) );
+        ContextNullException.ThrowIfNull( Context, nameof( LumexListboxItem<TValue> ) );
     }
 
     /// <inheritdoc />
     protected override void OnParametersSet()
     {
-        if( Id is null )
-        {
-            throw new InvalidOperationException( $"{GetType()} requires a value for parameter '{nameof( Id )}'." );
-        }
-
         _slots ??= ListboxItem.GetStyles( this, TwMerge );
     }
 
     internal bool GetSelectedState() =>
-        Listbox.SelectedItems is not null && Listbox.SelectedItems.Contains( Id );
+        Listbox?.Value?.Equals( Value ) is true ||
+        Listbox?.Values?.Contains( Value ) is true;
 
     internal bool GetDisabledState() =>
-        Listbox.DisabledItems is not null && Listbox.DisabledItems.Contains( Id );
+        Listbox?.DisabledItems?.Contains( Value ) is true;
 
     private async Task OnClickAsync( MouseEventArgs args )
     {
@@ -133,45 +134,39 @@ private async Task OnClickAsync( MouseEventArgs args )
             return;
         }
 
-        await OnClick.InvokeAsync( args );
-
-        if( Listbox.SelectionMode is not SelectionMode.None )
+        if( Context?.SelectionMode is not SelectionMode.None )
         {
             await SelectAsync();
         }
+
+        await OnClick.InvokeAsync( args );
     }
 
     private Task SelectAsync()
     {
-        if( Listbox.SelectedItems is null )
-        {
-            return Task.CompletedTask;
-        }
+        Debug.Assert( Context is not null && Listbox is not null );
 
-        var selectedItems = Listbox.SelectedItems;
-        if( selectedItems.Remove( Id ) )
+        if( Context.SelectionMode is SelectionMode.Single )
         {
-            return Listbox.SelectedItemsChanged.InvokeAsync( selectedItems );
+            return Listbox.ValueChanged.InvokeAsync( Value );
         }
-
-        switch( Listbox.SelectionMode )
+        else if( Context.SelectionMode is SelectionMode.Multiple )
         {
-            case SelectionMode.Single:
-                selectedItems.Clear();
-                selectedItems.Add( Id );
-                break;
-
-            case SelectionMode.Multiple:
-                selectedItems.Add( Id );
-                break;
+            var selectedItems = Listbox.Values ?? [];
+            if( !selectedItems.Remove( Value ) )
+            {
+                selectedItems.Add( Value );
+            }
+
+            return Listbox.ValuesChanged.InvokeAsync( selectedItems );
         }
 
-        return Listbox.SelectedItemsChanged.InvokeAsync( selectedItems );
+        return Task.CompletedTask;
     }
 
     /// <inheritdoc />
-    public void Dispose()
+    public virtual void Dispose()
     {
-        Context.Unregister( this );
+        Context?.Unregister( this );
     }
 }

src/LumexUI/Styles/Listbox.cs

@@ -115,17 +115,15 @@ internal class ListboxItem
 
     public static ListboxItemSlots GetStyles<T>( LumexListboxItem<T> listboxItem, TwMerge twMerge )
     {
-        var listbox = listboxItem.Context.Owner;
-
         return new ListboxItemSlots()
         {
             Root = twMerge.Merge(
                 ElementClass.Empty()
                     .Add( _base )
                     .Add( _disabled, when: listboxItem.GetDisabledState() )
                     .Add( listboxItem.Class )
-                    .Add( GetVariantStyles( listbox.Variant, slot: nameof( _base ) ) )
-                    .Add( GetCompoundStyles( listbox.Variant, listboxItem.Color, slot: nameof( _base ) ) )
+                    .Add( GetVariantStyles( listboxItem.Variant, slot: nameof( _base ) ) )
+                    .Add( GetCompoundStyles( listboxItem.Variant, listboxItem.Color, slot: nameof( _base ) ) )
                     .ToString() ),
 
             Wrapper = twMerge.Merge(