feat: add direction filter to address events tab

Add incoming/outgoing/all direction control to the events filter bar,
with bidirectional sync between direction and source/destination filters.
Extract shared applyEventDirectionSync utility for desktop and mobile.

Author: sallymoc

src/pages/network/address/components/AddressEvents.tsx

@@ -17,6 +17,7 @@ export default function AddressEvents({ addressId }: Props) {
     events,
     total,
     eventType,
+    direction,
     tickStart,
     tickEnd,
     dateRange,
@@ -30,9 +31,11 @@ export default function AddressEvents({ addressId }: Props) {
     tickStart,
     tickEnd,
     eventType,
+    direction,
     dateRange,
     sourceFilter,
-    destinationFilter
+    destinationFilter,
+    addressId
   })
 
   return (
@@ -42,12 +45,15 @@ export default function AddressEvents({ addressId }: Props) {
       <EventsFilterBar
         filters={filters}
         eventType={eventType}
+        direction={direction}
         tickStart={tickStart}
         tickEnd={tickEnd}
         dateRange={dateRange}
         sourceFilter={sourceFilter}
         destinationFilter={destinationFilter}
         idPrefix="addr-events"
+        showDirectionFilter
+        addressId={addressId}
       />
 
       {hasError ? (

src/pages/network/address/components/TransactionsOverview/filterUtils.ts

@@ -250,7 +250,7 @@ export const DATE_PRESETS = [
 /**
  * Helper to check if an address filter contains only the page address
  */
-function isOnlyPageAddress(filter: AddressFilter | undefined, addressId: string): boolean {
+export function isOnlyPageAddress(filter: AddressFilter | undefined, addressId: string): boolean {
   if (!filter) return false
   const validAddresses = filter.addresses.filter((addr) => addr.trim() !== '')
   return validAddresses.length === 1 && validAddresses[0] === addressId

src/pages/network/address/hooks/useAddressEvents.ts

@@ -8,7 +8,11 @@ import {
   useValidatedPageSize
 } from '@app/hooks'
 import { type ShouldFilter, type TransactionEvent, useGetEventsQuery } from '@app/store/apis/events'
-import type { AddressFilter } from '../components/TransactionsOverview/filterUtils'
+import type {
+  AddressFilter,
+  TransactionDirection
+} from '../components/TransactionsOverview/filterUtils'
+import { DIRECTION } from '../components/TransactionsOverview/filterUtils'
 import {
   buildEventAddressFilter,
   buildTickFilter,
@@ -23,6 +27,7 @@ export default function useAddressEvents(addressId: string): {
   events: TransactionEvent[]
   total: number
   eventType: number | undefined
+  direction: TransactionDirection | undefined
   tickStart: string | undefined
   tickEnd: string | undefined
   dateRange: DateRangeValue | undefined
@@ -45,16 +50,40 @@ export default function useAddressEvents(addressId: string): {
 
   const eventType = useSanitizedEventType()
 
-  const should = useMemo<ShouldFilter[]>(
-    () => [{ terms: { source: addressId, destination: addressId } }],
-    [addressId]
-  )
+  const directionRaw = searchParams.get('direction')
+  const direction: TransactionDirection | undefined =
+    directionRaw === DIRECTION.INCOMING || directionRaw === DIRECTION.OUTGOING
+      ? directionRaw
+      : undefined
 
   const { tickNumber, tickRange } = buildTickFilter(tickStart, tickEnd)
 
   const timestampRange = buildTimestampRange(dateRange)
-  const sourceResult = buildEventAddressFilter(sourceFilter)
-  const destResult = buildEventAddressFilter(destinationFilter)
+
+  // When direction is set, the conflicting filter is ignored (disabled in UI).
+  const isIncoming = direction === DIRECTION.INCOMING
+  const isOutgoing = direction === DIRECTION.OUTGOING
+
+  const effectiveSourceFilter = isOutgoing ? undefined : sourceFilter
+  const effectiveDestFilter = isIncoming ? undefined : destinationFilter
+
+  const sourceResult = buildEventAddressFilter(effectiveSourceFilter)
+  const destResult = buildEventAddressFilter(effectiveDestFilter)
+
+  // Use `should` (OR) to scope results to the page address when no explicit direction is set.
+  // When direction is set, implicit source/dest handles the scoping instead.
+  const useShouldFilter = !direction
+
+  const should = useMemo<ShouldFilter[] | undefined>(
+    () =>
+      useShouldFilter ? [{ terms: { source: addressId, destination: addressId } }] : undefined,
+    [addressId, useShouldFilter]
+  )
+
+  // When direction is set, implicit source/dest scopes to the page address.
+  // When direction is undefined, `should` (OR) handles scoping instead.
+  const implicitSource = isOutgoing ? addressId : undefined
+  const implicitDest = isIncoming ? addressId : undefined
 
   const { data, isFetching, isError } = useGetEventsQuery(
     {
@@ -65,9 +94,9 @@ export default function useAddressEvents(addressId: string): {
       offset,
       size: pageSize,
       logType: eventType,
-      source: sourceResult.include,
+      source: sourceResult.include ?? implicitSource,
       excludeSource: sourceResult.exclude,
-      destination: destResult.include,
+      destination: destResult.include ?? implicitDest,
       excludeDestination: destResult.exclude
     },
     { skip: !addressId }
@@ -81,6 +110,7 @@ export default function useAddressEvents(addressId: string): {
     events: data?.events ?? [],
     total,
     eventType,
+    direction,
     tickStart,
     tickEnd,
     dateRange,

src/pages/network/components/filters/EventsFilterBar.tsx

@@ -3,7 +3,11 @@ import { useTranslation } from 'react-i18next'
 
 import { FunnelIcon } from '@app/assets/icons'
 import { getEventTypeLabel } from '@app/store/apis/events'
-import type { AddressFilter } from '../../address/components/TransactionsOverview/filterUtils'
+import type {
+  AddressFilter,
+  TransactionDirection
+} from '../../address/components/TransactionsOverview/filterUtils'
+import DirectionControl from '../../address/components/TransactionsOverview/DirectionControl'
 import DateFilterContent from '../../address/components/TransactionsOverview/DateFilterContent'
 import MultiAddressFilterContent from '../../address/components/TransactionsOverview/MultiAddressFilterContent'
 import { formatRangeLabel } from '../../hooks'
@@ -22,6 +26,7 @@ import ResetFiltersButton from './ResetFiltersButton'
 type Props = {
   filters: EventFiltersResult
   eventType: number | undefined
+  direction?: TransactionDirection | undefined
   tickStart?: string
   tickEnd?: string
   dateRange?: DateRangeValue
@@ -30,19 +35,24 @@ type Props = {
   idPrefix: string
   showTickFilter?: boolean
   showDateFilter?: boolean
+  showDirectionFilter?: boolean
+  addressId?: string
 }
 
 export default function EventsFilterBar({
   filters,
   eventType,
+  direction,
   tickStart,
   tickEnd,
   dateRange,
   sourceFilter,
   destinationFilter,
   idPrefix,
   showTickFilter = true,
-  showDateFilter = true
+  showDateFilter = true,
+  showDirectionFilter = false,
+  addressId
 }: Props) {
   const { t } = useTranslation('network-page')
   const [openDropdown, setOpenDropdown] = useState<string | null>(null)
@@ -66,6 +76,7 @@ export default function EventsFilterBar({
 
   const mobileActiveFilters: EventsFilters = {
     eventType,
+    direction,
     sourceFilter,
     destinationFilter,
     ...(showTickFilter && {
@@ -76,9 +87,18 @@ export default function EventsFilterBar({
 
   return (
     <>
-      {/* Mobile: Filters button + active filter chips */}
+      {/* Mobile: Direction control + filters button + active filter chips */}
       <div className="flex flex-col gap-10 sm:hidden">
-        <div className="flex items-center justify-end">
+        <div
+          className={`flex items-center ${showDirectionFilter ? 'justify-between' : 'justify-end'}`}
+        >
+          {showDirectionFilter && (
+            <DirectionControl
+              value={direction}
+              onChange={filters.handleDirectionChange}
+              showTooltips
+            />
+          )}
           <MobileFiltersButton onClick={() => setIsMobileModalOpen(true)} />
         </div>
 
@@ -116,11 +136,20 @@ export default function EventsFilterBar({
         idPrefix={idPrefix}
         showTickFilter={showTickFilter}
         showDateFilter={showDateFilter}
+        showDirectionFilter={showDirectionFilter}
+        addressId={addressId}
       />
 
       {/* Desktop: Dropdown filters */}
       <div className="hidden items-center gap-8 sm:flex">
         <FunnelIcon className="h-16 w-16 text-gray-50" />
+        {showDirectionFilter && (
+          <DirectionControl
+            value={direction}
+            onChange={filters.handleDirectionChange}
+            showTooltips
+          />
+        )}
         <FilterDropdown
           label={eventTypeLabel}
           isActive={filters.isEventTypeActive}

src/pages/network/components/filters/EventsMobileFiltersModal.tsx

@@ -3,9 +3,14 @@ import { useTranslation } from 'react-i18next'
 
 import { useBodyScrollLock } from '@app/hooks'
 import DateFilterContent from '../../address/components/TransactionsOverview/DateFilterContent'
-import type { AddressFilter } from '../../address/components/TransactionsOverview/filterUtils'
+import type {
+  AddressFilter,
+  TransactionDirection
+} from '../../address/components/TransactionsOverview/filterUtils'
+import DirectionControl from '../../address/components/TransactionsOverview/DirectionControl'
 import MultiAddressFilterContent from '../../address/components/TransactionsOverview/MultiAddressFilterContent'
 import type { DateRangeValue, TickRangeValue } from '../../utils/eventFilterUtils'
+import { applyEventDirectionSync } from '../../utils/eventFilterUtils'
 import EventTypeChips from './EventTypeChips'
 import MobileFiltersModalWrapper from './MobileFiltersModalWrapper'
 import MobileFilterSection from './MobileFilterSection'
@@ -17,6 +22,7 @@ export type EventsFilters = {
   dateRange?: DateRangeValue
   sourceFilter?: AddressFilter
   destinationFilter?: AddressFilter
+  direction?: TransactionDirection
 }
 
 type Props = {
@@ -27,6 +33,8 @@ type Props = {
   idPrefix: string
   showTickFilter?: boolean
   showDateFilter?: boolean
+  showDirectionFilter?: boolean
+  addressId?: string
 }
 
 export default function EventsMobileFiltersModal({
@@ -36,7 +44,9 @@ export default function EventsMobileFiltersModal({
   onApplyFilters,
   idPrefix,
   showTickFilter = true,
-  showDateFilter = true
+  showDateFilter = true,
+  showDirectionFilter = false,
+  addressId
 }: Props) {
   const { t } = useTranslation('network-page')
 
@@ -55,6 +65,25 @@ export default function EventsMobileFiltersModal({
   const [localDestFilter, setLocalDestFilter] = useState<AddressFilter | undefined>(
     activeFilters.destinationFilter
   )
+  const [localDirection, setLocalDirection] = useState<TransactionDirection | undefined>(
+    activeFilters.direction
+  )
+
+  const handleLocalDirectionChange = useCallback(
+    (newDirection: TransactionDirection | undefined) => {
+      setLocalDirection(newDirection)
+      if (!addressId) return
+      const { sourceFilter: newSrc, destinationFilter: newDest } = applyEventDirectionSync(
+        newDirection,
+        addressId,
+        localSourceFilter,
+        localDestFilter
+      )
+      setLocalSourceFilter(newSrc)
+      setLocalDestFilter(newDest)
+    },
+    [addressId, localSourceFilter, localDestFilter]
+  )
 
   useEffect(() => {
     if (isOpen) {
@@ -63,14 +92,16 @@ export default function EventsMobileFiltersModal({
       setLocalDateRange(activeFilters.dateRange)
       setLocalSourceFilter(activeFilters.sourceFilter)
       setLocalDestFilter(activeFilters.destinationFilter)
+      setLocalDirection(activeFilters.direction)
     }
   }, [
     isOpen,
     activeFilters.tickRange,
     activeFilters.eventType,
     activeFilters.dateRange,
     activeFilters.sourceFilter,
-    activeFilters.destinationFilter
+    activeFilters.destinationFilter,
+    activeFilters.direction
   ])
 
   const handleApply = useCallback(() => {
@@ -79,7 +110,8 @@ export default function EventsMobileFiltersModal({
       eventType: localEventType,
       dateRange: localDateRange,
       sourceFilter: localSourceFilter,
-      destinationFilter: localDestFilter
+      destinationFilter: localDestFilter,
+      direction: localDirection
     })
     onClose()
   }, [
@@ -88,6 +120,7 @@ export default function EventsMobileFiltersModal({
     localDateRange,
     localSourceFilter,
     localDestFilter,
+    localDirection,
     onApplyFilters,
     onClose
   ])
@@ -99,6 +132,12 @@ export default function EventsMobileFiltersModal({
       onClose={onClose}
       onApply={handleApply}
     >
+      {showDirectionFilter && (
+        <MobileFilterSection id={`${idPrefix}-mobile-direction-filter`} label={t('direction')}>
+          <DirectionControl value={localDirection} onChange={handleLocalDirectionChange} />
+        </MobileFilterSection>
+      )}
+
       <MobileFilterSection id={`${idPrefix}-mobile-event-type-filter`} label={t('eventType')}>
         <EventTypeChips selectedType={localEventType} onSelectType={setLocalEventType} />
       </MobileFilterSection>