@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/ProgressCard/ProgressCard.chart.js

@@ -0,0 +1,373 @@
+import { AXIS_LABEL_LIMIT_EXPR } from "../../lib/vega/axisTicks.js";
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/ProgressCard/ProgressCard.chart.ts
+/** The completion series: `{ t, y }` per reading, `y` null for a missed one. */
+const PROGRESS_COMPLETED_DATASET = "table";
+/** The scope at each reading: `{ t, y }`, drawn `step-after` — scope moves at moments, not gradually. */
+const PROGRESS_SCOPE_DATASET = "scope";
+/** The remaining band: `{ t, y, y2 }` per reading — completion up to the scope above it. */
+const PROGRESS_GAP_DATASET = "gap";
+/** The required pace: two rows `{ t, y }` from the run's start to the deadline. */
+const PROGRESS_IDEAL_DATASET = "ideal";
+/** The projection: two rows `{ t, y, tone }` from the last reading to where the rate crosses the scope. */
+const PROGRESS_PROJECTION_DATASET = "projection";
+/** Zero or one row `{ t }` — the deadline's vertical rule. */
+const PROGRESS_DUE_DATASET = "due";
+/** One row `{ t, y }` — the last reading, dotted. */
+const PROGRESS_LATEST_DATASET = "latest";
+/** Zero or one row `{ t, y, tone }` — where the projection meets the scope. */
+const PROGRESS_FINISH_DATASET = "finish";
+/** Responsive x tick values, recomputed by Vega when the domain or width changes. */
+const PROGRESS_X_TICKS_PARAM = "progress_x_ticks";
+/** The nearest-reading hover selection. */
+const PROGRESS_HOVER_PARAM = "hover";
+const POINT_SIZE = 64;
+const AREA_OPACITY = .16;
+const GAP_OPACITY = .05;
+const IDEAL_DASH = [4, 3];
+const PROJECTION_DASH = [3, 3];
+const PLOT_PADDING = 6;
+const DUE_LABEL_ROW_PX = 13;
+const Y_AXIS_TICKS = 3;
+/**
+* A stroke or fill that follows the projection's standing through the row's
+* `tone`: the positive hue when the rate lands on or before the deadline, the
+* negative hue when it lands after — two token values in the spec, so the
+* spec stays structural while the data decides.
+*/
+function toneColor(tokens) {
+	return {
+		condition: [{
+			test: "datum.tone === 'positive'",
+			value: tokens.divergingPositive
+		}],
+		value: tokens.divergingNegative
+	};
+}
+/**
+* Builds the burn-up: the work remaining as a quiet band between completion
+* and scope, the scope as a stepped context line, the required pace as a
+* dashed reference from the run's start to the deadline, cumulative completion
+* as an area and a 2px line from zero (a count, so zero is meaningful and the
+* ink stays proportional), the deadline as a vertical rule, the projection as
+* a dashed continuation in its own polarity hue ending in a hollow dot at the
+* crossing, and a nearest-reading hover carrying the tooltip. Gaps stay gaps:
+* Vega-Lite's default `invalid` handling breaks the path at a null reading.
+*/
+function buildProgressBurnUpSpec(options, tokens) {
+	const { height, axes, ideal, projection, due, dueLabel, gap, tooltip, dateTitle, completedTitle, scopeTitle, valueFormat, timeFormat, axisTimeFormat, locale } = options;
+	const xScale = { nice: false };
+	const axisArgs = `domain('x'), width, false, ${JSON.stringify(axisTimeFormat)}, "time"`;
+	const xAxis = axes ? {
+		title: null,
+		orient: "bottom",
+		domain: true,
+		ticks: false,
+		grid: false,
+		values: { expr: PROGRESS_X_TICKS_PARAM },
+		labelAngle: 0,
+		labelAlign: { expr: `arcAxisLabelAlign(datum.value, ${axisArgs})` },
+		labelFlush: false,
+		labelOverlap: false,
+		labelLimit: { expr: AXIS_LABEL_LIMIT_EXPR },
+		labelPadding: 4,
+		format: axisTimeFormat,
+		formatType: "arcTime"
+	} : null;
+	const yAxis = axes ? {
+		title: null,
+		orient: "left",
+		domain: false,
+		ticks: false,
+		grid: true,
+		tickCount: Y_AXIS_TICKS,
+		labelOverlap: true,
+		labelPadding: 6,
+		format: valueFormat,
+		formatType: "arcNumber"
+	} : null;
+	const xField = {
+		field: "t",
+		type: "temporal",
+		axis: xAxis,
+		scale: xScale
+	};
+	const yField = {
+		field: "y",
+		type: "quantitative",
+		axis: yAxis,
+		scale: {
+			zero: true,
+			nice: axes
+		}
+	};
+	const tooltipChannel = [
+		{
+			field: "t",
+			type: "temporal",
+			title: dateTitle,
+			format: timeFormat,
+			formatType: "arcTime"
+		},
+		{
+			field: "y",
+			type: "quantitative",
+			title: completedTitle,
+			format: valueFormat,
+			formatType: "arcNumber"
+		},
+		{
+			field: "total",
+			type: "quantitative",
+			title: scopeTitle,
+			format: valueFormat,
+			formatType: "arcNumber"
+		}
+	];
+	const layers = [];
+	if (gap) layers.push({
+		data: { name: "gap" },
+		mark: {
+			type: "area",
+			fill: tokens.context,
+			fillOpacity: GAP_OPACITY,
+			line: false,
+			interpolate: "step-after",
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			y2: { field: "y2" }
+		}
+	});
+	layers.push({
+		data: { name: PROGRESS_SCOPE_DATASET },
+		mark: {
+			type: "line",
+			stroke: tokens.context,
+			strokeWidth: 1.5,
+			interpolate: "step-after",
+			ariaRoleDescription: "scope"
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			description: {
+				field: "aria",
+				type: "nominal"
+			}
+		}
+	});
+	if (ideal) layers.push({
+		data: { name: PROGRESS_IDEAL_DATASET },
+		mark: {
+			type: "line",
+			stroke: tokens.reference,
+			strokeWidth: 1.5,
+			strokeDash: IDEAL_DASH,
+			ariaRoleDescription: "required pace"
+		},
+		encoding: {
+			x: xField,
+			y: yField
+		}
+	});
+	layers.push({
+		data: { name: PROGRESS_COMPLETED_DATASET },
+		mark: {
+			type: "area",
+			fill: tokens.emphasis,
+			fillOpacity: AREA_OPACITY,
+			line: false,
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField
+		}
+	});
+	layers.push({
+		data: { name: PROGRESS_COMPLETED_DATASET },
+		mark: {
+			type: "line",
+			stroke: tokens.emphasis,
+			strokeWidth: 2,
+			strokeCap: "round",
+			strokeJoin: "round",
+			ariaRoleDescription: "completed"
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			description: {
+				field: "aria",
+				type: "nominal"
+			}
+		}
+	});
+	if (projection) layers.push({
+		data: { name: PROGRESS_PROJECTION_DATASET },
+		mark: {
+			type: "line",
+			strokeWidth: 2,
+			strokeDash: PROJECTION_DASH,
+			strokeCap: "round",
+			ariaRoleDescription: "projection"
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			stroke: toneColor(tokens),
+			description: {
+				field: "aria",
+				type: "nominal"
+			}
+		}
+	});
+	if (due) {
+		layers.push({
+			data: { name: "due" },
+			mark: {
+				type: "rule",
+				stroke: tokens.foreground,
+				strokeWidth: 1,
+				strokeDash: IDEAL_DASH,
+				aria: false
+			},
+			encoding: { x: xField }
+		});
+		layers.push({
+			data: { name: "due" },
+			mark: {
+				type: "text",
+				text: dueLabel,
+				baseline: "bottom",
+				dy: -2,
+				align: { expr: "scale('x', datum.t) > width - 28 ? 'right' : 'left'" },
+				dx: { expr: "scale('x', datum.t) > width - 28 ? -4 : 4" },
+				fontSize: 10,
+				font: tokens.fontSans,
+				fill: tokens.axisLabel,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: { value: 0 }
+			}
+		});
+	}
+	layers.push({
+		data: { name: PROGRESS_LATEST_DATASET },
+		mark: {
+			type: "point",
+			filled: true,
+			size: POINT_SIZE,
+			fill: tokens.emphasis,
+			stroke: tokens.background,
+			strokeWidth: 2,
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField
+		}
+	});
+	if (projection) layers.push({
+		data: { name: PROGRESS_FINISH_DATASET },
+		mark: {
+			type: "point",
+			filled: false,
+			size: POINT_SIZE,
+			strokeWidth: 2,
+			fill: tokens.background,
+			aria: false
+		},
+		encoding: {
+			x: xField,
+			y: yField,
+			stroke: toneColor(tokens)
+		}
+	});
+	if (tooltip) {
+		layers.push({
+			data: { name: PROGRESS_COMPLETED_DATASET },
+			params: [{
+				name: PROGRESS_HOVER_PARAM,
+				select: {
+					type: "point",
+					on: "pointerover",
+					clear: "pointerout",
+					nearest: true,
+					encodings: ["x"]
+				}
+			}],
+			mark: {
+				type: "rule",
+				strokeWidth: 12,
+				opacity: 0,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				tooltip: tooltipChannel
+			}
+		});
+		layers.push({
+			data: { name: PROGRESS_COMPLETED_DATASET },
+			mark: {
+				type: "point",
+				filled: true,
+				size: POINT_SIZE,
+				fill: tokens.emphasis,
+				stroke: tokens.background,
+				strokeWidth: 2,
+				aria: false
+			},
+			encoding: {
+				x: xField,
+				y: yField,
+				opacity: {
+					condition: {
+						param: PROGRESS_HOVER_PARAM,
+						empty: false,
+						value: 1
+					},
+					value: 0
+				}
+			}
+		});
+	}
+	const params = [];
+	if (axes) params.push({
+		name: PROGRESS_X_TICKS_PARAM,
+		expr: `arcAxisTicks(${axisArgs})`
+	});
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 240,
+		height,
+		autosize: {
+			type: "fit",
+			contains: "padding"
+		},
+		padding: axes ? {
+			left: 0,
+			right: PLOT_PADDING,
+			top: due ? DUE_LABEL_ROW_PX : PLOT_PADDING,
+			bottom: 0
+		} : {
+			left: PLOT_PADDING,
+			right: PLOT_PADDING,
+			top: due ? DUE_LABEL_ROW_PX : PLOT_PADDING,
+			bottom: PLOT_PADDING
+		},
+		background: "transparent",
+		data: { name: PROGRESS_COMPLETED_DATASET },
+		params,
+		layer: layers,
+		config: arcVegaConfig(tokens, { locale })
+	};
+}
+//#endregion
+export { PROGRESS_COMPLETED_DATASET, PROGRESS_DUE_DATASET, PROGRESS_FINISH_DATASET, PROGRESS_GAP_DATASET, PROGRESS_HOVER_PARAM, PROGRESS_IDEAL_DATASET, PROGRESS_LATEST_DATASET, PROGRESS_PROJECTION_DATASET, PROGRESS_SCOPE_DATASET, PROGRESS_X_TICKS_PARAM, buildProgressBurnUpSpec };

package/dist/components/ProgressCard/ProgressCard.d.ts

@@ -0,0 +1,137 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { ProgressCardLabels, ProgressCardSize, ProgressCardStatus, ProgressHeadline, ProgressSnapshot, ProgressStageInput } from "./ProgressCard.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/ProgressCard/ProgressCard.d.ts
+interface ProgressCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** What is being finished — the tile'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 work, shown in a tooltip behind an info control beside the label and exposed to assistive technology as the control's description. */
+  hint?: string;
+  /**
+   * The run's readings, as `{ date, completed, total? }` records — the
+   * **cumulative** count finished by each date, not the per-period delta. Any
+   * order: they are sorted. `completed: null` is a reading the transport
+   * missed, and the line breaks at it rather than drawing through it. Give a
+   * reading its own `total` whenever the scope moved, which is what makes the
+   * change visible instead of hidden. Two readings are the minimum for a
+   * trajectory; one renders the `insufficient` state. Pass `[]` while loading.
+   */
+  snapshots: readonly ProgressSnapshot[];
+  /** The whole, for readings that do not carry their own. A reading past it raises it, so the run never draws through its own ceiling. */
+  total?: number | null;
+  /**
+   * The deadline. It draws the required-pace line and the vertical rule, and
+   * it is what the projection is judged against — without it the card still
+   * projects a finish date but reaches no verdict, because there is nothing to
+   * be late against.
+   */
+  due?: Date | string | number | null;
+  /** The product's own forecast finish, replacing the one derived from the observed rate. */
+  projected?: Date | string | number | null;
+  /**
+   * Days of recent history the rate is measured over. Omit to use the whole
+   * run (`completed / elapsed`), which is steadier; pass a window when a
+   * recent change of pace is the point. A stall is always read from the most
+   * recent interval, whatever this says.
+   */
+  rateWindow?: number;
+  /** Days past the deadline that still count as `at-risk` rather than `late`. Default 2. */
+  tolerance?: number;
+  /**
+   * An optional breakdown of where the work sits right now, drawn as a
+   * composed `Progress` bar above the plot — `{ key?, label, value, tone? }`
+   * in the order the work moves through the stages. `tone` (`complete`,
+   * `active`, `blocked`, `remaining`) is the only colour decision it takes.
+   * Six or fewer.
+   */
+  stages?: readonly ProgressStageInput[];
+  /**
+   * Number format for every count — the headline, the axis, the legend, the
+   * table and the tooltip — as one grammar so nothing rounds two ways:
+   * `number[:digits]`, `integer` (default), `compact[:digits]`,
+   * `percent[:digits]`, `currency:CODE[:digits|compact]`.
+   */
+  format?: string;
+  /** Custom formatter for counts. Takes precedence over `format` everywhere a count is rendered. */
+  formatValue?: (value: number) => string;
+  /** Fraction digits for every share the card shows. Default 0. */
+  percentDigits?: number;
+  /** Unit shown after a `remaining` headline in the muted role (`tables`, `tickets`); it follows the counts line under a `percent` headline. */
+  unit?: ReactNode;
+  /**
+   * What the big number is: `percent` (default) — the finished share, counts
+   * beneath; `date` — the projected finish, the share beneath, for a delivery
+   * dashboard whose question is when; `remaining` — how much is left, for a
+   * burn-down framing. Stamped as `data-headline`.
+   */
+  headline?: ProgressHeadline;
+  /**
+   * How dates are written — a time-grammar granularity (`day` by default,
+   * `month`, `year`, `datetime`, `time`) or a formatter. Applies to the
+   * projection, the deadline, the as-of line, the table and the description
+   * alike, in the card's `locale` and `timeZone`.
+   */
+  dateFormat?: ArcTimeGranularity | ((date: Date) => string);
+  /** Draw the plot's x and y axes. Default `true`; `false` shrinks it toward a sparkline — the table still carries the figures. */
+  axes?: boolean;
+  /** Draw the required-pace line from the run's start to the deadline. Default `true`. */
+  showIdeal?: boolean;
+  /** Draw the dashed projection to where the rate crosses the scope. Default `true`. */
+  showProjection?: boolean;
+  /** Shade the gap between completion and scope as the work remaining. Default `true`. */
+  showGap?: boolean;
+  /** The plot's legend of mark keys. Default `true`; `false` for a dense grid — the tooltip, table and description still name every series. */
+  legend?: boolean;
+  /** Plot height in pixels, overriding the one `size` implies. */
+  plotHeight?: number;
+  /** The takeaway in a sentence, rendered beside the AI mark under the plot. Wrap values in `<strong>` to set them in bold. */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with readings already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: ProgressCardStatus;
+  /** 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;
+  /** 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. Scales type, padding and the plot's height (88 / 116 / 148px). */
+  size?: ProgressCardSize;
+  /** 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. Date-only reading and deadline strings are midnight in it, and whole days are counted between calendar dates in it — so a daylight-saving change never shifts "2 days late". */
+  timeZone?: string;
+  /** Overrides for every rendered or announced string. */
+  labels?: Partial<ProgressCardLabels>;
+  /** 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 details popover on first render, anchored to the card. */
+  defaultTableOpen?: boolean;
+  /** Hide the header info button for the details popover. Only when another surface exposes the same figures to keyboard and screen-reader users. */
+  hideTableToggle?: boolean;
+  /** Called with vega-embed's result once the burn-up mounts — for `view` access in advanced compositions. */
+  onEmbed?: (result: Result) => void;
+  /** Escape hatch: transform the burn-up's spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+/**
+ * A delivery tile for dashboard grids: how much of a finite body of work is
+ * finished, the rate it is being finished at, when that rate lands it, and
+ * whether that is before the deadline — on a burn-up chart (completion rising
+ * from zero, the scope it is chasing, the pace the deadline requires, and a
+ * dashed projection to the crossing) with every loading, empty, error and
+ * stale state, a generated text equivalent and a reading-by-reading table.
+ */
+declare const ProgressCard: import("react").ForwardRefExoticComponent<ProgressCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { ProgressCard, ProgressCardProps };