docs: update widget page

1 files changed, 29 insertions, 48 deletions

diff --git a/docs/guide/ags/widget.md b/docs/guide/ags/widget.md
index 1fe755f..3e96cb7 100644
--- a/docs/guide/ags/widget.md
+++ b/docs/guide/ags/widget.md
@@ -1,8 +1,8 @@
 # Widget
 
-## AGS widget properties
+## Additional widget properties
 
-These are properties that Astal.js additionally adds to Gtk.Widgets
+These are properties that Astal additionally adds to Gtk.Widgets
 
 - className: `string` - List of class CSS selectors separated by white space.
 - css: `string` - Inline CSS. e.g `label { color: white; }`. If no selector is specified `*` will be assumed. e.g `color: white;` will be inferred as `* { color: white; }`.
@@ -14,13 +14,12 @@ To have a full list of available properties, reference the documentation of the
 - [Astal widgets](https://aylur.github.io/libastal/index.html#classes)
 - [Gtk widgets](https://docs.gtk.org/gtk3/#classes)
 
-## AGS widget methods
-
-Additional methods that Astal.js adds to Gtk.Widget instances
+## Additional widget methods
 
 ### setup
 
-`setup` is a convenience prop to not have predefine widgets before returning them
+`setup` is a convenience prop to remove the need to predefine widgets
+before returning them in cases where a reference is needed.
 
 without `setup`
 
@@ -46,17 +45,19 @@ function MyWidget() {
 
 ### hook
 
-Shorthand for connection and disconnecting to gobjects.
+Shorthand for connection and disconnecting to [Subscribable and Connectable](http://localhost:5173/astal/guide/ags/binding#subscribable-and-connectable-interface) objects.
 
 without `hook`
 
 ```tsx
 function MyWidget() {
     const id = gobject.connect("signal", callback)
+    const unsub = variable.subscribe(callback)
 
     return <box
         onDestroy={() => {
             gobject.disconnect(id)
+            unsub()
         }}
     />
 }
@@ -69,6 +70,7 @@ function MyWidget() {
     return <box
         setup={(self) => {
             self.hook(gobject, "signal", callback)
+            self.hook(variable, callback)
         }}
     />
 }
@@ -90,33 +92,35 @@ function MyWidget() {
 
 ## How to use non builtin Gtk widgets
 
-Using `Widget.astalify` you can setup widget constructors to behave like builtin widgets.
-The `astalify` function will apply the following:
+Using the `Widget.astalify` mixin you can subclass widgets
+to behave like builtin widgets.
+The `astalify` mixin will apply the following:
 
 - set `visible` to true by default (Gtk3 widgets are invisible by default)
 - make gobject properties accept and consume `Binding` objects
 - add properties and methods listed above
-- proxify the constructor so the `new` keyword is not needed
 - sets up signal handlers that are passed as props prefixed with `on`
 
 ```tsx
-import { Widget, Gtk } from "astal"
-
-// define its props, constructor and type
-export type ColorButtonProps = Widget.ConstructProps<
-    Gtk.ColorButton,
-    Gtk.ColorButton.ConstructorProps,
-    { onColorSet: [] }
->
-export const ColorButton = Widget.astalify<
-    typeof Gtk.ColorButton,
-    ColorButtonProps,
-    "ColorButton"
->(Gtk.ColorButton)
-export type ColorButton = ReturnType<typeof ColorButton>
+import { Widget, Gtk, GObject, Gdk } from "astal"
+
+// subclass, register, define constructor props
+class ColorButton extends Widget.astalify(Gtk.ColorButton) {
+    static { GObject.registerClass(this) }
+
+    constructor(props: Widget.ConstructProps<
+        ColorButton,
+        Gtk.ColorButton.ConstructorProps,
+        { onColorSet: [] } // signals of Gtk.ColorButton have to be manually typed
+    >) {
+        super(props as any)
+    }
+}
 
 function MyWidget() {
-    function setup(button: ColorButton) {}
+    function setup(button: ColorButton) {
+
+    }
 
     return <ColorButton
         setup={setup}
@@ -140,29 +144,6 @@ You can reference [Gtk3](https://gjs-docs.gnome.org/gtk30~3.0/)
 and [Astal](https://aylur.github.io/libastal/index.html#classes) for available signals.
 :::
 
-:::tip
-
-As stated before children are passed as either `child` or `children` property,
-when passing a container widget with `Widget.astalify` these rules still apply.
-While subclasses of `Gtk.Bin` *can* take a `child` property in gjs, you might notice
-a warning that it is deprecated. You can workaround this with a simple wrapper function.
-
-```tsx
-const GtkFrame = Widget.astalify<
-    typeof Gtk.Frame,
-    FrameProps,
-    "Frame"
->(Gtk.Frame)
-
-export function Frame({ child, ...props }: FrameProps) {
-  const frame = GtkFrame(props)
-  frame.add(child) // use the widget's child adding function
-  return frame
-}
-```
-
-:::
-
 ## TypeScript
 
 Type of widgets are available through `Widget`.