@procore/labs-configurable-field-sets-data-table v3.1.0

Configurable Field Sets Data Table

Components and functions to support Configurable Field Sets and Custom Fields with the Data Table package. Please add yourself to the team-config slack channel and ask to be subscribed to bug fixes.

Procore Status

Trial

Dependencies

This package relies on @procore/labs-configurable-field-sets, @procore/labs-data-table, date-time-format-timezone, @procore/core-react, and react being external peer dependencies, it does not bundle the code, and requires an 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. Please review and stay within range of the peerDependencies.

IE11 Support

Timezone support is partially unavailable for IE 11, which can be restored with date-time-format-timezone polyfill. This package requires the client to include a single polyfill to support IE11. The polyfill is large in size and should only be installed in the app client once.

For the polyfill package above, add the below line to your list of imports

// index
import 'date-time-format-timezone';

Types

Exposed types for import in a client are available under the CFSDT namespace.

Assurance

By default, custom fields provide read-only, filtering, and sorting support and procore fields will be displayed when visible.

To change a column definition before it is added, the second argument of the hook's ensure method allows a callback with the to-be-added definition and the field.

If a field has already been added (like loading column definitions from localStorage), you will need to map over the return result. Tip: Importing isKeyCustomField from the main CFS package can help determine which columns are custom fields.

hook#ensure(columnDefinitions, adjustBeforeAdd?): columnDefinitions

Given no data, it will generate column definitions to get up and running.

More importantly, given initial columns it removes columns based on the company's CFS.

At time of writing, these are the guarnatees it makes. An updated list can be seen in the repo's tests.

Visibilty, Additions, Deletions
  Generic Columns
    ✓ Leaves them alone
  Procore Columns
    ✓ Removes hidden
    ✓ Adds newly added (basic text rendering)
  Custom Columns
    ✓ Removes hidden
    ✓ Removes deleted
    ✓ Adds newly added (fully featured*)
    Unsupported Field Types
      ✓ Removes rich text
      ✓ Removes file upload
Order Examples
  ✓ Keeps the order of the original columns (not CFS order)
  ✓ Adds new custom fields to the end

*fully featured may not mean has all the features, it is limited by Data Table support per feature per data loading model

Say you wanted to remove sorting from login_information types, you can use the second argument to adjust the column definition before it is added. Once that field is added (e.g. added in a previous session and saved in localStorage), it will not go through the adjuster again.

const columnDefinitions = ensure(
  [{ field: 'client_only' }, { field: 'title' }, { field: 'custom_field_1' }],
  (cd, field) =>
    field.data_type === 'login_information' ? { ...cd, sortable: false } : cd
);

The leaf package has a helper for checking if a field key is like custom_field_\d.

import { isKeyCustomField } from '@procore/labs-configurable-field-sets';

Usage

Server Side Data Model

Support Legend:

• ✅ Supported out of box
• 🟩 Supported if backend can, frontend can leverage
• ⭕️ Intentionally not supported by team, undefined by design system
• ☑️ Loose support, disabled by default
• ⚠️ No support but supported in Data Table
• ❌ No support and none to weak support in Data Table
• ❓ Does support make sense or needs design guidelines

Use useConfigurableFieldSetDataTableServerSide.

Required Style Props

timeZone string: required

Optional Style Props

currencyIsoCode string: optional

Formats the currency cell in the proper currency format leveraging the GTK. If currencyIsoCode is specified, currencyIdentifier will not be used.

currencyDisplay : 'code', 'name', 'narrowSymbol', 'symbol': optional

Determines what display will be used leveraging the GTK. This is used when there is a currencyIsoCode.

currencyIdentifier string: optional

Used to display the currency symbol. If you don't have a currencyIsoCode, use this. If this is present and currencyIsoCode is not, both currencyIsoCode and currencyDisplay will not be used. This is for legacy clients that don't have a currencyIsoCode yet. Eventually currencyIdentifier will be deprecated.

import { I18nProvider } from '@procore/core-react';

import {
  ConfigurableFieldSetProvider,
  ConfigurableFieldSetCacheProvider,
} from '@procore/labs-configurable-field-sets';

import { useConfigurableFieldSetDataTableServerSide } from '@procore/labs-configurable-field-sets-data-table';

