From ede8890a08b3fbbb1f6df3b8c277ab6424d1befd Mon Sep 17 00:00:00 2001
From: Aylur <k.demeter@protonmail.com>
Date: Tue, 15 Oct 2024 01:22:24 +0000
Subject: docs: better explain ags

---
 docs/guide/ags/first-widgets.md | 402 ----------------------------------------
 1 file changed, 402 deletions(-)
 delete mode 100644 docs/guide/ags/first-widgets.md

(limited to 'docs/guide/ags/first-widgets.md')

diff --git a/docs/guide/ags/first-widgets.md b/docs/guide/ags/first-widgets.md
deleted file mode 100644
index 6dba7b3..0000000
--- a/docs/guide/ags/first-widgets.md
+++ /dev/null
@@ -1,402 +0,0 @@
-# First Widgets
-
-AGS is the predecessor of Astal, which was written purely in TypeScript and so only supported
-JavaScript/TypeScript. Now it serves as a scaffolding tool for Astal projects in TypeScript.
-While what made AGS what it is, is now part of the Astal project, for simplicity we will
-refer to the Astal TypeScript lib as AGS.
-
-:::tip
-If you are not familiar with the JavaScript syntax [MDN](https://developer.mozilla.org/en-US/)
-and [javascript.info](https://javascript.info/) have great references.
-:::
-
-## Getting Started
-
-Start by initializing a project
-
-```sh
-ags --init
-```
-
-then run `ags` in the terminal
-
-```sh
-ags
-```
-
-Done! You have now a custom written bar using Gtk.
-
-:::tip
-AGS will transpile every `.ts`, `.jsx` and `.tsx` files into regular javascript then
-it will bundle everything into a single javascript file which then GJS can execute.
-The bundler used is [esbuild](https://esbuild.github.io/).
-:::
-
-## Root of every shell component: Window
-
-Astal apps are composed of widgets. A widget is a piece of UI that has its own logic and style.
-A widget can be as small as a button or an entire bar.
-The top level widget is always a [Window](https://aylur.github.io/libastal/class.Window.html) which will hold all widgets.
-
-::: code-group
-
-```tsx [widget/Bar.tsx]
-function Bar(monitor = 0) {
-    return <window className="Bar" monitor={monitor}>
-        <box>Content of the widget</box>
-    </window>
-}
-```
-
-:::
-
-::: code-group
-
-```ts [app.ts]
-import Bar from "./widget/Bar"
-
-App.start({
-    main() {
-        Bar(0)
-        Bar(1) // instantiate for each monitor
-    },
-})
-```
-
-:::
-
-## Creating and nesting widgets
-
-Widgets are JavaScript functions which return Gtk widgets,
-either by using JSX or using a widget constructor.
-
-:::code-group
-
-```tsx [MyButton.tsx]
-function MyButton(): JSX.Element {
-    return <button onClicked="echo hello">
-        <label label="Click me!" />
-    </button>
-}
-```
-
-```ts [MyButton.ts]
-import { Widget } from "astal"
-
-function MyButton(): Widget.Button {
-    return new Widget.Button(
-        { onClicked: "echo hello" },
-        new Widget.Label({ label: "Click me!" }),
-    )
-}
-```
-
-:::
-
-:::info
-The only difference between the two is the return type.
-Using markup the return type is always `Gtk.Widget` (globally available as `JSX.Element`),
-while using constructors the return type is the actual type of the widget.
-It is rare to need the actual return type, so most if not all of the time, you can use markup.
-:::
-
-Now that you have declared `MyButton`, you can nest it into another component.
-
-```tsx
-function MyBar() {
-    return <window>
-        <box>
-            Click The button
-            <MyButton />
-        </box>
-    </window>
-}
-```
-
-Notice that widgets you defined start with a capital letter `<MyButton />`.
-Lowercase tags are builtin widgets, while capital letter is for custom widgets.
-
-## Displaying Data
-
-JSX lets you put markup into JavaScript.
-Curly braces let you “escape back” into JavaScript so that you can embed some variable
-from your code and display it.
-
-```tsx
-function MyWidget() {
-    const label = "hello"
-
-    return <button>{label}</button>
-}
-```
-
-You can also pass JavaScript to markup attributes
-
-```tsx
-function MyWidget() {
-    const label = "hello"
-
-    return <button label={label} />
-}
-```
-
-## Conditional Rendering
-
-You can use the same techniques as you use when writing regular JavaScript code.
-For example, you can use an if statement to conditionally include JSX:
-
-```tsx
-function MyWidget() {
-    let content
-
-    if (condition) {
-        content = <True />
-    } else {
-        content = <False />
-    }
-
-    return <box>{content}</box>
-}
-```
-
-You can also inline a [conditional `?`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_operator) (ternary) expression.
-
-```tsx
-function MyWidget() {
-    return <box>{condition ? <True /> : <False />}</box>
-}
-```
-
-When you don’t need the `else` branch, you can also use a shorter [logical && syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_AND#short-circuit_evaluation):
-
-```tsx
-function MyWidget() {
-    return <box>{condition && <True />}</box>
-}
-```
-
-:::info
-As you can guess from the above snippet, [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) values are not rendered.
-:::
-
-## Rendering lists
-
-You can use [`for` loops](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for) or [array `map()` function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
-
-```tsx
-function MyWidget() {
-    const labels = [
-        "label1"
-        "label2"
-        "label3"
-    ]
-
-    return <box>
-        {labels.map(label => (
-            <label label={label} />
-        ))}
-    </box>
-}
-```
-
-## Widget signal handlers
-
-You can respond to events by declaring event handler functions inside your widget:
-
-```tsx
-function MyButton() {
-    function onClicked(self: Widget.Button, ...args) {
-        console.log(self, "was clicked")
-    }
-
-    return <button onClicked={onClicked} />
-}
-```
-
-The handler can also be a string, which will get executed in a subprocess asynchronously.
-
-```tsx
-function MyButton() {
-    return <button onClicked="echo hello" />
-}
-```
-
-:::info
-Attributes prefixed with `on` will connect to a `signal` of the widget.
-Their types are not generated, but written by hand, which means not all of them are typed.
-Refer to the Gtk and Astal docs to have a full list of them.
-:::
-
-## How properties are passed
-
-Using JSX, a custom widget will always have a single object as its parameter.
-
-```ts
-type Props = {
-    myprop: string
-    child?: JSX.Element // when only one child is passed
-    children?: Array<JSX.Element> // when multiple children are passed
-}
-
-function MyWidget({ myprop, child, children }: Props) {
-    //
-}
-```
-
-```tsx
-// child prop of MyWidget is the box
-return <MyWidget myprop="hello">
-    <box />
-</MyWidget>
-```
-
-```tsx
-// children prop of MyWidget is [box, box, box]
-return <MyWidget myprop="hello">
-    <box />
-    <box />
-    <box />
-</MyWidget>
-```
-
-## State management
-
-The state of widgets are handled with Bindings. A [Binding](./binding) lets you
-connect the state of an [object](./binding#subscribable-and-connectable-interface)
-to a widget so it re-renders when that state changes.
-
-Use the `bind` function to create a `Binding` object from a `Variable` or
-a regular `GObject` and one of its properties.
-
-Here is an example of a Counter widget that uses a `Variable` as its state:
-
-```tsx
-import { Variable, bind } from "astal"
-
-function Counter() {
-    const count = Variable(0)
-
-    function increment() {
-        count.set(count.get() + 1)
-    }
-
-    return <box>
-        <label label={bind(count).as(num => num.toString())} />
-        <button onClicked={increment}>
-            Click to increment
-        <button>
-    </box>
-}
-```
-
-:::info
-Bindings have an `.as()` method which lets you transform the assigned value.
-In the case of a Label, its label property expects a string, so it needs to be
-turned to a string first.
-:::
-
-:::tip
-`Variables` have a shorthand for `bind(variable).as(transform)`
-
-```tsx
-const v = Variable(0)
-const transform = (v) => v.toString()
-
-return <box>
-    {/* these two are equivalent */}
-    <label label={bind(v).as(transform)} />
-    <label label={v(transform)} />
-</box>
-```
-
-:::
-
-Here is an example of a battery percent label that binds the `percentage`
-property of the Battery object from the [Battery Library](/guide/libraries/battery):
-
-```tsx
-import Battery from "gi://AstalBattery"
-import { bind } from "astal"
-
-function BatteryPercentage() {
-    const bat = Battery.get_default()
-
-    return <label label={bind(bat, "percentage").as((p) => p * 100 + " %")} />
-}
-```
-
-## Dynamic children
-
-You can also use a `Binding` for `child` and `children` properties.
-
-```tsx
-const child = Variable(<box />)
-
-return <box>{child}</box>
-```
-
-```tsx
-const num = Variable(3)
-const range = (n) => [...Array(n).keys()]
-
-return <box>
-    {num(n => range(n).map(i => (
-        <button>
-            {i.toString()}
-        <button/>
-    )))}
-<box>
-```
-
-:::tip
-Binding children of widgets will implicitly call `.destroy()` on widgets
-that would be left without a parent. You can opt out of this behavior
-by setting `noImplicityDestroy` property on the container widget.
-:::
-
-:::info
-The above example destroys and recreates every widget in the list **every time**
-the value of the `Variable` changes. There might be cases where you would
-want to [handle child creation and deletion](/guide/ags/faq#avoiding-unnecessary-re-rendering)
-yourself, because you don't want to lose the
-inner state of widgets that does not need to be recreated. In this case
-you can create a [custom reactive structure](./binding#example-custom-subscribable)
-:::
-
-When there is at least one `Binding` passed as a child, the `children`
-parameter will always be a flattened `Binding<Array<JSX.Element>>`.
-When there is a single `Binding` passed as a child, the `child` parameter will
-be a `Binding<JSX.Element>` or a flattened `Binding<Array<JSX.Element>>`.
-
-```tsx
-function MyContainer({ children }) {
-    // children is a Binding over an Array of widgets
-}
-
-return <MyContainer>
-    <box />
-    {num(n => range(n).map(i => (
-        <button>
-            {i.toString()}
-        <button/>
-    )))}
-    [
-        [
-            <button />
-        ]
-        <button />
-    ]
-</MyContainer>
-```
-
-:::info
-You can pass the followings as children:
-
-- widgets
-- deeply nested arrays of widgets
-- bindings of widgets,
-- bindings of deeply nested arrays of widgets
-
-[falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) values are not rendered and anything not from this list
-will be coerced into a string and rendered as a label
-:::
-- 
cgit v1.2.3