diff options
author | Aylur <[email protected]> | 2024-11-12 01:22:51 +0000 |
---|---|---|
committer | Aylur <[email protected]> | 2024-11-12 01:23:13 +0000 |
commit | 17aeb9ef945848befdbce0be76ffbeffe27c24d6 (patch) | |
tree | d9ef10f45e95339d6479d975edec1104acae0191 /docs/guide/typescript | |
parent | 2a9bb96f056f25c95b330984cfe7ac484db6c9c6 (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.md | 20 | ||||
-rw-r--r-- | docs/guide/typescript/first-widgets.md | 41 | ||||
-rw-r--r-- | docs/guide/typescript/installation.md | 80 | ||||
-rw-r--r-- | docs/guide/typescript/theming.md | 77 |
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`. ::: |