@robosystems/report-components 0.2.0 → 0.2.2

package/dist/{index-D6FzPTm5.d.ts → index-BS6_6h3l.d.ts}

@@ -15,6 +15,14 @@ import { Store } from 'n3';
  */
 type PeriodType = 'instant' | 'duration';
 type BalanceType = 'debit' | 'credit';
+/**
+ * How a numeric fact is formatted and whether it may be rescaled. Monetary values
+ * take the unit's currency symbol and honor the section scale; per-share amounts
+ * and share counts are never rescaled (an EPS of 4.93 stays 4.93 under "in
+ * millions"); percentages render with a `%` suffix. Absent → the formatter falls
+ * back to `monetary ? 'monetary' : 'other'`.
+ */
+type NumericKind = 'monetary' | 'perShare' | 'shares' | 'percent' | 'pure' | 'integer' | 'other';
 /** A reportable concept (a taxonomy element). */
 interface ElementInfo {
     /** Full element IRI — the join key used everywhere. */
@@ -27,6 +35,18 @@ interface ElementInfo {
     periodType: PeriodType | null;
     abstract: boolean;
     monetary: boolean;
+    /**
+     * Finer numeric classification driving format + scale (per-share and share
+     * counts opt out of rescaling). Optional; when absent the formatter falls back
+     * to `monetary ? 'monetary' : 'other'`.
+     */
+    numericKind?: NumericKind;
+    /**
+     * Value domain (`rs:itemType`): `textBlock` / `monetary` / `shares` / `decimal`
+     * / `date` / `boolean` / `string`. `textBlock` marks an element whose facts are
+     * rendered HTML disclosures — orthogonal to elementType's structural role.
+     */
+    itemType?: string;
 }
 /** A reporting period — an instant (balance sheet) or a duration (flows). */
 interface PeriodInfo {
@@ -45,6 +65,12 @@ interface UnitInfo {
     measure: string;
     /** Short display label, e.g. `USD`. */
     label: string;
+    /**
+     * Currency symbol for a monetary unit (`$`, `€`, `£`, `¥`), else null — a share
+     * or pure unit has none. Lets the renderer stop hard-coding `$` for non-USD.
+     * Optional; when absent the formatter derives it from `measure`.
+     */
+    symbol?: string | null;
 }
 /** The reporting entity. */
 interface EntityInfo {
@@ -53,6 +79,28 @@ interface EntityInfo {
     legalName: string | null;
     country: string | null;
 }
+/**
+ * One dimensional qualifier on a fact: an axis pinned to a member. A fact's full
+ * dimensional coordinate is an ordered list of these (one per axis); an empty
+ * list is the consolidated total. Explicit dimensions name a `member`; typed
+ * dimensions carry a `typedValue` instead. This is the only multi-valued fact
+ * aspect, and it is what separates otherwise-identical facts (same element +
+ * period) into distinct pivot cells — so it is part of a fact's identity.
+ */
+interface DimensionQualifier {
+    /** Axis element IRI/qname, e.g. `us-gaap:StatementEquityComponentsAxis`. */
+    axis: string;
+    /** Member element IRI/qname (explicit), or null for a typed dimension. */
+    member: string | null;
+    /** Human axis label, e.g. `Equity Components`. */
+    axisLabel: string;
+    /** Human member label, e.g. `Common Stock`. */
+    memberLabel: string;
+    /** Explicit (member drawn from a domain) vs typed (an arbitrary value). */
+    explicit: boolean;
+    /** The typed-dimension value, present when `!explicit`. */
+    typedValue?: string | null;
+}
 /** A single reported value. */
 interface Fact {
     id: string;
@@ -74,6 +122,13 @@ interface Fact {
      * (the cover, narrative disclosures) render their content instead of a blank.
      */
     textValue?: string | null;
+    /**
+     * The fact's dimensional coordinate — one qualifier per axis, ordered by axis.
+     * Absent/empty means a consolidated (undimensioned) fact. Part of the fact's
+     * identity: the pivot engine keys cells by `(element, period, dimensions)`, so
+     * segment/component breakdowns no longer overwrite the consolidated total.
+     */
+    dimensions?: DimensionQualifier[];
 }
 /** A calculation arc: `parent` (subtotal) rolls up `child * weight`. */
 interface CalcAssociation {
@@ -169,6 +224,112 @@ interface Statement {
     columns: StatementColumn[];
     rows: StatementRow[];
 }
+/**
+ * A reference to one fact aspect, for assigning it a pivot role. `concept`,
+ * `period`, `entity`, `unit` are the single-valued builtins; `dim:<axisIri>`
+ * names a dimensional axis. String-form so a config round-trips through JSON or
+ * a UI control (e.g. `dim:us-gaap:StatementEquityComponentsAxis`).
+ */
+type AspectKey = 'concept' | 'period' | 'entity' | 'unit' | `dim:${string}`;
+/** Display scale for monetary values; `auto` infers from the facts' decimals. */
+type Scale = 'auto' | 'ones' | 'thousands' | 'millions' | 'billions';
+/**
+ * A pivot configuration: which aspects lay out as rows, which as columns, and
+ * which are held fixed as slicers. `defaultPivotConfig` derives one per section
+ * (concept→rows, period + multi-member dimensions→columns, entity + single-member
+ * dimensions→slicers); a caller may override any of it.
+ */
+interface PivotConfig {
+    rows: AspectKey[];
+    columns: AspectKey[];
+    slicers: AspectKey[];
+    scale: Scale;
+    /** Emit abstract concept rows as group headers (default true). */
+    showAbstracts: boolean;
+    /**
+     * Drop a period column with fewer than two populated facts when the densest
+     * period has several (default true). This removes lone stragglers — e.g. an
+     * equity opening balance that leaked into the balance-sheet factset — without
+     * ever touching a real comparative period (which repeats many line items).
+     * Metadata-safe: unlike the old fact filter, cells still own their own facts.
+     */
+    dropSparsePeriods?: boolean;
+}
+/** An aspect held fixed for the whole table, rendered as a header bar. */
+interface PivotSlicer {
+    aspect: AspectKey;
+    /** e.g. `Reporting Entity` or `Equity Components [Axis]`. */
+    label: string;
+    /** e.g. `NVIDIA CORP`, `Consolidated`, `USD`. */
+    valueLabel: string;
+}
+/** One leaf column — a single combination of the column aspects. */
+interface PivotColumn {
+    /** Stable key: signature of this column's coordinate. */
+    key: string;
+    /** The period, when period is a column aspect (else null). */
+    period: PeriodInfo | null;
+    /** The member coordinate, when dimensions are column aspects (else empty). */
+    members: DimensionQualifier[];
+    /** Leaf header label (a date, a member name, …). */
+    label: string;
+}
+/** A column-header cell spanning one level of the (possibly nested) column tree. */
+interface PivotColumnHeader {
+    label: string;
+    /** colspan across leaf columns. */
+    span: number;
+}
+/** One value in a pivot row, plus the fact behind it (for inspection / footing). */
+interface PivotCell {
+    value: number | null;
+    fact: Fact | null;
+    /** Raw string for a non-numeric fact, when `value` is null. */
+    textValue?: string | null;
+}
+/** One rendered pivot line. */
+interface PivotRow {
+    /** Stable key: element id + dimensional signature (when dims are on rows). */
+    key: string;
+    element: ElementInfo;
+    /** Indent depth in the concept tree — drives indentation. */
+    depth: number;
+    /** A concept header row (abstract) — carries no values. */
+    header: boolean;
+    /** A calculation parent (roll-up) — rendered emphasized. */
+    isSubtotal: boolean;
+    /** The member coordinate, when dimensions are row aspects (else empty). */
+    members: DimensionQualifier[];
+    /** One cell per leaf column, aligned by index (empty for header rows). */
+    cells: PivotCell[];
+}
+/** Resolved display scale + a caption for the section header. */
+interface ResolvedScale {
+    /** Divide monetary values by this (1 for ones, 1e6 for millions). */
+    factor: number;
+    /** `millions`, `thousands`, `billions`, or '' when unscaled. */
+    label: string;
+    /** Header caption, e.g. `In millions, except per-share amounts`, or null. */
+    caption: string | null;
+}
+/** A fully pivoted section — the render input, and the raw fact table's source. */
+interface PivotTable {
+    ib: InformationBlock;
+    blockType: string;
+    title: string;
+    structureName: string | null;
+    /** Aspects held fixed for the whole table, shown as header bars. */
+    slicers: PivotSlicer[];
+    /** Column header rows, outermost level first (period over members). */
+    columnHeaders: PivotColumnHeader[][];
+    /** Leaf columns; row cells align to these by index. */
+    columns: PivotColumn[];
+    rows: PivotRow[];
+    /** Resolved display scale (factor + caption). */
+    scale: ResolvedScale;
+    /** The configuration this table was built from (default, unless overridden). */
+    config: PivotConfig;
+}
 
 /** Injected transport — runs a read-only Cypher query and returns its rows. */
 type SecQuery = (cypher: string, params?: Record<string, unknown>) => Promise<Array<Record<string, unknown>>>;
@@ -269,4 +430,4 @@ declare function jsonldFileAdapter(doc: string | object, source?: string): Repor
 /** Traverse a populated quad `Store` into the normalized report model. */
 declare function parseStore(store: Store): NormalizedReport;
 
-export { type BalanceType as B, type CalcAssociation as C, type ElementInfo as E, type Fact as F, type InformationBlock as I, type NormalizedReport as N, type PeriodInfo as P, type ReportAdapter as R, type Statement as S, type UnitInfo as U, type StatementRow as a, type CypherAdapterConfig as b, type EntityInfo as c, type PeriodType as d, type PresAssociation as e, type RowCell as f, type SecQuery as g, type SecReportShell as h, type SecSection as i, type StatementColumn as j, type StructureInfo as k, cypherAdapter as l, fetchSecReportShell as m, fetchSecSection as n, jsonldFileAdapter as o, mergeSecSections as p, parseJsonld as q, parseStore as r, parseStructureDefinition as s };
+export { type AspectKey as A, type BalanceType as B, type CalcAssociation as C, type DimensionQualifier as D, type ElementInfo as E, type Fact as F, parseJsonld as G, parseStore as H, type InformationBlock as I, parseStructureDefinition as J, type NumericKind as N, type PeriodInfo as P, type ReportAdapter as R, type Scale as S, type UnitInfo as U, type NormalizedReport as a, type PivotConfig as b, type PivotTable as c, type PivotRow as d, type CypherAdapterConfig as e, type EntityInfo as f, type PeriodType as g, type PivotCell as h, type PivotColumn as i, type PivotColumnHeader as j, type PivotSlicer as k, type PresAssociation as l, type ResolvedScale as m, type RowCell as n, type SecQuery as o, type SecReportShell as p, type SecSection as q, type Statement as r, type StatementColumn as s, type StatementRow as t, type StructureInfo as u, cypherAdapter as v, fetchSecReportShell as w, fetchSecSection as x, jsonldFileAdapter as y, mergeSecSections as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PeriodInfo, E as ElementInfo, N as NormalizedReport, S as Statement, a as StatementRow } from './index-D6FzPTm5.js';
-export { B as BalanceType, C as CalcAssociation, b as CypherAdapterConfig, c as EntityInfo, F as Fact, I as InformationBlock, d as PeriodType, e as PresAssociation, R as ReportAdapter, f as RowCell, g as SecQuery, h as SecReportShell, i as SecSection, j as StatementColumn, k as StructureInfo, U as UnitInfo, l as cypherAdapter, m as fetchSecReportShell, n as fetchSecSection, o as jsonldFileAdapter, p as mergeSecSections, q as parseJsonld, r as parseStore, s as parseStructureDefinition } from './index-D6FzPTm5.js';
+import { N as NumericKind, P as PeriodInfo, E as ElementInfo, a as NormalizedReport, I as InformationBlock, b as PivotConfig, c as PivotTable, d as PivotRow, U as UnitInfo } from './index-BS6_6h3l.js';
+export { A as AspectKey, B as BalanceType, C as CalcAssociation, e as CypherAdapterConfig, D as DimensionQualifier, f as EntityInfo, F as Fact, g as PeriodType, h as PivotCell, i as PivotColumn, j as PivotColumnHeader, k as PivotSlicer, l as PresAssociation, R as ReportAdapter, m as ResolvedScale, n as RowCell, S as Scale, o as SecQuery, p as SecReportShell, q as SecSection, r as Statement, s as StatementColumn, t as StatementRow, u as StructureInfo, v as cypherAdapter, w as fetchSecReportShell, x as fetchSecSection, y as jsonldFileAdapter, z as mergeSecSections, G as parseJsonld, H as parseStore, J as parseStructureDefinition } from './index-BS6_6h3l.js';
 import * as react from 'react';
 import 'n3';
 
@@ -54,8 +54,72 @@ declare function formatMoney(value: number | null | undefined, opts?: {
 }): string;
 /** `2024-03-31` → `Mar 31, 2024`. Falls back to the raw string if unparseable. */
 declare function formatDate(iso: string | null | undefined): string;
+/**
+ * Humanize an ISO-8601 duration value (`P10Y` → "10 years", `P1Y6M` → "1 year 6
+ * months", `P30D` → "30 days"), or null when the string is not a duration — so a
+ * non-numeric fact that happens to start with "P" (a company name) is untouched.
+ * XBRL `durationItemType` facts (debt maturities, lease terms) arrive as these
+ * strings in the text path.
+ */
+declare function humanizeDuration(value: string | null | undefined): string | null;
 /** A human description of a period — "As of …" for instants, a span for durations. */
 declare function formatPeriod(period: PeriodInfo): string;
+/** The effective numeric kind of an element (explicit, else derived from monetary). */
+declare function numericKindOf(el: ElementInfo): NumericKind;
+/**
+ * A display prefix for a monetary unit measure (`iso4217:USD` → `$`), else null.
+ * Unknown currencies fall back to their code (`CHF `, `SEK `) rather than a wrong
+ * dollar sign — this is what fixes non-USD facts rendering as `$`.
+ */
+declare function currencySymbolFor(measure: string | null | undefined): string | null;
+interface ValueFormat {
+    /** Drives symbol, scaling opt-out, and decimal places. Defaults to `monetary`. */
+    numericKind?: NumericKind;
+    /** Currency symbol for monetary/per-share values (from the fact's unit). */
+    symbol?: string | null;
+    /** Divide monetary values by this (e.g. 1e6 to show millions); default 1. */
+    scaleFactor?: number;
+}
+/**
+ * Format a fact value for display: accounting style (negatives in parentheses,
+ * em-dash for absent), the fact's own currency symbol (never a hard-coded `$`),
+ * and the section scale — with per-share amounts and share counts never rescaled
+ * (an EPS of 4.93 stays 4.93 under "in millions"). A `percent` fact stores a
+ * decimal fraction, so it is scaled ×100 and suffixed with `%` (0.10 → 10%); a
+ * `pure` fact is a bare ratio, shown as a plain decimal (no `%`).
+ */
+declare function formatValue(value: number | null | undefined, fmt?: ValueFormat): string;
+
+/**
+ * Derive the default pivot for a section from the aspects its facts actually
+ * carry: concept on rows, period on columns, entity a slicer, and each dimension
+ * axis on columns when it has more than one member (a real breakdown) or a slicer
+ * when it has just one (diced to a single member, e.g. `Consolidated [Domain]`).
+ */
+declare function defaultPivotConfig(model: NormalizedReport, ib: InformationBlock): PivotConfig;
+/**
+ * Move every dimension axis to one side of the pivot — the toggle behind a
+ * "dimensions as rows / columns" control. Concept stays on rows and period on
+ * columns; only `dim:*` aspects move. Rows (nested breakdowns) is the default;
+ * columns gives the side-by-side matrix (equity components across the top).
+ */
+declare function pivotDimensionsOn(config: PivotConfig, placement: 'rows' | 'columns'): PivotConfig;
+/**
+ * Pivot one section into a `PivotTable`. Pass `config` to override the default
+ * arrangement (e.g. move a high-arity axis from columns to rows).
+ */
+declare function buildPivot(model: NormalizedReport, ib: InformationBlock, config?: PivotConfig): PivotTable;
+/** Section metadata (id + display title) for a report, in canonical order. */
+declare function reportSections(model: NormalizedReport): Array<{
+    id: string;
+    title: string;
+}>;
+/**
+ * Pivot every section of a report, in canonical block order. `configFor` may
+ * transform each section's default config before it is built — e.g. to apply a
+ * "dimensions as rows / columns" toggle across the whole report.
+ */
+declare function buildPivots(model: NormalizedReport, configFor?: (ib: InformationBlock, defaultConfig: PivotConfig) => PivotConfig): PivotTable[];
 
 interface OrderEntry {
     order: number;
@@ -64,26 +128,20 @@ interface OrderEntry {
 /**
  * Post-order the presentation arcs of one structure → `{element: {order, depth}}`.
  * Roots (a `from` that is never a `to`) are visited by their subtree's leading
- * arc order, so a balance sheet's roots (Assets, then Liabilities and Equity)
- * come out in the right sequence.
+ * arc order. Retained as a reusable utility; the pivot engine builds its own
+ * pre-order tree (it needs abstract headers), but external callers may still want
+ * a flat order map.
  */
 declare function presentationOrder(model: NormalizedReport, structureId: string): Map<string, OrderEntry>;
 /** Concepts that are calculation parents — the authoritative subtotal set. */
 declare function calcSubtotals(model: NormalizedReport): Set<string>;
-/** Section metadata (id + display title) for a report, in canonical order. */
-declare function reportSections(model: NormalizedReport): Array<{
-    id: string;
-    title: string;
-}>;
 /**
  * Narrow a whole report to a single section (one Information Block) so it can be
- * rendered on its own. `buildStatements` only iterates `informationBlocks`, so
- * restricting to one yields exactly that section — the facts, structures, and
- * networks stay intact because `buildStatement` filters them by the block.
+ * rendered on its own. `buildPivots` only iterates `informationBlocks`, so
+ * restricting to one yields exactly that section — facts, structures, and
+ * networks stay intact because the pivot filters them by the block.
  */
 declare function sliceReportSection(model: NormalizedReport, informationBlockId: string): NormalizedReport;
-/** Reconstruct every statement in the report, in canonical block order. */
-declare function buildStatements(model: NormalizedReport): Statement[];
 interface FootTerm {
     element: ElementInfo;
     weight: number;
@@ -102,9 +160,10 @@ interface FootCheck {
 /**
  * Foot a subtotal live: sum its calculation children (× weight) and compare to
  * its reported value, e.g. `13,550 + 900 = 14,450 ✓`. Returns `null` when the
- * element is not a calculation parent (nothing to foot).
+ * element is not a calculation parent (nothing to foot). Values are read from the
+ * consolidated (undimensioned) row for each concept.
  */
-declare function footCheck(model: NormalizedReport, statement: Statement, elementId: string, columnIndex: number): FootCheck | null;
+declare function footCheck(model: NormalizedReport, table: PivotTable, elementId: string, columnIndex: number): FootCheck | null;
 
 interface ExternalTextBlockProps {
     url: string;
@@ -113,34 +172,38 @@ declare function ExternalTextBlock({ url }: ExternalTextBlockProps): react.JSX.E
 
 interface FactInspectorProps {
     report: NormalizedReport;
-    statement: Statement;
-    row: StatementRow;
+    table: PivotTable;
+    row: PivotRow;
     columnIndex: number;
     onClose?: () => void;
-    currencySymbol?: string;
 }
-declare function FactInspector({ report, statement, row, columnIndex, onClose, currencySymbol, }: FactInspectorProps): react.JSX.Element;
+declare function FactInspector({ report, table, row, columnIndex, onClose }: FactInspectorProps): react.JSX.Element;
 
 interface ReportViewProps {
     report: NormalizedReport;
-    currencySymbol?: string;
     /** Disable the click-to-inspect fact panel (render-only). */
     inspect?: boolean;
+    /** Initial placement for dimension breakdowns (default `rows`). */
+    dimensionAxis?: 'rows' | 'columns';
 }
-declare function ReportView({ report, currencySymbol, inspect }: ReportViewProps): react.JSX.Element;
+declare function ReportView({ report, inspect, dimensionAxis }: ReportViewProps): react.JSX.Element;
 
 interface StatementTableProps {
-    statement: Statement;
+    table: PivotTable;
+    /** The report's units, to resolve each cell's currency symbol. */
+    units?: Record<string, UnitInfo>;
     /** Called when a value cell is clicked — drives fact inspection. */
-    onCellClick?: (row: StatementRow, columnIndex: number) => void;
-    /** Currency symbol for values (default `$`). */
-    currencySymbol?: string;
+    onCellClick?: (row: PivotRow, columnIndex: number) => void;
     /** The currently-selected cell, highlighted. */
     selected?: {
-        elementId: string;
+        rowKey: string;
         columnIndex: number;
     } | null;
+    /** Current dimension placement — set with `onDimensionPlacementChange` to show the toggle. */
+    dimensionPlacement?: 'rows' | 'columns';
+    /** Setter for the dimension placement; when provided (and the section is dimensional), a rows/columns toggle renders below the slicers. */
+    onDimensionPlacementChange?: (placement: 'rows' | 'columns') => void;
 }
-declare function StatementTable({ statement, onCellClick, currencySymbol, selected, }: StatementTableProps): react.JSX.Element;
+declare function StatementTable({ table, units, onCellClick, selected, dimensionPlacement, onDimensionPlacementChange, }: StatementTableProps): react.JSX.Element;
 
-export { BLOCK_ORDER, BLOCK_TITLES, ElementInfo, ExternalTextBlock, type ExternalTextBlockProps, FactInspector, type FactInspectorProps, type FootCheck, type FootTerm, NS, NormalizedReport, PeriodInfo, ReportView, type ReportViewProps, Statement, StatementRow, StatementTable, type StatementTableProps, buildStatements, calcSubtotals, footCheck, formatDate, formatMoney, formatPeriod, humanize, isExternalFactUrl, presentationOrder, qname, reportSections, sliceReportSection };
+export { BLOCK_ORDER, BLOCK_TITLES, ElementInfo, ExternalTextBlock, type ExternalTextBlockProps, FactInspector, type FactInspectorProps, type FootCheck, type FootTerm, InformationBlock, NS, NormalizedReport, NumericKind, PeriodInfo, PivotConfig, PivotRow, PivotTable, ReportView, type ReportViewProps, StatementTable, type StatementTableProps, UnitInfo, type ValueFormat, buildPivot, buildPivots, calcSubtotals, currencySymbolFor, defaultPivotConfig, footCheck, formatDate, formatMoney, formatPeriod, formatValue, humanize, humanizeDuration, isExternalFactUrl, numericKindOf, pivotDimensionsOn, presentationOrder, qname, reportSections, sliceReportSection };