Naive Puppets Marching

    orizzonte

    0.3.7 • Public • Published

    Orizzonte

    React components for a horizontal, filtered search UI

    npm version Build Status Coverage Status David gzip size license

    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

    Prop Type Required Description
    addBtnLabel string no Custom label for add-button
    autoExpandOnGroupAdd boolean no Makes a newly added group auto expand
    autoHideControls boolean no If true, add, clear and save buttons will hide automatically
    autoHideTimeout number no Custom timeout interval for auto-hiding controls
    className string no Custom additional class name for the top-level element
    clearAllLabel string no Custom label for the button to clear all of the query. onClear prop needs to be defined for the button to show.
    clearedQuerySnapshot object no Snapshot of initial query state. If set, this will be used to determine if the query diverged from blank-slate.
    collapseGroupOnClickOutside boolean no Whether the group should collapse when the user clicks outside of it. Changes will not be applied to the query.
    groupToggleIcon node no Toggle indicator icon to be shown in groups
    groupTopLabels boolean no Whether the group label should be shown at the top if some of it's filters have selected values
    hideAddOnAllGroupsIncluded boolean no Hide the add-button when there are no more groups to add
    dispatchOnFilterChange boolean no If true, the query object will be updated right after any filter change
    maxGroups number no Maximum number of groups to be added
    onChange function yes Callback function that triggers when the final query object is updated
    onClear function no Callback function for clearing all of the query. A snapshot of the cleared query state is given as argument.
    onGroupAdd function no Callback function for when a new filter group is added
    onGroupRemove function no Callback function for when a filter group is removed
    onSave function no Callback function saving the current query object
    orientation ltr or rtl no Render groups and controls from left-to-right (ltr, default) or right-to-left (rtl)
    query object no The current query object
    saveLabel string no Custom label for the button to save the current query. onSave prop needs to be defined for the button to show.
    showGroupControlsOnMouseover boolean no Only show the group controls (remove, done) when hovering over the dropdown list
    style object no Custom inline styles for the top-level element

    <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.

    Prop Type Required Description
    className string no Custom additional class name for top-level component element
    mutuallyExclusiveFilters boolean or array no When true, only one filter can be selected for this group. When you want only specific filters to be mutually exclusive, you can provide an array of (two or more) field names.
    description string no A description for this group of filters
    doneBtnLabel string no Custom label for Done-button
    hideClear boolean no Hides the clear button in the dropdown
    hideDone boolean no Hides the done button in the dropdown
    hideRemove boolean no Hides the button to remove this group
    included boolean no If the group should be present in the bar
    label string yes Label for this group
    orientation left or right no Default orientation of the group dropdown list
    removeBtnLabel string no Custom label for Remove-button.
    showControlsOnMouseover boolean no Only show group controls (remove, done) when hovering over the dropdown list element
    style object no Custom inline styles for top-level component element

    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:

    Filter Description
    Choices A series of inline checkboxes or radios
    Dropdown A more advanced dropdown select with support for filtering options and select all
    FullText A single or multi line full text field
    Select A simple single-select filter (uses browser <select /> element)
    Toggle A toggle switch filter for toggling a single-value field on and off

    <Choices /> filter

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

    Prop Type Required Description
    fieldName string yes Field name for this filter, to be used in composed query
    information string no Help text for this filter, to be shown on mouseover
    label string no Label for this filter
    multiple boolean no Whether to show checkboxes (true) or radios (false)
    noPreferenceLabel string no Label to show if you want to include a 'no preference' option. Only available for radio groups.
    options array yes Collection of possible options for this group of choices. Each option must at least have a value.
    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).

    Prop Type Description
    option.disabled bool Field name for this filter, to be used in composed query
    option.facetCount string or number Help text for this filter, to be shown on mouseover
    option.label string Label for this option. If no label is defined, option.value will be used instead.
    option.value string or number Selected value for this option (required)

    <Dropdown /> filter

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

    Prop Type Required Description
    fieldName string yes Field name for this filter, to be used in composed query
    information string no Help text for this filter, to be shown on mouseover
    disabled boolean no Disables the dropdown
    filter object no Filter dropdown options and highlight matches
    filter.enabled boolean yes If filtering options should be enabled
    filter.matchCase boolean no If the dropdown filter is case sensitive
    filter.matchDiacritics boolean no If the dropdown filter should strictly match diacritics
    filter.matchPosition start or end no Whether to match at any position in the string or from the start
    label string no Label for this filter
    multiple boolean no Allows selecting multiple options
    notSetLabel string no Label to shown when no options are selected
    options array yes Collection of selectable options (property value is required, label and disabled are optional). To create a group of options, use value for the group label and add an array of grouped options as children.
    remote object no Remote API to fetch dropdown options from
    remote.data object no Data object to use as request payload
    remote.endpoint string yes Remote endpoint URI
    remote.loadingText string no Text to show while loading data
    remote.searchParam string yes Query parameter to apply the filter value to
    remote.transformer function no Function for transforming response data before consuming it
    remote.requestMethod string no Request method (GET by default)
    selectAll boolean no Whether to include a select all option on multiselects. This is not supported when remote source is configured.
    selectAllCount boolean no Show total option count (excl. disabled options) in select all label
    selectAllLabel string no What label to show for the select all option
    selectedLabel string or function no Transforming function or placeholder for group label

    <FullText /> filter

    A single or multi line full text field

    Prop Type Required Description
    autoFocus boolean no If the input should automatically receive focus when group is expanded
    disabled boolean no Disables the input field
    dispatchTimeout number no Custom debounce timeout before dispatching the new value to the query object
    fieldName string yes Field name for this filter, to be used in composed query
    information string no Help text for this filter, to be shown on mouseover
    label string no Label for this filter section
    maxHeight number no Maximum textarea height (only applicable in multiline mode)
    maxWidth number no Maximum textarea width (only applicable in multiline mode)
    multiline boolean no Whether to render a textarea (true) or input field (false)
    placeholder string no Placeholder text for the input field
    selectedLabel string or function no Transforming function or placeholder for group label
    validateInput function no Function to validate input, should return true (valid) or false (invalid)

    <Select /> filter

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

    Prop Type Required Description
    disabled boolean no Disables the input field
    fieldName string yes Field name for this filter, to be used in composed query
    information string no Help text for this filter, to be shown on mouseover
    label string no Label for this filter section
    notSetLabel string no Which label the first (empty) option should have in case the select can be empty
    options array yes Collection of selectable options (property value is required, label and disabled are optional). To create a group of options, use value for the group label and add an array of grouped options as children.
    placeholder string no Placeholder text for the input field
    selectedLabel string or function no Transforming function or placeholder for group label

    <Toggle /> filter

    A toggle switch button (affects single value)

    Prop Type Required Description
    disabled boolean no Disables the toggle switch
    fieldName string yes Field name for this filter, to be used in composed query
    information string no Help text for this filter, to be shown on mouseover
    label string no Label for this filter
    option object yes Option that can be toggled (property value is required, label and disabled are optional). A toggle can only take one option. When switched on, the field will be included in the query with the option 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

    Install

    npm i orizzonte

    DownloadsWeekly Downloads

    3

    Version

    0.3.7

    License

    MIT

    Unpacked Size

    454 kB

    Total Files

    91

    Last publish

    Collaborators

    • carlobernardini