npm package: @shashank_s/summary-card
Description: SummaryCard React component (variant: basic) styled with shadcn/tailwind tokens.
Latest version: 0.1.12

# SummaryCard (basic variant)

A small, theme-friendly Summary Card React component using shadcn/tailwind design tokens.

## Install

```bash
npm install @shashank_s/summary-card
# or
yarn add @shashank_s/summary-card
# or
pnpm add @shashank_s/summary-card
```

Peer dependencies (expected in your app):
- react (>=17)
- react-dom (>=17)
- tailwind + shadcn tokens (bg-card, border, text-foreground, text-muted-foreground, bg-muted, border-border)

## Usage

```tsx
import { SummaryCard } from '@shashank_s/summary-card'

export default function Example() {
  return (
    <SummaryCard
      variant="basic"
      title="MATI available"
      value="8,400 Tons"
      subtitle="5 Villages, 18 Clusters"
      enableSelection
      className="w-[240px]" // optional sizing override
    />
  )
}
```

## Props

```ts
interface SummaryCardProps extends React.HTMLAttributes<HTMLDivElement> {
  title: string
  value: string | number
  subtitle?: string
  variant?: 'basic'
  enableSelection?: boolean // default: true
  onClick?: () => void
}
```

- variant: currently only `basic`.
- enableSelection: when true, clicking toggles a subtle selected state using shadcn tokens (`bg-muted` + `border-border`).

## Styling

The component uses design tokens:
- Base: `bg-card border text-card-foreground`
- Selected: `bg-muted border-border`
- Typography: `text-sm font-medium`, `text-2xl font-bold`, `text-xs text-muted-foreground`

You can pass additional classes via `className` (e.g., `w-[240px]`, `shadow-none`, etc.).

## Examples

### Basic Usage
```tsx
import { SummaryCard } from '@shashank_s/summary-card'

// Simple card with all props
<SummaryCard
  variant="basic"
  title="MATI available"
  value="8,400 Tons"
  subtitle="5 Villages, 18 Clusters"
/>
```

### With Click Handler
```tsx
// Card with click handler (selection still enabled)
<SummaryCard
  title="Users"
  value="1,234"
  subtitle="Active"
  onClick={() => console.log('Card clicked!')}
/>

// Card with click handler but no selection toggle
<SummaryCard
  title="KPI"
  value="98%"
  onClick={() => console.log('KPI clicked!')}
  enableSelection={false}
/>
```

### Styling Examples
```tsx
// Fixed width
<SummaryCard
  title="Revenue"
  value="$12,345"
  subtitle="This month"
  className="w-[240px]"
/>

// Custom styling
<SummaryCard
  title="Orders"
  value="456"
  subtitle="Pending"
  className="w-[300px] shadow-lg border-2"
/>

// No border
<SummaryCard
  title="Status"
  value="Online"
  className="border-0 shadow-none"
/>
```

### Different Data Types
```tsx
// String value
<SummaryCard
  title="Status"
  value="Active"
  subtitle="System running"
/>

// Number value
<SummaryCard
  title="Count"
  value={1234}
  subtitle="Total items"
/>

// No subtitle
<SummaryCard
  title="Temperature"
  value="72°F"
/>
```

### Interactive Examples
```tsx
import { useState } from 'react'

function Dashboard() {
  const [selectedCard, setSelectedCard] = useState<string | null>(null)

  return (
    <div className="grid grid-cols-3 gap-4">
      <SummaryCard
        title="Sales"
        value="$5,432"
        subtitle="This week"
        onClick={() => setSelectedCard('sales')}
        className={selectedCard === 'sales' ? 'ring-2 ring-blue-500' : ''}
      />
      
      <SummaryCard
        title="Orders"
        value="89"
        subtitle="Pending"
        onClick={() => setSelectedCard('orders')}
        className={selectedCard === 'orders' ? 'ring-2 ring-blue-500' : ''}
      />
      
      <SummaryCard
        title="Users"
        value="1,234"
        subtitle="Active"
        onClick={() => setSelectedCard('users')}
        className={selectedCard === 'users' ? 'ring-2 ring-blue-500' : ''}
      />
    </div>
  )
}
```

### All Props Example
```tsx
<SummaryCard
  // Required props
  title="Complete Example"
  value="100%"
  
  // Optional props
  subtitle="All systems operational"
  variant="basic"
  enableSelection={true}
  onClick={() => {
    console.log('Card clicked!')
    // Your custom logic here
  }}
  
  // Custom styling
  className="w-[280px] hover:shadow-xl transition-shadow"
  
  // Any other HTML div attributes
  id="summary-card-1"
  data-testid="summary-card"
  role="button"
  tabIndex={0}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault()
      // Handle keyboard activation
    }
  }}
/>
```

## Development

- Build: `npm run build`
- Types and ESM/CJS are emitted to `dist/`

## Repository / Issues

- Repository: https://github.com/shashank-samples/summary-card (placeholder)
- Issues: https://github.com/shashank-samples/summary-card/issues

## License

MIT