Add docs for Placeholder.

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   the return value of `DOMQuery.remove`, which uses to return `self`.
   https://github.com/Textualize/textual/issues/1094
 - Added Pilot.wait_for_animation
+- Added widget `Placeholder`
 
 ### Changed
 

docs/api/placeholder.md

@@ -0,0 +1 @@
+::: textual.widgets.Placeholder

docs/examples/widgets/placeholder.css

@@ -0,0 +1,50 @@
+Placeholder {
+    height: 100%;
+}
+
+#top {
+    height: 50%;
+    width: 100%;
+    layout: grid;
+    grid-size: 2 2;
+}
+
+#left {
+    row-span: 2;
+}
+
+#bot {
+    height: 50%;
+    width: 100%;
+    layout: grid;
+    grid-size: 8 8;
+}
+
+#c1 {
+    row-span: 4;
+    column-span: 8;
+}
+
+#col1, #col2, #col3 {
+    width: 1fr;
+}
+
+#p1 {
+    row-span: 4;
+    column-span: 4;
+}
+
+#p2 {
+    row-span: 2;
+    column-span: 4;
+}
+
+#p3 {
+    row-span: 2;
+    column-span: 2;
+}
+
+#p4 {
+    row-span: 1;
+    column-span: 2;
+}

docs/examples/widgets/placeholder.py

@@ -0,0 +1,39 @@
+from textual.app import App, ComposeResult
+from textual.containers import Container, Horizontal, Vertical
+from textual.widgets import Placeholder
+
+
+class PlaceholderApp(App):
+
+    CSS_PATH = "placeholder.css"
+
+    def compose(self) -> ComposeResult:
+        yield Vertical(
+            Container(
+                Placeholder(label="This is a custom label for p1.", id="p1"),
+                Placeholder(label="Placeholder p2 here!", id="p2"),
+                Placeholder(id="p3"),
+                Placeholder(id="p4"),
+                Placeholder(id="p5"),
+                Placeholder(),
+                Horizontal(
+                    Placeholder("size", id="col1"),
+                    Placeholder("text", id="col2"),
+                    Placeholder("size", id="col3"),
+                    id="c1",
+                ),
+                id="bot"
+            ),
+            Container(
+                Placeholder("text", id="left"),
+                Placeholder("size", id="topright"),
+                Placeholder("text", id="botright"),
+                id="top",
+            ),
+            id="content",
+        )
+
+
+if __name__ == "__main__":
+    app = PlaceholderApp()
+    app.run()

docs/widgets/placeholder.md

@@ -0,0 +1,47 @@
+# Placeholder
+
+
+A widget that is meant to have no complex functionality.
+Use the placeholder widget when studying the layout of your app before having to develop your custom widgets.
+
+The placeholder widget has variants that display different bits of useful information.
+Clicking a placeholder will cycle through its variants.
+
+- [ ] Focusable
+- [ ] Container
+
+## Example
+
+The example below shows each placeholder variant.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/placeholder.py"}
+    ```
+
+=== "placeholder.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/placeholder.py"
+    ```
+
+=== "placeholder.css"
+
+    ```css
+    --8<-- "docs/examples/widgets/placeholder.css"
+    ```
+
+## Reactive Attributes
+
+| Name       | Type   | Default     | Description                                        |
+| ---------- | ------ | ----------- | -------------------------------------------------- |
+| `variant`  | `str`  | `"default"` | Styling variant. One of `default`, `size`, `text`. |
+
+
+## Messages
+
+This widget sends no messages.
+
+## See Also
+
+* [Placeholder](../api/placeholder.md) code reference

mkdocs.yml

@@ -96,6 +96,7 @@ nav:
       - "widgets/footer.md"
       - "widgets/header.md"
       - "widgets/input.md"
+      - "widgets/placeholder.md"
       - "widgets/static.md"
       - "widgets/tree_control.md"
   - API: