@slipstream-ui/core 0.3.0 → 0.4.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 (128) hide show
  1. package/dist/index.d.mts +672 -52
  2. package/dist/index.d.ts +672 -52
  3. package/dist/index.js +1860 -657
  4. package/dist/index.js.map +1 -1
  5. package/dist/index.mjs +1836 -655
  6. package/dist/index.mjs.map +1 -1
  7. package/dist/manifests/app-shell.manifest.json +156 -0
  8. package/dist/manifests/auth-layout.manifest.json +99 -0
  9. package/dist/manifests/autocomplete.manifest.json +53 -5
  10. package/dist/manifests/badge.manifest.json +12 -0
  11. package/dist/manifests/button.manifest.json +6 -2
  12. package/dist/manifests/card.manifest.json +53 -6
  13. package/dist/manifests/date-picker.manifest.json +87 -0
  14. package/dist/manifests/dialog.manifest.json +49 -4
  15. package/dist/manifests/drawer.manifest.json +18 -4
  16. package/dist/manifests/empty-state.manifest.json +108 -0
  17. package/dist/manifests/file-upload.manifest.json +103 -0
  18. package/dist/manifests/filter-bar.manifest.json +100 -0
  19. package/dist/manifests/menu.manifest.json +13 -1
  20. package/dist/manifests/metric-card.manifest.json +105 -0
  21. package/dist/manifests/page-header.manifest.json +94 -0
  22. package/dist/manifests/pagination.manifest.json +62 -34
  23. package/dist/manifests/password-input.manifest.json +75 -0
  24. package/dist/manifests/select-menu.manifest.json +142 -0
  25. package/dist/manifests/select.manifest.json +49 -12
  26. package/dist/manifests/stepper.manifest.json +95 -0
  27. package/dist/manifests/table-card.manifest.json +123 -0
  28. package/dist/manifests/time-picker.manifest.json +86 -0
  29. package/dist/manifests/timeline.manifest.json +69 -0
  30. package/dist/manifests/toast.manifest.json +101 -25
  31. package/package.json +1 -1
  32. package/src/components/app-shell/AppShell.test.tsx +100 -0
  33. package/src/components/app-shell/AppShell.tsx +162 -0
  34. package/src/components/app-shell/index.ts +1 -0
  35. package/src/components/auth-layout/AuthLayout.test.tsx +34 -0
  36. package/src/components/auth-layout/AuthLayout.tsx +47 -0
  37. package/src/components/auth-layout/index.ts +1 -0
  38. package/src/components/autocomplete/Autocomplete.test.tsx +53 -0
  39. package/src/components/autocomplete/Autocomplete.tsx +160 -41
  40. package/src/components/badge/Badge.test.tsx +14 -0
  41. package/src/components/badge/Badge.tsx +10 -4
  42. package/src/components/button/Button.test.tsx +29 -0
  43. package/src/components/button/Button.tsx +10 -0
  44. package/src/components/button-group/ButtonGroup.test.tsx +6 -8
  45. package/src/components/button-group/ButtonGroup.tsx +17 -9
  46. package/src/components/card/Card.test.tsx +14 -0
  47. package/src/components/card/Card.tsx +15 -8
  48. package/src/components/date-picker/DatePicker.test.tsx +30 -0
  49. package/src/components/date-picker/DatePicker.tsx +57 -0
  50. package/src/components/date-picker/index.ts +1 -0
  51. package/src/components/dialog/Dialog.test.tsx +64 -1
  52. package/src/components/dialog/Dialog.tsx +113 -23
  53. package/src/components/dialog/index.ts +1 -2
  54. package/src/components/drawer/Drawer.test.tsx +50 -0
  55. package/src/components/drawer/Drawer.tsx +44 -6
  56. package/src/components/empty-state/EmptyState.test.tsx +30 -0
  57. package/src/components/empty-state/EmptyState.tsx +48 -0
  58. package/src/components/empty-state/index.ts +1 -0
  59. package/src/components/file-upload/FileUpload.test.tsx +43 -0
  60. package/src/components/file-upload/FileUpload.tsx +143 -0
  61. package/src/components/file-upload/index.ts +1 -0
  62. package/src/components/filter-bar/FilterBar.test.tsx +32 -0
  63. package/src/components/filter-bar/FilterBar.tsx +71 -0
  64. package/src/components/filter-bar/index.ts +1 -0
  65. package/src/components/input-group/InputGroup.test.tsx +6 -3
  66. package/src/components/input-group/InputGroup.tsx +9 -6
  67. package/src/components/menu/Menu.test.tsx +21 -0
  68. package/src/components/menu/Menu.tsx +8 -3
  69. package/src/components/metric-card/MetricCard.test.tsx +28 -0
  70. package/src/components/metric-card/MetricCard.tsx +54 -0
  71. package/src/components/metric-card/index.ts +1 -0
  72. package/src/components/page-header/PageHeader.test.tsx +31 -0
  73. package/src/components/page-header/PageHeader.tsx +37 -0
  74. package/src/components/page-header/index.ts +1 -0
  75. package/src/components/pagination/Pagination.test.tsx +25 -0
  76. package/src/components/pagination/Pagination.tsx +53 -12
  77. package/src/components/password-input/PasswordInput.test.tsx +29 -0
  78. package/src/components/password-input/PasswordInput.tsx +41 -0
  79. package/src/components/password-input/index.ts +1 -0
  80. package/src/components/select/Select.test.tsx +40 -1
  81. package/src/components/select/Select.tsx +52 -14
  82. package/src/components/select/index.ts +1 -1
  83. package/src/components/select-menu/SelectMenu.test.tsx +105 -0
  84. package/src/components/select-menu/SelectMenu.tsx +368 -0
  85. package/src/components/select-menu/index.ts +1 -0
  86. package/src/components/stepper/Stepper.test.tsx +35 -0
  87. package/src/components/stepper/Stepper.tsx +91 -0
  88. package/src/components/stepper/index.ts +1 -0
  89. package/src/components/table-card/TableCard.test.tsx +59 -0
  90. package/src/components/table-card/TableCard.tsx +48 -0
  91. package/src/components/table-card/index.ts +1 -0
  92. package/src/components/time-picker/TimePicker.test.tsx +30 -0
  93. package/src/components/time-picker/TimePicker.tsx +56 -0
  94. package/src/components/time-picker/index.ts +1 -0
  95. package/src/components/timeline/Timeline.test.tsx +26 -0
  96. package/src/components/timeline/Timeline.tsx +53 -0
  97. package/src/components/timeline/index.ts +1 -0
  98. package/src/components/toast/Toast.test.tsx +5 -0
  99. package/src/components/toast/Toast.tsx +2 -16
  100. package/src/components/toast/Toaster.test.tsx +84 -0
  101. package/src/components/toast/Toaster.tsx +116 -0
  102. package/src/components/toast/index.ts +4 -0
  103. package/src/components/toast/toast-store.ts +117 -0
  104. package/src/index.ts +14 -0
  105. package/src/manifests/app-shell.manifest.json +156 -0
  106. package/src/manifests/auth-layout.manifest.json +99 -0
  107. package/src/manifests/autocomplete.manifest.json +53 -5
  108. package/src/manifests/badge.manifest.json +12 -0
  109. package/src/manifests/button.manifest.json +6 -2
  110. package/src/manifests/card.manifest.json +53 -6
  111. package/src/manifests/date-picker.manifest.json +87 -0
  112. package/src/manifests/dialog.manifest.json +49 -4
  113. package/src/manifests/drawer.manifest.json +18 -4
  114. package/src/manifests/empty-state.manifest.json +108 -0
  115. package/src/manifests/file-upload.manifest.json +103 -0
  116. package/src/manifests/filter-bar.manifest.json +100 -0
  117. package/src/manifests/menu.manifest.json +13 -1
  118. package/src/manifests/metric-card.manifest.json +105 -0
  119. package/src/manifests/page-header.manifest.json +94 -0
  120. package/src/manifests/pagination.manifest.json +62 -34
  121. package/src/manifests/password-input.manifest.json +75 -0
  122. package/src/manifests/select-menu.manifest.json +142 -0
  123. package/src/manifests/select.manifest.json +49 -12
  124. package/src/manifests/stepper.manifest.json +95 -0
  125. package/src/manifests/table-card.manifest.json +123 -0
  126. package/src/manifests/time-picker.manifest.json +86 -0
  127. package/src/manifests/timeline.manifest.json +69 -0
  128. package/src/manifests/toast.manifest.json +101 -25
