orizzonte v0.3.7

Orizzonte

React components for a horizontal, filtered search UI

Usage

The organization of Orizzonte is simple: first you have the encapsulating Orizzonte component, then there are groups and every group holds one or more filters of its own. Groups can be added and removed from the Orizzonte bar, so users can include only what is relevant to them. Whenever field values change, Orizzonte will compute a new query object with all new values from all groups that are currently visible. Here is a basic example.

import Orizzonte, { Choices, Dropdown, FullText, Group, Select, Toggle } from 'orizzonte';

<Orizzonte
  query={{
    language: 'fr',
    waistSize: 32,
    shirtSize: ['m', 'xl']
  }}
  clearedQuerySnapshot={{
    language: 'en'
  }}
  onChange={(query) => {}}
  onGroupAdd={(groupIndex) => {}}
  onGroupRemove={(groupIndex) => {}}
  groupTopLabels
>
  <Group
    description="Choose your shirt and waist sizes"
    label="Sizes"
    included
  >
    <Dropdown
      fieldName="shirtSize"
      label="Shirt Size"
      selectedLabel={ (value, totalCount) => {
        if (value.length <= 2) {
          return `Size (${ value.map((v) => v.label).join(' & ') })`;
        }
        if (value.length === totalCount) {
          return 'Any shirt size';
        }
        return `Size (${ value.length } selected)`;
      }}
      options={[
        {
          value: 'Small sizes',
          children: [
            {label: 'Extra Small',value: 'xs',disabled: true,facetCount: 0},
            {label: 'Small',value: 's',facetCount: 129}
          ]
        },
        {label: 'Medium',value: 'm',facetCount: 213},
        …
      ]}
      multiple
      selectAll
    />
    <Choices
      fieldName="waistSize"
      label="Waist Size"
      selectedLabel={ (value) => (`${ value.selectedLabel || value.label } waist size`) }
      options={[
        {label: 'Extra Small (28)',selectedLabel: 'Extra Small',value: 28,facetCount: 345},
        {label: 'Small (30)',selectedLabel: 'Small',value: 30,facetCount: 12},
        {label: 'Medium (32)',selectedLabel: 'Medium',value: 32,facetCount: 228},
        …
      ]}
      multiple
    />
  </Group>
  <Group
    label="Locale"
    included
  >
    <Select
      fieldName="language"
      label="Language"
      selectedLabel="%s (Primary)"
      options={[
        {label: 'English',value: 'en'},
        {label: 'French',value: 'fr'},
        {label: 'German',value: 'de'},
        …
      ]}
    />
    <Toggle
      fieldName="toggle"
      option={{
        label: 'Toggle me on or off',
        value: 'on'
      }}
      selectedLabel="Toggle is on"
      toggleStateLabel={{
        on: 'Active',
        off: 'Inactive'
      }}
    />
    <Dropdown
      fieldName="country"
      label="Country"
      selectedLabel={selectedLabel}
      options={[
        {label: 'United Kingdom',value: 'uk'},
        {label: 'France',value: 'fr'},
        {label: 'Germany',value: 'de'},
        …
      ]}
      filter={{
        enabled: true,
        placeholder: 'Search options...'
      }}
    />
  </Group>
  <Group
    label="Keywords"
  >
    <FullText
      fieldName="keywords"
      label="Keywords"
      selectedLabel={(value) => (truncate(value.trim(), {
        length: 20
      }))}
      placeholder="Enter some keywords..."
      multiline
    />
    <FullText
      disabled
      fieldName="disabledTextField"
      label="Another field"
      placeholder="This one is disabled..."
    />
  </Group>
</Orizzonte>

Examples

Click here for a live demo

Storybook

Orizzonte comes with a Storybook that you can run yourself

1. Make sure you have Storybook installed (globally):

   $ npm i -g @storybook/cli

2. Run npm run storybook

3. Go to http://localhost:9001 to see all examples

Click on 'Show info' to see additional implementation details such as supported prop types and their definitions.

Configuration

<Orizzonte /> component

<Group /> component

Groups contain one or more filters for which it make sense to be shown together. Each group has its own name and can be provided with a description.

Filters

A filter is responsible for controlling the value of a particular field in the query object. Every filter should be included as part of a group. Orizzonte comes with the following filter types:

<Choices /> filter

A series of inline checkboxes (multiple selections) or radios (single selection). Each Choices filter can have multiple options.

Option properties

Each option is represented by an object that can have the following properties. All possible options are provided as an array of objects (collection).

<Dropdown /> filter

A more advanced dropdown select with support for filtering options and select all. Facet counts for individual options are supported.

<FullText /> filter

A single or multi line full text field

<Select /> filter

A simple single-select filter (uses browser <select /> element)

<Toggle /> filter

A toggle switch button (affects single value)

Theming

All customizable variables defaults are found in src/scss/variables.scss. To override any variable, don't import the compiled distribution CSS that comes with the package but instead, import the Sass source in your project's source and redeclare the variables you want before that statement. For example:

// Custom variable values
$color-a: blue;
$color-b: red;

// Import Sass source
@import '~orizzonte/src/scss/Orizzonte.scss';

Following this method, the styles should be compiled as part of your own project's build process while taking in consideration the customizations applied.

Custom filters

Orizzonte comes with a set of default filters out of the box. If these do not meet your requirements, you can choose to create a filter of your own. Internally, Orizzonte clones each filter component and adds a few props, in addition to the props you configured, that are used to read and update filter values. Any other filter interactivity should be managed within the filter component itself.

• fieldName This prop is required to be defined and will be used as the field name (key) for this filter in the query object (if a value is set). It should only be of type PropTypes.string.

• value The current filter value is provided through the value-prop and is derived directly from the current query object. Make sure to define which types you expect to receive for this prop.

• onUpdate(newValue) The filter value can be updated by calling the onUpdate function and passing the new value as it's first and only argument. Note that the value in the query object will be exactly as passed through the onUpdate callback. If for any reason the component expects a value representation different from how it's stored in the query, you should use a transformer function to convert the internal format from and to the query format.

Tests

• Run tests: npm test
• Test a specific component: npm test -- <component>.spec.js
• Run a coverage report: npm test -- --coverage