@factorialco/f0-react 1.396.0 → 1.397.0

package/dist/f0.d.ts

@@ -39,6 +39,7 @@ import { default as default_2 } from 'react';
 import { DeltaCellValue } from './types/delta';
 import { DotTagCellValue } from './f0';
 import { DotTagCellValue as DotTagCellValue_2 } from './types/dotTag';
+import { F0AnalyticsDashboardProps as F0AnalyticsDashboardProps_2 } from './types';
 import { F0AvatarCompanyProps as F0AvatarCompanyProps_2 } from './types';
 import { F0AvatarDateProps } from './F0AvatarDate';
 import { F0AvatarEmojiProps as F0AvatarEmojiProps_2 } from './F0AvatarEmoji';
@@ -62,6 +63,7 @@ import { f1Colors } from '@factorialco/f0-core';
 import { FC } from 'react';
 import { FileCellValue } from './f0';
 import { FileCellValue as FileCellValue_2 } from './types/file';
+import { FiltersDefinition as FiltersDefinition_2 } from './f0';
 import { FolderCellValue } from './f0';
 import { FolderCellValue as FolderCellValue_2 } from './types/folder';
 import { ForwardedRef } from 'react';
@@ -82,7 +84,7 @@ import { internalAvatarColors as internalAvatarColors_2 } from './f0';
 import { internalAvatarSizes as internalAvatarSizes_2 } from './f0';
 import { internalAvatarTypes as internalAvatarTypes_2 } from './f0';
 import { JSX as JSX_2 } from 'react';
-import { LineChartConfig } from './f0';
+import { LineChartConfig as LineChartConfig_2 } from './f0';
 import { LineChartPropsBase } from './utils/types';
 import { LocalAudioTrack } from 'livekit-client';
 import { LongTextCellValue } from './types/longText';
@@ -594,7 +596,7 @@ declare type AnimationVariantsOptions = {
     maxDelay?: number;
 };
 
-export declare const AreaChart: WithDataTestIdReturnType_5<ForwardRefExoticComponent<Omit<LineChartPropsBase<LineChartConfig> & {
+export declare const AreaChart: WithDataTestIdReturnType_5<ForwardRefExoticComponent<Omit<LineChartPropsBase<LineChartConfig_2> & {
 lineType?: "step" | "linear" | "natural" | "monotoneX";
 marginTop?: number;
 canBeBlurred?: boolean;
@@ -726,6 +728,14 @@ values: {
 }) => void) | undefined;
 } & RefAttributes<HTMLDivElement>, "ref"> & RefAttributes<HTMLElement | SVGElement>>>;
 