package/dist/index.d.mts CHANGED
@@ -155,15 +155,64 @@ declare function usePresence(open: boolean, animate: boolean, exitMs?: number):
155
155
  exiting: boolean;
156
156
  };
157
157
 
158
+ type SidebarItem = {
159
+ href: string;
160
+ label: string;
161
+ icon?: React.ReactNode;
162
+ /** Trailing slot — count, status dot, shortcut. */
163
+ badge?: React.ReactNode;
164
+ /** Force the active state (otherwise activeHref is compared). */
165
+ active?: boolean;
166
+ };
167
+ type SidebarSection = {
168
+ title?: string;
169
+ items: SidebarItem[];
170
+ };
171
+ type SidebarProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
172
+ sections: SidebarSection[];
173
+ /** Brand/mark rendered at the top. */
174
+ heading?: React.ReactNode;
175
+ /** Rendered at the bottom (user menu, upgrade CTA). */
176
+ footer?: React.ReactNode;
177
+ /** Current route — items with a matching href get aria-current="page". */
178
+ activeHref?: string;
179
+ /** Custom link element for routers (react-router `Link`, Next `Link`). */
180
+ linkComponent?: React.ElementType;
181
+ /** Accessible name of the nav landmark. Default 'Primary'. */
182
+ label?: string;
183
+ };
184
+ /**
185
+ * Sectioned navigation rail. Purely presentational: you pass the active
186
+ * route and a router link component, so it stays stateless and works with
187
+ * any routing library.
188
+ */
189
+ declare function Sidebar({ sections, heading, footer, activeHref, linkComponent, label, className, ...props }: SidebarProps): React.JSX.Element;
190
+ type AppShellProps = React.HTMLAttributes<HTMLDivElement> & {
191
+ /** Desktop rail; also rendered inside a mobile drawer. */
192
+ sidebar?: React.ReactNode;
193
+ /** Sticky top bar content. */
194
+ header?: React.ReactNode;
195
+ /** Hide the built-in mobile menu button (e.g. when the header owns one). */
196
+ hideMobileMenu?: boolean;
197
+ /** Tailwind width class for the desktop rail. Default 'w-64'. */
198
+ sidebarWidth?: string;
199
+ };
200
+ /**
201
+ * Application frame: fixed-height sidebar, sticky header, scrolling main.
202
+ * On small screens the sidebar becomes a left Drawer opened by a burger
203
+ * button, so pages never need their own responsive nav wiring.
204
+ */
205
+ declare function AppShell({ sidebar, header, hideMobileMenu, sidebarWidth, className, children, ...props }: AppShellProps): React.JSX.Element;
206
+
158
207
  declare const buttonVariants: (props?: ({
159
- variant?: "default" | "destructive" | "success" | "warning" | "info" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
208
+ variant?: "link" | "default" | "destructive" | "success" | "warning" | "info" | "outline" | "outline-destructive" | "outline-success" | "outline-warning" | "outline-info" | "secondary" | "ghost" | null | undefined;
160
209
  size?: "sm" | "lg" | "default" | "icon" | null | undefined;
161
210
  } & class_variance_authority_types.ClassProp) | undefined) => string;
162
211
  type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof buttonVariants> & {
163
212
  asChild?: boolean;
164
213
  };
165
214
  declare const Button: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<(props?: ({
166
- variant?: "default" | "destructive" | "success" | "warning" | "info" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
215
+ variant?: "link" | "default" | "destructive" | "success" | "warning" | "info" | "outline" | "outline-destructive" | "outline-success" | "outline-warning" | "outline-info" | "secondary" | "ghost" | null | undefined;
167
216
  size?: "sm" | "lg" | "default" | "icon" | null | undefined;
168
217
  } & class_variance_authority_types.ClassProp) | undefined) => string> & {
169
218
  asChild?: boolean;
@@ -174,11 +223,16 @@ type ButtonGroupProps = React.HTMLAttributes<HTMLDivElement> & {
174
223
  orientation?: 'horizontal' | 'vertical';
175
224
  };
176
225
  /**
177
- * Joins buttons into one segmented control: adjacent borders collapse
178
- * (negative spacing), middle corners square off, and only the outer
179
- * corners stay rounded — a single outline around the whole group.
180
- * Use border-bearing variants (default/outline/secondary); ghost
181
- * buttons have no border and would break the joined outline.
226
+ * Joins buttons into one segmented control.
227
+ *
228
+ * The group owns the outline: a single border, one outer radius (children
229
+ * are clipped by overflow-hidden), and 1px separators drawn between
230
+ * segments. Children lose their own borders and radii, so mixed variants
231
+ * (default/outline/secondary/ghost) still read as one instrument — a
232
+ * borderless variant no longer leaves the seam misaligned the way
233
+ * negative-margin border collapsing did.
234
+ *
235
+ * Focus rings render inset so they are never clipped at the edges.
182
236
  */
183
237
  declare const ButtonGroup: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
184
238
  /** Stacked segments share vertical edges (default: side-by-side). */
@@ -221,10 +275,16 @@ declare const InputGroupAddon: React.ForwardRefExoticComponent<React.HTMLAttribu
221
275
  declare const badgeVariants: (props?: ({
222
276
  variant?: "default" | "destructive" | "outline" | "secondary" | null | undefined;
223
277
  } & class_variance_authority_types.ClassProp) | undefined) => string;
224
- type BadgeProps = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof badgeVariants>;
278
+ type BadgeProps = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof badgeVariants> & {
279
+ /** Render the child element (e.g. a router Link) with badge styling. */
280
+ asChild?: boolean;
281
+ };
225
282
  declare const Badge: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
226
283
  variant?: "default" | "destructive" | "outline" | "secondary" | null | undefined;
227
- } & class_variance_authority_types.ClassProp) | undefined) => string> & React.RefAttributes<HTMLDivElement>>;
284
+ } & class_variance_authority_types.ClassProp) | undefined) => string> & {
285
+ /** Render the child element (e.g. a router Link) with badge styling. */
286
+ asChild?: boolean;
287
+ } & React.RefAttributes<HTMLDivElement>>;
228
288
 
229
289
  declare const Avatar: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarProps & React.RefAttributes<HTMLSpanElement>, "ref"> & React.RefAttributes<HTMLSpanElement>>;
230
290
  declare const AvatarImage: React.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarImageProps & React.RefAttributes<HTMLImageElement>, "ref"> & React.RefAttributes<HTMLImageElement>>;
@@ -239,6 +299,15 @@ type SpinnerProps = React.HTMLAttributes<HTMLSpanElement> & VariantProps<typeof
239
299
  };
240
300
  declare function Spinner({ className, size, label, ...props }: SpinnerProps): React.JSX.Element;
241
301
 
302
+ /**
303
+ * Imperative toast store.
304
+ *
305
+ * Components can call `toast(...)` from anywhere — event handlers, data
306
+ * layers, async catch blocks — without threading a hook through the tree.
307
+ * `<Toaster />` subscribes to this store and renders the queue. The
308
+ * provider/hook API in Toast.tsx remains for tree-scoped usage.
309
+ */
310
+ type ToastVariant = 'default' | 'success' | 'error' | 'warning' | 'info';
242
311
  type ToastAction = {
243
312
  label: string;
244
313
  onClick: () => void;
@@ -247,12 +316,31 @@ type ToastOptions = {
247
316
  title: string;
248
317
  description?: string;
249
318
  action?: ToastAction;
319
+ variant?: ToastVariant;
250
320
  /** Auto-dismiss delay in ms; 0 keeps the toast until dismissed. Default 5000. */
251
321
  duration?: number;
252
322
  };
253
323
  type ToastRecord = ToastOptions & {
254
324
  id: string;
255
325
  };
326
+ type ToastFunction = ((options: ToastOptions) => string) & {
327
+ success: (title: string, description?: string) => string;
328
+ error: (title: string, description?: string) => string;
329
+ warning: (title: string, description?: string) => string;
330
+ info: (title: string, description?: string) => string;
331
+ dismiss: (id?: string) => void;
332
+ clear: () => void;
333
+ };
334
+ /**
335
+ * Fire a toast from anywhere. Variant helpers mirror the sonner/Radix
336
+ * shape most codebases already call:
337
+ *
338
+ * toast.success('Saved')
339
+ * toast.error('Upload failed', 'Check your connection')
340
+ * toast({ title: 'Heads up', duration: 0 })
341
+ */
342
+ declare const toast: ToastFunction;
343
+
256
344
  type ToastContextValue = {
257
345
  toasts: ToastRecord[];
258
346
  toast: (options: ToastOptions) => string;
@@ -269,17 +357,52 @@ declare function ToastProvider({ children, label }: {
269
357
  }): React.JSX.Element;
270
358
  declare function useToast(): ToastContextValue;
271
359
 
360
+ type ToasterPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
361
+ type ToasterProps = {
362
+ /** Corner/edge the stack renders at. Default 'bottom-right'. */
363
+ position?: ToasterPosition;
364
+ /** Accessible name of the live region. Default 'Notifications'. */
365
+ label?: string;
366
+ /** Tint the toast surface with its status color (neutral by default). */
367
+ richColors?: boolean;
368
+ };
369
+ /**
370
+ * Renders the imperative toast queue. Mount once near the app root:
371
+ *
372
+ * <Toaster />
373
+ * toast.success('Saved')
374
+ *
375
+ * The region is a polite live region, so announcements don't steal focus.
376
+ */
377
+ declare function Toaster({ position, label, richColors }: ToasterProps): React.JSX.Element;
378
+
379
+ type DialogSize = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
272
380
  type DialogProps = {
273
381
  open: boolean;
274
382
  onOpenChange: (open: boolean) => void;
275
- title: string;
383
+ /** Accessible name + default header title. Optional when composing a custom header. */
384
+ title?: string;
276
385
  description?: string;
277
386
  children?: React.ReactNode;
387
+ /** Panel max-width preset (default 'md'). */
388
+ size?: DialogSize;
389
+ /**
390
+ * Replaces the default header row. Compose with `<DialogHeader>` /
391
+ * `<DialogTitle>` / `<DialogDescription>` — those parts pick up the
392
+ * dialog's aria ids automatically.
393
+ */
394
+ header?: React.ReactNode;
395
+ /** Action row pinned under the body. */
396
+ footer?: React.ReactNode;
397
+ /** Cap the body height and scroll inside the panel. */
398
+ scrollable?: boolean;
399
+ bodyClassName?: string;
278
400
  closeOnBackdrop?: boolean;
279
401
  /** Hide the close (✕) button in the header; Escape and backdrop still close. */
280
402
  showClose?: boolean;
281
403
  /** Focused when the dialog opens; defaults to the first focusable element. */
282
404
  initialFocusRef?: React.RefObject<HTMLElement | null>;
405
+ /** Accessible name when `title` is omitted (required with a custom header). */
283
406
  ariaLabel?: string;
284
407
  /**
285
408
  * Fade the backdrop and panel in on open and out on close (requires
@@ -288,15 +411,34 @@ type DialogProps = {
288
411
  */
289
412
  animate?: boolean;
290
413
  };
414
+ type DialogHeaderProps = React.HTMLAttributes<HTMLDivElement>;
415
+ /** Header row for composed dialogs. */
416
+ declare function DialogHeader({ className, ...props }: DialogHeaderProps): React.JSX.Element;
417
+ type DialogTitleProps = React.HTMLAttributes<HTMLHeadingElement>;
418
+ /** Dialog heading; automatically wired to aria-labelledby. */
419
+ declare function DialogTitle({ className, ...props }: DialogTitleProps): React.JSX.Element;
420
+ type DialogDescriptionProps = React.HTMLAttributes<HTMLParagraphElement>;
421
+ /** Supporting line; automatically wired to aria-describedby. */
422
+ declare function DialogDescription({ className, ...props }: DialogDescriptionProps): React.JSX.Element;
423
+ type DialogBodyProps = React.HTMLAttributes<HTMLDivElement>;
424
+ /** Body wrapper for composed dialogs. */
425
+ declare function DialogBody({ className, ...props }: DialogBodyProps): React.JSX.Element;
426
+ type DialogFooterProps = React.HTMLAttributes<HTMLDivElement>;
427
+ /** Action row pinned to the bottom of the panel. */
428
+ declare function DialogFooter({ className, ...props }: DialogFooterProps): React.JSX.Element;
291
429
  /**
292
430
  * Accessible modal dialog: portal, aria-modal + labelled/describedby wiring,
293
431
  * Escape and backdrop dismissal, initial focus on open and focus restoration
294
432
  * on close, plus a Tab/Shift+Tab focus trap.
433
+ *
434
+ * Use `title`/`description` for the default header, or pass `header` with
435
+ * `<DialogHeader>`/`<DialogTitle>`/`<DialogDescription>` (and an
436
+ * `ariaLabel` fallback) for full control.
295
437
  */
296
- declare function Dialog({ open, onOpenChange, title, description, children, closeOnBackdrop, showClose, initialFocusRef, animate, }: DialogProps): React.ReactPortal | null;
438
+ declare function Dialog({ open, onOpenChange, title, description, children, size, header, footer, scrollable, bodyClassName, closeOnBackdrop, showClose, initialFocusRef, ariaLabel, animate, }: DialogProps): React.ReactPortal | null;
297
439
 
298
440
  type DrawerSide = 'left' | 'right' | 'top' | 'bottom';
299
- type DrawerSize = 'sm' | 'md' | 'lg';
441
+ type DrawerSize = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
300
442
  type DrawerProps = {
301
443
  open: boolean;
302
444
  onOpenChange: (open: boolean) => void;
@@ -305,8 +447,18 @@ type DrawerProps = {
305
447
  children?: React.ReactNode;
306
448
  /** Edge the drawer slides from (default 'right'). */
307
449
  side?: DrawerSide;
308
- /** Extent along the side axis (width for left/right, height for top/bottom). */
450
+ /** Preset extent along the side axis (width for left/right, height for top/bottom). */
309
451
  size?: DrawerSize;
452
+ /**
453
+ * Custom extent for left/right drawers: pixels (480) or any CSS length
454
+ * ("70vw"). Overrides `size`.
455
+ */
456
+ width?: number | string;
457
+ /**
458
+ * Custom extent for top/bottom drawers: pixels (320) or any CSS length
459
+ * ("60vh"). Overrides `size`.
460
+ */
461
+ height?: number | string;
310
462
  /** Clicking the backdrop closes (default true). */
311
463
  closeOnBackdrop?: boolean;
312
464
  /** Hide the close (✕) button in the header (default true). */
@@ -329,34 +481,145 @@ type DrawerProps = {
329
481
  * restoration on close. Renders fixed to the chosen edge with a border
330
482
  * against the backdrop.
331
483
  */
332
- declare function Drawer({ open, onOpenChange, title, description, children, side, size, closeOnBackdrop, showClose, initialFocusRef, ariaLabel, animate, }: DrawerProps): React.ReactPortal | null;
484
+ declare function Drawer({ open, onOpenChange, title, description, children, side, size, width, height, closeOnBackdrop, showClose, initialFocusRef, ariaLabel, animate, }: DrawerProps): React.ReactPortal | null;
333
485
 
334
486
  type SelectOption = {
335
487
  value: string;
336
488
  label: string;
337
489
  disabled?: boolean;
338
490
  };
339
- type SelectProps = Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'onChange' | 'value' | 'defaultValue'> & {
491
+ type SelectOptionGroup = {
492
+ label: string;
340
493
  options: SelectOption[];
494
+ };
495
+ type SelectProps = Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'onChange' | 'value' | 'defaultValue' | 'multiple'> & {
496
+ /** Flat options. Ignored when `groups` is provided. */
497
+ options?: SelectOption[];
498
+ /** Optgroups with a heading per section. */
499
+ groups?: SelectOptionGroup[];
341
500
  label?: string;
342
- value?: string;
343
- defaultValue?: string;
344
- onChange?: (value: string) => void;
501
+ /** Renders a disabled empty option — the native "choose one" affordance. */
502
+ placeholder?: string;
503
+ /** Native multi-select: value/onChange switch to string[]. */
504
+ multiple?: boolean;
505
+ value?: string | string[];
506
+ defaultValue?: string | string[];
507
+ onChange?: (value: string | string[]) => void;
345
508
  };
346
509
  /**
347
510
  * Accessible select primitive built on the native <select>: full keyboard,
348
511
  * screen-reader and mobile platform behavior comes from the platform rather
349
- * than a re-implemented listbox. Controlled via `value`, or
350
- * uncontrolled via `defaultValue`.
512
+ * than a re-implemented listbox. Supports flat options, optgroups,
513
+ * placeholder rows and native multi-select (string[] contract).
351
514
  */
352
- declare const Select: React.ForwardRefExoticComponent<Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "value" | "defaultValue" | "onChange"> & {
353
- options: SelectOption[];
515
+ declare const Select: React.ForwardRefExoticComponent<Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "defaultValue" | "onChange" | "multiple" | "value"> & {
516
+ /** Flat options. Ignored when `groups` is provided. */
517
+ options?: SelectOption[];
518
+ /** Optgroups with a heading per section. */
519
+ groups?: SelectOptionGroup[];
354
520
  label?: string;
355
- value?: string;
356
- defaultValue?: string;
357
- onChange?: (value: string) => void;
521
+ /** Renders a disabled empty option — the native "choose one" affordance. */
522
+ placeholder?: string;
523
+ /** Native multi-select: value/onChange switch to string[]. */
524
+ multiple?: boolean;
525
+ value?: string | string[];
526
+ defaultValue?: string | string[];
527
+ onChange?: (value: string | string[]) => void;
358
528
  } & React.RefAttributes<HTMLSelectElement>>;
359
529
 
530
+ type TableCardProps = React.HTMLAttributes<HTMLDivElement> & {
531
+ title?: string;
532
+ description?: string;
533
+ /** Right-aligned header actions (create, export, column settings). */
534
+ actions?: React.ReactNode;
535
+ /** Row between the header and the table (filters, bulk actions). */
536
+ toolbar?: React.ReactNode;
537
+ /** Table/DataTable content. */
538
+ children: React.ReactNode;
539
+ /** Rendered under the table (pagination, summary). */
540
+ footer?: React.ReactNode;
541
+ /** Remove the inner padding so table edges reach the card border. */
542
+ flush?: boolean;
543
+ };
544
+ /**
545
+ * Table shell: title/description + actions, an optional toolbar, an
546
+ * edge-to-edge table body and a footer row. Standardizes the chrome every
547
+ * list page grows around a Table or DataTable.
548
+ */
549
+ declare const TableCard: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
550
+ title?: string;
551
+ description?: string;
552
+ /** Right-aligned header actions (create, export, column settings). */
553
+ actions?: React.ReactNode;
554
+ /** Row between the header and the table (filters, bulk actions). */
555
+ toolbar?: React.ReactNode;
556
+ /** Table/DataTable content. */
557
+ children: React.ReactNode;
558
+ /** Rendered under the table (pagination, summary). */
559
+ footer?: React.ReactNode;
560
+ /** Remove the inner padding so table edges reach the card border. */
561
+ flush?: boolean;
562
+ } & React.RefAttributes<HTMLDivElement>>;
563
+
564
+ type SelectMenuItem = {
565
+ value: string;
566
+ label: string;
567
+ /** Muted supporting line under the label. */
568
+ description?: string;
569
+ icon?: React.ReactNode;
570
+ disabled?: boolean;
571
+ /** Section heading the item renders under. */
572
+ group?: string;
573
+ };
574
+ type SelectMenuProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'value' | 'defaultValue' | 'onChange' | 'children' | 'type'> & {
575
+ items: SelectMenuItem[];
576
+ /** Selected value(s): a string, or string[] when multiple. */
577
+ value?: string | string[];
578
+ defaultValue?: string | string[];
579
+ onValueChange?: (value: string | string[]) => void;
580
+ /** Allow choosing several items (the listbox stays open). */
581
+ multiple?: boolean;
582
+ placeholder?: string;
583
+ /** Name for hidden form inputs (renders one input per selected value). */
584
+ name?: string;
585
+ /** Custom trigger content for the current selection. */
586
+ renderValue?: (selected: SelectMenuItem[]) => React.ReactNode;
587
+ /** Custom option row. */
588
+ renderItem?: (item: SelectMenuItem, state: {
589
+ selected: boolean;
590
+ active: boolean;
591
+ }) => React.ReactNode;
592
+ emptyText?: string;
593
+ };
594
+ /**
595
+ * Custom dropdown select for rich options: descriptions, icons, grouped
596
+ * headings, multi-select and custom row rendering. Unlike `Select` (native
597
+ * `<select>`), this renders a real listbox, so option content is not limited
598
+ * to text. Keyboard model follows the button/listbox pattern: arrows move the
599
+ * active option, Home/End jump, Enter/Space selects, Escape closes, and
600
+ * first-letter typeahead jumps to matching options.
601
+ */
602
+ declare const SelectMenu: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "type" | "defaultValue" | "onChange" | "value"> & {
603
+ items: SelectMenuItem[];
604
+ /** Selected value(s): a string, or string[] when multiple. */
605
+ value?: string | string[];
606
+ defaultValue?: string | string[];
607
+ onValueChange?: (value: string | string[]) => void;
608
+ /** Allow choosing several items (the listbox stays open). */
609
+ multiple?: boolean;
610
+ placeholder?: string;
611
+ /** Name for hidden form inputs (renders one input per selected value). */
612
+ name?: string;
613
+ /** Custom trigger content for the current selection. */
614
+ renderValue?: (selected: SelectMenuItem[]) => React.ReactNode;
615
+ /** Custom option row. */
616
+ renderItem?: (item: SelectMenuItem, state: {
617
+ selected: boolean;
618
+ active: boolean;
619
+ }) => React.ReactNode;
620
+ emptyText?: string;
621
+ } & React.RefAttributes<HTMLButtonElement>>;
622
+
360
623
  type SearchOption = {
361
624
  value: string;
362
625
  label: string;
@@ -441,27 +704,54 @@ type UseComboboxResult = {
441
704
  */
442
705
  declare function useCombobox({ items, onSelect, onOpenChange, closeOnSubmit, }: UseComboboxOptions): UseComboboxResult;
443
706
 
707
+ type AutocompleteOption = {
708
+ value: string;
709
+ /** Display label; defaults to the value. */
710
+ label?: string;
711
+ /** Section heading the option renders under. */
712
+ group?: string;
713
+ /** Muted supporting line under the label. */
714
+ description?: string;
715
+ };
444
716
  type AutocompleteProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'defaultValue' | 'onChange' | 'children' | 'size'> & {
445
717
  /** Current text — standard controlled-input contract. */
446
718
  value?: string;
447
719
  /** Initial text when uncontrolled. */
448
720
  defaultValue?: string;
449
- /** Fires on every keystroke AND on suggestion selection (like a native input's onChange). */
721
+ /** Fires on every keystroke AND on suggestion selection. */
450
722
  onValueChange?: (value: string) => void;
451
- /** Suggestion labels offered while typing; any value may still be entered free-form. */
452
- suggestions: string[];
453
- /** Shown when no suggestion matches (optional). */
723
+ /** Static suggestions (strings or option objects). */
724
+ options?: Array<string | AutocompleteOption>;
725
+ /** @deprecated Use `options`. */
726
+ suggestions?: string[];
727
+ /** Async source; called with the current query (debounced) when provided. */
728
+ loadOptions?: (query: string) => Promise<Array<string | AutocompleteOption>>;
729
+ /** Custom row rendering (receives the normalized option). */
730
+ renderOption?: (option: NormalizedOption, state: {
731
+ active: boolean;
732
+ }) => React.ReactNode;
733
+ /** Show a clear button once there is text. */
734
+ clearable?: boolean;
735
+ /** Shown when no option matches. */
454
736
  emptyText?: string;
737
+ /** Shown while async options load. */
738
+ loadingText?: string;
739
+ /** Debounce for `loadOptions`, in ms. Default 200. */
740
+ debounceMs?: number;
741
+ };
742
+ type NormalizedOption = {
743
+ value: string;
744
+ label: string;
745
+ group?: string;
746
+ description?: string;
455
747
  };
456
748
  /**
457
749
  * Type-ahead input following the HTML autocomplete model: users may enter
458
- * any value (free text is first-class), while matching suggestions appear
459
- * in a listbox — Arrow keys highlight, Enter accepts, Escape dismisses.
460
- * The native `autoComplete` attribute passes through (form autofill hints
461
- * keep working alongside the custom listbox). The listbox portals with
462
- * fixed positioning so scrollable containers never clip it.
750
+ * any value (free text is first-class), while matching options appear in a
751
+ * portalled listbox (grouped, optional async loading, custom rows).
752
+ * Arrow keys highlight, Enter accepts, Escape dismisses.
463
753
  */
464
- declare function Autocomplete({ value, defaultValue, onValueChange, suggestions, emptyText, placeholder, id, name, className, onKeyDown, onFocus, ...inputProps }: AutocompleteProps): React.JSX.Element;
754
+ declare function Autocomplete({ value, defaultValue, onValueChange, options, suggestions, loadOptions, renderOption, clearable, emptyText, loadingText, debounceMs, placeholder, id, name, className, onKeyDown, onFocus, ...inputProps }: AutocompleteProps): React.JSX.Element;
465
755
 
466
756
  type CheckboxProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange'> & {
467
757
  /** Controlled checked state; omit for uncontrolled usage. */
@@ -514,7 +804,7 @@ type CheckboxGroupItemProps = Omit<React.InputHTMLAttributes<HTMLInputElement>,
514
804
  label?: string;
515
805
  };
516
806
  /** A single multi-select option inside a `CheckboxGroup`. */
517
- declare const CheckboxGroupItem: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "name" | "type" | "value" | "onChange" | "checked"> & {
807
+ declare const CheckboxGroupItem: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "name" | "type" | "onChange" | "checked" | "value"> & {
518
808
  /** The value this item contributes to the selection. */
519
809
  value: string;
520
810
  /** Visible label rendered next to the checkbox. */
@@ -576,7 +866,7 @@ type RadioGroupItemProps = Omit<RadioProps, 'name' | 'checked' | 'onCheckedChang
576
866
  label?: string;
577
867
  };
578
868
  /** A single radio option inside a `RadioGroup`. */
579
- declare const RadioGroupItem: React.ForwardRefExoticComponent<Omit<RadioProps, "name" | "value" | "checked" | "onCheckedChange"> & {
869
+ declare const RadioGroupItem: React.ForwardRefExoticComponent<Omit<RadioProps, "name" | "checked" | "value" | "onCheckedChange"> & {
580
870
  /** The value this item contributes to the group. */
581
871
  value: string;
582
872
  /** Visible label rendered next to the radio. */
@@ -926,9 +1216,15 @@ type TooltipProps = {
926
1216
  */
927
1217
  declare const Tooltip: React.ForwardRefExoticComponent<TooltipProps & React.RefAttributes<HTMLDivElement>>;
928
1218
 
929
- type CardProps = React.HTMLAttributes<HTMLDivElement>;
1219
+ type CardProps = React.HTMLAttributes<HTMLDivElement> & {
1220
+ /** Render the child element (e.g. a router Link) with card styling. */
1221
+ asChild?: boolean;
1222
+ };
930
1223
  /** Content container with a subtle border and surface styling. */
931
- declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;
1224
+ declare const Card: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
1225
+ /** Render the child element (e.g. a router Link) with card styling. */
1226
+ asChild?: boolean;
1227
+ } & React.RefAttributes<HTMLDivElement>>;
932
1228
  type CardHeaderProps = React.HTMLAttributes<HTMLDivElement>;
933
1229
  /** Header section of a Card; typically contains CardTitle and CardDescription. */
934
1230
  declare const CardHeader: React.ForwardRefExoticComponent<CardHeaderProps & React.RefAttributes<HTMLDivElement>>;
@@ -1217,6 +1513,302 @@ declare const Heading: React.ForwardRefExoticComponent<React.HTMLAttributes<HTML
1217
1513
  muted?: boolean;
1218
1514
  } & React.RefAttributes<HTMLHeadingElement>>;
1219
1515
 
1516
+ type EmptyStateProps = React.HTMLAttributes<HTMLDivElement> & {
1517
+ /** Icon or illustration shown above the title. */
1518
+ icon?: React.ReactNode;
1519
+ title: string;
1520
+ description?: string;
1521
+ /** Primary action (button/link). */
1522
+ action?: React.ReactNode;
1523
+ /** Secondary action shown beside the primary one. */
1524
+ secondaryAction?: React.ReactNode;
1525
+ /** Compact padding for use inside panels and table bodies. */
1526
+ size?: 'sm' | 'md';
1527
+ };
1528
+ /**
1529
+ * Placeholder for empty collections, zero-result searches and unconfigured
1530
+ * features. Keeps the title/description/action hierarchy consistent across
1531
+ * the product.
1532
+ */
1533
+ declare const EmptyState: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
1534
+ /** Icon or illustration shown above the title. */
1535
+ icon?: React.ReactNode;
1536
+ title: string;
1537
+ description?: string;
1538
+ /** Primary action (button/link). */
1539
+ action?: React.ReactNode;
1540
+ /** Secondary action shown beside the primary one. */
1541
+ secondaryAction?: React.ReactNode;
1542
+ /** Compact padding for use inside panels and table bodies. */
1543
+ size?: "sm" | "md";
1544
+ } & React.RefAttributes<HTMLDivElement>>;
1545
+
1546
+ type PageHeaderProps = React.HTMLAttributes<HTMLDivElement> & {
1547
+ title: string;
1548
+ description?: string;
1549
+ /** Breadcrumbs/eyebrow above the title. */
1550
+ breadcrumbs?: React.ReactNode;
1551
+ /** Right-aligned actions (buttons, menus). */
1552
+ actions?: React.ReactNode;
1553
+ /** Small slot under the title row (tabs, filters). */
1554
+ children?: React.ReactNode;
1555
+ };
1556
+ /**
1557
+ * Standard page heading block: optional breadcrumbs, title, description and
1558
+ * a right-aligned action cluster. Pages stop inventing their own spacing
1559
+ * and heading hierarchy.
1560
+ */
1561
+ declare const PageHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
1562
+ title: string;
1563
+ description?: string;
1564
+ /** Breadcrumbs/eyebrow above the title. */
1565
+ breadcrumbs?: React.ReactNode;
1566
+ /** Right-aligned actions (buttons, menus). */
1567
+ actions?: React.ReactNode;
1568
+ /** Small slot under the title row (tabs, filters). */
1569
+ children?: React.ReactNode;
1570
+ } & React.RefAttributes<HTMLDivElement>>;
1571
+
1572
+ type MetricTrend = 'up' | 'down' | 'flat';
1573
+ type MetricCardProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> & {
1574
+ label: string;
1575
+ value: string | number;
1576
+ /** Secondary line under the value. */
1577
+ hint?: string;
1578
+ /** Signed change, e.g. "+12.4%" or "-3". */
1579
+ delta?: string;
1580
+ /** Direction colors the delta (green up / red down / muted flat). */
1581
+ trend?: MetricTrend;
1582
+ icon?: React.ReactNode;
1583
+ };
1584
+ /**
1585
+ * Compact KPI tile: label, value, optional delta with direction color and a
1586
+ * supporting hint. Deltas always carry an arrow glyph so the direction is
1587
+ * never communicated by color alone.
1588
+ */
1589
+ declare const MetricCard: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
1590
+ label: string;
1591
+ value: string | number;
1592
+ /** Secondary line under the value. */
1593
+ hint?: string;
1594
+ /** Signed change, e.g. "+12.4%" or "-3". */
1595
+ delta?: string;
1596
+ /** Direction colors the delta (green up / red down / muted flat). */
1597
+ trend?: MetricTrend;
1598
+ icon?: React.ReactNode;
1599
+ } & React.RefAttributes<HTMLDivElement>>;
1600
+
1601
+ type PasswordInputProps = Omit<InputProps, 'type'> & {
1602
+ /** Accessible labels for the visibility toggle. */
1603
+ showLabel?: string;
1604
+ hideLabel?: string;
1605
+ };
1606
+ /**
1607
+ * Password field with a show/hide toggle. The toggle is a real button with
1608
+ * pressed state, so keyboard and screen-reader users can reveal the value
1609
+ * without losing the focused field.
1610
+ */
1611
+ declare const PasswordInput: React.ForwardRefExoticComponent<Omit<InputProps, "type"> & {
1612
+ /** Accessible labels for the visibility toggle. */
1613
+ showLabel?: string;
1614
+ hideLabel?: string;
1615
+ } & React.RefAttributes<HTMLInputElement>>;
1616
+
1617
+ type AuthLayoutProps = React.HTMLAttributes<HTMLDivElement> & {
1618
+ title: string;
1619
+ description?: string;
1620
+ /** Brand/mark above the card. */
1621
+ brand?: React.ReactNode;
1622
+ /** Links or legal copy under the card. */
1623
+ footer?: React.ReactNode;
1624
+ /** Rendered inside the card under the heading. */
1625
+ children?: React.ReactNode;
1626
+ /** Card width preset (default 'md'). */
1627
+ size?: 'sm' | 'md' | 'lg';
1628
+ };
1629
+ /**
1630
+ * Centered auth surface: brand mark, title/description, the form card and a
1631
+ * footer slot. Keeps sign-in, sign-up, reset and verify screens visually
1632
+ * identical without each page re-deriving the layout.
1633
+ */
1634
+ declare const AuthLayout: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
1635
+ title: string;
1636
+ description?: string;
1637
+ /** Brand/mark above the card. */
1638
+ brand?: React.ReactNode;
1639
+ /** Links or legal copy under the card. */
1640
+ footer?: React.ReactNode;
1641
+ /** Rendered inside the card under the heading. */
1642
+ children?: React.ReactNode;
1643
+ /** Card width preset (default 'md'). */
1644
+ size?: "sm" | "md" | "lg";
1645
+ } & React.RefAttributes<HTMLDivElement>>;
1646
+
1647
+ type FilterBarProps = React.HTMLAttributes<HTMLDivElement> & {
1648
+ /** Controlled search text. */
1649
+ searchValue?: string;
1650
+ onSearchChange?: (value: string) => void;
1651
+ /** Search placeholder; the search box is hidden when omitted. */
1652
+ searchPlaceholder?: string;
1653
+ /** Rendered after the search box — selects, toggles, date pickers. */
1654
+ children?: React.ReactNode;
1655
+ /** Shows a reset button when provided (pass the active filter count for the label). */
1656
+ onReset?: () => void;
1657
+ activeCount?: number;
1658
+ /** Rendered at the far right (bulk actions, column settings). */
1659
+ trailing?: React.ReactNode;
1660
+ };
1661
+ /**
1662
+ * Horizontal filter strip for list pages: search field, filter controls and
1663
+ * a reset affordance. Scrolls horizontally on narrow screens instead of
1664
+ * wrapping into a tall stack.
1665
+ */
1666
+ declare const FilterBar: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
1667
+ /** Controlled search text. */
1668
+ searchValue?: string;
1669
+ onSearchChange?: (value: string) => void;
1670
+ /** Search placeholder; the search box is hidden when omitted. */
1671
+ searchPlaceholder?: string;
1672
+ /** Rendered after the search box — selects, toggles, date pickers. */
1673
+ children?: React.ReactNode;
1674
+ /** Shows a reset button when provided (pass the active filter count for the label). */
1675
+ onReset?: () => void;
1676
+ activeCount?: number;
1677
+ /** Rendered at the far right (bulk actions, column settings). */
1678
+ trailing?: React.ReactNode;
1679
+ } & React.RefAttributes<HTMLDivElement>>;
1680
+
1681
+ type DatePickerProps = Omit<InputProps, 'type' | 'onChange' | 'value' | 'defaultValue'> & {
1682
+ /** ISO date string (YYYY-MM-DD) — controlled. */
1683
+ value?: string;
1684
+ /** ISO date string — initial value when uncontrolled. */
1685
+ defaultValue?: string;
1686
+ /** Fired with the ISO string ('' when cleared). */
1687
+ onValueChange?: (value: string) => void;
1688
+ /** Show a clear button once a date is selected. */
1689
+ clearable?: boolean;
1690
+ };
1691
+ /**
1692
+ * Native date field with an ISO-string contract. Uses the platform picker
1693
+ * (mobile date wheels, keyboard editing, locale formatting) rather than a
1694
+ * custom calendar, so accessibility and input methods come for free.
1695
+ */
1696
+ declare const DatePicker: React.ForwardRefExoticComponent<Omit<InputProps, "type" | "defaultValue" | "onChange" | "value"> & {
1697
+ /** ISO date string (YYYY-MM-DD) — controlled. */
1698
+ value?: string;
1699
+ /** ISO date string — initial value when uncontrolled. */
1700
+ defaultValue?: string;
1701
+ /** Fired with the ISO string ('' when cleared). */
1702
+ onValueChange?: (value: string) => void;
1703
+ /** Show a clear button once a date is selected. */
1704
+ clearable?: boolean;
1705
+ } & React.RefAttributes<HTMLInputElement>>;
1706
+
1707
+ type TimePickerProps = Omit<InputProps, 'type' | 'onChange' | 'value' | 'defaultValue'> & {
1708
+ /** "HH:MM" (24h) — controlled. */
1709
+ value?: string;
1710
+ /** "HH:MM" — initial value when uncontrolled. */
1711
+ defaultValue?: string;
1712
+ /** Fired with the time string ('' when cleared). */
1713
+ onValueChange?: (value: string) => void;
1714
+ /** Show a clear button once a time is selected. */
1715
+ clearable?: boolean;
1716
+ };
1717
+ /**
1718
+ * Native time field with an "HH:MM" contract. The platform supplies the
1719
+ * picker, keyboard editing and locale behavior.
1720
+ */
1721
+ declare const TimePicker: React.ForwardRefExoticComponent<Omit<InputProps, "type" | "defaultValue" | "onChange" | "value"> & {
1722
+ /** "HH:MM" (24h) — controlled. */
1723
+ value?: string;
1724
+ /** "HH:MM" — initial value when uncontrolled. */
1725
+ defaultValue?: string;
1726
+ /** Fired with the time string ('' when cleared). */
1727
+ onValueChange?: (value: string) => void;
1728
+ /** Show a clear button once a time is selected. */
1729
+ clearable?: boolean;
1730
+ } & React.RefAttributes<HTMLInputElement>>;
1731
+
1732
+ type StepperStep = {
1733
+ label: string;
1734
+ description?: string;
1735
+ };
1736
+ type StepperProps = Omit<React.OlHTMLAttributes<HTMLOListElement>, 'onClick'> & {
1737
+ steps: StepperStep[];
1738
+ /** Zero-based index of the active step. */
1739
+ current: number;
1740
+ orientation?: 'horizontal' | 'vertical';
1741
+ /** Makes completed/upcoming steps clickable. */
1742
+ onStepClick?: (index: number) => void;
1743
+ };
1744
+ /**
1745
+ * Progress through a multi-step flow with proper semantics: an ordered list
1746
+ * where the active step carries aria-current="step" and each marker states
1747
+ * complete/current/upcoming in text, not only color.
1748
+ */
1749
+ declare const Stepper: React.ForwardRefExoticComponent<Omit<React.OlHTMLAttributes<HTMLOListElement>, "onClick"> & {
1750
+ steps: StepperStep[];
1751
+ /** Zero-based index of the active step. */
1752
+ current: number;
1753
+ orientation?: "horizontal" | "vertical";
1754
+ /** Makes completed/upcoming steps clickable. */
1755
+ onStepClick?: (index: number) => void;
1756
+ } & React.RefAttributes<HTMLOListElement>>;
1757
+
1758
+ type FileUploadProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'value' | 'onChange'> & {
1759
+ /** Controlled selection. */
1760
+ files?: File[];
1761
+ /** Initial selection when uncontrolled. */
1762
+ defaultFiles?: File[];
1763
+ /** Fired whenever the list changes (add, remove, drop, clear). */
1764
+ onFilesChange?: (files: File[]) => void;
1765
+ /** Drag-and-drop area copy. */
1766
+ label?: string;
1767
+ hint?: string;
1768
+ /** Per-file progress (0-100) keyed by file name, rendered as a bar. */
1769
+ progress?: Record<string, number>;
1770
+ };
1771
+ /**
1772
+ * Drag-and-drop file picker with a removable list. The native input drives
1773
+ * selection (keyboard + mobile camera/file dialogs); the drop zone is a
1774
+ * progressive enhancement. Files are plain `File` objects, so you own the
1775
+ * upload transport and can render progress per file.
1776
+ */
1777
+ declare const FileUpload: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "onChange" | "value"> & {
1778
+ /** Controlled selection. */
1779
+ files?: File[];
1780
+ /** Initial selection when uncontrolled. */
1781
+ defaultFiles?: File[];
1782
+ /** Fired whenever the list changes (add, remove, drop, clear). */
1783
+ onFilesChange?: (files: File[]) => void;
1784
+ /** Drag-and-drop area copy. */
1785
+ label?: string;
1786
+ hint?: string;
1787
+ /** Per-file progress (0-100) keyed by file name, rendered as a bar. */
1788
+ progress?: Record<string, number>;
1789
+ } & React.RefAttributes<HTMLInputElement>>;
1790
+
1791
+ type TimelineItem = {
1792
+ title: string;
1793
+ /** Period/date label (e.g. "2023 — Present"). */
1794
+ period?: string;
1795
+ description?: string;
1796
+ icon?: React.ReactNode;
1797
+ /** Muted items render dimmed (upcoming/archived). */
1798
+ muted?: boolean;
1799
+ };
1800
+ type TimelineProps = Omit<React.OlHTMLAttributes<HTMLOListElement>, 'children'> & {
1801
+ items: TimelineItem[];
1802
+ };
1803
+ /**
1804
+ * Vertical chronology (experience, activity, audit trail). Renders an
1805
+ * ordered list with a connector rule, so the sequence is conveyed
1806
+ * structurally instead of by decoration alone.
1807
+ */
1808
+ declare const Timeline: React.ForwardRefExoticComponent<Omit<React.OlHTMLAttributes<HTMLOListElement>, "children"> & {
1809
+ items: TimelineItem[];
1810
+ } & React.RefAttributes<HTMLOListElement>>;
1811
+
1220
1812
  type BlockElement = 'div' | 'span' | 'section' | 'article' | 'figure' | 'header' | 'footer' | 'nav' | 'main' | 'aside';
1221
1813
  type BlockProps = React.HTMLAttributes<HTMLElement> & {
1222
1814
  /** Semantic element to render (default 'div'). */
@@ -1392,11 +1984,15 @@ declare const MenuContent: React.ForwardRefExoticComponent<MenuContentProps & Re
1392
1984
  type MenuItemProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
1393
1985
  /** Renders the item in a destructive style. */
1394
1986
  destructive?: boolean;
1987
+ /** Render the child element (e.g. an <a>) as the menu item. */
1988
+ asChild?: boolean;
1395
1989
  };
1396
1990
  /** A single action item in the menu. */
1397
1991
  declare const MenuItem: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & {
1398
1992
  /** Renders the item in a destructive style. */
1399
1993
  destructive?: boolean;
1994
+ /** Render the child element (e.g. an <a>) as the menu item. */
1995
+ asChild?: boolean;
1400
1996
  } & React.RefAttributes<HTMLButtonElement>>;
1401
1997
  type MenuSeparatorProps = React.HTMLAttributes<HTMLDivElement>;
1402
1998
  /** Visual divider between menu items. */
@@ -1492,10 +2088,22 @@ type PaginationIcons = {
1492
2088
  last?: React.ReactNode;
1493
2089
  };
1494
2090
  type PaginationProps = React.HTMLAttributes<HTMLElement> & {
1495
- /** Current page number (1-based). */
1496
- page: number;
1497
- /** Total number of pages. */
1498
- pageCount: number;
2091
+ /** Current page number (1-based). Alias: currentPage. */
2092
+ page?: number;
2093
+ /** Total number of pages. Alias: totalPages (or derived from total/pageSize). */
2094
+ pageCount?: number;
2095
+ /** Alias for page (migration-friendly). */
2096
+ currentPage?: number;
2097
+ /** Alias for pageCount. */
2098
+ totalPages?: number;
2099
+ /** Rows per page — with `total`, enables the item-count summary. */
2100
+ pageSize?: number;
2101
+ /** Total item count — with `pageSize`, enables the summary and derives pageCount. */
2102
+ total?: number;
2103
+ /** Noun used in the summary ("Showing 26–50 of 312 classes"). Default "items". */
2104
+ itemLabel?: string;
2105
+ /** Force the summary on/off; defaults to on when total and pageSize are set. */
2106
+ showSummary?: boolean;
1499
2107
  /** Called with the new page number. */
1500
2108
  onPageChange?: (page: number) => void;
1501
2109
  /** How many page buttons to show around the current page (default 1). */
@@ -1511,16 +2119,28 @@ type PaginationProps = React.HTMLAttributes<HTMLElement> & {
1511
2119
  };
1512
2120
  /**
1513
2121
  * Numeric pagination with prev/next and optional boundary jumps. Renders
1514
- * as a nav landmark with aria-current="page" on the active button. Each
1515
- * control is a real <button> with an accessible name; glyphs are
1516
- * swappable and each boundary button can be shown or hidden independently
1517
- * (e.g. hide — instead of disabling — once you reach the list edge).
2122
+ * as a nav landmark with aria-current="page" on the active button. Accepts
2123
+ * either page/pageCount or the currentPage/totalPages aliases, and can
2124
+ * derive the page count (plus a "Showing X–Y of Z" summary) from
2125
+ * total/pageSize.
1518
2126
  */
1519
2127
  declare const Pagination: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
1520
- /** Current page number (1-based). */
1521
- page: number;
1522
- /** Total number of pages. */
1523
- pageCount: number;
2128
+ /** Current page number (1-based). Alias: currentPage. */
2129
+ page?: number;
2130
+ /** Total number of pages. Alias: totalPages (or derived from total/pageSize). */
2131
+ pageCount?: number;
2132
+ /** Alias for page (migration-friendly). */
2133
+ currentPage?: number;
2134
+ /** Alias for pageCount. */
2135
+ totalPages?: number;
2136
+ /** Rows per page — with `total`, enables the item-count summary. */
2137
+ pageSize?: number;
2138
+ /** Total item count — with `pageSize`, enables the summary and derives pageCount. */
2139
+ total?: number;
2140
+ /** Noun used in the summary ("Showing 26–50 of 312 classes"). Default "items". */
2141
+ itemLabel?: string;
2142
+ /** Force the summary on/off; defaults to on when total and pageSize are set. */
2143
+ showSummary?: boolean;
1524
2144
  /** Called with the new page number. */
1525
2145
  onPageChange?: (page: number) => void;
1526
2146
  /** How many page buttons to show around the current page (default 1). */
@@ -1535,4 +2155,4 @@ declare const Pagination: React.ForwardRefExoticComponent<React.HTMLAttributes<H
1535
2155
  icons?: PaginationIcons;
1536
2156
  } & React.RefAttributes<HTMLElement>>;
1537
2157
 
1538
- export { type AccessibilityRequirement, Accordion, AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, Alert, AlertDescription, type AlertDescriptionProps, type AlertProps, AlertTitle, type AlertTitleProps, type AntiPattern, Autocomplete, type AutocompleteProps, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Block, type BlockElement, type BlockProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Card, CardContent, type CardContentProps, CardDescription, type CardDescriptionProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, CardTitle, type CardTitleProps, Checkbox, CheckboxGroup, CheckboxGroupItem, type CheckboxGroupItemProps, type CheckboxGroupOrientation, type CheckboxGroupProps, type CheckboxProps, type ComboboxItem, type ComponentManifest, type ComponentTier, type CompositionRule, type ContentGuideline, DataTable, type DataTableColumn, type DataTableProps, Dialog, type DialogProps, Divider, Drawer, type DrawerProps, type DrawerSide, type DrawerSize, Fieldset, type FieldsetProps, Flex, FlexItem, type FlexItemProps, type FlexProps, Form, FormField, type FormFieldLabelPlacement, type FormFieldProps, FormLayout, type FormLayoutProps, type FormProps, type FormVariant, type GapValue, Grid, GridItem, type GridItemProps, type GridProps, Heading, type HeadingLevel, type HeadingProps, Input, InputGroup, InputGroupAddon, type InputGroupAddonProps, type InputGroupProps, type InputProps, Label, type LabelProps, List, ListItem, type ListItemProps, type ListProps, Menu, MenuContent, type MenuContentProps, MenuItem, type MenuItemProps, MenuLabel, type MenuLabelProps, type MenuProps, MenuSeparator, type MenuSeparatorProps, MenuTrigger, type MenuTriggerProps, Pagination, type PaginationIcons, type PaginationProps, Popover, PopoverContent, type PopoverContentProps, type PopoverProps, PopoverTrigger, type PopoverTriggerProps, Progress, type ProgressProps, type PropSchema, Radio, RadioCard, type RadioCardProps, RadioGroup, RadioGroupContext, RadioGroupItem, type RadioGroupItemProps, type RadioGroupProps, type RadioProps, Search, type SearchOption, type SearchProps, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Skeleton, type SkeletonProps, type SortIconState, Spinner, type SpinnerProps, Switch, type SwitchProps, Table, TableBody, type TableBodyProps, TableCaption, type TableCaptionProps, TableCell, type TableCellProps, TableFooter, type TableFooterProps, TableHead, type TableHeadProps, TableHeader, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, TabsContent, type TabsContentProps, TabsList, type TabsListProps, type TabsProps, TabsTrigger, type TabsTriggerProps, Text, type TextProps, Textarea, type TextareaProps, type ToastAction, type ToastContextValue, type ToastOptions, ToastProvider, type ToastRecord, Tooltip, type TooltipProps, type UsageExample, alertVariants, badgeVariants, buttonVariants, cn, isComponentManifest, resolveGap, separatorVariants, spinnerVariants, useCombobox, usePresence, useToast };
2158
+ export { type AccessibilityRequirement, Accordion, AccordionContent, type AccordionContentProps, AccordionItem, type AccordionItemProps, type AccordionProps, AccordionTrigger, type AccordionTriggerProps, Alert, AlertDescription, type AlertDescriptionProps, type AlertProps, AlertTitle, type AlertTitleProps, type AntiPattern, AppShell, type AppShellProps, AuthLayout, type AuthLayoutProps, Autocomplete, type AutocompleteOption, type AutocompleteProps, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Block, type BlockElement, type BlockProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Card, CardContent, type CardContentProps, CardDescription, type CardDescriptionProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, CardTitle, type CardTitleProps, Checkbox, CheckboxGroup, CheckboxGroupItem, type CheckboxGroupItemProps, type CheckboxGroupOrientation, type CheckboxGroupProps, type CheckboxProps, type ComboboxItem, type ComponentManifest, type ComponentTier, type CompositionRule, type ContentGuideline, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, Dialog, DialogBody, type DialogBodyProps, DialogDescription, type DialogDescriptionProps, DialogFooter, type DialogFooterProps, DialogHeader, type DialogHeaderProps, type DialogProps, type DialogSize, DialogTitle, type DialogTitleProps, Divider, Drawer, type DrawerProps, type DrawerSide, type DrawerSize, EmptyState, type EmptyStateProps, Fieldset, type FieldsetProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, Flex, FlexItem, type FlexItemProps, type FlexProps, Form, FormField, type FormFieldLabelPlacement, type FormFieldProps, FormLayout, type FormLayoutProps, type FormProps, type FormVariant, type GapValue, Grid, GridItem, type GridItemProps, type GridProps, Heading, type HeadingLevel, type HeadingProps, Input, InputGroup, InputGroupAddon, type InputGroupAddonProps, type InputGroupProps, type InputProps, Label, type LabelProps, List, ListItem, type ListItemProps, type ListProps, Menu, MenuContent, type MenuContentProps, MenuItem, type MenuItemProps, MenuLabel, type MenuLabelProps, type MenuProps, MenuSeparator, type MenuSeparatorProps, MenuTrigger, type MenuTriggerProps, MetricCard, type MetricCardProps, type MetricTrend, PageHeader, type PageHeaderProps, Pagination, type PaginationIcons, type PaginationProps, PasswordInput, type PasswordInputProps, Popover, PopoverContent, type PopoverContentProps, type PopoverProps, PopoverTrigger, type PopoverTriggerProps, Progress, type ProgressProps, type PropSchema, Radio, RadioCard, type RadioCardProps, RadioGroup, RadioGroupContext, RadioGroupItem, type RadioGroupItemProps, type RadioGroupProps, type RadioProps, Search, type SearchOption, type SearchProps, Select, SelectMenu, type SelectMenuItem, type SelectMenuProps, type SelectOption, type SelectOptionGroup, type SelectProps, Separator, type SeparatorProps, Sidebar, type SidebarItem, type SidebarProps, type SidebarSection, Skeleton, type SkeletonProps, type SortIconState, Spinner, type SpinnerProps, Stepper, type StepperProps, type StepperStep, Switch, type SwitchProps, Table, TableBody, type TableBodyProps, TableCaption, type TableCaptionProps, TableCard, type TableCardProps, TableCell, type TableCellProps, TableFooter, type TableFooterProps, TableHead, type TableHeadProps, TableHeader, type TableHeaderProps, type TableProps, TableRow, type TableRowProps, Tabs, TabsContent, type TabsContentProps, TabsList, type TabsListProps, type TabsProps, TabsTrigger, type TabsTriggerProps, Text, type TextProps, Textarea, type TextareaProps, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, type ToastAction, type ToastContextValue, type ToastOptions, ToastProvider, type ToastRecord, type ToastVariant, Toaster, type ToasterPosition, type ToasterProps, Tooltip, type TooltipProps, type UsageExample, alertVariants, badgeVariants, buttonVariants, cn, isComponentManifest, resolveGap, separatorVariants, spinnerVariants, toast, useCombobox, usePresence, useToast };