From 9d4ddaa192b0759045b7c7f00d483b7dd93d204a Mon Sep 17 00:00:00 2001
From: JL102 <jordanlees@mailbox.org>
Date: Mon, 30 Oct 2023 13:49:18 -0400
Subject: [PATCH] docs: added note on how to avoid the incorrectly floating
 label in a select with empty value

Signed-off-by: JL102 <jordanlees@mailbox.org>
---
 .../site/src/routes/demo/select/+page.svelte  | 21 +++++++++-
 .../routes/demo/select/_DefaultValue.svelte   | 39 +++++++++++++++++++
 2 files changed, 58 insertions(+), 2 deletions(-)
 create mode 100644 packages/site/src/routes/demo/select/_DefaultValue.svelte

diff --git a/packages/site/src/routes/demo/select/+page.svelte b/packages/site/src/routes/demo/select/+page.svelte
index 18c6cfeda..6a418a854 100644
--- a/packages/site/src/routes/demo/select/+page.svelte
+++ b/packages/site/src/routes/demo/select/+page.svelte
@@ -16,8 +16,12 @@
   <Demo component={Keys} file="select/_Keys.svelte">
     Using Keys
     <svelte:fragment slot="subtitle">
-      If your options aren't strings, you must provide a <code>key</code> function
-      that converts them to unique strings, or the label may misbehave.
+      If your options aren't strings, you must provide a <code>key</code>
+      function that converts them to unique strings, or the label may misbehave.
+      <br />
+      The only exception to this is if the text is non-empty while the value is empty.
+      In this case, due to a limitation in <code>@material/select</code>, the
+      label will float over the selected text.
     </svelte:fragment>
   </Demo>
 
@@ -53,6 +57,18 @@
   <Demo component={ConditionalIcon} file="select/_ConditionalIcon.svelte">
     Conditional icon
   </Demo>
+
+  <Demo component={DefaultValue} file="select/_DefaultValue.svelte">
+    Default Values
+    <svelte:fragment slot="subtitle">
+      Due to a limitation of <code>@material/select</code>, the floating label
+      will display incorrectly if the selected option has <code>value=""</code>
+      but its label is non-empty.
+      <br />
+      In the case where you need a default value, set it to a non-empty string like
+      in the second example below.
+    </svelte:fragment>
+  </Demo>
 </section>
 
 <script lang="ts">
@@ -69,6 +85,7 @@
   import Required from './_Required.svelte';
   import Disabled from './_Disabled.svelte';
   import ConditionalIcon from './_ConditionalIcon.svelte';
+  import DefaultValue from './_DefaultValue.svelte';
 </script>
 
 <style>
diff --git a/packages/site/src/routes/demo/select/_DefaultValue.svelte b/packages/site/src/routes/demo/select/_DefaultValue.svelte
new file mode 100644
index 000000000..d28a5556c
--- /dev/null
+++ b/packages/site/src/routes/demo/select/_DefaultValue.svelte
@@ -0,0 +1,39 @@
+<div class="columns margins">
+  <div>
+    <Select
+      key={(value) => `${value == null ? '' : value}`}
+      bind:value={valueA}
+      label="Wood type"
+    >
+      <Option value="">All</Option>
+      {#each woodTypes as type}
+        <Option value={type}>{type}</Option>
+      {/each}
+    </Select>
+
+    <pre class="status">Selected: {valueA}</pre>
+  </div>
+  <div>
+    <Select
+      key={(value) => `${value == null ? '' : value}`}
+      bind:value={valueB}
+      label="Wood type"
+    >
+      <Option value="all">All</Option>
+      {#each woodTypes as type}
+        <Option value={type}>{type}</Option>
+      {/each}
+    </Select>
+
+    <pre class="status">Selected: {valueB}</pre>
+  </div>
+</div>
+
+<script lang="ts">
+  import Select, { Option } from '@smui/select';
+
+  let woodTypes = ['Mahogany', 'Oak', 'Walnut', 'Pine'];
+
+  let valueA: string;
+  let valueB: string = 'all';
+</script>