[Reporting] Public API Documentation (#125141) (#126021)

* [Reporting] Public API Documentation

* clean up

(cherry picked from commit 1486741)

x-pack/plugins/reporting/common/index.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+/**
+ * Common types that are documented in the Public API
+ */
+export type {
+  BaseParams,
+  BaseParamsV2,
+  BasePayload,
+  BasePayloadV2,
+  JobAppParamsPDF,
+  JobAppParamsPDFV2,
+  LocatorParams,
+} from './types';

x-pack/plugins/reporting/common/types/base.ts

@@ -11,6 +11,9 @@ import { LocatorParams } from './url';
 
 export type JobId = string;
 
+/**
+ * @deprecated
+ */
 export type BaseParams = Ensure<
   {
     layout?: LayoutParams;
@@ -22,17 +25,26 @@ export type BaseParams = Ensure<
   SerializableRecord
 >;
 
+/**
+ * Report job parameters that an application must return from its
+ * getSharingData function.
+ */
 export type BaseParamsV2 = BaseParams & {
   locatorParams: LocatorParams[];
 };
 
-// base params decorated with encrypted headers that come into runJob functions
+/**
+ * @deprecated
+ */
 export interface BasePayload extends BaseParams {
   headers: string;
   spaceId?: string;
   isDeprecated?: boolean;
 }
 
+/**
+ * Report job parameters, after they are processed in the request handler.
+ */
 export interface BasePayloadV2 extends BaseParamsV2 {
   headers: string;
   spaceId?: string;

x-pack/plugins/reporting/common/types/export_types/printable_pdf.ts

@@ -15,14 +15,20 @@ interface BaseParamsPDF {
 }
 
 // Job params: structure of incoming user request data, after being parsed from RISON
+
 /**
  * @deprecated
  */
 export type JobParamsPDFDeprecated = BaseParamsPDF & BaseParams;
 
+/**
+ * @deprecated
+ */
 export type JobAppParamsPDF = Omit<JobParamsPDFDeprecated, 'browserTimezone' | 'version'>;
 
-// Job payload: structure of stored job data provided by create_job
+/**
+ * Structure of stored job data provided by create_job
+ */
 export interface TaskPayloadPDF extends BasePayload {
   layout: LayoutParams;
   forceNow?: string;

x-pack/plugins/reporting/common/types/url.ts

@@ -16,7 +16,15 @@ export type ManagementLinkFn = () => ManagementLink;
 
 export interface LocatorParams<P extends SerializableRecord = SerializableRecord> {
   id: string;
+
+  /**
+   * Kibana version used to create the params
+   */
   version: string;
+
+  /**
+   * Data to recreate the user's state in the application
+   */
   params: P;
 }
 

x-pack/plugins/reporting/public/index.ts

@@ -5,22 +5,41 @@
  * 2.0.
  */
 
-import { PluginInitializerContext } from 'src/core/public';
-import { ReportingAPIClient } from './lib/reporting_api_client';
+import type { PluginInitializerContext } from 'src/core/public';
 import { ReportingPublicPlugin } from './plugin';
-import { getSharedComponents } from './shared';
+import type { ReportingPublicComponents } from './shared/get_shared_components';
 
+/**
+ * Setup contract for the Reporting plugin.
+ */
 export interface ReportingSetup {
+  /**
+   * Used to inform plugins if Reporting config is compatible with UI Capabilities / Application Sub-Feature Controls
+   *
+   * @returns boolean
+   */
   usesUiCapabilities: () => boolean;
-  components: ReturnType<typeof getSharedComponents>;
+
+  /**
+   * A set of React components for displaying a Reporting share menu in an application
+   */
+  components: ReportingPublicComponents;
 }
 
+/**
+ * Start contract for the Reporting plugin.
+ */
 export type ReportingStart = ReportingSetup;
 
-export { ReportingAPIClient, ReportingPublicPlugin as Plugin };
+/**
+ * Public interface needed for shared components
+ */
+export type { ApplicationProps } from './shared';
+export type { ReportingPublicComponents };
 
 /**
  * @internal
+ *
  * @param {PluginInitializerContext} initializerContext
  * @returns {ReportingPublicPlugin}
  */

x-pack/plugins/reporting/public/lib/reporting_api_client/index.ts

@@ -7,5 +7,5 @@
 
 export { InternalApiClientProvider, useInternalApiClient } from './context';
 export { useCheckIlmPolicyStatus } from './hooks';
-export type { DiagnoseResponse } from './reporting_api_client';
 export { ReportingAPIClient } from './reporting_api_client';
+export type { DiagnoseResponse } from './reporting_api_client';

x-pack/plugins/reporting/public/lib/reporting_api_client/reporting_api_client.ts

@@ -71,7 +71,6 @@ interface IReportingAPI {
 /**
  * Client class for interacting with Reporting APIs
  * @implements IReportingAPI
- * @internal
  */
 export class ReportingAPIClient implements IReportingAPI {
   private http: HttpSetup;

x-pack/plugins/reporting/public/share_context_menu/reporting_panel_content/reporting_panel_content.tsx

@@ -33,6 +33,10 @@ import { ReportingAPIClient } from '../../lib/reporting_api_client';
 import { ErrorUnsavedWorkPanel, ErrorUrlTooLongPanel } from './components';
 import { getMaxUrlLength } from './constants';
 
+/**
+ * Properties for displaying a share menu with Reporting features, including
+ * internally-derived fields.
+ */
 export interface ReportingPanelProps {
   apiClient: ReportingAPIClient;
   toasts: ToastsSetup;
@@ -42,7 +46,9 @@ export interface ReportingPanelProps {
   requiresSavedState: boolean; // Whether the report to be generated requires saved state that is not captured in the URL submitted to the report generator.
   layoutId?: string;
   objectId?: string;
+
   getJobParams: (forShareUrl?: boolean) => Omit<BaseParams, 'browserTimezone' | 'version'>;
+
   options?: ReactElement | null;
   isDirty?: boolean;
   onClose?: () => void;

x-pack/plugins/reporting/public/shared/get_shared_components.tsx

@@ -7,29 +7,70 @@
 
 import { CoreSetup } from 'kibana/public';
 import React from 'react';
-import { ReportingAPIClient } from '../';
 import { PDF_REPORT_TYPE, PDF_REPORT_TYPE_V2, PNG_REPORT_TYPE_V2 } from '../../common/constants';
-import type { Props as PanelPropsScreenCapture } from '../share_context_menu/screen_capture_panel_content';
+import { ReportingAPIClient } from '../lib/reporting_api_client';
+import { ReportingPanelProps } from '../share_context_menu/reporting_panel_content';
 import { ScreenCapturePanelContent } from '../share_context_menu/screen_capture_panel_content_lazy';
 
-interface IncludeOnCloseFn {
+/**
+ * Properties for displaying a share menu with Reporting features.
+ */
+export interface ApplicationProps {
+  /**
+   * A function that Reporting calls to get the sharing data from the application.
+   */
+  getJobParams: ReportingPanelProps['getJobParams'];
+
+  /**
+   * Option to control how the screenshot(s) is/are placed in the PDF
+   */
+  layoutOption?: 'canvas' | 'print';
+
+  /**
+   * Saved object ID
+   */
+  objectId?: string;
+
+  /**
+   * A function to callback when the Reporting panel should be closed
+   */
   onClose: () => void;
 }
 
-type Props = Pick<PanelPropsScreenCapture, 'getJobParams' | 'layoutOption' | 'objectId'> &
-  IncludeOnCloseFn;
+/**
+ * React components used to display share menus with Reporting features in an application.
+ */
+export interface ReportingPublicComponents {
+  /**
+   * An element to display a form to export the page as PDF
+   * @deprecated
+   */
+  ReportingPanelPDF(props: ApplicationProps): JSX.Element;
 
-/*
+  /**
+   * An element to display a form to export the page as PDF
+   */
+  ReportingPanelPDFV2(props: ApplicationProps): JSX.Element;
+
+  /**
+   * An element to display a form to export the page as PNG
+   */
+  ReportingPanelPNGV2(props: ApplicationProps): JSX.Element;
+}
+
+/**
  * As of 7.14, the only shared component is a PDF report that is suited for Canvas integration.
  * This is not planned to expand, as work is to be done on moving the export-type implementations out of Reporting
  * Related Discuss issue: https://github.com/elastic/kibana/issues/101422
  */
-export function getSharedComponents(core: CoreSetup, apiClient: ReportingAPIClient) {
+export function getSharedComponents(
+  core: CoreSetup,
+  apiClient: ReportingAPIClient
+): ReportingPublicComponents {
   return {
-    ReportingPanelPDF(props: Props) {
+    ReportingPanelPDF(props: ApplicationProps) {
       return (
         <ScreenCapturePanelContent
-          layoutOption={props.layoutOption}
           requiresSavedState={false}
           reportType={PDF_REPORT_TYPE}
           apiClient={apiClient}
@@ -40,10 +81,9 @@ export function getSharedComponents(core: CoreSetup, apiClient: ReportingAPIClie
         />
       );
     },
-    ReportingPanelPDFV2(props: Props) {
+    ReportingPanelPDFV2(props: ApplicationProps) {
       return (
         <ScreenCapturePanelContent
-          layoutOption={props.layoutOption}
           requiresSavedState={false}
           reportType={PDF_REPORT_TYPE_V2}
           apiClient={apiClient}
@@ -54,10 +94,9 @@ export function getSharedComponents(core: CoreSetup, apiClient: ReportingAPIClie
         />
       );
     },
-    ReportingPanelPNGV2(props: Props) {
+    ReportingPanelPNGV2(props: ApplicationProps) {
       return (
         <ScreenCapturePanelContent
-          layoutOption={props.layoutOption}
           requiresSavedState={false}
           reportType={PNG_REPORT_TYPE_V2}
           apiClient={apiClient}

x-pack/plugins/reporting/public/shared/index.ts

@@ -6,3 +6,4 @@
  */
 
 export { getSharedComponents } from './get_shared_components';
+export type { ApplicationProps } from './get_shared_components';

x-pack/plugins/reporting/server/index.ts

@@ -9,16 +9,18 @@ import { PluginInitializerContext } from 'kibana/server';
 import { ReportingConfigType } from './config';
 import { ReportingPlugin } from './plugin';
 
+export { config } from './config';
+
+/**
+ * Common types that are documented in the Public API
+ */
+export type { ReportingSetup, ReportingStart } from './types';
+
+// @internal
 export const plugin = (initContext: PluginInitializerContext<ReportingConfigType>) =>
   new ReportingPlugin(initContext);
 
-export { config } from './config';
+// @internal
 export type { ReportingConfig } from './config/config';
-// internal imports
+// @internal
 export { ReportingCore } from './core';
-export type {
-  ReportingSetup,
-  ReportingSetupDeps as PluginSetup,
-  ReportingStartDeps as PluginStart,
-} from './types';
-export { ReportingPlugin as Plugin };

x-pack/plugins/reporting/server/types.ts

@@ -32,26 +32,28 @@ import type { ReportingCore } from './core';
 import type { LevelLogger } from './lib';
 import type { ReportTaskParams } from './lib/tasks';
 
-/*
- * Plugin Contract
+/**
+ * Plugin Setup Contract
  */
-
 export interface ReportingSetup {
+  /**
+   * Used to inform plugins if Reporting config is compatible with UI Capabilities / Application Sub-Feature Controls
+   */
   usesUiCapabilities: () => boolean;
 }
 
-export type ReportingStart = ReportingSetup;
-
-/*
- * Internal Types
+/**
+ * Plugin Start Contract
  */
-
+export type ReportingStart = ReportingSetup;
 export type ReportingUser = { username: AuthenticatedUser['username'] } | false;
 
 export type CaptureConfig = ReportingConfigType['capture'];
 export type ScrollConfig = ReportingConfigType['csv']['scroll'];
 
-export type { BaseParams, BasePayload };
+/**
+ * Internal Types
+ */
 
 // default fn type for CreateJobFnFactory
 export type CreateJobFn<JobParamsType = BaseParams, JobPayloadType = BasePayload> = (
@@ -91,9 +93,6 @@ export interface ExportTypeDefinition<
   validLicenses: string[];
 }
 
-/*
- * @internal
- */
 export interface ReportingSetupDeps {
   features: FeaturesPluginSetup;
   screenshotMode: ScreenshotModePluginSetup;
@@ -103,9 +102,6 @@ export interface ReportingSetupDeps {
   usageCollection?: UsageCollectionSetup;
 }
 
-/*
- * @internal
- */
 export interface ReportingStartDeps {
   data: DataPluginStart;
   fieldFormats: FieldFormatsStart;
@@ -115,22 +111,15 @@ export interface ReportingStartDeps {
   taskManager: TaskManagerStartContract;
 }
 
-/**
- * @internal
- */
 export interface ReportingRequestHandlerContext {
   reporting: ReportingStart | null;
   core: RequestHandlerContext['core'];
 }
 
-/**
- * @internal
- */
 export type ReportingPluginRouter = IRouter<ReportingRequestHandlerContext>;
 
-/**
- * @internal
- */
 export interface ScreenshotOptions extends Omit<BaseScreenshotOptions, 'timeouts' | 'urls'> {
   urls: UrlOrUrlLocatorTuple[];
 }
+
+export type { BaseParams, BasePayload };