@marianmeres/stuic 2.51.0 → 2.52.0

package/dist/components/Avatar/Avatar.svelte

@@ -0,0 +1,237 @@
+<script lang="ts" module>
+	export type IconFn = (opts?: { size?: number; class?: string }) => string;
+	export type AvatarFallback = "icon" | "initials" | { icon: IconFn } | { initials: string };
+
+	export interface Props {
+		/** Photo URL - when provided, renders in photo mode */
+		src?: string;
+		/** Alt text for photo mode */
+		alt?: string;
+		/** String to extract initials from. Supports: "AB", "John Doe", or "john.doe@example.com" */
+		initials?: string;
+		/** Icon function to display - when provided alone, renders in icon mode */
+		icon?: IconFn;
+		/** Fallback when photo fails to load. Defaults to "icon" */
+		fallback?: AvatarFallback;
+		/** Optional string for color hash calculation (e.g., email, user ID). Falls back to `initials` */
+		hashSource?: string;
+		/** Size preset or custom Tailwind size class */
+		size?: "sm" | "md" | "lg" | "xl" | string;
+		/** Click handler - when provided, renders as a button */
+		onclick?: (event: MouseEvent) => void;
+		/** Background color (Tailwind class). Ignored if autoColor=true */
+		bg?: string;
+		/** Text color (Tailwind class). Ignored if autoColor=true */
+		textColor?: string;
+		/** Generate deterministic pastel colors from hashSource/initials */
+		autoColor?: boolean;
+		/** CSS class override */
+		class?: string;
+		/** Bindable element reference */
+		el?: HTMLDivElement | HTMLButtonElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { generateAvatarColors } from "../../utils/avatar-colors.js";
+	import { iconUser as defaultIconUser } from "../../icons/index.js";
+
+	let {
+		src,
+		alt,
+		initials: initialsProp,
+		icon,
+		fallback = "icon",
+		hashSource,
+		size = "md",
+		onclick,
+		bg,
+		textColor,
+		autoColor = false,
+		class: classProp,
+		el = $bindable(),
+	}: Props = $props();
+
+	const SIZE_PRESETS: Record<string, { container: string; icon: number }> = {
+		sm: { container: "size-8 text-xs", icon: 16 },
+		md: { container: "size-10 text-sm", icon: 20 },
+		lg: { container: "size-14 text-base", icon: 28 },
+		xl: { container: "size-16 text-lg", icon: 32 },
+	};
+
+	// Image loading state
+	let imageError = $state(false);
+
+	// Reset image state when src changes
+	$effect(() => {
+		if (src) {
+			imageError = false;
+		}
+	});
+
+	// Extract initials from string
+	let extractedInitials = $derived.by(() => {
+		let _input = (initialsProp || "").trim();
+
+		if (!_input) return "?";
+
+		// Check if input looks like an email
+		if (_input.includes("@")) {
+			const username = _input.split("@")[0];
+			// Split by common separators (., _, -)
+			const parts = username.split(/[._+-]/).filter(Boolean);
+			if (parts.length > 1) {
+				_input = parts.map((p) => p.charAt(0)).join("");
+			} else {
+				_input = username;
+			}
+		}
+		// Check if input looks like a full name (multiple words)
+		else if (_input.length > 2 && /\s/.test(_input)) {
+			_input = _input
+				.split(/\s/)
+				.map((v) => v.trim())
+				.filter(Boolean)
+				.map((v) => v.charAt(0))
+				.join("");
+		}
+
+		// Extract first 2 chars, uppercase
+		return _input.slice(0, 2).toUpperCase();
+	});
+
+	// Determine the current render mode
+	let renderMode = $derived.by((): "photo" | "initials" | "icon" => {
+		// Photo mode (if src provided and no error)
+		if (src && !imageError) return "photo";
+
+		// Photo error - determine fallback
+		if (src && imageError) {
+			if (fallback === "initials") return "initials";
+			if (typeof fallback === "object" && "initials" in fallback) return "initials";
+			return "icon";
+		}
+
+		// No src - determine from other props
+		if (initialsProp) return "initials";
+		return "icon";
+	});
+
+	// Get fallback initials (from fallback prop or initialsProp)
+	let fallbackInitials = $derived.by(() => {
+		if (typeof fallback === "object" && "initials" in fallback) {
+			const _input = (fallback.initials || "").trim();
+			if (!_input) return "?";
+
+			// Apply same extraction logic
+			let result = _input;
+			if (_input.includes("@")) {
+				const username = _input.split("@")[0];
+				const parts = username.split(/[._+-]/).filter(Boolean);
+				if (parts.length > 1) {
+					result = parts.map((p) => p.charAt(0)).join("");
+				} else {
+					result = username;
+				}
+			} else if (_input.length > 2 && /\s/.test(_input)) {
+				result = _input
+					.split(/\s/)
+					.map((v) => v.trim())
+					.filter(Boolean)
+					.map((v) => v.charAt(0))
+					.join("");
+			}
+			return result.slice(0, 2).toUpperCase();
+		}
+		return extractedInitials;
+	});
+
+	// Get the icon to render
+	let iconToRender = $derived.by(() => {
+		// If fallback specifies a custom icon
+		if (imageError && typeof fallback === "object" && "icon" in fallback) {
+			return fallback.icon;
+		}
+		// Use provided icon or default
+		return icon || defaultIconUser;
+	});
+
+	// Get icon size based on preset or custom size
+	let iconSize = $derived.by(() => {
+		const preset = SIZE_PRESETS[size];
+		if (preset) return preset.icon;
+
+		// For custom sizes, try to parse size-N pattern
+		const match = size?.match(/size-(\d+)/);
+		if (match) {
+			// size-N = N * 4px, icon should be ~50%
+			return parseInt(match[1]) * 2;
+		}
+
+		return 20; // Default fallback
+	});
+
+	let colors = $derived(
+		autoColor ? generateAvatarColors(hashSource || initialsProp || "") : null
+	);
+
+	let sizeClass = $derived(SIZE_PRESETS[size]?.container || size);
+
+	let style = $derived(
+		autoColor && colors
+			? `background-color: ${colors.bg}; color: ${colors.text};`
+			: undefined
+	);
+
+	let baseClass = $derived(
+		twMerge(
+			"stuic-avatar",
+			"inline-flex items-center justify-center",
+			"rounded-full font-medium shrink-0 overflow-hidden",
+			!autoColor &&
+				"bg-neutral-200 text-neutral-700 dark:bg-neutral-700 dark:text-neutral-200",
+			sizeClass,
+			!autoColor && bg,
+			!autoColor && textColor,
+			onclick && "select-none cursor-pointer",
+			classProp
+		)
+	);
+
+	function handleImageError() {
+		imageError = true;
+	}
+</script>
+
+{#if onclick}
+	<button bind:this={el} type="button" class={baseClass} {style} {onclick}>
+		{#if renderMode === "photo"}
+			<img
+				{src}
+				{alt}
+				class="size-full object-cover"
+				onerror={handleImageError}
+			/>
+		{:else if renderMode === "initials"}
+			{fallbackInitials}
+		{:else}
+			{@html iconToRender({ size: iconSize })}
+		{/if}
+	</button>
+{:else}
+	<div bind:this={el} class={baseClass} {style}>
+		{#if renderMode === "photo"}
+			<img
+				{src}
+				{alt}
+				class="size-full object-cover"
+				onerror={handleImageError}
+			/>
+		{:else if renderMode === "initials"}
+			{fallbackInitials}
+		{:else}
+			{@html iconToRender({ size: iconSize })}
+		{/if}
+	</div>
+{/if}

package/dist/components/Avatar/Avatar.svelte.d.ts

@@ -0,0 +1,40 @@
+export type IconFn = (opts?: {
+    size?: number;
+    class?: string;
+}) => string;
+export type AvatarFallback = "icon" | "initials" | {
+    icon: IconFn;
+} | {
+    initials: string;
+};
+export interface Props {
+    /** Photo URL - when provided, renders in photo mode */
+    src?: string;
+    /** Alt text for photo mode */
+    alt?: string;
+    /** String to extract initials from. Supports: "AB", "John Doe", or "john.doe@example.com" */
+    initials?: string;
+    /** Icon function to display - when provided alone, renders in icon mode */
+    icon?: IconFn;
+    /** Fallback when photo fails to load. Defaults to "icon" */
+    fallback?: AvatarFallback;
+    /** Optional string for color hash calculation (e.g., email, user ID). Falls back to `initials` */
+    hashSource?: string;
+    /** Size preset or custom Tailwind size class */
+    size?: "sm" | "md" | "lg" | "xl" | string;
+    /** Click handler - when provided, renders as a button */
+    onclick?: (event: MouseEvent) => void;
+    /** Background color (Tailwind class). Ignored if autoColor=true */
+    bg?: string;
+    /** Text color (Tailwind class). Ignored if autoColor=true */
+    textColor?: string;
+    /** Generate deterministic pastel colors from hashSource/initials */
+    autoColor?: boolean;
+    /** CSS class override */
+    class?: string;
+    /** Bindable element reference */
+    el?: HTMLDivElement | HTMLButtonElement;
+}
+declare const Avatar: import("svelte").Component<Props, {}, "el">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;

package/dist/components/Avatar/index.d.ts

@@ -0,0 +1 @@
+export { default as Avatar, type Props as AvatarProps, type IconFn, type AvatarFallback, } from "./Avatar.svelte";

package/dist/components/Avatar/index.js

@@ -0,0 +1 @@
+export { default as Avatar, } from "./Avatar.svelte";

package/dist/icons/index.d.ts

@@ -34,3 +34,4 @@ export { iconLucideCheck as iconCheck } from "@marianmeres/icons-fns/lucide/icon
 export { iconLucideCircle as iconCircle } from "@marianmeres/icons-fns/lucide/iconLucideCircle.js";
 export { iconLucideSquare as iconSquare } from "@marianmeres/icons-fns/lucide/iconLucideSquare.js";
 export { iconLucideMenu as iconMenu } from "@marianmeres/icons-fns/lucide/iconLucideMenu.js";
+export { iconLucideUser as iconUser } from "@marianmeres/icons-fns/lucide/iconLucideUser.js";

package/dist/icons/index.js

@@ -38,3 +38,4 @@ export { iconLucideCheck as iconCheck } from "@marianmeres/icons-fns/lucide/icon
 export { iconLucideCircle as iconCircle } from "@marianmeres/icons-fns/lucide/iconLucideCircle.js";
 export { iconLucideSquare as iconSquare } from "@marianmeres/icons-fns/lucide/iconLucideSquare.js";
 export { iconLucideMenu as iconMenu } from "@marianmeres/icons-fns/lucide/iconLucideMenu.js";
+export { iconLucideUser as iconUser } from "@marianmeres/icons-fns/lucide/iconLucideUser.js";

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export * from "./components/AlertConfirmPrompt/index.js";
 export * from "./components/AnimatedElipsis/index.js";
 export * from "./components/AppShell/index.js";
 export * from "./components/AssetsPreview/index.js";
-export * from "./components/AvatarInitials/index.js";
+export * from "./components/Avatar/index.js";
 export * from "./components/Backdrop/index.js";
 export * from "./components/Button/index.js";
 export * from "./components/ButtonGroupRadio/index.js";

package/dist/index.js

@@ -26,7 +26,7 @@ export * from "./components/AlertConfirmPrompt/index.js";
 export * from "./components/AnimatedElipsis/index.js";
 export * from "./components/AppShell/index.js";
 export * from "./components/AssetsPreview/index.js";
-export * from "./components/AvatarInitials/index.js";
+export * from "./components/Avatar/index.js";
 export * from "./components/Backdrop/index.js";
 export * from "./components/Button/index.js";
 export * from "./components/ButtonGroupRadio/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marianmeres/stuic",
-  "version": "2.51.0",
+  "version": "2.52.0",
   "files": [
     "dist",
     "!dist/**/*.test.*",

package/dist/components/AvatarInitials/AvatarInitials.svelte

@@ -1,113 +0,0 @@
-<script lang="ts" module>
-	export interface Props {
-		/** String to extract initials from. Supports: "AB", "John Doe", or "john.doe@example.com" */
-		input: string;
-		/** Optional string for color hash calculation (e.g., email, user ID). Falls back to `input` */
-		hashSource?: string;
-		/** Size preset or custom Tailwind size class */
-		size?: "sm" | "md" | "lg" | "xl" | string;
-		/** Click handler - when provided, renders as a button */
-		onclick?: (event: MouseEvent) => void;
-		/** Background color (Tailwind class). Ignored if autoColor=true */
-		bg?: string;
-		/** Text color (Tailwind class). Ignored if autoColor=true */
-		textColor?: string;
-		/** Generate deterministic pastel colors from hashSource/input */
-		autoColor?: boolean;
-		/** CSS class override */
-		class?: string;
-		/** Bindable element reference */
-		el?: HTMLDivElement | HTMLButtonElement;
-	}
-</script>
-
-<script lang="ts">
-	import { twMerge } from "../../utils/tw-merge.js";
-	import { generateAvatarColors } from "../../utils/avatar-colors.js";
-
-	let {
-		input,
-		hashSource,
-		size = "md",
-		onclick,
-		bg,
-		textColor,
-		autoColor = false,
-		class: classProp,
-		el = $bindable(),
-	}: Props = $props();
-
-	const SIZE_PRESETS: Record<string, string> = {
-		sm: "size-8 text-xs",
-		md: "size-10 text-sm",
-		lg: "size-14 text-base",
-		xl: "size-16 text-lg",
-	};
-
-	let initials = $derived.by(() => {
-		let _input = (input || "").trim();
-
-		if (!_input) return "?";
-
-		// Check if input looks like an email
-		if (_input.includes("@")) {
-			const username = _input.split("@")[0];
-			// Split by common separators (., _, -)
-			const parts = username.split(/[._+-]/).filter(Boolean);
-			if (parts.length > 1) {
-				_input = parts.map((p) => p.charAt(0)).join("");
-			} else {
-				_input = username;
-			}
-		}
-		// Check if input looks like a full name (multiple words)
-		else if (_input.length > 2 && /\s/.test(_input)) {
-			_input = _input
-				.split(/\s/)
-				.map((v) => v.trim())
-				.filter(Boolean)
-				.map((v) => v.charAt(0))
-				.join("");
-		}
-
-		// Extract first 2 chars, uppercase
-		return _input.slice(0, 2).toUpperCase();
-	});
-
-	let colors = $derived(
-		autoColor ? generateAvatarColors(hashSource || input || "") : null
-	);
-
-	let sizeClass = $derived(SIZE_PRESETS[size] || size);
-
-	let style = $derived(
-		autoColor && colors
-			? `background-color: ${colors.bg}; color: ${colors.text};`
-			: undefined
-	);
-
-	let baseClass = $derived(
-		twMerge(
-			"stuic-avatar-initials",
-			"inline-flex items-center justify-center",
-			"rounded-full font-medium shrink-0",
-			!autoColor &&
-				"bg-neutral-200 text-neutral-700 dark:bg-neutral-700 dark:text-neutral-200",
-			sizeClass,
-			!autoColor && bg,
-			!autoColor && textColor,
-			onclick && "select-none cursor-pointer",
-			classProp
-		)
-	);
-</script>
-
-{#if onclick}
-	<button bind:this={el} type="button" class={baseClass} {style} {onclick}>
-		{initials}
-	</button>
-{:else}
-	<div bind:this={el} class={baseClass} {style}>
-		{initials}
-	</div>
-{/if}

package/dist/components/AvatarInitials/AvatarInitials.svelte.d.ts

@@ -1,23 +0,0 @@
-export interface Props {
-    /** String to extract initials from. Supports: "AB", "John Doe", or "john.doe@example.com" */
-    input: string;
-    /** Optional string for color hash calculation (e.g., email, user ID). Falls back to `input` */
-    hashSource?: string;
-    /** Size preset or custom Tailwind size class */
-    size?: "sm" | "md" | "lg" | "xl" | string;
-    /** Click handler - when provided, renders as a button */
-    onclick?: (event: MouseEvent) => void;
-    /** Background color (Tailwind class). Ignored if autoColor=true */
-    bg?: string;
-    /** Text color (Tailwind class). Ignored if autoColor=true */
-    textColor?: string;
-    /** Generate deterministic pastel colors from hashSource/input */
-    autoColor?: boolean;
-    /** CSS class override */
-    class?: string;
-    /** Bindable element reference */
-    el?: HTMLDivElement | HTMLButtonElement;
-}
-declare const AvatarInitials: import("svelte").Component<Props, {}, "el">;
-type AvatarInitials = ReturnType<typeof AvatarInitials>;
-export default AvatarInitials;

package/dist/components/AvatarInitials/README.md

@@ -1,169 +0,0 @@
-# AvatarInitials
-
-A circular avatar component displaying initials extracted from names or emails, with optional auto-generated colors and size presets.
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `input` | `string` | - | String to extract initials from (name, initials, or email) |
-| `hashSource` | `string` | - | Optional string for color hash calculation (falls back to `input`) |
-| `size` | `"sm" \| "md" \| "lg" \| "xl" \| string` | `"md"` | Size preset or custom Tailwind class |
-| `onclick` | `(event: MouseEvent) => void` | - | Click handler (renders as button when provided) |
-| `bg` | `string` | - | Background color Tailwind class (ignored if autoColor) |
-| `textColor` | `string` | - | Text color Tailwind class (ignored if autoColor) |
-| `autoColor` | `boolean` | `false` | Generate deterministic pastel colors from input |
-| `class` | `string` | - | Additional CSS classes |
-| `el` | `HTMLDivElement \| HTMLButtonElement` | - | Element reference (bindable) |
-
-## Size Presets
-
-| Size | Dimensions | Font Size |
-|------|------------|-----------|
-| `sm` | 32px (size-8) | text-xs |
-| `md` | 40px (size-10) | text-sm |
-| `lg` | 56px (size-14) | text-base |
-| `xl` | 64px (size-16) | text-lg |
-
-Custom sizes can be passed as Tailwind classes: `size="size-20 text-2xl"`
-
-## Initials Extraction Logic
-
-The component intelligently extracts up to 2 characters from the input:
-
-1. **Email addresses** (`john.doe@example.com`):
-   - Splits username by `.`, `_`, `+`, `-`
-   - Takes first letter of each part
-   - Result: `JD`
-
-2. **Full names** (`John Doe`):
-   - Splits by whitespace
-   - Takes first letter of each word
-   - Result: `JD`
-
-3. **Short strings** (`AB` or `Jo`):
-   - Takes first 2 characters
-   - Result: `AB` or `JO`
-
-4. **Empty input**:
-   - Returns `?`
-
-All initials are uppercase.
-
-## Auto Color Generation
-
-When `autoColor` is enabled, the component generates deterministic pastel colors:
-
-- Colors are derived from a hash of `hashSource` or `input`
-- Same input always produces the same color
-- Colors are designed as accessible pastel tones
-- Text color automatically contrasts with background
-
-## Usage
-
-### Basic Display
-
-```svelte
-<script lang="ts">
-  import { AvatarInitials } from 'stuic';
-</script>
-
-<AvatarInitials input="John Doe" />
-<AvatarInitials input="jane.smith@example.com" />
-<AvatarInitials input="AB" />
-```
-
-### Size Variants
-
-```svelte
-<AvatarInitials input="JD" size="sm" />
-<AvatarInitials input="JD" size="md" />
-<AvatarInitials input="JD" size="lg" />
-<AvatarInitials input="JD" size="xl" />
-
-<!-- Custom size -->
-<AvatarInitials input="JD" size="size-24 text-3xl" />
-```
-
-### Auto Color (Deterministic)
-
-```svelte
-<!-- Same email always produces same color -->
-<AvatarInitials input="john@example.com" autoColor />
-<AvatarInitials input="jane@example.com" autoColor />
-
-<!-- Use ID for consistent color regardless of display name -->
-<AvatarInitials input="John Doe" hashSource="user-123" autoColor />
-```
-
-### Custom Colors
-
-```svelte
-<AvatarInitials
-  input="JD"
-  bg="bg-blue-500"
-  textColor="text-white"
-/>
-
-<AvatarInitials
-  input="AB"
-  bg="bg-gradient-to-br from-purple-500 to-pink-500"
-  textColor="text-white"
-/>
-```
-
-### Clickable Avatar
-
-```svelte
-<script lang="ts">
-  function handleClick() {
-    console.log('Avatar clicked');
-  }
-</script>
-
-<AvatarInitials
-  input="john@example.com"
-  autoColor
-  onclick={handleClick}
-/>
-```
-
-### In Header Dropdown
-
-```svelte
-<script lang="ts">
-  import { AvatarInitials, DropdownMenu } from 'stuic';
-</script>
-
-<DropdownMenu
-  items={[
-    { type: "action", id: "profile", label: "View Profile" },
-    { type: "action", id: "logout", label: "Logout" },
-  ]}
->
-  {#snippet trigger({ toggle })}
-    <AvatarInitials
-      input={userEmail}
-      onclick={toggle}
-      autoColor
-      class="cursor-pointer hover:ring-2 hover:ring-blue-500"
-    />
-  {/snippet}
-</DropdownMenu>
-```
-
-### Avatar List
-
-```svelte
-<div class="flex -space-x-2">
-  {#each users as user}
-    <AvatarInitials
-      input={user.email}
-      hashSource={user.id}
-      autoColor
-      size="sm"
-      class="ring-2 ring-white"
-    />
-  {/each}
-</div>
-```

package/dist/components/AvatarInitials/index.d.ts

@@ -1 +0,0 @@
-export { default as AvatarInitials, type Props as AvatarInitialsProps, } from "./AvatarInitials.svelte";

package/dist/components/AvatarInitials/index.js

@@ -1 +0,0 @@
-export { default as AvatarInitials, } from "./AvatarInitials.svelte";