HtmlForgeX.ChartForgeX 3.0.0

HtmlForgeX.ChartForgeX

HtmlForgeX.ChartForgeX embeds ChartForgeX charts, chart grids, topology diagrams and static visual artifacts in HtmlForgeX documents. It owns document registration, report theme binding and the shared presentation frame. Charts and artifacts render as script-free SVG by default; chart and topology settings can enable the existing HTML interaction adapters.

Choose the package for the models your document authors:

Each peer is independent. Use using HtmlForgeX; for all three packages. The base adapter does not bring either presentation package into a chart-only report.

using HtmlForgeX;
using ChartForgeX.Core;

using var document = new Document();
Chart chart = Chart.Create().WithTitle("Service health");
document.Body.Add(new ChartForgeXChart(chart));

Use this companion package when a report already models its visualization in ChartForgeX. Keep charts out of raw HTML or SVG strings so the visual remains reusable and testable at its owning API boundary.

Chart rendering stays static until the document opts into interaction. Named review presets cover common report patterns while exposing the underlying ChartForgeX contract:

document.Body.ChartForgeX(chart, settings => settings
    .ReviewPreset(ChartForgeXChartReviewPreset.CompactReport, "service-health")
    .AccessibleLabel("Service health review")
    .End());

changeChart.Series[0].WithInteractionKey("rollout.baseline");
changeChart.Series[1].WithInteractionKey("rollout.candidate");

document.Body.ChartForgeX(changeChart, settings => settings
    .ReviewPreset(
        ChartForgeXChartReviewPreset.GuidedChangeReview,
        options => options.Interaction
            .AddScenario("rollout", "Rollout", route => route
                .AddSeriesStep("rollout.baseline", "Review baseline")
                .AddSeriesStep("rollout.candidate", "Review candidate")),
        chartId: "rollout-change",
        groupName: "release-review")
    .End());

Use the same semantic interaction key on related series to synchronize mixed chart families. Synchronized presets require a named group, guided presets require real scenarios, and HtmlForgeX registers the shared ChartForgeX browser assets once per document.

Interactive charts in a report

An interactive chart is hosted like the report's static charts, with defaults a report needs:

• Theme. It is drawn in the report's theme (ChartForgeXChartTheme.Report, chosen by Auto for interactive charts): the design-token colours and font, no card and a transparent background, with every token colour written as the report's custom property. It follows the light, dark or automatic theme, and the reader's theme switch, while the page is open; its tooltip, toolbar and reset button take the report's surface and text colours. Theme(ChartForgeXChartTheme.Chart) keeps the chart's own look.
• Width. It scales to its panel (HtmlChartResponsiveLayout.Fit). A chart 640 pixels or wider also gets a narrow drawing at 400 pixels that shows while its panel is narrower than 640 pixels, so a phone gets the whole chart with readable labels and a wrapped legend. Both drawings are one chart to links and host commands. NarrowDrawing(false) keeps one drawing; ResponsiveLayout(HtmlChartResponsiveLayout.Readable) keeps the drawn size and scrolls sideways inside the chart.
• Selection. A click or Space selects a mark: the other marks step back, the tooltip follows the pointer and the focus instead of staying pinned, and there is no compare tray. Zoom, pan, brush and export are small buttons at the top right of the chart. Chrome(...) brings back the standalone controls (CompareTray, PinnedTooltips, ToolbarBand, or Standalone for all three).

document.Body.ChartForgeX(chart, settings => settings
    .Interactive("services-by-site", features: ChartForgeXChartInteraction.ReportReview | ChartForgeXChartInteraction.Brush)
    .NarrowDrawing(width: 360)
    .Chrome(ChartForgeXChartChrome.CompareTray)
    .End());

An interactive topology follows the theme the same way. On a phone (a panel narrower than 640 pixels) a diagram wider than tall keeps a readable height of 288 pixels instead of shrinking to a thumbnail, and the reader moves through it with its zoom controls and by dragging; NarrowHeight(pixels) changes the height and NarrowHeight(0) lets it scale to the panel's width. A diagram without viewport controls always scales to its panel.

Static artifacts use the producer's rendering contract, including producers from optional packages:

using ChartForgeX.VisualArtifacts;

var artifact = chart.ToVisualArtifact("service-health");
document.Body.ChartForgeX(artifact, settings => settings
    .Svg("report-service-health")
    .Frame()
    .AccessibleLabel("Service health summary")
    .End());

Use Png() for a static image in a constrained host. Its alternative text and language come from the artifact envelope, and decorative artifacts use an empty alternative. RenderOptions(...) forwards the owning renderer's topology and raster settings. A prepared or decorated artifact keeps its producer-owned output; the document adapter does not select optional model renderers or modify the artifact.

Artifacts fit their container by default. For a detailed drawing, MinimumWidth(480) keeps labels readable below that width in a contained, keyboard-accessible scrolling viewport. The minimum is capped by the producer's natural width, and print fits the drawing to the page.

When the document owns the producer, build the artifact from ReportChartContext to use the same light and dark tokens as report charts:

