@arcfusionz/arc-analytic-ui 0.0.0

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

@@ -0,0 +1,330 @@
+import { ArcDeltaDirection, ArcDeltaMode } from "../../lib/vega/formatters.js";
+//#region src/components/TreeCard/TreeCard.model.d.ts
+/** What the consumer's transport reports. */
+type TreeCardStatus = "loading" | "ready" | "error";
+/**
+ * What the card actually shows, derived from `status`, the nodes and
+ * `filtered`. Stamped on the root as `data-state`.
+ */
+type TreeCardState = "loading" | "refreshing" | "ready" | "empty" | "no-match" | "error";
+/** Which way is good for the measure: revenue up, cost down, headcount neutral. */
+type TreeGoodDirection = "up" | "down" | "none";
+/** How a change reads once `goodDirection` is applied. Stamped as `data-polarity`. */
+type TreePolarity = "positive" | "negative" | "neutral";
+type TreeDeltaMode = ArcDeltaMode;
+/**
+ * Where a parent's value comes from. `sum` (default) always rolls children up,
+ * so the parts reconcile with the whole by construction. `own` lets a parent
+ * carry its own reading and reports the difference as an `Unallocated` child.
+ */
+type TreeRollup = "sum" | "own";
+/** Sibling order within every parent: the consumer's order, or ranked by value. */
+type TreeSort = "none" | "asc" | "desc";
+/** What the big number is. Stamped as `data-headline`. */
+type TreeHeadline = "total" | "focus" | "none";
+/** What the bars encode identity with. Stamped as `data-color-by`. */
+type TreeColorBy = "depth" | "emphasis";
+/** The second figure beside each row's value. */
+type TreeRowSecondary = "share" | "share-of-total" | "delta" | "none";
+type TreeCardSize = "sm" | "md" | "lg";
+/** A row's part in the tree — a real node, the fold of a long tail, or the remainder a parent's children do not account for. */
+type TreeNodeRole = "node" | "other" | "residual";
+/**
+ * One node of the hierarchy. `key` identifies it among its siblings and
+ * defaults to `label`; `value` is its own reading, which `rollup: "sum"`
+ * ignores for any node that has children. `previous` is the same node in the
+ * comparison period — supply it on the leaves and the rollup carries it up.
+ */
+interface TreeNode {
+  key?: string;
+  label: string;
+  value?: number | null;
+  previous?: number | null;
+  children?: readonly TreeNode[];
+}
+/** A node after the walk, in display order, with its rollup, share and ARIA bookkeeping resolved. */
+interface TreeRow {
+  /** Unique across the tree: the parent's key, a slash, and this node's own key. */
+  key: string;
+  label: string;
+  /** 0 for a top-level row. Rendered as indentation and announced as `aria-level` (depth + 1). */
+  depth: number;
+  /** The rolled-up reading, or `null` when nothing under it has one. */
+  value: number | null;
+  /** The same node in the comparison period, rolled up the same way. `null` without `previous` data. */
+  previous: number | null;
+  parentKey: string | null;
+  /** The parent's rolled-up value — the denominator of `share`. The total for a top-level row. */
+  parentValue: number | null;
+  /**
+   * This row's value over its parent's. `null` when either is missing or the
+   * parent is zero. Mixed signs can push it past 100% or below zero — that is
+   * the honest report of the data, not a bug.
+   */
+  share: number | null;
+  /** This row's value over the whole tree's total, on the same terms as `share`. */
+  shareOfTotal: number | null;
+  /** This row can be opened — it kept children after the depth cap. */
+  hasChildren: boolean;
+  /** This row is open, so its children are among the visible rows. */
+  expanded: boolean;
+  /** Position among its siblings, 1-based — `aria-posinset`. */
+  posInSet: number;
+  /** How many siblings it has — `aria-setsize`. */
+  setSize: number;
+  role: TreeNodeRole;
+  /** Source nodes folded into this `Other` row; 0 for every other row. */
+  folded: number;
+}
+interface TreeSummary {
+  /** The rows on screen — every node whose ancestors are all expanded, depth-first. */
+  rows: TreeRow[];
+  /** Every node in the tree, expanded or not, depth-first — what the table twin lists. */
+  allRows: TreeRow[];
+  /** Keys of the nodes that are open in this build; the seed for the reader's first toggle. */
+  expandedKeys: string[];
+  /** The sum of the top-level rows — the denominator of every `shareOfTotal`. */
+  total: number | null;
+  /** The same sum in the comparison period. */
+  previousTotal: number | null;
+  /** Visible rows with a finite value. */
+  count: number;
+  /** Every node in the tree, folds and residuals included. */
+  nodeCount: number;
+  /** How many levels deep the tree goes after the cap; 1 for a flat list. */
+  levels: number;
+  /**
+   * The depth the total's direct parts live at — 0 when several roots share
+   * the card, 1 when one root *is* the total. `largest` and `topMover` are
+   * drawn from it, so "the biggest part" always means a part of the whole.
+   */
+  partsDepth: number;
+  /** The biggest part at `partsDepth` — the branch the description names. */
+  largest: TreeRow | null;
+  /** The part at `partsDepth` whose value moved furthest from `previous`. `null` without a comparison period. */
+  topMover: TreeRow | null;
+  /** Any visible value is below zero — the plot then draws a zero rule. */
+  hasNegative: boolean;
+  /** At least one node carries a `previous` reading, so deltas are real. */
+  hasPrevious: boolean;
+  /** A parent's children did not account for its own reading; an `Unallocated` row says so. */
+  hasResidual: boolean;
+  /** Source nodes folded into `Other` rows anywhere in the tree. */
+  folded: number;
+  /** Any node can be opened. A tree where nothing can is a flat list — the card stamps `data-insufficient`. */
+  expandable: boolean;
+}
+interface TreeDelta {
+  direction: ArcDeltaDirection;
+  polarity: TreePolarity;
+  /** Signed, formatted change against the comparison period: `+24.9%`, `-0.3 pp`, `+฿424K`. */
+  text: string;
+  renderedMode: ArcDeltaMode;
+  /** The same change in the other form, or `null` when there is no other form (a zero baseline has no percent). */
+  secondaryText: string | null;
+}
+/** Every string the card renders or announces, so a product can localise it. Sentences are functions. */
+interface TreeCardLabels {
+  /** Heading of the total when `totalLabel` is not given. */
+  total: string;
+  /** Comparison line under the delta badge. */
+  versusPrevious: string;
+  increase: string;
+  decrease: string;
+  unchanged: string;
+  /** Suffix for a percentage-point delta. */
+  percentagePoints: string;
+  noData: string;
+  noMatch: string;
+  clearFilters: string;
+  error: string;
+  retry: string;
+  stale: string;
+  asOf: string;
+  /** Label of the row a parent's long tail folds into. */
+  other: string;
+  /** Label of the row carrying what a parent's children do not account for. */
+  unallocated: string;
+  /** Accessible name of a row's disclosure control — `Expand Online`. */
+  expand: (label: string) => string;
+  collapse: (label: string) => string;
+  /** Header of the tree's one control, which opens or closes every branch at once. */
+  expandAll: string;
+  collapseAll: string;
+  tableItem: string;
+  tableValue: string;
+  tableShare: string;
+  tableShareOfTotal: string;
+  tableLevel: string;
+  /** Header of the per-row change column. */
+  tableChange: string;
+  /** Read out after the selected row's label. */
+  selected: string;
+  /** Read out after a fold row's label — `3 items`. */
+  foldedItems: (count: number) => string;
+  showTable: (name: string) => string;
+  hideTable: (name: string) => string;
+  about: (name: string) => string;
+  loading: (name: string) => string;
+  tableCaption: (name: string) => string;
+  /** Accessible name of the tree — `Breakdown of Revenue`. */
+  treeLabel: (name: string) => string;
+  /** Accessible name of the delta group beside the value. */
+  deltaComparison: (name: string) => string;
+  /** Compact label/value rows explaining the delta badge. */
+  deltaExplanation: (input: {
+    label: string;
+    valueText: string;
+    previousText: string;
+    changeText: string;
+    secondaryText: string | null;
+    renderedMode: ArcDeltaMode;
+    direction: ArcDeltaDirection;
+  }) => readonly (readonly [label: string, value: string])[];
+  /** The comparison sentence in the card description. */
+  comparisonSentence: (input: {
+    word: string;
+    primary: string;
+    secondary: string | null;
+    previousText: string;
+  }) => string;
+  /** Names the branch that moved the total furthest. */
+  moverSentence: (input: {
+    label: string;
+    changeText: string;
+  }) => string;
+  /** How the tree is shaped — `12 parts across 3 levels`. */
+  shapeSummary: (input: {
+    nodes: number;
+    levels: number;
+  }) => string;
+  /** Lists the total's direct parts — `list` is `Online ฿2.1M (55%), Retail ฿1.7M (40%)`. */
+  partsSummary: (count: number, list: string) => string;
+  /** Appended when nodes were folded into `Other` rows. */
+  foldedSummary: (count: number) => string;
+  /** Appended when a parent's children do not reconcile with its own reading. */
+  residualSummary: string;
+  /** The plot's own `aria-label`. */
+  chartDescription: (input: {
+    name: string;
+    count: number;
+    levels: number;
+    total: string;
+    top: string;
+    topValue: string;
+  }) => string;
+  /** Accessible name of the AI mark beside the insight sentence. */
+  insightMark: string;
+}
+declare const DEFAULT_TREE_LABELS: TreeCardLabels;
+declare function resolveTreeLabels(overrides?: Partial<TreeCardLabels>): TreeCardLabels;
+interface DeriveTreeStateInput {
+  status: TreeCardStatus;
+  /** At least one node has a finite value. */
+  hasValue: boolean;
+  /** Anything is on screen already — any node at all — so a reload is a refresh, not a first load. */
+  hasData: boolean;
+  filtered: boolean;
+}
+/**
+ * The state machine. Error wins; loading over existing nodes is a refresh (the
+ * previous render stays under the veil); no values is `no-match` when the
+ * consumer's filter caused it and `empty` otherwise.
+ */
+declare function deriveTreeState({ status, hasValue, hasData, filtered }: DeriveTreeStateInput): TreeCardState;
+/** Local key segment of the row a parent's long tail folds into. */
+declare const TREE_OTHER_KEY = "__other__";
+/** Local key segment of the row carrying what a parent's children do not account for. */
+declare const TREE_RESIDUAL_KEY = "__residual__";
+/** Default share of a parent's own reading below which a mismatch with its children is rounding, not a gap. */
+declare const DEFAULT_RESIDUAL_TOLERANCE = 0.0005;
+interface BuildTreeOptions {
+  /** Where a parent's value comes from. Default `sum`. */
+  rollup?: TreeRollup;
+  /** Sibling order inside every parent. Default `none` — the consumer's order. */
+  sort?: TreeSort;
+  /** Fold each parent's tail past this many children into one `Other` row. */
+  maxChildren?: number;
+  /** Drop every node deeper than this (0-based). Ancestors keep the dropped values in their rollup. */
+  maxDepth?: number;
+  /** Keys the reader has open. `null` falls back to `expandDepth`. */
+  expanded?: ReadonlySet<string> | null;
+  /** With no explicit set, every node shallower than this is open. Default 1 — the top level and its children are visible. */
+  expandDepth?: number;
+  /** Report a parent's unaccounted remainder as an `Unallocated` child. Only ever fires under `rollup: "own"`. Default `true`. */
+  showResidual?: boolean;
+  /** Fraction of the parent's own reading below which a mismatch is rounding. Default `DEFAULT_RESIDUAL_TOLERANCE`. */
+  residualTolerance?: number;
+  otherLabel: string;
+  residualLabel: string;
+}
+/**
+ * Normalises the hierarchy into the rows the plot, the tree and the table all
+ * read from: unique path keys, a bottom-up rollup, the depth cap, each
+ * parent's long tail folded into `Other`, the unallocated remainder made
+ * explicit, shares against the parent and against the total, and the ARIA
+ * bookkeeping every `treeitem` needs. Returns `null` when there is nothing to
+ * speak of.
+ */
+declare function buildTree(nodes: readonly TreeNode[] | undefined, options: BuildTreeOptions): TreeSummary | null;
+interface DeriveTreeDeltaOptions {
+  deltaMode: TreeDeltaMode;
+  goodDirection: TreeGoodDirection;
+  format: string;
+  locale?: string;
+  percentagePoints: string;
+}
+/** A reading against its comparison period, with polarity resolved through `goodDirection`. `null` unless both are finite. */
+declare function deriveTreeDelta(value: number | null | undefined, previous: number | null | undefined, { deltaMode, goodDirection, format, locale, percentagePoints }: DeriveTreeDeltaOptions): TreeDelta | null;
+interface TreeTextFormatters {
+  formatValue: (value: number | null | undefined) => string;
+  /** A share as a percentage — `55%`. `MISSING_VALUE` when it could not be computed. */
+  formatShare: (share: number | null | undefined) => string;
+  /** A row's signed change against its own comparison period, in the card's `deltaMode`. */
+  formatChange: (value: number | null | undefined, previous: number | null | undefined) => string;
+}
+/** The formatters every text surface shares — headline, rows, delta, table, tooltip, descriptions. */
+declare function createTreeFormatters({ format, locale, formatValue, deltaMode, shareFormat, percentagePoints }: {
+  format: string;
+  locale?: string;
+  formatValue?: (value: number) => string;
+  /** The form of every row's change — the badge's own `deltaMode`, so the table and the badge never disagree. */
+  deltaMode?: TreeDeltaMode;
+  /** The share grammar; whole percents at tile scale. */
+  shareFormat?: string;
+  percentagePoints?: string;
+}): TreeTextFormatters;
+interface BuildTreeDescriptionInput {
+  name: string;
+  state: TreeCardState;
+  headline: TreeHeadline;
+  summary: TreeSummary | null;
+  /** The row the headline is about — the selection, or `null` for the total. */
+  focus: TreeRow | null;
+  delta: TreeDelta | null;
+  formatters: TreeTextFormatters;
+  asOfText?: string;
+  labels: TreeCardLabels;
+}
+/**
+ * The card's text equivalent (Amy Cesal's alt-text formula: what it is, what
+ * it shows, why it is here, when it was true) — the figure's accessible
+ * description.
+ *
+ * It names the shape, the total's direct parts with their values and shares,
+ * and the branch that moved furthest — rather than enumerating every visible
+ * row the way a flat card must. The rows here are real `treeitem`s carrying
+ * their own label, value, share and `aria-level`, so a screen reader already
+ * reaches each one in place; repeating all of them in one sentence would bury
+ * the answer this description exists to give.
+ */
+declare function buildTreeDescription({ name, state, headline, summary, focus, delta, formatters, asOfText, labels }: BuildTreeDescriptionInput): string;
+/** The plot's own `description` — the `aria-label` Vega stamps on the `graphics-document`. */
+declare function buildTreeChartDescription({ name, summary, formatters, labels }: {
+  name: string;
+  summary: TreeSummary;
+  formatters: TreeTextFormatters;
+  labels: TreeCardLabels;
+}): string;
+//#endregion
+export { BuildTreeDescriptionInput, BuildTreeOptions, DEFAULT_RESIDUAL_TOLERANCE, DEFAULT_TREE_LABELS, DeriveTreeDeltaOptions, DeriveTreeStateInput, TREE_OTHER_KEY, TREE_RESIDUAL_KEY, TreeCardLabels, TreeCardSize, TreeCardState, TreeCardStatus, TreeColorBy, TreeDelta, TreeDeltaMode, TreeGoodDirection, TreeHeadline, TreeNode, TreeNodeRole, TreePolarity, TreeRollup, TreeRow, TreeRowSecondary, TreeSort, TreeSummary, TreeTextFormatters, buildTree, buildTreeChartDescription, buildTreeDescription, createTreeFormatters, deriveTreeDelta, deriveTreeState, resolveTreeLabels };