@foundrykit/components 1.0.18 → 1.0.20

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.
@@ -24,20 +24,80 @@ import type {
24
24
  SearchSection as SearchSectionType,
25
25
  } from '@foundrykit/types';
26
26
 
27
- // Provider Component
27
+ /**
28
+ * Props for the AdvancedSearchProvider component.
29
+ * This provider manages the search state and behavior for all child components.
30
+ */
28
31
  export interface AdvancedSearchProviderProps {
32
+ /** Child components that will have access to the search context */
29
33
  children: React.ReactNode;
34
+ /**
35
+ * Function called when user types in the search input.
36
+ * Should return a Promise or array of SearchResult objects.
37
+ * @param query - The search query string
38
+ * @returns Promise<SearchResult[]> | SearchResult[] - Array of search results
39
+ */
30
40
  onSearch?: (query: string) => Promise<SearchResult[]> | SearchResult[];
41
+ /**
42
+ * Function called when user selects a result from the dropdown.
43
+ * @param result - The selected SearchResult object
44
+ */
31
45
  onResultSelect?: (result: SearchResult) => void;
46
+ /**
47
+ * Debounce delay in milliseconds for search requests.
48
+ * @default 300
49
+ */
32
50
  debounceMs?: number;
51
+ /**
52
+ * Minimum number of characters required before triggering search.
53
+ * @default 1
54
+ */
33
55
  minQueryLength?: number;
56
+ /**
57
+ * Behavior when search results are empty or query is too short.
58
+ * - 'show-empty-message': Show "No results found" message
59
+ * - 'hide-until-min-chars': Hide results until minimum characters typed
60
+ * - 'show-all-results': Show initial results when empty
61
+ * @default 'show-empty-message'
62
+ */
34
63
  emptyStateBehavior?: EmptyStateBehavior;
64
+ /**
65
+ * Initial results to show when component first loads.
66
+ * Useful for showing popular/recent searches.
67
+ */
35
68
  initialResults?: SearchResult[];
69
+ /**
70
+ * Custom styles for different parts of the search component.
71
+ */
36
72
  styles?: {
73
+ /** CSS properties for the results dropdown */
37
74
  results: React.CSSProperties;
38
75
  };
39
76
  }
40
77
 
