@iress-oss/ids-mcp-server 5.15.0 → 6.0.0-alpha.0

package/generated/docs/components-filter-docs.md

@@ -6,6 +6,14 @@ Overview
 
 A filter allows you to pick one or more options from a list (that may be searchable) and is triggered by an activator button.
 
+* * *
+
+Updated
+
+**Recently updated**
+
+This component has been recently updated with new props. The props have been marked as beta. Please tell us if there are any issues.
+
 Filter
 
 None selected
@@ -45,6 +53,220 @@ Hide code
 
 Copy
 
+[](#props)Props
+---------------
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| debounceThreshold | 
+Time in milliseconds to wait for before performing result search. Only applies to searchable options (function).
+
+numberundefined
+
+
+
+ | 
+
+500
+
+ | Set object |
+| defaultValue | 
+
+Value of selected option for uncontrolled filter.
+
+LabelValueMeta | LabelValueMeta\[\] | undefined
+
+ | \- | Set object |
+| initialOptions | 
+
+Initial options data set, shown when the input is empty.
+
+LabelValueMeta\[\] | undefined
+
+ | \- | Set object |
+| inputProps | 
+
+Customise the searchable `IressInput` props for your needs.
+
+Pick<IressInputProps, "append" | "prepend" | "placeholder" | "clearable"> | undefined
+
+ | { clearable: true, prepend: <IressIcon name="search" />, } | Set object |
+| label\* | 
+
+Label to display in the activator button.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Filter"
+
+ |
+| limitDesktop | 
+
+Maximum number of results displayed on larger screen sizes (>= 768).
+
+numberundefined
+
+
+
+ | 
+
+12
+
+ | Set object |
+| limitMobile | 
+
+Maximum number of results displayed on mobile screen sizes (< 768).
+
+numberundefined
+
+
+
+ | 
+
+6
+
+ | Set object |
+| minSearchLength | 
+
+Minimum number of characters required before triggering async search. Only applies to searchable options (function). Below this threshold, no search will be triggered and no loading state will be shown.
+
+numberundefined
+
+
+
+ | 
+
+1
+
+ | Set object |
+| multiSelect | 
+
+Multi-select mode. When `true`, multiple options can be selected.
+
+booleanundefined
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Emitted when the value changes.
+
+((selected?: ControlledValue<LabelValueMeta, TMultiple> | undefined) => void) | undefined
+
+ | \- | \- |
+| onReset | 
+
+Emitted when the value is reset.
+
+(() => void) | undefined
+
+ | \- | \- |
+| options | 
+
+Options data set, shown when the input is not empty.
+
+LabelValueMeta\[\] | ((query: string) => Promise<LabelValueMeta\[\]>) | undefined
+
+ | \- | 
+
+RAW
+
+options : \[
+
+0 : {...} 2 keys
+
+1 : {...} 2 keys
+
+2 : {...} 2 keys
+
+3 : {...} 2 keys
+
+4 : {...} 2 keys
+
+\]
+
+
+
+
+
+ |
+| popoverProps | 
+
+Customise the IressPopover props for your needs.
+
+FilterPopoverPropsundefined
+
+
+
+ | { align: 'bottom-start' } | 
+
+RAW
+
+popoverProps : {
+
+container : {...} 0 keys
+
+}
+
+
+
+
+
+ |
+| ref | 
+
+ForwardedRef<FilterRef> | undefined
+
+ | \- | Set object |
+| searchable | 
+
+When `true` a search field is shown to search for specific filter option(s).
+
+booleanundefined
+
+
+
+ | \- | Set object |
+| searchNoResultsText | 
+
+Text to be displayed when no results are found from search. Ignored when `searchable` is `false`
+
+ReactNode
+
+
+
+ | \- | Set object |
+| selectedOptionsText | 
+
+Text displayed next to label when two or more options are selected.
+
+stringundefined
+
+
+
+ | {{numOptions}} selected | Set object |
+| value | 
+
+Value of selected option for controlled filter.
+
+LabelValueMeta | LabelValueMeta\[\] | undefined
+
+ | \- | Set object |
+| visibleResetButton | 
+
+When `true`, a reset button will be shown above the options. If provided a string, it will be used as the reset button label.
+
+stringbooleanundefined
+
+
+
+ | \- | Set object |
+
 [](#usage)Usage
 ---------------
 
@@ -77,11 +299,7 @@ Reset filters
 System users
 | User | Name | Status | Location | Gender |
 | --- | --- | --- | --- | --- |
-| farmboy | Luke Skywalker | Inactive | Temple Island | male |
-| nevertellmetheodds | Han Solo | Inactive | unknown | male |
-| goldenrod | C-3PO | Active | Space | n/a |
-| whistles | R2-D2 | Active | Space | n/a |
-| princess | Leia Organa | Inactive | unknown | female |
+| No results found |
 
 Hide code
 
@@ -99,12 +317,6 @@ import {
 } from '@iress-oss/ids-components';
 import { useMemo, useState } from 'react';
 import { searchStarWarsCharacters } from '@/mocks/starWars';
-const toArray \= <T,\>(item?: T | T\[\]): T\[\] \=> {
-  if (Array.isArray(item)) {
-    return item;
-  }
-  return item !== undefined ? \[item\] : \[\];
-};
 const USERS \= \[
   {
     user: 'farmboy',
@@ -153,11 +365,11 @@ const getUniqueValues \= (key: string): LabelValueMeta\[\] \=> {
     value: item,
   }));
 };
-export const FilterSearchTable \= () \=> {
-  const \[name, setName\] \= useState<LabelValueMeta\[\]\>(\[\]);
-  const \[status, setStatus\] \= useState<LabelValueMeta\[\]\>(\[\]);
-  const \[location, setLocation\] \= useState<LabelValueMeta\[\]\>(\[\]);
-  const \[gender, setGender\] \= useState<LabelValueMeta\[\]\>(\[\]);
+export const FilterSearchTable \= (<false\>) => {
+  const \[name, setName\] \= useState<LabelValueMeta | undefined\>();
+  const \[status, setStatus\] \= useState<LabelValueMeta | undefined\>();
+  const \[location, setLocation\] \= useState<LabelValueMeta | undefined\>();
+  const \[gender, setGender\] \= useState<LabelValueMeta | undefined\>(undefined);
   const columns \= \[
     { key: 'user', label: 'User' },
     { key: 'name', label: 'Name' },
@@ -166,11 +378,8 @@ export const FilterSearchTable \= () \=> {
     { key: 'gender', label: 'Gender' },
   \];
   const rows \= useMemo(() \=> {
-    const match \= (filter: LabelValueMeta\[\], detail: string): boolean \=>
-      filter.length \=== 0 ||
-      filter.some(
-        (filterItem) \=> (filterItem.value ?? filterItem.label) \=== detail,
-      );
+    const match \= (filterItem?: LabelValueMeta, detail?: string): boolean \=>
+      (filterItem?.value ?? filterItem?.label) \=== detail;
     return USERS.filter(
       (user) \=>
         match(name, user.name) &&
@@ -180,14 +389,14 @@ export const FilterSearchTable \= () \=> {
     );
   }, \[name, status, location, gender\]);
   const handleReset \= () \=> {
-    setName(\[\]);
-    setStatus(\[\]);
-    setLocation(\[\]);
-    setGender(\[\]);
+    setName(undefined);
+    setStatus(undefined);
+    setLocation(undefined);
+    setGender(undefined);
   };
   return (
-    <IressStack gutter\={IressStack.Gutter.Md}\>
-      <IressInline gutter\={IressInline.Gutter.Md}\>
+    <IressStack gap\="md"\>
+      <IressInline gap\="md"\>
         <IressFilter
           {...{
   label: 'Filter',
@@ -221,8 +430,8 @@ export const FilterSearchTable \= () \=> {
           label\="Name"
           options\={searchStarWarsCharacters}
           value\={name}
-          onChange\={(value) \=> setName(toArray(value))}
-          onReset\={() \=> setName(\[\])}
+          onChange\={setName}
+          onReset\={() \=> setName(undefined)}
         />
         <IressFilter
           {...{
@@ -257,8 +466,8 @@ export const FilterSearchTable \= () \=> {
           label\="Status"
           options\={getUniqueValues('status')}
           value\={status}
-          onChange\={(value) \=> setStatus(toArray(value))}
-          onReset\={() \=> setStatus(\[\])}
+          onChange\={setStatus}
+          onReset\={() \=> setStatus(undefined)}
         />
         <IressFilter
           {...{
@@ -293,8 +502,8 @@ export const FilterSearchTable \= () \=> {
           label\="Location"
           options\={getUniqueValues('location')}
           value\={location}
-          onChange\={(value) \=> setLocation(toArray(value))}
-          onReset\={() \=> setLocation(\[\])}
+          onChange\={setLocation}
+          onReset\={() \=> setLocation(undefined)}
         />
         <IressFilter
           {...{
@@ -329,10 +538,10 @@ export const FilterSearchTable \= () \=> {
           label\="Gender"
           options\={getUniqueValues('gender')}
           value\={gender}
-          onChange\={(value) \=> setGender(toArray(value))}
-          onReset\={() \=> setGender(\[\])}
+          onChange\={setGender}
+          onReset\={() \=> setGender(undefined)}
         />
-        <IressButton onClick\={handleReset} mode\={IressButton.Mode.Tertiary}\>
+        <IressButton onClick\={handleReset} mode\="tertiary"\>
           Reset filters        </IressButton\>
       </IressInline\>
       <IressDivider />
@@ -459,8 +668,10 @@ Hide code
 
 import { IressFilter, IressFilterProps } from '@iress-oss/ids-components';
 import { useState } from 'react';
-export const FilterUsingState \= () \=> {
-  const \[value, setValue\] \= useState<IressFilterProps\['value'\]\>();
+export const FilterUsingState \= <TMultiple extends boolean \= false\>(
+  <TMultiple\>,
+) => {
+  const \[value, setValue\] \= useState<IressFilterProps<TMultiple\>\['value'\]\>();
   return (
     <IressFilter
       {...{
@@ -583,7 +794,7 @@ Hide code
     }
   \]}
   popoverProps\={{
-    container: document.body
+    container: {}
   }}
 />
 
@@ -611,7 +822,9 @@ interface StarWarsCharacter {
 interface StarWarsCharacterApi {
   results: StarWarsCharacter\[\];
 }
-export const FilterUsingAsync \= () \=> (
+export const FilterUsingAsync \= <TMultiple extends boolean \= false\>(
+  <TMultiple\>,
+) => (
   <IressFilter
     {...{
   label: 'Filter',
@@ -742,15 +955,15 @@ Hide code
     {
       label: 'John Smith',
       meta: \[
-        <IressText key\="opt1-type" element\="small" mode\="muted"\>Individual</IressText\>,
-        <IressText key\="opt1-email" element\="small" mode\="muted"\>test@iress.com</IressText\>
+        <IressText key\="opt1-type" color\="colour.neutral.70" element\="small"\>Individual</IressText\>,
+        <IressText key\="opt1-email" color\="colour.neutral.70" element\="small"\>test@iress.com</IressText\>
       \],
       value: 'opt1'
     },
     {
       label: 'Tom Wilson',
       meta: \[
-        <IressText key\="opt2-type" element\="small" mode\="muted"\>Individual</IressText\>
+        <IressText key\="opt2-type" color\="colour.neutral.70" element\="small"\>Individual</IressText\>
       \],
       value: 'opt2'
     },
@@ -758,29 +971,29 @@ Hide code
       append: <IressBadge mode\="success"\>Active</IressBadge\>,
       label: 'Alice Kay',
       meta: \[
-        <IressText key\="opt3-type" element\="small" mode\="muted"\>Individual</IressText\>
+        <IressText key\="opt3-type" color\="colour.neutral.70" element\="small"\>Individual</IressText\>
       \],
       value: 'opt3'
     },
     {
       label: 'John Smith',
       meta: \[
-        <IressText key\="opt4-type" element\="small" mode\="muted"\>Business</IressText\>,
-        <IressText key\="opt4-phone" element\="small" mode\="muted"\>0432325675</IressText\>
+        <IressText key\="opt4-type" color\="colour.neutral.70" element\="small"\>Business</IressText\>,
+        <IressText key\="opt4-phone" color\="colour.neutral.70" element\="small"\>0432325675</IressText\>
       \],
       value: 'opt4'
     },
     {
       label: 'Eelin Team',
       meta: \[
-        <IressText key\="opt5-contact" element\="small" mode\="muted"\>test2@iress.com, 0432325675</IressText\>
+        <IressText key\="opt5-contact" color\="colour.neutral.70" element\="small"\>test2@iress.com, 0432325675</IressText\>
       \],
       value: 'opt5'
     },
     {
       label: 'Eelin Team',
       meta: \[
-        <IressText key\="opt6-contact" element\="small" mode\="muted"\>test3@iress.com, 0439873244</IressText\>
+        <IressText key\="opt6-contact" color\="colour.neutral.70" element\="small"\>test3@iress.com, 0439873244</IressText\>
       \],
       value: 'opt6'
     }
@@ -812,7 +1025,7 @@ Copy
 
 You can customise some settings of the query input by setting the `inputProps`.
 
-It does have some defaults to help with user experience. `prepend` automatically has a search icon, and `clearable` and `watermark` are set to true by default.
+It does have some defaults to help with user experience. `prepend` automatically has a search icon, and `clearable` is set to true by default.
 
 Filter
 
@@ -896,7 +1109,7 @@ Hide code
     }
   \]}
   popoverProps\={{
-    container: {}
+    container: document.body
   }}
   searchable
 />
@@ -991,7 +1204,7 @@ Hide code
   popoverProps\={{
     container: document.body
   }}
-  searchNoResultsText\={<IressPanel className\="iress-u-text"\>No results found</IressPanel\>}
+  searchNoResultsText\={<IressPanel\>No results found</IressPanel\>}
   searchable
 />
 
@@ -1001,7 +1214,7 @@ Copy
 
 Under the hood, filter uses `IressPopover` to display the filter options. You can customise this with `popoverProps`. It accepts `align`, `className`, `container` and `displayMode`.
 
-There are two additional props that filter accepts to customise the popover: `append` and `prepend`. You can place additional content above or below the results using these props.
+There are two additional props that filter accepts to customise the popover: `header` and `footer`. You can place additional content above or below the results using these props.
 
 Filter
 
@@ -1036,8 +1249,8 @@ Hide code
     }
   \]}
   popoverProps\={{
-    append: <IressPanel\><IressButton\>Add an option</IressButton\></IressPanel\>,
-    container: document.body
+    container: document.body,
+    footer: <IressPanel\><IressButton\>Add an option</IressButton\></IressPanel\>
   }}
 />
 
@@ -1081,7 +1294,7 @@ Hide code
     }
   \]}
   popoverProps\={{
-    container: document.body
+    container: {}
   }}
   selectedOptionsText\="{{numOptions}} activated"
 />