| 1 | # Table Visualization Templates |
| 2 | |
| 3 | This directory contains six canonical cell-grid references. A table belongs |
| 4 | here only when a row header and column header jointly address each body fact; |
| 5 | headers, cells, rectangular merges, alignment, and boundaries preserve that |
| 6 | intersection model. Numeric values inside cells do not by themselves turn the |
| 7 | grid into a chart. |
| 8 | |
| 9 | Value-driven mark geometry belongs in [`charts/`](../charts/). Qualitative page |
| 10 | topology is built as a page-specific Structure by Executor. Reusable PowerPoint |
| 11 | Master/Layout systems belong in [`layouts/`](../layouts/). |
| 12 | |
| 13 | ## Source of truth |
| 14 | |
| 15 | [`tables_index.json`](./tables_index.json) is the machine registry. Its |
| 16 | `tables` object maps each canonical key to one diagnostic-recall `summary`; |
| 17 | keys match `<key>.svg`, and `meta.total` matches the canonical SVG roster. |
| 18 | [`table-vocabulary.md`](./table-vocabulary.md) projects the same six keys as |
| 19 | objective planning-side information relationships without execution details or |
| 20 | selection conclusions. |
| 21 | |
| 22 | Default Strategist and Quick read the complete Table vocabulary together with |
| 23 | the Chart vocabulary before planning. They compare every objective |
| 24 | relationship, then use |
| 25 | [`visualization_recall.py`](../../scripts/visualization_recall.py) `validate` |
| 26 | to resolve selected canonical references. Its `recall` mode remains an optional |
| 27 | diagnostic helper over the machine registry, not the runtime capability gate. |
| 28 | Default writes |
| 29 | `table/<key>` to `page_visualizations`; Quick keeps the selected reference in |
| 30 | active context. |
| 31 | |
| 32 | ## Authoring contract |
| 33 | |
| 34 | [`VISUALIZATION_TEMPLATE_AUTHORING.md`](../VISUALIZATION_TEMPLATE_AUTHORING.md) |
| 35 | owns the shared standalone-SVG, neutral-preview, root-boundary, Shape-first, |
| 36 | family, and catalog rules. Table-specific requirements are: |
| 37 | |
| 38 | - Preserve the complete row/column topology, headers, values, units, ordering, |
| 39 | merges, alignment, totals, status, and source notes. |
| 40 | - Default output remains independently editable DrawingML shapes. |
| 41 | - Add native Table replacement metadata to every supported pure text grid; it |
| 42 | is native-ready by default. The fallback and metadata contain the same cells. |
| 43 | - Keep graphical cells such as rating dots, icons, status marks, avatars, or |
| 44 | embedded bars on the Shape fallback route unless the active native-data |
| 45 | contract explicitly supports them. |
| 46 | |
| 47 | | Canonical key | Grid contract | |
| 48 | |---|---| |
| 49 | | `record_table` | One flat record per row and one stable heterogeneous field per column | |
| 50 | | `metric_table` | Operating metrics by entity with current values, changes, statuses, or target progress inside cells | |
| 51 | | `comparison_matrix` | Criteria × alternatives with exact, prose, or heterogeneous facts at intersections | |
| 52 | | `feature_matrix` | Capabilities × offerings with supported, unsupported, partial, or exception states | |
| 53 | | `rating_matrix` | Criteria × alternatives using one repeated ordinal scale | |
| 54 | | `hierarchical_table` | Grouped or indented rows with detail and subtotal/total hierarchy | |
| 55 | |
| 56 | **Hard rule — physical table is not semantic Table**: A PowerPoint table used |
| 57 | as a drawing grid does not enter this family automatically. Exact dates or |
| 58 | durations that drive horizontal task positions and lengths belong to |
| 59 | `chart/gantt_chart`; qualitative stage/lane placement belongs to |
| 60 | a page-specific Structure. |
| 61 | |
| 62 | Selecting a table reference does not itself select native output. Design Spec |
| 63 | §IX/Quick names independent objects separately and decides |
| 64 | `<object-key>=yes|no`; explicit `--native-charts-and-tables` export is a second |
| 65 | opt-in. |
| 66 |