v2.0.0 preview.3 (#206)

* fix(theme): remove extra shade (950) from the color scales for consistency in dark mode (#199)

* fix(theme): remove extra key (950) from the color scales for consistency in dark mode

* build(docs): explicitly set Tailwind v4.0.9

* feat(components): introduce Avatar and AvatarGroup components (#201)

* feat: add baseline implementation

* feat: add slots

* feat: add basic slots styles

* feat: add appearance params, such as `Color`, `Radius`, `Size`

* feat: add `Bordered` and `Disabled` params

* feat: add compound variants styles

* feat: apply slots styles

* docs: add baseline examples page

* feat: add `data-loaded` attribute on img

* feat: add `ShowFallback` parameter

* chore: fix compound style variants

* chore: set `showFallback` on after first render

* feat(utils): add implicit cast to string for the `ElementClass`

* feat: add LumexAvatarGroup component

* feat: take into account when LumexAvatar is rendered inside the LumexAvatarGroup

* feat: add `AvatarClasses` parameter in the avatar group component

* docs: add Avatar page

* build(docs): explicitly set Tailwind v4.0.9

* test: add tests for LumexAvatar and LumexAvatarGroup components

* chore: simplify condition for fallback render

* fix(docs): replace usages of `-foreground-950` CSS classes with `-foreground-900`

* fix(docs): remove `dark:prose-invert` CSS class until dark theme is properly configured

* feat(components): introduce Skeleton component (#202)

* feat(skeleton): add baseline implementation of the component

* feat(skeleton): add slots and styles

* feat(skeleton): add XML summaries

* fix(skeleton): return back `after` pseudo CSS classes to prevent flickering on state change

* docs(skeleton): add Skeleton page

* test(skeleton): add tests

* docs(skeleton): fix Loading example button text

* fix(navbar): add a check before toggling navbar menu on navigation (#204)

* v2.0.0-preview.3

Author: desmondinho

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

@@ -23,14 +23,15 @@ public class NavigationStore
 	private static NavigationCategory ComponentsCategory =>
 		new NavigationCategory( "Components", Icons.Rounded.Joystick )
 			.Add( new( nameof( LumexAccordion ) ) )
+			.Add( new( nameof( LumexAvatar ), ComponentStatus.New ) )
 			.Add( new( nameof( LumexButton ) ) )
 			.Add( new( nameof( LumexCard ) ) )
 			.Add( new( nameof( LumexCheckbox ) ) )
 			.Add( new( nameof( LumexCheckboxGroup ) ) )
 			.Add( new( nameof( LumexCollapse ) ) )
 			.Add( new( nameof( LumexDataGrid<T> ) ) )
 			.Add( new( nameof( LumexDivider ) ) )
-			.Add( new( nameof( LumexDropdown ), ComponentStatus.New ) )
+			.Add( new( nameof( LumexDropdown ) ) )
 			.Add( new( nameof( LumexIcon ) ) )
 			.Add( new( nameof( LumexLink ) ) )
 			.Add( new( nameof( LumexListbox<T> ) ) )
@@ -39,14 +40,17 @@ public class NavigationStore
 			.Add( new( nameof( LumexPopover ) ) )
 			.Add( new( nameof( LumexRadioGroup<T> ) ) )
 			.Add( new( nameof( LumexSelect<T> ) ) )
+			.Add( new( nameof( LumexSkeleton ), ComponentStatus.New ) )
 			.Add( new( nameof( LumexSwitch ) ) )
-			.Add( new( nameof( LumexTabs ), ComponentStatus.New ) )
+			.Add( new( nameof( LumexTabs ) ) )
 			.Add( new( nameof( LumexTextbox ) ) );
 
 	private static NavigationCategory ComponentsApiCategory =>
 		new NavigationCategory( "Components API", Icons.Rounded.Manufacturing )
 			.Add( new( nameof( LumexAccordion ) ) )
 			.Add( new( nameof( LumexAccordionItem ) ) )
+			.Add( new( nameof( LumexAvatar ) ) )
+			.Add( new( nameof( LumexAvatarGroup ) ) )
 			//.Add( nameof( LumexBooleanInputBase ) )
 			.Add( new( nameof( LumexButton ) ) )
 			.Add( new( nameof( LumexCard ) ) )
@@ -82,6 +86,7 @@ public class NavigationStore
 			.Add( new( nameof( LumexPopoverTrigger ) ) )
 			.Add( new( nameof( LumexSelect<T> ) ) )
 			.Add( new( nameof( LumexSelectItem<T> ) ) )
+			.Add( new( nameof( LumexSkeleton ) ) )
 			.Add( new( nameof( LumexSwitch ) ) )
 			.Add( new( nameof( LumexTab ) ) )
 			.Add( new( nameof( LumexTabs ) ) )

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

@@ -14,7 +14,7 @@
 
                     <LumexButton Color="@ThemeColor.None"
                                  Class="w-full min-w-fit h-auto p-0 justify-start gap-x-3 overflow-visible rounded-small sm:block sm:space-y-1">
-                        <div class="relative w-12 h-12 rounded-md ring ring-inset ring-foreground-950/10 sm:w-full"
+                        <div class="relative w-12 h-12 rounded-md ring ring-inset ring-foreground-900/15 sm:w-full"
                              style="background-color: @(color.Value + (isDivider ? "26" : default))">
 
                             <span class="absolute top-1 right-1.5 font-medium text-[0.625rem] leading-none"

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

@@ -8,7 +8,7 @@
                    Color="@ThemeColor.None"
                    Class="border-none">
             @Title
-            <span class="flex items-center justify-center size-6 ml-2 rounded-md text-foreground-400 shadow-xs ring ring-foreground-950/5 hover:ring-orange-200 hover:bg-orange-50 hover:text-orange-500">
+            <span class="flex items-center justify-center size-6 ml-2 rounded-md text-foreground-400 shadow-xs ring ring-foreground-900/10 hover:ring-orange-200 hover:bg-orange-50 hover:text-orange-500">
                 <LumexIcon Icon="@Icons.Rounded.Link"
                            Size="@new("16")" />
             </span>

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

@@ -5,12 +5,12 @@
     {
         foreach( var step in Steps )
         {
-            <li class="relative pl-10 pb-8 xl:grid xl:grid-cols-5 xl:gap-10 before:absolute before:content-[counter(step)] before:left-0 before:flex before:items-center before:justify-center before:size-6 before:text-[0.625rem] before:font-bold before:text-zinc-700 before:rounded-md before:shadow-xs before:ring before:ring-foreground-950/5 after:absolute after:top-8 after:bottom-0 after:left-3 after:w-px after:bg-divider" style="counter-increment: step;">
+            <li class="relative pl-10 pb-8 xl:grid xl:grid-cols-5 xl:gap-10 before:absolute before:content-[counter(step)] before:left-0 before:flex before:items-center before:justify-center before:size-6 before:text-[0.625rem] before:font-bold before:text-zinc-700 before:rounded-md before:shadow-xs before:ring before:ring-foreground-900/10 after:absolute after:top-8 after:bottom-0 after:left-3 after:w-px after:bg-divider" style="counter-increment: step;">
                 <div class="mb-6 xl:mb-0 xl:col-span-2">
                     <h4 class="text-sm leading-6 font-semibold mb-2">
                         @step.Title
                     </h4>
-                    <div class="prose prose-zinc prose-sm dark:prose-invert">
+                    <div class="prose prose-zinc prose-sm">
                         @step.Body
                     </div>
                 </div>

docs/LumexUI.Docs.Client/Components/Layouts/DocsContentLayout.razor

@@ -11,7 +11,7 @@
                     Description="@_description"
                     LinksProps="@_linksProps" />
 
-        <main class="mt-8 prose prose-zinc dark:prose-invert">
+        <main class="mt-8 prose prose-zinc">
             <LumexDivider />
 
             @Body

docs/LumexUI.Docs.Client/Components/Layouts/InstallationLayout.razor

@@ -10,7 +10,7 @@
                 Description="Follow the steps below to get started with LumexUI quickly!" />
 
     <main class="mt-8">
-        <div class="mb-8 prose prose-zinc dark:prose-invert">
+        <div class="mb-8 prose prose-zinc">
             <DocsSection Title="Prerequisites">
                 <p>Before you begin, ensure that you have the following:</p>
                 <ul>

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

@@ -25,7 +25,7 @@
     private readonly Slots _slots = new()
         {
             Preview = "relative flex flex-wrap items-center gap-4",
-            PreviewWrapper = "relative p-8 rounded-xl bg-zinc-50 ring ring-foreground-950/5 not-prose",
+            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%)]",
         };
 

docs/LumexUI.Docs.Client/Components/PreviewCode.razor.cs

@@ -16,7 +16,7 @@ public partial class PreviewCode
     private string? BaseClass => ElementClass.Empty()
         .Add( "rounded-2xl" )
         .Add( "ring" )
-        .Add( "ring-foreground-950/5" )
+        .Add( "ring-foreground-900/10" )
         .Add( "shadow-xs" )
         .Add( "overflow-hidden" )
         .Add( Class )
@@ -25,7 +25,7 @@ public partial class PreviewCode
     private string ToolbarClass => ElementClass.Empty()
         .Add( "p-2" )
         .Add( "border-t" )
-        .Add( "border-foreground-950/5" )
+        .Add( "border-foreground-900/10" )
         .Add( "border-b", when: _expanded )
         .Add( "rounded-b-xl", when: !_expanded )
         .ToString();

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

@@ -18,7 +18,7 @@
             @Description
         </p>
     </div>
-    <div class="absolute -z-10 -inset-3 rounded-2xl bg-gray-50 peer-hover:ring peer-hover:ring-foreground-950/5"></div>
+    <div class="absolute -z-10 -inset-3 rounded-2xl bg-gray-50 peer-hover:ring peer-hover:ring-foreground-900/10"></div>
 </li>
 
 @code {

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

@@ -0,0 +1,181 @@
+@page "/docs/components/avatar"
+@layout DocsContentLayout
+
+@using LumexUI.Docs.Client.Pages.Components.Avatar.PreviewCodes
+
+<DocsCompositionSection Components="@_compositionComponents" />
+
+<DocsSection Title="Usage">
+    <p>
+        The avatar component represents a user or entity 
+        with an image, initials, or a fallback icon.
+    </p>
+    <Usage />
+
+    <DocsSection Title="Bordered">
+        <p>Add a border around the avatar.</p>
+        <Bordered />
+    </DocsSection>
+
+    <DocsSection Title="Sizes">
+        <p>Customize the size of the avatar.</p>
+        <Sizes />
+    </DocsSection>
+
+    <DocsSection Title="Radius">
+        <p>Adjust the border radius to create circular or squared avatars.</p>
+        <Radii />
+    </DocsSection>
+
+    <DocsSection Title="Colors">
+        <p>Set a background and border color for avatar.</p>
+        <Colors />
+    </DocsSection>
+
+    <DocsSection Title="Fallbacks">
+        <p>When an image fails to load, a default fallback is displayed. There are 2 types of fallbacks:</p>
+        <ul>
+            <li>If a <Code>Name</Code> is provided, it is used to generate initials.</li>
+            <li>If no <Code>Name</Code> is provided, a default avatar icon is displayed.</li>
+        </ul>
+        <p>If <Code>ShowFallback</Code> is set to <Code>false</Code>, fallbacks will not be displayed.</p>
+        <Fallbacks />
+    </DocsSection>
+
+    <DocsSection Title="Custom Fallback">
+        <p>Use a custom content as a fallback when an image is unavailable.</p>
+        <CustomFallback />
+    </DocsSection>
+
+    <DocsSection Title="Custom Initials">
+        <p>
+            You can customize the logic for generating initials by passing a function to the <Code>Initials</Code> parameter.
+            By default, the initials are created by combining the first characters of each word in the <Code>Name</Code> parameter.
+        </p>
+    </DocsSection>
+</DocsSection>
+
+<DocsSection Title="Avatar Group">
+    <p>The avatar group component displays multiple avatars together.</p>
+    <GroupUsage />
+
+    <DocsSection Title="Max Count">
+        <p>Limit the number of avatars displayed, grouping the rest into a counter.</p>
+        <GroupMaxCount />
+    </DocsSection>
+
+    <DocsSection Title="Custom Count">
+        <p>Customize how the remaining avatars count is represented.</p>
+        <GroupCustomCount />
+    </DocsSection>
+
+    <DocsSection Title="Grid">
+        <p>Display avatars in a structured grid layout.</p>
+        <GroupGrid />
+    </DocsSection>
+</DocsSection>
+
+<DocsSection Title="Custom Styles">
+    <p>
+        This component suppots named slots (represented as <code>data-*</code> attributes) that
+        allow you to apply custom CSS to specific parts of the component.
+    </p>
+    @foreach( var (componentName, slots) in _slots )
+    {
+        <h4>@componentName</h4>
+        <ul>
+            @foreach( var slot in slots )
+            {
+                <li>
+                    <strong class="text-orange-500">@slot.Name:</strong> @slot.Description
+                </li>
+            }
+        </ul>
+    }
+    <p>
+        You can customize the component(s) by passing
+        any Tailwind CSS classes to the following component parameters:
+    </p>
+
+    <div>
+        <h4 class="font-semibold">Avatar</h4>
+        <ul>
+            <li><Code>Class</Code>: The CSS class names to style the avatar wrapper.</li>
+            <li><Code>Classes</Code>: The CSS class names to style the avatar slots.</li>
+        </ul>
+
+        <h4 class="font-semibold">Avatar Group</h4>
+        <ul>
+            <li><Code>Class</Code>: The CSS class names to style the avatar group wrapper.</li>
+            <li><Code>Classes</Code>: The CSS class names to style the avatar group slots.</li>
+            <li><Code>AvatarClasses</Code>: The CSS class names to style the avatars slots.</li>
+        </ul>
+    </div>
+    <CustomStyles />
+</DocsSection>
+
+<DocsApiSection Components="@_apiComponents" />
+
+@code {
+    [CascadingParameter] private DocsContentLayout Layout { get; set; } = default!;
+
+    private readonly CompositionComponent[] _compositionComponents = new CompositionComponent[]
+    {
+        new(nameof(LumexAvatar), "A component that represents an avatar."),
+        new(nameof(LumexAvatarGroup), "A component that represents a group of avatars.")
+    };
+
+    private readonly Heading[] _headings = new Heading[]
+    {
+        new("Composition"),
+        new("Usage", [
+            new("Bordered"),
+            new("Sizes"),
+            new("Radius"),
+            new("Colors"),
+            new("Fallbacks"),
+            new("Custom Fallback"),
+            new("Custom Initials"),
+        ]),
+        new("Avatar Group", [
+            new("Max Count"),
+            new("Custom Count"),
+            new("Grid")
+        ]),
+        new("Custom Styles"),
+        new("API")
+    };
+
+    private readonly Dictionary<string, Slot[]> _slots = new()
+    {
+        [nameof(LumexAvatar)] = [
+            new(nameof(AvatarSlots.Base), "The main container for the avatar component."),
+            new(nameof(AvatarSlots.Img), "The slot that holds the avatar image."),
+            new(nameof(AvatarSlots.Fallback), "Displays when the image is unavailable, showing initials or an icon."),
+            new(nameof(AvatarSlots.Name), "Represents the text or initials displayed inside the avatar."),
+            new(nameof(AvatarSlots.Icon), "The slot for a custom fallback icon when no image is provided.")
+        ],
+        [nameof(LumexAvatarGroup)] = [
+            new(nameof(AvatarGroupSlots.Base), "The main container for the avatar group."),
+            new(nameof(AvatarGroupSlots.Count), "Displays the number of hidden avatars when the max limit is reached.")
+        ]
+    };
+
+    private readonly string[] _apiComponents = new string[]
+    {
+        nameof(LumexAvatar),
+        nameof(LumexAvatarGroup),
+        nameof(LumexIcon)
+    };
+
+    protected override void OnInitialized()
+    {
+        Layout.Initialize(
+            title: "Avatar",
+            category: "Components",
+            description: "Avatars represent a user or entity using an image, initials, or a fallback icon.",
+            headings: _headings,
+            linksProps: new ComponentLinksProps( "Avatar", isServer: false )
+        );
+    }
+}

docs/LumexUI.Docs.Client/Pages/Components/Avatar/Examples/Bordered.razor

@@ -0,0 +1,8 @@
+<div class="flex gap-4 items-center">
+    <LumexAvatar Bordered="@true" Src="https://i.pravatar.cc/150?img=2" />
+    <LumexAvatar Bordered="@true" Name="Daniel" />
+    <LumexAvatar Bordered="@true" Src="https://i.pravatar.cc/150?img=6" />
+    <LumexAvatar Bordered="@true" Name="John Doe" />
+    <LumexAvatar Bordered="@true" Src="https://i.pravatar.cc/150?img=9" />
+    <LumexAvatar Bordered="@true" Name="Jane" />
+</div>

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

@@ -0,0 +1,23 @@
+<div class="flex gap-4 items-center">
+    <LumexAvatar Color="@ThemeColor.Default"
+                 Bordered="@true"
+                 Src="https://i.pravatar.cc/150?img=2" />
+    <LumexAvatar Color="@ThemeColor.Primary"
+                 Bordered="@true"
+                 Src="https://i.pravatar.cc/150?img=6" />
+    <LumexAvatar Color="@ThemeColor.Secondary"
+                 Bordered="@true"
+                 Src="https://i.pravatar.cc/150?img=9" />
+    <LumexAvatar Color="@ThemeColor.Success"
+                 Bordered="@true"
+                 Src="https://i.pravatar.cc/150?img=11" />
+    <LumexAvatar Color="@ThemeColor.Warning"
+                 Bordered="@true"
+                 Src="https://i.pravatar.cc/150?img=12" />
+    <LumexAvatar Color="@ThemeColor.Danger"
+                 Bordered="@true"
+                 Src="https://i.pravatar.cc/150?img=24" />
+    <LumexAvatar Color="@ThemeColor.Info"
+                 Bordered="@true"
+                 Src="https://i.pravatar.cc/150?img=43" />
+</div>

docs/LumexUI.Docs.Client/Pages/Components/Avatar/Examples/CustomFallback.razor

@@ -0,0 +1,10 @@
+<div class="flex gap-4 items-center">
+    <LumexAvatar Src="https://images.unsplash.com/broken">
+        <FallbackContent>
+            <LumexIcon Icon="@Icons.Rounded.PhotoCamera"
+                       Class="animate-pulse text-default-500" />
+        </FallbackContent>
+    </LumexAvatar>
+    <LumexAvatar Name="John Doe" Src="https://images.unsplash.com/broken" />
+    <LumexAvatar ShowFallback="@false" Name="Jane" Src="https://images.unsplash.com/broken" />
+</div>

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

@@ -0,0 +1,9 @@
+<LumexAvatar Icon="@Icons.Rounded.SupportAgent" Classes="@_classes" />
+
+@code {
+    private AvatarSlots _classes = new()
+    {
+        Base = "bg-gradient-to-br from-warning-200 to-warning-500",
+        Icon = "text-black/80"
+    };
+}

docs/LumexUI.Docs.Client/Pages/Components/Avatar/Examples/Fallbacks.razor

@@ -0,0 +1,5 @@
+<div class="flex gap-4 items-center">
+    <LumexAvatar Src="https://images.unsplash.com/broken" />
+    <LumexAvatar Name="John Doe" Src="https://images.unsplash.com/broken" />
+    <LumexAvatar ShowFallback="@false" Name="Jane" Src="https://images.unsplash.com/broken" />
+</div>

docs/LumexUI.Docs.Client/Pages/Components/Avatar/Examples/GroupCustomCount.razor

@@ -0,0 +1,13 @@
+<LumexAvatarGroup Max="3" Bordered="@true">
+    <CountContent Context="count">
+        <p class="text-small text-foreground font-medium ms-2">+@count others</p>
+    </CountContent>
+    <ChildContent>
+        <LumexAvatar Src="https://i.pravatar.cc/150?img=2" />
+        <LumexAvatar Src="https://i.pravatar.cc/150?img=6" />
+        <LumexAvatar Src="https://i.pravatar.cc/150?img=9" />
+        <LumexAvatar Src="https://i.pravatar.cc/150?img=11" />
+        <LumexAvatar Src="https://i.pravatar.cc/150?img=12" />
+        <LumexAvatar Src="https://i.pravatar.cc/150?img=24" />
+    </ChildContent>
+</LumexAvatarGroup>