summaryrefslogtreecommitdiff
path: root/docs/guide/typescript
diff options
context:
space:
mode:
authorAylur <[email protected]>2024-11-12 01:22:51 +0000
committerAylur <[email protected]>2024-11-12 01:23:13 +0000
commit17aeb9ef945848befdbce0be76ffbeffe27c24d6 (patch)
treed9ef10f45e95339d6479d975edec1104acae0191 /docs/guide/typescript
parent2a9bb96f056f25c95b330984cfe7ac484db6c9c6 (diff)
docs: remove ags related docs
ags documentation will live on its own site
Diffstat (limited to 'docs/guide/typescript')
-rw-r--r--docs/guide/typescript/cli-app.md20
-rw-r--r--docs/guide/typescript/first-widgets.md41
-rw-r--r--docs/guide/typescript/installation.md80
-rw-r--r--docs/guide/typescript/theming.md77
4 files changed, 35 insertions, 183 deletions
diff --git a/docs/guide/typescript/cli-app.md b/docs/guide/typescript/cli-app.md
index 85b117c..9217acc 100644
--- a/docs/guide/typescript/cli-app.md
+++ b/docs/guide/typescript/cli-app.md
@@ -6,7 +6,6 @@ Depending on gtk version import paths will differ
```ts
import { App } from "astal/gtk3"
-
import { App } from "astal/gtk4"
```
@@ -53,20 +52,11 @@ App.start({
})
```
-:::code-group
-
-```sh [astal]
+```sh
astal say hi
# hi cli
```
-```sh [ags]
-ags request "say hi"
-# hi cli
-```
-
-:::
-
If you want to run arbitrary JavaScript from CLI, you can use `App.eval`
which will evaluate the passed string as the body of an `async` function.
@@ -128,18 +118,10 @@ When assigning the `application` prop make sure `name` comes before.
Props are set sequentially and if name is applied after application it won't work.
:::
-:::code-group
-
```sh [astal]
astal -t Bar
```
-```sh [ags]
-ags toggle Bar
-```
-
-:::
-
## Bundled scripts
The produced scripts when bundling can run as the main instance
diff --git a/docs/guide/typescript/first-widgets.md b/docs/guide/typescript/first-widgets.md
index 96a1275..a467382 100644
--- a/docs/guide/typescript/first-widgets.md
+++ b/docs/guide/typescript/first-widgets.md
@@ -2,41 +2,26 @@
## Getting Started
-Start by initializing a project
+Start by importing the singleton
+[Astal.Application](https://aylur.github.io/libastal/astal3/class.Application.html) instance.
-```sh
-ags init
-```
+:::code-group
-then run `ags run` in the terminal
+```ts [app.ts]
+import { App } from "astal/gtk3"
-```sh
-ags run
+App.start({
+ main() {
+ // you will instantiate Widgets here
+ // and setup anything else if you need
+ }
+})
```
-:::details Usage without AGS
-🚧 Not yet documented. 🚧
-:::
-
-That's it! 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 AGS init command will generate the following files
-
-```txt
-.
-├── @girs/ # generated types
-├── widget/
-│ └── Bar.tsx
-├── app.ts # entry proint
-├── env.d.ts # additional types
-├── style.css
-└── tsconfig.json # needed by LSPs
-```
+After your [bundle step](./installation.md) run `gjs -m app.js`, and that's it!
+Now you have an Astal instance running written in TypeScript.
## Root of every shell component: Window
diff --git a/docs/guide/typescript/installation.md b/docs/guide/typescript/installation.md
index e0f1bd5..0c19325 100644
--- a/docs/guide/typescript/installation.md
+++ b/docs/guide/typescript/installation.md
@@ -1,89 +1,19 @@
# Installation
-It is recommended to use [AGS](https://github.com/aylur/ags)
+It is recommended to use [AGS](https://aylur.github.io/ags/)
to scaffold and run projects in TypeScript.
It lets you
- generate TypeScript types using [ts-for-gir](https://github.com/gjsify/ts-for-gir)
-- generate a tsconfig which is used by LSPs
-- bundle your TypeScript and JavaScript code using [esbuild](https://esbuild.github.io/).
+- generate a tsconfig which is used by LSPs to provide intellisense
+- bundle your TypeScript and JavaScript code using [esbuild](https://esbuild.github.io/)
:::details Trivia
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+TypeScript+JSX projects.
+JavaScript/TypeScript. Now it serves as a scaffolding tool for Astal+TypeScript projects.
:::
-## Nix
-
-maintainer: [@Aylur](https://github.com/Aylur)
-
-Read more about it on the [nix page](../getting-started/nix#ags)
-
-You can try without installing.
-
-<!--TODO: remove v2 after merge-->
-```sh
-nix run github:aylur/ags/v2#agsFull -- --help
-```
-
-## From source
-
-1. [Install Astal](../getting-started/installation.md) if you have not already
-
-2. Install the Astal GJS package
-
-```sh
-git clone https://github.com/aylur/astal /tmp/astal
-cd /tmp/astal/lang/gjs
-meson setup --prefix /usr build
-meson install -C build
-```
-
-:::tip
-You might be wondering why it is recommended to install a JavaScript
-package on the system instead of installing it as a node module.
-It is solely to keep it in **sync** with the core `astal-io` and `astal3`/`astal4` package.
-:::
-
-3. Install the following dependencies
-
-:::code-group
-
-```sh [<i class="devicon-archlinux-plain"></i> Arch]
-sudo pacman -Syu go npm gjs
-```
-
-```sh [<i class="devicon-fedora-plain"></i> Fedora]
-sudo dnf install golang npm gjs
-```
-
-```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
-sudo apt install golang-go npm gjs
-```
-
-:::
-
-3. Clone the repo and Install
-
-<!--TODO: remove v2 after merge-->
-```sh
-git clone https://github.com/aylur/ags.git /tmp/ags
-cd /tmp/ags
-git checkout v2 # https://github.com/Aylur/ags/pull/504
-go install
-```
-
-:::tip
-`go install` installs the `ags` binary to `$GOPATH/bin` so make sure its in your `$PATH`.
-You can move it to another directory if you like. For example
-
-```sh
-sudo mv $GOPATH/bin/ags /usr/bin/ags
-```
-
-:::
-
-## Without AGS
+## Setting up a project
🚧 Setting up a dev environment without AGS is not yet documented. 🚧
diff --git a/docs/guide/typescript/theming.md b/docs/guide/typescript/theming.md
index 10a3981..5944c4e 100644
--- a/docs/guide/typescript/theming.md
+++ b/docs/guide/typescript/theming.md
@@ -23,28 +23,24 @@ You can pass a path to a file or css as a string in `App.start`
:::code-group
```ts [app.ts]
-import style from "inline:./style.css"
-
-const inlineCssInCode = `
-window {
- background-color: transparent;
-}
+const inlineCss = `
+ window {
+ background-color: transparent;
+ }
`
App.start({
- css: "./style.css",
- css: style,
- css: `${SRC}/style.css'`,
css: inlineCss,
+ css: "./style.css",
+ css: "/path/to/style.css",
})
```
:::
-:::info
-When using AGS the global `SRC` will point to the directory `app.ts` is in.
-AGS will set the current working directory to `--config`, so `./style.css` also works.
-If you are not using AGS you should inline import CSS instead.
+:::warning
+When using relative paths, for example `./style.css` keep in mind that they
+will be relative to the current working directory.
:::
## Css Property on Widgets
@@ -90,20 +86,11 @@ You can reset stylesheets with `App.resetCss`
If you are not sure about the widget hierarchy or any CSS selector,
you can use the [GTK inspector](https://wiki.gnome.org/Projects/GTK/Inspector)
-::: code-group
-
-```sh [astal]
+```sh
# to bring up the inspector run
astal --inspector
```
-```sh [ags]
-# to bring up the inspector run
-ags --inspector
-```
-
-:::
-
## Using SCSS
Gtk's CSS only supports a subset of what the web offers.
@@ -126,54 +113,22 @@ npm install -g sass # not packaged on Ubuntu
:::
-Importing `scss` files will simply return transpiled css.
-
:::code-group
```ts [app.ts]
-import style from "./style.scss"
+import { exec } from "astal/process"
+
+exec("sass", "./style.scss", "/tmp/style.css")
App.start({
- css: style,
+ css: "/tmp/style.css",
main() {},
})
```
:::
-:::details Without AGS
-AGS uses a plugin to transpile scss files before importing them.
-If you are not using AGS, you can use a plugin for your chosen bundler.
-:::
-
:::tip
-If you for example want to set scss varibles from JS,
-You can inline import, compose, and transpile yourself.
-
-```ts [app.ts]
-import style1 from "inline:./style1.scss"
-import style2 from "inline:./style2.scss"
-
-const tmpscss = "/tmp/style.scss"
-const target = "/tmp/style.css"
-
-writeFile(tmpscss, `
- $var1: red;
- $var1: blue;
- ${style1}
- ${style1}
-`)
-
-exec(`sass ${tmpscss} ${target}`)
-
-App.start({
- css: target,
-})
-
-```
-
-:::
-
-:::info
-If you want other preprocessors support builtin open an Issue.
+You could also transpile scss into css using a bundler
+and simply passing the path of the resulting css file to `css`.
:::