@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/HighlightCard/HighlightCard.d.ts

@@ -0,0 +1,202 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { HighlightBaseline, HighlightCardLabels, HighlightCardSize, HighlightCardStatus, HighlightDeltaMode, HighlightDriver, HighlightGoodDirection, HighlightMark, HighlightPeerMode, HighlightPoint, HighlightScale, HighlightSection, HighlightSeverityThresholds, HighlightWindow } from "./HighlightCard.model.js";
+import { ReactNode } from "react";
+import { BoxProps } from "@arcfusionz/arc-primitive-ui";
+import { TopLevelSpec } from "vega-lite";
+import { Result } from "vega-embed";
+//#region src/components/HighlightCard/HighlightCard.d.ts
+interface HighlightCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** The metric's name — the panel's heading. Pass `name` too when this is not plain text. */
+  label: ReactNode;
+  /** Plain-text name used in the generated descriptions and control labels. Defaults to `label` when it is a string. */
+  name?: string;
+  /** Definition of the metric, shown in a tooltip behind an info control beside the label and exposed to assistive technology as the control's description. */
+  hint?: string;
+  /**
+   * The metric's readings: `{ x, y }` where `x` is a `Date`, an ISO string, a
+   * number or a period label, and `y` the value or `null` for a period with no
+   * reading (drawn as a gap, never as zero). Rows are sorted along the axis
+   * for a temporal or quantitative series; an ordinal series keeps the order
+   * you pass, which IS its axis. Pass `[]` while loading to reserve the
+   * panel's height.
+   */
+  series: readonly HighlightPoint[];
+  /**
+   * The window under analysis: `{ start, end, label? }` in the series' own `x`
+   * type. Each bound snaps inward to the nearest finite reading, so a window
+   * may begin or end on a gap. A window without two distinct readings is
+   * unresolved — the panel says so and stamps `data-window="unresolved"`
+   * rather than inventing a change. Pass stable values (ISO strings or
+   * memoized `Date`s): the window is re-resolved when they change.
+   */
+  highlight: HighlightWindow;
+  /**
+   * What drove the change: `{ key?, label, contribution }` — the signed amount
+   * each contributor added, in the value's own units — or `{ from, to }` per
+   * contributor, from which the contribution is the difference. Whatever the
+   * parts do not account for is drawn and named as an explicit `Unexplained`
+   * row, so the decomposition always reconciles with the window's own change
+   * or admits that it does not. Omitted, the `drivers` section is not drawn.
+   */
+  drivers?: readonly HighlightDriver[];
+  /**
+   * Which analysis sections the panel draws, in this order: `context` (the
+   * window inside the whole series), `peers` (how its change compares with
+   * every comparable window) and `drivers` (what the change decomposes into).
+   * Default all three; a section with no data to draw is skipped. Stamped as
+   * `data-sections`.
+   */
+  sections?: readonly HighlightSection[];
+  /**
+   * Which comparable windows the change is placed among. `rolling` (default)
+   * takes a window of the same length at every offset — the most peers, but
+   * overlapping windows share readings, so the spread is narrower than
+   * independent sampling would give. `adjacent` tiles non-overlapping windows
+   * aligned to the highlight's own start: fewer peers, and the statistically
+   * honest set. Either way the panel reports a comparison, never a
+   * significance test. Stamped as `data-peers`.
+   */
+  peerMode?: HighlightPeerMode;
+  /**
+   * How the placement is expressed. `sigma` (default) reports the typical
+   * change, the standard deviation and the window's distance from the mean in
+   * them, with the typical range as mean ± 1 sd. `percentile` reports where
+   * the change falls in the sorted peers, with the typical range as the 10th
+   * to 90th percentile. Stamped as `data-baseline`.
+   */
+  baseline?: HighlightBaseline;
+  /**
+   * Fewer comparable windows than this and the `peers` section is not drawn —
+   * the panel says there are not enough instead of calling one window out of
+   * three "extreme". Default 4.
+   */
+  minPeers?: number;
+  /**
+   * Where the verdict boundaries fall: compared against the absolute distance
+   * from the mean in standard deviations for the `sigma` baseline (defaults 1
+   * / 2 / 3), and against the distance from the median percentile, 0–50, for
+   * `percentile` (defaults 40 / 45 / 49 — outside p10–p90, p5–p95, p1–p99). A
+   * documented heuristic on the spread of comparable windows, not a test.
+   */
+  severityThresholds?: HighlightSeverityThresholds;
+  /**
+   * Fold every driver past this count (by absolute contribution) into one
+   * `Other` row whose contribution is their sum — honest only for additive
+   * measures, which passing this asserts. Stamped as `data-folded`.
+   */
+  driverLimit?: number;
+  /**
+   * How far the contributions may miss the window's own change and still
+   * reconcile, as a fraction of that change. Inside it the panel says the
+   * parts sum to the total; outside it an `Unexplained` row is drawn. Default
+   * `0.005`. Stamped as `data-reconciles`.
+   */
+  driverTolerance?: number;
+  /**
+   * Key of the driver the reader has drilled into, controlled — pair with
+   * `onDriverSelect`. Omit for the uncontrolled panel
+   * (`defaultSelectedDriver`, else none).
+   */
+  selectedDriver?: string | null;
+  /** The drilled driver on first render when `selectedDriver` is uncontrolled. */
+  defaultSelectedDriver?: string;
+  /**
+   * Called with a driver's key when the reader picks it. Setting it makes each
+   * driver row a real button — the keyboard path to a drill-through, since
+   * Vega has none — and the bars forward their own clicks to it.
+   */
+  onDriverSelect?: (key: string) => void;
+  /** `line` (default, may crop), `area` (zero baseline) or `bar` (zero baseline, discrete periods) for the context plot. */
+  mark?: HighlightMark;
+  /** Y-scale baseline for a `line` context plot: `auto` (default) fits the data range and reads for shape; `zero` includes zero. Areas and bars always include zero. */
+  scale?: HighlightScale;
+  /** Draw the context plot's axes with grid lines and labels. Default `true`; `false` shrinks it toward a sparkline — the tables still carry every value. */
+  axes?: boolean;
+  /** Context-plot height in pixels, axes included. Defaults per `size` (132 / 176 / 216), plus 24 when `axes` draws the x labels. */
+  contextHeight?: number;
+  /** `percent` (default) is relative change; `absolute` is the difference in the value's units — percentage points for a percent format. Also the unit of the peer strip's axis. */
+  deltaMode?: HighlightDeltaMode;
+  /**
+   * Which direction is good. Drives the polarity of the headline, the window's
+   * hue, the marked peer and every driver bar: `up` (revenue), `down` (churn,
+   * latency, cost) or `none` (headcount — everything stays neutral). Default
+   * `up`.
+   */
+  goodDirection?: HighlightGoodDirection;
+  /**
+   * Number format for every reading, contribution, axis, tooltip and table —
+   * one grammar so nothing rounds two ways: `number[:digits]`, `integer`,
+   * `compact[:digits]`, `percent[:digits]`, `currency:CODE[:digits|compact]`.
+   * Default `compact`.
+   */
+  format?: string;
+  /** Custom formatter for values. Takes precedence over `format` everywhere a reading is rendered. */
+  formatValue?: (value: number) => string;
+  /** Unit shown after the readings line in the muted role (`ms`, `req/s`). Prefer `format="currency:…"` for money. */
+  unit?: ReactNode;
+  /** Period granularity of temporal `x` values for the axis, tooltips and tables. Inferred from the spacing when omitted. */
+  granularity?: ArcTimeGranularity;
+  /**
+   * The takeaway in a sentence, rendered beside the AI mark under the
+   * sections — the insight slot. Wrap values in `<strong>` to set them in
+   * bold. Omitted, the panel generates one from the window, its placement and
+   * its largest driver; pass `null` or `false` to render none.
+   */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with a series already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: HighlightCardStatus;
+  /** The consumer's filter is active — no readings then reads as no-match rather than empty, with a clear-filters action when `onClearFilters` is set. */
+  filtered?: boolean;
+  /** The data is older than the product's freshness rule (TanStack Query's `isStale`). Shows a badge and stamps `data-stale`. */
+  stale?: boolean;
+  /** When the data was last true. Rendered as an "as of" line and included in the description. */
+  updatedAt?: Date | string | number;
+  /**
+   * How `updatedAt` is written, as a time-grammar granularity — `day`
+   * (default), `datetime`, `time`, `month`, `year` — or a formatter for a
+   * custom form. Applies to the as-of line and the description alike, in the
+   * panel's `locale` and `timeZone`.
+   */
+  updatedAtFormat?: ArcTimeGranularity | ((date: Date) => string);
+  /** Recovery action for the error state; renders a retry button when set. */
+  onRetry?: () => void;
+  /** Recovery action for the no-match state; renders a clear-filters button when set. */
+  onClearFilters?: () => void;
+  /** Density: `sm` for dense grids, `md` (default), `lg` for a hero panel. Scales type, padding, plot heights and the driver row step. */
+  size?: HighlightCardSize;
+  /** Heading level of the label for the document outline. Default 3 — panels usually sit under a page's h2; the section headings take the next level down. */
+  titleLevel?: 2 | 3 | 4 | 5 | 6;
+  /** BCP 47 locale for every number and date. Defaults to the runtime's. Thai products on the Gregorian calendar pass `th-TH-u-ca-gregory`. */
+  locale?: string;
+  /** IANA time zone for dates. Defaults to the runtime's — pass it for deterministic output and single-business-zone reporting. */
+  timeZone?: string;
+  /** Overrides for every rendered or announced string. */
+  labels?: Partial<HighlightCardLabels>;
+  /** Replaces the generated accessible description of the whole panel (the figure's `aria-describedby` text). */
+  description?: string;
+  /** Trailing header slot — a ghost `Button` or `Menu` for drill-through, export, or settings. */
+  action?: ReactNode;
+  /** Open the data popover on first render, anchored to the panel. */
+  defaultTableOpen?: boolean;
+  /** Hide the header info button for the data popover. Only when another surface exposes the same values to keyboard and screen-reader users. */
+  hideTableToggle?: boolean;
+  /** Called with vega-embed's result once each plot mounts, with the section it belongs to — for `view` access in advanced compositions. */
+  onEmbed?: (result: Result, section: HighlightSection) => void;
+  /** Escape hatch: transform a plot's spec before it renders, by section. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec, section: HighlightSection) => TopLevelSpec;
+}
+/**
+ * A highlight-analysis panel: one window of a metric, established and
+ * explained. The change across the window is the headline; the window is
+ * painted inside the whole series; its change is placed among the changes of
+ * every comparable window as a strip plot with a typical range and a verdict;
+ * and the change is decomposed into signed driver contributions that reconcile
+ * with it — plus every loading, empty, error and stale state, layout-stable,
+ * with generated text equivalents and a table for every plot.
+ *
+ * Where `MetricCard variant="highlight"` asserts that a window moved and by
+ * how much, HighlightCard answers "is that unusual, and what drove it".
+ */
+declare const HighlightCard: import("react").ForwardRefExoticComponent<HighlightCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { HighlightCard, HighlightCardProps };