Readme Update (Updates Contributing, Usage) Sections

[CalebGerman]

Usage

To begin using this package in your application, you will need to:

1. Add changedelements:read and changedelements:modify OAuth scopes to your iTwin Platform application App Setup.

2. Provide <VersionCompareContext /> somewhere in your app.

   import { VersionCompareContext } from "@itwin/changed-elements-react";
   
   <VersionCompareContext iModelsClient={iTwinIModelsClient}>
     <App />
   </VersionCompareContext>

3. Initialize Version Compare module at application startup. This only needs to be done once.

   import { VersionCompare } from "@itwin/changed-elements-react";
   
   VersionCompare.initialize({
     ... // Look at VersionCompareOptions interface for documentaton about the options
   });

4. The <ChangedElementsWidget /> React component lets users inspect differences in properties between versions, generate reports, search for changed elements, and control element visibility. The following code shows an example widget initialization (does not show off all props).

   import { ChangedElementsWidget } from "@itwin/changed-elements-react";
   
   <ChangedElementsWidget
     useV2Widget
     feedbackUrl="https://example.com"
     iModelConnection={UiFramework.getIModelConnection()}
     enableComparisonJobUpdateToasts
     manageNamedVersionsSlot={<ManageNamedVersions />}
     documentationHref="https://example.com"
   />,

5. The <NamedVersionSelectorWidget /> is an experimental React component that lets users inspect differences in properties between versions, generate reports, search for changed elements, and control element visibility. The following code shows an example widget initialization (does not show off all props).

   import { NamedVersionSelectorWidget } from "@itwin/changed-elements-react";
   
   <NamedVersionSelectorWidget
     iModel={iModel}
     manager={VersionCompare.manager}
     manageVersions={<ManageNamedVersions />}
     feedbackUrl="https://example.com"
     documentationHref="https://example.com"
   />

6. The <PropertyComparisonTable /> React component lists properties of a selected element and displays how they changed between two versions.

   import { PropertyComparisonTable } from "@itwin/changed-elements-react";
   
   <PropertyComparisonTable
     manager={versionCompareManager}
     selection={selection}
     isSideBySide={false}
     displaySideBySideToggle={true}
     onSideBySideToggle={() => {
       // handle toggle logic here
     }}
   />

Contributing

Issues

We welcome contributions to make this package better. You can submit feature requests or report bugs by creating an issue.

Versioning with Changesets

This repository uses Changesets to manage package versioning and changelogs. When making changes that affect the public API or behavior, please add a changeset by running:

pnpm changeset

Follow the prompts to describe your changes and select the appropriate version bump (major, minor, or patch). Versioning should follow semver conventions. If no version bump is required (such as for documentation-only changes), use pnpm changeset --empty.

When changesets are added and merged into the main branch, a release pull request (PR) will be automatically created by the Changesets GitHub Action. This PR will contain the version updates and changelog entries generated from your changesets. Review the release PR to ensure the version bumps and changelog messages are accurate before merging. Once the release PR is merged, the new package version will be published automatically.

For more details, see the Changesets documentation.

[changeset-bot]

🦋 Changeset detected

Latest commit: 73aa4ba

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR