sv5ui 1.1.2 → 1.2.0

package/README.md

@@ -9,10 +9,16 @@
   Built with Tailwind CSS 4, OKLCH color tokens, and accessible headless primitives.
 </p>
 
+<p align="center">
+  <a href="https://sv5ui.vercel.app/docs"><strong>Documentation</strong></a> · <a href="https://sv5ui.vercel.app"><strong>Live Demo</strong></a>
+</p>
+
 <p align="center">
   <a href="https://www.npmjs.com/package/sv5ui"><img src="https://img.shields.io/npm/v/sv5ui.svg?style=flat-square&colorA=18181b&colorB=ff3e00" alt="npm version" /></a>
   <a href="https://github.com/ndlabdev/sv5ui/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/sv5ui.svg?style=flat-square&colorA=18181b&colorB=ff3e00" alt="license" /></a>
   <a href="https://www.npmjs.com/package/sv5ui"><img src="https://img.shields.io/npm/dm/sv5ui.svg?style=flat-square&colorA=18181b&colorB=ff3e00" alt="downloads" /></a>
+  <a href="https://svelte.dev"><img src="https://img.shields.io/badge/svelte-5-ff3e00?style=flat-square&logo=svelte&logoColor=white" alt="Svelte 5" /></a>
+  <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/types-TypeScript-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
 </p>
 
 ---

package/dist/Alert/Alert.svelte

