1use core::fmt;
45use core::hash::{Hash, Hasher};
46
47#[derive(Clone, Debug, Eq, PartialEq)]
66pub struct StateKey {
67 pub widget_type: &'static str,
69 pub instance_id: String,
71}
72
73impl StateKey {
74 #[must_use]
76 pub fn new(widget_type: &'static str, id: impl Into<String>) -> Self {
77 Self {
78 widget_type,
79 instance_id: id.into(),
80 }
81 }
82
83 #[must_use]
92 pub fn from_path(path: &[&str]) -> Self {
93 assert!(
94 !path.is_empty(),
95 "StateKey::from_path requires a non-empty path"
96 );
97 let widget_type_str = path.last().expect("checked non-empty");
98 let widget_type: &'static str = Box::leak((*widget_type_str).to_owned().into_boxed_str());
102 Self {
103 widget_type,
104 instance_id: path.join("/"),
105 }
106 }
107
108 #[must_use]
110 pub fn canonical(&self) -> String {
111 format!("{}::{}", self.widget_type, self.instance_id)
112 }
113}
114
115impl Hash for StateKey {
116 fn hash<H: Hasher>(&self, state: &mut H) {
117 self.widget_type.hash(state);
118 self.instance_id.hash(state);
119 }
120}
121
122impl fmt::Display for StateKey {
123 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
124 write!(f, "{}::{}", self.widget_type, self.instance_id)
125 }
126}
127
128pub trait Stateful: Sized {
169 type State: Default;
173
174 fn state_key(&self) -> Option<StateKey>;
181
182 fn save_state(&self) -> Self::State;
186
187 fn restore_state(&mut self, state: Self::State);
192
193 fn state_version() -> u32 {
199 1
200 }
201}
202
203#[derive(Clone, Debug)]
214#[cfg_attr(
215 feature = "state-persistence",
216 derive(serde::Serialize, serde::Deserialize)
217)]
218pub struct VersionedState<S> {
219 pub version: u32,
221 pub data: S,
223}
224
225impl<S> VersionedState<S> {
226 #[must_use]
228 pub fn new(version: u32, data: S) -> Self {
229 Self { version, data }
230 }
231
232 pub fn pack<W: Stateful<State = S>>(widget: &W) -> Self {
234 Self {
235 version: W::state_version(),
236 data: widget.save_state(),
237 }
238 }
239
240 #[must_use = "use the unpacked state (if any)"]
243 pub fn unpack<W: Stateful<State = S>>(self) -> Option<S> {
244 if self.version == W::state_version() {
245 Some(self.data)
246 } else {
247 None
248 }
249 }
250
251 pub fn unpack_or_default<W: Stateful<State = S>>(self) -> S
254 where
255 S: Default,
256 {
257 if self.version == W::state_version() {
258 self.data
259 } else {
260 S::default()
261 }
262 }
263}
264
265impl<S: Default> Default for VersionedState<S> {
266 fn default() -> Self {
267 Self {
268 version: 1,
269 data: S::default(),
270 }
271 }
272}
273
274#[derive(Debug, Clone)]
280pub enum MigrationError {
281 NoPathFound { from: u32, to: u32 },
283 MigrationFailed { from: u32, to: u32, message: String },
285 InvalidVersionRange { from: u32, to: u32 },
287}
288
289impl core::fmt::Display for MigrationError {
290 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
291 match self {
292 Self::NoPathFound { from, to } => {
293 write!(f, "no migration path from version {} to {}", from, to)
294 }
295 Self::MigrationFailed { from, to, message } => {
296 write!(f, "migration from {} to {} failed: {}", from, to, message)
297 }
298 Self::InvalidVersionRange { from, to } => {
299 write!(f, "invalid version range: {} to {}", from, to)
300 }
301 }
302 }
303}
304
305#[allow(clippy::wrong_self_convention)]
332pub trait StateMigration {
333 type OldState;
335 type NewState;
337
338 fn from_version(&self) -> u32;
340
341 fn to_version(&self) -> u32;
344
345 fn migrate(&self, old: Self::OldState) -> Result<Self::NewState, String>;
349}
350
351#[allow(clippy::wrong_self_convention)]
355pub trait ErasedMigration<S>: Send + Sync {
356 fn from_version(&self) -> u32;
358 fn to_version(&self) -> u32;
360 fn migrate_erased(
362 &self,
363 old: Box<dyn core::any::Any + Send>,
364 ) -> Result<Box<dyn core::any::Any + Send>, String>;
365}
366
367pub struct MigrationChain<S> {
386 migrations: std::collections::HashMap<u32, Box<dyn ErasedMigration<S>>>,
388}
389
390impl<S: 'static> MigrationChain<S> {
391 #[must_use]
393 pub fn new() -> Self {
394 Self {
395 migrations: std::collections::HashMap::new(),
396 }
397 }
398
399 pub fn register(&mut self, migration: Box<dyn ErasedMigration<S>>) {
405 let from = migration.from_version();
406 let to = migration.to_version();
407 assert_eq!(
408 to,
409 from + 1,
410 "migration must increment version by exactly 1 (got {} -> {})",
411 from,
412 to
413 );
414 assert!(
415 !self.migrations.contains_key(&from),
416 "migration for version {} already registered",
417 from
418 );
419 self.migrations.insert(from, migration);
420 }
421
422 #[must_use]
424 pub fn has_path(&self, from_version: u32, to_version: u32) -> bool {
425 if from_version >= to_version {
426 return from_version == to_version;
427 }
428 let mut current = from_version;
429 while current < to_version {
430 if !self.migrations.contains_key(¤t) {
431 return false;
432 }
433 current += 1;
434 }
435 true
436 }
437
438 pub fn migrate(
442 &self,
443 state: Box<dyn core::any::Any + Send>,
444 from_version: u32,
445 to_version: u32,
446 ) -> Result<Box<dyn core::any::Any + Send>, MigrationError> {
447 if from_version > to_version {
448 return Err(MigrationError::InvalidVersionRange {
449 from: from_version,
450 to: to_version,
451 });
452 }
453 if from_version == to_version {
454 return Ok(state);
455 }
456
457 let mut current_state = state;
458 let mut current_version = from_version;
459
460 while current_version < to_version {
461 let migration =
462 self.migrations
463 .get(¤t_version)
464 .ok_or(MigrationError::NoPathFound {
465 from: current_version,
466 to: to_version,
467 })?;
468
469 current_state = migration.migrate_erased(current_state).map_err(|msg| {
470 MigrationError::MigrationFailed {
471 from: current_version,
472 to: current_version + 1,
473 message: msg,
474 }
475 })?;
476
477 current_version += 1;
478 }
479
480 Ok(current_state)
481 }
482}
483
484impl<S: 'static> Default for MigrationChain<S> {
485 fn default() -> Self {
486 Self::new()
487 }
488}
489
490#[derive(Debug)]
492pub enum RestoreResult<S> {
493 Direct(S),
495 Migrated { state: S, from_version: u32 },
497 DefaultFallback { error: MigrationError, default: S },
499}
500
501impl<S> RestoreResult<S> {
502 pub fn into_state(self) -> S {
504 match self {
505 Self::Direct(s) | Self::Migrated { state: s, .. } => s,
506 Self::DefaultFallback { default, .. } => default,
507 }
508 }
509
510 #[must_use]
512 pub fn was_migrated(&self) -> bool {
513 matches!(self, Self::Migrated { .. })
514 }
515
516 #[must_use]
518 pub fn is_fallback(&self) -> bool {
519 matches!(self, Self::DefaultFallback { .. })
520 }
521}
522
523impl<S> VersionedState<S> {
524 pub fn unpack_with_migration<W>(self, chain: &MigrationChain<S>) -> RestoreResult<S>
544 where
545 W: Stateful<State = S>,
546 S: Default + 'static + Send,
547 {
548 let current_version = W::state_version();
549
550 if self.version == current_version {
551 return RestoreResult::Direct(self.data);
552 }
553
554 let boxed: Box<dyn core::any::Any + Send> = Box::new(self.data);
556 match chain.migrate(boxed, self.version, current_version) {
557 Ok(migrated) => {
558 if let Ok(state) = migrated.downcast::<S>() {
559 RestoreResult::Migrated {
560 state: *state,
561 from_version: self.version,
562 }
563 } else {
564 RestoreResult::DefaultFallback {
566 error: MigrationError::MigrationFailed {
567 from: self.version,
568 to: current_version,
569 message: "type mismatch after migration".to_string(),
570 },
571 default: S::default(),
572 }
573 }
574 }
575 Err(e) => RestoreResult::DefaultFallback {
576 error: e,
577 default: S::default(),
578 },
579 }
580 }
581}
582
583#[cfg(test)]
584mod tests {
585 use super::*;
586
587 #[derive(Default)]
590 struct TestScrollView {
591 id: String,
592 offset: u16,
593 max: u16,
594 }
595
596 #[derive(Clone, Debug, Default, PartialEq)]
597 struct ScrollState {
598 scroll_offset: u16,
599 }
600
601 impl Stateful for TestScrollView {
602 type State = ScrollState;
603
604 fn state_key(&self) -> Option<StateKey> {
605 Some(StateKey::new("ScrollView", &self.id))
606 }
607
608 fn save_state(&self) -> ScrollState {
609 ScrollState {
610 scroll_offset: self.offset,
611 }
612 }
613
614 fn restore_state(&mut self, state: ScrollState) {
615 self.offset = state.scroll_offset.min(self.max);
616 }
617 }
618
619 #[derive(Default)]
622 struct TestTreeView {
623 id: String,
624 expanded: Vec<u32>,
625 }
626
627 #[derive(Clone, Debug, Default, PartialEq)]
628 struct TreeState {
629 expanded_nodes: Vec<u32>,
630 collapse_all_on_blur: bool, }
632
633 impl Stateful for TestTreeView {
634 type State = TreeState;
635
636 fn state_key(&self) -> Option<StateKey> {
637 Some(StateKey::new("TreeView", &self.id))
638 }
639
640 fn save_state(&self) -> TreeState {
641 TreeState {
642 expanded_nodes: self.expanded.clone(),
643 collapse_all_on_blur: false,
644 }
645 }
646
647 fn restore_state(&mut self, state: TreeState) {
648 self.expanded = state.expanded_nodes;
649 }
650
651 fn state_version() -> u32 {
652 2
653 }
654 }
655
656 #[test]
659 fn state_key_new() {
660 let key = StateKey::new("ScrollView", "main");
661 assert_eq!(key.widget_type, "ScrollView");
662 assert_eq!(key.instance_id, "main");
663 }
664
665 #[test]
666 fn state_key_from_path() {
667 let key = StateKey::from_path(&["app", "sidebar", "tree"]);
668 assert_eq!(key.instance_id, "app/sidebar/tree");
669 assert_eq!(key.widget_type, "tree");
670 }
671
672 #[test]
673 #[should_panic(expected = "non-empty path")]
674 fn state_key_from_empty_path_panics() {
675 let _ = StateKey::from_path(&[]);
676 }
677
678 #[test]
679 fn state_key_uniqueness() {
680 let a = StateKey::new("ScrollView", "main");
681 let b = StateKey::new("ScrollView", "sidebar");
682 let c = StateKey::new("TreeView", "main");
683 assert_ne!(a, b);
684 assert_ne!(a, c);
685 assert_ne!(b, c);
686 }
687
688 #[test]
689 fn state_key_equality() {
690 let a = StateKey::new("ScrollView", "main");
691 let b = StateKey::new("ScrollView", "main");
692 assert_eq!(a, b);
693 }
694
695 #[test]
696 fn state_key_hash_consistency() {
697 use std::collections::hash_map::DefaultHasher;
698
699 let a = StateKey::new("ScrollView", "main");
700 let b = StateKey::new("ScrollView", "main");
701
702 let hash = |key: &StateKey| {
703 let mut h = DefaultHasher::new();
704 key.hash(&mut h);
705 h.finish()
706 };
707 assert_eq!(hash(&a), hash(&b));
708 }
709
710 #[test]
711 fn state_key_display() {
712 let key = StateKey::new("ScrollView", "main");
713 assert_eq!(key.to_string(), "ScrollView::main");
714 }
715
716 #[test]
717 fn state_key_canonical() {
718 let key = StateKey::new("ScrollView", "main");
719 assert_eq!(key.canonical(), "ScrollView::main");
720 }
721
722 #[test]
725 fn save_restore_round_trip() {
726 let mut widget = TestScrollView {
727 id: "content".into(),
728 offset: 42,
729 max: 100,
730 };
731
732 let saved = widget.save_state();
733 assert_eq!(saved.scroll_offset, 42);
734
735 widget.offset = 0; widget.restore_state(saved);
737 assert_eq!(widget.offset, 42);
738 }
739
740 #[test]
741 fn restore_clamps_to_valid_range() {
742 let mut widget = TestScrollView {
743 id: "content".into(),
744 offset: 0,
745 max: 10,
746 };
747
748 widget.restore_state(ScrollState { scroll_offset: 999 });
750 assert_eq!(widget.offset, 10);
751 }
752
753 #[test]
754 fn default_state_on_missing() {
755 let mut widget = TestScrollView {
756 id: "new".into(),
757 offset: 5,
758 max: 100,
759 };
760
761 widget.restore_state(ScrollState::default());
762 assert_eq!(widget.offset, 0);
763 }
764
765 #[test]
768 fn default_state_version_is_one() {
769 assert_eq!(TestScrollView::state_version(), 1);
770 }
771
772 #[test]
773 fn custom_state_version() {
774 assert_eq!(TestTreeView::state_version(), 2);
775 }
776
777 #[test]
780 fn versioned_state_pack_unpack() {
781 let widget = TestScrollView {
782 id: "main".into(),
783 offset: 77,
784 max: 100,
785 };
786
787 let packed = VersionedState::pack(&widget);
788 assert_eq!(packed.version, 1);
789 assert_eq!(packed.data.scroll_offset, 77);
790
791 let unpacked = packed.unpack::<TestScrollView>();
792 assert!(unpacked.is_some());
793 assert_eq!(unpacked.unwrap().scroll_offset, 77);
794 }
795
796 #[test]
797 fn versioned_state_version_mismatch_returns_none() {
798 let stored = VersionedState::<TreeState> {
800 version: 1,
801 data: TreeState::default(),
802 };
803
804 let result = stored.unpack::<TestTreeView>();
805 assert!(result.is_none());
806 }
807
808 #[test]
809 fn versioned_state_unpack_or_default_on_mismatch() {
810 let stored = VersionedState::<TreeState> {
811 version: 1,
812 data: TreeState {
813 expanded_nodes: vec![1, 2, 3],
814 collapse_all_on_blur: true,
815 },
816 };
817
818 let result = stored.unpack_or_default::<TestTreeView>();
819 assert_eq!(result, TreeState::default());
821 }
822
823 #[test]
824 fn versioned_state_unpack_or_default_on_match() {
825 let stored = VersionedState::<ScrollState> {
826 version: 1,
827 data: ScrollState { scroll_offset: 55 },
828 };
829
830 let result = stored.unpack_or_default::<TestScrollView>();
831 assert_eq!(result.scroll_offset, 55);
832 }
833
834 #[test]
835 fn versioned_state_default() {
836 let vs = VersionedState::<ScrollState>::default();
837 assert_eq!(vs.version, 1);
838 assert_eq!(vs.data, ScrollState::default());
839 }
840
841 #[test]
844 fn migration_error_display() {
845 let err = MigrationError::NoPathFound { from: 1, to: 3 };
846 assert_eq!(err.to_string(), "no migration path from version 1 to 3");
847
848 let err = MigrationError::MigrationFailed {
849 from: 2,
850 to: 3,
851 message: "data corrupt".into(),
852 };
853 assert_eq!(
854 err.to_string(),
855 "migration from 2 to 3 failed: data corrupt"
856 );
857
858 let err = MigrationError::InvalidVersionRange { from: 5, to: 2 };
859 assert_eq!(err.to_string(), "invalid version range: 5 to 2");
860 }
861
862 #[test]
863 fn migration_chain_new_is_empty() {
864 let chain = MigrationChain::<ScrollState>::new();
865 assert!(!chain.has_path(1, 2));
866 }
867
868 #[derive(Debug, Clone, Default)]
870 struct ScrollStateV1 {
871 scroll_offset: u16,
872 }
873
874 #[derive(Debug, Clone, Default)]
875 struct ScrollStateV2 {
876 scroll_offset: u16,
877 velocity: f32, }
879
880 struct V1ToV2Migration;
881
882 impl ErasedMigration<ScrollStateV2> for V1ToV2Migration {
883 fn from_version(&self) -> u32 {
884 1
885 }
886 fn to_version(&self) -> u32 {
887 2
888 }
889 fn migrate_erased(
890 &self,
891 old: Box<dyn core::any::Any + Send>,
892 ) -> Result<Box<dyn core::any::Any + Send>, String> {
893 let v1 = old
894 .downcast::<ScrollStateV1>()
895 .map_err(|_| "invalid state type")?;
896 Ok(Box::new(ScrollStateV2 {
897 scroll_offset: v1.scroll_offset,
898 velocity: 0.0,
899 }))
900 }
901 }
902
903 #[test]
904 fn migration_chain_register_and_has_path() {
905 let mut chain = MigrationChain::<ScrollStateV2>::new();
906 chain.register(Box::new(V1ToV2Migration));
907
908 assert!(chain.has_path(1, 2));
909 assert!(chain.has_path(1, 1)); assert!(chain.has_path(2, 2)); assert!(!chain.has_path(1, 3)); }
913
914 #[test]
915 #[should_panic(expected = "migration must increment version by exactly 1")]
916 fn migration_chain_rejects_non_sequential_migration() {
917 struct BadMigration;
918 impl ErasedMigration<ScrollStateV2> for BadMigration {
919 fn from_version(&self) -> u32 {
920 1
921 }
922 fn to_version(&self) -> u32 {
923 3
924 } fn migrate_erased(
926 &self,
927 _: Box<dyn core::any::Any + Send>,
928 ) -> Result<Box<dyn core::any::Any + Send>, String> {
929 unreachable!()
930 }
931 }
932
933 let mut chain = MigrationChain::<ScrollStateV2>::new();
934 chain.register(Box::new(BadMigration));
935 }
936
937 #[test]
938 #[should_panic(expected = "migration for version 1 already registered")]
939 fn migration_chain_rejects_duplicate_registration() {
940 let mut chain = MigrationChain::<ScrollStateV2>::new();
941 chain.register(Box::new(V1ToV2Migration));
942 chain.register(Box::new(V1ToV2Migration)); }
944
945 #[test]
946 fn migration_chain_migrate_success() {
947 let mut chain = MigrationChain::<ScrollStateV2>::new();
948 chain.register(Box::new(V1ToV2Migration));
949
950 let old_state = Box::new(ScrollStateV1 { scroll_offset: 42 });
951 let result = chain.migrate(old_state, 1, 2);
952
953 assert!(result.is_ok());
954 let migrated = result
955 .unwrap()
956 .downcast::<ScrollStateV2>()
957 .expect("should be ScrollStateV2");
958 assert_eq!(migrated.scroll_offset, 42);
959 assert_eq!(migrated.velocity, 0.0);
960 }
961
962 #[test]
963 fn migration_chain_migrate_same_version() {
964 let chain = MigrationChain::<ScrollStateV2>::new();
965 let state = Box::new(ScrollStateV2 {
966 scroll_offset: 10,
967 velocity: 1.5,
968 });
969
970 let result = chain.migrate(state, 2, 2);
971 assert!(result.is_ok());
972 }
973
974 #[test]
975 fn migration_chain_migrate_no_path() {
976 let chain = MigrationChain::<ScrollStateV2>::new();
977 let state: Box<dyn core::any::Any + Send> = Box::new(ScrollStateV1 { scroll_offset: 0 });
978
979 let result = chain.migrate(state, 1, 2);
980 assert!(matches!(
981 result,
982 Err(MigrationError::NoPathFound { from: 1, to: 2 })
983 ));
984 }
985
986 #[test]
987 fn migration_chain_migrate_invalid_range() {
988 let chain = MigrationChain::<ScrollStateV2>::new();
989 let state: Box<dyn core::any::Any + Send> = Box::new(ScrollStateV2::default());
990
991 let result = chain.migrate(state, 3, 1);
992 assert!(matches!(
993 result,
994 Err(MigrationError::InvalidVersionRange { from: 3, to: 1 })
995 ));
996 }
997
998 #[test]
999 fn restore_result_into_state() {
1000 let direct = RestoreResult::Direct(ScrollState { scroll_offset: 10 });
1001 assert_eq!(direct.into_state().scroll_offset, 10);
1002
1003 let migrated = RestoreResult::Migrated {
1004 state: ScrollState { scroll_offset: 20 },
1005 from_version: 1,
1006 };
1007 assert_eq!(migrated.into_state().scroll_offset, 20);
1008
1009 let fallback = RestoreResult::DefaultFallback {
1010 error: MigrationError::NoPathFound { from: 1, to: 2 },
1011 default: ScrollState { scroll_offset: 0 },
1012 };
1013 assert_eq!(fallback.into_state().scroll_offset, 0);
1014 }
1015
1016 #[test]
1017 fn restore_result_was_migrated() {
1018 let direct = RestoreResult::Direct(ScrollState::default());
1019 assert!(!direct.was_migrated());
1020
1021 let migrated = RestoreResult::Migrated::<ScrollState> {
1022 state: ScrollState::default(),
1023 from_version: 1,
1024 };
1025 assert!(migrated.was_migrated());
1026
1027 let fallback = RestoreResult::DefaultFallback::<ScrollState> {
1028 error: MigrationError::NoPathFound { from: 1, to: 2 },
1029 default: ScrollState::default(),
1030 };
1031 assert!(!fallback.was_migrated());
1032 }
1033
1034 #[test]
1035 fn restore_result_is_fallback() {
1036 let direct = RestoreResult::Direct(ScrollState::default());
1037 assert!(!direct.is_fallback());
1038
1039 let migrated = RestoreResult::Migrated::<ScrollState> {
1040 state: ScrollState::default(),
1041 from_version: 1,
1042 };
1043 assert!(!migrated.is_fallback());
1044
1045 let fallback = RestoreResult::DefaultFallback::<ScrollState> {
1046 error: MigrationError::NoPathFound { from: 1, to: 2 },
1047 default: ScrollState::default(),
1048 };
1049 assert!(fallback.is_fallback());
1050 }
1051
1052 #[test]
1055 fn state_key_from_path_single_segment() {
1056 let key = StateKey::from_path(&["widget"]);
1057 assert_eq!(key.widget_type, "widget");
1058 assert_eq!(key.instance_id, "widget");
1059 }
1060
1061 #[test]
1062 fn state_key_from_path_two_segments() {
1063 let key = StateKey::from_path(&["parent", "child"]);
1064 assert_eq!(key.widget_type, "child");
1065 assert_eq!(key.instance_id, "parent/child");
1066 }
1067
1068 #[test]
1069 fn state_key_empty_instance_id() {
1070 let key = StateKey::new("Widget", "");
1071 assert_eq!(key.instance_id, "");
1072 assert_eq!(key.canonical(), "Widget::");
1073 assert_eq!(key.to_string(), "Widget::");
1074 }
1075
1076 #[test]
1077 fn state_key_canonical_matches_display() {
1078 let key = StateKey::new("TreeView", "sidebar/nav");
1079 assert_eq!(key.canonical(), key.to_string());
1080 }
1081
1082 #[test]
1083 fn state_key_clone() {
1084 let key = StateKey::new("Scroll", "main");
1085 let cloned = key.clone();
1086 assert_eq!(key, cloned);
1087 assert_eq!(key.widget_type, cloned.widget_type);
1088 assert_eq!(key.instance_id, cloned.instance_id);
1089 }
1090
1091 #[test]
1092 fn state_key_debug_format() {
1093 let key = StateKey::new("Foo", "bar");
1094 let dbg = format!("{:?}", key);
1095 assert!(dbg.contains("Foo"));
1096 assert!(dbg.contains("bar"));
1097 }
1098
1099 #[test]
1100 fn state_key_hash_differs_for_different_keys() {
1101 use std::collections::hash_map::DefaultHasher;
1102
1103 let hash = |key: &StateKey| {
1104 let mut h = DefaultHasher::new();
1105 key.hash(&mut h);
1106 h.finish()
1107 };
1108
1109 let a = StateKey::new("ScrollView", "main");
1110 let b = StateKey::new("ScrollView", "sidebar");
1111 let c = StateKey::new("TreeView", "main");
1112
1113 assert_ne!(hash(&a), hash(&b));
1115 assert_ne!(hash(&a), hash(&c));
1117 }
1118
1119 #[test]
1120 fn state_key_usable_as_hashmap_key() {
1121 use std::collections::HashMap;
1122
1123 let mut map = HashMap::new();
1124 let key1 = StateKey::new("Scroll", "a");
1125 let key2 = StateKey::new("Scroll", "b");
1126
1127 map.insert(key1.clone(), 1);
1128 map.insert(key2.clone(), 2);
1129
1130 assert_eq!(map.get(&key1), Some(&1));
1131 assert_eq!(map.get(&key2), Some(&2));
1132 assert_eq!(map.len(), 2);
1133 }
1134
1135 #[test]
1136 fn state_key_from_path_with_empty_segments() {
1137 let key = StateKey::from_path(&["", "child"]);
1138 assert_eq!(key.instance_id, "/child");
1139 assert_eq!(key.widget_type, "child");
1140 }
1141
1142 #[test]
1145 fn save_state_on_default_widget() {
1146 let widget = TestScrollView::default();
1147 let state = widget.save_state();
1148 assert_eq!(state.scroll_offset, 0);
1149 }
1150
1151 #[test]
1152 fn restore_state_to_zero_max() {
1153 let mut widget = TestScrollView {
1154 id: "x".into(),
1155 offset: 0,
1156 max: 0,
1157 };
1158 widget.restore_state(ScrollState { scroll_offset: 100 });
1159 assert_eq!(widget.offset, 0);
1161 }
1162
1163 #[test]
1164 fn save_restore_preserves_max_u16() {
1165 let mut widget = TestScrollView {
1166 id: "w".into(),
1167 offset: u16::MAX,
1168 max: u16::MAX,
1169 };
1170 let saved = widget.save_state();
1171 assert_eq!(saved.scroll_offset, u16::MAX);
1172
1173 widget.offset = 0;
1174 widget.restore_state(saved);
1175 assert_eq!(widget.offset, u16::MAX);
1176 }
1177
1178 #[test]
1179 fn multiple_save_restore_cycles() {
1180 let mut widget = TestScrollView {
1181 id: "cycle".into(),
1182 offset: 10,
1183 max: 100,
1184 };
1185
1186 for i in 0..5 {
1187 widget.offset = i * 10;
1188 let saved = widget.save_state();
1189 widget.offset = 0;
1190 widget.restore_state(saved);
1191 assert_eq!(widget.offset, i * 10);
1192 }
1193 }
1194
1195 #[test]
1196 fn state_key_from_widget() {
1197 let widget = TestScrollView {
1198 id: "content-panel".into(),
1199 offset: 0,
1200 max: 50,
1201 };
1202 let key = widget.state_key().expect("an identified widget has a key");
1203 assert_eq!(key.widget_type, "ScrollView");
1204 assert_eq!(key.instance_id, "content-panel");
1205 }
1206
1207 #[test]
1208 fn tree_view_save_restore_round_trip() {
1209 let mut widget = TestTreeView {
1210 id: "files".into(),
1211 expanded: vec![1, 3, 5],
1212 };
1213 let saved = widget.save_state();
1214 assert_eq!(saved.expanded_nodes, vec![1, 3, 5]);
1215 assert!(!saved.collapse_all_on_blur);
1216
1217 widget.expanded = vec![];
1218 widget.restore_state(saved);
1219 assert_eq!(widget.expanded, vec![1, 3, 5]);
1220 }
1221
1222 #[test]
1225 fn versioned_state_new_constructor() {
1226 let vs = VersionedState::new(42, ScrollState { scroll_offset: 7 });
1227 assert_eq!(vs.version, 42);
1228 assert_eq!(vs.data.scroll_offset, 7);
1229 }
1230
1231 #[test]
1232 fn versioned_state_clone() {
1233 let vs = VersionedState::new(1, ScrollState { scroll_offset: 5 });
1234 let cloned = vs.clone();
1235 assert_eq!(cloned.version, 1);
1236 assert_eq!(cloned.data.scroll_offset, 5);
1237 }
1238
1239 #[test]
1240 fn versioned_state_debug() {
1241 let vs = VersionedState::new(3, ScrollState { scroll_offset: 10 });
1242 let dbg = format!("{:?}", vs);
1243 assert!(dbg.contains("3"));
1244 assert!(dbg.contains("10"));
1245 }
1246
1247 #[test]
1248 fn versioned_state_unpack_version_match() {
1249 let vs = VersionedState::new(1, ScrollState { scroll_offset: 42 });
1250 let result = vs.unpack::<TestScrollView>();
1251 assert!(result.is_some());
1252 assert_eq!(result.unwrap().scroll_offset, 42);
1253 }
1254
1255 #[test]
1256 fn versioned_state_unpack_version_zero_mismatch() {
1257 let vs = VersionedState::new(0, ScrollState { scroll_offset: 99 });
1259 assert!(vs.unpack::<TestScrollView>().is_none());
1260 }
1261
1262 #[test]
1263 fn versioned_state_unpack_future_version() {
1264 let vs = VersionedState::new(999, ScrollState { scroll_offset: 1 });
1266 assert!(vs.unpack::<TestScrollView>().is_none());
1267 }
1268
1269 #[test]
1270 fn versioned_state_unpack_or_default_version_zero() {
1271 let vs = VersionedState::new(0, ScrollState { scroll_offset: 50 });
1272 let result = vs.unpack_or_default::<TestScrollView>();
1273 assert_eq!(result, ScrollState::default());
1274 }
1275
1276 #[test]
1277 fn versioned_state_default_for_tree_state() {
1278 let vs = VersionedState::<TreeState>::default();
1279 assert_eq!(vs.version, 1);
1280 assert!(vs.data.expanded_nodes.is_empty());
1281 assert!(!vs.data.collapse_all_on_blur);
1282 }
1283
1284 #[test]
1287 fn migration_error_clone() {
1288 let err = MigrationError::NoPathFound { from: 1, to: 5 };
1289 let cloned = err.clone();
1290 assert_eq!(cloned.to_string(), "no migration path from version 1 to 5");
1291
1292 let err2 = MigrationError::MigrationFailed {
1293 from: 2,
1294 to: 3,
1295 message: "oops".into(),
1296 };
1297 let cloned2 = err2.clone();
1298 assert_eq!(cloned2.to_string(), "migration from 2 to 3 failed: oops");
1299
1300 let err3 = MigrationError::InvalidVersionRange { from: 10, to: 1 };
1301 let cloned3 = err3.clone();
1302 assert_eq!(cloned3.to_string(), "invalid version range: 10 to 1");
1303 }
1304
1305 #[test]
1306 fn migration_error_debug() {
1307 let err = MigrationError::NoPathFound { from: 1, to: 2 };
1308 let dbg = format!("{:?}", err);
1309 assert!(dbg.contains("NoPathFound"));
1310 }
1311
1312 #[test]
1315 fn migration_chain_default() {
1316 let chain = MigrationChain::<ScrollState>::default();
1317 assert!(!chain.has_path(1, 2));
1318 }
1319
1320 #[test]
1321 fn migration_chain_has_path_same_version() {
1322 let chain = MigrationChain::<ScrollState>::new();
1323 assert!(chain.has_path(0, 0));
1325 assert!(chain.has_path(5, 5));
1326 assert!(chain.has_path(u32::MAX, u32::MAX));
1327 }
1328
1329 #[test]
1330 fn migration_chain_has_path_from_greater_than_to() {
1331 let chain = MigrationChain::<ScrollState>::new();
1332 assert!(!chain.has_path(3, 1));
1334 assert!(!chain.has_path(2, 1));
1335 }
1336
1337 #[test]
1338 fn migration_chain_has_path_gap_in_chain() {
1339 let mut chain = MigrationChain::<ScrollStateV2>::new();
1341 chain.register(Box::new(V1ToV2Migration));
1342 assert!(chain.has_path(1, 2));
1343 assert!(!chain.has_path(1, 3)); }
1345
1346 #[test]
1347 fn migration_chain_migrate_same_version_empty_chain() {
1348 let chain = MigrationChain::<ScrollState>::new();
1349 let state: Box<dyn core::any::Any + Send> = Box::new(ScrollState { scroll_offset: 77 });
1350 let result = chain.migrate(state, 5, 5);
1351 assert!(result.is_ok());
1352 let out = result.unwrap().downcast::<ScrollState>().unwrap();
1353 assert_eq!(out.scroll_offset, 77);
1354 }
1355
1356 #[test]
1357 fn migration_chain_migrate_invalid_range_adjacent() {
1358 let chain = MigrationChain::<ScrollState>::new();
1359 let state: Box<dyn core::any::Any + Send> = Box::new(ScrollState::default());
1360 let result = chain.migrate(state, 2, 1);
1361 assert!(matches!(
1362 result,
1363 Err(MigrationError::InvalidVersionRange { from: 2, to: 1 })
1364 ));
1365 }
1366
1367 #[derive(Debug, Clone, Default)]
1369 struct ScrollStateV3 {
1370 scroll_offset: u16,
1371 velocity: f32,
1372 smooth_scroll: bool, }
1374
1375 struct V2ToV3Migration;
1376
1377 impl ErasedMigration<ScrollStateV3> for V2ToV3Migration {
1378 fn from_version(&self) -> u32 {
1379 2
1380 }
1381 fn to_version(&self) -> u32 {
1382 3
1383 }
1384 fn migrate_erased(
1385 &self,
1386 old: Box<dyn core::any::Any + Send>,
1387 ) -> Result<Box<dyn core::any::Any + Send>, String> {
1388 let v2 = old
1389 .downcast::<ScrollStateV2>()
1390 .map_err(|_| "invalid state type")?;
1391 Ok(Box::new(ScrollStateV3 {
1392 scroll_offset: v2.scroll_offset,
1393 velocity: v2.velocity,
1394 smooth_scroll: true, }))
1396 }
1397 }
1398
1399 struct V1ToV2ForV3Migration;
1400
1401 impl ErasedMigration<ScrollStateV3> for V1ToV2ForV3Migration {
1402 fn from_version(&self) -> u32 {
1403 1
1404 }
1405 fn to_version(&self) -> u32 {
1406 2
1407 }
1408 fn migrate_erased(
1409 &self,
1410 old: Box<dyn core::any::Any + Send>,
1411 ) -> Result<Box<dyn core::any::Any + Send>, String> {
1412 let v1 = old
1413 .downcast::<ScrollStateV1>()
1414 .map_err(|_| "invalid state type")?;
1415 Ok(Box::new(ScrollStateV2 {
1416 scroll_offset: v1.scroll_offset,
1417 velocity: 0.0,
1418 }))
1419 }
1420 }
1421
1422 #[test]
1423 fn migration_chain_multi_step_v1_to_v3() {
1424 let mut chain = MigrationChain::<ScrollStateV3>::new();
1425 chain.register(Box::new(V1ToV2ForV3Migration));
1426 chain.register(Box::new(V2ToV3Migration));
1427
1428 assert!(chain.has_path(1, 3));
1429 assert!(chain.has_path(1, 2));
1430 assert!(chain.has_path(2, 3));
1431
1432 let old = Box::new(ScrollStateV1 { scroll_offset: 55 });
1433 let result = chain.migrate(old, 1, 3);
1434 assert!(result.is_ok());
1435
1436 let migrated = result.unwrap().downcast::<ScrollStateV3>().unwrap();
1437 assert_eq!(migrated.scroll_offset, 55);
1438 assert_eq!(migrated.velocity, 0.0);
1439 assert!(migrated.smooth_scroll);
1440 }
1441
1442 struct FailingMigration;
1444
1445 impl ErasedMigration<ScrollStateV2> for FailingMigration {
1446 fn from_version(&self) -> u32 {
1447 1
1448 }
1449 fn to_version(&self) -> u32 {
1450 2
1451 }
1452 fn migrate_erased(
1453 &self,
1454 _: Box<dyn core::any::Any + Send>,
1455 ) -> Result<Box<dyn core::any::Any + Send>, String> {
1456 Err("data corruption detected".into())
1457 }
1458 }
1459
1460 #[test]
1461 fn migration_chain_migrate_failure() {
1462 let mut chain = MigrationChain::<ScrollStateV2>::new();
1463 chain.register(Box::new(FailingMigration));
1464
1465 let state: Box<dyn core::any::Any + Send> = Box::new(ScrollStateV1 { scroll_offset: 1 });
1466 let result = chain.migrate(state, 1, 2);
1467 assert!(result.is_err());
1468 match result.unwrap_err() {
1469 MigrationError::MigrationFailed { from, to, message } => {
1470 assert_eq!(from, 1);
1471 assert_eq!(to, 2);
1472 assert_eq!(message, "data corruption detected");
1473 }
1474 other => panic!("expected MigrationFailed, got {:?}", other),
1475 }
1476 }
1477
1478 #[test]
1479 fn migration_chain_type_mismatch_in_migrate_erased() {
1480 let mut chain = MigrationChain::<ScrollStateV2>::new();
1481 chain.register(Box::new(V1ToV2Migration));
1482
1483 let wrong: Box<dyn core::any::Any + Send> = Box::new("not a state".to_string());
1485 let result = chain.migrate(wrong, 1, 2);
1486 assert!(result.is_err());
1487 match result.unwrap_err() {
1488 MigrationError::MigrationFailed { from: 1, to: 2, .. } => {}
1489 other => panic!("expected MigrationFailed, got {:?}", other),
1490 }
1491 }
1492
1493 #[test]
1496 fn restore_result_debug() {
1497 let direct = RestoreResult::Direct(ScrollState { scroll_offset: 1 });
1498 let dbg = format!("{:?}", direct);
1499 assert!(dbg.contains("Direct"));
1500
1501 let migrated = RestoreResult::Migrated {
1502 state: ScrollState { scroll_offset: 2 },
1503 from_version: 1,
1504 };
1505 let dbg = format!("{:?}", migrated);
1506 assert!(dbg.contains("Migrated"));
1507
1508 let fallback = RestoreResult::DefaultFallback {
1509 error: MigrationError::NoPathFound { from: 1, to: 2 },
1510 default: ScrollState::default(),
1511 };
1512 let dbg = format!("{:?}", fallback);
1513 assert!(dbg.contains("DefaultFallback"));
1514 }
1515
1516 #[test]
1517 fn restore_result_into_state_migrated_with_data() {
1518 let result = RestoreResult::Migrated {
1519 state: ScrollState { scroll_offset: 99 },
1520 from_version: 1,
1521 };
1522 assert_eq!(result.into_state().scroll_offset, 99);
1523 }
1524
1525 #[derive(Default)]
1529 struct WidgetV2 {
1530 data: ScrollStateV2,
1531 }
1532
1533 impl Stateful for WidgetV2 {
1534 type State = ScrollStateV2;
1535
1536 fn state_key(&self) -> Option<StateKey> {
1537 Some(StateKey::new("WidgetV2", "test"))
1538 }
1539
1540 fn save_state(&self) -> ScrollStateV2 {
1541 self.data.clone()
1542 }
1543
1544 fn restore_state(&mut self, state: ScrollStateV2) {
1545 self.data = state;
1546 }
1547
1548 fn state_version() -> u32 {
1549 2
1550 }
1551 }
1552
1553 #[test]
1554 fn unpack_with_migration_direct_match() {
1555 let vs = VersionedState::new(
1556 2,
1557 ScrollStateV2 {
1558 scroll_offset: 33,
1559 velocity: 1.5,
1560 },
1561 );
1562 let chain = MigrationChain::<ScrollStateV2>::new();
1563 let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1564
1565 assert!(matches!(&result, RestoreResult::Direct(_)));
1566 assert!(!result.was_migrated());
1567 assert!(!result.is_fallback());
1568 let state = result.into_state();
1569 assert_eq!(state.scroll_offset, 33);
1570 assert_eq!(state.velocity, 1.5);
1571 }
1572
1573 #[test]
1574 fn unpack_with_migration_version_mismatch_type_mismatch_falls_back() {
1575 let vs = VersionedState::new(1, ScrollStateV2::default());
1579
1580 let mut chain = MigrationChain::<ScrollStateV2>::new();
1581 chain.register(Box::new(V1ToV2Migration));
1582
1583 let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1584 assert!(result.is_fallback());
1585 assert!(!result.was_migrated());
1586 }
1587
1588 #[test]
1589 fn unpack_with_migration_no_path_falls_back() {
1590 let vs = VersionedState::new(
1591 1,
1592 ScrollStateV2 {
1593 scroll_offset: 10,
1594 velocity: 0.0,
1595 },
1596 );
1597 let chain = MigrationChain::<ScrollStateV2>::new();
1599 let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1600
1601 assert!(result.is_fallback());
1602 let state = result.into_state();
1603 assert_eq!(state.scroll_offset, 0);
1605 assert_eq!(state.velocity, 0.0);
1606 }
1607
1608 #[test]
1609 fn unpack_with_migration_failed_migration_falls_back() {
1610 let vs = VersionedState::new(1, ScrollStateV2::default());
1611
1612 let mut chain = MigrationChain::<ScrollStateV2>::new();
1613 chain.register(Box::new(FailingMigration));
1614
1615 let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1616 assert!(result.is_fallback());
1617 }
1618
1619 #[test]
1620 fn unpack_with_migration_type_mismatch_after_chain() {
1621 struct WrongTypeMigration;
1623
1624 impl ErasedMigration<ScrollStateV2> for WrongTypeMigration {
1625 fn from_version(&self) -> u32 {
1626 1
1627 }
1628 fn to_version(&self) -> u32 {
1629 2
1630 }
1631 fn migrate_erased(
1632 &self,
1633 _: Box<dyn core::any::Any + Send>,
1634 ) -> Result<Box<dyn core::any::Any + Send>, String> {
1635 Ok(Box::new("wrong type".to_string()))
1637 }
1638 }
1639
1640 let vs = VersionedState::new(1, ScrollStateV2::default());
1641 let mut chain = MigrationChain::<ScrollStateV2>::new();
1642 chain.register(Box::new(WrongTypeMigration));
1643
1644 let result = vs.unpack_with_migration::<WidgetV2>(&chain);
1645 assert!(result.is_fallback());
1646 }
1647
1648 #[test]
1651 fn versioned_state_pack_uses_state_version() {
1652 let widget = TestTreeView {
1653 id: "test".into(),
1654 expanded: vec![1, 2],
1655 };
1656 let packed = VersionedState::pack(&widget);
1657 assert_eq!(packed.version, 2); assert_eq!(packed.data.expanded_nodes, vec![1, 2]);
1659 }
1660
1661 #[test]
1662 fn versioned_state_pack_default_version() {
1663 let widget = TestScrollView {
1664 id: "test".into(),
1665 offset: 0,
1666 max: 100,
1667 };
1668 let packed = VersionedState::pack(&widget);
1669 assert_eq!(packed.version, 1); }
1671
1672 #[test]
1675 fn scroll_state_clone() {
1676 let s = ScrollState { scroll_offset: 42 };
1677 let cloned = s.clone();
1678 assert_eq!(s, cloned);
1679 }
1680
1681 #[test]
1682 fn scroll_state_debug() {
1683 let s = ScrollState { scroll_offset: 10 };
1684 let dbg = format!("{:?}", s);
1685 assert!(dbg.contains("ScrollState"));
1686 assert!(dbg.contains("10"));
1687 }
1688
1689 #[test]
1690 fn tree_state_clone() {
1691 let s = TreeState {
1692 expanded_nodes: vec![1, 2, 3],
1693 collapse_all_on_blur: true,
1694 };
1695 let cloned = s.clone();
1696 assert_eq!(s, cloned);
1697 }
1698
1699 #[test]
1700 fn tree_state_debug() {
1701 let s = TreeState {
1702 expanded_nodes: vec![],
1703 collapse_all_on_blur: false,
1704 };
1705 let dbg = format!("{:?}", s);
1706 assert!(dbg.contains("TreeState"));
1707 }
1708}