add better docs for layout controls

Author: batpad

docs/examples/demo.ipynb

@@ -30,7 +30,8 @@ pip install "manywidgets[lonboard]"
 
 **Layout:** [`Row`](widgets/row.ipynb), [`Column`](widgets/column.ipynb),
 [`Grid`](widgets/grid.ipynb) — arrange widgets side-by-side while keeping them
-linked, live and in static export.
+linked, live and in static export. See the [layout examples](examples/layout.ipynb)
+for how they compose.
 
 **Lonboard interop** (optional, `pip install "manywidgets[lonboard]"`):
 [`LayerToggle`](widgets/layer_toggle.ipynb),

docs/examples/layout.ipynb

@@ -55,6 +55,7 @@ project:
     - title: Examples
       children:
         - file: examples/demo.ipynb
+        - file: examples/layout.ipynb
         - file: examples/lonboard-map.ipynb
 site:
   template: book-theme

docs/index.md

@@ -42,9 +42,10 @@ const PALETTE = [
   "#8c564b", "#e377c2", "#7f7f7f", "#bcbd22", "#17becf",
 ];
 
-function formatSeriesData(seriesData: Series[]) {
+function formatSeriesData(seriesData: Series[], defaultType: string) {
   return (seriesData || []).map((series, index) => {
     const color = series.color || PALETTE[index % PALETTE.length];
+    const type = series.type || defaultType || "line";
 
     let data: unknown;
     if (series.data && series.data.length > 0) {
@@ -62,19 +63,19 @@ function formatSeriesData(seriesData: Series[]) {
       data,
       borderColor: color,
       backgroundColor: color + "33",
-      type: series.type || "line",
+      type,
       fill: series.fill !== undefined ? series.fill : false,
       tension: series.tension ?? 0.1,
       pointRadius: series.pointRadius !== undefined ? series.pointRadius : 3,
       pointHoverRadius: 5,
       borderWidth: series.borderWidth || 2,
     };
 
-    if (series.type === "scatter") {
+    if (type === "scatter") {
       dataset.showLine = false;
       dataset.pointRadius = series.pointRadius || 5;
     }
-    if (series.type === "bar") {
+    if (type === "bar") {
       dataset.backgroundColor = color + "80";
     }
     return dataset;
@@ -146,31 +147,33 @@ function render({ model, el }: RenderProps<ChartModel>): () => void {
     return options;
   }
 
+  function build(): void {
+    chart?.destroy();
+    chart = new Chart(canvas, {
+      type: (model.get("chart_type") || "line") as never,
+      data: { datasets: formatSeriesData(model.get("series_data"), model.get("chart_type")) as never },
+      options: buildOptions() as never,
+    });
+  }
+
   function createOrUpdate(): void {
-    const datasets = formatSeriesData(model.get("series_data"));
-    const options = buildOptions();
     if (!chart) {
-      chart = new Chart(canvas, {
-        type: (model.get("chart_type") || "line") as never,
-        data: { datasets: datasets as never },
-        options: options as never,
-      });
+      build();
     } else {
-      chart.data = { datasets: datasets as never };
-      chart.options = options as never;
+      chart.data = { datasets: formatSeriesData(model.get("series_data"), model.get("chart_type")) as never };
+      chart.options = buildOptions() as never;
       chart.update();
     }
   }
 
-  if ((model.get("series_data") || []).length > 0) createOrUpdate();
+  if ((model.get("series_data") || []).length > 0) build();
 
   // NOTE: register one listener per trait — the static-export model emitter does
   // not support space-separated event names (see core's onChanges docstring).
   onChanges(
     model,
     [
       "series_data",
-      "chart_type",
       "chart_options",
       "animation_enabled",
       "tooltips_enabled",
@@ -182,6 +185,10 @@ function render({ model, el }: RenderProps<ChartModel>): () => void {
     createOrUpdate,
   );
 
+  // Switching the default series type requires a fresh chart — Chart.js won't
+  // re-type existing datasets via update().
+  onChanges(model, ["chart_type"], build);
+
   onChanges(model, ["width", "height"], () => {
     container.style.width = `${model.get("width")}px`;
     container.style.height = `${model.get("height")}px`;

docs/myst.yml

@@ -87,7 +87,10 @@ def add_series(
         """
         data = self._coerce_points(x, y, data)
         series = {
-            "type": series_type or self.chart_type,
+            # Only pin a type when the caller asks for one; otherwise leave it
+            # unset so the series follows the chart's live ``chart_type`` (lets a
+            # control bound to ``chart_type`` re-type the chart).
+            "type": series_type,
             "data": data,
             "name": name or f"Series {len(self.series_data) + 1}",
         }

src/manywidgets/chart/src/index.ts

@@ -26,3 +26,6 @@ Column(s, nd, gap="12px")
 {api-table}
 
 Pass children positionally (`Column(a, b)`) or as a list (`Column(children=[a, b])`).
+
+See [Layout](../examples/layout.ipynb) for how `Row`, `Column`, and `Grid`
+compose into a full screen.

src/manywidgets/chart/widget.py

@@ -30,3 +30,6 @@ Grid(
 {api-table}
 
 Pass children positionally (`Grid(a, b, c)`) or as a list (`Grid(children=[a, b, c])`).
+
+See [Layout](../examples/layout.ipynb) for how `Row`, `Column`, and `Grid`
+compose into a full screen.

src/manywidgets/column/doc.md

@@ -27,3 +27,6 @@ Row(s, stat, gap="24px")
 {api-table}
 
 Pass children positionally (`Row(a, b)`) or as a list (`Row(children=[a, b])`).
+
+See [Layout](../examples/layout.ipynb) for how `Row`, `Column`, and `Grid`
+compose into a full screen.