Introduce `keyed::Column` widget

1 files changed, 55 insertions, 0 deletions

diff --git a/widget/src/keyed.rs b/widget/src/keyed.rs
new file mode 100644
index 00000000..55019535
--- /dev/null
+++ b/widget/src/keyed.rs
@@ -0,0 +1,55 @@
+//! Use widgets that can provide hints to ensure continuity.
+//!
+//! # What is continuity?
+//! Continuity is the feeling of persistence of state.
+//!
+//! In a graphical user interface, users expect widgets to have a
+//! certain degree of continuous state. For instance, a text input
+//! that is focused should stay focused even if the widget tree
+//! changes slightly.
+//!
+//! Continuity is tricky in `iced` and the Elm Architecture because
+//! the whole widget tree is rebuilt during every `view` call. This is
+//! very convenient from a developer perspective because you can build
+//! extremely dynamic interfaces without worrying about changing state.
+//!
+//! However, the tradeoff is that determining what changed becomes hard
+//! for `iced`. If you have a list of things, adding an element at the
+//! top may cause a loss of continuity on every element on the list!
+//!
+//! # How can we keep continuity?
+//! The good news is that user interfaces generally have a static widget
+//! structure. This structure can be relied on to ensure some degree of
+//! continuity. `iced` already does this.
+//!
+//! However, sometimes you have a certain part of your interface that is
+//! quite dynamic. For instance, a list of things where items may be added
+//! or removed at any place.
+//!
+//! There are different ways to mitigate this during the reconciliation
+//! stage, but they involve comparing trees at certain depths and
+//! backtracking... Quite computationally expensive.
+//!
+//! One approach that is cheaper consists in letting the user provide some hints
+//! about the identities of the different widgets so that they can be compared
+//! directly without going deeper.
+//!
+//! The widgets in this module will all ask for a "hint" of some sort. In order
+//! to help them keep continuity, you need to make sure the hint stays the same
+//! for the same items in your user interface between `view` calls.
+pub mod column;
+
+pub use column::Column;
+
+/// Creates a [`Column`] with the given children.
+///
+/// [`Column`]: widget::Column
+#[macro_export]
+macro_rules! keyed_column {
+    () => (
+        $crate::Column::new()
+    );
+    ($($x:expr),+ $(,)?) => (
+        $crate::keyed::Column::with_children(vec![$($crate::core::Element::from($x)),+])
+    );
+}