@factorialco/f0-react 6.3.3 → 6.5.0

package/dist/experimental.d.ts

@@ -2045,7 +2045,7 @@ declare interface ChatDashboardBarChartConfig extends ChatDashboardChartConfigBa
     stacked?: boolean;
 }
 
-declare type ChatDashboardChartConfig = ChatDashboardBarChartConfig | ChatDashboardLineChartConfig | ChatDashboardFunnelChartConfig | ChatDashboardRadarChartConfig | ChatDashboardPieChartConfig | ChatDashboardGaugeChartConfig | ChatDashboardHeatmapChartConfig;
+declare type ChatDashboardChartConfig = ChatDashboardBarChartConfig | ChatDashboardLineChartConfig | ChatDashboardFunnelChartConfig | ChatDashboardRadarChartConfig | ChatDashboardPieChartConfig | ChatDashboardGaugeChartConfig | ChatDashboardHeatmapChartConfig | ChatDashboardScatterChartConfig;
 
 declare interface ChatDashboardChartConfigBase {
     showLegend?: boolean;
@@ -2057,7 +2057,7 @@ declare interface ChatDashboardChartConfigBase {
 declare interface ChatDashboardChartItem extends ChatDashboardItemBase {
     type: "chart";
     chart: ChatDashboardChartConfig;
-    computation: ChartComputation | RadarComputation | PieComputation | GaugeComputation | HeatmapComputation;
+    computation: ChartComputation | RadarComputation | PieComputation | GaugeComputation | HeatmapComputation | ScatterComputation;
 }
 
 declare interface ChatDashboardCollectionItem extends ChatDashboardItemBase {
@@ -2244,6 +2244,23 @@ declare interface ChatDashboardRadarChartConfig extends ChatDashboardChartConfig
     showArea?: boolean;
 }
 
+declare interface ChatDashboardScatterChartConfig {
+    type: "scatter";
+    pointSize?: number;
+    scaleAxes?: boolean;
+    showGrid?: boolean;
+    /** Only rendered with 2+ series, but still needed so a skeleton can reserve for it. */
+    showLegend?: boolean;
+    /** What the X measure is, e.g. "salary" — labels the x row in the tooltip */
+    xAxisName?: string;
+    /** What the Y measure is, e.g. "tenure" — labels the y row in the tooltip */
+    yAxisName?: string;
+    /** Formats the Y measure */
+    valueFormat?: FormatPreset;
+    /** Formats the X measure, which is a second measure rather than a category */
+    xValueFormat?: FormatPreset;
+}
+
 export declare type ChatWidgetEmptyStateProps = Props_6;
 
 declare type ChildrenPaginationInfo = {
@@ -3908,6 +3925,7 @@ declare const defaultTranslations: {
             readonly title: "No data available";
             readonly description: "Try a different date or fewer filters";
         };
+        readonly windowedCategories: "Showing {{count}} of {{total}} categories";
         readonly tooltip: {
             readonly ofTotal: "of total";
             readonly total: "total";
@@ -9622,6 +9640,21 @@ export declare type RichTextEditorProps = F0RichTextEditorProps;
 /** @deprecated Use F0RichTextEditorSkeletonProps */
 export declare type RichTextEditorSkeletonProps = F0RichTextEditorSkeletonProps;
 
+/**
+ * Both axes are measures, so there is no aggregation: a scatter plots one
+ * point per row rather than grouping rows into categories. `label` names the
+ * column identifying each point, and `series` the optional column that splits
+ * the points into colour groups.
+ */
+declare interface ScatterComputation {
+    datasetId: string;
+    xAxis: string;
+    yAxis: string;
+    label?: string;
+    series?: string;
+    limit?: number;
+}
+
 export declare const ScrollArea: WithDataTestIdReturnType<ForwardRefExoticComponent<Omit<Omit<ScrollAreaProps & RefAttributes<HTMLDivElement>, "ref"> & {
 showBar?: boolean;
 viewportRef?: React.RefObject<HTMLDivElement>;
@@ -11965,11 +11998,9 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        enhanceHighlight: {
-            setEnhanceHighlight: (from: number, to: number, options?: {
-                placeholder?: string;
-            }) => ReturnType;
-            clearEnhanceHighlight: () => ReturnType;
+        fontSize: {
+            setFontSize: (fontSize: string) => ReturnType;
+            unsetFontSize: () => ReturnType;
         };
     }
 }
@@ -11977,9 +12008,11 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        fontSize: {
-            setFontSize: (fontSize: string) => ReturnType;
-            unsetFontSize: () => ReturnType;
+        enhanceHighlight: {
+            setEnhanceHighlight: (from: number, to: number, options?: {
+                placeholder?: string;
+            }) => ReturnType;
+            clearEnhanceHighlight: () => ReturnType;
         };
     }
 }

package/dist/f0.d.ts

@@ -2802,7 +2802,7 @@ export declare interface ChatDashboardBarChartConfig extends ChatDashboardChartC
     stacked?: boolean;
 }
 
-export declare type ChatDashboardChartConfig = ChatDashboardBarChartConfig | ChatDashboardLineChartConfig | ChatDashboardFunnelChartConfig | ChatDashboardRadarChartConfig | ChatDashboardPieChartConfig | ChatDashboardGaugeChartConfig | ChatDashboardHeatmapChartConfig;
+export declare type ChatDashboardChartConfig = ChatDashboardBarChartConfig | ChatDashboardLineChartConfig | ChatDashboardFunnelChartConfig | ChatDashboardRadarChartConfig | ChatDashboardPieChartConfig | ChatDashboardGaugeChartConfig | ChatDashboardHeatmapChartConfig | ChatDashboardScatterChartConfig;
 
 declare interface ChatDashboardChartConfigBase {
     showLegend?: boolean;
@@ -2814,7 +2814,7 @@ declare interface ChatDashboardChartConfigBase {
 export declare interface ChatDashboardChartItem extends ChatDashboardItemBase {
     type: "chart";
     chart: ChatDashboardChartConfig;
-    computation: ChartComputation | RadarComputation | PieComputation | GaugeComputation | HeatmapComputation;
+    computation: ChartComputation | RadarComputation | PieComputation | GaugeComputation | HeatmapComputation | ScatterComputation;
 }
 
 export declare interface ChatDashboardCollectionItem extends ChatDashboardItemBase {
@@ -3001,6 +3001,23 @@ export declare interface ChatDashboardRadarChartConfig extends ChatDashboardChar
     showArea?: boolean;
 }
 
+export declare interface ChatDashboardScatterChartConfig {
+    type: "scatter";
+    pointSize?: number;
+    scaleAxes?: boolean;
+    showGrid?: boolean;
+    /** Only rendered with 2+ series, but still needed so a skeleton can reserve for it. */
+    showLegend?: boolean;
+    /** What the X measure is, e.g. "salary" — labels the x row in the tooltip */
+    xAxisName?: string;
+    /** What the Y measure is, e.g. "tenure" — labels the y row in the tooltip */
+    yAxisName?: string;
+    /** Formats the Y measure */
+    valueFormat?: FormatPreset;
+    /** Formats the X measure, which is a second measure rather than a category */
+    xValueFormat?: FormatPreset;
+}
+
 export declare const ChatSpinner: ForwardRefExoticComponent<ChatSpinnerProps & RefAttributes<HTMLDivElement>>;
 
 declare interface ChatSpinnerProps {
@@ -3645,7 +3662,7 @@ export declare type DashboardCanvasContent = CanvasContentBase & {
  * 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 type DashboardChartConfig = BarChartConfig | LineChartConfig | FunnelChartConfig | PieChartConfig | RadarChartConfig | GaugeChartConfig | HeatmapChartConfig | ScatterChartConfig;
 
 export declare interface DashboardChartData {
     /** Category axis labels. Required for bar/line charts. */
@@ -3663,6 +3680,12 @@ export declare interface DashboardChartData {
     };
     /** Heatmap data points as [xIndex, yIndex, value] tuples. */
     data?: [number, number, number][];
+    /**
+     * Scatter series — x/y pairs, optionally split into color groups. Kept on
+     * its own field rather than reusing `series` or `data` so shape detection
+     * can never confuse it with a bar/line series array or the heatmap grid.
+     */
+    scatterSeries?: F0DataChartScatterSeries[];
 }
 
 export declare interface DashboardChartItem<Filters extends FiltersDefinition = FiltersDefinition> extends DashboardItemBase {
@@ -5196,6 +5219,7 @@ export declare const defaultTranslations: {
             readonly title: "No data available";
             readonly description: "Try a different date or fewer filters";
         };
+        readonly windowedCategories: "Showing {{count}} of {{total}} categories";
         readonly tooltip: {
             readonly ofTotal: "of total";
             readonly total: "total";
@@ -8402,7 +8426,7 @@ export declare interface F0DataChartBarProps extends F0DataChartBaseProps {
     /**
      * Per-side clearance in pixels the widest value must have before
      * {@link F0DataChartBarProps.hideOverflowingLabels} counts it as fitting.
-     * Overrides the default, which is placement-based: **12** for stacked (inside)
+     * Overrides the default, which is placement-based: **6** for stacked (inside)
      * labels, **0** for labels outside the bar.
      */
     labelFitPadding?: number;
@@ -8415,6 +8439,43 @@ export declare interface F0DataChartBarProps extends F0DataChartBaseProps {
      * widths differ. Height overflow is also evaluated per bar. @default true
      */
     hideAllLabelsOnOverflow?: boolean;
+    /**
+     * Draw only as many categories as fit at a readable bar thickness, instead of
+     * compressing every one of them into the available height.
+     *
+     * Opt-in, because it hides data: a windowed chart shows the first N rows in
+     * data order and nothing in the chart itself leads to the rest. Set it only
+     * where the surrounding UI offers the way back — subscribe to
+     * {@link F0DataChartBarProps.onHiddenCategoriesChange} and put a control next
+     * to the count, as `F0AnalyticsDashboard` does. Left off, a dense chart stays
+     * complete and its bars get thinner, which is the readable-but-honest end of
+     * the trade.
+     *
+     * Ignored by vertical charts, which lay categories out along the width.
+     * @default false
+     */
+    windowCategories?: boolean;
+    /**
+     * Render every category at once, overriding
+     * {@link F0DataChartBarProps.windowCategories}.
+     *
+     * Set this when the reader has asked to see the whole distribution — an
+     * expanded or fullscreen view — and accepts thinner bars in exchange. Ignored
+     * by vertical charts, which lay categories out along the width.
+     * @default false
+     */
+    showAllCategories?: boolean;
+    /**
+     * Reports how many categories the row window is hiding — `0` when every
+     * category is on screen. Fires whenever the count changes, which includes
+     * container resizes and {@link F0DataChartBarProps.showAllCategories} being
+     * switched on.
+     *
+     * The chart states the fact rather than rendering an affordance for it: only
+     * the surrounding UI knows where a "see everything" control belongs. The
+     * dashboard puts it in the widget's description, next to the count.
+     */
+    onHiddenCategoriesChange?: (hiddenCategoryCount: number) => void;
     /**
      * Suggested number of segments on the value axis — lower values draw fewer
      * grid lines. Applies to whichever axis is the value axis (Y for vertical
@@ -8751,9 +8812,9 @@ export declare interface F0DataChartPieSeries {
  * Props for the F0DataChart component.
  *
  * A unified chart component that supports bar, line, funnel, pie, radar,
- * gauge, and heatmap chart types via a discriminated `type` prop.
+ * gauge, heatmap, and scatter chart types via a discriminated `type` prop.
  */
-export declare type F0DataChartProps = F0DataChartBarProps | F0DataChartLineProps | F0DataChartFunnelProps | F0DataChartPieProps | F0DataChartRadarProps | F0DataChartGaugeProps | F0DataChartHeatmapProps;
+export declare type F0DataChartProps = F0DataChartBarProps | F0DataChartLineProps | F0DataChartFunnelProps | F0DataChartPieProps | F0DataChartRadarProps | F0DataChartGaugeProps | F0DataChartHeatmapProps | F0DataChartScatterProps;
 
 /**
  * A radar chart indicator (axis/dimension).
@@ -8808,6 +8869,89 @@ export declare interface F0DataChartRadarSeries {
     color?: ChartColorToken;
 }
 
+/**
+ * A single point in a scatter series.
+ *
+ * The bare `[x, y]` tuple is the terse form. The object form additionally
+ * carries `label` — the point's identity (e.g. an employee or team name),
+ * shown as the tooltip header.
+ */
+export declare type F0DataChartScatterDataPoint = [number, number] | {
+    /** Horizontal position, plotted on the value X axis */
+    x: number;
+    /** Vertical position, plotted on the value Y axis */
+    y: number;
+    /** Identity of this point, used as the tooltip header (e.g. "Ana Ruiz") */
+    label?: string;
+    /** Override color for this individual point. Must be an F0 design token name. */
+    color?: ChartColorToken;
+};
+
+/**
+ * Scatter chart variant props.
+ *
+ * Plots x/y pairs on two value axes to show the relationship between two
+ * measures. Unlike bar/line there is no category axis — both axes are
+ * continuous — so this interface is separate from `F0DataChartBaseProps`.
+ * Pass multiple `series` to color-split the points by a group dimension.
+ */
+export declare interface F0DataChartScatterProps extends F0DataChartCommonProps {
+    /** Chart type */
+    type: "scatter";
+    /** One or more point groups. Multiple series render as a color split. */
+    series: F0DataChartScatterSeries[];
+    /** Point diameter in pixels. @default 12 */
+    pointSize?: number;
+    /**
+     * Fit each axis to its data range instead of anchoring it at zero. Turn off
+     * to force both axes through the origin. @default true
+     */
+    scaleAxes?: boolean;
+    /** Show the legend below the chart. Only rendered with 2+ series. @default true */
+    showLegend?: boolean;
+    /** Show the background grid lines on both axes. @default true */
+    showGrid?: boolean;
+    /** Format the Y axis tick labels */
+    valueFormatter?: (value: number) => string;
+    /** Format the X axis tick labels */
+    xValueFormatter?: (value: number) => string;
+    /**
+     * Formatter for the y value shown in the hover tooltip. Defaults to
+     * {@link valueFormatter}, so a unit or a currency on the Y axis reads the same
+     * on hover, then to a plain localized number. Set it when the axis has to
+     * stay compact ("107.5K") but the tooltip should be exact ("107,505").
+     */
+    tooltipValueFormatter?: (value: number) => string;
+    /**
+     * Formatter for the x value shown in the hover tooltip. Same contract as
+     * {@link tooltipValueFormatter}, against {@link xValueFormatter}.
+     */
+    xTooltipValueFormatter?: (value: number) => string;
+    /**
+     * What the X measure is, e.g. "salary". Labels the x row in the tooltip —
+     * a scatter has no headline value, so both coordinates read as rows and
+     * need naming, the same way radar names its indicators.
+     */
+    xAxisName?: string;
+    /** What the Y measure is, e.g. "tenure". Labels the y row in the tooltip. */
+    yAxisName?: string;
+    /** Escape hatch: raw ECharts options merged (shallow) on top of the generated config */
+    echartsOptions?: Partial<echarts_2.EChartsOption>;
+}
+
+/**
+ * A group of points sharing a color and a legend entry. Use one series per
+ * group value to split a scatter by a dimension (e.g. one per department).
+ */
+export declare interface F0DataChartScatterSeries {
+    /** Display name used in legend and tooltip */
+    name: string;
+    /** Points in this group */
+    data: F0DataChartScatterDataPoint[];
+    /** Override color for this series. Must be an F0 design token name. Falls back to the theme palette. */
+    color?: ChartColorToken;
+}
+
 /**
  * F0 config options specific to date fields
  *
@@ -16287,6 +16431,53 @@ declare type SampleRatingQuestion = {
     maxLabel?: string;
 };
 
+export declare interface ScatterChartConfig {
+    type: "scatter";
+    /** Point diameter in pixels. @default 12 */
+    pointSize?: number;
+    /** Fit each axis to its data range instead of anchoring it at zero. @default true */
+    scaleAxes?: boolean;
+    /** Show the legend below the chart. Only rendered with 2+ series. @default true */
+    showLegend?: boolean;
+    /** Show the background grid lines. @default true */
+    showGrid?: boolean;
+    /** Format the Y axis tick labels */
+    valueFormatter?: (value: number) => string;
+    /** Format the X axis tick labels */
+    xValueFormatter?: (value: number) => string;
+    /** Format the y value in the tooltip, which shows full numbers */
+    tooltipValueFormatter?: (value: number) => string;
+    /** Format the x value in the tooltip, which shows full numbers */
+    xTooltipValueFormatter?: (value: number) => string;
+    /** What the X measure is, e.g. "salary" — labels the x row in the tooltip */
+    xAxisName?: string;
+    /** What the Y measure is, e.g. "tenure" — labels the y row in the tooltip */
+    yAxisName?: string;
+}
+
+/** Skeleton for scatter chart content area — points with no connecting path. */
+export declare function ScatterChartSkeleton({ showLegend, }?: ScatterChartSkeletonProps): JSX_2.Element;
+
+declare interface ScatterChartSkeletonProps {
+    /** Show the legend row below the plot. @default true */
+    showLegend?: boolean;
+}
+
+/**
+ * Both axes are measures, so there is no aggregation: a scatter plots one
+ * point per row rather than grouping rows into categories. `label` names the
+ * column identifying each point, and `series` the optional column that splits
+ * the points into colour groups.
+ */
+export declare interface ScatterComputation {
+    datasetId: string;
+    xAxis: string;
+    yAxis: string;
+    label?: string;
+    series?: string;
+    limit?: number;
+}
+
 export declare type SearchFilterDefinition = BaseFilterDefinition<"search">;
 
 declare type SearchOptions = {
@@ -19095,11 +19286,9 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        enhanceHighlight: {
-            setEnhanceHighlight: (from: number, to: number, options?: {
-                placeholder?: string;
-            }) => ReturnType;
-            clearEnhanceHighlight: () => ReturnType;
+        fontSize: {
+            setFontSize: (fontSize: string) => ReturnType;
+            unsetFontSize: () => ReturnType;
         };
     }
 }
@@ -19107,9 +19296,11 @@ declare module "@tiptap/core" {
 
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
-        fontSize: {
-            setFontSize: (fontSize: string) => ReturnType;
-            unsetFontSize: () => ReturnType;
+        enhanceHighlight: {
+            setEnhanceHighlight: (from: number, to: number, options?: {
+                placeholder?: string;
+            }) => ReturnType;
+            clearEnhanceHighlight: () => ReturnType;
         };
     }
 }