feat(docs): add decorations

Author: Curve

astro.config.ts

@@ -3,6 +3,7 @@ import { defineConfig } from "astro/config";
 import react from "@astrojs/react";
 import starlight from "@astrojs/starlight";
 
+import starlightImageZoom from "starlight-image-zoom";
 import starlightAutoSidebar from "starlight-auto-sidebar";
 import starlightThemeRapide from "starlight-theme-rapide";
 
@@ -22,13 +23,15 @@ export default defineConfig({
             },
             sidebar: [
                 { label: "Getting Started", autogenerate: { directory: "/getting-started/" } },
+                { label: "Window", autogenerate: { directory: "/window/" } },
                 { label: "Webview", autogenerate: { directory: "/webview/" } },
             ],
             components: {
                 Hero: "./src/components/Hero.astro",
                 SiteTitle: "./src/components/Title.astro",
             },
             plugins: [
+                starlightImageZoom(),
                 starlightAutoSidebar(),
                 starlightThemeRapide(),
             ],

package.json

@@ -21,6 +21,7 @@
     "react-dom": "^19.1.1",
     "sharp": "^0.34.2",
     "starlight-auto-sidebar": "^0.1.2",
+    "starlight-image-zoom": "^0.13.0",
     "starlight-theme-rapide": "^0.5.1"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -0,0 +1,66 @@
+---
+title: Decorations
+---
+
+import { Icon } from "@astrojs/starlight/components";
+
+> This page documents how window decorations work
+
+Window Decorations are commonly defined as the non-client area parts of a window, so things like the Titlebar and Resize-Borders.
+Saucer offers an API to change Window Decorations to allow for custom titlebars, which you might've seen in other apps such as e.g. Spotify or Discord.
+
+```cpp title="Example: Changing Window Decorations"
+window->set_decorations(saucer::window::decoration::partial);
+```
+
+There are three decoration-types to choose from (`none`, `partial`, `full`). Each of them behave differently.
+Their differences are listed in the table below:
+
+| Decoration | Titlebar                                   | Resizable                                  | Aero-Snap[^1]                              | Window Shadows                             | Note                                     |
+| ---------- | ------------------------------------------ | ------------------------------------------ | ------------------------------------------ | ------------------------------------------ | ---------------------------------------- |
+| `none`     | <Icon name="close" color="red"/>           | <Icon name="close" color="red"/>           | <Icon name="close" color="red"/>           | <Icon name="close" color="red"/>           | Prefer `partial` decorations if possible |
+| `partial`  | <Icon name="close" color="red"/>           | <Icon name="approve-check" color="green"/> | <Icon name="approve-check" color="green"/> | <Icon name="approve-check" color="green"/> | -                                        |
+| `full`     | <Icon name="approve-check" color="green"/> | <Icon name="approve-check" color="green"/> | <Icon name="approve-check" color="green"/> | <Icon name="approve-check" color="green"/> | The default window decorations           |
+
+[^1]: Refers to Window-Snapping, e.g. when dragging the window to the top of the screen, the operating system will usually prompt to maximize the window.
+
+## Gallery
+
+|    `decoration::none`     |    `decoration::partial`     |    `decoration::full`     |
+| :-----------------------: | :--------------------------: | :-----------------------: |
+| ![](/src/assets/none.png) | ![](/src/assets/partial.png) | ![](/src/assets/full.png) |
+
+## Webview Support
+
+When the webview `attributes` (`saucer::webview::options{.attributes = true}`) setting is enabled (_the default_), you can use the following `data`-attributes to more easily implement a custom titlebar:
+
+- `data-webview-close`
+
+  > When an element with this attribute is clicked, the window is closed
+
+- `data-webview-minimize`
+
+  > When an element with this attribute is clicked, the window is minimized
+
+- `data-webview-maximize`
+
+  > When an element with this attribute is clicked, the window is maximized or restored, depending on its current state
+
+- `data-webview-drag`
+
+  > When an element with this attribute is held, the window will follow the mouse cursor
+
+- `data-webview-resize="<edge>"`
+
+  > When an element with this attribute is held, the window will start resizing.  
+  > `<edge>` should be one (or a combination[^2]) of the following
+  >
+  > - `t` ≈ "top" window border
+  > - `b` ≈ "bottom" window border
+  > - `l` ≈ "left" window border
+  > - `r` ≈ "right" window border
+
+- `data-webview-ignore`
+  > Add this to elements that trigger any kind of unwanted operation. This can happen when the parent of such an element has a `data-webview` attribute
+
+[^2]: e.g. `data-webview-resize="tr"` to start resizing from the top right border.