Sample 06 — Interactive Data and Learning Widgets

A useful interactive invites the reader to test a relationship, not merely watch an animation. In this sample, readers can change a function's parameters, inspect a chart, explore a hierarchy, and check a short answer.

Every dataset here is invented for demonstration. The numbers do not describe site visitors, actual experiments, or a person's routine. Source blocks show the complete author-facing configuration; the live component appears immediately below each block.

Describe a widget with data

An interactive fence contains one validated JSON object. The type chooses a widget; chart widgets also have a style. Titles and captions explain what the reader should notice. Use JSON data rather than JavaScript expressions or callback functions.

The simplest experiment is a sine curve with amplitude and frequency controls.

1
```interactive
2
{
3
  "type": "function-plot",
4
  "title": "Change one parameter at a time",
5
  "preset": "sine",
6
  "amplitude": 1,
7
  "frequency": 1,
8
  "caption": "First change amplitude, then reset and change frequency. Compare height with repetition."
9
}
10
```

Try it: move a slider with the keyboard, inspect its value, and use Reset. A caption should give the reader a concrete comparison to make.

Follow a trend with a line chart

A category chart has labels and equally sized value arrays. A null is a missing observation, not a measured zero. A second series and a reference line give the reader useful comparisons.

1
```interactive
2
{
3
  "type": "chart",
4
  "style": "line",
5
  "title": "Two imagined sequences",
6
  "labels": ["Pass 1", "Pass 2", "Pass 3", "Pass 4", "Pass 5"],
7
  "series": [
8
    {"name": "Sequence A", "values": [4, 6, null, 9, 11]},
9
    {"name": "Sequence B", "values": [3, 5, 7, 8, 10], "dashed": true}
10
  ],
11
  "yAxis": {"type": "value", "title": "Illustrative count", "min": 0, "max": 12},
12
  "format": {"precision": 0},
13
  "annotations": [{"type": "line", "axis": "y", "value": 8, "label": "Example target"}],
14
  "zoom": true,
15
  "caption": "Synthetic counts. Sequence A deliberately has a missing value at Pass 3."
16
}
17
```

Try it: inspect the shared tooltip, hide a series with its legend, and reset. Focus the plot and use Left/Right to move between points and Up/Down to change series. Enter pins a tooltip; Escape dismisses it. Zoom controls change the visible range, while the data table retains the source values.

Use a time axis and dated XY points when the spacing represents real elapsed time. Category labels alone do not make an evenly spaced timeline into a continuous time scale.

Compare parts with stacked bars

Stacking is appropriate when the values are meaningful parts of a total. These invented minutes form one small scheduling example.

1
```interactive
2
{
3
  "type": "chart",
4
  "style": "bar",
5
  "title": "An imagined study session",
6
  "labels": ["Plan", "Draft", "Review"],
7
  "series": [
8
    {"name": "Reading", "values": [10, 5, 8]},
9
    {"name": "Making", "values": [5, 20, 7]}
10
  ],
11
  "stacking": "normal",
12
  "yAxis": {"type": "value", "title": "Minutes", "min": 0},
13
  "format": {"precision": 0, "suffix": " min"},
14
  "caption": "Illustrative allocations, not a record of anyone's actual work."
15
}
16
```

Try it: compare the total heights, then hide one category to inspect its contribution. Be explicit about whether the chart shows raw totals or percentages; changing the visual form changes the question a reader can answer.

Use numeric coordinates for a scatter plot

XY data uses points, with numeric x and y. Optional low and high fields display an interval. Here those bounds are illustrative marks, not estimated confidence intervals.

1
```interactive
2
{
3
  "type": "chart",
4
  "style": "scatter",
5
  "title": "A synthetic input-response relationship",
6
  "series": [{"name": "Example points", "points": [
7
    {"x": 1, "y": 2, "low": 1.5, "high": 2.5},
8
    {"x": 2, "y": 4.5, "low": 4, "high": 5},
9
    {"x": 3, "y": 6, "low": 5.5, "high": 6.5},
10
    {"x": 4, "y": 8.5, "low": 8, "high": 9}
11
  ]}],
12
  "xAxis": {"type": "value", "title": "Input (arbitrary units)", "min": 0, "max": 5},
13
  "yAxis": {"type": "value", "title": "Response (arbitrary units)", "min": 0, "max": 10},
14
  "format": {"precision": 1},
15
  "tooltip": "item",
16
  "zoom": true,
17
  "caption": "Invented points and bounds used solely to demonstrate XY data and intervals."
18
}
19
```

