feat(docs): add the Icon page

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

@@ -29,7 +29,7 @@ public class NavigationStore
             .Add( new( nameof( LumexCheckboxGroup ) ) )
             .Add( new( nameof( LumexCollapse ) ) )
             .Add( new( nameof( LumexDivider ) ) )
-            .Add( new( nameof( LumexIcon ), locked: true ) )
+            .Add( new( nameof( LumexIcon ) ) )
             .Add( new( nameof( LumexLink ) ) )
             .Add( new( nameof( LumexNavbar ) ) )
             .Add( new( nameof( LumexNumbox<T> ), locked: true ) )

docs/LumexUI.Docs.Client/Components/ComponentLinks.razor

@@ -43,13 +43,13 @@
     @<text>
         <LumexIcon Icon="@Icons.Brands.Blazor"
                    Size="@new("20")"
-                   ViewBox="-10 -38 340 340" />
+                   viewBox="-10 -38 340 340" />
     </text>;
 
     private RenderFragment GithubIcon =>
     @<text>
         <LumexIcon Icon="@Icons.Brands.GitHub"
                    Size="@new("20")"
-                   ViewBox="0 0 24 24" />
+                   viewBox="0 0 24 24" />
     </text>;
 }

docs/LumexUI.Docs.Client/Components/Header.razor

@@ -47,7 +47,7 @@
             <LumexLink Href="https://github.com/LumexUI/lumexui"
                        External="@true"
                        Class="text-foreground-400 hover:text-foreground-600">
-                <LumexIcon Icon="@Icons.Brands.GitHub" ViewBox="0 0 24 24" />
+                <LumexIcon Icon="@Icons.Brands.GitHub" viewBox="0 0 24 24" />
             </LumexLink>
         </LumexNavbarItem>
     </text>;

docs/LumexUI.Docs.Client/Pages/Components/Icon/Examples/Colors.razor

@@ -0,0 +1,7 @@
+<LumexIcon Color="@ThemeColor.Default" Icon="@Icons.Rounded.Favorite" />
+<LumexIcon Color="@ThemeColor.Primary" Icon="@Icons.Rounded.Favorite" />
+<LumexIcon Color="@ThemeColor.Secondary" Icon="@Icons.Rounded.Favorite" />
+<LumexIcon Color="@ThemeColor.Success" Icon="@Icons.Rounded.Favorite" />
+<LumexIcon Color="@ThemeColor.Warning" Icon="@Icons.Rounded.Favorite" />
+<LumexIcon Color="@ThemeColor.Danger" Icon="@Icons.Rounded.Favorite" />
+<LumexIcon Color="@ThemeColor.Info" Icon="@Icons.Rounded.Favorite" />

docs/LumexUI.Docs.Client/Pages/Components/Icon/Examples/CustomStyles.razor

@@ -0,0 +1 @@
+<LumexIcon Icon="@Icons.Rounded.Bed" Size="@new("40")" Class="text-indigo-500" />

docs/LumexUI.Docs.Client/Pages/Components/Icon/Examples/DimensionsFont.razor

@@ -0,0 +1,22 @@
+@using static LumexUI.LumexIcon
+
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&icon_names=accessibility" />
+
+<LumexIcon Size="@(new Dimensions("16"))" Icon="material-symbols-outlined">
+    accessibility
+</LumexIcon>
+<LumexIcon Size="@(new Dimensions("20"))" Icon="material-symbols-outlined">
+    accessibility
+</LumexIcon>
+<LumexIcon Size="@(new Dimensions("24"))" Icon="material-symbols-outlined">
+    accessibility
+</LumexIcon>
+<LumexIcon Size="@(new Dimensions("28"))" Icon="material-symbols-outlined">
+    accessibility
+</LumexIcon>
+<LumexIcon Size="@(new Dimensions("32"))" Icon="material-symbols-outlined">
+    accessibility
+</LumexIcon>
+<LumexIcon Size="@(new Dimensions("36"))" Icon="material-symbols-outlined">
+    accessibility
+</LumexIcon>

docs/LumexUI.Docs.Client/Pages/Components/Icon/Examples/DimensionsSvg.razor

@@ -0,0 +1,11 @@
+@using static LumexUI.LumexIcon
+
+<LumexIcon Size="@(new Dimensions("16"))" Icon="@Icons.Rounded.Home" />
+<LumexIcon Size="@(new Dimensions("20"))" Icon="@Icons.Rounded.Home" />
+<LumexIcon Size="@(new Dimensions("24"))" Icon="@Icons.Rounded.Home" />
+<LumexIcon Size="@(new Dimensions("28"))" Icon="@Icons.Rounded.Home" />
+<LumexIcon Size="@(new Dimensions("32"))" Icon="@Icons.Rounded.Home" />
+
+<div class="w-9 h-9">
+    <LumexIcon Size="@(new Dimensions("100%"))" Icon="@Icons.Rounded.Home" />
+</div>

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

@@ -0,0 +1,5 @@
+<LumexIcon Icon="@Icons.Rounded.Favorite" />
+<LumexIcon Icon="@Icons.Rounded.Settings" />
+<LumexIcon Icon="@Icons.Rounded.Person" />
+<LumexIcon Icon="@Icons.Rounded.Home" />
+<LumexIcon Icon="@Icons.Rounded.Bed" />

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

@@ -0,0 +1,71 @@
+@page "/docs/components/icon"
+@layout DocsContentLayout
+
+@using LumexUI.Docs.Client.Pages.Components.Icon.PreviewCodes
+
+<DocsSection Title="Usage">
+    <p>
+        The icon component allows you to easily integrate SVG or
+        font icons into your application to enhance the UI.
+    </p>
+    <Usage />
+
+    <DocsSection Title="Colors">
+        <p>
+            Change the color of the icon to match your
+            application’s theme or to highlight specific icons.
+        </p>
+        <Colors />
+    </DocsSection>
+
+    <DocsSection Title="Dimensions">
+        <p>
+            You can customize the icon’s size to fit different layouts or design needs. 
+            If the icon is an SVG, the dimensions are applied to the <Code>width</Code> and <Code>height</Code> attributes.
+        </p>
+        <DimensionsSvg />
+
+        <p>For font icons, the size corresponds to the font size in pixels.</p>
+        <DimensionsFont />
+    </DocsSection>
+</DocsSection>
+
+<DocsSection Title="Custom Styles">
+    <p>
+        You can customize the icon component by passing any Tailwind CSS
+        classes to the component's <Code>Class</Code> and/or <Code>Style</Code> parameters.
+    </p>
+    <CustomStyles />
+</DocsSection>
+
+<DocsApiSection Components="@_apiComponents" />
+
+@code {
+    [CascadingParameter] private DocsContentLayout Layout { get; set; } = default!;
+
+    private readonly Heading[] _headings = new Heading[]
+    {
+        new("Usage", [
+            new("Colors"),
+            new("Dimensions"),
+        ]),
+        new("Custom Styles"),
+        new("API")
+    };
+
+    private readonly string[] _apiComponents = new string[]
+    {
+        nameof(LumexIcon)
+    };
+
+    protected override void OnInitialized()
+    {
+        Layout.Initialize(
+            title: "Icon",
+            category: "Components",
+            description: "Icons provide visual cues, enhancing interfaces with scalable, customizable symbols.",
+            headings: _headings,
+            linksProps: new ComponentLinksProps( "Icon", isServer: true )
+        );
+    }
+}

docs/LumexUI.Docs.Client/Pages/Components/Icon/PreviewCodes/Colors.razor

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

docs/LumexUI.Docs.Client/Pages/Components/Icon/PreviewCodes/CustomStyles.razor

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

