@algenium/blocks 1.0.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,397 @@
+import * as React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import * as SliderPrimitive from '@radix-ui/react-slider';
+import * as TogglePrimitive from '@radix-ui/react-toggle';
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import { Drawer as Drawer$1 } from 'vaul';
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
+import { ClassValue } from 'clsx';
+
+/**
+ * Blocks Context Interfaces
+ *
+ * These interfaces define the contract that consuming apps must implement
+ * to provide context to blocks components. Components will automatically
+ * consume these contexts when available, falling back to props otherwise.
+ */
+/**
+ * Notification type for blocks components.
+ * This is the format that blocks components expect.
+ */
+interface BlocksNotification {
+    id: string;
+    title: string;
+    message?: string;
+    type?: "info" | "success" | "warning" | "error";
+    timestamp: Date;
+    read?: boolean;
+    href?: string;
+    channelId?: string;
+}
+/**
+ * Notifications context value interface.
+ * Consuming apps implement this interface to provide notifications data
+ * and actions to blocks components.
+ */
+interface NotificationsContextValue {
+    /** List of notifications to display */
+    notifications: BlocksNotification[];
+    /** Count of unread notifications */
+    unreadCount: number;
+    /** Mark a single notification as read by ID */
+    markAsRead: (id: string) => void | Promise<void>;
+    /** Mark all notifications as read */
+    markAllAsRead: () => void | Promise<void>;
+    /** Dismiss/remove a notification (optional) */
+    dismiss?: (id: string) => void;
+    /** Clear all notifications (optional) */
+    clearAll?: () => void;
+    /** Handle notification click (optional) */
+    onNotificationClick?: (notification: BlocksNotification) => void;
+}
+/**
+ * React context for notifications.
+ * Blocks components will consume this context when available.
+ */
+declare const NotificationsContext: React.Context<NotificationsContextValue | null>;
+/**
+ * Hook to consume the notifications context.
+ * Returns null if no provider is present (components should fall back to props).
+ */
+declare function useNotificationsContext(): NotificationsContextValue | null;
+/**
+ * Language definition for the language switcher.
+ */
+interface BlocksLanguage {
+    code: string;
+    name: string;
+    flag?: string;
+}
+/**
+ * Language context value interface.
+ * Consuming apps implement this interface to provide language state
+ * and actions to blocks components.
+ */
+interface LanguageContextValue {
+    /** Current language code (e.g., "en", "es") */
+    language: string;
+    /** Function to change the language */
+    setLanguage: (lang: string) => void;
+    /** Available languages (optional, components have defaults) */
+    languages?: BlocksLanguage[];
+}
+/**
+ * React context for language.
+ * Blocks components will consume this context when available.
+ */
+declare const LanguageContext: React.Context<LanguageContextValue | null>;
+/**
+ * Hook to consume the language context.
+ * Returns null if no provider is present (components should fall back to props).
+ */
+declare function useLanguageContext(): LanguageContextValue | null;
+
+type ThemeSwitcherLabels = {
+    /** Tooltip label for the theme switcher */
+    theme?: string;
+    /** Label for "System" option */
+    system?: string;
+    /** Label for "Light" option */
+    light?: string;
+    /** Label for "Dark" option */
+    dark?: string;
+};
+type ThemeSwitcherProps = {
+    className?: string;
+    /** Size of the switcher */
+    size?: "sm" | "md" | "lg";
+    /** Shape of the button */
+    shape?: "rounded" | "pill";
+    /** Mini variant shows only current theme icon as dropdown */
+    variant?: "default" | "mini";
+    /** Dropdown alignment (for mini variant) */
+    align?: "start" | "center" | "end";
+    /** Dropdown side (for mini variant) */
+    side?: "top" | "bottom" | "left" | "right";
+    /** Translation labels - consumers can pass their own t() values */
+    labels?: ThemeSwitcherLabels;
+};
+declare function ThemeSwitcher({ className, size, shape, variant, align, side, labels: userLabels, }: ThemeSwitcherProps): react_jsx_runtime.JSX.Element;
+
+type Language = {
+    /** Language key/code (e.g., "en", "es") */
+    key: string;
+    /** Short label for segmented control (e.g., "EN", "ES") */
+    label: string;
+    /** Full native name for dropdown (e.g., "English", "Español") */
+    nativeName: string;
+};
+type LanguageSwitcherLabels = {
+    /** Tooltip label for the language switcher */
+    language?: string;
+};
+/**
+ * Default languages when none are provided via props or context.
+ */
+declare const defaultLanguages: Language[];
+type LanguageSwitcherProps = {
+    /**
+     * Available languages. Optional if using LanguageContext.
+     * When context is available, context.languages is used; props override context.
+     * Falls back to defaultLanguages if neither provided.
+     */
+    languages?: Language[];
+    /**
+     * Current selected language key. Optional if using LanguageContext.
+     * When context is available, context.language is used; props override context.
+     */
+    currentLanguage?: string;
+    /**
+     * Callback when language changes. Optional if using LanguageContext.
+     * When context is available, context.setLanguage is used; props override context.
+     */
+    onLanguageChange?: (languageKey: string) => void;
+    /** Labels for accessibility/tooltips */
+    labels?: LanguageSwitcherLabels;
+    className?: string;
+    /** Size of the switcher */
+    size?: "sm" | "md" | "lg";
+    /** Shape of the button */
+    shape?: "rounded" | "squared" | "pill";
+    /** Mini variant shows only an icon */
+    variant?: "default" | "mini";
+    /** Show language icon in default variant */
+    showIcon?: boolean;
+    /** Dropdown alignment */
+    align?: "start" | "center" | "end";
+    /** Dropdown side */
+    side?: "top" | "bottom" | "left" | "right";
+};
+declare function LanguageSwitcher({ languages: propLanguages, currentLanguage: propCurrentLanguage, onLanguageChange: propOnLanguageChange, labels, className, size, shape, variant, showIcon, align, side, }: LanguageSwitcherProps): react_jsx_runtime.JSX.Element;
+
+interface AvatarEditorProps {
+    /** Current cropped image as data URL (controlled) */
+    value?: string | null;
+    /** Callback when the cropped image changes */
+    onChange?: (dataUrl: string | null) => void;
+    /** Size of the editor container in pixels */
+    size?: number;
+    /** Whether to show grid overlay by default */
+    showGrid?: boolean;
+    /** Output image size in pixels */
+    outputSize?: number;
+    /** Output format */
+    outputFormat?: "png" | "jpeg" | "webp";
+    /** Output quality for jpeg/webp (0-1) */
+    outputQuality?: number;
+    /** Additional class names */
+    className?: string;
+    /** Control size variant - 'default' for desktop, 'large' for mobile/touch devices */
+    controlSize?: "default" | "large";
+}
+declare function AvatarEditor({ value: _value, onChange, size, showGrid: initialShowGrid, outputSize, outputFormat, outputQuality, className, controlSize, }: AvatarEditorProps): react_jsx_runtime.JSX.Element;
+
+interface AvatarEditorDialogProps {
+    /** Current avatar URL or data URL */
+    value?: string | null;
+    /** Callback when avatar changes (after accepting) */
+    onChange?: (dataUrl: string | null) => void;
+    /** Async callback for saving/uploading - return true for success, false for failure */
+    onSave?: (dataUrl: string) => Promise<boolean> | boolean;
+    /** Size of the displayed avatar in pixels */
+    displaySize?: number;
+    /** Size of the editor in the dialog */
+    editorSize?: number;
+    /** Output image size */
+    outputSize?: number;
+    /** Placeholder text when no avatar */
+    placeholder?: string;
+    /** Edit button label for accessibility */
+    editLabel?: string;
+    /** Dialog title */
+    dialogTitle?: string;
+    /** Accept button text */
+    acceptText?: string;
+    /** Cancel button text */
+    cancelText?: string;
+    /** Success message */
+    successMessage?: string;
+    /** Error message */
+    errorMessage?: string;
+    /** Additional class names */
+    className?: string;
+}
+declare function AvatarEditorDialog({ value, onChange, onSave, displaySize, editorSize, outputSize, placeholder, editLabel, dialogTitle, acceptText, cancelText, successMessage, errorMessage, className, }: AvatarEditorDialogProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * NotificationsWidget - A compact notification bell for navigation bars
+ *
+ * @description
+ * Displays a bell icon with unread count badge, plays sound on new notifications,
+ * and shows a popover with recent notifications that can be marked as read or dismissed.
+ *
+ * @example
+ * ```tsx
+ * <NotificationsWidget
+ *   notifications={notifications}
+ *   onMarkAsRead={(id) => markAsRead(id)}
+ *   onMarkAllAsRead={() => markAllAsRead()}
+ *   onDismiss={(id) => dismiss(id)}
+ *   onClearAll={() => clearAll()}
+ *   playSound={true}
+ * />
+ * ```
+ */
+type NotificationType = "info" | "success" | "warning" | "error";
+interface Notification {
+    id: string;
+    title: string;
+    message?: string;
+    type?: NotificationType;
+    timestamp: Date;
+    read?: boolean;
+    href?: string;
+    channelId?: string;
+}
+type WidgetSize = "sm" | "md" | "lg";
+type DotColor = "red" | "blue" | "green" | "amber" | "purple" | "primary";
+type SoundType = "chime" | "bell" | "pop" | "ding" | "none";
+type PulseStyle = "ring" | "glow" | "bounce" | "none";
+interface NotificationsWidgetProps {
+    /**
+     * Notifications to display. Optional if using NotificationsContext.
+     * When context is available, context.notifications is used; props override context.
+     */
+    notifications?: Notification[];
+    /**
+     * Called when a notification becomes visible (scroll into view).
+     * Should return a Promise - if rejected, the notification will be reverted to unread.
+     * Uses optimistic update: marks as read immediately, reverts on failure.
+     * Optional if using NotificationsContext.
+     */
+    onMarkAsRead?: (id: string) => void | Promise<void>;
+    /**
+     * Called when "Mark all as read" button is clicked.
+     * Should return a Promise - if rejected, notifications will be reverted to unread.
+     * Uses optimistic update: marks all as read immediately, reverts on failure.
+     * Optional if using NotificationsContext.
+     */
+    onMarkAllAsRead?: () => void | Promise<void>;
+    /**
+     * Called when a notification is dismissed.
+     * Optional if using NotificationsContext.
+     */
+    onDismiss?: (id: string) => void;
+    /**
+     * Called when all notifications are cleared.
+     * Optional if using NotificationsContext.
+     */
+    onClearAll?: () => void;
+    /**
+     * Called when a notification is clicked.
+     * Optional if using NotificationsContext.
+     */
+    onNotificationClick?: (notification: Notification) => void;
+    size?: WidgetSize;
+    /**
+     * Maximum number of notifications to show in the list.
+     * Default: 5 on desktop. Scroll to see more.
+     */
+    maxVisible?: number;
+    playSound?: boolean;
+    soundUrl?: string;
+    className?: string;
+    emptyMessage?: string;
+    title?: string;
+    dotColor?: DotColor;
+    showPulse?: boolean;
+    soundType?: SoundType;
+    pulseStyle?: PulseStyle;
+    soundCooldown?: number;
+}
+declare function NotificationsWidget({ notifications: propNotifications, onMarkAsRead: propOnMarkAsRead, onMarkAllAsRead: propOnMarkAllAsRead, onDismiss: propOnDismiss, onClearAll: propOnClearAll, onNotificationClick: propOnNotificationClick, size, maxVisible, playSound, soundUrl, className, emptyMessage, title, dotColor, showPulse, soundType, pulseStyle, soundCooldown, }: NotificationsWidgetProps): react_jsx_runtime.JSX.Element;
+
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
+    size?: "default" | "sm" | "lg" | "icon" | "icon-sm" | "icon-lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+declare function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Root>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuPortal({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuTrigger({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuContent({ className, sideOffset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Content>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Group>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuItem({ className, inset, variant, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+    inset?: boolean;
+    variant?: "default" | "destructive";
+}): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuCheckboxItem({ className, children, checked, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuRadioGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuRadioItem({ className, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuLabel({ className, inset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+    inset?: boolean;
+}): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<"span">): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuSubTrigger({ className, inset, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+    inset?: boolean;
+}): react_jsx_runtime.JSX.Element;
+declare function DropdownMenuSubContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>): react_jsx_runtime.JSX.Element;
+
+declare function TooltipProvider({ delayDuration, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>): react_jsx_runtime.JSX.Element;
+declare function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>): react_jsx_runtime.JSX.Element;
+declare function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>): react_jsx_runtime.JSX.Element;
+declare function TooltipContent({ className, sideOffset, children, ...props }: React.ComponentProps<typeof TooltipPrimitive.Content>): react_jsx_runtime.JSX.Element;
+
+declare function Slider({ className, defaultValue, value, min, max, ...props }: React.ComponentProps<typeof SliderPrimitive.Root>): react_jsx_runtime.JSX.Element;
+
+declare const toggleVariants: (props?: ({
+    variant?: "default" | "outline" | null | undefined;
+    size?: "default" | "sm" | "lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Toggle({ className, variant, size, ...props }: React.ComponentProps<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants>): react_jsx_runtime.JSX.Element;
+
+declare function Dialog({ ...props }: React.ComponentProps<typeof DialogPrimitive.Root>): react_jsx_runtime.JSX.Element;
+declare function DialogTrigger({ ...props }: React.ComponentProps<typeof DialogPrimitive.Trigger>): react_jsx_runtime.JSX.Element;
+declare function DialogPortal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Portal>): react_jsx_runtime.JSX.Element;
+declare function DialogClose({ ...props }: React.ComponentProps<typeof DialogPrimitive.Close>): react_jsx_runtime.JSX.Element;
+declare function DialogOverlay({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Overlay>): react_jsx_runtime.JSX.Element;
+declare function DialogContent({ className, children, showCloseButton, ...props }: React.ComponentProps<typeof DialogPrimitive.Content> & {
+    showCloseButton?: boolean;
+}): react_jsx_runtime.JSX.Element;
+declare function DialogHeader({ className, ...props }: React.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
+declare function DialogFooter({ className, ...props }: React.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
+declare function DialogTitle({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Title>): react_jsx_runtime.JSX.Element;
+declare function DialogDescription({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Description>): react_jsx_runtime.JSX.Element;
+
+declare function Drawer({ ...props }: React.ComponentProps<typeof Drawer$1.Root>): react_jsx_runtime.JSX.Element;
+declare function DrawerTrigger({ ...props }: React.ComponentProps<typeof Drawer$1.Trigger>): react_jsx_runtime.JSX.Element;
+declare function DrawerPortal({ ...props }: React.ComponentProps<typeof Drawer$1.Portal>): react_jsx_runtime.JSX.Element;
+declare function DrawerClose({ ...props }: React.ComponentProps<typeof Drawer$1.Close>): react_jsx_runtime.JSX.Element;
+declare function DrawerOverlay({ className, ...props }: React.ComponentProps<typeof Drawer$1.Overlay>): react_jsx_runtime.JSX.Element;
+declare function DrawerContent({ className, children, ...props }: React.ComponentProps<typeof Drawer$1.Content>): react_jsx_runtime.JSX.Element;
+declare function DrawerHeader({ className, ...props }: React.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
+declare function DrawerFooter({ className, ...props }: React.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
+declare function DrawerTitle({ className, ...props }: React.ComponentProps<typeof Drawer$1.Title>): react_jsx_runtime.JSX.Element;
+declare function DrawerDescription({ className, ...props }: React.ComponentProps<typeof Drawer$1.Description>): react_jsx_runtime.JSX.Element;
+
+declare function Popover({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Root>): react_jsx_runtime.JSX.Element;
+declare function PopoverTrigger({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Trigger>): react_jsx_runtime.JSX.Element;
+declare function PopoverContent({ className, align, sideOffset, ...props }: React.ComponentProps<typeof PopoverPrimitive.Content>): react_jsx_runtime.JSX.Element;
+declare function PopoverAnchor({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Anchor>): react_jsx_runtime.JSX.Element;
+
+declare function ScrollArea({ className, children, ...props }: React.ComponentProps<typeof ScrollAreaPrimitive.Root>): react_jsx_runtime.JSX.Element;
+declare function ScrollBar({ className, orientation, ...props }: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>): react_jsx_runtime.JSX.Element;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+export { AvatarEditor, AvatarEditorDialog, type AvatarEditorDialogProps, type AvatarEditorProps, type BlocksLanguage, type BlocksNotification, Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, type Language, LanguageContext, type LanguageContextValue, LanguageSwitcher, type LanguageSwitcherLabels, type LanguageSwitcherProps, type Notification, type NotificationType, NotificationsContext, type NotificationsContextValue, NotificationsWidget, type NotificationsWidgetProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, ScrollArea, ScrollBar, Slider, ThemeSwitcher, type ThemeSwitcherLabels, type ThemeSwitcherProps, Toggle, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, buttonVariants, cn, defaultLanguages, toggleVariants, useLanguageContext, useNotificationsContext };