@tailor-platform/app-shell 0.30.0 → 0.31.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.
@@ -1,5 +1,10 @@
1
1
  import { AuthClient } from '@tailor-platform/auth-public-client';
2
+ import { Autocomplete as Autocomplete_2 } from '@base-ui/react/autocomplete';
3
+ import { AutocompleteFilter } from '@base-ui/react';
4
+ import { AutocompleteFilterOptions } from '@base-ui/react';
5
+ import { AutocompleteRootProps } from '@base-ui/react/autocomplete';
2
6
  import { ClassProp } from 'class-variance-authority/types';
7
+ import { Combobox as Combobox_2 } from '@base-ui/react/combobox';
3
8
  import { CSSProperties } from 'react';
4
9
  import { Dialog as Dialog_2 } from '@base-ui/react/dialog';
5
10
  import { Drawer } from '@base-ui/react/drawer';
@@ -7,10 +12,13 @@ import { FC } from 'react';
7
12
  import { JSX } from 'react/jsx-runtime';
8
13
  import { Link } from 'react-router';
9
14
  import { LoaderFunctionArgs } from 'react-router';
15
+ import { Menu as Menu_2 } from '@base-ui/react/menu';
10
16
  import * as React_2 from 'react';
11
17
  import { ReactNode } from 'react';
18
+ import { Select as Select_2 } from '@base-ui/react/select';
12
19
  import { toast } from 'sonner';
13
20
  import { Tooltip as Tooltip_2 } from '@base-ui/react/tooltip';
21
+ import { useFilter } from 'node_modules/@base-ui/react/esm/combobox/index.parts';
14
22
  import { useLocation } from 'react-router';
15
23
  import { useNavigate } from 'react-router';
16
24
  import { useParams } from 'react-router';
