@exotic-holidays/ui 0.1.0

package/src/base-components/Badge.tsx

@@ -0,0 +1,191 @@
+'use client';
+
+import React from 'react';
+import { cva } from 'class-variance-authority';
+import { block, modifier } from '../helpers/bem';
+import { cn } from '../helpers/cn';
+
+export interface BadgeProps {
+  children?: React.ReactNode;
+  variant?: 'solid' | 'bordered' | 'light' | 'shadow' | 'dot' | 'flat';
+  color?: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+  size?: 'small' | 'medium' | 'large';
+  radius?: 'full' | 'medium' | 'small';
+  isDisabled?: boolean;
+  startContent?: React.ReactNode;
+  endContent?: React.ReactNode;
+  ariaLabel?: string;
+  className?: string;
+  /** BEM class name prefix (default 'aceui'). Usually set via AceUIProvider when using @aceuidev/core. */
+  prefix?: string;
+  testId?: string;
+}
+
+export const badgeVariants = cva(
+  [
+    'inline-flex items-center justify-center gap-[8px] font-medium leading-none whitespace-nowrap box-border',
+  ],
+  {
+    variants: {
+      variant: {
+        solid: '',
+        bordered: '',
+        light: '',
+        shadow: '',
+        dot: '',
+        flat: '',
+      },
+      color: {
+        default: '',
+        primary: '',
+        secondary: '',
+        success: '',
+        warning: '',
+        danger: '',
+      },
+      size: {
+        small: 'text-[0.75rem] py-1 px-[8px] min-h-6',
+        medium: 'text-[0.875rem] py-1.5 px-[12px] min-h-7',
+        large: 'text-[1rem] py-1.5 px-[12px] min-h-8',
+      },
+      radius: {
+        full: 'rounded-full',
+        medium: 'rounded-[12px]',
+        small: 'rounded-[8px]',
+      },
+      isDisabled: {
+        true: 'opacity-[0.5] cursor-default',
+        false: '',
+      },
+    },
+    compoundVariants: [
+      // Solid (no border)
+      { variant: 'solid', color: 'default', class: 'border-0 bg-default-500 text-default-foreground' },
+      { variant: 'solid', color: 'primary', class: 'border-0 bg-primary-500 text-primary-foreground' },
+      { variant: 'solid', color: 'secondary', class: 'border-0 bg-secondary-500 text-secondary-foreground' },
+      { variant: 'solid', color: 'success', class: 'border-0 bg-success-500 text-success-foreground' },
+      { variant: 'solid', color: 'warning', class: 'border-0 bg-warning-500 text-warning-foreground' },
+      { variant: 'solid', color: 'danger', class: 'border-0 bg-danger-500 text-danger-foreground' },
+      // Bordered
+      { variant: 'bordered', color: 'default', class: 'bg-transparent text-default-500 border border-default-500' },
+      { variant: 'bordered', color: 'primary', class: 'bg-transparent text-primary-500 border border-primary-500' },
+      { variant: 'bordered', color: 'secondary', class: 'bg-transparent text-secondary-500 border border-secondary-500' },
+      { variant: 'bordered', color: 'success', class: 'bg-transparent text-success-500 border border-success-500' },
+      { variant: 'bordered', color: 'warning', class: 'bg-transparent text-warning-500 border border-warning-500' },
+      { variant: 'bordered', color: 'danger', class: 'bg-transparent text-danger-500 border border-danger-500' },
+      // Light (no border)
+      { variant: 'light', color: 'default', class: 'border-0 bg-default-50 text-default-500' },
+      { variant: 'light', color: 'primary', class: 'border-0 bg-primary-50 text-primary-500' },
+      { variant: 'light', color: 'secondary', class: 'border-0 bg-secondary-50 text-secondary-500' },
+      { variant: 'light', color: 'success', class: 'border-0 bg-success-50 text-success-500' },
+      { variant: 'light', color: 'warning', class: 'border-0 bg-warning-50 text-warning-500' },
+      { variant: 'light', color: 'danger', class: 'border-0 bg-danger-50 text-danger-500' },
+      // Shadow (no border; box-shadow via inline style)
+      { variant: 'shadow', color: 'default', class: 'border-0 bg-default-500 text-default-foreground' },
+      { variant: 'shadow', color: 'primary', class: 'border-0 bg-primary-500 text-primary-foreground' },
+      { variant: 'shadow', color: 'secondary', class: 'border-0 bg-secondary-500 text-secondary-foreground' },
+      { variant: 'shadow', color: 'success', class: 'border-0 bg-success-500 text-success-foreground' },
+      { variant: 'shadow', color: 'warning', class: 'border-0 bg-warning-500 text-warning-foreground' },
+      { variant: 'shadow', color: 'danger', class: 'border-0 bg-danger-500 text-danger-foreground' },
+      // Dot (no border)
+      { variant: 'dot', color: 'default', class: 'border-0 bg-default-200 text-default-700' },
+      { variant: 'dot', color: 'primary', class: 'border-0 bg-primary-50 text-primary-600' },
+      { variant: 'dot', color: 'secondary', class: 'border-0 bg-secondary-50 text-secondary-600' },
+      { variant: 'dot', color: 'success', class: 'border-0 bg-success-50 text-success-600' },
+      { variant: 'dot', color: 'warning', class: 'border-0 bg-warning-50 text-warning-600' },
+      { variant: 'dot', color: 'danger', class: 'border-0 bg-danger-50 text-danger-600' },
+      // Flat (light background)
+      { variant: 'flat', color: 'default', class: 'border-0 bg-surface-0 text-foreground-muted' },
+      { variant: 'flat', color: 'primary', class: 'border-0 bg-primary/10 text-primary' },
+      { variant: 'flat', color: 'secondary', class: 'border-0 bg-secondary/10 text-secondary' },
+      { variant: 'flat', color: 'success', class: 'border-0 bg-success/10 text-success' },
+      { variant: 'flat', color: 'warning', class: 'border-0 bg-warning/10 text-warning' },
+      { variant: 'flat', color: 'danger', class: 'border-0 bg-danger-alt/10 text-danger-alt' },
+    ],
+    defaultVariants: {
+      variant: 'solid',
+      color: 'primary',
+      size: 'medium',
+      radius: 'full',
+      isDisabled: false,
+    },
+  },
+);
+
+const dotColorMap: Record<string, string> = {
+  default: 'bg-default-500',
+  primary: 'bg-primary-500',
+  secondary: 'bg-secondary-500',
+  success: 'bg-success-500',
+  warning: 'bg-warning-500',
+  danger: 'bg-danger-500',
+};
+
+export const Badge = ({
+  children,
+  variant = 'solid',
+  color = 'primary',
+  size = 'medium',
+  radius = 'full',
+  isDisabled = false,
+  startContent,
+  endContent,
+  ariaLabel,
+  className,
+  prefix = 'aceui',
+  testId,
+}: BadgeProps) => {
+  const blockClass = block(prefix, 'badge');
+  const bemClasses = [
+    blockClass,
+    modifier(prefix, 'badge', variant),
+    modifier(prefix, 'badge', color),
+    modifier(prefix, 'badge', size),
+    modifier(prefix, 'badge', radius),
+    isDisabled && modifier(prefix, 'badge', 'disabled'),
+  ].filter(Boolean) as string[];
+
+  const shadowStyle =
+    variant === 'shadow'
+      ? {
+        boxShadow: `0 2px 8px 0 color-mix(in srgb, var(--color-${color}-500) calc(var(--aceui-badge-shadow-opacity) * 100%), transparent)`,
+      }
+      : undefined;
+
+  const showDot = variant === 'dot';
+
+  return (
+    <span
+      className={cn(bemClasses, badgeVariants({ variant, color, size, radius, isDisabled }), className)}
+      style={shadowStyle}
+      aria-disabled={isDisabled ? true : undefined}
+      aria-label={ariaLabel}
+      data-testid={testId}
+    >
+      {startContent != null ? (
+        <span className="inline-flex items-center leading-none">{startContent}</span>
+      ) : null}
+      {showDot ? (
+        <span
+          className={cn('w-2 h-2 rounded-full shrink-0', dotColorMap[color])}
+          aria-hidden
+        />
+      ) : null}
+      {children != null ? (
+        <span
+          className={cn(
+            'inline-flex items-center leading-none',
+            size !== 'small' && '-translate-y-[0.06em]',
+          )}
+        >
+          {children}
+        </span>
+      ) : null}
+      {endContent != null ? (
+        <span className="inline-flex items-center leading-none">{endContent}</span>
+      ) : null}
+    </span>
+  );
+};
+
+Badge.displayName = 'Badge';

package/src/base-components/Button.tsx

@@ -0,0 +1,331 @@
+'use client';
+
+import React, { useState, useRef } from 'react';
+import { motion } from 'framer-motion';
+import { cva } from 'class-variance-authority';
+import { block, modifier } from '../helpers/bem';
+import { cn } from '../helpers/cn';
+
+/**
+ * Button component props interface
+ */
+export interface ButtonProps {
+  /** The content to display inside the button */
+  children?: React.ReactNode;
+
+  /** The visual style variant of the button */
+  variant?: 'solid' | 'bordered' | 'light' | 'flat' | 'shadow' | 'ghost';
+
+  /** The color scheme of the button */
+  color?: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+
+  /** The size of the button */
+  size?: 'small' | 'medium' | 'large';
+
+  /** The border radius of the button */
+  radius?: 'none' | 'small' | 'medium' | 'large' | 'full' | 'squircle';
+
+  /** Whether the button is disabled */
+  isDisabled?: boolean;
+
+  /** Whether the button is in loading state */
+  isLoading?: boolean;
+
+  /** Icon element to display */
+  icon?: React.ReactNode;
+
+  /** Position of the icon relative to text */
+  iconPosition?: 'left' | 'right';
+
+  /** Custom text to show during loading state */
+  loadingText?: string;
+
+  /** Click event handler */
+  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+
+  /** Accessible label for screen readers */
+  ariaLabel?: string;
+
+  /** HTML button type */
+  type?: 'button' | 'submit' | 'reset';
+
+  /** Whether to disable the click wave (ripple) effect */
+  disableWave?: boolean;
+
+  /** Custom width (any valid CSS width: e.g. "4rem", "auto", "10px", "100%", "100vw") */
+  width?: React.CSSProperties['width'];
+
+  /** Additional CSS class names */
+  className?: string;
+
+  /** BEM class name prefix (default 'aceui'). Usually set via AceUIProvider when using @aceuidev/core. */
+  prefix?: string;
+
+  /** Test ID for testing */
+  testId?: string;
+}
+
+const iconSizeMap = {
+  small: 'w-4 h-4',
+  medium: 'w-5 h-5',
+  large: 'w-6 h-6',
+} as const;
+
+export const buttonVariants = cva(
+  [
+    'inline-flex items-center justify-center gap-2 font-[inherit] font-medium cursor-pointer transition-all duration-200 relative whitespace-nowrap select-none outline-none overflow-hidden',
+    'focus-visible:outline-2 focus-visible:outline-[var(--aceui-color-focus)] focus-visible:outline-offset-2',
+  ],
+  {
+    variants: {
+      variant: {
+        solid: '',
+        bordered: '',
+        light: '',
+        flat: '',
+        shadow: '',
+        ghost: '',
+      },
+      color: {
+        default: '',
+        primary: '',
+        secondary: '',
+        success: '',
+        warning: '',
+        danger: '',
+      },
+      size: {
+        small: 'text-[0.75rem] leading-[1rem] px-3 min-h-8',
+        medium: 'text-[0.875rem] leading-[1.25rem] px-4 min-h-10',
+        large: 'text-[1rem] leading-[1.5rem] px-6 min-h-12',
+      },
+      radius: {
+        none: 'rounded-none',
+        small: 'rounded-[8px]',
+        medium: 'rounded-[12px]',
+        large: 'rounded-[14px]',
+        full: 'rounded-full',
+        squircle: 'rounded-full',
+      },
+      isIconOnly: {
+        true: 'aspect-square !px-0 w-auto',
+        false: '',
+      },
+    },
+    compoundVariants: [
+      /* Solid */
+      { variant: 'solid', color: 'default', class: 'border-none bg-default-500 text-default-foreground hover:bg-default-600 active:bg-default-700' },
+      { variant: 'solid', color: 'primary', class: 'border-none bg-primary-500 text-primary-foreground hover:bg-primary-600 active:bg-primary-700' },
+      { variant: 'solid', color: 'secondary', class: 'border-none bg-secondary-500 text-secondary-foreground hover:bg-secondary-600 active:bg-secondary-700' },
+      { variant: 'solid', color: 'success', class: 'border-none bg-success-500 text-success-foreground hover:bg-success-600 active:bg-success-700' },
+      { variant: 'solid', color: 'warning', class: 'border-none bg-warning-500 text-warning-foreground hover:bg-warning-600 active:bg-warning-700' },
+      { variant: 'solid', color: 'danger', class: 'border-none bg-danger-500 text-danger-foreground hover:bg-danger-600 active:bg-danger-700' },
+      /* Bordered */
+      { variant: 'bordered', color: 'default', class: 'bg-transparent text-foreground-1 border-[1px] border-border-strong hover:bg-surface-hover' },
+      { variant: 'bordered', color: 'primary', class: 'bg-transparent text-primary-500 border-[1px] border-primary-500 hover:bg-primary-50' },
+      { variant: 'bordered', color: 'secondary', class: 'bg-transparent text-foreground-1 border-[1px] border-border-strong hover:bg-surface-hover' },
+      { variant: 'bordered', color: 'success', class: 'bg-transparent text-success-500 border-[1px] border-success-500 hover:bg-success-50' },
+      { variant: 'bordered', color: 'warning', class: 'bg-transparent text-warning-500 border-[1px] border-warning-500 hover:bg-warning-50' },
+      { variant: 'bordered', color: 'danger', class: 'bg-transparent text-danger-500 border-[1px] border-danger-500 hover:bg-danger-50' },
+      /* Light */
+      { variant: 'light', color: 'default', class: 'bg-surface-hover text-foreground-1 border-none hover:bg-surface-subtle hover:text-foreground-0' },
+      { variant: 'light', color: 'primary', class: 'bg-primary-50 text-primary-500 border-none hover:bg-primary-100' },
+      { variant: 'light', color: 'secondary', class: 'bg-surface-hover text-foreground-1 border-none hover:bg-surface-subtle hover:text-foreground-0' },
+      { variant: 'light', color: 'success', class: 'bg-success-50 text-success-500 border-none hover:bg-success-100' },
+      { variant: 'light', color: 'warning', class: 'bg-warning-50 text-warning-500 border-none hover:bg-warning-100' },
+      { variant: 'light', color: 'danger', class: 'bg-danger-50 text-danger-500 border-none hover:bg-danger-100' },
+      /* Flat */
+      { variant: 'flat', color: 'default', class: 'bg-transparent text-foreground-1 border-none hover:bg-surface-hover hover:text-foreground-0' },
+      { variant: 'flat', color: 'primary', class: 'bg-transparent text-primary-500 border-none hover:bg-primary-50' },
+      { variant: 'flat', color: 'secondary', class: 'bg-transparent text-foreground-1 border-none hover:bg-surface-hover hover:text-foreground-0' },
+      { variant: 'flat', color: 'success', class: 'bg-transparent text-success-500 border-none hover:bg-success-50' },
+      { variant: 'flat', color: 'warning', class: 'bg-transparent text-warning-500 border-none hover:bg-warning-50' },
+      { variant: 'flat', color: 'danger', class: 'bg-transparent text-danger-500 border-none hover:bg-danger-50' },
+      /* Shadow */
+      { variant: 'shadow', color: 'default', class: 'border-none bg-default-500 text-default-foreground hover:bg-default-600 active:bg-default-700' },
+      { variant: 'shadow', color: 'primary', class: 'border-none bg-primary-500 text-primary-foreground hover:bg-primary-600 active:bg-primary-700' },
+      { variant: 'shadow', color: 'secondary', class: 'border-none bg-secondary-500 text-secondary-foreground hover:bg-secondary-600 active:bg-secondary-700' },
+      { variant: 'shadow', color: 'success', class: 'border-none bg-success-500 text-success-foreground hover:bg-success-600 active:bg-success-700' },
+      { variant: 'shadow', color: 'warning', class: 'border-none bg-warning-500 text-warning-foreground hover:bg-warning-600 active:bg-warning-700' },
+      { variant: 'shadow', color: 'danger', class: 'border-none bg-danger-500 text-danger-foreground hover:bg-danger-600 active:bg-danger-700' },
+      /* Ghost */
+      { variant: 'ghost', color: 'default', class: 'border-none bg-transparent text-foreground-1 hover:bg-surface-hover hover:text-foreground-0' },
+      { variant: 'ghost', color: 'primary', class: 'border-none bg-transparent text-primary-500 hover:bg-primary-500 hover:text-primary-foreground' },
+      { variant: 'ghost', color: 'secondary', class: 'border-none bg-transparent text-foreground-1 hover:bg-surface-hover hover:text-foreground-0' },
+      { variant: 'ghost', color: 'success', class: 'border-none bg-transparent text-success-500 hover:bg-success-500 hover:text-success-foreground' },
+      { variant: 'ghost', color: 'warning', class: 'border-none bg-transparent text-warning-500 hover:bg-warning-500 hover:text-warning-foreground' },
+      { variant: 'ghost', color: 'danger', class: 'border-none bg-transparent text-danger-500 hover:bg-danger-500 hover:text-danger-foreground' },
+      /* Icon-only size overrides */
+      { isIconOnly: true, size: 'small', class: 'p-2 min-w-8' },
+      { isIconOnly: true, size: 'medium', class: 'p-3 min-w-10' },
+      { isIconOnly: true, size: 'large', class: 'p-4 min-w-12' },
+    ],
+    defaultVariants: {
+      variant: 'solid',
+      color: 'primary',
+      size: 'medium',
+      radius: 'medium',
+      isIconOnly: false,
+    },
+  }
+);
+
+export const Button = ({
+  children,
+  variant = 'solid',
+  color = 'primary',
+  size = 'medium',
+  radius = 'squircle',
+  isDisabled = false,
+  isLoading = false,
+  icon,
+  iconPosition = 'left',
+  loadingText,
+  onClick,
+  ariaLabel,
+  type = 'button',
+  width,
+  className = '',
+  prefix = 'aceui',
+  testId,
+  disableWave = false,
+}: ButtonProps) => {
+  const isIconOnly = Boolean(!children && icon);
+  const isActuallyDisabled = isDisabled || isLoading;
+
+  const blockClass = block(prefix, 'button');
+  const bemClasses = [
+    blockClass,
+    modifier(prefix, 'button', variant),
+    modifier(prefix, 'button', color),
+    modifier(prefix, 'button', size),
+    modifier(prefix, 'button', radius),
+    isActuallyDisabled && modifier(prefix, 'button', 'disabled'),
+    isLoading && modifier(prefix, 'button', 'loading'),
+    isIconOnly && modifier(prefix, 'button', 'icon-only'),
+  ].filter(Boolean) as string[];
+
+  const [wave, setWave] = useState<{ x: number; y: number; size: number; key: number } | null>(null);
+  const waveKeyRef = useRef(0);
+
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    if (isActuallyDisabled) {
+      event.preventDefault();
+      return;
+    }
+    if (!disableWave) {
+      const el = event.currentTarget;
+      const rect = el.getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const y = event.clientY - rect.top;
+      const size = 2 * Math.max(rect.width, rect.height);
+      waveKeyRef.current += 1;
+      setWave({ x, y, size, key: waveKeyRef.current });
+    }
+    onClick?.(event);
+  };
+
+  const shadowStyle =
+    variant === 'shadow'
+      ? {
+        boxShadow: `0 4px 14px 0 color-mix(in srgb, var(--color-${color}-500) 40%, transparent)`,
+      }
+      : undefined;
+  // const cornerShapeStyle = radius === 'squircle' ? {
+  //   cornerShape: 'squircle',
+  // } : undefined;
+  // const style = { ...shadowStyle, ...cornerShapeStyle, ...(width != null ? { width } : {}) };
+  const style = { ...shadowStyle, ...(width != null ? { width } : {}) };
+
+  const renderContent = () => {
+    if (isLoading) {
+      return (
+        <>
+          <span
+            className="inline-block w-[1em] h-[1em] border-2 border-current border-r-transparent rounded-full animate-spin"
+            aria-hidden="true"
+          />
+          {loadingText && <span className="inline-block leading-none">{loadingText}</span>}
+          {!loadingText && children && <span className="inline-block leading-none">{children}</span>}
+        </>
+      );
+    }
+
+    if (isIconOnly) {
+      return (
+        <span className={cn('inline-flex items-center justify-center shrink-0', iconSizeMap[size])}>
+          {icon}
+        </span>
+      );
+    }
+
+    if (icon) {
+      const iconElement = (
+        <span className={cn('inline-flex items-center justify-center shrink-0', iconSizeMap[size])}>
+          {icon}
+        </span>
+      );
+      const textElement = children && <span className="inline-block leading-none">{children}</span>;
+
+      return iconPosition === 'left' ? (
+        <>
+          {iconElement}
+          {textElement}
+        </>
+      ) : (
+        <>
+          {textElement}
+          {iconElement}
+        </>
+      );
+    }
+
+    return children ? <span className="inline-block leading-none">{children}</span> : null;
+  };
+
+  return (
+    <button
+      type={type}
+      className={cn(
+        bemClasses,
+        buttonVariants({
+          variant,
+          color,
+          size,
+          radius,
+          isIconOnly,
+        }),
+        isActuallyDisabled ? '!opacity-50 !cursor-not-allowed pointer-events-none' : '',
+        className
+      )}
+      style={Object.keys(style).length > 0 ? style : undefined}
+      disabled={isActuallyDisabled}
+      onClick={handleClick}
+      aria-label={ariaLabel}
+      aria-busy={isLoading ? 'true' : undefined}
+      data-testid={testId}
+    >
+      {wave && (
+        <motion.span
+          key={wave.key}
+          className="absolute rounded-full pointer-events-none"
+          style={{
+            left: wave.x,
+            top: wave.y,
+            width: wave.size,
+            height: wave.size,
+            background: 'color-mix(in srgb, currentColor 30%, transparent)',
+          }}
+          initial={{ scale: 0, x: '-50%', y: '-50%', opacity: 1 }}
+          animate={{ scale: 1, x: '-50%', y: '-50%', opacity: 0 }}
+          transition={{ duration: 0.65, ease: 'easeOut' }}
+          onAnimationComplete={() => setWave(null)}
+          aria-hidden="true"
+        />
+      )}
+      {renderContent()}
+    </button>
+  );
+};
+
+Button.displayName = 'Button';

package/src/base-components/ButtonGroup.tsx

@@ -0,0 +1,149 @@
+'use client';
+
+import React from 'react';
+import { block, modifier } from '../helpers/bem';
+import { cn } from '../helpers/cn';
+
+/**
+ * ButtonGroup component props interface
+ */
+export interface ButtonGroupProps {
+  /** Button components (or compatible elements) to group */
+  children?: React.ReactNode;
+
+  /** When true, disables all buttons inside the group */
+  isDisabled?: boolean;
+
+  /** Layout direction of the group */
+  orientation?: 'horizontal' | 'vertical';
+
+  /** Accessible label for the group */
+  ariaLabel?: string;
+
+  /** Additional CSS class names */
+  className?: string;
+
+  /** BEM class name prefix (default 'aceui'). Usually set via AceUIProvider when using @aceuidev/core. */
+  prefix?: string;
+
+  /** Test ID for testing */
+  testId?: string;
+}
+
+const BUTTON_DISABLED_PROP = 'isDisabled';
+
+function isReactElement(child: React.ReactNode): child is React.ReactElement<Record<string, unknown>> {
+  return typeof child === 'object' && child !== null && 'type' in child && 'props' in child;
+}
+
+function getPositionClasses(
+  isHorizontal: boolean,
+  isFirst: boolean,
+  isLast: boolean
+): string {
+  if (isFirst && isLast) return '';
+  if (isHorizontal) {
+    if (isFirst) return '!rounded-tr-none !rounded-br-none';
+    if (isLast) return '!rounded-tl-none !rounded-bl-none';
+    return '!rounded-none';
+  }
+  if (isFirst) return '!rounded-bl-none !rounded-br-none';
+  if (isLast) return '!rounded-tl-none !rounded-tr-none';
+  return '!rounded-none';
+}
+
+function getBorderCollapseClass(
+  isHorizontal: boolean,
+  isLast: boolean,
+  child: React.ReactElement<Record<string, unknown>>
+): string {
+  if (isLast) return '';
+  if (child.props?.variant !== 'bordered') return '';
+  return isHorizontal ? '!border-r-0' : '!border-b-0';
+}
+
+/**
+ * Groups multiple Button components into a single visual unit.
+ * Supports horizontal/vertical layout, seamless styling, and group-level isDisabled.
+ *
+ * @example
+ * ```tsx
+ * <ButtonGroup>
+ *   <Button>One</Button>
+ *   <Button>Two</Button>
+ *   <Button>Three</Button>
+ * </ButtonGroup>
+ * ```
+ */
+export const ButtonGroup = ({
+  children,
+  isDisabled = false,
+  orientation = 'horizontal',
+  ariaLabel,
+  className = '',
+  prefix = 'aceui',
+  testId,
+}: ButtonGroupProps) => {
+  const isHorizontal = orientation === 'horizontal';
+
+  const blockClass = block(prefix, 'button-group');
+  const bemClasses = [
+    blockClass,
+    modifier(prefix, 'button-group', orientation),
+    isDisabled && modifier(prefix, 'button-group', 'disabled'),
+  ].filter(Boolean) as string[];
+
+  const classes = cn(
+    bemClasses,
+    'inline-flex items-stretch gap-0',
+    isHorizontal ? 'flex-row' : 'flex-col',
+    className
+  );
+
+  const allChildren = React.Children.toArray(children);
+  const elementChildren = allChildren.filter(isReactElement);
+  const elementCount = elementChildren.length;
+  let elementIdx = 0;
+
+  const renderedChildren = allChildren.map((child, mapIdx) => {
+    if (!isReactElement(child)) {
+      if (isDisabled && child != null) {
+        return (
+          <div key={mapIdx} style={{ pointerEvents: 'none' }} aria-disabled="true">
+            {child}
+          </div>
+        );
+      }
+      return child;
+    }
+
+    const idx = elementIdx++;
+    const isFirst = idx === 0;
+    const isLast = idx === elementCount - 1;
+
+    const positionCls = getPositionClasses(isHorizontal, isFirst, isLast);
+    const borderCls = getBorderCollapseClass(isHorizontal, isLast, child);
+    const extraClasses = cn(positionCls, borderCls);
+
+    const props: Record<string, unknown> = {};
+    if (isDisabled) props[BUTTON_DISABLED_PROP] = true;
+    if (extraClasses) props.className = cn(child.props?.className as string, extraClasses);
+
+    return Object.keys(props).length > 0
+      ? React.cloneElement(child, props)
+      : child;
+  });
+
+  return (
+    <div
+      role="group"
+      className={classes}
+      aria-label={ariaLabel}
+      data-testid={testId}
+    >
+      {renderedChildren}
+    </div>
+  );
+};
+
+ButtonGroup.displayName = 'ButtonGroup';