@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/ReportCard/ReportCard.d.ts

@@ -0,0 +1,153 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { ReportBandPaint } from "./ReportCard.chart.js";
+import { ReportBand, ReportCardLabels, ReportCardSize, ReportCardStatus, ReportCriterion, ReportGoodDirection, ReportHeadline, ReportOverallMode, ReportScoreDomain, ReportSort } from "./ReportCard.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/ReportCard/ReportCard.d.ts
+interface ReportCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** What is being graded — 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;
+  /** How the grade is arrived at, shown in a tooltip behind an info control beside the label and exposed to assistive technology as the control's description. */
+  hint?: string;
+  /**
+   * What the subject is graded on, in the order they should read. Each
+   * criterion resolves to one score on `scoreDomain` by one of three routes,
+   * checked in order: `score` as given; `value` against `target` (attainment,
+   * where a `down` criterion inverts the ratio); `value` inside `range`
+   * (`[worst, best]`, reversed for lower-is-better). A criterion with none of
+   * those is unscored — its row stays, with no bar, and it is left out of the
+   * roll-up and counted as not measured rather than scored zero. Pass `[]`
+   * while loading; `expectedCriteria` rows are reserved.
+   */
+  criteria: readonly ReportCriterion[];
+  /**
+   * The grade ladder, low to high — each band runs from its `min` up to the
+   * next band's, so the ladder can never leave a gap. `tone` says what the
+   * grade means and paints the band and the bars in it. Default: Excellent
+   * (90) · Good (75) · Fair (60) · Poor (0), lettered A–D for the row column.
+   */
+  bands?: readonly ReportBand[];
+  /** How the ladder is painted: `neutral` (default) is one gray at four intensities, worst band darkest — Few's quiet qualitative ranges; `status` gives each band its own tone, the traffic-light scorecard. */
+  bandPaint?: ReportBandPaint;
+  /** The score scale, `[floor, ceiling]`. Default `[0, 100]`. The floor is the bars' baseline and the ceiling is a perfect score; a score past either end widens the plotted scale rather than clipping the bar. */
+  scoreDomain?: ReportScoreDomain;
+  /** Number format for every score — the headline, the rows, the detail line, the table and the tooltip. Default `number:0`. */
+  scoreFormat?: string;
+  /** Custom formatter for scores. Takes precedence over `scoreFormat`. */
+  formatScore?: (score: number) => string;
+  /** Number format for a criterion's raw reading when it names none of its own. Default `compact`. */
+  format?: string;
+  /** Custom formatter for raw readings. Takes precedence over `format` and a criterion's own. */
+  formatValue?: (value: number) => string;
+  /** Which way is good for a reading when a criterion does not say — `up` (a quota) or `down` (a budget, a defect rate). Only used where a score is derived from `value` and `target`. Default `up`. */
+  goodDirection?: ReportGoodDirection;
+  /** The score every criterion is expected to reach, drawn as each row's comparative tick. A criterion's own `targetScore` overrides it; `null` draws no ticks. */
+  passing?: number | null;
+  /** How the overall score is reached: `weighted` (default) is the weight-weighted mean of the scored criteria, `min` is the weakest one (a compliance scorecard), `none` leaves the roll-up to the consumer. Stamped as `data-overall-source`. */
+  overallMode?: ReportOverallMode;
+  /** The composite the product computed itself, which replaces the roll-up entirely. `null` while unknown. */
+  overall?: number | null;
+  /** The same subject's overall score last time — draws the change in points beside the headline. */
+  previousScore?: number | null;
+  /** What the change is against, under the delta badge. Default `vs previous` (`labels.versusPrevious`). */
+  previousLabel?: ReactNode;
+  /**
+   * What the big number is. `score` (default) is the overall score with its
+   * grade in a chip beneath — the KPI-tile convention. `grade` puts the grade
+   * word in the value role with the score beneath, for letter ladders.
+   * `none` leaves the rows to carry the panel. Stamped as `data-headline`.
+   */
+  headline?: ReportHeadline;
+  /** Write the score's ceiling after the headline value (`/100`) — only on a scale that starts at zero, where `score / ceiling` is a true reading. Default `true`; `false` when the scale is obvious from the product. */
+  showCeiling?: boolean;
+  /** Write each row's grade after its score, as a swatch and the band's short label. Default `true`; `false` for a very narrow panel — the tooltip, the table and the description still carry it. */
+  showGrades?: boolean;
+  /** Write the scale under the plot: `ends` (default) is the floor and the ceiling, `bands` adds every band boundary that fits, `none` writes nothing. */
+  scaleTicks?: "ends" | "bands" | "none";
+  /** Row order: `none` (default) keeps the consumer's order, `worst` puts the lowest score first (the action list), `best` the highest, `impact` ranks by the weighted points a criterion costs the overall. Unscored criteria always sort last. */
+  sort?: ReportSort;
+  /**
+   * Fold every criterion past this count (after sorting) into one `Other
+   * criteria` row whose score is the *weighted mean* of the folded rows and
+   * whose weight is their total — a mean folds honestly where a sum would
+   * not. Default: no fold.
+   */
+  maxCriteria?: number;
+  /** Rows the skeleton reserves before `criteria` arrive, so the panel is already its final height. Default 4. */
+  expectedCriteria?: number;
+  /**
+   * Let the reader choose a criterion: the rows become a radio group (click,
+   * or arrow keys once a row has focus) and the selected row's detail line
+   * under the headline names its reading, its target, its weight and its
+   * note. Default `true`; `false` for a static panel. Stamped as
+   * `data-selectable`.
+   */
+  selectable?: boolean;
+  /** Key of the selected criterion, controlled — pair with `onSelectedChange`. Omit for the uncontrolled panel (`defaultSelected`, else the weakest scored criterion); `null` selects none. */
+  selected?: string | null;
+  /** The criterion selected on first render when `selected` is uncontrolled. Default: the weakest scored one — the row the reader is here for. */
+  defaultSelected?: string | null;
+  /** Called with the chosen criterion's key when the reader selects another row. */
+  onSelectedChange?: (key: string) => void;
+  /** The takeaway in a sentence, rendered beside the AI mark under the rows. Wrap values in `<strong>` to set them in bold. */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with criteria already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: ReportCardStatus;
+  /** The consumer's filter is active — no criteria 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 report was last true. Rendered as an "as of" line (the date by default — see `updatedAtFormat`) and included in the description. */
+  updatedAt?: Date | string | number;
+  /**
+   * How `updatedAt` is written, as a time-grammar granularity — `day`
+   * (default, `Sep 8, 2026`), `datetime`, `time`, `month`, `year` — or a
+   * formatter for a custom form. Applies to the as-of line and the
+   * description alike, in the card'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 report. Scales type, padding, the row height (24 / 28 / 32px) and the bar thickness. */
+  size?: ReportCardSize;
+  /** Heading level of the label for the document outline. Default 3 — panels usually sit under a page's h2. */
+  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 the as-of date. Defaults to the runtime's — pass it for deterministic output. */
+  timeZone?: string;
+  /** Overrides for every rendered or announced string. */
+  labels?: Partial<ReportCardLabels>;
+  /** Replaces the generated accessible description of the whole card (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 card. */
+  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 the bullet rows mount — for `view` access in advanced compositions. */
+  onEmbed?: (result: Result) => void;
+  /** Escape hatch: transform the plot's spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+/**
+ * A scorecard panel — the roll-up subtype of the KPI card family: several
+ * criteria in their own units, each normalised to a score on one declared
+ * scale and graded against a ladder of bands, drawn as Few-style bullet rows
+ * over quiet qualitative ranges with a comparative tick, rolled up into one
+ * overall grade in the headline, with every name, score and grade as text
+ * beside the plot, a detail line for the selected criterion, and every
+ * loading, empty, insufficient, error and stale state — layout-stable inside
+ * one `Box` frame, with a generated text equivalent and a data table in an
+ * info popover.
+ */
+declare const ReportCard: import("react").ForwardRefExoticComponent<ReportCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { ReportCard, ReportCardProps };