@turquoisehealth/pit-viper 2.197.3-dev.1 → 2.198.0

package/pv-components/dist/vue/visualizations/components/charts/PvDataWidget/types.d.ts

@@ -0,0 +1,130 @@
+import { AgChartOptions } from 'ag-charts-types';
+export type PvDataWidgetChartType = "area" | "bar" | "bar_stacked" | "column" | "column_stacked" | "histogram" | "line" | "map" | "pie" | "scatter";
+export type PvDataWidgetViewType = PvDataWidgetChartType | "table" | (string & {});
+export type PvDataWidgetDataRow = Record<string, unknown>;
+export interface PvDataWidgetTableHeader {
+    /** Field identifier for this table column. */
+    field: string;
+    /** Resolved display label for this table column. */
+    label: string;
+}
+export interface PvDataWidgetTableProps {
+    /** Header cells rendered in the table head. */
+    headers: PvDataWidgetTableHeader[];
+    /** Pre-resolved string cells, one inner array per row. */
+    rows: string[][];
+}
+export interface PvDataWidgetColumnDefinition {
+    /**
+     * Optional context compatible with AG Grid ColDef context for simple data definitions.
+     * `context.dataType` takes precedence over the top-level `dataType` and `type` hints.
+     */
+    context?: {
+        [key: string]: unknown;
+        chartOnSecondaryAxes?: boolean;
+        chartSeriesDescription?: string;
+        chartSeriesDisplayName?: string;
+        dataType?: string;
+        hideFromCharting?: boolean;
+    };
+    /** Data type hint used to infer categories and series without formatter functions. Falls back to `type` and is superseded by `context.dataType`. */
+    dataType?: string;
+    /** Field name in each data row. */
+    field: string;
+    /** Display label for table headers, axes, and series names. */
+    headerName?: string;
+    /** Hide this column from generated charts and tables. */
+    hide?: boolean;
+    /** Data type hint alias for A2UI-style definitions. */
+    type?: string;
+    /** Allow simple AG Grid ColDef-style objects without requiring JS formatter support. */
+    [key: string]: unknown;
+}
+export interface PvDataWidgetChartTypeOption {
+    /** Accessible label for icon-only segmented controls. */
+    ariaLabel?: string;
+    /** Icon displayed in the segmented control. */
+    icon?: string;
+    /** Visible label displayed in the segmented control. */
+    label?: string;
+    /** Stable chart/view type value. */
+    value?: PvDataWidgetViewType;
+}
+export interface PvDataWidgetProps {
+    /** Applied filter labels rendered in the header area. */
+    appliedFilters?: string[];
+    /** Data rows used for generated chart and table views. */
+    chartData?: PvDataWidgetDataRow[];
+    /** Loading state passed to generated charts. */
+    chartLoading?: boolean;
+    /** AG Charts options. When supplied, these are used for chart rendering. */
+    chartOptions?: AgChartOptions;
+    /**
+     * Chart/view types available in the header segmented control. Accepts simple
+     * string values (e.g. `["column", "table"]`) or full option objects with custom
+     * labels and icons. At least one non-table chart type is always guaranteed.
+     */
+    chartTypes?: (PvDataWidgetViewType | PvDataWidgetChartTypeOption)[];
+    /** Column definitions used to infer labels and numeric/category fields. Compatible with simple AG Grid ColDefs. */
+    colDefs?: PvDataWidgetColumnDefinition[];
+    /** Maximum number of data rows rendered in generated chart and table views. Set to `0` to render no rows. */
+    dataLimit?: number;
+    /** When true, wraps large generated charts in a native Pit Viper-styled scroll container. */
+    enableChartScrolling?: boolean;
+    /**
+     * When true, scrolls table overflow. The body is capped by `tableMaxHeight` when set,
+     * otherwise by the constrained flex layout (i.e. a bounded widget `height`/`maxHeight`).
+     */
+    enableTableScrolling?: boolean;
+    /** Widget height. Numbers are treated as pixel values; strings are passed through as CSS values. */
+    height?: number | string;
+    /**
+     * When true, hides cartesian axis labels, ticks, lines, titles, and grid lines.
+     * Supersedes `hideAxisTitles` and `hideValueAxis` — the whole axis is hidden.
+     */
+    hideAxes?: boolean;
+    /** When true, hides axis titles (e.g. "Plan Type") while keeping tick labels. */
+    hideAxisTitles?: boolean;
+    /** When true, hides the chart legend on generated charts. */
+    hideLegend?: boolean;
+    /** When true, hides the numeric value axis while keeping the category (x) axis labels. */
+    hideValueAxis?: boolean;
+    /** Data field containing map region values. Defaults to `state` when present. */
+    mapKey?: string;
+    /** Maximum widget height. Numbers are treated as pixel values; strings are passed through as CSS values. */
+    maxHeight?: number | string;
+    /** Maximum widget width. Numbers are treated as pixel values; strings are passed through as CSS values. */
+    maxWidth?: number | string;
+    /**
+     * Minimum pixel height for generated charts. Required as a number because ag-charts
+     * sizes its canvas from an explicit height rather than CSS alone.
+     */
+    minHeight?: number;
+    /**
+     * Overlay text shown when a generated chart has no data. When omitted, the chart's
+     * own default overlay text is used.
+     */
+    noDataOverlayText?: string;
+    /** When true, renders value labels on generated cartesian series (e.g. above bars). */
+    showSeriesLabels?: boolean;
+    /**
+     * When true, renders the data table beneath the chart for non-table view types.
+     * Independent of whether `table` appears in the view toggle. The below-table is
+     * hidden when `table` is the selected view (a table is never stacked under a table).
+     */
+    showTableBelowChart?: boolean;
+    /** When true (default), shows the chart/table type toggle in the header. */
+    showWidgetTypeToggle?: boolean;
+    /** Field used as the generated stacked chart grouping key. Defaults to the second category-like column. */
+    stackKey?: string;
+    /** Maximum table container height when table scrolling is enabled. Numbers are treated as pixel values. */
+    tableMaxHeight?: number | string;
+    /** Title displayed in the widget header. */
+    title?: string;
+    /** Widget width. Numbers are treated as pixel values; strings are passed through as CSS values. */
+    width?: number | string;
+    /** Field used as the generated chart category/x-axis. */
+    xKey?: string;
+    /** Field used as the generated chart series/y-axis. */
+    yKey?: string;
+}

package/pv-components/dist/vue/visualizations/components/charts/PvDataWidget/usePvDataWidgetData.d.ts

@@ -0,0 +1,40 @@
+import { ComputedRef, Ref, WatchSource } from 'vue';
+import { PvDataWidgetDataRow, PvDataWidgetProps } from './types';
+/** Overlay text shown when a data handler fails and no `errorText` option is provided. */
+export declare const DEFAULT_DATA_WIDGET_ERROR_TEXT = "Unable to load data";
+/** Fetches the data rows for a PvDataWidget, e.g. from an API. */
+export type PvDataWidgetDataHandler = () => PvDataWidgetDataRow[] | Promise<PvDataWidgetDataRow[]>;
+export interface UsePvDataWidgetDataOptions {
+    /** Overlay text shown on the widget when the handler fails. */
+    errorText?: string;
+    /** When false, data is not fetched until `refresh` is called. Defaults to true. */
+    immediate?: boolean;
+    /** Reactive sources (e.g. filter state) that trigger a refetch when changed. */
+    watch?: WatchSource | WatchSource[];
+}
+export interface UsePvDataWidgetDataReturn {
+    /** Rows returned by the most recent successful handler call. */
+    chartData: Ref<PvDataWidgetDataRow[]>;
+    /** True while a handler call is pending. */
+    chartLoading: Ref<boolean>;
+    /** Error from the most recent handler call, cleared on the next successful call. */
+    error: Ref<Error | undefined>;
+    /** Re-invokes the handler. Resolves when the call settles. */
+    refresh: () => Promise<void>;
+    /**
+     * Spreadable PvDataWidget props: `chartData`, `chartLoading`, and — only while in an
+     * error state — `noDataOverlayText`. Place `v-bind="widgetProps"` after your own
+     * bindings: your `noDataOverlayText` then applies to genuinely empty data, while the
+     * error text takes precedence when a fetch fails.
+     */
+    widgetProps: ComputedRef<Pick<PvDataWidgetProps, "chartData" | "chartLoading" | "noDataOverlayText">>;
+}
+/**
+ * Manages the fetch lifecycle for a PvDataWidget whose rows come from an async
+ * source: loading state, error-to-overlay mapping, stale-response protection,
+ * and refetching on demand or when watched sources change.
+ *
+ * Entirely optional — PvDataWidget itself stays a pure presentational component
+ * and can be fed `chartData` directly.
+ */
+export declare const usePvDataWidgetData: (handler: PvDataWidgetDataHandler, options?: UsePvDataWidgetDataOptions) => UsePvDataWidgetDataReturn;

package/pv-components/dist/vue/visualizations/components/charts/PvMapChart/PvMapChart.vue.d.ts

@@ -12,15 +12,9 @@ export interface PvMapChartProps {
     seriesKey: string;
     /** The geographic granularity of the map. Currently only `"state"` is fully supported. */
     mapType?: MapTopologyType;
-    /**
-     * Reserved for future use. Currently has no effect on rendering; the color gradient legend
-     * below the map is always rendered.
-     */
+    /** When true, renders the color gradient legend above the map. */
     displayGradientLegend?: boolean;
-    /**
-     * Reserved for future use. Currently has no effect on rendering; the region selector dropdown
-     * is always rendered.
-     */
+    /** When true, renders the region selector dropdown above the map. */
     displayRegionSelector?: boolean;
     /** Minimum value for the gradient legend scale. */
     gradientLegendMin?: number;
@@ -54,6 +48,7 @@ declare const _default: DefineComponent<{
     isLoading: boolean;
     mapType: MapTopologyType;
     displayGradientLegend: boolean;
+    displayRegionSelector: boolean;
     gradientLegendMin: number;
     gradientLegendMax: number;
     seriesValueFormatter: (value: number) => string;

package/pv-components/dist/vue/visualizations/components/charts/widgetOptions.d.ts

@@ -0,0 +1,58 @@
+import { AgChartOptions } from 'ag-charts-types';
+type ChartRecord = Record<string, unknown>;
+/** Pixels of horizontal width allotted per data point when a chart scrolls horizontally. */
+export declare const CHART_SCROLL_ITEM_WIDTH_PX = 56;
+/** Pixels of vertical height allotted per data point when a horizontal-bar chart scrolls. */
+export declare const CHART_SCROLL_ITEM_HEIGHT_PX = 32;
+/** Coerce a numeric (pixel) or string CSS size into a CSS length, or `undefined` when unset. */
+export declare const getCssSize: (value: number | string | undefined) => string | undefined;
+/**
+ * Build the explicit `height`/`width` (and matching `max-*`) style for a widget shell.
+ * An explicit dimension also caps its `max-*` so the widget never grows past it.
+ */
+export declare const buildWidgetStyle: (dimensions: {
+    height?: number | string;
+    maxHeight?: number | string;
+    maxWidth?: number | string;
+    width?: number | string;
+}) => Record<string, string>;
+/** Whether any explicit dimension bounds the widget shell (switching it to constrained flex layout). */
+export declare const getIsWidgetConstrained: (dimensions: {
+    height?: number | string;
+    maxHeight?: number | string;
+    maxWidth?: number | string;
+    width?: number | string;
+}) => boolean;
+/**
+ * Minimum chart height for a widget: when a horizontal-bar chart scrolls vertically,
+ * grow past the base height so every data point keeps its allotted row height.
+ */
+export declare const getScrollableChartMinHeight: (params: {
+    baseMinHeight: number;
+    dataCount: number;
+    enableChartScrolling: boolean;
+    isHorizontalScrollingChart: boolean;
+}) => number;
+/**
+ * Inline style for the scrollable chart content: horizontal-bar charts grow vertically
+ * per data point; all other charts grow horizontally, never below `minContentWidth`.
+ */
+export declare const getChartScrollContentStyle: (params: {
+    chartMinHeight: number;
+    dataCount: number;
+    enableChartScrolling: boolean;
+    isHorizontalScrollingChart: boolean;
+    minContentWidth: number;
+}) => Record<string, string> | undefined;
+/** Coerce to a plain object record, or `undefined` when the value is not one. */
+export declare const asObjectRecord: (value: unknown) => ChartRecord | undefined;
+export declare const limitDataRows: <T>(data: T[], dataLimit: number | undefined) => T[];
+export declare const getChartDataLength: (options: AgChartOptions) => number;
+export declare const getIsHorizontalBarChart: (options: AgChartOptions) => boolean;
+export declare const applyChartWidgetOptions: (options: AgChartOptions, config: {
+    dataLimit?: number;
+    hideAxisTitles?: boolean;
+    hideValueAxis?: boolean;
+    showAxes?: boolean;
+}) => AgChartOptions;
+export {};

package/pv-components/dist/vue/visualizations/components/visualizations/index.d.ts

@@ -1,4 +1,6 @@
 export { default as PvChart } from '../charts/PvChart/PvChart.vue';
+export { default as PvChartWidget } from '../charts/PvChartWidget/PvChartWidget.vue';
+export { default as PvDataWidget } from '../charts/PvDataWidget/PvDataWidget.vue';
 export { default as PvDataTableWithChart } from '../charts/PvDataTableWithChart/PvDataTableWithChart.vue';
 export { default as PvMapChart } from '../charts/PvMapChart/PvMapChart.vue';
 export { SCATTER_MARKER_STROKE, PitViperAGChartsMonochromeTheme, PitViperAGChartsMonochromeThemeName, PitViperAGChartsMulticolorTheme, PitViperAGChartsMulticolorThemeName, } from '../charts/themes';
@@ -6,6 +8,10 @@ export { default as PvDataTable } from '../tables/PvDataTable/PvDataTable.vue';
 export { createPvDataTableFilterStore, providePvDataTableFilterStore, usePvDataTableFilterStore, } from '../tables/PvDataTable/useFilterStore';
 export type { PvDataTableFilterController, PvDataTableFilterModel, PvDataTableFilterStore, } from '../tables/PvDataTable/useFilterStore';
 export type { FocusUpdateEvent, FilterValueResponseOption, FilterRendererProps } from '../tables/PvDataTable/types';
+export type { PvChartWidgetMiniChartMode, PvChartWidgetProps, PvChartWidgetSlotProps, } from '../charts/PvChartWidget/types';
+export type { PvDataWidgetChartType, PvDataWidgetChartTypeOption, PvDataWidgetColumnDefinition, PvDataWidgetDataRow, PvDataWidgetProps, PvDataWidgetViewType, } from '../charts/PvDataWidget/types';
+export { DEFAULT_DATA_WIDGET_ERROR_TEXT, usePvDataWidgetData } from '../charts/PvDataWidget/usePvDataWidgetData';
+export type { PvDataWidgetDataHandler, UsePvDataWidgetDataOptions, UsePvDataWidgetDataReturn, } from '../charts/PvDataWidget/usePvDataWidgetData';
 export type { CrosslineOverlayGroup, VerticalLineOverlay } from '../charts/PvDataTableWithChart/types';
 export { constructAdvancedFilterCondition, convertFilterModelToAdvanced, filterModelContainsColId, mergeFilterModels, getSelectedValuesFromFilterModel, filterModelsEqual, mergeAdvancedFilterCondition, removeColumnFromAdvancedFilter, getSelectedValuesFromAdvancedFilterModel, isAdvancedFilterModel, isFilterModelEmpty, getSelectedValues, getSelectedValuesFromFilterModelByColId, updateSetFilter, updateMultiOrSetFilter, removeColumnFilter, excludeValueFromSetFilter, } from '../tables/PvDataTable/filters/filterHelpers';
 export type { AnyFilterModel } from '../tables/PvDataTable/filters/filterHelpers';