# Tables Showcase

Comprehensive table demo spanning Word (.docx), Excel (.xlsx), and PowerPoint (.pptx). Three output files are generated by a single script. This document covers the Word portion in detail.

- **tables.sh** — builds all three files with `officecli` (483 lines).
- **tables.docx** — Word output: 7 tables covering vertical merge, horizontal merge, color heatmap, border/layout/direction/cell-formatting, hmerge, RTL, and inline `data` shorthand.
- **tables.xlsx** — Excel output: 3 sheets with sales data, employee performance formulas, and cross-sheet summary.
- **tables.pptx** — PowerPoint output: 3 slides including a raw-XML data table.
- **tables.md** — this file.

## Regenerate

```bash
cd examples/word
bash tables.sh
# → tables.docx  tables.xlsx  tables.pptx
```

## Table 1: Project Progress Tracker (Vertical Merge)

A 7-row × 6-column table with `vmerge=restart`/`continue` to span project rows, shaded header, and color-coded progress cells.

```bash
# Create blank table
officecli add tables.docx /body --type table --prop rows=7 --prop cols=6

# Header row — blue shading, white bold text, center-aligned
officecli set tables.docx '/body/tbl[1]/tr[1]/tc[1]' \
  --prop text="Project Name" --prop bold=true \
  --prop shd=4472C4 --prop color=FFFFFF --prop valign=center
# ... repeat for tc[2]–tc[6] ...

# Project A rows — restart merge on first row, continue on next two
officecli set tables.docx '/body/tbl[1]/tr[2]/tc[1]' \
  --prop text="Smart Office System" \
  --prop vmerge=restart --prop valign=center --prop shd=D9E2F3
officecli set tables.docx '/body/tbl[1]/tr[3]/tc[1]' \
  --prop text="" --prop vmerge=continue --prop shd=D9E2F3
officecli set tables.docx '/body/tbl[1]/tr[4]/tc[1]' \
  --prop text="" --prop vmerge=continue --prop shd=D9E2F3

# Color-coded progress — green/amber/red
officecli set tables.docx '/body/tbl[1]/tr[2]/tc[6]' \
  --prop text="100%" --prop color=00B050
officecli set tables.docx '/body/tbl[1]/tr[3]/tc[6]' \
  --prop text="75%" --prop color=FFC000
officecli set tables.docx '/body/tbl[1]/tr[4]/tc[6]' \
  --prop text="0%" --prop color=FF0000
```

**Features:** `vmerge` (restart/continue — vertical cell merge across rows), `valign` (top/center/bottom), `shd` (hex cell background), `bold`, `color` (text color), `text`

## Table 2: Financial Statement (Gridspan + Vertical Merge)

An 8-row × 5-column table with a two-row header using `gridspan=2` (horizontal merge) and `vmerge` on the outer columns, plus right-aligned numeric data with color highlights.

```bash
officecli add tables.docx /body --type table --prop rows=8 --prop cols=5

# Two-column header span: gridspan=2 removes the merged cell;
# original tc[5] becomes tc[4] after the merge
officecli set tables.docx '/body/tbl[2]/tr[1]/tc[3]' \
  --prop text="Amount (10K USD)" \
  --prop bold=true --prop shd=2E75B6 --prop color=FFFFFF \
  --prop gridspan=2 --prop align=center

# Row 2 sub-headers (Budget / Actual)
officecli set tables.docx '/body/tbl[2]/tr[2]/tc[3]' \
  --prop text="Budget" --prop bold=true --prop shd=5B9BD5 \
  --prop color=FFFFFF --prop align=center
officecli set tables.docx '/body/tbl[2]/tr[2]/tc[4]' \
  --prop text="Actual" --prop bold=true --prop shd=5B9BD5 \
  --prop color=FFFFFF --prop align=center

# Data rows: right-align numeric cells, color-code vs. budget
officecli set tables.docx '/body/tbl[2]/tr[3]/tc[3]' \
  --prop text="500.00" --prop align=right
officecli set tables.docx '/body/tbl[2]/tr[3]/tc[4]' \
  --prop text="523.50" --prop align=right --prop color=00B050
```

**Features:** `gridspan` (integer ≥ 2; collapses that many cells into one — handler removes the absorbed `tc` elements automatically), `align` (left/center/right on cell paragraph), `vmerge` (restart/continue combined with gridspan for multi-level headers)

## Table 3: Skill Assessment Matrix (Color Heatmap)

A 6-row × 7-column color-coded matrix. Each cell uses `shd` for the fill and `color=FFFFFF` for white text, producing a traffic-light heatmap.

