Property widget: Include unexported APIs in API report (#1185)

* Include non-exported APIs into API report * Provide docs for `TelemetryContextProviderProps` attributes * Provide docs for `PropertyGridActionButtonRendererProps` attributes * change
iTwin · Feb 12, 2025 · 6da64c7 · 6da64c7
1 parent 376fd65
commit 6da64c7
Show file tree

Hide file tree

Showing 6 changed files with 38 additions and 17 deletions.
diff --git a/change/@itwin-property-grid-react-59000ff0-e219-4344-890d-b9d908e168d4.json b/change/@itwin-property-grid-react-59000ff0-e219-4344-890d-b9d908e168d4.json
@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Improve API docs",
+  "packageName": "@itwin/property-grid-react",
+  "email": "35135765+grigasp@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/itwin/property-grid/api/property-grid-react.api.md b/packages/itwin/property-grid/api/property-grid-react.api.md
@@ -119,13 +119,19 @@ export interface PreferencesStorage {
 // @public
 export function PropertyGrid({ createDataProvider, ...props }: PropertyGridProps): JSX.Element | null;
 
+// @public
+type PropertyGridActionButtonRenderer = (props: PropertyGridActionButtonRendererProps) => ReactNode;
+
+// @public (undocumented)
+interface PropertyGridActionButtonRendererProps extends ActionButtonRendererProps {
+    dataProvider: IPresentationPropertyDataProvider;
+}
+
 // @public
 export function PropertyGridComponent({ preferencesStorage, onPerformanceMeasured, onFeatureUsed, ...props }: PropertyGridComponentProps): JSX.Element | null;
 
 // @public
-export interface PropertyGridComponentProps extends Omit<MultiElementPropertyGridProps, "imodel"> {
-    onFeatureUsed?: (featureId: UsageTrackedFeatures) => void;
-    onPerformanceMeasured?: (feature: PerformanceTrackedFeatures, elapsedTime: number) => void;
+export interface PropertyGridComponentProps extends Omit<MultiElementPropertyGridProps, "imodel">, TelemetryContextProviderProps {
     preferencesStorage?: PreferencesStorage;
 }
 
@@ -221,6 +227,9 @@ export type PropertyGridWidgetProps = PropertyGridComponentProps & ({
 // @public
 export function RemoveFavoritePropertyContextMenuItem({ field, imodel, scope, onSelect }: FavoritePropertiesContextMenuItemProps): JSX.Element | null;
 
+// @public (undocumented)
+type SelectionStorage = Pick<SelectionStorage_2, "getSelection" | "replaceSelection" | "selectionChangeEvent">;
+
 // @public
 export interface SettingsMenuItemProps {
     close: () => void;
@@ -254,6 +263,15 @@ export type SingleElementPropertyGridProps = Omit<PropertyGridContentProps, "dat
 // @public
 export function TelemetryContextProvider({ onPerformanceMeasured, onFeatureUsed, children }: PropsWithChildren<TelemetryContextProviderProps>): JSX.Element;
 
+// @public (undocumented)
+interface TelemetryContextProviderProps {
+    onFeatureUsed?: (featureId: UsageTrackedFeatures) => void;
+    onPerformanceMeasured?: (featureId: PerformanceTrackedFeatures, elapsedTime: number) => void;
+}
+
+// @public
+type UsageTrackedFeatures = "single-element" | "multiple-elements" | "elements-list" | "single-element-from-list" | "ancestor-navigation" | "context-menu" | "hide-empty-values-enabled" | "hide-empty-values-disabled" | "filter-properties";
+
 // @public
 export function usePropertyGridTransientState<T extends Element>(): Ref<T>;
 

diff --git a/packages/itwin/property-grid/package.json b/packages/itwin/property-grid/package.json
@@ -39,7 +39,7 @@
     "copy:cjs": "cpx \"./src/**/*.scss\" ./lib/cjs",
     "copy:esm": "cpx \"./src/**/*.scss\" ./lib/esm",
     "cover": "c8 npm run test",
-    "extract-api": "betools extract-api --entry=lib/esm/property-grid-react --apiReportFolder=./api --apiReportTempFolder=./api/temp --apiSummaryFolder=./api",
+    "extract-api": "betools extract-api --entry=lib/esm/property-grid-react --apiReportFolder=./api --apiReportTempFolder=./api/temp --apiSummaryFolder=./api --includeUnexportedApis",
     "check-internal": "node ../../../scripts/checkInternal.js --apiSummary ./api/property-grid-react.api.md",
     "lint": "npm run lint:eslint && npm run lint:stylelint",
     "lint:eslint": "eslint -f visualstudio \"./src/**/*.{ts,tsx}\" 1>&2",

diff --git a/packages/itwin/property-grid/src/property-grid-react/PropertyGridComponent.tsx b/packages/itwin/property-grid/src/property-grid-react/PropertyGridComponent.tsx
@@ -8,30 +8,20 @@ import { MultiElementPropertyGrid } from "./components/MultiElementPropertyGrid.
 import { TelemetryContextProvider } from "./hooks/UseTelemetryContext.js";
 import { PreferencesContextProvider } from "./PropertyGridPreferencesContext.js";
 
-import type { PerformanceTrackedFeatures, UsageTrackedFeatures } from "./hooks/UseTelemetryContext.js";
+import type { TelemetryContextProviderProps } from "./hooks/UseTelemetryContext.js";
 import type { MultiElementPropertyGridProps } from "./components/MultiElementPropertyGrid.js";
 import type { PreferencesStorage } from "./api/PreferencesStorage.js";
 
 /**
  * Props for `PropertyGridComponent`.
  * @public
  */
-export interface PropertyGridComponentProps extends Omit<MultiElementPropertyGridProps, "imodel"> {
+export interface PropertyGridComponentProps extends Omit<MultiElementPropertyGridProps, "imodel">, TelemetryContextProviderProps {
   /**
    * Custom storage that should be used for persisting preferences.
    * Defaults to `IModelAppUserPreferencesStorage` that uses `IModelApp.userPreferences`.
    */
   preferencesStorage?: PreferencesStorage;
-
-  /**
-   * Callback that is invoked when performance of tracked feature is measured.
-   */
-  onPerformanceMeasured?: (feature: PerformanceTrackedFeatures, elapsedTime: number) => void;
-
-  /**
-   * Callback that is invoked when a tracked feature is used.
-   */
-  onFeatureUsed?: (featureId: UsageTrackedFeatures) => void;
 }
 
 /**

diff --git a/packages/itwin/property-grid/src/property-grid-react/hooks/UseActionButtons.ts b/packages/itwin/property-grid/src/property-grid-react/hooks/UseActionButtons.ts
@@ -9,7 +9,9 @@ import { useMemo } from "react";
 import type { IPresentationPropertyDataProvider } from "@itwin/presentation-components";
 import type { ActionButtonRendererProps } from "@itwin/components-react";
 
+/** @public */
 interface PropertyGridActionButtonRendererProps extends ActionButtonRendererProps {
+  /** Data provider used by the property grid. */
   dataProvider: IPresentationPropertyDataProvider;
 }
 

diff --git a/packages/itwin/property-grid/src/property-grid-react/hooks/UseTelemetryContext.tsx b/packages/itwin/property-grid/src/property-grid-react/hooks/UseTelemetryContext.tsx
@@ -39,8 +39,12 @@ const telemetryContext = createContext<TelemetryContext>({
   onFeatureUsed: () => {},
 });
 
-interface TelemetryContextProviderProps {
+/** @public */
+export interface TelemetryContextProviderProps {
+  /** Callback that is invoked when performance of tracked feature is measured. */
   onPerformanceMeasured?: (featureId: PerformanceTrackedFeatures, elapsedTime: number) => void;
+
+  /** Callback that is invoked when a tracked feature is used. */
   onFeatureUsed?: (featureId: UsageTrackedFeatures) => void;
 }