feat(components): add Kbd component

docs/LumexUI.Docs.Client/Common/Navigation/NavigationStore.cs

@@ -34,6 +34,7 @@ public class NavigationStore
 			.Add( new( nameof( LumexDataGrid<T> ) ) )
 			.Add( new( nameof( LumexDivider ) ) )
 			.Add( new( nameof( LumexDropdown ) ) )
+			.Add( new( nameof( LumexKbd ), PageStatus.New ) )
 			.Add( new( nameof( LumexLink ) ) )
 			.Add( new( nameof( LumexListbox<T> ) ) )
 			.Add( new( nameof( LumexNavbar ) ) )

docs/LumexUI.Docs.Client/Pages/Components/Kbd/Examples/Keys.razor

@@ -0,0 +1,5 @@
+<div class="flex items-center gap-2">
+	<LumexKbd Keys="@([KeyboardKey.Command])">K</LumexKbd>
+	<LumexKbd Keys="@([KeyboardKey.Command, KeyboardKey.Shift])">N</LumexKbd>
+	<LumexKbd Keys="@([KeyboardKey.Option, KeyboardKey.Command])">P</LumexKbd>
+</div>

docs/LumexUI.Docs.Client/Pages/Components/Kbd/Examples/Usage.razor

@@ -0,0 +1 @@
+<LumexKbd Keys="@([KeyboardKey.Command])">K</LumexKbd>

docs/LumexUI.Docs.Client/Pages/Components/Kbd/Kbd.razor

@@ -0,0 +1,59 @@
+@page "/docs/components/kbd"
+@layout DocsContentLayout
+
+@using LumexUI.Docs.Client.Pages.Components.Kbd.PreviewCodes
+
+<DocsSection Title="Usage">
+    <Usage />
+
+    <DocsSection Title="Keys">
+        <Keys />
+    </DocsSection>
+</DocsSection>
+
+<DocsSlotsSection Slots="@_slots" >
+    <div>
+        <h4 class="font-semibold">Kbd</h4>
+        <ul>
+            <li><code>Class</code>: The basic CSS class name styles the wrapper of the kbd contents.</li>
+            <li><code>Classes</code>: The CSS class names for the kbd slots style the entire kbd at once.</li>
+        </ul>
+    </div>
+</DocsSlotsSection>
+
+<DocsApiSection Components="@_apiComponents" />
+
+@code {
+    [CascadingParameter] private DocsContentLayout Layout { get; set; } = default!;
+
+    private readonly Heading[] _headings = new Heading[]
+    {
+        new("Usage", [
+            new("Keys")
+        ]),
+        new("API")
+    };
+
+    private readonly Slot[] _slots = new Slot[]
+    {
+        new(nameof( KbdSlots.Base ), "Kbd wrapper, it handles alignment, placement, and general appearance."),
+        new(nameof( KbdSlots.Abbr ), "The keys wrapper that handles the appearance of the keys."),
+        new(nameof( KbdSlots.Content ), "The children wrapper that handles the appearance of the content."),
+    };
+
+    private readonly string[] _apiComponents = new string[]
+    {
+        nameof(LumexKbd)
+    };
+
+    protected override void OnInitialized()
+    {
+        Layout.Initialize(
+            title: "Kbd",
+            category: "Components",
+            description: "Keyboard key component for displaying keyboard shortcuts and input combinations.",
+            headings: _headings,
+            linksProps: new ComponentLinksProps("Kbd", isServer: true)
+        );
+    }
+}

docs/LumexUI.Docs.Client/Pages/Components/Kbd/PreviewCodes/Keys.razor

@@ -0,0 +1,5 @@
+@rendermode InteractiveWebAssembly
+
+<PreviewCode Code="@new(name: null, snippet: "Kbd.Code.Keys")">
+    <LumexUI.Docs.Client.Pages.Components.Kbd.Examples.Keys />
+</PreviewCode>

docs/LumexUI.Docs.Client/Pages/Components/Kbd/PreviewCodes/Usage.razor

@@ -0,0 +1,5 @@
+@rendermode InteractiveWebAssembly
+
+<PreviewCode Code="@new(name: null, snippet: "Kbd.Code.Usage")">
+    <LumexUI.Docs.Client.Pages.Components.Kbd.Examples.Usage />
+</PreviewCode>

