@true-tech-team/react-components 0.0.4 → 0.0.6

package/lib/components/filters/fields/MultiSelectFilter.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { BaseComponentProps, ComponentSize } from '../../../types';
+export interface MultiSelectFilterProps extends BaseComponentProps {
+    /** Filter ID from FilterDefinition */
+    filterId: string;
+    /** Override label */
+    label?: string;
+    /** Show label */
+    showLabel?: boolean;
+    /** Size variant */
+    size?: ComponentSize;
+    /** Additional props */
+    componentProps?: Record<string, unknown>;
+}
+/**
+ * MultiSelectFilter wraps CheckboxGroup for multi-value selection
+ */
+export declare const MultiSelectFilter: React.ForwardRefExoticComponent<MultiSelectFilterProps & React.RefAttributes<HTMLDivElement>>;
+export default MultiSelectFilter;

package/lib/components/filters/fields/NumberFilter.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { BaseComponentProps, ComponentSize } from '../../../types';
+export interface NumberFilterProps extends BaseComponentProps {
+    /** Filter ID from FilterDefinition */
+    filterId: string;
+    /** Override label */
+    label?: string;
+    /** Show label */
+    showLabel?: boolean;
+    /** Size variant */
+    size?: ComponentSize;
+    /** Additional props for NumberInput component */
+    numberInputProps?: Record<string, unknown>;
+}
+/**
+ * NumberFilter wraps the NumberInput component for numeric filters
+ */
+export declare const NumberFilter: React.ForwardRefExoticComponent<NumberFilterProps & React.RefAttributes<HTMLDivElement>>;
+export default NumberFilter;

package/lib/components/filters/fields/NumberRangeFilter.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { BaseComponentProps, ComponentSize } from '../../../types';
+export interface NumberRangeFilterProps extends BaseComponentProps {
+    /** Filter ID from FilterDefinition */
+    filterId: string;
+    /** Override label */
+    label?: string;
+    /** Show label */
+    showLabel?: boolean;
+    /** Size variant */
+    size?: ComponentSize;
+    /** Additional props */
+    componentProps?: Record<string, unknown>;
+}
+/**
+ * NumberRangeFilter provides min/max number filtering with slider or inputs
+ */
+export declare const NumberRangeFilter: React.ForwardRefExoticComponent<NumberRangeFilterProps & React.RefAttributes<HTMLDivElement>>;
+export default NumberRangeFilter;

package/lib/components/filters/fields/RatingFilter.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { BaseComponentProps, ComponentSize } from '../../../types';
+export interface RatingFilterProps extends BaseComponentProps {
+    /** Filter ID from FilterDefinition */
+    filterId: string;
+    /** Override label */
+    label?: string;
+    /** Show label */
+    showLabel?: boolean;
+    /** Size variant */
+    size?: ComponentSize;
+    /** Additional props for Rating component */
+    ratingProps?: Record<string, unknown>;
+}
+/**
+ * RatingFilter wraps the Rating component for star-based filters
+ */
+export declare const RatingFilter: React.ForwardRefExoticComponent<RatingFilterProps & React.RefAttributes<HTMLDivElement>>;
+export default RatingFilter;

package/lib/components/filters/fields/SelectFilter.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+import { BaseComponentProps, ComponentSize } from '../../../types';
+export interface SelectFilterProps extends BaseComponentProps {
+    /** Filter ID from FilterDefinition */
+    filterId: string;
+    /** Override label */
+    label?: string;
+    /** Override placeholder */
+    placeholder?: string;
+    /** Show label */
+    showLabel?: boolean;
+    /** Size variant */
+    size?: ComponentSize;
+    /** Additional props for Select component */
+    selectProps?: Record<string, unknown>;
+}
+/**
+ * SelectFilter wraps the Select component for use in filter systems
+ */
+export declare const SelectFilter: React.ForwardRefExoticComponent<SelectFilterProps & React.RefAttributes<HTMLDivElement>>;
+export default SelectFilter;

package/lib/components/filters/fields/TextFilter.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+import { BaseComponentProps, ComponentSize } from '../../../types';
+export interface TextFilterProps extends BaseComponentProps {
+    /** Filter ID from FilterDefinition */
+    filterId: string;
+    /** Override label */
+    label?: string;
+    /** Override placeholder */
+    placeholder?: string;
+    /** Show label */
+    showLabel?: boolean;
+    /** Size variant */
+    size?: ComponentSize;
+    /** Additional props for Input component */
+    inputProps?: Record<string, unknown>;
+}
+/**
+ * TextFilter wraps the Input component for text/search filters
+ */
+export declare const TextFilter: React.ForwardRefExoticComponent<TextFilterProps & React.RefAttributes<HTMLDivElement>>;
+export default TextFilter;

