@revenexx/editor 0.1.0

package/dist/modules/charts/runtime/blokkli/chart-types/pie/illustration.vue

@@ -0,0 +1,20 @@
+<template>
+  <svg viewBox="0 0 120 80" xmlns="http://www.w3.org/2000/svg">
+    <path
+      v-for="(s, i) in slices"
+      :key="i"
+      :d="`M 60 40 L ${s.start[0]} ${s.start[1]} A 28 28 0 0 1 ${s.end[0]} ${s.end[1]} Z`"
+      :class="s.color"
+    />
+  </svg>
+</template>
+
+<script setup>
+import { tw } from "#blokkli/helpers/tw";
+const slices = [
+  { start: [88, 40], end: [55.1, 67.6], color: tw("_bk_fill-accent-500") },
+  { start: [55.1, 67.6], end: [32, 40], color: tw("_bk_fill-accent-800") },
+  { start: [32, 40], end: [60, 12], color: tw("_bk_fill-accent-300") },
+  { start: [60, 12], end: [88, 40], color: tw("_bk_fill-accent-400") }
+];
+</script>

package/dist/modules/charts/runtime/blokkli/chart-types/pie/illustration.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/pie/render.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<any, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, any, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/pie/render.vue

@@ -0,0 +1,71 @@
+<template>
+  <VChart :option="option" autoresize style="height: 550px; width: 100%" />
+</template>
+
+<script setup>
+import { computed } from "#imports";
+import VChart from "vue-echarts";
+import { use } from "echarts/core";
+import { CanvasRenderer } from "echarts/renderers";
+import { PieChart } from "echarts/charts";
+import {
+  TooltipComponent,
+  LegendComponent,
+  TitleComponent
+} from "echarts/components";
+import {
+  createNumberFormatter,
+  createPercentFormatter
+} from "../../../helpers/numberFormat";
+use([
+  CanvasRenderer,
+  PieChart,
+  TooltipComponent,
+  LegendComponent,
+  TitleComponent
+]);
+const props = defineProps({
+  title: { type: String, required: true },
+  categories: { type: Array, required: true },
+  series: { type: Array, required: true },
+  seriesHexColors: { type: Array, required: true },
+  categoryHexColors: { type: Array, required: true },
+  typeOptions: { type: Object, required: true },
+  numberFormat: { type: Object, required: false },
+  isEditing: { type: Boolean, required: true },
+  advancedConfig: { type: Object, required: false }
+});
+const option = computed(() => {
+  const t = props.typeOptions;
+  const showLabels = t.showLabels ?? true;
+  const values = props.series[0]?.data ?? [];
+  const valueFormatter = createNumberFormatter(props.numberFormat);
+  const percentFormatter = createPercentFormatter(props.numberFormat);
+  const data = props.categories.map((name, i) => ({
+    name,
+    value: values[i] ?? 0,
+    itemStyle: { color: props.categoryHexColors[i] }
+  }));
+  return {
+    title: props.title ? { text: props.title, left: "left" } : void 0,
+    animation: !props.isEditing,
+    tooltip: {
+      trigger: "item",
+      valueFormatter: (v) => valueFormatter(v)
+    },
+    legend: { left: "center", bottom: 0, orient: "horizontal" },
+    series: [
+      {
+        type: "pie",
+        radius: "60%",
+        center: ["50%", "50%"],
+        data,
+        label: {
+          show: showLabels,
+          formatter: (p) => percentFormatter(p.percent)
+        }
+      }
+    ]
+  };
+});
+</script>

package/dist/modules/charts/runtime/blokkli/chart-types/pie/render.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<any, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, any, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radar/definition.d.ts

@@ -0,0 +1,7 @@
+import type { DataLabelsTypeOptions, LegendTypeOptions, CategoryFilterTypeOptions } from '#blokkli/charts/types';
+export type TypeOptions = {
+    markers: boolean;
+    fillOpacity: string;
+} & DataLabelsTypeOptions & LegendTypeOptions & CategoryFilterTypeOptions;
+declare const _default: any;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radar/definition.js

