@neynar/ui 0.1.1 → 0.1.2

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 (173) hide show
  1. package/dist/components/ui/accordion.d.ts +1 -25
  2. package/dist/components/ui/accordion.d.ts.map +1 -1
  3. package/dist/components/ui/alert-dialog.d.ts +240 -46
  4. package/dist/components/ui/alert-dialog.d.ts.map +1 -1
  5. package/dist/components/ui/alert.d.ts +73 -11
  6. package/dist/components/ui/alert.d.ts.map +1 -1
  7. package/dist/components/ui/aspect-ratio.d.ts +44 -10
  8. package/dist/components/ui/aspect-ratio.d.ts.map +1 -1
  9. package/dist/components/ui/avatar.d.ts +117 -33
  10. package/dist/components/ui/avatar.d.ts.map +1 -1
  11. package/dist/components/ui/badge.d.ts +50 -71
  12. package/dist/components/ui/badge.d.ts.map +1 -1
  13. package/dist/components/ui/breadcrumb.d.ts +231 -49
  14. package/dist/components/ui/breadcrumb.d.ts.map +1 -1
  15. package/dist/components/ui/button.d.ts +189 -71
  16. package/dist/components/ui/button.d.ts.map +1 -1
  17. package/dist/components/ui/calendar.d.ts +197 -40
  18. package/dist/components/ui/calendar.d.ts.map +1 -1
  19. package/dist/components/ui/card.d.ts +7 -22
  20. package/dist/components/ui/card.d.ts.map +1 -1
  21. package/dist/components/ui/carousel.d.ts +369 -99
  22. package/dist/components/ui/carousel.d.ts.map +1 -1
  23. package/dist/components/ui/chart.d.ts.map +1 -1
  24. package/dist/components/ui/checkbox.d.ts +110 -38
  25. package/dist/components/ui/checkbox.d.ts.map +1 -1
  26. package/dist/components/ui/collapsible.d.ts +246 -61
  27. package/dist/components/ui/collapsible.d.ts.map +1 -1
  28. package/dist/components/ui/combobox.d.ts +207 -159
  29. package/dist/components/ui/combobox.d.ts.map +1 -1
  30. package/dist/components/ui/command.d.ts +336 -67
  31. package/dist/components/ui/command.d.ts.map +1 -1
  32. package/dist/components/ui/container.d.ts +159 -64
  33. package/dist/components/ui/container.d.ts.map +1 -1
  34. package/dist/components/ui/context-menu.d.ts +321 -39
  35. package/dist/components/ui/context-menu.d.ts.map +1 -1
  36. package/dist/components/ui/date-picker.d.ts +113 -86
  37. package/dist/components/ui/date-picker.d.ts.map +1 -1
  38. package/dist/components/ui/dialog.d.ts +106 -25
  39. package/dist/components/ui/dialog.d.ts.map +1 -1
  40. package/dist/components/ui/drawer.d.ts +388 -59
  41. package/dist/components/ui/drawer.d.ts.map +1 -1
  42. package/dist/components/ui/dropdown-menu.d.ts +521 -74
  43. package/dist/components/ui/dropdown-menu.d.ts.map +1 -1
  44. package/dist/components/ui/empty-state.d.ts +148 -76
  45. package/dist/components/ui/empty-state.d.ts.map +1 -1
  46. package/dist/components/ui/hover-card.d.ts +253 -34
  47. package/dist/components/ui/hover-card.d.ts.map +1 -1
  48. package/dist/components/ui/input.d.ts +143 -44
  49. package/dist/components/ui/input.d.ts.map +1 -1
  50. package/dist/components/ui/label.d.ts +0 -8
  51. package/dist/components/ui/label.d.ts.map +1 -1
  52. package/dist/components/ui/menubar.d.ts +288 -46
  53. package/dist/components/ui/menubar.d.ts.map +1 -1
  54. package/dist/components/ui/navigation-menu.d.ts +444 -127
  55. package/dist/components/ui/navigation-menu.d.ts.map +1 -1
  56. package/dist/components/ui/pagination.d.ts +342 -66
  57. package/dist/components/ui/pagination.d.ts.map +1 -1
  58. package/dist/components/ui/popover.d.ts +0 -8
  59. package/dist/components/ui/popover.d.ts.map +1 -1
  60. package/dist/components/ui/progress.d.ts +88 -30
  61. package/dist/components/ui/progress.d.ts.map +1 -1
  62. package/dist/components/ui/radio-group.d.ts +189 -45
  63. package/dist/components/ui/radio-group.d.ts.map +1 -1
  64. package/dist/components/ui/resizable.d.ts +178 -62
  65. package/dist/components/ui/resizable.d.ts.map +1 -1
  66. package/dist/components/ui/scroll-area.d.ts +180 -21
  67. package/dist/components/ui/scroll-area.d.ts.map +1 -1
  68. package/dist/components/ui/select.d.ts +382 -60
  69. package/dist/components/ui/select.d.ts.map +1 -1
  70. package/dist/components/ui/separator.d.ts +52 -39
  71. package/dist/components/ui/separator.d.ts.map +1 -1
  72. package/dist/components/ui/sheet.d.ts +144 -27
  73. package/dist/components/ui/sheet.d.ts.map +1 -1
  74. package/dist/components/ui/sidebar.d.ts +81 -31
  75. package/dist/components/ui/sidebar.d.ts.map +1 -1
  76. package/dist/components/ui/skeleton.d.ts +94 -32
  77. package/dist/components/ui/skeleton.d.ts.map +1 -1
  78. package/dist/components/ui/slider.d.ts +37 -31
  79. package/dist/components/ui/slider.d.ts.map +1 -1
  80. package/dist/components/ui/sonner.d.ts +280 -46
  81. package/dist/components/ui/sonner.d.ts.map +1 -1
  82. package/dist/components/ui/stack.d.ts +289 -148
  83. package/dist/components/ui/stack.d.ts.map +1 -1
  84. package/dist/components/ui/stories/aspect-ratio.stories.d.ts +1 -2
  85. package/dist/components/ui/stories/aspect-ratio.stories.d.ts.map +1 -1
  86. package/dist/components/ui/stories/container.stories.d.ts +2 -3
  87. package/dist/components/ui/stories/container.stories.d.ts.map +1 -1
  88. package/dist/components/ui/stories/empty-state.stories.d.ts +2 -2
  89. package/dist/components/ui/stories/scroll-area.stories.d.ts +1 -2
  90. package/dist/components/ui/stories/scroll-area.stories.d.ts.map +1 -1
  91. package/dist/components/ui/stories/stack.stories.d.ts +1 -1
  92. package/dist/components/ui/stories/text-field.stories.d.ts +7 -1
  93. package/dist/components/ui/stories/text-field.stories.d.ts.map +1 -1
  94. package/dist/components/ui/switch.d.ts +44 -38
  95. package/dist/components/ui/switch.d.ts.map +1 -1
  96. package/dist/components/ui/table.d.ts +33 -0
  97. package/dist/components/ui/table.d.ts.map +1 -1
  98. package/dist/components/ui/tabs.d.ts +4 -22
  99. package/dist/components/ui/tabs.d.ts.map +1 -1
  100. package/dist/components/ui/text-field.d.ts +170 -84
  101. package/dist/components/ui/text-field.d.ts.map +1 -1
  102. package/dist/components/ui/textarea.d.ts +106 -29
  103. package/dist/components/ui/textarea.d.ts.map +1 -1
  104. package/dist/components/ui/theme-toggle.d.ts +190 -65
  105. package/dist/components/ui/theme-toggle.d.ts.map +1 -1
  106. package/dist/components/ui/theme.d.ts +107 -23
  107. package/dist/components/ui/theme.d.ts.map +1 -1
  108. package/dist/components/ui/toggle-group.d.ts +143 -67
  109. package/dist/components/ui/toggle-group.d.ts.map +1 -1
  110. package/dist/components/ui/toggle.d.ts +118 -30
  111. package/dist/components/ui/toggle.d.ts.map +1 -1
  112. package/dist/components/ui/tooltip.d.ts +152 -28
  113. package/dist/components/ui/tooltip.d.ts.map +1 -1
  114. package/dist/components/ui/typography.d.ts +452 -134
  115. package/dist/components/ui/typography.d.ts.map +1 -1
  116. package/dist/index.js +9388 -8281
  117. package/dist/index.js.map +1 -1
  118. package/dist/tsconfig.tsbuildinfo +1 -1
  119. package/llms.txt +173 -3
  120. package/package.json +5 -2
  121. package/src/components/ui/accordion.tsx +112 -27
  122. package/src/components/ui/alert-dialog.tsx +401 -46
  123. package/src/components/ui/alert.tsx +114 -11
  124. package/src/components/ui/aspect-ratio.tsx +69 -14
  125. package/src/components/ui/avatar.tsx +179 -33
  126. package/src/components/ui/badge.tsx +74 -75
  127. package/src/components/ui/breadcrumb.tsx +335 -50
  128. package/src/components/ui/button.tsx +198 -90
  129. package/src/components/ui/calendar.tsx +867 -43
  130. package/src/components/ui/card.tsx +140 -33
  131. package/src/components/ui/carousel.tsx +529 -98
  132. package/src/components/ui/chart.tsx +222 -1
  133. package/src/components/ui/checkbox.tsx +176 -38
  134. package/src/components/ui/collapsible.tsx +321 -67
  135. package/src/components/ui/combobox.tsx +284 -83
  136. package/src/components/ui/command.tsx +527 -67
  137. package/src/components/ui/container.tsx +217 -65
  138. package/src/components/ui/context-menu.tsx +716 -51
  139. package/src/components/ui/date-picker.tsx +228 -38
  140. package/src/components/ui/dialog.tsx +270 -33
  141. package/src/components/ui/drawer.tsx +546 -67
  142. package/src/components/ui/dropdown-menu.tsx +657 -74
  143. package/src/components/ui/empty-state.tsx +241 -82
  144. package/src/components/ui/hover-card.tsx +328 -39
  145. package/src/components/ui/input.tsx +207 -44
  146. package/src/components/ui/label.tsx +98 -8
  147. package/src/components/ui/menubar.tsx +587 -54
  148. package/src/components/ui/navigation-menu.tsx +557 -128
  149. package/src/components/ui/pagination.tsx +561 -79
  150. package/src/components/ui/popover.tsx +119 -8
  151. package/src/components/ui/progress.tsx +131 -29
  152. package/src/components/ui/radio-group.tsx +260 -51
  153. package/src/components/ui/resizable.tsx +289 -63
  154. package/src/components/ui/scroll-area.tsx +377 -66
  155. package/src/components/ui/select.tsx +545 -60
  156. package/src/components/ui/separator.tsx +146 -40
  157. package/src/components/ui/sheet.tsx +348 -31
  158. package/src/components/ui/sidebar.tsx +471 -29
  159. package/src/components/ui/skeleton.tsx +114 -32
  160. package/src/components/ui/slider.tsx +77 -31
  161. package/src/components/ui/sonner.tsx +574 -46
  162. package/src/components/ui/stack.tsx +423 -101
  163. package/src/components/ui/switch.tsx +78 -39
  164. package/src/components/ui/table.tsx +170 -4
  165. package/src/components/ui/tabs.tsx +108 -22
  166. package/src/components/ui/text-field.tsx +226 -81
  167. package/src/components/ui/textarea.tsx +180 -29
  168. package/src/components/ui/theme-toggle.tsx +313 -65
  169. package/src/components/ui/theme.tsx +117 -23
  170. package/src/components/ui/toggle-group.tsx +280 -69
  171. package/src/components/ui/toggle.tsx +124 -35
  172. package/src/components/ui/tooltip.tsx +239 -29
  173. package/src/components/ui/typography.tsx +1115 -165
