@alfadocs/ui-kit 1.1.0 → 1.2.0

package/dist/_chunks/sparkline-DJtZBe7O.js

@@ -0,0 +1,501 @@
+import { jsx as d, jsxs as D } from "react/jsx-runtime";
+import { forwardRef as oe, useId as de, useMemo as A, useRef as S, useState as Z, useEffect as P, useImperativeHandle as ce } from "react";
+import { c as E } from "./index-D2ZczOXr.js";
+import { useTranslation as le } from "react-i18next";
+import ue from "react-apexcharts";
+import U from "apexcharts";
+import { g as J, u as pe } from "./apexcharts-theme-B_AxGC_h.js";
+import { m as me } from "./annotation-marker-CsUJGZjQ.js";
+import { u as he } from "./registry-DvAUVLHh.js";
+function fe(n) {
+  if (n.length < 2)
+    return { slope: 0, direction: "steady" };
+  const r = n.length, c = (r - 1) / 2, s = n.reduce((a, i) => a + i, 0) / r;
+  let o = 0, h = 0;
+  for (let a = 0; a < r; a++) {
+    const i = a - c;
+    o += i * (n[a] - s), h += i * i;
+  }
+  const p = h === 0 ? 0 : o / h, y = 0.01 * (Math.max(...n) - Math.min(...n) || 1), m = Math.abs(p) < y ? "steady" : p > 0 ? "increasing" : "decreasing";
+  return { slope: p, direction: m };
+}
+const ge = {
+  id: "sparkline",
+  capabilities: [],
+  state: {},
+  actions: {
+    update_series: {
+      // Replacing the rendered series mutates what the chart displays — write,
+      // not read.
+      safety: "write",
+      argsType: "{ data: number[] }",
+      argsSchema: {
+        type: "object",
+        properties: {
+          data: {
+            type: "array",
+            items: { type: "number" },
+            description: "The new data points to render."
+          }
+        },
+        required: ["data"]
+      },
+      idempotent: !0,
+      descriptionKey: "ui.agent.sparkline.actions.updateSeries",
+      description: "Replace the sparkline data without remounting.",
+      invoke: (n, r) => {
+        n.updateSeries(r.data);
+      }
+    },
+    export_png: {
+      // Pure getter — returns an image of the current chart, no state change.
+      safety: "read",
+      returns: "string",
+      returnsSchema: {
+        type: "string",
+        description: "A PNG image of the sparkline encoded as a data URI."
+      },
+      descriptionKey: "ui.agent.sparkline.actions.exportPng",
+      description: "Return a PNG data URI of the sparkline.",
+      invoke: (n) => n.dataURI()
+    },
+    select_annotation: {
+      // Routes the host somewhere — the same thing a pointer press on the
+      // annotation's band does. Nothing in the chart changes, but the host's
+      // surface does, so it is not a read.
+      safety: "write",
+      argsType: "{ annotationId: string }",
+      argsSchema: {
+        type: "object",
+        properties: {
+          annotationId: {
+            type: "string",
+            description: "The annotation's id, as carried by data-annotation-hit-id on the pressable band. The decorative drawn marker carries the same value as data-annotation-id, but is not selectable."
+          }
+        },
+        required: ["annotationId"]
+      },
+      idempotent: !0,
+      descriptionKey: "ui.agent.sparkline.actions.selectAnnotation",
+      description: "Select a drawn annotation, as pressing its band would. No-op unless the host wired onAnnotationSelect and the id names an annotation that is currently drawn.",
+      invoke: (n, r) => {
+        n.selectAnnotation(r.annotationId);
+      }
+    }
+  },
+  domHooks: {
+    root: { attr: "data-component", value: "sparkline" },
+    instanceId: {
+      attr: "data-component-id",
+      sourceProp: "id",
+      description: "Sourced from the id prop."
+    }
+  }
+}, Q = E("ds:relative ds:inline-block ds:w-full", {
+  variants: {
+    size: {
+      xs: "ds:h-6",
+      sm: "ds:h-8",
+      md: "ds:h-10",
+      // Applied when an explicit `height` prop is given: the wrapper
+      // grows with the svg instead of clipping at the size's fixed height.
+      auto: ""
+    }
+  },
+  defaultVariants: { size: "md" }
+}), X = E("", {
+  variants: {
+    tone: {
+      neutral: "ds:[--annotation-color:var(--muted-foreground)]",
+      info: "ds:[--annotation-color:var(--info)]",
+      success: "ds:[--annotation-color:var(--success)]",
+      /* `--warning-readable`, not `--warning`: a 1.5px dashed line is a
+       * non-text graphic (WCAG 1.4.11, 3:1), and yellow-500 is ~1.6:1 on a
+       * light card. The token aliases back to `--warning` in dark. */
+      warning: "ds:[--annotation-color:var(--warning-readable)]",
+      error: "ds:[--annotation-color:var(--destructive)]",
+      accent: "ds:[--annotation-color:var(--accent)]"
+    }
+  },
+  defaultVariants: { tone: "neutral" }
+}), ve = E(
+  "ds:pointer-events-none ds:absolute ds:inset-x-[2px]",
+  {
+    variants: {
+      size: {
+        xs: "ds:inset-y-[-10px]",
+        sm: "ds:inset-y-[-6px]",
+        md: "ds:inset-y-[-2px]",
+        auto: "ds:inset-y-0"
+      }
+    },
+    defaultVariants: { size: "md" }
+  }
+), ye = {
+  increasing: "↑",
+  decreasing: "↓",
+  steady: "→"
+}, be = {
+  xs: 24,
+  sm: 32,
+  md: 40
+}, k = 2, Y = 2.5, ke = 44;
+function we(n, r) {
+  const c = n.map((s) => ({
+    annotation: s,
+    centre: ee(s.position) * r
+  })).sort((s, o) => s.centre - o.centre);
+  return c.map((s, o) => {
+    const h = c[o - 1], p = c[o + 1], w = h ? (h.centre + s.centre) / 2 : 0, y = p ? (s.centre + p.centre) / 2 : r, m = Math.max(0, w), a = Math.min(r, y), i = Math.min(ke, Math.max(0, a - m)), x = Math.min(
+      Math.max(s.centre - i / 2, m),
+      a - i
+    );
+    return { annotation: s.annotation, x, width: i };
+  });
+}
+function ee(n) {
+  return Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+}
+function xe(n) {
+  return n.filter((r) => r != null);
+}
+function Ie() {
+  return typeof window < "u" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+const Ne = oe(
+  ({
+    id: n,
+    data: r,
+    variant: c = "line",
+    size: s = "md",
+    label: o,
+    color: h,
+    showEndpoint: p = !1,
+    showTooltip: w = !1,
+    width: y,
+    height: m,
+    annotations: a,
+    onAnnotationSelect: i,
+    className: x,
+    ...V
+  }, te) => {
+    var q;
+    const { t: f, i18n: $ } = le(), j = de(), b = A(
+      () => `sparkline-${j.replace(/[^a-zA-Z0-9-_]/g, "")}`,
+      [j]
+    ), I = S(null), [O, ne] = Z(0), l = A(() => xe(r), [r]), { direction: C } = fe(l), B = A(() => {
+      const e = a && a.length > 0 ? f("sparkline.annotations", {
+        list: a.map((v) => v.label).join(", ")
+      }) : "", t = (v) => e ? `${v}. ${e}` : v;
+      if (l.length === 0)
+        return t(f("sparkline.noData", "No data"));
+      const u = (v) => new Intl.NumberFormat($.language).format(v), g = f(`sparkline.direction.${C}`), R = {
+        min: u(Math.min(...l)),
+        max: u(Math.max(...l)),
+        current: u(l[l.length - 1]),
+        direction: g
+      };
+      return t(o ? f("sparkline.summary", { label: o, ...R }) : f("sparkline.summaryNoLabel", R));
+    }, [l, a, o, C, $.language, f]), [N, ae] = Z(
+      () => {
+        try {
+          return J();
+        } catch {
+          return {};
+        }
+      }
+    );
+    P(() => {
+      let e;
+      const t = new MutationObserver(() => {
+        clearTimeout(e), e = setTimeout(() => {
+          try {
+            ae(J());
+          } catch {
+          }
+        }, 50);
+      });
+      return t.observe(document.documentElement, {
+        attributes: !0,
+        attributeFilter: ["class"]
+      }), () => {
+        clearTimeout(e), t.disconnect();
+      };
+    }, []), P(() => {
+      const e = I.current;
+      if (!e) return;
+      const t = new ResizeObserver((u) => {
+        const g = u[0];
+        g && ne(Math.floor(g.contentRect.width));
+      });
+      return t.observe(e), () => t.disconnect();
+    }, []), pe(I);
+    const M = S(i);
+    P(() => {
+      M.current = i;
+    }, [i]);
+    const F = S(a);
+    F.current = a;
+    const z = A(
+      () => ({
+        updateSeries(e) {
+          var t;
+          (t = U.getChartByID(b)) == null || t.updateSeries([{ data: e }]);
+        },
+        updateOptions(e) {
+          var t;
+          (t = U.getChartByID(b)) == null || t.updateOptions(e);
+        },
+        async dataURI() {
+          const e = U.getChartByID(b);
+          return e ? (await e.dataURI()).imgURI : "";
+        },
+        selectAnnotation(e) {
+          var u, g;
+          (u = F.current) != null && u.some((R) => R.id === e) && ((g = M.current) == null || g.call(M, e));
+        }
+      }),
+      [b]
+    );
+    ce(te, () => z, [z]), he(ge, z, n);
+    const _ = h ?? ((q = N.colors) == null ? void 0 : q[0]) ?? "currentColor";
+    if (l.length === 0)
+      return /* @__PURE__ */ d(
+        "div",
+        {
+          ref: I,
+          role: "img",
+          "aria-label": B,
+          dir: "ltr",
+          className: Q({
+            size: m !== void 0 ? "auto" : s,
+            className: x
+          }),
+          "data-component": "sparkline",
+          "data-component-id": n,
+          ...V
+        }
+      );
+    const G = Ie(), H = r.length > l.length, L = H ? r.flatMap((e, t) => e == null ? [] : [{ x: t, y: e }]) : l, re = {
+      ...N,
+      chart: {
+        ...N.chart,
+        id: b,
+        type: c,
+        sparkline: { enabled: !0 },
+        toolbar: { show: !1 },
+        animations: {
+          enabled: !G,
+          // A gapped series is re-rendered as {x, y} pairs, and Apex's
+          // update tween interpolates between the old and new paths point by
+          // point. Across a width change the two have different lengths and
+          // the tween emits `d="… NaN …"` for a few frames. The finished
+          // render is correct either way; switching the tween off keeps the
+          // console clean.
+          dynamicAnimation: { enabled: !G && !H }
+        },
+        zoom: { enabled: !1 },
+        parentHeightOffset: 0
+      },
+      colors: [_],
+      stroke: {
+        curve: "smooth",
+        width: c === "bar" ? 0 : 2
+      },
+      fill: {
+        opacity: c === "area" ? 0.15 : 1
+      },
+      xaxis: {
+        crosshairs: { show: !1 },
+        // Pin the extent to the slot count so a gap at either end still holds
+        // its place — otherwise the plot would rescale to the measurements
+        // and the annotation fractions would no longer mean the same thing.
+        ...H ? { type: "numeric", min: 0, max: r.length - 1 } : {}
+      },
+      tooltip: { enabled: w },
+      markers: p ? {
+        size: [0],
+        discrete: [
+          {
+            // An index into the SERIES, whose holes have already been
+            // removed — so this is the last MEASURED point, never a slot
+            // the parameter was not measured at.
+            seriesIndex: 0,
+            dataPointIndex: L.length - 1,
+            fillColor: _,
+            strokeColor: _,
+            size: 4
+          }
+        ]
+      } : { size: 0 },
+      grid: {
+        ...N.grid,
+        show: !1,
+        // ApexCharts grid.padding uses physical keys (not CSS logical properties).
+        // The chart wrapper enforces dir="ltr" so these always resolve correctly.
+        padding: {
+          top: k,
+          right: k,
+          bottom: k,
+          left: k
+        }
+      }
+    }, se = y ?? (O > 0 ? O : "100%"), ie = m ?? be[s ?? "md"], T = a != null && a.length ? a : void 0, W = O - k * 2, K = i && T && W > 0 ? we(T, W) : void 0;
+    return /* @__PURE__ */ D(
+      "div",
+      {
+        ref: I,
+        role: "img",
+        "aria-label": B,
+        dir: "ltr",
+        className: Q({
+          size: m !== void 0 ? "auto" : s,
+          className: x
+        }),
+        "data-component": "sparkline",
+        "data-component-id": n,
+        ...V,
+        children: [
+          /* @__PURE__ */ d(
+            ue,
+            {
+              type: c,
+              series: [{ data: L }],
+              options: re,
+              width: se,
+              height: ie,
+              "aria-hidden": "true"
+            }
+          ),
+          T && /* Drawn over the plot rather than through ApexCharts' own xaxis
+          annotations: a fraction of the measured extent is the one
+          positioning rule that survives series of different lengths, which
+          is what makes a column of sparklines share an x. */
+          /* The inset lives on a div: an <svg> is a replaced element, so
+             left+right do not size it and it would fall back to its intrinsic
+             300px. The div is the plot box; the svg fills it. The 2px MUST
+             equal PLOT_EDGE_PADDING — Tailwind needs a static literal, so the
+             two cannot share one source; change them together or the first and
+             last annotation drift off the first and last data point. */
+          /* @__PURE__ */ d("div", { className: "ds:pointer-events-none ds:absolute ds:inset-y-0 ds:inset-x-[2px]", children: /* @__PURE__ */ d(
+            "svg",
+            {
+              "aria-hidden": "true",
+              focusable: "false",
+              "data-testid": "sparkline-annotations",
+              className: "ds:size-full",
+              children: T.map((e) => {
+                const t = ee(e.position);
+                return (
+                  /* A nested viewport placed at a percentage of the plot: the
+                   one positioning rule that needs no measurement, so a column
+                   of sparklines shares an x whatever their widths. */
+                  /* @__PURE__ */ D(
+                    "svg",
+                    {
+                      x: `${t * 100}%`,
+                      y: "0",
+                      width: "1",
+                      height: "100%",
+                      overflow: "visible",
+                      "data-annotation-id": e.id,
+                      "data-annotation-position": t,
+                      className: X({ tone: e.tone }),
+                      children: [
+                        /* @__PURE__ */ d(
+                          "line",
+                          {
+                            x1: 0,
+                            x2: 0,
+                            y1: 0,
+                            y2: "100%",
+                            className: "ds:[stroke:var(--annotation-color)] ds:[stroke-dasharray:2_3] ds:[stroke-width:1]"
+                          }
+                        ),
+                        /* @__PURE__ */ d(
+                          "path",
+                          {
+                            d: me(
+                              e.shape ?? "diamond",
+                              0,
+                              Y,
+                              Y
+                            ),
+                            className: "ds:[fill:var(--annotation-color)]"
+                          }
+                        )
+                      ]
+                    },
+                    e.id
+                  )
+                );
+              })
+            }
+          ) }),
+          K && i && /* Sized in px, not percentages: 44px is a measurement, not a
+          fraction of a box the reader can resize. `pointer-events-none`
+          holds all the way down to the bands, so the only live pixels are
+          the 44px each annotation owns. */
+          /* @__PURE__ */ d(
+            "div",
+            {
+              className: ve({
+                size: m !== void 0 ? "auto" : s
+              }),
+              children: /* @__PURE__ */ d(
+                "svg",
+                {
+                  "aria-hidden": "true",
+                  focusable: "false",
+                  "data-testid": "sparkline-annotation-hits",
+                  className: "ds:size-full",
+                  children: K.map(({ annotation: e, x: t, width: u }) => /* @__PURE__ */ D(
+                    "g",
+                    {
+                      "data-annotation-hit-id": e.id,
+                      onClick: () => i(e.id),
+                      className: `ds:group ds:pointer-events-auto ds:cursor-pointer ${X(
+                        { tone: e.tone }
+                      )}`,
+                      children: [
+                        /* @__PURE__ */ d("title", { children: f("sparkline.annotationAction", {
+                          label: e.label
+                        }) }),
+                        /* @__PURE__ */ d(
+                          "rect",
+                          {
+                            x: t,
+                            y: 0,
+                            width: u,
+                            height: "100%",
+                            className: "ds:[fill:var(--annotation-color)] ds:opacity-0 ds:transition-opacity ds:duration-[var(--animation-duration)] ds:motion-reduce:transition-none ds:group-hover:opacity-20"
+                          }
+                        )
+                      ]
+                    },
+                    e.id
+                  ))
+                }
+              )
+            }
+          ),
+          p && /* @__PURE__ */ d(
+            "span",
+            {
+              "aria-hidden": "true",
+              className: "ds:pointer-events-none ds:absolute ds:end-0 ds:top-0 ds:text-[length:var(--font-size-xs)] ds:leading-none",
+              children: ye[C]
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+Ne.displayName = "Sparkline";
+export {
+  Ne as S,
+  ge as s,
+  fe as u
+};
+//# sourceMappingURL=sparkline-DJtZBe7O.js.map

package/dist/agent-catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "1.1.0",
+  "packageVersion": "1.2.0",
   "components": [
     {
       "kind": "component",
@@ -6720,6 +6720,12 @@
           "type": "boolean",
           "description": "Whether the current user may write clinical notes (the practice_add_clinical_note permission gate).",
           "descriptionKey": "ui.agent.notesPanel.state.canAddClinical"
+        },
+        {
+          "name": "currentNoteId",
+          "type": "string | null",
+          "description": "Id of the note the host has addressed — the one marked, scrolled to and focused. Null when none is. An id only, never note content.",
+          "descriptionKey": "ui.agent.notesPanel.state.currentNoteId"
         }
       ],
       "actions": [
@@ -11099,6 +11105,26 @@
           },
           "description": "Return a PNG data URI of the sparkline.",
           "descriptionKey": "ui.agent.sparkline.actions.exportPng"
+        },
+        {
+          "name": "select_annotation",
+          "safety": "write",
+          "argsType": "{ annotationId: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "annotationId": {
+                "type": "string",
+                "description": "The annotation's id, as carried by data-annotation-hit-id on the pressable band. The decorative drawn marker carries the same value as data-annotation-id, but is not selectable."
+              }
+            },
+            "required": [
+              "annotationId"
+            ]
+          },
+          "idempotent": true,
+          "description": "Select a drawn annotation, as pressing its band would. No-op unless the host wired onAnnotationSelect and the id names an annotation that is currently drawn.",
+          "descriptionKey": "ui.agent.sparkline.actions.selectAnnotation"
         }
       ],
       "domHooks": {

package/dist/agent-i18n/en.json

@@ -688,7 +688,8 @@
     "notesPanel": {
       "state": {
         "notes": "Timeline note ids + pinned / flagged / clinical flags. Never the note body or author (both PHI).",
-        "canAddClinical": "Whether the current user may write clinical notes (the practice_add_clinical_note permission gate)."
+        "canAddClinical": "Whether the current user may write clinical notes (the practice_add_clinical_note permission gate).",
+        "currentNoteId": "Id of the note the host has addressed — the one marked, scrolled to and focused. Null when none is. An id only, never note content."
       },
       "actions": {
         "addNote": "Compose and commit a new note. A clinical note requires the clinical-note permission (read canAddClinical first).",
@@ -1137,7 +1138,8 @@
     "sparkline": {
       "actions": {
         "updateSeries": "Replace the sparkline data without remounting.",
-        "exportPng": "Return a PNG data URI of the sparkline."
+        "exportPng": "Return a PNG data URI of the sparkline.",
+        "selectAnnotation": "Select a drawn annotation, as pressing its band would. No-op unless the host wired onAnnotationSelect and the id names an annotation that is currently drawn."
       }
     },
     "stepperAccordion": {

package/dist/components/notes-panel/index.js

@@ -1,4 +1,4 @@
-import { N as a } from "../../_chunks/notes-panel-CTcOLLVo.js";
+import { N as a } from "../../_chunks/notes-panel-CCz0J140.js";
 export {
   a as NotesPanel
 };

package/dist/components/notes-panel/notes-panel.d.ts

@@ -1,8 +1,14 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
 import type { ClinicalNoteCardProps } from '../clinical-note-card';
 import type { RichTextEditorProps, RichTextEditorToolbar, RedactorFactory } from '../rich-text-editor';
-/** One note in the panel — the data subset of `ClinicalNoteCard`. */
-export type NotesPanelNote = Pick<ClinicalNoteCardProps, 'id' | 'dateIso' | 'createdAtIso' | 'author' | 'clinical' | 'attachedTo' | 'content' | 'contentFormat' | 'pinned' | 'flagged'>;
+/**
+ * One note in the panel — the data subset of `ClinicalNoteCard`.
+ *
+ * `aria-label` names the card for assistive tech. Set it whenever a row is not
+ * a clinical note: the card's fallback name is "Clinical note", so an entry
+ * that is something else (a dated event, an import) is announced as one.
+ */
+export type NotesPanelNote = Pick<ClinicalNoteCardProps, 'id' | 'dateIso' | 'createdAtIso' | 'author' | 'clinical' | 'attachedTo' | 'content' | 'contentFormat' | 'pinned' | 'flagged' | 'aria-label'>;
 /**
  * Curated agent handle for NotesPanel. Reads the note timeline's STRUCTURE
  * (ids + pinned / flagged / clinical flags — never the note body or author,
@@ -21,6 +27,8 @@ export interface NotesPanelHandle {
     canAddNote: () => boolean;
     /** Whether clinical notes may be written (the permission gate). */
     canAddClinical: () => boolean;
+    /** Id of the note the host has addressed, or null when none is. */
+    getCurrentNoteId: () => string | null;
     /** Commit a new note with explicit content (mirrors the composer's submit). */
     addNote: (submission: NotesPanelSubmission) => void;
     /** Toggle a note's pinned state (mirrors onTogglePin). */
@@ -45,6 +53,41 @@ export interface NotesPanelProps extends Omit<HTMLAttributes<HTMLElement>, 'titl
     notes: NotesPanelNote[];
     /** Commit a new note. Omit to hide the composer (read-only timeline). */
     onAddNote?: (submission: NotesPanelSubmission) => void;
+    /**
+     * The note the reader ASKED for, addressed by id from somewhere else in the
+     * record — a marker in a chart, a row in a grid, an agent. The panel marks
+     * it, scrolls it to the middle of its own scroll region and moves focus to
+     * it, and renders it unclamped so the thing that was asked for is readable
+     * in full without a second click.
+     *
+     * Opening a panel is not the same as answering a question: a rail's
+     * `setActiveTool` moves no focus and announces nothing, so a control whose
+     * name promises "in the notes panel" produces no perceivable change for a
+     * keyboard or screen-reader reader unless the panel lands them on the note.
+     * That is what this prop is for; without it, a host has to reach into the
+     * panel's DOM to do the same job.
+     *
+     * Marked on three channels, never colour alone (WCAG 1.4.1): a solid
+     * inline-start bar the other notes do not have, a tinted gutter, and
+     * `aria-current` plus a visually-hidden sentence naming the mark.
+     *
+     * Ids that match no note are ignored. To address the SAME note twice — the
+     * reader pressing the same marker again after scrolling away — bump
+     * `currentNoteKey` alongside it; this prop alone is a value, not a request.
+     */
+    currentNoteId?: string;
+    /**
+     * Bump on every address to re-scroll and re-focus the note in `currentNoteId`
+     * even when the id has not changed.
+     *
+     * Addressing is a request, not a value: a reader who presses the same marker
+     * a second time (having scrolled away, or having moved focus off the note) is
+     * asking to be taken back, and a control whose name promises the notes panel
+     * must do something perceivable every time it is pressed. Without this the
+     * second press is inert — the panel is already showing that note, so nothing
+     * re-runs. Hosts increment a counter in the same handler that opens the tool.
+     */
+    currentNoteKey?: string | number;
     /**
      * `'rich'` (default) mounts the kit `RichTextEditor` (Redactor; degrades to a
      * textarea where Redactor is absent). `'plain'` keeps a simple `TextArea` for

package/dist/components/sparkline/index.js

@@ -1,4 +1,4 @@
-import { S as r, s, u as n } from "../../_chunks/sparkline-DLq7xwic.js";
+import { S as r, s, u as n } from "../../_chunks/sparkline-DJtZBe7O.js";
 export {
   r as Sparkline,
   s as sparklineAgent,

package/dist/components/sparkline/sparkline.d.ts

@@ -9,6 +9,10 @@ export interface SparklineHandle {
     updateSeries: (data: (number | null)[]) => void;
     updateOptions: (opts: ApexCharts.ApexOptions) => void;
     dataURI: () => Promise<string>;
+    /** Fire the host's annotation handler for `id`, as a pointer press on that
+     * annotation's band would. No-op when the sparkline is not selectable, or
+     * when `id` names no currently drawn annotation. */
+    selectAnnotation: (id: string) => void;
 }
 /** Semantic tint for an annotation. Decorative reinforcement of `shape` —
  * never the only channel carrying which event this is. */
@@ -66,6 +70,26 @@ export interface SparklineProps extends Omit<HTMLAttributes<HTMLDivElement>, 'ro
     /** Vertical reference lines dropped across the plot. Omitted = none, so
      * every existing consumer is unaffected. */
     annotations?: readonly SparklineAnnotation[];
+    /**
+     * Make the drawn annotations POINTER-selectable — a press anywhere in an
+     * annotation's 44px band calls this with its `id`. Omitted (the default, and
+     * what every consumer before 1.1.0 gets) leaves them decorative, which is
+     * what a dashboard sparkline wants: a trend thumbnail should not be a click
+     * target.
+     *
+     * NOT a keyboard route, and deliberately so. The sparkline is `role="img"`,
+     * whose descendants are not exposed to assistive technology at all, so a
+     * focusable control drawn inside it would be a tab stop with no accessible
+     * name. The host MUST therefore already offer a keyboard control that does
+     * the same thing for the same annotation (WCAG 2.1.1) — this is a pointer
+     * shortcut to that control, never the only way in.
+     *
+     * The 44px band is delivered by the `size` variants only. Pass an explicit
+     * `height` and the pointer layer falls back to the drawn height, so
+     * `height={20}` yields a 20px-tall target — below even WCAG 2.5.8. Under
+     * `.theme-accessible`, where `--min-target-size` is 48px, the band stays 44.
+     */
+    onAnnotationSelect?: (annotationId: string) => void;
 }
 export declare const Sparkline: import("react").ForwardRefExoticComponent<SparklineProps & import("react").RefAttributes<SparklineHandle>>;
 export {};