docs(appkit-ui): document echarts registration contract for custom options

- Document on the `options` prop that only the built-in feature set is
  registered; extra ECharts features (dataZoom, toolbox, markLine, ...)
  must be registered by the consumer via `use` from "echarts/core",
  which requires resolving the same echarts module instance/version.
- Note in the registration block that tooltip-driven axisPointer ships
  with TooltipComponent, and that `use()` must stay co-located with
  BaseChart because package.json#sideEffects declares JS modules pure.
- Fix the type-only import comment: the ECharts type is used for the
  stored instance ref.
- Add tests: custom `options` with a registered component logs no
  registration errors; empty data renders the "No data" fallback.

Co-authored-by: Isaac
Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Author: MarioCadenas

packages/appkit-ui/src/react/charts/__tests__/base.test.tsx

@@ -205,4 +205,31 @@ describe("BaseChart ECharts registration", () => {
     );
     expect(registrationErrors).toEqual([]);
   });
+
+  test("renders custom `options` using a registered component without registration errors", async () => {
+    const { container } = render(
+      <BaseChart
+        data={cartesianData}
+        chartType="line"
+        xKey="month"
+        yKey="revenue"
+        options={{ title: { subtext: "custom" } }}
+      />,
+    );
+
+    await waitFor(() =>
+      expect(container.querySelector("canvas")).not.toBeNull(),
+    );
+    expect(registrationErrors).toEqual([]);
+  });
+
+  test("renders the no-data fallback for empty data without mounting ECharts", () => {
+    const { container, getByText } = render(
+      <BaseChart data={[]} chartType="line" />,
+    );
+
+    expect(getByText("No data")).toBeTruthy();
+    expect(container.querySelector("canvas")).toBeNull();
+    expect(registrationErrors).toEqual([]);
+  });
 });

packages/appkit-ui/src/react/charts/base.tsx

@@ -1,5 +1,5 @@
 // Type-only import: erased at compile time, does not pull the full echarts
-// bundle in. echarts-for-react's API is typed against this `ECharts` class.
+// bundle in. The `ECharts` type is used for the stored ECharts instance ref.
 import type { ECharts } from "echarts";
 import {
   BarChart,
@@ -50,6 +50,14 @@ import type {
 // toolbox, markLine), register it here. Consumers passing custom `options`
 // that need extra features can register them in their own app via
 // `import { use } from "echarts/core"`.
+//
+// Note: tooltip-driven axisPointer is bundled with `TooltipComponent`, so no
+// explicit AxisPointerComponent registration is needed.
+//
+// This `use()` call must stay co-located in the same module as `BaseChart`:
+// `package.json#sideEffects` declares JS modules side-effect free, so moving
+// registration to a separate import-for-side-effect module would let bundlers
+// drop it during tree-shaking.
 echarts.use([
   // Series types used by the option builders
   LineChart, // line + area charts (area = line with areaStyle)
@@ -140,7 +148,17 @@ export interface BaseChartProps {
   min?: number;
   /** Max value for heatmap color scale */
   max?: number;
-  /** Additional ECharts options to merge */
+  /**
+   * Additional ECharts options to merge.
+   *
+   * Only the built-in feature set is registered by this package, so options
+   * referencing extra ECharts features (`dataZoom`, `toolbox`, `markLine`,
+   * `markArea`, `graphic`, `dataset`, top-level `axisPointer`, ...) require
+   * registering them in your app via `import { use } from "echarts/core"`.
+   * This only works when your `echarts` resolves to the same module
+   * instance/version as this package's (the registry is a singleton;
+   * duplicate echarts copies won't share registrations).
+   */
   options?: Record<string, unknown>;
   /** Additional CSS classes */
   className?: string;