package/lib/components/filters/fields/ToggleFilter.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { BaseComponentProps, ComponentSize } from '../../../types';
+export interface ToggleFilterProps extends BaseComponentProps {
+    /** Filter ID from FilterDefinition */
+    filterId: string;
+    /** Override label */
+    label?: string;
+    /** Size variant */
+    size?: ComponentSize;
+    /** Additional props for Toggle component */
+    toggleProps?: Record<string, unknown>;
+}
+/**
+ * ToggleFilter wraps the Toggle component for boolean switch filters
+ */
+export declare const ToggleFilter: React.ForwardRefExoticComponent<ToggleFilterProps & React.RefAttributes<HTMLDivElement>>;
+export default ToggleFilter;

package/lib/components/filters/fields/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Filter field components exports
+ */
+export { SelectFilter } from './SelectFilter';
+export type { SelectFilterProps } from './SelectFilter';
+export { MultiSelectFilter } from './MultiSelectFilter';
+export type { MultiSelectFilterProps } from './MultiSelectFilter';
+export { CheckboxFilter } from './CheckboxFilter';
+export type { CheckboxFilterProps } from './CheckboxFilter';
+export { ToggleFilter } from './ToggleFilter';
+export type { ToggleFilterProps } from './ToggleFilter';
+export { TextFilter } from './TextFilter';
+export type { TextFilterProps } from './TextFilter';
+export { DateFilter } from './DateFilter';
+export type { DateFilterProps } from './DateFilter';
+export { DateRangeFilter } from './DateRangeFilter';
+export type { DateRangeFilterProps } from './DateRangeFilter';
+export { NumberFilter } from './NumberFilter';
+export type { NumberFilterProps } from './NumberFilter';
+export { NumberRangeFilter } from './NumberRangeFilter';
+export type { NumberRangeFilterProps } from './NumberRangeFilter';
+export { RatingFilter } from './RatingFilter';
+export type { RatingFilterProps } from './RatingFilter';
+export { ListSelectFilter } from './ListSelectFilter';
+export type { ListSelectFilterProps } from './ListSelectFilter';

package/lib/components/filters/hooks/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Filter hooks exports
+ */
+export { useFilter } from './useFilter';
+export type { UseFilterOptions, UseFilterReturn } from './useFilter';
+export { useFilterDependencies, getDependencyValues } from './useFilterDependencies';
+export type { UseFilterDependenciesOptions, UseFilterDependenciesReturn, } from './useFilterDependencies';
+export { useFilterOptions, clearOptionsCache } from './useFilterOptions';
+export type { UseFilterOptionsOptions, UseFilterOptionsReturn } from './useFilterOptions';

package/lib/components/filters/hooks/useFilter.d.ts

