@etus/ui 0.1.0

package/src/components/advanced/FilterBuilder/FilterBuilder.tsx

@@ -0,0 +1,881 @@
+// FilterBuilder/FilterBuilder.tsx
+"use client"
+
+import type {
+  FieldDefinition,
+  FilterBuilderProps,
+  FilterGroup,
+  FilterGroupProps,
+  FilterPreviewProps,
+  FilterRule,
+  FilterRuleProps,
+  FilterToolbarProps,
+  OperatorInfo,
+  OperatorsByType,
+  OperatorType,
+} from "./FilterBuilder.types"
+
+import { PlusIcon, TrashIcon, XIcon } from "lucide-react"
+import * as React from "react"
+
+import { cn } from "../../../lib/utils"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "../../forms/Select"
+import { TextInput } from "../../forms/TextInput"
+import { Button } from "../../primitives/Button"
+import { isFilterGroup } from "./FilterBuilder.types"
+import {
+  combinatorToggleVariants,
+  emptyStateVariants,
+  filterBuilderVariants,
+  filterGroupHeaderVariants,
+  filterGroupVariants,
+  filterPreviewVariants,
+  filterRuleVariants,
+  filterToolbarVariants,
+  ruleFieldVariants,
+  ruleOperatorVariants,
+  rulesContainerVariants,
+  ruleValueVariants,
+} from "./FilterBuilder.variants"
+
+// ============================================
+// CONSTANTS
+// ============================================
+
+/**
+ * Default operators available for each field type
+ */
+const DEFAULT_OPERATORS_BY_TYPE: OperatorsByType = {
+  boolean: ["equals", "not_equals"],
+  date: [
+    "equals",
+    "not_equals",
+    "greater_than",
+    "less_than",
+    "between",
+  ],
+  number: [
+    "equals",
+    "not_equals",
+    "greater_than",
+    "greater_than_or_equal",
+    "less_than",
+    "less_than_or_equal",
+    "between",
+  ],
+  select: ["equals", "not_equals", "in", "not_in"],
+  string: [
+    "equals",
+    "not_equals",
+    "contains",
+    "starts_with",
+    "ends_with",
+    "is_empty",
+    "is_not_empty",
+  ],
+}
+
+/**
+ * Operator display labels
+ */
+const OPERATOR_LABELS: Record<OperatorType, string> = {
+  between: "between",
+  contains: "contains",
+  ends_with: "ends with",
+  equals: "equals",
+  greater_than: "greater than",
+  greater_than_or_equal: "greater than or equal",
+  in: "is any of",
+  is_empty: "is empty",
+  is_not_empty: "is not empty",
+  less_than: "less than",
+  less_than_or_equal: "less than or equal",
+  not_equals: "does not equal",
+  not_in: "is none of",
+  starts_with: "starts with",
+}
+
+/**
+ * Generate a unique ID for rules and groups
+ */
+function generateId(): string {
+  return Math.random().toString(36).slice(2, 11)
+}
+
+/**
+ * Create an empty rule
+ */
+function createEmptyRule(): FilterRule {
+  return {
+    field: "",
+    id: generateId(),
+    operator: "",
+    value: "",
+  }
+}
+
+/**
+ * Create an empty group
+ */
+function createEmptyGroup(): FilterGroup {
+  return {
+    combinator: "and",
+    id: generateId(),
+    rules: [],
+  }
+}
+
+/**
+ * Get operators for a field
+ */
+function getOperatorsForField(
+  field: FieldDefinition | undefined
+): OperatorInfo[] {
+  if (!field) return []
+
+  const operators = field.operators ?? DEFAULT_OPERATORS_BY_TYPE[field.type]
+  return operators.map((op) => ({
+    label: OPERATOR_LABELS[op],
+    value: op,
+  }))
+}
+
+/**
+ * Count total rules in a filter group (including nested)
+ */
+function countRules(group: FilterGroup): number {
+  return group.rules.reduce((count, item) => {
+    if (isFilterGroup(item)) {
+      return count + countRules(item)
+    }
+    return count + 1
+  }, 0)
+}
+
+/**
+ * Get size for input components
+ */
+function getInputSize(size: "default" | "lg" | "sm"): "lg" | "md" | "sm" {
+  if (size === "lg") return "lg"
+  if (size === "sm") return "sm"
+  return "md"
+}
+
+// ============================================
+// CONTEXT
+// ============================================
+
+interface FilterBuilderContextValue {
+  fields: FieldDefinition[]
+  size: "default" | "lg" | "sm"
+}
+
+const FilterBuilderContext = React.createContext<FilterBuilderContextValue>({
+  fields: [],
+  size: "default",
+})
+
+function useFilterBuilderContext() {
+  return React.use(FilterBuilderContext)
+}
+
+// ============================================
+// VALUE INPUT COMPONENT (extracted to reduce complexity)
+// ============================================
+
+interface ValueInputProps {
+  needsSecondValue: boolean
+  onChange: (value: string) => void
+  selectedField: FieldDefinition | undefined
+  size: "default" | "lg" | "sm"
+  value: unknown
+}
+
+function ValueInput({
+  needsSecondValue,
+  onChange,
+  selectedField,
+  size,
+  value,
+}: ValueInputProps) {
+  const inputSize = getInputSize(size)
+
+  // Select field type
+  if (selectedField?.type === "select" && selectedField.options) {
+    return (
+      <Select
+        value={value as string}
+        onValueChange={onChange}
+      >
+        <SelectTrigger
+          aria-label="Select value"
+          size={inputSize}
+        >
+          <SelectValue placeholder="Select value" />
+        </SelectTrigger>
+        <SelectContent>
+          {selectedField.options.map((option) => (
+            <SelectItem key={option.value} value={option.value}>
+              {option.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    )
+  }
+
+  // Boolean field type
+  if (selectedField?.type === "boolean") {
+    return (
+      <Select
+        value={String(value)}
+        onValueChange={onChange}
+      >
+        <SelectTrigger
+          aria-label="Select value"
+          size={inputSize}
+        >
+          <SelectValue placeholder="Select value" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="true">True</SelectItem>
+          <SelectItem value="false">False</SelectItem>
+        </SelectContent>
+      </Select>
+    )
+  }
+
+  // Between operator (two inputs)
+  if (needsSecondValue) {
+    const rawArray = Array.isArray(value) ? value : ["", ""]
+    const fromValue = String(rawArray[0] ?? "")
+    const toValue = String(rawArray[1] ?? "")
+    return (
+      <div className="flex items-center gap-2">
+        <TextInput
+          aria-label="From value"
+          placeholder="From"
+          size={inputSize}
+          type={selectedField?.type === "number" ? "number" : "text"}
+          value={fromValue}
+          onChange={(e) =>
+            { onChange(JSON.stringify([e.target.value, toValue])); }
+          }
+        />
+        <span className="text-sm text-muted-foreground">and</span>
+        <TextInput
+          aria-label="To value"
+          placeholder="To"
+          size={inputSize}
+          type={selectedField?.type === "number" ? "number" : "text"}
+          value={toValue}
+          onChange={(e) =>
+            { onChange(JSON.stringify([fromValue, e.target.value])); }
+          }
+        />
+      </div>
+    )
+  }
+
+  // Default text/number/date input
+  const inputType =
+    selectedField?.type === "number"
+      ? "number"
+      : selectedField?.type === "date"
+        ? "date"
+        : "text"
+
+  return (
+    <TextInput
+      aria-label="Filter value"
+      placeholder="Enter value"
+      size={inputSize}
+      type={inputType}
+      value={value as string}
+      onChange={(e) => { onChange(e.target.value); }}
+    />
+  )
+}
+
+// ============================================
+// FILTER RULE COMPONENT
+// ============================================
+
+function FilterRuleComponent({
+  fields,
+  onChange,
+  onRemove,
+  rule,
+}: FilterRuleProps) {
+  const { size } = useFilterBuilderContext()
+
+  const selectedField = fields.find((f) => f.name === rule.field)
+  const operators = getOperatorsForField(selectedField)
+  const isInvalid = Boolean(rule.field && !rule.operator)
+  const inputSize = getInputSize(size)
+
+  const handleFieldChange = (fieldName: string) => {
+    const newField = fields.find((f) => f.name === fieldName)
+    const newOperators = getOperatorsForField(newField)
+
+    onChange({
+      ...rule,
+      field: fieldName,
+      operator: newOperators[0]?.value ?? "",
+      value: "",
+    })
+  }
+
+  const handleOperatorChange = (operator: string) => {
+    onChange({
+      ...rule,
+      operator: operator as OperatorType,
+      value: ["is_empty", "is_not_empty"].includes(operator) ? "" : rule.value,
+    })
+  }
+
+  const handleValueChange = (value: string) => {
+    onChange({ ...rule, value })
+  }
+
+  const needsValue = rule.operator && !["is_empty", "is_not_empty"].includes(rule.operator)
+  const needsSecondValue = rule.operator === "between"
+
+  return (
+    <div
+      aria-label={`Filter rule: ${selectedField?.label ?? "Select field"}`}
+      className={cn(filterRuleVariants({ invalid: isInvalid, size }))}
+      data-slot="filter-rule"
+      role="group"
+    >
+      {/* Field Select */}
+      <div className={cn(ruleFieldVariants({ size }))}>
+        <Select
+          value={rule.field}
+          onValueChange={handleFieldChange}
+        >
+          <SelectTrigger
+            aria-label="Select field"
+            size={inputSize}
+          >
+            <SelectValue placeholder="Select field" />
+          </SelectTrigger>
+          <SelectContent>
+            {fields.map((field) => (
+              <SelectItem key={field.name} value={field.name}>
+                {field.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+
+      {/* Operator Select */}
+      {rule.field && (
+        <div className={cn(ruleOperatorVariants({ size }))}>
+          <Select
+            value={rule.operator}
+            onValueChange={handleOperatorChange}
+          >
+            <SelectTrigger
+              aria-label="Select operator"
+              size={inputSize}
+            >
+              <SelectValue placeholder="Operator" />
+            </SelectTrigger>
+            <SelectContent>
+              {operators.map((op) => (
+                <SelectItem key={op.value} value={op.value}>
+                  {op.label}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+      )}
+
+      {/* Value Input */}
+      {needsValue && (
+        <div className={cn(ruleValueVariants({ size }))}>
+          <ValueInput
+            needsSecondValue={needsSecondValue}
+            selectedField={selectedField}
+            size={size}
+            value={rule.value}
+            onChange={handleValueChange}
+          />
+        </div>
+      )}
+
+      {/* Remove Button */}
+      <Button
+        aria-label="Remove rule"
+        className="flex-shrink-0 text-muted-foreground hover:text-destructive"
+        size="icon"
+        type="button"
+        variant="ghost"
+        onClick={onRemove}
+      >
+        <XIcon className="size-4" />
+      </Button>
+    </div>
+  )
+}
+
+// ============================================
+// FILTER GROUP COMPONENT
+// ============================================
+
+function FilterGroupComponent({
+  depth,
+  fields,
+  group,
+  isRoot = false,
+  maxDepth,
+  maxRules,
+  onChange,
+  onRemove,
+  rulesCount,
+}: FilterGroupProps) {
+  const { size } = useFilterBuilderContext()
+
+  const handleCombinatorChange = (combinator: "and" | "or") => {
+    onChange({ ...group, combinator })
+  }
+
+  const handleAddRule = () => {
+    if (rulesCount >= maxRules) return
+    onChange({ ...group, rules: [...group.rules, createEmptyRule()] })
+  }
+
+  const handleAddGroup = () => {
+    if (depth >= maxDepth || rulesCount >= maxRules) return
+    onChange({ ...group, rules: [...group.rules, createEmptyGroup()] })
+  }
+
+  const handleRuleChange = (index: number, updatedItem: FilterGroup | FilterRule) => {
+    const newRules = [...group.rules]
+    newRules[index] = updatedItem
+    onChange({ ...group, rules: newRules })
+  }
+
+  const handleRemoveItem = (index: number) => {
+    onChange({ ...group, rules: group.rules.filter((_, i) => i !== index) })
+  }
+
+  const canAddRule = rulesCount < maxRules
+  const canAddGroup = depth < maxDepth && rulesCount < maxRules
+  const buttonSize = size === "lg" ? "default" : "sm"
+
+  return (
+    <div
+      aria-label={`Filter group with ${group.combinator.toUpperCase()} combinator`}
+      className={cn(filterGroupVariants({ isRoot, size }))}
+      data-slot="filter-group"
+      role="group"
+    >
+      {/* Group Header - Combinator Toggle */}
+      {!isRoot && (
+        <div className={cn(filterGroupHeaderVariants({ size }))}>
+          <div className="flex items-center gap-1">
+            <button
+              className={cn(
+                combinatorToggleVariants({
+                  active: group.combinator === "and",
+                  size,
+                })
+              )}
+              aria-pressed={group.combinator === "and"}
+              type="button"
+              onClick={() => { handleCombinatorChange("and"); }}
+            >
+              AND
+            </button>
+            <button
+              className={cn(
+                combinatorToggleVariants({
+                  active: group.combinator === "or",
+                  size,
+                })
+              )}
+              aria-pressed={group.combinator === "or"}
+              type="button"
+              onClick={() => { handleCombinatorChange("or"); }}
+            >
+              OR
+            </button>
+          </div>
+
+          {onRemove && (
+            <Button
+              aria-label="Remove group"
+              className="ml-auto text-muted-foreground hover:text-destructive"
+              size="icon"
+              type="button"
+              variant="ghost"
+              onClick={onRemove}
+            >
+              <TrashIcon className="size-4" />
+            </Button>
+          )}
+        </div>
+      )}
+
+      {/* Rules Container */}
+      <div className={cn(rulesContainerVariants({ size }))}>
+        {group.rules.length === 0 ? (
+          <div className={cn(emptyStateVariants({ size }))}>
+            <span>No filters added</span>
+            <span className="text-xs">Click &quot;Add Rule&quot; to create a filter</span>
+          </div>
+        ) : (
+          group.rules.map((item, index) => (
+            <React.Fragment key={item.id}>
+              {/* Combinator Label between rules (not for first item) */}
+              {index > 0 && (
+                <div className="flex items-center gap-2 pl-2">
+                  <span className="text-xs font-medium uppercase text-muted-foreground">
+                    {group.combinator}
+                  </span>
+                  <div className="h-px flex-1 bg-border" />
+                </div>
+              )}
+
+              {isFilterGroup(item) ? (
+                <FilterGroupComponent
+                  depth={depth + 1}
+                  fields={fields}
+                  group={item}
+                  maxDepth={maxDepth}
+                  maxRules={maxRules}
+                  rulesCount={rulesCount}
+                  onChange={(updated) => { handleRuleChange(index, updated); }}
+                  onRemove={() => { handleRemoveItem(index); }}
+                />
+              ) : (
+                <FilterRuleComponent
+                  fields={fields}
+                  rule={item}
+                  onChange={(updated) => { handleRuleChange(index, updated); }}
+                  onRemove={() => { handleRemoveItem(index); }}
+                />
+              )}
+            </React.Fragment>
+          ))
+        )}
+      </div>
+
+      {/* Add Buttons */}
+      <div className="mt-2 flex items-center gap-2">
+        <Button
+          className="gap-1"
+          disabled={!canAddRule}
+          size={buttonSize}
+          type="button"
+          variant="outline"
+          onClick={handleAddRule}
+        >
+          <PlusIcon className="size-3" />
+          Add Rule
+        </Button>
+
+        {!isRoot && (
+          <Button
+            className="gap-1"
+            disabled={!canAddGroup}
+            size={buttonSize}
+            type="button"
+            variant="outline"
+            onClick={handleAddGroup}
+          >
+            <PlusIcon className="size-3" />
+            Add Group
+          </Button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// ============================================
+// FILTER TOOLBAR COMPONENT
+// ============================================
+
+function FilterToolbar({
+  canAddGroup,
+  canAddRule,
+  hasRules,
+  onAddGroup,
+  onAddRule,
+  onApply,
+  onClear,
+}: FilterToolbarProps) {
+  const { size } = useFilterBuilderContext()
+  const buttonSize = size === "lg" ? "default" : "sm"
+
+  return (
+    <div
+      className={cn(filterToolbarVariants({ size }))}
+      data-slot="filter-toolbar"
+    >
+      <div className="flex items-center gap-2">
+        <Button
+          className="gap-1"
+          disabled={!canAddRule}
+          size={buttonSize}
+          type="button"
+          variant="outline"
+          onClick={onAddRule}
+        >
+          <PlusIcon className="size-3" />
+          Add Rule
+        </Button>
+
+        <Button
+          className="gap-1"
+          disabled={!canAddGroup}
+          size={buttonSize}
+          type="button"
+          variant="outline"
+          onClick={onAddGroup}
+        >
+          <PlusIcon className="size-3" />
+          Add Group
+        </Button>
+      </div>
+
+      <div className="flex items-center gap-2">
+        {onClear && hasRules && (
+          <Button
+            size={buttonSize}
+            type="button"
+            variant="ghost"
+            onClick={onClear}
+          >
+            Clear All
+          </Button>
+        )}
+
+        {onApply && (
+          <Button
+            size={buttonSize}
+            type="button"
+            variant="default"
+            onClick={onApply}
+          >
+            Apply Filters
+          </Button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// ============================================
+// FILTER PREVIEW COMPONENT
+// ============================================
+
+function FilterPreview({ fields, filter }: FilterPreviewProps) {
+  const { size } = useFilterBuilderContext()
+
+  const getFieldLabel = (fieldName: string): string => {
+    const field = fields.find((f) => f.name === fieldName)
+    return field?.label ?? fieldName
+  }
+
+  const formatValue = (value: unknown): string => {
+    if (Array.isArray(value)) {
+      return value.join(" and ")
+    }
+    return String(value)
+  }
+
+  const renderRule = (rule: FilterRule): string => {
+    if (!rule.field || !rule.operator) return ""
+
+    const fieldLabel = getFieldLabel(rule.field)
+    // After the check above, rule.operator is guaranteed to be a valid OperatorType
+    const operatorLabel = OPERATOR_LABELS[rule.operator]
+
+    if (["is_empty", "is_not_empty"].includes(rule.operator)) {
+      return `${fieldLabel} ${operatorLabel}`
+    }
+
+    return `${fieldLabel} ${operatorLabel} "${formatValue(rule.value)}"`
+  }
+
+  const renderGroup = (group: FilterGroup): string => {
+    const parts = group.rules
+      .map((item) => {
+        if (isFilterGroup(item)) {
+          return `(${renderGroup(item)})`
+        }
+        return renderRule(item)
+      })
+      .filter(Boolean)
+
+    return parts.join(` ${group.combinator.toUpperCase()} `)
+  }
+
+  const preview = renderGroup(filter)
+
+  if (!preview) {
+    return (
+      <div
+        className={cn(filterPreviewVariants({ size }), "italic text-muted-foreground")}
+        data-slot="filter-preview"
+      >
+        No filters defined
+      </div>
+    )
+  }
+
+  return (
+    <div
+      className={cn(filterPreviewVariants({ size }))}
+      data-slot="filter-preview"
+    >
+      <code>{preview}</code>
+    </div>
+  )
+}
+
+// ============================================
+// MAIN FILTER BUILDER COMPONENT
+// ============================================
+
+/**
+ * FilterBuilder - Advanced visual query builder component
+ *
+ * Allows creating complex filters with multiple conditions,
+ * logical operators (AND/OR), nested groups, and various field types.
+ *
+ * @example
+ * ```tsx
+ * const fields = [
+ *   { name: "name", label: "Name", type: "string" },
+ *   { name: "age", label: "Age", type: "number" },
+ *   { name: "status", label: "Status", type: "select", options: [
+ *     { value: "active", label: "Active" },
+ *     { value: "inactive", label: "Inactive" },
+ *   ]},
+ * ]
+ *
+ * <FilterBuilder
+ *   fields={fields}
+ *   value={filter}
+ *   onChange={setFilter}
+ *   onApply={(f) => console.log("Apply:", f)}
+ * />
+ * ```
+ */
+function FilterBuilder({
+  className,
+  fields,
+  maxDepth = 3,
+  maxRules = 20,
+  onApply,
+  onChange,
+  onClear,
+  showPreview = false,
+  size = "default",
+  value,
+  ...props
+}: FilterBuilderProps) {
+  const filter = value ?? createEmptyGroup()
+
+  const handleChange = (updatedFilter: FilterGroup) => {
+    onChange?.(updatedFilter)
+  }
+
+  const handleAddRule = () => {
+    const rulesCount = countRules(filter)
+    if (rulesCount >= maxRules) return
+    handleChange({ ...filter, rules: [...filter.rules, createEmptyRule()] })
+  }
+
+  const handleAddGroup = () => {
+    const rulesCount = countRules(filter)
+    if (rulesCount >= maxRules) return
+    handleChange({ ...filter, rules: [...filter.rules, createEmptyGroup()] })
+  }
+
+  const handleClear = () => {
+    handleChange(createEmptyGroup())
+    onClear?.()
+  }
+
+  const handleApply = () => {
+    onApply?.(filter)
+  }
+
+  const rulesCount = countRules(filter)
+  const hasRules = rulesCount > 0
+  const canAddRule = rulesCount < maxRules
+  const canAddGroup = rulesCount < maxRules
+
+  return (
+    <FilterBuilderContext value={{ fields, size: size ?? "default" }}>
+      <div
+        aria-label="Filter builder"
+        className={cn(filterBuilderVariants({ size }), className)}
+        data-slot="filter-builder"
+        role="region"
+        {...props}
+      >
+        {/* Main Filter Group */}
+        <FilterGroupComponent
+          isRoot
+          depth={0}
+          fields={fields}
+          group={filter}
+          maxDepth={maxDepth}
+          maxRules={maxRules}
+          rulesCount={rulesCount}
+          onChange={handleChange}
+        />
+
+        {/* Toolbar */}
+        <FilterToolbar
+          canAddGroup={canAddGroup}
+          canAddRule={canAddRule}
+          hasRules={hasRules}
+          onAddGroup={handleAddGroup}
+          onAddRule={handleAddRule}
+          onApply={onApply ? handleApply : undefined}
+          onClear={onClear ? handleClear : undefined}
+        />
+
+        {/* Preview */}
+        {showPreview && (
+          <FilterPreview fields={fields} filter={filter} />
+        )}
+      </div>
+    </FilterBuilderContext>
+  )
+}
+
+FilterBuilder.displayName = "FilterBuilder"
+
+// ============================================
+// EXPORTS
+// ============================================
+
+export {
+  FilterBuilder,
+  type FilterBuilderProps,
+  FilterGroupComponent as FilterGroup,
+  type FilterGroupProps,
+  FilterPreview,
+  type FilterPreviewProps,
+  FilterRuleComponent as FilterRule,
+  type FilterRuleProps,
+  FilterToolbar,
+  type FilterToolbarProps,
+}