@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/InsightCard/InsightCard.d.ts

@@ -0,0 +1,161 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { InsightCardLabels, InsightCardSize, InsightCardStatus, InsightDeltaMode, InsightEvidence, InsightFeedback, InsightGoodDirection, InsightKind, InsightObservation, InsightPoint, InsightSeverity, InsightSeverityThresholds, InsightXType } from "./InsightCard.model.js";
+import { InsightAxes } from "./InsightCard.chart.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/InsightCard/InsightCard.d.ts
+interface InsightCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** What the finding is about — the measure, the slice, the subject. The panel's heading. Pass `name` too when this is not plain text. */
+  label: ReactNode;
+  /** Plain-text subject used in the generated descriptions and control labels. Defaults to `label` when it is a string. */
+  name?: string;
+  /**
+   * The finding itself, as a sentence — the card's primary content and the
+   * most prominent thing on it. Wrap the values in `<strong>`. Pass
+   * `statementText` too when this is not plain text, or the description
+   * falls back to a sentence generated from the observation.
+   */
+  statement?: ReactNode;
+  /** Plain-text form of `statement`, for the generated description. Defaults to `statement` when it is a string. */
+  statementText?: string;
+  /** What the finding means, shown in a tooltip behind a help control beside the label and exposed to assistive technology as its description. */
+  hint?: string;
+  /**
+   * What kind of finding this is. It drives the badge's word and glyph and
+   * nothing else — the encoding underneath never changes with the kind, so a
+   * rail of mixed kinds still reads as one medium. Stamped as `data-kind`.
+   */
+  kind?: InsightKind;
+  /**
+   * The finding's numbers: the reading it is about and what was expected of
+   * it. This is what makes the claim checkable — without it the card renders
+   * the statement as the assertion it is, with no evidence row and no plot.
+   */
+  observation?: InsightObservation | null;
+  /**
+   * The measure's history, for the evidence spark. `{ x, y }` at minimum;
+   * `expected`, `lower` and `upper` per point draw the corridor a detector
+   * that reports one per period produces. A reading the card has no value
+   * for is a gap, not a zero — omit `y` or pass `null`. Pass `[]` while
+   * loading, or for a finding with no history.
+   */
+  points?: readonly InsightPoint[];
+  /** Axis kind for `points`. Inferred from the first reading when omitted. */
+  xType?: InsightXType;
+  /**
+   * The evidence form. `auto` (default) takes the fullest the data supports —
+   * `spark` when there is history, then `range`, then `none`. Stamped as
+   * `data-evidence` with what was actually resolved.
+   */
+  evidence?: InsightEvidence;
+  /** Which axes the spark draws. `none` (default) is the sparkline convention: the key row above the plot carries the numbers. The range strip never draws one. */
+  axes?: InsightAxes;
+  /** Include zero in the spark's value scale. Default `false` — a line may crop, and the key row prints the readings. */
+  zeroScale?: boolean;
+  /**
+   * How much the finding matters — a different axis from polarity. Derived
+   * from how far the reading is from expectation, on whichever scale the
+   * detector's data establishes; pass it to override with a detector's own
+   * score. Stamped as `data-severity`.
+   */
+  severity?: InsightSeverity;
+  /**
+   * Overrides the severity ladder, **in the units of the active strength
+   * scale** — σ when the observation carries `sd` (defaults 2 and 3),
+   * half-widths of the expected range when it carries a band (1 and 2), a
+   * share of the expectation otherwise (0.1 and 0.25). Which one is active is
+   * stamped as `data-strength`.
+   */
+  severityThresholds?: InsightSeverityThresholds;
+  /** Which way is good for this measure: revenue up, churn down, headcount neither. Drives the delta's polarity and the marker's hue. Default `none`. */
+  goodDirection?: InsightGoodDirection;
+  /** How the deviation is written: `percent` (default) is relative to the expectation, `absolute` is the difference in the measure's own units. */
+  deltaMode?: InsightDeltaMode;
+  /** The measure's number grammar: `number[:digits]`, `integer`, `compact[:digits]`, `percent[:digits]`, `currency:CODE[:digits|compact]`. */
+  format?: string;
+  /** Custom formatter for every reading. Takes precedence over `format`. */
+  formatValue?: (value: number) => string;
+  /** Granularity for the period labels in the table, the tooltip and the description. Default `day`. */
+  granularity?: ArcTimeGranularity;
+  /** How the finding was made — "Seasonal decomposition", "3σ control chart", "Claude Opus 4.5". Rendered in the provenance line and read out in the description. */
+  method?: string;
+  /** How much the detector trusts the finding, 0–1. Rendered as a word and the number, never as a bare bar. */
+  confidence?: number;
+  /** How many readings the finding was made from. Rendered in the provenance line. */
+  sampleSize?: number;
+  /** When the finding was made — distinct from `updatedAt`, which is when the data was last true. */
+  detectedAt?: Date | string | number;
+  /** How `detectedAt` is written, in the card's `locale` and `timeZone`. Default `day`. */
+  detectedAtFormat?: ArcTimeGranularity | ((date: Date) => string);
+  /** This finding came from a model or a detector rather than a person; shows the AI mark beside the statement. Default `true`. */
+  generated?: boolean;
+  /** The transport's status. `loading` with a finding already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: InsightCardStatus;
+  /** The consumer's filter is active — no finding then reads as no-match rather than empty. */
+  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, in the card's `locale` and `timeZone`. Default `day`. */
+  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;
+  /** Renders the dismiss control in the header. The consumer removes the card — this card never hides itself. */
+  onDismiss?: () => void;
+  /** What the reader said about the finding, controlled — pair with `onFeedback`. */
+  feedback?: InsightFeedback | null;
+  /** The choice on first render when `feedback` is uncontrolled. */
+  defaultFeedback?: InsightFeedback | null;
+  /** Called with the reader's verdict, or `null` when they take it back. Renders the feedback controls when set. */
+  onFeedback?: (feedback: InsightFeedback | null) => void;
+  /** The act-on-it control, rendered in the footer — a `Button` or a `Menu`. This is where "Investigate" belongs. */
+  primaryAction?: ReactNode;
+  /** Trailing header slot — a ghost `Button` or `Menu`. */
+  action?: ReactNode;
+  /** Lines the statement reserves before it arrives, so a rail of cards is already its final height. Default 2. */
+  expectedLines?: number;
+  /** Density: `sm` for a dense rail, `md` (default), `lg` for a hero panel. */
+  size?: InsightCardSize;
+  /** Heading level of the label for the document outline. Default 3. */
+  titleLevel?: 2 | 3 | 4 | 5 | 6;
+  /** BCP 47 locale for every number and date. Thai products on the Gregorian calendar pass `th-TH-u-ca-gregory`. */
+  locale?: string;
+  /** IANA time zone for every date. Defaults to the runtime's — pass it for deterministic output. */
+  timeZone?: string;
+  /** Overrides for every rendered or announced string. */
+  labels?: Partial<InsightCardLabels>;
+  /** Replaces the generated accessible description of the whole card. */
+  description?: string;
+  /** Open the data popover on first render. */
+  defaultTableOpen?: boolean;
+  /** Hide the header data button. Only when another surface exposes the same values to keyboard and screen-reader users. */
+  hideTableToggle?: boolean;
+  /** Called with vega-embed's result once the plot mounts — for `view` access in advanced compositions. */
+  onEmbed?: (result: Result) => void;
+  /** Escape hatch: transform the spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+/**
+ * A finding, stated — the tenth member of the analytics card family, and the
+ * only one whose primary content is a **claim** rather than a reading.
+ * Everything else here takes data and computes something; this takes a finding
+ * a detector or a model already made and lays it out so a person can judge it:
+ * the statement, the observed reading against what was expected, the evidence
+ * plot, the provenance behind the claim, and the triage — act, dismiss, or say
+ * it was wrong.
+ *
+ * The evidence resolves itself: a `spark` when there is history to plot, a
+ * `range` strip when there is only a reading and an expectation, `none` when
+ * the finding is not a number on a scale. Severity is derived on whichever
+ * scale the detector's own data establishes and stamped with which one that
+ * was, polarity is separate and rides `goodDirection`, and every value the
+ * plot shows is also in the key row, the description and the popover table.
+ */
+declare const InsightCard: import("react").ForwardRefExoticComponent<InsightCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { InsightCard, InsightCardProps };