feat(components): Implement reusable Card and Button components with click support

[ainergiz]

Summary

Create reusable Card and Button components with proper click handling, building on the experimental work done in PostCard. This supports the router migration (#200) by enabling mouse-driven navigation alongside keyboard controls.

Context

Related to #165 (modular component library) and follows the TanStack Router validation spike (#200). As we move toward a more centralized navigation architecture, clickable components become essential for mouse-driven navigation.

Experimental Findings

An experiment was conducted in PostCard.tsx to understand OpenTUI's mouse event capabilities. Key learnings:

1. OpenTUI Has Full Mouse Support

OpenTUI core (@opentui/core) provides comprehensive mouse event handlers through RenderableOptions:

onMouse?: (event: MouseEvent) => void      // Catch-all handler
onMouseDown?: (event: MouseEvent) => void
onMouseUp?: (event: MouseEvent) => void
onMouseMove?: (event: MouseEvent) => void
onMouseDrag?: (event: MouseEvent) => void
onMouseDragEnd?: (event: MouseEvent) => void
onMouseDrop?: (event: MouseEvent) => void
onMouseOver?: (event: MouseEvent) => void
onMouseOut?: (event: MouseEvent) => void
onMouseScroll?: (event: MouseEvent) => void

2. React Integration Works Via Pass-Through

The React reconciler passes unknown props directly to the underlying Renderable:

// In @opentui/react reconciler - unknown props flow through
default:
  instance[propKey] = propValue

This means mouse handlers work on any OpenTUI React component without modification.

3. Click vs Drag Detection Required

Using onMouseDown alone causes clicks to fire during text selection. Solution: track mouse movement between down and up events.

const DRAG_THRESHOLD = 3; // pixels

const handleMouse = (event: MouseEvent) => {
  if (event.type === "down") {
    dragState.current = { isDragging: false, startX: event.x, startY: event.y };
  } else if (event.type === "drag") {
    const dx = Math.abs(event.x - dragState.current.startX);
    const dy = Math.abs(event.y - dragState.current.startY);
    if (dx > DRAG_THRESHOLD || dy > DRAG_THRESHOLD) {
      dragState.current.isDragging = true;
    }
  } else if (event.type === "up") {
    if (!dragState.current.isDragging) {
      onClick(); // Only fire if no significant movement
    }
  }
};

4. Event Propagation Works as Expected

event.stopPropagation() prevents parent handlers from firing, enabling nested clickable elements (e.g., like button inside card).

5. Hover States Work

onMouseOver and onMouseOut work for hover effects. State-based color changes provide visual feedback since terminal cursor styling isn't controllable by applications.

6. Terminal Cursor Limitation

Unlike web CSS cursor: pointer, terminal applications cannot change the mouse pointer appearance. The pointer is controlled by the terminal emulator, not the application. Hover color changes are the primary visual feedback mechanism.

Proposed Components

<Card> Component

A clickable container with optional hover highlighting:

interface CardProps {
  children: React.ReactNode;
  onClick?: () => void;
  selected?: boolean;
  hoverHighlight?: boolean;
  style?: BoxProps["style"];
}

// Usage
<Card onClick={() => navigate("postDetail", { tweet })} selected={isSelected}>
  <PostContent post={post} />
</Card>

<Button> Component

A clickable action element with hover states:

interface ButtonProps {
  children: React.ReactNode;
  onClick?: () => void;
  variant?: "default" | "primary" | "danger";
  disabled?: boolean;
}

// Usage
<Button onClick={handleLike} variant="danger">
  {isLiked ? "♥" : "♡"}
</Button>

useClickHandler Hook

Extract the click vs drag detection logic into a reusable hook:

function useClickHandler(onClick?: () => void) {
  const dragState = useRef({ isDragging: false, startX: 0, startY: 0 });
  
  const handleMouse = onClick ? (event: MouseEvent) => {
    // ... click vs drag logic
  } : undefined;
  
  return { onMouse: handleMouse };
}

Tasks

• Extract useClickHandler hook from PostCard
• Create Card component with click and hover support
• Create Button component for action icons
• Refactor PostCard to use new components
• Add hover highlight option to Card
• Document mouse event patterns in component library

Files to Create/Modify

• src/components/Card.tsx (new)
• src/components/Button.tsx (new)
• src/hooks/useClickHandler.ts (new)
• src/components/PostCard.tsx (refactor to use Card/Button)
• src/components/index.ts (exports)

Success Criteria

• Card and Button components are reusable across screens
• Click handling works correctly (no false triggers on text selection)
• Hover states provide visual feedback
• PostCard uses the new components without regression
• Components are documented with usage examples

Related

• Parent: refactor(components): Create more modular and reusable component library #165 (modular component library)
• Prior work: feat(router): TanStack Router validation spike #200 (TanStack Router validation spike)
• May support: feat(nav): Add global number key navigation and repurpose Tab for in-screen tabs #188 (global navigation), feat(nav): Add URL input to open tweets/profiles from x.com links #194 (URL input navigation)

[ainergiz]

Enhanced Button Component with Icons & Loading Spinner

Following up on the initial proposal, here's an enhanced design that includes icon support and loading spinners using opentui-spinner.

Dependencies

bun add opentui-spinner

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                         Button Component                          │
│                                                                   │
│  ┌─────────┐  ┌──────────────────┐  ┌─────────┐                  │
│  │ iconLeft│  │     children     │  │iconRight│                  │
│  │    OR   │  │                  │  │         │                  │
│  │ spinner │  │                  │  │         │                  │
│  └─────────┘  └──────────────────┘  └─────────┘                  │
│                                                                   │
│  loading=true → shows spinner instead of iconLeft                 │
└──────────────────────────────────────────────────────────────────┘

---

Implementation

1. useClickHandler Hook

// src/hooks/useClickHandler.ts
import type { MouseEvent } from "@opentui/core";
import { useRef } from "react";

const DRAG_THRESHOLD = 3;

interface DragState {
  isDragging: boolean;
  startX: number;
  startY: number;
}

interface UseClickHandlerOptions {
  onClick?: () => void;
  stopPropagation?: boolean;
  disabled?: boolean;
}

interface UseClickHandlerReturn {
  onMouse: ((event: MouseEvent) => void) | undefined;
}

export function useClickHandler(options: UseClickHandlerOptions): UseClickHandlerReturn {
  const { onClick, stopPropagation = false, disabled = false } = options;
  const dragState = useRef<DragState>({ isDragging: false, startX: 0, startY: 0 });

  const onMouse = onClick && !disabled
    ? (event: MouseEvent) => {
        if (event.button !== 0) return;
        if (stopPropagation) event.stopPropagation();

        if (event.type === "down") {
          dragState.current = { isDragging: false, startX: event.x, startY: event.y };
        } else if (event.type === "drag") {
          const dx = Math.abs(event.x - dragState.current.startX);
          const dy = Math.abs(event.y - dragState.current.startY);
          if (dx > DRAG_THRESHOLD || dy > DRAG_THRESHOLD) {
            dragState.current.isDragging = true;
          }
        } else if (event.type === "up") {
          if (!dragState.current.isDragging) {
            onClick();
          }
          dragState.current.isDragging = false;
        }
      }
    : undefined;

  return { onMouse };
}

2. Button Component with Icon & Loading Support

// src/components/Button.tsx
import "opentui-spinner/react"; // Register <spinner> component

import { useState } from "react";
import { colors } from "@/lib/colors";
import { useClickHandler } from "@/hooks/useClickHandler";

type ButtonVariant = "default" | "primary" | "danger" | "success" | "ghost";
type SpinnerName = "dots" | "line" | "arc" | "bouncingBall" | "simpleDots";

interface ButtonProps {
  children?: React.ReactNode;
  onClick?: () => void;
  variant?: ButtonVariant;
  disabled?: boolean;
  stopPropagation?: boolean;
  
  // Icon support
  iconLeft?: string;
  iconRight?: string;
  
  // Loading state
  loading?: boolean;
  spinnerName?: SpinnerName;
  
  // Spacing
  gap?: number;
}

const variantColors: Record<ButtonVariant, { default: string; hover: string; disabled: string }> = {
  default: { default: colors.muted, hover: "#ffffff", disabled: colors.dim },
  primary: { default: colors.primary, hover: "#4DB5F5", disabled: colors.dim },
  danger: { default: colors.error, hover: "#FF4081", disabled: colors.dim },
  success: { default: colors.success, hover: "#4CD964", disabled: colors.dim },
  ghost: { default: colors.dim, hover: colors.muted, disabled: colors.dim },
};

export function Button({
  children,
  onClick,
  variant = "default",
  disabled = false,
  stopPropagation = false,
  iconLeft,
  iconRight,
  loading = false,
  spinnerName = "dots",
  gap = 1,
}: ButtonProps) {
  const [isHovered, setIsHovered] = useState(false);
  const { onMouse } = useClickHandler({ 
    onClick, 
    stopPropagation, 
    disabled: disabled || loading
  });

  const colorSet = variantColors[variant];
  const isDisabled = disabled || loading;
  const fg = isDisabled
    ? colorSet.disabled
    : isHovered
      ? colorSet.hover
      : colorSet.default;

  const gapStr = " ".repeat(gap);

  return (
    <box
      onMouse={onMouse}
      onMouseOver={() => !isDisabled && setIsHovered(true)}
      onMouseOut={() => setIsHovered(false)}
      style={{ flexDirection: "row", alignItems: "center" }}
    >
      {loading ? (
        <spinner name={spinnerName} color={fg} />
      ) : iconLeft ? (
        <text fg={fg}>{iconLeft}</text>
      ) : null}
      
      {(loading || iconLeft) && children ? <text>{gapStr}</text> : null}
      {children ? <text fg={fg}>{children}</text> : null}
      {iconRight && children ? <text>{gapStr}</text> : null}
      {iconRight ? <text fg={fg}>{iconRight}</text> : null}
    </box>
  );
}

3. IconButton Component for Action Icons

// src/components/IconButton.tsx
import "opentui-spinner/react";

import { useState } from "react";
import { colors } from "@/lib/colors";
import { useClickHandler } from "@/hooks/useClickHandler";

interface IconButtonProps {
  icon: string;
  activeIcon?: string;
  isActive?: boolean;
  isJustActivated?: boolean;
  onClick?: () => void;
  activeColor?: string;
  hoverColor?: string;
  stopPropagation?: boolean;
  disabled?: boolean;
  loading?: boolean;
  spinnerName?: string;
  prefix?: string;
}

export function IconButton({
  icon,
  activeIcon,
  isActive = false,
  isJustActivated = false,
  onClick,
  activeColor = colors.primary,
  hoverColor,
  stopPropagation = true,
  disabled = false,
  loading = false,
  spinnerName = "dots",
  prefix = "",
}: IconButtonProps) {
  const [isHovered, setIsHovered] = useState(false);
  const { onMouse } = useClickHandler({ 
    onClick, 
    stopPropagation, 
    disabled: disabled || loading 
  });

  const effectiveHoverColor = hoverColor ?? activeColor;
  const fg = isJustActivated
    ? colors.success
    : loading
      ? colors.dim
      : isHovered
        ? effectiveHoverColor
        : isActive
          ? activeColor
          : colors.muted;

  const displayIcon = isActive && activeIcon ? activeIcon : icon;

  return (
    <box
      onMouse={onMouse}
      onMouseOver={() => !disabled && !loading && setIsHovered(true)}
      onMouseOut={() => setIsHovered(false)}
      style={{ flexDirection: "row" }}
    >
      {prefix ? <text>{prefix}</text> : null}
      {loading ? (
        <spinner name={spinnerName} color={fg} />
      ) : (
        <text fg={fg}>
          {isActive ? displayIcon : <b>{displayIcon}</b>}
        </text>
      )}
    </box>
  );
}

---

Usage Examples

Basic Button

<Button onClick={handleSubmit}>Submit</Button>
<Button variant="primary" onClick={handleSave}>Save</Button>
<Button variant="danger" onClick={handleDelete}>Delete</Button>

Button with Icons

<Button iconLeft="←" onClick={goBack}>Back</Button>
<Button iconRight="→" onClick={goNext}>Next</Button>
<Button iconLeft="✓" iconRight="→" variant="success">Continue</Button>

Loading State

<Button loading onClick={handleSubmit}>
  Submitting...
</Button>

IconButton for Actions (Like/Bookmark)

<IconButton
  icon={HEART_EMPTY}
  activeIcon={HEART_FILLED}
  isActive={isLiked}
  isJustActivated={isJustLiked}
  activeColor={colors.error}
  onClick={onLikeClick}
  loading={isLikePending}
  prefix="  "
/>

<IconButton
  icon={FLAG_EMPTY}
  activeIcon={FLAG_FILLED}
  isActive={isBookmarked}
  isJustActivated={isJustBookmarked}
  activeColor={colors.primary}
  onClick={onBookmarkClick}
  loading={isBookmarkPending}
  prefix="  "
/>

---

Refactored PostCard with IconButton

// PostCard.tsx - Stats line becomes much cleaner
<box style={{ flexDirection: "row", marginTop: 1, paddingLeft: 2 }}>
  <text fg={colors.muted}>
    {formatCount(post.replyCount)} replies {"  "}
    {formatCount(post.retweetCount)} reposts {"  "}
    {formatCount(post.likeCount)} likes
  </text>
  
  <IconButton
    icon={HEART_EMPTY}
    activeIcon={HEART_FILLED}
    isActive={isLiked}
    isJustActivated={isJustLiked}
    activeColor={colors.error}
    onClick={onLikeClick}
    prefix="  "
  />
  
  <IconButton
    icon={FLAG_EMPTY}
    activeIcon={FLAG_FILLED}
    isActive={isBookmarked}
    isJustActivated={isJustBookmarked}
    activeColor={colors.primary}
    onClick={onBookmarkClick}
    prefix="  "
  />
</box>

---

Available Spinner Types (from cli-spinners)

Name	Preview	Best For
dots	⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏	Default, subtle
line	-|/	Simple
arc	◜◠◝◞◡◟	Elegant
bouncingBall	⠁⠂⠄⠂	Playful
simpleDots	. .. ...	Minimal

---

Files to Create

src/
├── hooks/
│   └── useClickHandler.ts    # Extracted click logic
├── components/
│   ├── Button.tsx            # Base button with icons & loading
│   ├── IconButton.tsx        # Icon action button
│   └── index.ts              # Exports

References

• opentui-spinner - Spinner library for OpenTUI
• cli-spinners - 70+ spinner animations
• MUI Base UI Button - Architecture inspiration