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/mod.rs

@@ -1,11 +1,11 @@
 // Copyright 2022 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
-//! A widget providing a conjoined set of linear buttons that function in conjunction with each other.
+//! A widget providing a conjoined set of linear items that function in conjunction as a single button.
 //!
 //! ## Example
 //!
-//! Add the state and a message variant in your application for handling selections.
+//! Add the model and a message variant in your application for handling selections.
 //!
 //! ```ignore
 //! use iced_core::Length;
@@ -17,24 +17,35 @@
 //! }
 //!
 //! struct App {
-//!     state: segmented_button::SingleSelectModel<u16>(),
+//!     model: segmented_button::SingleSelectModel,
 //! }
 //! ```
 //!
-//! Then add choices to the state, while activating the first.
+//! Then add choices to the model, while activating the first.
 //!
 //! ```ignore
-//! application.model = SingleSelectModel::builder()
-//!     .insert_activate("Choice A", 0)
-//!     .insert("Choice B", 1)
-//!     .insert("Choice C", 2)
+//! application.model = segmented_button::Model::builder()
+//!     .insert(|b| b.text("Choice A").data(0u16))
+//!     .insert(|b| b.text("Choice B").data(1u16))
+//!     .insert(|b| b.text("Choice C").data(2u16))
 //!     .build();
 //! ```
 //!
+//! Or incrementally insert items with
+//!
+//! ```ignore
+//! let id = application.model.insert()
+//!     .text("Choice C")
+//!     .icon("custom-icon")
+//!     .data(3u16)
+//!     .data("custom-meta")
+//!     .id();
+//! ```
+//!
 //! Then use it in the view method to create segmented button widgets.
 //!
 //! ```ignore
-//! let widget = horizontal_segmented_button(&application.model)
+//! let widget = segmented_button::horizontal(&application.model)
 //!     .style(theme::SegmentedButton::ViewSeitcher)
 //!     .button_height(32)
 //!     .button_padding([16, 10, 16, 10])
@@ -43,22 +54,46 @@
 //!     .spacing(8)
 //!     .on_activate(AppMessage::Selected);
 //! ```
-
-/// COSMIC configurations of [`SegmentedButton`].
-pub mod cosmic;
+//!
+//! And respond to events like so:
+//!
+//! ```ignore
+//! match message {
+//!     AppMessage::Selected(id) => {
+//!         application.model.activate(id);
+//!
+//!         if let Some(number) = application.model.data::<u16>(id) {
+//!             println!("activated item with number {number}");
+//!         }
+//!
+//!         if let Some(text) = application.text(id) {
+//!             println!("activated button with text {text}");
+//!         }
+//!     }
+//! }
+//! ```
 
 mod horizontal;
-mod item;
 mod model;
-mod selection_modes;
 mod style;
 mod vertical;
 mod widget;
 
-pub use self::horizontal::{horizontal_segmented_button, HorizontalSegmentedButton};
-pub use self::item::{item, SegmentedItem};
-pub use self::model::{Batch, Key, Model, ModelBuilder, MultiSelectModel, SingleSelectModel};
-pub use self::selection_modes::Selectable;
-pub use self::style::{Appearance, ButtonAppearance, ButtonStatusAppearance, StyleSheet};
-pub use self::vertical::{vertical_segmented_button, VerticalSegmentedButton};
+pub use self::horizontal::{horizontal, HorizontalSegmentedButton};
+pub use self::model::{
+    BuilderEntity, Entity, EntityMut, Model, ModelBuilder, MultiSelect, MultiSelectEntityMut,
+    MultiSelectModel, Selectable, SingleSelect, SingleSelectEntityMut, SingleSelectModel,
+};
+pub use self::style::{Appearance, ItemAppearance, ItemStatusAppearance, StyleSheet};
+pub use self::vertical::{vertical, VerticalSegmentedButton};
 pub use self::widget::{focus, Id, SegmentedButton, SegmentedVariant};
+
+/// Associates extra data with an external secondary map.
+///
+/// The secondary map internally uses a `Vec`, so should only be used for data that
+pub type SecondaryMap<T> = slotmap::SecondaryMap<Entity, T>;
+
+/// Associates extra data with an external sparse secondary map.
+///
+/// Sparse maps internally use a `HashMap`, for data that is sparsely associated.
+pub type SparseSecondaryMap<T> = slotmap::SparseSecondaryMap<Entity, T>;