Artstr-Studio/docs/CHART_IMPORT_FEATURE.md

Artstr Studio PPTX Chart Import

Native rendering of OOXML charts into Artstr layers

Status

Spec draft, not yet implemented. Follows on from docs/PPTX_IMPORT_FEATURE.md, which currently lands every chart as a single placeholder image layer (the UNSUPPORTED_CHART_PLACEHOLDER path in §11.4 of that spec). This document scopes a phased replacement that turns a real OOXML chart into a set of native Artstr layers — shape layers for bars / wedges / segments, text layers for axis labels / titles / legends.

---

1. Why this is its own arc

A chart in a PPTX package is its own sub-document:

ppt/slides/slide10.xml          ← references the graphic frame
ppt/slides/_rels/slide10.xml.rels
ppt/charts/chart1.xml           ← chart XML (this spec)
ppt/charts/_rels/chart1.xml.rels
ppt/embeddings/*.xlsx           ← the underlying spreadsheet (cached)

The chart XML has its own ~30 element vocabulary (c:chartSpace, c:barChart, c:pieChart, c:ser, c:cat, c:val, c:dLbls, c:catAx, c:valAx, …) and its own internal coordinate system (0–1 plot-area relative). Folding all of that into pptx-importer.js alongside the slide-walker would balloon the file; the chart converter gets its own helpers and is gated by the existing convertGraphicFrame dispatch.

---

2. Scope

In scope for the first cut (Phase 1)

• Bar / column charts (c:barChart with c:barDir val="col" or val="bar"). Single or multiple series. Clustered grouping only.
• Read category labels from c:cat/c:multiLvlStrRef/c:multiLvlStrCache or c:cat/c:strRef/c:strCache. Read numeric values from c:val/c:numRef/c:numCache. Ignore the spreadsheet reference path — the cache is always present in OOXML output.
• Per-series fill colour from c:ser/c:spPr/a:solidFill/a:srgbClr, falling back to a small built-in palette when missing (matches the default Office theme order: accent1..6).
• Compute the plot area inside the chart's bounding box (the p:graphicFrame/p:xfrm) using a fixed inset for axis labels. Phase 6 of PPTX_IMPORT_FEATURE.md can refine this with the chart's own c:layout/c:manualLayout later.
• Emit each bar as a rect shape layer with the series fill.
• Emit category axis labels (Q1, Q2, …) as text layers below the plot area.
• Skip value-axis tick labels, title, legend, data labels, gridlines in Phase 1 — they all land in Phase 4 polish.

Phase 2

• Pie / doughnut charts (c:pieChart, c:doughnutChart). Each slice becomes a shape layer. The slice geometry is a wedge that Artstr doesn't natively support as a preset; rendered as a kind: 'path' shape with an SVG arc-path d-attribute. Doughnut draws an inner-radius hole via even-odd fill rule on the path.

Phase 3

• Line charts (c:lineChart). Each data point is a vertex; the series renders as a sequence of line shape layers between adjacent points (or one kind: 'path' polyline). Markers (c:marker) emit small circle/rect shape layers at each point.

Phase 4 — polish

• Chart title (c:title/c:tx/c:rich/a:p/a:r).
• Legend (c:legend) — series name + colour swatch as paired text-layer + shape-layer.
• Data labels (c:dLbls) — value or category text above / inside each bar / wedge based on c:showVal / c:showCatName / c:showPercent.
• Value-axis tick labels with auto-rounding to a nice step (5, 10, 20, 50, 100).
• Gridlines (c:majorGridlines / c:minorGridlines) — thin shape layers at each tick.

Phase 5

• Stacked + percent-stacked variants of bar / column / line (c:grouping val="stacked" / "percentStacked").
• Stacked rendering is sum-aware: bar heights are the running sum per category and the per-series rect is the delta segment.

Out of scope (kept as placeholder images)

• Scatter (c:scatterChart), bubble (c:bubbleChart), area (c:areaChart), radar (c:radarChart), surface (c:surface3DChart), stock (c:stockChart).
• All 3D variants (c:bar3DChart, c:line3DChart, c:pie3DChart).
• Combo charts (c:plotArea containing multiple different chart types).
• Trendlines (c:trendline), error bars (c:errBars).
• Conditional formatting / per-point overrides (c:dPt).

Anything in this list keeps the current UNSUPPORTED_CHART_PLACEHOLDER behavior from §11.4 of the PPTX spec.

---

3. Target architecture

convertGraphicFrame(gfNode, ctx)
  uri === '…/chart'
  ├─ resolve r:id to ppt/charts/chartN.xml
  ├─ parseXml(chartText)
  ├─ chartImport.convertChart(chartDoc, gfBounds, ctx)
  │    ├─ read plot area bounds from gfBounds (with insets)
  │    ├─ dispatch on chart type:
  │    │    barChart  → buildBarChartLayers(plotArea, chartDoc, ctx)
  │    │    pieChart  → buildPieChartLayers(...)
  │    │    lineChart → buildLineChartLayers(...)
  │    │    else      → null (fall through to placeholder)
  │    └─ return Artstr layer array (or null)
  └─ if null: emit the existing placeholder image as before.

New file: src/pptx-importer-charts.js — exports window.ArtstrPptxImporter.charts with the per-chart-type builders. Lazy-loaded inside the existing pptx-importer.js flow on first chart encountered; not a separate user-facing button.

Update pptx-importer.js:

• convertGraphicFrame first parses the chart XML and tries the native builder. If it returns layers, emit them in place of the placeholder. If it returns null (unsupported type), keep the current placeholder behaviour + warning.
• Add chartRels to ctx (same shape as slideRels) to resolve the chart-XML relationship from the slide rels file.

---

4. Coordinate system inside a chart

PPTX charts use a 0–1 relative coord system inside their bounding box. The chart's bounding box on the slide is the p:graphicFrame/p:xfrm/a:off + a:ext, which we already convert to Artstr inches in convertGraphicFrame via readXfrm.

For Phase 1 we use a fixed inset model:

plotArea = {
  x: chartBounds.x + chartBounds.w * 0.05,
  y: chartBounds.y + chartBounds.h * 0.05,
  w: chartBounds.w * 0.90,
  h: chartBounds.h * 0.80,   // leaves 15% for category labels below
};

Phase 4 will read c:plotArea/c:layout/c:manualLayout when present to get the chart's actual plot-area placement.

---

5. Bar / column chart layout

Given a clustered column chart with N categories × S series, plot area pa = { x, y, w, h }, and series values data[s][c]:

maxV = max over all data
catW = pa.w / N
gap  = catW * 0.15            // ~15% gap between category groups
barW = (catW - gap) / S       // S bars per category

for c in 0..N-1:
  for s in 0..S-1:
    h_bar = pa.h * data[s][c] / maxV
    x_bar = pa.x + c * catW + gap/2 + s * barW
    y_bar = pa.y + pa.h - h_bar
    emit rect layer (x_bar, y_bar, barW, h_bar) filled with series colour

Bar charts (c:barDir val="bar") swap axes: categories on Y, value extending in X. The same math applies with x/y swapped.

For "clustered" grouping only in Phase 1 — stacked and percentStacked are Phase 5.

---

6. Pie chart layout (Phase 2)

Given a pie chart with K slices summing to T, plot area pa:

cx = pa.x + pa.w / 2
cy = pa.y + pa.h / 2
r  = min(pa.w, pa.h) / 2 * 0.9   // 90% of half-min, leaves margin

angle = 0
for k in 0..K-1:
  sweep = 2π * values[k] / T
  d = sliceArcPath(cx, cy, r, angle, angle + sweep)
  emit shape layer:
    kind: 'path'
    d: d
    viewBox: { x: 0, y: 0, w: 100, h: 100*pa.h/pa.w }
    fill: slice colour
  angle += sweep

sliceArcPath builds an SVG <path d="..."> with M, L, arc commands. Doughnut adds an inner-radius arc subtracted via even-odd fill rule.

---

7. Series colour resolution

PPTX charts pick series colours in this order:

1. Explicit c:ser/c:spPr/a:solidFill/a:srgbClr (most decks).
2. Explicit c:ser/c:spPr/a:solidFill/a:schemeClr — resolves via the slide's theme (the existing convertColor(node, theme) helper handles this).
3. The theme's chart-style colour rotation (accent1, accent2, …) when neither is specified — falls back to a built-in palette matching the Office default.

The user's gallery_template_layout_set.pptx chart uses option 1 (explicit #5E735D, #B05A44), so Phase 1 should resolve to the exact colours seen in PowerPoint.

---

8. Layer naming

So users can find chart pieces in the layer panel:

Chart placeholder: Chart 1                          ← (current; replaced)
Chart 1 / Plot background
Chart 1 / Bar [Q1, Baseline]                        ← series s, category c
Chart 1 / Bar [Q1, Target]
…
Chart 1 / Bar [Q4, Target]
Chart 1 / Category label: Q1
…
Chart 1 / Category label: Q4

Chart 1 matches the source c:cNvPr@name (or Chart placeholder: <name>). Square brackets contain the category + series for bars / line points, the slice name for pie wedges.

---

9. Report integration

Reuse the existing report counters:

• report.imported.shapes += <num shapes emitted from chart>
• report.imported.text += <num text layers from chart>
• report.placeholders.charts stays as the unsupported-fallback counter. Successfully-imported native charts don't bump this.

New warning codes:

• CHART_TYPE_UNSUPPORTED — chart type not yet handled (scatter, 3D, combo, etc.), falling back to placeholder.
• CHART_AXIS_LABELS_SKIPPED_PHASE1 — value-axis ticks deferred to Phase 4.
• CHART_GRIDLINES_SKIPPED_PHASE1 — same.

---

10. Test plan

Build synthetic charts in-browser via fflate.zipSync (the same pattern as the existing /tmp/test_pptx_*.js harnesses):

1. 2-series, 4-category clustered column chart, explicit srgbClr per series. Mirrors the user's test deck (slide 10). Expected: 8 rect shape layers + 4 category-label text layers.
2. Single-series, 6-category column chart with very different values (1, 10, 100, 1000, …) to test axis-scale math.
3. Empty / missing strCache — chart that references a spreadsheet but has no cached data. Expected: fall through to placeholder + CHART_TYPE_UNSUPPORTED warning.
4. 3-slice pie chart (Phase 2 milestone).
5. 2-series line chart (Phase 3 milestone).
6. Scatter chart — expected: placeholder + warning, no crash.

Real-deck regression: gallery_template_layout_set.pptx slide 10's chart should now appear with 8 bars (green + terracotta clustered across Q1–Q4) and 4 category labels instead of the postimg placeholder.

---

11. Implementation plan

Phase 1 — bar / column

• Create src/pptx-importer-charts.js.
• Implement convertChart(chartDoc, chartBounds, ctx) dispatch.
• Implement buildBarChartLayers.
• Read series / categories / values from cache.
• Wire into convertGraphicFrame so chart URIs try the native builder first.
• Synthetic test 1 + real-deck slide 10 must pass.

Phase 2 — pie / doughnut

• Add buildPieChartLayers.
• Add sliceArcPath helper.
• Synthetic test 4 must pass.

Phase 3 — line

• Add buildLineChartLayers.
• Markers if c:marker/c:symbol is set and != none.
• Synthetic test 5 must pass.

Phase 4 — polish

• Title, legend, data labels, value-axis ticks, gridlines.

Phase 5 — stacked variants

• Stacked + percent-stacked column / bar / line.

---

12. Open questions

• Group layers. Artstr doesn't expose a "layer group" primitive today (PPTX groups are flattened by walkSpTree per Phase 5 of PPTX_IMPORT_FEATURE.md). For now chart sub-layers will be individual editable layers with the Chart N / … naming convention. If Artstr later adds groups, the importer can opt-in.
• Editing after import. A user might want to "change a value" on an imported chart. Today that means moving a bar manually. True data-bound editing would require keeping the source values in a hidden layer-level field and re-deriving bars on change — out of scope for the initial arc.
• Animated reveals / build-by. PPTX charts can specify per-series animation. Artstr doesn't render slide animations, so these get ignored uniformly with the rest of p:timing.

---

13. Acceptance criteria for first release (Phase 1 done)

• Importing gallery_template_layout_set.pptx produces slide 10 with 8 native bar shape layers in #5E735D and #B05A44, plus 4 Q1..Q4 text labels, instead of a single placeholder image.
• Synthetic 2-series 4-category test deck imports the same.
• Synthetic scatter / 3D / area decks still produce the placeholder image + warning (no regression on the existing unsupported-chart path).
• Pure-Node unit tests cover the cache-extraction helpers (readCategoryLabels, readSeriesValues, readSeriesColor).