@@ -0,0 +1,45 @@
+import { defineChartType } from "#blokkli/charts/definition";
+import {
+  dataLabelsOptions,
+  legendOptions,
+  categoryFilterOptions,
+  mergeShared
+} from "#blokkli/charts/definition/options";
+export default defineChartType("radar", ($t) => {
+  const shared = mergeShared(
+    dataLabelsOptions($t),
+    legendOptions($t),
+    categoryFilterOptions($t)
+  );
+  return {
+    hasSeriesColors: true,
+    hasCategoryColors: false,
+    editor: {
+      label: $t("chartsTypeRadar", "Radar"),
+      description: $t(
+        "chartsTypeRadarDescription",
+        "Plots several variables on radial axes to compare strengths and weaknesses across categories."
+      ),
+      icon: "bk_mdi_radar",
+      options: {
+        markers: {
+          type: "checkbox",
+          label: $t("showMarkers", "Show markers"),
+          default: false,
+          group: "display"
+        },
+        fillOpacity: {
+          type: "radios",
+          label: $t("chartsRadarFillOpacity", "Fill opacity"),
+          default: "0.2",
+          options: {
+            "0.2": $t("chartsOpacityTransparent", "Transparent"),
+            "0.4": $t("chartsOpacityLight", "Light"),
+            "0.8": $t("chartsOpacitySolid", "Solid")
+          }
+        },
+        ...shared.options
+      }
+    }
+  };
+});

package/dist/modules/charts/runtime/blokkli/chart-types/radar/illustration.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radar/illustration.vue

@@ -0,0 +1,60 @@
+<template>
+  <svg viewBox="0 0 120 80" xmlns="http://www.w3.org/2000/svg">
+    <polygon
+      :points="toPoints(innerGrid)"
+      fill="none"
+      stroke-width="1"
+      class="_bk_stroke-accent-200"
+    />
+    <polygon
+      :points="toPoints(outerGrid)"
+      fill="none"
+      stroke-width="1.5"
+      class="_bk_stroke-accent-400"
+    />
+    <line
+      v-for="([x, y], i) in outerGrid"
+      :key="i"
+      x1="60"
+      y1="40"
+      :x2="x"
+      :y2="y"
+      stroke-width="1"
+      class="_bk_stroke-accent-300"
+    />
+    <polygon
+      :points="toPoints(data)"
+      fill-opacity="0.45"
+      stroke-width="2"
+      stroke-linejoin="round"
+      class="_bk_fill-accent-500 _bk_stroke-accent-800"
+    />
+  </svg>
+</template>
+
+<script setup>
+const outerGrid = [
+  [60, 12],
+  [86.6, 31.35],
+  [76.5, 62.65],
+  [43.5, 62.65],
+  [33.4, 31.35]
+];
+const innerGrid = [
+  [60, 26],
+  [78.6, 32.8],
+  [71.5, 53.2],
+  [48.5, 53.2],
+  [41.4, 32.8]
+];
+const data = [
+  [60, 18],
+  [77.1, 34.4],
+  [74.1, 59.4],
+  [52.9, 49.7],
+  [41, 33.8]
+];
+function toPoints(points) {
+  return points.map((p) => p.join(",")).join(" ");
+}
+</script>

package/dist/modules/charts/runtime/blokkli/chart-types/radar/illustration.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radar/render.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<any, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, any, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radar/render.vue

@@ -0,0 +1,95 @@
+<template>
+  <VChart :option="option" autoresize style="height: 550px; width: 100%" />
+</template>
+
+<script setup>
+import { computed } from "#imports";
+import VChart from "vue-echarts";
+import { use } from "echarts/core";
+import { CanvasRenderer } from "echarts/renderers";
+import { RadarChart } from "echarts/charts";
+import {
+  TooltipComponent,
+  LegendComponent,
+  TitleComponent
+} from "echarts/components";
+import { legendPositionToEcharts } from "../../../helpers/echarts";
+import { createNumberFormatter } from "../../../helpers/numberFormat";
+use([
+  CanvasRenderer,
+  RadarChart,
+  TooltipComponent,
+  LegendComponent,
+  TitleComponent
+]);
+const props = defineProps({
+  title: { type: String, required: true },
+  categories: { type: Array, required: true },
+  series: { type: Array, required: true },
+  seriesHexColors: { type: Array, required: true },
+  categoryHexColors: { type: Array, required: true },
+  typeOptions: { type: Object, required: true },
+  numberFormat: { type: Object, required: false },
+  isEditing: { type: Boolean, required: true },
+  advancedConfig: { type: Object, required: false }
+});
+const opts = computed(() => {
+  const t = props.typeOptions;
+  return {
+    markers: t.markers ?? false,
+    fillOpacity: Number(t.fillOpacity ?? 0.2) || 0.2,
+    dataLabels: t.dataLabels ?? false,
+    legendPosition: t.legendPosition ?? "bottom"
+  };
+});
+const option = computed(() => {
+  const o = opts.value;
+  const valueFormatter = createNumberFormatter(props.numberFormat);
+  const indicators = props.categories.map((name, i) => {
+    let max = 0;
+    for (const s of props.series) {
+      const v = s.data[i] ?? 0;
+      if (v > max) max = v;
+    }
+    return { name, max: max > 0 ? max : 1 };
+  });
+  return {
+    title: props.title ? { text: props.title, left: "left" } : void 0,
+    animation: !props.isEditing,
+    tooltip: {
+      trigger: "item",
+      valueFormatter: (v) => valueFormatter(v)
+    },
+    legend: {
+      ...legendPositionToEcharts(o.legendPosition),
+      data: props.series.map((s) => s.name)
+    },
+    radar: {
+      indicator: indicators,
+      center: ["50%", "52%"],
+      radius: "65%"
+    },
+    series: [
+      {
+        type: "radar",
+        symbol: o.markers ? "circle" : "none",
+        symbolSize: 5,
+        data: props.series.map((s, i) => ({
+          name: s.name,
+          value: s.data,
+          itemStyle: { color: props.seriesHexColors[i] },
+          lineStyle: { color: props.seriesHexColors[i] },
+          areaStyle: {
+            color: props.seriesHexColors[i],
+            opacity: o.fillOpacity
+          },
+          label: {
+            show: o.dataLabels,
+            formatter: (p) => valueFormatter(p.value)
+          }
+        }))
+      }
+    ]
+  };
+});
+</script>

package/dist/modules/charts/runtime/blokkli/chart-types/radar/render.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<any, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, any, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radialBar/definition.d.ts

@@ -0,0 +1,6 @@
+import type { CategoryFilterTypeOptions } from '#blokkli/charts/types';
+export type TypeOptions = {
+    showLabels: boolean;
+} & CategoryFilterTypeOptions;
+declare const _default: any;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radialBar/definition.js

@@ -0,0 +1,29 @@
+import { defineChartType } from "#blokkli/charts/definition";
+import {
+  categoryFilterOptions,
+  mergeShared
+} from "#blokkli/charts/definition/options";
+export default defineChartType("radialBar", ($t) => {
+  const shared = mergeShared(categoryFilterOptions($t));
+  return {
+    hasSeriesColors: false,
+    hasCategoryColors: true,
+    editor: {
+      label: $t("chartsTypeRadialBar", "Radial Bar"),
+      description: $t(
+        "chartsTypeRadialBarDescription",
+        "Shows values as concentric circular bars on a polar grid \u2014 suited to KPIs and progress indicators."
+      ),
+      icon: "bk_mdi_track_changes",
+      options: {
+        showLabels: {
+          type: "checkbox",
+          label: $t("showLabels", "Show labels"),
+          default: true,
+          group: "labels"
+        },
+        ...shared.options
+      }
+    }
+  };
+});

package/dist/modules/charts/runtime/blokkli/chart-types/radialBar/illustration.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radialBar/illustration.vue

@@ -0,0 +1,32 @@
+<template>
+  <svg viewBox="0 0 120 80" xmlns="http://www.w3.org/2000/svg">
+    <circle
+      v-for="r in [12, 20, 28]"
+      :key="r"
+      cx="60"
+      cy="40"
+      :r="r"
+      fill="none"
+      stroke-width="4"
+      class="_bk_stroke-accent-200"
+    />
+    <path
+      v-for="(a, i) in arcs"
+      :key="i"
+      :d="a.d"
+      fill="none"
+      stroke-width="4"
+      stroke-linecap="round"
+      :class="a.color"
+    />
+  </svg>
+</template>
+
+<script setup>
+import { tw } from "#blokkli/helpers/tw";
+const arcs = [
+  { d: "M 60 28 A 12 12 0 1 1 48 40", color: tw("_bk_stroke-accent-800") },
+  { d: "M 60 20 A 20 20 0 0 1 60 60", color: tw("_bk_stroke-accent-500") },
+  { d: "M 60 12 A 28 28 0 0 1 88 40", color: tw("_bk_stroke-accent-300") }
+];
+</script>

