Frontend

Date Dropper & Wheel Picker

Relevant source files

The following files were used as context for generating this wiki page:

The Date Dropper system provides a touch-friendly, wheel-based interface for selecting dates and times. It is built upon a custom WheelPicker primitive and supports high-precision CalendarDate and CalendarDateTime objects from the @internationalized/date library.

1. DateDropper Component

The DateDropper (implemented as date-wheel-picker.svelte) is the primary UI component for date selection. It wraps the wheel selection logic in a Popover and handles the conversion between internal wheel states and structured date objects src/lib/components/date-dropper/date-wheel-picker.svelte:1-26.

1.1 Value Types and Props

The component supports two primary modes of operation based on the includeTime prop:

CalendarDate: Used when includeTime is false.
CalendarDateTime: Used when includeTime is true, adding hour, minute, and second precision src/lib/components/date-dropper/date-wheel-picker.svelte:176-191.

Prop	Type	Description
`value`	`CalendarDate \| CalendarDateTime`	The $bindable value representing the selected point in time src/lib/components/date-dropper/date-wheel-picker.svelte:26-26.
`includeTime`	`boolean`	Enables time selection (hours/minutes/seconds) src/lib/components/date-dropper/date-wheel-picker.svelte:26-26.
`timezone`	`string`	$bindable IANA timezone string src/lib/components/date-dropper/date-wheel-picker.svelte:26-26.
`defaultTime`	`string`	Optional "HH:mm" string to initialize the time wheels src/lib/components/date-dropper/date-wheel-picker.svelte:26-26.

1.2 Timezone Management

The component integrates with the browser's IANA timezone database. It uses getResolvedIanaTimeZone to detect the user's system timezone on mount src/lib/components/date-dropper/date-wheel-picker.svelte:80-85.

IANA Toggle: Users can search and select from all supported IANA timezones via an internal DropdownMenu src/lib/components/date-dropper/date-wheel-picker.svelte:93-124.
Display Logic: Timezones are retrieved via Intl.supportedValuesOf('timeZone') with a fallback list for legacy environments src/lib/components/date-dropper/date-wheel-picker.svelte:93-116.

Sources:

2. WheelPicker Primitive

The WheelPicker is a low-level UI primitive that provides a 3D-rotated, scrollable selection interface. It uses Svelte 5 Runes for reactive state management across a group of items.

2.1 Component Architecture

The system is divided into three parts:

WheelPicker (Container): Provides the 3D perspective and visual overlays (gradients and selection highlight) src/lib/components/ui/wheel-picker/wheel-picker.svelte:12-32.
WheelPickerGroup: Manages the physics, scrolling, and snapping logic for a single column (e.g., "Month" or "Hour") src/lib/components/ui/wheel-picker/wheel-picker-group.svelte:7-19.
WheelPickerItem: Individual selectable nodes that calculate their own 3D transform based on their distance from the center src/lib/components/ui/wheel-picker/wheel-picker-item.svelte:33-73.

2.2 State Management (`ctx.svelte.ts`)

The WheelState class uses $state to share real-time scroll positions and dragging status between the group and its items src/lib/components/ui/wheel-picker/ctx.svelte.ts:5-10.

2.3 Physics and Interaction

The WheelPickerGroup implements custom scroll physics:

Inertia: Calculates velocity during drag and continues movement after release with friction src/lib/components/ui/wheel-picker/wheel-picker-group.svelte:143-165.
Snapping: Automatically aligns the nearest item to the center highlight using snapToNearest src/lib/components/ui/wheel-picker/wheel-picker-group.svelte:168-171.
Looping: If loop is enabled, items wrap around infinitely using modulo arithmetic on the scroll position src/lib/components/ui/wheel-picker/wheel-picker-group.svelte:72-79.

Wheel Picker Data Flow

The following diagram illustrates how interaction with the UI updates the shared context and eventually the bound value.

Title: Wheel Picker Interaction Flow

Code
graph TD
    subgraph "User Input"
        "onmousedown"["onmousedown / ontouchstart"]
        "onwheel"["onwheel"]
    end

    subgraph "WheelPickerGroup (Logic)"
        "handleStart"["handleStart()"]
        "setScroll"["setScroll(y)"]
        "snapTo"["snapTo(targetY)"]
        "commitValue"["commitValue()"]
    end

    subgraph "WheelState (Context)"
        "translateY"["$state: translateY"]
        "isDragging"["$state: isDragging"]
    end

    subgraph "WheelPickerItem (View)"
        "calcTransform"["calculate 3D transform"]
        "isSelected"["aria-selected"]
    end

    "onmousedown" --> "handleStart"
    "onwheel" --> "setScroll"
    "handleStart" --> "isDragging"
    "setScroll" --> "translateY"
    "translateY" --> "calcTransform"
    "translateY" --> "isSelected"
    "snapTo" --> "commitValue"
    "commitValue" --> "val_update"["Update $bindable value"]

