@dashforge/tw 0.11.0-beta → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/CHANGELOG.md +234 -12
  2. package/COVERAGE.md +2 -2
  3. package/PARITY.md +7 -9
  4. package/PERFORMANCE.md +3 -4
  5. package/README.md +74 -15
  6. package/THEME-AUDIT.md +3 -4
  7. package/dashforge-tw-1.0.0.tgz +0 -0
  8. package/dist/index.esm.js +3127 -748
  9. package/dist/src/components/Alert/Alert.d.ts +65 -0
  10. package/dist/src/components/Alert/Alert.d.ts.map +1 -0
  11. package/dist/src/components/Alert/alert.types.d.ts +130 -0
  12. package/dist/src/components/Alert/alert.types.d.ts.map +1 -0
  13. package/dist/src/components/Alert/alert.variants.d.ts +85 -0
  14. package/dist/src/components/Alert/alert.variants.d.ts.map +1 -0
  15. package/dist/src/components/Avatar/Avatar.d.ts +48 -0
  16. package/dist/src/components/Avatar/Avatar.d.ts.map +1 -0
  17. package/dist/src/components/Avatar/avatar.types.d.ts +162 -0
  18. package/dist/src/components/Avatar/avatar.types.d.ts.map +1 -0
  19. package/dist/src/components/Avatar/avatar.variants.d.ts +208 -0
  20. package/dist/src/components/Avatar/avatar.variants.d.ts.map +1 -0
  21. package/dist/src/components/Badge/Badge.d.ts +63 -0
  22. package/dist/src/components/Badge/Badge.d.ts.map +1 -0
  23. package/dist/src/components/Badge/badge.types.d.ts +124 -0
  24. package/dist/src/components/Badge/badge.types.d.ts.map +1 -0
  25. package/dist/src/components/Badge/badge.variants.d.ts +262 -0
  26. package/dist/src/components/Badge/badge.variants.d.ts.map +1 -0
  27. package/dist/src/components/Box/Box.d.ts.map +1 -1
  28. package/dist/src/components/Box/box.types.d.ts +53 -0
  29. package/dist/src/components/Box/box.types.d.ts.map +1 -1
  30. package/dist/src/components/Button/Button.d.ts.map +1 -1
  31. package/dist/src/components/Button/button.types.d.ts +35 -0
  32. package/dist/src/components/Button/button.types.d.ts.map +1 -1
  33. package/dist/src/components/Card/Card.d.ts +107 -0
  34. package/dist/src/components/Card/Card.d.ts.map +1 -0
  35. package/dist/src/components/Card/card.types.d.ts +119 -0
  36. package/dist/src/components/Card/card.types.d.ts.map +1 -0
  37. package/dist/src/components/Chip/Chip.d.ts +67 -0
  38. package/dist/src/components/Chip/Chip.d.ts.map +1 -0
  39. package/dist/src/components/Chip/chip.types.d.ts +113 -0
  40. package/dist/src/components/Chip/chip.types.d.ts.map +1 -0
  41. package/dist/src/components/Chip/chip.variants.d.ts +155 -0
  42. package/dist/src/components/Chip/chip.variants.d.ts.map +1 -0
  43. package/dist/src/components/IconButton/IconButton.d.ts +57 -0
  44. package/dist/src/components/IconButton/IconButton.d.ts.map +1 -0
  45. package/dist/src/components/IconButton/iconButton.types.d.ts +96 -0
  46. package/dist/src/components/IconButton/iconButton.types.d.ts.map +1 -0
  47. package/dist/src/components/IconButton/iconButton.variants.d.ts +26 -0
  48. package/dist/src/components/IconButton/iconButton.variants.d.ts.map +1 -0
  49. package/dist/src/components/Menu/Menu.d.ts +118 -0
  50. package/dist/src/components/Menu/Menu.d.ts.map +1 -0
  51. package/dist/src/components/Menu/menu.types.d.ts +179 -0
  52. package/dist/src/components/Menu/menu.types.d.ts.map +1 -0
  53. package/dist/src/components/Menu/menu.variants.d.ts +129 -0
  54. package/dist/src/components/Menu/menu.variants.d.ts.map +1 -0
  55. package/dist/src/components/Snackbar/Snackbar.d.ts.map +1 -1
  56. package/dist/src/components/Snackbar/snackbar.types.d.ts +40 -3
  57. package/dist/src/components/Snackbar/snackbar.types.d.ts.map +1 -1
  58. package/dist/src/components/Snackbar/snackbar.variants.d.ts +12 -57
  59. package/dist/src/components/Snackbar/snackbar.variants.d.ts.map +1 -1
  60. package/dist/src/components/Spinner/Spinner.d.ts +44 -0
  61. package/dist/src/components/Spinner/Spinner.d.ts.map +1 -0
  62. package/dist/src/components/Spinner/spinner.types.d.ts +89 -0
  63. package/dist/src/components/Spinner/spinner.types.d.ts.map +1 -0
  64. package/dist/src/components/Spinner/spinner.variants.d.ts +111 -0
  65. package/dist/src/components/Spinner/spinner.variants.d.ts.map +1 -0
  66. package/dist/src/components/Table/cells/RenderChip.d.ts +15 -72
  67. package/dist/src/components/Table/cells/RenderChip.d.ts.map +1 -1
  68. package/dist/src/components/_shared/severity/index.d.ts +21 -0
  69. package/dist/src/components/_shared/severity/index.d.ts.map +1 -0
  70. package/dist/src/components/_shared/severity/severity.types.d.ts +48 -0
  71. package/dist/src/components/_shared/severity/severity.types.d.ts.map +1 -0
  72. package/dist/src/components/_shared/severity/severityIcons.d.ts +45 -0
  73. package/dist/src/components/_shared/severity/severityIcons.d.ts.map +1 -0
  74. package/dist/src/components/_shared/severity/severityVariants.d.ts +22 -0
  75. package/dist/src/components/_shared/severity/severityVariants.d.ts.map +1 -0
  76. package/dist/src/index.d.ts +27 -2
  77. package/dist/src/index.d.ts.map +1 -1
  78. package/package.json +8 -7
  79. package/src/components/Alert/Alert.test.tsx +302 -0
  80. package/src/components/Alert/Alert.tsx +186 -0
  81. package/src/components/Alert/alert.types.ts +144 -0
  82. package/src/components/Alert/alert.variants.ts +71 -0
  83. package/src/components/Autocomplete/autocomplete.variants.ts +1 -1
  84. package/src/components/Avatar/Avatar.test.tsx +287 -0
  85. package/src/components/Avatar/Avatar.tsx +304 -0
  86. package/src/components/Avatar/avatar.types.ts +205 -0
  87. package/src/components/Avatar/avatar.variants.ts +194 -0
  88. package/src/components/Badge/Badge.test.tsx +385 -0
  89. package/src/components/Badge/Badge.tsx +174 -0
  90. package/src/components/Badge/badge.types.ts +154 -0
  91. package/src/components/Badge/badge.variants.ts +161 -0
  92. package/src/components/Box/Box.test.tsx +21 -0
  93. package/src/components/Box/Box.tsx +32 -3
  94. package/src/components/Box/box.types.ts +55 -0
  95. package/src/components/Button/Button.test.tsx +21 -0
  96. package/src/components/Button/Button.tsx +28 -27
  97. package/src/components/Button/button.types.ts +36 -0
  98. package/src/components/Card/Card.test.tsx +291 -0
  99. package/src/components/Card/Card.tsx +241 -0
  100. package/src/components/Card/card.types.ts +132 -0
  101. package/src/components/Chip/Chip.test.tsx +316 -0
  102. package/src/components/Chip/Chip.tsx +224 -0
  103. package/src/components/Chip/chip.types.ts +128 -0
  104. package/src/components/Chip/chip.variants.ts +173 -0
  105. package/src/components/DataGrid/visibility/ColumnVisibilityMenu.tsx +1 -1
  106. package/src/components/IconButton/IconButton.test.tsx +367 -0
  107. package/src/components/IconButton/IconButton.tsx +159 -0
  108. package/src/components/IconButton/iconButton.types.ts +106 -0
  109. package/src/components/IconButton/iconButton.variants.ts +31 -0
  110. package/src/components/LeftNav/leftNav.variants.ts +2 -2
  111. package/src/components/Menu/Menu.test.tsx +408 -0
  112. package/src/components/Menu/Menu.tsx +335 -0
  113. package/src/components/Menu/menu.types.ts +221 -0
  114. package/src/components/Menu/menu.variants.ts +132 -0
  115. package/src/components/Pagination/pagination.variants.ts +1 -1
  116. package/src/components/Snackbar/Snackbar.tsx +46 -28
  117. package/src/components/Snackbar/snackbar.types.ts +47 -3
  118. package/src/components/Snackbar/snackbar.variants.ts +29 -22
  119. package/src/components/Spinner/Spinner.test.tsx +199 -0
  120. package/src/components/Spinner/Spinner.tsx +158 -0
  121. package/src/components/Spinner/spinner.types.ts +113 -0
  122. package/src/components/Spinner/spinner.variants.ts +83 -0
  123. package/src/components/Table/cells/RenderChip.tsx +24 -87
  124. package/src/components/Table/cells/RowActionsMenu.tsx +1 -1
  125. package/src/components/TextField/TextField.test.tsx +5 -1
  126. package/src/components/_shared/severity/index.ts +33 -0
  127. package/src/components/_shared/severity/severity.types.ts +50 -0
  128. package/src/components/_shared/severity/severityIcons.tsx +104 -0
  129. package/src/components/_shared/severity/severityVariants.test.ts +136 -0
  130. package/src/components/_shared/severity/severityVariants.ts +115 -0
  131. package/src/index.ts +163 -1
  132. package/vite.config.ts +8 -0
  133. package/vitest.config.mts +8 -1
  134. package/LICENSE +0 -21
@@ -0,0 +1,304 @@
1
+ import {
2
+ Children,
3
+ cloneElement,
4
+ forwardRef,
5
+ isValidElement,
6
+ useState,
7
+ type ReactElement,
8
+ } from 'react';
9
+ import { cn } from '../../utils/cn.js';
10
+ import {
11
+ AVATAR_SOFT_FALLBACK,
12
+ AVATAR_TONE_FALLBACK,
13
+ avatarVariants,
14
+ } from './avatar.variants.js';
15
+ import type {
16
+ AvatarGroupProps,
17
+ AvatarProps,
18
+ AvatarShape,
19
+ AvatarSize,
20
+ } from './avatar.types.js';
21
+ import type { BoxProps } from '../Box/box.types.js';
22
+
23
+ /**
24
+ * Generic user icon — inline SVG fallback when no `src` and no
25
+ * `name` are provided. Stroke uses `currentColor` so it inherits the
26
+ * resolved fallback text color. Same convention as Calendar +
27
+ * Autocomplete + Alert icons (no icon-library dep).
28
+ *
29
+ * @internal
30
+ */
31
+ function DefaultUserIcon() {
32
+ return (
33
+ <svg
34
+ viewBox="0 0 24 24"
35
+ fill="none"
36
+ stroke="currentColor"
37
+ strokeWidth={1.75}
38
+ strokeLinecap="round"
39
+ strokeLinejoin="round"
40
+ aria-hidden="true"
41
+ >
42
+ <circle cx="12" cy="8" r="3.75" />
43
+ <path d="M4.5 20a7.5 7.5 0 0 1 15 0" />
44
+ </svg>
45
+ );
46
+ }
47
+
48
+ /**
49
+ * Map the semantic `shape` shortcut to a Box-style `radius` token.
50
+ * Used only when `radius` is NOT explicitly passed (explicit wins).
51
+ *
52
+ * @internal
53
+ */
54
+ function shapeToRadius(shape: AvatarShape): BoxProps['rounded'] {
55
+ switch (shape) {
56
+ case 'circle':
57
+ return 'full';
58
+ case 'rounded':
59
+ return 'lg';
60
+ case 'square':
61
+ return 'none';
62
+ }
63
+ }
64
+
65
+ /**
66
+ * Extract initials from a name string. Strategy:
67
+ * - Split by whitespace, filter empty.
68
+ * - Take the first letter of the first 2 tokens, uppercased.
69
+ * - "Maya Rodriguez" → "MR"
70
+ * - "Cher" → "C"
71
+ * - " multiple spaces " → "MS" (if 2+ words after trim)
72
+ * - "" → "" (empty string — caller falls back to icon)
73
+ *
74
+ * @internal
75
+ */
76
+ function initialsFromName(name?: string): string {
77
+ if (!name) return '';
78
+ const tokens = name.trim().split(/\s+/).filter(Boolean);
79
+ if (tokens.length === 0) return '';
80
+ return (tokens[0]![0]! + (tokens[1]?.[0] ?? '')).toUpperCase();
81
+ }
82
+
83
+ /**
84
+ * `<Avatar>` — image / initials / icon visual identity.
85
+ *
86
+ * Fallback chain (top to bottom — first match wins):
87
+ * 1. `src` set + image loads OK → render `<img>`
88
+ * 2. `src` set + image fails → render initials from `name`
89
+ * 3. `src` absent + `name` set → render initials from `name`
90
+ * 4. `fallbackIcon` set → render that ReactNode
91
+ * 5. Nothing → render generic user SVG
92
+ *
93
+ * Color resolution (only for fallback content, image surface is
94
+ * independent):
95
+ * - `color="primary"` only → soft default (bg-100, text-900)
96
+ * - `color="primary" tone={500}` → bg-primary-500 + text-primary-50
97
+ * - Outside the palette → use `sx`
98
+ *
99
+ * No `access` / `visibleWhen` — Avatar is display-only by category.
100
+ * For visibility gating, wrap in `<Box>` (which has both since
101
+ * Sprint 4.4).
102
+ */
103
+ export const Avatar = forwardRef<HTMLSpanElement, AvatarProps>(function Avatar(
104
+ props,
105
+ ref
106
+ ) {
107
+ const {
108
+ src,
109
+ alt,
110
+ imgProps,
111
+ name,
112
+ shape = 'circle',
113
+ radius,
114
+ size = 'md',
115
+ color = 'neutral',
116
+ tone,
117
+ fallbackIcon,
118
+ sx,
119
+ className,
120
+ } = props;
121
+
122
+ // Track image-load failures so we can fall through to initials/icon
123
+ // dynamically. `imgLoaded` distinguishes between "still loading"
124
+ // (don't show fallback yet — would flash) and "loaded successfully"
125
+ // (don't paint a fallback color underneath, which would peek through
126
+ // transparent PNGs).
127
+ const [imgFailed, setImgFailed] = useState(false);
128
+
129
+ // Resolve final radius: explicit `radius` prop wins over `shape`.
130
+ const finalRadius = radius ?? shapeToRadius(shape);
131
+
132
+ // Compute base classes from the TV recipe.
133
+ const v = avatarVariants({ size, radius: finalRadius });
134
+
135
+ // Fallback color resolution. `tone` (when set) drives the specific
136
+ // shade; otherwise the soft-default lookup is used.
137
+ const fallbackTone =
138
+ tone !== undefined
139
+ ? AVATAR_TONE_FALLBACK[color]?.[tone] ?? AVATAR_SOFT_FALLBACK[color]
140
+ : AVATAR_SOFT_FALLBACK[color];
141
+
142
+ // Image is "successful" when src is set AND the load hasn't failed.
143
+ const showImage = !!src && !imgFailed;
144
+ const initials = initialsFromName(name);
145
+
146
+ // The root carries the fallback color ONLY when we're showing the
147
+ // fallback content. Painting it underneath a successful image is
148
+ // wrong if the image has transparency.
149
+ const fallbackBgClasses = !showImage ? fallbackTone : '';
150
+
151
+ const rootClasses = cn(
152
+ v.root(),
153
+ fallbackBgClasses,
154
+ sx,
155
+ className
156
+ );
157
+
158
+ // Pick which fallback to render — priority: initials > custom icon > generic SVG.
159
+ const fallbackContent: ReactElement = initials ? (
160
+ <span className={v.initials()}>{initials}</span>
161
+ ) : fallbackIcon ? (
162
+ <span className="inline-flex items-center justify-center w-full h-full">
163
+ {fallbackIcon}
164
+ </span>
165
+ ) : (
166
+ <span className={v.icon() + ' inline-flex items-center justify-center'}>
167
+ <DefaultUserIcon />
168
+ </span>
169
+ );
170
+
171
+ return (
172
+ <span
173
+ ref={ref}
174
+ className={rootClasses}
175
+ role="img"
176
+ aria-label={alt ?? name ?? undefined}
177
+ >
178
+ {showImage ? (
179
+ // Inner img is DECORATIVE (alt="") — the parent span carries
180
+ // the accessible name via role="img" + aria-label. This avoids
181
+ // a duplicate role="img" announcement and matches MUI's a11y
182
+ // pattern.
183
+ <img
184
+ src={src}
185
+ alt=""
186
+ onError={() => setImgFailed(true)}
187
+ {...imgProps}
188
+ className={cn(v.img(), imgProps?.className)}
189
+ />
190
+ ) : (
191
+ fallbackContent
192
+ )}
193
+ </span>
194
+ );
195
+ });
196
+
197
+ Avatar.displayName = 'Avatar';
198
+
199
+ // ─── AvatarGroup ─────────────────────────────────────────────────
200
+
201
+ /**
202
+ * Horizontal spacing tokens for the group overlap. Negative margin
203
+ * pulls each child onto the previous, simulating the "stack of
204
+ * avatars" pattern. Tokens map to spacing scale.
205
+ *
206
+ * @internal
207
+ */
208
+ const GROUP_SPACING: Record<NonNullable<AvatarGroupProps['spacing']>, string> = {
209
+ xs: '-space-x-1',
210
+ sm: '-space-x-2',
211
+ md: '-space-x-3',
212
+ };
213
+
214
+ /**
215
+ * `<AvatarGroup>` — thin horizontal wrapper for overlapping avatars.
216
+ *
217
+ * Slices children to `max - 1` visible items and renders a trailing
218
+ * "+N" overflow indicator with the remaining count (when more than
219
+ * `max` children are passed).
220
+ *
221
+ * Each child Avatar inherits the group's `size` unless it explicitly
222
+ * overrides. When `withRing` is `true` (default), each visible
223
+ * Avatar gets a `ring-2 ring-white` halo so overlapping borders
224
+ * stay visually separated.
225
+ *
226
+ * @example
227
+ * ```tsx
228
+ * <AvatarGroup max={3}>
229
+ * <Avatar name="Maya Rodriguez" color="primary" />
230
+ * <Avatar name="John Doe" color="success" />
231
+ * <Avatar name="Sara Chen" color="warning" />
232
+ * <Avatar name="Lila Park" color="info" />
233
+ * <Avatar name="Eve Kim" color="danger" />
234
+ * </AvatarGroup>
235
+ * // Renders: MR, JD, SC + a "+2" overflow chip
236
+ * ```
237
+ */
238
+ export const AvatarGroup = forwardRef<HTMLDivElement, AvatarGroupProps>(
239
+ function AvatarGroup(props, ref) {
240
+ const {
241
+ children,
242
+ max = 4,
243
+ size = 'md',
244
+ spacing = 'sm',
245
+ withRing = true,
246
+ className,
247
+ sx,
248
+ } = props;
249
+
250
+ const allChildren = Children.toArray(children).filter(isValidElement);
251
+ const total = allChildren.length;
252
+ const visibleCount = Math.min(total, max);
253
+ const overflow = Math.max(0, total - visibleCount);
254
+
255
+ // Decorate each visible child with size (if not overridden by the
256
+ // child) and optional ring halo. cloneElement is the standard
257
+ // React pattern for prop-injection across a children array.
258
+ const visible = allChildren.slice(0, visibleCount).map((child, idx) => {
259
+ const childProps = (child as ReactElement<AvatarProps>).props;
260
+ const inheritedSize: AvatarSize = childProps.size ?? size;
261
+ const ringClass = withRing ? 'ring-2 ring-neutral-50' : '';
262
+ const mergedSx = cn(
263
+ ringClass,
264
+ childProps.sx as string | undefined,
265
+ childProps.className
266
+ );
267
+ return cloneElement(child as ReactElement<AvatarProps>, {
268
+ key: idx,
269
+ size: inheritedSize,
270
+ sx: mergedSx,
271
+ });
272
+ });
273
+
274
+ return (
275
+ <div
276
+ ref={ref}
277
+ className={cn(
278
+ 'inline-flex items-center',
279
+ GROUP_SPACING[spacing],
280
+ sx,
281
+ className
282
+ )}
283
+ >
284
+ {visible}
285
+ {overflow > 0 && (
286
+ <Avatar
287
+ // The overflow indicator IS an avatar (same dimensions /
288
+ // radius), but with a +N text fallback rather than initials.
289
+ // We pass an empty `name` and a custom `fallbackIcon` that
290
+ // renders the count.
291
+ size={size}
292
+ color="neutral"
293
+ sx={cn(withRing && 'ring-2 ring-neutral-50')}
294
+ fallbackIcon={
295
+ <span className="text-xs font-medium">+{overflow}</span>
296
+ }
297
+ />
298
+ )}
299
+ </div>
300
+ );
301
+ }
302
+ );
303
+
304
+ AvatarGroup.displayName = 'AvatarGroup';
@@ -0,0 +1,205 @@
1
+ import type { ImgHTMLAttributes, ReactNode } from 'react';
2
+ import type { ClassValue } from 'tailwind-variants';
3
+ import type { BoxProps } from '../Box/box.types.js';
4
+
5
+ /**
6
+ * Avatar size scale — maps to spacing tokens via avatar.variants.ts:
7
+ * - xs → w-5 / 20px
8
+ * - sm → w-7 / 28px
9
+ * - md → w-9 / 36px ← default
10
+ * - lg → w-12 / 48px
11
+ * - xl → w-16 / 64px
12
+ */
13
+ export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
14
+
15
+ /**
16
+ * Avatar shape — semantic shortcut. Maps internally to a Box-style
17
+ * `radius` value:
18
+ * - circle → 'full'
19
+ * - rounded → 'lg'
20
+ * - square → 'none'
21
+ *
22
+ * When both `shape` and `radius` are set, `radius` wins (explicit
23
+ * token reference takes precedence over semantic shortcut).
24
+ */
25
+ export type AvatarShape = 'circle' | 'rounded' | 'square';
26
+
27
+ /**
28
+ * Intent color — drives the fallback bg + text colors when no `src`
29
+ * is provided (or when the image fails to load). Reuses the 7
30
+ * Dashforge intent tokens.
31
+ */
32
+ export type AvatarColor =
33
+ | 'neutral'
34
+ | 'primary'
35
+ | 'secondary'
36
+ | 'success'
37
+ | 'warning'
38
+ | 'danger'
39
+ | 'info';
40
+
41
+ /**
42
+ * Tone shade for the fallback background — gives type-safe access to
43
+ * any specific shade within the chosen `color` palette. When omitted,
44
+ * the default "soft" treatment is applied (bg-{color}-100 +
45
+ * text-{color}-900). When set, both bg and text are computed:
46
+ * - tones 50-400 → bg-{color}-{tone} + text-{color}-900 (dark text)
47
+ * - tones 500-900 → bg-{color}-{tone} + text-{color}-50 (light text)
48
+ *
49
+ * For colors outside the token palette (custom hex, gradient, image
50
+ * patterns), use the `sx` escape hatch with arbitrary Tailwind
51
+ * utilities.
52
+ */
53
+ export type AvatarTone =
54
+ | 50
55
+ | 100
56
+ | 200
57
+ | 300
58
+ | 400
59
+ | 500
60
+ | 600
61
+ | 700
62
+ | 800
63
+ | 900;
64
+
65
+ /**
66
+ * Props for `<Avatar>`.
67
+ *
68
+ * Fallback resolution chain:
69
+ * 1. `src` set + image loads OK → render `<img>`
70
+ * 2. `src` set + image fails → render initials from `name`
71
+ * (or a generic user icon if `name` is also absent)
72
+ * 3. `src` absent + `name` set → render initials from `name`
73
+ * (first letter of first two words, uppercased)
74
+ * 4. Everything absent → render a generic user icon
75
+ *
76
+ * No `access` / `visibleWhen` — Avatar is display-only by category.
77
+ * For visibility gating, wrap in `<Box>` (which has both props since
78
+ * Sprint 4.4).
79
+ */
80
+ export interface AvatarProps {
81
+ // ─── Image source ──────────────────────────────────────────────
82
+ /** Image URL. Falls back to initials/icon on load failure. */
83
+ src?: string;
84
+
85
+ /**
86
+ * `alt` text for the image. **Required when `src` is set** (a11y
87
+ * — screen readers need a name). When `src` is absent, the alt is
88
+ * implied from `name`.
89
+ */
90
+ alt?: string;
91
+
92
+ /** Additional `<img>` HTML attributes (sizes, loading, srcSet, …). */
93
+ imgProps?: ImgHTMLAttributes<HTMLImageElement>;
94
+
95
+ // ─── Fallback ──────────────────────────────────────────────────
96
+ /**
97
+ * Person / entity name. Auto-generates initials when `src` is
98
+ * absent or the image fails to load. Algorithm: take the first
99
+ * letter of the first two whitespace-separated words, uppercased.
100
+ * "Maya Rodriguez" → "MR". "Cher" → "C". Empty → generic icon.
101
+ */
102
+ name?: string;
103
+
104
+ // ─── Visual ────────────────────────────────────────────────────
105
+ /**
106
+ * Shape — semantic shortcut. Override with `radius` for fine
107
+ * control on the Box token scale.
108
+ * @default 'circle'
109
+ */
110
+ shape?: AvatarShape;
111
+
112
+ /**
113
+ * Border radius — same enum as `<Box rounded>` (Box token scale).
114
+ * When set, overrides the `shape` mapping. Useful for matching a
115
+ * specific Card/Box radius (e.g., `radius='2xl'`).
116
+ */
117
+ radius?: BoxProps['rounded'];
118
+
119
+ /** @default 'md' */
120
+ size?: AvatarSize;
121
+
122
+ /**
123
+ * Intent color used for the fallback background. Ignored when the
124
+ * image loads successfully.
125
+ * @default 'neutral'
126
+ */
127
+ color?: AvatarColor;
128
+
129
+ /**
130
+ * Specific shade within the `color` palette (TS-safe). When set,
131
+ * overrides the default "soft" treatment. See `AvatarTone` for the
132
+ * full scale.
133
+ */
134
+ tone?: AvatarTone;
135
+
136
+ // ─── Override ──────────────────────────────────────────────────
137
+ /** Root-element class shortcut (string or clsx-compatible value). */
138
+ sx?: ClassValue;
139
+
140
+ /** Standard React className — appended to the root via `cn()`. */
141
+ className?: string;
142
+
143
+ /**
144
+ * Optional custom fallback ReactNode — replaces both initials and
145
+ * the generic icon when the image is absent / fails. Useful for
146
+ * Avatar-with-emoji or Avatar-with-custom-icon patterns. When
147
+ * passed, `name` is ignored for initials generation but kept as
148
+ * `alt` semantic.
149
+ *
150
+ * **NB**: this is the ONE exception to the "no fallback prop —
151
+ * only name" rule from the spec. Kept narrow because emoji /
152
+ * custom icon avatars are common enough that forcing `sx` for
153
+ * them would be friction.
154
+ */
155
+ fallbackIcon?: ReactNode;
156
+ }
157
+
158
+ /**
159
+ * Props for `<AvatarGroup>` — thin horizontal wrapper.
160
+ *
161
+ * Renders the first `max` children visibly (with negative-margin
162
+ * overlap), then an overflow indicator avatar with the remaining
163
+ * count. Each child Avatar inherits `size` from the group unless it
164
+ * overrides explicitly. Optional `ring-2 ring-white` halo on each
165
+ * child via the group's `withRing` prop (visually separates
166
+ * overlapping avatars on a busy background).
167
+ */
168
+ export interface AvatarGroupProps {
169
+ /** Avatar children. */
170
+ children: ReactNode;
171
+
172
+ /**
173
+ * Max number of avatars to render visibly. Excess collapses into
174
+ * a trailing "+N" overflow indicator.
175
+ * @default 4
176
+ */
177
+ max?: number;
178
+
179
+ /**
180
+ * Size applied to every child Avatar (unless the child explicitly
181
+ * overrides). Propagated via React.cloneElement.
182
+ * @default 'md'
183
+ */
184
+ size?: AvatarSize;
185
+
186
+ /**
187
+ * Negative margin between overlapping avatars. Tighter = more
188
+ * overlap. Looser = more space.
189
+ * @default 'sm'
190
+ */
191
+ spacing?: 'xs' | 'sm' | 'md';
192
+
193
+ /**
194
+ * Wrap each child avatar with a `ring-2 ring-white` halo for
195
+ * separation on busy backgrounds.
196
+ * @default true
197
+ */
198
+ withRing?: boolean;
199
+
200
+ /** Standard className. */
201
+ className?: string;
202
+
203
+ /** sx escape hatch. */
204
+ sx?: ClassValue;
205
+ }
@@ -0,0 +1,194 @@
1
+ import { tv, type VariantProps } from 'tailwind-variants';
2
+
3
+ /**
4
+ * Tailwind-variants recipe for `<Avatar>`.
5
+ *
6
+ * Axes:
7
+ * - `size` — 5 steps (xs/sm/md/lg/xl), maps to w/h spacing tokens
8
+ * + matching text-size for the initials inside.
9
+ * - `radius` — 7 steps (none/sm/md/lg/xl/2xl/full), same scale as
10
+ * `<Box rounded>`. `shape` prop in the component maps
11
+ * semantically: circle → full, rounded → lg, square → none.
12
+ * - `color` — 7 intents. Drives the FALLBACK bg+text only (image
13
+ * surface is independent of color).
14
+ *
15
+ * The `color` × `tone` combo is resolved at render time in
16
+ * `Avatar.tsx` via compound lookup — see the SOFT_TINT and TONE
17
+ * tables there. We do NOT expand the matrix exhaustively in this TV
18
+ * recipe (it would be 7 colors × 10 tones × 5 sizes = 350 rules; the
19
+ * runtime resolver keeps the recipe slim).
20
+ */
21
+ export const avatarVariants = tv({
22
+ slots: {
23
+ /** Outer wrapper — sets dimensions + radius + ring + alignment. */
24
+ root: [
25
+ 'relative inline-flex items-center justify-center shrink-0',
26
+ 'overflow-hidden align-middle',
27
+ 'select-none',
28
+ // The font weight + leading are baked into root so initials slot
29
+ // inherits them without an extra class layer.
30
+ 'font-medium leading-none',
31
+ ],
32
+ /** `<img>` slot — fills the root, object-cover for crop-to-square. */
33
+ img: 'block w-full h-full object-cover',
34
+ /** Initials text slot. */
35
+ initials: 'uppercase tracking-tight',
36
+ /** Generic user icon SVG fallback. */
37
+ icon: 'w-1/2 h-1/2 opacity-80',
38
+ },
39
+ variants: {
40
+ size: {
41
+ xs: {
42
+ root: 'w-5 h-5 text-[10px]',
43
+ initials: '',
44
+ },
45
+ sm: {
46
+ root: 'w-7 h-7 text-xs',
47
+ initials: '',
48
+ },
49
+ md: {
50
+ root: 'w-9 h-9 text-sm',
51
+ initials: '',
52
+ },
53
+ lg: {
54
+ root: 'w-12 h-12 text-base',
55
+ initials: '',
56
+ },
57
+ xl: {
58
+ root: 'w-16 h-16 text-xl',
59
+ initials: '',
60
+ },
61
+ },
62
+ radius: {
63
+ none: { root: 'rounded-none' },
64
+ sm: { root: 'rounded-sm' },
65
+ md: { root: 'rounded-md' },
66
+ lg: { root: 'rounded-lg' },
67
+ xl: { root: 'rounded-xl' },
68
+ '2xl':{ root: 'rounded-2xl' },
69
+ full: { root: 'rounded-full' },
70
+ },
71
+ },
72
+ defaultVariants: {
73
+ size: 'md',
74
+ radius: 'full',
75
+ },
76
+ });
77
+
78
+ export type AvatarVariants = VariantProps<typeof avatarVariants>;
79
+
80
+ /**
81
+ * Default "soft" fallback treatment per intent — what you get when
82
+ * `tone` is omitted. Light tinted bg + dark text for legibility.
83
+ * Neutral row uses no `dark:` because the dashforgePreset() CSS-var
84
+ * swap auto-inverts neutral; color rows keep `dark:` for the
85
+ * intentional palette shift (palette colors don't auto-invert).
86
+ */
87
+ export const AVATAR_SOFT_FALLBACK: Record<string, string> = {
88
+ neutral: 'bg-neutral-100 text-neutral-900',
89
+ primary: 'bg-primary-100 text-primary-900 dark:bg-primary-950 dark:text-primary-100',
90
+ secondary: 'bg-secondary-100 text-secondary-900 dark:bg-secondary-950 dark:text-secondary-100',
91
+ success: 'bg-success-100 text-success-900 dark:bg-success-950 dark:text-success-100',
92
+ warning: 'bg-warning-100 text-warning-900 dark:bg-warning-950 dark:text-warning-100',
93
+ danger: 'bg-danger-100 text-danger-900 dark:bg-danger-950 dark:text-danger-100',
94
+ info: 'bg-info-100 text-info-900 dark:bg-info-950 dark:text-info-100',
95
+ };
96
+
97
+ /**
98
+ * Specific-tone resolver — when the consumer sets `tone={500}` (or
99
+ * any other value), this lookup builds the matching bg + text class.
100
+ *
101
+ * Text color logic:
102
+ * - tones 50-400 → dark text (uses the 900 step)
103
+ * - tones 500-900 → light text (uses the 50 step)
104
+ *
105
+ * Tailwind JIT requires literal class strings, so we enumerate them
106
+ * explicitly here. The bundle cost is ~70 lines, acceptable for the
107
+ * type-safety win of letting consumers pick any palette shade.
108
+ */
109
+ export const AVATAR_TONE_FALLBACK: Record<string, Record<number, string>> = {
110
+ neutral: {
111
+ 50: 'bg-neutral-50 text-neutral-900',
112
+ 100: 'bg-neutral-100 text-neutral-900',
113
+ 200: 'bg-neutral-200 text-neutral-900',
114
+ 300: 'bg-neutral-300 text-neutral-900',
115
+ 400: 'bg-neutral-400 text-neutral-900',
116
+ 500: 'bg-neutral-500 text-neutral-50',
117
+ 600: 'bg-neutral-600 text-neutral-50',
118
+ 700: 'bg-neutral-700 text-neutral-50',
119
+ 800: 'bg-neutral-800 text-neutral-50',
120
+ 900: 'bg-neutral-900 text-neutral-50',
121
+ },
122
+ primary: {
123
+ 50: 'bg-primary-50 text-primary-900',
124
+ 100: 'bg-primary-100 text-primary-900',
125
+ 200: 'bg-primary-200 text-primary-900',
126
+ 300: 'bg-primary-300 text-primary-900',
127
+ 400: 'bg-primary-400 text-primary-900',
128
+ 500: 'bg-primary-500 text-primary-50',
129
+ 600: 'bg-primary-600 text-primary-50',
130
+ 700: 'bg-primary-700 text-primary-50',
131
+ 800: 'bg-primary-800 text-primary-50',
132
+ 900: 'bg-primary-900 text-primary-50',
133
+ },
134
+ secondary: {
135
+ 50: 'bg-secondary-50 text-secondary-900',
136
+ 100: 'bg-secondary-100 text-secondary-900',
137
+ 200: 'bg-secondary-200 text-secondary-900',
138
+ 300: 'bg-secondary-300 text-secondary-900',
139
+ 400: 'bg-secondary-400 text-secondary-900',
140
+ 500: 'bg-secondary-500 text-secondary-50',
141
+ 600: 'bg-secondary-600 text-secondary-50',
142
+ 700: 'bg-secondary-700 text-secondary-50',
143
+ 800: 'bg-secondary-800 text-secondary-50',
144
+ 900: 'bg-secondary-900 text-secondary-50',
145
+ },
146
+ success: {
147
+ 50: 'bg-success-50 text-success-900',
148
+ 100: 'bg-success-100 text-success-900',
149
+ 200: 'bg-success-200 text-success-900',
150
+ 300: 'bg-success-300 text-success-900',
151
+ 400: 'bg-success-400 text-success-900',
152
+ 500: 'bg-success-500 text-success-50',
153
+ 600: 'bg-success-600 text-success-50',
154
+ 700: 'bg-success-700 text-success-50',
155
+ 800: 'bg-success-800 text-success-50',
156
+ 900: 'bg-success-900 text-success-50',
157
+ },
158
+ warning: {
159
+ 50: 'bg-warning-50 text-warning-900',
160
+ 100: 'bg-warning-100 text-warning-900',
161
+ 200: 'bg-warning-200 text-warning-900',
162
+ 300: 'bg-warning-300 text-warning-900',
163
+ 400: 'bg-warning-400 text-warning-900',
164
+ 500: 'bg-warning-500 text-warning-50',
165
+ 600: 'bg-warning-600 text-warning-50',
166
+ 700: 'bg-warning-700 text-warning-50',
167
+ 800: 'bg-warning-800 text-warning-50',
168
+ 900: 'bg-warning-900 text-warning-50',
169
+ },
170
+ danger: {
171
+ 50: 'bg-danger-50 text-danger-900',
172
+ 100: 'bg-danger-100 text-danger-900',
173
+ 200: 'bg-danger-200 text-danger-900',
174
+ 300: 'bg-danger-300 text-danger-900',
175
+ 400: 'bg-danger-400 text-danger-900',
176
+ 500: 'bg-danger-500 text-danger-50',
177
+ 600: 'bg-danger-600 text-danger-50',
178
+ 700: 'bg-danger-700 text-danger-50',
179
+ 800: 'bg-danger-800 text-danger-50',
180
+ 900: 'bg-danger-900 text-danger-50',
181
+ },
182
+ info: {
183
+ 50: 'bg-info-50 text-info-900',
184
+ 100: 'bg-info-100 text-info-900',
185
+ 200: 'bg-info-200 text-info-900',
186
+ 300: 'bg-info-300 text-info-900',
187
+ 400: 'bg-info-400 text-info-900',
188
+ 500: 'bg-info-500 text-info-50',
189
+ 600: 'bg-info-600 text-info-50',
190
+ 700: 'bg-info-700 text-info-50',
191
+ 800: 'bg-info-800 text-info-50',
192
+ 900: 'bg-info-900 text-info-50',
193
+ },
194
+ };