Initial commit
This commit is contained in:
Zhongwei Li
244
docs/components/context.md
Normal file
244
docs/components/context.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Context
|
||||
|
||||
URL: /components/context
|
||||
|
||||
---
|
||||
|
||||
title: Context
|
||||
description: A compound component system for displaying AI model context window usage, token consumption, and cost estimation.
|
||||
path: elements/components/context
|
||||
|
||||
---
|
||||
|
||||
The `Context` component provides a comprehensive view of AI model usage through a compound component system. It displays context window utilization, token consumption breakdown (input, output, reasoning, cache), and cost estimation in an interactive hover card interface.
|
||||
|
||||
<Preview path="context" />
|
||||
|
||||
## Installation
|
||||
|
||||
<ElementsInstaller path="context" />
|
||||
|
||||
## Usage
|
||||
|
||||
```tsx
|
||||
import {
|
||||
Context,
|
||||
ContextTrigger,
|
||||
ContextContent,
|
||||
ContextContentHeader,
|
||||
ContextContentBody,
|
||||
ContextContentFooter,
|
||||
ContextInputUsage,
|
||||
ContextOutputUsage,
|
||||
ContextReasoningUsage,
|
||||
ContextCacheUsage,
|
||||
} from "@/components/ai-elements/context";
|
||||
```
|
||||
|
||||
```tsx
|
||||
<Context
|
||||
maxTokens={128000}
|
||||
usedTokens={40000}
|
||||
usage={{
|
||||
inputTokens: 32000,
|
||||
outputTokens: 8000,
|
||||
totalTokens: 40000,
|
||||
cachedInputTokens: 0,
|
||||
reasoningTokens: 0,
|
||||
}}
|
||||
modelId="openai:gpt-4"
|
||||
>
|
||||
<ContextTrigger />
|
||||
<ContextContent>
|
||||
<ContextContentHeader />
|
||||
<ContextContentBody>
|
||||
<ContextInputUsage />
|
||||
<ContextOutputUsage />
|
||||
<ContextReasoningUsage />
|
||||
<ContextCacheUsage />
|
||||
</ContextContentBody>
|
||||
<ContextContentFooter />
|
||||
</ContextContent>
|
||||
</Context>
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
- **Compound Component Architecture**: Flexible composition of context display elements
|
||||
- **Visual Progress Indicator**: Circular SVG progress ring showing context usage percentage
|
||||
- **Token Breakdown**: Detailed view of input, output, reasoning, and cached tokens
|
||||
- **Cost Estimation**: Real-time cost calculation using the `tokenlens` library
|
||||
- **Intelligent Formatting**: Automatic token count formatting (K, M, B suffixes)
|
||||
- **Interactive Hover Card**: Detailed information revealed on hover
|
||||
- **Context Provider Pattern**: Clean data flow through React Context API
|
||||
- **TypeScript Support**: Full type definitions for all components
|
||||
- **Accessible Design**: Proper ARIA labels and semantic HTML
|
||||
- **Theme Integration**: Uses currentColor for automatic theme adaptation
|
||||
|
||||
## Props
|
||||
|
||||
### `<Context />`
|
||||
|
||||
<TypeTable
|
||||
type={{
|
||||
maxTokens: {
|
||||
description: 'The total context window size in tokens.',
|
||||
type: 'number',
|
||||
},
|
||||
usedTokens: {
|
||||
description: 'The number of tokens currently used.',
|
||||
type: 'number',
|
||||
},
|
||||
usage: {
|
||||
description: 'Detailed token usage breakdown from the AI SDK (input, output, reasoning, cached tokens).',
|
||||
type: 'LanguageModelUsage',
|
||||
},
|
||||
modelId: {
|
||||
description: 'Model identifier for cost calculation (e.g., "openai:gpt-4", "anthropic:claude-3-opus").',
|
||||
type: 'ModelId',
|
||||
},
|
||||
'...props': {
|
||||
description: 'Any other props are spread to the HoverCard component.',
|
||||
type: 'ComponentProps<HoverCard>',
|
||||
},
|
||||
}}
|
||||
/>
|
||||
|
||||
### `<ContextTrigger />`
|
||||
|
||||
<TypeTable
|
||||
type={{
|
||||
children: {
|
||||
description: 'Custom trigger element. If not provided, renders a default button with percentage and icon.',
|
||||
type: 'React.ReactNode',
|
||||
},
|
||||
'...props': {
|
||||
description: 'Props spread to the default button element.',
|
||||
type: 'ComponentProps<Button>',
|
||||
},
|
||||
}}
|
||||
/>
|
||||
|
||||
### `<ContextContent />`
|
||||
|
||||
<TypeTable
|
||||
type={{
|
||||
className: {
|
||||
description: 'Additional CSS classes for the hover card content.',
|
||||
type: 'string',
|
||||
},
|
||||
'...props': {
|
||||
description: 'Props spread to the HoverCardContent component.',
|
||||
type: 'ComponentProps<HoverCardContent>',
|
||||
},
|
||||
}}
|
||||
/>
|
||||
|
||||
### `<ContextContentHeader />`
|
||||
|
||||
<TypeTable
|
||||
type={{
|
||||
children: {
|
||||
description: 'Custom header content. If not provided, renders percentage and token count with progress bar.',
|
||||
type: 'React.ReactNode',
|
||||
},
|
||||
'...props': {
|
||||
description: 'Props spread to the header div element.',
|
||||
type: 'ComponentProps<div>',
|
||||
},
|
||||
}}
|
||||
/>
|
||||
|
||||
### `<ContextContentBody />`
|
||||
|
||||
<TypeTable
|
||||
type={{
|
||||
children: {
|
||||
description: 'Body content, typically containing usage breakdown components.',
|
||||
type: 'React.ReactNode',
|
||||
},
|
||||
'...props': {
|
||||
description: 'Props spread to the body div element.',
|
||||
type: 'ComponentProps<div>',
|
||||
},
|
||||
}}
|
||||
/>
|
||||
|
||||
### `<ContextContentFooter />`
|
||||
|
||||
<TypeTable
|
||||
type={{
|
||||
children: {
|
||||
description: 'Custom footer content. If not provided, renders total cost when modelId is provided.',
|
||||
type: 'React.ReactNode',
|
||||
},
|
||||
'...props': {
|
||||
description: 'Props spread to the footer div element.',
|
||||
type: 'ComponentProps<div>',
|
||||
},
|
||||
}}
|
||||
/>
|
||||
|
||||
### Usage Components
|
||||
|
||||
All usage components (`ContextInputUsage`, `ContextOutputUsage`, `ContextReasoningUsage`, `ContextCacheUsage`) share the same props:
|
||||
|
||||
<TypeTable
|
||||
type={{
|
||||
children: {
|
||||
description: 'Custom content. If not provided, renders token count and cost for the respective usage type.',
|
||||
type: 'React.ReactNode',
|
||||
},
|
||||
className: {
|
||||
description: 'Additional CSS classes.',
|
||||
type: 'string',
|
||||
},
|
||||
'...props': {
|
||||
description: 'Props spread to the div element.',
|
||||
type: 'ComponentProps<div>',
|
||||
},
|
||||
}}
|
||||
/>
|
||||
|
||||
## Component Architecture
|
||||
|
||||
The Context component uses a compound component pattern with React Context for data sharing:
|
||||
|
||||
1. **`<Context>`** - Root provider component that holds all context data
|
||||
2. **`<ContextTrigger>`** - Interactive trigger element (default: button with percentage)
|
||||
3. **`<ContextContent>`** - Hover card content container
|
||||
4. **`<ContextContentHeader>`** - Header section with progress visualization
|
||||
5. **`<ContextContentBody>`** - Body section for usage breakdowns
|
||||
6. **`<ContextContentFooter>`** - Footer section for total cost
|
||||
7. **Usage Components** - Individual token usage displays (Input, Output, Reasoning, Cache)
|
||||
|
||||
## Token Formatting
|
||||
|
||||
The component uses `Intl.NumberFormat` with compact notation for automatic formatting:
|
||||
|
||||
- Under 1,000: Shows exact count (e.g., "842")
|
||||
- 1,000+: Shows with K suffix (e.g., "32K")
|
||||
- 1,000,000+: Shows with M suffix (e.g., "1.5M")
|
||||
- 1,000,000,000+: Shows with B suffix (e.g., "2.1B")
|
||||
|
||||
## Cost Calculation
|
||||
|
||||
When a `modelId` is provided, the component automatically calculates costs using the `tokenlens` library:
|
||||
|
||||
- **Input tokens**: Cost based on model's input pricing
|
||||
- **Output tokens**: Cost based on model's output pricing
|
||||
- **Reasoning tokens**: Special pricing for reasoning-capable models
|
||||
- **Cached tokens**: Reduced pricing for cached input tokens
|
||||
- **Total cost**: Sum of all token type costs
|
||||
|
||||
Costs are formatted using `Intl.NumberFormat` with USD currency.
|
||||
|
||||
## Styling
|
||||
|
||||
The component uses Tailwind CSS classes and follows your design system:
|
||||
|
||||
- Progress indicator uses `currentColor` for theme adaptation
|
||||
- Hover card has customizable width and padding
|
||||
- Footer has a secondary background for visual separation
|
||||
- All text sizes use the `text-xs` class for consistency
|
||||
- Muted foreground colors for secondary information
|
||||
Reference in New Issue
Block a user