@spscommerce/ds-react 6.7.0 → 6.8.0

package/lib/index.es.js

@@ -32790,202 +32790,286 @@ const SpsScrollableContainerExamples = {
   }
 };
 const SpsSelectExamples = {
+  general: {
+    label: "General Usage",
+    description: ({ NavigateTo }) => /* @__PURE__ */ React__default.createElement(React__default.Fragment, null, /* @__PURE__ */ React__default.createElement("h5", null, "Use a Select:"), /* @__PURE__ */ React__default.createElement("ul", null, /* @__PURE__ */ React__default.createElement("li", {
+      className: "mb-2"
+    }, "When a list of predetermined values can be provided.")), /* @__PURE__ */ React__default.createElement("h5", null, "Do Not Use a Select:"), /* @__PURE__ */ React__default.createElement("ul", null, /* @__PURE__ */ React__default.createElement("li", {
+      className: "mb-2"
+    }, "When there are only two possible options. Consider", " ", /* @__PURE__ */ React__default.createElement(NavigateTo, {
+      to: "checkbox"
+    }, "Checkboxes"), " or", " ", /* @__PURE__ */ React__default.createElement(NavigateTo, {
+      to: "radio-buttons"
+    }, "Radio Buttons"), " insead."), /* @__PURE__ */ React__default.createElement("li", {
+      className: "mb-2"
+    }, "When it is ideal to display all available options without requiring a click. Consider", " ", /* @__PURE__ */ React__default.createElement(NavigateTo, {
+      to: "checkbox"
+    }, "Checkboxes"), " or", " ", /* @__PURE__ */ React__default.createElement(NavigateTo, {
+      to: "radio-buttons"
+    }, "Radio Buttons"), " insead.")), /* @__PURE__ */ React__default.createElement("h5", null, "Using Selects in a Form"), /* @__PURE__ */ React__default.createElement("p", null, "Reference the ", /* @__PURE__ */ React__default.createElement(NavigateTo, {
+      to: "form"
+    }, "Forms"), " page for guidelines for placing inputs in Form layouts"))
+  },
   basic: {
-    label: "Basic",
-    description: "info about basic selects",
+    label: "Basic Select",
+    description: () => /* @__PURE__ */ React__default.createElement("p", null, "Basic Selects include a label and dropdown menu containing a list of options. The user is allowed to make a single selection."),
     examples: {
-      a_simple: {
-        description: "Simple value options",
+      basic: {
         react: code`
-                    function DemoComponent() {
-                        const colors = ["red", "blue", "green"];
-
-                        return (
-                            <SpsSelect id="basic" options={colors}/>
-                        )
-                    }
-                `
+          function DemoComponent() {
+            const colors = ["red", "blue", "green"];
+
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel>Color</SpsLabel>
+                  <SpsSelect options={colors} />
+                </div>
+              </div>
+            )
+          }
+        `
       },
-      b_formHooks: {
-        description: "Form hooks",
+      placeholderText: {
+        description: () => /* @__PURE__ */ React__default.createElement(React__default.Fragment, null, /* @__PURE__ */ React__default.createElement("h4", null, "Customizable Placeholder Text"), /* @__PURE__ */ React__default.createElement("p", null, "Placeholder text can be customized to specifically reference the content in the dropdown menu.")),
         react: code`
-                    function DemoComponent() {
-                        const colors = ["red", "blue", "green"];
-                        const { formValue, formMeta, updateForm } = useSpsForm({
-                            color: colors[0]
-                        });
-
-                        return <>
-                            <SpsLabel for={formMeta.fields.color}>Color</SpsLabel>
-                            <SpsSelect options={colors} formMeta={formMeta.fields.color}
-                                value={formValue.color}
-                            />
-                        </>
-                    }
-                `
+          function DemoComponent() {
+            const colors = ["red", "blue", "green"];
+
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel>Color</SpsLabel>
+                  <SpsSelect options={colors} placeholder="Select a color..." />
+                </div>
+              </div>
+            )
+          }
+        `
       },
-      c_placeholder: {
-        description: "Custom placeholder text",
+      defaultSelection: {
+        description: () => /* @__PURE__ */ React__default.createElement(React__default.Fragment, null, /* @__PURE__ */ React__default.createElement("h4", null, "Default Selection / No Clear Button"), /* @__PURE__ */ React__default.createElement("p", null, "Selects can default to a selection in certain cases. Use Default Selections only when a selection is required and a default selection can be confidently made. Selects with a default selection do not have a clear option.")),
         react: code`
-                    function DemoComponent() {
-                        const colors = ["red", "blue", "green"];
-
-                        return (
-                            <SpsSelect id="placeholder" options={colors} placeholder="Choose a color…"/>
-                        )
-                    }
-                `
+          function DemoComponent() {
+            const colors = ["Small", "Medium", "Large"];
+
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel>Size</SpsLabel>
+                  <SpsSelect options={colors} value="Small" notClearable />
+                </div>
+              </div>
+            )
+          }
+        `
       },
-      d_notClearable: {
-        description: "Not clearable",
+      zeroState: {
+        description: () => /* @__PURE__ */ React__default.createElement(React__default.Fragment, null, /* @__PURE__ */ React__default.createElement("h4", null, "Zero State / No Available Options"), /* @__PURE__ */ React__default.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 DemoComponent() {
-                        const colors = ["red", "blue", "green"];
+        function DemoComponent() {
 
-                        return (
-                            <SpsSelect options={colors} value="red" notClearable />
-                        )
-                    }
-                `
+          return (
+            <div className="sfg-row">
+              <div className="sfg-col-4">
+                <SpsLabel>Company</SpsLabel>
+                <SpsSelect options={[]} zeroState="We're sorry, there are no options to choose from at this time." />
+              </div>
+            </div>
+          )
+        }
+        `
       },
-      e_zeroState: {
-        description: "Zero state",
+      formHooks: {
+        description: ({ NavigateTo }) => /* @__PURE__ */ React__default.createElement(React__default.Fragment, null, /* @__PURE__ */ React__default.createElement("h4", null, "Form Hooks"), /* @__PURE__ */ React__default.createElement("p", null, "The ", /* @__PURE__ */ React__default.createElement("code", null, "formMeta"), " and ", /* @__PURE__ */ React__default.createElement("code", null, "formValue"), " props are used with the", " ", /* @__PURE__ */ React__default.createElement("code", null, "useSpsForm"), " hook. By using the ", /* @__PURE__ */ React__default.createElement("code", null, "useSpsForm"), " hook you can add validators, get the form value, update the form value, and more. The form is documented on the ", /* @__PURE__ */ React__default.createElement(NavigateTo, {
+          to: "form"
+        }, "Forms"), " page.")),
         react: code`
-                    function DemoComponent() {
-                        return (
-                            <SpsSelect options={[]} zeroState="We're sorry, there are no options to choose from at this time, because reasons." />
-                        )
-                    }
-                `
+          function DemoComponent() {
+            const colors = ["red", "blue", "green"];
+            const { formValue, formMeta, updateForm } = useSpsForm({
+              color: colors[0]
+            });
+
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel for={formMeta.fields.color}>Color</SpsLabel>
+                  <SpsSelect options={colors} formMeta={formMeta.fields.color} formValue={formValue.color}/>
+                </div>
+              </div>
+            )
+          }
+        `
       }
     }
   },
