update to 1.8.0

TODO: list rest of subclassed widgets

Author: Aylur

src/content/docs/config/cli.md

@@ -20,7 +20,7 @@ OPTIONS:
     -r, --run-js            Execute string as an async function
     -f, --run-file          Execute file as an async function
     -I, --init              Initialize the configuration directory
-    -C, --clear-cache       Remove $HOME/.cache/ags
+    --clear-cache           Remove $HOME/.cache/ags
 
 ```
 

src/content/docs/config/common-issues.md

@@ -14,32 +14,28 @@ revealer that starts off with `reveal_child: false`
 
 ```js
 Widget.Window({
-  child: Widget.Box({
-    css: 'padding: 1px;',
-    child: Widget.Revealer(),
-  }),
+    child: Widget.Box({
+        css: 'padding: 1px;',
+        child: Widget.Revealer(),
+    }),
 })
 ```
 
 ## Custom svg symbolic icons
 
 Put svgs in a directory, named `<icon-name>-symbolic.svg`
-and use `Gtk.IconTheme.append_search_path` or `icons` option in exported object
+and use `App.addIcons` or `icons` option in exported object
 
 ```js
 // config.js
 import Gtk from 'gi://Gtk?version=3.0';
 
-Gtk.IconTheme.get_default().append_search_path(`${App.configDir}/assets`);
+App.addIcons(`${App.configDir}/assets`)
 
 Widget.Icon({
     icon: 'custom-symbolic', // custom-symbolic.svg
     css: 'color: green;', // can be colored, like other named icons
 });
-
-export default {
-    icons: `${App.configDir}/assets`,
-}
 ```
 
 ## GtkWindow is not a layer surface

src/content/docs/config/config-object.md

@@ -3,14 +3,12 @@ title: Config Object
 description: Exported configuration object
 ---
 
-When you start `ags`, it will try to `import` the `default` `export`
-from a module which defaults to `~/.config/ags/config.js`.
-Even if you mutate this object after initialization,
-the config **will not be reloaded**.
+`App.config` can be called any number of times, the passed
+properties will be applied on top of previous calls
 
 ```js
 // config.js
