From 98e5df90cb2620583591cf29e9b05e169bd8f928 Mon Sep 17 00:00:00 2001 From: Nigel Breslaw Date: Thu, 28 Nov 2024 00:00:32 +0200 Subject: [PATCH] 1.9 docs tweaks (#6935) Fix code readability issues. Support screenshot scale. Bring back types and tweak screenshots. --- docs/astro.config.mjs | 6 +-- docs/ec.config.mjs | 46 +++++++++++++++++- docs/src/components/CodeSnippetMD.astro | 1 + .../content/docs/guide/language/basics.mdx | 48 ++++++++++++++----- ...iltinfunctions.md => builtinfunctions.mdx} | 0 .../builtins/{colors.md => colors.mdx} | 2 +- .../reference/builtins/{key.md => key.mdx} | 0 .../reference/builtins/{math.md => math.mdx} | 0 .../reference/builtins/type-conversions.mdx | 44 +++++++++++++++++ .../language => reference/builtins}/types.mdx | 42 ---------------- .../content/docs/reference/elements/image.mdx | 7 +-- .../content/docs/reference/elements/text.mdx | 3 +- .../gestures/swipegestrurehandler.mdx | 2 +- .../docs/reference/std-widgets/aboutslint.mdx | 2 +- .../docs/reference/std-widgets/combobox.mdx | 9 ++-- .../content/docs/reference/window/dialog.mdx | 2 +- docs/src/styles/custom.css | 6 ++- 17 files changed, 147 insertions(+), 73 deletions(-) rename docs/src/content/docs/reference/builtins/{builtinfunctions.md => builtinfunctions.mdx} (100%) rename docs/src/content/docs/reference/builtins/{colors.md => colors.mdx} (98%) rename docs/src/content/docs/reference/builtins/{key.md => key.mdx} (100%) rename docs/src/content/docs/reference/builtins/{math.md => math.mdx} (100%) create mode 100644 docs/src/content/docs/reference/builtins/type-conversions.mdx rename docs/src/content/docs/{guide/language => reference/builtins}/types.mdx (79%) diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index b0c1cbcd8d2..bb22727d046 100644 --- a/docs/astro.config.mjs +++ b/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", diff --git a/docs/ec.config.mjs b/docs/ec.config.mjs index bb265eb2c14..744b1b4dcfd 100644 --- a/docs/ec.config.mjs +++ b/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( diff --git a/docs/src/components/CodeSnippetMD.astro b/docs/src/components/CodeSnippetMD.astro index 3e1912b3b1e..8b1ce4916ba 100644 --- a/docs/src/components/CodeSnippetMD.astro +++ b/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 }>( diff --git a/docs/src/content/docs/guide/language/basics.mdx b/docs/src/content/docs/guide/language/basics.mdx index 8d6d666ed36..15da7dd9eb0 100644 --- a/docs/src/content/docs/guide/language/basics.mdx +++ b/docs/src/content/docs/guide/language/basics.mdx @@ -19,7 +19,7 @@ any type of UI. The first part covers the basic syntax -```slint title="Basic syntax" +```slint Text { text: "Hello World"; color: blue; @@ -27,12 +27,13 @@ Text { ``` Here we declared a `Text` element with a `text` property and a `color` property. - -```slint title="Basic syntax" playground + +```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: - + +```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"; + } + } +} +``` + + + ```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"; } } ``` + + 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. diff --git a/docs/src/content/docs/reference/builtins/builtinfunctions.md b/docs/src/content/docs/reference/builtins/builtinfunctions.mdx similarity index 100% rename from docs/src/content/docs/reference/builtins/builtinfunctions.md rename to docs/src/content/docs/reference/builtins/builtinfunctions.mdx diff --git a/docs/src/content/docs/reference/builtins/colors.md b/docs/src/content/docs/reference/builtins/colors.mdx similarity index 98% rename from docs/src/content/docs/reference/builtins/colors.md rename to docs/src/content/docs/reference/builtins/colors.mdx index dde1fe21429..b99b9240b35 100644 --- a/docs/src/content/docs/reference/builtins/colors.md +++ b/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. diff --git a/docs/src/content/docs/reference/builtins/key.md b/docs/src/content/docs/reference/builtins/key.mdx similarity index 100% rename from docs/src/content/docs/reference/builtins/key.md rename to docs/src/content/docs/reference/builtins/key.mdx diff --git a/docs/src/content/docs/reference/builtins/math.md b/docs/src/content/docs/reference/builtins/math.mdx similarity index 100% rename from docs/src/content/docs/reference/builtins/math.md rename to docs/src/content/docs/reference/builtins/math.mdx diff --git a/docs/src/content/docs/reference/builtins/type-conversions.mdx b/docs/src/content/docs/reference/builtins/type-conversions.mdx new file mode 100644 index 00000000000..f7fea65a278 --- /dev/null +++ b/docs/src/content/docs/reference/builtins/type-conversions.mdx @@ -0,0 +1,44 @@ +--- + +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 xxx: "42.1"; + property xxx1: xxx.to-float(); // 42.1 + property xxx2: xxx.is-float(); // true + property xxx3: 45.8; // 45 +} +``` diff --git a/docs/src/content/docs/guide/language/types.mdx b/docs/src/content/docs/reference/builtins/types.mdx similarity index 79% rename from docs/src/content/docs/guide/language/types.mdx rename to docs/src/content/docs/reference/builtins/types.mdx index bdd53e164dd..33ccdc2047b 100644 --- a/docs/src/content/docs/guide/language/types.mdx +++ b/docs/src/content/docs/reference/builtins/types.mdx @@ -166,46 +166,4 @@ export component Example { out property list-len: list-of-int.length; out property 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 xxx: "42.1"; - property xxx1: xxx.to-float(); // 42.1 - property xxx2: xxx.is-float(); // true - property xxx3: 45.8; // 45 -} ``` diff --git a/docs/src/content/docs/reference/elements/image.mdx b/docs/src/content/docs/reference/elements/image.mdx index 53b37eaaefa..321c60bee7b 100644 --- a/docs/src/content/docs/reference/elements/image.mdx +++ b/docs/src/content/docs/reference/elements/image.mdx @@ -8,7 +8,7 @@ import SlintProperty from '../../../../components/SlintProperty.astro'; import CodeSnippetMD from '../../../../components/CodeSnippetMD.astro'; -```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 When set, the image is used as an alpha mask and is drawn in the given color (or with the gradient). -```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; diff --git a/docs/src/content/docs/reference/elements/text.mdx b/docs/src/content/docs/reference/elements/text.mdx index f4a173f0b5a..0f2734cdc35 100644 --- a/docs/src/content/docs/reference/elements/text.mdx +++ b/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 { diff --git a/docs/src/content/docs/reference/gestures/swipegestrurehandler.mdx b/docs/src/content/docs/reference/gestures/swipegestrurehandler.mdx index 4c2e66d501a..ddbab9380a3 100644 --- a/docs/src/content/docs/reference/gestures/swipegestrurehandler.mdx +++ b/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; diff --git a/docs/src/content/docs/reference/std-widgets/aboutslint.mdx b/docs/src/content/docs/reference/std-widgets/aboutslint.mdx index f50e28c3d56..6a53eb03cb2 100644 --- a/docs/src/content/docs/reference/std-widgets/aboutslint.mdx +++ b/docs/src/content/docs/reference/std-widgets/aboutslint.mdx @@ -6,7 +6,7 @@ description: AboutSlint api. import CodeSnippetMD from "../../../../../src/components/CodeSnippetMD.astro"; - + ```slint playground import { AboutSlint } from "std-widgets.slint"; export component Example inherits Window { diff --git a/docs/src/content/docs/reference/std-widgets/combobox.mdx b/docs/src/content/docs/reference/std-widgets/combobox.mdx index 7b8d93ca8cc..18cbf83354f 100644 --- a/docs/src/content/docs/reference/std-widgets/combobox.mdx +++ b/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'; - + ```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"; } diff --git a/docs/src/content/docs/reference/window/dialog.mdx b/docs/src/content/docs/reference/window/dialog.mdx index 3de6fde98da..d493269f0d6 100644 --- a/docs/src/content/docs/reference/window/dialog.mdx +++ b/docs/src/content/docs/reference/window/dialog.mdx @@ -8,7 +8,7 @@ import CodeSnippetMD from '../../../../components/CodeSnippetMD.astro'; -```slint title="dialog-example.slint" playground +```slint playground import { StandardButton, Button } from "std-widgets.slint"; export component Example inherits Dialog { Text { diff --git a/docs/src/styles/custom.css b/docs/src/styles/custom.css index 46580dd6fdf..fb4d4b9e2bb 100644 --- a/docs/src/styles/custom.css +++ b/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;