78
+ /**
79
+ * AdvancedSearchProvider component that manages search state and provides context to child components.
80
+ *
81
+ * @example
82
+ * ```tsx
83
+ * <AdvancedSearchProvider
84
+ * onSearch={async (query) => {
85
+ * const results = await searchAPI(query);
86
+ * return results;
87
+ * }}
88
+ * onResultSelect={(result) => {
89
+ * console.log('Selected:', result);
90
+ * }}
91
+ * emptyStateBehavior="show-all-results"
92
+ * initialResults={popularDestinations}
93
+ * >
94
+ * <AdvancedSearchBar>
95
+ * <SearchInput placeholder="Search destinations..." />
96
+ * <SearchResults />
97
+ * </AdvancedSearchBar>
98
+ * </AdvancedSearchProvider>
99
+ * ```
100
+ */
41
101
  export function AdvancedSearchProvider({
42
102
  children,
43
103
  onSearch,
@@ -156,7 +216,10 @@ export function AdvancedSearchProvider({
156
216
  );
157
217
  }
158
218
 
159
- // Search Input Wrapper Variants
219
+ /**
220
+ * Variant styles for the search input wrapper.
221
+ * Controls the size and visual appearance of the search input container.
222
+ */
160
223
  const searchInputWrapperVariants = cva('relative flex items-center w-full', {
161
224
  variants: {
162
225
  size: {
@@ -177,7 +240,10 @@ const searchInputWrapperVariants = cva('relative flex items-center w-full', {
177
240
  },
178
241
  });
179
242
 
180
- // Search Results Variants
243
+ /**
244
+ * Variant styles for the search results container.
245
+ * Controls the maximum width of the search results dropdown.
246
+ */
181
247
  const searchResultsVariants = cva('w-full', {
182
248
  variants: {
183
249
  size: {
@@ -194,17 +260,40 @@ const searchResultsVariants = cva('w-full', {
194
260
  },
195
261
  });
196
262
 
197
- // Search Input Component
263
+ /**
264
+ * Props for the SearchInput component.
265
+ * Extends standard input props with search-specific functionality.
266
+ */
198
267
  export interface SearchInputProps
199
268
  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'>,
200
269
  VariantProps<typeof searchInputWrapperVariants> {
270
+ /** Placeholder text shown when input is empty */
201
271
  placeholder?: string;
272
+ /** Whether to show the search icon on the left side */
202
273
  showSearchIcon?: boolean;
274
+ /** Whether to show the clear button when there's text */
203
275
  showClearButton?: boolean;
276
+ /** Callback function called when clear button is clicked */
204
277
  onClear?: () => void;
278
+ /** Whether to render as a child component using Slot */
205
279
  asChild?: boolean;
206
280
  }
207
281
 
282
+ /**
283
+ * SearchInput component that provides a search input field with optional search icon and clear button.
284
+ * Automatically integrates with the search context to handle query state and search triggering.
285
+ *
286
+ * @example
287
+ * ```tsx
288
+ * <SearchInput
289
+ * placeholder="Search destinations..."
290
+ * size="lg"
291
+ * variant="default"
292
+ * showSearchIcon={true}
293
+ * showClearButton={true}
294
+ * />
295
+ * ```
296
+ */
208
297
  export const SearchInput = React.forwardRef<HTMLInputElement, SearchInputProps>(
209
298
  (
210
299
  {
@@ -317,12 +406,30 @@ export const SearchInput = React.forwardRef<HTMLInputElement, SearchInputProps>(
317
406
  );
318
407
  SearchInput.displayName = 'SearchInput';
319
408
 
320
- // Search Trigger Component
409
+ /**
410
+ * Props for the SearchTrigger component.
411
+ * Used to create custom trigger buttons that open the search dropdown.
412
+ */
321
413
  export interface SearchTriggerProps
322
414
  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
415
+ /** Whether to render as a child component using Slot */
323
416
  asChild?: boolean;
324
417
  }
325
418
 
419
+ /**
420
+ * SearchTrigger component that creates a button to open/close the search dropdown.
421
+ * Can be used with asChild to wrap custom button components.
422
+ *
423
+ * @example
424
+ * ```tsx
425
+ * <SearchTrigger asChild>
426
+ * <Button variant="outline" className="w-full justify-start">
427
+ * <Search className="mr-2 h-4 w-4" />
428
+ * Click to search...
429
+ * </Button>
430
+ * </SearchTrigger>
431
+ * ```
432
+ */
326
433
  export const SearchTrigger = React.forwardRef<
327
434
  HTMLButtonElement,
328
435
  SearchTriggerProps
@@ -343,17 +450,40 @@ export const SearchTrigger = React.forwardRef<
343
450
  });
344
451
  SearchTrigger.displayName = 'SearchTrigger';
345
452
 
346
- // Search Results Component
453
+ /**
454
+ * Props for the SearchResults component.
455
+ * Displays the search results in a scrollable dropdown with customizable sections.
456
+ */
347
457
  export interface SearchResultsProps
348
458
  extends React.HTMLAttributes<HTMLDivElement>,
349
459
  VariantProps<typeof searchResultsVariants> {
460
+ /** Custom sections to display instead of default results */
350
461
  sections?: SearchSectionType[];
462
+ /** Whether to show empty state message when no results */
351
463
  showEmptyState?: boolean;
464
+ /** Custom message to show when no results are found */
352
465
  emptyStateMessage?: string;
466
+ /** Whether to show loading state while searching */
353
467
  showLoadingState?: boolean;
468
+ /** Custom message to show while loading */
354
469
  loadingMessage?: string;
355
470
  }
356
471
 
472
+ /**
473
+ * SearchResults component that displays search results in a scrollable dropdown.
474
+ * Automatically handles loading states, empty states, and result selection.
475
+ *
476
+ * @example
477
+ * ```tsx
478
+ * <SearchResults
479
+ * size="lg"
480
+ * showEmptyState={true}
481
+ * emptyStateMessage="No destinations found."
482
+ * showLoadingState={true}
483
+ * loadingMessage="Searching destinations..."
484
+ * />
485
+ * ```
486
+ */
357
487
  export const SearchResults = React.forwardRef<
358
488
  HTMLDivElement,
359
489
  SearchResultsProps
@@ -484,9 +614,14 @@ export const SearchResults = React.forwardRef<
484
614
  );
485
615
  SearchResults.displayName = 'SearchResults';
486
616
 
487
- // Search Result Item Component
617
+ /**
618
+ * Props for the SearchResultItem component.
619
+ * Internal component used to render individual search results.
620
+ */
488
621
  interface SearchResultItemProps {
622
+ /** The search result data to display */
489
623
  result: SearchResult;
624
+ /** Callback function called when the result is clicked */
490
625
  onClick: () => void;
491
626
  }
492
627
 
@@ -550,13 +685,30 @@ const SearchResultItem = ({ result, onClick }: SearchResultItemProps) => {
550
685
  );
551
686
  };
552
687
 
553
- // Main Advanced Search Bar Component (Compound Pattern)
688
+ /**
689
+ * Props for the AdvancedSearchBar component.
690
+ * Main container component that orchestrates the search input and results dropdown.
691
+ */
554
692
  export interface AdvancedSearchBarProps
555
693
  extends React.HTMLAttributes<HTMLDivElement> {
694
+ /** Controlled open state of the results dropdown */
556
695
  open?: boolean;
696
+ /** Callback function called when open state changes */
557
697
  onOpenChange?: (open: boolean) => void;
558
698
  }
559
699
 
700
+ /**
701
+ * AdvancedSearchBar component that provides the main search interface.
702
+ * Combines search input with results dropdown in a compound pattern.
703
+ *
704
+ * @example
705
+ * ```tsx
706
+ * <AdvancedSearchBar>
707
+ * <SearchInput placeholder="Search destinations..." />
708
+ * <SearchResults />
709
+ * </AdvancedSearchBar>
710
+ * ```
711
+ */
560
712
  export const AdvancedSearchBar = React.forwardRef<
561
713
  HTMLDivElement,
562
714
  AdvancedSearchBarProps
@@ -593,15 +745,34 @@ AdvancedSearchBar.displayName = 'AdvancedSearchBar';
593
745
 
594
746
  // Compound Pattern Components
595
747
 
596
- // Search Section Component (for compound pattern)
748
+ /**
749
+ * Props for the SearchSection component.
750
+ * Used in compound pattern to create organized sections of search results.
751
+ */
597
752
  export interface SearchSectionProps
598
753
  extends React.HTMLAttributes<HTMLDivElement> {
754
+ /** Title displayed above the section results */
599
755
  title?: string;
756
+ /** Maximum number of results to show in this section */
600
757
  maxResults?: number;
758
+ /** Whether to show a "Show more" button */
601
759
  showMore?: boolean;
760
+ /** Callback function called when "Show more" is clicked */
602
761
  onShowMore?: () => void;
603
762
  }
604
763
 
764
+ /**
765
+ * SearchSection component for organizing search results into sections.
766
+ * Used in compound pattern to create structured result displays.
767
+ *
768
+ * @example
769
+ * ```tsx
770
+ * <SearchSection title="Popular Searches" showMore={true} onShowMore={handleShowMore}>
771
+ * <SearchItem result={popularResult1} />
772
+ * <SearchItem result={popularResult2} />
773
+ * </SearchSection>
774
+ * ```
775
+ */
605
776
  export const SearchSection = React.forwardRef<
606
777
  HTMLDivElement,
607
778
  SearchSectionProps
@@ -632,12 +803,31 @@ export const SearchSection = React.forwardRef<
632
803
  });
633
804
  SearchSection.displayName = 'SearchSection ';
634
805
 
635
- // Search Item Component (for compound pattern)
806
+ /**
807
+ * Props for the SearchItem component.
808
+ * Used in compound pattern to render individual search result items.
809
+ */
636
810
  export interface SearchItemProps extends React.HTMLAttributes<HTMLDivElement> {
811
+ /** The search result data to display */
637
812
  result?: SearchResult;
813
+ /** Callback function called when the item is clicked */
638
814
  onClick?: () => void;
639
815
  }
640
816
 
817
+ /**
818
+ * SearchItem component for rendering individual search result items.
819
+ * Can be used with result data or custom children in compound pattern.
820
+ *
821
+ * @example
822
+ * ```tsx
823
+ * <SearchItem result={searchResult} />
824
+ *
825
+ * // Or with custom children
826
+ * <SearchItem onClick={handleClick}>
827
+ * <div>Custom result display</div>
828
+ * </SearchItem>
829
+ * ```
830
+ */
641
831
  export const SearchItem = React.forwardRef<HTMLDivElement, SearchItemProps>(
642
832
  ({ className, result, onClick, children, ...props }, ref) => {
643
833
  const { onResultSelect } = useAdvancedSearch();
@@ -743,7 +933,26 @@ export const SearchItem = React.forwardRef<HTMLDivElement, SearchItemProps>(
743
933
  );
744
934
  SearchItem.displayName = 'SearchItem';
745
935
 
746
- // Export all components with compound pattern
936
+ /**
937
+ * Compound pattern exports for the advanced search bar components.
938
+ * These provide a more intuitive API for composing search interfaces.
939
+ *
940
+ * @example
941
+ * ```tsx
942
+ * import * as SearchBar from '@/components/ui/advanced-search-bar'
943
+ *
944
+ * <SearchBar.Provider onSearch={handleSearch} onResultSelect={handleSelect}>
945
+ * <SearchBar.Root>
946
+ * <SearchBar.Input placeholder="Search..." />
947
+ * <SearchBar.Results>
948
+ * <SearchBar.Section title="Popular">
949
+ * <SearchBar.Item result={popularResult} />
950
+ * </SearchBar.Section>
951
+ * </SearchBar.Results>
952
+ * </SearchBar.Root>
953
+ * </SearchBar.Provider>
954
+ * ```
955
+ */
747
956
  export {
748
957
  AdvancedSearchBar as Root,
749
958
  SearchInput as Input,
@@ -755,19 +964,43 @@ export {
755
964
  searchResultsVariants,
756
965
  };
757
966
 
758
- // Export Provider separately to avoid conflicts
967
+ /**
968
+ * Provider component exported separately to avoid naming conflicts.
969
+ * This is the same as AdvancedSearchProvider but with a shorter name for compound pattern usage.
970
+ */
759
971
  export { AdvancedSearchProvider as Provider };
760
972
 
761
- // Wrapper component for documentation/preview purposes
973
+ /**
974
+ * Wrapper component for documentation and preview purposes.
975
+ * Provides a complete search implementation with mock data for testing and demos.
976
+ *
977
+ * @param props - Configuration props for the search wrapper
978
+ * @returns Complete search component with mock functionality
979
+ *
980
+ * @example
981
+ * ```tsx
982
+ * <AdvancedSearchBarWrapper
983
+ * emptyStateBehavior="show-all-results"
984
+ * size="lg"
985
+ * variant="default"
986
+ * useCustomTrigger={false}
987
+ * />
988
+ * ```
989
+ */
762
990
  export function AdvancedSearchBarWrapper(
763
991
  props: {
992
+ /** Minimum number of characters required before triggering search */
764
993
  minQueryLength?: number;
994
+ /** Behavior when search results are empty or query is too short */
765
995
  emptyStateBehavior?:
766
996
  | 'show-empty-message'
767
997
  | 'hide-until-min-chars'
768
998
  | 'show-all-results';
999
+ /** Size variant for the search input */
769
1000
  size?: 'sm' | 'md' | 'lg' | 'xl';
1001
+ /** Visual variant for the search input */
770
1002
  variant?: 'default' | 'ghost' | 'filled';
1003
+ /** Whether to use a custom trigger button instead of input */
771
1004
  useCustomTrigger?: boolean;
772
1005
  } = {}
773
1006
  ) {
@@ -0,0 +1,21 @@
1
+ import type { ComponentConfig } from '@foundrykit/types';
2
+
3
+ export const formConfig: ComponentConfig = {
4
+ name: 'Form',
5
+ description: 'Form component for collecting user input',
6
+ category: 'components',
7
+ tags: ['form', 'input', 'interactive'],
8
+ preview: {
9
+ type: 'static',
10
+ html: '<div class="flex h-12 w-full items-center justify-center rounded-md bg-gray-200"><div class="relative w-32"><div class="flex h-9 w-full items-center justify-between rounded-md border border-gray-300 bg-white px-3 py-2 text-sm"><span>Select option</span><div class="h-4 w-4 rotate-90 border border-gray-400"></div></div></div></div>',
11
+ },
12
+ variants: [],
13
+ files: ['components/components/form/index.tsx'],
14
+ dependencies: ['utils'],
15
+ packageDependencies: [
16
+ 'react-hook-form',
17
+ 'zod',
18
+ '@radix-ui/react-slot',
19
+ '@radix-ui/react-label',
20
+ ],
21
+ };
@@ -0,0 +1,168 @@
1
+ 'use client';
2
+
3
+ import * as React from 'react';
4
+ import * as LabelPrimitive from '@radix-ui/react-label';
5
+ import { Slot } from '@radix-ui/react-slot';
6
+ import {
7
+ Controller,
8
+ FormProvider,
9
+ useFormContext,
10
+ useFormState,
11
+ type ControllerProps,
12
+ type FieldPath,
13
+ type FieldValues,
14
+ } from 'react-hook-form';
15
+
16
+ import { cn } from '@foundrykit/utils';
17
+ import { Label } from '@foundrykit/primitives';
18
+
19
+ const Form = FormProvider;
20
+
21
+ type FormFieldContextValue<
22
+ TFieldValues extends FieldValues = FieldValues,
23
+ TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
24
+ > = {
25
+ name: TName;
26
+ };
27
+
28
+ const FormFieldContext = React.createContext<FormFieldContextValue>(
29
+ {} as FormFieldContextValue
30
+ );
31
+
32
+ const FormField = <
33
+ TFieldValues extends FieldValues = FieldValues,
34
+ TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
35
+ >({
36
+ ...props
37
+ }: ControllerProps<TFieldValues, TName>) => {
38
+ return (
39
+ <FormFieldContext.Provider value={{ name: props.name }}>
40
+ <Controller {...props} />
41
+ </FormFieldContext.Provider>
42
+ );
43
+ };
44
+
45
+ const useFormField = () => {
46
+ const fieldContext = React.useContext(FormFieldContext);
47
+ const itemContext = React.useContext(FormItemContext);
48
+ const { getFieldState } = useFormContext();
49
+ const formState = useFormState({ name: fieldContext.name });
50
+ const fieldState = getFieldState(fieldContext.name, formState);
51
+
52
+ if (!fieldContext) {
53
+ throw new Error('useFormField should be used within <FormField>');
54
+ }
55
+
56
+ const { id } = itemContext;
57
+
58
+ return {
59
+ id,
60
+ name: fieldContext.name,
61
+ formItemId: `${id}-form-item`,
62
+ formDescriptionId: `${id}-form-item-description`,
63
+ formMessageId: `${id}-form-item-message`,
64
+ ...fieldState,
65
+ };
66
+ };
67
+
68
+ type FormItemContextValue = {
69
+ id: string;
70
+ };
71
+
72
+ const FormItemContext = React.createContext<FormItemContextValue>(
73
+ {} as FormItemContextValue
74
+ );
75
+
76
+ function FormItem({ className, ...props }: React.ComponentProps<'div'>) {
77
+ const id = React.useId();
78
+
79
+ return (
80
+ <FormItemContext.Provider value={{ id }}>
81
+ <div
82
+ data-slot='form-item'
83
+ className={cn('grid gap-2', className)}
84
+ {...props}
85
+ />
86
+ </FormItemContext.Provider>
87
+ );
88
+ }
89
+
90
+ function FormLabel({
91
+ className,
92
+ ...props
93
+ }: React.ComponentProps<typeof LabelPrimitive.Root>) {
94
+ const { error, formItemId } = useFormField();
95
+
96
+ return (
97
+ <Label
98
+ data-slot='form-label'
99
+ data-error={!!error}
100
+ className={cn('data-[error=true]:text-destructive', className)}
101
+ htmlFor={formItemId}
102
+ {...props}
103
+ />
104
+ );
105
+ }
106
+
107
+ function FormControl({ ...props }: React.ComponentProps<typeof Slot>) {
108
+ const { error, formItemId, formDescriptionId, formMessageId } =
109
+ useFormField();
110
+
111
+ return (
112
+ <Slot
113
+ data-slot='form-control'
114
+ id={formItemId}
115
+ aria-describedby={
116
+ !error
117
+ ? `${formDescriptionId}`
118
+ : `${formDescriptionId} ${formMessageId}`
119
+ }
120
+ aria-invalid={!!error}
121
+ {...props}
122
+ />
123
+ );
124
+ }
125
+
126
+ function FormDescription({ className, ...props }: React.ComponentProps<'p'>) {
127
+ const { formDescriptionId } = useFormField();
128
+
129
+ return (
130
+ <p
131
+ data-slot='form-description'
132
+ id={formDescriptionId}
133
+ className={cn('text-muted-foreground text-sm', className)}
134
+ {...props}
135
+ />
136
+ );
137
+ }
138
+
139
+ function FormMessage({ className, ...props }: React.ComponentProps<'p'>) {
140
+ const { error, formMessageId } = useFormField();
141
+ const body = error ? String(error?.message ?? '') : props.children;
142
+
143
+ if (!body) {
144
+ return null;
145
+ }
146
+
147
+ return (
148
+ <p
149
+ data-slot='form-message'
150
+ id={formMessageId}
151
+ className={cn('text-destructive text-sm', className)}
152
+ {...props}
153
+ >
154
+ {body}
155
+ </p>
156
+ );
157
+ }
158
+
159
+ export {
160
+ useFormField,
161
+ Form,
162
+ FormItem,
163
+ FormLabel,
164
+ FormControl,
165
+ FormDescription,
166
+ FormMessage,
167
+ FormField,
168
+ };
package/src/index.ts CHANGED
@@ -32,6 +32,16 @@ export {
32
32
  SearchItem,
33
33
  AdvancedSearchBarWrapper,
34
34
  } from './components/advanced-search-bar/index.js';
35
+ export {
36
+ useFormField,
37
+ Form,
38
+ FormItem,
39
+ FormLabel,
40
+ FormControl,
41
+ FormDescription,
42
+ FormMessage,
43
+ FormField,
44
+ } from './components/form/index.js';
35
45
 
36
46
  // Export types from types package
37
47
  export type {