Sources:

3. Integration with Entity List

The Date Dropper is heavily utilized within the FiltersPanel for filtering entity records by date or datetime fields.

3.1 Date Normalization and Formatting

When displaying dates in the EntityListTable, the system differentiates between the browser's local time and the time stored in the record (if an IANA timezone field is present).

formatDatetimeIanaListCell: This function determines whether to format the date using the user's browser locale or a specific IANA timezone defined in the record's metadata src/lib/entity-list/format-datetime-iana-cell.ts:6-24.
datetimeIanaToggle: A configuration in the MetaColumn that indicates if a column should support switching between local and record-specific timezones src/lib/entity-list/format-datetime-iana-cell.ts:12-14.

Date Processing Architecture

This diagram shows the relationship between the raw data from the API and the UI components.

Title: Date Processing and Rendering Pipeline

Code
graph LR
    subgraph "Data Layer"
        "API_Row"["API Row Record"]
        "MetaColumn"["MetaColumn Config"]
    end

    subgraph "Formatting Logic"
        "formatDatetimeIanaListCell"["formatDatetimeIanaListCell()"]
        "formatUiDateTimeInTimeZone"["formatUiDateTimeInTimeZone()"]
    end

    subgraph "UI Components"
        "DateDropper"["DateDropper Component"]
        "FiltersPanel"["FiltersPanel (Inputs)"]
        "TableCell"["EntityListTable Cell"]
    end

    "API_Row" --> "formatDatetimeIanaListCell"
    "MetaColumn" --> "formatDatetimeIanaListCell"
    "formatDatetimeIanaListCell" --> "formatUiDateTimeInTimeZone"
    "formatUiDateTimeInTimeZone" --> "TableCell"
    "DateDropper" -- "produces" --> "CalendarDateTime"
    "CalendarDateTime" -- "filter input" --> "FiltersPanel"

Sources:

Last modified on July 13, 2026

Customer List & CRM Development Conventions & AI Agent Rules

Frontend

Date Dropper & Wheel Picker

Relevant source files

The following files were used as context for generating this wiki page:

1. DateDropper Component

1.1 Value Types and Props

The component supports two primary modes of operation based on the includeTime prop:

CalendarDate: Used when includeTime is false.
CalendarDateTime: Used when includeTime is true, adding hour, minute, and second precision src/lib/components/date-dropper/date-wheel-picker.svelte:176-191.

Prop	Type	Description
`value`	`CalendarDate \| CalendarDateTime`	The $bindable value representing the selected point in time src/lib/components/date-dropper/date-wheel-picker.svelte:26-26.
`includeTime`	`boolean`	Enables time selection (hours/minutes/seconds) src/lib/components/date-dropper/date-wheel-picker.svelte:26-26.
`timezone`	`string`	$bindable IANA timezone string src/lib/components/date-dropper/date-wheel-picker.svelte:26-26.
`defaultTime`	`string`	Optional "HH:mm" string to initialize the time wheels src/lib/components/date-dropper/date-wheel-picker.svelte:26-26.

1.2 Timezone Management

IANA Toggle: Users can search and select from all supported IANA timezones via an internal DropdownMenu src/lib/components/date-dropper/date-wheel-picker.svelte:93-124.
Display Logic: Timezones are retrieved via Intl.supportedValuesOf('timeZone') with a fallback list for legacy environments src/lib/components/date-dropper/date-wheel-picker.svelte:93-116.

Sources:

2. WheelPicker Primitive

The WheelPicker is a low-level UI primitive that provides a 3D-rotated, scrollable selection interface. It uses Svelte 5 Runes for reactive state management across a group of items.

2.1 Component Architecture

The system is divided into three parts:

WheelPicker (Container): Provides the 3D perspective and visual overlays (gradients and selection highlight) src/lib/components/ui/wheel-picker/wheel-picker.svelte:12-32.
WheelPickerGroup: Manages the physics, scrolling, and snapping logic for a single column (e.g., "Month" or "Hour") src/lib/components/ui/wheel-picker/wheel-picker-group.svelte:7-19.
WheelPickerItem: Individual selectable nodes that calculate their own 3D transform based on their distance from the center src/lib/components/ui/wheel-picker/wheel-picker-item.svelte:33-73.

2.2 State Management (`ctx.svelte.ts`)

The WheelState class uses $state to share real-time scroll positions and dragging status between the group and its items src/lib/components/ui/wheel-picker/ctx.svelte.ts:5-10.

2.3 Physics and Interaction

The WheelPickerGroup implements custom scroll physics:

Inertia: Calculates velocity during drag and continues movement after release with friction src/lib/components/ui/wheel-picker/wheel-picker-group.svelte:143-165.
Snapping: Automatically aligns the nearest item to the center highlight using snapToNearest src/lib/components/ui/wheel-picker/wheel-picker-group.svelte:168-171.
Looping: If loop is enabled, items wrap around infinitely using modulo arithmetic on the scroll position src/lib/components/ui/wheel-picker/wheel-picker-group.svelte:72-79.

Wheel Picker Data Flow

The following diagram illustrates how interaction with the UI updates the shared context and eventually the bound value.

Title: Wheel Picker Interaction Flow

Code
graph TD
    subgraph "User Input"
        "onmousedown"["onmousedown / ontouchstart"]
        "onwheel"["onwheel"]
    end

    subgraph "WheelPickerGroup (Logic)"
        "handleStart"["handleStart()"]
        "setScroll"["setScroll(y)"]
        "snapTo"["snapTo(targetY)"]
        "commitValue"["commitValue()"]
    end

    subgraph "WheelState (Context)"
        "translateY"["$state: translateY"]
        "isDragging"["$state: isDragging"]
    end

    subgraph "WheelPickerItem (View)"
        "calcTransform"["calculate 3D transform"]
        "isSelected"["aria-selected"]
    end

    "onmousedown" --> "handleStart"
    "onwheel" --> "setScroll"
    "handleStart" --> "isDragging"
    "setScroll" --> "translateY"
    "translateY" --> "calcTransform"
    "translateY" --> "isSelected"
    "snapTo" --> "commitValue"
    "commitValue" --> "val_update"["Update $bindable value"]

Sources:

3. Integration with Entity List

The Date Dropper is heavily utilized within the FiltersPanel for filtering entity records by date or datetime fields.

3.1 Date Normalization and Formatting

When displaying dates in the EntityListTable, the system differentiates between the browser's local time and the time stored in the record (if an IANA timezone field is present).

formatDatetimeIanaListCell: This function determines whether to format the date using the user's browser locale or a specific IANA timezone defined in the record's metadata src/lib/entity-list/format-datetime-iana-cell.ts:6-24.
datetimeIanaToggle: A configuration in the MetaColumn that indicates if a column should support switching between local and record-specific timezones src/lib/entity-list/format-datetime-iana-cell.ts:12-14.

Date Processing Architecture

This diagram shows the relationship between the raw data from the API and the UI components.

Title: Date Processing and Rendering Pipeline

Code
graph LR
    subgraph "Data Layer"
        "API_Row"["API Row Record"]
        "MetaColumn"["MetaColumn Config"]
    end

    subgraph "Formatting Logic"
        "formatDatetimeIanaListCell"["formatDatetimeIanaListCell()"]
        "formatUiDateTimeInTimeZone"["formatUiDateTimeInTimeZone()"]
    end

    subgraph "UI Components"
        "DateDropper"["DateDropper Component"]
        "FiltersPanel"["FiltersPanel (Inputs)"]
        "TableCell"["EntityListTable Cell"]
    end

    "API_Row" --> "formatDatetimeIanaListCell"
    "MetaColumn" --> "formatDatetimeIanaListCell"
    "formatDatetimeIanaListCell" --> "formatUiDateTimeInTimeZone"
    "formatUiDateTimeInTimeZone" --> "TableCell"
    "DateDropper" -- "produces" --> "CalendarDateTime"
    "CalendarDateTime" -- "filter input" --> "FiltersPanel"

Sources:

Last modified on July 13, 2026

Customer List & CRM Development Conventions & AI Agent Rules

Date Dropper & Wheel Picker

1. DateDropper Component

1.1 Value Types and Props

1.2 Timezone Management

2. WheelPicker Primitive

2.1 Component Architecture

2.2 State Management (ctx.svelte.ts)

2.3 Physics and Interaction

Wheel Picker Data Flow

3. Integration with Entity List

3.1 Date Normalization and Formatting

Date Processing Architecture

Date Dropper & Wheel Picker

1. DateDropper Component

1.1 Value Types and Props

1.2 Timezone Management

2. WheelPicker Primitive

2.1 Component Architecture

2.2 State Management (ctx.svelte.ts)

2.3 Physics and Interaction

Wheel Picker Data Flow

3. Integration with Entity List

3.1 Date Normalization and Formatting

Date Processing Architecture

2.2 State Management (`ctx.svelte.ts`)

2.2 State Management (`ctx.svelte.ts`)