Tree and Property Widget: Cleanup internal APIs

.github/workflows/extract-api.yml

@@ -0,0 +1,39 @@
+# iTwin.js Extract API Build
+
+name: Extract API
+
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - packages/itwin/property-grid/**
+      - packages/itwin/tree-widget/**
+    types: [opened, synchronize, reopened, ready_for_review]
+
+jobs:
+  extract-api:
+    if: '! github.event.pull_request.draft'
+    runs-on: ubuntu-latest
+    name: Extract API
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 9
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Extract API
+        env:
+          TF_BUILD: 1
+        run: pnpm lage extract-api check-internal

change/@itwin-property-grid-react-816aaa9b-ba52-42ce-88d6-8a971fe377bf.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Do not export top level `@internal` API through barrel.",
+  "packageName": "@itwin/property-grid-react",
+  "email": "33428304+jasdom@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

change/@itwin-tree-widget-react-061618f3-9d76-4749-a94a-32fd7f0ab62b.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Do not export top level `@internal` API through barrel.",
+  "packageName": "@itwin/tree-widget-react",
+  "email": "33428304+jasdom@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

lage.config.js

@@ -35,6 +35,11 @@ module.exports = {
       outputs: ["./api/**"],
       inputs: ["src/**"],
     },
+    "check-internal": {
+      dependsOn: ["extract-api"],
+      outputs: [],
+      inputs: ["api/**"],
+    },
     clean: {
       cache: false,
     },

package.json

@@ -28,6 +28,7 @@
   "devDependencies": {
     "beachball": "^2.43.1",
     "lage": "^2.7.16",
-    "prettier": "^3.2.5"
+    "prettier": "^3.2.5",
+    "yargs": "^17.7.2"
   }
 }

packages/itwin/property-grid/api/property-grid-react.api.md

@@ -15,10 +15,7 @@ import type { IPropertyDataFilterer } from '@itwin/components-react';
 import { Localization } from '@itwin/core-common';
 import type { LocalizationOptions } from '@itwin/core-i18n';
 import type { PropertyCategory } from '@itwin/components-react';
-import type { PropertyDataFilterResult } from '@itwin/components-react';
-import type { PropertyGridContextMenuArgs } from '@itwin/components-react';
 import type { PropertyRecord } from '@itwin/appui-abstract';
-import { PropertyRecordDataFiltererBase } from '@itwin/components-react';
 import type { PropertyUpdatedArgs } from '@itwin/components-react';
 import type { PropsWithChildren } from 'react';
 import type { ReactNode } from 'react';
@@ -74,13 +71,9 @@ export interface FavoritePropertiesContextMenuItemProps extends DefaultContextMe
     scope?: FavoritePropertiesScope;
 }
 
-// @internal
-export function FilteringPropertyGrid({ filterer, dataProvider, autoExpandChildCategories, ...props }: FilteringPropertyGridProps): JSX.Element | null;
-
 // @public
 export interface FilteringPropertyGridProps extends VirtualizedPropertyGridWithDataProviderProps {
     autoExpandChildCategories?: boolean;
-    // @internal (undocumented)
     filterer: IPropertyDataFilterer;
 }
 
@@ -93,12 +86,6 @@ export class IModelAppUserPreferencesStorage implements PreferencesStorage {
     set(key: string, value: string): Promise<void>;
 }
 
-// @internal
-export interface InstanceSelectionProps {
-    // (undocumented)
-    imodel: IModelConnection;
-}
-
 // @public
 export function MultiElementPropertyGrid({ ancestorsNavigationControls, ...props }: MultiElementPropertyGridProps): JSX.Element;
 
@@ -107,35 +94,9 @@ export interface MultiElementPropertyGridProps extends Omit<PropertyGridProps, "
     ancestorsNavigationControls?: (props: AncestorsNavigationControlsProps) => ReactNode;
 }
 
-// @internal
-export class NonEmptyValuesPropertyDataFilterer extends PropertyRecordDataFiltererBase {
-    // (undocumented)
-    get isActive(): boolean;
-    // (undocumented)
-    recordMatchesFilter(node: PropertyRecord): Promise<PropertyDataFilterResult>;
-}
-
-// @internal
-export class NoopPropertyDataFilterer extends PropertyRecordDataFiltererBase {
-    // (undocumented)
-    get isActive(): boolean;
-    // (undocumented)
-    recordMatchesFilter(): Promise<PropertyDataFilterResult>;
-}
-
 // @public
 export function NullValueSettingContext({ children }: PropsWithChildren<{}>): JSX.Element;
 
-// @internal (undocumented)
-export interface NullValueSettingContextValue {
-    // (undocumented)
-    setShowNullValues: (value: boolean, options?: {
-        persist?: boolean;
-    }) => Promise<void>;
-    // (undocumented)
-    showNullValues: boolean;
-}
-
 // @public
 export type PerformanceTrackedFeatures = "properties-load" | "elements-list-load";
 
@@ -160,16 +121,13 @@ export interface PropertyGridComponentProps extends Omit<MultiElementPropertyGri
     preferencesStorage?: PreferencesStorage;
 }
 
-// @internal
-export function PropertyGridContent({ dataProvider, imodel, contextMenuItems, className, onBackButton, headerControls, settingsMenuItems, dataRenderer, onPropertyUpdated, ...props }: PropertyGridContentProps): JSX.Element;
-
 // @public
 export interface PropertyGridContentBaseProps extends Omit<FilteringPropertyGridProps, "dataProvider" | "filterer" | "isPropertyHoverEnabled" | "isPropertySelectionEnabled" | "onPropertyContextMenu" | "width" | "height" | "onPropertyUpdated"> {
     // (undocumented)
     className?: string;
-    // @internal (undocumented)
+    // (undocumented)
     dataProvider: IPresentationPropertyDataProvider;
-    // @internal (undocumented)
+    // (undocumented)
     dataRenderer?: (props: FilteringPropertyGridProps) => ReactNode;
     // (undocumented)
     headerControls?: ReactNode;
@@ -244,15 +202,6 @@ export const PropertyGridWidgetId = "vcr:PropertyGridComponent";
 // @public
 export function RemoveFavoritePropertyContextMenuItem({ field, imodel, scope, onSelect }: FavoritePropertiesContextMenuItemProps): JSX.Element | null;
 
-// @internal
-export function SettingsDropdownMenu({ settingsMenuItems, dataProvider }: SettingsDropdownMenuProps): JSX.Element | null;
-
-// @internal
-export interface SettingsDropdownMenuProps extends SettingsMenuProps {
-    // (undocumented)
-    dataProvider: IPresentationPropertyDataProvider;
-}
-
 // @public
 export interface SettingsMenuItemProps {
     close: () => void;
@@ -272,9 +221,6 @@ export interface ShowHideNullValuesSettingsMenuItemProps extends SettingsMenuIte
     persist?: boolean;
 }
 
-// @internal (undocumented)
-export const SHOWNULL_KEY = "showNullValues";
-
 // @public
 export interface SingleElementDataProviderProps extends DataProviderProps {
     instanceKey: InstanceKey;
@@ -289,49 +235,6 @@ export type SingleElementPropertyGridProps = Omit<PropertyGridContentProps, "dat
 // @public
 export function TelemetryContextProvider({ onPerformanceMeasured, onFeatureUsed, children }: PropsWithChildren<TelemetryContextProviderProps>): JSX.Element;
 
-// @internal
-export interface UseContentMenuProps extends ContextMenuProps {
-    // (undocumented)
-    dataProvider: IPresentationPropertyDataProvider;
-    // (undocumented)
-    imodel: IModelConnection;
-}
-
-// @internal
-export function useContextMenu({ dataProvider, imodel, contextMenuItems }: UseContentMenuProps): {
-    onPropertyContextMenu: (args: PropertyGridContextMenuArgs) => Promise<void>;
-    renderContextMenu: () => JSX.Element | undefined;
-};
-
-// @internal
-export function useDataProvider({ imodel, createDataProvider }: DataProviderProps & {
-    imodel: IModelConnection;
-}): IPresentationPropertyDataProvider | undefined;
-
-// @internal
-export function useInstanceSelection({ imodel }: InstanceSelectionProps): {
-    selectedKeys: InstanceKey[];
-    focusedInstanceKey: InstanceKey | undefined;
-    focusInstance: (key: InstanceKey) => void;
-    ancestorsNavigationProps: {
-        navigateDown: () => void;
-        navigateUp: () => Promise<void>;
-        canNavigateUp: boolean;
-        canNavigateDown: boolean;
-    };
-};
-
-// @internal
-export function useNullValueSetting(): {
-    showNullValues: boolean;
-    setShowNullValues: (value: boolean, options?: {
-        persist?: boolean;
-    }) => Promise<void>;
-};
-
-// @internal (undocumented)
-export function useNullValueSettingContext(): NullValueSettingContextValue;
-
 // @public
 export function usePropertyGridTransientState<T extends Element>(): Ref<T>;
 

packages/itwin/property-grid/api/property-grid-react.exports.csv

@@ -9,22 +9,16 @@ public;CopyPropertyTextContextMenuItem({ record, onSelect }: DefaultContextMenuI
 public;DataProviderProps
 public;DefaultContextMenuItemProps 
 public;FavoritePropertiesContextMenuItemProps 
-internal;FilteringPropertyGrid({ filterer, dataProvider, autoExpandChildCategories, ...props }: FilteringPropertyGridProps): JSX.Element | null
 public;FilteringPropertyGridProps 
 public;IModelAppUserPreferencesStorage 
-internal;InstanceSelectionProps
 public;MultiElementPropertyGrid({ ancestorsNavigationControls, ...props }: MultiElementPropertyGridProps): JSX.Element
 public;MultiElementPropertyGridProps 
-internal;NonEmptyValuesPropertyDataFilterer 
-internal;NoopPropertyDataFilterer 
 public;NullValueSettingContext({ children }: PropsWithChildren
-internal;NullValueSettingContextValue
 public;PerformanceTrackedFeatures = "properties-load" | "elements-list-load"
 public;PreferencesStorage
 public;PropertyGrid({ createDataProvider, ...props }: PropertyGridProps): JSX.Element | null
 public;PropertyGridComponent({ preferencesStorage, onPerformanceMeasured, onFeatureUsed, ...props }: PropertyGridComponentProps): JSX.Element | null
 public;PropertyGridComponentProps 
-internal;PropertyGridContent({ dataProvider, imodel, contextMenuItems, className, onBackButton, headerControls, settingsMenuItems, dataRenderer, onPropertyUpdated, ...props }: PropertyGridContentProps): JSX.Element
 public;PropertyGridContentBaseProps 
 public;PropertyGridContentProps = PropertyGridContentBaseProps & ContextMenuProps & SettingsMenuProps
 public;PropertyGridContextMenuItem({ id, children, title, onSelect }: PropsWithChildren
@@ -38,21 +32,12 @@ public;PropertyGridUiItemsProvider
 public;PropertyGridUiItemsProviderProps
 public;PropertyGridWidgetId = "vcr:PropertyGridComponent"
 public;RemoveFavoritePropertyContextMenuItem({ field, imodel, scope, onSelect }: FavoritePropertiesContextMenuItemProps): JSX.Element | null
-internal;SettingsDropdownMenu({ settingsMenuItems, dataProvider }: SettingsDropdownMenuProps): JSX.Element | null
-internal;SettingsDropdownMenuProps 
 public;SettingsMenuItemProps
 public;SettingsMenuProps
 public;ShowHideNullValuesSettingsMenuItem({ close, persist }: ShowHideNullValuesSettingsMenuItemProps): JSX.Element
 public;ShowHideNullValuesSettingsMenuItemProps 
-internal;SHOWNULL_KEY = "showNullValues"
 public;SingleElementDataProviderProps 
 public;SingleElementPropertyGrid({ instanceKey, createDataProvider, ...props }: SingleElementPropertyGridProps): JSX.Element | null
 public;SingleElementPropertyGridProps = Omit
 public;TelemetryContextProvider({ onPerformanceMeasured, onFeatureUsed, children }: PropsWithChildren
-internal;UseContentMenuProps 
-internal;useContextMenu({ dataProvider, imodel, contextMenuItems }: UseContentMenuProps):
-internal;useDataProvider({ imodel, createDataProvider }: DataProviderProps &
-internal;useInstanceSelection({ imodel }: InstanceSelectionProps):
-internal;useNullValueSetting():
-internal;useNullValueSettingContext(): NullValueSettingContextValue
 public;usePropertyGridTransientState

packages/itwin/property-grid/package.json

@@ -34,6 +34,7 @@
     "copy:esm": "cpx \"./src/**/*.scss\" ./lib/esm",
     "cover": "nyc npm run test",
     "extract-api": "betools extract-api --entry=property-grid-react --apiReportFolder=./api --apiReportTempFolder=./api/temp --apiSummaryFolder=./api",
+    "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",
     "lint:stylelint": "stylelint \"./src/**/*.scss\"",

packages/itwin/property-grid/src/PropertyGridComponent.tsx

@@ -11,6 +11,7 @@ import { PreferencesContextProvider } from "./PropertyGridPreferencesContext";
 import type { PerformanceTrackedFeatures, UsageTrackedFeatures } from "./hooks/UseTelemetryContext";
 import type { MultiElementPropertyGridProps } from "./components/MultiElementPropertyGrid";
 import type { PreferencesStorage } from "./api/PreferencesStorage";
+
 /**
  * Props for `PropertyGridComponent`.
  * @public

packages/itwin/property-grid/src/components/ElementList.tsx

@@ -15,6 +15,7 @@ import { Header } from "./Header";
 
 import type { IModelConnection } from "@itwin/core-frontend";
 import type { InstanceKey } from "@itwin/presentation-common";
+
 /**
  * Props for `ElementList` component.
  * @internal

packages/itwin/property-grid/src/components/FilteringPropertyGrid.tsx

@@ -6,11 +6,7 @@
 import { useEffect, useState } from "react";
 import { PropertyValueFormat } from "@itwin/appui-abstract";
 import {
-  FilteredType,
-  FilteringPropertyDataProvider,
-  PropertyDataChangeEvent,
-  PropertyRecordDataFiltererBase,
-  VirtualizedPropertyGridWithDataProvider,
+  FilteredType, FilteringPropertyDataProvider, PropertyDataChangeEvent, PropertyRecordDataFiltererBase, VirtualizedPropertyGridWithDataProvider,
 } from "@itwin/components-react";
 
 import type { PropertyRecord } from "@itwin/appui-abstract";
@@ -31,7 +27,7 @@ import type { IDisposable } from "@itwin/core-bentley";
 export interface FilteringPropertyGridProps extends VirtualizedPropertyGridWithDataProviderProps {
   /** Specifies whether child categories should be auto expanded or not. */
   autoExpandChildCategories?: boolean;
-  /** @internal */
+  /** Filterer used to filter data. */
   filterer: IPropertyDataFilterer;
 }
 

packages/itwin/property-grid/src/components/PropertyGridContent.tsx

@@ -7,19 +7,16 @@ import "./PropertyGridContent.scss";
 import classnames from "classnames";
 import { useCallback, useMemo, useState } from "react";
 import {
-  CompositeFilterType,
-  CompositePropertyDataFilterer,
-  DisplayValuePropertyDataFilterer,
-  FilteredType,
-  LabelPropertyDataFilterer,
-  PropertyCategoryLabelFilterer,
-  PropertyValueRendererManager,
+  CompositeFilterType, CompositePropertyDataFilterer, DisplayValuePropertyDataFilterer, FilteredType, LabelPropertyDataFilterer,
+  PropertyCategoryLabelFilterer, PropertyValueRendererManager,
 } from "@itwin/components-react";
 import { ResizableContainerObserver } from "@itwin/core-react";
 import { Text } from "@itwin/itwinui-react";
 import { useContextMenu } from "../hooks/UseContextMenu";
 import { useLoadedInstanceInfo } from "../hooks/UseInstanceInfo";
+import { useLatest } from "../hooks/UseLatest";
 import { useNullValueSettingContext } from "../hooks/UseNullValuesSetting";
