Improve masonry docs (linebender#1059)

This fixes some things that have bitrotted due to API and other changes.

It also removes usages of `masonry_winit` where `masonry` should be used
instead.

Dependencies like `kurbo`, `peniko`, `smallvec`, and `vello` should be
referenced via their re-exports so that code outside of Masonry doesn't
have to keep track of the versions and maintain their own dependencies.

Author: waywardmonkeys

masonry/src/doc/02_implementing_widget.md

@@ -61,8 +61,8 @@ This widget has a size, a color, and will notify Masonry when the user left-clic
 First, let's create our struct:
 
 ```rust,ignore
-use vello::kurbo::Size;
-use vello::peniko::Color;
+use masonry::kurbo::Size;
+use masonry::peniko::Color;
 
 struct ColorRectangle {
     size: Size,
@@ -85,15 +85,15 @@ Note that we store a size, and not a position: our widget's position is managed
 First we implement event methods:
 
 ```rust,ignore
-use masonry_winit::core::{
-    Widget, EventCtx, PointerEvent, TextEvent, AccessEvent, Action
+use masonry::core::{
+    AccessEvent, Action, EventCtx, PointerButton, PointerEvent, PropertiesMut, TextEvent, Widget
 };
 
 impl Widget for ColorRectangle {
     fn on_pointer_event(&mut self, ctx: &mut EventCtx<'_>, _props: &mut PropertiesMut<'_>, event: &PointerEvent) {
         match event {
-            PointerEvent::PointerDown(PointerButton::Primary, _) => {
-                ctx.submit_action(Action::ButtonPressed(PointerButton::Primary));
+            PointerEvent::Down { button: Some(PointerButton::Primary), .. } => {
+                ctx.submit_action(Action::ButtonPressed(Some(PointerButton::Primary)));
             }
             _ => {},
         }
@@ -104,7 +104,7 @@ impl Widget for ColorRectangle {
     fn on_access_event(&mut self, ctx: &mut EventCtx<'_>, _props: &mut PropertiesMut<'_>, event: &AccessEvent) {
             match event.action {
                 accesskit::Action::Click => {
-                    ctx.submit_action(Action::ButtonPressed(PointerButton::Primary));
+                    ctx.submit_action(Action::ButtonPressed(Some(PointerButton::Primary)));
                 }
                 _ => {}
             }
@@ -129,8 +129,8 @@ We don't handle any text events.
 Since our widget isn't animated and doesn't react to changes in status, we can leave the `on_anim_frame` and `update` implementations empty:
 
 ```rust,ignore
-use masonry_winit::core::{
-    UpdateCtx, Update,
+use masonry::core::{
+    PropertiesMut, UpdateCtx, Update, Widget
 };
 
 impl Widget for ColorRectangle {
@@ -148,9 +148,10 @@ impl Widget for ColorRectangle {
 Next we implement layout:
 
 ```rust,ignore
-use masonry_winit::core::{
-    LayoutCtx, BoxConstraints
+use masonry::core::{
+    BoxConstraints, LayoutCtx, PropertiesMut, Widget
 };
+use masonry::kurbo::Size;
 
 impl Widget for ColorRectangle {
     // ...
@@ -173,11 +174,13 @@ We return our stored size, clamped between the min and max constraints.
 Next we write our render methods:
 
 ```rust,ignore
-use masonry_winit::core::{
-    PaintCtx, AccessCtx
+use masonry::accesskit::{Node, Role};
+use masonry::core::{
+    AccessCtx, PaintCtx, PropertiesRef, Widget
 };
-use vello::Scene;
-use accesskit::{Node, Role};
+use masonry::kurbo::Affine;
+use masonry::peniko::Fill;
+use masonry::vello::Scene;
 
 impl Widget for ColorRectangle {
     // ...
@@ -239,13 +242,14 @@ Pragmatically, if you're not sure about what a certain value means or how to imp
 We also write a `make_trace_span()` method, which is useful for debugging with the [tracing](https://docs.rs/tracing/latest/tracing/) framework.
 
 ```rust,ignore
+use masonry::core::{QueryCtx, Widget};
 use tracing::{trace_span, Span};
 
 impl Widget for ColorRectangle {
     // ...
 
-    fn make_trace_span(&self) -> Span {
-        trace_span!("ColorRectangle")
+    fn make_trace_span(&self, ctx: &QueryCtx<'_>) -> Span {
+        trace_span!("ColorRectangle", id = ctx.widget_id().trace())
     }
 
     // ...
@@ -255,10 +259,10 @@ impl Widget for ColorRectangle {
 And last, we stub in some additional methods:
 
 ```rust,ignore
-use masonry_winit::core::{
-    RegisterCtx, WidgetId
+use masonry::core::{
+    RegisterCtx, Widget, WidgetId
 };
-use smallvec::SmallVec;
+use masonry::smallvec::SmallVec;
 
 impl Widget for ColorRectangle {
     // ...

masonry/src/doc/03_implementing_container_widget.md

@@ -50,7 +50,7 @@ A container widget needs to pay special attention to these methods:
 trait Widget {
     // ...
 
-    fn layout(&mut self, ctx: &mut LayoutCtx<'_>) -> Size;
+    fn layout(&mut self, ctx: &mut LayoutCtx<'_>, _props: &mut PropertiesMut<'_>, bc: &BoxConstraints) -> Size;
     fn compose(&mut self, ctx: &mut ComposeCtx<'_>);
 
     fn register_children(&mut self, ctx: &mut RegisterCtx<'_>);
@@ -78,9 +78,10 @@ When debug assertions are on, Masonry will actively try to detect cases where yo
 For our `VerticalStack`, we'll lay out our children in a vertical line, with a gap between each child; we give each child an equal share of the available height:
 
 ```rust,ignore
-use masonry_winit::core::{
-    LayoutCtx, BoxConstraints
+use masonry::core::{
+    BoxConstraints, LayoutCtx, PropertiesMut, Widget
 };
+use masonry::kurbo::{Point, Size};
 
 impl Widget for VerticalStack {
     // ...
@@ -131,8 +132,8 @@ For instance, if a widget in a list changes size, its siblings and parents must
 In the case of our `VerticalStack`, we don't implement any transform-only changes, so we don't need to do anything in compose:
 
 ```rust,ignore
-use masonry_winit::core::{
-    LayoutCtx, BoxConstraints
+use masonry::core::{
+    BoxConstraints, ComposeCtx, Widget
 };
 
 impl Widget for VerticalStack {
@@ -147,8 +148,8 @@ impl Widget for VerticalStack {
 The `register_children` method must call [`RegisterCtx::register_child`] for each child:
 
 ```rust,ignore
-use masonry_winit::{
-    Widget, RegisterCtx
+use masonry::core::{
+    RegisterCtx, Widget
 };
 
 impl Widget for VerticalStack {

masonry/src/doc/04_testing_widget.md

@@ -31,8 +31,8 @@ First, let's write a test module with a first unit test:
 #[cfg(test)]
 mod tests {
     use insta::assert_debug_snapshot;
-    use masonry_winit::testing::{widget_ids, TestHarness, TestWidgetExt};
-    use masonry_winit::theme::default_property_set;
+    use masonry::testing::{widget_ids, TestHarness, TestWidgetExt};
+    use masonry::theme::default_property_set;
 
     use super::*;
 
@@ -78,7 +78,7 @@ Let's add a visual test:
 
 ```rust,ignore
     // ...
-    use masonry_winit::assert_render_snapshot;
+    use masonry::assert_render_snapshot;
 
     #[test]
     fn simple_rect() {
@@ -191,7 +191,7 @@ Since our `WidgetRectangle` doesn't emit actions, let's look at a unit test for
         harness.mouse_click_on(button_id);
         assert_eq!(
             harness.pop_action(),
-            Some((Action::ButtonPressed(PointerButton::Primary), button_id))
+            Some((Action::ButtonPressed(Some(PointerButton::Primary)), button_id))
         );
     }
 ```

masonry/src/doc/04b_widget_properties.md

@@ -83,13 +83,13 @@ Properties should *not* be used to represent an individual widget's state. The f
 With that in mind, let's rewrite our `ColorRectangle` widget to use properties:
 
 ```rust,ignore
-use masonry_winit::properties::BackgroundColor;
+use masonry::properties::BackgroundColor;
 
 impl Widget for ColorRectangle {
     // ...
 
     fn paint(&mut self, ctx: &mut PaintCtx<'_>, props: &PropertiesRef<'_>, scene: &mut Scene) {
-        let color = props.get::<BackgroundColor>().unwrap_or(masonry_winit::palette::css::WHITE);
+        let color = props.get::<BackgroundColor>().unwrap_or(masonry::palette::css::WHITE);
         let rect = ctx.size().to_rect();
         scene.fill(
             Fill::NonZero,
@@ -111,7 +111,7 @@ The most idiomatic way to set properties is through `WidgetMut`:
 ```rust,ignore
 let color_rectangle_mut: WidgetMut<ColorRectangle> = ...;
 
-let bg = BackgroundColor { color: masonry_winit::palette::css::BLUE };
+let bg = BackgroundColor { color: masonry::palette::css::BLUE };
 
 color_rectangle_mut.insert_prop(bg);
 ```