-  b_objectOpts: {
-    label: "Object Options",
-    description: "info about object options",
+  filter: {
+    label: "Select with Filter",
+    description: () => /* @__PURE__ */ React__default.createElement("p", null, "It can be helpful to add a filter field to dropdown menus that contain a large amount of options to aid the user in finding the option they need."),
     examples: {
-      a_basic: {
-        description: "Basic use of object options",
+      basic: {
         react: code`
-                    function DemoComponent() {
-                        const sizes = [
-                            { size: "S", price: "10.99" },
-                            { size: "M", price: "12.99" },
-                            { size: "L", price: "14.99" }
-                        ];
+          function DemoComponent() {
+            function colorSearch(search) {
+              return ["red", "orange", "yellow", "green", "blue", "indigo", "violet"].filter(s => (new RegExp(search, "i")).test(s));
+            }
 
-                        return (
-                            <SpsSelect options={sizes} textKey="size" />
-                        )
-                    }
-                `
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel>Color</SpsLabel>
+                  <SpsSelect options={colorSearch} zeroState="While I'm sure that's a lovely color, it's not an option we support.ssssssssss" />
+                </div>
+              </div>
+            )
+          }
+        `
       },
-      b_captions: {
-        description: "Captions",
+      promise: {
+        description: () => /* @__PURE__ */ React__default.createElement(React__default.Fragment, null, /* @__PURE__ */ React__default.createElement("h4", null, "Return a Promise"), /* @__PURE__ */ React__default.createElement("p", null, "A promise should be used when the options are being returned asynchronously. A common use case for this is when the options are being returned as a result of an API call.")),
         react: code`
-                    function DemoComponent() {
-                        const lorem = [
-                            {
-                                title: "Lorem",
-                                description: "Ut enim ad minim veniam"
-                            },
-                            {
-                                title: "Ipsum",
-                                description: "Excepteur sint occaecat cupidatat non proident"
-                            }
-                        ];
+          function DemoComponent() {
+            function colorSearch(search) {
+              return new Promise((resolve, reject) => {
+                const result = ["red", "orange", "yellow", "green", "blue", "indigo", "violet"].filter(s => new RegExp(search, "i").test(s));
+                resolve(result);
+              });
+            }
 
-                        return (
-                            <SpsSelect options={lorem} textKey="title" captionKey="description" />
-                        )
-                    }
-                `
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel>Color</SpsLabel>
+                  <SpsSelect options={colorSearch} />
+                </div>
+              </div>
+            )
+          }
+        `
+      },
+      debounce: {
+        description: () => /* @__PURE__ */ React__default.createElement(React__default.Fragment, null, /* @__PURE__ */ React__default.createElement("h4", null, "Debounce"), /* @__PURE__ */ React__default.createElement("p", null, "When the options are a result of a search or are not available right away a debounce may be helpful. A debounce adds a delay to the option search so the search function is not getting called repeatedly.")),
+        react: code`
+          function DemoComponent() {
+            function colorSearch(search) {
+              return ["red", "orange", "yellow", "green", "blue", "indigo", "violet"].filter(s => new RegExp(search, "i").test(s));
+            }
+
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel>Color</SpsLabel>
+                  <SpsSelect options={colorSearch} searchDebounce={2000} />
+                </div>
+              </div>
+            )
+          }
+        `
       }
     }
   },
-  c_searchable: {
-    label: "Search/Filter",
-    description: "info about search/filter",
+  objectOptions: {
+    label: "Object Options",
+    description: () => /* @__PURE__ */ React__default.createElement("p", null, "The values in the select menu can be modified to provide more detail to the user or the system, when necessary."),
     examples: {
-      a_simple: {
-        description: "Simple search function",
+      basic: {
         react: code`
-                    function DemoComponent() {
-                        function colorSearch(search) {
-                            return ["red", "orange", "yellow", "green", "blue", "indigo", "violet"]
-                                .filter(s => (new RegExp(search, "i")).test(s));
-                        }
-
-                        return (
-                            <SpsSelect  id="search-function" options={colorSearch} zeroState="While I'm sure that's a lovely color, it's not an option we support."/>
-                        )
-                    }
-                `
+          function DemoComponent() {
+            const sizes = [
+              { size: "S", price: "10.99" },
+              { size: "M", price: "12.99" },
+              { size: "S", price: "10.99" },
+            ]
+
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel>Size</SpsLabel>
+                  <SpsSelect options={sizes} textKey="size" />
+                </div>
+              </div>
+            )
+          }
+        `
       },
-      b_promise: {
-        description: "Search function returning a Promise",
+      extendedDetails: {
+        description: () => /* @__PURE__ */ React__default.createElement(React__default.Fragment, null, /* @__PURE__ */ React__default.createElement("h4", null, "Extended Details"), /* @__PURE__ */ React__default.createElement("p", null, "Extended details can be displayed in the dropdown menu. Only the primary detail is displayed as the selection.")),
         react: code`
-                    function DemoComponent() {
-                        function colorSearch(search) {
-                            return new Promise((resolve, reject) => {
-                                const result = ["red", "orange", "yellow", "green", "blue", "indigo", "violet"]
-                                    .filter(s => new RegExp(search, "i").test(s));
-                                resolve(result);
-                            });
-                        }
-
-                        return (
-                            <SpsSelect options={colorSearch}/>
-                        )
-                    }
-                `
-      },
-      c_debounce: {
-        description: "Search with Debounce",
+          function DemoComponent() {
+            const sizes = [
+              { size: "S", price: "$10.99" },
+              { size: "M", price: "$12.99" },
+              { size: "S", price: "$10.99" },
+            ]
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel>Size</SpsLabel>
+                  <SpsSelect options={sizes} textKey="size" captionKey="price" />
+                </div>
+              </div>
+            )
+          }
+        `
+      }
+    }
+  },
+  selectWithAction: {
+    label: "Select with Action Button",
+    description: () => /* @__PURE__ */ React__default.createElement("p", null, "A Text Button can be added to the bottom of the dropdown menu to provide a specific action."),
+    examples: {
+      basic: {
         react: code`
-                    function DemoComponent() {
-                        function colorSearch(search) {
-                            return ["red", "orange", "yellow", "green", "blue", "indigo", "violet"]
-                                .filter(s => (new RegExp(search, "i")).test(s));
-                        }
+          function DemoComponent() {
+            const colors = ["red", "blue", "green"];
+            const [action, updateAction] = useSpsAction(
+              {
+                  label: "Go to Overview",
+                  icon: "dashboard",
+                  href: "#/overview",
+                  newTab: true
+              },
+              () => console.log("Action")
+            );
+
+            function handleChange(event) {
+              updateAction({
+                  label: "Test Action"
+              });
+            }
 
-                        return (
-                            <SpsSelect id="debounce-select" options={colorSearch} searchDebounce={2000}/>
-                        )
-                    }
-                `
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsSelect options={colors} action={action} onChange={handleChange} />
+                </div>
+              </div>
+            )
+          }
+        `
       }
     }
   },
-  d_specialAction: {
-    label: "Simple Action",
-    description: "info about simple action selects",
+  disabled: {
+    label: "Disabled State",
+    description: () => /* @__PURE__ */ React__default.createElement("p", null, "In the disabled state, select inputs display the current selection or placeholder text, but cannot be interacted with."),
     examples: {
-      a_action: {
-        description: "Action",
+      basic: {
         react: code`
-                    function DemoComponent() {
-                        const colors = ["red", "orange", "yellow", "blue", "indigo", "violet"];
-                        const [action, updateAction] = useSpsAction(
-                            {
-                                label: "Go to Overview",
-                                icon: "dashboard",
-                                href: "#/overview",
-                                newTab: true
-                            },
-                            () => console.log("Action")
-                        );
-                        function handleChange(event) {
-                            updateAction({
-                                label: "Test Action"
-                            });
-                        }
-
-                        return (
-                            <SpsSelect  id="special-action" options={colors} action={action} onChange={handleChange}/>
-                        )
-                    }
-                `
+          function DemoComponent() {
+            const colors = ["red", "blue", "green"];
+
+            return (
+              <div className="sfg-row">
+                <div className="sfg-col-4">
+                  <SpsLabel>Color</SpsLabel>
+                  <SpsSelect options={colors} disabled />
+                </div>
+              </div>
+            )
+          }
+        `
       }
     }
   }
