From 0c36e42f907e378a2263f9ef6748127e3c243f2d Mon Sep 17 00:00:00 2001 From: Sylvia Crowe Date: Wed, 16 Oct 2024 14:00:55 -0700 Subject: [PATCH 1/2] feat: make install instructions for custom widgets --- docs/customwidgets.mdx | 107 +++++++++++++++++++++++++++++++++++++++++ docs/faq.mdx | 5 +- docs/index.mdx | 1 + docs/releasenotes.mdx | 2 +- 4 files changed, 110 insertions(+), 5 deletions(-) create mode 100644 docs/customwidgets.mdx diff --git a/docs/customwidgets.mdx b/docs/customwidgets.mdx new file mode 100644 index 0000000..284d7b5 --- /dev/null +++ b/docs/customwidgets.mdx @@ -0,0 +1,107 @@ +--- +sidebar_position: 6 +id: "customwidgets" +title: "Custom Widgets" +--- + +# Custom Widgets + +Wave allows users to create their own widgets to uniquely customize their experience for what works for them. While we plan on greatly expanding on this in the future, it is already possible to make terminal/cli widgets that you can access at the press of a button. + +# Terminal and CLI Widgets + +A terminal widget, or CLI widget, is a widget that simply opens a terminal and runs a CLI command. These widgets are managed in the `~/.waveterm/config/widgets.json` file. + +## Designing a Widget + +Each widget is a key-value pair of a json object where the key is the name of the widget, and the value is an object responsible for configuring the widget. As a whole, it looks like: +```json +{ + <... other widgets go here ...>, + "": { + "icon": "", + "label": "", + "color": "", + "blockdef": { + "meta": { + "view": "term", + "controller": "cmd" + "cmd": "" + } + } + }, + <... other widgets go here ...> +} +``` +In essence, there are two places that require customization. The first is the outer `WidgetConfigType` which is directly in the object that corresponds with the widget name. In the example above, it contains `"icon"`, `"label"`, and `"color"`. Valid options for this type include: +| Key | Description | +|-----|-------------| +|"display:order"| (optional) Overrides the order of widgets with a number in case you want the widget to be different than the order provided in the `widgets.json` file. Defaults to 0. | +|"icon"| (optional) The name of a fontawesome icon. Defaults to `"browser"`.| +|"color"| (optional) A string representing a color as would be used in CSS. Hex codes and custom CSS properties are included. This defaults to `"var(--secondary-text-color)"` which is a color wave uses for text that should be differentiated from other text. Out of the box, it is `"#c3c8c2"`.| +|"label"| (optional) A string representing the label that appears underneath the widget. It will also act as a tooltip on hover if the `"description"` key isn't filled out. It is null by default.| +|"description"| (optional) A description of what the widget does. If it is specified, this serves as a tooltip on hover. It is null by default.| +|"blockdef"| This is where the the non-visual portion of the widget is defined. Note that all further definition takes place inside a meta object inside this one.| + + +The other part to configure is the `MetaTSType` associated with the widget. The topic of the `MetaTSType` is vast and deserves it's own documentation, but here is a subset that is relevant to creating terminal widgets. +| Key | Description | +|-----|-------------| +| "view" | A string that specifies the general type of widget. In the case of custom terminal widgets, this must be set to `"term"`.| +| "controller" | A string that specifies the type of command being used. For more persistent shell sessions, set it to "shell". For one off commands, set it to "cmd". Note that it is often possible to achieve the same result through each depending on the command being used.| +| "cmd" | (optional) When the `"controller"` is set to `"cmd"`, this option provides the actual command to be run. Note that because it is run as a command, there is no shell session unless you are launching a command that contains a shell session itself. Defaults to an empty string. | +| "cmd:interactive" | (optional) When the `"controller"` is set to `"term", this boolean adds the interactive flag to the launched terminal. Defaults to false.| +| "cmd:login" | (optional) When the `"controller"` is set to `"term"`, this boolean adds the login flag to the term command. Defaults to false.| +| "cmd:runonstart" | (optional) The command will rerun when the app is started. Without it, you must manually run the command. Defaults to true.| +| "cmd:clearonstart" | (optional) When the cmd starts, the contents of the block are cleared out. Defaults to false. | +| "cmd:clearonrestart" | (optional) When the app restarts, the contents of the block are cleared out. Defaults to false. | +| "cmd:env" | (optional) A key-value object represting environment variables to be run with the command. Currently only works locally. Defaults to an empty object. | +| "cmd:cwd" | (optional) A string representing the current working directory to be run with the command. Currently only works locally. Defaults to the home directory. | +| "cmd:nowsh" | (optional) A boolean that will turn off wsh integration for the command. Defaults to false. | +| "term:localshellpath" | (optional) Sets the shell used for running your widget command. Only works locally. If left blank, wave will determine your system default instead. | +| "term:localshellopts" | (optional) Sets the shell options meant to be used with `"term:localshellpath"`. This is useful if you are using a nonstandard shell and need to provide a specific option that we do not cover. Only works locally. Defaults to an empty string. | + + + +## Example Widgets + +Here are a few simple widgets to serve as examples. + +Suppose I want a widget that will run speedtest-go when opened. Then, I can define a widget as +```json +{ + <... other widgets go here ...>, + "speedtest" : { + "icon": "gauge-high", + "label": "speed", + "blockdef": { + "meta": { + "view": "term", + "controller": "cmd", + "cmd": "speedtest-go --unix", + "cmd:clearonstart" + } + } + }, + <... other widgets go here ...> +} +``` +Using `"cmd"` for the `"controller"` is the simplest way to accomplish this. `"cmd:clearonstart"` isn't necessary, but it makes it so every time the command is run (which can be done by right clicking the header and selecting `Force Controller Restart`), the previous contents are cleared out. + +Now suppose I wanted to run a TUI app, for instance, `dua`. Well, it turns out that you can more or less do the same thing: +```json + <... other widgets go here ...>, + "dua" : { + "icon": "brands@linux", + "label": "dua", + "blockdef": { + "meta": { + "view": "term", + "controller": "cmd", + "cmd": "dua" + } + } + }, + <... other widgets go here ...> +``` +Because this is a TUI app that does not return anything when closed, the `"cmd:clearonstart"` option doesn't change the behavior, so it has been excluded. diff --git a/docs/faq.mdx b/docs/faq.mdx index 64b2aa6..59715d4 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 7 id: "faq" title: "FAQ" --- @@ -60,6 +60,3 @@ Just remember in JSON, backslashes need to be escaped. So add this to your [set ```json "term:localshellpath": "C:\\Program Files\\Git\\bin\\bash.exe" ``` - - - diff --git a/docs/index.mdx b/docs/index.mdx index 9af8e4c..052cfeb 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -22,6 +22,7 @@ References: * [Key Bindings](./keybindings) * [wsh command](./wsh) * [Connections](./connections) +* [Custom Widgets](./customwidgets) * [Telemetry](./telemetry) * [FAQ](./faq) diff --git a/docs/releasenotes.mdx b/docs/releasenotes.mdx index e1f2ec0..46099dc 100644 --- a/docs/releasenotes.mdx +++ b/docs/releasenotes.mdx @@ -1,7 +1,7 @@ --- id: "releasenotes" title: "Release Notes" -sidebar_position: 9 +sidebar_position: 8 --- # Release Notes From 8d46e43c3270b0da0fbd7a5cce81d7d55934b7ea Mon Sep 17 00:00:00 2001 From: sawka Date: Mon, 28 Oct 2024 21:23:03 -0700 Subject: [PATCH 2/2] update config paths --- docs/config.mdx | 5 +++-- docs/customwidgets.mdx | 3 ++- docs/faq.mdx | 4 ++-- sidebars.ts | 5 +++++ 4 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/config.mdx b/docs/config.mdx index 682b57b..cba3971 100644 --- a/docs/config.mdx +++ b/docs/config.mdx @@ -14,7 +14,8 @@ use ":" as level separators. :::info If you installed Wave pre-v0.9.0 your configuration file will be located at -`~/.waveterm/config/settings.json`. +`~/.waveterm/config/settings.json`. This includes all of the other configuration +files as well: `termthemes.json`, `presets.json`, and `widgets.json`. ::: @@ -82,7 +83,7 @@ For reference this is the current default configuration (v0.8.8): ### Terminal Theming -User-defined terminal themes are located in `~/.waveterm/config/termthemes.json`. This JSON file is structured as an object, with each sub-key defining a theme. +User-defined terminal themes are located in `~/.config/waveterm/termthemes.json`. This JSON file is structured as an object, with each sub-key defining a theme. Themes are applied by right-clicking on the terminal's header bar and selecting an entry from the "Themes" sub-menu. Alternatively they can be applied to the block's metadata key `term:theme`. This uses the JSON key value as the identifier. Note, for best consistency all colors should be of the format "#rrggbb" or "#rrggbbaa" (aa = alpha channel for transparency). diff --git a/docs/customwidgets.mdx b/docs/customwidgets.mdx index 284d7b5..22ae0ae 100644 --- a/docs/customwidgets.mdx +++ b/docs/customwidgets.mdx @@ -10,7 +10,8 @@ Wave allows users to create their own widgets to uniquely customize their experi # Terminal and CLI Widgets -A terminal widget, or CLI widget, is a widget that simply opens a terminal and runs a CLI command. These widgets are managed in the `~/.waveterm/config/widgets.json` file. +A terminal widget, or CLI widget, is a widget that simply opens a terminal and runs a CLI command. +These widgets are managed in the `~/.config/waveterm/widgets.json` file. ## Designing a Widget diff --git a/docs/faq.mdx b/docs/faq.mdx index 59715d4..60a516d 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -8,7 +8,7 @@ title: "FAQ" ### How do I set up my own LLM? -You must manually edit the [config file](./config) located at `~/.waveterm/config/settings.json`. +You must manually edit the [config file](./config) located at `~/.config/waveterm/settings.json`. | Key Name | Type | Function | |----------|------|----------| @@ -36,7 +36,7 @@ Here are the ollma open AI compatibility docs: https://github.com/ollama/ollama/ ### How can I connect to Azure AI -You must manually edit the [config file](./config) located at `~/.waveterm/config/settings.json`. +You must manually edit the [config file](./config) located at `~/.config/waveterm/settings.json`. You'll need to set your `ai:baseurl` to your Azure AI Base URL (do not include query parameters or `api-version`). You'll also need to set `ai:apitype` to `azure`. You can then set the `ai:model`, and `ai:apitoken` appropriately diff --git a/sidebars.ts b/sidebars.ts index d9202d5..929ac58 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -17,6 +17,11 @@ const sidebars: SidebarsConfig = { id: "config", label: "Configuration", }, + { + type: "doc", + id: "customwidgets", + label: "Custom Widgets", + }, { type: "doc", id: "telemetry",