@refraction-ui/react 0.4.1 → 0.5.0

package/dist/internal/animated-text/index.d.cts

@@ -0,0 +1,47 @@
+interface AnimatedTextProps {
+    words: string[];
+    interval?: number;
+    transitionDuration?: number;
+}
+interface AnimatedTextState {
+    currentIndex: number;
+}
+interface AnimatedTextAPI {
+    /** Get the current word */
+    getCurrentWord: () => string;
+    /** Get the next index (wraps around) */
+    getNextIndex: () => number;
+    /** Current state */
+    state: AnimatedTextState;
+}
+interface TypewriterProps {
+    text: string;
+    speed?: number;
+    startDelay?: number;
+}
+interface TypewriterState {
+    currentIndex: number;
+}
+interface TypewriterAPI {
+    /** Get the currently visible portion of text */
+    getVisibleText: () => string;
+    /** Whether the typewriter has finished */
+    isComplete: () => boolean;
+    /** Current state */
+    state: TypewriterState;
+}
+declare function createAnimatedText(props: AnimatedTextProps): AnimatedTextAPI;
+declare function createTypewriter(props: TypewriterProps): TypewriterAPI;
+
+declare const animatedTextVariants: (props?: ({
+    state?: "entering" | "exiting" | "idle" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const typewriterVariants: (props?: ({
+    cursor?: "blinking" | "hidden" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type AnimatedTextAPI, type AnimatedTextProps, type AnimatedTextState, type TypewriterAPI, type TypewriterProps, type TypewriterState, animatedTextVariants, createAnimatedText, createTypewriter, typewriterVariants };

package/dist/internal/animated-text/index.d.ts

@@ -0,0 +1,47 @@
+interface AnimatedTextProps {
+    words: string[];
+    interval?: number;
+    transitionDuration?: number;
+}
+interface AnimatedTextState {
+    currentIndex: number;
+}
+interface AnimatedTextAPI {
+    /** Get the current word */
+    getCurrentWord: () => string;
+    /** Get the next index (wraps around) */
+    getNextIndex: () => number;
+    /** Current state */
+    state: AnimatedTextState;
+}
+interface TypewriterProps {
+    text: string;
+    speed?: number;
+    startDelay?: number;
+}
+interface TypewriterState {
+    currentIndex: number;
+}
+interface TypewriterAPI {
+    /** Get the currently visible portion of text */
+    getVisibleText: () => string;
+    /** Whether the typewriter has finished */
+    isComplete: () => boolean;
+    /** Current state */
+    state: TypewriterState;
+}
+declare function createAnimatedText(props: AnimatedTextProps): AnimatedTextAPI;
+declare function createTypewriter(props: TypewriterProps): TypewriterAPI;
+
+declare const animatedTextVariants: (props?: ({
+    state?: "entering" | "exiting" | "idle" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const typewriterVariants: (props?: ({
+    cursor?: "blinking" | "hidden" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type AnimatedTextAPI, type AnimatedTextProps, type AnimatedTextState, type TypewriterAPI, type TypewriterProps, type TypewriterState, animatedTextVariants, createAnimatedText, createTypewriter, typewriterVariants };

package/dist/internal/app-shell/index.d.cts

@@ -0,0 +1,128 @@
+type BreakpointName = 'mobile' | 'tablet' | 'desktop';
+interface AppShellConfig {
+    /** Sidebar width when expanded (default '16rem') */
+    sidebarWidth?: string;
+    /** Sidebar width when collapsed to icon-only (default '4rem') */
+    sidebarCollapsedWidth?: string;
+    /** Header height (default '3.5rem') */
+    headerHeight?: string;
+    /** Breakpoint below which layout is mobile (default 768) */
+    mobileBreakpoint?: number;
+    /** Breakpoint below which layout is tablet (default 1024) */
+    tabletBreakpoint?: number;
+    /** Sidebar position (default 'left') */
+    sidebarPosition?: 'left' | 'right';
+    /** Whether sidebar can be collapsed on desktop (default true) */
+    sidebarCollapsible?: boolean;
+    /** Whether sidebar starts collapsed on desktop (default false) */
+    sidebarDefaultCollapsed?: boolean;
+    /** Mobile nav position (default 'bottom') */
+    mobileNavPosition?: 'bottom' | 'none';
+}
+interface AppShellState {
+    /** On mobile: drawer open/closed */
+    sidebarOpen: boolean;
+    /** On desktop: full/icon-only */
+    sidebarCollapsed: boolean;
+    /** Current responsive breakpoint */
+    breakpoint: BreakpointName;
+    /** Convenience: breakpoint === 'mobile' */
+    isMobile: boolean;
+    /** Convenience: breakpoint === 'tablet' */
+    isTablet: boolean;
+    /** Convenience: breakpoint === 'desktop' */
+    isDesktop: boolean;
+}
+type AppShellSubscriber = (state: AppShellState) => void;
+interface AppShellAPI {
+    /** Current state (snapshot — will not mutate) */
+    state: AppShellState;
+    /** Resolved config with all defaults applied */
+    config: Required<AppShellConfig>;
+    /** Mobile: open/close drawer. Desktop: collapse/expand sidebar. */
+    toggleSidebar(): void;
+    /** Open sidebar (mobile drawer) */
+    openSidebar(): void;
+    /** Close sidebar (mobile drawer) */
+    closeSidebar(): void;
+    /** Collapse sidebar to icon-only (desktop) */
+    collapseSidebar(): void;
+    /** Expand sidebar from icon-only (desktop) */
+    expandSidebar(): void;
+    /** Update the current breakpoint */
+    setBreakpoint(bp: BreakpointName): void;
+    /** CSS custom property map for layout dimensions */
+    getCSSVariables(): Record<string, string>;
+    /** ARIA attributes for sidebar region */
+    sidebarAriaProps: Record<string, string>;
+    /** ARIA attributes for main region */
+    mainAriaProps: Record<string, string>;
+    /** ARIA attributes for header region */
+    headerAriaProps: Record<string, string>;
+    /** ARIA attributes for mobile bottom nav */
+    mobileNavAriaProps: Record<string, string>;
+    /** ARIA attributes for mobile sidebar overlay/backdrop */
+    overlayAriaProps: Record<string, string>;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(fn: AppShellSubscriber): () => void;
+}
+declare function resolveBreakpoint(width: number, mobileBp: number, tabletBp: number): BreakpointName;
+declare function createAppShell(config?: AppShellConfig): AppShellAPI;
+
+interface PageShellConfig {
+    /** Max width for contained sections (default '80rem') */
+    maxWidth?: string;
+    /** Navigation bar height (default '4rem') */
+    navHeight?: string;
+    /** Whether nav is transparent (for hero sections, default false) */
+    navTransparent?: boolean;
+    /** Whether nav is sticky (default true) */
+    navSticky?: boolean;
+    /** Number of footer columns (default 4) */
+    footerColumns?: number;
+}
+interface SectionConfig {
+    /** Whether section spans edge-to-edge (default false) */
+    fullWidth?: boolean;
+    /** Override max-width for this section */
+    maxWidth?: string;
+    /** Whether section has padding (default true) */
+    padding?: boolean;
+    /** Background variant */
+    background?: 'default' | 'muted' | 'primary' | 'none';
+}
+interface PageShellAPI {
+    /** Resolved config with all defaults applied */
+    config: Required<PageShellConfig>;
+    /** ARIA attributes for the nav region */
+    navAriaProps: Record<string, string>;
+    /** ARIA attributes for the footer region */
+    footerAriaProps: Record<string, string>;
+    /** Returns Tailwind utility classes for a section */
+    getSectionClasses(sectionConfig?: SectionConfig): string;
+    /** CSS custom property map */
+    getCSSVariables(): Record<string, string>;
+}
+declare function createPageShell(config?: PageShellConfig): PageShellAPI;
+
+interface AuthShellConfig {
+    /** Card max-width preset (default 'sm') */
+    maxWidth?: 'xs' | 'sm' | 'md';
+    /** Card position (default 'center') */
+    position?: 'center' | 'left';
+    /** Show decorative background pattern (default true) */
+    showBackground?: boolean;
+}
+interface AuthShellAPI {
+    /** Resolved config with all defaults */
+    config: Required<AuthShellConfig>;
+    /** Tailwind classes for the outer container */
+    containerClasses: string;
+    /** Tailwind classes for the card */
+    cardClasses: string;
+    /** ARIA attributes for the auth region */
+    ariaProps: Record<string, string>;
+}
+declare function createAuthShell(config?: AuthShellConfig): AuthShellAPI;
+
+export { type AppShellAPI, type AppShellConfig, type AppShellState, type AppShellSubscriber, type AuthShellAPI, type AuthShellConfig, type BreakpointName, type PageShellAPI, type PageShellConfig, type SectionConfig, createAppShell, createAuthShell, createPageShell, resolveBreakpoint };

package/dist/internal/app-shell/index.d.ts

@@ -0,0 +1,128 @@
+type BreakpointName = 'mobile' | 'tablet' | 'desktop';
+interface AppShellConfig {
+    /** Sidebar width when expanded (default '16rem') */
+    sidebarWidth?: string;
+    /** Sidebar width when collapsed to icon-only (default '4rem') */
+    sidebarCollapsedWidth?: string;
+    /** Header height (default '3.5rem') */
+    headerHeight?: string;
+    /** Breakpoint below which layout is mobile (default 768) */
+    mobileBreakpoint?: number;
+    /** Breakpoint below which layout is tablet (default 1024) */
+    tabletBreakpoint?: number;
+    /** Sidebar position (default 'left') */
+    sidebarPosition?: 'left' | 'right';
+    /** Whether sidebar can be collapsed on desktop (default true) */
+    sidebarCollapsible?: boolean;
+    /** Whether sidebar starts collapsed on desktop (default false) */
+    sidebarDefaultCollapsed?: boolean;
+    /** Mobile nav position (default 'bottom') */
+    mobileNavPosition?: 'bottom' | 'none';
+}
+interface AppShellState {
+    /** On mobile: drawer open/closed */
+    sidebarOpen: boolean;
+    /** On desktop: full/icon-only */
+    sidebarCollapsed: boolean;
+    /** Current responsive breakpoint */
+    breakpoint: BreakpointName;
+    /** Convenience: breakpoint === 'mobile' */
+    isMobile: boolean;
+    /** Convenience: breakpoint === 'tablet' */
+    isTablet: boolean;
+    /** Convenience: breakpoint === 'desktop' */
+    isDesktop: boolean;
+}
+type AppShellSubscriber = (state: AppShellState) => void;
+interface AppShellAPI {
+    /** Current state (snapshot — will not mutate) */
+    state: AppShellState;
+    /** Resolved config with all defaults applied */
+    config: Required<AppShellConfig>;
+    /** Mobile: open/close drawer. Desktop: collapse/expand sidebar. */
+    toggleSidebar(): void;
+    /** Open sidebar (mobile drawer) */
+    openSidebar(): void;
+    /** Close sidebar (mobile drawer) */
+    closeSidebar(): void;
+    /** Collapse sidebar to icon-only (desktop) */
+    collapseSidebar(): void;
+    /** Expand sidebar from icon-only (desktop) */
+    expandSidebar(): void;
+    /** Update the current breakpoint */
+    setBreakpoint(bp: BreakpointName): void;
+    /** CSS custom property map for layout dimensions */
+    getCSSVariables(): Record<string, string>;
+    /** ARIA attributes for sidebar region */
+    sidebarAriaProps: Record<string, string>;
+    /** ARIA attributes for main region */
+    mainAriaProps: Record<string, string>;
+    /** ARIA attributes for header region */
+    headerAriaProps: Record<string, string>;
+    /** ARIA attributes for mobile bottom nav */
+    mobileNavAriaProps: Record<string, string>;
+    /** ARIA attributes for mobile sidebar overlay/backdrop */
+    overlayAriaProps: Record<string, string>;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(fn: AppShellSubscriber): () => void;
+}
+declare function resolveBreakpoint(width: number, mobileBp: number, tabletBp: number): BreakpointName;
+declare function createAppShell(config?: AppShellConfig): AppShellAPI;
+
+interface PageShellConfig {
+    /** Max width for contained sections (default '80rem') */
+    maxWidth?: string;
+    /** Navigation bar height (default '4rem') */
+    navHeight?: string;
+    /** Whether nav is transparent (for hero sections, default false) */
+    navTransparent?: boolean;
+    /** Whether nav is sticky (default true) */
+    navSticky?: boolean;
+    /** Number of footer columns (default 4) */
+    footerColumns?: number;
+}
+interface SectionConfig {
+    /** Whether section spans edge-to-edge (default false) */
+    fullWidth?: boolean;
+    /** Override max-width for this section */
+    maxWidth?: string;
+    /** Whether section has padding (default true) */
+    padding?: boolean;
+    /** Background variant */
+    background?: 'default' | 'muted' | 'primary' | 'none';
+}
+interface PageShellAPI {
+    /** Resolved config with all defaults applied */
+    config: Required<PageShellConfig>;
+    /** ARIA attributes for the nav region */
+    navAriaProps: Record<string, string>;
+    /** ARIA attributes for the footer region */
+    footerAriaProps: Record<string, string>;
+    /** Returns Tailwind utility classes for a section */
+    getSectionClasses(sectionConfig?: SectionConfig): string;
+    /** CSS custom property map */
+    getCSSVariables(): Record<string, string>;
+}
+declare function createPageShell(config?: PageShellConfig): PageShellAPI;
+
+interface AuthShellConfig {
+    /** Card max-width preset (default 'sm') */
+    maxWidth?: 'xs' | 'sm' | 'md';
+    /** Card position (default 'center') */
+    position?: 'center' | 'left';
+    /** Show decorative background pattern (default true) */
+    showBackground?: boolean;
+}
+interface AuthShellAPI {
+    /** Resolved config with all defaults */
+    config: Required<AuthShellConfig>;
+    /** Tailwind classes for the outer container */
+    containerClasses: string;
+    /** Tailwind classes for the card */
+    cardClasses: string;
+    /** ARIA attributes for the auth region */
+    ariaProps: Record<string, string>;
+}
+declare function createAuthShell(config?: AuthShellConfig): AuthShellAPI;
+
+export { type AppShellAPI, type AppShellConfig, type AppShellState, type AppShellSubscriber, type AuthShellAPI, type AuthShellConfig, type BreakpointName, type PageShellAPI, type PageShellConfig, type SectionConfig, createAppShell, createAuthShell, createPageShell, resolveBreakpoint };

package/dist/internal/auth/index.d.cts

@@ -0,0 +1,74 @@
+/** User object — framework-agnostic, provider-agnostic */
+interface User {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    photoURL: string | null;
+    roles: string[];
+}
+/** Auth state */
+type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
+interface AuthState {
+    user: User | null;
+    status: AuthStatus;
+}
+/** OAuth providers */
+type OAuthProvider = string;
+/**
+ * AuthAdapter — interface implemented by provider adapters (e.g. Firebase, Supabase, Auth0).
+ * Consumers must provide an implementation of this adapter to the AuthProvider.
+ */
+interface AuthAdapter {
+    signIn(email: string, password: string): Promise<User>;
+    signInWithOAuth(provider: OAuthProvider): Promise<User>;
+    signUp(email: string, password: string, displayName: string): Promise<User>;
+    signOut(): Promise<void>;
+    resetPassword(email: string): Promise<void>;
+    getToken(): Promise<string | null>;
+    onAuthStateChange(callback: (user: User | null) => void): () => void;
+}
+interface AuthConfig {
+    /** The adapter implementation for your specific auth provider (Supabase, Firebase, Auth0, Custom, etc.) */
+    adapter: AuthAdapter;
+    /** Token refresh interval in minutes. Default: 50 */
+    tokenRefreshInterval?: number;
+    /** Enable E2E test mode with mock user */
+    testMode?: boolean;
+    /** Mock user for test mode */
+    testUser?: User;
+}
+
+interface AuthAPI {
+    getState(): AuthState;
+    signIn(email: string, password: string): Promise<User>;
+    signInWithOAuth(provider: OAuthProvider): Promise<User>;
+    signUp(email: string, password: string, displayName: string): Promise<User>;
+    signOut(): Promise<void>;
+    resetPassword(email: string): Promise<void>;
+    getToken(): Promise<string | null>;
+    subscribe(fn: (state: AuthState) => void): () => void;
+    destroy(): void;
+}
+declare function createAuth(adapter: AuthAdapter, config?: Omit<AuthConfig, 'adapter'>): AuthAPI;
+
+/** Check if user has a specific role */
+declare function hasRole(user: User | null, role: string): boolean;
+/** Check if user has any of the specified roles */
+declare function hasAnyRole(user: User | null, roles: string[]): boolean;
+/** Check if user has all of the specified roles */
+declare function hasAllRoles(user: User | null, roles: string[]): boolean;
+/** Convenience role checks */
+declare function canAccessAdmin(user: User | null): boolean;
+declare function canAccessReviewer(user: User | null): boolean;
+/** Get the default portal URL based on highest-privilege role */
+declare function getDefaultPortal(roles: string[]): string;
+/** Get roles that the given user can assign to others */
+declare function getAssignableRoles(user: User | null): string[];
+
+/**
+ * Mock auth adapter for testing and development.
+ * No external dependencies. Stores state in memory.
+ */
+declare function createMockAdapter(initialUser?: User): AuthAdapter;
+
+export { type AuthAPI, type AuthAdapter, type AuthConfig, type AuthState, type AuthStatus, type OAuthProvider, type User, canAccessAdmin, canAccessReviewer, createAuth, createMockAdapter, getAssignableRoles, getDefaultPortal, hasAllRoles, hasAnyRole, hasRole };

package/dist/internal/auth/index.d.ts

@@ -0,0 +1,74 @@
+/** User object — framework-agnostic, provider-agnostic */
+interface User {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    photoURL: string | null;
+    roles: string[];
+}
+/** Auth state */
+type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
+interface AuthState {
+    user: User | null;
+    status: AuthStatus;
+}
+/** OAuth providers */
+type OAuthProvider = string;
+/**
+ * AuthAdapter — interface implemented by provider adapters (e.g. Firebase, Supabase, Auth0).
+ * Consumers must provide an implementation of this adapter to the AuthProvider.
+ */
+interface AuthAdapter {
+    signIn(email: string, password: string): Promise<User>;
+    signInWithOAuth(provider: OAuthProvider): Promise<User>;
+    signUp(email: string, password: string, displayName: string): Promise<User>;
+    signOut(): Promise<void>;
+    resetPassword(email: string): Promise<void>;
+    getToken(): Promise<string | null>;
+    onAuthStateChange(callback: (user: User | null) => void): () => void;
+}
+interface AuthConfig {
+    /** The adapter implementation for your specific auth provider (Supabase, Firebase, Auth0, Custom, etc.) */
+    adapter: AuthAdapter;
+    /** Token refresh interval in minutes. Default: 50 */
+    tokenRefreshInterval?: number;
+    /** Enable E2E test mode with mock user */
+    testMode?: boolean;
+    /** Mock user for test mode */
+    testUser?: User;
+}
+
+interface AuthAPI {
+    getState(): AuthState;
+    signIn(email: string, password: string): Promise<User>;
+    signInWithOAuth(provider: OAuthProvider): Promise<User>;
+    signUp(email: string, password: string, displayName: string): Promise<User>;
+    signOut(): Promise<void>;
+    resetPassword(email: string): Promise<void>;
+    getToken(): Promise<string | null>;
+    subscribe(fn: (state: AuthState) => void): () => void;
+    destroy(): void;
+}
+declare function createAuth(adapter: AuthAdapter, config?: Omit<AuthConfig, 'adapter'>): AuthAPI;
+
+/** Check if user has a specific role */
+declare function hasRole(user: User | null, role: string): boolean;
+/** Check if user has any of the specified roles */
+declare function hasAnyRole(user: User | null, roles: string[]): boolean;
+/** Check if user has all of the specified roles */
+declare function hasAllRoles(user: User | null, roles: string[]): boolean;
+/** Convenience role checks */
+declare function canAccessAdmin(user: User | null): boolean;
+declare function canAccessReviewer(user: User | null): boolean;
+/** Get the default portal URL based on highest-privilege role */
+declare function getDefaultPortal(roles: string[]): string;
+/** Get roles that the given user can assign to others */
+declare function getAssignableRoles(user: User | null): string[];
+
+/**
+ * Mock auth adapter for testing and development.
+ * No external dependencies. Stores state in memory.
+ */
+declare function createMockAdapter(initialUser?: User): AuthAdapter;
+
+export { type AuthAPI, type AuthAdapter, type AuthConfig, type AuthState, type AuthStatus, type OAuthProvider, type User, canAccessAdmin, canAccessReviewer, createAuth, createMockAdapter, getAssignableRoles, getDefaultPortal, hasAllRoles, hasAnyRole, hasRole };

package/dist/internal/avatar/index.d.cts

@@ -0,0 +1,53 @@
+import { AccessibilityProps, TokenContract } from '../shared/index.cjs';
+
+type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type AvatarLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';
+interface AvatarProps {
+    src?: string;
+    alt?: string;
+    fallback?: string;
+    size?: AvatarSize;
+}
+interface AvatarAPI {
+    /** ARIA attributes to spread on the root element */
+    ariaProps: Partial<AccessibilityProps>;
+    /** Data attributes for CSS styling hooks */
+    dataAttributes: Record<string, string>;
+    /** Image ARIA props */
+    imageProps: {
+        alt: string;
+        role: string;
+    };
+    /** Fallback text (initials) */
+    fallbackText: string;
+    /** Current state */
+    state: {
+        size: AvatarSize;
+        hasSrc: boolean;
+    };
+}
+/**
+ * Extract initials from a name or fallback string.
+ * Takes first letter of first two words, uppercased.
+ */
+declare function getInitials(name: string): string;
+declare function createAvatar(props?: AvatarProps): AvatarAPI;
+
+declare const avatarTokens: TokenContract;
+declare const avatarVariants: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const avatarImageVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const avatarFallbackVariants: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type AvatarAPI, type AvatarLoadingStatus, type AvatarProps, type AvatarSize, avatarFallbackVariants, avatarImageVariants, avatarTokens, avatarVariants, createAvatar, getInitials };

package/dist/internal/avatar/index.d.ts

@@ -0,0 +1,53 @@
+import { AccessibilityProps, TokenContract } from '../shared/index.js';
+
+type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type AvatarLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';
+interface AvatarProps {
+    src?: string;
+    alt?: string;
+    fallback?: string;
+    size?: AvatarSize;
+}
+interface AvatarAPI {
+    /** ARIA attributes to spread on the root element */
+    ariaProps: Partial<AccessibilityProps>;
+    /** Data attributes for CSS styling hooks */
+    dataAttributes: Record<string, string>;
+    /** Image ARIA props */
+    imageProps: {
+        alt: string;
+        role: string;
+    };
+    /** Fallback text (initials) */
+    fallbackText: string;
+    /** Current state */
+    state: {
+        size: AvatarSize;
+        hasSrc: boolean;
+    };
+}
+/**
+ * Extract initials from a name or fallback string.
+ * Takes first letter of first two words, uppercased.
+ */
+declare function getInitials(name: string): string;
+declare function createAvatar(props?: AvatarProps): AvatarAPI;
+
+declare const avatarTokens: TokenContract;
+declare const avatarVariants: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const avatarImageVariants: (props?: ({
+    [x: string]: string | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const avatarFallbackVariants: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { type AvatarAPI, type AvatarLoadingStatus, type AvatarProps, type AvatarSize, avatarFallbackVariants, avatarImageVariants, avatarTokens, avatarVariants, createAvatar, getInitials };

package/dist/internal/avatar-group/index.d.cts

@@ -0,0 +1,70 @@
+import { AccessibilityProps } from '../shared/index.cjs';
+
+type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type PresenceStatus = 'online' | 'offline' | 'away' | 'busy' | 'dnd';
+interface AvatarUser {
+    /** Unique identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Avatar image URL */
+    src?: string;
+    /** Online presence status */
+    status?: PresenceStatus;
+}
+interface AvatarGroupProps {
+    /** Array of users to display */
+    users: AvatarUser[];
+    /** Maximum number of visible avatars */
+    max?: number;
+    /** Avatar size */
+    size?: AvatarSize;
+}
+interface AvatarGroupAPI {
+    /** Users that are visible (within max limit) */
+    visibleUsers: AvatarUser[];
+    /** Number of overflow users */
+    overflowCount: number;
+    /** All overflow users (for tooltip/popup) */
+    overflowUsers: AvatarUser[];
+    /** ARIA props for the group container */
+    ariaProps: Partial<AccessibilityProps> & Record<string, unknown>;
+    /** Get ARIA props for an individual avatar */
+    getAvatarAriaProps(user: AvatarUser): Record<string, unknown>;
+    /** Get initials from a user's name */
+    getInitials(name: string): string;
+    /** Get the overflow badge ARIA props */
+    overflowBadgeProps: Record<string, unknown>;
+    /** Generated IDs */
+    ids: {
+        group: string;
+        label: string;
+    };
+}
+declare const AVATAR_SIZES: Record<AvatarSize, {
+    width: number;
+    fontSize: number;
+}>;
+declare function getInitials(name: string): string;
+declare function createAvatarGroup(props: AvatarGroupProps): AvatarGroupAPI;
+
+declare const avatarGroupStyles = "flex items-center -space-x-2";
+declare const avatarVariants: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const avatarOverflowBadgeVariants: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+declare const avatarImageStyles = "h-full w-full object-cover";
+declare const avatarPresenceDotVariants: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+    status?: "online" | "offline" | "away" | "busy" | "dnd" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+
+export { AVATAR_SIZES, type AvatarGroupAPI, type AvatarGroupProps, type AvatarSize, type AvatarUser, type PresenceStatus, avatarGroupStyles, avatarImageStyles, avatarOverflowBadgeVariants, avatarPresenceDotVariants, avatarVariants, createAvatarGroup, getInitials };