Skip to content

Chart-Lab Import Gaps

This note documents the current import process for bringing chart-lab work into Dataface, with special attention to the gaps between what a base Vega-Lite lab spec can express and what Dataface can currently express through its typed YAML surface.

Future reviewers should start here when asking:

  • what was intentionally imported
  • what was deferred because it depends on chart-lab helper functions
  • what Vega-Lite can express directly that Dataface does not yet expose cleanly

Review Process

Use this order when reviewing a chart-lab import:

  1. Identify whether the lab chart has a base variant, an enhanced variant, or both.
  2. Compare Dataface only against the base variant first.
  3. Port anything that is expressible through Dataface's typed surface:
  4. theme
  5. style preset
  6. style.charts.*
  7. family style such as style.line.* or style.arc.*
  8. existing chart settings and labels
  9. Record any remaining gap as one of:
  10. typed-surface gap
  11. helper-layer gap
  12. specimen-only copy/content difference
  13. Only after the base variant is understood should enhanced helper behavior be considered for productization.

Base vs Enhanced

For this import effort:

  • base variant means a chart-lab chart that is still plain Vega-Lite, even if it uses layering or low-level config directly.
  • enhanced variant means a chart that depends on chart-lab helper functions or custom directive logic that is not yet part of Dataface.

The import goal is not to copy chart-lab helpers blindly. The goal is to learn which parts should become:

  • Dataface defaults
  • Dataface typed chart/style fields
  • Dataface future composition APIs
  • lab-only experimental behavior

Current Known Typed-Surface Gaps

These are gaps where a base Vega-Lite chart can express something directly, but Dataface does not yet have a clean first-class typed way to say the same thing.

line-single

Current status:

  • partially ported into examples/playground/faces/charts/chart-lab-import-review.yml
  • imported more directly through Dataface's existing Vega-Lite passthrough surfaces, so the base lab config is now working in the review page
  • closer on title/subtitle, month bucketing, null axis titles, layered line/point treatment, and non-zero y-scale

Known gaps:

  • Dataface now exposes temporal bucketing through style.axis_x.time_unit. Chart-lab specimens that still hand-author raw Vega-Lite time-unit snippets should move to the typed surface when touched.

  • No clean typed way to suppress axis titles with title: null.

  • Vega-Lite can express this directly on axis config.
  • Dataface can currently carry it through axis passthrough in the review specimen.
  • Dataface does not yet expose it as a clean typed authoring intent.

Not counted as typed-surface gaps for this chart:

  • helper-driven secondary rows like yearUnderJanuary, valueUnderMonth, and footerRight
  • helper-driven biSpacedK label mode
  • layered halo/understroke treatment

Those are real gaps versus the full chart-lab result, but they belong to the helper/composition layer rather than the base Vega-Lite parity layer.

How To Use This Note

When reviewing the next imported chart:

  1. Add its typed-surface gaps here.
  2. Keep helper-layer gaps separate from typed-surface gaps.
  3. Link the current specimen or review page that demonstrates the gap.
  4. Prefer a precise statement like:
  5. "Vega-Lite supports X directly."
  6. "Dataface currently lacks a typed field for X."
  7. "Current workaround is Y."

This keeps chart-lab import review honest. It prevents us from confusing three different problems:

  • theme/default migration
  • missing typed Dataface API
  • missing chart-lab helper/composition features