BankPeriodSelector class

Prev/next time-period navigator for statements, insights and budgets.

Renders a row with a back chevron, a centred period label, and a forward chevron. Hosts keep the current period in their own state and receive the previous/next period through onChanged: the widget itself is stateless with respect to the selected period (controlled component).

Typical placement is as the header above a spending breakdown chart or a budget gauge, so users can page through months, quarters or years.

Behaviour:

  • The label is formatted per unit (March 2026 / Q1 2026 / 2026) and digits follow the ambient NumeralStyle from BankUiScope (Eastern Arabic-Indic digits in Arabic-script locales).
  • Chevrons dim to 40% opacity and stop responding at minPeriod / maxPeriod bounds (compared at unit granularity).
  • Chevrons flip for right-to-left locales, and their semantic labels stay direction-agnostic ("Previous month" / "Next month").
  • The label crossfades over 150 ms with a short horizontal slide that matches the direction of travel (reversed in RTL); the animation is skipped when the platform requests reduced motion.
  • onTapLabel lets hosts open a month-grid or year picker when the user taps the label itself.
BankPeriodSelector(
  period: DateTime(2026, 3),
  unit: BankPeriodUnit.month,
  onChanged: (next) => setState(() => _period = next),
  minPeriod: DateTime(2024, 1),
  maxPeriod: DateTime.now(),
  onTapLabel: _openMonthGridPicker,
)
Inheritance

Constructors

BankPeriodSelector({required DateTime period, required BankPeriodUnit unit, required ValueChanged<DateTime> onChanged, Key? key, DateTime? minPeriod, DateTime? maxPeriod, VoidCallback? onTapLabel, String? previousSemanticLabel, String? nextSemanticLabel, String labelFormatter(DateTime period)?, TextStyle? labelStyle, IconData? previousIcon, IconData? nextIcon, Color? foregroundColor, Duration? animationDuration, Curve? animationCurve})
const

Properties

animationCurve → Curve?
Overrides BankTokens.curveStandard for the label transition.
final
animationDuration → Duration?
Overrides BankTokens.durationFast for the label transition.
final
foregroundColor → Color?
Overrides BankThemeData.onSurface as the chevron colour (the disabled state keeps its 40 % opacity treatment).
final
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
labelFormatter → String Function(DateTime period)?
Replaces the default label text for a normalised period start. Defaults to March 2026 / Q1 2026 / 2026 formatting with ambient-numeral conversion; the returned string is shown verbatim.
final
labelStyle → TextStyle?
Merged over the computed label style (default: BankTokens.headlineSmall in BankThemeData.onSurface).
final
maxPeriod → DateTime?
Latest reachable period (inclusive), compared at unit granularity. The forward chevron disables once period reaches this bound.
final
minPeriod → DateTime?
Earliest reachable period (inclusive), compared at unit granularity. The back chevron disables once period reaches this bound.
final
nextIcon → IconData?
Overrides the forward chevron glyph (default: a direction-aware Icons.chevron_right, mirrored in RTL). Overrides are not mirrored.
final
nextSemanticLabel → String?
Semantic label for the forward chevron. Defaults to an English label matching unit, e.g. Next month.
final
onChanged → ValueChanged<DateTime>
Called with the start of the previous/next period when a chevron is tapped. The host owns the state and rebuilds with the new period.
final
onTapLabel → VoidCallback?
Called when the user taps the period label: hosts typically open a month-grid or year picker here. When null the label is not tappable.
final
period → DateTime
The currently selected period. Any DateTime inside the period is accepted; it is normalised to the start of the unit internally.
final
previousIcon → IconData?
Overrides the back chevron glyph (default: a direction-aware Icons.chevron_left, mirrored in RTL). Overrides are not mirrored.
final
previousSemanticLabel → String?
Semantic label for the back chevron. Defaults to an English label matching unit, e.g. Previous month.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
unit → BankPeriodUnit
Granularity of navigation: month, quarter or year.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<BankPeriodSelector>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited