fitness_workout library

Public API of the fitness_workout package.

The package ships two complementary runners:

  • WorkoutRunner — sets × reps × weight, for strength workouts.
  • CardioRunner — interval / lap based, for running, cycling, rowing, HIIT, jump rope, etc.

Both are ChangeNotifiers and share the same RunnerStorage abstraction, so the same app can run a strength and a cardio session side-by-side (each uses its own storage slot).

Classes

AllSetsCompletionRule
CardioInterval
A single segment inside a CardioPlan. Either bounded by targetDuration, by targetDistance, or both — the runner only auto-advances when the bounded dimension hits its target. Free-form steady-state intervals can leave both null and rely on the user pressing "next".
CardioLap
A completed interval as actually executed by the user. Counterpart of PerformedSet on the strength side.
CardioPlan
A cardio session described as an ordered list of CardioIntervals.
CardioPlanBuilder
Fluent builder for creating CardioPlans. Mirrors WorkoutPlanBuilder.
CardioPlanEditorScreen
Full-screen drop-in editor for a CardioPlan.
CardioQuickRunner
Cardio counterpart of QuickRunner. Surfaces the running cardio session (or a horizontal plan picker when idle).
CardioResult
Returned by CardioRunner.finish and emitted via its finished stream. Counterpart of WorkoutResult on the strength side.
CardioResultsStatTile
Reusable stat-tile in the same look as the default tiles inside CardioResultsView. Exposed so custom CardioStatBuilders can mix in extra tiles without rebuilding the visual style.
CardioResultsView
Stand-alone result summary for a finished cardio session.
CardioRunner
Interval-based companion to WorkoutRunner. Designed for workouts where the natural progress unit is a lap — running, intervals on a bike or rower, jump-rope rounds, etc. — rather than a set×reps×weight tuple.
CardioRunnerPanel
Headline cardio view: hero timer + active-interval card + lap timeline + control bar (complete / skip / pause-resume / finish).
CardioRunnerScope
Provides a CardioRunner to descendants. Analogous to RunnerScope but for cardio sessions.
CardioRunnerScreen
Drop-in cardio screen: AppBar, panel and automatic transition to CardioResultsView on finish.
CardioRunnerState
Persistable snapshot of an active cardio session. Mirrors WorkoutRunnerState on the strength side.
CardioRunnerStatusAppBarAction
Drops a CardioRunnerStatusChip into an AppBar.actions: slot with the expected horizontal padding. Renders nothing while no cardio session is active, so it's safe to mount unconditionally.
CardioRunnerStatusBanner
Inline banner — drop under your AppBar / hero block. Empty SizedBox when idle.
CardioRunnerStatusBottomBar
Bottom-attached continue cardio CTA. Empty when idle.
CardioRunnerStatusChip
Tiny pill that surfaces a running cardio session. Renders nothing while idle, so it is safe to drop unconditionally into an AppBar.
CardioTemplates
Catalog
Reads the bundled Default* catalogues and overlays user-defined entries from a CustomEntityRegistry on top. Custom entries WIN over defaults with the same id (so a user can shadow / override a bundled exercise).
CatalogPickerSheet<T>
Reusable bottom-sheet picker for any catalog list (default + user-defined exercises, muscles, categories, plans).
CatalogSnapshot
CategoryEditorSheet
Drop-in bottom sheet that creates or edits an ExerciseCategory.
CoachEngine
CoachingAction
CoachingMessage
CoachingMessageTemplate
CoachSignalEvent
CompletionEvaluation
CompletionRule
ConsentGate
ConsentState
CustomEntityKinds
Well-known kind ids used by Catalog. Storage adapters can support arbitrary kinds — these are the ones the bundled merger understands.
CustomEntityRegistry
Persistence for user-defined catalogue entries — exercises, muscles, categories, plans, cardio plans. Independent from RunnerStorage so the implementation can pick a different backend (SQLite, IndexedDB, …) without touching the runner.
DataBundle
DataExport
DefaultBars
Bar weight presets — pure constants, in their native unit.
DefaultCardioPlans
Built-in CardioPlan presets. Use these straight from the package or copy them as a template for app-specific plans.
DefaultCategories
Built-in ExerciseCategory presets. Apps may use these directly or supply their own list.
DefaultCoachEngine
DefaultExercises
Catalogue of built-in WorkoutExercise templates. Use DefaultExercises.all to get the full list, or one of the helpers like byCategory / byMuscle.
DefaultMuscles
Built-in Muscle presets with English names and a coarse group split (upper / lower / core).
DefaultPlans
Built-in WorkoutPlans composed from DefaultExercises. Useful for demos, onboarding flows, or as a starting point when the user has not yet created their own plans.
DefaultPlateSets
Catalogue of built-in plate sets. All values are pure constants — apps can pass their own lists to PlateCalculator.load without depending on these.
DefaultRunnerHaptics
Default flutter/services.dart HapticFeedback-based implementation.
DeloadConfig
DeloadPlan
DeloadSuggestion
EnergyEstimator
EquipmentPickerSheet
Modal bottom sheet that lets the user toggle the EquipmentItems they have access to. A quick-pick row at the top swaps the whole selection to one of the bundled EquipmentProfile presets (bodyweight only, home gym, commercial gym, cardio studio).
EquipmentProfile
ExerciseAlternativeGroup
ExerciseAlternatives
ExerciseCategory
ExerciseEditorSheet
Drop-in bottom sheet that creates or edits a WorkoutExercise.
ExerciseFavoritesStorage
Optional storage for exercise favorites and usage tracking.
ExerciseFocusCard
Big-focus card for the currently active exercise in the focus runner.
ExerciseIndex
ExercisePicker
Pure helper that re-orders a catalog of exercises using favorites + recents pulled from an ExerciseFavoritesStorage.
ExerciseSearch
ExperienceLevelPicker
Three horizontally-arranged pill chips representing the three ExperienceLevel values. The currently selected level gets the accent fill; the others stay outlined.
ExportAuditEntry
ExportAuditSink
FocusActionBar
Sticky bottom action bar for the focus runner. Always shows exactly one primary CTA (Start Set / Finish Set / Continue / Finish Workout) and optional secondary actions on the right (e.g. Skip / Edit).
FocusSecondaryAction
FormCueBundle
FormCues
FreeSessionCompletionRule
GoalPickerSheet
Modal bottom-sheet that asks the user to pick one of the four TrainingGoal presets. Renders each option as a large RunnerCard tile with icon + label + 1-line description.
HistoryPage<T>
Slice of a history sink for cursor-based iteration over large result sets.
ImportError
ImportResult
InMemoryCustomEntityRegistry
In-memory CustomEntityRegistry for tests, demos and prototypes. Not persisted across app launches — wire a real registry (Hive, Isar, …) for production.
InMemoryExerciseFavoritesStorage
In-memory ExerciseFavoritesStorage for tests, demos and prototypes.
InMemoryExportAuditSink
InMemoryPagedHistoryStorage
In-memory history sink that implements both the eager WorkoutHistoryStorage contract and the cursor-based PagedWorkoutHistoryStorage contract.
InMemoryPlanDraftStorage
InMemoryRunnerStorage
In-memory RunnerStorage for tests and previews. Does not persist across app restarts.
InMemoryScheduledWorkoutStorage
In-memory ScheduledWorkoutStorage for tests, demos and prototypes.
InMemorySessionRatingStorage
InMemoryWorkoutHistoryStorage
In-memory WorkoutHistoryStorage for tests, demos and prototypes.
KnownTag
MetaFieldRow
Compact label-plus-trailing-input row used by every bundled editor (ExerciseEditorSheet, MuscleEditorSheet, CategoryEditorSheet, PlanEditorScreen, …).
MinimumSetsCompletionRule
Muscle
MuscleEditorSheet
Drop-in bottom sheet that creates or edits a Muscle.
NextSetSuggestion
NextUpStrip
Slim horizontal preview of what comes after the current focus. Reads from the ambient WorkoutRunner and renders the next exercise (or "Final exercise") so users always know where the session is heading.
NoOpRunnerAudio
NoOpRunnerHaptics
Explicit do-nothing implementation. Useful for tests and for web builds where HapticFeedback is a no-op anyway but you want to make the intent visible at the call site.
NoOpRunnerVoiceCues
NotesTimeline
NotesTimelineEntry
OverloadEngine
OverloadSuggestion
PagedWorkoutHistoryStorage
Optional pagination contract that sits next to WorkoutHistoryStorage.
PerformedExercise
An exercise as performed during a workout — name snapshot + executed sets.
PerformedExerciseDetails
PerformedSet
A set that has been executed by the user (with actual values).
PersonalRecord
A single personal record detected from history.
PersonalRecords
Pure helpers that scan workout/cardio history for personal records.
PlanDraftController
PlanDraftStorage
Persistence contract for in-progress WorkoutPlan drafts produced by the plan editor.
PlanEditorScreen
Drop-in full-screen editor for a WorkoutPlan. Maintains a mutable working copy of the plan and emits the final value via onSave when the user taps the save action.
PlanGenerationProfile
PlanGenerationProfileSheet
Composite onboarding sheet that walks the user through the four inputs of a PlanGenerationProfile (goal, experience level, days-per-week, equipment) and emits the final profile when the user taps "Save".
PlanGenerator
PlateCalculator
Pure helper that picks the largest possible plate combination per side to hit a target weight on a barbell.
PlateLoading
Result of loading a barbell for a target weight.
PrefsRunnerStorage
Default RunnerStorage using SharedPreferences. Suitable for most apps.
PrHighlightsCard
Compact "recent PRs" card — pure data input.
ProgramDay
ProgramProgress
ProgramProgressTracker
ProgramTemplates
ProgramWeek
QuickRunner
Compact card that either advertises a running workout (with a Continue CTA) or lets the user pick from a list of plans to start one.
Readiness
Pure helpers that derive TrainingReadiness and VolumeAdjustment from recent WorkoutResults plus optional self-reported signals.
RecentSessionsList
Vertical list of recent strength sessions.
Recommendations
Redaction
RequiredExercisesCompletionRule
RestPreset
RestPresetResolver
RestSuggestion
ResultsStatTile
Reusable stat-tile in the same look as the default tiles inside ResultsView. Exposed so custom WorkoutStatBuilders can mix in extra tiles without rebuilding the visual style.
ResultsView
Stand-alone result summary, ready to push as a destination after runner.finish(). Looks the same as the in-app RunnerScreen summary.
RunnerActionResult
RunnerAudio
RunnerAudioBridge
RunnerCard
Surface used by every bundled widget — fills with WorkoutRunnerThemeData.surface and applies the standard border + drop shadow.
RunnerErrorMessages
RunnerFocusPanel
Compose the new focus-mode runner UI from its building blocks:
RunnerHaptics
Plug-in hook interface the runner invokes at semantic moments (set start/complete, rest tick, rest complete, etc.).
RunnerHapticsBridge
Convenience wiring helper. Apps call once after constructing the runner to attach a RunnerHaptics implementation to the runner's existing callback slots.
RunnerPanel
The headline workout view: plan header, exercise carousel, finish CTA and a full-bleed rest overlay that drops in while the user is resting.
RunnerPillButton
Compact pill-shaped button used across the package. Falls back to nicer system defaults than ElevatedButton inside dark surfaces.
RunnerScope
Provides a WorkoutRunner to descendants so they don't have to pass it through every constructor.
RunnerScreen
Drop-in workout screen: AppBar, panel, and an automatic transition to a results view when the workout finishes.
RunnerStatusAppBarAction
Convenience wrapper that puts a RunnerStatusChip into an existing AppBar actions: list — call it from your AppBar.
RunnerStatusBanner
Inline banner you can place under your AppBar or hero block. Renders an empty SizedBox when idle.
RunnerStatusBottomBar
Slim banner suitable for bottomNavigationBar slot when you want a tappable "continue workout" surface. Renders nothing when idle.
RunnerStatusChip
Compact chip that surfaces a running workout. Renders nothing while no workout is active, so it is safe to drop unconditionally into an AppBar.
RunnerStorage
Pluggable persistence for WorkoutRunner.
RunnerVoiceCues
ScheduledWorkout
Lightweight planning DTO above WorkoutPlan / CardioPlan.
ScheduledWorkoutQuery
Pure query helpers over a list of ScheduledWorkout. Apps own the storage of the underlying list; these helpers never mutate the input.
ScheduledWorkoutStorage
Optional storage for ScheduledWorkout entries. Apps wire this to whatever key/value persistence layer they prefer (SharedPreferences, Hive, sqflite …).
ScoredAlternative
SectionLabel
Uppercase "eyebrow" caption used on cards.
SessionHeader
Compact header block for the focus runner. Shows plan name, elapsed timer, progress (done sets / total sets), and pause/resume + finish actions.
SessionRating
SessionRatingStats
SessionRatingStorage
SetInputResult
Return type for SetInputSheet.
SetInputSheet
Bottom-sheet entry/edit form for a single set. Use show to display it; the result is a SetInputResult or null if the user cancelled.
SetRow
A single set row inside an exercise card. Handles the start / running / done visuals and opens the SetInputSheet when the user taps a running set or a finished set (to edit it).
SetRowSlotData
Data passed to a SetRow.trailingBuilder override.
SetTimeline
Compact horizontal timeline of an exercise's sets. Each dot is small but reflects state via color (done/active/pending/locked) and shape (square vs circle vs ring) so a glance tells you "where am I in this exercise".
ShareHelpers
Pure formatting helpers for sharing WorkoutResult and CardioResult snapshots as plain text or Markdown. No Social SDK integration, no I/O — callers wire these into share sheets, clipboard buttons, or messaging.
StreamingStats
Lazy/streaming aggregations over a PagedWorkoutHistoryStorage.
StrengthTemplates
Curated catalogue of ready-to-use strength WorkoutPlans. Each plan is built from DefaultExercises so muscle / category metadata stays in sync with the rest of the package, and carries a tmpl_* id so it can be distinguished from user-authored or DefaultPlans entries.
SyncConflict<T>
SyncEnvelope<T>
SyncMerge
SyncMergeResult<T>
TagFilter
TimerText
Renders a Duration as mm:ss (or hh:mm:ss past 60min) with tabular numbers so the digits don't dance while ticking.
TrainingProgram
TrainingReadiness
Snapshot of training readiness derived from recent WorkoutResults and optional self-reported signals (RPE, sleep).
VolumeAdjustment
Single-number volume adjustment derived from a TrainingReadiness bucket.
VolumeTrendChart
Bar chart of weekly training volume.
WarmupGenerator
Pure helper that emits a list of warm-up WorkoutSets leading into a given working set.
WeeklySummaryCard
Big "this week" summary card. Pure data-input — the caller provides a pre-computed WeeklyWorkoutSummary (see WorkoutStats.weeklySummary).
WeeklyWorkoutSummary
WorkoutBlock
A grouping of exercises performed back-to-back as a superset or circuit.
WorkoutCompletion
WorkoutExercise
WorkoutHistoryStorage
Optional history sink for finished workouts and cardio sessions.
WorkoutImport
WorkoutNotes
WorkoutPlan
WorkoutPlanBuilder
Fluent builder for creating WorkoutPlans without deeply nested model constructors.
WorkoutPlanValidationIssue
WorkoutPlanValidationResult
WorkoutResult
Returned by WorkoutRunner.finish and emitted via the finished stream.
WorkoutRunner
Heart of the package. Owns the active WorkoutPlan, the running state (timers, set/exercise indices, performed sets) and persistence.
WorkoutRunnerLocalizations
All user-facing strings shown by the bundled workout-runner widgets.
WorkoutRunnerLocalizationsScope
Provides a WorkoutRunnerLocalizations to the subtree. Falls back to the English defaults when no ancestor is present, so consumers only need to install this if they want to override strings or formatters.
WorkoutRunnerState
Persistable snapshot of an active workout. Stored by RunnerStorage and reloaded on auto-resume.
WorkoutRunnerTheme
Wrap any subtree in this widget to provide a WorkoutRunnerThemeData. Defaults to the dark fitness preset when no ancestor exists.
WorkoutRunnerThemeData
Design tokens for the workout-runner widgets. Override fields on WorkoutRunnerThemeData and wrap your subtree in WorkoutRunnerTheme to re-style the bundled widgets.
WorkoutRunnerUnitFormatters
Static-style helpers that turn raw metric values into display strings under a chosen MeasurementSystem.
WorkoutSet
WorkoutStats
WorkoutTags

Enums

AlternativeMatch
CardioDiscipline
How the cardio session is structured. Mostly informational — drives UI hints, not runtime behaviour.
CardioPhase
What the user is supposed to be doing during a CardioInterval.
CatalogPickerKind
Discriminator the host app passes to show so it can wire one shared catalogue picker to multiple lookup sources (exercises, muscles, categories). The sheet itself is generic, so this enum exists purely as metadata for callers — it does NOT change the rendered UI.
CoachSeverity
CoachSignal
ConsentScope
DeloadStrategy
EquipmentItem
ExerciseDifficulty
Rough difficulty bucket — apps can use it to filter exercise pickers or gate beginners away from advanced moves. Not a substitute for coaching.
ExerciseEquipment
Equipment a WorkoutExercise needs. Free-form string id matches what the EquipmentItem enum from lib/src/intelligence/equipment_profile.dart uses, so a user's EquipmentProfile.idSet filters against this directly.
ExperienceLevel
ImportConflictPolicy
MeasurementSystem
The unit system a UI layer wants to display values in.
MovementPattern
Coarse-grained movement pattern. Drives substitution suggestions, programming heuristics and filter chips in editor screens.
OverloadStrategy
ProgramDayKind
PrType
Kinds of personal record this module can detect.
ReadinessLevel
Coarse readiness bucket derived from training history.
RestGoal
RunnerActionError
RunnerButtonStyle
ScheduledStatus
Status buckets a ScheduledWorkout can fall into.
SessionMood
SetRowState
Lifecycle state of a SetRow, surfaced to custom trailing builders.
SetType
Semantic flavour of a set inside a WorkoutPlan.
SoundCue
SyncMergeStrategy
SyncOperation
TagMatchMode
TrainingGoal
WarmupStrategy
Pre-baked ramp shape for WarmupGenerator.forSet.
WorkoutCompletionStatus
WorkoutPlanValidationSeverity

Constants

kDefaultMet → const double
Default MET value when nothing else is known. Picks the middle of the "light-moderate calisthenics" band so kcal output stays plausible for any strength session that doesn't bother to specify MET per exercise.
kDefaultMetByCategoryId → const Map<String, double>
Default MET by ExerciseCategory.id. Strength sits at 6 (Compendium 02050), calisthenics/core 4, mobility 2.5.
kDefaultMetByDiscipline → const Map<CardioDiscipline, double>
Default MET by CardioDiscipline. Running pace-adjustment is not applied here — the value is an average for a moderate session. Apps that need pace-adjusted MET should pass met explicitly on the CardioInterval.
kDefaultRestPresets → const Map<RestGoal, RestPreset>
kKgPerLb → const double
1 lb = this many kilograms (NIST definition, exact).
kLbPerKg → const double
1 kg in pounds — reciprocal of kKgPerLb, pre-computed for speed.
kMetersPerFoot → const double
1 foot in metres (international foot, exact).
kMetersPerMile → const double
1 mile in metres (international mile, exact).
kPluginSchemaVersion → const int

Functions

distanceFromSystem(double value, MeasurementSystem system) → double
Convert a "long" distance value in system's native unit back to metres.
distanceToSystem(double meters, MeasurementSystem system) → double
Convert metres to the "long" distance unit of system (kilometres for metric, miles for imperial).
feetToMeters(double ft) → double
kgToLb(double kg) → double
Convert kilograms to pounds.
kmToMeters(double km) → double
lbToKg(double lb) → double
Convert pounds to kilograms.
metersPerSecond({required Duration duration, required double distanceMeters}) → double?
Compute speed in metres per second from duration + distance.
metersToFeet(double m) → double
metersToKm(double m) → double
metersToMiles(double m) → double
milesToMeters(double mi) → double
mpsToKmh(double mps) → double
mpsToMph(double mps) → double
paceFromSystem(Duration value, MeasurementSystem system) → Duration
Convert a pace in system's native unit back to seconds-per-kilometre.
pacePerKm({required Duration duration, required double distanceMeters}) → Duration?
Compute pace (seconds per kilometre) from duration + distance in metres. Returns null when either input is non-positive — callers can decide how to render "no pace yet".
pacePerKmToPerMile(Duration perKm) → Duration
Convert a pace in seconds-per-kilometre to seconds-per-mile.
pacePerMileToPerKm(Duration perMile) → Duration
Convert a pace in seconds-per-mile to seconds-per-kilometre.
paceToSystem(Duration perKm, MeasurementSystem system) → Duration
Render a stored seconds-per-km pace into the chosen system's native pace (min/km for metric, min/mi for imperial).
speedToSystem(double mps, MeasurementSystem system) → double
Convert m/s to the "speed" unit of system (km/h or mph).
weightFromSystem(double value, MeasurementSystem system) → double
Convert a value in the chosen system's native weight unit back to kilograms (the canonical storage unit).
weightToSystem(double kg, MeasurementSystem system) → double
Convert a metric (kg) value into the chosen system's native weight unit (kg for metric, lb for imperial). Round-trippable with weightFromSystem.

