xrpl-dev-portal/shared/components/CardOffgrid/CardOffgrid.tsx

import React, { useState, useCallback } from 'react';
import clsx from 'clsx';

export interface CardOffgridProps {
  /** Color variant of the card */
  variant?: 'neutral' | 'green';
  /** Icon element or image source */
  icon: React.ReactNode | string;
  /** Card title (supports multi-line via \n) */
  title: string;
  /** Card description text */
  description: string;
  /** Click handler */
  onClick?: () => void;
  /** Link destination (renders as anchor if provided) */
  href?: string;
  /** Disabled state */
  disabled?: boolean;
  /** Optional className for custom styling */
  className?: string;
}

/**
 * BDS CardOffgrid Component
 * 
 * A versatile card component for displaying feature highlights with an icon,
 * title, and description. Supports neutral and green color variants with
 * interactive states (hover, focus, pressed, disabled).
 * 
 * Features a "window shade" color wipe animation:
 * - Hover in: shade rises from bottom to top (reveals hover color)
 * - Hover out: shade falls from top to bottom (hides hover color)
 * 
 * @example
 * // Basic neutral card
 * <CardOffgrid
 *   variant="neutral"
 *   icon={<MetadataIcon />}
 *   title="Onchain Metadata"
 *   description="Easily store key asset information."
 *   onClick={() => console.log('clicked')}
 * />
 * 
 * @example
 * // Green card with link
 * <CardOffgrid
 *   variant="green"
 *   icon="/icons/metadata.svg"
 *   title="Onchain Metadata"
 *   description="Easily store key asset information."
 *   href="/docs/metadata"
 * />
 */
export const CardOffgrid: React.FC<CardOffgridProps> = ({
  variant = 'neutral',
  icon,
  title,
  description,
  onClick,
  href,
  disabled = false,
  className = '',
}) => {
  // Track hover state for animation
  const [isHovered, setIsHovered] = useState(false);

  const handleMouseEnter = useCallback(() => {
    if (!disabled) {
      setIsHovered(true);
    }
  }, [disabled]);

  const handleMouseLeave = useCallback(() => {
    if (!disabled) {
      setIsHovered(false);
    }
  }, [disabled]);

  // A card with neither `href` nor `onClick` has nothing to activate, so it gets
  // none of the interactive affordances: no pointer cursor, no color wipe, no
  // pressed state. Hover tracking is what drives the wipe, so a static card
  // doesn't even listen for it.
  const isInteractive = !disabled && Boolean(href || onClick);

  const hoverHandlers = isInteractive
    ? { onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave }
    : {};

  // Build class names using BEM with bds namespace
  const classNames = clsx(
    'bds-card-offgrid',
    `bds-card-offgrid--${variant}`,
    {
      'bds-card-offgrid--disabled': disabled,
      'bds-card-offgrid--static': !isInteractive && !disabled,
      'bds-card-offgrid--hovered': isHovered,
    },
    className
  );

  // Render icon - supports both React nodes and image URLs
  const renderIcon = () => {
    if (typeof icon === 'string') {
      return (
        <img
          src={icon}
          alt=""
          className="bds-card-offgrid__icon-image"
          aria-hidden="true"
          loading="lazy"
          decoding="async"
        />
      );
    }
    return icon;
  };

  // Split title by newline for multi-line support
  const renderTitle = () => {
    const lines = title.split('\n');
    return lines.map((line, index) => (
      <React.Fragment key={index}>
        {line}
        {index < lines.length - 1 && <br />}
      </React.Fragment>
    ));
  };

  // Common content for both button and anchor
  const content = (
    <>
      {/* Hover color wipe overlay - interactive cards only */}
      {isInteractive && (
        <span className="bds-card-offgrid__overlay" aria-hidden="true" />
      )}
      
      <span className="bds-card-offgrid__icon-container">
        {renderIcon()}
      </span>
      
      <span className="bds-card-offgrid__content">
        <span className="bds-card-offgrid__title sh-lg-l">
          {renderTitle()}
        </span>
        <span className="bds-card-offgrid__description body-l">
          {description}
        </span>
      </span>
    </>
  );

  // Render as anchor if href is provided
  if (href && !disabled) {
    return (
      <a
        href={href}
        className={classNames}
        aria-disabled={disabled}
        {...hoverHandlers}
      >
        {content}
      </a>
    );
  }

  // Render as button when an onClick handler exists (or the card is disabled and
  // needs to be visible as a disabled control).
  if (onClick || disabled) {
    return (
      <button
        type="button"
        className={classNames}
        onClick={disabled ? undefined : onClick}
        disabled={disabled}
        aria-disabled={disabled}
        {...hoverHandlers}
      >
        {content}
      </button>
    );
  }

  // Static (non-interactive) card — no href, no onClick. Render a plain div so
  // the card isn't focusable / announced as a control.
  return (
    <div
      className={classNames}
      {...hoverHandlers}
    >
      {content}
    </div>
  );
};

export default CardOffgrid;