@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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # @foundrykit/components
2
2
 
3
+ ## 1.0.20
4
+
5
+ ### Patch Changes
6
+
7
+ - adding form to components package
8
+
9
+ ## 1.0.19
10
+
11
+ ### Patch Changes
12
+
13
+ - Adding in JSdocs for better DX
14
+ - Updated dependencies
15
+ - @foundrykit/hooks@1.0.8
16
+
3
17
  ## 1.0.18
4
18
 
5
19
  ### Patch Changes
package/dist/index.d.ts CHANGED
@@ -8,6 +8,10 @@ import { VariantProps } from 'class-variance-authority';
8
8
  import { EmptyStateBehavior } from '@foundrykit/hooks';
9
9
  import { SearchResult, SearchSection as SearchSection$1 } from '@foundrykit/types';
10
10
  export { SearchResult, SearchSection as SearchSectionType } from '@foundrykit/types';
11
+ import * as react_hook_form from 'react-hook-form';
12
+ import { FieldValues, FieldPath, ControllerProps } from 'react-hook-form';
13
+ import * as LabelPrimitive from '@radix-ui/react-label';
14
+ import { Slot } from '@radix-ui/react-slot';
11
15
  export { cn } from '@foundrykit/utils';
12
16
 
13
17
  interface SearchBarProps extends React.InputHTMLAttributes<HTMLInputElement> {
@@ -58,70 +62,306 @@ declare function CommandSeparator({ className, ...props }: React.ComponentProps<
58
62
  declare function CommandItem({ className, ...props }: React.ComponentProps<typeof Command$1.Item>): react_jsx_runtime.JSX.Element;
59
63
  declare function CommandShortcut({ className, ...props }: React.ComponentProps<'span'>): react_jsx_runtime.JSX.Element;
60
64
 
65
+ /**
66
+ * Props for the AdvancedSearchProvider component.
67
+ * This provider manages the search state and behavior for all child components.
68
+ */
61
69
  interface AdvancedSearchProviderProps {
70
+ /** Child components that will have access to the search context */
62
71
  children: React.ReactNode;
72
+ /**
73
+ * Function called when user types in the search input.
74
+ * Should return a Promise or array of SearchResult objects.
75
+ * @param query - The search query string
76
+ * @returns Promise<SearchResult[]> | SearchResult[] - Array of search results
77
+ */
63
78
  onSearch?: (query: string) => Promise<SearchResult[]> | SearchResult[];
79
+ /**
80
+ * Function called when user selects a result from the dropdown.
81
+ * @param result - The selected SearchResult object
82
+ */
64
83
  onResultSelect?: (result: SearchResult) => void;
84
+ /**
85
+ * Debounce delay in milliseconds for search requests.
86
+ * @default 300
87
+ */
65
88
  debounceMs?: number;
89
+ /**
90
+ * Minimum number of characters required before triggering search.
91
+ * @default 1
92
+ */
66
93
  minQueryLength?: number;
94
+ /**
95
+ * Behavior when search results are empty or query is too short.
96
+ * - 'show-empty-message': Show "No results found" message
97
+ * - 'hide-until-min-chars': Hide results until minimum characters typed
98
+ * - 'show-all-results': Show initial results when empty
99
+ * @default 'show-empty-message'
100
+ */
67
101
  emptyStateBehavior?: EmptyStateBehavior;
102
+ /**
103
+ * Initial results to show when component first loads.
104
+ * Useful for showing popular/recent searches.
105
+ */
68
106
  initialResults?: SearchResult[];
107
+ /**
108
+ * Custom styles for different parts of the search component.
109
+ */
69
110
  styles?: {
111
+ /** CSS properties for the results dropdown */
70
112
  results: React.CSSProperties;
71
113
  };
72
114
  }
115
+ /**
116
+ * AdvancedSearchProvider component that manages search state and provides context to child components.
117
+ *
118
+ * @example
119
+ * ```tsx
120
+ * <AdvancedSearchProvider
121
+ * onSearch={async (query) => {
122
+ * const results = await searchAPI(query);
123
+ * return results;
124
+ * }}
125
+ * onResultSelect={(result) => {
126
+ * console.log('Selected:', result);
127
+ * }}
128
+ * emptyStateBehavior="show-all-results"
129
+ * initialResults={popularDestinations}
130
+ * >
131
+ * <AdvancedSearchBar>
132
+ * <SearchInput placeholder="Search destinations..." />
133
+ * <SearchResults />
134
+ * </AdvancedSearchBar>
135
+ * </AdvancedSearchProvider>
136
+ * ```
137
+ */
73
138
  declare function AdvancedSearchProvider({ children, onSearch, onResultSelect, debounceMs, minQueryLength, emptyStateBehavior, initialResults, styles, }: AdvancedSearchProviderProps): react_jsx_runtime.JSX.Element;
139
+ /**
140
+ * Variant styles for the search input wrapper.
141
+ * Controls the size and visual appearance of the search input container.
142
+ */
74
143
  declare const searchInputWrapperVariants: (props?: ({
75
144
  size?: "sm" | "lg" | "md" | "xl" | null | undefined;
76
145
  variant?: "default" | "ghost" | "filled" | null | undefined;
77
146
  } & class_variance_authority_types.ClassProp) | undefined) => string;
147
+ /**
148
+ * Variant styles for the search results container.
149
+ * Controls the maximum width of the search results dropdown.
150
+ */
78
151
  declare const searchResultsVariants: (props?: ({
79
152
  size?: "sm" | "lg" | "md" | "xl" | "2xl" | "full" | null | undefined;
80
153
  } & class_variance_authority_types.ClassProp) | undefined) => string;
154
+ /**
155
+ * Props for the SearchInput component.
156
+ * Extends standard input props with search-specific functionality.
157
+ */
81
158
  interface SearchInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'>, VariantProps<typeof searchInputWrapperVariants> {
159
+ /** Placeholder text shown when input is empty */
82
160
  placeholder?: string;
161
+ /** Whether to show the search icon on the left side */
83
162
  showSearchIcon?: boolean;
163
+ /** Whether to show the clear button when there's text */
84
164
  showClearButton?: boolean;
165
+ /** Callback function called when clear button is clicked */
85
166
  onClear?: () => void;
167
+ /** Whether to render as a child component using Slot */
86
168
  asChild?: boolean;
87
169
  }
170
+ /**
171
+ * SearchInput component that provides a search input field with optional search icon and clear button.
172
+ * Automatically integrates with the search context to handle query state and search triggering.
173
+ *
174
+ * @example
175
+ * ```tsx
176
+ * <SearchInput
177
+ * placeholder="Search destinations..."
178
+ * size="lg"
179
+ * variant="default"
180
+ * showSearchIcon={true}
181
+ * showClearButton={true}
182
+ * />
183
+ * ```
184
+ */
88
185
  declare const SearchInput: React.ForwardRefExoticComponent<SearchInputProps & React.RefAttributes<HTMLInputElement>>;
186
+ /**
187
+ * Props for the SearchTrigger component.
188
+ * Used to create custom trigger buttons that open the search dropdown.
189
+ */
89
190
  interface SearchTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
191
+ /** Whether to render as a child component using Slot */
90
192
  asChild?: boolean;
91
193
  }
