@turtleclub/core 0.1.0-beta.100

package/src/wrappers/FiltersWrapper.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import React from "react";
+import { cn } from "@turtleclub/ui";
+import { FiltersGrid } from "./FiltersGrid";
+import { FiltersPopover } from "./FiltersPopover";
+import { ActiveFilterBadges, ActiveFilterConfig } from "./ActiveFilterBadges";
+import { FilterConfig } from "./FiltersGrid";
+
+export interface FiltersWrapperProps {
+  /** Array of filter configurations */
+  filters: FilterConfig[];
+  /** Array of active filter configurations for badges */
+  activeFilters: ActiveFilterConfig[];
+  /** Layout type: 'grid' or 'popover' */
+  layout: "grid" | "popover";
+  /** Custom className for the wrapper */
+  className?: string;
+  /** Custom className for the active badges section */
+  badgesClassName?: string;
+  /** Custom className for the slot container */
+  slotClassName?: string;
+  /** Optional content to render on the left side of filters */
+  leftSlot?: React.ReactNode;
+  /** Optional content to render on the right side of filters */
+  rightSlot?: React.ReactNode;
+
+  // Grid-specific props
+  /** Number of columns for grid layout (default: 3) */
+  columns?: number;
+
+  // Popover-specific props
+  /** Button label for popover trigger (default: "Filters") */
+  triggerLabel?: string;
+  /** Number of columns in popover (default: 2) */
+  popoverColumns?: number;
+  /** Custom className for popover trigger button */
+  popoverClassName?: string;
+  /** Custom className for popover content */
+  popoverContentClassName?: string;
+  /** Alignment for popover (default: "start") */
+  align?: "start" | "center" | "end";
+
+  // Active badges props
+  /** Label for clear all button (default: "Clear All") */
+  clearAllLabel?: string;
+  /** Whether to show clear all button (default: true) */
+  showClearAll?: boolean;
+  /** Custom render function for individual badges */
+  renderBadge?: (filter: ActiveFilterConfig, clearFilter: () => void) => React.ReactNode;
+  /** Whether to show active filter badges (default: true) */
+  showActiveBadges?: boolean;
+  /** Callback function to clear individual filter */
+  onClearFilter: (queryKeys: string | string[]) => void;
+  /** Callback function to clear all filters */
+  onClearAll: (allQueryKeys: (string | string[])[]) => void;
+}
+
+/**
+ * Unified wrapper component that combines filter controls with active filter badges.
+ *
+ * Supports both grid and popover layouts, automatically displays active filter badges
+ * below the filter controls with individual and bulk clear functionality.
+ *
+ * @example
+ * ```tsx
+ * const filters = [
+ *   {
+ *     key: 'chain',
+ *     label: 'Chain',
+ *     component: <ChainFilter />,
+ *     enabled: true,
+ *   },
+ * ];
+ *
+ * const activeFilters = [
+ *   {
+ *     key: 'chain',
+ *     label: 'Chain',
+ *     value: 'Ethereum',
+ *     queryKeys: 'chainId',
+ *     isActive: true,
+ *   },
+ * ];
+ *
+ * <FiltersWrapper
+ *   layout="grid"
+ *   filters={filters}
+ *   activeFilters={activeFilters}
+ * />
+ * ```
+ */
+export function FiltersWrapper({
+  filters,
+  activeFilters,
+  layout,
+  className,
+  badgesClassName,
+  slotClassName,
+  leftSlot,
+  rightSlot,
+  columns = 3,
+  triggerLabel = "Filters",
+  popoverColumns = 2,
+  popoverClassName,
+  popoverContentClassName,
+  align = "start",
+  clearAllLabel = "Clear All",
+  showClearAll = true,
+  renderBadge,
+  showActiveBadges = true,
+  onClearFilter,
+  onClearAll,
+}: FiltersWrapperProps) {
+  const hasActiveFilters = activeFilters.some((filter) => filter.isActive && filter.value);
+
+  return (
+    <div className={cn("space-y-3", className)}>
+      {/* Filter Controls */}
+      <div className={cn("flex items-center gap-2", slotClassName)}>
+        {leftSlot}
+        <>
+          {layout === "grid" ? (
+            <FiltersGrid filters={filters} columns={columns} className={popoverClassName} />
+          ) : (
+            <FiltersPopover
+              filters={filters}
+              triggerLabel={triggerLabel}
+              columns={popoverColumns}
+              className={popoverClassName}
+              popoverClassName={popoverContentClassName}
+              align={align}
+              onClearAll={() => {
+                const allQueryKeys = activeFilters
+                  .map((filter) => filter.queryKeys)
+                  .filter((keys): keys is string | string[] => keys !== undefined);
+                onClearAll(allQueryKeys);
+              }}
+            />
+          )}
+        </>
+        {rightSlot}
+      </div>
+
+      {/* Active Filter Badges */}
+      {showActiveBadges && hasActiveFilters && (
+        <ActiveFilterBadges
+          filters={activeFilters}
+          className={badgesClassName}
+          clearAllLabel={clearAllLabel}
+          showClearAll={showClearAll}
+          renderBadge={renderBadge}
+          onClearFilter={onClearFilter}
+          onClearAll={onClearAll}
+        />
+      )}
+    </div>
+  );
+}

package/src/wrappers/README.md

@@ -0,0 +1,272 @@
+# Filter Wrappers
+
+Two wrapper components for managing filters with a consistent interface. Each filter can be individually toggled on/off using the `enabled` property.
+
+## Components
+
+### `FiltersGrid`
+
+A simple grid layout wrapper for displaying filters in a responsive grid.
+
+**Props:**
+- `filters`: Array of `FilterConfig` objects
+- `columns`: Number of columns (default: 3)
+- `gap`: Gap between items (default: 4)
+- `className`: Additional CSS classes
+
+### `FiltersPopover`
+
+A popover-based wrapper that displays filters inside a dropdown/popover component.
+
+**Props:**
+- `filters`: Array of `FilterConfig` objects
+- `triggerLabel`: Button label (default: "Filters")
+- `columns`: Number of columns in popover (default: 2)
+- `gap`: Gap between items (default: 4)
+- `className`: Additional CSS classes for trigger button
+- `popoverClassName`: Additional CSS classes for popover content
+
+## FilterConfig Interface
+
+```typescript
+interface FilterConfig {
+  key: string;           // Unique identifier for the filter
+  label: string;         // Display label for the filter
+  component: React.ReactNode;  // The filter component to render
+  enabled: boolean;      // Whether to show this filter (if false, filter is omitted)
+}
+```
+
+## Usage Examples
+
+### Basic Grid Layout
+
+```tsx
+import { FiltersGrid } from '@turtleclub/core/wrappers';
+import { ChainFilter, TokenFilter, ProductFilter } from '@turtleclub/core/filters';
+
+function MyComponent() {
+  const filters = [
+    {
+      key: 'chain',
+      label: 'Chain',
+      component: <ChainFilter />,
+      enabled: true,
+    },
+    {
+      key: 'token',
+      label: 'Token',
+      component: <TokenFilter />,
+      enabled: true,
+    },
+    {
+      key: 'product',
+      label: 'Product',
+      component: <ProductFilter onValueChange={(val) => console.log(val)} />,
+      enabled: false, // This filter will not be rendered
+    },
+  ];
+
+  return (
+    <FiltersGrid 
+      filters={filters} 
+      columns={3}
+      gap={4}
+    />
+  );
+}
+```
+
+### Popover Layout
+
+```tsx
+import { FiltersPopover } from '@turtleclub/core/wrappers';
+import { ChainFilter, TokenFilter, TvlRangeFilter } from '@turtleclub/core/filters';
+
+function MyComponent() {
+  const filters = [
+    {
+      key: 'chain',
+      label: 'Chain',
+      component: <ChainFilter />,
+      enabled: true,
+    },
+    {
+      key: 'token',
+      label: 'Token',
+      component: <TokenFilter />,
+      enabled: true,
+    },
+    {
+      key: 'tvl',
+      label: 'TVL Range',
+      component: <TvlRangeFilter />,
+      enabled: true,
+    },
+  ];
+
+  return (
+    <FiltersPopover 
+      filters={filters}
+      triggerLabel="Apply Filters"
+      columns={2}
+    />
+  );
+}
+```
+
+### Dynamic Filter Toggling
+
+```tsx
+import { useState } from 'react';
+import { FiltersGrid } from '@turtleclub/core/wrappers';
+import { ChainFilter, TokenFilter, ProductFilter, TagFilter } from '@turtleclub/core/filters';
+
+function MyComponent() {
+  const [showChain, setShowChain] = useState(true);
+  const [showToken, setShowToken] = useState(true);
+  const [showProduct, setShowProduct] = useState(false);
+  const [showTags, setShowTags] = useState(false);
+
+  const filters = [
+    {
+      key: 'chain',
+      label: 'Chain',
+      component: <ChainFilter />,
+      enabled: showChain,
+    },
+    {
+      key: 'token',
+      label: 'Token',
+      component: <TokenFilter />,
+      enabled: showToken,
+    },
+    {
+      key: 'product',
+      label: 'Product',
+      component: <ProductFilter onValueChange={(val) => console.log(val)} />,
+      enabled: showProduct,
+    },
+    {
+      key: 'tags',
+      label: 'Tags',
+      component: <TagFilter />,
+      enabled: showTags,
+    },
+  ];
+
+  return (
+    <div>
+      <div className="mb-4 flex gap-2">
+        <button onClick={() => setShowChain(!showChain)}>
+          Toggle Chain Filter
+        </button>
+        <button onClick={() => setShowToken(!showToken)}>
+          Toggle Token Filter
+        </button>
+        <button onClick={() => setShowProduct(!showProduct)}>
+          Toggle Product Filter
+        </button>
+        <button onClick={() => setShowTags(!showTags)}>
+          Toggle Tags Filter
+        </button>
+      </div>
+      
+      <FiltersGrid filters={filters} />
+    </div>
+  );
+}
+```
+
+### Responsive Grid
+
+```tsx
+import { FiltersGrid } from '@turtleclub/core/wrappers';
+import { ChainFilter, TokenFilter, ProductFilter } from '@turtleclub/core/filters';
+
+function MyComponent() {
+  const filters = [
+    {
+      key: 'chain',
+      label: 'Chain',
+      component: <ChainFilter />,
+      enabled: true,
+    },
+    {
+      key: 'token',
+      label: 'Token',
+      component: <TokenFilter />,
+      enabled: true,
+    },
+    {
+      key: 'product',
+      label: 'Product',
+      component: <ProductFilter onValueChange={(val) => console.log(val)} />,
+      enabled: true,
+    },
+  ];
+
+  return (
+    <FiltersGrid 
+      filters={filters} 
+      columns={3}
+      className="md:grid-cols-2 lg:grid-cols-3"
+    />
+  );
+}
+```
+
+### Combined Approach
+
+You can use both wrappers together for different screen sizes:
+
+```tsx
+import { useState } from 'react';
+import { FiltersGrid, FiltersPopover } from '@turtleclub/core/wrappers';
+import { ChainFilter, TokenFilter, ProductFilter } from '@turtleclub/core/filters';
+
+function MyComponent() {
+  const filters = [
+    {
+      key: 'chain',
+      label: 'Chain',
+      component: <ChainFilter />,
+      enabled: true,
+    },
+    {
+      key: 'token',
+      label: 'Token',
+      component: <TokenFilter />,
+      enabled: true,
+    },
+    {
+      key: 'product',
+      label: 'Product',
+      component: <ProductFilter onValueChange={(val) => console.log(val)} />,
+      enabled: true,
+    },
+  ];
+
+  return (
+    <>
+      {/* Show popover on mobile */}
+      <div className="block md:hidden">
+        <FiltersPopover filters={filters} />
+      </div>
+      
+      {/* Show grid on desktop */}
+      <div className="hidden md:block">
+        <FiltersGrid filters={filters} columns={3} />
+      </div>
+    </>
+  );
+}
+```
+
+## Benefits
+
+- **Consistent Interface**: Both wrappers use the same `FilterConfig` interface
+- **Easy Toggle**: Simply set `enabled: false` to hide a filter
+- **Flexible Layout**: Choose between grid or popover based on your needs
+- **Type-Safe**: Full TypeScript support
+- **Composable**: Works with any React component as the filter

package/src/wrappers/index.ts

@@ -0,0 +1,8 @@
+export { FiltersGrid } from "./FiltersGrid";
+export { FiltersPopover } from "./FiltersPopover";
+export { ActiveFilterBadges } from "./ActiveFilterBadges";
+export { FiltersWrapper } from "./FiltersWrapper";
+export type { FilterConfig, FiltersGridProps } from "./FiltersGrid";
+export type { FiltersPopoverProps } from "./FiltersPopover";
+export type { ActiveFilterConfig, ActiveFilterBadgesProps } from "./ActiveFilterBadges";
+export type { FiltersWrapperProps } from "./FiltersWrapper";