@kaizen/components 0.0.0-canary-test-exports-20231114054615 → 0.0.0-canary-bundle-size-check-20231115005811

package/src/Filter/FilterBar/FilterBar.tsx

@@ -0,0 +1,54 @@
+import React from "react"
+import classnames from "classnames"
+import { OverrideClassName } from "~types/OverrideClassName"
+import {
+  FilterBarProvider,
+  FilterBarProviderProps,
+} from "./context/FilterBarContext"
+import {
+  FilterBarDatePicker,
+  FilterBarDateRangePicker,
+  FilterBarMultiSelect,
+  FilterBarSelect,
+} from "./subcomponents"
+import { AddFiltersMenu } from "./subcomponents/AddFiltersMenu"
+import { ClearAllButton } from "./subcomponents/ClearAllButton"
+import { FiltersValues } from "./types"
+import styles from "./FilterBar.module.scss"
+
+export type FilterBarProps<ValuesMap extends FiltersValues> = OverrideClassName<
+  Omit<FilterBarProviderProps<ValuesMap>, "children">
+>
+
+export const FilterBar = <ValuesMap extends FiltersValues>({
+  filters,
+  classNameOverride,
+  ...providerProps
+}: FilterBarProps<ValuesMap>): JSX.Element => (
+  <FilterBarProvider<ValuesMap> filters={filters} {...providerProps}>
+    {(activeFilters): JSX.Element => (
+      <div className={classnames(styles.filterBar, classNameOverride)}>
+        <div className={styles.filtersContainer}>
+          {Object.values(activeFilters).map(({ id, Component }) => (
+            // `id` will always be `string`, but keyof ValuesMap transformed it
+            <React.Fragment key={id as string}>
+              {React.cloneElement(Component, { id })}
+            </React.Fragment>
+          ))}
+          <AddFiltersMenu />
+        </div>
+
+        <div>
+          <ClearAllButton />
+        </div>
+      </div>
+    )}
+  </FilterBarProvider>
+)
+
+FilterBar.displayName = "FilterBar"
+
+FilterBar.DatePicker = FilterBarDatePicker
+FilterBar.DateRangePicker = FilterBarDateRangePicker
+FilterBar.MultiSelect = FilterBarMultiSelect
+FilterBar.Select = FilterBarSelect

package/src/Filter/FilterBar/_docs/FilterBar.mdx