194
+ /**
195
+ * SearchTrigger component that creates a button to open/close the search dropdown.
196
+ * Can be used with asChild to wrap custom button components.
197
+ *
198
+ * @example
199
+ * ```tsx
200
+ * <SearchTrigger asChild>
201
+ * <Button variant="outline" className="w-full justify-start">
202
+ * <Search className="mr-2 h-4 w-4" />
203
+ * Click to search...
204
+ * </Button>
205
+ * </SearchTrigger>
206
+ * ```
207
+ */
92
208
  declare const SearchTrigger: React.ForwardRefExoticComponent<SearchTriggerProps & React.RefAttributes<HTMLButtonElement>>;
209
+ /**
210
+ * Props for the SearchResults component.
211
+ * Displays the search results in a scrollable dropdown with customizable sections.
212
+ */
93
213
  interface SearchResultsProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof searchResultsVariants> {
214
+ /** Custom sections to display instead of default results */
94
215
  sections?: SearchSection$1[];
216
+ /** Whether to show empty state message when no results */
95
217
  showEmptyState?: boolean;
218
+ /** Custom message to show when no results are found */
96
219
  emptyStateMessage?: string;
220
+ /** Whether to show loading state while searching */
97
221
  showLoadingState?: boolean;
222
+ /** Custom message to show while loading */
98
223
  loadingMessage?: string;
99
224
  }
225
+ /**
226
+ * SearchResults component that displays search results in a scrollable dropdown.
227
+ * Automatically handles loading states, empty states, and result selection.
228
+ *
229
+ * @example
230
+ * ```tsx
231
+ * <SearchResults
232
+ * size="lg"
233
+ * showEmptyState={true}
234
+ * emptyStateMessage="No destinations found."
235
+ * showLoadingState={true}
236
+ * loadingMessage="Searching destinations..."
237
+ * />
238
+ * ```
239
+ */
100
240
  declare const SearchResults: React.ForwardRefExoticComponent<SearchResultsProps & React.RefAttributes<HTMLDivElement>>;
241
+ /**
242
+ * Props for the AdvancedSearchBar component.
243
+ * Main container component that orchestrates the search input and results dropdown.
244
+ */
101
245
  interface AdvancedSearchBarProps extends React.HTMLAttributes<HTMLDivElement> {
246
+ /** Controlled open state of the results dropdown */
102
247
  open?: boolean;
248
+ /** Callback function called when open state changes */
103
249
  onOpenChange?: (open: boolean) => void;
104
250
  }
251
+ /**
252
+ * AdvancedSearchBar component that provides the main search interface.
253
+ * Combines search input with results dropdown in a compound pattern.
254
+ *
255
+ * @example
256
+ * ```tsx
257
+ * <AdvancedSearchBar>
258
+ * <SearchInput placeholder="Search destinations..." />
259
+ * <SearchResults />
260
+ * </AdvancedSearchBar>
261
+ * ```
262
+ */
105
263
  declare const AdvancedSearchBar: React.ForwardRefExoticComponent<AdvancedSearchBarProps & React.RefAttributes<HTMLDivElement>>;
264
+ /**
265
+ * Props for the SearchSection component.
266
+ * Used in compound pattern to create organized sections of search results.
267
+ */
106
268
  interface SearchSectionProps extends React.HTMLAttributes<HTMLDivElement> {
269
+ /** Title displayed above the section results */
107
270
  title?: string;
271
+ /** Maximum number of results to show in this section */
108
272
  maxResults?: number;
273
+ /** Whether to show a "Show more" button */
109
274
  showMore?: boolean;
275
+ /** Callback function called when "Show more" is clicked */
110
276
  onShowMore?: () => void;
111
277
  }
278
+ /**
279
+ * SearchSection component for organizing search results into sections.
280
+ * Used in compound pattern to create structured result displays.
281
+ *
282
+ * @example
283
+ * ```tsx
284
+ * <SearchSection title="Popular Searches" showMore={true} onShowMore={handleShowMore}>
285
+ * <SearchItem result={popularResult1} />
286
+ * <SearchItem result={popularResult2} />
287
+ * </SearchSection>
288
+ * ```
289
+ */
112
290
  declare const SearchSection: React.ForwardRefExoticComponent<SearchSectionProps & React.RefAttributes<HTMLDivElement>>;
291
+ /**
292
+ * Props for the SearchItem component.
293
+ * Used in compound pattern to render individual search result items.
294
+ */
113
295
  interface SearchItemProps extends React.HTMLAttributes<HTMLDivElement> {
296
+ /** The search result data to display */
114
297
  result?: SearchResult;
298
+ /** Callback function called when the item is clicked */
115
299
  onClick?: () => void;
116
300
  }
