@grasco/profile-picture 0.1.7 → 0.1.8

package/dist/react.d.ts

@@ -0,0 +1,407 @@
+import React from 'react';
+import * as lit from 'lit';
+import { LitElement } from 'lit';
+
+/**
+ * Profile Picture Component - Type Definitions
+ * Apple-inspired design system with modern 2025 aesthetics
+ */
+type Size = "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+type Variant = "circle" | "rounded" | "squircle" | "square";
+type Position = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+type LoadingStrategy = "lazy" | "eager";
+type PlaceholderType = "shimmer" | "pulse" | "blur" | "skeleton" | "none";
+type PresenceStatus = "online" | "away" | "busy" | "offline" | "dnd";
+interface PresenceConfig {
+    /** Current status */
+    status: PresenceStatus;
+    /** Show animated ring */
+    animate?: boolean;
+    /** Ring thickness (1-3) */
+    thickness?: 1 | 2 | 3;
+}
+interface BadgeConfig {
+    /** Badge content (text, number, or empty for dot) */
+    content?: string | number;
+    /** Position of the badge */
+    position?: Position;
+    /** Text/icon color */
+    color?: string;
+    /** Background color */
+    bgColor?: string;
+    /** Border radius (CSS value, e.g., "8px", "50%", "9999px") */
+    borderRadius?: string;
+    /** Enable pulse animation */
+    pulse?: boolean;
+    /** Enable glow effect */
+    glow?: boolean;
+    /** Max value to display (shows 99+ if exceeded) */
+    max?: number;
+    /** Icon to display before content (emoji, Unicode symbol, or text) */
+    icon?: string;
+}
+interface GlowConfig {
+    /** Glow color (defaults to border or bg color) */
+    color?: string;
+    /** Intensity (0-1) */
+    intensity?: number;
+    /** Animate the glow */
+    animate?: boolean;
+}
+interface RingConfig {
+    /** Show ring */
+    show: boolean;
+    /** Ring color or gradient */
+    color?: string;
+    /** Gradient colors for multi-color ring */
+    gradient?: string[];
+    /** Ring width */
+    width?: number;
+    /** Gap between ring and avatar */
+    gap?: number;
+    /** Animate (rotate for gradient) */
+    animate?: boolean;
+    /** Progress percentage (0-100) for partial fill ring */
+    progress?: number;
+    /** Color for unfilled portion when progress is set (defaults to gray) */
+    emptyColor?: string;
+}
+interface InteractionConfig {
+    /** Enable hover effects */
+    hoverable?: boolean;
+    /** Enable press/click effects */
+    pressable?: boolean;
+    /** Show focus ring on focus */
+    focusable?: boolean;
+    /** Cursor style */
+    cursor?: "pointer" | "default" | "zoom-in";
+}
+type ShadowPreset = "none" | "sm" | "md" | "lg" | "glow";
+/**
+ * Base props interface shared across all framework wrappers.
+ * This ensures type consistency between React, Vue, Svelte, and Angular.
+ */
+interface ProfilePictureProps$1 {
+    /** Image source URL */
+    src?: string;
+    /** Alt text for accessibility and fallback initials */
+    alt?: string;
+    /** External customer ID for CDN image loading */
+    extCustomerId?: string;
+    /** Predefined size or custom pixel value */
+    size?: Size | number;
+    /** Shape variant */
+    variant?: Variant;
+    /** Shadow preset */
+    shadow?: ShadowPreset;
+    /** Enable border */
+    border?: boolean;
+    /** Border width in pixels */
+    borderWidth?: 1 | 2 | 3 | 4 | 5 | 6 | 8;
+    /** Border color (CSS color value) */
+    borderColor?: string;
+    /** Rotation angle in degrees */
+    rotation?: number;
+    /** Background color (CSS color value) */
+    bgColor?: string;
+    /** Background gradient (CSS gradient value) */
+    bgGradient?: string;
+    /** Glow effect configuration */
+    glow?: GlowConfig;
+    /** Ring effect configuration (Instagram-style) */
+    ring?: RingConfig;
+    /** Presence indicator configuration */
+    presence?: PresenceConfig;
+    /** Badge configuration */
+    badge?: BadgeConfig;
+    /** Loading strategy */
+    loading?: LoadingStrategy;
+    /** Placeholder type while loading */
+    placeholder?: PlaceholderType;
+    /** Placeholder background color */
+    placeholderColor?: string;
+    /** Custom fallback text (overrides initials from alt) */
+    fallback?: string;
+    /** Interactive behavior configuration */
+    interactive?: InteractionConfig;
+}
+/** Direction for stacking avatars */
+type StackDirection = "ltr" | "rtl";
+/** Tooltip position relative to avatar */
+type TooltipPosition = "top" | "bottom" | "left" | "right";
+/** Tooltip configuration */
+interface TooltipConfig {
+    /** Enable/disable tooltip (default: true) */
+    enabled?: boolean;
+    /** Position of tooltip relative to avatar */
+    position?: TooltipPosition;
+    /** Delay before showing tooltip in ms (default: 300) */
+    delay?: number;
+}
+/** User data extracted from profile-picture elements */
+interface GroupUserData {
+    /** User ID from data-user-id attribute */
+    id?: string;
+    /** User name from alt attribute */
+    name: string;
+    /** Image source URL */
+    src?: string;
+    /** External customer ID for CDN image loading */
+    extCustomerId?: string;
+    /** Presence status from data-status attribute */
+    status?: PresenceStatus;
+    /** Reference to the profile-picture element */
+    element: HTMLElement;
+    /** Index in the group */
+    index: number;
+    /** Visual variant (circle, rounded, squircle, square) */
+    variant?: Variant;
+    /** Shadow preset */
+    shadow?: ShadowPreset;
+    /** Show border */
+    border?: boolean;
+    /** Border width (1-8) */
+    borderWidth?: 1 | 2 | 3 | 4 | 5 | 6 | 8;
+    /** Border color */
+    borderColor?: string;
+    /** Background color */
+    bgColor?: string;
+    /** Background gradient */
+    bgGradient?: string;
+}
+/** Dropdown configuration for overflow users */
+interface DropdownConfig {
+    /** Max height of dropdown in px (default: 280) */
+    maxHeight?: number;
+    /** Show presence indicator dots (default: true) */
+    showPresence?: boolean;
+    /** Dropdown position (default: 'bottom') */
+    position?: "bottom" | "top";
+}
+
+declare class ProfilePictureGroup$1 extends LitElement {
+    protected createRenderRoot(): this;
+    max: 4;
+    direction: StackDirection;
+    overlap: 0.3;
+    size: Size | string;
+    spacing?: number;
+    tooltip?: TooltipConfig;
+    dropdown?: DropdownConfig;
+    showAddButton: boolean;
+    addButtonLabel: string;
+    animated: true;
+    rotationAmount: number;
+    private users;
+    private dropdownOpen;
+    private tooltipData;
+    private tooltipTimeout;
+    private slotObserver;
+    private portalContainer;
+    private counterRef;
+    private get pixelSize();
+    private get tooltipEnabled();
+    private get tooltipPosition();
+    private get tooltipDelay();
+    private get dropdownMaxHeight();
+    private get showPresence();
+    private get dropdownPosition();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private setupSlotObserver;
+    private updateUsers;
+    private createPortal;
+    private destroyPortal;
+    private updatePortalContent;
+    private handleAvatarClick;
+    private handleAvatarHover;
+    private handleAvatarLeave;
+    private clearTooltipTimeout;
+    private handleCounterClick;
+    private readonly handleBackdropClick;
+    private handleDropdownItemClick;
+    private handleAddClick;
+    private handleKeyDown;
+    private renderAvatar;
+    private renderProfilePicture;
+    private renderCounter;
+    private renderAddButton;
+    private renderTooltip;
+    private renderDropdownItem;
+    private formatStatus;
+    protected updated(changedProperties: Map<PropertyKey, unknown>): void;
+    render(): lit.TemplateResult<1>;
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        "profile-picture-group": ProfilePictureGroup$1;
+    }
+}
+
+/**
+ * React wrapper for ProfilePictureGroup Web Component
+ *
+ * Provides a type-safe React interface for the ProfilePictureGroup web component.
+ *
+ * @example
+ * ```tsx
+ * import { ProfilePictureGroup, ProfilePicture } from '@grasco/profile-picture';
+ *
+ * function App() {
+ *   return (
+ *     <ProfilePictureGroup
+ *       max={4}
+ *       direction="ltr"
+ *       overlap={0.3}
+ *       size="md"
+ *       showAddButton
+ *       onAvatarClick={(user) => console.log('Clicked:', user)}
+ *       onAddClick={() => console.log('Add clicked')}
+ *     >
+ *       <ProfilePicture src="avatar1.jpg" alt="John Doe" data-user-id="1" />
+ *       <ProfilePicture src="avatar2.jpg" alt="Jane Smith" data-user-id="2" />
+ *       <ProfilePicture src="avatar3.jpg" alt="Bob Wilson" data-user-id="3" />
+ *     </ProfilePictureGroup>
+ *   );
+ * }
+ * ```
+ */
+
+interface ProfilePictureGroupProps {
+    /** Maximum visible avatars before showing counter (default: 4) */
+    max?: number;
+    /** Stack direction - ltr shows first on left (default: 'ltr') */
+    direction?: StackDirection;
+    /** Overlap amount as percentage 0-1 (default: 0.3) */
+    overlap?: number;
+    /** Avatar size - inherited by children (default: 'md') */
+    size?: Size | number;
+    /** Spacing between avatars in px (overrides overlap calculation) */
+    spacing?: number;
+    /** Tooltip configuration */
+    tooltip?: TooltipConfig;
+    /** Dropdown configuration for overflow users */
+    dropdown?: DropdownConfig;
+    /** Show add button (default: false) */
+    showAddButton?: boolean;
+    /** Add button label for accessibility */
+    addButtonLabel?: string;
+    /** Enable hover lift animation (default: true) */
+    animated?: boolean;
+    /** Alternating rotation amount in degrees (0 = no rotation) */
+    rotationAmount?: number;
+    /** Called when an avatar is clicked */
+    onAvatarClick?: (user: GroupUserData) => void;
+    /** Called when hovering over an avatar */
+    onAvatarHover?: (user: GroupUserData) => void;
+    /** Called when the counter is clicked */
+    onCounterClick?: (hiddenUsers: GroupUserData[], open: boolean) => void;
+    /** Called when a dropdown item is clicked */
+    onDropdownItemClick?: (user: GroupUserData) => void;
+    /** Called when the add button is clicked */
+    onAddClick?: () => void;
+    className?: string;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+}
+/**
+ * ProfilePictureGroup React Component
+ *
+ * Type-safe wrapper around the profile-picture-group web component
+ */
+declare const ProfilePictureGroup: React.ForwardRefExoticComponent<ProfilePictureGroupProps & React.RefAttributes<HTMLElement>>;
+
+/**
+ * React wrapper for ProfilePicture Web Component
+ *
+ * Provides a type-safe React interface for the ProfilePicture web component.
+ *
+ * @example
+ * ```tsx
+ * import { ProfilePicture } from '@grasco/profile-picture';
+ *
+ * function App() {
+ *   return (
+ *     <ProfilePicture
+ *       src="https://example.com/avatar.png"
+ *       alt="John Doe"
+ *       size="lg"
+ *       variant="circle"
+ *       border
+ *       borderColor="white"
+ *       bgColor="bg-gradient-to-br from-purple-500 to-pink-500"
+ *       badge={{ content: '3', position: 'bottom-right', pulse: true }}
+ *       onLoad={() => console.log('loaded')}
+ *       onError={() => console.error('failed')}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+
+/**
+ * Set global CDN base URL for all ProfilePicture instances
+ * @example setCdnBaseUrl('https://api.example.com')
+ */
+declare function setCdnBaseUrl(url: string): void;
+/**
+ * Get current CDN base URL
+ */
+declare function getCdnBaseUrl(): string;
+/**
+ * React-specific props extending the core ProfilePictureProps
+ */
+interface ProfilePictureProps extends ProfilePictureProps$1 {
+    /** Called when image loads successfully */
+    onLoad?: () => void;
+    /** Called when image fails to load */
+    onError?: () => void;
+    /** Called when CDN image fails to load */
+    onCdnError?: (detail: {
+        error: string;
+    }) => void;
+    /** Additional CSS class names */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+}
+/**
+ * ProfilePicture React Component
+ *
+ * Type-safe wrapper around the profile-picture web component.
+ * Uses ref as a prop (React 19+ pattern).
+ */
+declare function ProfilePicture({ src, alt, extCustomerId, size, variant, shadow, border, borderWidth, borderColor, rotation, bgColor, bgGradient, glow, ring, presence, badge, loading, placeholder, placeholderColor, fallback, interactive, onLoad, onError, onCdnError, className, style, ref, }: ProfilePictureProps & {
+    ref?: React.Ref<HTMLElement>;
+}): React.ReactElement<{
+    ref: React.RefObject<HTMLElement>;
+    src: string | undefined;
+    alt: string | undefined;
+    "ext-customer-id": string | undefined;
+    size: number | Size | undefined;
+    variant: Variant | undefined;
+    shadow: ShadowPreset | undefined;
+    border: true | undefined;
+    "border-width": 1 | 2 | 3 | 4 | 5 | 6 | 8 | undefined;
+    "border-color": string | undefined;
+    rotation: number | undefined;
+    "bg-color": string | undefined;
+    "bg-gradient": string | undefined;
+    glow: string | undefined;
+    ring: string | undefined;
+    presence: string | undefined;
+    badge: string | undefined;
+    loading: LoadingStrategy | undefined;
+    placeholder: PlaceholderType | undefined;
+    "placeholder-color": string | undefined;
+    fallback: string | undefined;
+    interactive: string | undefined;
+    class: string | undefined;
+    style: React.CSSProperties | undefined;
+}, string | React.JSXElementConstructor<any>>;
+declare namespace ProfilePicture {
+    var displayName: string;
+}
+
+export { type BadgeConfig, type DropdownConfig, type GlowConfig, type GroupUserData, type InteractionConfig, type LoadingStrategy, type PlaceholderType, type PresenceConfig, ProfilePicture, ProfilePictureGroup, type ProfilePictureGroupProps, type ProfilePictureProps, type RingConfig, type ShadowPreset, type Size, type StackDirection, type TooltipConfig, type Variant, getCdnBaseUrl, setCdnBaseUrl };