feat!(segmented-button): improved interfaces and documentation

BREAKING CHANGE: Various type and function names have changed to reflect
themselves better in documentation. Code has been reorganized into
separate modules with a better placement in libcosmic. Most of the
functions, types, and modules now have documentation and examples.

These changes no longer require the `Model` type to define the
data/component type that it stores. The component functionality is now
optional, and it's also possible to associate many components to an item
with one component per type. This has had a side effect of simplifying a
lot of the type signatures in the implementation.

Before, to insert an item into the model, you had to define a
`SegmentedItem` and a `Component` on insert, and get back an ID for that
item. Which makes it difficult to define an item that contains only an
icon or has no components. And requires an extra insert function to
activate the item on insert.

Now, there is a flexible builder-style API for configuring
newly-inserted items in the model. So the complexity for inserting and
retrieving values from the model has decreased significantly

src/widget/segmented_button/model/selection.rs

@@ -0,0 +1,106 @@
+// Copyright 2022 System76 <info@system76.com>
+// SPDX-License-Identifier: MPL-2.0
+
+//! Describes logic specific to the single-select and multi-select modes of a model.
+
+use super::{Entity, Model};
+use std::collections::HashSet;
+
+/// Describes a type that has selectable items.
+pub trait Selectable {
+    /// Activate an item.
+    fn activate(&mut self, id: Entity);
+
+    /// Deactivate an item.
+    fn deactivate(&mut self, id: Entity);
+
+    /// Checks if the item is active.
+    fn is_active(&self, id: Entity) -> bool;
+}
+
+/// [`Model<SingleSelect>`] Ensures that only one key may be selected.
+#[derive(Debug, Default)]
+pub struct SingleSelect {
+    pub active: Entity,
+}
+
+impl Selectable for Model<SingleSelect> {
+    fn activate(&mut self, id: Entity) {
+        if !self.items.contains_key(id) {
+            return;
+        }
+
+        self.selection.active = id;
+    }
+
+    fn deactivate(&mut self, _id: Entity) {
+        self.selection.active = Entity::default();
+    }
+
+    fn is_active(&self, id: Entity) -> bool {
+        self.selection.active == id
+    }
+}
+
+impl Model<SingleSelect> {
+    /// Get an immutable reference to the data associated with the active item.
+    #[must_use]
+    pub fn active_data<Data: 'static>(&self) -> Option<&Data> {
+        self.data(self.active())
+    }
+
+    /// Get a mutable reference to the data associated with the active item.
+    #[must_use]
+    pub fn active_data_mut<Data: 'static>(&mut self) -> Option<&mut Data> {
+        self.data_mut(self.active())
+    }
+
+    /// Deactivates the active item.
+    pub fn deactivate(&mut self) {
+        Selectable::deactivate(self, Entity::default());
+    }
+
+    /// The ID of the active item.
+    #[must_use]
+    pub fn active(&self) -> Entity {
+        self.selection.active
+    }
+}
+
+/// [`Model<MultiSelect>`] permits multiple keys to be active at a time.
+#[derive(Debug, Default)]
+pub struct MultiSelect {
+    pub active: HashSet<Entity>,
+}
+
+impl Selectable for Model<MultiSelect> {
+    fn activate(&mut self, id: Entity) {
+        if !self.items.contains_key(id) {
+            return;
+        }
+
+        if !self.selection.active.insert(id) {
+            self.selection.active.remove(&id);
+        }
+    }
+
+    fn deactivate(&mut self, id: Entity) {
+        self.selection.active.remove(&id);
+    }
+
+    fn is_active(&self, id: Entity) -> bool {
+        self.selection.active.contains(&id)
+    }
+}
+
+impl Model<MultiSelect> {
+    /// Deactivates the item in the model.
+    pub fn deactivate(&mut self, id: Entity) {
+        Selectable::deactivate(self, id);
+    }
+
+    /// The IDs of the active items.
+    pub fn active(&self) -> impl Iterator<Item = Entity> + '_ {
+        self.selection.active.iter().copied()
+    }
+}