@@ -1,5 +1,5 @@
1
1
  import * as React from "react";
2
- import { Command as CommandPrimitive } from "cmdk";
2
+ import { Command as CommandPrimitive, useCommandState } from "cmdk";
3
3
  import { Dialog } from "@/components/ui/dialog";
4
4
  /**
5
5
  * Command - A fast, composable command menu for search and navigation
@@ -8,11 +8,23 @@ import { Dialog } from "@/components/ui/dialog";
8
8
  * interface with search, filtering, and keyboard navigation. Perfect for creating
9
9
  * search interfaces, command palettes, and action menus with full accessibility support.
10
10
  *
11
- * @component
11
+ * Features advanced filtering with fuzzy search, keyboard shortcuts, nested navigation,
12
+ * asynchronous loading states, and comprehensive accessibility patterns.
13
+ *
14
+ * @param label - Accessibility label for screen readers and assistive technology
15
+ * @param shouldFilter - Controls automatic filtering and sorting @default true
16
+ * @param filter - Custom filter function for ranking items based on search
17
+ * @param value - Currently selected item value for controlled usage
18
+ * @param onValueChange - Callback fired when selected item changes
19
+ * @param loop - Enables circular navigation through items @default false
20
+ * @param disablePointerSelection - Prevents mouse selection behavior @default true
21
+ * @param vimBindings - Enables Vim-style navigation keybindings @default false
22
+ * @param className - Additional CSS classes
23
+ *
12
24
  * @example
13
25
  * ```tsx
14
26
  * // Basic command menu
15
- * <Command>
27
+ * <Command label="Main Menu">
16
28
  * <CommandInput placeholder="Type a command or search..." />
17
29
  * <CommandList>
18
30
  * <CommandEmpty>No results found.</CommandEmpty>
@@ -27,6 +39,34 @@ import { Dialog } from "@/components/ui/dialog";
27
39
  *
28
40
  * @example
29
41
  * ```tsx
42
+ * // Controlled command menu with custom filtering
43
+ * const [value, setValue] = useState('');
44
+ * const [search, setSearch] = useState('');
45
+ *
46
+ * <Command
47
+ * value={value}
48
+ * onValueChange={setValue}
49
+ * filter={(value, search, keywords) => {
50
+ * const extended = value + ' ' + (keywords?.join(' ') || '');
51
+ * return extended.toLowerCase().includes(search.toLowerCase()) ? 1 : 0;
52
+ * }}
53
+ * loop
54
+ * >
55
+ * <CommandInput
56
+ * value={search}
57
+ * onValueChange={setSearch}
58
+ * placeholder="Search..."
59
+ * />
60
+ * <CommandList>
61
+ * <CommandItem value="apple" keywords={['fruit', 'red']}>
62
+ * Apple
63
+ * </CommandItem>
64
+ * </CommandList>
65
+ * </Command>
66
+ * ```
67
+ *
68
+ * @example
69
+ * ```tsx
30
70
  * // Command dialog with keyboard shortcut
31
71
  * const [open, setOpen] = useState(false);
32
72
  *
@@ -55,17 +95,20 @@ import { Dialog } from "@/components/ui/dialog";
55
95
  * ```
56
96
  *
57
97
  * @accessibility
58
- * - Full keyboard navigation with arrow keys and Home/End
59
- * - Type-ahead search and filtering
98
+ * - Full keyboard navigation with Arrow keys, Home/End, Page Up/Down
99
+ * - Type-ahead search with live region announcements
60
100
  * - Enter key to select items, Escape to close dialogs
61
- * - Screen reader announcements for filtered results
62
- * - ARIA roles following command palette pattern
63
- * - Focus management and trapping in dialog mode
101
+ * - Screen reader announcements for filtered results and state changes
102
+ * - ARIA roles following WAI-ARIA command palette patterns
103
+ * - Focus management with proper tab trapping in dialog mode
104
+ * - Support for disabled items and groups
64
105
  *
106
+ * @see {@link https://cmdk.paco.me} Official CMDK documentation
65
107
  * @see {@link https://ui.shadcn.com/docs/components/command} for design patterns
66
108
  * @see {@link CommandDialog} - For modal command palette
67
109
  * @see {@link CommandInput} - Search input component
68
110
  * @see {@link CommandList} - Scrollable results container
111
+ * @see {@link useCommandState} - Hook for accessing command state
69
112
  * @since 1.0.0
70
113
  */
