carbon-design-system / carbon-addons-iot-react

A collection of React components shared between IBM Watson IoT products.

Warning

This library no longer has a dedicated development resource maintaining it. When you are able to migrate to Carbon v11 we recommend you reference the related component guide and use components from Carbon for IBM Products and core Carbon.

Carbon add-ons for Watson IoT

Carbon add-ons for Watson IoT is an open-source react component library built by IBM Watson Internet Of Things. With the Carbon Design System and IBM Design Language as its foundation, the library consists of working code, resources, and a vibrant community of contributors.

Installation

@latest from master   -  

# with npm
npm install carbon-addons-iot-react d3@">=5.0.0 <=5.14.2"

# with yarn
yarn add carbon-addons-iot-react d3@">=5.0.0 <=5.14.2"

@next pre-releases from next   -  

# with npm
npm install carbon-addons-iot-react@next d3@"^7.0.0"

# with yarn
yarn add carbon-addons-iot-react@next d3@"^7.0.0"

d3 is a peer dependency due to the usage of @carbon/charts in various components. The required version range is specified in package.json

Subscribe to all pre-releases on next

Pre-release versions are available on carbon-addons-iot-react@next. The default version range that is automatically added to your package.json on install/add will only follow pre-releases on the same major.minor.patch version. The version range can be modifed to follow all pre-releases:

"dependencies": {
-    "carbon-addons-iot-react": "^2.139.0-next.4"
+    "carbon-addons-iot-react": "next"
  }

🚀 Quick Start

To test drive everything here, use create-iot-react-app. It will create a new project that is preconfigured with everything you need to begin to build an application.

npx create-iot-react-app <app-name>

Styling

What's included

carbon-addons-iot-react/
├── css
│   ├── carbon-addons-iot-react.css
│   └── carbon-addons-iot-react.css.map
├── scss
│   └── components
│       └── modal
│           └── _modal.scss
│       └── ...
│   └── globals
│       └── scss
│           └── _vars.scss
│           └── ...
│   └── styles.scss (sass entrypoint)

Compiled CSS files are provided for ease of use getting started.

A sass entrypoint is available at scss/styles.scss for use in your project.

Using sass files (instead of the compiled .css) infers usage of a SCSS pre-processor. All Sass files use the *.scss file extension. For transpiling Sass code, use node-sass based Sass compilers, for example, WebPack sass-loader or gulp-sass. Make sure your build process uses autoprefixer to ensure vendor prefixes are automatically added to your output CSS.

Feedback and improvement requests regarding this configuration would be appreciated, please open an issue.

Dependencies

Usage of this package does not require you to install additional Carbon packages; carbon-components, carbon-components-react, or @carbon packages (@carbon/grid, @carbon-layout, etc) as peer dependencies. You may still need these packages if you use them directly in your project.

🤲 Contributing

Please check out our Contribution Guidelines for more info on how you can help out!

Testing

You can find our component test statement here

If you are using our project with Jest tests, due to it's dependency on d3, you may have to add some mock to your Jest setup script. See this issue for more details: jestjs/jest#5379

Here's an example setup script, update your jest config to point to a setup script: setupFiles: ['setupJest.js'],

setupJest.js contents:

class SVGPathElement extends HTMLElement {}

window.SVGPathElement = SVGPathElement;

carbon-addons-iot-react's Issues

[Table] selectable and reorderable columns

[Table]: Handle automatic truncation at max-width and native browser flyovers

Detailed description

Tables should automatically truncate at some max-width and set titles on spans for automatic browser flyovers.

[Table] Provide example story on how to render custom component inside Table, figure out how to handle sort/search as well

[Table]: Need an onclick handler for the table

Title line template: [Title]: Brief description

