0
# Advanced Tables
1

2
Tables with colspan and rowspan support using standard Markdown table syntax with cell-spanning notation. This Markdown extension provides enhanced table functionality, allowing cells to span multiple columns and rows while maintaining compatibility with standard Markdown table syntax.
3

4
## Capabilities
5

6
### Extension Configuration
7

8
Configure the advanced tables extension for enhanced table processing.
9

10
```python { .api }
11
class SpanTableExtension(Extension):
12
    """
13
    Markdown extension for tables with colspan and rowspan support.
14
    """
15
    def extendMarkdown(self, md):
16
        """
17
        Registers the span table processor with the Markdown parser.
18
        
19
        Parameters:
20
        - md: Markdown parser instance
21
        """
22

23
def make_extension(*args, **kwargs):
24
    """
25
    Factory function for creating SpanTableExtension instances.
26
    
27
    Returns:
28
    SpanTableExtension: Configured extension instance
29
    """
30
```
31

32
### Table Processing
33

34
The extension processes `::spantable::` blocks to create advanced tables.
35

36
```python { .api }
37
class SpanTableProcessor(BlockProcessor):
38
    """
39
    Block processor for span tables with advanced cell spanning.
40
    """
41
    START_RE: Pattern  # Compiled regex for ::spantable::
42
    END_RE: Pattern    # Compiled regex for ::end-spantable::
43
    
44
    def test(self, parent, block):
45
        """
46
        Tests if block contains span table syntax.
47
        
48
        Parameters:
49
        - parent: Parent XML element
50
        - block: Markdown block to test
51
        
52
        Returns:
53
        bool: True if block matches span table pattern
54
        """
55
    
56
    def run(self, parent, blocks):
57
        """
58
        Processes span table blocks and generates HTML.
59
        
60
        Parameters:
61
        - parent: Parent XML element
62
        - blocks: List of Markdown blocks
63
        """
64
    
65
    def find_closing_fragment_index(self, blocks) -> int:
66
        """
67
        Finds the index of the closing ::end-spantable:: tag.
68
        
69
        Parameters:
70
        - blocks: List of Markdown blocks
71
        
72
        Returns:
73
        int: Index of closing tag, -1 if not found
74
        """
75
    
76
    def read_first_table(self, blocks) -> Optional[SpanTable]:
77
        """
78
        Extracts the first table from the given blocks.
79
        
80
        Parameters:
81
        - blocks: List of Markdown blocks
82
        
83
        Returns:
84
        Optional[SpanTable]: Parsed table or None
85
        """
86
```
87

88
## Data Models
89

90
### Table Data Structures
91

92
```python { .api }
93
class Cell:
94
    """
95
    Represents a table cell with spanning capabilities.
96
    
97
    Attributes:
98
    - text: Cell text content
99
    - skip: Whether to skip rendering (used for spanned cells)
100
    - col_span: Number of columns to span
101
    - row_span: Number of rows to span
102
    - col_span_defined: Whether colspan was explicitly set
103
    - row_span_defined: Whether rowspan was explicitly set
104
    - props: Additional HTML properties
105
    """
106
    text: str
107
    skip: bool
108
    col_span: int
109
    row_span: int
110
    col_span_defined: bool
111
    row_span_defined: bool
112
    props: Optional[Dict[str, str]]
113
    
114
    @property
115
    def html_class(self) -> str:
116
        """
117
        Returns CSS class string for the cell.
118
        
119
        Returns:
120
        str: Space-separated CSS class names
121
        """
122

123
class SpanTable(Table):
124
    """
125
    Table with colspan and rowspan support.
126
    
127
    Attributes:
128
    - matrix: Table matrix structure with Cell objects
129
    """
130
    matrix: Matrix
131

132
class Matrix:
133
    """
134
    Represents table structure as a matrix of cells.
135
    
136
    Attributes:
137
    - rows: Tuple of row lists containing Cell objects
138
    """
139
    rows: Tuple[List[Any], ...]
140
    
141
    def __setitem__(self, key, value): ...
142
    def __getitem__(self, key): ...
143
    def __iter__(self): ...
144

145
class Table:
146
    """
147
    Base table class with headers and records.
148
    
149
    Attributes:
150
    - headers: Table column headers
151
    - records: Table data records
152
    """
153
    headers: Tuple[str, ...]
154
    records: Tuple[Tuple[str, ...], ...]
155
    
156
    def items(self): ...
157
    def __iter__(self): ...
158
    def __len__(self): ...
159
    def __getitem__(self, index): ...
160
```
161

162
### Table Parsing
163

164
```python { .api }
165
def read_table(markdown: str, cls=Table):
166
    """
167
    Parses Markdown table syntax into Table objects.
168
    
169
    Parameters:
170
    - markdown: Markdown table content
171
    - cls: Table class to instantiate (default: Table)
172
    
173
    Returns:
174
    Table instance or None if no valid table found
175
    """
176
```
177

178
## Usage Examples
179

180
### Basic Span Table
181

182
Use `::spantable::` blocks with standard Markdown table syntax:
183