Typedefs

CardioFinishedCallback = void Function(CardioResult result)
Fired whenever CardioRunner.finish returns a CardioResult.
CardioStatBuilder = List<Widget> Function(BuildContext context, CardioResult result)
Build the row of stat tiles shown in a CardioResultsView. Use the bundled CardioResultsStatTile for consistent visuals.
CoachingMessageMapper = CoachingMessage? Function(CoachSignalEvent)
SetTrailingBuilder = Widget Function(BuildContext context, SetRowSlotData data)
Builder signature for SetRow.trailingBuilder. Return any widget — the bundled trailing visuals are shown when the builder is null.
SetTypeAccents = Map<SetType, Color>
Per-SetType accent colour used for badges and set-row tinting in the bundled widgets. Plain Color so consumers can wire any palette; the foreground/background contrast pair is built by widgets at paint time (using WorkoutRunnerThemeData.onAccent for solid badges).
WorkoutFinishedCallback = void Function(WorkoutResult result)
Result emitted whenever WorkoutRunner.finish completes successfully.
WorkoutStatBuilder = List<Widget> Function(BuildContext context, WorkoutResult result)
Build the row of stat tiles shown in a ResultsView. Return whatever widgets you want — the bundled ResultsStatTile is exposed publicly so you can mix custom values in with the defaults without rebuilding the visual style from scratch.