feat(components): introduce Spinner component (#207)

desmondinho · web-flow · commit 19261d2c30ec · 2025-03-16T22:20:43.000+02:00
* feat(spinner): add baseline implementation

* feat(spinner): add variants and styles

* feat(spinner): add slots

* docs(spinner): add Spinner page

* docs: nits

* test(spinner): add tests

* docs: map static assets
diff --git a/docs/LumexUI.Docs.Client/Common/Navigation/NavigationStore.cs b/docs/LumexUI.Docs.Client/Common/Navigation/NavigationStore.cs
@@ -41,6 +41,7 @@ public class NavigationStore
 			.Add( new( nameof( LumexRadioGroup<T> ) ) )
 			.Add( new( nameof( LumexSelect<T> ) ) )
 			.Add( new( nameof( LumexSkeleton ), ComponentStatus.New ) )
+			.Add( new( nameof( LumexSpinner ), ComponentStatus.New ) )
 			.Add( new( nameof( LumexSwitch ) ) )
 			.Add( new( nameof( LumexTabs ) ) )
 			.Add( new( nameof( LumexTextbox ) ) );
@@ -87,6 +88,7 @@ public class NavigationStore
 			.Add( new( nameof( LumexSelect<T> ) ) )
 			.Add( new( nameof( LumexSelectItem<T> ) ) )
 			.Add( new( nameof( LumexSkeleton ) ) )
+			.Add( new( nameof( LumexSpinner ) ) )
 			.Add( new( nameof( LumexSwitch ) ) )
 			.Add( new( nameof( LumexTab ) ) )
 			.Add( new( nameof( LumexTabs ) ) )
diff --git a/docs/LumexUI.Docs.Client/Components/Preview.razor b/docs/LumexUI.Docs.Client/Components/Preview.razor
@@ -24,7 +24,7 @@
 
     private readonly Slots _slots = new()
         {
-            Preview = "relative flex flex-wrap items-center gap-4",
+            Preview = "relative flex flex-wrap items-center gap-4 overflow-x-auto scrollbar-hide",
             PreviewWrapper = "relative p-8 rounded-xl bg-zinc-50 ring ring-foreground-900/10 not-prose",
             Background = "absolute inset-0 [mask-image:radial-gradient(#fff_0%,transparent_100%)]",
         };
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Skeleton/Skeleton.razor b/docs/LumexUI.Docs.Client/Pages/Components/Skeleton/Skeleton.razor
@@ -41,7 +41,6 @@
 
     private readonly Heading[] _headings = new Heading[]
     {
-        new("Composition"),
         new("Usage", [
             new("Standalone"),
             new("Loading")
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Colors.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Colors.razor
@@ -0,0 +1,9 @@
+﻿<div class="flex gap-8">
+    <LumexSpinner Label="Default" LabelColor="@ThemeColor.Default" Color="@ThemeColor.Default" />
+    <LumexSpinner Label="Primary" LabelColor="@ThemeColor.Primary" Color="@ThemeColor.Primary" />
+    <LumexSpinner Label="Secondary" LabelColor="@ThemeColor.Secondary" Color="@ThemeColor.Secondary" />
+    <LumexSpinner Label="Success" LabelColor="@ThemeColor.Success" Color="@ThemeColor.Success" />
+    <LumexSpinner Label="Warning" LabelColor="@ThemeColor.Warning" Color="@ThemeColor.Warning" />
+    <LumexSpinner Label="Danger" LabelColor="@ThemeColor.Danger" Color="@ThemeColor.Danger" />
+    <LumexSpinner Label="Info" LabelColor="@ThemeColor.Info" Color="@ThemeColor.Info" />
+</div>
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Label.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Label.razor
@@ -0,0 +1 @@
+﻿<LumexSpinner Label="Loading..." />
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Sizes.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Sizes.razor
@@ -0,0 +1,5 @@
+﻿<div class="flex gap-4">
+    <LumexSpinner Size="@Size.Small" />
+    <LumexSpinner Size="@Size.Medium" />
+    <LumexSpinner Size="@Size.Large" />
+</div>
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Usage.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Usage.razor
@@ -0,0 +1 @@
+﻿<LumexSpinner />
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Variants.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Examples/Variants.razor
@@ -0,0 +1,8 @@
+﻿<div class="flex gap-8">
+    <LumexSpinner Variant="@SpinnerVariant.Ring" Label="Ring" />
+    <LumexSpinner Variant="@SpinnerVariant.Arc" Label="Arc" />
+    <LumexSpinner Variant="@SpinnerVariant.ArcGradient" Label="Arc Gradient" />
+    <LumexSpinner Variant="@SpinnerVariant.DotsWave" Label="Dots Wave" />
+    <LumexSpinner Variant="@SpinnerVariant.DotsFade" Label="Dots Fade" />
+    <LumexSpinner Variant="@SpinnerVariant.Classic" Label="Classic" />
+</div>
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Colors.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Colors.razor
@@ -0,0 +1,5 @@
+﻿@rendermode InteractiveWebAssembly
+
+<PreviewCode Code="@new(name: null, snippet: "Spinner.Code.Colors")">
+    <LumexUI.Docs.Client.Pages.Components.Spinner.Examples.Colors />
+</PreviewCode>
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Label.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Label.razor
@@ -0,0 +1,5 @@
+﻿@rendermode InteractiveWebAssembly
+
+<PreviewCode Code="@new(name: null, snippet: "Spinner.Code.Label")">
+    <LumexUI.Docs.Client.Pages.Components.Spinner.Examples.Label />
+</PreviewCode>
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Sizes.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Sizes.razor
@@ -0,0 +1,5 @@
+﻿@rendermode InteractiveWebAssembly
+
+<PreviewCode Code="@new(name: null, snippet: "Spinner.Code.Sizes")">
+    <LumexUI.Docs.Client.Pages.Components.Spinner.Examples.Sizes />
+</PreviewCode>
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Usage.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Usage.razor
@@ -0,0 +1,5 @@
+﻿@rendermode InteractiveWebAssembly
+
+<PreviewCode Code="@new(name: null, snippet: "Spinner.Code.Usage")">
+    <LumexUI.Docs.Client.Pages.Components.Spinner.Examples.Usage />
+</PreviewCode>
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Variants.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/PreviewCodes/Variants.razor
@@ -0,0 +1,5 @@
+﻿@rendermode InteractiveWebAssembly
+
+<PreviewCode Code="@new(name: null, snippet: "Spinner.Code.Variants")">
+    <LumexUI.Docs.Client.Pages.Components.Spinner.Examples.Variants />
+</PreviewCode>
diff --git a/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Spinner.razor b/docs/LumexUI.Docs.Client/Pages/Components/Spinner/Spinner.razor
@@ -0,0 +1,87 @@
+﻿@page "/docs/components/spinner"
+@layout DocsContentLayout
+
+@using LumexUI.Docs.Client.Pages.Components.Spinner.PreviewCodes
+
+<DocsSection Title="Usage">
+    <p>
+        The spinner component provides a visual loading indicator,
+        commonly used to show ongoing processes.
+    </p>
+    <Usage />
+
+    <DocsSection Title="Label">
+        <p>Add a label to the spinner to provide context about what is loading.</p>
+        <Label />
+    </DocsSection>
+
+    <DocsSection Title="Sizes">
+        <p>Adjust the size of the spinner.</p>
+        <Sizes />
+    </DocsSection>
+
+    <DocsSection Title="Colors">
+        <p>Customize the spinner color.</p>
+        <Colors />
+    </DocsSection>
+
+    <DocsSection Title="Variants">
+        <p>Choose different spinner styles.</p>
+        <Variants />
+    </DocsSection>
+</DocsSection>
+
+<DocsSlotsSection Slots="@_slots">
+    <div>
+        <h4 class="font-semibold">Spinner</h4>
+        <ul>
+            <li><Code>Class</Code>: The CSS class names to style the wrapper.</li>
+            <li><Code>Classes</Code>: The CSS class names to style the slots.</li>
+        </ul>
+    </div>
+</DocsSlotsSection>
+
+<DocsApiSection Components="@_apiComponents" />
+
+@code {
+    [CascadingParameter] private DocsContentLayout Layout { get; set; } = default!;
+
+    private readonly Heading[] _headings = new Heading[]
+    {
+        new("Usage", [
+            new("Label"),
+            new("Sizes"),
+            new("Colors"),
+            new("Variants")
+        ]),
+        new("Custom Styles"),
+        new("API")
+    };
+
+    private readonly Slot[] _slots = new Slot[]
+    {
+        new(nameof(SpinnerSlots.Base), "The main container for the spinner component."),
+        new(nameof(SpinnerSlots.Wrapper), "The wrapper of the circles."),
+        new(nameof(SpinnerSlots.Label), "The label associated with the spinner."),
+        new(nameof(SpinnerSlots.Circle1), "The first animated circle in circular spinner variants."),
+        new(nameof(SpinnerSlots.Circle2), "The second animated circle in circular spinner variants."),
+        new(nameof(SpinnerSlots.Dots), "A set of animated dots used in dot-based spinner variants."),
+        new(nameof(SpinnerSlots.Bars), "A set of animated bars used in bar-based spinner variants."),
+    };
+
+    private readonly string[] _apiComponents = new string[]
+    {
+        nameof(LumexSpinner)
+    };
+
+    protected override void OnInitialized()
+    {
+        Layout.Initialize(
+            title: "Spinner",
+            category: "Components",
+            description: "Spinners indicate loading states with a visual cue.",
+            headings: _headings,
+            linksProps: new ComponentLinksProps( "Spinner", isServer: true )
+        );
+    }
+}
diff --git a/docs/LumexUI.Docs/Components/App.razor b/docs/LumexUI.Docs/Components/App.razor
@@ -5,14 +5,14 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <base href="/" />
-    @* <link href="css/docs.css" rel="stylesheet" /> *@
-    <link href="@Assets["css/docs-tw4.css"]" rel="stylesheet" />
+    <link href="css/docs.css" rel="stylesheet" />
     <link rel="icon" type="image/png" href="favicon.png" />
     <PageTitle>LumexUI - A versatile Blazor UI library built using Tailwind CSS</PageTitle>
+    <ImportMap />
     <HeadOutlet />
 </head>
 
-<body class="bg-background text-foreground">
+<body>
     <div id="app">
         <Routes />
     </div>
diff --git a/docs/LumexUI.Docs/LumexUI.Docs.csproj b/docs/LumexUI.Docs/LumexUI.Docs.csproj
@@ -47,9 +47,14 @@
 		<Exec Command="chmod +x tailwindcss" Condition="'$(OS)' != 'Windows_NT'" />
 	</Target>
 
-	<Target Name="TailwindCSS" AfterTargets="InstallTailwindCSS">
-		<Exec Command="tailwindcss -i ./Styles/globals.css -o ./wwwroot/css/docs-tw4.css" Condition="'$(OS)' == 'Windows_NT'" />
-		<Exec Command="./tailwindcss -i ./Styles/globals.css -o ./wwwroot/css/docs-tw4.css" Condition="'$(OS)' != 'Windows_NT'" />
+	<Target Name="TailwindCSS-Dev" AfterTargets="InstallTailwindCSS" Condition="'$(Configuration)' == 'Debug'">
+		<Exec Command="tailwindcss -i ./Styles/globals.css -o ./wwwroot/css/docs.css" Condition="'$(OS)' == 'Windows_NT'" />
+		<Exec Command="./tailwindcss -i ./Styles/globals.css -o ./wwwroot/css/docs.css" Condition="'$(OS)' != 'Windows_NT'" />
+	</Target>
+
+	<Target Name="TailwindCSS-Prod" AfterTargets="InstallTailwindCSS" Condition="'$(Configuration)' == 'Release'">
+		<Exec Command="tailwindcss -i ./Styles/globals.css -o ./wwwroot/css/docs.css --minify" Condition="'$(OS)' == 'Windows_NT'" />
+		<Exec Command="./tailwindcss -i ./Styles/globals.css -o ./wwwroot/css/docs.css --minify" Condition="'$(OS)' != 'Windows_NT'" />
 	</Target>
 
 </Project>
diff --git a/docs/LumexUI.Docs/Program.cs b/docs/LumexUI.Docs/Program.cs
@@ -37,9 +37,9 @@
 
 app.UseHttpsRedirection();
 
-app.UseStaticFiles();
 app.UseAntiforgery();
 
+app.MapStaticAssets();
 app.MapRazorComponents<App>()
     .AddInteractiveWebAssemblyRenderMode()
     .AddAdditionalAssemblies( typeof( LumexUI.Docs.Client._Imports ).Assembly );
diff --git a/src/LumexUI/Common/Enums/SpinnerVariant.cs b/src/LumexUI/Common/Enums/SpinnerVariant.cs
@@ -0,0 +1,23 @@
+﻿// 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>
+/// Specifies the visual variants for the <see cref="LumexSpinner"/>.
+/// </summary>
+public enum SpinnerVariant
+{
+	Ring,
+
+	Arc,
+
+	ArcGradient,
+
+	DotsWave,
+
+	DotsFade,
+
+	Classic
+}
diff --git a/src/LumexUI/Components/Spinner/LumexSpinner.razor b/src/LumexUI/Components/Spinner/LumexSpinner.razor
@@ -0,0 +1,99 @@
+﻿@namespace LumexUI
+@inherits LumexComponentBase
+
+@using S = SpinnerSlots;
+
+@if( Variant is SpinnerVariant.DotsWave or SpinnerVariant.DotsFade )
+{
+    <div class="@GetStyles(nameof(S.Base))"
+         style="@Style"
+         data-slot="base"
+         aria-label="@AriaLabel"
+         @attributes="@AdditionalAttributes">
+        <div class="@GetStyles(nameof(S.Wrapper))" data-slot="wrapper">
+            @foreach( var index in Enumerable.Range( 0, 3 ) )
+            {
+                <span class="@GetStyles(nameof(S.Dots))"
+                      style="--index: @index"
+                      data-slot="dots" />
+            }
+        </div>
+
+        @_renderLabel
+    </div>
+}
+else if( Variant is SpinnerVariant.Ring )
+{
+    <div class="@GetStyles(nameof(S.Base))"
+         style="@Style"
+         data-slot="base"
+         aria-label="@AriaLabel"
+         @attributes="@AdditionalAttributes">
+        <svg class="@GetStyles(nameof(S.Wrapper))"
+             viewBox="0 0 24 24"
+             fill="none"
+             data-slot="wrapper">
+            <circle class="@GetStyles(nameof(S.Circle1))"
+                    cx="12"
+                    cy="12"
+                    r="10"
+                    stroke="currentColor"
+                    stroke-width="4"
+                    data-slot="circle1" />
+            <path class="@GetStyles(nameof(S.Circle2))"
+                  d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+                  fill="currentColor"
+                  data-slot="circle2" />
+        </svg>
+
+        @_renderLabel
+    </div>
+}
+else if( Variant is SpinnerVariant.Classic )
+{
+    <div class="@GetStyles(nameof(S.Base))"
+         style="@Style"
+         data-slot="base"
+         aria-label="@AriaLabel"
+         @attributes="@AdditionalAttributes">
+        <div class="@GetStyles(nameof(S.Wrapper))" data-slot="wrapper">
+            @foreach( var index in Enumerable.Range( 0, 12 ) )
+            {
+                <span class="@GetStyles(nameof(S.Bars))"
+                      style="--index: @index"
+                      data-slot="bars" />
+            }
+        </div>
+
+        @_renderLabel
+    </div>
+}
+else
+{
+    <div class="@GetStyles(nameof(S.Base))"
+         style="@Style"
+         data-slot="base"
+         aria-label="@AriaLabel"
+         @attributes="@AdditionalAttributes">
+        <div class="@GetStyles(nameof(S.Wrapper))" data-slot="wrapper">
+            <span class="@GetStyles(nameof(S.Circle1))" data-slot="circle1" />
+            <span class="@GetStyles(nameof(S.Circle2))" data-slot="circle2" />
+        </div>
+
+        @_renderLabel
+    </div>
+}
+
+@code {
+    private void RenderLabel( RenderTreeBuilder __builder )
+    {
+        if( string.IsNullOrEmpty( Label ) && ChildContent is null )
+        {
+            return;
+        }
+
+        <span class="@GetStyles(nameof(S.Label))" data-slot="label">
+            @(string.IsNullOrEmpty( Label ) ? ChildContent : Label)
+        </span>
+    }
+}
diff --git a/src/LumexUI/Components/Spinner/LumexSpinner.razor.cs b/src/LumexUI/Components/Spinner/LumexSpinner.razor.cs
diff --git a/src/LumexUI/Components/Spinner/SpinnerSlots.cs b/src/LumexUI/Components/Spinner/SpinnerSlots.cs
diff --git a/src/LumexUI/Styles/Spinner.cs b/src/LumexUI/Styles/Spinner.cs
diff --git a/src/LumexUI/Styles/_theme.css b/src/LumexUI/Styles/_theme.css
diff --git a/src/LumexUI/Utilities/Variants/TwVariants.cs b/src/LumexUI/Utilities/Variants/TwVariants.cs
diff --git a/tests/LumexUI.Tests/Components/Spinner/SpinnerTests.razor b/tests/LumexUI.Tests/Components/Spinner/SpinnerTests.razor

Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@`
`24`	`24`
`25`	`25`	`private readonly Slots _slots = new()`
`26`	`26`	`{`
`27`		`- Preview = "relative flex flex-wrap items-center gap-4",`
	`27`	`+ Preview = "relative flex flex-wrap items-center gap-4 overflow-x-auto scrollbar-hide",`
`28`	`28`	`PreviewWrapper = "relative p-8 rounded-xl bg-zinc-50 ring ring-foreground-900/10 not-prose",`
`29`	`29`	`Background = "absolute inset-0 [mask-image:radial-gradient(#fff_0%,transparent_100%)]",`
`30`	`30`	`};`
Original file line number	Diff line number	Diff line change
`@@ -41,7 +41,6 @@`
`41`	`41`
`42`	`42`	`private readonly Heading[] _headings = new Heading[]`
`43`	`43`	`{`
`44`		`- new("Composition"),`
`45`	`44`	`new("Usage", [`
`46`	`45`	`new("Standalone"),`
`47`	`46`	`new("Loading")`