@@ -15,6 +15,7 @@
     const icons = getComponentConfig('icons', iconsDefaults)
 
     let {
+        ref = $bindable(null),
         as = 'div',
         ui,
         title,
@@ -24,7 +25,7 @@
         color = config.defaultVariants.color,
         variant = config.defaultVariants.variant,
         orientation = config.defaultVariants.orientation,
-        open = true,
+        open = $bindable(true),
         close = false,
         closeIcon,
         actions,
@@ -41,7 +42,7 @@
     const resolvedCloseIcon = $derived(closeIcon ?? icons.close)
 
     const classes = $derived.by(() => {
-        const slots = alertVariants({ variant, color, orientation })
+        const slots = alertVariants({ variant, color, orientation, title: !!title })
         return {
             root: slots.root({ class: [config.slots.root, className, ui?.root] }),
             wrapper: slots.wrapper({ class: [config.slots.wrapper, ui?.wrapper] }),
@@ -54,19 +55,31 @@
         }
     })
 
-    const closeButtonProps = $derived.by(() => {
-        if (!close) return null
-        if (close === true) return {}
-        return close
-    })
+    const closeButtonProps = $derived(!close ? null : close === true ? {} : close)
+
+    const isVertical = $derived(orientation === 'vertical')
+    const hasActions = $derived(!!actionsSlot || (actions && actions.length > 0))
 
     function handleClose() {
+        open = false
         onClose?.()
     }
 </script>
 
+{#snippet actionsContent()}
+    {#if actionsSlot}
+        {@render actionsSlot()}
+    {:else if actions && actions.length > 0}
+        <div class={classes.actions}>
+            {#each actions as action, index (index)}
+                <Button size="xs" {...action} />
+            {/each}
+        </div>
+    {/if}
+{/snippet}
+
 {#if open}
-    <svelte:element this={as} class={classes.root} role="alert" {...restProps}>
+    <svelte:element this={as} bind:this={ref} class={classes.root} role="alert" {...restProps}>
         {#if leading}
             {@render leading()}
         {:else if icon}
@@ -75,7 +88,7 @@
             <Avatar {...avatar} class={classes.avatar} />
         {/if}
 
-        {#if title || description || titleSlot || descriptionSlot}
+        {#if title || description || titleSlot || descriptionSlot || (isVertical && hasActions)}
             <div class={classes.wrapper}>
                 {#if titleSlot}
                     {@render titleSlot()}
@@ -88,17 +101,15 @@
                 {:else if description}
                     <div class={classes.description}>{description}</div>
                 {/if}
+
+                {#if isVertical}
+                    {@render actionsContent()}
+                {/if}
             </div>
         {/if}
 
-        {#if actionsSlot}
-            {@render actionsSlot()}
-        {:else if actions && actions.length > 0}
-            <div class={classes.actions}>
-                {#each actions as action, index (index)}
-                    <Button size="xs" {...action} />
-                {/each}
-            </div>
+        {#if !isVertical}
+            {@render actionsContent()}
         {/if}
 
         {#if closeSlot}
@@ -107,13 +118,13 @@
             </div>
         {:else if closeButtonProps}
             <Button
-                icon={resolvedCloseIcon}
-                variant="link"
-                color="surface"
+                {...closeButtonProps}
+                icon={closeButtonProps.icon ?? resolvedCloseIcon}
+                variant={closeButtonProps.variant ?? 'link'}
+                color={closeButtonProps.color ?? 'surface'}
                 class={classes.close}
                 onclick={handleClose}
-                aria-label="Close alert"
-                {...closeButtonProps}
+                aria-label={closeButtonProps['aria-label'] ?? 'Close alert'}
             />
         {/if}
     </svelte:element>

package/dist/Alert/Alert.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { AlertProps } from './alert.types.js';
 export type Props = AlertProps;
-declare const Alert: import("svelte").Component<AlertProps, {}, "">;
+declare const Alert: import("svelte").Component<AlertProps, {}, "ref" | "open">;
 type Alert = ReturnType<typeof Alert>;
 export default Alert;

package/dist/Alert/alert.types.d.ts

@@ -5,6 +5,10 @@ import type { AlertVariantProps, AlertSlots } from './alert.variants.js';
 import type { AvatarProps } from '../Avatar/avatar.types.js';
 import type { ButtonProps } from '../Button/button.types.js';
 export type AlertProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'title'> & {
+    /**
+     * Bindable reference to the root DOM element.
+     */
+    ref?: HTMLElement | null;
     /**
      * The HTML element to render as.
      * @default 'div'

package/dist/Avatar/Avatar.svelte

@@ -1,26 +1,16 @@
 <script lang="ts" module>
-    import type { AvatarProps, AvatarSize } from './avatar.types.js'
+    import type { AvatarProps, AvatarSize, AvatarRounded } from './avatar.types.js'
 
     export type Props = AvatarProps
-
-    const SIZE_PX: Record<AvatarSize, number> = {
-        '3xs': 16,
-        '2xs': 20,
-        xs: 24,
-        sm: 28,
-        md: 32,
-        lg: 36,
-        xl: 40,
-        '2xl': 44,
-        '3xl': 48
-    }
 </script>
 
 <script lang="ts">
     import { Avatar } from 'bits-ui'
-    import { avatarVariants, avatarDefaults } from './avatar.variants.js'
+    import { avatarVariants, avatarDefaults, avatarSizePx } from './avatar.variants.js'
     import { getComponentConfig } from '../config.js'
     import { getContext } from 'svelte'
+    import Icon from '../Icon/Icon.svelte'
+    import Chip from '../Chip/Chip.svelte'
 
     const config = getComponentConfig('avatar', avatarDefaults)
 
@@ -29,60 +19,96 @@
         src,
         alt,
         size,
+        rounded,
         text,
+        icon,
+        chip,
+        loading,
         delayMs = 0,
         class: className,
         ui,
+        fallback: fallbackSnippet,
         children,
         ...restProps
     }: Props = $props()
 
-    const groupContext = getContext<{ size: AvatarSize; baseClass: string } | undefined>(
-        'avatarGroup'
-    )
+    const groupContext = getContext<
+        { size: AvatarSize; rounded: AvatarRounded; baseClass: string } | undefined
+    >('avatarGroup')
 
     const resolvedSize = $derived(size ?? groupContext?.size ?? config.defaultVariants.size ?? 'md')
-    const sizePx = $derived(SIZE_PX[resolvedSize])
+    const resolvedRounded = $derived(
+        rounded ?? groupContext?.rounded ?? config.defaultVariants.rounded ?? 'full'
+    )
+    const sizePx = $derived(avatarSizePx[resolvedSize])
 
     const initials = $derived(
-        text ||
-            (alt
-                ? alt
-                      .split(' ')
-                      .slice(0, 2)
-                      .map((w) => w[0])
-                      .join('')
-                      .toUpperCase()
-                : '')
+        text !== undefined
+            ? text
+            : alt
+              ? alt
+                    .split(' ')
+                    .filter(Boolean)
+                    .slice(0, 2)
+                    .map((w) => w[0])
+                    .join('')
+                    .toUpperCase()
+              : ''
+    )
+
+    const chipProps = $derived(
+        chip === true
+            ? { inset: true as const }
+            : chip
+              ? { inset: true as const, ...chip }
+              : undefined
     )
 
     const classes = $derived.by(() => {
-        const slots = avatarVariants({ size: resolvedSize })
+        const slots = avatarVariants({ size: resolvedSize, rounded: resolvedRounded })
         return {
             root: slots.root({
                 class: [config.slots.root, groupContext?.baseClass, className, ui?.root]
             }),
             image: slots.image({ class: [config.slots.image, ui?.image] }),
-            fallback: slots.fallback({ class: [config.slots.fallback, ui?.fallback] })
+            fallback: slots.fallback({ class: [config.slots.fallback, ui?.fallback] }),
+            icon: slots.icon({ class: [config.slots.icon, ui?.icon] })
         }
     })
 </script>
 
-<Avatar.Root bind:ref class={classes.root} {delayMs} {...restProps}>
-    {#if children}
-        {@render children()}
-    {:else}
-        {#if src}
-            <Avatar.Image
-                {src}
-                alt={alt ?? ''}
-                class={classes.image}
-                width={sizePx}
-                height={sizePx}
-            />
+{#snippet avatarContent()}
+    <Avatar.Root {...restProps} bind:ref class={classes.root} {delayMs}>
+        {#if children}
+            {@render children()}
+        {:else}
+            {#if src}
+                <Avatar.Image
+                    {src}
+                    alt={alt ?? ''}
+                    class={classes.image}
+                    width={sizePx}
+                    height={sizePx}
+                    {loading}
+                />
+            {/if}
+            <Avatar.Fallback class={classes.fallback}>
+                {#if fallbackSnippet}
+                    {@render fallbackSnippet()}
+                {:else if initials}
+                    {initials}
+                {:else if icon}
+                    <Icon name={icon} class={classes.icon} />
+                {/if}
+            </Avatar.Fallback>
         {/if}
-        <Avatar.Fallback class={classes.fallback}>
-            {initials}
-        </Avatar.Fallback>
-    {/if}
-</Avatar.Root>
+    </Avatar.Root>
+{/snippet}
+
+{#if chipProps}
+    <Chip {...chipProps}>
+        {@render avatarContent()}
+    </Chip>
+{:else}
+    {@render avatarContent()}
+{/if}

package/dist/Avatar/avatar.types.d.ts

@@ -1,14 +1,23 @@
 import type { Snippet } from 'svelte';
 import type { Avatar } from 'bits-ui';
 import type { ClassNameValue } from 'tailwind-merge';
-import type { AvatarVariantProps, AvatarSlots } from './avatar.variants.js';
-export type AvatarSize = NonNullable<AvatarVariantProps['size']>;
+import type { AvatarVariantProps, AvatarSize, AvatarSlots } from './avatar.variants.js';
+import type { ChipProps } from '../Chip/chip.types.js';
+export type { AvatarSize };
+export type AvatarRounded = NonNullable<AvatarVariantProps['rounded']>;
+export type AvatarChipProps = Pick<ChipProps, 'color' | 'size' | 'position' | 'inset' | 'show' | 'text'>;
 export type AvatarProps = Omit<Avatar.RootProps, 'children'> & {
     /**
      * Controls the dimensions of the avatar.
      * @default 'md'
      */
     size?: AvatarSize;
+    /**
+     * Controls the border radius of the avatar.
+     * Use `'lg'`, `'md'`, `'sm'` for square-ish avatars (e.g. organization logos).
+     * @default 'full'
+     */
+    rounded?: AvatarRounded;
     /**
      * URL of the image to display.
      * The image will be shown once it loads successfully.
@@ -24,6 +33,25 @@ export type AvatarProps = Omit<Avatar.RootProps, 'children'> & {
      * Overrides auto-generated initials from `alt`.
      */
     text?: string;
+    /**
+     * Iconify icon name to display as fallback when no image or text is available.
+     * @example 'lucide:user', 'mdi:account'
+     */
+    icon?: string;
+    /**
+     * Renders a Chip indicator on the avatar.
+     * Pass `true` for default chip, or an object to customize.
+     * @example true
+     * @example { color: 'success' }
+     * @example { color: 'error', position: 'bottom-right' }
+     */
+    chip?: boolean | AvatarChipProps;
+    /**
+     * Image loading strategy.
+     * Use `'lazy'` for avatars below the fold to improve page load performance.
+     * @default 'eager'
+     */
+    loading?: 'lazy' | 'eager';
     /**
      * Additional CSS classes for the root element.
      */
@@ -32,9 +60,14 @@ export type AvatarProps = Omit<Avatar.RootProps, 'children'> & {
      * Override styles for specific avatar slots.
      */
     ui?: Partial<Record<AvatarSlots, ClassNameValue>>;
+    /**
+     * Custom fallback content to render when the image is unavailable.
+     * Overrides text, initials, and icon fallback.
+     */
+    fallback?: Snippet;
     /**
      * Custom content to render inside the avatar.
-     * When provided, overrides image, text, and icon.
+     * When provided, overrides the entire avatar content (image + fallback).
      */
     children?: Snippet;
 };

package/dist/Avatar/avatar.variants.d.ts

@@ -3,176 +3,314 @@ export declare const avatarVariants: import("tailwind-variants").TVReturnType<{
     size: {
         '3xs': {
             root: string;
+            icon: string;
         };
         '2xs': {
             root: string;
+            icon: string;
         };
         xs: {
             root: string;
+            icon: string;
         };
         sm: {
             root: string;
+            icon: string;
         };
         md: {
             root: string;
+            icon: string;
         };
         lg: {
             root: string;
+            icon: string;
         };
         xl: {
             root: string;
+            icon: string;
         };
         '2xl': {
             root: string;
+            icon: string;
         };
         '3xl': {
             root: string;
+            icon: string;
+        };
+    };
+    rounded: {
+        full: {
+            root: string;
+        };
+        lg: {
+            root: string;
+        };
+        md: {
+            root: string;
+        };
+        sm: {
+            root: string;
+        };
+        none: {
+            root: string;
         };
     };
 }, {
     root: string;
     image: string;
     fallback: string;
+    icon: string;
 }, undefined, {
     size: {
         '3xs': {
             root: string;
+            icon: string;
         };
         '2xs': {
             root: string;
+            icon: string;
         };
         xs: {
             root: string;
+            icon: string;
         };
         sm: {
             root: string;
+            icon: string;
         };
         md: {
             root: string;
+            icon: string;
         };
         lg: {
             root: string;
+            icon: string;
         };
         xl: {
             root: string;
+            icon: string;
         };
         '2xl': {
             root: string;
+            icon: string;
         };
         '3xl': {
             root: string;
+            icon: string;
+        };
+    };
+    rounded: {
+        full: {
+            root: string;
+        };
+        lg: {
+            root: string;
+        };
+        md: {
+            root: string;
+        };
+        sm: {
+            root: string;
+        };
+        none: {
+            root: string;
         };
     };
 }, {
     root: string;
     image: string;
     fallback: string;
+    icon: string;
 }, import("tailwind-variants").TVReturnType<{
     size: {
         '3xs': {
             root: string;
+            icon: string;
         };
         '2xs': {
             root: string;
+            icon: string;
         };
         xs: {
             root: string;
+            icon: string;
         };
         sm: {
             root: string;
+            icon: string;
         };
         md: {
             root: string;
+            icon: string;
         };
         lg: {
             root: string;
+            icon: string;
         };
         xl: {
             root: string;
+            icon: string;
         };
         '2xl': {
             root: string;
+            icon: string;
         };
         '3xl': {
             root: string;
+            icon: string;
+        };
+    };
+    rounded: {
+        full: {
+            root: string;
+        };
+        lg: {
+            root: string;
+        };
+        md: {
+            root: string;
+        };
+        sm: {
+            root: string;
+        };
+        none: {
+            root: string;
         };
     };
 }, {
     root: string;
     image: string;
     fallback: string;
+    icon: string;
 }, undefined, unknown, unknown, undefined>>;
 export type AvatarVariantProps = VariantProps<typeof avatarVariants>;
+export type AvatarSize = NonNullable<AvatarVariantProps['size']>;
 export type AvatarSlots = keyof ReturnType<typeof avatarVariants>;
+/** Tailwind size-4 through size-12 → (4 + index) × 4 pixels */
+export declare const avatarSizePx: Record<AvatarSize, number>;
 export declare const avatarDefaults: {
     defaultVariants: import("tailwind-variants").TVDefaultVariants<{
         size: {
             '3xs': {
                 root: string;
+                icon: string;
             };
             '2xs': {
                 root: string;
+                icon: string;
             };
             xs: {
                 root: string;
+                icon: string;
             };
             sm: {
                 root: string;
+                icon: string;
             };
             md: {
                 root: string;
+                icon: string;
             };
             lg: {
                 root: string;
+                icon: string;
             };
             xl: {
                 root: string;
+                icon: string;
             };
             '2xl': {
                 root: string;
+                icon: string;
             };
             '3xl': {
                 root: string;
+                icon: string;
+            };
+        };
+        rounded: {
+            full: {
+                root: string;
+            };
+            lg: {
+                root: string;
+            };
+            md: {
+                root: string;
+            };
+            sm: {
+                root: string;
+            };
+            none: {
+                root: string;
             };
         };
     }, {
         root: string;
         image: string;
         fallback: string;
+        icon: string;
     }, {
         size: {
             '3xs': {
                 root: string;
+                icon: string;
             };
             '2xs': {
                 root: string;
+                icon: string;
             };
             xs: {
                 root: string;
+                icon: string;
             };
             sm: {
                 root: string;
+                icon: string;
             };
             md: {
                 root: string;
+                icon: string;
             };
             lg: {
                 root: string;
+                icon: string;
             };
             xl: {
                 root: string;
+                icon: string;
             };
             '2xl': {
                 root: string;
+                icon: string;
             };
             '3xl': {
                 root: string;
+                icon: string;
+            };
+        };
+        rounded: {
+            full: {
+                root: string;
+            };
+            lg: {
+                root: string;
+            };
+            md: {
+                root: string;
+            };
+            sm: {
+                root: string;
+            };
+            none: {
+                root: string;
             };
         };
     }, {
         root: string;
         image: string;
         fallback: string;
+        icon: string;
     }>;
     slots: Partial<Record<AvatarSlots, string>>;
 };