From 7291d7fbc94bf2b5d50c688e5782d1dcbb14fe6a Mon Sep 17 00:00:00 2001
From: Alejandro Celaya <alejandro.celaya@hypothes.is>
Date: Fri, 25 Oct 2024 15:31:12 +0200
Subject: [PATCH] Document listboxOverflow Select prop

---
 src/components/input/Select.tsx               | 11 ----
 .../patterns/prototype/SelectPage.tsx         | 34 +++++++++++++
 .../examples/select-truncate-listbox.tsx      | 51 +++++++++++++++++++
 .../examples/select-wrap-listbox.tsx          | 51 +++++++++++++++++++
 4 files changed, 136 insertions(+), 11 deletions(-)
 create mode 100644 src/pattern-library/examples/select-truncate-listbox.tsx
 create mode 100644 src/pattern-library/examples/select-wrap-listbox.tsx

diff --git a/src/components/input/Select.tsx b/src/components/input/Select.tsx
index 6d6b8049..9aaa5686 100644
--- a/src/components/input/Select.tsx
+++ b/src/components/input/Select.tsx
@@ -446,7 +446,6 @@ type BaseSelectProps = CompositeProps & {
   /**
    * Indicates how overflowing content should be handled in the listbox.
    *
-<<<<<<< HEAD
    * - `truncate`: Truncate the options via `text-overflow: ellipsis`, so that
    *               they all fit in one line. This is the default value.
    * - `wrap`: Let options content wrap onto multiple lines via
@@ -454,16 +453,6 @@ type BaseSelectProps = CompositeProps & {
    *
    * Complex content may still need to provide its own styling to handle content
    * overflow.
-=======
-   * - `truncate`: Truncate the options so that they all fit in one line. An
-   *               ellipsis will be rendered where needed.
-   *               This is the default value.
-   * - `wrap`: Let options content wrap multiple lines so that all content is
-   *           visible.
-   *
-   * This behavior can be also overwritten by providing more complex options
-   * content.
->>>>>>> 51ceff5 (Prevent Select listbox to grow out of viewport)
    */
   listboxOverflow?: ListboxOverflow;
 };
diff --git a/src/pattern-library/components/patterns/prototype/SelectPage.tsx b/src/pattern-library/components/patterns/prototype/SelectPage.tsx
index d450c819..2168b7a3 100644
--- a/src/pattern-library/components/patterns/prototype/SelectPage.tsx
+++ b/src/pattern-library/components/patterns/prototype/SelectPage.tsx
@@ -447,6 +447,40 @@ export default function SelectPage() {
               </Library.InfoItem>
             </Library.Info>
           </Library.Example>
+          <Library.Example title="listboxOverflow">
+            <Library.Info>
+              <Library.InfoItem label="description">
+                Determines the behavior of the listbox options when their
+                content is larger than the listbox.
+                <ul className="list-disc">
+                  <li>
+                    <code>{"'truncate'"}</code>: Text will use one line and be
+                    truncated with an ellipsis.
+                  </li>
+                  <li>
+                    <code>{"'wrap'"}</code>: Text will span multiple lines if
+                    needed, ensuring all content is visible.
+                  </li>
+                </ul>
+              </Library.InfoItem>
+              <Library.InfoItem label="type">
+                <code>{"'truncate' | 'wrap'"}</code>
+              </Library.InfoItem>
+              <Library.InfoItem label="default">
+                <code>{"'truncate'"}</code>
+              </Library.InfoItem>
+            </Library.Info>
+            <Library.Demo
+              title="Truncate listbox options"
+              exampleFile="select-truncate-listbox"
+              withSource
+            />
+            <Library.Demo
+              title="Wrap listbox options"
+              exampleFile="select-wrap-listbox"
+              withSource
+            />
+          </Library.Example>
         </Library.Pattern>
 
         <Library.Pattern title="Select.Option component API">
diff --git a/src/pattern-library/examples/select-truncate-listbox.tsx b/src/pattern-library/examples/select-truncate-listbox.tsx
new file mode 100644
index 00000000..f38390ac
--- /dev/null
+++ b/src/pattern-library/examples/select-truncate-listbox.tsx
@@ -0,0 +1,51 @@
+import { useId, useState } from 'preact/hooks';
+
+import { Select } from '../..';
+
+const items = [
+  {
+    id: '1',
+    name: 'All students - content is very long and will not fit the listbox',
+  },
+  {
+    id: '2',
+    name: 'Albert Banana - content is very long and will not fit the listbox',
+  },
+  {
+    id: '3',
+    name: 'Bernard California - content is very long and will not fit the listbox',
+  },
+  {
+    id: '4',
+    name: 'Cecelia Davenport - content is very long and will not fit the listbox',
+  },
+  {
+    id: '5',
+    name: 'Doris Evanescence - content is very long and will not fit the listbox',
+  },
+];
+
+export default function App() {
+  const [value, setSelected] = useState<{ id: string; name: string }>();
+  const selectId = useId();
+
+  return (
+    <div className="w-96 mx-auto">
+      <label htmlFor={selectId}>Select a person</label>
+      <Select
+        value={value}
+        onChange={newValue => setSelected(newValue)}
+        buttonId={selectId}
+        buttonContent={value ? value.name : <>Select one…</>}
+        listboxClasses="w-36"
+        listboxOverflow="truncate"
+      >
+        {items.map(item => (
+          <Select.Option value={item} key={item.id}>
+            {item.name}
+          </Select.Option>
+        ))}
+      </Select>
+    </div>
+  );
+}
diff --git a/src/pattern-library/examples/select-wrap-listbox.tsx b/src/pattern-library/examples/select-wrap-listbox.tsx
new file mode 100644
index 00000000..a7a21bc5
--- /dev/null
+++ b/src/pattern-library/examples/select-wrap-listbox.tsx
@@ -0,0 +1,51 @@
+import { useId, useState } from 'preact/hooks';
+
+import { Select } from '../..';
+
+const items = [
+  {
+    id: '1',
+    name: 'All students - content is very long and will not fit the listbox',
+  },
+  {
+    id: '2',
+    name: 'Albert Banana - content is very long and will not fit the listbox',
+  },
+  {
+    id: '3',
+    name: 'Bernard California - content is very long and will not fit the listbox',
+  },
+  {
+    id: '4',
+    name: 'Cecelia Davenport - content is very long and will not fit the listbox',
+  },
+  {
+    id: '5',
+    name: 'Doris Evanescence - content is very long and will not fit the listbox',
+  },
+];
+
+export default function App() {
+  const [value, setSelected] = useState<{ id: string; name: string }>();
+  const selectId = useId();
+
+  return (
+    <div className="w-96 mx-auto">
+      <label htmlFor={selectId}>Select a person</label>
+      <Select
+        value={value}
+        onChange={newValue => setSelected(newValue)}
+        buttonId={selectId}
+        buttonContent={value ? value.name : <>Select one…</>}
+        listboxClasses="w-36"
+        listboxOverflow="wrap"
+      >
+        {items.map(item => (
+          <Select.Option value={item} key={item.id}>
+            {item.name}
+          </Select.Option>
+        ))}
+      </Select>
+    </div>
+  );
+}