feat(adapter-stellar): add comprehensive history filtering (changeType, txId, timestamp, ledger) (#268)

* feat(adapter-stellar): add server-side changeType filtering to getHistory

Adds support for filtering history events by change type (GRANTED, REVOKED,
TRANSFERRED) at the server level via GraphQL. This enables proper filtering
across paginated results, fixing the limitation where client-side filtering
only worked on the current page.

Changes:
- Add HistoryChangeType to types package
- Add changeType parameter to HistoryQueryOptions and IndexerHistoryOptions
- Update buildHistoryQuery() to include type filter in GraphQL query
- Add integration tests for changeType filtering
- Fix unit tests with missing pageInfo in mock responses

* fix: address PR review - add TRANSFERRED support to HistoryEntry

- Add 'TRANSFERRED' to HistoryEntry.changeType union type
- Update transformIndexerEntries to map OWNERSHIP_TRANSFER_COMPLETED to 'TRANSFERRED'
- Add integration test for TRANSFERRED changeType filtering
- Update unit test expectation for ownership transfer mapping
- Refactor: use HistoryChangeType type alias consistently (DRY)

* feat(adapter-stellar): add txId, timestamp, and ledger filters to getHistory

Extends the history query API with additional server-side filtering options:
- txId: filter by exact transaction ID match
- timestampFrom/timestampTo: filter by timestamp range
- ledger: filter by exact block/ledger number

Key implementation details:
- Uses BigFloat for blockHeight GraphQL variable type
- Uses Datetime for timestamp GraphQL variable type
- Timestamps should be passed without timezone suffix (e.g., '2025-12-05T10:34:00')

All filters can be combined with existing roleId, account, and changeType filters.

* refactor(adapter-stellar): remove duplicate IndexerHistoryOptions interface

- Use HistoryQueryOptions from types package instead of local duplicate
- Fix comment to correctly state BigFloat for blockHeight filtering

* feat(ui): add date range picker components

- Add Calendar component using react-day-picker with shadcn styling
- Add Popover component using Radix UI primitives
- Add DateRangePicker component combining calendar and popover
- Add react-day-picker and date-fns dependencies

* fix: address PR review comments

- Update timestamp format docs to use generic 'YYYY-MM-DDTHH:mm:ss' format
- Add assertions to verify timestamps are within bounds in tests

Author: pasevin

packages/adapter-stellar/src/access-control/indexer-client.ts

@@ -8,6 +8,7 @@
 import type {
   HistoryChangeType,
   HistoryEntry,
+  HistoryQueryOptions,
   IndexerEndpointConfig,
   PageInfo,
   PaginatedHistoryResult,
@@ -81,19 +82,6 @@ export interface GrantInfo {
   ledger: number;
 }
 
-/**
- * Options for querying history with pagination
- */
-export interface IndexerHistoryOptions {
-  roleId?: string;
-  account?: string;
-  /** Filter by change type (grant, revoke, or ownership transfer) */
-  changeType?: HistoryChangeType;
-  limit?: number;
-  /** Cursor for fetching the next page */
-  cursor?: string;
-}
-
 /**
  * Stellar Indexer Client
  * Handles GraphQL queries to the configured indexer for historical access control data
@@ -170,7 +158,7 @@ export class StellarIndexerClient {
    */
   async queryHistory(
     contractAddress: string,
-    options?: IndexerHistoryOptions
+    options?: HistoryQueryOptions
   ): Promise<PaginatedHistoryResult> {
     const isAvailable = await this.checkAvailability();
     if (!isAvailable) {
@@ -539,21 +527,38 @@ export class StellarIndexerClient {
   /**
    * Build GraphQL query for history with SubQuery filtering and pagination
    */
-  private buildHistoryQuery(_contractAddress: string, options?: IndexerHistoryOptions): string {
+  private buildHistoryQuery(_contractAddress: string, options?: HistoryQueryOptions): string {
     const roleFilter = options?.roleId ? ', role: { equalTo: $role }' : '';
     const accountFilter = options?.account ? ', account: { equalTo: $account }' : '';
     // Type filter uses inline enum value (consistent with buildLatestGrantsQuery pattern)
     const typeFilter = options?.changeType
       ? `, type: { equalTo: ${this.mapChangeTypeToGraphQLEnum(options.changeType)} }`
       : '';
+    const txFilter = options?.txId ? ', txHash: { equalTo: $txHash }' : '';
+    // Build combined timestamp filter to avoid duplicate keys
+    const timestampConditions: string[] = [];
+    if (options?.timestampFrom) {
+      timestampConditions.push('greaterThanOrEqualTo: $timestampFrom');
+    }
+    if (options?.timestampTo) {
+      timestampConditions.push('lessThanOrEqualTo: $timestampTo');
+    }
+    const timestampFilter =
+      timestampConditions.length > 0 ? `, timestamp: { ${timestampConditions.join(', ')} }` : '';
+    const ledgerFilter = options?.ledger ? ', blockHeight: { equalTo: $blockHeight }' : '';
     const limitClause = options?.limit ? ', first: $limit' : '';
     const cursorClause = options?.cursor ? ', after: $cursor' : '';
 
     // Build variable declarations
+    // Note: SubQuery uses Datetime for timestamp filters and BigFloat for blockHeight filtering
     const varDeclarations = [
       '$contract: String!',
       options?.roleId ? '$role: String' : '',
       options?.account ? '$account: String' : '',
+      options?.txId ? '$txHash: String' : '',
+      options?.timestampFrom ? '$timestampFrom: Datetime' : '',
+      options?.timestampTo ? '$timestampTo: Datetime' : '',
+      options?.ledger ? '$blockHeight: BigFloat' : '',
       options?.limit ? '$limit: Int' : '',
       options?.cursor ? '$cursor: Cursor' : '',
     ]
@@ -564,7 +569,7 @@ export class StellarIndexerClient {
       query GetHistory(${varDeclarations}) {
         accessControlEvents(
           filter: {
-            contract: { equalTo: $contract }${roleFilter}${accountFilter}${typeFilter}
+            contract: { equalTo: $contract }${roleFilter}${accountFilter}${typeFilter}${txFilter}${timestampFilter}${ledgerFilter}
           }
           orderBy: TIMESTAMP_DESC${limitClause}${cursorClause}
         ) {
@@ -591,7 +596,7 @@ export class StellarIndexerClient {
    */
   private buildQueryVariables(
     contractAddress: string,
-    options?: IndexerHistoryOptions
+    options?: HistoryQueryOptions
   ): Record<string, unknown> {
     const variables: Record<string, unknown> = {
       contract: contractAddress,
@@ -603,6 +608,19 @@ export class StellarIndexerClient {
     if (options?.account) {
       variables.account = options.account;
     }
+    if (options?.txId) {
+      variables.txHash = options.txId;
+    }
+    if (options?.timestampFrom) {
+      variables.timestampFrom = options.timestampFrom;
+    }
+    if (options?.timestampTo) {
+      variables.timestampTo = options.timestampTo;
+    }
+    if (options?.ledger) {
+      // GraphQL expects blockHeight as string
+      variables.blockHeight = String(options.ledger);
+    }
     if (options?.limit) {
       variables.limit = options.limit;
     }

packages/adapter-stellar/test/access-control/indexer-integration.test.ts

@@ -672,6 +672,126 @@ describe('StellarIndexerClient - Integration Test with Real Indexer', () => {
         `  ✅ Combined filter: ${combinedResult.items.length} GRANTED events for account '${targetAccount.slice(0, 10)}...'`
       );
     }, 15000);
+
+    it('should filter history by txId (server-side)', async () => {
+      if (!indexerAvailable) {
+        return; // Skip test if indexer is not available
+      }
+
+      // First get all history to find a valid txId
+      const allResult = await client.queryHistory(TEST_CONTRACT, { limit: 10 });
+
+      if (allResult.items.length === 0) {
+        console.log('  ⏭️ No events found, skipping txId filter test');
+        return;
+      }
+
+      const targetTxId = allResult.items[0].txId;
+
+      // Query with txId filter
+      const filteredResult = await client.queryHistory(TEST_CONTRACT, {
+        txId: targetTxId,
+      });
+
+      expect(filteredResult.items.length).toBeGreaterThan(0);
+
+      // Verify ALL returned entries have the matching txId
+      for (const entry of filteredResult.items) {
+        expect(entry.txId).toBe(targetTxId);
+      }
+
+      console.log(
+        `  ✅ Filtered ${filteredResult.items.length} event(s) by txId '${targetTxId.slice(0, 16)}...'`
+      );
+    }, 15000);
+
+    it('should filter history by ledger/blockHeight (server-side)', async () => {
+      if (!indexerAvailable) {
+        return; // Skip test if indexer is not available
+      }
+
+      // First get all history to find a valid ledger number
+      const allResult = await client.queryHistory(TEST_CONTRACT, { limit: 10 });
+
+      if (allResult.items.length === 0) {
+        console.log('  ⏭️ No events found, skipping ledger filter test');
+        return;
+      }
+
+      const targetLedger = allResult.items[0].ledger!;
+
+      // Query with ledger filter
+      const filteredResult = await client.queryHistory(TEST_CONTRACT, {
+        ledger: targetLedger,
+      });
+
+      expect(filteredResult.items.length).toBeGreaterThan(0);
+
+      // Verify ALL returned entries have the matching ledger
+      for (const entry of filteredResult.items) {
+        expect(entry.ledger).toBe(targetLedger);
+      }
+
+      console.log(
+        `  ✅ Filtered ${filteredResult.items.length} event(s) at ledger ${targetLedger}`
+      );
+    }, 15000);
+
+    it('should filter history by timestamp range (server-side)', async () => {
+      if (!indexerAvailable) {
+        return; // Skip test if indexer is not available
+      }
+
+      // Use known timestamp range - indexer stores times without timezone
+      // Events are around 2025-12-05T10:34:xx (indexer time, no Z suffix)
+      const timestampFrom = '2025-12-05T10:34:00';
+      const timestampTo = '2025-12-05T10:35:00';
+
+      const filteredResult = await client.queryHistory(TEST_CONTRACT, {
+        timestampFrom,
+        timestampTo,
+        limit: 20,
+      });
+
+      expect(filteredResult.items.length).toBeGreaterThan(0);
+
+      // Verify all returned events have timestamps within the specified range
+      for (const item of filteredResult.items) {
+        if (item.timestamp) {
+          expect(item.timestamp >= timestampFrom).toBe(true);
+          expect(item.timestamp <= timestampTo).toBe(true);
+        }
+      }
+
+      console.log(
+        `  ✅ Filtered ${filteredResult.items.length} event(s) in timestamp range (${timestampFrom} to ${timestampTo})`
+      );
+    }, 15000);
+
+    it('should filter with timestampFrom only (events after date)', async () => {
+      if (!indexerAvailable) {
+        return; // Skip test if indexer is not available
+      }
+
+      // Use known timestamp - indexer stores times without timezone
+      const timestampFrom = '2025-12-05T10:34:20';
+
+      const filteredResult = await client.queryHistory(TEST_CONTRACT, {
+        timestampFrom,
+        limit: 20,
+      });
+
+      expect(filteredResult.items.length).toBeGreaterThan(0);
+
+      // Verify all returned events have timestamps on or after timestampFrom
+      for (const item of filteredResult.items) {
+        if (item.timestamp) {
+          expect(item.timestamp >= timestampFrom).toBe(true);
+        }
+      }
+
+      console.log(`  ✅ Filtered ${filteredResult.items.length} event(s) from ${timestampFrom}`);
+    }, 15000);
   });
 
   describe('History Query - Known Event Verification', () => {

packages/types/src/adapters/access-control.ts

@@ -143,6 +143,14 @@ export interface HistoryQueryOptions {
   account?: string;
   /** Filter by change type (grant, revoke, or ownership transfer) */
   changeType?: HistoryChangeType;
+  /** Filter by transaction ID (exact match) */
+  txId?: string;
+  /** Filter by timestamp - return events on or after this time (format: 'YYYY-MM-DDTHH:mm:ss', no timezone) */
+  timestampFrom?: string;
+  /** Filter by timestamp - return events on or before this time (format: 'YYYY-MM-DDTHH:mm:ss', no timezone) */
+  timestampTo?: string;
+  /** Filter by ledger/block number (exact match) */
+  ledger?: number;
   /** Maximum number of items to return (page size) */
   limit?: number;
   /** Cursor for fetching the next page */

packages/ui/package.json

@@ -57,6 +57,7 @@
     "@radix-ui/react-dialog": "^1.1.14",
     "@radix-ui/react-dropdown-menu": "^2.1.15",
     "@radix-ui/react-label": "^2.1.7",
+    "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-progress": "^1.1.7",
     "@radix-ui/react-radio-group": "^1.3.7",
     "@radix-ui/react-select": "^2.2.5",
@@ -68,9 +69,11 @@
     "@web3icons/react": "^4.0.26",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
     "lodash": "^4.17.21",
     "lucide-react": "^0.510.0",
     "next-themes": "^0.4.6",
+    "react-day-picker": "^9.12.0",
     "react-hook-form": "^7.62.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.3.1",

packages/ui/src/components/ui/calendar.tsx

@@ -0,0 +1,79 @@
+'use client';
+
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import * as React from 'react';
+import { DayPicker } from 'react-day-picker';
+
+import { cn } from '@openzeppelin/ui-builder-utils';
+
+import { buttonVariants } from '../../utils/button-variants';
+
+export type CalendarProps = React.ComponentProps<typeof DayPicker>;
+
+/**
+ * Calendar component built on react-day-picker with shadcn/ui styling.
+ * Supports single date, multiple dates, and date range selection modes.
+ */
+function Calendar({
+  className,
+  classNames,
+  showOutsideDays = true,
+  ...props
+}: CalendarProps): React.ReactElement {
+  return (
+    <DayPicker
+      showOutsideDays={showOutsideDays}
+      className={cn('p-3', className)}
+      classNames={{
+        months: 'flex flex-col sm:flex-row gap-2 px-5',
+        month: 'flex flex-col gap-4',
+        month_caption: 'flex justify-center pt-1 relative items-center w-full',
+        caption_label: 'text-sm font-medium',
+        nav: 'flex items-center gap-1',
+        button_previous: cn(
+          buttonVariants({ variant: 'outline' }),
+          'absolute left-1 h-7 w-7 bg-transparent p-0 opacity-50 hover:opacity-100'
+        ),
+        button_next: cn(
+          buttonVariants({ variant: 'outline' }),
+          'absolute right-1 h-7 w-7 bg-transparent p-0 opacity-50 hover:opacity-100'
+        ),
+        month_grid: 'w-full border-collapse space-y-1',
+        weekdays: 'flex',
+        weekday: 'text-muted-foreground rounded-md w-9 font-normal text-[0.8rem]',
+        week: 'flex w-full mt-2',
+        day: cn(
+          'relative p-0 text-center text-sm focus-within:relative focus-within:z-20 [&:has([aria-selected])]:bg-accent [&:has([aria-selected].day-outside)]:bg-accent/50 [&:has([aria-selected].day-range-end)]:rounded-r-md',
+          props.mode === 'range'
+            ? '[&:has(>.day-range-end)]:rounded-r-md [&:has(>.day-range-start)]:rounded-l-md first:[&:has([aria-selected])]:rounded-l-md last:[&:has([aria-selected])]:rounded-r-md'
+            : '[&:has([aria-selected])]:rounded-md'
+        ),
+        day_button: cn(
+          buttonVariants({ variant: 'ghost' }),
+          'h-9 w-9 p-0 font-normal aria-selected:opacity-100 rounded-none hover:rounded-none'
+        ),
+        range_start: 'day-range-start rounded-l-md',
+        range_end: 'day-range-end rounded-r-md',
+        selected:
+          'bg-zinc-200 dark:bg-zinc-700 text-foreground hover:bg-zinc-200 dark:hover:bg-zinc-700 hover:text-foreground focus:bg-zinc-200 dark:focus:bg-zinc-700 focus:text-foreground',
+        today: 'bg-accent text-accent-foreground',
+        outside:
+          'day-outside text-muted-foreground opacity-50 aria-selected:bg-accent/50 aria-selected:text-muted-foreground aria-selected:opacity-30',
+        disabled: 'text-muted-foreground opacity-50',
+        range_middle: 'aria-selected:bg-accent aria-selected:text-accent-foreground',
+        hidden: 'invisible',
+        ...classNames,
+      }}
+      components={{
+        Chevron: ({ orientation }) => {
+          const Icon = orientation === 'left' ? ChevronLeft : ChevronRight;
+          return <Icon className="h-4 w-4" />;
+        },
+      }}
+      {...props}
+    />
+  );
+}
+Calendar.displayName = 'Calendar';
+
+export { Calendar };