@@ -37638,6 +37722,7 @@ const MANIFEST = {
     examples: SpsSearchResultsBarExamples
   },
   Select: {
+    description: "Selects consist off a Label and a dropdown menu from which a user selects a value from a list of pre-defined options.",
     components: [SpsSelect],
     examples: SpsSelectExamples
   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spscommerce/ds-react",
   "description": "SPS Design System React components",
-  "version": "6.7.0",
+  "version": "6.8.0",
   "author": "SPS Commerce",
   "license": "UNLICENSED",
   "repository": "https://github.com/spscommerce/design-system/tree/main/packages/@spscommerce/ds-react",
@@ -28,11 +28,11 @@
   },
   "peerDependencies": {
     "@react-stately/collections": "^3.3.3",
-    "@spscommerce/ds-colors": "6.7.0",
-    "@spscommerce/ds-illustrations": "6.7.0",
-    "@spscommerce/ds-shared": "6.7.0",
-    "@spscommerce/positioning": "6.7.0",
-    "@spscommerce/utils": "6.7.0",
+    "@spscommerce/ds-colors": "6.8.0",
+    "@spscommerce/ds-illustrations": "6.8.0",
+    "@spscommerce/ds-shared": "6.8.0",
+    "@spscommerce/positioning": "6.8.0",
+    "@spscommerce/utils": "6.8.0",
     "moment": "^2.25.3",
     "moment-timezone": "^0.5.28",
     "react": "^16.9.0",
@@ -40,11 +40,11 @@
   },
   "devDependencies": {
     "@react-stately/collections": "^3.3.3",
-    "@spscommerce/ds-colors": "6.7.0",
-    "@spscommerce/ds-illustrations": "6.7.0",
-    "@spscommerce/ds-shared": "6.7.0",
-    "@spscommerce/positioning": "6.7.0",
-    "@spscommerce/utils": "6.7.0",
+    "@spscommerce/ds-colors": "6.8.0",
+    "@spscommerce/ds-illustrations": "6.8.0",
+    "@spscommerce/ds-shared": "6.8.0",
+    "@spscommerce/positioning": "6.8.0",
+    "@spscommerce/utils": "6.8.0",
     "@testing-library/react": "^9.3.2",
     "@types/prop-types": "^15.7.1",
     "@types/react": "^16.9.0",