@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/ChartCard/ChartCard.d.ts

@@ -0,0 +1,206 @@
+import { ChartAggregate, ChartCardLabels, ChartCardSize, ChartCardStatus, ChartExtent, ChartFieldType, ChartRecord, ChartSeriesColor, ChartSort, ChartType } from "./ChartCard.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/ChartCard/ChartCard.d.ts
+/** Where the legend sits relative to the plot. */
+type ChartLegendPosition = "top" | "bottom";
+/**
+ * How the table twin's control is exposed. `focus` (default) keeps the card
+ * face to title, legend and chart while leaving the data one Tab key away;
+ * `visible` draws the button always; `none` removes it — only when another
+ * surface exposes the same values to keyboard and screen-reader users.
+ */
+type ChartTableToggle = "focus" | "visible" | "none";
+interface ChartCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** The chart's title — the panel's heading, and the only prominent text the card carries. Pass `name` too when this is not plain text. */
+  title: ReactNode;
+  /** Plain-text title used in the generated descriptions and control labels. Defaults to `title` when it is a string. */
+  name?: string;
+  /**
+   * Which form to draw — 36 of them, one per distinct Vega-Lite encoding,
+   * grouped by the comparison each makes visible: magnitude and ranking
+   * (`bar`, `bar-horizontal`, `bar-grouped`, `lollipop`), part-to-whole
+   * (`bar-stacked`, `bar-normalized`, `area-stacked`, `area-normalized`,
+   * `pie`, `donut`, `radial`), change over time (`line`, `line-points`,
+   * `step`, `trail`, `area`, `streamgraph`, `slope`), deviation and flow
+   * (`bar-diverging`, `bar-range`, `waterfall`), correlation (`scatter`,
+   * `bubble`, `connected-scatter`, `heatmap-binned`, `radar`), distribution
+   * (`histogram`, `density`, `boxplot`, `violin`, `strip`, `dot`, `errorbar`,
+   * `errorband`) and many categories at once (`heatmap`, `punchcard`).
+   * Stamped as `data-type`.
+   */
+  type: ChartType;
+  /**
+   * The rows to plot — plain records from any transport. The card reads them
+   * through the field-name props below and knows nothing about how they were
+   * fetched. Pass `[]` while loading to reserve the plot's height.
+   */
+  data: readonly ChartRecord[];
+  /** Field name for the primary dimension — the x position, or a heatmap's column. */
+  x?: string;
+  /** Field name for the second position: the measure on most forms, a heatmap's row on the table-shaped ones. */
+  y?: string;
+  /** Field name for identity — one series per distinct value, in first-seen order. Drives the colour and the legend. */
+  series?: string;
+  /**
+   * Field name for the measure where it is NOT a position: a slice's angle, a
+   * cell's colour, a punch card's area. Falls back to `y`, which is the
+   * measure everywhere else.
+   */
+  value?: string;
+  /** Field name for a second measure drawn as area — `bubble` and `trail`. Named `sizeBy` because `size` is the card's density. */
+  sizeBy?: string;
+  /** Field name closing a range — the end of a `bar-range` span. */
+  x2?: string;
+  /** Vega-Lite type of the `x` field. Inferred from the rows (`Date` and ISO-8601 strings are temporal, numbers quantitative, everything else nominal). */
+  xType?: ChartFieldType;
+  /** Vega-Lite type of the `y` field. Inferred the same way. */
+  yType?: ChartFieldType;
+  /** Plain-text name of the dimension, used in the tooltip, the table header and the description. Defaults to the `x` field's name. */
+  xLabel?: string;
+  /** Plain-text name of the second position. Defaults to the `y` field's name. */
+  yLabel?: string;
+  /** Plain-text name of the measure. Defaults to the `value` (or `y`) field's name. */
+  valueLabel?: string;
+  /** Plain-text name of the identity dimension. Defaults to the `series` field's name. */
+  seriesLabel?: string;
+  /** Plain-text name of the size measure. Defaults to the `size` field's name. */
+  sizeLabel?: string;
+  /**
+   * Draw the axis titles from `xLabel` / `yLabel`. Default `false` — the title
+   * names the subject, the description names every field, and an axis title on
+   * a dashboard tile is furniture.
+   */
+  axisTitles?: boolean;
+  /** Draw the axes at all. Default `true`; `false` strips the plot to its marks — the table twin still carries every value. */
+  axes?: boolean;
+  /** Draw grid lines behind the marks. Default `true`. */
+  grid?: boolean;
+  /**
+   * Draw the legend — one chip per series with a swatch in the plot's own mark
+   * shape, or, for a form whose colour is a measure, the ramp's buckets.
+   * Default `true` when there is more than one series or the colour is a ramp,
+   * `false` for a single series. The tooltip, the table and the description
+   * name every series regardless.
+   */
+  legend?: boolean;
+  /** Where the legend sits. Default `top` — under the title and above the plot. */
+  legendPosition?: ChartLegendPosition;
+  /**
+   * Keys of the series currently shown, controlled — pair with
+   * `onVisibleSeriesChange`. A key is the `series` field's value. Omit for the
+   * uncontrolled card (`defaultVisibleSeries`, else every series). The card
+   * never hides the last one: a plot with nothing in it is not a state.
+   */
+  visibleSeries?: readonly string[];
+  /** The series shown on first render when `visibleSeries` is uncontrolled. Default: all of them. */
+  defaultVisibleSeries?: readonly string[];
+  /** Called with the remaining keys when the reader shows or hides a series from the legend. */
+  onVisibleSeriesChange?: (keys: string[]) => void;
+  /**
+   * How colour is used. `auto` (default) picks against the theme's identity
+   * budget: one series takes the emphasis hue, two or three take the
+   * `chart-1…N` slots, and past the budget the sequential ramp takes over —
+   * repeating a slot would make two series look like one. `categorical` forces
+   * identity slots and degrades to the ramp for the same reason. `sequential`
+   * is for ORDERED series (cohorts, buckets, quarters). `emphasis` puts the
+   * first series in the hue and the rest in the context gray. A form whose
+   * colour encodes a MEASURE ignores this — colour there has a job already.
+   * The resolved job is stamped as `data-series-color`.
+   */
+  seriesColor?: ChartSeriesColor;
+  /**
+   * Fold every series past this count into one `Other` whose readings are the
+   * sum of the folded ones — honest only for additive measures, which passing
+   * this asserts. The biggest series survive; the fold keeps the consumer's
+   * order, so a colour slot never moves. Stamped as `data-folded`.
+   */
+  maxSeries?: number;
+  /** Rank the x categories by the measure: `desc` for a ranked bar chart, `asc`, or `none` (default, the consumer's order). Ignored for a continuous x. */
+  sort?: ChartSort;
+  /**
+   * Aggregation Vega applies to the measure, named in the description so the
+   * transform is never silent. Only the forms that aggregate read it
+   * (`histogram`, `density`, `boxplot`, `violin`, `errorbar`, `errorband`,
+   * `heatmap-binned`).
+   */
+  aggregate?: ChartAggregate;
+  /** Bin-count ceiling for `histogram` and `heatmap-binned`. Default 20. */
+  maxBins?: number;
+  /**
+   * Whisker or band extent. `boxplot` takes `"min-max"` (default — no separate
+   * outlier layer, so no observation is hidden) or a number such as `1.5` for
+   * the Tukey form; `errorbar` and `errorband` take `"ci"` (default),
+   * `"stderr"`, `"stdev"` or `"iqr"`.
+   */
+  extent?: ChartExtent;
+  /** Hole size of a `donut`, as a fraction of the outer radius. Default 0.6. */
+  innerRadius?: number;
+  /**
+   * Number format for the axis, the legend, the tooltip, the table and the
+   * description — 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 the measure. Takes precedence over `format` everywhere a value is rendered. */
+  formatValue?: (value: number) => string;
+  /** Plot height in pixels, axes included. Defaults per `size` (180 / 240 / 320), plus 24 when `axes` draws the x labels. */
+  height?: number;
+  /** Show the hover tooltip. Default `true`. Every value it shows is also in the table twin, so `false` loses nothing but the convenience. */
+  tooltip?: boolean;
+  /** The transport's status. `loading` with rows already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: ChartCardStatus;
+  /** The consumer's filter is active — no rows 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, stamps `data-stale` and says so in the description. */
+  stale?: boolean;
+  /** 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 the title, the padding and the default plot height. */
+  size?: ChartCardSize;
+  /** Heading level of the title 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 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<ChartCardLabels>;
+  /** Replaces the generated accessible description of the card (the figure's `aria-describedby` text). */
+  description?: string;
+  /** Trailing header slot — a ghost `Button` or `Menu` for expand, export or settings, as the reference cards carry. Empty by default. */
+  action?: ReactNode;
+  /**
+   * How the table twin's control is exposed. `focus` (default) hides it until
+   * it is tabbed to, so the card face stays title + legend + chart while every
+   * value stays one key away; `visible` always draws it; `none` removes it.
+   */
+  tableToggle?: ChartTableToggle;
+  /** Open the data popover on first render, anchored to the card. */
+  defaultTableOpen?: 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 plot spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+/**
+ * A chart panel for dashboards: a title, a legend, and a chart — nothing else
+ * on its face. `type` picks one of 36 Vega-Lite forms, `data` is plain records
+ * and the remaining fields are field NAMES, so the same card draws a stacked
+ * bar, a donut, a heatmap, a box plot or a radar without changing shape.
+ *
+ * Where the other cards in this package answer one fixed question in text and
+ * illustrate it with a plot, ChartCard is the plot: the comparison is the form
+ * the consumer chose. Every state is handled and layout-stable, and the text
+ * equivalents the chart owes a screen reader — a generated description, a
+ * generated plot label, and a table twin holding every value — are all there,
+ * none of them on the card's face.
+ */
+declare const ChartCard: import("react").ForwardRefExoticComponent<ChartCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { ChartCard, ChartCardProps, ChartLegendPosition, ChartTableToggle };