Skip to content

Commit cfa9541

Browse files
iamgpiamgp
committed
feat: callouts
1 parent c578743 commit cfa9541

5 files changed

Lines changed: 585 additions & 46 deletions

File tree

‎demo/callouts.py‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
#!/usr/bin/env python3
2+
"""Demo of the new callout components."""
3+
4+
import sys
5+
from pathlib import Path
6+
7+
import dash
8+
from dash import html
9+
10+
# Add the src directory to the Python path
11+
sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
12+
13+
from dashkit import (
14+
CautionCallout,
15+
ImportantCallout,
16+
NoteCallout,
17+
TipCallout,
18+
WarningCallout,
19+
setup_app,
20+
)
21+
22+
# Create Dash app
23+
app = dash.Dash(__name__)
24+
setup_app(app)
25+
26+
app.layout = html.Div(
27+
[
28+
html.H1(
29+
"Dashkit Callout Components Demo",
30+
className="text-3xl font-bold mb-8 text-center text-gray-900",
31+
),
32+
# Light and Dark mode split view
33+
html.Div(
34+
[
35+
# Light mode section
36+
html.Div(
37+
[
38+
html.H2(
39+
"Light Mode",
40+
className="text-xl font-semibold mb-4 text-center text-gray-900",
41+
),
42+
html.Div(
43+
[
44+
NoteCallout(
45+
"Useful information that users should know, even when skimming content."
46+
),
47+
TipCallout(
48+
[
49+
"Helpful advice for doing things better or more easily. ",
50+
html.Strong("Pro tip: "),
51+
"Use callouts sparingly to maintain effectiveness.",
52+
]
53+
),
54+
ImportantCallout(
55+
"Key information users need to know to achieve their goal."
56+
),
57+
WarningCallout(
58+
"Urgent info that needs immediate user attention to avoid problems."
59+
),
60+
CautionCallout(
61+
[
62+
"Advises about risks or negative outcomes of certain actions. ",
63+
html.Strong("Be careful!"),
64+
]
65+
),
66+
],
67+
className="space-y-4 bg-white p-6 rounded-lg border border-gray-200",
68+
),
69+
],
70+
className="flex-1",
71+
),
72+
# Dark mode section
73+
html.Div(
74+
[
75+
html.H2(
76+
"Dark Mode",
77+
className="text-xl font-semibold mb-4 text-center text-white",
78+
),
79+
html.Div(
80+
[
81+
NoteCallout(
82+
"Useful information that users should know, even when skimming content."
83+
),
84+
TipCallout(
85+
[
86+
"Helpful advice for doing things better or more easily. ",
87+
html.Strong("Pro tip: "),
88+
"Use callouts sparingly to maintain effectiveness.",
89+
]
90+
),
91+
ImportantCallout(
92+
"Key information users need to know to achieve their goal."
93+
),
94+
WarningCallout(
95+
"Urgent info that needs immediate user attention to avoid problems."
96+
),
97+
CautionCallout(
98+
[
99+
"Advises about risks or negative outcomes of certain actions. ",
100+
html.Strong("Be careful!"),
101+
]
102+
),
103+
],
104+
className="dark space-y-4 bg-dashkit-gray-900 p-6 rounded-lg border border-gray-700",
105+
),
106+
],
107+
className="flex-1",
108+
),
109+
],
110+
className="flex gap-8 max-w-7xl mx-auto p-8",
111+
),
112+
],
113+
className="min-h-screen bg-gray-100",
114+
)
115+
116+
if __name__ == "__main__":
117+
print("Starting Dashkit Callout Demo...")
118+
print("Open http://127.0.0.1:8050 in your browser")
119+
app.run(debug=True)

