@mdxui/zero 6.0.0

package/src/mail/mail-item.stories.tsx

@@ -0,0 +1,422 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { MailThread as Thread } from "mdxui";
+import { MailItem } from "./mail-item";
+
+// Sample thread data for testing different MailItem states
+const unreadThread: Thread = {
+	id: "1",
+	subject: "Weekly Team Sync - Q4 Planning",
+	messages: [
+		{
+			id: "m1",
+			threadId: "1",
+			subject: "Weekly Team Sync - Q4 Planning",
+			from: { address: "sarah@company.com", name: "Sarah Chen" },
+			to: [{ address: "team@company.com", name: "Engineering Team" }],
+			date: new Date(Date.now() - 3600000).toISOString(),
+			snippet: "Hey team, let's discuss our Q4 roadmap priorities...",
+			isRead: false,
+			isStarred: true,
+			isImportant: true,
+			isDraft: false,
+			attachments: [],
+			labels: [],
+		},
+	],
+	latestDate: new Date(Date.now() - 3600000).toISOString(),
+	participants: [
+		{ address: "sarah@company.com", name: "Sarah Chen" },
+		{ address: "team@company.com", name: "Engineering Team" },
+	],
+	unreadCount: 1,
+	labels: [{ id: "l1", name: "Work", color: "#3b82f6", type: "user" }],
+	isStarred: true,
+	isImportant: true,
+	hasAttachments: false,
+	snippet: "Hey team, let's discuss our Q4 roadmap priorities...",
+};
+
+const readThread: Thread = {
+	id: "2",
+	subject: "Re: Design Review - Homepage Redesign",
+	messages: [
+		{
+			id: "m2",
+			threadId: "2",
+			subject: "Re: Design Review - Homepage Redesign",
+			from: { address: "mike@design.co", name: "Mike Johnson" },
+			to: [{ address: "me@company.com", name: "Me" }],
+			date: new Date(Date.now() - 7200000).toISOString(),
+			snippet:
+				"I've updated the mockups based on your feedback. The new hero section...",
+			isRead: true,
+			isStarred: false,
+			isImportant: false,
+			isDraft: false,
+			attachments: [
+				{
+					id: "a1",
+					filename: "homepage-v3.fig",
+					mimeType: "application/figma",
+					size: 2400000,
+					inline: false,
+				},
+			],
+			labels: [],
+		},
+	],
+	latestDate: new Date(Date.now() - 7200000).toISOString(),
+	participants: [
+		{ address: "mike@design.co", name: "Mike Johnson" },
+		{ address: "me@company.com", name: "Me" },
+	],
+	unreadCount: 0,
+	labels: [{ id: "l2", name: "Design", color: "#10b981", type: "user" }],
+	isStarred: false,
+	isImportant: false,
+	hasAttachments: true,
+	snippet:
+		"I've updated the mockups based on your feedback. The new hero section...",
+};
+
+const conversationThread: Thread = {
+	id: "3",
+	subject: "Project Timeline Discussion",
+	messages: [
+		{
+			id: "m3a",
+			threadId: "3",
+			subject: "Project Timeline Discussion",
+			from: { address: "alex@startup.io", name: "Alex Rivera" },
+			to: [{ address: "me@company.com", name: "Me" }],
+			date: new Date(Date.now() - 172800000).toISOString(),
+			snippet: "Initial message...",
+			isRead: true,
+			isStarred: false,
+			isImportant: false,
+			isDraft: false,
+			attachments: [],
+			labels: [],
+		},
+		{
+			id: "m3b",
+			threadId: "3",
+			subject: "Re: Project Timeline Discussion",
+			from: { address: "me@company.com", name: "Me" },
+			to: [{ address: "alex@startup.io", name: "Alex Rivera" }],
+			date: new Date(Date.now() - 86400000).toISOString(),
+			snippet: "My reply...",
+			isRead: true,
+			isStarred: false,
+			isImportant: false,
+			isDraft: false,
+			attachments: [],
+			labels: [],
+		},
+		{
+			id: "m3c",
+			threadId: "3",
+			subject: "Re: Project Timeline Discussion",
+			from: { address: "alex@startup.io", name: "Alex Rivera" },
+			to: [{ address: "me@company.com", name: "Me" }],
+			date: new Date(Date.now() - 43200000).toISOString(),
+			snippet: "Thanks for the update! I agree with your approach.",
+			isRead: false,
+			isStarred: false,
+			isImportant: true,
+			isDraft: false,
+			attachments: [],
+			labels: [],
+		},
+	],
+	latestDate: new Date(Date.now() - 43200000).toISOString(),
+	participants: [
+		{ address: "alex@startup.io", name: "Alex Rivera" },
+		{ address: "me@company.com", name: "Me" },
+	],
+	unreadCount: 1,
+	labels: [
+		{ id: "l3", name: "Project", color: "#8b5cf6", type: "user" },
+		{ id: "l4", name: "Urgent", color: "#ef4444", type: "user" },
+	],
+	isStarred: false,
+	isImportant: true,
+	hasAttachments: false,
+	snippet: "Thanks for the update! I agree with your approach.",
+};
+
+const multiLabelThread: Thread = {
+	id: "4",
+	subject: "Invoice #12345 - Payment Confirmation",
+	messages: [
+		{
+			id: "m4",
+			threadId: "4",
+			subject: "Invoice #12345 - Payment Confirmation",
+			from: { address: "billing@stripe.com", name: "Stripe" },
+			to: [{ address: "me@company.com", name: "Me" }],
+			date: new Date(Date.now() - 86400000).toISOString(),
+			snippet: "Your payment of $299.00 has been successfully processed...",
+			isRead: true,
+			isStarred: false,
+			isImportant: false,
+			isDraft: false,
+			attachments: [
+				{
+					id: "a2",
+					filename: "invoice-12345.pdf",
+					mimeType: "application/pdf",
+					size: 45000,
+					inline: false,
+				},
+			],
+			labels: [],
+		},
+	],
+	latestDate: new Date(Date.now() - 86400000).toISOString(),
+	participants: [{ address: "billing@stripe.com", name: "Stripe" }],
+	unreadCount: 0,
+	labels: [
+		{ id: "l5", name: "Finance", color: "#f59e0b", type: "user" },
+		{ id: "l6", name: "Important", color: "#ef4444", type: "user" },
+		{ id: "l7", name: "Archive", color: "#6b7280", type: "user" },
+		{ id: "l8", name: "Tax", color: "#10b981", type: "user" },
+		{ id: "l9", name: "Receipts", color: "#3b82f6", type: "user" },
+	],
+	isStarred: false,
+	isImportant: false,
+	hasAttachments: true,
+	snippet: "Your payment of $299.00 has been successfully processed...",
+};
+
+const meta: Meta<typeof MailItem> = {
+	title: "Zero/Mail/MailItem",
+	component: MailItem,
+	parameters: {
+		layout: "centered",
+	},
+	tags: ["autodocs"],
+	argTypes: {
+		compact: {
+			control: "boolean",
+		},
+		showCheckbox: {
+			control: "boolean",
+		},
+		showAvatar: {
+			control: "boolean",
+		},
+		isSelected: {
+			control: "boolean",
+		},
+		isFocused: {
+			control: "boolean",
+		},
+	},
+	decorators: [
+		(Story) => (
+			<div className="w-full max-w-2xl border bg-background">
+				<Story />
+			</div>
+		),
+	],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Default unread mail item with star and label.
+ * Shows checkbox on hover, avatar, subject, snippet, and timestamp.
+ */
+export const Default: Story = {
+	args: {
+		thread: unreadThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: false,
+	},
+};
+
+/**
+ * Read mail item without star.
+ * Shows muted appearance for read messages.
+ */
+export const Read: Story = {
+	args: {
+		thread: readThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: false,
+	},
+};
+
+/**
+ * Selected mail item with checkbox visible.
+ * Highlights the item with accent background.
+ */
+export const Selected: Story = {
+	args: {
+		thread: unreadThread,
+		isSelected: true,
+		isFocused: false,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: false,
+	},
+};
+
+/**
+ * Focused mail item with keyboard navigation.
+ * Shows ring outline for accessibility.
+ */
+export const Focused: Story = {
+	args: {
+		thread: unreadThread,
+		isSelected: false,
+		isFocused: true,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: false,
+	},
+};
+
+/**
+ * Compact display mode for higher density.
+ * Reduced padding and no snippet shown.
+ */
+export const Compact: Story = {
+	args: {
+		thread: unreadThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: true,
+	},
+};
+
+/**
+ * Mail thread with multiple messages.
+ * Shows message count next to sender name.
+ */
+export const Conversation: Story = {
+	args: {
+		thread: conversationThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: false,
+	},
+};
+
+/**
+ * Mail item with attachment indicator.
+ * Shows paperclip icon.
+ */
+export const WithAttachment: Story = {
+	args: {
+		thread: readThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: false,
+	},
+};
+
+/**
+ * Mail item with multiple labels.
+ * Shows first 3 labels with "+N more" badge.
+ */
+export const MultipleLabels: Story = {
+	args: {
+		thread: multiLabelThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: false,
+	},
+};
+
+/**
+ * Without checkbox control.
+ * Simpler view for read-only lists.
+ */
+export const NoCheckbox: Story = {
+	args: {
+		thread: unreadThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: false,
+		showAvatar: true,
+		compact: false,
+	},
+};
+
+/**
+ * Without avatar display.
+ * More compact horizontal layout.
+ */
+export const NoAvatar: Story = {
+	args: {
+		thread: unreadThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: true,
+		showAvatar: false,
+		compact: false,
+	},
+};
+
+/**
+ * With search term highlighting.
+ * Highlights matching text in subject and snippet.
+ */
+export const WithHighlight: Story = {
+	args: {
+		thread: unreadThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: false,
+		highlightTerms: ["Q4", "roadmap"],
+	},
+};
+
+/**
+ * Selected and focused together.
+ * Common state when navigating with keyboard.
+ */
+export const SelectedAndFocused: Story = {
+	args: {
+		thread: unreadThread,
+		isSelected: true,
+		isFocused: true,
+		showCheckbox: true,
+		showAvatar: true,
+		compact: false,
+	},
+};
+
+/**
+ * Minimal configuration.
+ * Compact, no checkbox, no avatar.
+ */
+export const Minimal: Story = {
+	args: {
+		thread: readThread,
+		isSelected: false,
+		isFocused: false,
+		showCheckbox: false,
+		showAvatar: false,
+		compact: true,
+	},
+};

package/src/mail/mail-item.tsx

@@ -0,0 +1,229 @@
+import { Avatar, AvatarFallback, AvatarImage } from "@mdxui/primitives/avatar";
+import { Badge } from "@mdxui/primitives/badge";
+import { Checkbox } from "@mdxui/primitives/checkbox";
+import { cn } from "@mdxui/primitives/lib/utils";
+import { Paperclip, Star } from "lucide-react";
+import type { MailItemProps } from "mdxui";
+import type * as React from "react";
+
+/**
+ * MailItem - Individual email thread item in the mail list.
+ *
+ * Displays:
+ * - Selection checkbox
+ * - Sender avatar
+ * - Subject and snippet
+ * - Labels/tags
+ * - Star indicator
+ * - Attachment indicator
+ * - Timestamp
+ */
+function MailItem({
+	thread,
+	isSelected = false,
+	isFocused = false,
+	onClick,
+	onSelect,
+	onStar,
+	compact = false,
+	showCheckbox = true,
+	showAvatar = true,
+	highlightTerms,
+	className,
+}: MailItemProps) {
+	const latestMessage = thread.messages[thread.messages.length - 1];
+	const sender = latestMessage?.from;
+	const isUnread = thread.unreadCount > 0;
+
+	// Format date relative to now
+	const formatDate = (dateStr: string) => {
+		const date = new Date(dateStr);
+		const now = new Date();
+		const diffMs = now.getTime() - date.getTime();
+		const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+
+		if (diffDays === 0) {
+			return date.toLocaleTimeString([], {
+				hour: "numeric",
+				minute: "2-digit",
+			});
+		} else if (diffDays === 1) {
+			return "Yesterday";
+		} else if (diffDays < 7) {
+			return date.toLocaleDateString([], { weekday: "short" });
+		} else {
+			return date.toLocaleDateString([], { month: "short", day: "numeric" });
+		}
+	};
+
+	// Get initials for avatar fallback
+	const getInitials = (name?: string, email?: string) => {
+		if (name) {
+			return name
+				.split(" ")
+				.map((n) => n[0])
+				.join("")
+				.toUpperCase()
+				.slice(0, 2);
+		}
+		return email?.charAt(0).toUpperCase() || "?";
+	};
+
+	// Highlight search terms in text
+	const highlightText = (text: string) => {
+		if (!highlightTerms?.length) return text;
+		const regex = new RegExp(`(${highlightTerms.join("|")})`, "gi");
+		return text.replace(
+			regex,
+			'<mark class="bg-yellow-200 dark:bg-yellow-800">$1</mark>',
+		);
+	};
+
+	const handleKeyDown = (e: React.KeyboardEvent) => {
+		if (e.key === "Enter" || e.key === " ") {
+			e.preventDefault();
+			onClick?.();
+		}
+	};
+
+	return (
+		// biome-ignore lint/a11y/useSemanticElements: MailItem contains nested interactive elements (checkbox, star button) which can't be inside a <button>
+		<div
+			role="button"
+			data-slot="mail-item"
+			data-selected={isSelected || undefined}
+			tabIndex={0}
+			onClick={() => onClick?.()}
+			onKeyDown={handleKeyDown}
+			className={cn(
+				"group relative flex cursor-pointer items-start gap-3 border-b px-4 transition-colors",
+				compact ? "py-2" : "py-3",
+				isUnread && "bg-muted/50",
+				isSelected && "bg-accent",
+				isFocused && "ring-2 ring-ring ring-inset",
+				"hover:bg-accent/50",
+				className,
+			)}
+		>
+			{/* Selection Checkbox */}
+			{showCheckbox && (
+				<div className="flex items-center pt-1">
+					<Checkbox
+						checked={isSelected}
+						onCheckedChange={() => onSelect?.()}
+						onClick={(e) => e.stopPropagation()}
+						className="opacity-0 group-hover:opacity-100 data-[state=checked]:opacity-100"
+					/>
+				</div>
+			)}
+
+			{/* Avatar */}
+			{showAvatar && (
+				<Avatar className={cn("shrink-0", compact ? "size-8" : "size-10")}>
+					<AvatarImage src={undefined} alt={sender?.name || sender?.address} />
+					<AvatarFallback className={cn(isUnread && "font-semibold")}>
+						{getInitials(sender?.name, sender?.address)}
+					</AvatarFallback>
+				</Avatar>
+			)}
+
+			{/* Content */}
+			<div className="min-w-0 flex-1">
+				{/* Header Row */}
+				<div className="flex items-center justify-between gap-2">
+					<span
+						className={cn(
+							"truncate text-sm",
+							isUnread ? "font-semibold" : "text-muted-foreground",
+						)}
+					>
+						{sender?.name || sender?.address}
+						{thread.messages.length > 1 && (
+							<span className="text-muted-foreground ml-1 font-normal">
+								({thread.messages.length})
+							</span>
+						)}
+					</span>
+					<span className="text-muted-foreground shrink-0 text-xs">
+						{formatDate(thread.latestDate)}
+					</span>
+				</div>
+
+				{/* Subject */}
+				<div
+					className={cn(
+						"truncate text-sm",
+						isUnread ? "font-medium" : "text-muted-foreground",
+					)}
+					// biome-ignore lint/security/noDangerouslySetInnerHtml: MailItem is a trusted component
+					dangerouslySetInnerHTML={{
+						__html: highlightText(thread.subject || "(no subject)"),
+					}}
+				/>
+
+				{/* Snippet */}
+				{!compact && thread.snippet && (
+					<div
+						className="text-muted-foreground line-clamp-1 text-xs"
+						// biome-ignore lint/security/noDangerouslySetInnerHtml: MailItem is a trusted component
+						dangerouslySetInnerHTML={{ __html: highlightText(thread.snippet) }}
+					/>
+				)}
+
+				{/* Labels */}
+				{thread.labels.length > 0 && (
+					<div className="mt-1 flex flex-wrap gap-1">
+						{thread.labels.slice(0, 3).map((label) => (
+							<Badge
+								key={label.id}
+								variant="secondary"
+								className="text-xs"
+								style={
+									label.color ? { backgroundColor: label.color } : undefined
+								}
+							>
+								{label.name}
+							</Badge>
+						))}
+						{thread.labels.length > 3 && (
+							<Badge variant="outline" className="text-xs">
+								+{thread.labels.length - 3}
+							</Badge>
+						)}
+					</div>
+				)}
+			</div>
+
+			{/* Action Indicators */}
+			<div className="flex shrink-0 items-center gap-1 pt-1">
+				{/* Attachment indicator */}
+				{thread.hasAttachments && (
+					<Paperclip className="text-muted-foreground size-4" />
+				)}
+
+				{/* Star button */}
+				<button
+					type="button"
+					onClick={(e) => {
+						e.stopPropagation();
+						onStar?.();
+					}}
+					className={cn(
+						"rounded p-1 transition-colors hover:bg-accent",
+						thread.isStarred
+							? "text-yellow-500"
+							: "text-muted-foreground opacity-0 group-hover:opacity-100",
+					)}
+					aria-label={thread.isStarred ? "Unstar" : "Star"}
+				>
+					<Star
+						className="size-4"
+						fill={thread.isStarred ? "currentColor" : "none"}
+					/>
+				</button>
+			</div>
+		</div>
+	);
+}
+
+export { MailItem };