docs/LumexUI.Docs.Client/Pages/Components/Icon/PreviewCodes/DimensionsFont.razor

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

docs/LumexUI.Docs.Client/Pages/Components/Icon/PreviewCodes/DimensionsSvg.razor

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

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

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

src/LumexUI/Common/Models/Dimensions.cs

@@ -0,0 +1,25 @@
+namespace LumexUI.Common;
+
+/// <summary>
+/// Represents the dimensions with width and height.
+/// </summary>
+/// <param name="w">The width.</param>
+/// <param name="h">The height.</param>
+public readonly struct Dimensions( string w, string h )
+{
+    /// <summary>
+    /// Gets the width.
+    /// </summary>
+    public readonly string W = w;
+
+    /// <summary>
+    /// Gets the height.
+    /// </summary>
+    public readonly string H = h;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Dimensions"/> with equal width and height.
+    /// </summary>
+    /// <param name="size">The size to be used for both width and height.</param>
+    public Dimensions( string size ) : this( w: size, h: size ) { }
+}

src/LumexUI/Components/Icon/LumexIcon.razor

@@ -7,7 +7,7 @@
          style="@RootStyle"
          width="@Size.W"
          height="@Size.H"
-         viewBox="@ViewBox"
+         viewBox="0 -960 960 960"
          focusable="false"
          @attributes="@AdditionalAttributes">
         @((MarkupString)Icon)

src/LumexUI/Components/Icon/LumexIcon.razor.cs

@@ -31,14 +31,6 @@
     /// </remarks>
     [Parameter] public Dimensions Size { get; set; } = new( "24" );
 
-    /// <summary>
-    /// Gets or sets the viewBox attribute of the SVG element representing the icon.
-    /// </summary>
-    /// <remarks>
-    /// The default value is "0 -960 960 960" (<seealso href="https://fonts.google.com/icons">Material Symbols</seealso>)
-    /// </remarks>
-    [Parameter] public string ViewBox { get; set; } = "0 -960 960 960";
-
     /// <summary>
     /// Gets or sets a color of the icon.
     /// </summary>
@@ -47,36 +39,22 @@
     private protected override string? RootClass =>
         TwMerge.Merge( Styles.Icon.GetStyles( this ) );
 
-    private string FontIconStyle => ElementStyle.Empty()
-        .Add( "font-size", Size.W, when: Size.W == Size.H )
+    private string? FontIconStyle => ElementStyle.Empty()
+        .Add( "font-size", $"{Size.W}px", when: Size.W == Size.H )
         .Add( RootStyle )
         .ToString();
 
     [MemberNotNullWhen( true, nameof( Icon ) )]
     private bool IsSvgIcon => !string.IsNullOrEmpty( Icon ) && Icon.Trim().StartsWith( '<' );
 
-    /// <summary>
-    /// Represents the dimensions of an icon with width and height.
-    /// </summary>
-    /// <param name="w">The width of the icon.</param>
-    /// <param name="h">The height of the icon.</param>
-    public readonly struct Dimensions( string w, string h )
+    /// <inheritdoc />
+    protected override void OnParametersSet()
     {
-        /// <summary>
-        /// Gets the width of the icon.
-        /// </summary>
-        public readonly string W = w;
-
-        /// <summary>
-        /// Gets the height of the icon.
-        /// </summary>
-        public readonly string H = h;
-
-        /// <summary>
-        /// Initializes a new instance of the <see cref="Dimensions"/> 
-        /// with equal width and height for the icon.
-        /// </summary>
-        /// <param name="size">The size to be used for both width and height.</param>
-        public Dimensions( string size ) : this( size, size ) { }
+        if( ChildContent is not null && ( Size.W != Size.H ) )
+        {
+            throw new InvalidOperationException(
+                $"{GetType()} requires equal width and height dimensions for " +
+                $"{nameof( Size )} if used as a font icon." );
+        }
     }
 }