@spscommerce/ds-react 6.3.0 → 6.4.0

package/lib/index.es.js

@@ -30282,212 +30282,375 @@ Object.assign(SpsMultiSelect, {
   displayName: "SpsMultiSelect"
 });
 const SpsMultiSelectExamples = {
-  basic: {
-    label: "Basic",
-    description: "<p>Multi select component</p>",
+  general: {
+    label: "General Usage",
+    description: ({ NavigateTo }) => /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("h5", null, "Use a Mulit-Select"), /* @__PURE__ */ React.createElement("ul", null, /* @__PURE__ */ React.createElement("li", null, "When a list of predetermined values can be provided and the input allows multiple entries.")), /* @__PURE__ */ React.createElement("h5", null, "Do Not Use a Multi-Select:"), /* @__PURE__ */ React.createElement("ul", null, /* @__PURE__ */ React.createElement("li", {
+      className: "mb-2"
+    }, "When there are only two possible options. Consider", " ", /* @__PURE__ */ React.createElement(NavigateTo, {
+      to: "checkbox"
+    }, "Checkboxes"), " or", " ", /* @__PURE__ */ React.createElement(NavigateTo, {
+      to: "radio-buttons"
+    }, "Radio Buttons"), " instead."), /* @__PURE__ */ React.createElement("li", null, "When it is ideal to display all available options without requiring a click. Consider", " ", /* @__PURE__ */ React.createElement(NavigateTo, {
+      to: "checkbox"
+    }, "Checkboxes"), " or", " ", /* @__PURE__ */ React.createElement(NavigateTo, {
+      to: "radio-buttons"
+    }, "Radio Buttons"), " instead.")), /* @__PURE__ */ React.createElement("h5", null, "Using Multi-Selects in a Form"), /* @__PURE__ */ React.createElement("p", null, "Reference the ", /* @__PURE__ */ React.createElement(NavigateTo, {
+      to: "form"
+    }, "Forms"), " page for guidelines for placing", " ", /* @__PURE__ */ React.createElement(NavigateTo, {
+      to: "text-inputs"
+    }, "Inputs"), " in Form Layouts."))
+  },
+  basicMuliSelect: {
+    label: "Basic Multi-Selects",
+    description: "Basic Multi-Selects include a label and dropdown menu including a list of options. The user is allowed to make a single selection.",
     examples: {
-      a_basic: {
+      basic: {
         react: code`
-                    function Component() {
-                        const [opts] = React.useState(["foo", "bar", "baz", "orp"])
-                        const { formValue, formMeta, updateForm } = useSpsForm({
-                            things: [ opts[0] ]
-                        })
-
-                        return <>
-                            <SpsLabel for={formMeta.fields.things}>Things</SpsLabel>
-                            <SpsMultiSelect
-                                options={opts}
-                                formMeta={formMeta.fields.things}
-                                value={formValue.things}
-                            />
-                            <br />
-                            {JSON.stringify(formValue)}
-                        </>
-                    }
-                `
+        function Component() {
+          const [opts] = React.useState(["foo", "bar", "baz", "orp"])
+          const { formValue, formMeta, updateForm } = useSpsForm({
+              things: [opts[0]]
+          })
+      
+          return <>
+              <SpsLabel for={formMeta.fields.things}>Company Names</SpsLabel>
+              <SpsMultiSelect
+                  options={opts}
+                  formMeta={formMeta.fields.things}
+                  value={formValue.things}
+              />
+              <br />
+              {JSON.stringify(formValue)}
+          </>
+      }`
       },
-      b_disabled: {
+      customizablePlaceholderText: {
+        description: () => /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("h4", null, "Customizable Placeholder Text"), /* @__PURE__ */ React.createElement("p", null, "Placeholder text can be customized to specifically reference the content in the dropdown menu.")),
         react: code`
-                    function Component() {
-                        const [opts] = React.useState(["foo", "bar", "baz", "orp"])
-                        const { formValue, formMeta, updateForm } = useSpsForm({
-                            things: [ opts[0] ]
-                        })
-
-                        return <>
-                            <SpsLabel for={formMeta.fields.things}>Things</SpsLabel>
-                            <SpsMultiSelect disabled
-                                options={opts}
-                                formMeta={formMeta.fields.things}
-                                value={formValue.things}
-                            />
-                            <br />
-                            {JSON.stringify(formValue)}
-                        </>
-                    }
-                `
+        function Component() {
+          const [opts] = React.useState(["foo", "bar", "baz", "orp"])
+          const { formValue, formMeta, updateForm } = useSpsForm({
+              things: []
+          })
+      
+          return <>
+              <SpsLabel for={formMeta.fields.things}>Company Names</SpsLabel>
+              <SpsMultiSelect
+                  placeholder= "Select companies..."
+                  options={opts}
+                  formMeta={formMeta.fields.things}
+                  value={formValue.things}
+              />
+              <br />
+              {JSON.stringify(formValue)}
+          </>
+      }`
       },
-      c_externalTags: {
+      zeroStateNoAvailableOptions: {
+        description: () => /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("h4", null, "Zero State / No Available Options"), /* @__PURE__ */ React.createElement("p", null, "If no options are available in the dropdown menu, a zero state message appears. This option is most commonly used with the Select with Filter option.")),
         react: code`
-                    function Component() {
-                        const [foo, setFoo] = React.useState(["orp"])
-                        const [opts] = React.useState(["foo", "bar", "baz", "orp"])
-                        function handleChange(event) {
-                            setFoo(event.target.value)
-                        }
-                        function removeByIndex(i) {
-                            foo.splice(i, 1)
-                            setFoo([...foo])
-                        }
-                        return (
-                            <>
-                                <SpsMultiSelect
-                                    hideSelected
-                                    options={opts}
-                                    value={foo}
-                                    onChange={handleChange}
-                                />
-                                <br />
-                                {foo.map((opt, i) => (
-                                    <SpsClickableTag
-                                        className="mt-1 ml-1"
-                                        key={i}
-                                        onRemove={() => removeByIndex(i)}
-                                    >
-                                        {opt}
-                                    </SpsClickableTag>
-                                ))}
-                            </>
-                        )
-                    }
-                `
-      },
-      icon: {
+        function Component() {
+          const [opts] = React.useState([])
+          const { formValue, formMeta, updateForm } = useSpsForm({
+              things: []
+          })
+      
+          return <>
+              <SpsLabel for={formMeta.fields.things}>Company Names</SpsLabel>
+              <SpsMultiSelect
+                  zeroState="No options available"
+                  options={opts}
+                  formMeta={formMeta.fields.things}
+                  value={formValue.things}
+              />
+              <br />
+              {JSON.stringify(formValue)}
+          </>
+      }`
+      }
+    }
+  },
+  promise: {
+    label: "Asynchronous Data Source",
+    description: "If the list of options must be sourced asynchronously, the options prop can take a function that returns a Promise.",
+    examples: {
+      returnAPromise: {
+        react: code`function Component() {
+          const { formValue, formMeta, updateForm } = useSpsForm({
+              things: []
+          })
+          function colorSearch(search) {
+              return new Promise((resolve, reject) => {
+                  const result = ["foo", "bar", "baz", "orp"]
+                      .filter(s => new RegExp(search, "i").test(s));
+                  resolve(result);
+              });
+          }
+      
+          return <>
+              <SpsLabel for={formMeta.fields.things}>Things</SpsLabel>
+              <SpsMultiSelect
+                  options={colorSearch}
+                  formMeta={formMeta.fields.things}
+                  value={formValue.things}
+              />
+              <br />
+              {JSON.stringify(formValue)}
+          </>
+      }`
+      }
+    }
+  },
+  objectOptions: {
+    label: "Object Options",
+    description: "The values in the select menu can be modified to provide more detail to the user or the system, when necssary.",
+    examples: {
+      basic: {
         react: code`
-                    function Component() {
-                        const [opts] = React.useState(["foo", "bar", "baz", "orp"])
-                        const { formValue, formMeta, updateForm } = useSpsForm({
-                            things: [ opts[0] ]
-                        })
-
-                        return <>
-                            <SpsLabel for={formMeta.fields.things}>Things</SpsLabel>
-                            <SpsMultiSelect
-                                icon={SpsIcon.FILTER}
-                                options={opts}
-                                formMeta={formMeta.fields.things}
-                                value={formValue.things}
-                            />
-                            <br />
-                            {JSON.stringify(formValue)}
-                        </>
-                    }
-                `
+        function Component() {
+          const [opts] = React.useState([
+              { id: 1, name: "Target" },
+              { id: 2, name: "Cabela's" },
+              { id: 3, name: "Best Buy" },
+          ])
+          const [foo, setFoo] = React.useState([])
+          function handleChange(event) {
+              setFoo(event.target.value)
+          }
+          return (
+              <>
+                  <SpsMultiSelect
+                      options={opts}
+                      textKey="name"
+                      value={foo}
+                      onChange={handleChange}
+                  />
+                  <br />
+                  {JSON.stringify(foo)}
+              </>
+          )
+      }`
       },
-      objects: {
+      extendedDetails: {
+        description: () => /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("h4", null, "Extended Details"), /* @__PURE__ */ React.createElement("p", null, "Extended details can be displayed in the dropdown menu. Only the primary detail is displayed as the selection.")),
         react: code`
-                    function Component() {
-                        const [opts] = React.useState([
-                            { id: 1, name: "Target" },
-                            { id: 2, name: "Cabela's" },
-                            { id: 3, name: "Best Buy" },
-                        ])
-                        const [foo, setFoo] = React.useState([])
-                        function handleChange(event) {
-                            setFoo(event.target.value)
-                        }
-                        return (
-                            <>
-                                <SpsMultiSelect
-                                    options={opts}
-                                    textKey="name"
-                                    value={foo}
-                                    onChange={handleChange}
-                                />
-                                <br />
-                                {JSON.stringify(foo)}
-                            </>
-                        )
-                    }
-                `
+        function Component() {
+          const [opts] = React.useState([
+              { id: 1, name: "Target", description: "blah", disabled: true },
+              { id: 2, name: "Cabela's", description: "test", disabled: true },
+              { id: 3, name: "Best Buy", description: "2" },
+          ])
+          const [foo, setFoo] = React.useState([])
+          function handleChange(event) {
+              setFoo(event.target.value)
+          }
+          return (
+              <>
+                  <SpsMultiSelect
+                      options={opts}
+                      textKey="name"
+                      captionKey="description"
+                      value={foo}
+                      onChange={handleChange}
+                  />
+                  <br />
+                  {JSON.stringify(foo)}
+              </>
+          )
+      }`
       },
-      disabledOptions: {
+      disabledOption: {
+        description: () => /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("h4", null, "Disabled Options"), /* @__PURE__ */ React.createElement("p", null, "When options in the dropdown list are unavailable (as a result of having been selected or for any other reason) they should adopt a disabled style.")),
         react: code`
-                    function Component() {
-                        const [opts] = React.useState([
-                            { id: 1, name: "Target", disabled: true },
-                            { id: 2, name: "Cabela's", disabled: true },
-                            { id: 3, name: "Best Buy" },
-                        ])
-                        const [foo, setFoo] = React.useState([])
-                        function handleChange(event) {
-                            setFoo(event.target.value)
-                        }
-                        return (
-                            <>
-                                <SpsMultiSelect
-                                    options={opts}
-                                    textKey="name"
-                                    value={foo}
-                                    onChange={handleChange}
-                                />
-                                <br />
-                                {JSON.stringify(foo)}
-                            </>
-                        )
-                    }
-                `
+        function Component() {
+          const [opts] = React.useState(["foo", "bar", "baz", "orp"])
+          const { formValue, formMeta, updateForm } = useSpsForm({
+              things: [ opts[0] ]
+          })
+      
+          return <>
+              <SpsLabel for={formMeta.fields.things}>Company Names</SpsLabel>
+              <SpsMultiSelect
+                  options={opts}
+                  formMeta={formMeta.fields.things}
+                  value={formValue.things}
+                  disableSelected
+              />
+              <br />
+              {JSON.stringify(formValue)}
+          </>
+      }
+        `
       }
     }
   },
-  searchText: {
-    label: "Search text",
-    description: "Get search text",
+  getSearchText: {
+    label: "Get Search Text",
+    description: "The text that the user has entered into the input can be accessed via passing a handler to onSearchChange. This is typically used in combination with the action option to enable a user to add a value they don't find in the list.",
     examples: {
-      a_actionWithSearchText: {
-        react: code`
-           function Component() {
-              const [opts] = React.useState(["foo", "bar", "baz", "orp"]);
-              const { formValue, formMeta, updateForm } = useSpsForm({
-                tags: [opts[0]],
+      basic: {
+        react: code`function Component() {
+          const [opts] = React.useState(["foo", "bar", "baz", "orp"]);
+          const { formValue, formMeta, updateForm } = useSpsForm({
+            tags: [opts[0]],
+          });
+        
+          const [searchText, setSearchText] = React.useState("");
+        
+          React.useEffect(() => {
+              updateAction({
+              label: searchText ? \`Create a New Tag "\${searchText}"\` : "Create a New Tag",
               });
-            
-              const [searchText, setSearchText] = React.useState("");
-            
-              React.useEffect(() => {
-                  updateAction({
-                  label: searchText ? \`Create a New Tag "\${searchText}"\` : "Create a New Tag",
-                  });
-              }, [searchText, opts]);
-              
-              const handleSearchChange = (searchTextValue) => {
-                setSearchText(searchTextValue)
-              }
-            
-              const [action, updateAction] = useSpsAction(
-                {
-                  label: "Create a New Tag",
-                  icon: SpsIcon.PLUS_SIGN,
-                },
-                () => console.log("New Tag has been created")
-              );
-            
-              return (
-                <>
-                  <SpsLabel for={formMeta.fields.tags}>Tags</SpsLabel>
+          }, [searchText, opts]);
+          
+          const handleSearchChange = (searchTextValue) => {
+            setSearchText(searchTextValue)
+          }
+        
+          const [action, updateAction] = useSpsAction(
+            {
+              label: "Create a New Tag",
+              icon: SpsIcon.PLUS_SIGN,
+            },
+            () => console.log("New Tag has been created")
+          );
+        
+          return (
+            <>
+              <SpsLabel for={formMeta.fields.tags}>Tags</SpsLabel>
+              <SpsMultiSelect
+                disableSelected
+                icon={SpsIcon.FILTER}
+                options={opts}
+                action={action}
+                formMeta={formMeta.fields.tags}
+                value={formValue.tags}
+                onSearchChange={handleSearchChange}
+              />
+            </>
+          );
+      }`
+      }
+    }
+  },
+  createANewValue: {
+    label: "Create a New Value",
+    description: "This feature allows users to add, and select, a new value that doesn't exist in the current dropdown menu options.",
+    examples: {
+      basic: {
+        react: code`function Component() {
+          const [opts, setOpts] = React.useState(["foo", "bar", "baz", "orp"]);
+          const { formValue, formMeta, updateForm } = useSpsForm({
+            tags: [opts[0]],
+          });
+        
+          const [searchText, setSearchText] = React.useState("");
+        
+          React.useEffect(() => {
+            updateAction({
+              label: searchText
+                ? \`Create a New Tag "\${searchText}"\`
+                : "Create a New Tag",
+              disabled: searchText === ""
+            });
+          }, [searchText, opts]);
+        
+          const handleSearchChange = (searchTextValue) => {
+            setSearchText(searchTextValue);
+          };
+        
+          const [action, updateAction] = useSpsAction(
+            {
+              label: "Create a New Tag",
+              icon: SpsIcon.PLUS_SIGN,
+            },
+            () => {
+              setOpts([...opts, searchText]);
+              updateForm({ ...formValue, tags: [...formValue.tags, searchText] });
+              handleSearchChange("");
+            }
+          );
+        
+          return (
+            <>
+              <SpsLabel for={formMeta.fields.tags}>Tags</SpsLabel>
+              <SpsMultiSelect
+                disableSelected
+                icon={SpsIcon.FILTER}
+                options={opts}
+                action={action}
+                formMeta={formMeta.fields.tags}
+                value={formValue.tags}
+                onSearchChange={handleSearchChange}
+                clearSearchOnBlur
+              />
+            </>
+          );
+        }`
+      }
+    }
+  },
+  selectedValuesAlternate: {
+    label: "Selected Values Alternate",
+    description: () => /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("p", null, "Use this option when it is ideal for the selected values to appear as tags outside of the input field. Opt for this option when adding or removing values from a large list of selections that would create a cumbersome field."), /* @__PURE__ */ React.createElement("p", null, /* @__PURE__ */ React.createElement("i", null, "Note: The placement of the selected values can appear belcow the input field or elsewhere in the UI if necessary."))),
+    examples: {
+      basic: {
+        react: code`function Component() {
+          const [foo, setFoo] = React.useState(["orp"])
+          const [opts] = React.useState(["foo", "bar", "baz", "orp"])
+          function handleChange(event) {
+              setFoo(event.target.value)
+          }
+          function removeByIndex(i) {
+              foo.splice(i, 1)
+              setFoo([...foo])
+          }
+          return (
+              <>
                   <SpsMultiSelect
-                    disableSelected
-                    icon={SpsIcon.FILTER}
-                    options={opts}
-                    action={action}
-                    formMeta={formMeta.fields.tags}
-                    value={formValue.tags}
-                    onSearchChange={handleSearchChange}
+                      hideSelected
+                      options={opts}
+                      value={foo}
+                      onChange={handleChange}
                   />
-                </>
-              );
-          }`
+                  <br />
+                  {foo.map((opt, i) => (
+                      <SpsClickableTag
+                          className="mt-1 ml-1"
+                          key={i}
+                          onRemove={() => removeByIndex(i)}
+                      >
+                          {opt}
+                      </SpsClickableTag>
+                  ))}
+              </>
+          )
+      }`
+      }
+    }
+  },
+  disabledState: {
+    label: "Disabled State",
+    description: "In the disabled state, select inputs display the current selection or placeholder text, but cannot be interacted with.",
+    examples: {
+      basic: {
+        react: code`function Component() {
+          const [opts] = React.useState(["foo", "bar", "baz", "orp"])
+          const { formValue, formMeta, updateForm } = useSpsForm({
+              things: [ opts[0] ]
+          })
+      
+          return <>
+              <SpsLabel for={formMeta.fields.things}>Company Name</SpsLabel>
+              <SpsMultiSelect disabled
+                  options={opts}
+                  formMeta={formMeta.fields.things}
+                  value={formValue.things}
+              />
+              <br />
+              {JSON.stringify(formValue)}
+          </>
+      }`
       }
     }
   }
@@ -37390,13 +37553,7 @@ const MANIFEST = {
   },
   Cards: {
     description: () => /* @__PURE__ */ React.createElement("p", null, "Cards are used to group similar or related content together in a single container. They can be combined with additional elements such as Headers, Footers, or Tabs."),
-    components: [
-      SpsCardV2,
-      SpsCardV2Footer,
-      SpsCardV2Header,
-      SpsCardV2Title,
-      SpsTabsV2
-    ],
+    components: [SpsCardV2, SpsCardV2Footer, SpsCardV2Header, SpsCardV2Title, SpsTabsV2],
     examples: SpsCardExamples
   },
   Checkbox: {
@@ -37427,12 +37584,7 @@ const MANIFEST = {
     examples: SpsContentRowExamples
   },
   "Content Tiles": {
-    components: [
-      SpsTile,
-      SpsTileList,
-      SpsSortingHeader,
-      SpsSortingHeaderCell
-    ],
+    components: [SpsTile, SpsTileList, SpsSortingHeader, SpsSortingHeaderCell],
     examples: SpsTileListExamples
   },
   "Filter Tiles": {
@@ -37452,11 +37604,7 @@ const MANIFEST = {
     examples: SpsDatetimeExamples
   },
   "Description Lists": {
-    components: [
-      SpsDescriptionList,
-      SpsDescriptionListDefinition,
-      SpsDescriptionListTerm
-    ],
+    components: [SpsDescriptionList, SpsDescriptionListDefinition, SpsDescriptionListTerm],
     examples: SpsDescriptionListExamples
   },
   Dropdown: {
@@ -37464,7 +37612,7 @@ const MANIFEST = {
     examples: SpsDropdownExamples
   },
   "Feedback Blocks": {
-    description: ({ NavigateTo }) => /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("p", null, "Feedback Blocks show static informational messages on a page. They should not dynamically appear or disappear. For feedback that responds to a user action, Use a ", /* @__PURE__ */ React.createElement(NavigateTo, {
+    description: ({ NavigateTo }) => /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("p", null, "Feedback Blocks show static informational messages on a page. They should not dynamically appear or disappear. For feedback that responds to a user action, Use a", " ", /* @__PURE__ */ React.createElement(NavigateTo, {
       to: "growler"
     }, "Growler"), " instead."), /* @__PURE__ */ React.createElement("h5", null, "Variants"), /* @__PURE__ */ React.createElement("p", null, "Variants are generally tied to a specific color and an accompanying icon."), /* @__PURE__ */ React.createElement(SpsMicroBlock, {
       kind: FeedbackBlockKind.ERROR,
@@ -37490,12 +37638,7 @@ const MANIFEST = {
     examples: SpsFieldsetExamples
   },
   "Filter Panel": {
-    components: [
-      SpsFilterPanel,
-      SpsFilterPanelSection,
-      SpsFilterPanelCap,
-      SpsFilterPanelFilterBox
-    ],
+    components: [SpsFilterPanel, SpsFilterPanelSection, SpsFilterPanelCap, SpsFilterPanelFilterBox],
     examples: SpsFilterPanelExamples
   },
   "Focused Task": {
@@ -37552,6 +37695,7 @@ const MANIFEST = {
     examples: SpsModalExamples
   },
   "Multi Select": {
+    description: () => /* @__PURE__ */ React.createElement("p", null, "Multi-Selects consist of a Label and a dropdown menu from which a user selects one or more values from a list of pre-defined options."),
     components: [SpsMultiSelect],
     examples: SpsMultiSelectExamples
   },
@@ -37611,11 +37755,7 @@ const MANIFEST = {
     examples: SpsSlackLinkExamples
   },
   "Summary List Row": {
-    components: [
-      SpsSummaryListRow,
-      SpsSummaryListColumn,
-      SpsSummaryListExpansion
-    ],
+    components: [SpsSummaryListRow, SpsSummaryListColumn, SpsSummaryListExpansion],
     examples: SpsSummaryListExamples
   },
   Tables: {
@@ -37628,14 +37768,7 @@ const MANIFEST = {
     }, "Content Tiles"), ") are one of three options for displaying a list of records on a page."), /* @__PURE__ */ React.createElement("br", null), /* @__PURE__ */ React.createElement("div", {
       className: "sps-body-14"
     }, "Tables are the ideal solution for displaying tabular data, especially when the listed records contain a considerable amount of data points. While tables are primarily used to display an extensive list of records, often in a paginated format, they can also be used to display smaller sets of tabular data in any context.")),
-    components: [
-      SpsTable,
-      SpsTableBody,
-      SpsTableCell,
-      SpsTableHead,
-      SpsTableHeader,
-      SpsTableRow
-    ],
+    components: [SpsTable, SpsTableBody, SpsTableCell, SpsTableHead, SpsTableHeader, SpsTableRow],
     examples: SpsTableExamples
   },
   Tags: {
@@ -37669,12 +37802,7 @@ const MANIFEST = {
     examples: SpsWizardExamples
   },
   Workflow: {
-    components: [
-      SpsWorkflow,
-      SpsWorkflowDocument,
-      SpsWorkflowDocumentStatus,
-      SpsWorkflowStep
-    ],
+    components: [SpsWorkflow, SpsWorkflowDocument, SpsWorkflowDocumentStatus, SpsWorkflowStep],
     examples: SpsWorkflowExamples
   },
   "Zero States": {