<I18nProvider>
  <ConfigurableFieldSetCacheProvider>
    <ConfigurableFieldSetProvider
      companyName={string}
      companyId={string | number}
      projectId={string | number}
      projectName={string}
      config={{
        id: -1,
        fields: { title: {}, custom_field_1: {}: previously_there_cfs_field: {} },
      }}
    >
      <AppWithDataTable />
    </ConfigurableFieldSetProvider>
  </ConfigurableFieldSetCacheProvider>
</I18nProvider>;

async function onServerSideDataRequest({ request, onSuccess }) {
  const url = todoMakeUrl(request.serverFilters, request.sortModel);
  await const rows = fetch(url);

  onSuccess({
    rowData: rows,
    rowCount: rows.length,
  });
}

function AppWithDataTable() {
  const { ensure } = useConfigurableFieldSetDataTableServerSide({
    timeZone: string,
    currencyDisplay?: 'symbol' | 'narrowSymbol' | 'code' | 'name' | undefined,
    currencyIdentifier?: string,
    currencyIsoCode?: string,
  });
  const someDefinitions = [
    { field: 'client_only', cellRenderer: 'textCellRenderer' },
    { field: 'previously_there_cfs_field', cellRenderer: 'textCellRenderer' },
  ];
  const columnDefinitions = ensure(someDefinitions);

  return (
    <DataTable columnDefinitions={columnDefinitions} onServerSideDataRequest>
      <DataTable.Table />
    </DataTable>
  );
}

Client Side Data Model

Support Legend:

• ✅ Supported out of box
• 🟩 Supported if backend can, frontend can leverage
• ⭕️ Intentionally not supported by team, undefined by design system
• ☑️ Loose support, disabled by default
• ⚠️ No support but supported in Data Table
• ❌ No support and none to weak support in Data Table
• ❓ Does support make sense or needs design guidelines

Use useConfigurableFieldSetDataTableClientSide.

Required Style Props

timeZone string: required

Optional Style Props

currencyIsoCode string: optional

Formats the currency cell in the proper currency format leveraging the GTK. If currencyIsoCode is specified, currencyIdentifier will not be used.

currencyDisplay : 'code', 'name', 'narrowSymbol', 'symbol': optional

Determines what display will be used leveraging the GTK. This is used when there is a currencyIsoCode.

currencyIdentifier string: optional

Used to display the currency symbol. If you don't have a currencyIsoCode, use this. If this is present and currencyIsoCode is not, both currencyIsoCode and currencyDisplay will not be used. This is for legacy clients that don't have a currencyIsoCode yet. Eventually currencyIdentifier will be deprecated.

import { I18nProvider } from '@procore/core-react';

import {
  ConfigurableFieldSetProvider,
  ConfigurableFieldSetRow,
  ConfigurableFieldSetCacheProvider,
} from '@procore/labs-configurable-field-sets';

import { useConfigurableFieldSetDataTableClientSide } from '@procore/labs-configurable-field-sets-data-table';

<I18nProvider>
  <ConfigurableFieldSetCacheProvider>
    <ConfigurableFieldSetProvider
      companyName={string}
      companyId={string | number}
      projectId={string | number}
      projectName={string}
      config={{
        id: -1,
        fields: {
          title: {},
          custom_field_1: {},
          previously_there_cfs_field: {},
        },
      }}
    >
      <AppWithDataTable />
    </ConfigurableFieldSetProvider>
  </ConfigurableFieldSetCacheProvider>
</I18nProvider>;

function AppWithDataTable() {
  const { ensure } = useConfigurableFieldSetDataTableClientSide({
    timeZone: string,
    currencyDisplay?: 'symbol' | 'narrowSymbol' | 'code' | 'name' | undefined,
    currencyIdentifier?: string,
    currencyIsoCode?: string,
  });
  const someDefinitions = [
    { field: 'client_only', cellRenderer: 'textCellRenderer' },
    { field: 'previously_there_cfs_field', cellRenderer: 'textCellRenderer' },
  ];
  const columnDefinitions = ensure(someDefinitions);

  return (
    <DataTable columnDefinitions={columnDefinitions}>
      <DataTable.Table rows />
    </DataTable>
  );
}