+import { useTelemetryContext } from "../hooks/UseTelemetryContext";
 import { FilteringPropertyGrid, NonEmptyValuesPropertyDataFilterer } from "./FilteringPropertyGrid";
 import { Header } from "./Header";
 import { SettingsDropdownMenu } from "./SettingsDropdownMenu";
@@ -32,8 +29,6 @@ import type { PropertyCategory, PropertyUpdatedArgs } from "@itwin/components-re
 import type { IPresentationPropertyDataProvider } from "@itwin/presentation-components";
 import type { FilteringPropertyGridProps } from "./FilteringPropertyGrid";
 import type { ContextMenuProps } from "../hooks/UseContextMenu";
-import { useTelemetryContext } from "../hooks/UseTelemetryContext";
-import { useLatest } from "../hooks/UseLatest";
 
 /**
  * Arguments for the `onPropertyUpdated` callback.
@@ -58,9 +53,7 @@ export interface PropertyGridContentBaseProps
   onBackButton?: () => void;
   headerControls?: ReactNode;
   onPropertyUpdated?: (args: PropertyGridPropertyUpdatedArgs, category: PropertyCategory) => Promise<boolean>;
-  /** @internal */
   dataProvider: IPresentationPropertyDataProvider;
-  /** @internal */
   dataRenderer?: (props: FilteringPropertyGridProps) => ReactNode;
 }
 

packages/itwin/property-grid/src/hooks/UseDataProvider.ts

@@ -13,6 +13,7 @@ import type { PropertyDescription, PropertyRecord } from "@itwin/appui-abstract"
 import type { KeySet, PageOptions, SelectionInfo } from "@itwin/presentation-common";
 import type { IModelConnection } from "@itwin/core-frontend";
 import type { IPresentationPropertyDataProvider } from "@itwin/presentation-components";
+
 /**
  * Props for data provider used by `PropertyGrid`
  * @public