@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/StatusCard/index.d.ts

@@ -0,0 +1,4 @@
+import { BuildStatusDescriptionInput, BuildStatusExplanationInput, BuildStatusStripInput, CreateStatusFormattersInput, DEFAULT_STATUS_LABELS, DeriveStatusRunInput, DeriveStatusStateInput, FormatDurationOptions, STATUS_LEVELS, STATUS_SEVERITY, StatusCardLabels, StatusCardSize, StatusCardState, StatusCardStatus, StatusChartDescriptionInput, StatusDetailRow, StatusDurationUnits, StatusExplanationInput, StatusHeadline, StatusHold, StatusIncident, StatusIncidentRow, StatusLevel, StatusPeriod, StatusPolarity, StatusResolution, StatusRun, StatusSegment, StatusSla, StatusStrip, StatusStripRow, StatusTextFormatters, StatusUptimeMode, StatusVerdict, StatusWindow, StatusWindowInput, buildStatusChartDescription, buildStatusDescription, buildStatusDetailRows, buildStatusExplanation, buildStatusIncidentRows, buildStatusStrip, createStatusFormatters, deriveIncidents, deriveStatusRun, deriveStatusState, describeResolution, formatDuration, formatStripCell, normalizeHistory, resolveStatusHold, resolveStatusLabels, resolveStatusWindow, resolveStep, statusHue, statusLevelBreakdown, statusStepKey } from "./StatusCard.model.js";
+import { StatusCard, StatusCardBaseProps, StatusCardLabelProps, StatusCardProps } from "./StatusCard.js";
+import { STATUS_AXIS_ROW_PX, STATUS_CELL_GAP_MAX_PX, STATUS_CELL_GAP_MIN_PX, STATUS_CELL_GAP_RATIO, STATUS_HOVER_PARAM, STATUS_MAX_PARAM, STATUS_MIN_CELL_PX, STATUS_MIN_PARAM, STATUS_TABLE_DATASET, STATUS_WINDOW_DATASET, STATUS_X_TICKS_PARAM, StatusTimelineSpecOptions, buildStatusTimelineSpec } from "./StatusCard.chart.js";
+export { type BuildStatusDescriptionInput, type BuildStatusExplanationInput, type BuildStatusStripInput, type CreateStatusFormattersInput, DEFAULT_STATUS_LABELS, type DeriveStatusRunInput, type DeriveStatusStateInput, type FormatDurationOptions, STATUS_AXIS_ROW_PX, STATUS_CELL_GAP_MAX_PX, STATUS_CELL_GAP_MIN_PX, STATUS_CELL_GAP_RATIO, STATUS_HOVER_PARAM, STATUS_LEVELS, STATUS_MAX_PARAM, STATUS_MIN_CELL_PX, STATUS_MIN_PARAM, STATUS_SEVERITY, STATUS_TABLE_DATASET, STATUS_WINDOW_DATASET, STATUS_X_TICKS_PARAM, StatusCard, type StatusCardBaseProps, type StatusCardLabelProps, type StatusCardLabels, type StatusCardProps, type StatusCardSize, type StatusCardState, type StatusCardStatus, type StatusChartDescriptionInput, type StatusDetailRow, type StatusDurationUnits, type StatusExplanationInput, type StatusHeadline, type StatusHold, type StatusIncident, type StatusIncidentRow, type StatusLevel, type StatusPeriod, type StatusPolarity, type StatusResolution, type StatusRun, type StatusSegment, type StatusSla, type StatusStrip, type StatusStripRow, type StatusTextFormatters, type StatusTimelineSpecOptions, type StatusUptimeMode, type StatusVerdict, type StatusWindow, type StatusWindowInput, buildStatusChartDescription, buildStatusDescription, buildStatusDetailRows, buildStatusExplanation, buildStatusIncidentRows, buildStatusStrip, buildStatusTimelineSpec, createStatusFormatters, deriveIncidents, deriveStatusRun, deriveStatusState, describeResolution, formatDuration, formatStripCell, normalizeHistory, resolveStatusHold, resolveStatusLabels, resolveStatusWindow, resolveStep, statusHue, statusLevelBreakdown, statusStepKey };

package/dist/components/StatusCard/index.js

