@algenium/blocks 1.0.0-rc.1

package/README.md

@@ -0,0 +1,676 @@
+# @algenium/blocks
+
+> Shared UI components for Algenium applications
+
+A collection of reusable, accessible UI components built with React, Radix UI, and Tailwind CSS. Designed for use across all Algenium applications.
+
+## Installation
+
+```bash
+npm install @algenium/blocks
+# or
+pnpm add @algenium/blocks
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```bash
+pnpm add react react-dom next-themes lucide-react motion
+```
+
+## Configuration
+
+### Tailwind CSS
+
+Configure your Tailwind CSS to include this package:
+
+```js
+// tailwind.config.js
+module.exports = {
+	content: [
+		// ... your other content paths
+		"./node_modules/@algenium/blocks/dist/**/*.js",
+	],
+	// ... rest of your config
+};
+```
+
+## Components
+
+### ThemeSwitcher
+
+A theme switcher component that integrates with `next-themes`. Supports light, dark, and system themes.
+
+**Features:**
+
+- Multiple variants (default, mini)
+- Multiple sizes (sm, md, lg)
+- Multiple shapes (rounded, pill)
+- Internationalization support
+
+**Usage:**
+
+```tsx
+import { ThemeSwitcher } from "@algenium/blocks";
+
+// Default usage
+<ThemeSwitcher />;
+
+// With custom labels (for i18n)
+<ThemeSwitcher
+	labels={{
+		theme: "Theme",
+		system: "System",
+		light: "Light",
+		dark: "Dark",
+	}}
+/>;
+
+// Mini variant (icon only with dropdown)
+<ThemeSwitcher variant="mini" />;
+
+// Different sizes and shapes
+<ThemeSwitcher size="sm" shape="pill" />;
+```
+
+**Props:**
+
+```typescript
+interface ThemeSwitcherProps {
+	variant?: "default" | "mini";
+	size?: "sm" | "md" | "lg";
+	shape?: "rounded" | "pill";
+	showIcon?: boolean;
+	labels?: ThemeSwitcherLabels;
+	className?: string;
+}
+```
+
+---
+
+### LanguageSwitcher
+
+A language switcher component with support for multiple languages and display variants.
+
+**Features:**
+
+- Multiple variants (default, mini)
+- Multiple sizes (sm, md, lg)
+- Dropdown positioning control
+- Language flag/icon support
+- Internationalization support
+
+**Usage:**
+
+```tsx
+import { LanguageSwitcher } from "@algenium/blocks";
+
+const languages = [
+	{ key: "en", label: "EN", nativeName: "English" },
+	{ key: "es", label: "ES", nativeName: "Español" },
+];
+
+<LanguageSwitcher
+	languages={languages}
+	currentLanguage="en"
+	onLanguageChange={(key) => setLanguage(key)}
+	labels={{ language: "Language" }}
+/>;
+
+// Mini variant
+<LanguageSwitcher
+	variant="mini"
+	languages={languages}
+	currentLanguage="en"
+	onLanguageChange={(key) => setLanguage(key)}
+/>;
+
+// With icon
+<LanguageSwitcher
+	languages={languages}
+	currentLanguage="en"
+	onLanguageChange={(key) => setLanguage(key)}
+	showIcon
+/>;
+```
+
+**Props:**
+
+```typescript
+interface LanguageSwitcherProps {
+	languages: Language[];
+	currentLanguage: string;
+	onLanguageChange: (languageKey: string) => void;
+	variant?: "default" | "mini";
+	size?: "sm" | "md" | "lg";
+	dropdownAlign?: "start" | "center" | "end";
+	showIcon?: boolean;
+	labels?: LanguageSwitcherLabels;
+	className?: string;
+}
+
+interface Language {
+	key: string;
+	label: string;
+	nativeName: string;
+}
+```
+
+---
+
+### AvatarEditor
+
+An interactive avatar editor with zoom, rotation, and drag controls.
+
+**Features:**
+
+- Image zoom via UI buttons and slider (0.5x - 3x)
+- Image rotation in 15° increments (0° - 360°)
+- Drag to reposition image
+- Real-time preview with circular crop
+- Customizable editor size
+- Optional grid overlay for alignment
+- Reset all transforms
+- Touch-optimized controls for mobile
+
+**Usage:**
+
+```tsx
+import { AvatarEditor } from "@algenium/blocks";
+
+<AvatarEditor
+	value={avatarData}
+	onChange={(editedImage) => {
+		console.log("Edited image:", editedImage);
+	}}
+/>;
+
+// With custom size and grid
+<AvatarEditor
+	value={avatarData}
+	onChange={setAvatarData}
+	size={280}
+	showGrid={true}
+/>;
+
+// With custom output settings
+<AvatarEditor
+	value={avatarData}
+	onChange={setAvatarData}
+	outputSize={512}
+	outputFormat="jpeg"
+	outputQuality={0.95}
+/>;
+
+// With large controls for mobile/touch
+<AvatarEditor
+	value={avatarData}
+	onChange={setAvatarData}
+	controlSize="large"
+/>;
+```
+
+**Props:**
+
+```typescript
+interface AvatarEditorProps {
+	value?: string | null;
+	onChange?: (dataUrl: string | null) => void;
+	size?: number;
+	showGrid?: boolean;
+	outputSize?: number;
+	outputFormat?: "png" | "jpeg" | "webp";
+	outputQuality?: number;
+	controlSize?: "default" | "large";
+	className?: string;
+}
+```
+
+---
+
+### AvatarEditorDialog
+
+A complete avatar editing experience with preview display and edit dialog.
+
+**Features:**
+
+- Large avatar display with edit button
+- Opens fullscreen drawer on mobile, modal on desktop
+- Integrated AvatarEditor with all controls
+- Controlled component (value/onChange)
+- Optional async save handler with feedback
+- Success/error feedback messages
+- Customizable sizes and labels
+- Accessibility optimized
+
+**Usage:**
+
+```tsx
+import { AvatarEditorDialog } from "@algenium/blocks";
+
+// Basic usage with value/onChange
+<AvatarEditorDialog value={avatar} onChange={setAvatar} />;
+
+// With async save handler
+<AvatarEditorDialog
+	value={avatar}
+	onChange={setAvatar}
+	onSave={async (dataUrl) => {
+		const result = await uploadAvatar(dataUrl);
+		return result.success;
+	}}
+	dialogTitle="Edit Profile Picture"
+	acceptText="Save"
+	cancelText="Cancel"
+	successMessage="Avatar saved successfully!"
+	errorMessage="Failed to save avatar"
+/>;
+
+// With custom sizes
+<AvatarEditorDialog
+	value={avatar}
+	onChange={setAvatar}
+	displaySize={120}
+	editorSize={280}
+	outputSize={512}
+/>;
+```
+
+**Props:**
+
+```typescript
+interface AvatarEditorDialogProps {
+	value?: string | null;
+	onChange?: (dataUrl: string | null) => void;
+	onSave?: (dataUrl: string) => Promise<boolean> | boolean;
+	displaySize?: number;
+	editorSize?: number;
+	outputSize?: number;
+	placeholder?: string;
+	editLabel?: string;
+	dialogTitle?: string;
+	acceptText?: string;
+	cancelText?: string;
+	successMessage?: string;
+	errorMessage?: string;
+	className?: string;
+}
+```
+
+---
+
+### NotificationsWidget
+
+A compact notification bell widget with popover display, sound alerts, and animations.
+
+**Features:**
+
+- Bell icon with unread count badge
+- Popover with scrollable notification list
+- Multiple notification types (info, success, warning, error)
+- Sound notifications (chime, bell, pop, ding)
+- Pulse animations (ring, glow, bounce)
+- Mark as read/dismiss actions
+- Click-to-navigate support
+- Customizable colors, sizes, and sounds
+
+**Usage:**
+
+```tsx
+import { NotificationsWidget, Notification } from "@algenium/blocks";
+
+const notifications: Notification[] = [
+	{
+		id: "1",
+		title: "New message",
+		message: "You have a new message from John",
+		type: "info",
+		timestamp: new Date(),
+		read: false,
+	},
+	{
+		id: "2",
+		title: "Task completed",
+		message: "Your export task finished successfully",
+		type: "success",
+		timestamp: new Date(Date.now() - 1000 * 60 * 5),
+		read: false,
+	},
+];
+
+<NotificationsWidget
+	notifications={notifications}
+	onMarkAsRead={(id) => markAsRead(id)}
+	onMarkAllAsRead={() => markAllAsRead()}
+	onDismiss={(id) => dismiss(id)}
+	onClearAll={() => clearAll()}
+	onNotificationClick={(notification) => {
+		if (notification.href) {
+			router.push(notification.href);
+		}
+	}}
+	playSound
+	soundType="chime"
+	size="md"
+	dotColor="red"
+	pulseStyle="ring"
+/>;
+
+// Minimal usage
+<NotificationsWidget
+	notifications={notifications}
+	onMarkAsRead={(id) => markAsRead(id)}
+/>;
+
+// Custom configuration
+<NotificationsWidget
+	notifications={notifications}
+	onMarkAsRead={(id) => markAsRead(id)}
+	size="lg"
+	dotColor="primary"
+	soundType="bell"
+	pulseStyle="glow"
+	maxVisible={10}
+	title="Alerts"
+	emptyMessage="No alerts"
+/>;
+```
+
+**Props:**
+
+```typescript
+interface NotificationsWidgetProps {
+	notifications: Notification[];
+	onMarkAsRead?: (id: string) => void;
+	onMarkAllAsRead?: () => void;
+	onDismiss?: (id: string) => void;
+	onClearAll?: () => void;
+	onNotificationClick?: (notification: Notification) => void;
+	size?: "sm" | "md" | "lg";
+	maxVisible?: number; // Default: 5
+	playSound?: boolean; // Default: true
+	soundUrl?: string; // Custom sound file URL
+	soundType?: "chime" | "bell" | "pop" | "ding" | "none"; // Default: "chime"
+	soundCooldown?: number; // Default: 2000ms
+	className?: string;
+	emptyMessage?: string; // Default: "No notifications"
+	title?: string; // Default: "Notifications"
+	dotColor?: "red" | "blue" | "green" | "amber" | "purple" | "primary"; // Default: "red"
+	showPulse?: boolean; // Default: true
+	pulseStyle?: "ring" | "glow" | "bounce" | "none"; // Default: "ring"
+}
+
+interface Notification {
+	id: string;
+	title: string;
+	message?: string;
+	type?: "info" | "success" | "warning" | "error"; // Default: "info"
+	timestamp: Date;
+	read?: boolean;
+	href?: string; // Optional link for click navigation
+}
+```
+
+---
+
+## UI Primitives
+
+The package also exports underlying UI primitives that can be used independently:
+
+### Button
+
+```tsx
+import { Button } from "@algenium/blocks";
+
+<Button variant="default">Click me</Button>;
+<Button variant="outline" size="sm">
+	Small
+</Button>;
+<Button variant="ghost" size="icon">
+	<Icon />
+</Button>;
+```
+
+### Dialog
+
+```tsx
+import {
+	Dialog,
+	DialogTrigger,
+	DialogContent,
+	DialogHeader,
+	DialogTitle,
+	DialogDescription,
+	DialogFooter,
+} from "@algenium/blocks";
+
+<Dialog>
+	<DialogTrigger>Open</DialogTrigger>
+	<DialogContent>
+		<DialogHeader>
+			<DialogTitle>Title</DialogTitle>
+			<DialogDescription>Description</DialogDescription>
+		</DialogHeader>
+		{/* Content */}
+		<DialogFooter>{/* Actions */}</DialogFooter>
+	</DialogContent>
+</Dialog>;
+```
+
+### Drawer
+
+```tsx
+import {
+	Drawer,
+	DrawerTrigger,
+	DrawerContent,
+	DrawerHeader,
+	DrawerTitle,
+} from "@algenium/blocks";
+
+<Drawer>
+	<DrawerTrigger>Open</DrawerTrigger>
+	<DrawerContent>
+		<DrawerHeader>
+			<DrawerTitle>Title</DrawerTitle>
+		</DrawerHeader>
+		{/* Content */}
+	</DrawerContent>
+</Drawer>;
+```
+
+### DropdownMenu
+
+```tsx
+import {
+	DropdownMenu,
+	DropdownMenuTrigger,
+	DropdownMenuContent,
+	DropdownMenuItem,
+} from "@algenium/blocks";
+
+<DropdownMenu>
+	<DropdownMenuTrigger>Open</DropdownMenuTrigger>
+	<DropdownMenuContent>
+		<DropdownMenuItem>Item 1</DropdownMenuItem>
+		<DropdownMenuItem>Item 2</DropdownMenuItem>
+	</DropdownMenuContent>
+</DropdownMenu>;
+```
+
+### Popover
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent } from "@algenium/blocks";
+
+<Popover>
+	<PopoverTrigger>Open</PopoverTrigger>
+	<PopoverContent>Content here</PopoverContent>
+</Popover>;
+```
+
+### ScrollArea
+
+```tsx
+import { ScrollArea } from "@algenium/blocks";
+
+<ScrollArea className="h-[200px]">{/* Scrollable content */}</ScrollArea>;
+```
+
+### Slider
+
+```tsx
+import { Slider } from "@algenium/blocks";
+
+<Slider
+	value={[50]}
+	onValueChange={(value) => setValue(value[0])}
+	max={100}
+	step={1}
+/>;
+```
+
+### Toggle
+
+```tsx
+import { Toggle } from "@algenium/blocks";
+
+<Toggle pressed={isPressed} onPressedChange={setIsPressed}>
+	Toggle me
+</Toggle>;
+```
+
+### Tooltip
+
+```tsx
+import {
+	Tooltip,
+	TooltipTrigger,
+	TooltipContent,
+	TooltipProvider,
+} from "@algenium/blocks";
+
+<TooltipProvider>
+	<Tooltip>
+		<TooltipTrigger>Hover me</TooltipTrigger>
+		<TooltipContent>Tooltip text</TooltipContent>
+	</Tooltip>
+</TooltipProvider>;
+```
+
+---
+
+## Utilities
+
+### cn (Class Name utility)
+
+A utility function for conditionally merging Tailwind CSS classes.
+
+```tsx
+import { cn } from "@algenium/blocks";
+
+const className = cn("base-class", condition && "conditional-class", {
+	"another-class": someCondition,
+});
+```
+
+---
+
+## TypeScript Support
+
+All components are fully typed with TypeScript. Import types as needed:
+
+```tsx
+import type {
+	ThemeSwitcherProps,
+	LanguageSwitcherProps,
+	Language,
+	AvatarEditorProps,
+	AvatarEditorDialogProps,
+	NotificationsWidgetProps,
+	Notification,
+	NotificationType,
+} from "@algenium/blocks";
+```
+
+---
+
+## Best Practices
+
+### Internationalization
+
+All text-based components accept label props for i18n:
+
+```tsx
+import { useTranslation } from "your-i18n-library";
+
+const { t } = useTranslation();
+
+<ThemeSwitcher
+	labels={{
+		theme: t("theme"),
+		light: t("light"),
+		dark: t("dark"),
+		system: t("system"),
+	}}
+/>;
+```
+
+### Theme Integration
+
+Components use CSS variables for theming. Ensure your app provides these variables:
+
+```css
+:root {
+	--background: 0 0% 100%;
+	--foreground: 222.2 84% 4.9%;
+	--primary: 222.2 47.4% 11.2%;
+	--muted: 210 40% 96.1%;
+	--border: 214.3 31.8% 91.4%;
+	/* ... other variables */
+}
+```
+
+### Notification Management
+
+For `NotificationsWidget`, implement a notification management system:
+
+```tsx
+// Example notification manager
+const [notifications, setNotifications] = useState<Notification[]>([]);
+
+const markAsRead = (id: string) => {
+	setNotifications((prev) =>
+		prev.map((n) => (n.id === id ? { ...n, read: true } : n)),
+	);
+};
+
+const dismiss = (id: string) => {
+	setNotifications((prev) => prev.filter((n) => n.id !== id));
+};
+
+const addNotification = (notification: Omit<Notification, "id">) => {
+	const id = crypto.randomUUID();
+	setNotifications((prev) => [{ ...notification, id }, ...prev]);
+};
+```
+
+---
+
+## Contributing
+
+This package is maintained as part of the Algenium monorepo. See the main repository for contribution guidelines.
+
+## License
+
+Proprietary - Algenium © 2026
+
+## Version
+
+Current version: `1.0.0-rc.4`
+
+## Support
+
+For issues or questions, contact the Algenium development team or open an issue in the repository.