package/dist/modules/charts/runtime/blokkli/chart-types/radialBar/illustration.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radialBar/render.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<any, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, any, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/chart-types/radialBar/render.vue

@@ -0,0 +1,77 @@
+<template>
+  <VChart :option="option" autoresize style="height: 550px; width: 100%" />
+</template>
+
+<script setup>
+import { computed } from "#imports";
+import VChart from "vue-echarts";
+import { use } from "echarts/core";
+import { CanvasRenderer } from "echarts/renderers";
+import { BarChart } from "echarts/charts";
+import {
+  PolarComponent,
+  TooltipComponent,
+  TitleComponent
+} from "echarts/components";
+import { createNumberFormatter } from "../../../helpers/numberFormat";
+use([
+  CanvasRenderer,
+  BarChart,
+  PolarComponent,
+  TooltipComponent,
+  TitleComponent
+]);
+const props = defineProps({
+  title: { type: String, required: true },
+  categories: { type: Array, required: true },
+  series: { type: Array, required: true },
+  seriesHexColors: { type: Array, required: true },
+  categoryHexColors: { type: Array, required: true },
+  typeOptions: { type: Object, required: true },
+  numberFormat: { type: Object, required: false },
+  isEditing: { type: Boolean, required: true },
+  advancedConfig: { type: Object, required: false }
+});
+const option = computed(() => {
+  const t = props.typeOptions;
+  const showLabels = t.showLabels ?? true;
+  const values = props.series[0]?.data ?? [];
+  const valueFormatter = createNumberFormatter(props.numberFormat);
+  const max = Math.max(0, ...values.map((v) => v ?? 0));
+  const data = props.categories.map((name, i) => ({
+    name,
+    value: values[i] ?? 0,
+    itemStyle: { color: props.categoryHexColors[i] }
+  }));
+  return {
+    title: props.title ? { text: props.title, left: "left" } : void 0,
+    animation: !props.isEditing,
+    polar: { radius: ["20%", "70%"] },
+    tooltip: {
+      trigger: "item",
+      formatter: (p) => `${p.name}: ${valueFormatter(p.value)}`
+    },
+    angleAxis: { max: max || 1, startAngle: 90, show: false },
+    radiusAxis: {
+      type: "category",
+      data: props.categories,
+      axisLabel: { show: showLabels },
+      axisLine: { show: false },
+      axisTick: { show: false }
+    },
+    series: [
+      {
+        type: "bar",
+        coordinateSystem: "polar",
+        data,
+        roundCap: true,
+        label: {
+          show: showLabels,
+          position: "middle",
+          formatter: (p) => valueFormatter(p.value)
+        }
+      }
+    ]
+  };
+});
+</script>

package/dist/modules/charts/runtime/blokkli/chart-types/radialBar/render.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<any, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, any, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/modules/charts/runtime/blokkli/skills/charts.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/modules/charts/runtime/blokkli/skills/charts.js

