From 3ab715b4e9be5e2559fd11e6a4fde243c66bd2e9 Mon Sep 17 00:00:00 2001 From: Walter Rafelsberger Date: Wed, 17 Apr 2024 17:36:07 +0200 Subject: [PATCH] jsdoc --- .../document_count_chart.tsx | 16 +++++++++- .../log_rate_analysis_state_provider.tsx | 31 ++++++++++++++++--- .../log_rate_analysis_state_provider/types.ts | 16 ++++++++++ 3 files changed, 58 insertions(+), 5 deletions(-) diff --git a/x-pack/packages/ml/aiops_components/src/document_count_chart/document_count_chart.tsx b/x-pack/packages/ml/aiops_components/src/document_count_chart/document_count_chart.tsx index 7b42ffdc58d69c..02c532d1867047 100644 --- a/x-pack/packages/ml/aiops_components/src/document_count_chart/document_count_chart.tsx +++ b/x-pack/packages/ml/aiops_components/src/document_count_chart/document_count_chart.tsx @@ -89,6 +89,11 @@ export type BrushSelectionUpdateHandler = ( logRateAnalysisType: LogRateAnalysisType ) => void; +/** + * Callback to set the autoRunAnalysis flag + */ +type SetAutoRunAnalysisFn = (isAutoRun: boolean) => void; + /** * Props for document count chart */ @@ -121,7 +126,7 @@ export interface DocumentCountChartProps { /** Whether or not brush has been reset */ isBrushCleared: boolean; /** Callback to set the autoRunAnalysis flag */ - setAutoRunAnalysis?: (isAutoRun: boolean) => void; + setAutoRunAnalysis?: SetAutoRunAnalysisFn; /** Timestamp for start of initial analysis */ autoAnalysisStart?: number | WindowParameters; /** Optional style to override bar chart */ @@ -553,6 +558,15 @@ export const DocumentCountChart: FC = (props) => { ); }; +/** + * Functional component that renders a `DocumentCountChart` with additional properties + * managed by the log rate analysis state. It leverages the `useLogRateAnalysisStateContext` + * to acquire state variables like `initialAnalysisStart` and functions such as + * `setAutoRunAnalysis`. These values are then passed as props to the `DocumentCountChart`. + * + * @param props - The properties passed to the DocumentCountChart component. + * @returns The DocumentCountChart component enhanced with automatic analysis start capabilities. + */ export const DocumentCountChartWithAutoAnalysisStart: FC = (props) => { const { initialAnalysisStart, setAutoRunAnalysis } = useLogRateAnalysisStateContext(); diff --git a/x-pack/packages/ml/aiops_components/src/log_rate_analysis_state_provider/log_rate_analysis_state_provider.tsx b/x-pack/packages/ml/aiops_components/src/log_rate_analysis_state_provider/log_rate_analysis_state_provider.tsx index a3ee3fc81f0da1..f3aa55bdce7711 100644 --- a/x-pack/packages/ml/aiops_components/src/log_rate_analysis_state_provider/log_rate_analysis_state_provider.tsx +++ b/x-pack/packages/ml/aiops_components/src/log_rate_analysis_state_provider/log_rate_analysis_state_provider.tsx @@ -44,14 +44,30 @@ interface LogRateAnalysisState { const LogRateAnalysisStateContext = createContext(undefined); +/** + * Props for LogRateAnalysisStateProvider. + */ interface LogRateAnalysisStateProviderProps { + /** The parameters to be used to trigger an analysis. */ initialAnalysisStart?: InitialAnalysisStart; } -export const LogRateAnalysisStateProvider: FC = ({ - children, - initialAnalysisStart: incomingInitialAnalysisStart, -}) => { +/** + * Context provider component that manages and provides global state for Log Rate Analysis. + * This provider handles several pieces of state important for controlling and displaying + * log rate analysis data, such as the control of automatic analysis runs, and the management + * of both pinned and selected significant items and groups. + * + * The state includes mechanisms for setting initial analysis parameters, toggling analysis, + * and managing the current selection and pinned state of significant items and groups. + * + * @param props - Props object containing initial settings for the analysis, + * including children components to be wrapped by the Provider. + * @returns A context provider wrapping children with access to log rate analysis state. + */ +export const LogRateAnalysisStateProvider: FC = (props) => { + const { children, initialAnalysisStart: incomingInitialAnalysisStart } = props; + const [autoRunAnalysis, setAutoRunAnalysis] = useState(true); const [initialAnalysisStart, setInitialAnalysisStart] = useState< number | WindowParameters | undefined @@ -131,6 +147,13 @@ export const LogRateAnalysisStateProvider: FC ); }; +/** + * Custom hook for accessing the state of log rate analysis from the LogRateAnalysisStateContext. + * This hook must be used within a component that is a descendant of the LogRateAnalysisStateContext provider. + * + * @returns The current state of the log rate analysis. + * @throws Throws an error if the hook is used outside of its Provider context. + */ export const useLogRateAnalysisStateContext = () => { const logRateAnalysisState = useContext(LogRateAnalysisStateContext); diff --git a/x-pack/packages/ml/aiops_components/src/log_rate_analysis_state_provider/types.ts b/x-pack/packages/ml/aiops_components/src/log_rate_analysis_state_provider/types.ts index 400e4534b54f13..4c4013e3d48679 100644 --- a/x-pack/packages/ml/aiops_components/src/log_rate_analysis_state_provider/types.ts +++ b/x-pack/packages/ml/aiops_components/src/log_rate_analysis_state_provider/types.ts @@ -9,20 +9,36 @@ import type { EuiTableActionsColumnType } from '@elastic/eui'; import type { SignificantItem, SignificantItemGroupItem } from '@kbn/ml-agg-utils'; +/** + * Type for defining attributes picked from + * SignificantItemGroupItem used in the grouped table. + */ export type GroupTableItemGroup = Pick< SignificantItemGroupItem, 'key' | 'type' | 'fieldName' | 'fieldValue' | 'docCount' | 'pValue' | 'duplicate' >; +/** + * Represents a single item in the group table. + */ export interface GroupTableItem { + /** Unique identifier for the group table item. */ id: string; + /** Document count associated with the item. */ docCount: number; + /** Statistical p-value indicating the significance of the item, nullable. */ pValue: number | null; + /** Count of unique items within the group. */ uniqueItemsCount: number; + /** Array of items within the group, sorted by uniqueness. */ groupItemsSortedByUniqueness: GroupTableItemGroup[]; + /** Histogram data for the significant item. */ histogram: SignificantItem['histogram']; } +/** + * Type for action columns in a table that involves SignificantItem or GroupTableItem. + */ export type TableItemAction = EuiTableActionsColumnType< SignificantItem | GroupTableItem >['actions'][number];