@arcfusionz/arc-analytic-ui 0.0.0

package/dist/components/TreeCard/TreeCard.chart.js

@@ -0,0 +1,178 @@
+import { arcVegaConfig } from "../../lib/vega/config.js";
+//#region src/components/TreeCard/TreeCard.chart.ts
+/** The visible rows: `{ key, label, depth, value, share, role, inFocus }` per `TreeRow`, in display order. */
+const TREE_TABLE_DATASET = "table";
+/** Zero or one row `{ value: 0 }` — a hairline at zero, pushed only when a visible value is negative. */
+const TREE_ZERO_DATASET = "zero";
+/** The hovered row's point selection. */
+const TREE_HOVER_PARAM = "hover";
+/**
+* The upper bound of the shared value scale — the tree's total, pushed as a
+* signal.
+*
+* Pinning the domain to the whole rather than to the tallest visible bar is
+* what makes a bar's length read as its share of the total at every depth,
+* whether or not the total is itself a row. It rides a signal, not the spec,
+* because the total is data: baking it into the spec would re-embed the view
+* on every refresh.
+*/
+const TREE_TOTAL_PARAM = "treeTotal";
+const TREE_MAX_BAR_HEIGHT = 24;
+const RESTING_OPACITY = .6;
+const ROW_DOMAIN_EXPR = `pluck(data('${TREE_TABLE_DATASET}'), 'key')`;
+/**
+* Depth reads through the sequential ramp's top steps, darkest at the root.
+*
+* Only three: the ramp's lighter steps (`chart-sequential-1…4`) do not clear
+* WCAG 1.4.11's 3:1 against `background` — `primary-400` measures 2.7:1 on
+* white — so a fourth shade would buy a depth cue by making the deepest bars
+* unreadable. Depth past the third level therefore repeats the third step;
+* indentation, the disclosure control and `aria-level` carry the rest, so the
+* hierarchy never depends on the ramp alone.
+*/
+const TREE_DEPTH_STEPS = [
+	6,
+	5,
+	4
+];
+/** The exact hue a row's bar wears — the swatches in the legend, chips and tooltip read from this too. */
+function treeBarColor(tokens, { depth, role, inFocus }, colorBy, emphasize) {
+	if (role === "residual") return tokens.context;
+	if (colorBy === "emphasis") return !emphasize || inFocus ? tokens.emphasis : tokens.context;
+	const step = TREE_DEPTH_STEPS[Math.min(depth, TREE_DEPTH_STEPS.length - 1)];
+	return tokens.sequential[step] ?? tokens.emphasis;
+}
+/**
+* Builds the bars: one horizontal bar per visible row on a shared zero-based
+* scale (length compares magnitude — Cleveland & McGill's second-best channel
+* — and, because the whole is on the same scale, reads as share of it), the
+* fill carrying depth through the sequential ramp or the selected branch
+* through the emphasis hue, a hairline at zero once a value is negative, and
+* a hover selection that keeps the pointed bar solid while its siblings
+* recede. Every band has no padding, so the bar centers line up with the DOM
+* rows that carry the names, values and shares.
+*/
+function buildTreeBarsSpec(options, tokens) {
+	const { barHeight, height, zeroRule, tooltip, colorBy, emphasize, itemTitle, valueTitle, shareTitle, valueFormat, shareFormat, locale } = options;
+	const xField = {
+		field: "value",
+		type: "quantitative",
+		axis: null,
+		scale: {
+			zero: true,
+			nice: false,
+			domainMax: { expr: TREE_TOTAL_PARAM }
+		}
+	};
+	const yField = {
+		field: "key",
+		type: "nominal",
+		sort: null,
+		axis: null,
+		scale: {
+			domain: { expr: ROW_DOMAIN_EXPR },
+			paddingInner: 0,
+			paddingOuter: 0
+		}
+	};
+	const layers = [];
+	if (zeroRule) layers.push({
+		data: { name: TREE_ZERO_DATASET },
+		mark: {
+			type: "rule",
+			stroke: tokens.axis,
+			strokeWidth: 1,
+			aria: false
+		},
+		encoding: { x: xField }
+	});
+	const residualCondition = {
+		test: "datum.role === 'residual'",
+		value: tokens.context
+	};
+	const fill = colorBy === "emphasis" ? emphasize ? {
+		condition: [residualCondition, {
+			test: "datum.inFocus",
+			value: tokens.emphasis
+		}],
+		value: tokens.context
+	} : {
+		condition: [residualCondition],
+		value: tokens.emphasis
+	} : {
+		condition: [residualCondition, ...TREE_DEPTH_STEPS.slice(0, -1).map((step, depth) => ({
+			test: `datum.depth === ${depth}`,
+			value: tokens.sequential[step] ?? tokens.emphasis
+		}))],
+		value: tokens.sequential[TREE_DEPTH_STEPS[TREE_DEPTH_STEPS.length - 1]] ?? tokens.emphasis
+	};
+	layers.push({
+		...tooltip ? { params: [{
+			name: TREE_HOVER_PARAM,
+			select: {
+				type: "point",
+				on: "pointerover",
+				clear: "pointerout",
+				encodings: ["y"]
+			}
+		}] } : {},
+		mark: {
+			type: "bar",
+			height: Math.min(24, barHeight),
+			cornerRadiusEnd: 2,
+			aria: false
+		},
+		encoding: {
+			y: yField,
+			x: xField,
+			fill,
+			...tooltip ? {
+				opacity: {
+					condition: {
+						param: TREE_HOVER_PARAM,
+						value: 1
+					},
+					value: RESTING_OPACITY
+				},
+				tooltip: [
+					{
+						field: "label",
+						type: "nominal",
+						title: itemTitle
+					},
+					{
+						field: "value",
+						type: "quantitative",
+						title: valueTitle,
+						format: valueFormat,
+						formatType: "arcNumber"
+					},
+					{
+						field: "share",
+						type: "quantitative",
+						title: shareTitle,
+						format: shareFormat,
+						formatType: "arcNumber"
+					}
+				]
+			} : {}
+		}
+	});
+	return {
+		$schema: "https://vega.github.io/schema/vega-lite/v6.json",
+		width: 240,
+		height,
+		autosize: { type: "none" },
+		padding: 0,
+		background: "transparent",
+		params: [{
+			name: TREE_TOTAL_PARAM,
+			value: 1
+		}],
+		data: { name: TREE_TABLE_DATASET },
+		layer: layers,
+		config: arcVegaConfig(tokens, { locale })
+	};
+}
+//#endregion
+export { TREE_DEPTH_STEPS, TREE_HOVER_PARAM, TREE_MAX_BAR_HEIGHT, TREE_TABLE_DATASET, TREE_TOTAL_PARAM, TREE_ZERO_DATASET, buildTreeBarsSpec, treeBarColor };