page.ChartForgeX(context => context.CreateChart(640, 320)
        .WithXLabels("Mon", "Tue", "Wed")
        .AddLine("Success", ChartPoints.FromValues(97, 98, 99), context.Series(0))
        .ToVisualArtifact("success"),
    settings => settings.Svg("report-success").MinimumWidth(480).End());

The callback returns a fresh artifact for each theme. The nearest HtmlForgeX theme scope chooses its drawing, and print constructs only the light artifact. This works with core artifacts and optional canvas or completed-story producers; each producer keeps its own rendering and semantic model. The chartforgex-integration example builds one typed report with a chart and data table, a metric composition, a dependency map and a completed story, plus its print document.

Migrating typed presentation components

ChartForgeX 2.0 separates composition and stories from the core engine. Add HtmlForgeX.ChartForgeX.Visuals when callers use ChartForgeXVisualGrid or ChartForgeXVisualCanvas, and add HtmlForgeX.ChartForgeX.Stories when callers use ChartForgeXVisualStory or ChartForgeXStory(...). Rebuild callers because these types live in their peer assemblies. Their HtmlForgeX namespace and fluent calls stay the same.

Code that explicitly invokes an extension's static declaring class uses ChartForgeXVisualElementExtensions for grids and canvases, or ChartForgeXStoryElementExtensions for stories. Ordinary extension-call syntax stays unchanged. Concrete fact models such as MetricCard require ChartForgeX.Visuals; ChartForgeXVisualBlock remains in the base adapter because it consumes the core IVisualBlock contract.

See the Visuals guide and Stories guide for composition and story examples.

Paired themes and series identity

The adapters use ChartForgeX's immutable VisualTheme for charts, topology, canvases and stories. A report callback receives the paired context.Theme and the explicit context.Mode. Use both when creating a visual outside context.CreateChart; light and dark renderings then share typography and geometry while selecting their own colors.

Interactive series have stable IDs separate from their displayed names. Keep the series handle and pass its Id to scenario steps. Give corresponding series the same explicit ID when selection should synchronize across charts; changing a caption or series order then preserves its meaning.

ChartForgeXTopology.Settings(settings => settings.AdaptiveTheme(true)) binds the diagram to the report palette through role-based SVG color variables. This is the default. The drawing has light fallbacks for print, and the document's theme selects its on-screen colors. Use AdaptiveTheme(false) to retain an authored theme and its explicit mode.

When migrating from the 2.x adapters, replace ChartTheme and TopologyTheme with paired VisualTheme presets, and replace mutable interaction keys with construction-time ChartSeriesId values. A custom topology theme now opts out of report theme binding explicitly with AdaptiveTheme(false).

Charts in reports

ReportChart, ReportStatusTimeline, ReportTimeSeries and ReportTopology host ChartForgeX visuals in a report page. The visual is drawn from the Evotec design tokens for the light and for the dark theme as script-free SVG, with the token colours written as the report's custom properties by their role (ChartForgeX SvgColorVariables). When the light drawing paints exactly what the dark one paints, the page gets that one SVG, which follows the theme; otherwise it gets a literal drawing per theme, shows the one of the nearest theme scope and prints the light one. A caption, a note and a data table under a disclosure are HTML around the chart, so it has a text alternative.

page.ReportTimeSeries(series => series
    .Title("LDAP bind latency", "5-minute rollups over 36 hours")
    .ValueAxis("Latency (ms)")
    .Threshold(60, "Alert at 60 ms", ReportSeverity.High)
    .Series("p95", samples, s => s.Time, s => s.P95));

page.ReportChart(context => context.CreateChart(760, 320).AddHistogram("Samples", values, 10, context.Series(0)),
    chart => chart.Title("Latency").Summary("Most samples are under 30 ms."));

Start a custom chart from context.CreateChart(width, height): it carries the tokens of the theme, the token font, no card and no in-chart title. context.OperationalStates(), context.Outcomes() and context.Severities() return state categories with the report's words and the treatments of the report views (not observable and not evaluated hatched, unknown and could not evaluate a dashed outline, up and passed quiet); ReportChartContext.StatusKey(status) gives the key of any ReportStatus. Calendars take context.FirstDayOfWeek, context.DayNames and context.MonthNames from the culture the report is rendered in, and Labels.ChartText (ReportChartTextLabels, one shared instance per report) holds the words ChartForgeX writes on its own: the ends of calendar scales and the sentences that describe a chart or a topology without a summary. Calendar days are named by their long date in the report's culture. See "Report Views" in Docs/COMPONENT_REFERENCE.md.

A product that draws its own ChartForgeX charts (with its own tokens or words) reuses the same rules instead of copying them: ReportChartStates.OperationalStates(status, labels), Outcomes and Severities build the categories from any VisualStatusTokens, ReportChartStates.Treat(categories, quiet) applies the treatments to a vocabulary of its own (unknown and could not evaluate as a dashed outline, as the views and token metadata draw them), and the report's ReportChartTextLabels instance writes the sentences with Describe(facts, culture): labels.AccessibleTextFormatter = facts => text.Describe(facts, culture).