@@ -0,0 +1,57 @@
+import { FilterValue, FilterValueWithMeta, FilterDefinition, FilterOptionsState } from '../types';
+export interface UseFilterOptions {
+    filterId: string;
+}
+export interface UseFilterReturn<T extends FilterValue = FilterValue> {
+    /** Filter definition */
+    filter: FilterDefinition<T> | undefined;
+    /** Current value */
+    value: T | undefined;
+    /** Value with metadata */
+    valueMeta: FilterValueWithMeta<T> | undefined;
+    /** Whether filter has a non-empty value */
+    isActive: boolean;
+    /** Whether filter is visible (considering dependencies) */
+    isVisible: boolean;
+    /** Whether filter is enabled (considering dependencies) */
+    isEnabled: boolean;
+    /** Whether options are loading */
+    isLoading: boolean;
+    /** Whether filter has been interacted with */
+    isTouched: boolean;
+    /** Validation error message */
+    error: string | null;
+    /** Options state for select-based filters */
+    options: FilterOptionsState;
+    /** Set the filter value */
+    setValue: (value: T) => void;
+    /** Clear the filter (reset to default) */
+    clear: () => void;
+    /** Mark filter as touched */
+    touch: () => void;
+    /** Validate the filter value */
+    validate: () => boolean;
+}
+/**
+ * Hook to access a single filter's state and actions
+ *
+ * @param options - Hook options with filterId
+ * @returns Filter state and actions
+ *
+ * @example
+ * ```tsx
+ * function StatusFilter() {
+ *   const { value, setValue, options, isLoading } = useFilter({ filterId: 'status' });
+ *
+ *   return (
+ *     <Select
+ *       value={value as string}
+ *       onChange={setValue}
+ *       options={options.items}
+ *       loading={isLoading}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function useFilter<T extends FilterValue = FilterValue>(options: UseFilterOptions): UseFilterReturn<T>;

package/lib/components/filters/hooks/useFilterDependencies.d.ts

@@ -0,0 +1,40 @@
+import { FilterDefinition, FilterValue } from '../types';
+export interface UseFilterDependenciesOptions {
+    /** The filter definition */
+    filter: FilterDefinition;
+    /** All current filter values */
+    allValues: Record<string, FilterValue>;
+    /** Callback when options should be reloaded */
+    onReloadOptions?: () => void;
+    /** Callback when value should be reset */
+    onResetValue?: () => void;
+}
+export interface UseFilterDependenciesReturn {
+    /** Whether the filter should be visible */
+    isVisible: boolean;
+    /** Whether the filter should be enabled */
+    isEnabled: boolean;
+    /** Whether options should be reloaded */
+    shouldReloadOptions: boolean;
+}
+/**
+ * Hook to evaluate filter dependencies and manage cascading behavior
+ *
+ * @param options - Hook options
+ * @returns Dependency evaluation results
+ *
+ * @example
+ * ```tsx
+ * const { isVisible, isEnabled } = useFilterDependencies({
+ *   filter: subcategoryFilter,
+ *   allValues: filterValues,
+ *   onReloadOptions: () => reloadSubcategories(),
+ *   onResetValue: () => clearSubcategory(),
+ * });
+ * ```
+ */
+export declare function useFilterDependencies(options: UseFilterDependenciesOptions): UseFilterDependenciesReturn;
+/**
+ * Get the dependency values for a filter
+ */
+export declare function getDependencyValues(filter: FilterDefinition, allValues: Record<string, FilterValue>): Record<string, FilterValue>;

package/lib/components/filters/hooks/useFilterOptions.d.ts

@@ -0,0 +1,70 @@
+import { FilterOption, FilterOptionsLoader, FilterValue } from '../types';
+export interface UseFilterOptionsOptions<T = string> {
+    /** Static options (takes precedence if provided) */
+    staticOptions?: Array<FilterOption<T>>;
+    /** Async options loader configuration */
+    loader?: FilterOptionsLoader<T>;
+    /** Current search query */
+    searchQuery?: string;
+    /** Dependency values (for cascading filters) */
+    dependencyValues?: Record<string, FilterValue>;
+    /** Whether to load options immediately
+     * @default true
+     */
+    loadOnMount?: boolean;
+    /** Filter ID (used for cache key) */
+    filterId?: string;
+}
+export interface UseFilterOptionsReturn<T = string> {
+    /** Current options */
+    options: Array<FilterOption<T>>;
+    /** Whether options are loading */
+    loading: boolean;
+    /** Error message if loading failed */
+    error: string | null;
+    /** Whether more options are available */
+    hasMore: boolean;
+    /** Total count of options (if known) */
+    totalCount: number | undefined;
+    /** Load more options (pagination) */
+    loadMore: () => void;
+    /** Reload options from scratch */
+    reload: () => void;
+    /** Update search query */
+    search: (query: string) => void;
+}
+/**
+ * Hook to manage filter options with async loading, caching, and pagination
+ *
+ * @param options - Hook options
+ * @returns Options state and actions
+ *
+ * @example
+ * ```tsx
+ * // Static options
+ * const { options } = useFilterOptions({
+ *   staticOptions: [
+ *     { value: 'active', label: 'Active' },
+ *     { value: 'inactive', label: 'Inactive' },
+ *   ],
+ * });
+ *
+ * // Async options with pagination
+ * const { options, loading, hasMore, loadMore, search } = useFilterOptions({
+ *   loader: {
+ *     load: async ({ searchQuery, page, pageSize }) => {
+ *       const response = await fetch(`/api/items?q=${searchQuery}&page=${page}`);
+ *       const data = await response.json();
+ *       return { options: data.items, hasMore: data.hasMore };
+ *     },
+ *     paginated: true,
+ *     debounceMs: 300,
+ *   },
+ * });
+ * ```
+ */
+export declare function useFilterOptions<T = string>(options: UseFilterOptionsOptions<T>): UseFilterOptionsReturn<T>;
+/**
+ * Clear the options cache for a specific filter or all filters
+ */
+export declare function clearOptionsCache(filterId?: string): void;