package/dist/components/TreeCard/TreeCard.d.ts

@@ -0,0 +1,182 @@
+import { ArcTimeGranularity } from "../../lib/vega/formatters.js";
+import { TreeCardLabels, TreeCardSize, TreeCardStatus, TreeColorBy, TreeDeltaMode, TreeGoodDirection, TreeHeadline, TreeNode, TreeRollup, TreeRowSecondary, TreeSort } from "./TreeCard.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/TreeCard/TreeCard.d.ts
+interface TreeCardProps extends Omit<BoxProps, "children" | "padding" | "title"> {
+  /** The metric's name — 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 metric, shown in a tooltip behind an info control beside the label and exposed to assistive technology as the control's description. */
+  hint?: string;
+  /**
+   * The hierarchy, as nested `{ key?, label, value?, previous?, children? }`
+   * records. `key` identifies a node among its siblings and defaults to
+   * `label`; the card joins it with its ancestors' keys, so the keys it hands
+   * back through `expanded`, `selected` and their callbacks are paths like
+   * `online/marketplace`. Give the leaves their `value` and let `rollup`
+   * total the branches, or give every level its own reading with
+   * `rollup="own"`. Pass `[]` while loading — `expectedRows` rows are
+   * reserved.
+   */
+  nodes: readonly TreeNode[];
+  /**
+   * Where a parent's value comes from. `sum` (default) always rolls the
+   * children up, so the parts reconcile with the whole by construction.
+   * `own` prefers a parent's own reading and reports whatever its children do
+   * not account for as an explicit `Unallocated` row. Stamped as `data-rollup`.
+   */
+  rollup?: TreeRollup;
+  /** Sibling order inside every parent: `none` (default) keeps the consumer's order, `desc` and `asc` rank by value with missing values last. */
+  sort?: TreeSort;
+  /**
+   * Fold each parent's tail past this many children into one `Other` row
+   * whose value is the sum of the folded values — for additive measures
+   * (counts, revenue), never for rates or averages. The count includes the
+   * `Other` row, so `maxChildren={4}` shows three named children beside it.
+   * Default: no fold.
+   */
+  maxChildren?: number;
+  /** Drop every node deeper than this level (0-based, so `1` shows two levels). Ancestors keep the dropped values in their rollup. Default: the whole tree. */
+  maxDepth?: number;
+  /** Report a parent's unaccounted remainder as an `Unallocated` row. Only ever fires under `rollup="own"`. Default `true`. */
+  showResidual?: boolean;
+  /** Fraction of a parent's own reading below which a mismatch with its children is rounding rather than a gap. Default `0.0005` (0.05%). */
+  residualTolerance?: number;
+  /**
+   * Keys of the open branches, controlled — pair with `onExpandedChange`.
+   * Omit for the uncontrolled card (`defaultExpanded`, else every branch
+   * shallower than `defaultExpandDepth`).
+   */
+  expanded?: readonly string[];
+  /** The open branches on first render when `expanded` is uncontrolled. Takes precedence over `defaultExpandDepth`. */
+  defaultExpanded?: readonly string[];
+  /** With neither `expanded` nor `defaultExpanded`, every branch shallower than this level starts open. Default 1 — the top level and its children are visible. */
+  defaultExpandDepth?: number;
+  /** Called with the open branches' keys whenever the reader opens or closes one. */
+  onExpandedChange?: (keys: string[]) => void;
+  /**
+   * Key of the selected row, controlled — pair with `onSelectedChange`. It is
+   * the `focus` headline's subject and, under `colorBy="emphasis"`, the
+   * branch that takes the hue. Omit for the uncontrolled card
+   * (`defaultSelected`, else nothing selected).
+   */
+  selected?: string | null;
+  /** The selected row on first render when `selected` is uncontrolled. */
+  defaultSelected?: string | null;
+  /** Called with the chosen row's key — or `null` when the reader deselects it — on click or Enter. */
+  onSelectedChange?: (key: string | null) => void;
+  /**
+   * Let the reader select a row. Rows stay focusable and arrow-navigable
+   * either way, since opening a branch is always a keyboard action. A value
+   * the app controls without its change handler (`selected` without
+   * `onSelectedChange`) is pinned. Default `true`; `false` for a static tile.
+   * Stamped as `data-selectable`.
+   */
+  selectable?: boolean;
+  /**
+   * What the big number is. `total` (default) is the sum of the top-level
+   * rows. `focus` follows the selection and falls back to the total while
+   * nothing is selected. `none` leaves the tree to carry the card. Stamped as
+   * `data-headline`.
+   */
+  headline?: TreeHeadline;
+  /** What the total is called, under the headline value and in the description. Default `labels.total`. */
+  totalLabel?: ReactNode;
+  /**
+   * Name the headline's subject in a chip under the value — a soft primary
+   * `Badge` with a swatch in the row's bar hue. Default `true`; `false` when
+   * the card's title already names it. Not rendered with `headline="none"`.
+   */
+  headlineChip?: boolean;
+  /**
+   * What the bars encode. `depth` (default) ramps the sequential steps by
+   * level, redundantly with the indentation. `emphasis` paints the selected
+   * branch and its descendants in the emphasis hue and everything else in the
+   * context gray. Stamped as `data-color-by`.
+   */
+  colorBy?: TreeColorBy;
+  /**
+   * The second figure beside each row's value: `share` of its parent
+   * (default), `share-of-total`, the `delta` against `previous`, or `none`.
+   * Stamped as `data-row-secondary`.
+   */
+  rowSecondary?: TreeRowSecondary;
+  /** `percent` (default) is relative change; `absolute` is the difference in the value's units — percentage points for a `percent` format. Also the form of every row's change in the table and tooltip. */
+  deltaMode?: TreeDeltaMode;
+  /** Which direction is good: `up` (revenue), `down` (cost, churn) or `none` (headcount — the delta stays neutral). Drives the badge's polarity color. Default `up`. */
+  goodDirection?: TreeGoodDirection;
+  /**
+   * Number format for the headline, rows, delta, table and tooltip — one
+   * grammar so nothing rounds two ways: `number[:digits]`, `integer`,
+   * `compact[:digits]`, `percent[:digits]`, `currency:CODE[:digits|compact]`.
+   * Default `compact` (`3.8M`).
+   */
+  format?: string;
+  /** Custom formatter for values. Takes precedence over `format` everywhere a value is rendered. */
+  formatValue?: (value: number) => string;
+  /** Format grammar for shares. Default `percent:0` (`55%`). */
+  shareFormat?: string;
+  /** Unit shown after the headline value in the muted role (`ms`, `req/s`). Prefer `format="currency:…"` for money. */
+  unit?: ReactNode;
+  /** Rows the skeleton reserves before `nodes` arrive, so the tile is already its final height. Default 4. */
+  expectedRows?: number;
+  /** Show the header control that opens or closes every branch at once. Default `true`; hidden when nothing can be opened. */
+  showExpandAll?: boolean;
+  /** The takeaway in a sentence, rendered beside the AI mark under the tree. Wrap values in `<strong>` to set them in bold. */
+  insight?: ReactNode;
+  /** The transport's status. `loading` with nodes already present is a refresh: the previous render stays under the veil. Default `ready`. */
+  status?: TreeCardStatus;
+  /** The consumer's filter is active — no values 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 data was last true. Rendered as an "as of" line and included in the description. */
+  updatedAt?: Date | string | number;
+  /** How `updatedAt` is written, as a time-grammar granularity — `day` (default), `datetime`, `time`, `month`, `year` — or a formatter. */
+  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 breakdown. Scales type, padding, the row height (24 / 28 / 32px), the bar thickness and the indent. */
+  size?: TreeCardSize;
+  /** 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 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<TreeCardLabels>;
+  /** Replaces the generated accessible description of the whole card. */
+  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 bars mount — for `view` access in advanced compositions. */
+  onEmbed?: (result: Result) => void;
+  /** Escape hatch: transform the bars' spec before it renders. Voids the token and accessibility guarantees for whatever it changes. */
+  patchSpec?: (spec: TopLevelSpec) => TopLevelSpec;
+}
+/**
+ * A hierarchical breakdown tile — the decomposition subtype of the KPI card
+ * family beside `MetricCard` and `ComparisonCard`: one total broken into
+ * nested parts as indented, expandable rows whose bars share a single
+ * zero-based scale, so every bar length reads as its share of the whole.
+ * Depth rides the sequential ramp, each row carries its value and share as
+ * text, an optional `previous` per node turns it into a decomposition of
+ * change with the family's polarity badge, and every loading, empty, error
+ * and stale state is layout-stable inside one `Box` frame — with a generated
+ * text equivalent, full WAI-ARIA tree keyboard navigation, and a data table
+ * in an info popover.
+ */
+declare const TreeCard: import("react").ForwardRefExoticComponent<TreeCardProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+export { TreeCard, TreeCardProps };