@@ -0,0 +1,85 @@
+import { defineBlokkliAgentSkill } from "#blokkli/agent/server/skills";
+export default defineBlokkliAgentSkill({
+  name: "charts",
+  label: { en: "Working with charts", de: "Arbeiten mit Diagrammen" },
+  description: "Load this when the user asks about charts or when you need to create or update a chart!",
+  tools: [
+    "create_chart",
+    "update_chart",
+    "get_chart_data",
+    "get_chart_type_options",
+    "create_advanced_chart",
+    "update_advanced_chart",
+    "get_advanced_chart_config"
+  ],
+  getContents: () => `
+# Charts
+
+## Key concept
+
+A "chart block" is any block whose definition has a JSON option with \`dataType: 'chart'\`. The chart tools automatically detect which option holds chart data, so you don't need to know the option key or bundle name.
+
+## Available tools
+
+- **get_chart_data**: Read the current chart data (type, categories, series, colors, typeOptions). Always call this first when modifying an existing chart!
+- **create_chart**: Create a new chart. Requires chart data (type, categories, series). The tool automatically finds which bundle in the target field has a chart option.
+- **update_chart**: Update an existing chart. Pass the block's UUID and only the properties you want to change (title, type, categories, series, categoryColors, footnotes, typeOptions).
+- **get_chart_type_options**: Get available typeOptions for a chart type. Call this to discover which rendering options exist (e.g. stacked, horizontal for bar charts) before setting typeOptions.
+
+## Workflow
+
+1. To **read** a chart's current state: use get_chart_data with the paragraph UUID.
+2. To **create** a chart: use create_chart with the data. The tool finds the right bundle automatically from the target field's allowed bundles.
+3. To **modify** a chart: first call get_chart_data to see the current state, then use update_chart with only the properties you want to change.
+4. To **change rendering options** (e.g. stacked bars, smooth lines, grid lines): first call get_chart_type_options with the chart type to see available options, then use update_chart with the typeOptions property.
+
+## IMPORTANT
+
+- DO NOT use the add_paragraph tool for creating charts! Always use create_chart!
+- DO NOT use the set_paragraph_option tool for updating charts! Always use update_chart!
+
+## Chart types
+
+bar, line, pie, area, donut, heatmap, radialBar, radar, agePyramid.
+
+- pie, donut, radialBar: Single-series charts where each category gets its own color (categoryColors).
+- bar, line, area, heatmap, radar: Multi-series charts where each series has its own color.
+- agePyramid: Back-to-back horizontal bars by category. The \`splitIndex\` typeOption picks which series index starts on the right; series before it render on the left. Defaults to half the number of series.
+
+Each chart type has different options!
+
+## Advanced charts (raw ECharts)
+
+There is also an \`advanced\` chart type that stores a raw ECharts option object instead of structured categories/series. It is **not** in the type enum used by \`create_chart\` / \`update_chart\` / \`get_chart_data\` \u2014 use the dedicated tools:
+
+- **create_advanced_chart**: Create a new advanced chart from a full ECharts option object.
+- **update_advanced_chart**: Replace the ECharts option on an existing advanced chart. The config is a full replacement, not a partial merge \u2014 call \`get_advanced_chart_config\` first if you need to read-then-edit. Refuses if the chart is structured.
+- **get_advanced_chart_config**: Read the current ECharts option. Refuses if the chart is structured.
+
+Use the advanced tools only when the user needs a chart type or layout not covered by the structured types. The agent **cannot** convert between structured and advanced \u2014 to swap, delete the chart and create a new one.
+
+## Colors
+
+Series colors and category colors use color IDs defined in the project configuration. They are auto-assigned if omitted. The valid color IDs are part of the tool schemas (enum values).
+
+## Dynamic data sources
+
+A chart can be bound to a dynamic data source (e.g. a backend-provided dataset). When \`get_chart_data\` returns a \`dataSource\` field, the chart's inline \`categories\` and \`series\` are ignored at render time and replaced with the live data. In this state:
+
+- \`update_chart\` refuses changes to \`categories\` or \`series\` and returns an error \u2014 the user has to unbind the data source in the editor first.
+- Other fields (title, type, typeOptions, footnotes, numberFormat, dateFormat) remain editable.
+
+## Filterable categories
+
+Many chart types (bar, line, area, heatmap, radar, pie, donut, radialBar) support a \`categoryFilter\` typeOption. When enabled, the chart wrapper renders a category picker so viewers can show one category at a time. The companion \`categoryFilterLabel\` typeOption is a string shown next to the picker.
+
+## Formatting
+
+- \`numberFormat\`: Controls axes, data labels and tooltips. Fields: \`locale\` (BCP-47), \`decimals\` (0-4), \`prefix\`, \`suffix\`, \`notation\` ('standard' | 'compact').
+- \`dateFormat.style\`: Applied to category labels that look like dates. Use 'auto' to let the chart pick. Locale is reused from \`numberFormat.locale\`.
+
+## Nullable typeOptions
+
+Some typeOptions (e.g. \`yaxisMin\`, agePyramid's \`splitIndex\`) can be cleared back to "auto" by passing \`null\` for that key in \`typeOptions\`.
+`
+});