@procore/labs-related-items

Related Items

RelatedItems is a component connected with Procore API.

Installation

yarn add @procore/labs-related-items

Dependencies

@procore/core-react, @procore/core-icons, @procore/labs-toast-alert, react and styled-components are listed as external peer dependencies. The package will not bundle the code, and requires the app client to provide it as a dependency. The external peer dep is to assure React Context is consistent in a client's React tree, the child consumers can reference the correct parent provider. If the package uses latest features or bug fixes and a new minimum version of core-react is required, it should be considered a breaking change as the peer dependency version must be met.

RelatedItems depend on CORE I18nProvider and @procore/labs-toast-alert's ToastAlertProvider to work properly.

Usage

import { I18nProvider } from '@procore/core-react';
import { ToastAlertProvider } from '@procore/labs-toast-alert';
import { RelatedItems } from '@procore/labs-related-items';

<I18nProvider>
  <ToastAlertProvider>
    <RelatedItems.Provider
      procoreEnv={...}
      holder={...}
      permissions={...}
    >
      <RelatedItems/>
    </RelatedItems.Provider>
  </ToastAlertProvider>
</I18nProvider>

RelatedItems.Provider

RelatedItems.Provider holds and shares application configuration and state between RelatedItems, RelatedItems.Sidebar and RelatedItems.Count.

The primary configuration points are:

• procoreEnv - describes Procore project and company,
• holder - identifies the entity which holds related items.
• permissions - describes current user permissions to link and unlink items, has shape: { canLinkItem: boolean; canUnlinkItem: boolean; }

It is recommended to put RelatedItems.Provider on the top of the application tree, with the rest of providers.

RelatedItems.Panel

RelatedItems.Panel component is responsible for displaying the Related Item creation form. It is intended to be placed inside DetailPage.Aside CORE component and requires no configuration.

RelatedItems.Panel#ref should be used to control it's visibility. ref contains open and close methods, as well as rootElRef containing the DOM root of the panel.

RelatedItems.Count

RelatedItems.Count component is responsible for dynamically displaying the total amount of related items. It is intended to be placed inside DetailPage.Tabs CORE component. format prop can be used to alternate the view of a counter.

RelatedItems

RelatedItems component is responsible for displaying and editing the list of related items. It is intended to be placed inside DetailPage.Body CORE component.

Migration to 1.0.0 version

Pass required permissions prop to RelatedItems.Provider. Example PR for 1.0.0 version migration