@@ -205,6 +213,52 @@ export declare type AppShellProps = SharedAppShellProps & {
205
213
  export declare interface AppShellRegister {
206
214
  }
207
215
 
216
+ /**
217
+ * Fetcher specification for async item loading.
218
+ *
219
+ * Can be either:
220
+ * - A plain function — uses the default debounce delay (300ms)
221
+ * - An object with `fn` and `debounceMs` — uses the specified debounce delay
222
+ *
223
+ * @example
224
+ * ```tsx
225
+ * // Plain function (default 300ms debounce)
226
+ * fetcher: async (query, { signal }) => {
227
+ * const res = await fetch(`/api/search?q=${query}`, { signal });
228
+ * return res.json();
229
+ * }
230
+ *
231
+ * // Object with custom debounce
232
+ * fetcher: {
233
+ * fn: async (query, { signal }) => {
234
+ * const res = await fetch(`/api/search?q=${query}`, { signal });
235
+ * return res.json();
236
+ * },
237
+ * debounceMs: 500,
238
+ * }
239
+ * ```
240
+ */
241
+ declare type AsyncFetcher<T> = AsyncFetcherFn<T> | {
242
+ fn: AsyncFetcherFn<T>;
243
+ debounceMs: number;
244
+ };
245
+
246
+ /**
247
+ * A function that fetches items for a given query string.
248
+ *
249
+ * Receives an `AbortSignal` that is aborted when a newer request supersedes
250
+ * this one — pass it through to `fetch()` so the browser cancels the
251
+ * in-flight HTTP request automatically.
252
+ *
253
+ * **Error handling:** Errors should be handled inside the fetcher.
254
+ * If the fetcher throws, the component silently falls back to an empty
255
+ * item list — there is no `onError` callback. Catch errors in the
256
+ * fetcher to show toasts, log to error tracking, or return fallback data.
257
+ */
258
+ declare type AsyncFetcherFn<T> = (query: string, options: {
259
+ signal: AbortSignal;
260
+ }) => Promise<T[]>;
261
+
208
262
  export { AuthClient }
209
263
 
210
264
  /**
@@ -283,6 +337,186 @@ export declare type AuthState = {
283
337
  isReady: boolean;
284
338
  };
285
339
 
340
+ export declare const Autocomplete: typeof AutocompleteStandalone & {
341
+ Async: typeof AutocompleteAsyncStandalone;
342
+ Parts: {
343
+ Root: typeof AutocompleteRoot;
344
+ Value: AutocompleteValue;
345
+ InputGroup: typeof AutocompleteInputGroup;
346
+ Input: typeof AutocompleteInput;
347
+ Trigger: typeof AutocompleteTrigger;
348
+ Content: typeof AutocompleteContent;
349
+ List: typeof AutocompleteList;
350
+ Item: typeof AutocompleteItem;
351
+ Empty: typeof AutocompleteEmpty;
352
+ Clear: typeof AutocompleteClear;
353
+ Group: typeof AutocompleteGroup;
354
+ GroupLabel: typeof AutocompleteGroupLabel;
355
+ Collection: typeof AutocompleteCollection;
356
+ Status: AutocompleteStatus;
357
+ useFilter: (options?: AutocompleteFilterOptions) => AutocompleteFilter;
358
+ useAsync: typeof useAsync_2;
359
+ };
360
+ };
361
+
362
+ /** Fetcher type for `Autocomplete.Async`. */
363
+ export declare type AutocompleteAsyncFetcher<T> = AsyncFetcher<T>;
364
+
365
+ declare function AutocompleteAsyncStandalone<T>(props: AutocompleteAsyncStandaloneProps<T>): JSX.Element;
366
+
367
+ declare namespace AutocompleteAsyncStandalone {
368
+ var displayName: string;
369
+ }
370
+
371
+ declare interface AutocompleteAsyncStandaloneProps<T> extends AutocompletePropsBase<T> {
372
+ /** Fetcher for async item loading. Pass a function for default debounce, or `{ fn, debounceMs }` to customize. */
373
+ fetcher: AutocompleteAsyncFetcher<T>;
374
+ /** Text shown while loading. @default "Loading..." */
375
+ loadingText?: string;
376
+ }
377
+
378
+ declare function AutocompleteClear({ className, children, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Clear>): JSX.Element;
379
+
380
+ declare namespace AutocompleteClear {
381
+ var displayName: string;
382
+ }
383
+
384
+ declare function AutocompleteCollection({ ...props }: React_2.ComponentProps<typeof Autocomplete_2.Collection>): JSX.Element;
385
+
386
+ declare namespace AutocompleteCollection {
387
+ var displayName: string;
388
+ }
389
+
390
+ declare function AutocompleteContent({ className, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Popup>): JSX.Element;
391
+
392
+ declare namespace AutocompleteContent {
393
+ var displayName: string;
394
+ }
395
+
396
+ declare function AutocompleteEmpty({ className, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Empty>): JSX.Element;
397
+
398
+ declare namespace AutocompleteEmpty {
399
+ var displayName: string;
400
+ }
401
+
402
+ declare function AutocompleteGroup({ ...props }: React_2.ComponentProps<typeof Autocomplete_2.Group>): JSX.Element;
403
+
404
+ declare namespace AutocompleteGroup {
405
+ var displayName: string;
406
+ }
407
+
408
+ declare function AutocompleteGroupLabel({ className, ...props }: React_2.ComponentProps<typeof Autocomplete_2.GroupLabel>): JSX.Element;
409
+
410
+ declare namespace AutocompleteGroupLabel {
411
+ var displayName: string;
412
+ }
413
+
414
+ declare function AutocompleteInput({ className, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Input>): JSX.Element;
415
+
416
+ declare namespace AutocompleteInput {
417
+ var displayName: string;
418
+ }
419
+
420
+ declare function AutocompleteInputGroup({ className, children, ...props }: React_2.ComponentProps<"div">): JSX.Element;
421
+
422
+ declare namespace AutocompleteInputGroup {
423
+ var displayName: string;
424
+ }
425
+
426
+ declare function AutocompleteItem({ className, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Item>): JSX.Element;
427
+
428
+ declare namespace AutocompleteItem {
429
+ var displayName: string;
430
+ }
431
+
432
+ declare function AutocompleteList({ className, ...props }: React_2.ComponentProps<typeof Autocomplete_2.List>): JSX.Element;
433
+
434
+ declare namespace AutocompleteList {
435
+ var displayName: string;
436
+ }
437
+
438
+ declare type AutocompletePickedRootProps<Value> = Pick<AutocompleteRootProps<Value>, "value" | "defaultValue" | "onValueChange" | "filter" | "disabled" | "children"> & {
439
+ items?: readonly Value[];
440
+ };
441
+
442
+ /**
443
+ * Common props shared between Autocomplete and Autocomplete.Async.
444
+ *
445
+ * Unlike Select and Combobox, Autocomplete always operates in single-value
446
+ * mode — its value is the raw input string, not a discrete item selection.
447
+ */
448
+ declare interface AutocompletePropsBase<T> {
449
+ /** Placeholder text for the input */
450
+ placeholder?: string;
451
+ /** Text shown when no items match */
452
+ emptyText?: string;
453
+ /** Map each item to its label, key, and optional custom render. */
454
+ mapItem?: (item: T) => MappedItem;
455
+ /** Additional className for the root container */
456
+ className?: string;
457
+ /** Whether the autocomplete is disabled */
458
+ disabled?: boolean;
459
+ /** Current value (controlled) */
460
+ value?: string;
461
+ /** Default value (uncontrolled) */
462
+ defaultValue?: string;
463
+ /** Called when the value changes */
464
+ onValueChange?: (value: string) => void;
465
+ }
466
+
467
+ declare function AutocompleteRoot<Value>(props: AutocompletePickedRootProps<Value>): JSX.Element;
468
+
469
+ declare namespace AutocompleteRoot {
470
+ var displayName: string;
471
+ }
472
+
473
+ declare function AutocompleteStandalone<I>(props: AutocompleteStandaloneProps<I>): JSX.Element;
474
+
475
+ declare namespace AutocompleteStandalone {
476
+ var displayName: string;
477
+ }
478
+
479
+ declare interface AutocompleteStandaloneProps<I> extends AutocompletePropsBase<ExtractItem<I>> {
480
+ /**
481
+ * Items to show as suggestions. May be a flat array of `T` or an array of
482
+ * `ItemGroup<T>`. Items are identified as groups by the presence of
483
+ * `label: string` and `items: T[]` fields — avoid item types whose
484
+ * shape coincidentally matches this structure.
485
+ */
486
+ items: I[];
487
+ }
488
+
489
+ declare function AutocompleteStatus({ className, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Status>): JSX.Element;
490
+
491
+ declare namespace AutocompleteStatus {
492
+ var displayName: string;
493
+ }
494
+
495
+ declare function AutocompleteTrigger({ className, children, ...props }: React_2.ComponentProps<typeof Autocomplete_2.Trigger>): JSX.Element;
496
+
497
+ declare namespace AutocompleteTrigger {
498
+ var displayName: string;
499
+ }
500
+
501
+ declare interface AutocompleteUseAsyncReturn<T> {
502
+ /** Fetched items — pass to the Root `items` prop */
503
+ items: T[];
504
+ /** Whether a fetch is currently in-flight */
505
+ loading: boolean;
506
+ /** Current input value — pass to the Root `value` prop */
507
+ value: string;
508
+ /** The error thrown by the last fetch, if any */
509
+ error: unknown;
510
+ /** Value change handler — pass to the Root `onValueChange` prop. */
511
+ onValueChange: (value: string) => void;
512
+ }
513
+
514
+ declare function AutocompleteValue({ ...props }: React_2.ComponentProps<typeof Autocomplete_2.Value>): JSX.Element;
515
+
516
+ declare namespace AutocompleteValue {
517
+ var displayName: string;
518
+ }
519
+
286
520
  export declare function Badge({ className, variant, children, ...props }: BadgeProps): JSX.Element;
287
521
 
288
522
  export declare interface BadgeProps extends React_2.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
@@ -341,6 +575,20 @@ declare namespace Cell {
341
575
  var displayName: string;
342
576
  }
343
577
 
578
+ /** A menu item that toggles a setting on or off. */
579
+ declare function CheckboxItem({ className, ...props }: React_2.ComponentProps<typeof Menu_2.CheckboxItem>): JSX.Element;
580
+
581
+ declare namespace CheckboxItem {
582
+ var displayName: string;
583
+ }
584
+
585
+ /** Indicates whether the checkbox item is ticked. */
586
+ declare function CheckboxItemIndicator({ className, ...props }: React_2.ComponentProps<typeof Menu_2.CheckboxItemIndicator>): JSX.Element;
587
+
588
+ declare namespace CheckboxItemIndicator {
589
+ var displayName: string;
590
+ }
591
+
344
592
  /** A button that closes the dialog. */
345
593
  declare function Close({ ...props }: React_2.ComponentProps<typeof Dialog_2.Close>): JSX.Element;
346
594
 
@@ -390,6 +638,209 @@ declare interface ColumnProps {
390
638
  */
391
639
  declare type Columns = 3 | 4;
392
640
 
641
+ export declare const Combobox: typeof ComboboxStandalone & {
642
+ Async: typeof ComboboxAsyncStandalone;
643
+ Parts: {
644
+ Root: typeof ComboboxRoot;
645
+ InputGroup: typeof ComboboxInputGroup;
646
+ Input: typeof ComboboxInput;
647
+ Trigger: typeof ComboboxTrigger;
648
+ Content: typeof ComboboxContent;
649
+ List: typeof ComboboxList;
650
+ Item: typeof ComboboxItem;
651
+ Empty: typeof ComboboxEmpty;
652
+ Group: typeof ComboboxGroup;
653
+ GroupLabel: typeof ComboboxGroupLabel;
654
+ Clear: typeof ComboboxClear;
655
+ Chips: typeof ComboboxChips;
656
+ Chip: typeof ComboboxChip;
657
+ ChipRemove: typeof ComboboxChipRemove;
658
+ Value: typeof ComboboxValue;
659
+ Collection: typeof ComboboxCollection;
660
+ Status: ComboboxStatus;
661
+ useFilter: useFilter;
662
+ useCreatable: typeof useCreatable;
663
+ useAsync: typeof useAsync;
664
+ };
665
+ };
666
+
667
+ declare type ComboboxAsyncCreatableProps<T extends object> = (ComboboxAsyncOwnProps<T> & CreatableProps<T> & Omit<ComboboxPropsSingle<T>, "mapItem">) | (ComboboxAsyncOwnProps<T> & CreatableProps<T> & Omit<ComboboxPropsMultiple<T>, "mapItem">);
668
+
669
+ /** Fetcher type for `Combobox.Async`. */
670
+ export declare type ComboboxAsyncFetcher<T> = AsyncFetcher<T>;
671
+
672
+ declare interface ComboboxAsyncOwnProps<T> {
673
+ /** Fetcher for async item loading. Pass a function for default debounce, or `{ fn, debounceMs }` to customize. */
674
+ fetcher: ComboboxAsyncFetcher<T>;
675
+ /** Text shown while loading. @default "Loading..." */
676
+ loadingText?: string;
677
+ }
678
+
679
+ declare type ComboboxAsyncPlainProps<T> = (ComboboxAsyncOwnProps<T> & ComboboxPropsSingle<T>) | (ComboboxAsyncOwnProps<T> & ComboboxPropsMultiple<T>);
680
+
681
+ declare function ComboboxAsyncStandalone<T extends object>(props: ComboboxAsyncCreatableProps<T>): React_2.JSX.Element;
682
+
683
+ declare function ComboboxAsyncStandalone<T>(props: ComboboxAsyncPlainProps<T>): React_2.JSX.Element;
684
+
685
+ declare function ComboboxChip({ className, ...props }: React_2.ComponentProps<typeof Combobox_2.Chip>): JSX.Element;
686
+
687
+ declare namespace ComboboxChip {
688
+ var displayName: string;
689
+ }
690
+
691
+ declare function ComboboxChipRemove({ className, children, ...props }: React_2.ComponentProps<typeof Combobox_2.ChipRemove>): JSX.Element;
692
+
693
+ declare namespace ComboboxChipRemove {
694
+ var displayName: string;
695
+ }
696
+
697
+ declare function ComboboxChips({ className, ...props }: React_2.ComponentProps<typeof Combobox_2.Chips>): JSX.Element;
698
+
699
+ declare namespace ComboboxChips {
700
+ var displayName: string;
701
+ }
702
+
703
+ declare function ComboboxClear({ className, children, ...props }: React_2.ComponentProps<typeof Combobox_2.Clear>): JSX.Element;
704
+
705
+ declare namespace ComboboxClear {
706
+ var displayName: string;
707
+ }
708
+
709
+ declare function ComboboxCollection({ ...props }: React_2.ComponentProps<typeof Combobox_2.Collection>): JSX.Element;
710
+
711
+ declare namespace ComboboxCollection {
712
+ var displayName: string;
713
+ }
714
+
715
+ declare function ComboboxContent({ className, ...props }: React_2.ComponentProps<typeof Combobox_2.Popup>): JSX.Element;
716
+
717
+ declare namespace ComboboxContent {
718
+ var displayName: string;
719
+ }
720
+
721
+ declare function ComboboxEmpty({ className, ...props }: React_2.ComponentProps<typeof Combobox_2.Empty>): JSX.Element;
722
+
723
+ declare namespace ComboboxEmpty {
724
+ var displayName: string;
725
+ }
726
+
727
+ declare function ComboboxGroup({ ...props }: React_2.ComponentProps<typeof Combobox_2.Group>): JSX.Element;
728
+
729
+ declare namespace ComboboxGroup {
730
+ var displayName: string;
731
+ }
732
+
733
+ declare function ComboboxGroupLabel({ className, ...props }: React_2.ComponentProps<typeof Combobox_2.GroupLabel>): JSX.Element;
734
+
735
+ declare namespace ComboboxGroupLabel {
736
+ var displayName: string;
737
+ }
738
+
739
+ declare function ComboboxInput({ className, ...props }: React_2.ComponentProps<typeof Combobox_2.Input>): JSX.Element;
740
+
741
+ declare namespace ComboboxInput {
742
+ var displayName: string;
743
+ }
744
+
745
+ declare function ComboboxInputGroup({ className, children, ...props }: React_2.ComponentProps<typeof Combobox_2.InputGroup>): JSX.Element;
746
+
747
+ declare namespace ComboboxInputGroup {
748
+ var displayName: string;
749
+ }
750
+
751
+ declare function ComboboxItem({ className, children, ...props }: React_2.ComponentProps<typeof Combobox_2.Item>): JSX.Element;
752
+
753
+ declare namespace ComboboxItem {
754
+ var displayName: string;
755
+ }
756
+
757
+ declare function ComboboxList({ className, ...props }: React_2.ComponentProps<typeof Combobox_2.List>): JSX.Element;
758
+
759
+ declare namespace ComboboxList {
760
+ var displayName: string;
761
+ }
762
+
763
+ declare interface ComboboxPropsBase<T> {
764
+ /** Placeholder text for the input */
765
+ placeholder?: string;
766
+ /** Text shown when no items match. @default "No results." */
767
+ emptyText?: string;
768
+ /** Map each item to its label, key, and optional custom render. */
769
+ mapItem?: (item: T) => MappedItem;
770
+ /** Additional className for the root container */
771
+ className?: string;
772
+ /** Whether the combobox is disabled */
773
+ disabled?: boolean;
774
+ }
775
+
776
+ declare interface ComboboxPropsMultiple<T> extends ComboboxPropsBase<T> {
777
+ multiple: true;
778
+ /** Current value (controlled) */
779
+ value?: T[];
780
+ /** Default value (uncontrolled) */
781
+ defaultValue?: T[];
782
+ /** Called when the selected values change */
783
+ onValueChange?: (value: T[]) => void;
784
+ }
785
+
786
+ declare interface ComboboxPropsSingle<T> extends ComboboxPropsBase<T> {
787
+ multiple?: false | undefined;
788
+ /** Current value (controlled) */
789
+ value?: T | null;
790
+ /** Default value (uncontrolled) */
791
+ defaultValue?: T | null;
792
+ /** Called when the selected value changes */
793
+ onValueChange?: (value: T | null) => void;
794
+ }
795
+
796
+ declare function ComboboxRoot<Value, Multiple extends boolean | undefined = false>(props: ComboboxRootProps<Value, Multiple>): JSX.Element;
797
+
798
+ declare namespace ComboboxRoot {
799
+ var displayName: string;
800
+ }
801
+
802
+ declare type ComboboxRootProps<Value, Multiple extends boolean | undefined = false> = Pick<React_2.ComponentProps<typeof Combobox_2.Root<Value, Multiple>>, "items" | "value" | "defaultValue" | "onValueChange" | "multiple" | "filter" | "inputValue" | "onInputValueChange" | "itemToStringLabel" | "itemToStringValue" | "disabled" | "children">;
803
+
804
+ declare function ComboboxStandalone<T extends object>(props: ComboboxStaticCreatableProps<T>): React_2.JSX.Element;
805
+
806
+ declare function ComboboxStandalone<I>(props: ComboboxStaticPlainProps<I>): React_2.JSX.Element;
807
+
808
+ declare type ComboboxStaticCreatableProps<T extends object> = ({
809
+ items: T[];
810
+ } & CreatableProps<T> & Omit<ComboboxPropsSingle<T>, "mapItem">) | ({
811
+ items: T[];
812
+ } & CreatableProps<T> & Omit<ComboboxPropsMultiple<T>, "mapItem">);
813
+
814
+ /**
815
+ * @property items - Items to display. May be a flat array of `T` or an array of
816
+ * `ItemGroup<T>`. Items are identified as groups by the presence of
817
+ * `label: string` and `items: T[]` fields — avoid item types whose
818
+ * shape coincidentally matches this structure.
819
+ */
820
+ declare type ComboboxStaticPlainProps<I> = ({
821
+ items: I[];
822
+ } & ComboboxPropsSingle<ExtractItem<I>>) | ({
823
+ items: I[];
824
+ } & ComboboxPropsMultiple<ExtractItem<I>>);
825
+
826
+ declare function ComboboxStatus({ className, ...props }: React_2.ComponentProps<typeof Combobox_2.Status>): JSX.Element;
827
+
828
+ declare namespace ComboboxStatus {
829
+ var displayName: string;
830
+ }
831
+
832
+ declare function ComboboxTrigger({ className, children, ...props }: React_2.ComponentProps<typeof Combobox_2.Trigger>): JSX.Element;
833
+
834
+ declare namespace ComboboxTrigger {
835
+ var displayName: string;
836
+ }
837
+
838
+ declare function ComboboxValue({ ...props }: React_2.ComponentProps<typeof Combobox_2.Value>): JSX.Element;
839
+
840
+ declare namespace ComboboxValue {
841
+ var displayName: string;
842
+ }
843
+
393
844
  /**
394
845
  * CommandPalette component that uses navigation items with access control.
395
846
  * Renders a searchable command palette UI triggered by Cmd+K / Ctrl+K.
@@ -450,21 +901,34 @@ declare namespace Content {
450
901
  var displayName: string;
451
902
  }
452
903
 
453
- /** The main sheet panel. The `side` is inherited from `Sheet.Root` via context. */
454
- declare function Content_2({ className, children, ...props }: React_2.ComponentProps<typeof Drawer.Popup>): JSX.Element;
904
+ /** The menu popup that displays menu items. */
905
+ declare function Content_2({ className, position, children, ...restProps }: React_2.ComponentProps<typeof Menu_2.Popup> & {
906
+ position?: PositionProps;
907
+ }): JSX.Element;
455
908
 
456
909
  declare namespace Content_2 {
457
910
  var displayName: string;
458
911
  }
459
912
 
913
+ /** The main sheet panel. The `side` is inherited from `Sheet.Root` via context. */
914
+ declare function Content_3({ className, children, ...props }: React_2.ComponentProps<typeof Drawer.Popup>): JSX.Element;
915
+
916
+ declare namespace Content_3 {
917
+ var displayName: string;
918
+ }
919
+
460
920
  /** The tooltip popup that displays additional information. */
461
- declare function Content_3({ className, sideOffset, side, align, children, ...restProps }: React_2.ComponentProps<typeof Tooltip_2.Popup> & {
462
- sideOffset?: number;
463
- side?: "top" | "right" | "bottom" | "left";
464
- align?: "start" | "center" | "end";
921
+ declare function Content_4({ className, position, side: _side, align: _align, sideOffset: _sideOffset, children, ...restProps }: React_2.ComponentProps<typeof Tooltip_2.Popup> & {
922
+ position?: PositionProps;
923
+ /** @deprecated Use `position={{ side }}` instead. */
924
+ side?: PositionProps["side"];
925
+ /** @deprecated Use `position={{ align }}` instead. */
926
+ align?: PositionProps["align"];
927
+ /** @deprecated Use `position={{ sideOffset }}` instead. */
928
+ sideOffset?: PositionProps["sideOffset"];
465
929
  }): JSX.Element;
466
930
 
467
- declare namespace Content_3 {
931
+ declare namespace Content_4 {
468
932
  var displayName: string;
469
933
  }
470
934
 
@@ -476,6 +940,32 @@ export declare type ContextData = AppShellRegister extends {
476
940
  contextData: infer T;
477
941
  } ? T : Record<string, unknown>;
478
942
 
943
+ /**
944
+ * Creatable opt-in props. When `onCreateItem` is provided, the combobox allows
945
+ * users to create new items on-the-fly.
946
+ *
947
+ * `T` must be an object type because the creatable mechanism uses a sentinel
948
+ * object for identity comparison — primitive types (string, number) would
949
+ * collide with real items.
950
+ */
951
+ declare interface CreatableProps<T extends object> {
952
+ /**
953
+ * Called when the user selects the "create" option.
954
+ *
955
+ * Return values control what happens next:
956
+ * - `T` — accept the item and add it to the selection
957
+ * - `false` — cancel the creation (item is NOT selected)
958
+ *
959
+ * May return a `Promise` for async workflows.
960
+ * A rejected promise also cancels the creation.
961
+ */
962
+ onCreateItem: (value: string) => T | false | Promise<T | false>;
963
+ /** Map each item to its label, key, and optional custom render. Required when creatable. */
964
+ mapItem: (item: T) => MappedItem;
965
+ /** Format the label for the "create" option. @default (v) => `Create "${v}"` */
966
+ formatCreateLabel?: (value: string) => string;
967
+ }
968
+
479
969
  /**
480
970
  * Create an enhanced authentication client.
481
971
  *
@@ -955,6 +1445,9 @@ declare type ErrorBoundaryProps = {
955
1445
  */
956
1446
  declare type ExtractBasePath<T extends string> = T extends `${infer Base}?${string}` ? Base : T;
957
1447
 
1448
+ /** Extracts the item type from a possibly-grouped items array element. */
1449
+ declare type ExtractItem<I> = I extends ItemGroup<infer T> ? T : I;
1450
+
958
1451
  /**
959
1452
  * A field configuration - either a divider or a field definition
960
1453
  */
@@ -1035,6 +1528,20 @@ declare namespace Footer_3 {
1035
1528
  var displayName: string;
1036
1529
  }
1037
1530
 
1531
+ /** Groups related menu items with the corresponding label. */
1532
+ declare function Group({ ...props }: React_2.ComponentProps<typeof Menu_2.Group>): JSX.Element;
1533
+
1534
+ declare namespace Group {
1535
+ var displayName: string;
1536
+ }
1537
+
1538
+ /** An accessible label that is automatically associated with its parent group. */
1539
+ declare function GroupLabel({ className, ...props }: React_2.ComponentProps<typeof Menu_2.GroupLabel>): JSX.Element;
1540
+
1541
+ declare namespace GroupLabel {
1542
+ var displayName: string;
1543
+ }
1544
+
1038
1545
  /**
1039
1546
  * Guard function type.
1040
1547
  * Guards are executed in order and stop on the first non-pass result.
@@ -1181,6 +1688,25 @@ export declare type InputProps = React_2.ComponentProps<"input">;
1181
1688
  */
1182
1689
  declare type IsEmptyObject<T> = keyof T extends never ? true : false;
1183
1690
 
1691
+ /** An individual interactive item in the menu. */
1692
+ declare function Item({ className, ...props }: React_2.ComponentProps<typeof Menu_2.Item>): JSX.Element;
1693
+
1694
+ declare namespace Item {
1695
+ var displayName: string;
1696
+ }
1697
+
1698
+ /**
1699
+ * A group of items with a label, used by Select, Combobox, and Autocomplete standalone components.
1700
+ *
1701
+ * Items are identified as groups by the presence of `label: string` and `items: T[]` fields.
1702
+ * Avoid item types whose shape coincidentally matches this structure, as they will be
1703
+ * silently treated as group containers at both the type level and runtime.
1704
+ */
1705
+ export declare interface ItemGroup<T> {
1706
+ label: string;
1707
+ items: T[];
1708
+ }
1709
+
1184
1710
  /**
1185
1711
  * Ensures that other locales have the same label structure as the base definition.
1186
1712
  * For dynamic labels (functions), the props type must match.
@@ -1290,10 +1816,56 @@ export declare interface LayoutProps {
1290
1816
 
1291
1817
  export { Link }
1292
1818
 
1819
+ /** A link item in the menu that can be used to navigate to a different page. */
1820
+ declare function LinkItem({ className, ...props }: React_2.ComponentProps<typeof Menu_2.LinkItem>): JSX.Element;
1821
+
1822
+ declare namespace LinkItem {
1823
+ var displayName: string;
1824
+ }
1825
+
1293
1826
  declare type LoaderHandler = (args: LoaderFunctionArgs) => Promise<unknown> | unknown;
1294
1827
 
1295
1828
  declare type LocalizedString = string | ((locale: string) => string);
1296
1829
 
1830
+ /** Shape returned by `mapItem` to describe how an item appears in the dropdown. */
1831
+ export declare interface MappedItem {
1832
+ /** Display text — used for filtering, a11y, and fallback display. */
1833
+ label: string;
1834
+ /** React key for list reconciliation. Defaults to `label`. */
1835
+ key?: string;
1836
+ /** Custom JSX to render in the dropdown. Defaults to `label`. */
1837
+ render?: React_2.ReactNode;
1838
+ }
1839
+
1840
+ export declare const Menu: {
1841
+ Root: typeof Root_3;
1842
+ Trigger: typeof Trigger_2;
1843
+ Content: typeof Content_2;
1844
+ Item: typeof Item;
1845
+ LinkItem: typeof LinkItem;
1846
+ CheckboxItem: typeof CheckboxItem;
1847
+ CheckboxItemIndicator: typeof CheckboxItemIndicator;
1848
+ RadioItem: typeof RadioItem;
1849
+ RadioItemIndicator: typeof RadioItemIndicator;
1850
+ RadioGroup: typeof RadioGroup;
1851
+ Group: typeof Group;
1852
+ GroupLabel: typeof GroupLabel;
1853
+ Separator: typeof MenuSeparator;
1854
+ SubmenuRoot: typeof SubmenuRoot;
1855
+ SubmenuTrigger: typeof SubmenuTrigger;
1856
+ };
1857
+
1858
+ declare type MenuRootProps = Pick<React_2.ComponentProps<typeof Menu_2.Root>, "open" | "defaultOpen" | "onOpenChange" | "modal" | "disabled"> & {
1859
+ children: React_2.ReactNode;
1860
+ };
1861
+
1862
+ /** A visual separator between menu items. */
1863
+ declare function MenuSeparator({ className, ...props }: React_2.ComponentProps<typeof Menu_2.Separator>): JSX.Element;
1864
+
1865
+ declare namespace MenuSeparator {
1866
+ var displayName: string;
1867
+ }
1868
+
1297
1869
  /**
1298
1870
  * A resource that can be included in the root-level content in the navigation.
1299
1871
  */
@@ -1356,6 +1928,8 @@ export declare type PageMeta = {
1356
1928
  */
1357
1929
  export declare const pass: () => GuardResult;
1358
1930
 
1931
+ /* Excluded from this release type: PositionProps */
1932
+
1359
1933
  /** Provides shared delay configuration for nested tooltips. */
1360
1934
  declare function Provider({ delay, children, ...props }: ProviderProps): JSX.Element;
1361
1935
 
@@ -1367,6 +1941,27 @@ declare type ProviderProps = Pick<React_2.ComponentProps<typeof Tooltip_2.Provid
1367
1941
  children: React_2.ReactNode;
1368
1942
  };
1369
1943
 
1944
+ /** Groups related radio items. */
1945
+ declare function RadioGroup({ ...props }: React_2.ComponentProps<typeof Menu_2.RadioGroup>): JSX.Element;
1946
+
1947
+ declare namespace RadioGroup {
1948
+ var displayName: string;
1949
+ }
1950
+
1951
+ /** A menu item that works like a radio button in a given group. */
1952
+ declare function RadioItem({ className, ...props }: React_2.ComponentProps<typeof Menu_2.RadioItem>): JSX.Element;
1953
+
1954
+ declare namespace RadioItem {
1955
+ var displayName: string;
1956
+ }
1957
+
1958
+ /** Indicates whether the radio item is selected. */
1959
+ declare function RadioItemIndicator({ className, ...props }: React_2.ComponentProps<typeof Menu_2.RadioItemIndicator>): JSX.Element;
1960
+
1961
+ declare namespace RadioItemIndicator {
1962
+ var displayName: string;
1963
+ }
1964
+
1370
1965
  /**
1371
1966
  * Redirect to another path.
1372
1967
  *
@@ -1473,6 +2068,28 @@ declare namespace Root_2 {
1473
2068
  var displayName: string;
1474
2069
  }
1475
2070
 
2071
+ /**
2072
+ * The root component that manages menu open/close state.
2073
+ *
2074
+ * @example
2075
+ * ```tsx
2076
+ * <Menu.Root>
2077
+ * <Menu.Trigger>Open menu</Menu.Trigger>
2078
+ * <Menu.Content>
2079
+ * <Menu.Item>Edit</Menu.Item>
2080
+ * <Menu.Item>Duplicate</Menu.Item>
2081
+ * <Menu.Separator />
2082
+ * <Menu.Item>Delete</Menu.Item>
2083
+ * </Menu.Content>
2084
+ * </Menu.Root>
2085
+ * ```
2086
+ */
2087
+ declare function Root_3({ children, ...props }: MenuRootProps): JSX.Element;
2088
+
2089
+ declare namespace Root_3 {
2090
+ var displayName: string;
2091
+ }
2092
+
1476
2093
  /**
1477
2094
  * The root component that manages sheet open/close state.
1478
2095
  * The `side` prop controls which edge of the screen the sheet slides in from.
@@ -1493,9 +2110,9 @@ declare namespace Root_2 {
1493
2110
  * </Sheet.Root>
1494
2111
  * ```
1495
2112
  */
1496
- declare function Root_3({ side, ...props }: SheetRootProps): JSX.Element;
2113
+ declare function Root_4({ side, ...props }: SheetRootProps): JSX.Element;
1497
2114
 
1498
- declare namespace Root_3 {
2115
+ declare namespace Root_4 {
1499
2116
  var displayName: string;
1500
2117
  }
1501
2118
 
@@ -1512,9 +2129,9 @@ declare namespace Root_3 {
1512
2129
  * </Tooltip.Root>
1513
2130
  * ```
1514
2131
  */
1515
- declare function Root_4({ children, ...props }: TooltipRootProps): JSX.Element;
2132
+ declare function Root_5({ children, ...props }: TooltipRootProps): JSX.Element;
1516
2133
 
1517
- declare namespace Root_4 {
2134
+ declare namespace Root_5 {
1518
2135
  var displayName: string;
1519
2136
  }
1520
2137
 
@@ -1547,6 +2164,156 @@ declare namespace Row {
1547
2164
  var displayName: string;
1548
2165
  }
1549
2166
 
2167
+ export declare const Select: typeof SelectStandalone & {
2168
+ Async: typeof SelectAsyncStandalone;
2169
+ Parts: {
2170
+ Root: typeof SelectRoot;
2171
+ Trigger: typeof SelectTrigger;
2172
+ Value: typeof SelectValue;
2173
+ Content: typeof SelectContent;
2174
+ Item: typeof SelectItem;
2175
+ Group: typeof SelectGroup;
2176
+ GroupLabel: typeof SelectGroupLabel;
2177
+ Separator: SelectSeparator;
2178
+ };
2179
+ };
2180
+
2181
+ /**
2182
+ * Fetcher type for `Select.Async`.
2183
+ *
2184
+ * Unlike `ComboboxAsyncFetcher` and `AutocompleteAsyncFetcher`, this fetcher
2185
+ * does **not** receive a `query` string — Select has no search input.
2186
+ * It is called each time the dropdown is opened (not per-keystroke).
2187
+ *
2188
+ * Receives an `AbortSignal` so in-flight requests are cancelled
2189
+ * when the component unmounts or the dropdown is re-opened before
2190
+ * the previous request completes.
2191
+ *
2192
+ * Note: `Select.Async` does not support `ItemGroup<T>[]` — the fetcher
2193
+ * must return a flat array.
2194
+ *
2195
+ * If caching or deduplication is needed, implement it in the fetcher
2196
+ * (e.g. via a query library or a simple cache layer).
2197
+ *
2198
+ * **Error handling:** Errors should be handled inside the fetcher.
2199
+ * If the fetcher throws, the component silently falls back to an empty
2200
+ * item list — there is no `onError` callback. Catch errors in the
2201
+ * fetcher to show toasts, log to error tracking, or return fallback data.
2202
+ */
2203
+ export declare type SelectAsyncFetcher<T> = (options: {
2204
+ signal: AbortSignal;
2205
+ }) => Promise<T[]>;
2206
+
2207
+ declare interface SelectAsyncOwnProps<T> {
2208
+ /** Fetcher for async item loading. Called each time the dropdown is opened. */
2209
+ fetcher: SelectAsyncFetcher<T>;
2210
+ /** Text shown while loading. @default "Loading..." */
2211
+ loadingText?: string;
2212
+ }
2213
+
2214
+ declare type SelectAsyncProps<T> = (SelectAsyncOwnProps<T> & SelectPropsSingle<T>) | (SelectAsyncOwnProps<T> & SelectPropsMultiple<T>);
2215
+
2216
+ declare function SelectAsyncStandalone<T>(props: SelectAsyncProps<T>): JSX.Element;
2217
+
2218
+ declare function SelectContent({ className, ...props }: React_2.ComponentProps<typeof Select_2.Popup>): JSX.Element;
2219
+
2220
+ declare namespace SelectContent {
2221
+ var displayName: string;
2222
+ }
2223
+
2224
+ declare function SelectGroup({ ...props }: React_2.ComponentProps<typeof Select_2.Group>): JSX.Element;
2225
+
2226
+ declare namespace SelectGroup {
2227
+ var displayName: string;
2228
+ }
2229
+
2230
+ declare function SelectGroupLabel({ className, ...props }: React_2.ComponentProps<typeof Select_2.GroupLabel>): JSX.Element;
2231
+
2232
+ declare namespace SelectGroupLabel {
2233
+ var displayName: string;
2234
+ }
2235
+
2236
+ declare function SelectItem({ className, children, ...props }: React_2.ComponentProps<typeof Select_2.Item>): JSX.Element;
2237
+
2238
+ declare namespace SelectItem {
2239
+ var displayName: string;
2240
+ }
2241
+
2242
+ declare interface SelectPropsBase<T> {
2243
+ /** Placeholder text shown when no value is selected */
2244
+ placeholder?: string;
2245
+ /** Map each item to its label, key, and optional custom render. */
2246
+ mapItem?: (item: T) => MappedItem;
2247
+ /** Additional className for the root container */
2248
+ className?: string;
2249
+ /** Whether the select is disabled */
2250
+ disabled?: boolean;
2251
+ }
2252
+
2253
+ declare interface SelectPropsMultiple<T> extends SelectPropsBase<T> {
2254
+ multiple: true;
2255
+ /** Current value (controlled) */
2256
+ value?: T[];
2257
+ /** Default value (uncontrolled) */
2258
+ defaultValue?: T[];
2259
+ /** Called when the selected values change */
2260
+ onValueChange?: (value: T[]) => void;
2261
+ /** Custom render function for the selected values display */
2262
+ renderValue?: (value: T[]) => React_2.ReactNode;
2263
+ }
2264
+
2265
+ declare interface SelectPropsSingle<T> extends SelectPropsBase<T> {
2266
+ multiple?: false | undefined;
2267
+ /** Current value (controlled) */
2268
+ value?: T | null;
2269
+ /** Default value (uncontrolled) */
2270
+ defaultValue?: T | null;
2271
+ /** Called when the selected value changes */
2272
+ onValueChange?: (value: T | null) => void;
2273
+ /** Custom render function for the selected value display */
2274
+ renderValue?: (value: T | null) => React_2.ReactNode;
2275
+ }
2276
+
2277
+ declare function SelectRoot<Value, Multiple extends boolean | undefined = false>(props: SelectRootProps<Value, Multiple>): JSX.Element;
2278
+
2279
+ declare namespace SelectRoot {
2280
+ var displayName: string;
2281
+ }
2282
+
2283
+ declare type SelectRootProps<Value, Multiple extends boolean | undefined = false> = Pick<React_2.ComponentProps<typeof Select_2.Root<Value, Multiple>>, "value" | "defaultValue" | "onValueChange" | "open" | "onOpenChange" | "multiple" | "itemToStringLabel" | "disabled" | "children">;
2284
+
2285
+ declare function SelectSeparator({ className, ...props }: React_2.ComponentProps<"div">): JSX.Element;
2286
+
2287
+ declare namespace SelectSeparator {
2288
+ var displayName: string;
2289
+ }
2290
+
2291
+ declare function SelectStandalone<I>(props: SelectStandaloneProps<I>): JSX.Element;
2292
+
2293
+ /**
2294
+ * @property items - Items to display. May be a flat array of `T` or an array of
2295
+ * `ItemGroup<T>`. Items are identified as groups by the presence of
2296
+ * `label: string` and `items: T[]` fields — avoid item types whose
2297
+ * shape coincidentally matches this structure.
2298
+ */
2299
+ declare type SelectStandaloneProps<I> = ({
2300
+ items: I[];
2301
+ } & SelectPropsSingle<ExtractItem<I>>) | ({
2302
+ items: I[];
2303
+ } & SelectPropsMultiple<ExtractItem<I>>);
2304
+
2305
+ declare function SelectTrigger({ className, children, ...props }: React_2.ComponentProps<typeof Select_2.Trigger>): JSX.Element;
2306
+
2307
+ declare namespace SelectTrigger {
2308
+ var displayName: string;
2309
+ }
2310
+
2311
+ declare function SelectValue({ ...props }: React_2.ComponentProps<typeof Select_2.Value>): JSX.Element;
2312
+
2313
+ declare namespace SelectValue {
2314
+ var displayName: string;
2315
+ }
2316
+
1550
2317
  declare type SharedAppShellProps = React.PropsWithChildren<{
1551
2318
  /**
1552
2319
  * App shell title
@@ -1637,10 +2404,10 @@ declare type SharedAppShellProps = React.PropsWithChildren<{
1637
2404
  }>;
1638
2405
 
1639
2406
  export declare const Sheet: {
1640
- Root: typeof Root_3;
1641
- Trigger: typeof Trigger_2;
2407
+ Root: typeof Root_4;
2408
+ Trigger: typeof Trigger_3;
1642
2409
  Close: typeof Close_2;
1643
- Content: typeof Content_2;
2410
+ Content: typeof Content_3;
1644
2411
  Header: typeof Header_4;
1645
2412
  Footer: typeof Footer_3;
1646
2413
  Title: typeof Title_2;
@@ -1834,6 +2601,24 @@ export declare type SidebarLayoutProps = {
1834
2601
  */
1835
2602
  export declare const SidebarSeparator: () => JSX.Element;
1836
2603
 
2604
+ /** Groups all parts of a submenu. */
2605
+ declare function SubmenuRoot({ children, ...props }: SubmenuRootProps): JSX.Element;
2606
+
2607
+ declare namespace SubmenuRoot {
2608
+ var displayName: string;
2609
+ }
2610
+
2611
+ declare type SubmenuRootProps = Pick<React_2.ComponentProps<typeof Menu_2.SubmenuRoot>, "open" | "defaultOpen" | "onOpenChange" | "disabled"> & {
2612
+ children: React_2.ReactNode;
2613
+ };
2614
+
2615
+ /** A menu item that opens a submenu. */
2616
+ declare function SubmenuTrigger({ className, ...props }: React_2.ComponentProps<typeof Menu_2.SubmenuTrigger>): JSX.Element;
2617
+
2618
+ declare namespace SubmenuTrigger {
2619
+ var displayName: string;
2620
+ }
2621
+
1837
2622
  export declare const Table: {
1838
2623
  Root: typeof Root;
1839
2624
  Header: typeof Header_2;
@@ -1868,9 +2653,9 @@ declare namespace Title_2 {
1868
2653
  }
1869
2654
 
1870
2655
  export declare const Tooltip: {
1871
- Root: typeof Root_4;
1872
- Trigger: typeof Trigger_3;
1873
- Content: typeof Content_3;
2656
+ Root: typeof Root_5;
2657
+ Trigger: typeof Trigger_4;
2658
+ Content: typeof Content_4;
1874
2659
  Provider: typeof Provider;
1875
2660
  };
1876
2661
 
@@ -1885,20 +2670,27 @@ declare namespace Trigger {
1885
2670
  var displayName: string;
1886
2671
  }
1887
2672
 
1888
- /** The element that opens the sheet when clicked. */
1889
- declare function Trigger_2({ ...props }: React_2.ComponentProps<typeof Drawer.Trigger>): JSX.Element;
2673
+ /** The element that opens the menu when clicked. */
2674
+ declare function Trigger_2({ ...props }: React_2.ComponentProps<typeof Menu_2.Trigger>): JSX.Element;
1890
2675
 
1891
2676
  declare namespace Trigger_2 {
1892
2677
  var displayName: string;
1893
2678
  }
1894
2679
 
1895
- /** The element that triggers the tooltip on hover or focus. */
1896
- declare function Trigger_3({ ...props }: React_2.ComponentProps<typeof Tooltip_2.Trigger>): JSX.Element;
2680
+ /** The element that opens the sheet when clicked. */
2681
+ declare function Trigger_3({ ...props }: React_2.ComponentProps<typeof Drawer.Trigger>): JSX.Element;
1897
2682
 
1898
2683
  declare namespace Trigger_3 {
1899
2684
  var displayName: string;
1900
2685
  }
1901
2686
 
2687
+ /** The element that triggers the tooltip on hover or focus. */
2688
+ declare function Trigger_4({ ...props }: React_2.ComponentProps<typeof Tooltip_2.Trigger>): JSX.Element;
2689
+
2690
+ declare namespace Trigger_4 {
2691
+ var displayName: string;
2692
+ }
2693
+
1902
2694
  /**
1903
2695
  * Type-safe path builder interface.
1904
2696
  *
@@ -1951,6 +2743,130 @@ export declare const useAppShellConfig: () => AppShellConfigContextType;
1951
2743
  */
1952
2744
  export declare const useAppShellData: () => AppShellDataContextType;
1953
2745
 
2746
+ /**
2747
+ * Hook that encapsulates the async combobox pattern — debounced fetching,
2748
+ * request cancellation via `AbortController`, and loading state.
2749
+ *
2750
+ * Pass `filter={null}` to `<Combobox.Root>` to disable internal filtering
2751
+ * since items are already filtered by the remote source.
2752
+ *
2753
+ * @example
2754
+ * ```tsx
2755
+ * const countries = Combobox.useAsync({
2756
+ * fetcher: async (query, { signal }) => {
2757
+ * const res = await fetch(
2758
+ * `https://restcountries.com/v3.1/name/${query}`,
2759
+ * { signal },
2760
+ * );
2761
+ * if (!res.ok) return [];
2762
+ * return res.json();
2763
+ * },
2764
+ * });
2765
+ *
2766
+ * // Or with custom debounce:
2767
+ * const countries = Combobox.useAsync({
2768
+ * fetcher: {
2769
+ * fn: async (query, { signal }) => { ... },
2770
+ * debounceMs: 500,
2771
+ * },
2772
+ * });
2773
+ *
2774
+ * <Combobox.Root
2775
+ * items={countries.items}
2776
+ * filter={null}
2777
+ * onInputValueChange={countries.onInputValueChange}
2778
+ * >
2779
+ * ...
2780
+ * <Combobox.Empty>
2781
+ * {countries.loading ? "Loading..." : "No results."}
2782
+ * </Combobox.Empty>
2783
+ * </Combobox.Root>
2784
+ * ```
2785
+ */
2786
+ declare function useAsync<T>(options: UseAsyncItemsOptions<T>): UseAsyncItemsReturn<T>;
2787
+
2788
+ /**
2789
+ * Hook that encapsulates the async autocomplete pattern — debounced fetching,
2790
+ * request cancellation via `AbortController`, and loading state.
2791
+ *
2792
+ * Pass `filter={null}` to `<Autocomplete.Root>` to disable internal filtering
2793
+ * since items are already filtered by the remote source.
2794
+ *
2795
+ * Unlike `Combobox.useAsync`, Autocomplete's value is always the input text
2796
+ * (there is no separate `inputValue` prop), so you must pass `value` and
2797
+ * `onValueChange` instead of `onInputValueChange`.
2798
+ *
2799
+ * @example
2800
+ * ```tsx
2801
+ * const movies = Autocomplete.useAsync({
2802
+ * fetcher: async (query, { signal }) => {
2803
+ * const res = await fetch(`/api/movies?q=${query}`, { signal });
2804
+ * if (!res.ok) return [];
2805
+ * return res.json();
2806
+ * },
2807
+ * });
2808
+ *
2809
+ * // Or with custom debounce:
2810
+ * const movies = Autocomplete.useAsync({
2811
+ * fetcher: {
2812
+ * fn: async (query, { signal }) => { ... },
2813
+ * debounceMs: 500,
2814
+ * },
2815
+ * });
2816
+ *
2817
+ * <Autocomplete.Root
2818
+ * items={movies.items}
2819
+ * value={movies.value}
2820
+ * onValueChange={movies.onValueChange}
2821
+ * filter={null}
2822
+ * >
2823
+ * ...
2824
+ * <Autocomplete.Empty>
2825
+ * {movies.loading ? "Loading..." : "No results."}
2826
+ * </Autocomplete.Empty>
2827
+ * </Autocomplete.Root>
2828
+ * ```
2829
+ */
2830
+ declare function useAsync_2<T>(options: UseAsyncItemsOptions<T>): AutocompleteUseAsyncReturn<T>;
2831
+
2832
+ declare interface UseAsyncItemsOptions<T> {
2833
+ /**
2834
+ * Fetcher for async item loading.
2835
+ *
2836
+ * Pass a plain function to use the default debounce delay (300ms),
2837
+ * or an object `{ fn, debounceMs }` to control the debounce timing.
2838
+ *
2839
+ * @example
2840
+ * ```tsx
2841
+ * // Plain function
2842
+ * fetcher: async (query, { signal }) => {
2843
+ * const res = await fetch(`/api/search?q=${query}`, { signal });
2844
+ * return res.json();
2845
+ * }
2846
+ *
2847
+ * // With custom debounce
2848
+ * fetcher: {
2849
+ * fn: async (query, { signal }) => { ... },
2850
+ * debounceMs: 500,
2851
+ * }
2852
+ * ```
2853
+ */
2854
+ fetcher: AsyncFetcher<T>;
2855
+ }
2856
+
2857
+ declare interface UseAsyncItemsReturn<T> {
2858
+ /** Fetched items — pass to the Root `items` prop */
2859
+ items: T[];
2860
+ /** Whether a fetch is currently in-flight */
2861
+ loading: boolean;
2862
+ /** Current input query string */
2863
+ query: string;
2864
+ /** The error thrown by the last fetch, if any */
2865
+ error: unknown;
2866
+ /** Input change handler — pass to the Root `onInputValueChange` prop */
2867
+ onInputValueChange: (value: string) => void;
2868
+ }
2869
+
1954
2870
  /**
1955
2871
  * Authentication hook.
1956
2872
  *
@@ -2038,6 +2954,153 @@ export declare const useAuthSuspense: () => {
2038
2954
  checkAuthStatus: () => Promise<AuthState>;
2039
2955
  };
2040
2956
 
2957
+ /**
2958
+ * Hook that encapsulates the "creatable" combobox pattern — allowing users
2959
+ * to create new items on-the-fly from the dropdown.
2960
+ *
2961
+ * Manages selected value, input query, and sentinel item injection internally.
2962
+ * Supports both single and multiple select.
2963
+ *
2964
+ * @example
2965
+ * ```tsx
2966
+ * // Sync
2967
+ * onItemCreated: (item) => {
2968
+ * setItems((prev) => [...prev, item]);
2969
+ * }
2970
+ *
2971
+ * // Async — return server-assigned item to use as selected value
2972
+ * onItemCreated: async (item) => {
2973
+ * const saved = await api.create(item);
2974
+ * setItems((prev) => [...prev, saved]);
2975
+ * return saved;
2976
+ * }
2977
+ *
2978
+ * // Cancel via return false
2979
+ * onItemCreated: async (item) => {
2980
+ * const ok = await confirm("Create?");
2981
+ * if (!ok) return false;
2982
+ * setItems((prev) => [...prev, item]);
2983
+ * }
2984
+ * ```
2985
+ */
2986
+ declare function useCreatable<T extends object>(options: UseCreatableOptionsMultiple<T>): UseCreatableReturnMultiple<T>;
2987
+
2988
+ declare function useCreatable<T extends object>(options: UseCreatableOptionsSingle<T>): UseCreatableReturnSingle<T>;
2989
+
2990
+ declare function useCreatable<T extends object>(options: UseCreatableOptionsCombined<T>): UseCreatableReturnMultiple<T> | UseCreatableReturnSingle<T>;
2991
+
2992
+ declare interface UseCreatableOptionsBase<T extends object> {
2993
+ /** Current items list (managed externally since items may come from API) */
2994
+ items: T[];
2995
+ /** Extract display label from an item */
2996
+ getLabel: (item: T) => string;
2997
+ /** Factory to create a new item from user input string */
2998
+ createItem: (value: string) => T;
2999
+ /**
3000
+ * Called when a new item is created via the "create" option.
3001
+ *
3002
+ * Return values control what happens next:
3003
+ * - `void` / `undefined` — accept the item produced by `createItem` as-is
3004
+ * - `T` — accept, but use the returned item instead (e.g. item with server-assigned ID)
3005
+ * - `false` — cancel the creation (item is NOT selected)
3006
+ *
3007
+ * May return a `Promise` for async workflows (API calls, confirmation dialogs, etc.).
3008
+ * A rejected promise also cancels the creation.
3009
+ *
3010
+ * If not provided, created items are added to the selection immediately.
3011
+ *
3012
+ * @example
3013
+ * ```tsx
3014
+ * // Sync
3015
+ * onItemCreated: (item) => {
3016
+ * setItems(prev => [...prev, item]);
3017
+ * }
3018
+ *
3019
+ * // Async — return server-assigned item
3020
+ * onItemCreated: async (item) => {
3021
+ * const saved = await api.create(item);
3022
+ * setItems(prev => [...prev, saved]);
3023
+ * return saved;
3024
+ * }
3025
+ *
3026
+ * // Cancel
3027
+ * onItemCreated: async (item) => {
3028
+ * const ok = await confirm("Create?");
3029
+ * if (!ok) return false;
3030
+ * setItems(prev => [...prev, item]);
3031
+ * }
3032
+ * ```
3033
+ */
3034
+ onItemCreated?: (item: T) => void | false | T | Promise<void | false | T>;
3035
+ /**
3036
+ * Format the label for the "create" option in the dropdown.
3037
+ * Useful for i18n (e.g. Japanese: `(v) => \`「${v}」を作成\``).
3038
+ * @default (value) => \`Create "${value}"\`
3039
+ */
3040
+ formatCreateLabel?: (value: string) => string;
3041
+ }
3042
+
3043
+ /**
3044
+ * Combined options type for callers that don't know single vs multiple at compile time.
3045
+ * Accepts the union of both value shapes.
3046
+ */
3047
+ declare interface UseCreatableOptionsCombined<T extends object> extends UseCreatableOptionsBase<T> {
3048
+ multiple?: boolean;
3049
+ defaultValue?: T[] | T | null;
3050
+ onValueChange?: ((value: T[]) => void) | ((value: T | null) => void);
3051
+ }
3052
+
3053
+ declare interface UseCreatableOptionsMultiple<T extends object> extends UseCreatableOptionsBase<T> {
3054
+ multiple: true;
3055
+ defaultValue?: T[];
3056
+ /** Called when selection changes (sentinel items are already excluded) */
3057
+ onValueChange?: (value: T[]) => void;
3058
+ }
3059
+
3060
+ declare interface UseCreatableOptionsSingle<T extends object> extends UseCreatableOptionsBase<T> {
3061
+ multiple?: false | undefined;
3062
+ defaultValue?: T | null;
3063
+ /** Called when selection changes */
3064
+ onValueChange?: (value: T | null) => void;
3065
+ }
3066
+
3067
+ declare interface UseCreatableReturnBase<T> {
3068
+ /** Items list with "create" sentinel appended when query has no exact match */
3069
+ items: T[];
3070
+ /** Current input query — pass to `Combobox.Root inputValue` */
3071
+ inputValue: string;
3072
+ /** Input change handler — pass to `Combobox.Root onInputValueChange` */
3073
+ onInputValueChange: (value: string) => void;
3074
+ /** Converts item to display label — pass to `Combobox.Root itemToStringLabel` */
3075
+ itemToStringLabel: (item: T) => string;
3076
+ /** Converts item to form value — pass to `Combobox.Root itemToStringValue` */
3077
+ itemToStringValue: (item: T) => string;
3078
+ /** Check if an item is the "create" sentinel */
3079
+ isCreateItem: (item: T) => boolean;
3080
+ /** Get the original input value from a sentinel item */
3081
+ getCreateLabel: (item: T) => string | undefined;
3082
+ /** The active formatCreateLabel function */
3083
+ formatCreateLabel: (value: string) => string;
3084
+ /** `true` while an async `onItemCreated` callback is in-flight */
3085
+ creating: boolean;
3086
+ }
3087
+
3088
+ declare interface UseCreatableReturnMultiple<T> extends UseCreatableReturnBase<T> {
3089
+ /** Current selected values */
3090
+ value: T[];
3091
+ /** Value change handler — pass to `Combobox.Root onValueChange` */
3092
+ onValueChange: (value: T[]) => void;
3093
+ multiple: true;
3094
+ }
3095
+
3096
+ declare interface UseCreatableReturnSingle<T> extends UseCreatableReturnBase<T> {
3097
+ /** Current selected value */
3098
+ value: T | null;
3099
+ /** Value change handler — pass to `Combobox.Root onValueChange` */
3100
+ onValueChange: (value: T | null) => void;
3101
+ multiple: false;
3102
+ }
3103
+
2041
3104
  export { useLocation }
2042
3105
 
2043
3106
  export { useNavigate }