71
114
  declare function Command({ className, ...props }: React.ComponentProps<typeof CommandPrimitive>): import("react/jsx-runtime").JSX.Element;
@@ -73,10 +116,20 @@ declare function Command({ className, ...props }: React.ComponentProps<typeof Co
73
116
  * CommandDialog - Modal dialog wrapper for command menu
74
117
  *
75
118
  * Presents the command menu in a modal dialog overlay, perfect for application-wide
76
- * command palettes triggered by keyboard shortcuts like Cmd+K. Includes proper
77
- * focus management and accessibility features.
119
+ * command palettes triggered by keyboard shortcuts like Cmd+K or Ctrl+K. Built on
120
+ * Radix UI Dialog with proper focus management, portal rendering, and accessibility.
121
+ *
122
+ * The dialog automatically handles focus trapping, scroll locking, and provides
123
+ * screen reader announcements. Use `container` prop to specify custom portal target.
124
+ *
125
+ * @param open - Controls dialog visibility state
126
+ * @param onOpenChange - Callback when dialog open state changes
127
+ * @param title - Screen reader accessible title @default "Command Palette"
128
+ * @param description - Screen reader description @default "Search for a command to run..."
129
+ * @param showCloseButton - Whether to show the X close button @default true
130
+ * @param container - Custom portal container element for rendering
131
+ * @param className - Additional CSS classes for dialog content
78
132
  *
79
- * @component
80
133
  * @example
81
134
  * ```tsx
82
135
  * // Command palette dialog with keyboard shortcut
@@ -104,48 +157,68 @@ declare function Command({ className, ...props }: React.ComponentProps<typeof Co
104
157
  * </CommandDialog>
105
158
  * ```
106
159
  *
107
- * @param title - Screen reader title for the dialog
108
- * @param description - Screen reader description for the dialog
109
- * @param showCloseButton - Whether to show the close button
160
+ * @example
161
+ * ```tsx
162
+ * // Custom portal container
163
+ * const containerRef = useRef<HTMLDivElement>(null);
164
+ *
165
+ * <>
166
+ * <CommandDialog
167
+ * open={open}
168
+ * onOpenChange={setOpen}
169
+ * container={containerRef.current}
170
+ * title="Quick Actions"
171
+ * description="Find and run commands quickly"
172
+ * >
173
+ * <CommandInput />
174
+ * <CommandList>
175
+ * <CommandItem>Action 1</CommandItem>
176
+ * </CommandList>
177
+ * </CommandDialog>
178
+ * <div ref={containerRef} />
179
+ * </>
180
+ * ```
110
181
  *
111
182
  * @accessibility
112
- * - Focus trapped within dialog when open
183
+ * - Focus trapped within dialog when open with proper restoration
113
184
  * - Escape key closes the dialog
185
+ * - Click outside or close button dismisses dialog
114
186
  * - Screen reader announcements with title and description
115
187
  * - Preserves all command menu keyboard navigation
188
+ * - Modal backdrop prevents interaction with background content
116
189
  *
190
+ * @see {@link Dialog} - Base dialog component
191
+ * @see {@link Command} - Command menu component
117
192
  * @since 1.0.0
118
193
  */
119
- declare function CommandDialog({ title, description, children, className, showCloseButton, ...props }: React.ComponentProps<typeof Dialog> & {
120
- /**
121
- * The title for screen readers
122
- * @default "Command Palette"
123
- */
194
+ declare function CommandDialog({ title, description, children, className, showCloseButton, ...props }: {
124
195
  title?: string;
125
- /**
126
- * The description for screen readers
127
- * @default "Search for a command to run..."
128
- */
129
196
  description?: string;
130
- /**
131
- * Additional CSS classes
132
- */
197
+ children?: React.ReactNode;
133
198
  className?: string;
134
- /**
135
- * Whether to show the close button
136
- * @default true
137
- */
138
199
  showCloseButton?: boolean;
139
- }): import("react/jsx-runtime").JSX.Element;
200
+ } & React.ComponentProps<typeof Dialog>): import("react/jsx-runtime").JSX.Element;
140
201
  /**
141
202
  * CommandInput - Search input for command menu filtering
142
203
  *
143
204
  * Provides a search input with search icon for filtering command menu items.
144
- * Automatically filters items as the user types and handles focus management.
205
+ * Automatically filters items as the user types and triggers live region announcements
206
+ * for screen readers. Supports both controlled and uncontrolled usage patterns.
207
+ *
208
+ * The input integrates with the Command context to provide real-time filtering,
209
+ * search highlighting, and result announcements. Includes built-in search icon
210
+ * and proper focus management.
211
+ *
212
+ * @param value - Controlled input value for managing search state externally
213
+ * @param onValueChange - Callback fired when input value changes
214
+ * @param placeholder - Placeholder text displayed when input is empty
215
+ * @param disabled - Disables the input and prevents interaction @default false
216
+ * @param autoFocus - Auto-focus the input when rendered @default false
217
+ * @param className - Additional CSS classes
145
218
  *
146
- * @component
147
219
  * @example
148
220
  * ```tsx
221
+ * // Basic uncontrolled input
149
222
  * <Command>
150
223
  * <CommandInput placeholder="Search commands..." />
151
224
  * <CommandList>...</CommandList>
@@ -154,18 +227,32 @@ declare function CommandDialog({ title, description, children, className, showCl
154
227
  *
155
228
  * @example
156
229
  * ```tsx
157
- * // Controlled input with state
230
+ * // Controlled input with external state
231
+ * const [search, setSearch] = useState('');
232
+ *
158
233
  * <CommandInput
234
+ * value={search}
235
+ * onValueChange={setSearch}
159
236
  * placeholder="Type a command or search..."
160
- * value={searchValue}
161
- * onValueChange={setSearchValue}
237
+ * autoFocus
238
+ * />
239
+ * ```
240
+ *
241
+ * @example
242
+ * ```tsx
243
+ * // With disabled state
244
+ * <CommandInput
245
+ * placeholder="Loading..."
246
+ * disabled={isLoading}
162
247
  * />
163
248
  * ```
164
249
  *
165
250
  * @accessibility
166
- * - Auto-focuses when command menu opens
167
- * - Live region announces result count to screen readers
251
+ * - Auto-focuses when command menu opens (if autoFocus is true)
252
+ * - Live region announces result count changes to screen readers
168
253
  * - Supports all standard input accessibility features
254
+ * - Proper labeling and description associations
255
+ * - Keyboard navigation integration with command list
169
256
  *
170
257
  * @since 1.0.0
171
258
  */
@@ -173,10 +260,15 @@ declare function CommandInput({ className, ...props }: React.ComponentProps<type
173
260
  /**
174
261
  * CommandList - Scrollable container for command items
175
262
  *
176
- * Contains and manages the list of command items with automatic scrolling
177
- * and overflow handling. Manages keyboard navigation and selection state.
263
+ * Contains and manages the list of command items with automatic scrolling,
264
+ * overflow handling, and dynamic height calculation. Provides the scrollable
265
+ * viewport for command items and groups with proper keyboard navigation.
266
+ *
267
+ * Uses CSS custom property `--cmdk-list-height` for smooth height transitions
268
+ * when items are filtered. Supports scroll padding for better item visibility.
269
+ *
270
+ * @param className - Additional CSS classes
178
271
  *
179
- * @component
180
272
  * @example
181
273
  * ```tsx
182
274
  * <CommandList>
@@ -188,10 +280,25 @@ declare function CommandInput({ className, ...props }: React.ComponentProps<type
188
280
  * </CommandList>
189
281
  * ```
190
282
  *
283
+ * @example
284
+ * ```tsx
285
+ * // With custom height and scroll behavior
286
+ * <CommandList className="max-h-[400px] scroll-py-2">
287
+ * {items.map((item) => (
288
+ * <CommandItem key={item.id} value={item.id}>
289
+ * {item.name}
290
+ * </CommandItem>
291
+ * ))}
292
+ * </CommandList>
293
+ * ```
294
+ *
191
295
  * @accessibility
192
296
  * - Scrollable with keyboard arrow navigation
193
297
  * - Maintains focus within list boundaries
194
- * - Supports Home/End key navigation
298
+ * - Supports Home/End key navigation to first/last items
299
+ * - Page Up/Page Down for faster scrolling
300
+ * - Proper ARIA role as listbox
301
+ * - Screen reader announcements for list changes
195
302
  *
196
303
  * @since 1.0.0
197
304
  */
@@ -200,9 +307,14 @@ declare function CommandList({ className, ...props }: React.ComponentProps<typeo
200
307
  * CommandEmpty - Empty state message for command menu
201
308
  *
202
309
  * Displays when no command items match the current search query.
203
- * Can contain custom content beyond simple text messages.
310
+ * Can contain custom content beyond simple text messages. Automatically
311
+ * shows/hides based on filtered results and announces changes to screen readers.
312
+ *
313
+ * Supports dynamic content using the `useCommandState` hook to access current
314
+ * search term and create contextual empty messages.
315
+ *
316
+ * @param className - Additional CSS classes
204
317
  *
205
- * @component
206
318
  * @example
207
319
  * ```tsx
208
320
  * <CommandList>
@@ -224,20 +336,44 @@ declare function CommandList({ className, ...props }: React.ComponentProps<typeo
224
336
  * </CommandEmpty>
225
337
  * ```
226
338
  *
339
+ * @example
340
+ * ```tsx
341
+ * // Dynamic empty message with search term
342
+ * function DynamicEmpty() {
343
+ * const search = useCommandState((state) => state.search);
344
+ * return (
345
+ * <CommandEmpty>
346
+ * {search ? `No results found for "${search}".` : 'Start typing to search...'}
347
+ * </CommandEmpty>
348
+ * );
349
+ * }
350
+ * ```
351
+ *
227
352
  * @accessibility
228
353
  * - Announced to screen readers when no results are found
229
- * - Content is properly focusable if interactive
354
+ * - Content is properly focusable if interactive elements are included
355
+ * - Live region updates when search state changes
356
+ * - Proper semantic markup for empty state content
230
357
  *
358
+ * @see {@link useCommandState} - Hook for accessing search state
231
359
  * @since 1.0.0
232
360
  */
233
361
  declare function CommandEmpty({ ...props }: React.ComponentProps<typeof CommandPrimitive.Empty>): import("react/jsx-runtime").JSX.Element;
234
362
  /**
235
363
  * CommandGroup - Groups related command items under a heading
236
364
  *
237
- * Organizes command items into labeled sections for better organization
238
- * and navigation. Groups provide semantic structure for screen readers.
365
+ * Organizes command items into labeled sections with optional headings for better
366
+ * organization and navigation. Groups provide semantic structure for screen readers
367
+ * and can be hidden/shown based on whether they contain matching items.
368
+ *
369
+ * Groups automatically manage their visibility - if all contained items are filtered
370
+ * out, the entire group is hidden. Use `forceMount` to override this behavior.
371
+ *
372
+ * @param heading - The group heading text or component displayed above items
373
+ * @param value - Group identifier for programmatic control
374
+ * @param forceMount - Whether to always render the group even when hidden @default false
375
+ * @param className - Additional CSS classes
239
376
  *
240
- * @component
241
377
  * @example
242
378
  * ```tsx
243
379
  * <CommandGroup heading="Recent Files">
@@ -250,12 +386,35 @@ declare function CommandEmpty({ ...props }: React.ComponentProps<typeof CommandP
250
386
  * </CommandGroup>
251
387
  * ```
252
388
  *
253
- * @param heading - The group heading text displayed above items
389
+ * @example
390
+ * ```tsx
391
+ * // Group with custom heading component
392
+ * <CommandGroup
393
+ * heading={
394
+ * <div className="flex items-center gap-2">
395
+ * <FolderIcon className="h-4 w-4" />
396
+ * <span>Projects</span>
397
+ * </div>
398
+ * }
399
+ * >
400
+ * <CommandItem>Project A</CommandItem>
401
+ * <CommandItem>Project B</CommandItem>
402
+ * </CommandGroup>
403
+ * ```
404
+ *
405
+ * @example
406
+ * ```tsx
407
+ * // Group that always shows even when filtered
408
+ * <CommandGroup heading="Important" forceMount>
409
+ * <CommandItem>Critical Action</CommandItem>
410
+ * </CommandGroup>
411
+ * ```
254
412
  *
255
413
  * @accessibility
256
414
  * - Group headings are announced to screen readers
257
- * - Provides semantic grouping for better navigation
415
+ * - Provides semantic grouping with proper ARIA roles
258
416
  * - Maintains keyboard navigation flow between groups
417
+ * - Groups are properly labeled for assistive technology
259
418
  *
260
419
  * @since 1.0.0
261
420
  */
@@ -264,9 +423,15 @@ declare function CommandGroup({ className, ...props }: React.ComponentProps<type
264
423
  * CommandSeparator - Visual separator between command groups
265
424
  *
266
425
  * Provides visual separation between different sections of commands.
267
- * Purely decorative element that improves visual organization.
426
+ * Purely decorative element that improves visual organization and hierarchy.
427
+ * Automatically hides when adjacent groups are filtered out.
428
+ *
429
+ * The separator will only render when it has visible content before and after it,
430
+ * unless `alwaysRender` is true.
431
+ *
432
+ * @param alwaysRender - Whether to always show separator regardless of context @default false
433
+ * @param className - Additional CSS classes
268
434
  *
269
- * @component
270
435
  * @example
271
436
  * ```tsx
272
437
  * <CommandGroup heading="Recent">...</CommandGroup>
@@ -274,9 +439,18 @@ declare function CommandGroup({ className, ...props }: React.ComponentProps<type
274
439
  * <CommandGroup heading="Actions">...</CommandGroup>
275
440
  * ```
276
441
  *
442
+ * @example
443
+ * ```tsx
444
+ * // Separator that always renders
445
+ * <CommandGroup heading="Primary">...</CommandGroup>
446
+ * <CommandSeparator alwaysRender />
447
+ * <CommandGroup heading="Secondary">...</CommandGroup>
448
+ * ```
449
+ *
277
450
  * @accessibility
278
- * - Decorative element, properly hidden from screen readers
451
+ * - Decorative element, properly hidden from screen readers with aria-hidden
279
452
  * - Does not interfere with keyboard navigation
453
+ * - No focusable content or semantic meaning
280
454
  *
281
455
  * @since 1.0.0
282
456
  */
@@ -284,10 +458,20 @@ declare function CommandSeparator({ className, ...props }: React.ComponentProps<
284
458
  /**
285
459
  * CommandItem - Individual selectable command item
286
460
  *
287
- * Represents a single command or action that can be selected via
288
- * keyboard or mouse interaction. Supports icons, text, and shortcuts.
461
+ * Represents a single command or action that can be selected via keyboard or mouse
462
+ * interaction. Supports icons, text, shortcuts, and advanced filtering with keywords.
463
+ * Items can be disabled, have custom values for filtering, and trigger callbacks on selection.
464
+ *
465
+ * The item's value is used for filtering - if not provided, it defaults to the text content.
466
+ * Keywords can be added to improve search matching without affecting the display.
467
+ *
468
+ * @param value - Unique identifier for filtering and selection (defaults to text content)
469
+ * @param keywords - Additional search terms for improved filtering
470
+ * @param disabled - Disables interaction and selection @default false
471
+ * @param onSelect - Callback fired when item is selected with Enter or click
472
+ * @param forceMount - Always render even when filtered out @default false
473
+ * @param className - Additional CSS classes
289
474
  *
290
- * @component
291
475
  * @example
292
476
  * ```tsx
293
477
  * // Basic command item
@@ -306,15 +490,33 @@ declare function CommandSeparator({ className, ...props }: React.ComponentProps<
306
490
  * </CommandItem>
307
491
  * ```
308
492
  *
309
- * @param value - Unique identifier for the item (used for filtering)
310
- * @param onSelect - Callback when item is selected
311
- * @param disabled - Whether the item is disabled
493
+ * @example
494
+ * ```tsx
495
+ * // Item with keywords for better search
496
+ * <CommandItem
497
+ * value="apple"
498
+ * keywords={['fruit', 'red', 'healthy']}
499
+ * onSelect={() => selectFruit('apple')}
500
+ * >
501
+ * 🍎 Apple
502
+ * </CommandItem>
503
+ * ```
504
+ *
505
+ * @example
506
+ * ```tsx
507
+ * // Disabled item that shows but cannot be selected
508
+ * <CommandItem disabled>
509
+ * <LockIcon className="mr-2 h-4 w-4" />
510
+ * Premium Feature
511
+ * </CommandItem>
512
+ * ```
312
513
  *
313
514
  * @accessibility
314
515
  * - Keyboard selectable with Enter key and arrow navigation
315
- * - Visual highlight on focus and hover states
516
+ * - Visual highlight on focus and hover states with proper contrast
316
517
  * - Supports disabled state with proper ARIA attributes
317
- * - Screen reader announces item content and state
518
+ * - Screen reader announces item content, state, and shortcuts
519
+ * - Maintains focus within list boundaries
318
520
  *
319
521
  * @since 1.0.0
320
522
  */
@@ -322,10 +524,15 @@ declare function CommandItem({ className, ...props }: React.ComponentProps<typeo
322
524
  /**
323
525
  * CommandShortcut - Displays keyboard shortcut for command items
324
526
  *
325
- * Shows the keyboard shortcut associated with a command item,
326
- * typically displayed on the right side. Supports platform-specific shortcuts.
527
+ * Shows the keyboard shortcut associated with a command item, typically displayed
528
+ * on the right side with proper spacing. Supports platform-specific shortcuts and
529
+ * complex key combinations with consistent formatting.
530
+ *
531
+ * The component uses monospace-style formatting with appropriate opacity and spacing
532
+ * to clearly indicate keyboard shortcuts without overwhelming the item content.
533
+ *
534
+ * @param className - Additional CSS classes
327
535
  *
328
- * @component
329
536
  * @example
330
537
  * ```tsx
331
538
  * <CommandItem>
@@ -343,13 +550,75 @@ declare function CommandItem({ className, ...props }: React.ComponentProps<typeo
343
550
  * </CommandItem>
344
551
  * ```
345
552
  *
553
+ * @example
554
+ * ```tsx
555
+ * // Platform-specific shortcuts
556
+ * <CommandItem>
557
+ * Copy
558
+ * <CommandShortcut>{isMac ? '⌘C' : 'Ctrl+C'}</CommandShortcut>
559
+ * </CommandItem>
560
+ * ```
561
+ *
562
+ * @example
563
+ * ```tsx
564
+ * // Complex shortcuts with modifiers
565
+ * <CommandItem>
566
+ * Open Command Palette
567
+ * <CommandShortcut>⌘⇧P</CommandShortcut>
568
+ * </CommandItem>
569
+ * ```
570
+ *
346
571
  * @accessibility
347
572
  * - Semantically associated with its command item
348
573
  * - Announced to screen readers as part of item description
349
- * - Uses proper keyboard shortcut formatting
574
+ * - Uses proper keyboard shortcut formatting and labeling
575
+ * - Maintains readability with appropriate contrast
350
576
  *
351
577
  * @since 1.0.0
352
578
  */
353
579
  declare function CommandShortcut({ className, ...props }: React.ComponentProps<"span">): import("react/jsx-runtime").JSX.Element;
354
- export { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandShortcut, CommandSeparator, };
580
+ /**
581
+ * CommandLoading - Loading state indicator for command menu
582
+ *
583
+ * Displays a loading message while command items are being fetched asynchronously.
584
+ * Should be conditionally rendered based on loading state. Shares the same styling
585
+ * and behavior as CommandEmpty but indicates active loading rather than empty state.
586
+ *
587
+ * @param className - Additional CSS classes
588
+ *
589
+ * @example
590
+ * ```tsx
591
+ * const [loading, setLoading] = useState(false);
592
+ * const [items, setItems] = useState([]);
593
+ *
594
+ * <CommandList>
595
+ * {loading && <CommandLoading>Fetching commands...</CommandLoading>}
596
+ * {items.map(item => (
597
+ * <CommandItem key={item.id} value={item.id}>
598
+ * {item.name}
599
+ * </CommandItem>
600
+ * ))}
601
+ * </CommandList>
602
+ * ```
603
+ *
604
+ * @example
605
+ * ```tsx
606
+ * // With custom loading indicator
607
+ * <CommandLoading>
608
+ * <div className="flex items-center justify-center py-6">
609
+ * <Spinner className="mr-2 h-4 w-4" />
610
+ * <span>Loading commands...</span>
611
+ * </div>
612
+ * </CommandLoading>
613
+ * ```
614
+ *
615
+ * @accessibility
616
+ * - Announced to screen readers as loading state
617
+ * - Uses appropriate ARIA live region for status updates
618
+ * - Provides context for users while waiting for results
619
+ *
620
+ * @since 1.0.0
621
+ */
622
+ declare function CommandLoading({ ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
623
+ export { Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandShortcut, CommandSeparator, CommandLoading, useCommandState, };
355
624
  //# sourceMappingURL=command.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/components/ui/command.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,MAAM,CAAC;AAInD,OAAO,EACL,MAAM,EAKP,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,iBAAS,OAAO,CAAC,EACf,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,2CAW/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,iBAAS,aAAa,CAAC,EACrB,KAAyB,EACzB,WAA8C,EAC9C,QAAQ,EACR,SAAS,EACT,eAAsB,EACtB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,MAAM,CAAC,GAAG;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,2CAiBA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,iBAAS,YAAY,CAAC,EACpB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,KAAK,CAAC,2CAiBrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,IAAI,CAAC,2CAWpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,iBAAS,YAAY,CAAC,EACpB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,KAAK,CAAC,2CAQrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iBAAS,YAAY,CAAC,EACpB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,KAAK,CAAC,2CAWrD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,gBAAgB,CAAC,EACxB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,SAAS,CAAC,2CAQzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,gBAAgB,CAAC,IAAI,CAAC,2CAWpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,iBAAS,eAAe,CAAC,EACvB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,2CAW9B;AAED,OAAO,EACL,OAAO,EACP,aAAa,EACb,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EACf,gBAAgB,GACjB,CAAC"}
1
+ {"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/components/ui/command.tsx"],"names":[],"mappings":"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"}