@svgrid/grid 3.0.0 → 3.0.2

package/dist/SvGridChart.svelte.d.ts

@@ -6,7 +6,17 @@
    * focus tooltips, a clickable legend that toggles series, optional data
    * labels, and an `onSelect` drill hook. No external charting dependency.
    */
-import { type ChartSpec, type ChartSelection } from './chart.js';
+import type { Snippet } from 'svelte';
+import { type ChartSpec, type ChartSelection, type ChartGeometry, type ChartScales } from './chart.js';
+/** What a custom mark is handed. `scales` is null on non-cartesian types. */
+type ChartRenderContext = {
+    geo: ChartGeometry;
+    /** Pixel x at the centre of category `i`. Null when there is no x axis. */
+    xOf: ChartScales['xOf'] | null;
+    /** Pixel y for a value. Null when there is no value axis. */
+    yOf: ChartScales['yOf'] | null;
+    scales: ChartScales | null;
+};
 type Props = {
     spec: ChartSpec;
     /** Show the (clickable) legend. Default true. */
@@ -40,6 +50,58 @@ type Props = {
      *  fit exactly - used by the docked panel to size the chart to its body. */
     width?: number;
     height?: number;
+    /**
+     * Draw your own marks in the chart's own coordinates - the custom-series
+     * seam. `underlay` paints beneath the built-in marks (bands, shaded
+     * regions, a background you want the bars to sit on); `overlay` paints
+     * above them but below the crosshair and the hit layer, so tooltips and
+     * clicks keep working over whatever you draw.
+     *
+     * Both receive the laid-out geometry and its scales, so a custom mark lands
+     * on exactly the axis the built-in ones did:
+     *
+     * ```svelte
+     * <SvChart {spec}>
+     *   {#snippet overlay({ geo, xOf, yOf })}
+     *     <circle cx={xOf(3)} cy={yOf(120)} r="5" fill="tomato" />
+     *   {/snippet}
+     * </SvChart>
+     * ```
+     *
+     * `xOf` / `yOf` are null for the types with no cartesian axes (pie, gauge,
+     * treemap, sankey, calendar, radar, funnel); `geo` is always there.
+     */
+    underlay?: Snippet<[ChartRenderContext]>;
+    overlay?: Snippet<[ChartRenderContext]>;
+    /**
+     * Let a reader pin annotations on the plot. Adds an "Annotate" toggle to
+     * the toolbar; while it is on, clicking the plot fires `onAnnotate` with
+     * the point that was clicked, and clicking an existing marker fires
+     * `onAnnotationRemove` with its index.
+     *
+     * The chart does NOT store them. It owns the gesture - which you cannot
+     * build from outside, because drag is already zoom and click is already
+     * drill - and hands back the data point; where the annotations live, and
+     * whether they survive a reload, is the host's business. Put what comes
+     * back into `spec.annotations` and they render like any other.
+     */
+    annotatable?: boolean;
+    /**
+     * A point the reader picked while annotating. It is a DATA point, not a
+     * pixel: annotate mode takes over the category gesture, so a note anchors
+     * to the category it was pinned on and stays there when the chart is
+     * re-laid-out, re-sorted or zoomed. That also means it works from the
+     * keyboard, since the category hit zones already navigate with arrows.
+     */
+    onAnnotate?: (at: {
+        /** The category picked, and its index. */
+        category: string;
+        index: number;
+        /** The value at that category on the first series. */
+        value: number;
+    }) => void;
+    /** An existing `spec.annotations` entry was clicked, by index. */
+    onAnnotationRemove?: (index: number) => void;
 };
 declare const SvGridChart: import("svelte").Component<Props, {}, "">;
 type SvGridChart = ReturnType<typeof SvGridChart>;