@paprika/list-box-browser

Description

ListBox Browser component is a two column layout that allows users to select one or multiple options. It is similar to the experience of browsing a file manager in any operating system.

Installation

yarn add @paprika/list-box-browser

or with npm:

npm install @paprika/list-box-browser

Props

ListBoxBrowser

| Prop | Type | required | default | Description | | ---------------------- | ------ | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | data | any | true | - | An array of javascript objects holding the data structure for the ListBoxBrowser. The object shape must have at least a string label property and an array options property in one of the objects. Also can hold any other kind of data for your own use. | | isMulti | bool | false | true | Indicates if the user can select multiple options | | height | number | false | 220 | Set the height for the ListBoxBrowser | | onChange | func | false | () => {} | Callback function receiving an array of selected options by the component | | isParentSelectable | bool | false | null | Allows the user to select the parent options | | rootTitle | node | false | "" | Content title for the left column | | browserTitle | node | false | "" | Content title for the right column | | children | node | false | null | You can pass <ListBoxBrowser.OptionSelected /> as a children | | hasBreadcrumb | bool | false | true | Indicates if the right column should display a breadcrumb | | hasError | bool | false | false | Set a border red color around the component indicating that has an error | | onFetch | func | false | null | When declaring the array options empty, this will be executed to retrieve the data, useful if you want to do a lazy load. | | defaultSelectedOptions | func | false | () => false | A function that sets an option selected returning true or false you can use to compare your data structure and decide if the option is initially selected or not. | | defaultSelectedView | func | false | null | A function that sets the initial view for the right columns (Browser) of the ListBoxBrowser the option selected to be the initial view should have options to be valid, by default the ListBoxBrowser picked the first option which has options to be the initial value. | | hasLeftColumn | bool | false | true | In the case you want to use the ListBoxBrowser with one column you can hide the root column |

CustomListBox

| Prop | Type | required | default | Description | | --------------- | --------------- | -------- | -------- | ----------- | | hasOnUp | bool | false | false | | | id | [string,number] | false | "root" | | | isLoading | bool | false | false | | | onChange | func | true | - | | | onClickNavigate | func | true | - | | | onUp | func | false | () => {} | | | options | arrayOf | true | - | |

Title

| Prop | Type | required | default | Description | | ----------------- | --------------- | -------- | ------- | ----------- | | rootTitle | node | true | - | | | browserTitle | node | true | - | | | data | arrayOf | false | - | | | browserKey | [string,number] | true | - | | | onClickBreadcrumb | func | true | - | | | hasLeftColumn | bool | true | - | |

Usage

The <ListBoxBrowser /> is primarily an uncontrolled component which receives a data prop which allows the consumer to set the initial state.

It has two functions to set defaults. One for selected options and another for a default selected view for the browser column.

The onChange prop receives a parameter with an array of the selected options.

Data prop

The most important prop for the <ListBoxBrowser /> is the data prop, which initializes the state for the component.

The data prop is an array of objects where each object requires to have at least a label attribute on it and at least one of those items should include an options property.

Data prop shape

[{ label: "One" }, { label: "Two", options: [{ label: "Three" }] }];

{
	label: "require attribute",
	options: [{}{}{}], // more object with the same shape
}

The object can have an options attribute, which is an array of the same kind of objects.

A data prop with options looks like:

const data = [
   {
        label: "NBA",
        options: [{ label: "Toronto Raptors"}, {...}]
   },
   {
        label: "NHL",
        options: [{ label: "Vancouver Canucks"}, {...}]
   },
   {
        label: "MLS",
        options: [{ label: "Vancouver Whitecaps"}, {...}]
   },
]

Recursively the component runs over all the options on the array and assembles the UI for the user.

NOTE You can add extra properties to the objects; those are and pass to you back on the onChange function or when using defaultSelectedOptions, defaultSelectedView functions.

Basic example

import ListBoxBrowser from "@paprika/list-box-browser";

export default function App() {
   const data = [{...}...{...}]; // your data;
   return <ListBoxBrowser data={data} />
}

ListBoxBrowser.SelectedOptions

By default, the <ListBoxBrowser /> does not display a list of the selected options. But you can activate this feature to display multiple options using the <ListBoxBrowser.SelectedOptions /> subcomponent.

<ListBoxBrowser data={data}>
  <ListBoxBrowser.SelectedOptions />
</ListBoxBrowser>

defaultSelectedOptions

The defaultSelectedOptions receives a function to be executed to determine if an option should start as selected or not. This function is called as options are passed down on the data prop.

Ex.

const data = [{ key: 1, label: "one", options: [...] }, { key: 2, label: "two" }, { key: 3, label: "three" }]

<ListBoxBrowser data={data} defaultSelectedOptions={(option) => {
  return option.key === 2 or option.key === 3
}} />

const data = [
	{ key: 1, label: "one", options: [{...}]},
	{ key: 2, label: "two", options: [{...}]},
	...
]

<ListBoxBrowser
	data={data}
	defaultSelectedView={(option) =>  (option.key === 1)}  />

/** The previous result on option with `key 1` to be selected */

defaultSelectedView

This prop works exactly like the defaultSelectedOptions. It receives a function which you can use to compare and decide what option should be the one as initial view.

Note: Be sure to select an option property with options. Otherwise, this function doesn't work and falls back to the default behaviour, which selects the first option with options.

Lazy loading

This component provides a way to load async options. To achieve this, you can declare the options array property empty []. This indicates to the component to fire the onFetch={option => ()} prop when the user interacts with it.

<ListBoxBrowser
  data={[{ label: "lazy", options: [] }]}
  onFetch={option => {
    logic;
  }}
>
  <ListBoxBrowser.Browser isLoading={isBrowserLoading} />
</ListBoxBrowser>

Lazy loading example

To help you to sync your data with the newest options, the ListBoxBrowser provides you with some tools to make it easier:

A Subcomponent <ListBoxBrowser.Browser isLoading /> which lets you set the right column into a pending state. A ListBoxBrowser.findOption(data, fn) which helps you in finding an option in your data so you can modify it.

export default function App(props) {
  const [isBrowserLoading, setIsBrowserLoading] = React.useState(false);
  const [data, setData] = React.useState(props.defaultData);

  async function handleFetch(option) {
    setIsBrowserLoading(() => true);
    const key = option.key;
    const response = await fakeFetch({ key });

    setData(data => {
      const cloneData = data.splice(0);
      const o = ListBoxBrowser.findOption(cloneData, option => option.key === key);
      o.options = response;

      return cloneData;
    });
    setIsBrowserLoading(() => false);
  }

  return (
    <ListBoxBrowser onFetch={handleFetch} data={data} rootTitle="Universes" browserTitle="Heroes">
      <ListBoxBrowser.Browser isLoading={isBrowserLoading} />
      <ListBoxBrowser.OptionsSelected />
    </ListBoxBrowser>
  );
}

Links

• Storybook Showcase
• GitHub source code
• Create GitHub issue
• CHANGELOG