Need an onclick handler for table. We need to know when a row is clicked on (not just when its mark selected via the checkbox.

Detailed description

The table should support onclick so that when a user clicks on a specific row we can take the appropriate action.

What version of the Carbon Design System are you using?
"carbon-components": "9.66.3",
"carbon-components-react": "6.83.2",

What offering/product do you work on? Any pressing ship or release dates we should be aware of?
This is for the Maximo Spark project.

[Table]: Filter toggle icon should switch to blue if filter toolbar is currently active

To more clearly indicate which toolbar is toggled on, these buttons should change colors when they're toggled on.

[Table]: MVP Epic for shared table component

Full MVP of Table Epic scope documented here: https://ibm.box.com/s/s7g41diabavblm2ulk7qjt0nkuhv99sc

Remove top margin from header component

Detailed description

Describe in detail the issue you're having.

A margin was applied to the Header component so it would look better in storybook. Should not be deployed with the component. Remove

Is this a feature request (new component, new icon), a bug, or a general issue?

Bug

Is this issue related to a specific component?

Related to Header Component

[Table] batch actions action pass along selected row id (or row data) too

It would be nice to pass along the current row selections with the batch action callback

[Table]: table row actions are hidden on the far right of the table in a scroll

Small little bug where the table body/headers is too big for the view and the right side is getting chopped a little

[Table] Row Actions

Implement row actions

State: Row Hover

State: Row Expanded

When a row is expanded, the row actions should be visible regardless of hover state (and use a white line/fill).

[Table] Stateful table - Searching behavior needs to support matching on child and showing parent OR matching on parent and showing child

[Table]: should we support lazy loading of the children rows. If so we'll need some UX to indicate this expansion is loading

[Table]: Twisty Can we set icon indicators to the far left of the twisty and or selection checkbox

[Page Layout] Need to share Page Hero and internal Tab navigation components

Detailed description

Enhancement request to share Page Hero and internal Tabbing structure between our IoTP platform

See the "Devices" "Device Types" etc below...

[Wizard]: Add inline wizard to shared library for reuse

IoT Platform has implemented this, please port over to this shared library so we can reuse in IoT CS Entity Type creation

Denny will implement

[TileCatalog]: last card shouldn't stretch out to be full width and update story

This is from @lukefirth

@scottsd Could we see the example with some descriptive text in there as well as the title?

• I see on the default and w/search examples, we have a ‘test tile 7’ which spans the full width. That raises a good point I didn’t include - how we handle blank space. I suggest we have a blank/no-selectable filler card rather than stretch the final one.

[Table]: Support internal vertical scrolling

Our current Entity Type table supports internal vertical table scrolling

[Table]: Loading State while data loading

Add loading state to Table enhancement

[Table] Provide example of table with horizontal scrolling

Ensure that the Table can horizontally scroll if it exceeds the bounds of the parent container.

This will likely just require a overflow CSS rule on the table content.

Write two stories:

1. Table rendered inside of a container div that is smaller than the page width
2. Table rendered with the full width of the page, but enough content inside to force the rendered table width to exceed the window size.

[Table]: Need a nice "deleting" state as records are being deleted..

Usecase is that the table should give some sort of indication as records are being deleted from a remote server. And also handle the fact that the record deletion might fail.

[List]: add shared list component to repo

Include new list components:

• Structured List:

1. Present simple data
2. Items in list can be selected

• Resource List:

1. To present non-data items that have more details to show
2. Supports inline actions and single-select selection interaction

[Table] Add cell indicator

Detailed description

Add support for a column to support a custom cell decorator icon. This icon would appear to the left of a column (with a fixed width) and with value determined from the row data.

Additional information

[Table]: Users want our stateful table example to support sorting on their cells with custom (non-text) content

Plan is to always use the 'value' of the cell to do sort and filtration on the table row, if they have a custom renderer that they want to pass to the cell, we'll do a callback on the render function.

Add RTL support to Storybook

Storybook support a RTL plugin for testing in RTL environments. This should be added to the storybook, so that component developers and QA testers can verify that components are functional (both visually and interactively) in RTL environments.

https://www.npmjs.com/package/storybook-addon-rtl

[Table] Empty state

Implement an empty table state. Optionally include a CTA button

[Modal]: if no helpText is set we shouldn't keep padding

Bug:

If I pass null to helpText prop of header, it shouldn't render the paragraph with styles

[Table]: Add Quick search and stateful table support search

Server-side search too...

[Table]: support some fixed columns with other columns in a horizontal scrollpane

https://pages.github.ibm.com/cynthiaz/PlatformPrototype/Explore/entity_splitview.html#Entity_Type=illuminance&CSUM=1

[Table] Allow Advanced Query of Table component, need a UX mockup of how that would look, where we would implement

The usecase is, what does the Table component look like if it is being Searched with an Advanced Searched query dialog that will fire a query against the server and then prepopulate the table. Do filters within the Table update, etc. We need some UX designs here of how the table should act.

@JordanWSmith15 can you work with Karen to help with that?

[Table]: Row Actions how should they work with horizontal scrolling?

[Header] Desktop Support for left navigation, top dropdown menus

Detailed description

Enhancement request to have a shared UI Shell/Navigation drop. Starting from Carbon component UI Shell

Target is Q2 for IoT Platform teams and IoT CS, Main pressure would be @JordanWSmith15 team

[Table] Lightweight design

Add a "lightweight" styling to the table (prop under options) that matches the following designs.

This table still maintains all capabilities of the full table (pagination, filter, column selection, batch actions).

[Header]: Support switching left-hand navigation between modes with different navigation areas.

The maximo team has a usecase where the navigation area switches between modes (carbon's SideNavDetails & SideNavSwitcher)

[Table]: selection box support indeterminate state based on the selection of their children state

Pulled from comments:

This issue clarifies the general selection state across parent and child row.
The IoT Table component should follow the core behavior of the Carbon table component, and secondarily any common hierarchical table component row selection industry practices.

In summary

• Selection states are none (empty), all (filled), partial (dash). There are selection icons for each.
• Selecting the parent will select all children
• Unselecting the parent will unselect all children
• Changing the selection of a child will change the state of the parent to partial
• Selecting a partial parent will make the parent and children selected

Optional

• A selection state change may be revoked with a ctrl-z

[Table]: Support row children as well as row details

Enhancement to support expanding rows and children

[Table]: Extend our stateful table sort to support number, timestamp, column sorting out of the box

Change to the table reducer to not just do a simple string sort...

[FileUploader]: add shared file uploader component to repo

Add shared file uploader Carbon extension for reuse across the teams

1 - It supports bothbrowse and drag and drop design
2 - The component handles file reading and accepts a callback for when the file data is loaded

[Table]: GVT testing.

Use the table in a GVT environment and make sure that all the user-visible strings are correctly translated/translatable

[Table] Expand/Collapse icon can we allow the checkbox to the far left of the twisty.

[Table]: Easy to consume max table cell width applied per column

take a look at the story for an example of how to do this dynamically with classes
https://ibm.github.io/carbon-addons-iot-react/?selectedKind=Table&selectedStory=max%20column%20width&full=0&addons=1&stories=1&panelRight=0&addonPanel=storybooks%2Fstorybook-addon-knobs

[Table]: validate the server-side paging works with filter/sort

We think this is a test only statement to make sure this works..

[Table]: Nested Rows render within Tables

add nested rows to the table props model

[Table]: none sort indicator isn't working correctly on Table column

Steps to reproduce the issue

1. Sort a column 3 times in the Stateful table example (which should set it to the none sort) . Instead the table shows an indicator as if the column is sorted:

Additional information

[Table] Variable row height at 24px, (32px), 42px height

Need to investigate, how is this different from lightweight mode of table

What is the QA and regression testing process around components

Is there a formal QA process for the IoT components? I know there are Jest tests and code reviews, but, are the dedicated resources to verifying a component does what it should do, and that a component isn't broken? Are there UI automation tests (selenium?) that are run to verify a component's behaviour hasn't changed?

[Table]: Export example tableState Reducers to reuse by external teams that might want to link to Redux

export tableState Reducers

[Table] Filters

Implement filter enhancement to table component

Model

• Filter option and format (i.e. canFilter, filterType = 'enum', filterOptions = ['Connected', 'Disconnected']) should be associated with columns prop in table.
• Active filter(s) should be under view prop (example: `view.filter.activeFilters = [{ id: 'deviceId', value: 'A123*' }, { id: 'status', value: 'Connected' }])

State: No filters added

• User can apply filters in the table at column level.
• When filter button is clicked, the filter icon turns blue and the filters expand

State: With filters added

• Once a user starts typing in a filter, a cancel button would pop up similar to how the search bar functions
• User can press enter or click off the input to add their filter
• A "clear all filters" button would appear once any filters have been added

[Table]: Provide a stateful table component for easy reuse with some defaults

Setting up the reducers, etc

Create a consistent data interface for components

There are several components that all manage data, such as, Table, ResourceList, StructuredList, and TileCatalog. Each of these have very different interfaces for how data is provided and how content is rendered. There needs to be a closer discussion around each of these components on how they manage and render items.

Table and StructuredList share a similar data model for columns and data, although the data model is not ideal for consumption, since it forces consumers to transform their data into model for the table. Table and StructuredList are very similar in that a basic table is rendered like a StructuredList, so, it begs the question as to why StructuredList exists? (do we really need both?)

ResourceList uses a normal data model of a json array of flat objects, but, lacks any ability to customize what is in the list.

TileCatalog uses a data model that is a mix of data and React content nodes, that makes it problematic for consuming, since, I have to pre-build all my tiles before passing it to the component.

Every component that manages a list of data, should use the same interface for the data. I should be able to set my data items on a Table or TileCatalog and not be expected to transform my data differently for each of those.

When we have repeated data, we can always think about that a json array of rows, where each row is a json object. Each row will usually have an id field, but that field will likely be different depending on the data source. ie, sometimes the id might be id, or _id, or uniqueId, rowstamp, etc.

When we have components that need to render repeatable data, we should always try to defer that rendering as late as possible, and not make the consumer pre-build the content as part of the data. Using the the React Render Props Pattern is generally a good way defer the rendering a repeated component, and give the flexibility to the consumer of how render. It also ensure that you can ensure that you are not mixing data and view components in the same structure.

As a general rule, if your repeatable data structure requires that that a consumer start iterating their data and transform it, radically, adding in View nodes, alarm bells should be going off, as a bad design.

Ideally, as noted, we should be able to move our data between components and not have to transform the data over and over. At a minimum, the interface to a repeating component that manages data should be something like...

const data = [
   {_id: 0, name: 'bill', age: 39},
   {_id: 1, name: 'tom', age: 42}
];
const renderFunc = (props) => {
    return <div>{props.item.name}</div>
};
<List idAttribute="_id" data={data} itemRenderer={renderFunc}/>

Typically the render function will want to accept a props structure where the props will have the item as the very minium piece of information, but you might also want to pass the id, index and even the list of the items. Components can provide a default render function if they don't wan the user to have to specify one, every time.

As a consumer, I should be able to pass my data to a Table or TileCatalog. I might need to provide different kinds of renders for each (table using a cell render and tile catalog using a tile renderer) but the data interface remains the same.

Some components may actually manage their own "selection" state, and as such, components that manage selection, should also be able to set their initial selection state based on the data, such as...

<List idAttribute="_id" data={data} itemRenderer={renderFunc} selectedAttribute="_selected_" onRowSelected={(row, selectionStatus)=>updateSelectionInModel(row, selectionStatus)}/>

The use case for this would something like this.. Let's say I have Table View but I allow the user to switch to a Tile View. The data manager will manage the selection status, since, if I select a row in the table and then move to a tile view, that row should still be selected. If select additional tiles, and then switch back to the table view, then those rows should be selected in the table as well.

[Table]: Style fixes on the table bug

we found some style issues on the Table yesterday when unit testing it