@@ -0,0 +1,4 @@
+import { STATUS_AXIS_ROW_PX, STATUS_CELL_GAP_MAX_PX, STATUS_CELL_GAP_MIN_PX, STATUS_CELL_GAP_RATIO, STATUS_HOVER_PARAM, STATUS_MAX_PARAM, STATUS_MIN_CELL_PX, STATUS_MIN_PARAM, STATUS_TABLE_DATASET, STATUS_WINDOW_DATASET, STATUS_X_TICKS_PARAM, buildStatusTimelineSpec } from "./StatusCard.chart.js";
+import { DEFAULT_STATUS_LABELS, STATUS_LEVELS, STATUS_SEVERITY, buildStatusChartDescription, buildStatusDescription, buildStatusDetailRows, buildStatusExplanation, buildStatusIncidentRows, buildStatusStrip, createStatusFormatters, deriveIncidents, deriveStatusRun, deriveStatusState, describeResolution, formatDuration, formatStripCell, normalizeHistory, resolveStatusHold, resolveStatusLabels, resolveStatusWindow, resolveStep, statusHue, statusLevelBreakdown, statusStepKey } from "./StatusCard.model.js";
+import { StatusCard } from "./StatusCard.js";
+export { DEFAULT_STATUS_LABELS, STATUS_AXIS_ROW_PX, STATUS_CELL_GAP_MAX_PX, STATUS_CELL_GAP_MIN_PX, STATUS_CELL_GAP_RATIO, STATUS_HOVER_PARAM, STATUS_LEVELS, STATUS_MAX_PARAM, STATUS_MIN_CELL_PX, STATUS_MIN_PARAM, STATUS_SEVERITY, STATUS_TABLE_DATASET, STATUS_WINDOW_DATASET, STATUS_X_TICKS_PARAM, StatusCard, buildStatusChartDescription, buildStatusDescription, buildStatusDetailRows, buildStatusExplanation, buildStatusIncidentRows, buildStatusStrip, buildStatusTimelineSpec, createStatusFormatters, deriveIncidents, deriveStatusRun, deriveStatusState, describeResolution, formatDuration, formatStripCell, normalizeHistory, resolveStatusHold, resolveStatusLabels, resolveStatusWindow, resolveStep, statusHue, statusLevelBreakdown, statusStepKey };

package/dist/components/TableCard/TableCard.chart.d.ts

@@ -0,0 +1,53 @@
+import { ChartTokens } from "../../lib/vega/tokens.js";
+import { TableCardTrendMark } from "./TableCard.model.js";
+import { arcVegaConfig } from "../../lib/vega/config.js";
+import { TopLevelSpec } from "vega-lite";
+//#region src/components/TableCard/TableCard.chart.d.ts
+/** The readings: `{ x, y }` per `TableCardTrendPoint`. */
+declare const TABLE_TREND_DATASET = "table";
+/** Zero or one row — the last reading with a value, marked with a dot. */
+declare const TABLE_TREND_LATEST_DATASET = "latest";
+/** The nearest-point hover selection. */
+declare const TABLE_TREND_HOVER_PARAM = "hover";
+interface TableTrendSpecOptions {
+  /** `line` may crop its y domain; `area` and `bar` keep a zero baseline. */
+  mark: TableCardTrendMark;
+  /** Plot height in pixels — the row's content height, so the table's rhythm decides it. */
+  height: number;
+  /** Dot the last reading, so the cell's own value and the plot's right edge agree. */
+  latest: boolean;
+  /** Wire the nearest-point hover selection and the tooltip channel. */
+  tooltip: boolean;
+  /** `temporal` when the readings carry real dates, `ordinal` for categories, `quantitative` for an index. */
+  xType: "temporal" | "ordinal" | "quantitative";
+  /** Tooltip titles — the column's own header and the period's name. */
+  xTitle: string;
+  yTitle: string;
+  /** `arcNumber` grammar for the readings (`compact@en-US`). */
+  valueFormat: string;
+  /** `arcTime` grammar for a temporal x in the tooltip (`day@en-US@Asia/Bangkok`). */
+  timeFormat: string;
+  locale?: string;
+  timeZone?: string;
+  /** d3 locale definitions for the parts of Vega-Lite that still format through d3. */
+  vegaLocale?: ReturnType<typeof arcVegaConfig>["locale"];
+}
+/**
+ * Builds a table-cell sparkline: a bare line (or an area with a crisp line on
+ * top, or thin bars), the last reading as a dot, and a nearest-point hover
+ * layer carrying the tooltip. No axes, no grid, no legend, no title — the
+ * cell's own text and its neighbouring columns carry every number, so the
+ * plot is the shape and nothing else.
+ *
+ * `aria: false` on every mark: the plot is a redundant visual hint inside a
+ * cell whose reading is already text (the component hides it from the
+ * accessibility tree and puts the series' sentence in the cell instead), so
+ * a `graphics-symbol` node per reading × a row per table would be pure noise.
+ *
+ * Gaps stay gaps — Vega-Lite's default `invalid` handling breaks the path at a
+ * null reading rather than drawing through it, so a missing day never reads as
+ * a dip to zero.
+ */
+declare function buildTableTrendSpec(options: TableTrendSpecOptions, tokens: ChartTokens): TopLevelSpec;
+//#endregion
+export { TABLE_TREND_DATASET, TABLE_TREND_HOVER_PARAM, TABLE_TREND_LATEST_DATASET, TableTrendSpecOptions, buildTableTrendSpec };