-export default {
+App.config({
     style: "./style.css",
     icons: "./assests",
     windows: [
@@ -28,11 +26,9 @@ export default {
     onWindowToggled: function (windowName, visible) {
         print(`${windowName} is ${visible}`)
     },
-};
+});
 ```
 
-## The exported config object
-
 | Field | Type | Description |
 |-------|------|-------------|
 | style | `string` | Path to a css file.

src/content/docs/config/first-widgets.md

@@ -3,15 +3,15 @@ title: Your First Widget
 description: Starting point to understanding how AGS works
 ---
 
-Start by creating `~/.config/ags/config.js` with the following contents:
+Start by creating `~/.config/ags/config.js`
 
 ```js
 // ~/.config/ags/config.js
-export default {
+App.config({
     windows: [
         // this is where window definitions will go
     ]
-}
+})
 ```
 
 then run `ags` in the terminal
@@ -45,11 +45,11 @@ const myBar = Widget.Window({
     child: myLabel,
 })
 
-export default { windows: [myBar] }
+App.config({ windows: [myBar] })
 ```
 
 :::tip
-GObject properties can be accessed or set in multiple ways:
+GObject properties can be accessed or set in several ways:
 with `camelCase`, `snake_case`, and `kebab-case`
 
 ```js
@@ -89,12 +89,12 @@ function Bar(monitor = 0) {
     })
 }
 
-export default {
+App.config({
     windows: [
         Bar(0), // can be instantiated for each monitor
         Bar(1),
     ],
-}
+})
 ```
 
 :::note
@@ -103,7 +103,7 @@ if it is passed to `windows` in the exported object.
 
 Calling `Widget.Window` will create and show the window by default.
 It is not necessary to pass a reference to `windows` in
-the exported object, but if it is not,
+the config object, but if it is not,
 it can't be toggled with `ags --toggle-window` or through `App.toggleWindow`
 :::
 

src/content/docs/config/reactivity.md

@@ -2,8 +2,84 @@
 title: Reactivity
 ---
 
-We have used `poll` and `bind` so far to make widgets
-have content dynamically. There is also `on`, `hook` and `keybind` methods.
+In order for widgets to have dynamic content we pass `Binding`s as properties
+or setup a `hook`.
+A `Binding` is just an object that holds information for widget constructors
+to setup a listener.
+
+## Property Bindings
+
+We can make a `Binding` from a Variable
+
+```js
+const percent = Variable(0.5)
+const slider = Widget.Slider({
+    value: percent.bind(),
+    onChange: ({ value }) => percent.value = value,
+})
+```
+
+From a `Service`
+
+```js
+const { speaker } = await Service.import("audio")
+const slider = Widget.Slider({
+    value: speaker.bind("volume"),
+    onChange: ({ value }) => speaker.volume = value,
+})
+```
+
+Merge any number of `Binding`s into another `Binding`
+
+```js
+const a = Variable(0.3)
+const b = Variable(0.7)
+const merged = Utils.merge([a.bind(), b.bind()], (a, b) => {
+    return a * b
+})
+
+const level = Widget.LevelBar({
+    value: merged
+})
+```
+
+Turn one or multiple Service signals into a `Binding`
+
+```js
+const mpris = await Service.import("mpris")
+
+const label = Widget.Label({
+    label: Utils.watch("initial-label", mpris, "player-added", (busName) => {
+        return `player ${busName} was added`
+    })
+})
+
+const label = Widget.Label({
+    label: Utils.watch("initial-label", [
+        [mpris, "player-added"],
+        [mpris, "player-removed"],
+    ], (busName) => {
+        return `player ${busName} was added or removed`
+    })
+})
+```
+
+A `Binding` can be transformed according to need
+
+```js
+const num = Variable(0)
+
+const label = Widget.Label({
+    // will throw an error, because number is not assignable to string
+    label: num.bind(),
+
+    // will have to be transformed
+    label: num.bind().as(n => n.toString()),
+    label: num.bind().as(String)
+})
+```
+
+## Hooks
 
 You can call these on any Widget that you have a reference on.
 They will return `this` reference, meaning you
@@ -12,90 +88,69 @@ can chain them up in any order in any number.
 ```js
 const widget = Widget()
 widget.hook()
-widget.bind()
+widget.on()
+widget.poll()
+widget.keybind()
 ```
 
 ```js
 const widget = Widget()
     .hook()
-    .bind()
+    .on()
 ```
 
 ```js
 const widget = Widget({
     setup: self => {
-        self.bind()
         self.hook()
+        self.on()
     }
 })
 ```
 
 ```js
 const widget = Widget({
     setup: self => self
-        .bind()
         .hook()
+        .on()
 })
 ```
 
-## Hook
+### Hook
 
 `hook` will setup a listener to a `GObject` and will handle disconnection
 when the widget is destroyed. It will connect
 to the `changed` signal by default when not specified otherwise.
 
 ```js
+const battery = await Service.import("battery")
+
 // .hook(GObject, callback, signal?)
 const BatteryPercent = () => Label()
-    .hook(Battery, label => {
-        label.label = `${Battery.percent}%`
-        label.visible = Battery.available
-    }, 'changed')
+    .hook(battery, self => {
+        self.label = `${battery.percent}%`
+        self.visible = battery.available
+    }, "changed")
 ```
 
-## Bind
-
-`bind` can be directly translated to `hook`.
-It will setup a listener based on property changes
+:::caution
+A `hook` callback will be executed on startup.
+If you are connecting to a signal that has an argument
+you will need to check if its defined first
 
 ```js
-const label = Label()
+const mpris = await Service.import("mpris")
+const label = Widget.Label().hook(mpris, (self, busName) => {
+    if (!busName)
+        return // skip startup execution
 
-label.bind(
-    'label', // self property to bind
-    Battery, // GObject to listen to
-    'percent', // target property
-    p => `${p}%`) // optional transform method
-
-// translates to
-label.hook(
-    Battery,
-    self => self['label'] = `${Battery['percent']}%`,
-    'notify::percent')
+    self.label = busName
+}, "player-added")
 ```
 
-It is also possible to call `bind` on [Services](./services)
-and [Variables](./variables) that can be used inside constructors.
+:::
 
-```js
-Label({
-    label: Battery
-        .bind('percent')
-        .as(p => `${p}%`)
-})
-```
-
-```js
-const text = Variable('hello')
-
-Label({
-    label: text
-        .bind()
-        .as(v => `transformed ${v}`)
-})
-```
-
-## On
+### On
 
 `on` is the same as `connect` but instead of the signal handler id,
 it returns a reference to the widget. `on` will setup a callback on a widget signal.
@@ -106,8 +161,8 @@ These two are equivalent
 function MyButton() {
     const self = Widget.Button()
 
-    self.connect('clicked', () => {
-        print(self, 'is clicked')
+    self.connect("clicked", () => {
+        print(self, "is clicked")
     })
 
     return self
@@ -116,12 +171,24 @@ function MyButton() {
 
 ```js
 const MyButton = () => Widget.Button()
-    .on('clicked', self => {
-        print(self, 'is clicked')
+    .on("clicked", self => {
+        print(self, "is clicked")
     })
 ```
 
-## Poll
+:::note
+Most signals like `clicked` are available as a propety on the widget.
+So its rare that `.on` or `.connect` will be needed.
+
+```js
+Widget.Button({
+    on_clicked: self => print(self, "was clicked")
+})
+```
+
+:::
+
+### Poll
 
 Avoid using this as much as possible, using this is considered bad practice.
 
@@ -146,7 +213,7 @@ const MyLabel = () => Widget.Label()
     })
 ```
 
-## Keybind
+### Keybind
 
 It is possible to setup keybindings on focused widgets