-
Notifications
You must be signed in to change notification settings - Fork 49
[Docs] Filter Bar component #3396
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: dchyun/filter-bar-component
Are you sure you want to change the base?
Changes from all commits
e3f41f3
ad2b057
967ffb5
9bfe9dc
362e4a8
6fb1b7b
d02ef57
c339274
fdf00d1
8322651
bd7cbed
61d6ac0
92bad51
10c9dfd
7c734b1
9ab4fa1
2d57a74
3f5c3c3
3d7a4de
64d27e1
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| /** | ||
| * Copyright (c) HashiCorp, Inc. | ||
| * SPDX-License-Identifier: MPL-2.0 | ||
| */ | ||
|
|
||
| import Component from '@glimmer/component'; | ||
| import { tracked } from '@glimmer/tracking'; | ||
|
|
||
| export default class Index extends Component { | ||
| @tracked filters = {}; | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| --- | ||
| title: Filter Bar | ||
| description: A composition of HDS components to support filtering a data set. | ||
| caption: A composition of HDS components to support filtering a data set. | ||
| links: | ||
| figma: >- | ||
| https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?node-id=67385-76599&t=w8xQlWxzH7bwXLe2-1 | ||
| github: >- | ||
| https://github.com/hashicorp/design-system/tree/main/packages/components/src/components/hds/filter-bar | ||
| related: | ||
| - components/table/advanced-table | ||
| - components/table/table | ||
| - patterns/filter-patterns | ||
| previewImage: assets/illustrations/components/filter-bar.jpg | ||
| navigation: | ||
| keywords: | ||
| - filtering | ||
| status: | ||
| added: 5.2.0 | ||
| --- | ||
|
|
||
| <section data-tab="Guidelines"> | ||
| @include "partials/guidelines/guidelines.md" | ||
| </section> | ||
|
|
||
| <section data-tab="Code"> | ||
| @include "partials/code/how-to-use.md" | ||
| @include "partials/code/component-api.md" | ||
| </section> | ||
|
|
||
| <section data-tab="Specifications"> | ||
| @include "partials/specifications/anatomy.md" | ||
| @include "partials/specifications/states.md" | ||
| </section> | ||
|
|
||
| <section data-tab="Accessibility"> | ||
| @include "partials/accessibility/accessibility.md" | ||
| </section> |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| ## Conformance Rating | ||
|
|
||
| ## Applicable WCAG Success Criteria | ||
|
|
||
| This section is for reference only. This component intends to conform to the following WCAG Success Criteria: | ||
|
|
||
| <Doc::WcagList @criteriaList={{array "1.3.1" }} /> | ||
|
|
||
| --- | ||
|
|
||
| <Doc::A11ySupport /> |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| ## Component API | ||
|
|
||
| ### FilterBar | ||
|
|
||
| <Doc::ComponentApi as |C|> | ||
| <C.Property @name="...attributes"> | ||
| This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). | ||
| </C.Property> | ||
| </Doc::ComponentApi> | ||
|
|
||
| ### Contextual components |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| ## How to use this component | ||
|
|
||
| ```handlebars | ||
| <Hds::FilterBar @filters={{this.filters}} as |F|> | ||
| <F.Dropdown as |D|> | ||
| <D.FilterGroup | ||
| @key="name" | ||
| @text="Name" | ||
| @type="multi-select" | ||
| as |F| | ||
| > | ||
| <F.Checkbox @value="project-1" @label="Project 1" /> | ||
| <F.Checkbox @value="project-2" @label="Project 2" /> | ||
| <F.Checkbox @value="project-3" @label="Project 3" /> | ||
| </D.FilterGroup> | ||
| <D.FilterGroup | ||
| @key="version" | ||
| @text="Version" | ||
| @type="single-select" | ||
| as |F| | ||
| > | ||
| <F.Checkbox @value="1.0" @label="1.0" /> | ||
| <F.Checkbox @value="2.0" @label="2.0" /> | ||
| <F.Checkbox @value="3.0" @label="3.0" /> | ||
| </D.FilterGroup> | ||
| </F.Dropdown> | ||
| </Hds::FilterBar> | ||
| ``` |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,186 @@ | ||
| The Filter Bar is used to apply and display filters to a data set. It is most often used in conjunction with the [Advanced Table](/components/table/advanced-table), but is flexible enough to support different data sets and rendering methods such as in a list or grid of cards. | ||
|
|
||
| The Filter Bar comes paired with a complex dropdown menu that displays available filter parameters (a parameter is often the equivalent of a column in a table), values within each parameter, support for numerical/date/time values, ranges of values, and actions to apply and clear filters from the data set. | ||
|
|
||
| !!! Callout | ||
|
|
||
| While the Filter Bar underwent rigorous research and testing, this component is relatively complex. If specific functionality or the filtering methods don't meet your needs, please [contact the Design Systems Team](/about/support) so we can provide support. | ||
| !!! | ||
|
|
||
| ## Usage | ||
|
|
||
| ### When to use | ||
|
|
||
| - When displaying relevant filters and filters that have been applied to a data set. | ||
| - For common filter methods like multi-selection, single selection, numbers, dates, and times. | ||
| - As a direct replacement for the HDS [Filter patterns](/patterns/filter-patterns) guidance. | ||
|
|
||
| ### When not to use | ||
|
|
||
| - For complex query builder features. | ||
|
|
||
| ## Overlap with the Filter patterns guidance <!--Consider a different headline --> | ||
|
|
||
| The Filter Bar component is a successor to the [Filter patterns](/patterns/filter-patterns) guidance and supports the vast majority of filtering experiences within HashiCorp applications out of the box. New experiences should use the Filter Bar by default instead of the adhering to the pattern guidance, while already delivered features should consider migrating to the Filter Bar component. | ||
|
|
||
| ## Type | ||
|
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [Suggestion] Talking of "types" for this is kind of a misalignment with the code side. On the code side there is no property to change the filter bar from looking like standalone or attached. It really is just if the filter bar is used through the advanced table, or on its own. Maybe it would help to say the filter bar can either be used directly through components (ex: advanced table, table) or as its own individual component. And we could link out to the adv table filter docs. But if what you currently have more closely aligns to how the component is in figma then all good to leave it as is.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Good callout, however, I think it's useful to include this for designers because that matches the property in Figma. I've added a callout block noting this difference, take a look to see if the language makes sense. |
||
|
|
||
| !!! Callout | ||
|
|
||
| The `type` property is available in Figma only. The Ember component can be passed to the [Advanced Table](#add-a-link-when-ready) as a contextual component, or used on it's own in which case the styling will adjust accordingly. | ||
| !!! | ||
|
|
||
| The Filter Bar supports two visual presentations, `attached` and `standalone`, to be used in different contexts and with different types of data sets. | ||
|
|
||
| ### Attached | ||
|
|
||
| Use the `attached` variant with the [Advanced Table](/components/table/advanced-table) and standard [Table](/components/table/table). | ||
|
|
||
|  | ||
|
|
||
| ### Standalone | ||
|
|
||
| Use the `standalone` variant when a data set is rendered in formats other than a table, e.g., a list or array of cards. | ||
|
|
||
|  | ||
|
|
||
| ## Expand & collapse | ||
|
|
||
| The Filter Bar supports expanding and collapsing the applied filters section to help simplify the UI around the data set and bring focus to the data or content. This is especially helpful when many filters are applied or the data set is very complex. | ||
|
|
||
|  | ||
|
|
||
| When no filters are applied, the Filter Bar is collapsed by default and displays an empty state message when expanded. | ||
|
|
||
|  | ||
|
|
||
| When one or more filters are applied the Filter Bar is expanded by default. | ||
|
|
||
|  | ||
|
|
||
| ## Search | ||
|
|
||
| Use the search input in the Filter Bar to apply a broad text/string-based filter across the entire data set. | ||
|
|
||
|  | ||
|
|
||
| ## Bulk actions | ||
|
|
||
| The Filter Bar supports bulk actions corresponding with our recommendations for [multi-select](/patterns/table-multi-select) within a table, and can be used to perform actions across multiple results such as edit, delete, and different selection methods across the data set. | ||
|
|
||
|  | ||
|
|
||
| ## Generic content | ||
|
|
||
| If custom functionality is needed for manipulating the view or contents of the data set, a generic block is grouped with the bulk actions in the Filter Bar. We aren't prescriptive about what can be passed to this generic block, but it should generally be limited to additional actions (as [Buttons](/components/button)) and [Dropdowns](/components/dropdown) with multiple grouped actions. | ||
|
|
||
|  | ||
|
|
||
| ## Applied filters | ||
|
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [Suggestion] Would it make more sense to move this section below "applying filters"? That way the filter dropdown comes first which is what people use to apply filters and then after that we talk about how to view the filters you applied.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I thought about that as well, but part of me was also trying to somewhat create separate sections for the Filter Bar, and the Dropdown, which categorically this would land in the Filter Bar section. But this is a good point, I'll encourage others to chime in on whether the narrative makes sense. If we decide to more intentionally group things together that are kind of "dependencies" then there are other opportunities in the docs as well |
||
|
|
||
| Applied filters are represented by a [Tag](/components/tag) displaying the filter parameter (the category or column the filter corresponds to) and the filter value (corresponding with the specific cell content). | ||
|
|
||
|  | ||
|
|
||
| The text rendered within the Tag uses a standardized format depending on the type of filter and the method: | ||
|
|
||
| - Single and multiple selection filters group the parameter and value using a colon; e.g., "Region: AWS (us-east)". | ||
| - Numerical filters group the parameter and value with an operator symbol; e.g., "Modules > 50". | ||
| - Date and time filters group the parameter and value with natural language; e.g., "Creation time before 12:00 PM". | ||
|
|
||
|  | ||
|
|
||
| For a full list of supported operators visit the [specifications](/components/filter-bar?tab=specifications#value-input-operators) page. | ||
|
|
||
| Text within the Tag component will truncate at roughly 20 characters, about which more details can be found in the [Tag documentation](/components/tag?tab=code#truncation). | ||
|
|
||
| ### Custom applied filter text | ||
|
|
||
| If necessary, the default formatting within the Tag can be overidden with custom text. This can be useful if the label of the parameter is an irregular plural, if the parameter reads more naturally with certain punctuation or grammar, or for product-specific reasons. | ||
|
|
||
| <!-- @dylan could you help me out a bit with this? --> | ||
|
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [todo] Once I implement this on the dev side to not just be for custom filters we can add in some more specifics if we need to, but I think you covered a lot of it. Do we want to talk about custom filters at all? |
||
|
|
||
| ## Filter dropdown | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It would be helpful to have an image of the entire menu here so consumers can see the left and right panels
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Added a basic example |
||
|
|
||
| The Filter Dropdown is responsible for the selection and application of filters and is broken two "panels": | ||
|
|
||
| - The left panel displays the list of parameters (categories) that can be filtered upon. | ||
| - The right panel conditionally displays either a list of options, or a grouping of input fields when filtering by a numerical, date, or time value. | ||
|
|
||
|  | ||
|
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [Suggestion] Should we show / talk about the applied filters count on the tab somewhere in this image or elsewhere in this section?
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I've actually added this to the specs instead, which seems better suited. |
||
|
|
||
| Which filtering method to use depends on the data type and context. In the Figma component, select the `type` from the nested FilterValue component. In Ember, pass the filter type and method into the configuration. | ||
|
|
||
| ### Multi-selection | ||
|
|
||
| Multi-selection supports the selection of multiple values in a list of options and is the most common method of filtering. It is suited for categorical data like statuses and IDs, but can also be used more generally to filter by a handful of similar values. | ||
|
|
||
|  | ||
|
|
||
| ### Single-selection | ||
|
|
||
| Single selection supports a _mutually exclusive_ selection using radio buttons; e.g., the selection of a value where more than one selection will logically result in an empty state, therefore, only value can be selected. | ||
|
|
||
|  | ||
|
|
||
| ### Numbers, dates, times, and datetimes | ||
|
|
||
| Filtering by numerical values, dates, times, and datetimes is handled through the combination of an operator (greater than, less than, before, etc.) and an input field or grouping of input fields. This filtering method is best suited for range-based filtering; e.g., filtering by results relationally compared to the value or range of values. | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| For a full list of supported operators visit the [specifications](/components/filter-bar?tab=specifications#value-input-operators) page. | ||
|
|
||
| ### Custom filtering | ||
|
|
||
| If your filtering requirements extend beyond the methods supported directly by the component, the Filter Dropdown supports passing HDS components and custom elements to the values panel. | ||
|
|
||
|  | ||
|
|
||
| ### Search across filter values | ||
|
|
||
| Use the integrated search (`hasSearch`) in the values panel to allow users to search by string across all values within a selected parameter. While only relevant for single/multi selection, search can be useful if there are many filter values or if a unique naming convention is used to artificially group results together. | ||
|
|
||
|  | ||
|
|
||
| ## Applying Filters | ||
|
|
||
| Depending on how consumers would prefer to trigger the filtering on their data sets, the Filter Bar supports different methods of applying filters: | ||
|
|
||
| - **Per-filter:** selected filters are applied when the user confirms their selection with the "Apply filters" submit button in the Filters Dropdown. This is the most common method and generally requires a database or API call to update the data set with the corresponding filter parameters. | ||
| - **Live filtering:** filters are applied immediately upon selection. This method generally requires updating the data set on the client. | ||
|
|
||
| ## Clearing filters | ||
|
|
||
| Filters can be cleared either in bulk or individually from the Filter Bar or Dropdown. | ||
|
|
||
| ### Filter Bar | ||
|
|
||
| Clear all filters with the Button in the Filter Bar. | ||
|
|
||
|  | ||
|
|
||
| Clear filters individually via the dismiss button of the Tag. | ||
|
|
||
|  | ||
|
|
||
| ### Filter Dropdown | ||
|
|
||
| Clear all filters via the Button in the footer of the Dropdown. | ||
|
|
||
|  | ||
|
|
||
| Deselect all filter values within a parameter with the "Clear selection" Button, then confirm the changes with the "Apply filters" Button in the footer. | ||
|
|
||
|  | ||
|
|
||
| Clear filter input fields with the "Clear filter" Button, then apply the changes with the "Apply filters" Button in the footer. | ||
|
|
||
|  | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| ## Anatomy | ||
|
|
||
| ### Filter Bar | ||
|
|
||
|  | ||
|
|
||
| | Element | Usage | | ||
| |------------------|------------------------| | ||
| | Collapse/expand | Required; Toggles open and closed the applied filters. | | ||
| | Filter toggle button | Required; Toggles open and closed the Filter Dropdown. | | ||
| | Search | Optional; Searches based on string matching across the entire data set. | | ||
| | Generic content | Optional | | ||
| | Bulk actions | Optional; Supports performing bulk actions on the data set. | | ||
| | Applied Filters List | Required; Displays the filters that have been applied to the data set, or an empty state. | | ||
| | Applied Filter Tag | Required; Displays the filter as `Parameter: Value` within an HDS [Tag](/components/tag). | | ||
| | Clear All Filters | Required; Clears all of the applied filters, sets the Filter Bar and the data set back to their default state. | | ||
|
|
||
| ### Filter Dropdown | ||
|
|
||
| The Filter Dropdown anatomy is dependent on the filter method and is dependent on the filtering method: | ||
|
|
||
| - Selection: multi-selection using checkboxes or single selection using radios. | ||
| - Input: numerical, date, time, datetime values, or a range between a start and end value. | ||
|
|
||
|  | ||
|
|
||
| | Element | Usage | | ||
| |------------------|------------------------| | ||
| | Parameters list | Required; Displays all of the available filter parameters, generally corresponding with columns in a table. | | ||
| | Filter value(s) | Required; Displays available values within a parameter for selection, or allows the input of custom values. | | ||
| | Apply Filters action | Required if the filtering method is "per-filter". Applies the filters selected in either the values list or the values input. | | ||
| | Clear all filters action | Required; Clears the selection of filters across all parameters. | | ||
| | Selected filters count | Displays the number of values selected in a parameter. | | ||
|
|
||
| #### Filter value selection | ||
|
|
||
|  | ||
| <Doc::ImageCaption @text="This filter value selection anatomy is the same for single selection using radios." /> | ||
|
|
||
| | Element | Usage | | ||
| |------------------|------------------------| | ||
| | Search | Optional; Searches across available filter parameter values using string matching. | | ||
| | Clear selected values action | Required; De-selects all values in the list. | | ||
| | Value input | Required; Supports filtering on numbers, strings, dates, or times. | | ||
|
|
||
| #### Filter value input | ||
|
|
||
|  | ||
|
|
||
| | Element | Usage | | ||
| |------------------|------------------------| | ||
| | Operator selection | Requried; Allows the user to select how the filter is applied. | | ||
| | Value input | Required; Allows the user to input a value to filter upon such as a number, string, date, or time. | | ||
| | Clear filter | Required; Clears the filter operator and input fields. | | ||
|
|
||
| #### Filter value range input | ||
|
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [Question] Do we want to mention the generic / custom filter somewhere in here?
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Added some content for custom filtering both here in the specs, and in the guidelines. |
||
|
|
||
| When applying a filter value via an input, if `Between` is selected in the operator list, the input fields will be broken into a `start` value and `end` value. | ||
|
|
||
|  | ||
|
|
||
| | Element | Usage | | ||
| |------------------|------------------------| | ||
| | Operator selection | Required; Allows the user to select how the filter is applied. | | ||
| | Value range input | Required; Allows the user to input a start and end value to filter upon. | | ||
| | Clear filter fields action | Required; Clears the filter input field. | | ||
|
|
||
| #### Custom filtering | ||
|
|
||
| The Filter Dropdown supports custom filtering by passing elements to a generic yielded block. | ||
|
|
||
|  | ||
|
|
||
| ##### Value input operators | ||
|
|
||
| Available operators are dependent on the type of data being filtered upon, but are generally either numerical, or date/time based. | ||
|
|
||
|  | ||
|
|
||
| | Type | Options | | ||
| |------|-----------| | ||
| | Numerical | Less than (>), Less than or equal to (≤), Equal to (=), Not equal to (≠), Greater than or equal to (≥), Greater than (>), Between | | ||
| | Date and time | Before, Exactly, After, Between | | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| ## States | ||
|
|
||
| ### Parameter List Item | ||
|
|
||
|  |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,6 @@ | ||
| !!! Insight | ||
|
|
||
| In version [5.2.0](/whats-new/release-notes#520) the [Filter Bar](/components/filter-bar) component was released to support direct filtering with HDS components. While this documentation is still relevant for filtering experiences that have been built around this guidance, new filtering features and experiences should use the Filter Bar component instead, while already delivered features should consider migrating. | ||
| !!! | ||
|
|
||
| Filtering is used to limit the objects in a data set based on one or more parameters. It is commonly used in tandem with a [Table](/components/table/table) or [Advanced Table](/components/table/advanced-table), but the core concepts have a wide range of relevant use cases depending on the type of data set and the context within the application. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[todo] We could link this directly to the filter bar examples in the adv table docs once I create those.