package/dist/components/TableCard/TableCard.chart.js

@@ -0,0 +1,192 @@
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/TableCard/TableCard.chart.ts
+/** The readings: `{ x, y }` per `TableCardTrendPoint`. */
+const TABLE_TREND_DATASET = "table";
+/** Zero or one row — the last reading with a value, marked with a dot. */
+const TABLE_TREND_LATEST_DATASET = "latest";
+/** The nearest-point hover selection. */
+const TABLE_TREND_HOVER_PARAM = "hover";
+const LINE_WIDTH = 1.5;
+const POINT_SIZE = 28;
+const PLOT_PADDING = 4;
+const NOMINAL_WIDTH = 120;
+const BAR_WIDTH_EXPR = "min(6, bandwidth('x') * 0.7)";
+/**
+* Builds a table-cell sparkline: a bare line (or an area with a crisp line on
+* top, or thin bars), the last reading as a dot, and a nearest-point hover
+* layer carrying the tooltip. No axes, no grid, no legend, no title — the
+* cell's own text and its neighbouring columns carry every number, so the
+* plot is the shape and nothing else.
+*
+* `aria: false` on every mark: the plot is a redundant visual hint inside a
+* cell whose reading is already text (the component hides it from the
+* accessibility tree and puts the series' sentence in the cell instead), so
+* a `graphics-symbol` node per reading × a row per table would be pure noise.
+*
+* Gaps stay gaps — Vega-Lite's default `invalid` handling breaks the path at a
+* null reading rather than drawing through it, so a missing day never reads as
+* a dip to zero.
+*/
+function buildTableTrendSpec(options, tokens) {
+	const { mark, height, latest, tooltip, xType, xTitle, yTitle, valueFormat, timeFormat, locale, timeZone, vegaLocale } = options;
+	const zero = mark !== "line";
+	const xField = mark === "bar" || xType === "ordinal" ? {
+		field: "x",
+		type: "ordinal",
+		sort: null,
+		axis: null
+	} : {
+		field: "x",
+		type: xType,
+		axis: null,
+		scale: {
+			nice: false,
+			...xType === "quantitative" ? { zero: false } : {}
+		}
+	};
+	const yField = {
+		field: "y",
+		type: "quantitative",
+		axis: null,
+		scale: {
+			zero,
+			nice: false
+		}
+	};
+	const tooltipChannel = [xType === "temporal" ? {
+		field: "x",
+		type: "temporal",
+		title: xTitle,
+		format: timeFormat,
+		formatType: "arcTime"
+	} : xType === "quantitative" ? {
+		field: "x",
+		type: "quantitative",
+		title: xTitle,
+		format: "integer",
+		formatType: "arcNumber"
+	} : {
+		field: "x",
+		type: "nominal",
+		title: xTitle
+	}, {
+		field: "y",
+		type: "quantitative",
+		title: yTitle,
+		format: valueFormat,
+		formatType: "arcNumber"
+	}];
+	const layers = [];
+	if (mark === "bar") layers.push({
+		mark: {
+			type: "bar",
+			fill: tokens.emphasis,
+			cornerRadiusEnd: 1,
+			width: { expr: BAR_WIDTH_EXPR },
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField
+		}
+	});
+	else {
+		if (mark === "area") layers.push({
+			mark: {
+				type: "area",
+				fill: tokens.emphasis,
+				fillOpacity: .12,
+				line: false,
+				interpolate: "linear",
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: yField
+			}
+		});
+		layers.push({
+			mark: {
+				type: "line",
+				stroke: tokens.emphasis,
+				strokeWidth: LINE_WIDTH,
+				strokeCap: "round",
+				strokeJoin: "round",
+				interpolate: "linear",
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: yField
+			}
+		});
+	}
+	if (latest) layers.push({
+		data: { name: TABLE_TREND_LATEST_DATASET },
+		mark: {
+			type: "point",
+			filled: true,
+			size: POINT_SIZE,
+			fill: tokens.emphasis,
+			stroke: tokens.background,
+			strokeWidth: 1,
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField
+		}
+	});
+	if (tooltip) layers.push({
+		params: [{
+			name: TABLE_TREND_HOVER_PARAM,
+			select: {
+				type: "point",
+				on: "pointerover",
+				clear: "pointerout",
+				nearest: true,
+				encodings: ["x"]
+			}
+		}],
+		mark: {
+			type: "point",
+			filled: true,
+			size: POINT_SIZE,
+			fill: tokens.emphasis,
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			opacity: {
+				condition: {
+					param: TABLE_TREND_HOVER_PARAM,
+					empty: false,
+					value: 1
+				},
+				value: 0
+			},
+			tooltip: tooltipChannel
+		}
+	});
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		data: { name: TABLE_TREND_DATASET },
+		autosize: {
+			type: "fit",
+			contains: "padding",
+			resize: true
+		},
+		padding: PLOT_PADDING,
+		width: NOMINAL_WIDTH,
+		height,
+		layer: layers,
+		config: arcVegaConfig(tokens, {
+			locale,
+			timeZone,
+			vegaLocale
+		})
+	};
+}
+//#endregion
+export { TABLE_TREND_DATASET, TABLE_TREND_HOVER_PARAM, TABLE_TREND_LATEST_DATASET, buildTableTrendSpec };