184
```markdown
185
::spantable::
186
| Name    | Age | Location     |
187
|---------|-----|--------------|
188
| John    | 25  | New York     |
189
| Jane    | 30  | Los Angeles  |
190
| Bob     | 35  | Chicago      |
191
::end-spantable::
192
```
193

194
### Tables with Column Spanning
195

196
Use `||` to span cells across columns:
197

198
```markdown
199
::spantable::
200
| Product | Q1 | Q2 | Q3 | Q4 |
201
|---------|----|----|----|----|
202
| A       | 10 | 20 | 15 | 25 |
203
| B       | 30 | Total: 90 ||
204
| C       | 40 | 35 | 30 | 20 |
205
::end-spantable::
206
```
207

208
### Tables with Row Spanning
209

210
Use row spanning notation for cells that span multiple rows:
211

212
```markdown
213
::spantable::
214
| Category | Item      | Price |
215
|----------|-----------|-------|
216
| Food ^   | Apple     | $1.00 |
217
|          | Banana    | $0.50 |
218
|          | Orange    | $0.75 |
219
| Drinks ^ | Water     | $1.50 |
220
|          | Soda      | $2.00 |
221
::end-spantable::
222
```
223

224
### Complex Table with Both Spanning Types
225

226
```markdown
227
::spantable:: caption="Sales Report" class="sales-table"
228
| Region  | Q1    | Q2    | Q3    | Q4    | Total |
229
|---------|-------|-------|-------|-------|-------|
230
| North ^ | Jan   | 100   | 150   | 200   | 450   |
231
|         | Feb   | 110   | 160   | 210   |       |
232
|         | Mar   | 120   | 170   | 220   |       |
233
| South   | 300   | Summary ||||| 800   |
234
| West    | 250   | 280   | 290   | 300   | 1120  |
235
| Total   | 1050  | Grand Total |||||| 2370  |
236
::end-spantable::
237
```
238

239
### Table with Custom Properties
240

241
```markdown
242
::spantable:: class="data-table" caption="Quarterly Results"
243
| Metric      | Value    | Change |
244
|-------------|----------|--------|
245
| Revenue     | $1.2M    | +15%   |
246
| Profit      | $300K    | +22%   |
247
| Growth Rate | Combined ||       |
248
::end-spantable::
249
```
250

251
### Table with Cell Classes
252

253
Cells can have individual CSS classes:
254

255
```markdown
256
::spantable::
257
| Status  | Count | Percentage |
258
|---------|-------|------------|
259
| Active  | 150   | 75%        |
260
| Pending | 30    | 15%        |
261
| Error   | 20    | 10%        |
262
::end-spantable::
263
```
264

265
## Cell Spanning Syntax
266

267
### Column Spanning
268

269
- Single empty cell: `|` - Normal cell boundary
270
- Column span: `||` - Cell spans to the next column
271
- Multiple column span: `|||` - Cell spans multiple columns
272

273
### Row Spanning
274

275
- Row span marker: `^` - Indicates the cell above spans down
276
- Cell content with row span: Cell content followed by `^`
277

278
### Combining Spans
279

280
```markdown
281
::spantable::
282
| A  | B spanning 2 cols || D |
283
| E^ | F                 | G | H |
284
|    | I                 | J | K |
285
::end-spantable::
286
```
287

288
This creates:
289
- Cell A spans 2 rows
290
- Cell B spans 2 columns
291
- Cell F is a regular cell
292
- Proper alignment maintained
293

294
## Table Properties
295

296
### Supported Properties
297

298
```markdown
299
::spantable:: caption="Table Title" class="custom-class" id="table-id"
300
```
301

302
Available properties:
303
- `caption`: Table caption text
304
- `class`: Additional CSS classes
305
- `id`: HTML ID attribute
306

307
### Generated HTML Structure
308

309
```html
310
<div class="span-table-wrapper">
311
  <table class="span-table custom-class" id="table-id">
312
    <caption>Table Title</caption>
313
    <tr>
314
      <td colspan="2">Spanning Cell</td>
315
      <td rowspan="2">Row Spanning Cell</td>
316
    </tr>
317
    <tr>
318
      <td>Regular Cell</td>
319
      <td>Another Cell</td>
320
    </tr>
321
  </table>
322
</div>
323
```
324

325
## Styling and Customization
326

327
### Default CSS Classes
328

329
- `.span-table-wrapper`: Container wrapper
330
- `.span-table`: Table element
331
- Custom classes can be added via the `class` property
332

333
### Cell Alignment
334

335
Standard Markdown alignment syntax is supported:
336

337
```markdown
338
::spantable::
339
| Left | Center | Right |
340
|:-----|:------:|------:|
341
| A    | B      | C     |
342
::end-spantable::
343
```
344

345
### Responsive Tables
346

347
The wrapper div allows for responsive table styling:
348

349
```css
350
.span-table-wrapper {
351
  overflow-x: auto;
352
}
353

354
.span-table {
355
  min-width: 100%;
356
  border-collapse: collapse;
357
}
358
```