@@ -0,0 +1,388 @@
+import { Controls, Meta } from "@storybook/blocks"
+import { ResourceLinks, KaioNotification, Installation, NoClipCanvas } from "~storybook/components"
+import { LinkTo } from "~storybook/components/LinkTo"
+import * as FilterBarStories from "./FilterBar.stories"
+
+<Meta of={FilterBarStories} />
+
+# Filter Bar
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/FilterBar"
+  className="!mb-8"
+/>
+
+<KaioNotification />
+
+<Installation
+  installCommand="yarn add @kaizen/components"
+  importStatement='import { FilterBar } from "@kaizen/components"'
+/>
+
+## Overview
+
+The Filter Bar is a collection of Filter components, used to filter data.
+
+The `Clear all` button clears all active values, and moves any removable filters into the `Add Filters` menu.
+
+This example showcases a minimal implementation of the FilterBar.
+
+<NoClipCanvas of={FilterBarStories.BasicImplementation} />
+
+## API
+
+<Controls of={FilterBarStories.BasicImplementation} />
+
+### `FilterBar<ValuesMap>` (generic)
+
+FilterBar accepts a TypeScript generic where you can outline the shape of the expected value types for each filter.
+
+We also provide a `Filters` type which can accept the same generic to provide improved type safety.
+
+`ValuesMap` should be in the shape of `{ [filterId]: filterValueType }`.
+
+```tsx
+import { FilterBar, Filters } from "@kaizen/components"
+
+type ValuesMap = {
+  filterId1: string
+  filterId2: number
+}
+
+const [values, setValues] = useState<Partial<ValuesMap>>({
+  filterId1: "default-value"
+})
+
+const filters = [
+  { id: "filterId1", ...rest },
+  { id: "filterId2", ...rest },
+] satisfies Filters<ValuesMap>
+
+return (
+  <FilterBar<ValuesMap>
+    filters={filters}
+    values={values}
+    onValuesChange={setValues}
+  />
+)
+```
+
+### `filters`
+
+The `filters` prop is an array of attributes used to create the list of filters.
+
+#### Usage
+
+We provide a `Filters<ValuesMap>` type you can use for improved type safety.
+
+```tsx
+import { FilterBar, Filters, DateRange, FilterMultiSelect } from "@kaizen/components"
+
+type ValuesMap = {
+  filterId1: string
+  filterId2: string[]
+  filterId3: DateRange
+}
+
+const filters = [
+  {
+    id: "filterId1",
+    name: "Filter 1",
+    Component: <FilterBar.Select {...props} />,
+  },
+  {
+    id: "filterId2",
+    name: "Filter 2",
+    Component: (
+      <FilterBar.MultiSelect {...props}>
+        {/* Compose your structure using subcomponents of FilterMultiSelect */}
+        {() => <FilterMultiSelect.ListBox {...props} />}
+      </FilterBar.MultiSelect>
+    ),
+  },
+  {
+    id: "filterId3",
+    name: "Filter 3",
+    Component: <FilterBar.DateRangePicker {...props} />,
+    isRemovable: true,
+    isUsableWhen: state => state.filterId1.value !== undefined
+  },
+] satisfies Filters<ValuesMap>
+```
+
+#### Filter attributes
+
+Each filter has the following attributes:
+
+- [`id: string`](#id-string)
+- [`name: string`](#name-string)
+- [`Component: JSX.Element`](#component-jsxelement)
+- [`isRemovable?: boolean`](#isremovable-boolean)
+- [`isUsableWhen?: (state: FiltersState<ValuesMap>) => boolean`](#isusablewhen-state-filtersstatevaluesmap--boolean)
+
+##### `id: string`
+
+A unique id for the filter.
+
+##### `name: string`
+
+The name used to label the filter, shown in the trigger button.
+
+##### `Component: JSX.Element`
+
+This attribute must be a Filter component or a custom component consuming the FilterBarContext.
+
+Provided Filter components are built on top of their base component, and have the
+`id`, `label`, `renderTrigger`, `isOpen`, `setIsOpen`, and `value` (or similar) props omitted as they are filled in for you.
+
+If the component comes with an `onChange` (or similar) prop, it will be made optional and it can be used for additional actions (eg. adding analytics).
+
+Available Filter components:
+- `<FilterBar.DatePicker>` - extends <LinkTo pageId="components-filter-date-picker">FilterDatePicker</LinkTo>
+  - `selectedDate` is omitted
+  - `onDateChange` is now optional
+  - `locale` is now optional (defaults to `"en-AU"`)
+- `<FilterBar.DateRangePicker>` - extends <LinkTo pageId="components-filter-date-range-picker">FilterDateRangePicker</LinkTo>
+  - `selectedRange` is omitted
+  - `onRangeChange` is now optional
+  - `locale` is now optional (defaults to `"en-AU"`)
+- `<FilterBar.MultiSelect>` - extends <LinkTo pageId="components-filter-multi-select">FilterMultiSelect</LinkTo>
+  - `selectedKeys` is omitted
+  - `onSelectionChange` remains available as optional
+  - **Note:** To use the subcomponents, import `FilterMultiSelect` from `@kaizen/components` (not `@kaizen/select`)
+- `<FilterBar.Select>` - extends <LinkTo pageId="components-filter-select">FilterSelect</LinkTo>
+  - `selectedKey` is omitted
+  - `onSelectionChange` remains available as optional
+  - **Note:** To use the subcomponents, import `FilterSelect` from `@kaizen/components` (not `@kaizen/select`)
+
+##### `isRemovable?: boolean`
+
+When this attribute is applied, the Filter will become removable (a remove button will be attached to the trigger button),
+and its value will be cleared upon removal.
+
+Filters with this attribute will be automatically put into the `Add Filter` menu on first render,
+unless there is a default value provided, of which it will be in the active filters after the non-removable filters.
+
+When removed from the active filters, the filter will be added to the `Add Filter` menu options.
+
+##### `isUsableWhen?: (state: FiltersState<ValuesMap>) => boolean`
+
+Note: _Usable_ refers to a filter showing in either the Active Filters or as an option in the Add Filters menu.
+
+Use this attribute to apply a condition to a filter based on the state of another filter.
+
+For example, if you want `Milk` to only be _Usable_ when `Coffee` is `"latte"`:
+
+```tsx
+type ValuesMap = {
+  coffee: string
+  milk: string
+}
+
+const filters = [
+  {
+    id: "coffee",
+    name: "Coffee",
+    Component: <FilterBar.Select items={[
+      { value: "long-black", label: "Long Black" },
+      { value: "latte", label: "Latte" },
+    ]} />,
+  },
+  {
+    id: "milk",
+    name: "Milk",
+    Component: <FilterBar.Select {...props} />,
+    isUsableWhen: state => state.coffee.value === "latte",
+  },
+] satisfies Filters<ValuesMap>
+```
+
+The `state` arg will provide you with the following attributes for all the filters (mapped to the keys of the `ValuesMap`):
+```
+id: keyof ValuesMap
+name: string
+value?: ValueMap[keyof ValuesMap]
+isActive: boolean
+```
+
+When a dependent filter has not met its condition (not _Usable_):
+- it will be removed from the FilterBar
+- if it has a value, the value will be cleared
+
+If this attribute is not defined, the filter will default to be _Usable_.
+
+### `values`
+
+A key-value pair of currently active values.
+
+The `values` prop should be in the shape of `{ [filterId]: filterValueType }` (matching `ValuesMap`).
+
+This is instantiated by the consumer to allow for updates from external events (eg. using url params).
+
+```tsx
+type ValuesMap = {
+  filterId1: string
+  filterId2: number
+}
+
+// @note: Unless you are providing a default value for all the filters,
+// you will want to wrap it in Partial.
+const [values, setValues] = useState<Partial<ValuesMap>>({
+  filterId1: "default-value"
+})
+
+return (
+  <FilterBar<ValuesMap> values={values} {...rest} />
+)
+```
+
+### `onValuesChange`
+
+A callback (`(values: Partial<ValuesMap>) => void`) for when the active `values` change.
+
+<NoClipCanvas of={FilterBarStories.OnValuesChange} />
+
+## Examples
+
+### Dependent filters
+
+Dependent filters are filters which are not able to be used by the end user until a certain condition has been met.
+Filters that do not meet their condition will not be shown amongst the Active Filters, nor in the Add Filters menu.
+
+See [filter attribute `isUsableWhen`](#isusablewhen-state-filtersstatevaluesmap--boolean) for api.
+
+This example shows the following dependencies:
+- **Milk** is only usable when **Coffee** _is Latte_
+  - `isUsableWhen: state => state.coffee.value === "latte"`
+  - An initial value of _Full Cream_ is passed in, but immediately cleared
+    as (on load) **Coffee** does not have an initial value
+- **Syrup** is only usable when **Milk** _has a value_ AND **Sugar** _is not active_
+  - `isUsableWhen: state => state.milk.value !== undefined && !state.sugar.isActive`
+  - This filter is removable, so it will start in the `Add Filters` menu
+- **Sugar** is only usable when **Milk** _has a value_ AND **Syrup** _is not active_
+  - `isUsableWhen: state => state.milk.value !== undefined && !state.syrup.isActive`
+  - This filter is removable, so it will start in the `Add Filters` menu
+- **Ice** is only available when **Coffee** _has a value_
+  - `isUsableWhen: state => state.coffee.value !== undefined`
+
+<NoClipCanvas of={FilterBarStories.DependentFilter} />
+
+### Dependent (Multi)Select options
+
+A Select or MultiSelect's options may change depending on another filter's value.
+
+To do this, the dependent filter must be made into a custom component
+which calls `getFilterState` or `getActiveFilterValues` from `useFilterBarContext`.
+It must also either have an optional `id` prop (`id?: string`) (filled in by `<FilterBar>`),
+or a matching `id` from the filter config must be provided to the rendered component.
+
+```tsx
+type Values = {
+  source: string
+  dependent: string
+}
+
+/**
+ * Explicit id
+ * No props required as you put the string directly into the Filter component
+ * Using `getFilterState` as dependency source is known
+ */
+const ExampleDependentFilter = () => {
+  const { getFilterState } = useFilterBarContext<Values["dependent"], Values>()
+  const sourceFilter = getFilterState("source")
+  const items = retrieveItems(sourceFilter.value)
+  return (<FilterBar.Select<Option> id="dependent" items={items} />)
+}
+
+/**
+ * Optional id prop
+ * A simple example if you want to make a more reusable filter
+ * Using `getActiveFilterValues` as dependency source is unknown
+ */
+const ExampleDependentFilter = (props: {
+  id?: keyof Values
+  retrieveItemsCallback: (filterValue) => SelectOption[]
+}) => {
+  const { getActiveFilterValues } = useFilterBarContext<Values[Id], Values>()
+  const activeValues = getActiveFilterValues()
+  const items = props.retrieveItemsCallback(activeValues)
+  return (<FilterBar.Select<Option> id={props.id} items={items} />)
+}
+
+const CustomFilterBar = () => {
+  const filters = [
+    { id: "source", ...rest },
+    { id: "dependent", Component: <ExampleDependentFilter />, ...rest },
+  ] satisfies Filters<Values>
+
+  return <FilterBar<Values> filters={filters} {...rest} />
+}
+```
+
+Values of dependent filters will be cleared if the option no longer exists.
+
+The following example shows `Person` (multi-select with a 3 second loading time) and
+`Room` (single select) re-populating with different options based on the values selected in `Role`.
+
+<NoClipCanvas of={FilterBarStories.SiblingValueDependentFilter} />
+
+### Update values via external event
+
+The api allows you to update the values of the FilterBar via an external event (eg. updating url params).
+
+Simply update the value passed into the `values` prop.
+
+Out of the box, we do not make assumptions about your state management tool, so you will need to encode/decode
+the types to match the expected format of your chosen query param library.
+
+The following example uses the
+<a href="https://www.npmjs.com/package/serialize-query-params">serialize-query-params</a>
+and <a href="https://www.npmjs.com/package/query-string">query-string</a>
+packages.
+
+<NoClipCanvas of={FilterBarStories.ExternalEventValuesUpdate} />
+
+### Open a filter through selecting a value from another filter
+
+There may be a situation where you want to open a filter based on selecting a value from another filter.
+
+To do so, call the `openFilter` function from `useFilterBarContext` in your event handler
+(you will need to create a custom component wrapping the Filter to access the context).
+
+**Note:**
+If you have a similar situation to below where _Custom Range_ appears later in the list than _Cycle_
+**and** it opens upon selecting a value from _Cycle_, we recommend you combine your implementation with an
+`isUsableWhen`, as the positioning calculation for _Custom Range_'s popover happens before the
+re-render of the Filter Buttons and _Cycle_'s button width will increase from having a selected value.
+
+```tsx
+type Values = {
+  cycle: string
+  customRange: DateRange
+}
+
+const CycleFilter = () => {
+  const { openFilter } = useFilterBarContext<Values["cycle"], Values>()
+
+  return (
+    <FilterBar.Select
+      id="cycle"
+      items={[{ value: "custom", label: "Custom Range" }]}
+      onSelectionChange={key => {
+        if (key === "custom") openFilter("customRange")
+      }}
+    />
+  )
+}
+
+const CustomFilterBar = () => {
+  const filters = [
+    { id: "cycle", Component: <CycleFilter />, ...rest },
+    { id: "customRange", isUsableWhen: state => state.cycle.value === "custom", ...rest },
+  ] satisfies Filters<Values>
+
+  return <FilterBar<Values> filters={filters} {...rest} />
+}
+```
+
+<NoClipCanvas of={FilterBarStories.ExternalEventOpenFilter} />

package/src/Filter/FilterBar/_docs/FilterBar.stickersheet.stories.tsx

@@ -0,0 +1,194 @@
+import React, { useState } from "react"
+import { Meta } from "@storybook/react"
+import {
+  StickerSheet,
+  StickerSheetStory,
+} from "~storybook/components/StickerSheet"
+import { FilterBar, Filters } from "../index"
+
+export default {
+  title: "Components/Filter Bar",
+  parameters: {
+    chromatic: { disable: false },
+    controls: { disable: true },
+  },
+} satisfies Meta
+
+type Values = {
+  flavour: string
+  topping: string
+  sugarLevel: number
+  drank: Date
+}
+
+const filters = [
+  {
+    id: "flavour",
+    name: "Flavour",
+    Component: (
+      <FilterBar.Select
+        items={[
+          { value: "jasmine-milk-tea", label: "Jasmine Milk Tea" },
+          { value: "honey-milk-tea", label: "Honey Milk Tea" },
+          { value: "lychee-green-tea", label: "Lychee Green Tea" },
+        ]}
+      />
+    ),
+  },
+  {
+    id: "topping",
+    name: "Topping",
+    Component: (
+      <FilterBar.Select
+        items={[
+          { value: "none", label: "None" },
+          { value: "pearls", label: "Pearls" },
+          { value: "fruit-jelly", label: "Fruit Jelly" },
+        ]}
+      />
+    ),
+  },
+  {
+    id: "sugarLevel",
+    name: "Sugar Level",
+    Component: (
+      <FilterBar.Select
+        items={[
+          { value: 0, label: "0%" },
+          { value: 50, label: "50%" },
+          { value: 100, label: "100%" },
+        ]}
+      />
+    ),
+  },
+  {
+    id: "drank",
+    name: "Drank",
+    Component: <FilterBar.DatePicker />,
+  },
+] satisfies Filters<Values>
+
+type ValuesRemovable = {
+  flavour: string
+  topping: string
+}
+
+const removableFilters = [
+  {
+    id: "flavour",
+    name: "Flavour",
+    Component: (
+      <FilterBar.Select
+        items={[
+          { value: "jasmine-milk-tea", label: "Jasmine Milk Tea" },
+          { value: "honey-milk-tea", label: "Honey Milk Tea" },
+          { value: "lychee-green-tea", label: "Lychee Green Tea" },
+        ]}
+      />
+    ),
+  },
+  {
+    id: "topping",
+    name: "Topping",
+    Component: (
+      <FilterBar.Select
+        items={[
+          { value: "none", label: "None" },
+          { value: "pearls", label: "Pearls" },
+          { value: "fruit-jelly", label: "Fruit Jelly" },
+        ]}
+      />
+    ),
+    isRemovable: true,
+  },
+] satisfies Filters<ValuesRemovable>
+
+const StickerSheetTemplate: StickerSheetStory = {
+  render: () => {
+    const [activeValues, setActiveValues] = useState<Partial<Values>>({
+      flavour: "jasmine-milk-tea",
+    })
+    const [activeValuesOverflow, setActiveValuesOverflow] = useState<
+      Partial<Values>
+    >({
+      flavour: "jasmine-milk-tea",
+      sugarLevel: 50,
+    })
+    const [valuesRemovableAllActive, setValuesRemovableAllActive] = useState<
+      Partial<ValuesRemovable>
+    >({ topping: "pearls" })
+    const [valuesRemovablePartialActive, setValuesRemovablePartialActive] =
+      useState<Partial<ValuesRemovable>>({})
+
+    return (
+      <>
+        <StickerSheet heading="Filter Bar" style={{ width: "100%" }}>
+          <StickerSheet.Body>
+            <StickerSheet.Row>
+              <FilterBar<Values>
+                filters={filters}
+                values={activeValues}
+                onValuesChange={setActiveValues}
+              />
+            </StickerSheet.Row>
+          </StickerSheet.Body>
+        </StickerSheet>
+
+        <StickerSheet
+          heading="Overflow (container 500px)"
+          style={{ width: "100%" }}
+        >
+          <StickerSheet.Body>
+            <StickerSheet.Row>
+              <div style={{ maxWidth: "500px" }}>
+                <FilterBar<Values>
+                  filters={filters}
+                  values={activeValuesOverflow}
+                  onValuesChange={setActiveValuesOverflow}
+                />
+              </div>
+            </StickerSheet.Row>
+          </StickerSheet.Body>
+        </StickerSheet>
+
+        <StickerSheet heading="Removable; All active" style={{ width: "100%" }}>
+          <StickerSheet.Body>
+            <StickerSheet.Row>
+              <FilterBar<ValuesRemovable>
+                filters={removableFilters}
+                values={valuesRemovableAllActive}
+                onValuesChange={setValuesRemovableAllActive}
+              />
+            </StickerSheet.Row>
+          </StickerSheet.Body>
+        </StickerSheet>
+
+        <StickerSheet
+          heading="Removable; Partial active"
+          style={{ width: "100%" }}
+        >
+          <StickerSheet.Body>
+            <StickerSheet.Row>
+              <FilterBar<ValuesRemovable>
+                filters={removableFilters}
+                values={valuesRemovablePartialActive}
+                onValuesChange={setValuesRemovablePartialActive}
+              />
+            </StickerSheet.Row>
+          </StickerSheet.Body>
+        </StickerSheet>
+      </>
+    )
+  },
+}
+
+export const StickerSheetDefault: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: "Sticker Sheet (Default)",
+}
+
+export const StickerSheetRTL: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: "Sticker Sheet (RTL)",
+  parameters: { textDirection: "rtl" },
+}