1.9 docs tweaks (#6935)

Fix code readability issues.
Support screenshot scale.
Bring back types and tweak screenshots.

docs/astro.config.mjs

@@ -83,10 +83,6 @@ export default defineConfig({
                                     label: "Syntax",
                                     slug: "guide/language/syntax",
                                 },
-                                {
-                                    label: "Types",
-                                    slug: "guide/language/types",
-                                },
                                 {
                                     label: "Positioning & Layouts",
                                     slug: "guide/language/positioning-and-layouts",
@@ -114,6 +110,8 @@ export default defineConfig({
                         {
                             label: "Basics",
                             items: [
+                                "reference/builtins/types",
+                                "reference/builtins/type-conversions",
                                 "reference/builtins/builtinfunctions",
                                 "reference/builtins/colors",
                                 "reference/builtins/math",

docs/ec.config.mjs

@@ -4,6 +4,43 @@ import { definePlugin } from "@expressive-code/core";
 import { h } from "@expressive-code/core/hast";
 import fs from "node:fs";
 
+function sideBorder() {
+    return definePlugin({
+        name: "Adds side border to slint code blocks",
+        baseStyles: `
+
+        .sideBar {
+            position: absolute;
+            top: calc(var(--button-spacing) - 4px);
+            bottom: 0;
+            left: 0;
+            width: 2px;
+            background: #2479f4;
+            border-top-left-radius: 1.4rem;
+            border-bottom-left-radius: 1.4rem;    
+        }
+        `,
+        hooks: {
+            postprocessRenderedBlock: async (context) => {
+                if (
+                    context.renderData.blockAst.children[1].properties
+                        .dataLanguage !== "slint"
+                ) {
+                    return;
+                }
+                const content = context.codeBlock.code;
+
+                const side = h("div.sideBar");
+
+                const ast = context.renderData.blockAst;
+                ast.children.push(side);
+
+                context.renderData.blockAst = ast;
+            },
+        },
+    });
+}
+
 function workersPlaygroundButton() {
     return definePlugin({
         name: "Adds 'Run in SlintPad' button to slint codeblocks",
@@ -75,9 +112,14 @@ function workersPlaygroundButton() {
 }
 
 export default {
-    plugins: [workersPlaygroundButton()],
+    plugins: [workersPlaygroundButton(), sideBorder()],
     themes: ["dark-plus", "light-plus"],
-    styleOverrides: { borderRadius: "0.2rem" },
+    styleOverrides: {
+        borderRadius: "0.4rem",
+        borderColor: "var(--slint-code-background)",
+        frames: { shadowColor: "transparent" },
+        codeBackground: "var(--slint-code-background)",
+    },
     shiki: {
         langs: [
             JSON.parse(

docs/src/components/CodeSnippetMD.astro

@@ -12,6 +12,7 @@ interface Props {
     imageHeight: number;
     needsBackground?: boolean;
     skip?: boolean;
+    scale?: number;
 }
 const { imagePath, imageAlt, skip, needsBackground } = Astro.props as Props;
 const images = import.meta.glob<{ default: ImageMetadata }>(

docs/src/content/docs/guide/language/basics.mdx

@@ -19,20 +19,21 @@ any type of UI.
 
 The first part covers the basic syntax
 
-```slint title="Basic syntax"
+```slint
 Text {
     text: "Hello World";
     color: blue;
 }
 ```
 
 Here we declared a `Text` element with a `text` property and a `color` property.
-<CodeSnippetMD imagePath="/src/assets/generated/basic-syntax.png"  imageWidth="100" imageHeight="100" imageAlt='Basic syntax'>
-```slint title="Basic syntax" playground
+<CodeSnippetMD imagePath="/src/assets/generated/basic-syntax.png" scale="2"  imageWidth="100" imageHeight="100" imageAlt='Basic syntax'>
+```slint playground
 import { Button } from "std-widgets.slint";
 
-component MyComponent {
+component MyComponent inherits Window {
     width: 100px; height: 100px;
+    background: transparent;
     Button {
         text: "Click me!";
     }
@@ -48,26 +49,46 @@ already understand the majority of how all components are built.
 
 The next part will cover how to layout elements and nest them. Which is as simple as:
 
-<CodeSnippetMD imagePath="/src/assets/generated/basic-layout.png" needsBackground="true"  imageWidth="200" imageHeight="200" imageAlt='Basic syntax'>
+<CodeSnippetMD skip="true"  imagePath="/src/assets/generated/basic-layout.png" scale="3"  imageWidth="100" imageHeight="100" imageAlt='Basic syntax'>
+```slint
+import { Button } from "std-widgets.slint";
+export component MyComponent inherits Window {
+    background: transparent;
+    VerticalLayout {
+        padding: 10px;
+        Text {
+            text: "Top";
+        }
+        Text {
+            text: "Middle";
+        }
+        Text {
+            text: "Bottom";
+        }
+    }
+}
+```
+</CodeSnippetMD>
+
+<CodeSnippetMD noScreenShot needsBackground="true" imagePath="/src/assets/generated/basic-layout.png" scale="3"  imageWidth="200" imageHeight="200" imageAlt='Basic syntax'>
 ```slint
 VerticalLayout {
     padding: 10px;
     Text {
-        text: "I'm in a column";
-        font-size: 24px;
+        text: "Top";
     }
-    Rectangle {
-        height: 100px;
-        background: blue;
+    Text {
+        text: "Middle";
     }
     Text {
-        text: "So am I";
-        font-size: 24px;
+        text: "Bottom";
     }
 }
 ```
 </CodeSnippetMD>
 
+
+
 The next part covers bindings.
 
 The next part covers states.
@@ -79,12 +100,13 @@ The next part covers animations.
 The next part covers the basics of the Slint language. It covers the basics of how to declare
 elements and components, how to declare identifiers and how to use them.
 
-```slint title="Basics"
+```slint
 component MyApp {
     Text {
         text: "Hello World";
         font-size: 24px;
     }
 }
+```
 
 The final part covers how the Slint UI and the business logic communicate with each other.

docs/src/content/docs/reference/builtins/colors.md → docs/src/content/docs/reference/builtins/colors.mdx

@@ -99,7 +99,7 @@ The transparency is obtained by multiplying the alpha channel by `(1 - factor)`.
 
 Returns a new color with the alpha value set to `alpha` (between 0 and 1)
 
-### to-hsv()->{hue: float, saturation: float, value: float, alpha: float}
+### to-hsv() -> \{ hue: float, saturation: float, value: float, alpha: float }
 
 Converts this color to the HSV color space and returns a struct with the `hue`, `saturation`, `value`,
 and `alpha` fields. `hue` is between 0 and 360 while `saturation`, `value`, and `alpha` are between 0 and 1.

docs/src/content/docs/reference/builtins/type-conversions.mdx

@@ -0,0 +1,44 @@
+---
+<!-- Copyright © SixtyFPS GmbH <[email protected]> ; SPDX-License-Identifier: MIT -->
+title: Type Conversions
+description: Type Conversions
+---
+
+Slint supports conversions between different types. Explicit
+conversions are required to make the UI description more robust, but implicit
+conversions are allowed between some types for convenience.
+
+The following conversions are possible:
+
+-   `int` can be converted implicitly to `float` and vice-versa.
+     When converting from `float` to `int`, the value is truncated.
+-   `int` and `float` can be converted implicitly to `string`
+-   `physical-length`, `relative-font-size`, and `length` can be converted implicitly to each other only in
+    context where the pixel ratio is known.
+-   the units type (`length`, `physical-length`, `duration`, ...) can't be converted to numbers (`float` or `int`)
+    but they can be divided by themselves to result in a number. Similarly, a number can be multiplied by one of
+    these unit. The idea is that one would multiply by `1px` or divide by `1px` to do such conversions
+-   The literal `0` can be converted to any of these types that have associated unit.
+-   Struct types convert with another struct type if they have the same property names and their types can be converted.
+    The source struct can have either missing properties, or extra properties. But not both.
+-   Arrays generally don't convert between each other. Array literals can be converted if the element types are convertible.
+-   String can be converted to float by using the `to-float` function. That function returns 0 if the string isn't
+    a valid number. You can check with `is-float()` if the string contains a valid number
+
+```slint
+export component Example {
+    // OK: int converts to string
+    property<{a: string, b: int}> prop1: {a: 12, b: 12 };
+    // OK: even if a is missing, it will just have the default value ("")
+    property<{a: string, b: int}> prop2: { b: 12 };
+    // OK: even if c is too many, it will be discarded
+    property<{a: string, b: int}> prop3: { a: "x", b: 12, c: 42 };
+    // ERROR: b is missing and c is extra, this doesn't compile, because it could be a typo.
+    // property<{a: string, b: int}> prop4: { a: "x", c: 42 };
+
+    property<string> xxx: "42.1";
+    property<float> xxx1: xxx.to-float(); // 42.1
+    property<bool> xxx2: xxx.is-float(); // true
+    property<int> xxx3: 45.8; // 45
+}
+```

docs/src/content/docs/guide/language/types.mdx → docs/src/content/docs/reference/builtins/types.mdx

@@ -166,46 +166,4 @@ export component Example {
     out property <int> list-len: list-of-int.length;
     out property <int> first-int: list-of-int[0];
 }
-
-```
-
-## Conversions
-
-Slint supports conversions between different types. Explicit
-conversions are required to make the UI description more robust, but implicit
-conversions are allowed between some types for convenience.
-
-The following conversions are possible:
-
--   `int` can be converted implicitly to `float` and vice-versa.
-     When converting from `float` to `int`, the value is truncated.
--   `int` and `float` can be converted implicitly to `string`
--   `physical-length`, `relative-font-size`, and `length` can be converted implicitly to each other only in
-    context where the pixel ratio is known.
--   the units type (`length`, `physical-length`, `duration`, ...) can't be converted to numbers (`float` or `int`)
-    but they can be divided by themselves to result in a number. Similarly, a number can be multiplied by one of
-    these unit. The idea is that one would multiply by `1px` or divide by `1px` to do such conversions
--   The literal `0` can be converted to any of these types that have associated unit.
--   Struct types convert with another struct type if they have the same property names and their types can be converted.
-    The source struct can have either missing properties, or extra properties. But not both.
--   Arrays generally don't convert between each other. Array literals can be converted if the element types are convertible.
--   String can be converted to float by using the `to-float` function. That function returns 0 if the string isn't
-    a valid number. You can check with `is-float()` if the string contains a valid number
-
-```slint
-export component Example {
-    // OK: int converts to string
-    property<{a: string, b: int}> prop1: {a: 12, b: 12 };
-    // OK: even if a is missing, it will just have the default value ("")
-    property<{a: string, b: int}> prop2: { b: 12 };
-    // OK: even if c is too many, it will be discarded
-    property<{a: string, b: int}> prop3: { a: "x", b: 12, c: 42 };
-    // ERROR: b is missing and c is extra, this doesn't compile, because it could be a typo.
-    // property<{a: string, b: int}> prop4: { a: "x", c: 42 };
-
-    property<string> xxx: "42.1";
-    property<float> xxx1: xxx.to-float(); // 42.1
-    property<bool> xxx2: xxx.is-float(); // true
-    property<int> xxx3: 45.8; // 45
-}
 ```

docs/src/content/docs/reference/elements/image.mdx

@@ -8,7 +8,7 @@ import SlintProperty  from '../../../../components/SlintProperty.astro';
 import CodeSnippetMD from '../../../../components/CodeSnippetMD.astro';
 
 <CodeSnippetMD imagePath="/src/assets/generated/image-example.png"  imageWidth="300" imageHeight="200"  imageAlt='image example'>
-```slint title="test-example.slint"
+```slint
 Image {
     source: @image-url("mini-banner.png");
 }
@@ -30,7 +30,7 @@ An `Image` can be used to represent an image loaded from a file. Supported image
 <SlintProperty propName="colorize" typeName="brush"> 
 When set, the image is used as an alpha mask and is drawn in the given color (or with the gradient).
 <CodeSnippetMD imagePath="/src/assets/generated/image-colorize.png"  imageWidth="300" imageHeight="200"  imageAlt='image example'>
-```slint title="test-example.slint"
+```slint
 Image {
     source: @image-url("mini-banner.png");
     colorize: gray;
@@ -229,7 +229,8 @@ export component Example inherits Window {
 }
 ```
 
-```slint title="nine-slice scaling"
+```slint
+// nine-slice scaling
 export component Example inherits Window {
     width: 100px;
     height: 150px;

docs/src/content/docs/reference/elements/text.mdx

@@ -9,7 +9,8 @@ import CodeSnippetMD from '../../../../components/CodeSnippetMD.astro';
 
 
 
-```slint title="test-example.slint" playground
+```slint playground
+// text-example.slint
 export component TextExample inherits Window {
     // Text colored red.
     Text {

docs/src/content/docs/reference/gestures/swipegestrurehandler.mdx

@@ -5,7 +5,7 @@ description: SwipeGestureHandler element api.
 ---
 import SlintProperty  from '../../../../components/SlintProperty.astro';
 
-```slint title="SwipeGestureHandler example" playground
+```slint playground
 export component Example inherits Window {
     width: 270px;
     height: 100px;

docs/src/content/docs/reference/std-widgets/aboutslint.mdx

@@ -6,7 +6,7 @@ description: AboutSlint api.
 
 import CodeSnippetMD from "../../../../../src/components/CodeSnippetMD.astro";
 
-<CodeSnippetMD imagePath="/src/assets/generated/std-widgets-aboutslint.png" imageWidth="200" imageHeight="200" imageAlt='Aboud Slint component'>
+<CodeSnippetMD imagePath="/src/assets/generated/std-widgets-aboutslint.png" scale="3" imageWidth="200" imageHeight="200" imageAlt='Aboud Slint component'>
 ```slint playground
 import { AboutSlint } from "std-widgets.slint";
 export component Example inherits Window {

docs/src/content/docs/reference/std-widgets/combobox.mdx

@@ -7,13 +7,16 @@ description: ComboBox api.
 import SlintProperty  from '../../../../components/SlintProperty.astro';
 import CodeSnippetMD from '../../../../components/CodeSnippetMD.astro';
 
-<CodeSnippetMD imagePath="/src/assets/generated/std-widget-combobox-example.png"  imageWidth="200" imageHeight="200"  imageAlt='combobox example'>
+<CodeSnippetMD imagePath="/src/assets/generated/std-widget-combobox-example.png" scale="3" imageWidth="110" imageHeight="35"  imageAlt='combobox example'>
 ```slint
 import { ComboBox } from "std-widgets.slint";
 export component Example inherits Window {
-    width: 200px;
-    height: 130px;
+    width: 100px;
+    height: 100px;
+    background: transparent;
     ComboBox {
+        x: 5px; y: 5px;
+        width: 100px;
         model: ["first", "second", "third"];
         current-value: "first";
     }

docs/src/content/docs/reference/window/dialog.mdx

@@ -8,7 +8,7 @@ import CodeSnippetMD from '../../../../components/CodeSnippetMD.astro';
 
 <CodeSnippetMD imagePath="/src/assets/generated/dialog-example.png"  imageWidth="200" imageHeight="100"  imageAlt='dialog example'>
 
-```slint title="dialog-example.slint" playground
+```slint playground
 import { StandardButton, Button } from "std-widgets.slint";
 export component Example inherits Dialog {
     Text {

docs/src/styles/custom.css

@@ -55,10 +55,12 @@
     --sl-hue-blue: 222;
     --sl-text-h3: var(--sl-text-2xl);
     --sl-content-width: 50rem;
-    --sl-color-gray-6: #1b1c21;
+    --sl-color-bg: #1b1b1f;
+    --sl-color-gray-6: #161618;
     --sl-color-hairline: #212329;
     --sl-color-hairline-shade: var(--sl-color-hairline);
     --badge-border-color: --sl-color-hairline;
+    --slint-code-background: #151517;
 
     .screenshot-container {
         background-color: #cdcdcd;
@@ -73,8 +75,10 @@
 :root[data-theme="light"] {
     --sl-text-h3: var(--sl-text-2xl);
     --sl-content-width: 50rem;
+    --sl-color-bg: #ffffff;
     --badge-border-color: lightgrey;
     --sl-color-hairline: #edeef3;
+    --slint-code-background: #f6f6f7;
 
     .screenshot-container {
         background-color: whitesmoke;