‎docs/api/components/callouts.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Callouts
2+
3+
Callout components for displaying important information with different styling variants. Perfect for highlighting notes, tips, warnings, and other important content.
4+
5+
## Overview
6+
7+
Callouts provide a consistent way to display contextual information with colored borders, icons, and semantic meaning. Each callout type uses specific colors and icons to communicate the urgency or type of information.
8+
9+
## Components
10+
11+
### Callout
12+
13+
The base callout component with configurable variants.
14+
15+
```python
16+
from dashkit import Callout
17+
18+
# Basic usage
19+
Callout("Your message here", variant="note")
20+
```
21+
22+
**Props:**
23+
- `children` (Any): Content to display inside the callout
24+
- `variant` (Literal["note", "tip", "important", "warning", "caution"]): The type of callout (default: "note")
25+
- `className` (str): Additional CSS classes (default: "")
26+
- `**kwargs`: Additional props passed to the outer div
27+
28+
### Specialized Callouts
29+
30+
For convenience, we provide specialized callout components for each type:
31+
32+
#### NoteCallout
33+
Blue callout for useful information that users should know.
34+
35+
```python
36+
from dashkit import NoteCallout
37+
38+
NoteCallout("Useful information that users should know, even when skimming content.")
39+
```
40+
41+
#### TipCallout
42+
Green callout for helpful advice and pro tips.
43+
44+
```python
45+
from dashkit import TipCallout
46+
47+
TipCallout([
48+
"Helpful advice for doing things better or more easily. ",
49+
html.Strong("Pro tip: "),
50+
"Use callouts sparingly to maintain their effectiveness."
51+
])
52+
```
53+
54+
#### ImportantCallout
55+
Purple callout for key information users need to know.
56+
57+
```python
58+
from dashkit import ImportantCallout
59+
60+
ImportantCallout("Key information users need to know to achieve their goal.")
61+
```
62+
63+
#### WarningCallout
64+
Amber/yellow callout for urgent information requiring immediate attention.
65+
66+
```python
67+
from dashkit import WarningCallout
68+
69+
WarningCallout("Urgent info that needs immediate user attention to avoid problems.")
70+
```
71+
72+
#### CautionCallout
73+
Red callout for risks or negative outcomes.
74+
75+
```python
76+
from dashkit import CautionCallout
77+
78+
CautionCallout([
79+
"Advises about risks or negative outcomes of certain actions. ",
80+
html.Strong("Be careful: "),
81+
"This action cannot be undone and may result in data loss."
82+
])
83+
```
84+
85+
## Examples
86+
87+
### Basic Usage
88+
89+
```python
90+
from dashkit import NoteCallout, TipCallout, ImportantCallout, WarningCallout, CautionCallout
91+
92+
# Simple text
93+
NoteCallout("This is a note with useful information.")
94+
95+
# With HTML elements
96+
TipCallout([
97+
"You can use ",
98+
html.Strong("HTML elements"),
99+
" inside callouts for formatting."
100+
])
101+
102+
# Custom styling
103+
WarningCallout(
104+
"Custom warning with additional styling",
105+
className="my-4 shadow-lg"
106+
)
107+
```
108+
109+
### Mixed Content
110+
111+
```python
112+
# Callouts can contain any Dash components
113+
ImportantCallout([
114+
html.P("This callout contains multiple paragraphs."),
115+
html.P([
116+
"You can include ",
117+
html.A("links", href="#", className="text-purple-600 underline"),
118+
" and other interactive elements."
119+
]),
120+
html.Ul([
121+
html.Li("List items work too"),
122+
html.Li("Making callouts very flexible")
123+
], className="mt-2 ml-4")
124+
])
125+
```
126+
127+
## Styling
128+
129+
### Colors and Variants
130+
131+
Each callout type uses specific colors:
132+
133+
- **Note**: Blue (`text-blue-500`, `border-blue-500`)
134+
- **Tip**: Green (`text-green-500`, `border-green-500`)
135+
- **Important**: Purple (`text-purple-500`, `border-purple-500`)
136+
- **Warning**: Amber (`text-amber-600`, `border-amber-500`)
137+
- **Caution**: Red (`text-red-500`, `border-red-500`)
138+
139+
### Icons
140+
141+
Callouts use MynaUI icons via dash-iconify:
142+
143+
- **Note**: `mynaui:info-circle`
144+
- **Tip**: `mynaui:danger-circle`
145+
- **Important**: `mynaui:bookmark`
146+
- **Warning**: `mynaui:danger-diamond`
147+
- **Caution**: `mynaui:danger-hexagon`
148+
149+
### Dark Mode
150+
151+
All callouts automatically support dark mode with appropriate color adjustments for text and backgrounds.
152+
153+
### Customization
154+
155+
You can customize callouts by:
156+
157+
1. **Adding custom CSS classes:**
158+
```python
159+
NoteCallout("Custom note", className="my-custom-class")
160+
```
161+
162+
2. **Using the base Callout component for different styling:**
163+
```python
164+
Callout("Custom callout", variant="note", className="border-2 shadow-xl")
165+
```
166+
167+
## Best Practices
168+
169+
1. **Use sparingly** - Too many callouts can overwhelm users
170+
2. **Choose the right type** - Match the semantic meaning to the content
171+
3. **Keep content concise** - Callouts should highlight key information
172+
4. **Consider placement** - Position callouts where they provide the most value
173+
5. **Test accessibility** - Ensure sufficient color contrast and screen reader support
174+
175+
## Accessibility
176+
177+
- Icons are decorative and don't interfere with screen readers
178+
- Color coding is supplemented with text labels (Note, Tip, etc.)
179+
- Semantic HTML structure supports assistive technologies
180+
- Sufficient color contrast in both light and dark modes

‎src/dashkit/__init__.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,14 @@
1010
from flask import send_from_directory
1111

1212
from .buttons import PrimaryButton, SecondaryButton
13+
from .callout import (
14+
Callout,
15+
CautionCallout,
16+
ImportantCallout,
17+
NoteCallout,
18+
TipCallout,
19+
WarningCallout,
20+
)
1321
from .card import Card, ChartCard, MetricCard
1422
from .header import create_header
1523
from .layout import create_layout
@@ -112,6 +120,12 @@ def _dashkit_assets(filename: str): # type: ignore
112120
"Card",
113121
"MetricCard",
114122
"ChartCard",
123+
"Callout",
124+
"NoteCallout",
125+
"TipCallout",
126+
"ImportantCallout",
127+
"WarningCallout",
128+
"CautionCallout",
115129
"setup_app",
116130
]
117131

0 commit comments

Comments
 (0)