A visually smooth pattern is not evidence of a causal relationship. Supply the data source, units, sampling method, and interpretation when replacing this synthetic example with real results.

Find a pattern across two categories

A heatmap has column labels, row labels, and cells of the form [columnIndex, rowIndex, value]. Indices begin at zero.

1
```interactive
2
{
3
  "type": "chart",
4
  "style": "heatmap",
5
  "title": "An imagined weekly practice grid",
6
  "labels": ["Mon", "Tue", "Wed", "Thu"],
7
  "yLabels": ["Read", "Make", "Review"],
8
  "cells": [
9
    [0,0,5], [1,0,8], [2,0,4], [3,0,6],
10
    [0,1,3], [1,1,5], [2,1,9], [3,1,7],
11
    [0,2,2], [1,2,4], [2,2,3], [3,2,5]
12
  ],
13
  "format": {"precision": 0, "suffix": " min"},
14
  "caption": "Synthetic practice minutes. Inspect individual cells and try the value-range filter."
15
}
16
```

Try it: inspect a cell and check its row in the data table. Then narrow the value range to highlight only part of the grid. A legend or exact-value table should carry meaning that color alone cannot communicate.

Explore a hierarchy with a treemap

A hierarchy uses named branches and numeric leaf values. A treemap emphasizes relative area; it should not be used when precise comparison of similar values is the main task.

1
```interactive
2
{
3
  "type": "chart",
4
  "style": "treemap",
5
  "title": "An illustrative allocation of attention",
6
  "tree": [
7
    {"name": "Study", "children": [
8
      {"name": "Reading", "value": 12},
9
      {"name": "Notes", "value": 8}
10
    ]},
11
    {"name": "Practice", "children": [
12
      {"name": "Experiments", "value": 18},
13
      {"name": "Review", "value": 10}
14
    ]}
15
  ],
16
  "format": {"precision": 0},
17
  "caption": "Invented values. Explore a branch, then use the chart's return navigation."
18
}
19
```

The exported data records the hierarchy's paths and values. Keep branch names meaningful when you substitute a real collection.

Check an idea with a quiz

A quiz has a prompt, two to eight choices, a zero-based answer index, and an explanation. The explanation should show the reasoning, not just announce a result.

1
```interactive
2
{
3
  "type": "quiz",
4
  "title": "Read the numbers before the chart",
5
  "prompt": "What is the arithmetic mean of 2, 4, 6, and 8?",
6
  "choices": ["4", "5", "6"],
7
  "answer": 1,
8
  "explanation": "The values sum to 20. Dividing by four values gives 5.",
9
  "caption": "Choose a value, then check the explanation. The second choice has index 1."
10
}
11
```

In a tutorial like this one, the visible source intentionally reveals the answer. For an exercise article, present only the rendered quiz and keep the source in Studio.

Switch between short plain-text summaries

Use the plain-text tab widget when panels need only text. Choose rich Markdown tabs instead when a panel contains lists, equations, images, or links.

1
```interactive
2
{
3
  "type": "tabs",
4
  "title": "Three ways to approach a visual",
5
  "tabs": [
6
    {"label": "Read", "body": "Start with the title, units, and data source."},
7
    {"label": "Try", "body": "Change one control and observe which relationship changes."},
8
    {"label": "Explain", "body": "Describe what the visual supports and what it leaves uncertain."}
9
  ],
10
  "active": 0,
11
  "caption": "Switch views with the controls or arrow keys."
12
}
13
```

Inspect, export, and keep a static fallback

Charts are compiled to light/dark SVG with exact-value tables before publication. Their interactive engine loads on intent, such as hover, focus, or touch. The static drawing remains useful while the enhancement loads or if it is unavailable.

Try it: activate a chart, open its data table, and compare a tooltip with the corresponding source value. Download CSV for the full dataset, or SVG/PNG for the current chart view. Hidden series and a narrowed zoom range do not remove source rows from CSV.

Without JavaScript, the chart drawings and data tables remain readable, quiz explanations remain available, and tab content has a static representation. Print and PDF use the static presentation. Write titles, captions, and explanations that make sense in those modes too.

When adapting this sample, start with one question and one small dataset. Add interaction only when the reader can use it to answer that question more clearly.