npm package: @ishannahata/blade-ai
Description: AI Elements for Razorpay's Blade Design System - Production-grade components for AI chat interfaces
Latest version: 0.3.0

# @aspect-ui/blade-ai

Production-grade AI chat UI components for Razorpay's Blade Design System.

## Installation

```bash
npm install @aspect-ui/blade-ai
```

## Peer Dependencies

```json
{
  "react": "^18.0.0",
  "react-dom": "^18.0.0",
  "motion": "^11.0.0 || ^12.0.0",
  "tailwindcss": "^4.0.0",
  "clsx": "^2.0.0"
}
```

Optional:
- `ogl` ^1.0.0 - Required for `SparkRipplesBackground`

## Quick Start

```tsx
import {
  StreamingText,
  ChainOfThought,
  SuggestionStack,
  MessageFooter,
  useStreamSequencer,
} from '@aspect-ui/blade-ai';
import '@aspect-ui/blade-ai/styles';
```

## Core Components

### Streaming Text

Character-by-character streaming with layout shift prevention:

```tsx
<StreamingText
  content="**Important:** Payment of ₹5,000 processed successfully"
  style="glow"
  speed={10}
  onComplete={() => console.log('Done')}
/>
```

Styles: `basic` | `glow` | `typewriter` | `gradient`

### Chain of Thought

3-mode thinking indicator:

```tsx
// Waiting mode - cycles through steps
<ChainOfThought
  steps={['Analyzing...', 'Searching...', 'Formatting...']}
  mode="waiting"
/>

// Streaming mode - rotating icon only
<ChainOfThought steps={[]} mode="streaming" />

// Complete mode - with suggestions
<ChainOfThought
  steps={[]}
  mode="complete"
  suggestions={['Show details', 'Export']}
  onSuggestionClick={handleClick}
/>
```

### ArtifactMessage

Full 8-part AI response composition:

```tsx
<ArtifactMessage
  headline="Found 3 matching transactions"
  subtext="Based on **payment ID 12345**:"
  stats={[
    { label: 'Total', value: '₹15,000' },
    { label: 'Status', value: 'Processed' }
  ]}
  table={{
    columns: [
      { key: 'id', label: 'ID', copyable: true },
      { key: 'amount', label: 'Amount' }
    ],
    rows: transactions
  }}
  resolution={{
    title: 'Recommendation',
    content: 'All transactions processed correctly.'
  }}
  suggestions={['Show details', 'Export CSV']}
  onSuggestionClick={handleSuggestion}
  isLastMessage
/>
```

### Data Table

SmartTable patterns with action dock:

```tsx
<DataTable
  columns={[
    { key: 'id', label: 'ID', copyable: true },
    { key: 'amount', label: 'Amount' },
    { key: 'status', label: 'Status', variant: 'status' }
  ]}
  rows={transactions}
  onRowClick={handleRowClick}
  showActionDock
  animate
/>
```

### Chat Input

Hero and compact variants:

```tsx
// Landing page
<ChatInput
  variant="hero"
  animatedPlaceholder
  placeholder="Ask me anything..."
  onSubmit={handleSubmit}
/>

// Chat interface
<ChatInput
  variant="compact"
  placeholder="Type a message..."
  onSubmit={handleSubmit}
/>
```

## Hooks

### useStreamSequencer

6-phase streaming orchestration:

```tsx
const {
  phase,
  onNarrativeComplete,
  showDataAsset,
  showInsight,
  showActions,
  showSuggestions
} = useStreamSequencer({
  hasDataAsset: true,
  hasInsight: true,
  hasSuggestions: true,
  thinkingDuration: 2000,
  onStreamComplete: () => console.log('Done')
});
```

### useAgenticStream

Simple 4-phase alternative:

```tsx
const { phase, nextPhase, showTable, showInsight, showActions } = useAgenticStream({
  onComplete: () => console.log('Complete')
});
```

### useChatInterceptor

Smart input classification for forms:

```tsx
const classify = useChatInterceptor({
  formFields: ['email', 'amount', 'phone']
});

const result = classify('set email to john@example.com');
// { type: 'FIELD_UPDATE', field: 'email', value: 'john@example.com' }
```

## Visual Effects

### SparkRipplesBackground

WebGL background with glass effect:

```tsx
<SparkRipplesBackground
  opacity={0.8}
  loop
  enableGrain={false}
/>
```

Requires `ogl` peer dependency.

### GlassCard

Glassmorphism container:

```tsx
<GlassCard blur="strong" opacity="heavy" shadow rounded="rounded-2xl">
  <div>Frosted panel content</div>
</GlassCard>
```

Blur: `none` | `subtle` | `medium` | `strong` | `ultra`
Opacity: `light` | `medium` | `heavy` | `solid`

## Theming

Override magic colors with CSS variables:

```css
:root {
  --magic-primary: #009E5C;
  --magic-gradient-light: rgba(0, 158, 92, 0.5);
}

/* Blue theme */
.blue-theme {
  --magic-primary: #3B82F6;
  --magic-gradient-light: rgba(59, 130, 246, 0.5);
}
```

## Module Structure

```
@aspect-ui/blade-ai
├── primitives     # StreamingText, SmartHighlight, StreamingBulletList
├── thinking       # ChainOfThought, SimpleThinking, ThinkingIndicator
├── actions        # SuggestionStack, MessageFooter
├── hooks          # useStreamSequencer, useAgenticStream, useChatInterceptor
├── backgrounds    # SparkRipplesBackground
├── artifacts      # DataTable, CodeBlock, DataCard
├── chat           # ChatContainer, MessageList, ArtifactMessage
├── input          # ChatInput, SendButton, FileUpload
├── forms          # WizardForm, FormStep, InlineForm
├── progress       # Stepper, ProgressBar, ProgressRing
├── feedback       # SuccessState, ErrorState, ActionGuardBubble
├── layout         # SplitView, FloatingPanel, GlassCard
└── skeletons      # MessageSkeleton, AnimatedLoadingCard
```

## Documentation

See [docs/AI_METADATA.md](./docs/AI_METADATA.md) for complete AI agent reference.

## Version History

### v0.3.0
- Added `ArtifactMessage` compound component
- Added `StreamingBulletList` with two-phase streaming
- Added `ChatInput` hero/compact variants
- Added `useAgenticStream` and `useChatInterceptor` hooks
- Added `AnimatedLoadingCard` with spotlight border
- Added `ActionGuardBubble` for confirmations
- Added `GlassCard` glassmorphism container
- Added `SimpleThinking` pulsing indicator

### v0.2.0
- Updated `StreamingText` with layout shift prevention
- Added `SmartHighlight` and `SmartHighlightWithBold`
- Updated `ChainOfThought` with 3-mode system
- Added `useStreamSequencer` hook
- Added `SuggestionStack` and `MessageFooter`
- Updated `DataTable` with SmartTable patterns
- Added `SparkRipplesBackground` WebGL effect
- Added magic color CSS variable system

### v0.1.0
- Initial release with core components

## License

MIT