package/dist/components/TableCard/TableCard.d.ts

@@ -0,0 +1,140 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { TableCardColumn, TableCardLabels, TableCardRow, TableCardSize, TableCardSort, TableCardStatus, TableCardTrendColumn } from "./TableCard.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/TableCard/TableCard.d.ts
+interface TableCardBaseProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** The table's name — the card's heading. Pass `name` too when this is not plain text. */
+  label: ReactNode;
+  /** Plain-text name used in the generated description, the table's caption and every control's accessible name. Required when `label` is not a string. */
+  name?: string;
+  /** What the table shows and how it is built, in a tooltip behind an info control beside the heading and read as that control's description. */
+  hint?: string;
+  /**
+   * The columns, in reading order. Each declares the `field` it reads on every
+   * row, its `header`, and the `kind` that decides how the cell encodes:
+   * `text` (identity), `number` (the exact reading), `bar` (magnitude on the
+   * column's own zero-based scale), `delta` (the change against a baseline),
+   * `trend` (the shape over time, the one Vega cell), `badge` (a category).
+   * The first `text` column becomes each row's header cell and the one that
+   * stays pinned when the table scrolls sideways.
+   */
+  columns: readonly TableCardColumn[];
+  /**
+   * The rows as plain records — `{ campaign: "Search", spend: 412000, … }` —
+   * read at each column's `field`. Values may be `null`: the cell prints a
+   * dash and sorts last, in either direction. Pass `[]` while loading;
+   * `expectedRows` skeleton rows are reserved.
+   */
+  rows: readonly TableCardRow[];
+  /** Field that identifies a row for selection and React keys. Default: the first `text` column's field. */
+  rowKey?: string;
+  /** What the consumer's transport reports. `loading` over existing rows is a refresh: the table stays, dimmed. Stamped as `data-status`. */
+  status?: TableCardStatus;
+  /** Body rows reserved by the loading skeleton, so the card does not resize when the data lands. Default 5. */
+  expectedRows?: number;
+  /** A filter is active, so no rows means the filters exclude everything (`no-match`) rather than there being no data (`empty`). */
+  filtered?: boolean;
+  /** Called by the no-match state's action. Omit it and the state renders without one. */
+  onClearFilters?: () => void;
+  /** Called by the error state's retry action. Omit it and the state renders without one. */
+  onRetry?: () => void;
+  /**
+   * The active order, controlled — pair with `onSortChange`. `null` keeps the
+   * consumer's own row order (and hides the rank column, since a place in an
+   * arbitrary order means nothing). Omit for the uncontrolled table
+   * (`defaultSort`).
+   */
+  sort?: TableCardSort | null;
+  /** The order on first render when `sort` is uncontrolled. Default: none — the consumer's order. */
+  defaultSort?: TableCardSort;
+  /** Called with the new order when the reader activates a column heading. */
+  onSortChange?: (sort: TableCardSort) => void;
+  /** Offer the column headings as sort controls. Default `true`; `false` for a fixed order. A column opts out with its own `sortable: false`. */
+  sortable?: boolean;
+  /** Number the rows in the current order — only meaningful in a sorted table, so it is ignored without a `sort`. Ties share a place. */
+  showRank?: boolean;
+  /**
+   * Cap the rows shown. The tail is cut off and counted in a caption
+   * ("Showing top 10 of 48"), never folded into an "Other" row: a table's
+   * columns are not all additive, so summing a rate would invent a number.
+   * Default 10 — which is also the trend column's view budget.
+   */
+  maxRows?: number;
+  /** The true row count behind the table when the consumer already capped or paged upstream, so the caption can be honest. Default: `rows.length`. */
+  totalRows?: number;
+  /** Called by the truncation caption's action. Omit it and the caption states the cap without offering one. */
+  onShowAll?: () => void;
+  /** Key of the highlighted row, controlled — pair with `onRowSelect`. Omit for the uncontrolled table (`defaultSelectedRow`). */
+  selectedRow?: string | null;
+  /** The highlighted row on first render when `selectedRow` is uncontrolled. */
+  defaultSelectedRow?: string | null;
+  /** Called with a row's key when the reader activates it. Providing it turns each row's header cell into a real button — the keyboard path to a drill-through. */
+  onRowSelect?: (key: string) => void;
+  /** Type ramp, padding, cell density, row height and plot height. Default `md`. */
+  size?: TableCardSize;
+  /** Maximum height of the scroll area as a CSS length. Set it to pin the header and scroll the body — without it the card grows to fit every row. */
+  maxHeight?: number | string;
+  /** Pin the first column while the table scrolls sideways, so each row keeps its identifying cell in view. Default `true`. */
+  stickyColumn?: boolean;
+  /** Give alternating body rows a supporting surface. Default `false` — dividers already separate them, and zebra stripes add ink a scan does not need. */
+  zebra?: boolean;
+  /** How the trend cells draw: `line` (default, may crop so a small move stays visible), `area` or `bar` (both keep a zero baseline). */
+  trendMark?: TableCardTrendColumn["mark"];
+  /** Dot the last reading of each trend cell, so the plot's right edge and the cell's number agree. Default `true`. */
+  trendLatest?: boolean;
+  /** The takeaway under the table — how far the leader stands above the median. Generated from the data; pass your own, or `false` for none. */
+  insight?: ReactNode | false;
+  /** Replaces the generated accessible description of the whole card. Prefer letting it generate. */
+  description?: string;
+  /** The table's own caption, read by assistive technology when navigating tables. Defaults to the card's `name`; visually hidden either way. */
+  caption?: ReactNode;
+  /** When the data was read. Renders the as-of line under the table and feeds the description. */
+  updatedAt?: string | number | Date;
+  /** Granularity of the as-of line. Default `day`. */
+  updatedAtFormat?: ArcTimeGranularity;
+  /** The data is older than the product's freshness rule (TanStack Query's `isStale`). Shows a badge and stamps `data-stale`. */
+  stale?: boolean;
+  /** BCP 47 tag for every number and date. Thai products on the Gregorian calendar pass `th-TH-u-ca-gregory` — a bare `th-TH` is the Buddhist calendar. */
+  locale?: string;
+  /** IANA zone for every date, so a product that reports in one business zone is deterministic. */
+  timeZone?: string;
+  /** Every rendered and announced string, for localisation. Sentences are functions. */
+  labels?: Partial<TableCardLabels>;
+  /** Trailing header slot — a ghost `Button` or `Menu` for export, drill-through or settings. */
+  action?: ReactNode;
+  /** Heading level of the card's label. Default 4. */
+  titleLevel?: 2 | 3 | 4 | 5 | 6;
+  /** Re-resolve the chart tokens when a subtree's theme changes rather than the document's. */
+  theme?: string;
+  /** Last word on the trend cells' compiled spec. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+  /** Called with vega-embed's result for each trend cell that mounts — the escape hatch to the View API. */
+  onEmbed?: (result: Result) => void;
+}
+type TableCardLabelProps = {
+  label: string;
+  name?: string;
+} | {
+  label: ReactNode;
+  name: string;
+};
+type TableCardProps = TableCardBaseProps & TableCardLabelProps;
+/**
+ * An analytical table for dashboard grids and analysis pages: many entities
+ * down the page, several measures across it, each column encoding what its
+ * kind calls for — exact numbers, magnitude bars on the column's own
+ * zero-based scale, signed deltas, categories, and a sparkline per row — with
+ * sortable headings, a rank, an honest cap, opt-in footer totals, every
+ * loading, empty, no-match, error and stale state, and a generated
+ * description and insight sentence.
+ *
+ * It is the family's form for the question a plot cannot take: more measures
+ * per entity than a chart can encode, exact values, and long names. Only the
+ * trend column is a chart; every other cell is an Arc primitive.
+ */
+declare const TableCard: import("react").ForwardRefExoticComponent<TableCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { TableCard, TableCardBaseProps, TableCardLabelProps, TableCardProps };