Document styles (#785)

* Add docs for CSS variables

* Add ref docs for various styles, fix some typos in places

docs/guide/layout.md

@@ -518,6 +518,8 @@ However, in this case, both `#box1` and `#box2` are assigned to layers.
 From the `layers: below above;` declaration inside `layers.css`, we can see that the layer named `above` is on top of the `below` layer.
 Since `#box1` is on the higher layer, it is drawn on top of `#box2`.
 
+[//]: # (NOTE: the example below also appears in the layers and layer style reference)
+
 === "Output"
 
     ```{.textual path="docs/examples/guide/layout/layers.py"}

docs/styles/color.md

@@ -5,7 +5,7 @@ The `color` rule sets the text color of a Widget.
 ## Syntax
 
 ```
-color: <COLOR> [<PERCENTAGE>];
+color: <COLOR> | auto [<PERCENTAGE>];
 ```
 
 ## Example
@@ -40,6 +40,9 @@ color: red 20%;
 
 /* RGB color */
 color: rgb(100,120,200);
+
+/* Automatically choose color with suitable contrast for readability */
+color: auto;
 ```
 
 ## Python

docs/styles/dock.md

@@ -0,0 +1,45 @@
+# Dock
+
+The `dock` property is used to fix a widget to the edge of a container (which may be the entire terminal window).
+
+## Syntax
+
+```
+dock: top|right|bottom|left;
+```
+
+## Example
+
+The example below shows a `left` docked sidebar.
+Notice that even though the content is scrolled, the sidebar remains fixed.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/guide/layout/dock_layout1_sidebar.py" press="pagedown,down,down,_,_,_,_,_"}
+    ```
+
+=== "dock_layout1_sidebar.py"
+
+    ```python
+    --8<-- "docs/examples/guide/layout/dock_layout1_sidebar.py"
+    ```
+
+=== "dock_layout1_sidebar.css"
+
+    ```sass hl_lines="2"
+    --8<-- "docs/examples/guide/layout/dock_layout1_sidebar.css"
+    ```
+
+## CSS
+
+```sass
+/* Dock the widget on the left edge of its parent container */
+dock: left;
+```
+
+## Python
+
+```python
+# Dock the widget on the left edge of its parent container
+widget.styles.dock = "left"
+```

docs/styles/grid.md

@@ -0,0 +1,27 @@
+# Grid properties
+
+There are a number of properties relating to the Textual `grid` layout.
+
+For an in-depth look at the grid layout, visit the grid [guide](../guide/layout.md#grid).
+
+| Property       | Description                                    |
+|----------------|------------------------------------------------|
+| `grid-size`    | Number of columns and rows in the grid layout. |
+| `grid-rows`    | Height of grid rows.                           |
+| `grid-columns` | Width of grid columns.                         |
+| `grid-gutter`  | Spacing between grid cells.                    |
+| `row-span`     | Number of rows a cell spans.                   |
+| `column-span`  | Number of columns a cell spans.                |
+
+## Syntax
+
+```sass
+grid-size: <INTEGER> [<INTEGER>];  /* columns first, then rows */
+grid-rows: <SCALAR> ...;
+grid-columns: <SCALAR> ...;
+grid-gutter: <SCALAR>;
+row-span: <INTEGER>;
+column-span: <INTEGER>;
+```
+
+## Example

docs/styles/layer.md

@@ -0,0 +1,50 @@
+# Layer
+
+The `layer` property is used to assign widgets to a layer.
+The value of the `layer` property must be the name of a layer defined using a `layers` declaration.
+Layers control the order in which widgets are painted on screen.
+More information on layers can be found in the [guide](../guide/layout.md#layers).
+
+## Syntax
+
+```
+layer: <STRING>;
+```
+
+## Example
+
+In the example below, `#box1` is yielded before `#box2`.
+However, since `#box1` is on the higher layer, it is drawn on top of `#box2`.
+
+[//]: # (NOTE: the example below also appears in the guide and 'layers.md'.)
+
+=== "Output"
+
+    ```{.textual path="docs/examples/guide/layout/layers.py"}
+    ```
+
+=== "layers.py"
+
+    ```python
+    --8<-- "docs/examples/guide/layout/layers.py"
+    ```
+
+=== "layers.css"
+
+    ```sass hl_lines="3 15 19"
+    --8<-- "docs/examples/guide/layout/layers.css"
+    ```
+
+## CSS
+
+```sass
+/* Draw the widget on the layer called 'below' */
+layer: below;
+```
+
+## Python
+
+```python
+# Draw the widget on the layer called 'below'
+widget.layer = "below"
+```

docs/styles/layers.md

@@ -0,0 +1,50 @@
+# Layers
+
+The `layers` property allows you to define an ordered set of layers.
+These `layers` can later be referenced using the `layer` property.
+Layers control the order in which widgets are painted on screen.
+More information on layers can be found in the [guide](../guide/layout.md#layers).
+
+## Syntax
+
+```
+layers: <STRING> ...;
+```
+
+## Example
+
+In the example below, `#box1` is yielded before `#box2`.
+However, since `#box1` is on the higher layer, it is drawn on top of `#box2`.
+
+[//]: # (NOTE: the example below also appears in the guide and 'layer.md'.)
+
+=== "Output"
+
+    ```{.textual path="docs/examples/guide/layout/layers.py"}
+    ```
+
+=== "layers.py"
+
+    ```python
+    --8<-- "docs/examples/guide/layout/layers.py"
+    ```
+
+=== "layers.css"
+
+    ```sass hl_lines="3 15 19"
+    --8<-- "docs/examples/guide/layout/layers.css"
+    ```
+
+## CSS
+
+```sass
+/* Bottom layer is called 'below', layer above it is called 'above' */
+layers: below above;
+```
+
+## Python
+
+```python
+# Bottom layer is called 'below', layer above it is called 'above'
+widget.layers = ("below", "above")
+```

docs/styles/max_height.md

@@ -22,10 +22,10 @@ max-height: 25vh;
 ## Python
 
 ```python
-# Set the maximum width to 10 rows
+# Set the maximum height to 10 rows
 widget.styles.max_height = 10
 
-# Set the maximum width to 25% of the screen width
-widget.styles.max_height = "25vw"
+# Set the maximum height to 25% of the screen height
+widget.styles.max_height = "25vh"
 
 ```

docs/styles/max_width.md

@@ -16,7 +16,7 @@ max-width: <SCALAR>;
 max-width: 10;
 
 /* Set a maximum width of 25% of the screen width */
-max-width: 25vh;
+max-width: 25vw;
 ```
 
 ## Python
@@ -27,5 +27,4 @@ widget.styles.max_width = 10
 
 # Set the maximum width to 25% of the screen width
 widget.styles.max_width = "25vw"
-
 ```

docs/styles/min_width.md

@@ -16,7 +16,7 @@ min-width: <SCALAR>;
 min-width: 10;
 
 /* Set a minimum width of 25% of the screen width */
-min-width: 25vh;
+min-width: 25vw;
 ```
 
 ## Python
@@ -25,7 +25,6 @@ min-width: 25vh;
 # Set the minimum width to 10 cells
 widget.styles.min_width = 10
 
-# Set the minimum width to 25% of the screen height
-widget.styles.min_width = "25vh"
-
+# Set the minimum width to 25% of the screen width
+widget.styles.min_width = "25vw"
 ```

mkdocs.yml

@@ -57,7 +57,11 @@ nav:
     - "styles/color.md"
     - "styles/content_align.md"
     - "styles/display.md"
+    - "styles/dock.md"
+    - "styles/grid.md"
     - "styles/height.md"
+    - "styles/layer.md"
+    - "styles/layers.md"
     - "styles/layout.md"
     - "styles/margin.md"
     - "styles/max_height.md"