```bash
officecli add tables.docx /body --type table --prop rows=6 --prop cols=7

# Header row — dark navy
officecli set tables.docx '/body/tbl[3]/tr[1]/tc[1]' \
  --prop text="Name/Skill" --prop bold=true \
  --prop shd=002060 --prop color=FFFFFF --prop align=center

# Data cells: Expert=00B050, Proficient=92D050, Familiar=FFC000, Beginner=FF0000
officecli set tables.docx '/body/tbl[3]/tr[2]/tc[2]' \
  --prop text="Expert" --prop shd=00B050 --prop color=FFFFFF \
  --prop align=center --prop bold=true
officecli set tables.docx '/body/tbl[3]/tr[2]/tc[3]' \
  --prop text="Proficient" --prop shd=92D050 --prop color=FFFFFF \
  --prop align=center --prop bold=true
# ... and so on for each cell ...
```

**Features:** `shd` (cell fill for heatmap coloring), `bold` + `color=FFFFFF` (white text on colored backgrounds), `align=center`

## Table 4: Property Coverage (Border / Layout / Direction / Cell Formatting)

A table created with `border.all`, `colWidths`, `cellSpacing`, `indent`, `layout`, and `padding`, then each border side is overridden individually. Row and cell properties exercise the full tc property surface.

```bash
# Create table with all table-level props
officecli add tables.docx /body --type table \
  --prop rows=3 --prop cols=4 \
  --prop "border.all=single;8;2E74B5" \
  --prop "colWidths=2500,2500,2500,2500" \
  --prop "cellSpacing=20" \
  --prop "indent=200" \
  --prop "layout=fixed" \
  --prop "padding=80"

# Override individual border sides after creation
officecli set tables.docx '/body/tbl[4]' --prop "border.top=double;8;1F3864"
officecli set tables.docx '/body/tbl[4]' --prop "border.bottom=double;8;1F3864"
officecli set tables.docx '/body/tbl[4]' --prop "border.left=double;8;1F3864"
officecli set tables.docx '/body/tbl[4]' --prop "border.right=double;8;1F3864"
officecli set tables.docx '/body/tbl[4]' --prop "border.horizontal=single;4;9DC3E6"
officecli set tables.docx '/body/tbl[4]' --prop "border.vertical=single;4;9DC3E6"

# Row-level props: header repeat + exact height
officecli set tables.docx '/body/tbl[4]/tr[1]' \
  --prop header=true --prop height.exact=400
officecli set tables.docx '/body/tbl[4]/tr[1]/tc[1]' \
  --prop text="Cell Borders" --prop bold=true \
  --prop fill=2E74B5 --prop color=FFFFFF

# Cell with diagonal borders
officecli set tables.docx '/body/tbl[4]/tr[2]/tc[1]' \
  --prop text="border.all + tl2br + tr2bl" \
  --prop "border.all=single;8;FF0000" \
  --prop "border.tl2br=single;4;0000FF" \
  --prop "border.tr2bl=single;4;0000FF"

# Cell with run formatting
officecli set tables.docx '/body/tbl[4]/tr[2]/tc[2]' \
  --prop text="font + italic + strike + underline + highlight" \
  --prop "font=Times New Roman" \
  --prop italic=true --prop strike=true \
  --prop underline=single --prop highlight=yellow

# Cell with direction + textDirection + nowrap
officecli set tables.docx '/body/tbl[4]/tr[2]/tc[3]' \
  --prop text="direction=rtl + nowrap + textDirection=btlr" \
  --prop direction=rtl --prop nowrap=true --prop textDirection=btlr

# Cell with per-side padding
officecli set tables.docx '/body/tbl[4]/tr[2]/tc[4]' \
  --prop text="padding per side + skipGridSync" \
  --prop padding.top=50 --prop padding.bottom=150 \
  --prop padding.left=80 --prop padding.right=80

# Per-side cell borders
officecli set tables.docx '/body/tbl[4]/tr[3]/tc[1]' \
  --prop text="border.top + border.bottom" \
  --prop "border.top=single;8;FF0000" \
  --prop "border.bottom=single;8;0000FF"
officecli set tables.docx '/body/tbl[4]/tr[3]/tc[2]' \
  --prop text="border.left + border.right" \
  --prop "border.left=single;8;00FF00" \
  --prop "border.right=single;8;FF00FF"

# fitText + skipGridSync
officecli set tables.docx '/body/tbl[4]/tr[3]/tc[3]' \
  --prop text="fitText squeezes text to cell width" --prop fitText=true
officecli set tables.docx '/body/tbl[4]/tr[3]/tc[4]' \
  --prop text="width + skipGridSync" \
  --prop width=2500 --prop skipGridSync=true
```

**Features:** `border.all` (style;size;color shorthand for all 6 edges), `border.top/bottom/left/right` (outer edges), `border.horizontal/vertical` (inside dividers), `border.tl2br` (diagonal top-left to bottom-right), `border.tr2bl` (diagonal top-right to bottom-left), `colWidths` (comma-separated column widths in twips), `cellSpacing` (inter-cell gap in twips), `indent` (table left offset in twips), `layout` (fixed/autofit), `padding` (default cell padding all sides), `header` (true = repeat row as header on every page), `height.exact` (exact row height in twips), `fill` (cell background; alias for `shd`), `font`, `italic`, `strike`, `underline`, `highlight`, `direction` (rtl on cell → `w:bidi`), `nowrap`, `textDirection` (lrtb/btlr/tbrl/lrbt/tblrV/btlrV), `padding.top/bottom/left/right`, `fitText`, `width`, `skipGridSync`