301
+ /**
302
+ * SearchItem component for rendering individual search result items.
303
+ * Can be used with result data or custom children in compound pattern.
304
+ *
305
+ * @example
306
+ * ```tsx
307
+ * <SearchItem result={searchResult} />
308
+ *
309
+ * // Or with custom children
310
+ * <SearchItem onClick={handleClick}>
311
+ * <div>Custom result display</div>
312
+ * </SearchItem>
313
+ * ```
314
+ */
117
315
  declare const SearchItem: React.ForwardRefExoticComponent<SearchItemProps & React.RefAttributes<HTMLDivElement>>;
118
316
 
317
+ /**
318
+ * Wrapper component for documentation and preview purposes.
319
+ * Provides a complete search implementation with mock data for testing and demos.
320
+ *
321
+ * @param props - Configuration props for the search wrapper
322
+ * @returns Complete search component with mock functionality
323
+ *
324
+ * @example
325
+ * ```tsx
326
+ * <AdvancedSearchBarWrapper
327
+ * emptyStateBehavior="show-all-results"
328
+ * size="lg"
329
+ * variant="default"
330
+ * useCustomTrigger={false}
331
+ * />
332
+ * ```
333
+ */
119
334
  declare function AdvancedSearchBarWrapper(props?: {
335
+ /** Minimum number of characters required before triggering search */
120
336
  minQueryLength?: number;
337
+ /** Behavior when search results are empty or query is too short */
121
338
  emptyStateBehavior?: 'show-empty-message' | 'hide-until-min-chars' | 'show-all-results';
339
+ /** Size variant for the search input */
122
340
  size?: 'sm' | 'md' | 'lg' | 'xl';
341
+ /** Visual variant for the search input */
123
342
  variant?: 'default' | 'ghost' | 'filled';
343
+ /** Whether to use a custom trigger button instead of input */
124
344
  useCustomTrigger?: boolean;
125
345
  }): react_jsx_runtime.JSX.Element;
126
346
 
127
- export { AdvancedSearchBar, AdvancedSearchBarWrapper, AdvancedSearchProvider, Calendar, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, DatePicker, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, SearchBar, SearchInput, SearchItem, SearchResults, SearchSection, SearchTrigger };
347
+ declare const Form: <TFieldValues extends FieldValues, TContext = any, TTransformedValues = TFieldValues>(props: react_hook_form.FormProviderProps<TFieldValues, TContext, TTransformedValues>) => React.JSX.Element;
348
+ declare const FormField: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ ...props }: ControllerProps<TFieldValues, TName>) => react_jsx_runtime.JSX.Element;
349
+ declare const useFormField: () => {
350
+ invalid: boolean;
351
+ isDirty: boolean;
352
+ isTouched: boolean;
353
+ isValidating: boolean;
354
+ error?: react_hook_form.FieldError;
355
+ id: string;
356
+ name: string;
357
+ formItemId: string;
358
+ formDescriptionId: string;
359
+ formMessageId: string;
360
+ };
361
+ declare function FormItem({ className, ...props }: React.ComponentProps<'div'>): react_jsx_runtime.JSX.Element;
362
+ declare function FormLabel({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>): react_jsx_runtime.JSX.Element;
363
+ declare function FormControl({ ...props }: React.ComponentProps<typeof Slot>): react_jsx_runtime.JSX.Element;
364
+ declare function FormDescription({ className, ...props }: React.ComponentProps<'p'>): react_jsx_runtime.JSX.Element;
365
+ declare function FormMessage({ className, ...props }: React.ComponentProps<'p'>): react_jsx_runtime.JSX.Element | null;
366
+
367
+ export { AdvancedSearchBar, AdvancedSearchBarWrapper, AdvancedSearchProvider, Calendar, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, DatePicker, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, SearchBar, SearchInput, SearchItem, SearchResults, SearchSection, SearchTrigger, useFormField };