package/lib/components/filters/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Filter component system - Main exports
+ *
+ * A highly configurable filter component system supporting multiple filter types,
+ * cascading dependencies, lazy-loaded options, and various UI layouts.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import {
+ *   FilterProvider,
+ *   FilterSidebar,
+ *   FilterSection,
+ *   FilterField,
+ *   ActiveFilters,
+ * } from '@ui-components';
+ *
+ * const filters = [
+ *   { id: 'status', type: 'select', label: 'Status', options: [...] },
+ *   { id: 'date', type: 'date-range', label: 'Date Range' },
+ * ];
+ *
+ * <FilterProvider filters={filters} onChange={handleChange}>
+ *   <FilterSidebar>
+ *     <FilterSection title="Filters">
+ *       <FilterField filterId="status" />
+ *       <FilterField filterId="date" />
+ *     </FilterSection>
+ *   </FilterSidebar>
+ *   <ActiveFilters />
+ * </FilterProvider>
+ * ```
+ */
+export type { FilterType, FilterValue, FilterValueWithMeta, FilterOption, FilterOptionsLoader, FilterOptionsLoaderParams, FilterOptionsLoadResult, FilterDependency, FilterDependencyAction, FilterDefinition, FilterGroup, FilterState, FilterActions, FilterContextValue, FilterOptionsState, NumberRangeValue, DateRangeValue, SelectFilterConfig, MultiSelectFilterConfig, MultiSelectDisplayMode, TextFilterConfig, NumberFilterConfig, NumberRangeFilterConfig, NumberRangeDisplayMode, DateFilterConfig, DateRangeFilterConfig, DateRangePreset, RatingFilterConfig, ListSelectFilterConfig, FilterTypeConfig, FilterProviderProps, FilterFieldProps, FilterSectionProps, ActiveFiltersProps, FilterLayoutProps, FilterSidebarProps, FilterBarProps, FilterPopoverProps, FilterModalProps, FilterAccordionProps, } from './types';
+export { FilterContext, useFilterContext, useFilterContextStrict, } from './FilterContext';
+export { useFilter, useFilterDependencies, useFilterOptions, getDependencyValues, clearOptionsCache, } from './hooks';
+export type { UseFilterOptions, UseFilterReturn, UseFilterDependenciesOptions, UseFilterDependenciesReturn, UseFilterOptionsOptions, UseFilterOptionsReturn, } from './hooks';
+export { FilterProvider } from './core/FilterProvider';
+export { FilterField } from './core/FilterField';
+export { FilterSection } from './core/FilterSection';
+export { ActiveFilters } from './core/ActiveFilters';
+export { SelectFilter, MultiSelectFilter, CheckboxFilter, ToggleFilter, TextFilter, DateFilter, DateRangeFilter, NumberFilter, NumberRangeFilter, RatingFilter, ListSelectFilter, } from './fields';
+export type { SelectFilterProps, MultiSelectFilterProps, CheckboxFilterProps, ToggleFilterProps, TextFilterProps, DateFilterProps, DateRangeFilterProps, NumberFilterProps, NumberRangeFilterProps, RatingFilterProps, ListSelectFilterProps, } from './fields';
+export { FilterSidebar, FilterBar, FilterPopover, FilterModal, FilterAccordion, } from './layouts';

package/lib/components/filters/layouts/FilterAccordion/FilterAccordion.d.ts

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+import { FilterAccordionProps } from '../../types';
+/**
+ * FilterAccordion automatically groups filters by their group property
+ * and displays them in an accordion layout.
+ *
+ * @example
+ * ```tsx
+ * <FilterProvider filters={filters} groups={groups}>
+ *   <FilterAccordion mode="multiple" showGroupCounts />
+ * </FilterProvider>
+ * ```
+ */
+export declare const FilterAccordion: React.ForwardRefExoticComponent<FilterAccordionProps & React.RefAttributes<HTMLDivElement>>;
+export default FilterAccordion;

package/lib/components/filters/layouts/FilterAccordion/index.d.ts

@@ -0,0 +1,2 @@
+export { FilterAccordion } from './FilterAccordion';
+export { default } from './FilterAccordion';

package/lib/components/filters/layouts/FilterBar/FilterBar.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+import { FilterBarProps } from '../../types';
+/**
+ * FilterBar provides a horizontal layout for inline filters.
+ * Supports overflow handling with a "More Filters" dropdown.
+ *
+ * @example
+ * ```tsx
+ * <FilterProvider filters={filters}>
+ *   <FilterBar visibleFilters={['status', 'date']}>
+ *     <FilterField filterId="status" showLabel={false} />
+ *     <FilterField filterId="date" showLabel={false} />
+ *   </FilterBar>
+ * </FilterProvider>
+ * ```
+ */
+export declare const FilterBar: React.ForwardRefExoticComponent<FilterBarProps & React.RefAttributes<HTMLDivElement>>;
+export default FilterBar;

package/lib/components/filters/layouts/FilterBar/index.d.ts

@@ -0,0 +1,2 @@
+export { FilterBar } from './FilterBar';
+export { default } from './FilterBar';

package/lib/components/filters/layouts/FilterModal/FilterModal.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+import { FilterModalProps } from '../../types';
+/**
+ * FilterModal provides a full modal dialog for complex filter interfaces.
+ * Useful for advanced filters with many options.
+ *
+ * @example
+ * ```tsx
+ * <FilterProvider filters={filters}>
+ *   <FilterModal
+ *     title="Advanced Filters"
+ *     renderTrigger={({ onClick, activeCount }) => (
+ *       <Button onClick={onClick}>
+ *         Filters {activeCount > 0 && `(${activeCount})`}
+ *       </Button>
+ *     )}
+ *   >
+ *     <FilterAccordion>...</FilterAccordion>
+ *   </FilterModal>
+ * </FilterProvider>
+ * ```
+ */
+export declare const FilterModal: React.ForwardRefExoticComponent<FilterModalProps & React.RefAttributes<HTMLDivElement>>;
+export default FilterModal;

package/lib/components/filters/layouts/FilterModal/index.d.ts

@@ -0,0 +1,2 @@
+export { FilterModal } from './FilterModal';
+export { default } from './FilterModal';

package/lib/components/filters/layouts/FilterPopover/FilterPopover.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { FilterPopoverProps } from '../../types';
+/**
+ * FilterPopover provides a trigger-based dropdown for filter controls.
+ * Shows a badge with active filter count on the trigger button.
+ *
+ * @example
+ * ```tsx
+ * <FilterProvider filters={filters}>
+ *   <FilterPopover triggerLabel="Filters">
+ *     <FilterSection title="Status">
+ *       <FilterField filterId="status" />
+ *     </FilterSection>
+ *   </FilterPopover>
+ * </FilterProvider>
+ * ```
+ */
+export declare const FilterPopover: React.ForwardRefExoticComponent<FilterPopoverProps & React.RefAttributes<HTMLDivElement>>;
+export default FilterPopover;

package/lib/components/filters/layouts/FilterPopover/index.d.ts

@@ -0,0 +1,2 @@
+export { FilterPopover } from './FilterPopover';
+export { default } from './FilterPopover';

package/lib/components/filters/layouts/FilterSidebar/FilterSidebar.d.ts

@@ -0,0 +1,20 @@
+import { default as React } from 'react';
+import { FilterSidebarProps } from '../../types';
+/**
+ * FilterSidebar provides a vertical sidebar layout for filter controls.
+ * Supports collapsible behavior, header/footer slots, and active filters display.
+ *
+ * @example
+ * ```tsx
+ * <FilterProvider filters={filters}>
+ *   <FilterSidebar width={280} header={<h3>Filters</h3>}>
+ *     <FilterSection title="Status">
+ *       <FilterField filterId="status" />
+ *     </FilterSection>
+ *   </FilterSidebar>
+ *   <main>Content</main>
+ * </FilterProvider>
+ * ```
+ */
+export declare const FilterSidebar: React.ForwardRefExoticComponent<FilterSidebarProps & React.RefAttributes<HTMLDivElement>>;
+export default FilterSidebar;

package/lib/components/filters/layouts/FilterSidebar/index.d.ts

@@ -0,0 +1,2 @@
+export { FilterSidebar } from './FilterSidebar';
+export { default } from './FilterSidebar';

package/lib/components/filters/layouts/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Filter layout components exports
+ */
+export { FilterSidebar } from './FilterSidebar';
+export { FilterBar } from './FilterBar';
+export { FilterPopover } from './FilterPopover';
+export { FilterModal } from './FilterModal';
+export { FilterAccordion } from './FilterAccordion';