src/LumexUI/Common/Enums/KeyboardKey.cs

@@ -0,0 +1,121 @@
+// Copyright (c) LumexUI 2024
+// LumexUI licenses this file to you under the MIT license
+// See the license here https://github.com/LumexUI/lumexui/blob/main/LICENSE
+
+namespace LumexUI.Common;
+
+/// <summary>
+/// Represents common keyboard keys for UI interactions.
+/// </summary>
+public enum KeyboardKey
+{
+	/// <summary>
+	/// The Command key (⌘), commonly found on Apple keyboards.
+	/// </summary>
+	Command,
+
+	/// <summary>
+	/// The Shift key.
+	/// </summary>
+	Shift,
+
+	/// <summary>
+	/// The Control key (Ctrl).
+	/// </summary>
+	Control,
+
+	/// <summary>
+	/// The Option key (⌥), commonly found on Apple keyboards.
+	/// </summary>
+	Option,
+
+	/// <summary>
+	/// The Alt key (⎇), commonly found on Windows and Linux keyboards.
+	/// </summary>
+	Alt,
+
+	/// <summary>
+	/// The Windows key (⊞).
+	/// </summary>
+	Win,
+
+	/// <summary>
+	/// The Function (fn) key, often found on laptops.
+	/// </summary>
+	Fn,
+
+	/// <summary>
+	/// The Enter key.
+	/// </summary>
+	Enter,
+
+	/// <summary>
+	/// The Delete key.
+	/// </summary>
+	Delete,
+
+	/// <summary>
+	/// The Escape key (Esc).
+	/// </summary>
+	Escape,
+
+	/// <summary>
+	/// The Tab key.
+	/// </summary>
+	Tab,
+
+	/// <summary>
+	/// The Caps Lock key.
+	/// </summary>
+	CapsLock,
+
+	/// <summary>
+	/// The Up Arrow key.
+	/// </summary>
+	Up,
+
+	/// <summary>
+	/// The Right Arrow key.
+	/// </summary>
+	Right,
+
+	/// <summary>
+	/// The Down Arrow key.
+	/// </summary>
+	Down,
+
+	/// <summary>
+	/// The Left Arrow key.
+	/// </summary>
+	Left,
+
+	/// <summary>
+	/// The Page Up key.
+	/// </summary>
+	PageUp,
+
+	/// <summary>
+	/// The Page Down key.
+	/// </summary>
+	PageDown,
+
+	/// <summary>
+	/// The Home key.
+	/// </summary>
+	Home,
+
+	/// <summary>
+	/// The End key.
+	/// </summary>
+	End,
+
+	/// <summary>
+	/// The Help key.
+	/// </summary>
+	Help,
+
+	/// <summary>
+	/// The Space key (Spacebar).
+	/// </summary>
+	Space,
+}

src/LumexUI/Components/Kbd/KbdConstants.cs

@@ -0,0 +1,43 @@
+// Copyright (c) LumexUI 2024
+// LumexUI licenses this file to you under the MIT license
+// See the license here https://github.com/LumexUI/lumexui/blob/main/LICENSE
+
+using LumexUI.Common;
+
+namespace LumexUI;
+
+/// <summary>
+/// Provides a collection of constants for mapping keyboard keys to their corresponding display symbols.
+/// </summary>
+public static class KbdConstants
+{
+	/// <summary>
+	/// Provides a mapping of keyboard keys to their corresponding display symbols for use in user interfaces or
+	/// documentation.
+	/// </summary>
+	public static readonly Dictionary<KeyboardKey, string> KeyboardKeys = new()
+	{
+		[KeyboardKey.Command] = "⌘",
+		[KeyboardKey.Shift] = "⇧",
+		[KeyboardKey.Control] = "⌃",
+		[KeyboardKey.Option] = "⌥",
+		[KeyboardKey.Alt] = "⎇",
+		[KeyboardKey.Win] = "⊞",
+		[KeyboardKey.Fn] = "fn",
+		[KeyboardKey.Enter] = "↵",
+		[KeyboardKey.Delete] = "⌫",
+		[KeyboardKey.Escape] = "⎋",
+		[KeyboardKey.Tab] = "⇥",
+		[KeyboardKey.CapsLock] = "⇪",
+		[KeyboardKey.Up] = "↑",
+		[KeyboardKey.Right] = "→",
+		[KeyboardKey.Down] = "↓",
+		[KeyboardKey.Left] = "←",
+		[KeyboardKey.PageUp] = "⇞",
+		[KeyboardKey.PageDown] = "⇟",
+		[KeyboardKey.Home] = "↖",
+		[KeyboardKey.End] = "↘",
+		[KeyboardKey.Help] = "?",
+		[KeyboardKey.Space] = "␣",
+	};
+}

src/LumexUI/Components/Kbd/KbdSlots.cs

@@ -0,0 +1,26 @@
+// Copyright (c) LumexUI 2024
+// 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.CodeAnalysis;
+
+using LumexUI.Common;
+
+namespace LumexUI;
+
+/// <summary>
+/// Represents the set of customizable slots for the <see cref="LumexKbd"/> component.
+/// </summary>
+[ExcludeFromCodeCoverage]
+public class KbdSlots : SlotBase
+{
+	/// <summary>
+	/// Gets or sets the CSS class for the abbr slot.
+	/// </summary>
+	public string? Abbr { get; set; }
+
+	/// <summary>
+	/// Gets or sets the CSS class for the content slot.
+	/// </summary>
+	public string? Content { get; set; }
+}

src/LumexUI/Components/Kbd/LumexKbd.razor

@@ -0,0 +1,27 @@
+@namespace LumexUI
+@inherits LumexComponentBase
+
+@using S = KbdSlots;
+@using C = KbdConstants;
+
+<LumexComponent As="@As"
+				Class="@GetStyles( nameof( S.Base ) )"
+				Style="@RootStyle"
+				data-slot="kbd"
+				@attributes="AdditionalAttributes">
+
+	@foreach ( var key in Keys )
+	{
+		<abbr class="@GetStyles( nameof( S.Abbr ) )"
+			  title="@key"
+			  data-slot="abbr">
+			@C.KeyboardKeys[key]
+		</abbr>
+	}
+
+	<span class="@GetStyles( nameof( S.Content ) )"
+		  data-slot="content">
+		@ChildContent
+	</span>
+
+</LumexComponent>

src/LumexUI/Components/Kbd/LumexKbd.razor.cs

@@ -0,0 +1,67 @@
+// Copyright (c) LumexUI 2024
+// 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.CodeAnalysis;
+
+using LumexUI.Common;
+using LumexUI.Utilities;
+
+using Microsoft.AspNetCore.Components;
+
+namespace LumexUI;
+
+/// <summary>
+/// A component that represents a keyboard key or combination of keys used to perform a specific action.
+/// </summary>
+public partial class LumexKbd : LumexComponentBase, ISlotComponent<KbdSlots>
+{
+	/// <summary>
+	/// Gets or sets the content to be rendered inside the component.
+	/// </summary>
+	[Parameter] public RenderFragment? ChildContent { get; set; }
+
+	/// <summary>
+	/// Gets or sets the CSS class names for the kbd slots.
+	/// </summary>
+	[Parameter] public KbdSlots? Classes { get; set; }
+
+	/// <summary>
+	/// Gets or sets the collection of keys to be used as input for the component.
+	/// </summary>
+	[Parameter] public IEnumerable<KeyboardKey> Keys { get; set; } = [];
+
+	private Dictionary<string, ComponentSlot> _slots = [];
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="LumexKbd"/> class, representing a keyboard element.
+	/// </summary>
+	public LumexKbd()
+	{
+		As = "kbd";
+	}
+
+	/// <inheritdoc/>
+	protected override void OnParametersSet()
+	{
+		var kbd = Styles.Kbd.Style( TwMerge );
+		_slots = kbd();
+	}
+
+	[ExcludeFromCodeCoverage]
+	private string? GetStyles( string slot )
+	{
+		if( !_slots.TryGetValue( slot, out var styles ) )
+		{
+			throw new NotImplementedException();
+		}
+
+		return slot switch
+		{
+			nameof( KbdSlots.Base ) => styles( Classes?.Base, Class ),
+			nameof( KbdSlots.Abbr ) => styles( Classes?.Abbr ),
+			nameof( KbdSlots.Content ) => styles( Classes?.Content ),
+			_ => throw new NotImplementedException()
+		};
+	}
+}