## Table 5: Horizontal Merge (hmerge)

A small 2-row × 3-column table demonstrating `hmerge=restart`. Setting `hmerge=restart` on a cell inserts a `gridspan` and removes the absorbed `tc` — set other cells in the same row before applying the merge.

```bash
officecli add tables.docx /body --type table \
  --prop rows=2 --prop cols=3 \
  --prop "border.all=single;4;808080"

# Set the non-merged cell first (it will become tc[2] after merge)
officecli set tables.docx '/body/tbl[5]/tr[1]/tc[3]' --prop text="normal tc"

# Apply horizontal merge — tc[2] is absorbed; original tc[3] becomes tc[2]
officecli set tables.docx '/body/tbl[5]/tr[1]/tc[1]' \
  --prop text="hmerge restart (spans 2 cols)" \
  --prop hmerge=restart

officecli set tables.docx '/body/tbl[5]/tr[2]/tc[1]' --prop text="row 2 col 1"
officecli set tables.docx '/body/tbl[5]/tr[2]/tc[2]' --prop text="row 2 col 2"
officecli set tables.docx '/body/tbl[5]/tr[2]/tc[3]' --prop text="row 2 col 3"
```

**Features:** `hmerge` (restart — legacy horizontal merge: inserts `gridspan`, removes absorbed cell; handler re-indexes subsequent cells automatically)

> Set cells in the row that will remain **after** the merge before setting `hmerge=restart`, because the merge removes the absorbed `tc` and subsequent tc indices shift.

## Table 6: RTL Table Direction

A 2-row × 2-column table with `direction=rtl` on the table itself, which mirrors the column order (`w:bidiVisual`).

```bash
officecli add tables.docx /body --type table \
  --prop rows=2 --prop cols=2 \
  --prop "direction=rtl" \
  --prop "border.all=single;8;C00000"
officecli set tables.docx '/body/tbl[6]/tr[1]/tc[1]' \
  --prop text="RTL table" --prop bold=true
officecli set tables.docx '/body/tbl[6]/tr[1]/tc[2]' \
  --prop text="column order mirrored"
```

**Features:** `direction=rtl` on table (writes `w:bidiVisual` — mirrors column order for right-to-left reading direction)

## Table 7: Inline Data Shorthand (`data`)

Build an entire grid in one property: rows separated by `;`, cells by `,` — no
`rows`/`cols`/per-cell `set` needed.

```bash
officecli add tables.docx /body --type table \
  --prop "data=Region,Q1,Q2;North,120,150;South,90,110" \
  --prop "border.all=single;4;808080"
```

**Features:** `data` (inline grid shorthand — `;`-separated rows of `,`-separated cells; sizes the table automatically)

## Complete Feature Coverage

| Feature | Table |
|---------|-------|
| **Vertical merge:** `vmerge=restart/continue` | 1, 2 |
| **Horizontal merge:** `gridspan`, `hmerge=restart` | 2, 5 |
| **Cell background:** `shd`, `fill` | 1, 2, 3, 4 |
| **Text color & bold:** `color`, `bold` | 1, 2, 3, 4 |
| **Cell alignment:** `align`, `valign` | 1, 2, 3 |
| **Table borders:** `border.all`, `border.top/bottom/left/right`, `border.horizontal/vertical` | 4 |
| **Cell borders:** `border.all`, `border.top/bottom/left/right`, `border.tl2br`, `border.tr2bl` | 4 |
| **Table layout:** `layout`, `colWidths`, `cellSpacing`, `indent`, `padding` | 4 |
| **Row props:** `header`, `height.exact` | 4 |
| **Cell run formatting:** `font`, `italic`, `strike`, `underline`, `highlight` | 4 |
| **Cell text direction:** `direction=rtl` (cell), `textDirection`, `nowrap` | 4 |
| **Per-side padding:** `padding.top/bottom/left/right` | 4 |
| **Cell width:** `width`, `skipGridSync`, `fitText` | 4 |
| **Table RTL:** `direction=rtl` (table) | 6 |
| **Inline data shorthand:** `data` | 7 |

## Inspect the Generated File

```bash
# List all tables in the document
officecli query tables.docx table

# Inspect a specific table's structure
officecli get tables.docx '/body/tbl[1]'

# Inspect a cell's properties
officecli get tables.docx '/body/tbl[1]/tr[2]/tc[1]'

# List all rows in a table
officecli query tables.docx '/body/tbl[4]' row
```