+export declare interface BarChartConfig extends ChartConfigBase {
+    type: "bar";
+    /** @default "vertical" */
+    orientation?: "vertical" | "horizontal";
+    /** Stack all series into a single bar per category. @default false */
+    stacked?: boolean;
+}
+
 declare type BaseAction = {
     label: string;
     onClick: () => Promise<void> | void;
@@ -1378,6 +1388,28 @@ declare type CardVisualizationOptions<T, _Filters extends FiltersDefinition, _So
 
 export declare const CategoryBarChart: WithDataTestIdReturnType_5<ForwardRefExoticComponent<Omit<CategoryBarProps & RefAttributes<HTMLDivElement>, "ref"> & RefAttributes<HTMLElement | SVGElement>>>;
 
+/** A valid chart color token — one of the 15 chromatic F0 base-color names. */
+declare type ChartColorToken = (typeof chartColorTokens)[number];
+
+/**
+ * The 15 chromatic color names from the F0 design token palette.
+ * These are the only colors allowed for custom series / data-point colors.
+ */
+declare const chartColorTokens: readonly ["lilac", "barbie", "smoke", "army", "flubber", "indigo", "camel", "radical", "viridian", "orange", "red", "grass", "malibu", "yellow", "purple"];
+
+declare interface ChartConfigBase {
+    /** Show the legend below the chart. @default true */
+    showLegend?: boolean;
+    /** Show background grid lines. @default true */
+    showGrid?: boolean;
+    /** Show value labels on each data point. @default false */
+    showLabels?: boolean;
+    /** Format the value axis tick labels */
+    valueFormatter?: (value: number) => string;
+    /** Format category axis tick labels */
+    categoryFormatter?: (value: string) => string;
+}
+
 export declare const ChatSpinner: ForwardRefExoticComponent<Omit<SVGProps<SVGSVGElement>, "ref"> & RefAttributes<SVGSVGElement>>;
 
 /**
@@ -1710,6 +1742,116 @@ declare interface CustomFieldRenderPropsBase {
 
 export declare const Dashboard: WithDataTestIdReturnType_3<ComponentType<DashboardProps_2> & PageLayoutGroupComponent_2>;
 
+/**
+ * Chart display configuration — discriminated on `type`.
+ * This object is JSON-serializable (no functions, except optional formatters).
+ */
+export declare type DashboardChartConfig = BarChartConfig | LineChartConfig | FunnelChartConfig | PieChartConfig | RadarChartConfig | GaugeChartConfig | HeatmapChartConfig;
+
+export declare interface DashboardChartData {
+    /** Category axis labels. Required for bar/line charts. */
+    categories?: string[];
+    /** X-axis category labels for heatmap charts. */
+    xCategories?: string[];
+    /** Y-axis category labels for heatmap charts. */
+    yCategories?: string[];
+    /** Radar chart axis indicators. */
+    indicators?: F0DataChartRadarIndicator[];
+    /** Chart series data — shape depends on chart type. Omit for heatmaps. */
+    series?: F0DataChartBarSeries[] | F0DataChartLineSeries[] | F0DataChartFunnelSeries | F0DataChartPieSeries | F0DataChartRadarSeries[] | {
+        value: number;
+        name?: string;
+    };
+    /** Heatmap data points as [xIndex, yIndex, value] tuples. */
+    data?: [number, number, number][];
+}
+
+export declare interface DashboardChartItem<Filters extends FiltersDefinition = FiltersDefinition> extends DashboardItemBase {
+    type: "chart";
+    /** Visual chart configuration (JSON-serializable) */
+    chart: DashboardChartConfig;
+    /**
+     * Reserved for future use. Currently all chart cells share the same
+     * height derived from the grid column width.
+     */
+    aspectRatio?: string;
+    /** Async data fetcher — receives dashboard filters when useDashboardFilters is true */
+    fetchData: (filters: FiltersState<Filters>) => Promise<DashboardChartData>;
+}
+
+/**
+ * Minimal collection config — enough to render a table/card/list inside
+ * a dashboard widget without its own filter bar.
+ *
+ * The consumer provides `createSource` which receives the dashboard-level
+ * filters and returns a full DataCollectionSourceDefinition. The dashboard
+ * calls `useDataCollectionSource` internally.
+ */
+export declare interface DashboardCollectionItem<Filters extends FiltersDefinition = FiltersDefinition> extends DashboardItemBase {
+    type: "collection";
+    /**
+     * Factory that creates a DataCollectionSourceDefinition for this item.
+     * Called whenever dashboard filters change.
+     * The returned definition should NOT include its own filters/presets
+     * (the dashboard provides those globally).
+     */
+    createSource: (filters: FiltersState<Filters>) => any;
+    /**
+     * Visualization configs for the collection (table, card, list, kanban).
+     * Same shape as OneDataCollection's `visualizations` prop.
+     */
+    visualizations: ReadonlyArray<any>;
+}
+
+/**
+ * A single dashboard item. Discriminated on `type`.
+ *
+ * Currently supports `"chart"`, `"metric"`, and `"collection"`.
+ * Future types (e.g. `"custom"`) extend this union.
+ */
+export declare type DashboardItem<Filters extends FiltersDefinition = FiltersDefinition> = DashboardChartItem<Filters> | DashboardMetricItem<Filters> | DashboardCollectionItem<Filters>;
+
+export declare interface DashboardItemBase {
+    /** Unique key for React reconciliation and identity */
+    id: string;
+    /** Widget title displayed in the header */
+    title: string;
+    /** Optional description below the title */
+    description?: string;
+    /** Number of grid columns this item spans (1–3). @default 1 */
+    colSpan?: 1 | 2 | 3;
+    /**
+     * Whether this item receives dashboard-level filters in its fetchData.
+     * When false, fetchData receives an empty object.
+     * @default true
+     */
+    useDashboardFilters?: boolean;
+}
+
+/** Data returned by a metric item's fetchData */
+export declare interface DashboardMetricData {
+    /** The main numeric value displayed in large text */
+    value: number;
+    /** Optional previous value — used to compute a trend indicator */
+    previousValue?: number;
+}
+
+/**
+ * A single big-number KPI widget.
+ *
+ * Displays a large formatted number with optional trend indicator
+ * (up/down vs previous value). Receives dashboard filters like any other item.
+ */
+export declare interface DashboardMetricItem<Filters extends FiltersDefinition = FiltersDefinition> extends DashboardItemBase {
+    type: "metric";
+    /** How to format the value. @default { type: "number" } */
+    format?: MetricFormat;
+    /** Number of decimal places. @default 0 */
+    decimals?: number;
+    /** Async data fetcher — receives dashboard filters */
+    fetchData: (filters: FiltersState<Filters>) => Promise<DashboardMetricData>;
+}
+
 export declare type DashboardProps = GroupGridProps<DashboardWidget>;
 
 export declare type DashboardWidget = GroupGridWidget<{
@@ -3131,6 +3273,45 @@ export declare interface F0AlertProps {
     variant: AlertVariant;
 }
 
+/**
+ * @experimental This is an experimental component use it at your own risk
+ */
+export declare const F0AnalyticsDashboard: {
+    <Filters extends FiltersDefinition_2 = FiltersDefinition_2>({ filters, presets, defaultFilters, items, }: F0AnalyticsDashboardProps_2<Filters>): JSX_2.Element;
+    displayName: string;
+};
+
+/**
+ * Props for the F0AnalyticsDashboard component.
+ *
+ * The entire dashboard is defined declaratively via `filters` (optional shared
+ * filter definitions), `presets`, and `items` (an ordered array of chart /
+ * collection configs).
+ *
+ * An LLM can generate the full `items` array as JSON (minus the `fetchData`
+ * functions) to build dashboards on the fly.
+ */
+export declare interface F0AnalyticsDashboardProps<Filters extends FiltersDefinition = FiltersDefinition> {
+    /**
+     * Filter definitions for the dashboard-level filter bar.
+     * When omitted, no filter bar is rendered.
+     */
+    filters?: Filters;
+    /**
+     * Preset filter configurations shown as quick-select chips.
+     */
+    presets?: PresetsDefinition<Filters>;
+    /**
+     * Initial filter values applied when the dashboard first renders.
+     */
+    defaultFilters?: FiltersState<Filters>;
+    /**
+     * Ordered list of dashboard items to render in the grid.
+     * Each item declares its type, visual config, grid span, and data fetcher.
+     */
+    items: DashboardItem<Filters>[];
+}
+
 /**
  * Config for array fields (multi-select or multi-file)
  * @typeParam T - The value type (string or number)
@@ -3782,6 +3963,130 @@ declare type F0CustomFieldConfigWithConfig<TValue = unknown, TConfig = unknown>
     fieldType: "custom";
 };
 
+/**
+ * A single data point in a bar chart series.
+ * Can be a simple number or an object with value and optional target.
+ */
+declare type F0DataChartBarDataPoint = number | {
+    value: number;
+    /** When set, renders a gradient fade from the bar top up to the target value */
+    target?: number;
+    /** Override color for this individual bar. Must be an F0 design token name. */
+    color?: ChartColorToken;
+};
+
+/**
+ * A series of bars to render in the chart.
+ */
+declare interface F0DataChartBarSeries {
+    /** Display name used in legend and tooltip */
+    name: string;
+    /** Data points — one per category */
+    data: F0DataChartBarDataPoint[];
+    /** Override color for this series. Must be an F0 design token name. Falls back to the theme palette. */
+    color?: ChartColorToken;
+}
+
+/**
+ * A single data point in a funnel chart series.
+ * Each point has a value and a stage name.
+ */
+declare interface F0DataChartFunnelDataPoint {
+    /** Numeric value for this funnel stage */
+    value: number;
+    /** Stage label (e.g. "Applied", "Phone Screen", "Hired") */
+    name: string;
+    /** Override color for this individual stage. Must be an F0 design token name. */
+    color?: ChartColorToken;
+}
+
+/**
+ * A single funnel series with named data points.
+ */
+declare interface F0DataChartFunnelSeries {
+    /** Display name used in legend and tooltip */
+    name: string;
+    /** Data points — one per funnel stage */
+    data: F0DataChartFunnelDataPoint[];
+    /** Override color for the entire series. Must be an F0 design token name. */
+    color?: ChartColorToken;
+}
+
+/**
+ * A single data point in a line chart series.
+ * Can be a simple number or an object with a value.
+ */
+declare type F0DataChartLineDataPoint = number | {
+    value: number;
+};
+
+/**
+ * A series of data points to render as a line.
+ */
+declare interface F0DataChartLineSeries {
+    /** Display name used in legend and tooltip */
+    name: string;
+    /** Data points — one per category */
+    data: F0DataChartLineDataPoint[];
+    /** Override color for this series. Must be an F0 design token name. Falls back to the theme palette. */
+    color?: ChartColorToken;
+    /** Render this line with a dashed pattern (useful for projections/targets) */
+    dashed?: boolean;
+    /** Override line interpolation for this series */
+    lineType?: F0DataChartLineType;
+    /** Override area fill for this series */
+    showArea?: boolean;
+}
+
+/** Line interpolation type */
+declare type F0DataChartLineType = "linear" | "smooth" | "step";
+
+/**
+ * A single data point in a pie chart.
+ */
+declare interface F0DataChartPieDataPoint {
+    /** Numeric value for this segment */
+    value: number;
+    /** Segment label */
+    name: string;
+    /** Override color for this individual segment. Must be an F0 design token name. */
+    color?: ChartColorToken;
+}
+
+/**
+ * A single pie series with named data points.
+ */
+declare interface F0DataChartPieSeries {
+    /** Display name used in tooltip */
+    name: string;
+    /** Data points — one per pie segment */
+    data: F0DataChartPieDataPoint[];
+    /** Override color for the entire series. Must be an F0 design token name. */
+    color?: ChartColorToken;
+}
+
+/**
+ * A radar chart indicator (axis/dimension).
+ */
+declare interface F0DataChartRadarIndicator {
+    /** Name of the axis/dimension (e.g. "Performance", "Engagement") */
+    name: string;
+    /** Maximum value for this axis. @default auto-calculated from data */
+    max?: number;
+}
+
+/**
+ * A series of data points for a radar chart.
+ */
+declare interface F0DataChartRadarSeries {
+    /** Display name used in legend and tooltip (e.g. "Team A", "Team B") */
+    name: string;
+    /** Values — one per indicator, in the same order */
+    data: number[];
+    /** Override color for this series. Must be an F0 design token name. */
+    color?: ChartColorToken;
+}
+
 /**
  * Component that renders an optional markdown preview followed by
  * a dropdown button with "Download Excel" as the primary action and
@@ -5668,6 +5973,28 @@ declare type FullscreenChatContextType = {
     setInProgress: (value: boolean) => void;
 };
 
+export declare interface FunnelChartConfig {
+    type: "funnel";
+    /** Sort direction of funnel stages. @default "descending" */
+    sort?: "descending" | "ascending" | "none";
+    /** Funnel orientation. @default "horizontal" */
+    orient?: "horizontal" | "vertical";
+    /** Show the legend below the chart. @default false */
+    showLegend?: boolean;
+    /** Show value labels on each stage. @default true */
+    showLabels?: boolean;
+    /**
+     * Show conversion percentages in labels.
+     * Each stage displays its value as a percentage of the first stage.
+     * @default false
+     */
+    showConversion?: boolean;
+    /** Use a color scale gradient instead of distinct colors. @default true */
+    colorScale?: boolean;
+    /** Format the value displayed in labels and tooltip */
+    valueFormatter?: (value: number) => string;
+}
+
 /**
  * Gap tokens for spacing between flex/grid children.
  * Uses betweenSpacing (rem) for sm–xl, absoluteSpacing (px) for extended sizes.
@@ -5687,6 +6014,20 @@ declare type FullscreenChatContextType = {
  */
 export declare type GapToken = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl";
 
+export declare interface GaugeChartConfig {
+    type: "gauge";
+    /** Minimum value. @default 0 */
+    min?: number;
+    /** Maximum value. @default 100 */
+    max?: number;
+    /** Color token for the gauge arc */
+    color?: ChartColorToken;
+    /** Show the numeric value inside the gauge. @default true */
+    showValue?: boolean;
+    /** Format the value displayed inside the gauge */
+    valueFormatter?: (value: number) => string;
+}
+
 /**
  * Generates an anchor ID for a form element
  * Format: forms.[formName].[sectionId].[fieldId]
@@ -5894,6 +6235,20 @@ declare type HeadingTags = (typeof headingTags)[number];
 
 declare const headingTags: readonly ["h1", "h2", "h3", "h4", "h5", "h6"];
 
+export declare interface HeatmapChartConfig {
+    type: "heatmap";
+    /** Minimum value for the color scale */
+    min?: number;
+    /** Maximum value for the color scale */
+    max?: number;
+    /** Show value labels on each cell. @default false */
+    showLabels?: boolean;
+    /** Show the visual map legend. @default false */
+    showVisualMap?: boolean;
+    /** Format the value displayed in cells and tooltip */
+    valueFormatter?: (value: number) => string;
+}
+
 declare type heightType = "xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "full" | "auto";
 
 export declare const HomeLayout: WithDataTestIdReturnType_2<ForwardRefExoticComponent<Omit<{
@@ -6279,10 +6634,20 @@ declare const levels: readonly ["info", "warning", "critical", "positive"];
 
 export declare function Li({ children, ...props }: React.HTMLAttributes<HTMLLIElement>): JSX_2.Element;
 
-export declare const LineChart: WithDataTestIdReturnType_5<ForwardRefExoticComponent<Omit<LineChartPropsBase<LineChartConfig> & {
+export declare const LineChart: WithDataTestIdReturnType_5<ForwardRefExoticComponent<Omit<LineChartPropsBase<LineChartConfig_2> & {
 lineType?: "natural" | "linear";
 } & RefAttributes<HTMLDivElement>, "ref"> & RefAttributes<HTMLElement | SVGElement>>>;
 
+export declare interface LineChartConfig extends ChartConfigBase {
+    type: "line";
+    /** @default "linear" */
+    lineType?: "linear" | "smooth" | "step";
+    /** Show gradient area fill below lines. @default true */
+    showArea?: boolean;
+    /** Show data point dots on the lines. @default false */
+    showDots?: boolean;
+}
+
 declare type LinkContextValue = {
     currentPath?: string;
     component?: (props: LinkProps, ref: ForwardedRef<HTMLAnchorElement>) => JSX.Element;
@@ -6384,6 +6749,20 @@ declare type MentionsConfig = {
     users: MentionedUser[];
 };
 
+/** How to format the metric value */
+export declare type MetricFormat = {
+    type: "number";
+} | {
+    type: "currency";
+    currency?: string;
+} | {
+    type: "percent";
+} | {
+    type: "custom";
+    suffix?: string;
+    prefix?: string;
+};
+
 /**
  * Known MIME types for the file field `accept` prop.
  *
@@ -6915,6 +7294,20 @@ declare type PersonTagProps = ComponentProps<typeof F0TagPerson>;
 
 export declare const PieChart: WithDataTestIdReturnType_5<ForwardRefExoticComponent<Omit<PieChartProps & RefAttributes<HTMLDivElement>, "ref"> & RefAttributes<HTMLElement | SVGElement>>>;
 
+export declare interface PieChartConfig {
+    type: "pie";
+    /** Inner radius ratio (0 = full pie, >0 = donut). @default 0 */
+    innerRadius?: number;
+    /** Show the legend below the chart. @default true */
+    showLegend?: boolean;
+    /** Show value labels on each segment. @default true */
+    showLabels?: boolean;
+    /** Show percentage in labels. @default false */
+    showPercentage?: boolean;
+    /** Format the value displayed in labels and tooltip */
+    valueFormatter?: (value: number) => string;
+}
+
 declare type PopupSize = "sm" | "md" | "lg";
 
 /** CSS position */
@@ -7169,6 +7562,18 @@ declare type Props_3 = {
     list?: TagCounterItem[];
 };
 
+export declare interface RadarChartConfig {
+    type: "radar";
+    /** Fill the radar area. @default true */
+    showArea?: boolean;
+    /** Show the legend below the chart. @default true */
+    showLegend?: boolean;
+    /** Show value labels on data points. @default false */
+    showLabels?: boolean;
+    /** Format the value displayed in labels and tooltip */
+    valueFormatter?: (value: number) => string;
+}
+
 /**
  * Utility type to get all possible paths through an object using dot notation
  * @template T - The object type to traverse