Initial commit

skills/textual-builder/references/layout.md

@@ -0,0 +1,298 @@
+# Layout and Positioning
+
+## Layout Types
+
+### Vertical (Default)
+
+Stacks widgets vertically:
+
+```css
+Container {
+    layout: vertical;
+}
+```
+
+### Horizontal
+
+Arranges widgets side-by-side:
+
+```css
+Container {
+    layout: horizontal;
+}
+```
+
+### Grid
+
+Grid layout with rows and columns:
+
+```css
+Grid {
+    layout: grid;
+    grid-size: 3 2;  /* 3 columns, 2 rows */
+    grid-gutter: 1 2;  /* vertical horizontal spacing */
+}
+```
+
+#### Grid Cell Spanning
+
+Make widgets span multiple cells:
+
+```css
+#header {
+    column-span: 3;  /* Span 3 columns */
+}
+
+#sidebar {
+    row-span: 2;     /* Span 2 rows */
+}
+```
+
+#### Grid Rows and Columns
+
+Define row heights and column widths:
+
+```css
+Grid {
+    grid-size: 2 3;
+    grid-rows: 1fr 6 25%;     /* Flexible, fixed 6, 25% */
+    grid-columns: 1fr 2fr;    /* 1:2 ratio */
+}
+```
+
+## Alignment
+
+### Screen/Container Alignment
+
+Center content within screen:
+
+```css
+Screen {
+    align: center middle;  /* horizontal vertical */
+}
+```
+
+Options: `left`, `center`, `right` × `top`, `middle`, `bottom`
+
+### Content Alignment
+
+Align content within a widget:
+
+```css
+MyWidget {
+    content-align: center middle;
+    text-align: center;
+}
+```
+
+## Docking
+
+Pin widgets to screen edges:
+
+```css
+#header {
+    dock: top;
+    height: 3;
+}
+
+#sidebar {
+    dock: left;
+    width: 20;
+}
+
+#footer {
+    dock: bottom;
+}
+```
+
+Docking order matters - earlier docked widgets take priority.
+
+## Sizing
+
+### Fixed Sizes
+
+```css
+Widget {
+    width: 50;      /* 50 cells */
+    height: 10;     /* 10 rows */
+}
+```
+
+### Relative Sizes
+
+```css
+Widget {
+    width: 50%;     /* 50% of parent */
+    height: 100%;
+}
+```
+
+### Fractional Units
+
+Share available space proportionally:
+
+```css
+#left {
+    width: 1fr;     /* Gets 1 part */
+}
+
+#right {
+    width: 2fr;     /* Gets 2 parts (twice as wide) */
+}
+```
+
+### Auto Sizing
+
+Fit content:
+
+```css
+Widget {
+    width: auto;
+    height: auto;
+}
+```
+
+### Min/Max Constraints
+
+```css
+Widget {
+    min-width: 20;
+    max-width: 80;
+    min-height: 5;
+    max-height: 30;
+}
+```
+
+## Spacing
+
+### Margin
+
+Space outside widget border:
+
+```css
+Widget {
+    margin: 1;          /* All sides */
+    margin: 1 2;        /* vertical horizontal */
+    margin: 1 2 3 4;    /* top right bottom left */
+}
+```
+
+### Padding
+
+Space inside widget border:
+
+```css
+Widget {
+    padding: 1;         /* All sides */
+    padding: 1 2;       /* vertical horizontal */
+}
+```
+
+## Visibility
+
+### Display
+
+Show or hide widgets:
+
+```css
+#hidden {
+    display: none;
+}
+
+#visible {
+    display: block;
+}
+```
+
+Toggle in Python:
+
+```python
+widget.display = False  # Hide
+widget.display = True   # Show
+```
+
+### Visibility
+
+Similar to display but reserves space:
+
+```css
+Widget {
+    visibility: hidden;  /* Hidden but takes space */
+    visibility: visible;
+}
+```
+
+## Layers
+
+Control stacking order:
+
+```css
+#background {
+    layer: below;
+}
+
+#popup {
+    layer: above;
+}
+```
+
+## Scrolling
+
+### Enable Scrolling
+
+```css
+Container {
+    overflow-x: auto;  /* Horizontal scrolling */
+    overflow-y: auto;  /* Vertical scrolling */
+    overflow: auto auto;  /* Both */
+}
+```
+
+### Programmatic Scrolling
+
+```python
+# Scroll to specific position
+container.scroll_to(x=0, y=100)
+
+# Scroll widget into view
+widget.scroll_visible()
+
+# Scroll to end
+self.screen.scroll_end(animate=True)
+```
+
+## Example: Card Game Layout
+
+```css
+Screen {
+    layout: vertical;
+}
+
+#opponent-hand {
+    dock: top;
+    height: 12;
+    layout: horizontal;
+    align: center top;
+}
+
+#play-area {
+    height: 1fr;
+    layout: grid;
+    grid-size: 5 3;
+    align: center middle;
+}
+
+#player-hand {
+    dock: bottom;
+    height: 15;
+    layout: horizontal;
+    align: center bottom;
+    padding: 1;
+}
+
+.card {
+    width: 12;
+    height: 10;
+    margin: 0 1;
+}
+```